a11y(Calendar): convey disabled month state in YearCalendar and MultiSelectYearCalendar

Disabled (out-of-range) month cells were only greyed via the Disabled CSS
class and silently no-oped on click, leaving screen-reader and keyboard
users with no signal that the month is unavailable. Set `aria-disabled` on
the cell button; the existing handleClick early-return already blocks
activation.

We use `aria-disabled` rather than the native `disabled` attribute on
purpose: the year grid manages a roving focus that programmatically focuses
the cell matching focusedDate as the user arrows through the months. A
native `disabled` button cannot receive focus, which would desync the focus
ring from focusedDate while traversing disabled cells. aria-disabled keeps
the cells focusable while conveying the state, per the WAI-ARIA grid pattern.

The selected month also gets a ", selected" suffix in its aria-label. That
string is consumer-translatable via a new `labels` prop (YearCalendarLabels),
following the same convention as the Table footer's `labels`/TableLabels —
it falls back to the English default when unset.

Also expose minValue/maxValue on MultiSelectYearCalendarProps — the cell's
isDisabled logic already reads them from calendar state, but they were not
part of the typed API — and add Storybook coverage for both year-calendar
variants plus a localized-labels example (the package's unit tests cannot
run: @testing-library/dom is absent from the workspace).

Unblocks IDS-DRR-Frontend ACC-005. Refs CivicDataLab/IDS-DRR-Frontend#499.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: jpmckinney

packages/opub-ui/src/components/Calendar/Calendar.stories.tsx

@@ -9,6 +9,7 @@ import { Meta, StoryObj } from '@storybook/react-vite';
 import { useDateFormatter, useLocale } from 'react-aria';
 
 import { Calendar } from './Calendar';
+import { MultiSelectYearCalendar } from './MultiSelectYearCalendar';
 import { RangeCalendar } from './RangeCalendar';
 import { YearCalendar } from './YearCalendar';
 
@@ -89,3 +90,53 @@ export const YearDisabled: any = {
   },
   args: {},
 };
+
+export const MultiSelectYear: any = {
+  render: ({ ...args }) => {
+    return (
+      <MultiSelectYearCalendar
+        {...args}
+        onChange={(dates: any) => {
+          console.log(dates);
+        }}
+      />
+    );
+  },
+  args: {},
+};
+
+export const MultiSelectYearDisabled: any = {
+  render: ({ ...args }) => {
+    return (
+      <MultiSelectYearCalendar
+        minValue={parseDate('2021-01-01')}
+        maxValue={today(getLocalTimeZone())}
+        {...args}
+        onChange={(dates: any) => {
+          console.log(dates);
+        }}
+      />
+    );
+  },
+  args: {},
+};
+
+/**
+ * Consumers translate the calendar's aria-label strings by passing `labels`,
+ * the same way the Table footer accepts localized labels. Inspect a selected
+ * month's aria-label to see the localized "selected" suffix.
+ */
+export const YearLocalizedLabels: any = {
+  render: ({ ...args }) => {
+    return (
+      <YearCalendar
+        labels={{ selected: 'sélectionné' }}
+        {...args}
+        onChange={(date: any) => {
+          console.log(date);
+        }}
+      />
+    );
+  },
+  args: {},
+};

packages/opub-ui/src/components/Calendar/MultiSelectYearCalendar.tsx

@@ -15,6 +15,7 @@ import {
   useCalendarState,
 } from 'react-stately';
 
+import { YearCalendarLabels } from '../../types/datetime';
 import { cn } from '../../utils';
 import { Icon } from '../Icon';
 import { Text } from '../Text';
@@ -48,6 +49,11 @@ interface MultiSelectYearCalendarProps {
   disabledMonths?: DateValue[];
   yearRange?: { start: number; end: number };
 
+  /** Earliest selectable month; earlier months render disabled */
+  minValue?: DateValue | null;
+  /** Latest selectable month; later months render disabled */
+  maxValue?: DateValue | null;
+
   // onSelectionChange: (
   //   selections: {
   //     year: number;
@@ -61,6 +67,9 @@ interface MultiSelectYearCalendarProps {
   defaultValues?: DateValue[];
 
   onChange?: (dates: DateValue[]) => void;
+
+  /** Localizable strings. Falls back to English defaults. */
+  labels?: YearCalendarLabels;
 }
 
 export const MultiSelectYearCalendar = (
@@ -147,6 +156,7 @@ export const MultiSelectYearCalendar = (
         state={state}
         selectedDates={selectedDates}
         defaultValue={props.defaultValues}
+        labels={props.labels}
       />
     </div>
   );
@@ -170,10 +180,12 @@ function MonthSelector({
   state,
   selectedDates,
   defaultValue,
+  labels,
 }: {
   state: CalendarState;
   selectedDates: DateValue[];
   defaultValue?: DateValue[];
+  labels?: YearCalendarLabels;
 }) {
   React.useEffect(() => {
     const nextFocusElm = document.querySelector(
@@ -224,6 +236,7 @@ function MonthSelector({
               state={state}
               selectedDates={selectedDates}
               defaultValue={defaultValue}
+              labels={labels}
             />
           );
         })}
@@ -243,11 +256,13 @@ const Cell = ({
   state,
   selectedDates,
   defaultValue,
+  labels,
 }: {
   mon: { month: string; value: number; label: string };
   state: CalendarState;
   selectedDates: DateValue[];
   defaultValue?: DateValue[];
+  labels?: YearCalendarLabels;
 }) => {
   let date = state.focusedDate.set({ month: mon.value });
 
@@ -278,8 +293,8 @@ const Cell = ({
     state.setFocusedDate(date);
   };
 
-  const ariaLabel = `${mon.label} ${state.focusedDate.year}${
-    isSelected ? ', selected' : ''
+  const ariaLabel = `${mon.label}, ${state.focusedDate.year}${
+    isSelected ? `, ${labels?.selected ?? 'selected'}` : ''
   }`;
 
   return (

packages/opub-ui/src/components/Calendar/YearCalendar.tsx

@@ -15,6 +15,7 @@ import {
   useCalendarState,
 } from 'react-stately';
 
+import { YearCalendarLabels } from '../../types/datetime';
 import { cn } from '../../utils';
 import { Icon } from '../Icon';
 import { Text } from '../Text';
@@ -44,7 +45,10 @@ const monthsObj: {
 };
 
 export const YearCalendar = (
-  props: CalendarStateOptions<DateValue> | AriaCalendarProps<DateValue>
+  props: (CalendarStateOptions<DateValue> | AriaCalendarProps<DateValue>) & {
+    /** Localizable strings. Falls back to English defaults. */
+    labels?: YearCalendarLabels;
+  }
 ) => {
   let { locale } = useLocale();
   let state = useCalendarState({
@@ -98,7 +102,7 @@ export const YearCalendar = (
         <NextButton />
       </div>
 
-      <MonthSelector state={state} />
+      <MonthSelector state={state} labels={props.labels} />
     </div>
   );
 };
@@ -117,7 +121,13 @@ function YearDropdown({ state }: { state: CalendarState }) {
   );
 }
 
-function MonthSelector({ state }: { state: CalendarState }) {
+function MonthSelector({
+  state,
+  labels,
+}: {
+  state: CalendarState;
+  labels?: YearCalendarLabels;
+}) {
   React.useEffect(() => {
     const nextFocusElm = document.querySelector(
       `[data-label="${state.focusedDate.month}, ${state.focusedDate.year}"]`
@@ -155,7 +165,9 @@ function MonthSelector({ state }: { state: CalendarState }) {
     return (
       <tr key={i}>
         {monthsObj[i].map((mon) => {
-          return <Cell key={mon.value} mon={mon} state={state} />;
+          return (
+            <Cell key={mon.value} mon={mon} state={state} labels={labels} />
+          );
         })}
       </tr>
     );
@@ -171,9 +183,11 @@ function MonthSelector({ state }: { state: CalendarState }) {
 const Cell = ({
   mon,
   state,
+  labels,
 }: {
   mon: { month: string; value: number; label: string };
   state: CalendarState;
+  labels?: YearCalendarLabels;
 }) => {
   let date = state.focusedDate.set({ month: mon.value });
 
@@ -203,8 +217,8 @@ const Cell = ({
     state.setValue(date);
   };
 
-  const ariaLabel = `${mon.label} ${state.focusedDate.year}${
-    isSelected ? ', selected' : ''
+  const ariaLabel = `${mon.label}, ${state.focusedDate.year}${
+    isSelected ? `, ${labels?.selected ?? 'selected'}` : ''
   }`;
 
   return (

packages/opub-ui/src/types/datetime.ts

@@ -1,6 +1,12 @@
 import { LabelledProps } from '../components/Labelled';
 import React from 'react';
 
+/** Localizable strings for the year calendars. All keys are optional and fall back to English defaults. */
+export type YearCalendarLabels = {
+  /** Appended to a month's aria-label when it is the selected value. Default "selected" */
+  selected?: string;
+};
+
 export interface DateTimeProps {
   /** Additional hint text to display */
   helpText?: React.ReactNode;