@skdx/react 0.28.0 → 0.29.0

package/dist/calendar/types.d.cts

@@ -1,4 +1,4 @@
-import type { DateInput } from '../utils/dateValue.cjs';
+import type { DateInput } from '../utils/date-value.cjs';
 import type { PrimitivePropsWithRef } from '../utils/primitive.cjs';
 /** One cell in a {@link Calendar} grid week, as produced by `getVisibleWeeks`. */
 export interface CalendarDay {
@@ -6,36 +6,21 @@ export interface CalendarDay {
     /** Whether this date falls outside the grid's displayed month (leading/trailing filler day). */
     outsideMonth: boolean;
 }
-/**
- * Selection count: 'single' (Date | null), 'multiple' (Date[]), or 'range'
- * ({ start: Date; end: Date | null } | null). Determines the shape of `value`.
- */
+/** Selection mode determining the shape of `value`: `'single'` (`Date | null`), `'multiple'` (`Date[]`), or `'range'` (`{ start: Date; end: Date | null } | null`). */
 export type CalendarSelectionMode = 'single' | 'multiple' | 'range';
-/**
- * A selected date range. `end` is `null` while the range is *anchored* — the
- * user has picked a start date and the next selection will close the range.
- */
+/** A selected date range; `end` is `null` while the range is anchored, awaiting a closing date. */
 export interface DateRange {
     /** First date of the range (always the earlier of the two once `end` is set). */
     start: Date;
     /** Last date of the range, or `null` while only the anchor has been picked. */
     end: Date | null;
 }
-/**
- * Calendar's selection shape following {@link CalendarSelectionMode}. Union
- * type (not discriminated props) for semantic parity across frameworks.
- */
+/** Calendar's selection shape following {@link CalendarSelectionMode}. */
 export type CalendarValue = Date | Date[] | DateRange | null;
-/**
- * Lenient input form of {@link CalendarValue}. Each Date position accepts ISO
- * strings; the whole selection accepts wire strings ('2026-08-10' single,
- * '2026-08-10,2026-08-14' set, '2026-08-10/2026-08-14' range, trailing / for
- * anchored range). Strings read as local-time calendar dates, never UTC.
- * Component emits the strict `Date` shape.
- */
+/** Lenient input form of {@link CalendarValue} that also accepts ISO date strings and wire strings (`'2026-08-10'` single, `'2026-08-10,2026-08-14'` set, `'2026-08-10/2026-08-14'` range) as local-time calendar dates. */
 export type CalendarValueInput = DateInput | ReadonlyArray<DateInput> | {
     start: DateInput;
-    end?: DateInput | null;
+    end?: DateInput | null | undefined;
 } | null;
 /** Where a date sits inside a selected range, for the `data-range-*` styling hooks. */
 export type RangePosition = 'start' | 'middle' | 'end';
@@ -44,12 +29,9 @@ export type RangePosition = 'start' | 'middle' | 'end';
  * pages never overlap; 'single' always moves one month.
  */
 export type CalendarPageBehavior = 'visible' | 'single';
-/**
- * Which grid a {@link Calendar} is showing. Ordered coarsest-last —
- * `CalendarHeading` steps *up* this list, activating a cell steps *down* it.
- */
+/** Which grid a {@link Calendar} is showing, ordered coarsest-last so `CalendarHeading` steps up this list and activation steps down it. */
 export type CalendarView = 'day' | 'month' | 'year';
-/** @internal Shared state distributed from {@link Calendar} to its parts via context. Not part of the public API. */
+/** @internal Shared state distributed from {@link Calendar} to its parts via context. */
 export interface CalendarContextValue {
     value: CalendarValue;
     selectionMode: CalendarSelectionMode;
@@ -62,31 +44,28 @@ export interface CalendarContextValue {
     weekStartsOn: number;
     /** Whether week rows show their ISO-8601 week number. */
     weekNumbers: boolean;
-    locale?: string;
+    locale?: string | undefined;
     /** Weekday names for `locale`, rotated to `weekStartsOn`, as `[short, long]` pairs. */
     weekDayNames: Array<{
         short: string;
         long: string;
     }>;
-    minDate?: Date;
-    maxDate?: Date;
+    minDate?: Date | undefined;
+    maxDate?: Date | undefined;
     readOnly: boolean;
     disabled: boolean;
     /** Whether a day from an adjacent month is pickable rather than natively disabled. */
     outsideDaySelectable: boolean;
     /**
-     * Predicate marking arbitrary dates as disabled, in addition to `minDate`/`maxDate`.
-     * A disabled cell is neither focusable nor clickable.
+     * Predicate marking arbitrary dates as disabled, in addition to `minDate`/`maxDate`; a disabled cell is neither focusable nor clickable.
      * @default undefined — no additional dates disabled.
      */
-    isDateDisabled?: (date: Date) => boolean;
+    isDateDisabled?: ((date: Date) => boolean) | undefined;
     /**
-     * Predicate marking dates as *unavailable* — a booked night, a closed day. Stays
-     * keyboard-reachable and announced via `aria-disabled`, unlike `isDateDisabled`,
-     * which skips the cell entirely.
+     * Predicate marking dates as *unavailable* — a booked night, a closed day — staying keyboard-reachable and announced via `aria-disabled`, unlike `isDateDisabled`.
      * @default undefined — every date is available.
      */
-    isDateUnavailable?: (date: Date) => boolean;
+    isDateUnavailable?: ((date: Date) => boolean) | undefined;
     onValueChange: (date: Date) => void;
     onMonthChange: (month: Date) => void;
     /** Moves one page back (`-1`) or forward (`1`) and announces it. */
@@ -107,179 +86,158 @@ export interface CalendarGridContextValue {
 /** Props for the {@link Calendar} root. */
 export interface CalendarProps extends Omit<PrimitivePropsWithRef<'div'>, 'defaultValue' | 'onChange'> {
     /**
-     * How many dates can be selected at once; determines the shape of `value`.
-     * See {@link CalendarSelectionMode}.
+     * How many dates can be selected at once, determining the shape of `value` per {@link CalendarSelectionMode}.
      * @default 'single'
      */
-    selectionMode?: CalendarSelectionMode;
+    selectionMode?: CalendarSelectionMode | undefined;
     /**
      * Current selection for controlled usage. Pair with `onValueChange`.
      * @default undefined — uncontrolled, tracks its own selection internally.
      */
-    value?: CalendarValueInput;
+    value?: CalendarValueInput | undefined;
     /**
      * Initial selection for uncontrolled usage, follows `selectionMode`.
      * @default null for `single`/`range`, `[]` for `multiple`.
      */
-    defaultValue?: CalendarValueInput;
+    defaultValue?: CalendarValueInput | undefined;
     /**
      * Fires with the whole new selection whenever a `CalendarCell` is chosen.
      * @default undefined — no-op if omitted.
      */
-    onValueChange?: (value: CalendarValue) => void;
+    onValueChange?: ((value: CalendarValue) => void) | undefined;
     /**
      * Displayed month, for controlled usage. Pair with `onMonthChange`.
      * @default undefined — uncontrolled, tracks its own displayed month internally.
      */
-    month?: DateInput;
+    month?: DateInput | undefined;
     /**
      * Initially displayed month, for uncontrolled usage.
      * @default undefined — defaults to the selection's month, or the current month.
      */
-    defaultMonth?: DateInput;
+    defaultMonth?: DateInput | undefined;
     /**
      * Fires with the newly displayed month whenever navigation changes it.
      * @default undefined — no-op if omitted.
      */
-    onMonthChange?: (month: Date) => void;
+    onMonthChange?: ((month: Date) => void) | undefined;
     /**
-     * The date holding the grid's roving tab stop, for controlled usage. Pair
-     * with `onFocusChange`. Distinct from `value` — focus moves on every arrow
-     * key and selects nothing.
+     * The date holding the grid's roving tab stop, for controlled usage (pair with `onFocusChange`); distinct from `value` since focus moves on every arrow key and selects nothing.
      * @default undefined — uncontrolled, tracks its own roving focus internally.
      */
-    focusedDate?: DateInput;
+    focusedDate?: DateInput | undefined;
     /**
      * Initially focused date, for uncontrolled usage.
      * @default undefined — the selection's anchor date, else the displayed month.
      */
-    defaultFocusedDate?: DateInput;
+    defaultFocusedDate?: DateInput | undefined;
     /**
      * Fires with the newly focused date whenever the grid's roving tab stop moves.
      * @default undefined — no-op if omitted.
      */
-    onFocusChange?: (date: Date) => void;
+    onFocusChange?: ((date: Date) => void) | undefined;
     /**
-     * Which grid is showing, for controlled usage. Pair with `onViewChange`. A
-     * non-day grid navigates only: activating a cell steps the view down
-     * without touching `value`.
+     * Which grid is showing, for controlled usage (pair with `onViewChange`); a non-day grid navigates only, since activating a cell steps the view down without touching `value`.
      * @default undefined — uncontrolled, tracks its own view internally.
      */
-    view?: CalendarView;
+    view?: CalendarView | undefined;
     /**
      * Which grid shows first, for uncontrolled usage.
      * @default 'day'
      */
-    defaultView?: CalendarView;
+    defaultView?: CalendarView | undefined;
     /**
      * The most granular view the calendar steps down to; raising it makes the
      * calendar navigation-only.
      * @default 'day'
      */
-    minView?: CalendarView;
+    minView?: CalendarView | undefined;
     /**
      * The least granular view the calendar steps up to, and how far
      * `CalendarHeading` goes.
      * @default 'year'
      */
-    maxView?: CalendarView;
+    maxView?: CalendarView | undefined;
     /**
      * Fires with the view now showing whenever it steps up or down.
      * @default undefined — no-op if omitted.
      */
-    onViewChange?: (view: CalendarView) => void;
+    onViewChange?: ((view: CalendarView) => void) | undefined;
     /**
      * How many consecutive months to display, starting at `month`.
      * @default 1
      */
-    numberOfMonths?: number;
+    numberOfMonths?: number | undefined;
     /**
      * BCP 47 tag to derive month and weekday names via Intl, and default `weekStartsOn`.
      * @default undefined — the runtime's own locale.
      */
-    locale?: string;
+    locale?: string | undefined;
     /**
      * Earliest selectable date; earlier dates render disabled.
      * @default undefined — no minimum.
      */
-    minDate?: DateInput;
+    minDate?: DateInput | undefined;
     /**
      * Latest selectable date; later dates render disabled.
      * @default undefined — no maximum.
      */
-    maxDate?: DateInput;
+    maxDate?: DateInput | undefined;
     /**
-     * Day of week the grid's first column represents (0=Sunday…6=Saturday).
-     * Derived from `locale` when omitted.
+     * Day of week the grid's first column represents (`0`=Sunday…`6`=Saturday), derived from `locale` when omitted.
      * @default undefined — derived from `locale`, falling back to `0` (Sunday).
      */
-    weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+    weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | undefined;
     /**
-     * How far the previous/next buttons move — `'visible'` pages by the whole
-     * displayed span (`numberOfMonths` months) so consecutive pages never
-     * overlap, `'single'` always moves one month. Only observable with
-     * `numberOfMonths` above 1.
+     * How far the previous/next buttons move — `'visible'` pages by the whole displayed span so consecutive pages never overlap, `'single'` always moves one month.
      * @default 'visible'
      */
-    pageBehavior?: CalendarPageBehavior;
+    pageBehavior?: CalendarPageBehavior | undefined;
     /**
-     * Label each week with its ISO-8601 number. ISO numbering runs from Monday
-     * independently of `weekStartsOn`.
+     * Labels each week with its ISO-8601 number, which runs from Monday independently of `weekStartsOn`.
      * @default false
      */
-    weekNumbers?: boolean;
+    weekNumbers?: boolean | undefined;
     /**
-     * Date treated as today: carries `data-today` and `aria-current="date"`.
-     * Read once per mount. Pass explicitly in SSR to prevent hydration mismatch
-     * when server and client are in different time zones.
+     * Date treated as today, carrying `data-today` and `aria-current="date"`; pass explicitly in SSR to prevent a hydration mismatch across time zones.
      * @default undefined — `new Date()`, read once when the calendar mounts.
      */
-    today?: DateInput;
+    today?: DateInput | undefined;
     /**
-     * Non-editable: cells stay focusable, `onValueChange` never fires, grid
-     * carries `aria-readonly="true"`. Distinct from `disabled`.
+     * Non-editable: cells stay focusable, `onValueChange` never fires, and the grid carries `aria-readonly="true"`, distinct from `disabled`.
      * @default false
      */
-    readOnly?: boolean;
+    readOnly?: boolean | undefined;
     /**
-     * Disables the whole calendar: cells carry the native `disabled` attribute,
-     * grid leaves the tab order, carries `aria-disabled="true"`. Use
-     * `isDateDisabled` for per-date disabling.
+     * Disables the whole calendar: cells carry the native `disabled` attribute, and the grid leaves the tab order and carries `aria-disabled="true"`.
      * @default false
      */
-    disabled?: boolean;
+    disabled?: boolean | undefined;
     /**
      * Allow selecting adjacent-month days. Enabled cells stay focusable and page
      * the calendar on selection.
      * @default false
      */
-    outsideDaySelectable?: boolean;
+    outsideDaySelectable?: boolean | undefined;
     /**
-     * Predicate marking arbitrary dates as disabled, in addition to
-     * `minDate`/`maxDate`. A disabled cell is not focusable or clickable.
+     * Predicate marking arbitrary dates as disabled, in addition to `minDate`/`maxDate`; a disabled cell is not focusable or clickable.
      * @default undefined — no additional dates disabled.
      */
-    isDateDisabled?: (date: Date) => boolean;
+    isDateDisabled?: ((date: Date) => boolean) | undefined;
     /**
-     * Predicate marking dates as *unavailable* — a booked night, a closed day.
-     * Stays keyboard-reachable and announced via `aria-disabled`, unlike
-     * `isDateDisabled` which skips the cell entirely.
+     * Predicate marking dates as *unavailable* — a booked night, a closed day — staying keyboard-reachable and announced via `aria-disabled`, unlike `isDateDisabled`.
      * @default undefined — every date is available.
      */
-    isDateUnavailable?: (date: Date) => boolean;
+    isDateUnavailable?: ((date: Date) => boolean) | undefined;
     /**
-     * Words the polite live-region message announced after a selection change
-     * in `multiple`/`range` mode, where no single cell's `aria-selected` flip
-     * carries it. Return `''` to announce nothing.
+     * Words the polite live-region message announced after a selection change in `multiple`/`range` mode; return `''` to announce nothing.
      * @default undefined — the built-in English wording ("Range selected, 1 May to 8 May.").
      */
-    getSelectionAnnouncement?: (value: CalendarValue, locale: string | undefined) => string;
+    getSelectionAnnouncement?: ((value: CalendarValue, locale: string | undefined) => string) | undefined;
     /**
-     * Words the polite live-region message announced when paging the grid, so a
-     * screen reader learns the whole view changed. Return `''` for nothing.
+     * Words the polite live-region message announced when paging the grid; return `''` for nothing.
      * @default undefined — `formatMonthLabel(month, locale)`, e.g. "février 2026".
      */
-    getMonthAnnouncement?: (month: Date, locale: string | undefined) => string;
+    getMonthAnnouncement?: ((month: Date, locale: string | undefined) => string) | undefined;
 }
 /** Props for {@link CalendarHeader}, the purely presentational wrapper around the month navigation row. */
 export interface CalendarHeaderProps extends PrimitivePropsWithRef<'div'> {
@@ -290,7 +248,7 @@ export interface CalendarHeadingProps extends PrimitivePropsWithRef<'div'> {
      * Which of the displayed months to label, `0` being the first.
      * @default 0
      */
-    monthOffset?: number;
+    monthOffset?: number | undefined;
 }
 /** Props for {@link CalendarPreviousButton}, which navigates to the previous month. */
 export interface CalendarPreviousButtonProps extends PrimitivePropsWithRef<'button'> {
@@ -305,7 +263,7 @@ export interface CalendarGridProps extends PrimitivePropsWithRef<'div'> {
      * only meaningful when the `Calendar` sets `numberOfMonths` above 1.
      * @default 0
      */
-    monthOffset?: number;
+    monthOffset?: number | undefined;
 }
 /** Props for {@link CalendarWeekNumber}, a `rowheader` cell carrying one week's ISO-8601 number. */
 export interface CalendarWeekNumberProps extends PrimitivePropsWithRef<'div'> {