@astryxdesign/core 0.7.9-canary.f8a309d → 0.7.9-canary.ffa495b

package/dist/Calendar/Calendar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Calendar.d.ts","sourceRoot":"","sources":["../../src/Calendar/Calendar.tsx"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AA6B5C,OAAO,EAEL,KAAK,cAAc,EAQpB,MAAM,yBAAyB,CAAC;AAoBjC,YAAY,EACV,aAAa,EACb,SAAS,EACT,aAAa,EACb,SAAS,GACV,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EACV,aAAa,EACb,SAAS,EACT,aAAa,EACb,SAAS,EACV,MAAM,oBAAoB,CAAC;AAiB5B,+CAA+C;AAC/C,MAAM,WAAW,cAAc;IAC7B,wEAAwE;IACxE,UAAU,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,IAAI,CAAC;CAC3C;AAID,UAAU,iBAAkB,SAAQ,IAAI,CACtC,SAAS,CAAC,cAAc,CAAC,EACzB,UAAU,GAAG,cAAc,CAC5B;IACC,kDAAkD;IAClD,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC,qDAAqD;IACrD,SAAS,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IACtC,+CAA+C;IAC/C,cAAc,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;IAEvB,4CAA4C;IAC5C,GAAG,CAAC,EAAE,aAAa,CAAC;IAEpB,4CAA4C;IAC5C,GAAG,CAAC,EAAE,aAAa,CAAC;IAEpB;;;OAGG;IACH,eAAe,CAAC,EAAE,aAAa,CAAC,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC;IAEzD;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,aAAa,CAAC;IAE1B,yDAAyD;IACzD,iBAAiB,CAAC,EAAE,CAAC,SAAS,EAAE,aAAa,KAAK,IAAI,CAAC;IAEvD;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAE9B;;;;OAIG;IACH,YAAY,CAAC,EAAE,SAAS,GAAG,aAAa,CAAC;IAEzC;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC3B;AAID,UAAU,mBAAoB,SAAQ,iBAAiB;IACrD,qBAAqB;IACrB,IAAI,CAAC,EAAE,QAAQ,CAAC;IAEhB,mFAAmF;IACnF,KAAK,CAAC,EAAE,aAAa,GAAG,IAAI,CAAC;IAE7B,0CAA0C;IAC1C,YAAY,CAAC,EAAE,aAAa,CAAC;IAE7B,qCAAqC;IACrC,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,IAAI,KAAK,IAAI,CAAC;CAC9D;AAED,UAAU,kBAAmB,SAAQ,iBAAiB;IACpD,qBAAqB;IACrB,IAAI,EAAE,OAAO,CAAC;IAEd,8DAA8D;IAC9D,KAAK,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IAEzB,0CAA0C;IAC1C,YAAY,CAAC,EAAE,SAAS,CAAC;IAEzB,sCAAsC;IACtC,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;CACvC;AAED,MAAM,MAAM,aAAa,GAAG,mBAAmB,GAAG,kBAAkB,CAAC;AA4BrE;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,EAAC,GAAG,EAAE,GAAG,KAAK,EAAC,EAAE,aAAa,+BAogBtD;yBApgBe,QAAQ"}
+{"version":3,"file":"Calendar.d.ts","sourceRoot":"","sources":["../../src/Calendar/Calendar.tsx"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AA6B5C,OAAO,EAEL,KAAK,cAAc,EASpB,MAAM,yBAAyB,CAAC;AAoBjC,YAAY,EACV,aAAa,EACb,SAAS,EACT,aAAa,EACb,SAAS,GACV,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EACV,aAAa,EACb,SAAS,EACT,aAAa,EACb,SAAS,EACV,MAAM,oBAAoB,CAAC;AAiB5B,+CAA+C;AAC/C,MAAM,WAAW,cAAc;IAC7B,wEAAwE;IACxE,UAAU,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,IAAI,CAAC;CAC3C;AAID,UAAU,iBAAkB,SAAQ,IAAI,CACtC,SAAS,CAAC,cAAc,CAAC,EACzB,UAAU,GAAG,cAAc,CAC5B;IACC,kDAAkD;IAClD,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC,qDAAqD;IACrD,SAAS,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IACtC,+CAA+C;IAC/C,cAAc,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;IAEvB,4CAA4C;IAC5C,GAAG,CAAC,EAAE,aAAa,CAAC;IAEpB,4CAA4C;IAC5C,GAAG,CAAC,EAAE,aAAa,CAAC;IAEpB;;;OAGG;IACH,eAAe,CAAC,EAAE,aAAa,CAAC,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC;IAEzD;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,aAAa,CAAC;IAE1B,yDAAyD;IACzD,iBAAiB,CAAC,EAAE,CAAC,SAAS,EAAE,aAAa,KAAK,IAAI,CAAC;IAEvD;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAE9B;;;;OAIG;IACH,YAAY,CAAC,EAAE,SAAS,GAAG,aAAa,CAAC;IAEzC;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC3B;AAID,UAAU,mBAAoB,SAAQ,iBAAiB;IACrD,qBAAqB;IACrB,IAAI,CAAC,EAAE,QAAQ,CAAC;IAEhB,mFAAmF;IACnF,KAAK,CAAC,EAAE,aAAa,GAAG,IAAI,CAAC;IAE7B,0CAA0C;IAC1C,YAAY,CAAC,EAAE,aAAa,CAAC;IAE7B,qCAAqC;IACrC,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,IAAI,KAAK,IAAI,CAAC;CAC9D;AAED,UAAU,kBAAmB,SAAQ,iBAAiB;IACpD,qBAAqB;IACrB,IAAI,EAAE,OAAO,CAAC;IAEd,8DAA8D;IAC9D,KAAK,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IAEzB,0CAA0C;IAC1C,YAAY,CAAC,EAAE,SAAS,CAAC;IAEzB,sCAAsC;IACtC,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;CACvC;AAED,MAAM,MAAM,aAAa,GAAG,mBAAmB,GAAG,kBAAkB,CAAC;AA4BrE;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,EAAC,GAAG,EAAE,GAAG,KAAK,EAAC,EAAE,aAAa,+BAogBtD;yBApgBe,QAAQ"}

package/dist/Calendar/Calendar.js

@@ -23,10 +23,10 @@ import { Button } from "../Button/index.js";
 import { Icon } from "../Icon/index.js";
 import { useAnnounce, useGridFocus } from "../hooks/index.js";
 import { useCalendarConstraints } from "./hooks/index.js";
-import { useCalendarMonthDays } from "./hooks/useCalendarDays.js";
+import { useCalendarDays } from "./hooks/useCalendarDays.js";
 import { calendarStyles, monthGridStyles, dayCellStyles, dayCellTheme } from "./styles.js";
 import { plainDateFromISO, plainDateToISO, plainDateToDate, plainDateToday, plainDateAddDays, plainDateDiffDays, plainDateIsAfter, plainDateIsBefore, plainDateIsEqual, plainDateGetWeekNumber, plainDateWeekFieldName, plainDateFormatDayNumber, DATE_FORMAT_WITH_WEEKDAY } from "../utils/plainDate.js";
-import { calendarAddMonths, calendarMonthOf, calendarShiftMonths, calendarShiftYears, formatCalendarDate, formatCalendarMonthLabel, isInCalendarMonth } from "../utils/calendarSystem.js";
+import { calendarAddMonths, calendarMonthOf, calendarShiftMonths, calendarShiftYears, calendarYearMonthOf, formatCalendarDate, formatCalendarMonthLabel, isInCalendarMonth } from "../utils/calendarSystem.js";
 import { mergeProps, composeEventHandlers, rtlStyles } from "../utils/index.js";
 import { focusOutlineProps } from "../utils/focusOutline.stylex.js";
 import { interactionOverlayStyles } from "../utils/interactionOverlay.stylex.js";
@@ -524,11 +524,13 @@ function MonthGrid({
   const locale = useLocale();
 
   // Use hooks for days generation and constraints
+  const yearMonth = useMemo(() => calendarYearMonthOf(calendar, month), [calendar, month]);
   const {
     days,
     weeks
-  } = useCalendarMonthDays({
-    month,
+  } = useCalendarDays({
+    year: yearMonth.year,
+    month: yearMonth.month,
     calendar,
     weekStartsOn,
     hasVariableRowCount

package/dist/Calendar/hooks/useCalendarDays.d.ts

@@ -1,6 +1,6 @@
 import type { DayOfWeek, ISODateString } from '../../utils/dateTypes.js';
 import { type PlainDate } from '../../utils/plainDate.js';
-import { type CalendarMonth, type CalendarSystem } from '../../utils/calendarSystem.js';
+import { type CalendarSystem } from '../../utils/calendarSystem.js';
 /**
  * Represents a single day in the calendar grid.
  */
@@ -18,14 +18,27 @@ export interface CalendarDay {
  * Configuration for calendar days generation
  */
 export interface UseCalendarDaysOptions {
-    /** The year to generate days for */
+    /** The year to generate days for, in `calendar`'s numbering */
     year: number;
-    /** The month (1-based: 1 = January, 12 = December) */
+    /**
+     * The month's position in its year (1-based). In the Gregorian calendar,
+     * 1 is January and 12 is December. In other calendars it is numbered as
+     * `Temporal.PlainDate` numbers it: 1 through 13 in a Hebrew leap year.
+     */
     month: number;
     /** First day of week (0=Sunday through 6=Saturday) */
     weekStartsOn?: DayOfWeek;
     /** Use variable rows per month vs. fixed 6-row grid */
     hasVariableRowCount?: boolean;
+    /**
+     * The calendar system that numbers `year`, `month`, and each `dayNumber`.
+     * Each day keeps its Gregorian `date` and `iso`. The hook never reads the
+     * InternationalizationProvider calendar. Calendars other than gregory,
+     * iso8601, buddhist, roc, and japanese need Temporal; without it, the hook
+     * reads Gregorian numbers and warns once in development.
+     * @default 'gregory'
+     */
+    calendar?: CalendarSystem;
 }
 /**
  * Return type for useCalendarDays hook
@@ -54,24 +67,10 @@ export interface UseCalendarDaysReturn {
  *   weekStartsOn: 0, // Sunday
  * });
  * // days[i].date is a PlainDate { year, month (1-based), day }
+ *
+ * // Aban 1405 in the Persian calendar; dates stay Gregorian
+ * useCalendarDays({year: 1405, month: 8, calendar: 'persian'});
  * ```
  */
 export declare function useCalendarDays(options: UseCalendarDaysOptions): UseCalendarDaysReturn;
-/** Configuration for the day grid of one month of a calendar system. */
-export interface UseCalendarMonthDaysOptions {
-    /** The month to lay out, located by its Gregorian days. */
-    month: CalendarMonth;
-    /** The calendar system the month belongs to; it numbers the days. */
-    calendar: CalendarSystem;
-    /** First day of week (0=Sunday through 6=Saturday) */
-    weekStartsOn?: DayOfWeek;
-    /** Use variable rows per month vs. fixed 6-row grid */
-    hasVariableRowCount?: boolean;
-}
-/**
- * The day grid of one month of any calendar system. Each day keeps its
- * Gregorian date; `dayNumber` is its day of the calendar month. Internal to
- * Calendar.
- */
-export declare function useCalendarMonthDays(options: UseCalendarMonthDaysOptions): UseCalendarDaysReturn;
 //# sourceMappingURL=useCalendarDays.d.ts.map

package/dist/Calendar/hooks/useCalendarDays.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useCalendarDays.d.ts","sourceRoot":"","sources":["../../../src/Calendar/hooks/useCalendarDays.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAC,SAAS,EAAE,aAAa,EAAC,MAAM,uBAAuB,CAAC;AACpE,OAAO,EACL,KAAK,SAAS,EAKf,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,cAAc,EAEpB,MAAM,4BAA4B,CAAC;AAEpC;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,iCAAiC;IACjC,IAAI,EAAE,SAAS,CAAC;IAChB,mCAAmC;IACnC,GAAG,EAAE,aAAa,CAAC;IACnB,oDAAoD;IACpD,SAAS,EAAE,OAAO,CAAC;IACnB,4BAA4B;IAC5B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,KAAK,EAAE,MAAM,CAAC;IACd,sDAAsD;IACtD,YAAY,CAAC,EAAE,SAAS,CAAC;IACzB,uDAAuD;IACvD,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,mDAAmD;IACnD,IAAI,EAAE,WAAW,EAAE,CAAC;IACpB,8BAA8B;IAC9B,KAAK,EAAE,WAAW,EAAE,EAAE,CAAC;IACvB,yCAAyC;IACzC,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,wCAAwC;IACxC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,sBAAsB,GAC9B,qBAAqB,CAcvB;AAED,wEAAwE;AACxE,MAAM,WAAW,2BAA2B;IAC1C,2DAA2D;IAC3D,KAAK,EAAE,aAAa,CAAC;IACrB,qEAAqE;IACrE,QAAQ,EAAE,cAAc,CAAC;IACzB,sDAAsD;IACtD,YAAY,CAAC,EAAE,SAAS,CAAC;IACzB,uDAAuD;IACvD,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,2BAA2B,GACnC,qBAAqB,CAsBvB"}
+{"version":3,"file":"useCalendarDays.d.ts","sourceRoot":"","sources":["../../../src/Calendar/hooks/useCalendarDays.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAC,SAAS,EAAE,aAAa,EAAC,MAAM,uBAAuB,CAAC;AACpE,OAAO,EACL,KAAK,SAAS,EAIf,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,KAAK,cAAc,EAGpB,MAAM,4BAA4B,CAAC;AAGpC;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,iCAAiC;IACjC,IAAI,EAAE,SAAS,CAAC;IAChB,mCAAmC;IACnC,GAAG,EAAE,aAAa,CAAC;IACnB,oDAAoD;IACpD,SAAS,EAAE,OAAO,CAAC;IACnB,4BAA4B;IAC5B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC;IACd,sDAAsD;IACtD,YAAY,CAAC,EAAE,SAAS,CAAC;IACzB,uDAAuD;IACvD,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,mDAAmD;IACnD,IAAI,EAAE,WAAW,EAAE,CAAC;IACpB,8BAA8B;IAC9B,KAAK,EAAE,WAAW,EAAE,EAAE,CAAC;IACvB,yCAAyC;IACzC,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,wCAAwC;IACxC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,sBAAsB,GAC9B,qBAAqB,CAuBvB"}

package/dist/Calendar/hooks/useCalendarDays.js

@@ -6,18 +6,19 @@
  * @file useCalendarDays.ts
  * @input Uses React useMemo, useLocale, PlainDate and calendar-system
  *   utilities, generated CLDR weekday data
- * @output Exports useCalendarDays (a Gregorian month) and useCalendarMonthDays
- *   (a month of any calendar system) for generating calendar day grids
- * @position Calendar-specific hooks; useCalendarMonthDays is used by Calendar
+ * @output Exports useCalendarDays, the day grid of one month of any calendar
+ *   system (Gregorian by default)
+ * @position Calendar-specific hook; used by Calendar and MonthScroller
  *
  * SYNC: When modified, update:
  * - /packages/core/src/Calendar/hooks/index.ts
  */
 import { useMemo } from 'react';
-import { plainDateToISO, getDaysInMonth, plainDateDayOfWeek, plainDateAddDays } from "../../utils/plainDate.js";
+import { plainDateToISO, plainDateDayOfWeek, plainDateAddDays } from "../../utils/plainDate.js";
 import { useLocale } from "../../i18n/index.js";
 import { getWeekdayHeaderNames } from "../getWeekdayHeaderNames.js";
-import { calendarDayOfMonth } from "../../utils/calendarSystem.js";
+import { calendarDayOfMonth, calendarMonthFromYearMonth } from "../../utils/calendarSystem.js";
+import { resolveShownCalendar } from "../../i18n/useCalendarSystem.js";
 
 /**
  * Represents a single day in the calendar grid.
@@ -45,6 +46,9 @@ import { calendarDayOfMonth } from "../../utils/calendarSystem.js";
  *   weekStartsOn: 0, // Sunday
  * });
  * // days[i].date is a PlainDate { year, month (1-based), day }
+ *
+ * // Aban 1405 in the Persian calendar; dates stay Gregorian
+ * useCalendarDays({year: 1405, month: 8, calendar: 'persian'});
  * ```
  */
 export function useCalendarDays(options) {
@@ -52,43 +56,23 @@ export function useCalendarDays(options) {
     year,
     month,
     weekStartsOn = 0,
-    hasVariableRowCount = false
+    hasVariableRowCount = false,
+    calendar: calendarOption = 'gregory'
   } = options;
-  const days = useMemo(() => layOutMonthDays({
-    first: {
+  const calendar = resolveShownCalendar(calendarOption, 'useCalendarDays');
+  const days = useMemo(() => {
+    const calendarMonth = calendarMonthFromYearMonth(calendar, {
       year,
-      month,
-      day: 1
-    },
-    length: getDaysInMonth(year, month),
-    weekStartsOn,
-    hasVariableRowCount,
-    dayNumberOf: pd => pd.day
-  }), [year, month, weekStartsOn, hasVariableRowCount]);
-  return useMonthGrid(days, weekStartsOn);
-}
-
-/** Configuration for the day grid of one month of a calendar system. */
-
-/**
- * The day grid of one month of any calendar system. Each day keeps its
- * Gregorian date; `dayNumber` is its day of the calendar month. Internal to
- * Calendar.
- */
-export function useCalendarMonthDays(options) {
-  const {
-    month,
-    calendar,
-    weekStartsOn = 0,
-    hasVariableRowCount = false
-  } = options;
-  const days = useMemo(() => layOutMonthDays({
-    first: month.start,
-    length: month.length,
-    weekStartsOn,
-    hasVariableRowCount,
-    dayNumberOf: (pd, offset) => offset >= 0 && offset < month.length ? offset + 1 : calendarDayOfMonth(calendar, pd)
-  }), [month, calendar, weekStartsOn, hasVariableRowCount]);
+      month
+    });
+    return layOutMonthDays({
+      first: calendarMonth.start,
+      length: calendarMonth.length,
+      weekStartsOn,
+      hasVariableRowCount,
+      dayNumberOf: (pd, offset) => offset >= 0 && offset < calendarMonth.length ? offset + 1 : calendarDayOfMonth(calendar, pd)
+    });
+  }, [year, month, calendar, weekStartsOn, hasVariableRowCount]);
   return useMonthGrid(days, weekStartsOn);
 }
 function layOutMonthDays(layout) {

package/dist/Calendar/hooks/useCalendarNavigation.d.ts

@@ -1,5 +1,6 @@
 import type { ISODateString } from '../../utils/dateTypes.js';
 import { type PlainDate } from '../../utils/plainDate.js';
+import { type CalendarSystem } from '../../utils/calendarSystem.js';
 /**
  * Configuration for calendar navigation
  */
@@ -12,16 +13,33 @@ export interface UseCalendarNavigationOptions {
     onFocusDateChange?: (focusDate: ISODateString) => void;
     /** Number of months to display */
     numberOfMonths?: 1 | 2;
+    /**
+     * The calendar system whose months the hook steps and labels. Dates stay
+     * Gregorian ISO. The hook never reads the InternationalizationProvider
+     * calendar. Calendars other than gregory, iso8601, buddhist, roc, and
+     * japanese need Temporal; without it, the hook steps Gregorian months and
+     * warns once in development.
+     * @default 'gregory'
+     */
+    calendar?: CalendarSystem;
 }
 /**
  * Return type for useCalendarNavigation hook
  */
 export interface UseCalendarNavigationReturn {
-    /** The base month (first day of the focus month) as a PlainDate */
+    /** The Gregorian first day of the focus month */
     baseMonth: PlainDate;
-    /** Array of visible months to render as PlainDates */
+    /** The Gregorian first day of each visible month */
     visibleMonths: PlainDate[];
-    /** Formatted label for the month header */
+    /**
+     * The year and month numbers of each visible month in `calendar`, as
+     * `useCalendarDays` reads them with the same `calendar`
+     */
+    visibleCalendarMonths: {
+        year: number;
+        month: number;
+    }[];
+    /** Formatted label for the month header, in `calendar` */
     monthYearLabel: string;
     /** Navigate to previous/next month */
     navigateMonth: (delta: number, focusedDate?: ISODateString, offset?: number) => void;
@@ -55,6 +73,13 @@ export interface UseCalendarNavigationReturn {
  * // Navigate from arrow key (with focus tracking)
  * navigateMonth(1, focusedDate, 1); // horizontal offset
  * navigateMonth(1, focusedDate, 7); // vertical offset
+ *
+ * // Persian months, laid out by useCalendarDays
+ * const nav = useCalendarNavigation({initialValue, calendar: 'persian'});
+ * const {weeks} = useCalendarDays({
+ *   ...nav.visibleCalendarMonths[0],
+ *   calendar: 'persian',
+ * });
  * ```
  */
 export declare function useCalendarNavigation(options: UseCalendarNavigationOptions): UseCalendarNavigationReturn;

package/dist/Calendar/hooks/useCalendarNavigation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useCalendarNavigation.d.ts","sourceRoot":"","sources":["../../../src/Calendar/hooks/useCalendarNavigation.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,uBAAuB,CAAC;AACzD,OAAO,EACL,KAAK,SAAS,EAOf,MAAM,uBAAuB,CAAC;AAI/B;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C,gDAAgD;IAChD,YAAY,CAAC,EAAE,aAAa,CAAC;IAC7B,qDAAqD;IACrD,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,0CAA0C;IAC1C,iBAAiB,CAAC,EAAE,CAAC,SAAS,EAAE,aAAa,KAAK,IAAI,CAAC;IACvD,kCAAkC;IAClC,cAAc,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C,mEAAmE;IACnE,SAAS,EAAE,SAAS,CAAC;IACrB,sDAAsD;IACtD,aAAa,EAAE,SAAS,EAAE,CAAC;IAC3B,2CAA2C;IAC3C,cAAc,EAAE,MAAM,CAAC;IACvB,sCAAsC;IACtC,aAAa,EAAE,CACb,KAAK,EAAE,MAAM,EACb,WAAW,CAAC,EAAE,aAAa,EAC3B,MAAM,CAAC,EAAE,MAAM,KACZ,IAAI,CAAC;IACV,4CAA4C;IAC5C,YAAY,EAAE,aAAa,GAAG,IAAI,CAAC;IACnC,8BAA8B;IAC9B,iBAAiB,EAAE,MAAM,IAAI,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,4BAA4B,GACpC,2BAA2B,CAyF7B"}
+{"version":3,"file":"useCalendarNavigation.d.ts","sourceRoot":"","sources":["../../../src/Calendar/hooks/useCalendarNavigation.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,uBAAuB,CAAC;AACzD,OAAO,EACL,KAAK,SAAS,EAKf,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,KAAK,cAAc,EAKpB,MAAM,4BAA4B,CAAC;AAIpC;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C,gDAAgD;IAChD,YAAY,CAAC,EAAE,aAAa,CAAC;IAC7B,qDAAqD;IACrD,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,0CAA0C;IAC1C,iBAAiB,CAAC,EAAE,CAAC,SAAS,EAAE,aAAa,KAAK,IAAI,CAAC;IACvD,kCAAkC;IAClC,cAAc,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;IACvB;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C,iDAAiD;IACjD,SAAS,EAAE,SAAS,CAAC;IACrB,oDAAoD;IACpD,aAAa,EAAE,SAAS,EAAE,CAAC;IAC3B;;;OAGG;IACH,qBAAqB,EAAE;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAC,EAAE,CAAC;IACvD,0DAA0D;IAC1D,cAAc,EAAE,MAAM,CAAC;IACvB,sCAAsC;IACtC,aAAa,EAAE,CACb,KAAK,EAAE,MAAM,EACb,WAAW,CAAC,EAAE,aAAa,EAC3B,MAAM,CAAC,EAAE,MAAM,KACZ,IAAI,CAAC;IACV,4CAA4C;IAC5C,YAAY,EAAE,aAAa,GAAG,IAAI,CAAC;IACnC,8BAA8B;IAC9B,iBAAiB,EAAE,MAAM,IAAI,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,4BAA4B,GACpC,2BAA2B,CAuG7B"}

package/dist/Calendar/hooks/useCalendarNavigation.js

@@ -4,17 +4,20 @@
 
 /**
  * @file useCalendarNavigation.ts
- * @input Uses React useState, useMemo, useCallback, useLocale, PlainDate utilities
- * @output Exports useCalendarNavigation hook for month navigation
- * @position Calendar-specific hook; used by Calendar
+ * @input Uses React useState, useMemo, useCallback, useLocale, PlainDate and
+ *   calendar-system utilities
+ * @output Exports useCalendarNavigation hook for month navigation in any
+ *   calendar system (Gregorian by default)
+ * @position Calendar-specific public hook
  *
  * SYNC: When modified, update:
  * - /packages/core/src/Calendar/hooks/index.ts
  */
 import { useState, useMemo, useCallback } from 'react';
-import { plainDateFromISO, plainDateToISO, plainDateToday, plainDateSetFirstOfMonth, plainDateAddMonths, plainDateAddDays } from "../../utils/plainDate.js";
-import { plainDateFormatStandaloneMonthYear } from "../../utils/plainDate.js";
+import { plainDateFromISO, plainDateToISO, plainDateToday, plainDateAddDays } from "../../utils/plainDate.js";
+import { calendarAddMonths, calendarMonthOf, calendarYearMonthOf, formatCalendarMonthLabel } from "../../utils/calendarSystem.js";
 import { useLocale } from "../../i18n/index.js";
+import { resolveShownCalendar } from "../../i18n/useCalendarSystem.js";
 
 /**
  * Configuration for calendar navigation
@@ -49,6 +52,13 @@ import { useLocale } from "../../i18n/index.js";
  * // Navigate from arrow key (with focus tracking)
  * navigateMonth(1, focusedDate, 1); // horizontal offset
  * navigateMonth(1, focusedDate, 7); // vertical offset
+ *
+ * // Persian months, laid out by useCalendarDays
+ * const nav = useCalendarNavigation({initialValue, calendar: 'persian'});
+ * const {weeks} = useCalendarDays({
+ *   ...nav.visibleCalendarMonths[0],
+ *   calendar: 'persian',
+ * });
  * ```
  */
 export function useCalendarNavigation(options) {
@@ -56,9 +66,11 @@ export function useCalendarNavigation(options) {
     initialValue,
     focusDate: focusDateProp,
     onFocusDateChange,
-    numberOfMonths = 1
+    numberOfMonths = 1,
+    calendar: calendarOption = 'gregory'
   } = options;
   const locale = useLocale();
+  const calendar = resolveShownCalendar(calendarOption, 'useCalendarNavigation');
 
   // Pending focus target after month navigation
   const [pendingFocus, setPendingFocus] = useState(null);
@@ -78,27 +90,25 @@ export function useCalendarNavigation(options) {
   const isControlledFocus = focusDateProp !== undefined && onFocusDateChange !== undefined;
   const focusDate = isControlledFocus ? plainDateFromISO(focusDateProp) : internalFocusDate;
 
-  // Base month (first day of focus month)
-  const baseMonth = useMemo(() => {
-    return plainDateSetFirstOfMonth(focusDate);
-  }, [focusDate]);
-
-  // Generate visible months
-  const visibleMonths = useMemo(() => {
+  // A controlled focus date is a new object on each render. Key the memo on
+  // its ISO string.
+  const focusIso = plainDateToISO(focusDate);
+  const shownMonths = useMemo(() => {
+    const first = calendarMonthOf(calendar, plainDateFromISO(focusIso));
     return Array.from({
       length: numberOfMonths
-    }, (_, i) => {
-      return plainDateAddMonths(baseMonth, i);
-    });
-  }, [baseMonth, numberOfMonths]);
+    }, (_, i) => calendarAddMonths(calendar, first, i));
+  }, [calendar, focusIso, numberOfMonths]);
+  const visibleMonths = useMemo(() => shownMonths.map(month => month.start), [shownMonths]);
+  const baseMonth = visibleMonths[0];
+  const visibleCalendarMonths = useMemo(() => shownMonths.map(month => calendarYearMonthOf(calendar, month)), [calendar, shownMonths]);
 
-  // Format month header
-  // Each month is its own stand-alone label (Calendar FR1).
-  const monthYearLabel = useMemo(() => visibleMonths.map(m => plainDateFormatStandaloneMonthYear(m, locale)).join(' – '), [visibleMonths, locale]);
+  // Each month is its own stand-alone label.
+  const monthYearLabel = useMemo(() => shownMonths.map(month => formatCalendarMonthLabel(calendar, month, locale)).join(' – '), [calendar, shownMonths, locale]);
 
   // Navigate to previous/next month
   const navigateMonth = useCallback((delta, focusedDate, offset) => {
-    const newMonth = plainDateAddMonths(baseMonth, delta);
+    const newMonth = calendarAddMonths(calendar, shownMonths[0], delta).start;
     const newISO = plainDateToISO(newMonth);
 
     // Calculate target focus date if provided
@@ -114,7 +124,7 @@ export function useCalendarNavigation(options) {
     } else {
       setInternalFocusDate(newMonth);
     }
-  }, [baseMonth, onFocusDateChange]);
+  }, [calendar, shownMonths, onFocusDateChange]);
 
   // Clear pending focus
   const clearPendingFocus = useCallback(() => {
@@ -123,6 +133,7 @@ export function useCalendarNavigation(options) {
   return {
     baseMonth,
     visibleMonths,
+    visibleCalendarMonths,
     monthYearLabel,
     navigateMonth,
     pendingFocus,

package/dist/i18n/useCalendarSystem.d.ts

@@ -4,6 +4,12 @@ import { type CalendarSystem } from '../utils/calendarSystem.js';
  * resolves to `gregory` and warns once in development.
  */
 export declare function resolveCalendarSystem(id: string, source: string): CalendarSystem;
+/**
+ * The calendar that a caller names, without the provider: an unknown
+ * identifier, or one this runtime cannot show, becomes `gregory` and warns
+ * once in development.
+ */
+export declare function resolveShownCalendar(calendar: string, source: string): CalendarSystem;
 /**
  * The calendar a date component shows: its own `calendar`, else the
  * provider's resolved calendar, else `gregory`. It resolves during render, so

package/dist/i18n/useCalendarSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useCalendarSystem.d.ts","sourceRoot":"","sources":["../../src/i18n/useCalendarSystem.ts"],"names":[],"mappings":"AAeA,OAAO,EACL,KAAK,cAAc,EAGpB,MAAM,yBAAyB,CAAC;AAGjC;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,MAAM,GACb,cAAc,CAUhB;AAyBD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,cAAc,GAAG,SAAS,EACpC,MAAM,EAAE,MAAM,GACb,cAAc,CAOhB"}
+{"version":3,"file":"useCalendarSystem.d.ts","sourceRoot":"","sources":["../../src/i18n/useCalendarSystem.ts"],"names":[],"mappings":"AAgBA,OAAO,EACL,KAAK,cAAc,EAGpB,MAAM,yBAAyB,CAAC;AAGjC;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,MAAM,GACb,cAAc,CAUhB;AAyBD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,GACb,cAAc,CAKhB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,cAAc,GAAG,SAAS,EACpC,MAAM,EAAE,MAAM,GACb,cAAc,CAMhB"}

package/dist/i18n/useCalendarSystem.js

@@ -5,10 +5,11 @@
 /**
  * @file useCalendarSystem.ts
  * @input InternationalizationContext, an optional component `calendar`
- * @output The calendar system a date component shows, and the helper that
- *   normalizes a calendar identifier
- * @position Internal i18n hook; read by InternationalizationProvider and date
- *   components. Not re-exported from the i18n barrel.
+ * @output The calendar system a date component shows, and the helpers that
+ *   normalize a calendar identifier
+ * @position Internal i18n hook; read by InternationalizationProvider, date
+ *   components, and the public calendar hooks. Not re-exported from the i18n
+ *   barrel.
  */
 import { use } from 'react';
 import { InternationalizationContext } from "./InternationalizationContext.js";
@@ -40,6 +41,15 @@ function availableCalendarOrGregorian(calendar, source) {
   return 'gregory';
 }
 
+/**
+ * The calendar that a caller names, without the provider: an unknown
+ * identifier, or one this runtime cannot show, becomes `gregory` and warns
+ * once in development.
+ */
+export function resolveShownCalendar(calendar, source) {
+  return availableCalendarOrGregorian(resolveCalendarSystem(calendar, source), source);
+}
+
 /**
  * The calendar a date component shows: its own `calendar`, else the
  * provider's resolved calendar, else `gregory`. It resolves during render, so
@@ -47,6 +57,5 @@ function availableCalendarOrGregorian(calendar, source) {
  */
 export function useCalendarSystem(calendar, source) {
   const context = use(InternationalizationContext);
-  const requested = calendar != null ? resolveCalendarSystem(calendar, source) : context.calendar ?? 'gregory';
-  return availableCalendarOrGregorian(requested, source);
+  return resolveShownCalendar(calendar ?? context.calendar ?? 'gregory', source);
 }

package/dist/utils/calendarSystem.d.ts

@@ -1,11 +1,11 @@
 /**
  * @file calendarSystem.ts
  * @input A calendar identifier and Gregorian PlainDates
- * @output Calendar months located by their Gregorian days, month and year
- *   steps, dates from calendar fields, availability of each calendar, and
- *   calendar labels and digits
- * @position Shared date utility; read by the i18n calendar resolution and by
- *   Calendar. Values stay Gregorian PlainDates. Temporal owns the arithmetic of
+ * @output Calendar months located by their Gregorian days, their year and
+ *   month numbers, month and year steps, dates from calendar fields,
+ *   availability of each calendar, and calendar labels and digits
+ * @position Shared date utility; read by the i18n calendar resolution, by
+ *   Calendar, and by its public hooks. Values stay Gregorian PlainDates. Temporal owns the arithmetic of
  *   every calendar whose months are not Gregorian.
  */
 import type { Locale } from '../i18n/types.js';
@@ -36,6 +36,21 @@ export interface CalendarMonth {
 export declare function calendarDayOfMonth(calendar: CalendarSystem, pd: PlainDate): number;
 /** The calendar month that contains a Gregorian date. */
 export declare function calendarMonthOf(calendar: CalendarSystem, pd: PlainDate): CalendarMonth;
+/**
+ * A calendar month by its year and its position in that year, as
+ * `Temporal.PlainDate` numbers them: month 13 exists in a Hebrew leap year.
+ */
+export interface CalendarYearMonth {
+    readonly year: number;
+    readonly month: number;
+}
+/** The year and month numbers of a calendar month. */
+export declare function calendarYearMonthOf(calendar: CalendarSystem, month: CalendarMonth): CalendarYearMonth;
+/**
+ * The calendar month with these year and month numbers. A month past the end
+ * of its year becomes the last month of that year, as Temporal constrains it.
+ */
+export declare function calendarMonthFromYearMonth(calendar: CalendarSystem, { year, month }: CalendarYearMonth): CalendarMonth;
 /** The calendar month `n` months after `month`, or before it when negative. */
 export declare function calendarAddMonths(calendar: CalendarSystem, month: CalendarMonth, n: number): CalendarMonth;
 /**

package/dist/utils/calendarSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"calendarSystem.d.ts","sourceRoot":"","sources":["../../src/utils/calendarSystem.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"calendarSystem.d.ts","sourceRoot":"","sources":["../../src/utils/calendarSystem.ts"],"names":[],"mappings":"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"}

package/dist/utils/calendarSystem.js

@@ -3,11 +3,11 @@
 /**
  * @file calendarSystem.ts
  * @input A calendar identifier and Gregorian PlainDates
- * @output Calendar months located by their Gregorian days, month and year
- *   steps, dates from calendar fields, availability of each calendar, and
- *   calendar labels and digits
- * @position Shared date utility; read by the i18n calendar resolution and by
- *   Calendar. Values stay Gregorian PlainDates. Temporal owns the arithmetic of
+ * @output Calendar months located by their Gregorian days, their year and
+ *   month numbers, month and year steps, dates from calendar fields,
+ *   availability of each calendar, and calendar labels and digits
+ * @position Shared date utility; read by the i18n calendar resolution, by
+ *   Calendar, and by its public hooks. Values stay Gregorian PlainDates. Temporal owns the arithmetic of
  *   every calendar whose months are not Gregorian.
  */
 
@@ -142,6 +142,59 @@ export function calendarMonthOf(calendar, pd) {
   }));
 }
 
+/**
+ * A calendar month by its year and its position in that year, as
+ * `Temporal.PlainDate` numbers them: month 13 exists in a Hebrew leap year.
+ */
+
+// Temporal counts the years of these Gregorian-aligned calendars from another
+// epoch: 2026 is 2569 in `buddhist` and 115 in `roc`.
+const GREGORIAN_YEAR_OFFSETS = {
+  buddhist: 543,
+  roc: -1911
+};
+
+/** The year and month numbers of a calendar month. */
+export function calendarYearMonthOf(calendar, month) {
+  if (isGregorianAligned(calendar)) {
+    return {
+      year: month.start.year + (GREGORIAN_YEAR_OFFSETS[calendar] ?? 0),
+      month: month.start.month
+    };
+  }
+  const {
+    year,
+    month: monthOfYear
+  } = inCalendar(calendar, month.start);
+  return {
+    year,
+    month: monthOfYear
+  };
+}
+
+/**
+ * The calendar month with these year and month numbers. A month past the end
+ * of its year becomes the last month of that year, as Temporal constrains it.
+ */
+export function calendarMonthFromYearMonth(calendar, {
+  year,
+  month
+}) {
+  if (isGregorianAligned(calendar)) {
+    return gregorianMonth(year - (GREGORIAN_YEAR_OFFSETS[calendar] ?? 0), month);
+  }
+  // `with` replaces the year and month of any date in the calendar.
+  return temporalMonth(inCalendar(calendar, {
+    year: 2000,
+    month: 1,
+    day: 1
+  }).with({
+    year,
+    month,
+    day: 1
+  }));
+}
+
 /** The calendar month `n` months after `month`, or before it when negative. */
 export function calendarAddMonths(calendar, month, n) {
   if (n === 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.7.9-canary.f8a309d",
+  "version": "0.7.9-canary.ffa495b",
   "displayName": "Astryx Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",
@@ -875,9 +875,9 @@
     "react-dom": ">=19.0.0"
   },
   "devDependencies": {
-    "@astryxdesign/a11y-spec": "0.7.9-canary.f8a309d",
-    "@astryxdesign/cli": "0.7.9-canary.f8a309d",
-    "@astryxdesign/interaction-harness": "0.7.9-canary.f8a309d",
+    "@astryxdesign/a11y-spec": "0.7.9-canary.ffa495b",
+    "@astryxdesign/cli": "0.7.9-canary.ffa495b",
+    "@astryxdesign/interaction-harness": "0.7.9-canary.ffa495b",
     "@babel/cli": "^7.29.7",
     "@babel/core": "^7.29.7",
     "@babel/preset-react": "^7.29.7",

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:
@@ -195,6 +200,41 @@ export const docs = {
       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: [
       {className: 'astryx-calendar', visualProps: ['mode']},
@@ -239,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:
@@ -391,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:

package/src/Calendar/Calendar.tsx

@@ -32,7 +32,7 @@ import {Button} from '../Button';
 import {Icon} from '../Icon';
 import {useAnnounce, useGridFocus} from '../hooks';
 import {useCalendarConstraints, type CalendarDay} from './hooks';
-import {useCalendarMonthDays} from './hooks/useCalendarDays';
+import {useCalendarDays} from './hooks/useCalendarDays';
 import {
   calendarStyles,
   monthGridStyles,
@@ -62,6 +62,7 @@ import {
   calendarMonthOf,
   calendarShiftMonths,
   calendarShiftYears,
+  calendarYearMonthOf,
   formatCalendarDate,
   formatCalendarMonthLabel,
   isInCalendarMonth,
@@ -864,8 +865,13 @@ function MonthGrid({
   const locale = useLocale();
 
   // Use hooks for days generation and constraints
-  const {days, weeks} = useCalendarMonthDays({
-    month,
+  const yearMonth = useMemo(
+    () => calendarYearMonthOf(calendar, month),
+    [calendar, month],
+  );
+  const {days, weeks} = useCalendarDays({
+    year: yearMonth.year,
+    month: yearMonth.month,
     calendar,
     weekStartsOn,
     hasVariableRowCount,

package/src/Calendar/hooks/useCalendarDays.ts

@@ -6,9 +6,9 @@
  * @file useCalendarDays.ts
  * @input Uses React useMemo, useLocale, PlainDate and calendar-system
  *   utilities, generated CLDR weekday data
- * @output Exports useCalendarDays (a Gregorian month) and useCalendarMonthDays
- *   (a month of any calendar system) for generating calendar day grids
- * @position Calendar-specific hooks; useCalendarMonthDays is used by Calendar
+ * @output Exports useCalendarDays, the day grid of one month of any calendar
+ *   system (Gregorian by default)
+ * @position Calendar-specific hook; used by Calendar and MonthScroller
  *
  * SYNC: When modified, update:
  * - /packages/core/src/Calendar/hooks/index.ts
@@ -19,17 +19,17 @@ import type {DayOfWeek, ISODateString} from '../../utils/dateTypes';
 import {
   type PlainDate,
   plainDateToISO,
-  getDaysInMonth,
   plainDateDayOfWeek,
   plainDateAddDays,
 } from '../../utils/plainDate';
 import {useLocale} from '../../i18n';
 import {getWeekdayHeaderNames} from '../getWeekdayHeaderNames';
 import {
-  type CalendarMonth,
   type CalendarSystem,
   calendarDayOfMonth,
+  calendarMonthFromYearMonth,
 } from '../../utils/calendarSystem';
+import {resolveShownCalendar} from '../../i18n/useCalendarSystem';
 
 /**
  * Represents a single day in the calendar grid.
@@ -49,14 +49,27 @@ export interface CalendarDay {
  * Configuration for calendar days generation
  */
 export interface UseCalendarDaysOptions {
-  /** The year to generate days for */
+  /** The year to generate days for, in `calendar`'s numbering */
   year: number;
-  /** The month (1-based: 1 = January, 12 = December) */
+  /**
+   * The month's position in its year (1-based). In the Gregorian calendar,
+   * 1 is January and 12 is December. In other calendars it is numbered as
+   * `Temporal.PlainDate` numbers it: 1 through 13 in a Hebrew leap year.
+   */
   month: number;
   /** First day of week (0=Sunday through 6=Saturday) */
   weekStartsOn?: DayOfWeek;
   /** Use variable rows per month vs. fixed 6-row grid */
   hasVariableRowCount?: boolean;
+  /**
+   * The calendar system that numbers `year`, `month`, and each `dayNumber`.
+   * Each day keeps its Gregorian `date` and `iso`. The hook never reads the
+   * InternationalizationProvider calendar. Calendars other than gregory,
+   * iso8601, buddhist, roc, and japanese need Temporal; without it, the hook
+   * reads Gregorian numbers and warns once in development.
+   * @default 'gregory'
+   */
+  calendar?: CalendarSystem;
 }
 
 /**
@@ -87,66 +100,35 @@ export interface UseCalendarDaysReturn {
  *   weekStartsOn: 0, // Sunday
  * });
  * // days[i].date is a PlainDate { year, month (1-based), day }
+ *
+ * // Aban 1405 in the Persian calendar; dates stay Gregorian
+ * useCalendarDays({year: 1405, month: 8, calendar: 'persian'});
  * ```
  */
 export function useCalendarDays(
   options: UseCalendarDaysOptions,
-): UseCalendarDaysReturn {
-  const {year, month, weekStartsOn = 0, hasVariableRowCount = false} = options;
-  const days = useMemo(
-    () =>
-      layOutMonthDays({
-        first: {year, month, day: 1},
-        length: getDaysInMonth(year, month),
-        weekStartsOn,
-        hasVariableRowCount,
-        dayNumberOf: pd => pd.day,
-      }),
-    [year, month, weekStartsOn, hasVariableRowCount],
-  );
-  return useMonthGrid(days, weekStartsOn);
-}
-
-/** Configuration for the day grid of one month of a calendar system. */
-export interface UseCalendarMonthDaysOptions {
-  /** The month to lay out, located by its Gregorian days. */
-  month: CalendarMonth;
-  /** The calendar system the month belongs to; it numbers the days. */
-  calendar: CalendarSystem;
-  /** First day of week (0=Sunday through 6=Saturday) */
-  weekStartsOn?: DayOfWeek;
-  /** Use variable rows per month vs. fixed 6-row grid */
-  hasVariableRowCount?: boolean;
-}
-
-/**
- * The day grid of one month of any calendar system. Each day keeps its
- * Gregorian date; `dayNumber` is its day of the calendar month. Internal to
- * Calendar.
- */
-export function useCalendarMonthDays(
-  options: UseCalendarMonthDaysOptions,
 ): UseCalendarDaysReturn {
   const {
+    year,
     month,
-    calendar,
     weekStartsOn = 0,
     hasVariableRowCount = false,
+    calendar: calendarOption = 'gregory',
   } = options;
-  const days = useMemo(
-    () =>
-      layOutMonthDays({
-        first: month.start,
-        length: month.length,
-        weekStartsOn,
-        hasVariableRowCount,
-        dayNumberOf: (pd, offset) =>
-          offset >= 0 && offset < month.length
-            ? offset + 1
-            : calendarDayOfMonth(calendar, pd),
-      }),
-    [month, calendar, weekStartsOn, hasVariableRowCount],
-  );
+  const calendar = resolveShownCalendar(calendarOption, 'useCalendarDays');
+  const days = useMemo(() => {
+    const calendarMonth = calendarMonthFromYearMonth(calendar, {year, month});
+    return layOutMonthDays({
+      first: calendarMonth.start,
+      length: calendarMonth.length,
+      weekStartsOn,
+      hasVariableRowCount,
+      dayNumberOf: (pd, offset) =>
+        offset >= 0 && offset < calendarMonth.length
+          ? offset + 1
+          : calendarDayOfMonth(calendar, pd),
+    });
+  }, [year, month, calendar, weekStartsOn, hasVariableRowCount]);
   return useMonthGrid(days, weekStartsOn);
 }
 

package/src/Calendar/hooks/useCalendarNavigation.ts

@@ -4,9 +4,11 @@
 
 /**
  * @file useCalendarNavigation.ts
- * @input Uses React useState, useMemo, useCallback, useLocale, PlainDate utilities
- * @output Exports useCalendarNavigation hook for month navigation
- * @position Calendar-specific hook; used by Calendar
+ * @input Uses React useState, useMemo, useCallback, useLocale, PlainDate and
+ *   calendar-system utilities
+ * @output Exports useCalendarNavigation hook for month navigation in any
+ *   calendar system (Gregorian by default)
+ * @position Calendar-specific public hook
  *
  * SYNC: When modified, update:
  * - /packages/core/src/Calendar/hooks/index.ts
@@ -19,12 +21,17 @@ import {
   plainDateFromISO,
   plainDateToISO,
   plainDateToday,
-  plainDateSetFirstOfMonth,
-  plainDateAddMonths,
   plainDateAddDays,
 } from '../../utils/plainDate';
-import {plainDateFormatStandaloneMonthYear} from '../../utils/plainDate';
+import {
+  type CalendarSystem,
+  calendarAddMonths,
+  calendarMonthOf,
+  calendarYearMonthOf,
+  formatCalendarMonthLabel,
+} from '../../utils/calendarSystem';
 import {useLocale} from '../../i18n';
+import {resolveShownCalendar} from '../../i18n/useCalendarSystem';
 
 /**
  * Configuration for calendar navigation
@@ -38,17 +45,31 @@ export interface UseCalendarNavigationOptions {
   onFocusDateChange?: (focusDate: ISODateString) => void;
   /** Number of months to display */
   numberOfMonths?: 1 | 2;
+  /**
+   * The calendar system whose months the hook steps and labels. Dates stay
+   * Gregorian ISO. The hook never reads the InternationalizationProvider
+   * calendar. Calendars other than gregory, iso8601, buddhist, roc, and
+   * japanese need Temporal; without it, the hook steps Gregorian months and
+   * warns once in development.
+   * @default 'gregory'
+   */
+  calendar?: CalendarSystem;
 }
 
 /**
  * Return type for useCalendarNavigation hook
  */
 export interface UseCalendarNavigationReturn {
-  /** The base month (first day of the focus month) as a PlainDate */
+  /** The Gregorian first day of the focus month */
   baseMonth: PlainDate;
-  /** Array of visible months to render as PlainDates */
+  /** The Gregorian first day of each visible month */
   visibleMonths: PlainDate[];
-  /** Formatted label for the month header */
+  /**
+   * The year and month numbers of each visible month in `calendar`, as
+   * `useCalendarDays` reads them with the same `calendar`
+   */
+  visibleCalendarMonths: {year: number; month: number}[];
+  /** Formatted label for the month header, in `calendar` */
   monthYearLabel: string;
   /** Navigate to previous/next month */
   navigateMonth: (
@@ -87,6 +108,13 @@ export interface UseCalendarNavigationReturn {
  * // Navigate from arrow key (with focus tracking)
  * navigateMonth(1, focusedDate, 1); // horizontal offset
  * navigateMonth(1, focusedDate, 7); // vertical offset
+ *
+ * // Persian months, laid out by useCalendarDays
+ * const nav = useCalendarNavigation({initialValue, calendar: 'persian'});
+ * const {weeks} = useCalendarDays({
+ *   ...nav.visibleCalendarMonths[0],
+ *   calendar: 'persian',
+ * });
  * ```
  */
 export function useCalendarNavigation(
@@ -97,8 +125,13 @@ export function useCalendarNavigation(
     focusDate: focusDateProp,
     onFocusDateChange,
     numberOfMonths = 1,
+    calendar: calendarOption = 'gregory',
   } = options;
   const locale = useLocale();
+  const calendar = resolveShownCalendar(
+    calendarOption,
+    'useCalendarNavigation',
+  );
 
   // Pending focus target after month navigation
   const [pendingFocus, setPendingFocus] = useState<ISODateString | null>(null);
@@ -121,32 +154,40 @@ export function useCalendarNavigation(
     ? plainDateFromISO(focusDateProp)
     : internalFocusDate;
 
-  // 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 shownMonths = useMemo(() => {
+    const first = calendarMonthOf(calendar, plainDateFromISO(focusIso));
+    return Array.from({length: numberOfMonths}, (_, i) =>
+      calendarAddMonths(calendar, first, i),
+    );
+  }, [calendar, focusIso, numberOfMonths]);
+
+  const visibleMonths = useMemo(
+    () => shownMonths.map(month => month.start),
+    [shownMonths],
+  );
+  const baseMonth = visibleMonths[0];
 
-  // Generate visible months
-  const visibleMonths = useMemo(() => {
-    return Array.from({length: numberOfMonths}, (_, i) => {
-      return plainDateAddMonths(baseMonth, i);
-    });
-  }, [baseMonth, numberOfMonths]);
+  const visibleCalendarMonths = useMemo(
+    () => shownMonths.map(month => calendarYearMonthOf(calendar, month)),
+    [calendar, shownMonths],
+  );
 
-  // Format month header
-  // Each month is its own stand-alone label (Calendar FR1).
+  // Each month is its own stand-alone label.
   const monthYearLabel = useMemo(
     () =>
-      visibleMonths
-        .map(m => plainDateFormatStandaloneMonthYear(m, locale))
+      shownMonths
+        .map(month => formatCalendarMonthLabel(calendar, month, locale))
         .join(' – '),
-    [visibleMonths, locale],
+    [calendar, shownMonths, locale],
   );
 
   // Navigate to previous/next month
   const navigateMonth = useCallback(
     (delta: number, focusedDate?: ISODateString, offset?: number) => {
-      const newMonth = plainDateAddMonths(baseMonth, delta);
+      const newMonth = calendarAddMonths(calendar, shownMonths[0], delta).start;
       const newISO = plainDateToISO(newMonth);
 
       // Calculate target focus date if provided
@@ -164,7 +205,7 @@ export function useCalendarNavigation(
         setInternalFocusDate(newMonth);
       }
     },
-    [baseMonth, onFocusDateChange],
+    [calendar, shownMonths, onFocusDateChange],
   );
 
   // Clear pending focus
@@ -175,6 +216,7 @@ export function useCalendarNavigation(
   return {
     baseMonth,
     visibleMonths,
+    visibleCalendarMonths,
     monthYearLabel,
     navigateMonth,
     pendingFocus,

package/src/i18n/useCalendarSystem.ts

@@ -5,10 +5,11 @@
 /**
  * @file useCalendarSystem.ts
  * @input InternationalizationContext, an optional component `calendar`
- * @output The calendar system a date component shows, and the helper that
- *   normalizes a calendar identifier
- * @position Internal i18n hook; read by InternationalizationProvider and date
- *   components. Not re-exported from the i18n barrel.
+ * @output The calendar system a date component shows, and the helpers that
+ *   normalize a calendar identifier
+ * @position Internal i18n hook; read by InternationalizationProvider, date
+ *   components, and the public calendar hooks. Not re-exported from the i18n
+ *   barrel.
  */
 
 import {use} from 'react';
@@ -62,6 +63,21 @@ function availableCalendarOrGregorian(
   return 'gregory';
 }
 
+/**
+ * The calendar that a caller names, without the provider: an unknown
+ * identifier, or one this runtime cannot show, becomes `gregory` and warns
+ * once in development.
+ */
+export function resolveShownCalendar(
+  calendar: string,
+  source: string,
+): CalendarSystem {
+  return availableCalendarOrGregorian(
+    resolveCalendarSystem(calendar, source),
+    source,
+  );
+}
+
 /**
  * The calendar a date component shows: its own `calendar`, else the
  * provider's resolved calendar, else `gregory`. It resolves during render, so
@@ -72,9 +88,8 @@ export function useCalendarSystem(
   source: string,
 ): CalendarSystem {
   const context = use(InternationalizationContext);
-  const requested =
-    calendar != null
-      ? resolveCalendarSystem(calendar, source)
-      : (context.calendar ?? 'gregory');
-  return availableCalendarOrGregorian(requested, source);
+  return resolveShownCalendar(
+    calendar ?? context.calendar ?? 'gregory',
+    source,
+  );
 }

package/src/utils/calendarSystem.ts

@@ -3,11 +3,11 @@
 /**
  * @file calendarSystem.ts
  * @input A calendar identifier and Gregorian PlainDates
- * @output Calendar months located by their Gregorian days, month and year
- *   steps, dates from calendar fields, availability of each calendar, and
- *   calendar labels and digits
- * @position Shared date utility; read by the i18n calendar resolution and by
- *   Calendar. Values stay Gregorian PlainDates. Temporal owns the arithmetic of
+ * @output Calendar months located by their Gregorian days, their year and
+ *   month numbers, month and year steps, dates from calendar fields,
+ *   availability of each calendar, and calendar labels and digits
+ * @position Shared date utility; read by the i18n calendar resolution, by
+ *   Calendar, and by its public hooks. Values stay Gregorian PlainDates. Temporal owns the arithmetic of
  *   every calendar whose months are not Gregorian.
  */
 
@@ -97,7 +97,7 @@ interface TemporalPlainDate {
   readonly day: number;
   readonly daysInMonth: number;
   readonly monthsInYear: number;
-  with(fields: {day: number}): TemporalPlainDate;
+  with(fields: {year?: number; month?: number; day: number}): TemporalPlainDate;
   add(duration: {months?: number; years?: number}): TemporalPlainDate;
   withCalendar(calendar: 'iso8601'): TemporalPlainDate;
 }
@@ -216,6 +216,61 @@ export function calendarMonthOf(
   return temporalMonth(inCalendar(calendar, pd).with({day: 1}));
 }
 
+/**
+ * A calendar month by its year and its position in that year, as
+ * `Temporal.PlainDate` numbers them: month 13 exists in a Hebrew leap year.
+ */
+export interface CalendarYearMonth {
+  readonly year: number;
+  readonly month: number;
+}
+
+// Temporal counts the years of these Gregorian-aligned calendars from another
+// epoch: 2026 is 2569 in `buddhist` and 115 in `roc`.
+const GREGORIAN_YEAR_OFFSETS: Partial<Record<CalendarSystem, number>> = {
+  buddhist: 543,
+  roc: -1911,
+};
+
+/** The year and month numbers of a calendar month. */
+export function calendarYearMonthOf(
+  calendar: CalendarSystem,
+  month: CalendarMonth,
+): CalendarYearMonth {
+  if (isGregorianAligned(calendar)) {
+    return {
+      year: month.start.year + (GREGORIAN_YEAR_OFFSETS[calendar] ?? 0),
+      month: month.start.month,
+    };
+  }
+  const {year, month: monthOfYear} = inCalendar(calendar, month.start);
+  return {year, month: monthOfYear};
+}
+
+/**
+ * The calendar month with these year and month numbers. A month past the end
+ * of its year becomes the last month of that year, as Temporal constrains it.
+ */
+export function calendarMonthFromYearMonth(
+  calendar: CalendarSystem,
+  {year, month}: CalendarYearMonth,
+): CalendarMonth {
+  if (isGregorianAligned(calendar)) {
+    return gregorianMonth(
+      year - (GREGORIAN_YEAR_OFFSETS[calendar] ?? 0),
+      month,
+    );
+  }
+  // `with` replaces the year and month of any date in the calendar.
+  return temporalMonth(
+    inCalendar(calendar, {year: 2000, month: 1, day: 1}).with({
+      year,
+      month,
+      day: 1,
+    }),
+  );
+}
+
 /** The calendar month `n` months after `month`, or before it when negative. */
 export function calendarAddMonths(
   calendar: CalendarSystem,