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

package/state/date-field.d.ts

@@ -0,0 +1,407 @@
+import type { SlotId } from "../slots/index.jsx";
+import { type Signal } from "@rivetjs/reactivity";
+import { CalendarDate, DateFormatter, Time, type AnyDateValue, type CalendarDateTime, type DateValueString, type ZonedDateTime } from "@rivetjs/cdk/date";
+import type { Calendar, CalendarIdentifier } from "@rivetjs/cdk/date";
+import { type FormValidationState, type MaybeAccessor, type ValidationBehavior, type ValidationErrors, type ValidationFunction, type ValidationResult } from "./form-validation.js";
+export type DateValue = AnyDateValue;
+export type TimeValue = Time | CalendarDateTime | ZonedDateTime;
+/** The date type emitted for a value of type `T`. */
+export type MappedDateValue<T> = T extends ZonedDateTime ? ZonedDateTime : T extends CalendarDateTime ? CalendarDateTime : T extends CalendarDate ? CalendarDate : never;
+/** The time type emitted for a value of type `T`. */
+export type MappedTimeValue<T> = T extends ZonedDateTime ? ZonedDateTime : T extends CalendarDateTime ? CalendarDateTime : T extends Time ? Time : never;
+export type { DateValueString } from "@rivetjs/cdk/date";
+export type Granularity = "day" | "hour" | "minute" | "second";
+export interface RangeValue<T> {
+    start: T;
+    end: T;
+}
+export type DateRange = RangeValue<DateValue>;
+/** A date value or its string form (`2026-10-04`, `2026-10-04T09:30`, …). */
+export type DateInput = DateValue | DateValueString;
+export type DateSegmentType = "era" | "year" | "month" | "day" | "hour" | "minute" | "second" | "dayPeriod" | "literal" | "timeZoneName";
+export interface DateSegment {
+    /** The type of segment. */
+    type: DateSegmentType;
+    /** The formatted text for the segment. */
+    text: string;
+    /** The numeric value for the segment, if applicable. */
+    value?: number | null;
+    /** The minimum numeric value for the segment, if applicable. */
+    minValue?: number;
+    /** The maximum numeric value for the segment, if applicable. */
+    maxValue?: number;
+    /** Whether the value is a placeholder. */
+    isPlaceholder: boolean;
+    /** A placeholder string for the segment. */
+    placeholder: string;
+    /** Whether the segment is editable. */
+    isEditable: boolean;
+}
+export declare function getPlaceholder(field: string, value: string, locale: string): string;
+export type FieldOptions = Pick<Intl.DateTimeFormatOptions, "year" | "month" | "day" | "hour" | "minute" | "second">;
+export interface FormatterOptions {
+    timeZone?: string;
+    hideTimeZone?: boolean;
+    granularity?: Granularity;
+    maxGranularity?: "year" | "month" | Granularity;
+    hourCycle?: 12 | 24;
+    showEra?: boolean;
+    shouldForceLeadingZeros?: boolean;
+}
+export declare function getValidationResult(value: DateValue | null, minValue: DateValue | null | undefined, maxValue: DateValue | null | undefined, isDateUnavailable: ((v: DateValue) => boolean) | undefined, options: FormatterOptions): ValidationResult;
+export declare function getRangeValidationResult(value: RangeValue<DateValue | null> | null, minValue: DateValue | null | undefined, maxValue: DateValue | null | undefined, isDateUnavailable: ((v: DateValue) => boolean) | undefined, options: FormatterOptions): ValidationResult;
+export declare function getFormatOptions(fieldOptions: FieldOptions, options: FormatterOptions): Intl.DateTimeFormatOptions;
+export declare function getPlaceholderTime(placeholderValue: DateValue | null | undefined): TimeValue;
+export declare function convertValue(value: DateValue | null | undefined, calendar: Calendar): DateValue | null | undefined;
+export declare function createPlaceholderDate(placeholderValue: DateValue | null | undefined, granularity: string, calendar: Calendar, timeZone: string | undefined): DateValue;
+/** Granularity / time zone kept from the last non-null value (`useDefaultProps` state). */
+export interface LastFormat {
+    granularity: Granularity;
+    timeZone: string | null;
+}
+/** `useDefaultProps`: default granularity and time zone from the value; when it is null, the last ones. */
+export declare function defaultProps(v: DateValue | null, granularity: Granularity | undefined, last: LastFormat): [Granularity, string | undefined];
+/** The `LastFormat` of a non-null value. */
+export declare const lastFormatOf: (v: DateValue) => LastFormat;
+/** Record the format of `v` (React's `setLastValue` during render). */
+export declare function noteLast(last: Signal<LastFormat>, v: DateValue | null): void;
+export declare const parseValue: (text: DateValueString | null | undefined) => DateValue | null;
+export declare const parseInput: (value: DateInput | null | undefined) => DateValue | null;
+export type HourCycle = "h12" | "h11" | "h23" | "h24";
+/** Plain fields of an `IncompleteDate` (what the display signal stores). */
+export interface IncompleteFields {
+    era: string | null;
+    year: number | null;
+    month: number | null;
+    day: number | null;
+    hour: number | null;
+    dayPeriod: number | null;
+    minute: number | null;
+    second: number | null;
+    millisecond: number | null;
+    offset: number | null;
+}
+/**
+ * This class represents a date that is incomplete or otherwise invalid as a result of user editing.
+ * For example, it can represent temporary dates such as February 31st if the user edits the day
+ * before the month. Times are represented according to an hour cycle rather than always in 24 hour
+ * time. This enables the user to adjust the day period (e.g. am/pm) independently from the hour.
+ */
+export declare class IncompleteDate {
+    calendar: Calendar;
+    era: string | null;
+    year: number | null;
+    month: number | null;
+    day: number | null;
+    hour: number | null;
+    hourCycle: HourCycle;
+    dayPeriod: number | null;
+    minute: number | null;
+    second: number | null;
+    millisecond: number | null;
+    offset: number | null;
+    constructor(calendar: Calendar, hourCycle: HourCycle, dateValue?: Partial<Record<string, unknown>> | null);
+    /** Rivet: restore from plain fields (no hour cycle conversion). */
+    static fromFields(calendar: Calendar, hourCycle: HourCycle, fields: IncompleteFields): IncompleteDate;
+    /** Rivet: the plain fields (JSON for the display signal). */
+    toFields(): IncompleteFields;
+    copy(): IncompleteDate;
+    /** Checks whether all the specified segments have a value. */
+    isComplete(segments: DateSegmentType[]): boolean;
+    /** Checks whether the given date value matches this value for the specified segments. */
+    validate(dt: DateValue, segments: DateSegmentType[]): boolean;
+    /** Checks if the date is empty (i.e. all specified segments are null). */
+    isCleared(segments: DateSegmentType[]): boolean;
+    /** Sets the given field. */
+    set(field: DateSegmentType, value: number | string, placeholder: DateValue): IncompleteDate;
+    /** Sets the given field to null. */
+    clear(field: DateSegmentType): IncompleteDate;
+    /**
+     * Increments or decrements the given field. If it is null, then it is set to the placeholder
+     * value.
+     */
+    cycle(field: DateSegmentType, amount: number, placeholder: DateValue, displaySegments: DateSegmentType[]): IncompleteDate;
+    /**
+     * Converts the incomplete date to a full date value, using the provided value for any unset
+     * fields.
+     */
+    toValue(value: DateValue): DateValue;
+    getSegmentLimits(type: string): {
+        value: number | null;
+        minValue: number;
+        maxValue: number;
+    } | undefined;
+}
+/** A DateRangePicker's value: the committed complete range plus the partial one its fields edit. */
+export interface RangeModel {
+    /** Committed value (complete range, or null). */
+    readonly value: Signal<RangeValue<DateValueString> | null>;
+    /** The placeholder range the fields edit (React Stately `placeholderValue` state). */
+    readonly partial: Signal<RangeValue<DateValueString | null>>;
+    readonly onChange?: ((value: RangeValue<DateValue> | null) => void) | undefined;
+}
+/** The effective range (`controlledValue || placeholderValue`; a stale complete placeholder resets). */
+export declare function rangeValueOf(model: RangeModel): RangeValue<DateValueString | null>;
+export declare const isCompleteRange: <T>(value: RangeValue<T | null> | null | undefined) => value is RangeValue<T>;
+/** A value cell the state may write: a Signal (two-way / internal). A read-only accessor (live controlled `value`) is
+ *  never written: a change only calls `onChange`. */
+export declare const isWritable: (cell: unknown) => cell is {
+    set(value: unknown): void;
+};
+/** React Stately `useDateRangePickerState` `setValue`: keeps the partial range, commits complete ones. */
+export declare function writeRange(model: RangeModel, newValue: RangeValue<DateValue | null> | null): void;
+/** Common props of a field / picker (formatting + built-in validation). */
+export interface DateOwnerBase {
+    readonly locale: string;
+    readonly minValue: DateValueString | null;
+    readonly maxValue: DateValueString | null;
+    readonly placeholderValue: DateValueString | null;
+    readonly granularityProp?: Granularity | undefined;
+    readonly hourCycleProp?: 12 | 24 | undefined;
+    readonly hideTimeZone?: boolean | undefined;
+    readonly shouldForceLeadingZeros?: boolean | undefined;
+    /** Flags at creation; read `ownerDisabled` / `ownerReadOnly` / `ownerRequired` (follow a live accessor). */
+    readonly isDisabled: boolean;
+    readonly isReadOnly: boolean;
+    readonly isRequired: boolean;
+    /** Live `isDisabled` / `isReadOnly` / `isRequired` accessors (live props P5; created by the component). */
+    readonly disabled?: (() => boolean | undefined) | undefined;
+    readonly readOnly?: (() => boolean | undefined) | undefined;
+    readonly required?: (() => boolean | undefined) | undefined;
+    /** Format of the last non-null value (`useDefaultProps`). */
+    readonly last: Signal<LastFormat>;
+    /**
+     * Client validation (`validate`, run on the date value) merged before the built-in one (min / max /
+     * unavailable), refreshed on writes. Rivet: the user's `validate` runs here, not in the form
+     * validation state, so it receives date objects while the state stays plain data.
+     */
+    readonly builtin: Signal<ValidationResult>;
+    /** Custom client validation (`validate`): gets the value as date object(s). */
+    readonly validate?: ValidationFunction<never> | undefined;
+    readonly validation: FormValidationState;
+}
+/** A single value owner: a standalone DateField / TimeField or a DatePicker. */
+export interface DateValueOwner extends DateOwnerBase {
+    /** `time`: a TimeField (`value` holds a `TimeValue` string; the field edits it as a date-time). */
+    readonly kind: "field" | "picker" | "time";
+    readonly value: Signal<DateValueString | null>;
+    readonly onChange?: ((value: never) => void) | undefined;
+    readonly isDateUnavailable?: ((date: DateValue) => boolean) | undefined;
+    /** TimeField: the time zone of `defaultValue` (useTimeFieldState `defaultValueTimeZone`). */
+    readonly defaultTimeZone?: string | undefined;
+}
+/** A DateRangePicker (range value owner). */
+export interface DateRangeOwner extends DateOwnerBase, RangeModel {
+    readonly kind: "range";
+    readonly isDateUnavailable?: ((date: DateValue, anchorDate: CalendarDate | null) => boolean) | undefined;
+    /** Native validity of the start / end fields' inputs (React Aria's per-field validation refs). */
+    readonly partValidity: Signal<RangeValue<ValidationResult>>;
+}
+export type DateOwner = DateValueOwner | DateRangeOwner;
+/** Whether the field / picker is disabled now (its live `isDisabled` accessor, else the creation value). Reads. */
+export declare const ownerDisabled: (owner: DateOwnerBase) => boolean;
+/** Whether the field / picker is read-only now. Reads. */
+export declare const ownerReadOnly: (owner: DateOwnerBase) => boolean;
+/** Whether the field / picker is required now. Reads. */
+export declare const ownerRequired: (owner: DateOwnerBase) => boolean;
+/** useTimeFieldState `convertValue`: a `Time` as the date-time on `date` (default today); date-times unchanged. */
+export declare function timeAsDateTime(value: TimeValue | null | undefined, date?: DateValue): DateValue | null;
+/** The owner's value as a date value string (a TimeField's `Time` becomes today's date-time). Reads. */
+export declare function ownerValueString(owner: DateValueOwner): DateValueString | null;
+/** The placeholder date of an owner (TimeField: placeholder time, default midnight, on today, zoned like the value). Reads. */
+export declare function ownerPlaceholder(owner: DateOwner): DateValue | null;
+/** Formatter options of an owner for its current value (validation messages, `formatValue`). */
+export declare function ownerFormat(owner: DateOwner): FormatterOptions;
+/** Built-in validation of the owner's current value. Reads the value. */
+export declare function builtinValidation(owner: DateOwner): ValidationResult;
+/** Refresh the built-in validation signal (after a write, or before validity is synced). */
+export declare function syncBuiltin(owner: DateOwner): void;
+/** Owner validation displayed (aria-invalid, data-invalid, error message). Reads. */
+export declare const ownerDisplayValidation: (owner: DateOwner) => ValidationResult;
+export interface DateFieldBaseOptions {
+    /** The minimum allowed date that a user may select. */
+    minValue?: DateInput | null;
+    /** The maximum allowed date that a user may select. */
+    maxValue?: DateInput | null;
+    /** A placeholder date that influences the format of the placeholder shown when no value is selected. Defaults to today's date at midnight. */
+    placeholderValue?: DateInput | null;
+    /** Whether to display the time in 12 or 24 hour format. By default, this is determined by the user's locale. */
+    hourCycle?: 12 | 24;
+    /** Determines the smallest unit that is displayed in the date picker. By default, this is `"day"` for dates, and `"minute"` for times. */
+    granularity?: Granularity;
+    /** Whether to hide the time zone abbreviation. */
+    hideTimeZone?: boolean;
+    /** Whether to always show leading zeros in the month, day, and hour fields. By default, this is determined by the user's locale. */
+    shouldForceLeadingZeros?: boolean;
+    /** Whether the field is disabled; an accessor stays live (`ownerDisabled`). */
+    isDisabled?: boolean | (() => boolean | undefined);
+    /** Whether the value is immutable; an accessor stays live (`ownerReadOnly`). */
+    isReadOnly?: boolean | (() => boolean | undefined);
+    /** Whether a value is required; an accessor stays live (`ownerRequired`). */
+    isRequired?: boolean | (() => boolean | undefined);
+    /** Controlled invalid state; an accessor stays live. */
+    isInvalid?: MaybeAccessor<boolean | undefined>;
+    /** @deprecated Use `isInvalid` instead. */
+    validationState?: "valid" | "invalid";
+    /** `native` (default for the components) or `aria`. */
+    validationBehavior?: ValidationBehavior;
+    /** Form field name (server errors of `<Form validationErrors>` apply by it). */
+    name?: string;
+    /** Server errors (from `<Form>` context, or passed directly). */
+    validationErrors?: MaybeAccessor<ValidationErrors | undefined>;
+    /** 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;
+}
+/**
+ * A controlled date prop: a date (or its string form), a two-way signal of the string form (resumable), or a
+ * read-only accessor of the string form (live props: `date-field/live-value.tsx` `liveDateValue`; never written).
+ */
+export type DateValueProp<T> = T | DateValueString | null | Signal<DateValueString | null> | (() => DateValueString | null);
+/** A value prop as the state's value signal: the caller's signal (two-way), or one starting at the plain value / default. */
+export declare function dateValueSignal<T extends DateValue | TimeValue>(value: DateValueProp<T> | undefined, defaultValue: T | DateValueString | null | undefined): Signal<DateValueString | null>;
+export interface DateFieldStateOptions<T extends DateValue = DateValue> extends DateFieldBaseOptions {
+    /** Controlled value: a date, or a two-way signal of its string form. */
+    value?: DateValueProp<T>;
+    /** Uncontrolled initial value. */
+    defaultValue?: T | DateValueString | null;
+    /** Called with the new value (date object, in the calendar of the original value). */
+    onChange?: (value: MappedDateValue<T> | null) => void;
+    /** Callback that is called for each date of the calendar. If it returns true, then the date is unavailable. */
+    isDateUnavailable?: (date: DateValue) => boolean;
+    /** Custom client validation of the value (a date object). */
+    validate?: ValidationFunction<MappedDateValue<T>>;
+    /** The maximum unit to display in the date field. @default 'year' */
+    maxGranularity?: "year" | "month" | Granularity;
+    id?: string;
+}
+/** Where a picker's field reads and writes its value (React Aria's `fieldProps` of useDatePicker / useDateRangePicker). */
+export type DateFieldOwnerLink = {
+    owner: DateValueOwner;
+} | {
+    owner: DateRangeOwner;
+    part: "start" | "end";
+};
+export interface DateFieldState {
+    readonly id: string;
+    readonly locale: string;
+    /** Display calendar system identifier (from the locale). */
+    readonly calendar: CalendarIdentifier;
+    readonly createCalendar?: (identifier: CalendarIdentifier) => Calendar;
+    /** Resolved hour cycle of the locale (and `hourCycle` prop). */
+    readonly hourCycle: HourCycle;
+    readonly maxGranularity: "year" | "month" | Granularity;
+    /** The owner of the value: its picker (absent: a standalone field owns its value). */
+    readonly owner?: DateOwner;
+    /** Range picker field: which end it edits. */
+    readonly part?: "start" | "end";
+    /** Field default value (`defaultValue ?? initial value`; form reset). */
+    readonly defaultValue: DateValueString | null;
+    /** Temporary display override while editing (plain IncompleteDate fields + the value it was based on). */
+    readonly display: Signal<{
+        base: DateValueString | null;
+        fields: IncompleteFields;
+    } | null>;
+    /**
+     * Rivet: React Aria's `hookData` (useDateField → useDateSegment): the field's labelling, set by
+     * `dateFieldProps` (`describedBy` is an accessor read by the first segment's binding).
+     */
+    /**
+     * React Aria `hookData`: the field's labelling the segments read. Plain data only (no closure over the state:
+     * the state would reference itself, a cycle the resume format rejects).
+     */
+    aria?: {
+        label?: string | undefined;
+        /** The user's `aria-labelledby`; a picker's field gets the picker's (an accessor: the picker label slot settles after mount). */
+        ownLabelledBy?: string | (() => string | undefined) | undefined;
+        hasLabel?: (() => boolean) | boolean | undefined;
+        descriptionId?: SlotId | undefined;
+        errorId?: SlotId | undefined;
+        /** The user's `aria-describedby`; a picker's field gets the picker's (an accessor, RA `fieldProps['aria-describedby']`). */
+        extraDescribedBy?: string | (() => string | undefined) | undefined;
+        /** A picker's field (`role="presentation"`): described only by `extraDescribedBy` (RA useDateField `roleSymbol`). */
+        presentation?: boolean | undefined;
+    };
+}
+/** A standalone DateField (its own value owner). */
+export interface StandaloneDateFieldState extends DateFieldState, DateValueOwner {
+}
+/** @internal Read-only `resolvedOptions()` of a (cached) formatter: never mutate the result. */
+export declare function resolvedOptionsOf(formatter: DateFormatter): Intl.ResolvedDateTimeFormatOptions;
+/** Owner fields shared by DateField / DatePicker / DateRangePicker state. */
+export declare function ownerBase(options: DateFieldBaseOptions, v: DateValue | null, locale: string): Omit<DateOwnerBase, "builtin" | "validation"> & {
+    builtin: Signal<ValidationResult>;
+};
+/**
+ * `useDateFieldState`: state of a standalone DateField (its own value + validation). Pickers
+ * create their fields with `createPickerFieldState`.
+ */
+export declare function createDateFieldState<T extends DateValue = DateValue>(options?: DateFieldStateOptions<T>): StandaloneDateFieldState;
+/** @internal A standalone field state (DateField, or TimeField with `kind: "time"`) over its value signal. */
+export declare function fieldState(options: Omit<DateFieldStateOptions, "value" | "validate" | "onChange"> & {
+    validate?: unknown;
+    onChange?: unknown;
+    defaultTimeZone?: string;
+}, value: Signal<DateValueString | null>, kind: "field" | "time"): StandaloneDateFieldState;
+/** The field of a DatePicker (`link.owner`) or one end of a DateRangePicker (`link.part`). */
+export declare function createPickerFieldState(link: DateFieldOwnerLink, options: {
+    id: string;
+    locale: string;
+    maxGranularity?: "year" | "month" | Granularity;
+    createCalendar?: (identifier: CalendarIdentifier) => Calendar;
+    defaultValue: DateValueString | null;
+}): DateFieldState;
+/** The value owner of a field: its picker, or the (standalone) field itself. */
+export declare const ownerOf: (state: DateFieldState) => DateOwner;
+/** The display calendar system of the field. */
+export declare function calendarOf(state: Pick<DateFieldState, "calendar" | "createCalendar">): Calendar;
+/** The field's value (string form; owner calendar). Reads. */
+export declare function fieldValueString(state: DateFieldState): DateValueString | null;
+/** The granularity for the field, based on the `granularity` prop and current value. Reads. */
+export declare const fieldGranularity: (state: DateFieldState) => Granularity;
+/** The current value in the display calendar (React Stately `state.value`). Reads. */
+export declare function fieldValue(state: DateFieldState): DateValue | null;
+/** The current display value: the editing override when it belongs to the current value, else the value. Reads. */
+export declare function displayValue(state: DateFieldState): IncompleteDate;
+/** The placeholder date used for unset segments (today at midnight unless `placeholderValue`). Reads. */
+export declare function placeholderDate(state: DateFieldState): DateValue;
+/** The segments the field displays (types only), from `maxGranularity` to the granularity. */
+export declare function displaySegments(state: DateFieldState): DateSegmentType[];
+/** The date formatter of the field (locale + format options). Reads. */
+export declare function fieldDateFormatter(state: DateFieldState): DateFormatter;
+/** The current value as a native `Date` (placeholder fields fill the unset ones). Reads. */
+export declare function fieldDateValue(state: DateFieldState): Date;
+/** A list of segments for the current value. Reads. */
+export declare function segments(state: DateFieldState): DateSegment[];
+/** Owner validation displayed for the field. Reads. */
+export declare const fieldDisplayValidation: (state: DateFieldState) => ValidationResult;
+/** Whether the date field is invalid, based on the `isInvalid`, `minValue`, and `maxValue` props. Reads. */
+export declare const isFieldInvalid: (state: DateFieldState) => boolean;
+/** @deprecated Use `isFieldInvalid`. */
+export declare const fieldValidationState: (state: DateFieldState) => "invalid" | null;
+/** Sets the field's value: a date, or an (incomplete) display value while editing. */
+export declare function setValue(state: DateFieldState, newValue: DateValue | IncompleteDate | null): void;
+/** Increments the given segment. Upon reaching the minimum or maximum value, the value wraps around to the opposite limit. */
+export declare const increment: (state: DateFieldState, part: DateSegmentType) => void;
+/** Decrements the given segment. Upon reaching the minimum or maximum value, the value wraps around to the opposite limit. */
+export declare const decrement: (state: DateFieldState, part: DateSegmentType) => void;
+/** Increments the given segment by a larger amount, rounding it to the nearest increment (15 minutes, 7 days, 5 years …). */
+export declare const incrementPage: (state: DateFieldState, part: DateSegmentType) => void;
+/** Decrements the given segment by a larger amount, rounding it to the nearest increment. */
+export declare const decrementPage: (state: DateFieldState, part: DateSegmentType) => void;
+/** Increments the given segment to its maxiumum value. */
+export declare function incrementToMax(state: DateFieldState, part: DateSegmentType): void;
+/** Decrements the given segment to its minimum value. */
+export declare function decrementToMin(state: DateFieldState, part: DateSegmentType): void;
+/** Sets the value of the given segment. */
+export declare function setSegment(state: DateFieldState, part: DateSegmentType, v: string | number): void;
+/** Updates the remaining unfilled segments with the placeholder value. */
+export declare function confirmPlaceholder(state: DateFieldState): void;
+/** Clears the value of the given segment, reverting it to the placeholder. */
+export declare function clearSegment(state: DateFieldState, part: DateSegmentType): void;
+/** Formats the current date value using the given options. Reads. */
+export declare function formatValue(state: DateFieldState, fieldOptions: FieldOptions): string;
+/** Gets a formatter based on state's props. */
+export declare function getFieldDateFormatter(state: DateFieldState, locale: string, formatOptions: FormatterOptions): DateFormatter;
+export { CalendarDate };