@astryxdesign/core 0.0.0-bootstrap.0 → 0.1.0-canary.08d4cf4

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

@@ -0,0 +1,17 @@
+/**
+ * @file index.ts
+ * @input Imports calendar-specific hooks
+ * @output Exports all calendar hooks
+ * @position Calendar hooks entry point; used by Calendar
+ *
+ * SYNC: When modified, update this header
+ */
+export { useCalendarDays } from './useCalendarDays';
+export type { CalendarDay, UseCalendarDaysOptions, UseCalendarDaysReturn, } from './useCalendarDays';
+export { useCalendarConstraints } from './useCalendarConstraints';
+export type { UseCalendarConstraintsOptions, UseCalendarConstraintsReturn, } from './useCalendarConstraints';
+export { useCalendarNavigation } from './useCalendarNavigation';
+export type { UseCalendarNavigationOptions, UseCalendarNavigationReturn, } from './useCalendarNavigation';
+export { useCalendarRovingTabindex } from './useCalendarRovingTabindex';
+export type { UseCalendarRovingTabindexOptions, UseCalendarRovingTabindexReturn, } from './useCalendarRovingTabindex';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/Calendar/hooks/index.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AAEH,OAAO,EAAC,eAAe,EAAC,MAAM,mBAAmB,CAAC;AAClD,YAAY,EACV,WAAW,EACX,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAC,sBAAsB,EAAC,MAAM,0BAA0B,CAAC;AAChE,YAAY,EACV,6BAA6B,EAC7B,4BAA4B,GAC7B,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAC,qBAAqB,EAAC,MAAM,yBAAyB,CAAC;AAC9D,YAAY,EACV,4BAA4B,EAC5B,2BAA2B,GAC5B,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAC,yBAAyB,EAAC,MAAM,6BAA6B,CAAC;AACtE,YAAY,EACV,gCAAgC,EAChC,+BAA+B,GAChC,MAAM,6BAA6B,CAAC"}

package/dist/Calendar/hooks/index.js

@@ -0,0 +1,15 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file index.ts
+ * @input Imports calendar-specific hooks
+ * @output Exports all calendar hooks
+ * @position Calendar hooks entry point; used by Calendar
+ *
+ * SYNC: When modified, update this header
+ */
+
+export { useCalendarDays } from "./useCalendarDays.js";
+export { useCalendarConstraints } from "./useCalendarConstraints.js";
+export { useCalendarNavigation } from "./useCalendarNavigation.js";
+export { useCalendarRovingTabindex } from "./useCalendarRovingTabindex.js";

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

@@ -0,0 +1,51 @@
+import type { ISODateString } from '../../utils/dateTypes';
+import { type PlainDate } from '../../utils/plainDate';
+/**
+ * Configuration for date constraints
+ */
+export interface UseCalendarConstraintsOptions {
+    /** Minimum selectable date in ISO format */
+    min?: ISODateString;
+    /** Maximum selectable date in ISO format */
+    max?: ISODateString;
+    /**
+     * Custom date constraint functions.
+     * Date is disabled if ANY function returns false.
+     */
+    dateConstraints?: ReadonlyArray<(date: Date) => boolean>;
+}
+/**
+ * Return type for useCalendarConstraints hook
+ */
+export interface UseCalendarConstraintsReturn {
+    /** Check if a PlainDate is disabled */
+    isDateDisabled: (date: PlainDate) => boolean;
+    /** Parsed min date (or null) */
+    minDate: PlainDate | null;
+    /** Parsed max date (or null) */
+    maxDate: PlainDate | null;
+}
+/**
+ * Hook for managing calendar date validation constraints.
+ *
+ * Provides a function to check if a date is disabled based on
+ * min/max bounds and custom constraint functions.
+ *
+ * @example
+ * ```
+ * const {isDateDisabled} = useCalendarConstraints({
+ *   min: '2026-01-01',
+ *   max: '2026-12-31',
+ *   dateConstraints: [
+ *     (date) => date.getDay() !== 0, // No Sundays (receives native Date)
+ *   ],
+ * });
+ *
+ * // Check if a PlainDate can be selected
+ * if (isDateDisabled({year: 2026, month: 6, day: 15})) {
+ *   console.log('This date is not selectable');
+ * }
+ * ```
+ */
+export declare function useCalendarConstraints(options: UseCalendarConstraintsOptions): UseCalendarConstraintsReturn;
+//# sourceMappingURL=useCalendarConstraints.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useCalendarConstraints.d.ts","sourceRoot":"","sources":["../../../src/Calendar/hooks/useCalendarConstraints.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,uBAAuB,CAAC;AACzD,OAAO,EACL,KAAK,SAAS,EAKf,MAAM,uBAAuB,CAAC;AAE/B;;GAEG;AACH,MAAM,WAAW,6BAA6B;IAC5C,4CAA4C;IAC5C,GAAG,CAAC,EAAE,aAAa,CAAC;IACpB,4CAA4C;IAC5C,GAAG,CAAC,EAAE,aAAa,CAAC;IACpB;;;OAGG;IACH,eAAe,CAAC,EAAE,aAAa,CAAC,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC;CAC1D;AAED;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C,uCAAuC;IACvC,cAAc,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,OAAO,CAAC;IAC7C,gCAAgC;IAChC,OAAO,EAAE,SAAS,GAAG,IAAI,CAAC;IAC1B,gCAAgC;IAChC,OAAO,EAAE,SAAS,GAAG,IAAI,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,6BAA6B,GACrC,4BAA4B,CAuC9B"}

package/dist/Calendar/hooks/useCalendarConstraints.js

@@ -0,0 +1,85 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useCalendarConstraints.ts
+ * @input Uses React useCallback, useMemo, PlainDate utilities
+ * @output Exports useCalendarConstraints hook for date validation
+ * @position Calendar-specific hook; used by Calendar
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/Calendar/hooks/index.ts
+ */
+import { useCallback, useMemo } from 'react';
+import { plainDateFromISO, plainDateToDate, plainDateIsBefore, plainDateIsAfter } from "../../utils/plainDate.js";
+
+/**
+ * Configuration for date constraints
+ */
+
+/**
+ * Return type for useCalendarConstraints hook
+ */
+
+/**
+ * Hook for managing calendar date validation constraints.
+ *
+ * Provides a function to check if a date is disabled based on
+ * min/max bounds and custom constraint functions.
+ *
+ * @example
+ * ```
+ * const {isDateDisabled} = useCalendarConstraints({
+ *   min: '2026-01-01',
+ *   max: '2026-12-31',
+ *   dateConstraints: [
+ *     (date) => date.getDay() !== 0, // No Sundays (receives native Date)
+ *   ],
+ * });
+ *
+ * // Check if a PlainDate can be selected
+ * if (isDateDisabled({year: 2026, month: 6, day: 15})) {
+ *   console.log('This date is not selectable');
+ * }
+ * ```
+ */
+export function useCalendarConstraints(options) {
+  const {
+    min,
+    max,
+    dateConstraints
+  } = options;
+
+  // Parse min/max dates
+  const minDate = useMemo(() => min ? plainDateFromISO(min) : null, [min]);
+  const maxDate = useMemo(() => max ? plainDateFromISO(max) : null, [max]);
+
+  // Check if a date is disabled
+  const isDateDisabled = useCallback(date => {
+    // Check min bound
+    if (minDate && plainDateIsBefore(date, minDate)) {
+      return true;
+    }
+
+    // Check max bound
+    if (maxDate && plainDateIsAfter(date, maxDate)) {
+      return true;
+    }
+
+    // Check custom constraints (convert to Date for public API compatibility)
+    if (dateConstraints) {
+      for (const constraint of dateConstraints) {
+        if (!constraint(plainDateToDate(date))) {
+          return true;
+        }
+      }
+    }
+    return false;
+  }, [minDate, maxDate, dateConstraints]);
+  return {
+    isDateDisabled,
+    minDate,
+    maxDate
+  };
+}

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

@@ -0,0 +1,59 @@
+import type { DayOfWeek, ISODateString } from '../../utils/dateTypes';
+import { type PlainDate } from '../../utils/plainDate';
+/**
+ * Represents a single day in the calendar grid.
+ */
+export interface CalendarDay {
+    /** The PlainDate for this day */
+    date: PlainDate;
+    /** ISO date string (YYYY-MM-DD) */
+    iso: ISODateString;
+    /** Whether this day is outside the current month */
+    isOutside: boolean;
+    /** The day number (1-31) */
+    dayNumber: number;
+}
+/**
+ * Configuration for calendar days generation
+ */
+export interface UseCalendarDaysOptions {
+    /** The year to generate days for */
+    year: number;
+    /** The month (1-based: 1 = January, 12 = December) */
+    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;
+}
+/**
+ * Return type for useCalendarDays hook
+ */
+export interface UseCalendarDaysReturn {
+    /** All days in the grid (includes outside days) */
+    days: CalendarDay[];
+    /** Days grouped into weeks */
+    weeks: CalendarDay[][];
+    /** Localized day names for the header */
+    dayNames: string[];
+    /** Total number of cells in the grid */
+    totalCells: number;
+}
+/**
+ * Hook for generating calendar day grids.
+ *
+ * Calculates all the days to display for a given month, including
+ * days from adjacent months to fill the grid.
+ *
+ * @example
+ * ```
+ * const {days, weeks, dayNames} = useCalendarDays({
+ *   year: 2026,
+ *   month: 1, // January (1-based)
+ *   weekStartsOn: 0, // Sunday
+ * });
+ * // days[i].date is a PlainDate { year, month (1-based), day }
+ * ```
+ */
+export declare function useCalendarDays(options: UseCalendarDaysOptions): UseCalendarDaysReturn;
+//# sourceMappingURL=useCalendarDays.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useCalendarDays.d.ts","sourceRoot":"","sources":["../../../src/Calendar/hooks/useCalendarDays.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAC,SAAS,EAAE,aAAa,EAAC,MAAM,uBAAuB,CAAC;AACpE,OAAO,EACL,KAAK,SAAS,EAKf,MAAM,uBAAuB,CAAC;AAE/B;;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,CA+EvB"}

package/dist/Calendar/hooks/useCalendarDays.js

@@ -0,0 +1,133 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useCalendarDays.ts
+ * @input Uses React useMemo, PlainDate utilities
+ * @output Exports useCalendarDays hook for generating calendar day grids
+ * @position Calendar-specific hook; used by Calendar
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/Calendar/hooks/index.ts
+ */
+import { useMemo } from 'react';
+import { plainDateToISO, getDaysInMonth, plainDateDayOfWeek, plainDateAddDays } from "../../utils/plainDate.js";
+
+/**
+ * Represents a single day in the calendar grid.
+ */
+
+/**
+ * Configuration for calendar days generation
+ */
+
+/**
+ * Return type for useCalendarDays hook
+ */
+
+/**
+ * Hook for generating calendar day grids.
+ *
+ * Calculates all the days to display for a given month, including
+ * days from adjacent months to fill the grid.
+ *
+ * @example
+ * ```
+ * const {days, weeks, dayNames} = useCalendarDays({
+ *   year: 2026,
+ *   month: 1, // January (1-based)
+ *   weekStartsOn: 0, // Sunday
+ * });
+ * // days[i].date is a PlainDate { year, month (1-based), day }
+ * ```
+ */
+export function useCalendarDays(options) {
+  const {
+    year,
+    month,
+    weekStartsOn = 0,
+    hasVariableRowCount = false
+  } = options;
+
+  // Calculate grid structure
+  const gridInfo = useMemo(() => {
+    const totalDaysInMonth = getDaysInMonth(year, month);
+
+    // Calculate starting offset based on weekStartsOn
+    let startingDayOfWeek = plainDateDayOfWeek({
+      year,
+      month,
+      day: 1
+    }) - weekStartsOn;
+    if (startingDayOfWeek < 0) {
+      startingDayOfWeek += 7;
+    }
+
+    // Calculate total cells
+    const totalDays = totalDaysInMonth + startingDayOfWeek;
+    const totalRows = hasVariableRowCount ? Math.ceil(totalDays / 7) : 6;
+    const totalCells = totalRows * 7;
+    return {
+      daysInMonth: totalDaysInMonth,
+      startingDayOfWeek,
+      totalCells
+    };
+  }, [year, month, weekStartsOn, hasVariableRowCount]);
+
+  // Generate day names
+  const dayNames = useMemo(() => {
+    const names = ['Su', 'Mo', 'Tu', 'We', 'Th', 'Fr', 'Sa'];
+    const rotated = [];
+    for (let i = 0; i < 7; i++) {
+      rotated.push(names[(i + weekStartsOn) % 7]);
+    }
+    return rotated;
+  }, [weekStartsOn]);
+
+  // Generate days array
+  const days = useMemo(() => {
+    const {
+      daysInMonth: totalDaysInMonth,
+      startingDayOfWeek,
+      totalCells
+    } = gridInfo;
+    const firstOfMonth = {
+      year,
+      month,
+      day: 1
+    };
+    const result = [];
+    for (let i = 0; i < totalCells; i++) {
+      const dayOffset = i - startingDayOfWeek + 1;
+      const isOutside = dayOffset < 1 || dayOffset > totalDaysInMonth;
+      const pd = 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 = [];
+    for (let i = 0; i < days.length; i += 7) {
+      result.push(days.slice(i, i + 7));
+    }
+    return result;
+  }, [days]);
+  return {
+    days,
+    weeks,
+    dayNames,
+    totalCells: gridInfo.totalCells
+  };
+}

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

@@ -0,0 +1,61 @@
+import type { ISODateString } from '../../utils/dateTypes';
+import { type PlainDate } from '../../utils/plainDate';
+/**
+ * Configuration for calendar navigation
+ */
+export interface UseCalendarNavigationOptions {
+    /** Initial value to determine starting month */
+    initialValue?: ISODateString;
+    /** Controlled focus date (which month is visible) */
+    focusDate?: ISODateString;
+    /** Callback when visible month changes */
+    onFocusDateChange?: (focusDate: ISODateString) => void;
+    /** Number of months to display */
+    numberOfMonths?: 1 | 2;
+}
+/**
+ * Return type for useCalendarNavigation hook
+ */
+export interface UseCalendarNavigationReturn {
+    /** The base month (first day of the focus month) as a PlainDate */
+    baseMonth: PlainDate;
+    /** Array of visible months to render as PlainDates */
+    visibleMonths: PlainDate[];
+    /** Formatted label for the month header */
+    monthYearLabel: string;
+    /** Navigate to previous/next month */
+    navigateMonth: (delta: number, focusedDate?: ISODateString, offset?: number) => void;
+    /** Target date to focus after navigation */
+    pendingFocus: ISODateString | null;
+    /** Clear the pending focus */
+    clearPendingFocus: () => void;
+}
+/**
+ * Hook for managing calendar month navigation.
+ *
+ * Handles the current focus date (which month is visible), previous/next
+ * navigation, and pending focus for keyboard navigation across months.
+ *
+ * @example
+ * ```
+ * const {
+ *   visibleMonths,
+ *   monthYearLabel,
+ *   navigateMonth,
+ *   pendingFocus,
+ *   clearPendingFocus,
+ * } = useCalendarNavigation({
+ *   initialValue: '2026-01-15',
+ *   numberOfMonths: 1,
+ * });
+ *
+ * // Navigate to next month
+ * navigateMonth(1);
+ *
+ * // Navigate from arrow key (with focus tracking)
+ * navigateMonth(1, focusedDate, 1); // horizontal offset
+ * navigateMonth(1, focusedDate, 7); // vertical offset
+ * ```
+ */
+export declare function useCalendarNavigation(options: UseCalendarNavigationOptions): UseCalendarNavigationReturn;
+//# sourceMappingURL=useCalendarNavigation.d.ts.map

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

@@ -0,0 +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,EASf,MAAM,uBAAuB,CAAC;AAE/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,CAwF7B"}

package/dist/Calendar/hooks/useCalendarNavigation.js

@@ -0,0 +1,132 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useCalendarNavigation.ts
+ * @input Uses React useState, useMemo, useCallback, PlainDate utilities
+ * @output Exports useCalendarNavigation hook for month navigation
+ * @position Calendar-specific hook; used by Calendar
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/Calendar/hooks/index.ts
+ */
+import { useState, useMemo, useCallback } from 'react';
+import { plainDateFromISO, plainDateToISO, plainDateToday, plainDateSetFirstOfMonth, plainDateAddMonths, plainDateAddDays, plainDateFormat, DATE_FORMAT_MONTH_YEAR } from "../../utils/plainDate.js";
+
+/**
+ * Configuration for calendar navigation
+ */
+
+/**
+ * Return type for useCalendarNavigation hook
+ */
+
+/**
+ * Hook for managing calendar month navigation.
+ *
+ * Handles the current focus date (which month is visible), previous/next
+ * navigation, and pending focus for keyboard navigation across months.
+ *
+ * @example
+ * ```
+ * const {
+ *   visibleMonths,
+ *   monthYearLabel,
+ *   navigateMonth,
+ *   pendingFocus,
+ *   clearPendingFocus,
+ * } = useCalendarNavigation({
+ *   initialValue: '2026-01-15',
+ *   numberOfMonths: 1,
+ * });
+ *
+ * // Navigate to next month
+ * navigateMonth(1);
+ *
+ * // Navigate from arrow key (with focus tracking)
+ * navigateMonth(1, focusedDate, 1); // horizontal offset
+ * navigateMonth(1, focusedDate, 7); // vertical offset
+ * ```
+ */
+export function useCalendarNavigation(options) {
+  const {
+    initialValue,
+    focusDate: focusDateProp,
+    onFocusDateChange,
+    numberOfMonths = 1
+  } = options;
+
+  // Pending focus target after month navigation
+  const [pendingFocus, setPendingFocus] = useState(null);
+
+  // Internal focus date state (PlainDate)
+  const [internalFocusDate, setInternalFocusDate] = useState(() => {
+    if (focusDateProp) {
+      return plainDateFromISO(focusDateProp);
+    }
+    if (initialValue) {
+      return plainDateFromISO(initialValue);
+    }
+    return plainDateToday();
+  });
+
+  // Determine if focus is controlled
+  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(() => {
+    return Array.from({
+      length: numberOfMonths
+    }, (_, i) => {
+      return plainDateAddMonths(baseMonth, i);
+    });
+  }, [baseMonth, numberOfMonths]);
+
+  // Format month header
+  const monthYearLabel = useMemo(() => {
+    if (numberOfMonths === 1) {
+      return plainDateFormat(visibleMonths[0], DATE_FORMAT_MONTH_YEAR);
+    }
+    return visibleMonths.map(m => plainDateFormat(m, DATE_FORMAT_MONTH_YEAR)).join(' – ');
+  }, [visibleMonths, numberOfMonths]);
+
+  // Navigate to previous/next month
+  const navigateMonth = useCallback((delta, focusedDate, offset) => {
+    const newMonth = plainDateAddMonths(baseMonth, delta);
+    const newISO = plainDateToISO(newMonth);
+
+    // Calculate target focus date if provided
+    if (focusedDate) {
+      const currentDate = plainDateFromISO(focusedDate);
+      // Use the provided offset (1 for horizontal, 7 for vertical)
+      const daysToMove = offset ?? 7;
+      const targetDate = plainDateAddDays(currentDate, delta * daysToMove);
+      setPendingFocus(plainDateToISO(targetDate));
+    }
+    if (onFocusDateChange) {
+      onFocusDateChange(newISO);
+    } else {
+      setInternalFocusDate(newMonth);
+    }
+  }, [baseMonth, onFocusDateChange]);
+
+  // Clear pending focus
+  const clearPendingFocus = useCallback(() => {
+    setPendingFocus(null);
+  }, []);
+  return {
+    baseMonth,
+    visibleMonths,
+    monthYearLabel,
+    navigateMonth,
+    pendingFocus,
+    clearPendingFocus
+  };
+}

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

@@ -0,0 +1,57 @@
+import type { ISODateString } from '../../utils/dateTypes';
+import { type PlainDate } from '../../utils/plainDate';
+import type { CalendarDay } from './useCalendarDays';
+/**
+ * Configuration for calendar roving tabindex
+ */
+export interface UseCalendarRovingTabindexOptions {
+    /** All days in the grid */
+    days: CalendarDay[];
+    /** Today's date as a PlainDate */
+    today: PlainDate;
+    /** The year being displayed */
+    year: number;
+    /** The month being displayed (1-based: 1 = January, 12 = December) */
+    month: number;
+    /** Function to check if a date is disabled */
+    isDateDisabled: (date: PlainDate) => boolean;
+    /** Currently selected date (if any) */
+    selectedDate?: PlainDate | null;
+}
+/**
+ * Return type for useCalendarRovingTabindex hook
+ */
+export interface UseCalendarRovingTabindexReturn {
+    /** The ISO date string of the tabbable element, or null */
+    tabbableDate: ISODateString | null;
+    /** Check if a specific date is the tabbable one */
+    isTabbable: (iso: ISODateString) => boolean;
+}
+/**
+ * Hook for managing roving tabindex in calendar grids.
+ *
+ * Implements the WAI-ARIA roving tabindex pattern where only one element
+ * in a group has tabindex="0" while others have tabindex="-1".
+ *
+ * Priority for tabbable element:
+ * 1. Today if visible in the current month and enabled
+ * 2. First enabled day in the month
+ *
+ * @example
+ * ```
+ * const {tabbableDate, isTabbable} = useCalendarRovingTabindex({
+ *   days,
+ *   today: {year: 2026, month: 1, day: 20},
+ *   year: 2026,
+ *   month: 1, // January (1-based)
+ *   isDateDisabled,
+ * });
+ *
+ * // In day rendering:
+ * <button tabIndex={isTabbable(day.iso) ? 0 : -1}>
+ *   {day.dayNumber}
+ * </button>
+ * ```
+ */
+export declare function useCalendarRovingTabindex(options: UseCalendarRovingTabindexOptions): UseCalendarRovingTabindexReturn;
+//# sourceMappingURL=useCalendarRovingTabindex.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useCalendarRovingTabindex.d.ts","sourceRoot":"","sources":["../../../src/Calendar/hooks/useCalendarRovingTabindex.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAC,KAAK,SAAS,EAAiB,MAAM,uBAAuB,CAAC;AACrE,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,mBAAmB,CAAC;AAEnD;;GAEG;AACH,MAAM,WAAW,gCAAgC;IAC/C,2BAA2B;IAC3B,IAAI,EAAE,WAAW,EAAE,CAAC;IACpB,kCAAkC;IAClC,KAAK,EAAE,SAAS,CAAC;IACjB,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAC;IACd,8CAA8C;IAC9C,cAAc,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,OAAO,CAAC;IAC7C,uCAAuC;IACvC,YAAY,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,+BAA+B;IAC9C,2DAA2D;IAC3D,YAAY,EAAE,aAAa,GAAG,IAAI,CAAC;IACnC,mDAAmD;IACnD,UAAU,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,OAAO,CAAC;CAC7C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,gCAAgC,GACxC,+BAA+B,CA0CjC"}