@rivetjs/cdk 0.0.0-stage → 0.1.0-alpha.0

package/state/calendar.d.ts

@@ -0,0 +1,284 @@
+import { type Signal } from "@rivetjs/reactivity";
+import { CalendarDate, type Calendar, type CalendarIdentifier, type DateDuration } from "@rivetjs/cdk/date";
+import { type AnyDateValue, type DateValueString } from "@rivetjs/cdk/date";
+import type { CalendarDateTime, ZonedDateTime } from "@rivetjs/cdk/date";
+import { type CalendarMessageKey } from "../calendar/intl.js";
+export type DateValue = AnyDateValue;
+export type { DateValueString } from "@rivetjs/cdk/date";
+/** The date type emitted for a value of type `T` (types.ts). */
+export type MappedDateValue<T> = T extends ZonedDateTime ? ZonedDateTime : T extends CalendarDateTime ? CalendarDateTime : T extends CalendarDate ? CalendarDate : never;
+export type PageBehavior = "single" | "visible";
+export type CalendarSelectionMode = "single" | "multiple";
+/** `T` for single selection, `T[]` for multiple (types.ts). */
+export type CalendarValueType<T, M extends CalendarSelectionMode> = M extends "single" ? T : T[];
+export type FirstDayOfWeek = "sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat";
+export interface RangeValue<T> {
+    start: T;
+    end: T;
+}
+/** A date value or its string form (`2026-10-04`, `2026-10-04T09:30`, …). */
+export type DateInput = DateValue | DateValueString;
+export interface CalendarPropsBase {
+    /** The minimum allowed date that a user may select. */
+    minValue?: DateInput | null;
+    /** The maximum allowed date that a user may select. */
+    maxValue?: DateInput | null;
+    /** Whether the calendar is disabled (an accessor stays live: `isCalendarDisabled`). */
+    isDisabled?: boolean | (() => boolean | undefined);
+    /** Whether the calendar value is immutable (an accessor stays live: `isCalendarReadOnly`). */
+    isReadOnly?: boolean | (() => boolean | undefined);
+    /** Whether to automatically focus the calendar when it mounts. */
+    autoFocus?: boolean;
+    /** Controls the currently focused date: a date, or a two-way signal of its string form. */
+    focusedValue?: DateValue | null | Signal<DateValueString>;
+    /** The date that is focused when the calendar first mounts (uncontrolled). */
+    defaultFocusedValue?: DateInput | null;
+    /** Handler that is called when the focused date changes. */
+    onFocusChange?: (date: CalendarDate) => void;
+    /** @deprecated Use `isInvalid` instead. */
+    validationState?: "valid" | "invalid";
+    /** Whether the current selection is invalid according to application logic (an accessor stays live). */
+    isInvalid?: boolean | (() => boolean | undefined);
+    /** Paging by the visible duration (default) or one unit of it. */
+    pageBehavior?: PageBehavior;
+    /** The day that starts the week. */
+    firstDayOfWeek?: FirstDayOfWeek;
+    /** Alignment of the visible months on first render around the selection / today. */
+    selectionAlignment?: "start" | "center" | "end";
+    /** The number of weeks in a month (overrides the locale's). */
+    weeksInMonth?: number;
+}
+/**
+ * Props of `useCalendarState` (CalendarProps + CalendarStateOptions). Controlled `value`: a date
+ * (array for `selectionMode="multiple"`), or a two-way signal of its string form(s) (resumable).
+ */
+export interface CalendarStateOptions<T extends DateValue = DateValue, M extends CalendarSelectionMode = CalendarSelectionMode> extends CalendarPropsBase {
+    /** Whether single or multiple selection is enabled. Default `single`. */
+    selectionMode?: M;
+    /** Controlled value: a date (multiple: dates), or a signal of the string form (multiple: array of strings). */
+    value?: CalendarValueType<T | DateValueString | null, M> | Signal<DateValueString | null> | Signal<DateValueString[]>;
+    /** Uncontrolled initial value. */
+    defaultValue?: CalendarValueType<T | DateValueString | null, M> | readonly DateInput[];
+    /** Called with the new value (date objects, in the calendar of the original value). */
+    onChange?: (value: CalendarValueType<MappedDateValue<T>, M>) => void;
+    /** Returns true for dates that cannot be selected. */
+    isDateUnavailable?: (date: CalendarDate) => boolean;
+    /** The locale to display and edit the value according to (default: the enclosing `I18nProvider`'s, `useLocale()`). */
+    locale?: string;
+    /** Creates the display calendar system for an identifier (default: `createCalendar` of `@rivetjs/cdk/date`). */
+    createCalendar?: (identifier: CalendarIdentifier) => Calendar;
+    /** The amount of days that will be displayed at once. Default `{ months: 1 }`. */
+    visibleDuration?: DateDuration;
+    id?: string;
+}
+/** Props of `useRangeCalendarState`. Controlled `value`: a range of dates, or a two-way signal of `{ start, end }` string forms. */
+export interface RangeCalendarStateOptions<T extends DateValue = DateValue> extends CalendarPropsBase {
+    /** Controlled value: a range of dates, or a signal of `{ start, end }` string forms, or null. */
+    value?: RangeValue<T | DateValueString> | null | Signal<RangeValue<DateValueString> | null>;
+    defaultValue?: RangeValue<T | DateValueString> | null;
+    onChange?: (value: RangeValue<MappedDateValue<T>>) => void;
+    /** Whether non-contiguous ranges (containing unavailable dates) may be selected. */
+    allowsNonContiguousRanges?: boolean;
+    /** Returns true for dates that cannot be selected; `anchorDate` is the date the selection started on. */
+    isDateUnavailable?: (date: CalendarDate, anchorDate: CalendarDate | null) => boolean;
+    /** The locale (default: `useLocale()`). */
+    locale?: string;
+    createCalendar?: (identifier: CalendarIdentifier) => Calendar;
+    visibleDuration?: DateDuration;
+    id?: string;
+}
+export type CalendarStrings = Record<CalendarMessageKey, string>;
+interface StateBase {
+    readonly id: string;
+    readonly locale: string;
+    /** Display calendar system identifier (from the locale). */
+    readonly calendar: CalendarIdentifier;
+    readonly createCalendar?: (identifier: CalendarIdentifier) => Calendar;
+    readonly timeZone: string;
+    readonly visibleDuration: DateDuration;
+    readonly pageBehavior: PageBehavior;
+    readonly firstDayOfWeek?: FirstDayOfWeek;
+    readonly weeksInMonth?: number;
+    /** Flags at creation; read `isCalendarDisabled` / `isCalendarReadOnly` (follow a live accessor). */
+    readonly isDisabled: boolean;
+    readonly isReadOnly: boolean;
+    /** Live `isDisabled` / `isReadOnly` / `isInvalid` accessors (live props P5; created by the component). */
+    readonly disabled?: (() => boolean | undefined) | undefined;
+    readonly readOnly?: (() => boolean | undefined) | undefined;
+    readonly invalid?: (() => boolean | undefined) | undefined;
+    /** A static `isInvalid` / `validationState="invalid"` prop (a live `isInvalid` is `invalid`). */
+    readonly invalidProp: boolean;
+    readonly minValue: DateValueString | null;
+    readonly maxValue: DateValueString | null;
+    readonly onFocusChange?: (date: CalendarDate) => void;
+    /** Focused date (display calendar, string form). */
+    readonly focused: Signal<DateValueString>;
+    /** First visible date (string form). */
+    readonly start: Signal<DateValueString>;
+    /** Rivet: `focusedValue` is the caller's signal (writes from outside the calendar may leave the visible range). */
+    readonly focusControlled: boolean;
+    /** Focus is within the grid. */
+    readonly isFocused: Signal<boolean>;
+    /**
+     * Rivet: the cell interaction states RAC CalendarCell keeps per cell (useHover / usePress /
+     * useFocusRing), as the `cellKey` of the hovered / pressed / keyboard-focused cell (written by the
+     * grid's delegated handlers; read by the cells' `isHovered` / `isPressed` / `isFocusVisible`).
+     */
+    readonly hoveredCell: Signal<string | null>;
+    readonly pressedCell: Signal<string | null>;
+    readonly focusVisibleCell: Signal<string | null>;
+    readonly strings: CalendarStrings;
+    /** Rivet: React Aria's `hookData` (useCalendarBase → useCalendarGrid): the calendar's labelling, set by `calendarProps`. */
+    aria?: {
+        label?: string | undefined;
+        labelledBy?: string | undefined;
+    };
+}
+export interface CalendarState extends StateBase {
+    readonly mode: "single";
+    readonly selectionMode: CalendarSelectionMode;
+    readonly value: Signal<DateValueString | null> | Signal<DateValueString[]>;
+    readonly isDateUnavailable?: (date: CalendarDate) => boolean;
+    readonly onChange?: (value: never) => void;
+}
+export interface RangeCalendarState extends StateBase {
+    readonly mode: "range";
+    readonly value: Signal<RangeValue<DateValueString> | null>;
+    /** Range selection anchor (string form), null when not selecting. */
+    readonly anchor: Signal<DateValueString | null>;
+    readonly dragging: Signal<boolean>;
+    readonly allowsNonContiguousRanges: boolean;
+    readonly rangeUnavailable?: (date: CalendarDate, anchorDate: CalendarDate | null) => boolean;
+    readonly onChange?: (value: never) => void;
+}
+export type AnyCalendarState = CalendarState | RangeCalendarState;
+export declare function isInvalid(date: DateValue, minValue?: DateValue | null, maxValue?: DateValue | null): boolean;
+export declare function alignCenter(date: CalendarDate, duration: DateDuration, locale: string, minValue?: DateValue | null, maxValue?: DateValue | null): CalendarDate;
+export declare function alignStart(date: CalendarDate, duration: DateDuration, locale: string, minValue?: DateValue | null, maxValue?: DateValue | null): CalendarDate;
+export declare function alignEnd(date: CalendarDate, duration: DateDuration, locale: string, minValue?: DateValue | null, maxValue?: DateValue | null): CalendarDate;
+export declare function constrainStart(date: CalendarDate, aligned: CalendarDate, duration: DateDuration, locale: string, minValue?: DateValue | null, maxValue?: DateValue | null): CalendarDate;
+export declare function constrainValue(date: CalendarDate, minValue?: DateValue | null, maxValue?: DateValue | null): CalendarDate;
+export declare function previousAvailableDate(date: CalendarDate, minValue: DateValue, isDateUnavailable?: (date: CalendarDate) => boolean): CalendarDate | null;
+export declare function isEqualDuration(a: DateDuration, b: DateDuration): boolean;
+/** The display calendar of `state`. */
+export declare function getCalendar(state: Pick<StateBase, "calendar" | "createCalendar">): Calendar;
+/** Parse a display-calendar date string of the state. */
+export declare function readDate(state: Pick<StateBase, "calendar" | "createCalendar">, text: DateValueString): CalendarDate;
+/** `useCalendarState`: state of a Calendar (single or multiple selection). */
+export declare function createCalendarState<T extends DateValue = DateValue, M extends CalendarSelectionMode = "single">(options?: CalendarStateOptions<T, M>): CalendarState;
+/** `useRangeCalendarState`: state of a RangeCalendar. */
+export declare function createRangeCalendarState<T extends DateValue = DateValue>(options?: RangeCalendarStateOptions<T>): RangeCalendarState;
+/** Props-level min (string → value). */
+export declare const minValueOf: (state: StateBase) => DateValue | null;
+export declare const maxValueOf: (state: StateBase) => DateValue | null;
+/** Range calendar: the anchor date. Reads `anchor`. */
+export declare function anchorDate(state: AnyCalendarState): CalendarDate | null;
+/** `isDateUnavailable` as the inner calendar sees it (range: bound to the anchor). Reads `anchor`. */
+export declare function unavailablePredicate(state: AnyCalendarState): ((date: CalendarDate) => boolean) | undefined;
+/**
+ * Range calendar: the range available around the anchor. Reads `anchor` only when it can narrow
+ * anything (`isDateUnavailable` without `allowsNonContiguousRanges`): Rivet (resume) — a page button
+ * or grid reading it would otherwise be re-created on the first anchor change of a resumed page.
+ */
+export declare function availableRange(state: AnyCalendarState): {
+    start?: CalendarDate;
+    end?: CalendarDate;
+} | null;
+/** Effective min (range: narrowed to the available range). Reads `anchor`. */
+export declare function effectiveMin(state: AnyCalendarState): DateValue | null;
+/** Effective max. Reads `anchor`. */
+export declare function effectiveMax(state: AnyCalendarState): DateValue | null;
+/** The currently focused date (constrained to min / max). Reads `focused` (+ `anchor`). */
+export declare function focusedDate(state: AnyCalendarState): CalendarDate;
+/**
+ * First visible date. Rivet (resume): every focus write inside the calendar keeps `start` corrected
+ * (`syncStart`), so an uncontrolled focus reads `start` only; a `focusedValue` signal may be written from
+ * outside, so it reads the corrected start (`start`, `focused`). On a resumed page a binding wakes on the
+ * first change of any signal it read on the server (not the computed it read through): the grid rows,
+ * weekday header and page buttons depending on `focused` would be re-created on the first focus move /
+ * range anchor, replacing the focused cell.
+ */
+export declare function visibleStart(state: AnyCalendarState): CalendarDate;
+/** The date range that is currently visible. Reads `start` (+ `focused` when focus is controlled). */
+export declare function visibleRange(state: AnyCalendarState): RangeValue<CalendarDate>;
+/** Selected value in the display calendar (single: date or null; multiple: dates; range: `{start, end}` of the value). Reads `value`. */
+export declare function calendarValue(state: CalendarState): CalendarDate | null | CalendarDate[];
+/** Range value in the display calendar. Reads `value`. */
+export declare function rangeValue(state: RangeCalendarState): RangeValue<CalendarDate> | null;
+/** Range value as the original date values (calendar + time kept). Reads `value`. */
+export declare function rangeDateValue(state: RangeCalendarState): RangeValue<DateValue> | null;
+/** Range calendar: the highlighted range (anchor → focused while selecting, else the value). Reads `anchor`, `focused`, `value`. */
+export declare function highlightedRange(state: AnyCalendarState): RangeValue<CalendarDate> | null;
+/** Whether the calendar is disabled now (its live `isDisabled` accessor, else the creation value). Reads. */
+export declare const isCalendarDisabled: (state: AnyCalendarState) => boolean;
+/** Whether the calendar is read-only now. Reads. */
+export declare const isCalendarReadOnly: (state: AnyCalendarState) => boolean;
+/** Whether the selection is invalid (unavailable / outside min-max, or `isInvalid`). */
+export declare function isValueInvalid(state: AnyCalendarState): boolean;
+/** Deprecated `validationState`. */
+export declare const validationState: (state: AnyCalendarState) => "invalid" | null;
+/** Sets the focused date. */
+export declare const setFocusedDate: (state: AnyCalendarState, date: CalendarDate) => void;
+/** Sets whether focus is within the calendar. */
+export declare const setFocused: (state: AnyCalendarState, value: boolean) => void;
+/** Moves focus to the next calendar date. */
+export declare function focusNextDay(state: AnyCalendarState): void;
+/** Moves focus to the previous calendar date. */
+export declare function focusPreviousDay(state: AnyCalendarState): void;
+/** Moves focus to the next row of dates, e.g. the next week. */
+export declare function focusNextRow(state: AnyCalendarState): void;
+/** Moves focus to the previous row of dates. */
+export declare function focusPreviousRow(state: AnyCalendarState): void;
+/** Moves focus to the next page of dates, e.g. the next month if one month is visible. */
+export declare const focusNextPage: (state: AnyCalendarState) => void;
+/** Moves focus to the previous page of dates. */
+export declare const focusPreviousPage: (state: AnyCalendarState) => void;
+/** Moves focus to the start of the current section of dates, e.g. the start of the current month. */
+export declare function focusSectionStart(state: AnyCalendarState): void;
+/** Moves focus to the end of the current section of dates. */
+export declare function focusSectionEnd(state: AnyCalendarState): void;
+/** Moves focus to the next section (one displayed unit, or the next larger unit with `larger`). */
+export declare function focusNextSection(state: AnyCalendarState, larger?: boolean): void;
+/** Moves focus to the previous section. */
+export declare function focusPreviousSection(state: AnyCalendarState, larger?: boolean): void;
+/** Sets the selected value (React Stately `setValue`). */
+export declare function setValue(state: CalendarState, newValue: CalendarDate | CalendarDate[] | null): void;
+/** Selects the given date (range: anchors or completes the range). */
+export declare function selectDate(state: AnyCalendarState, date: CalendarDate): void;
+/** Selects the currently focused date (unless unavailable). */
+export declare function selectFocusedDate(state: AnyCalendarState): void;
+/** Sets the range selection anchor. */
+export declare function setAnchorDate(state: AnyCalendarState, date: CalendarDate | null): void;
+/** Range: sets the value (React Stately `setValue`). */
+export declare function setRangeValue(state: RangeCalendarState, value: RangeValue<DateValue> | null): void;
+/** Highlights the given date during range selection (hover / drag). */
+export declare function highlightDate(state: AnyCalendarState, date: CalendarDate): void;
+/** Commits the current selection (selects the focused date). */
+export declare function commitSelection(state: AnyCalendarState): void;
+/** Clears the current selection. */
+export declare function clearSelection(state: AnyCalendarState): void;
+/** Sets whether the user is dragging over the calendar. */
+export declare function setDragging(state: AnyCalendarState, value: boolean): void;
+/** Focuses the next available day before or after `anchor`. */
+export declare function focusNearestAvailableDate(state: AnyCalendarState, anchor: CalendarDate): void;
+/** Whether the date is outside min / max (range: also outside the available range). */
+export declare function isInvalidDate(state: AnyCalendarState, date: CalendarDate): boolean;
+/** Whether the date is currently selected. */
+export declare function isSelected(state: AnyCalendarState, date: CalendarDate): boolean;
+/** Whether the date is focused (focus within the grid). */
+export declare function isCellFocused(state: AnyCalendarState, date: CalendarDate): boolean;
+/** Whether the date is disabled (min / max, outside the visible range, or `isDisabled`). */
+export declare function isCellDisabled(state: AnyCalendarState, date: CalendarDate): boolean;
+/** Whether the date is unavailable (`isDateUnavailable`). */
+export declare function isCellUnavailable(state: AnyCalendarState, date: CalendarDate): boolean;
+/** Whether the previous visible range is out of bounds. */
+export declare function isPreviousVisibleRangeInvalid(state: AnyCalendarState): boolean;
+/** Whether the next visible range is out of bounds. */
+export declare function isNextVisibleRangeInvalid(state: AnyCalendarState): boolean;
+/** Dates in week `weekIndex` from `from` (default: the first visible date); null where the calendar system has no date. */
+export declare function getDatesInWeek(state: AnyCalendarState, weekIndex: number, from?: CalendarDate): (CalendarDate | null)[];
+/** Number of weeks displayed for the month of `from` (default: the first visible date). */
+export declare function getWeeksInMonth(state: AnyCalendarState, from?: CalendarDate): number;
+/** Format a localized string of the calendar. */
+export declare const message: (state: StateBase, key: CalendarMessageKey, variables?: Record<string, string>) => string;
+export { CalendarDate };