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

package/src/Calendar/getInitialFocusDate.ts

@@ -2,7 +2,7 @@
 
 /**
  * @file getInitialFocusDate.ts
- * @input PlainDate utilities, min/max bounds, today
+ * @input PlainDate and calendar-system utilities, min/max bounds, today
  * @output Exports getInitialFocusDate — the month Calendar opens on
  * @position Calendar-specific helper; used by Calendar.tsx
  *
@@ -15,11 +15,14 @@ import type {ISODateString, DateRange} from '../utils/dateTypes';
 import {
   type PlainDate,
   plainDateFromISO,
-  plainDateSetFirstOfMonth,
-  plainDateAddMonths,
   plainDateIsBefore,
   plainDateIsAfter,
 } from '../utils/plainDate';
+import {
+  type CalendarSystem,
+  calendarAddMonths,
+  calendarMonthOf,
+} from '../utils/calendarSystem';
 
 export interface InitialFocusDateOptions {
   /** Controlled visible month, if the consumer supplied one. */
@@ -34,6 +37,8 @@ export interface InitialFocusDateOptions {
   numberOfMonths: number;
   /** Today, injected so the caller keeps a single memoized source of "now". */
   today: PlainDate;
+  /** The calendar system whose months the panes show. Default: `gregory`. */
+  calendar?: CalendarSystem;
 }
 
 /**
@@ -57,7 +62,15 @@ export interface InitialFocusDateOptions {
 export function getInitialFocusDate(
   options: InitialFocusDateOptions,
 ): PlainDate {
-  const {focusDate, value, min, max, numberOfMonths, today} = options;
+  const {
+    focusDate,
+    value,
+    min,
+    max,
+    numberOfMonths,
+    today,
+    calendar = 'gregory',
+  } = options;
 
   if (focusDate) {
     return plainDateFromISO(focusDate);
@@ -76,13 +89,14 @@ export function getInitialFocusDate(
 
   if (maxDate && plainDateIsAfter(today, maxDate)) {
     const lastPaneOffset = Math.max(0, numberOfMonths - 1);
-    const shifted = plainDateAddMonths(
-      plainDateSetFirstOfMonth(maxDate),
+    const shifted = calendarAddMonths(
+      calendar,
+      calendarMonthOf(calendar, maxDate),
       -lastPaneOffset,
-    );
+    ).start;
     if (
       minDate &&
-      plainDateIsBefore(shifted, plainDateSetFirstOfMonth(minDate))
+      plainDateIsBefore(shifted, calendarMonthOf(calendar, minDate).start)
     ) {
       return minDate;
     }

package/src/Calendar/hooks/useCalendarDays.ts

@@ -4,9 +4,11 @@
 
 /**
  * @file useCalendarDays.ts
- * @input Uses React useMemo, useLocale, PlainDate utilities, generated CLDR weekday data
- * @output Exports useCalendarDays hook for generating calendar day grids
- * @position Calendar-specific hook; used by Calendar
+ * @input Uses React useMemo, useLocale, PlainDate and calendar-system
+ *   utilities, generated CLDR weekday data
+ * @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
@@ -17,12 +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 CalendarSystem,
+  calendarDayOfMonth,
+  calendarMonthFromYearMonth,
+} from '../../utils/calendarSystem';
+import {resolveShownCalendar} from '../../i18n/useCalendarSystem';
 
 /**
  * Represents a single day in the calendar grid.
@@ -42,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;
 }
 
 /**
@@ -80,71 +100,82 @@ 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 locale = useLocale();
-
-  // Calculate grid structure
-  const gridInfo = useMemo(() => {
-    const totalDaysInMonth = getDaysInMonth(year, month);
+  const {
+    year,
+    month,
+    weekStartsOn = 0,
+    hasVariableRowCount = false,
+    calendar: calendarOption = 'gregory',
+  } = options;
+  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);
+}
 
-    // Calculate starting offset based on weekStartsOn
-    let startingDayOfWeek =
-      plainDateDayOfWeek({year, month, day: 1}) - weekStartsOn;
-    if (startingDayOfWeek < 0) {
-      startingDayOfWeek += 7;
-    }
+interface MonthLayout {
+  first: PlainDate;
+  length: number;
+  weekStartsOn: DayOfWeek;
+  hasVariableRowCount: boolean;
+  /** The day number of a grid day, given its offset from the month's first day. */
+  dayNumberOf: (pd: PlainDate, offset: number) => number;
+}
 
-    // Calculate total cells
-    const totalDays = totalDaysInMonth + startingDayOfWeek;
-    const totalRows = hasVariableRowCount ? Math.ceil(totalDays / 7) : 6;
-    const totalCells = totalRows * 7;
+function layOutMonthDays(layout: MonthLayout): CalendarDay[] {
+  const {first, length, weekStartsOn, hasVariableRowCount, dayNumberOf} =
+    layout;
+  let startingDayOfWeek = plainDateDayOfWeek(first) - weekStartsOn;
+  if (startingDayOfWeek < 0) {
+    startingDayOfWeek += 7;
+  }
+  const totalRows = hasVariableRowCount
+    ? Math.ceil((length + startingDayOfWeek) / 7)
+    : 6;
+  const result: CalendarDay[] = [];
+  for (let i = 0; i < totalRows * 7; i++) {
+    const offset = i - startingDayOfWeek;
+    const pd = plainDateAddDays(first, offset);
+    result.push({
+      date: pd,
+      iso: plainDateToISO(pd),
+      isOutside: offset < 0 || offset >= length,
+      dayNumber: dayNumberOf(pd, offset),
+    });
+  }
+  return result;
+}
 
-    return {
-      daysInMonth: totalDaysInMonth,
-      startingDayOfWeek,
-      totalCells,
-    };
-  }, [year, month, weekStartsOn, hasVariableRowCount]);
+function useMonthGrid(
+  days: CalendarDay[],
+  weekStartsOn: DayOfWeek,
+): UseCalendarDaysReturn {
+  const locale = useLocale();
 
   const dayNames = useMemo(
     () => getWeekdayHeaderNames(locale, weekStartsOn),
     [locale, weekStartsOn],
   );
 
-  // Generate days array
-  const days = useMemo(() => {
-    const {
-      daysInMonth: totalDaysInMonth,
-      startingDayOfWeek,
-      totalCells,
-    } = gridInfo;
-    const firstOfMonth: PlainDate = {year, month, day: 1};
-    const result: CalendarDay[] = [];
-
-    for (let i = 0; i < totalCells; i++) {
-      const dayOffset = i - startingDayOfWeek + 1;
-      const isOutside = dayOffset < 1 || dayOffset > totalDaysInMonth;
-      const pd: PlainDate = isOutside
-        ? plainDateAddDays(firstOfMonth, dayOffset - 1)
-        : {year, month, day: dayOffset};
-
-      result.push({
-        date: pd,
-        iso: plainDateToISO(pd),
-        isOutside,
-        dayNumber: pd.day,
-      });
-    }
-
-    return result;
-  }, [year, month, gridInfo]);
-
-  // Group days into weeks
   const weeks = useMemo(() => {
     const result: CalendarDay[][] = [];
     for (let i = 0; i < days.length; i += 7) {
@@ -153,10 +184,5 @@ export function useCalendarDays(
     return result;
   }, [days]);
 
-  return {
-    days,
-    weeks,
-    dayNames,
-    totalCells: gridInfo.totalCells,
-  };
+  return {days, weeks, dayNames, totalCells: days.length};
 }

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/CheckboxInput/CheckboxInput.doc.mjs

@@ -109,7 +109,7 @@ export const docs = {
       name: 'size',
       type: "'sm' | 'md'",
       description:
-        'The size of the checkbox. sm for compact layouts, md for default.',
+        'The size of the checkbox. sm for compact layouts, md for default. Under a coarse pointer a labelled checkbox’s target grows toward 44 px through an invisible hit area. It never shrinks below the row and stops at half the gap to a closer neighbour; nothing changes size.',
       default: "'md'",
     },
     {
@@ -155,7 +155,7 @@ export const docs = {
       {
         name: '--_indicator-press-image',
         description:
-          "The row's touch press image, handed down to a first-party indicator that paints its own press. Set from the press paint only while the row itself is pressed; only this row declares it.",
+          "The row's touch press image, handed down to a first-party indicator that paints its own press. Set from the press paint only while the row itself is pressed, or, under a CheckboxList row that owns the press, from that row's press paint. Only this row declares it.",
         default: 'none',
         private: true,
       },
@@ -361,7 +361,8 @@ export const docsZh = {
     {
       name: 'size',
       type: "'sm' | 'md'",
-      description: '复选框尺寸。sm 用于紧凑布局，md 为默认。',
+      description:
+        '复选框尺寸。sm 用于紧凑布局，md 为默认。在粗指针（触摸）下，带可见标签的复选框的目标通过不可见的点击区域向 44 px 扩展。它不小于所在行，与相邻控件较近时止于间距的一半；尺寸不变。',
       default: "'md'",
     },
     {
@@ -403,7 +404,7 @@ export const docsZh = {
       {
         name: '--_indicator-press-image',
         description:
-          '复选框行的触摸按下图像，传递给自行绘制按下效果的第一方指示器。仅在该行自身被按下时根据按下涂层设置，只有该行声明它。',
+          '复选框行的触摸按下图像，传递给自行绘制按下效果的第一方指示器。仅在该行自身被按下时根据按下涂层设置；在拥有按下效果的 CheckboxList 行中，取该行的按下涂层。只有该行声明它。',
         default: 'none',
         private: true,
       },