@astryxdesign/core 0.7.8 → 0.7.9-canary.0200dfe

package/src/Calendar/Calendar.doc.mjs

@@ -39,6 +39,11 @@ export const docs = {
         description:
           'Show two months side by side when the user frequently selects dates that span a month boundary.',
       },
+      {
+        guidance: true,
+        description:
+          'For a custom month view, use useCalendarNavigation and useCalendarDays from @astryxdesign/core/Calendar. To show another calendar system, pass the same calendar to both and feed visibleCalendarMonths into useCalendarDays. The hooks default to gregory and never read the InternationalizationProvider calendar.',
+      },
       {
         guidance: false,
         description:
@@ -169,13 +174,15 @@ export const docs = {
     {
       name: 'hasWeekNumbers',
       type: 'boolean',
-      description: 'Show ISO week numbers.',
+      description:
+        'Show ISO 8601 week numbers. They are ISO 8601 week numbers in every calendar system.',
       default: 'false',
     },
     {
       name: 'hasVariableRowCount',
       type: 'boolean',
-      description: 'Variable vs fixed 6-row grid.',
+      description:
+        'Give each month only the rows it needs. The default fixed 6-row grid keeps the same height from month to month; a variable row count trades that fixed height for a more compact grid.',
       default: 'false',
     },
     {
@@ -185,6 +192,48 @@ export const docs = {
         'First day of week. Accepts a number (0=Sunday) or a three-letter day name (e.g. "mon").',
       default: '0',
     },
+    {
+      name: 'calendar',
+      type: "'gregory' | 'iso8601' | 'buddhist' | 'roc' | 'japanese' | 'persian' | 'indian' | 'hebrew' | 'chinese' | 'dangi' | 'coptic' | 'ethiopic' | 'ethioaa' | 'islamic-civil' | 'islamic-tbla' | 'islamic-umalqura'",
+      description:
+        "Calendar system the grid shows, such as 'persian', 'hebrew', or 'islamic-umalqura'. It sets the months, their names, and month and year navigation. value, min, max, focusDate, and every callback stay Gregorian ISO dates. Calendars other than gregory, iso8601, buddhist, roc, and japanese need Temporal; where the runtime lacks it, load a polyfill such as temporal-polyfill/full/global on the server and in the browser, or the grid shows Gregorian months. Month starts in the Chinese and Dangi calendars come from the runtime's Temporal, and some polyfills start a few months one day apart from native Temporal; when server and browser markup must match, use one implementation on both sides, such as installImplementation() from temporal-polyfill/full/shim, which replaces a native Temporal.",
+      default: 'the InternationalizationProvider calendar, else gregory',
+    },
+  ],
+  examples: [
+    {
+      label: 'A custom month view in the Persian calendar',
+      code: `import {Button} from '@astryxdesign/core/Button';
+import {
+  useCalendarDays,
+  useCalendarNavigation,
+} from '@astryxdesign/core/Calendar';
+
+function PersianMonth() {
+  const {monthYearLabel, visibleCalendarMonths, navigateMonth} =
+    useCalendarNavigation({initialValue: '2026-10-30', calendar: 'persian'});
+  // visibleCalendarMonths[0] is {year: 1405, month: 8}: Aban 1405.
+  const {weeks} = useCalendarDays({
+    ...visibleCalendarMonths[0],
+    calendar: 'persian',
+  });
+  return (
+    <section aria-label={monthYearLabel}>
+      <Button label="Previous month" onClick={() => navigateMonth(-1)} />
+      <Button label="Next month" onClick={() => navigateMonth(1)} />
+      {weeks.map(week => (
+        <div key={week[0].iso}>
+          {week.map(day => (
+            <span key={day.iso} data-date={day.iso}>
+              {day.isOutside ? '' : day.dayNumber}
+            </span>
+          ))}
+        </div>
+      ))}
+    </section>
+  );
+}`,
+    },
   ],
   theming: {
     targets: [
@@ -230,6 +279,11 @@ export const docsZh = {
         description:
           'Show two months side by side when the user frequently selects dates that span a month boundary.',
       },
+      {
+        guidance: true,
+        description:
+          'For a custom month view, use useCalendarNavigation and useCalendarDays from @astryxdesign/core/Calendar. To show another calendar system, pass the same calendar to both and feed visibleCalendarMonths into useCalendarDays. The hooks default to gregory and never read the InternationalizationProvider calendar.',
+      },
       {
         guidance: false,
         description:
@@ -311,13 +365,14 @@ export const docsZh = {
     {
       name: 'hasWeekNumbers',
       type: 'boolean',
-      description: '显示 ISO 周数。',
+      description: '显示 ISO 8601 周数。在任何历法中都是 ISO 8601 周数。',
       default: 'false',
     },
     {
       name: 'hasVariableRowCount',
       type: 'boolean',
-      description: '可变行数与固定 6 行网格。',
+      description:
+        '每个月只显示所需的行数。默认的固定 6 行网格使每个月高度相同；可变行数以固定高度换取更紧凑的网格。',
       default: 'false',
     },
     {
@@ -327,6 +382,13 @@ export const docsZh = {
         '每周起始日。可为数字（0=周日）或三字母星期缩写（如 "mon"）。',
       default: '0',
     },
+    {
+      name: 'calendar',
+      type: "'gregory' | 'iso8601' | 'buddhist' | 'roc' | 'japanese' | 'persian' | 'indian' | 'hebrew' | 'chinese' | 'dangi' | 'coptic' | 'ethiopic' | 'ethioaa' | 'islamic-civil' | 'islamic-tbla' | 'islamic-umalqura'",
+      description:
+        "网格显示的历法，如 'persian'、'hebrew' 或 'islamic-umalqura'。它决定月份、月份名称以及按月和按年的导航。value、min、max、focusDate 和所有回调仍为公历 ISO 日期。gregory、iso8601、buddhist、roc 和 japanese 以外的历法需要 Temporal；运行环境没有 Temporal 时，请在服务端和浏览器中加载 polyfill（如 temporal-polyfill/full/global），否则网格显示公历月份。农历（chinese）和檀纪历（dangi）的月初取自运行环境的 Temporal，部分 polyfill 与原生 Temporal 有少数月份的月初相差一天；服务端渲染且需要两端标记一致时，请在两端使用同一种实现，例如 temporal-polyfill/full/shim 的 installImplementation()，它会替换原生 Temporal。",
+      default: 'InternationalizationProvider 的历法，否则为 gregory',
+    },
   ],
   theming: {
     targets: [
@@ -374,6 +436,11 @@ export const docsDense = {
         description:
           'Show two months side by side when user frequently selects dates spanning a month boundary.',
       },
+      {
+        guidance: true,
+        description:
+          'Custom month view: useCalendarNavigation + useCalendarDays; pass the same calendar to both, feed visibleCalendarMonths into useCalendarDays. Default gregory; never read the provider calendar.',
+      },
       {
         guidance: false,
         description:
@@ -400,8 +467,11 @@ export const docsDense = {
     onFocusDateChange: 'navigation callback',
     handleRef: 'imperative navigation handle',
     hasOutsideDays: 'show days from adjacent months',
-    hasWeekNumbers: 'show ISO week numbers',
-    hasVariableRowCount: 'variable vs fixed 6-row grid',
+    hasWeekNumbers: 'show ISO 8601 week numbers, in every calendar system',
+    hasVariableRowCount:
+      'only the rows each month needs; trades the fixed 6-row height for a compact grid',
     weekStartsOn: 'first day of week (0=Sunday, or name e.g. "mon")',
+    calendar:
+      'calendar system shown (default: provider calendar, else gregory); values stay Gregorian ISO; non-Gregorian-aligned calendars need Temporal',
   },
 };

package/src/Calendar/Calendar.tsx

@@ -31,11 +31,8 @@ import * as stylex from '@stylexjs/stylex';
 import {Button} from '../Button';
 import {Icon} from '../Icon';
 import {useAnnounce, useGridFocus} from '../hooks';
-import {
-  useCalendarDays,
-  useCalendarConstraints,
-  type CalendarDay,
-} from './hooks';
+import {useCalendarConstraints, type CalendarDay} from './hooks';
+import {useCalendarDays} from './hooks/useCalendarDays';
 import {
   calendarStyles,
   monthGridStyles,
@@ -48,23 +45,28 @@ import {
   plainDateToISO,
   plainDateToDate,
   plainDateToday,
-  plainDateSetFirstOfMonth,
-  plainDateAddMonths,
   plainDateAddDays,
   plainDateDiffDays,
-  getDaysInMonth,
   plainDateIsAfter,
   plainDateIsBefore,
   plainDateIsEqual,
   plainDateGetWeekNumber,
-  plainDateFormat,
   plainDateWeekFieldName,
+  plainDateFormatDayNumber,
   DATE_FORMAT_WITH_WEEKDAY,
 } from '../utils/plainDate';
 import {
-  plainDateFormatDayNumber,
-  plainDateFormatStandaloneMonthYear,
-} from '../utils/plainDate';
+  type CalendarMonth,
+  type CalendarSystem,
+  calendarAddMonths,
+  calendarMonthOf,
+  calendarShiftMonths,
+  calendarShiftYears,
+  calendarYearMonthOf,
+  formatCalendarDate,
+  formatCalendarMonthLabel,
+  isInCalendarMonth,
+} from '../utils/calendarSystem';
 import {mergeProps, composeEventHandlers, rtlStyles} from '../utils';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
 import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';
@@ -99,6 +101,7 @@ import type {
 import {normalizeDayOfWeek} from '../utils/dateTypes';
 import {themeProps} from '../utils/themeProps';
 import {useLocale} from '../i18n';
+import {useCalendarSystem} from '../i18n/useCalendarSystem';
 import {VisuallyHidden} from '../VisuallyHidden';
 import {
   registerEnglishFallback,
@@ -108,7 +111,7 @@ import english from '../i18n/generated-english/Calendar/Calendar.generated';
 
 registerEnglishFallback(english);
 
-/** How a month navigation moves the focused day: by its row offset in days, or by whole months or years. */
+/** How a month navigation moves the focused day: by its row offset in days, or by whole calendar months or years. */
 type NavigationUnit = 'days' | 'months' | 'years';
 
 /** Imperative handle for Calendar handleRef */
@@ -181,13 +184,15 @@ interface CalendarBaseProps extends Omit<
   hasOutsideDays?: boolean;
 
   /**
-   * Show ISO week numbers in a side column.
+   * Show ISO 8601 week numbers in a side column. They are ISO 8601 week
+   * numbers in every calendar system.
    * Default: false
    */
   hasWeekNumbers?: boolean;
 
   /**
-   * Use variable rows per month vs. fixed 6-row grid.
+   * Give each month only the rows it needs instead of a fixed 6-row grid.
+   * The fixed grid keeps the same height from month to month.
    * Default: false (fixed 6 rows for consistent height)
    */
   hasVariableRowCount?: boolean;
@@ -198,6 +203,16 @@ interface CalendarBaseProps extends Omit<
    * Default: 0 (Sunday)
    */
   weekStartsOn?: DayOfWeek | DayOfWeekName;
+
+  /**
+   * The calendar system the grid shows, such as `'persian'` or `'hebrew'`.
+   * It sets the months, their labels, and month and year navigation. `value`,
+   * `min`, `max`, `focusDate`, and every callback stay Gregorian ISO dates.
+   * Default: the `InternationalizationProvider` calendar, else Gregorian.
+   * Calendars other than `gregory`, `iso8601`, `buddhist`, `roc`, and
+   * `japanese` need `Temporal`; without it the grid shows Gregorian months.
+   */
+  calendar?: CalendarSystem;
 }
 
 // ─── Mode-specific Props (discriminated union) ────────────────
@@ -232,14 +247,12 @@ interface CalendarRangeProps extends CalendarBaseProps {
 
 export type CalendarProps = CalendarSingleProps | CalendarRangeProps;
 
-/** The first day of `month`'s month that `isDisabled` allows, or null. */
 function firstEnabledDayOfMonth(
-  month: PlainDate,
+  month: CalendarMonth,
   isDisabled: (pd: PlainDate) => boolean,
 ): PlainDate | null {
-  const days = getDaysInMonth(month.year, month.month);
-  for (let day = 1; day <= days; day += 1) {
-    const pd = {year: month.year, month: month.month, day};
+  for (let offset = 0; offset < month.length; offset += 1) {
+    const pd = plainDateAddDays(month.start, offset);
     if (!isDisabled(pd)) {
       return pd;
     }
@@ -247,6 +260,15 @@ function firstEnabledDayOfMonth(
   return null;
 }
 
+/** A day's full label, such as "Friday, Aban 8, 1405 AP", in the calendar. */
+function formatDateLabel(
+  date: PlainDate,
+  calendar: CalendarSystem,
+  locale: string,
+): string {
+  return formatCalendarDate(calendar, date, DATE_FORMAT_WITH_WEEKDAY, locale);
+}
+
 // =============================================================================
 // Main Component
 // =============================================================================
@@ -280,12 +302,14 @@ export function Calendar({ref, ...props}: CalendarProps) {
     hasWeekNumbers = false,
     hasVariableRowCount = false,
     weekStartsOn: weekStartsOnProp = 0,
+    calendar: calendarProp,
     xstyle,
     className,
     style,
     onKeyDown,
     ...rest
   } = props;
+  const calendar = useCalendarSystem(calendarProp, 'Calendar');
 
   // Normalize `weekStartsOn` (number or three-letter day name) to a numeric
   // DayOfWeek so all downstream date math keeps working with an index.
@@ -329,6 +353,7 @@ export function Calendar({ref, ...props}: CalendarProps) {
       max,
       numberOfMonths,
       today,
+      calendar,
     }),
   );
 
@@ -354,17 +379,21 @@ export function Calendar({ref, ...props}: CalendarProps) {
     [isControlledFocus, onFocusDateChange],
   );
 
-  // Base month (first day of focus month)
-  const baseMonth = useMemo(() => {
-    return plainDateSetFirstOfMonth(focusDate);
-  }, [focusDate]);
+  // A controlled focus date is a new object on each render. Key the memo on
+  // its ISO string.
+  const focusIso = plainDateToISO(focusDate);
+  const baseMonth = useMemo(
+    () => calendarMonthOf(calendar, plainDateFromISO(focusIso)),
+    [calendar, focusIso],
+  );
 
   // Generate visible months
   const visibleMonths = useMemo(() => {
     return Array.from({length: numberOfMonths}, (_, i) => {
-      return plainDateAddMonths(baseMonth, i);
+      return calendarAddMonths(calendar, baseMonth, i);
     });
-  }, [baseMonth, numberOfMonths]);
+  }, [calendar, baseMonth, numberOfMonths]);
+  const lastVisibleMonth = visibleMonths[visibleMonths.length - 1];
 
   // A pending target is claimed by the grid that shows its month, or dropped
   // by the next focus move that is not onto the target day: when a controlled
@@ -378,9 +407,7 @@ export function Calendar({ref, ...props}: CalendarProps) {
       return null;
     }
     const target = plainDateFromISO(pendingFocus);
-    return visibleMonths.some(
-      pd => pd.year === target.year && pd.month === target.month,
-    )
+    return visibleMonths.some(month => isInCalendarMonth(target, month))
       ? pendingFocus
       : null;
   }, [pendingFocus, visibleMonths]);
@@ -405,9 +432,9 @@ export function Calendar({ref, ...props}: CalendarProps) {
   const monthYearLabel = useMemo(
     () =>
       visibleMonths
-        .map(m => plainDateFormatStandaloneMonthYear(m, locale))
+        .map(m => formatCalendarMonthLabel(calendar, m, locale))
         .join(' – '),
-    [visibleMonths, locale],
+    [calendar, visibleMonths, locale],
   );
 
   // Announce the newly visible month to screen readers whenever it changes.
@@ -439,31 +466,13 @@ export function Calendar({ref, ...props}: CalendarProps) {
     [max],
   );
 
-  const canNavigatePrevious = useMemo(() => {
-    if (!min) {
-      return true;
-    }
-    const minDate = plainDateFromISO(min);
-    // Can't go back if min is in the current focus month
-    return (
-      minDate.year < baseMonth.year ||
-      (minDate.year === baseMonth.year && minDate.month < baseMonth.month)
-    );
-  }, [min, baseMonth]);
-
-  const canNavigateNext = useMemo(() => {
-    if (!max) {
-      return true;
-    }
-    const maxDate = plainDateFromISO(max);
-    // Check against the last visible month, not just baseMonth
-    const lastVisibleMonth = plainDateAddMonths(baseMonth, numberOfMonths - 1);
-    return (
-      maxDate.year > lastVisibleMonth.year ||
-      (maxDate.year === lastVisibleMonth.year &&
-        maxDate.month > lastVisibleMonth.month)
-    );
-  }, [max, baseMonth, numberOfMonths]);
+  // A month button is available while a day past the shown months is in range.
+  const canNavigatePrevious =
+    minDateForKeys == null ||
+    plainDateIsBefore(minDateForKeys, baseMonth.start);
+  const canNavigateNext =
+    maxDateForKeys == null ||
+    plainDateIsAfter(maxDateForKeys, lastVisibleMonth.end);
 
   // Navigation handlers
   // The same constraint view the grids use, so a key can resolve its target
@@ -491,10 +500,6 @@ export function Calendar({ref, ...props}: CalendarProps) {
       offset?: number,
       unit: NavigationUnit = 'days',
     ) => {
-      const monthIndex = (pd: PlainDate) => pd.year * 12 + pd.month;
-      const firstShown = monthIndex(baseMonth);
-      const lastShown = firstShown + numberOfMonths - 1;
-
       // The Previous/Next buttons move the month with no focused day.
       if (!focusedDate) {
         if (
@@ -503,7 +508,7 @@ export function Calendar({ref, ...props}: CalendarProps) {
         ) {
           return;
         }
-        const newPd = plainDateAddMonths(baseMonth, delta);
+        const newPd = calendarAddMonths(calendar, baseMonth, delta).start;
         if (onFocusDateChange) {
           onFocusDateChange(plainDateToISO(newPd));
         } else {
@@ -523,19 +528,19 @@ export function Calendar({ref, ...props}: CalendarProps) {
         !(maxDateForKeys && plainDateIsAfter(pd, maxDateForKeys));
       let targetPd: PlainDate;
       if (unit === 'months' || unit === 'years') {
-        // A page or a year step keeps the day of the month and clamps it to the
-        // target month's length. A month with no enabled day is no target, the
-        // same as for an arrow.
-        const candidate = plainDateAddMonths(
-          currentPd,
-          unit === 'years' ? delta * 12 : delta,
-        );
+        // A page or a year step keeps the day of the calendar month and clamps
+        // it to the target month's length. A month with no enabled day is no
+        // target, the same as for an arrow.
+        const candidate =
+          unit === 'years'
+            ? calendarShiftYears(calendar, currentPd, delta)
+            : calendarShiftMonths(calendar, currentPd, delta);
         if (!inRange(candidate)) {
           return;
         }
         if (isRootDateDisabled(candidate)) {
           const firstEnabled = firstEnabledDayOfMonth(
-            candidate,
+            calendarMonthOf(calendar, candidate),
             isRootDateDisabled,
           );
           if (firstEnabled == null) {
@@ -572,16 +577,15 @@ export function Calendar({ref, ...props}: CalendarProps) {
       // key's direction, so the target month becomes the first (backwards)
       // or last (forwards) month shown.
       const resolved: PlainDate = targetPd;
-      const targetMonth = monthIndex(resolved);
       setPendingFocus(plainDateToISO(resolved));
-      if (targetMonth >= firstShown && targetMonth <= lastShown) {
+      const isBeforeShown = plainDateIsBefore(resolved, baseMonth.start);
+      if (!isBeforeShown && !plainDateIsAfter(resolved, lastVisibleMonth.end)) {
         return;
       }
-      const targetFirst = {year: resolved.year, month: resolved.month, day: 1};
-      const newPd =
-        targetMonth < firstShown
-          ? targetFirst
-          : plainDateAddMonths(targetFirst, -(numberOfMonths - 1));
+      const targetMonth = calendarMonthOf(calendar, resolved);
+      const newPd = isBeforeShown
+        ? targetMonth.start
+        : calendarAddMonths(calendar, targetMonth, -(numberOfMonths - 1)).start;
       if (onFocusDateChange) {
         onFocusDateChange(plainDateToISO(newPd));
       } else {
@@ -590,9 +594,11 @@ export function Calendar({ref, ...props}: CalendarProps) {
     },
     [
       baseMonth,
+      calendar,
       canNavigateNext,
       canNavigatePrevious,
       isRootDateDisabled,
+      lastVisibleMonth,
       maxDateForKeys,
       minDateForKeys,
       numberOfMonths,
@@ -637,7 +643,7 @@ export function Calendar({ref, ...props}: CalendarProps) {
           setRangeSelectionStart(iso);
           announce(
             t('@astryx.calendar.rangeStartAnnounce', {
-              date: plainDateFormat(date, DATE_FORMAT_WITH_WEEKDAY, locale),
+              date: formatDateLabel(date, calendar, locale),
             }),
           );
         } else {
@@ -653,7 +659,7 @@ export function Calendar({ref, ...props}: CalendarProps) {
             setRangeSelectionStart(null);
             announce(
               t('@astryx.calendar.rangeClearedAnnounce', {
-                date: plainDateFormat(date, DATE_FORMAT_WITH_WEEKDAY, locale),
+                date: formatDateLabel(date, calendar, locale),
               }),
             );
             return;
@@ -679,22 +685,23 @@ export function Calendar({ref, ...props}: CalendarProps) {
           // swapped {start, end} above even for a reverse pick).
           announce(
             t('@astryx.calendar.rangeCompleteAnnounce', {
-              start: plainDateFormat(
-                plainDateFromISO(start),
-                DATE_FORMAT_WITH_WEEKDAY,
-                locale,
-              ),
-              end: plainDateFormat(
-                plainDateFromISO(end),
-                DATE_FORMAT_WITH_WEEKDAY,
-                locale,
-              ),
+              start: formatDateLabel(plainDateFromISO(start), calendar, locale),
+              end: formatDateLabel(plainDateFromISO(end), calendar, locale),
             }),
           );
         }
       }
     },
-    [mode, onChange, rangeSelectionStart, minRangeSpan, announce, t, locale],
+    [
+      mode,
+      onChange,
+      rangeSelectionStart,
+      minRangeSpan,
+      announce,
+      t,
+      locale,
+      calendar,
+    ],
   );
 
   return (
@@ -756,8 +763,9 @@ export function Calendar({ref, ...props}: CalendarProps) {
       <div {...stylex.props(calendarStyles.monthsContainer)}>
         {visibleMonths.map(month => (
           <MonthGrid
-            key={`${month.year}-${month.month}`}
+            key={plainDateToISO(month.start)}
             month={month}
+            calendar={calendar}
             value={effectiveValue}
             mode={mode}
             rangeSelectionStart={rangeSelectionStart}
@@ -798,7 +806,8 @@ Calendar.displayName = 'Calendar';
 // =============================================================================
 
 interface MonthGridProps {
-  month: PlainDate;
+  month: CalendarMonth;
+  calendar: CalendarSystem;
   value: ISODateString | DateRange | undefined;
   mode: 'single' | 'range';
   rangeSelectionStart: ISODateString | null;
@@ -831,6 +840,7 @@ interface MonthGridProps {
 
 function MonthGrid({
   month,
+  calendar,
   value,
   mode,
   rangeSelectionStart,
@@ -853,12 +863,16 @@ function MonthGrid({
   onPendingFocusHandled,
 }: MonthGridProps) {
   const locale = useLocale();
-  const year = month.year;
 
   // Use hooks for days generation and constraints
+  const yearMonth = useMemo(
+    () => calendarYearMonthOf(calendar, month),
+    [calendar, month],
+  );
   const {days, weeks} = useCalendarDays({
-    year,
-    month: month.month,
+    year: yearMonth.year,
+    month: yearMonth.month,
+    calendar,
     weekStartsOn,
     hasVariableRowCount,
   });
@@ -899,15 +913,16 @@ function MonthGrid({
   // enabled) > today (if visible and enabled) > first enabled in-month day.
   const seedTabbableIso = useMemo((): ISODateString | null => {
     if (selectedDateForTabindex) {
-      const isSelectedInMonth =
-        selectedDateForTabindex.year === year &&
-        selectedDateForTabindex.month === month.month;
+      const isSelectedInMonth = isInCalendarMonth(
+        selectedDateForTabindex,
+        month,
+      );
       if (isSelectedInMonth && !isDateDisabled(selectedDateForTabindex)) {
         return plainDateToISO(selectedDateForTabindex);
       }
     }
 
-    const isTodayInMonth = today.year === year && today.month === month.month;
+    const isTodayInMonth = isInCalendarMonth(today, month);
     if (isTodayInMonth && !isDateDisabled(today)) {
       return plainDateToISO(today);
     }
@@ -919,7 +934,7 @@ function MonthGrid({
     }
 
     return null;
-  }, [days, today, year, month.month, isDateDisabled, selectedDateForTabindex]);
+  }, [days, today, month, isDateDisabled, selectedDateForTabindex]);
 
   // Helper to get the focused date from the currently focused element.
   // Reads the machine-readable `data-date` (ISO) attribute rather than parsing
@@ -1028,7 +1043,7 @@ function MonthGrid({
     }
 
     const targetPd = plainDateFromISO(pendingFocus);
-    if (targetPd.year !== year || targetPd.month !== month.month) {
+    if (!isInCalendarMonth(targetPd, month)) {
       return;
     }
     const targetIso = plainDateToISO(targetPd);
@@ -1063,7 +1078,7 @@ function MonthGrid({
       targetButton.focus();
     }
     onPendingFocusHandled?.();
-  }, [pendingFocus, gridRef, month.month, onPendingFocusHandled, year]);
+  }, [pendingFocus, gridRef, month, onPendingFocusHandled]);
 
   // Parse selection
   let selectedDate: PlainDate | null = null;
@@ -1103,8 +1118,8 @@ function MonthGrid({
 
   // Month label for announcements
   const monthLabel = useMemo(() => {
-    return plainDateFormatStandaloneMonthYear(month, locale);
-  }, [month, locale]);
+    return formatCalendarMonthLabel(calendar, month, locale);
+  }, [calendar, month, locale]);
 
   return (
     <div {...stylex.props(monthGridStyles.monthGrid)}>
@@ -1198,6 +1213,7 @@ function MonthGrid({
                     neighbors={neighbors}
                     isTabbable={day.iso === seedTabbableIso}
                     isRangeSelectionInProgress={rangeSelectionStart !== null}
+                    calendar={calendar}
                     onDayClick={onDayClick}
                     onDayHover={onDayHover}
                   />
@@ -1246,6 +1262,8 @@ interface DayCellProps {
    * "range start and range end" (rangeStart === rangeEnd in both cases).
    */
   isRangeSelectionInProgress: boolean;
+  /** The calendar system that writes the day's accessible name. */
+  calendar: CalendarSystem;
   onDayClick: (date: PlainDate) => void;
   onDayHover: (date: PlainDate | null) => void;
 }
@@ -1265,6 +1283,7 @@ function DayCell({
   neighbors,
   isTabbable: isTabbableDay,
   isRangeSelectionInProgress,
+  calendar,
   onDayClick,
   onDayHover,
 }: DayCellProps) {
@@ -1316,7 +1335,7 @@ function DayCell({
   // params rather than string concatenation. A mid-flight first pick (where
   // rangeStart === rangeEnd) reads as "range start" only; a completed one-day
   // range reads as both start and end.
-  const dateLabel = plainDateFormat(date, DATE_FORMAT_WITH_WEEKDAY, locale);
+  const dateLabel = formatDateLabel(date, calendar, locale);
   const dayLabel = state.isSelected
     ? t('@astryx.calendar.daySelected', {date: dateLabel})
     : state.isRangeStart && state.isRangeEnd