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

package/state/disclosure.d.ts

@@ -0,0 +1,90 @@
+import { type Signal } from "@rivetjs/reactivity";
+import type { Key } from "@rivetjs/cdk/collections";
+export type { Key };
+/** Readable (and, when not controlled by a plain value, writable) value cell. */
+interface Cell<T> {
+    (): T;
+    set?: (value: T) => void;
+}
+export interface DisclosureProps {
+    /** Whether the disclosure is expanded (controlled): a plain value or a two-way Signal. */
+    isExpanded?: boolean | Signal<boolean> | (() => boolean);
+    /** Whether the disclosure is expanded by default (uncontrolled). */
+    defaultExpanded?: boolean;
+    /** Handler that is called when the disclosure expanded state changes. */
+    onExpandedChange?: (isExpanded: boolean) => void;
+}
+export interface DisclosureState {
+    /** Whether the disclosure is currently expanded (accessor: bind it). */
+    readonly isExpanded: Cell<boolean>;
+    /** A plain controlled value: never written. */
+    readonly controlled: boolean;
+    readonly onExpandedChange?: ((isExpanded: boolean) => void) | undefined;
+}
+/**
+ * Manages state for a disclosure widget (react-stately `useDisclosureState`). `isExpanded` may also be
+ * a read-only accessor (a `computed`, e.g. the group's `isKeyExpanded`): controlled, not written.
+ */
+export declare function createDisclosureState(props?: DisclosureProps): DisclosureState;
+/** Sets whether the disclosure is expanded (useControlledState setter: no-op when unchanged). */
+export declare function setExpanded(state: DisclosureState, isExpanded: boolean): void;
+/** Expand the disclosure. */
+export declare const expand: (state: DisclosureState) => void;
+/** Collapse the disclosure. */
+export declare const collapse: (state: DisclosureState) => void;
+/** Toggles the disclosure's visibility. */
+export declare const toggleDisclosure: (state: DisclosureState) => void;
+export interface DisclosureGroupProps {
+    /** Whether multiple items can be expanded at the same time (Rivet: or a Signal — Angular CDK accordion `multi` — or an accessor: live). */
+    allowsMultipleExpanded?: boolean | Signal<boolean> | (() => boolean | undefined);
+    /** Whether all items are disabled (a value, or an accessor: live; read with `isGroupDisabled(state)`). */
+    isDisabled?: boolean | (() => boolean | undefined);
+    /** The currently expanded keys in the group (controlled): a plain iterable, a two-way Signal or a read-only accessor (live prop; never written). */
+    expandedKeys?: Iterable<Key> | Signal<Set<Key>> | (() => Set<Key>);
+    /** The initial expanded keys in the group (uncontrolled). */
+    defaultExpandedKeys?: Iterable<Key>;
+    /** Handler that is called when items are expanded or collapsed. */
+    onExpandedChange?: (keys: Set<Key>) => unknown;
+}
+export interface DisclosureGroupState {
+    /** Whether multiple items can be expanded at the same time (read with `allowsMultiple(state)`). */
+    readonly allowsMultipleExpanded: boolean | Signal<boolean> | (() => boolean | undefined);
+    /** Whether all items are disabled, when the state was created (live: `isGroupDisabled(state)`). */
+    readonly isDisabled: boolean;
+    /** Rivet: the live `isDisabled` accessor (read by `isGroupDisabled`). */
+    readonly liveDisabled?: () => boolean | undefined;
+    /** A set of keys for items that are expanded (accessor). */
+    readonly expandedKeys: Cell<Set<Key>>;
+    /** A plain controlled `expandedKeys`: never written. */
+    readonly controlled: boolean;
+    readonly onExpandedChange?: ((keys: Set<Key>) => unknown) | undefined;
+    /** Rivet: keys of the rendered disclosures (Angular CDK accordion `openAll`); filled by `registerDisclosure`. */
+    readonly members: Key[];
+    /** Rivet: keys of the rendered disabled disclosures (`openAll` / `closeAll` leave them as they are). */
+    readonly disabledMembers: Key[];
+}
+/** Whether multiple items can be expanded at the same time (binding-safe read). */
+export declare const allowsMultiple: (state: DisclosureGroupState) => boolean;
+/** Whether all items are disabled now (binding-safe read: tracks a live `isDisabled`). */
+export declare const isGroupDisabled: (state: DisclosureGroupState) => boolean;
+/** Manages state for a group of disclosures, e.g. an accordion (react-stately `useDisclosureGroupState`). */
+export declare function createDisclosureGroupState(props?: DisclosureGroupProps): DisclosureGroupState;
+/** Replaces the set of expanded keys (useControlledState setter + single-expansion clamp). */
+export declare function setExpandedKeys(state: DisclosureGroupState, keys: Set<Key>): void;
+/** Whether the item `key` is expanded (binding accessor; keys compare as strings). */
+export declare const isKeyExpanded: (state: DisclosureGroupState, key: Key) => boolean;
+/** A computed of `isKeyExpanded` (serializable: a Disclosure's controlled `isExpanded` inside a group). */
+export declare const keyExpanded: (state: DisclosureGroupState, key: Key) => (() => boolean);
+/** Rivet: a rendered disclosure joins the group (for `openAll` / `closeAll`, Angular `UniqueSelectionDispatcher`). */
+export declare function registerDisclosure(state: DisclosureGroupState, key: Key, isDisabled?: boolean): void;
+/** Rivet: a disclosure leaves the group (Angular CDK accordion item destroyed). */
+export declare function unregisterDisclosure(state: DisclosureGroupState, key: Key): void;
+/**
+ * Rivet (Angular CDK accordion `openAll`): expands every registered enabled disclosure — only when
+ * multiple may be expanded; disabled disclosures keep their state.
+ */
+export declare function openAll(state: DisclosureGroupState): void;
+/** Rivet (Angular CDK accordion `closeAll`): collapses every enabled disclosure of the group (also in single mode). */
+export declare function closeAll(state: DisclosureGroupState): void;
+/** Toggles the expanded state for an item by its key. */
+export declare function toggleKey(state: DisclosureGroupState, key: Key): void;

package/state/disclosure.js

@@ -0,0 +1,148 @@
+// Ported from react-stately disclosure/useDisclosureState.ts + disclosure/useDisclosureGroupState.ts
+// (packages/react-stately/src/disclosure), Apache-2.0, © Adobe.
+//
+// Rivet:
+// - State = signals + JSON + free functions (methods take the state), so handlers capturing it resume.
+// - Controlled values follow useControlledState: a plain value (RAC controlled: never written, every
+//   change only calls `on…Change`), a Signal (two-way: written, then `on…Change`) or undefined
+//   (uncontrolled: an internal region signal starting at the default).
+// - The group's single-expansion clamp runs at creation and on every write instead of in an effect.
+// - Angular CDK accordion extras (user decision 2026-10-06: the accordion merges into Disclosure):
+//   `allowsMultipleExpanded` may be a Signal (Angular `multi` input), `openAll` / `closeAll` skip
+//   disabled disclosures (`registerDisclosure(state, key, isDisabled)`, `unregisterDisclosure`).
+// Deviation: group keys compare as strings (`id` props / DOM ids are strings; `1` and `"1"` match).
+import { computed, signal, untrack, _regionState } from "@rivetjs/reactivity";
+const isSignal = (value) => typeof value === "function";
+/**
+ * useControlledState over signals: `controlled` is true for a plain controlled value (the state is
+ * not written; only `onChange` is called).
+ */
+function cell(value, defaultValue) {
+    if (isSignal(value))
+        return { value, controlled: false };
+    if (value !== undefined)
+        return { value: signal(value), controlled: true };
+    return { value: _regionState(() => signal(defaultValue)), controlled: false };
+}
+/**
+ * Manages state for a disclosure widget (react-stately `useDisclosureState`). `isExpanded` may also be
+ * a read-only accessor (a `computed`, e.g. the group's `isKeyExpanded`): controlled, not written.
+ */
+export function createDisclosureState(props = {}) {
+    const v = props.isExpanded;
+    if (typeof v === "function" && !("set" in v))
+        return { isExpanded: v, controlled: true, onExpandedChange: props.onExpandedChange };
+    const c = cell(v, props.defaultExpanded || false);
+    return { isExpanded: c.value, controlled: c.controlled, onExpandedChange: props.onExpandedChange };
+}
+/** Sets whether the disclosure is expanded (useControlledState setter: no-op when unchanged). */
+export function setExpanded(state, isExpanded) {
+    if (untrack(state.isExpanded) === isExpanded)
+        return;
+    if (!state.controlled)
+        state.isExpanded.set?.(isExpanded);
+    state.onExpandedChange?.(isExpanded);
+}
+/** Expand the disclosure. */
+export const expand = (state) => setExpanded(state, true);
+/** Collapse the disclosure. */
+export const collapse = (state) => setExpanded(state, false);
+/** Toggles the disclosure's visibility. */
+export const toggleDisclosure = (state) => setExpanded(state, !untrack(state.isExpanded));
+/** Whether multiple items can be expanded at the same time (binding-safe read). */
+export const allowsMultiple = (state) => !!(typeof state.allowsMultipleExpanded === "function" ? state.allowsMultipleExpanded() : state.allowsMultipleExpanded);
+/** Whether all items are disabled now (binding-safe read: tracks a live `isDisabled`). */
+export const isGroupDisabled = (state) => (state.liveDisabled ? !!state.liveDisabled() : state.isDisabled);
+const clamp = (keys, multiple) => (multiple || keys.size <= 1 ? keys : new Set([keys.values().next().value]));
+/** Manages state for a group of disclosures, e.g. an accordion (react-stately `useDisclosureGroupState`). */
+export function createDisclosureGroupState(props = {}) {
+    const allowsMultipleExpanded = props.allowsMultipleExpanded ?? false;
+    const multiple = !!untrack(() => (typeof allowsMultipleExpanded === "function" ? allowsMultipleExpanded() : allowsMultipleExpanded));
+    const raw = props.expandedKeys;
+    const c = isSignal(raw)
+        ? cell(raw, new Set())
+        : cell(raw !== undefined ? new Set(raw) : undefined, new Set(props.defaultExpandedKeys ?? []));
+    const state = {
+        allowsMultipleExpanded,
+        isDisabled: typeof props.isDisabled === "function" ? !!untrack(props.isDisabled) : (props.isDisabled ?? false),
+        ...(typeof props.isDisabled === "function" ? { liveDisabled: props.isDisabled } : {}),
+        expandedKeys: c.value,
+        controlled: c.controlled,
+        onExpandedChange: props.onExpandedChange,
+        members: [],
+        disabledMembers: [],
+    };
+    // Ensure only one item is expanded if allowsMultipleExpanded is false (upstream: an effect).
+    const current = untrack(c.value);
+    const clamped = clamp(current, multiple);
+    if (clamped !== current)
+        setExpandedKeys(state, clamped);
+    return state;
+}
+/** Replaces the set of expanded keys (useControlledState setter + single-expansion clamp). */
+export function setExpandedKeys(state, keys) {
+    const next = clamp(keys, untrack(() => allowsMultiple(state)));
+    if (Object.is(untrack(state.expandedKeys), next))
+        return;
+    if (!state.controlled)
+        state.expandedKeys.set?.(next);
+    state.onExpandedChange?.(next);
+}
+/** Whether the item `key` is expanded (binding accessor; keys compare as strings). */
+export const isKeyExpanded = (state, key) => {
+    for (const k of state.expandedKeys())
+        if (String(k) === String(key))
+            return true;
+    return false;
+};
+/** A computed of `isKeyExpanded` (serializable: a Disclosure's controlled `isExpanded` inside a group). */
+export const keyExpanded = (state, key) => computed(() => isKeyExpanded(state, key));
+const has = (keys, key) => keys.some((k) => String(k) === String(key));
+const without = (keys, key) => {
+    const i = keys.findIndex((k) => String(k) === String(key));
+    if (i >= 0)
+        keys.splice(i, 1);
+};
+/** Rivet: a rendered disclosure joins the group (for `openAll` / `closeAll`, Angular `UniqueSelectionDispatcher`). */
+export function registerDisclosure(state, key, isDisabled = false) {
+    if (!has(state.members, key))
+        state.members.push(key);
+    if (isDisabled && !has(state.disabledMembers, key))
+        state.disabledMembers.push(key);
+}
+/** Rivet: a disclosure leaves the group (Angular CDK accordion item destroyed). */
+export function unregisterDisclosure(state, key) {
+    without(state.members, key);
+    without(state.disabledMembers, key);
+}
+/**
+ * Rivet (Angular CDK accordion `openAll`): expands every registered enabled disclosure — only when
+ * multiple may be expanded; disabled disclosures keep their state.
+ */
+export function openAll(state) {
+    if (!untrack(() => allowsMultiple(state)))
+        return;
+    const keys = new Set(untrack(state.expandedKeys));
+    for (const key of state.members)
+        if (!has(state.disabledMembers, key))
+            keys.add(key);
+    setExpandedKeys(state, keys);
+}
+/** Rivet (Angular CDK accordion `closeAll`): collapses every enabled disclosure of the group (also in single mode). */
+export function closeAll(state) {
+    setExpandedKeys(state, new Set([...untrack(state.expandedKeys)].filter((key) => has(state.disabledMembers, key))));
+}
+/** Toggles the expanded state for an item by its key. */
+export function toggleKey(state, key) {
+    const current = untrack(state.expandedKeys);
+    const has = untrack(() => isKeyExpanded(state, key));
+    let keys;
+    if (untrack(() => allowsMultiple(state))) {
+        keys = new Set([...current].filter((k) => String(k) !== String(key)));
+        if (!has)
+            keys.add(key);
+    }
+    else
+        keys = new Set(has ? [] : [key]);
+    setExpandedKeys(state, keys);
+}

package/state/form-validation.d.ts

@@ -0,0 +1,89 @@
+import { type Signal } from "@rivetjs/reactivity";
+/** Snapshot of `ValidityState` (the native object is live and not serializable). */
+export interface ValidityDetails {
+    badInput: boolean;
+    customError: boolean;
+    patternMismatch: boolean;
+    rangeOverflow: boolean;
+    rangeUnderflow: boolean;
+    stepMismatch: boolean;
+    tooLong: boolean;
+    tooShort: boolean;
+    typeMismatch: boolean;
+    valueMissing: boolean;
+    valid: boolean;
+}
+export interface ValidationResult {
+    /** Whether the input value is invalid. */
+    isInvalid: boolean;
+    /** The current error messages for the input if it is invalid, otherwise an empty array. */
+    validationErrors: string[];
+    /** The native validation details for the input. */
+    validationDetails: ValidityDetails;
+}
+/** Server errors per field name (RAC `Form validationErrors`). */
+export type ValidationErrors = Record<string, string | string[]>;
+/** Custom client validation: error message(s), or `true` / null / undefined when valid. */
+export type ValidationFunction<T> = (value: T) => string | string[] | true | null | undefined;
+export type ValidationBehavior = "aria" | "native";
+export declare const VALID_VALIDITY_STATE: ValidityDetails;
+export declare const DEFAULT_VALIDATION_RESULT: ValidationResult;
+/** A value or an accessor (props that may read signals are accessors: the component body must not read). */
+export type MaybeAccessor<T> = T | (() => T);
+export declare const read: <T>(value: MaybeAccessor<T>) => T;
+export interface FormValidationOptions<T> {
+    /** Controlled invalid state (`true` / `false`); a signal or accessor stays live. */
+    isInvalid?: MaybeAccessor<boolean | undefined>;
+    /** Legacy `validationState="invalid"`. */
+    validationState?: "valid" | "invalid";
+    /** Custom client validation of the current value. */
+    validate?: ValidationFunction<T>;
+    /** `native` (default for the components): constraint validation blocks submit, errors show on commit; `aria`: realtime, never blocks. */
+    validationBehavior?: ValidationBehavior;
+    /** Field name(s) whose server errors (`validationErrors`) apply. */
+    name?: string | string[];
+    /** Server errors (from `<Form validationErrors>` context, or passed directly). */
+    validationErrors?: MaybeAccessor<ValidationErrors | undefined>;
+    /** Built-in validation of a composite state (e.g. CheckboxGroup required), valid → ignored. */
+    builtinValidation?: MaybeAccessor<ValidationResult | undefined>;
+}
+export interface FormValidationState {
+    readonly behavior: ValidationBehavior;
+    /** Current value accessor (the field's value signal). */
+    readonly value: () => unknown;
+    readonly isInvalid: MaybeAccessor<boolean | undefined> | undefined;
+    readonly validate: ValidationFunction<any> | undefined;
+    readonly name: string | string[] | undefined;
+    readonly serverErrors: MaybeAccessor<ValidationErrors | undefined> | undefined;
+    readonly builtin: MaybeAccessor<ValidationResult | undefined> | undefined;
+    /** Committed (displayed) validation result — RA `currentValidity`. */
+    readonly current: Signal<ValidationResult>;
+    /** The server-errors object the user cleared by editing (`isServerErrorCleared` keyed by identity: a new object shows again). */
+    readonly cleared: Signal<ValidationErrors | null | undefined>;
+    /** Native mode: the next result (from native validity), shown on commit — RA `nextValidation` ref. */
+    readonly next: Signal<ValidationResult>;
+}
+/** Create the validation state of a field. `value` is the field's value accessor (pass the value signal). */
+export declare function createFormValidationState<T>(options: FormValidationOptions<T> & {
+    value: () => T;
+}): FormValidationState;
+export declare function runValidate<T>(validate: ValidationFunction<T> | undefined, value: T): string[];
+export declare function getValidationResult(errors: string[]): ValidationResult | null;
+export declare function isEqualValidation(a: ValidationResult | null | undefined, b: ValidationResult | null | undefined): boolean;
+export declare function mergeValidation(...results: ValidationResult[]): ValidationResult;
+/** Realtime validation (drives the native custom validity). Reads the value, controlled and server errors. */
+export declare function realtimeValidation(state: FormValidationState): ValidationResult;
+/** Displayed validation (aria-invalid, error message). `native`: committed results only (after change / blur / submit). */
+export declare function displayValidation(state: FormValidationState): ValidationResult;
+/** Store a validation result (native validity). `aria`: shown at once; `native`: shown on the next commit. */
+export declare function updateValidation(state: FormValidationState, result: ValidationResult): void;
+/** Hide the current server errors (RA `setServerErrorCleared(true)`); a new errors object shows again. */
+export declare function clearServerErrors(state: FormValidationState): void;
+/** Reset the displayed result to valid (form reset); server errors are cleared too. */
+export declare function resetValidation(state: FormValidationState): void;
+/**
+ * Commit the realtime validation so the user sees it (blur / change / submit). Also clears server
+ * errors. RA defers the commit to after the next render; handlers here run after the value signal
+ * was written, so the commit is immediate.
+ */
+export declare function commitValidation(state: FormValidationState): void;

package/state/form-validation.js

@@ -0,0 +1,158 @@
+// Ported from react-stately `useFormValidationState` (packages/react-stately/src/form/useFormValidationState.ts),
+// Apache-2.0, © Adobe. Rivet: plain signals + JSON (serializable, resumable); "realtime" / "display"
+// validation are read functions (bindings call them) instead of per-render values.
+import { signal, untrack } from "@rivetjs/reactivity";
+export const VALID_VALIDITY_STATE = {
+    badInput: false,
+    customError: false,
+    patternMismatch: false,
+    rangeOverflow: false,
+    rangeUnderflow: false,
+    stepMismatch: false,
+    tooLong: false,
+    tooShort: false,
+    typeMismatch: false,
+    valueMissing: false,
+    valid: true,
+};
+const CUSTOM_VALIDITY_STATE = { ...VALID_VALIDITY_STATE, customError: true, valid: false };
+export const DEFAULT_VALIDATION_RESULT = {
+    isInvalid: false,
+    validationDetails: VALID_VALIDITY_STATE,
+    validationErrors: [],
+};
+export const read = (value) => (typeof value === "function" ? value() : value);
+/** Create the validation state of a field. `value` is the field's value accessor (pass the value signal). */
+export function createFormValidationState(options) {
+    let isInvalid = options.isInvalid;
+    if (options.validationState === "invalid" && isInvalid === undefined)
+        isInvalid = true;
+    return {
+        behavior: options.validationBehavior ?? "aria",
+        value: options.value,
+        isInvalid,
+        validate: options.validate,
+        name: options.name,
+        serverErrors: options.validationErrors,
+        builtin: options.builtinValidation,
+        current: signal(DEFAULT_VALIDATION_RESULT),
+        cleared: signal(null),
+        next: signal(DEFAULT_VALIDATION_RESULT),
+    };
+}
+function asArray(v) {
+    if (!v)
+        return [];
+    return Array.isArray(v) ? v : [v];
+}
+export function runValidate(validate, value) {
+    if (typeof validate === "function") {
+        const e = validate(value);
+        if (e && typeof e !== "boolean")
+            return asArray(e);
+    }
+    return [];
+}
+export function getValidationResult(errors) {
+    return errors.length ? { isInvalid: true, validationErrors: errors, validationDetails: CUSTOM_VALIDITY_STATE } : null;
+}
+export function isEqualValidation(a, b) {
+    if (a === b)
+        return true;
+    return (!!a &&
+        !!b &&
+        a.isInvalid === b.isInvalid &&
+        a.validationErrors.length === b.validationErrors.length &&
+        a.validationErrors.every((e, i) => e === b.validationErrors[i]) &&
+        Object.keys(a.validationDetails).every((k) => b.validationDetails[k] === a.validationDetails[k]));
+}
+export function mergeValidation(...results) {
+    const errors = new Set();
+    let isInvalid = false;
+    const validationDetails = { ...VALID_VALIDITY_STATE };
+    for (const v of results) {
+        for (const e of v.validationErrors)
+            errors.add(e);
+        isInvalid ||= v.isInvalid;
+        for (const key in validationDetails) {
+            const k = key;
+            validationDetails[k] ||= v.validationDetails[k];
+        }
+    }
+    validationDetails.valid = !isInvalid;
+    return { isInvalid, validationErrors: [...errors], validationDetails };
+}
+const controlledError = (state) => {
+    const invalid = state.isInvalid === undefined ? undefined : read(state.isInvalid);
+    return invalid !== undefined ? { isInvalid: invalid, validationErrors: [], validationDetails: CUSTOM_VALIDITY_STATE } : null;
+};
+const clientError = (state) => {
+    if (!state.validate)
+        return null;
+    const value = state.value();
+    if (value == null)
+        return null;
+    return getValidationResult(runValidate(state.validate, value));
+};
+const builtinError = (state) => {
+    const builtin = state.builtin === undefined ? undefined : read(state.builtin);
+    return builtin && !builtin.validationDetails.valid ? builtin : null;
+};
+function serverError(state) {
+    if (state.serverErrors === undefined || state.name === undefined)
+        return null;
+    const errors = read(state.serverErrors);
+    if (!errors || state.cleared() === errors)
+        return null;
+    const { name } = state;
+    const messages = Array.isArray(name) ? name.flatMap((n) => asArray(errors[n])) : asArray(errors[name]);
+    return getValidationResult(messages);
+}
+/** Realtime validation (drives the native custom validity). Reads the value, controlled and server errors. */
+export function realtimeValidation(state) {
+    return controlledError(state) || serverError(state) || clientError(state) || builtinError(state) || DEFAULT_VALIDATION_RESULT;
+}
+/** Displayed validation (aria-invalid, error message). `native`: committed results only (after change / blur / submit). */
+export function displayValidation(state) {
+    if (state.behavior === "native")
+        return controlledError(state) || serverError(state) || state.current();
+    return controlledError(state) || serverError(state) || clientError(state) || builtinError(state) || state.current();
+}
+/** Store a validation result (native validity). `aria`: shown at once; `native`: shown on the next commit. */
+export function updateValidation(state, result) {
+    if (state.behavior === "aria") {
+        if (!isEqualValidation(untrack(state.current), result))
+            state.current.set(result);
+    }
+    else if (!isEqualValidation(untrack(state.next), result))
+        state.next.set(result);
+}
+/** Hide the current server errors (RA `setServerErrorCleared(true)`); a new errors object shows again. */
+export function clearServerErrors(state) {
+    if (state.serverErrors === undefined)
+        return;
+    const errors = untrack(() => read(state.serverErrors));
+    if (errors && untrack(state.cleared) !== errors)
+        state.cleared.set(errors);
+}
+/** Reset the displayed result to valid (form reset); server errors are cleared too. */
+export function resetValidation(state) {
+    if (!isEqualValidation(untrack(state.current), DEFAULT_VALIDATION_RESULT))
+        state.current.set(DEFAULT_VALIDATION_RESULT);
+    if (state.behavior === "native" && !isEqualValidation(untrack(state.next), DEFAULT_VALIDATION_RESULT))
+        state.next.set(DEFAULT_VALIDATION_RESULT);
+    clearServerErrors(state);
+}
+/**
+ * Commit the realtime validation so the user sees it (blur / change / submit). Also clears server
+ * errors. RA defers the commit to after the next render; handlers here run after the value signal
+ * was written, so the commit is immediate.
+ */
+export function commitValidation(state) {
+    clearServerErrors(state);
+    if (state.behavior !== "native")
+        return;
+    const error = untrack(() => clientError(state) || builtinError(state)) || untrack(state.next);
+    if (!isEqualValidation(error, untrack(state.current)))
+        state.current.set(error);
+}

package/state/grid.d.ts

@@ -0,0 +1,62 @@
+import { type Signal } from "@rivetjs/reactivity";
+import type { Collection, FocusStrategy, Key, Node } from "../collections/types.js";
+import type { IGridCollection } from "../collections/grid.js";
+import { SelectionManager, type SelectionManagerOptions } from "../selection/manager.js";
+import { type MultipleSelectionState, type MultipleSelectionStateProps } from "../selection/state.js";
+export type { GridNode, IGridCollection } from "../collections/grid.js";
+/** react-stately `GridState`: the derived view the grid hooks read. */
+export interface GridState<T, C extends IGridCollection<T>> {
+    collection: C;
+    /** A set of keys for rows that are disabled. */
+    disabledKeys: Set<Key>;
+    /** A selection manager to read and update row selection state. */
+    selectionManager: SelectionManager;
+    /**
+     * Whether keyboard navigation is disabled, such as when the arrow keys should be handled by a
+     * component within a cell.
+     */
+    isKeyboardNavigationDisabled: boolean;
+}
+export interface GridStateOptions extends MultipleSelectionStateProps {
+    disabledKeys?: Iterable<Key> | undefined;
+    focusMode?: "row" | "cell" | undefined;
+    /** @private - Do not use unless you know what you're doing. */
+    UNSAFE_selectionState?: MultipleSelectionState | undefined;
+}
+/** The serializable part of a grid state (signals + plain data). */
+export interface GridStateData {
+    /** Selection + focus state. */
+    readonly selectionState: MultipleSelectionState;
+    /** A set of keys for rows that are disabled. */
+    readonly disabledKeys: Set<Key>;
+    readonly focusMode: "row" | "cell" | undefined;
+    /** Table: arrow keys handled by a component inside a cell (resizer). Grid: always false. */
+    readonly keyboardNavigationDisabled?: Signal<boolean> | undefined;
+}
+/**
+ * Provides state management for a grid component (react-stately `useGridState`). Handles row
+ * selection and focusing a grid cell's focusable child if applicable.
+ */
+export declare function createGridState(props?: GridStateOptions): GridStateData;
+/**
+ * A `SelectionManager` whose `setFocusedKey` focuses a row's first / last cell when the grid's
+ * focus mode is "cell" (react-stately overrides `selectionState.setFocusedKey`).
+ */
+export declare class GridSelectionManager extends SelectionManager {
+    readonly focusMode: "row" | "cell" | undefined;
+    private readonly gridCollection;
+    private readonly managerOptions;
+    constructor(collection: Collection<Node<unknown>>, state: MultipleSelectionState, focusMode: "row" | "cell" | undefined, options?: SelectionManagerOptions);
+    setFocusedKey(key: Key | null, childFocusStrategy?: FocusStrategy): void;
+    withCollection(collection: Collection<Node<unknown>>): SelectionManager;
+}
+/** The key `setFocusedKey(key, child)` really focuses: in "cell" focus mode an item key → its first / last cell. */
+export declare function gridFocusKey(collection: Collection<Node<unknown>>, focusMode: "row" | "cell" | undefined, key: Key | null, child?: FocusStrategy | null): Key | null;
+/** The react-stately `GridState` view of `data` over `collection` (build per handler / binding). */
+export declare function gridState<T, C extends IGridCollection<T>>(data: GridStateData, collection: C, options?: SelectionManagerOptions): GridState<T, C>;
+/**
+ * Reset the focused key if that item was deleted from the collection (react-stately's effect):
+ * focus the nearest focusable row at or after the deleted position, else before it, keeping the
+ * cell index when a cell was focused.
+ */
+export declare function resetGridFocusedKey<T>(data: GridStateData, cachedCollection: IGridCollection<T> | null | undefined, collection: IGridCollection<T>): void;