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

package/state/checkbox-group.d.ts

@@ -0,0 +1,67 @@
+import { type Signal } from "@rivetjs/reactivity";
+import { type ControlledState } from "../interactions/controllable.js";
+import { type FormValidationOptions, type FormValidationState, type ValidationResult } from "./form-validation.js";
+export interface CheckboxGroupStateOptions extends Omit<FormValidationOptions<string[]>, "name"> {
+    /** The current value (controlled): a plain array, a two-way Signal or an accessor (read live, never written). */
+    value?: string[] | Signal<string[]> | (() => string[]);
+    defaultValue?: string[];
+    onChange?: (value: string[]) => void;
+    /** Rivet (live props): an accessor stays live (`state.disabled`, read `isCheckboxGroupDisabled`). */
+    isDisabled?: boolean | (() => boolean | undefined) | undefined;
+    /** Rivet (live props): an accessor stays live (`state.readOnly`, read `isCheckboxGroupReadOnly`). */
+    isReadOnly?: boolean | (() => boolean | undefined) | undefined;
+    /** Rivet (live props): an accessor stays live (`state.isRequired`, read `isRequiredNow`). */
+    isRequired?: boolean | (() => boolean | undefined) | undefined;
+    name?: string | undefined;
+}
+export interface CheckboxGroupState {
+    /** The shown selected values (signal; change with `setValue` / `addValue` / …). */
+    readonly value: Signal<string[]>;
+    /** RA `useControlledState` state behind `value`. */
+    readonly controlled: ControlledState<string[]>;
+    readonly defaultValue: readonly string[];
+    /** Disabled at creation; read `isCheckboxGroupDisabled(state)` (follows a live `disabled`). */
+    readonly isDisabled: boolean;
+    /** Read-only at creation; read `isCheckboxGroupReadOnly(state)` (follows a live `readOnly`). */
+    readonly isReadOnly: boolean;
+    /** Live `isDisabled` / `isReadOnly` / `isRequired` accessors (live props). */
+    readonly disabled?: (() => boolean | undefined) | undefined;
+    readonly readOnly?: (() => boolean | undefined) | undefined;
+    readonly requiredNow?: (() => boolean | undefined) | undefined;
+    /** `isRequired` prop at creation (the group is required while nothing is selected: `isRequiredNow`). */
+    readonly required: boolean;
+    readonly validation: FormValidationState;
+    /** Invalid checkbox results by value (RA `invalidValues` ref; merged into the group validation). */
+    readonly invalid: Signal<Record<string, ValidationResult>>;
+    /** RA `checkboxGroupData` (module WeakMap upstream): written by `checkboxGroupProps`, read by the items. */
+    data?: {
+        name?: string;
+        form?: string;
+        descriptionId?: {
+            readonly id: string;
+            readonly rendered: Signal<boolean | string>;
+        };
+        errorMessageId?: {
+            readonly id: string;
+            readonly rendered: Signal<boolean | string>;
+        };
+        validationBehavior: "aria" | "native";
+    };
+}
+export declare function createCheckboxGroupState(options?: CheckboxGroupStateOptions): CheckboxGroupState;
+/** RA `isRequired`: required while nothing is selected. Reads the value. */
+export declare const isRequiredNow: (state: CheckboxGroupState) => boolean;
+/** Whether the group is disabled now (its live `isDisabled` accessor, else the creation value). */
+export declare const isCheckboxGroupDisabled: (state: CheckboxGroupState) => boolean;
+/** Whether the group is read-only now (its live `isReadOnly` accessor, else the creation value). */
+export declare const isCheckboxGroupReadOnly: (state: CheckboxGroupState) => boolean;
+/** The group's `isRequired` prop now (its live accessor, else the creation value). */
+export declare const isCheckboxGroupRequired: (state: CheckboxGroupState) => boolean;
+export declare const isSelected: (state: CheckboxGroupState, v: string) => boolean;
+export declare const isGroupInvalid: (state: CheckboxGroupState) => boolean;
+export declare function setValue(state: CheckboxGroupState, next: string[]): void;
+export declare function addValue(state: CheckboxGroupState, v: string): void;
+export declare function removeValue(state: CheckboxGroupState, v: string): void;
+export declare function toggleValue(state: CheckboxGroupState, v: string): void;
+/** RA `setInvalid`: record a checkbox's validation and merge all into the group's. */
+export declare function setInvalid(state: CheckboxGroupState, v: string, result: ValidationResult): void;

package/state/checkbox-group.js

@@ -0,0 +1,76 @@
+// Ported from react-stately `useCheckboxGroupState` (packages/react-stately/src/checkbox/useCheckboxGroupState.ts),
+// Apache-2.0, © Adobe.
+// Rivet: plain signals + JSON; methods are free functions taking the state; the per-checkbox invalid
+// map is a signal of a record; `value` plain or two-way Signal through `controllable` (RA
+// useControlledState: several writes in one task chain on each other's result).
+import { signal, untrack } from "@rivetjs/reactivity";
+import { controllable, controlledValue, setControlledValue } from "../interactions/controllable.js";
+import { createFormValidationState, displayValidation, mergeValidation, updateValidation, } from "./form-validation.js";
+export function createCheckboxGroupState(options = {}) {
+    const controlled = controllable(options.value, options.defaultValue || [], options.onChange);
+    const value = controlled.value;
+    const disabled = typeof options.isDisabled === "function" ? options.isDisabled : undefined;
+    const readOnly = typeof options.isReadOnly === "function" ? options.isReadOnly : undefined;
+    const requiredNow = typeof options.isRequired === "function" ? options.isRequired : undefined;
+    return {
+        value,
+        controlled,
+        defaultValue: options.defaultValue ?? untrack(value),
+        isDisabled: disabled ? !!untrack(disabled) : !!options.isDisabled,
+        isReadOnly: readOnly ? !!untrack(readOnly) : !!options.isReadOnly,
+        ...(disabled ? { disabled } : {}),
+        ...(readOnly ? { readOnly } : {}),
+        ...(requiredNow ? { requiredNow } : {}),
+        required: requiredNow ? !!untrack(requiredNow) : !!options.isRequired,
+        validation: createFormValidationState({ ...options, value }),
+        invalid: signal({}),
+    };
+}
+/** RA `isRequired`: required while nothing is selected. Reads the value. */
+export const isRequiredNow = (state) => isCheckboxGroupRequired(state) && state.value().length === 0;
+/** Whether the group is disabled now (its live `isDisabled` accessor, else the creation value). */
+export const isCheckboxGroupDisabled = (state) => (state.disabled ? !!state.disabled() : state.isDisabled);
+/** Whether the group is read-only now (its live `isReadOnly` accessor, else the creation value). */
+export const isCheckboxGroupReadOnly = (state) => (state.readOnly ? !!state.readOnly() : state.isReadOnly);
+/** The group's `isRequired` prop now (its live accessor, else the creation value). */
+export const isCheckboxGroupRequired = (state) => (state.requiredNow ? !!state.requiredNow() : state.required);
+/** Whether writes are blocked now (read at event time: untracked). */
+const blocked = (state) => untrack(() => isCheckboxGroupReadOnly(state) || isCheckboxGroupDisabled(state));
+export const isSelected = (state, v) => state.value().includes(v);
+export const isGroupInvalid = (state) => displayValidation(state.validation).isInvalid;
+const write = (state, next) => setControlledValue(state.controlled, next);
+/** The latest value, including writes earlier in the same task. */
+const latest = (state) => untrack(() => controlledValue(state.controlled));
+export function setValue(state, next) {
+    if (blocked(state))
+        return;
+    write(state, next);
+}
+export function addValue(state, v) {
+    if (blocked(state))
+        return;
+    write(state, (current) => (current.includes(v) ? current : current.concat(v)));
+}
+export function removeValue(state, v) {
+    if (blocked(state))
+        return;
+    const current = latest(state);
+    if (current.includes(v))
+        write(state, current.filter((x) => x !== v));
+}
+export function toggleValue(state, v) {
+    if (blocked(state))
+        return;
+    const current = latest(state);
+    write(state, current.includes(v) ? current.filter((x) => x !== v) : current.concat(v));
+}
+/** RA `setInvalid`: record a checkbox's validation and merge all into the group's. */
+export function setInvalid(state, v, result) {
+    const next = { ...untrack(state.invalid) };
+    if (result.isInvalid)
+        next[v] = result;
+    else
+        delete next[v];
+    state.invalid.set(next);
+    updateValidation(state.validation, mergeValidation(...Object.values(next)));
+}

package/state/combobox.d.ts

@@ -0,0 +1,238 @@
+import { type Signal } from "@rivetjs/reactivity";
+import type { Collection, CollectionChildren, FocusStrategy, Key, Node, Selection } from "@rivetjs/cdk/collections/types";
+import { SelectionManager } from "@rivetjs/cdk/selection/manager";
+import type { MultipleSelectionState } from "@rivetjs/cdk/selection/state";
+import { type FormValidationState, type MaybeAccessor, type ValidationBehavior, type ValidationErrors, type ValidationFunction } from "./form-validation.js";
+import type { Point } from "./overlays.js";
+export type { Key, Selection, FocusStrategy, Node, Collection };
+export type MenuTriggerAction = "focus" | "input" | "manual";
+export type SelectionMode = "single" | "multiple";
+export type ValueType<M extends SelectionMode> = M extends "single" ? Key | null : readonly Key[];
+export type ChangeValueType<M extends SelectionMode> = M extends "single" ? Key | null : Key[];
+type ValidationType<M extends SelectionMode> = M extends "single" ? Key | null : Key[];
+type FilterFn = (textValue: string, inputValue: string) => boolean;
+export interface ComboBoxValidationValue<M extends SelectionMode = "single"> {
+    /** @deprecated The selected key in the ComboBox. */
+    selectedKey: Key | null;
+    /** The keys of the currently selected items. */
+    value: ValidationType<M>;
+    /** The value of the ComboBox input. */
+    inputValue: string;
+}
+/** A controlled value: plain, a two-way Signal, or an accessor (a live prop: read on use, never written). */
+export type Controllable<T> = T | Signal<T> | (() => T);
+/** react-stately `ComboBoxStateOptions` (`ComboBoxProps` + collection options). */
+export interface ComboBoxStateProps<T = any, M extends SelectionMode = "single"> {
+    /** The list of ComboBox items (uncontrolled): filtered with `defaultFilter`. */
+    defaultItems?: readonly T[] | (() => readonly T[]) | undefined;
+    /** The list of ComboBox items (controlled): not filtered (the application filters). */
+    items?: readonly T[] | (() => readonly T[]) | null | undefined;
+    /** Collection elements, or a renderer `(item) => Item(...)` for the items. Default: `{ id, name | label | textValue }` items. */
+    children?: CollectionChildren<T> | undefined;
+    /** A pre-built collection (RAC: the CollectionBuilder output of the ListBox parts), or an accessor of one. */
+    collection?: Collection<Node<T>> | (() => Collection<Node<T>>) | undefined;
+    /** Whether single or multiple selection is enabled. @default 'single' */
+    selectionMode?: M | undefined;
+    /** The current value (controlled). */
+    value?: Controllable<ValueType<M>> | undefined;
+    /** The default value (uncontrolled). */
+    defaultValue?: ValueType<M> | undefined;
+    /** Handler that is called when the value changes. */
+    onChange?: ((value: ChangeValueType<M>) => void) | undefined;
+    /** @deprecated The currently selected key in the collection (controlled). */
+    selectedKey?: Controllable<Key | null> | undefined;
+    /** @deprecated The initial selected key in the collection (uncontrolled). */
+    defaultSelectedKey?: Key | null | undefined;
+    /** @deprecated Handler that is called when the selection changes. */
+    onSelectionChange?: ((key: Key | null) => void) | undefined;
+    /** The value of the ComboBox input (controlled). */
+    inputValue?: Controllable<string> | undefined;
+    /** The default value of the ComboBox input (uncontrolled). */
+    defaultInputValue?: string | undefined;
+    /** Handler that is called when the ComboBox input value changes. */
+    onInputChange?: ((value: string) => void) | undefined;
+    /** Whether the ComboBox allows a non-item matching input value to be set. */
+    allowsCustomValue?: boolean | undefined;
+    /** The interaction required to display the ComboBox menu. @default 'input' */
+    menuTrigger?: MenuTriggerAction | undefined;
+    /** Method that is called when the open state of the menu changes, with the action that opened it. */
+    onOpenChange?: ((isOpen: boolean, menuTrigger?: MenuTriggerAction) => void) | undefined;
+    /** The filter function used to determine if a option should be included in the combo box list. */
+    defaultFilter?: FilterFn | undefined;
+    /** Rivet: locale of the default `contains` filter (sensitivity "base") used when `defaultFilter` is omitted. */
+    filterLocale?: string | undefined;
+    /** Whether the combo box allows the menu to be open when the collection is empty. */
+    allowsEmptyCollection?: boolean | undefined;
+    /** Whether the combo box menu should close on blur. @default true */
+    shouldCloseOnBlur?: boolean | undefined;
+    /** The item keys that are disabled. */
+    disabledKeys?: Iterable<Key> | undefined;
+    /** Rivet (live props): the ComboBox part passes an accessor for a live flag (read once here, except `isReadOnly`:
+     *  `core.readOnly`, read `isComboReadOnly`). */
+    isDisabled?: boolean | undefined;
+    isReadOnly?: boolean | undefined;
+    isRequired?: MaybeAccessor<boolean | undefined>;
+    isInvalid?: MaybeAccessor<boolean | undefined> | undefined;
+    validate?: ValidationFunction<ComboBoxValidationValue<M>> | undefined;
+    /** @default 'aria' (the ComboBox component defaults to 'native', RAC) */
+    validationBehavior?: ValidationBehavior | undefined;
+    /** Server errors (from `<Form validationErrors>`). */
+    validationErrors?: MaybeAccessor<ValidationErrors | undefined> | undefined;
+    name?: string | undefined;
+    form?: string | undefined;
+    /** Base id of the parts; generated when omitted. */
+    id?: string | undefined;
+}
+type AnyValue = Key | null | readonly Key[];
+/**
+ * The serializable core of a ComboBox state (signals + JSON + user callbacks). Every free function
+ * that does not need the selection manager takes it.
+ */
+export interface ComboBoxCore<T = any, M extends SelectionMode = SelectionMode> {
+    readonly id: string;
+    readonly selectionMode: M;
+    readonly menuTrigger: MenuTriggerAction;
+    readonly allowsEmptyCollection: boolean;
+    readonly allowsCustomValue: boolean;
+    readonly shouldCloseOnBlur: boolean;
+    /** The flags at creation; read `isComboReadOnly(core)` (follows a live `readOnly`). */
+    readonly isDisabled: boolean;
+    readonly isReadOnly: boolean;
+    readonly isRequired: boolean;
+    /** Live `isReadOnly` accessor (live props). */
+    readonly readOnly?: (() => boolean | undefined) | undefined;
+    readonly name?: string | undefined;
+    readonly form?: string | undefined;
+    readonly items: ComboBoxStateProps<T, M>["items"];
+    readonly defaultItems: ComboBoxStateProps<T, M>["defaultItems"];
+    readonly children: CollectionChildren<T> | undefined;
+    readonly collection: ComboBoxStateProps<T, M>["collection"];
+    readonly defaultFilter: FilterFn | undefined;
+    readonly filterLocale: string | undefined;
+    readonly disabledKeys: readonly Key[];
+    /** The value (single: key, multiple: keys). */
+    readonly value: Signal<AnyValue>;
+    /** `value` / `selectedKey` was given (upstream `value !== undefined`). */
+    readonly valueControlled: boolean;
+    /** A plain controlled value: never written (only reported). */
+    readonly valueFixed: boolean;
+    readonly defaultValue: ValueType<M>;
+    readonly defaultSelectedKey: Key | null;
+    /** The input text. */
+    readonly inputValue: Signal<string>;
+    /** `inputValue` was given (upstream `props.inputValue !== undefined`). */
+    readonly inputControlled: boolean;
+    readonly inputFixed: boolean;
+    readonly defaultInputValue: string;
+    readonly isOpen: Signal<boolean>;
+    readonly point: Signal<Point | null>;
+    readonly focusStrategy: Signal<FocusStrategy | null>;
+    readonly isFocused: Signal<boolean>;
+    readonly showAllItems: Signal<boolean>;
+    readonly closedDueToEmpty: Signal<boolean>;
+    readonly menuOpenTrigger: Signal<MenuTriggerAction | null>;
+    readonly lastValue: Signal<string>;
+    /** `lastValueRef`: the display value at the last update. */
+    readonly lastDisplayValue: Signal<AnyValue>;
+    readonly lastSelectedKeyText: Signal<string>;
+    readonly valueOnFocus: Signal<[string, AnyValue]>;
+    readonly selectedKeys: Signal<Selection>;
+    readonly listFocused: Signal<boolean>;
+    readonly focusedKey: Signal<Key | null>;
+    readonly childFocusStrategy: Signal<FocusStrategy | null>;
+    readonly selectionBehavior: Signal<"toggle" | "replace">;
+    readonly anchorKey: Signal<Key | null>;
+    readonly currentKey: Signal<Key | null>;
+    readonly validationValue: Signal<ComboBoxValidationValue<M> | null>;
+    readonly validation: FormValidationState;
+    readonly onChange?: ((value: never) => void) | undefined;
+    readonly onSelectionChange?: ((key: Key | null) => void) | undefined;
+    readonly onInputChange?: ((value: string) => void) | undefined;
+    readonly onOpenChange?: ((isOpen: boolean, menuTrigger?: MenuTriggerAction) => void) | undefined;
+}
+/** The ComboBox state: the core plus the list's selection state (`selectionManager` source). */
+export interface ComboBoxState<T = any, M extends SelectionMode = SelectionMode> extends ComboBoxCore<T, M> {
+    readonly selectionState: MultipleSelectionState;
+}
+/**
+ * The serializable core of a combo box state (react-stately `useComboBoxState` minus the selection
+ * view). Region state: a resumed page re-creating the combobox's region keeps it.
+ */
+export declare function createComboBoxCore<T = any, M extends SelectionMode = "single">(props: ComboBoxStateProps<T, M>): ComboBoxCore<T, M>;
+/** Whether the combobox is read-only now (its live `isReadOnly` accessor, else the creation value). */
+export declare const isComboReadOnly: (core: ComboBoxCore) => boolean;
+/**
+ * Rivet (live props): the input text, after running the update loop when a plain controlled `value` / `selectedKey` /
+ * `inputValue` (an accessor: the parent's prop) changed since the last update — RA re-renders and its per-render
+ * effect re-syncs the input with the selection. Called from the input's value binding, so a resumed page (where the
+ * component's update effect never runs) follows the prop in place. Reads the value / input tracked.
+ */
+export declare function comboInputText(core: ComboBoxCore): string;
+/**
+ * The list's selection state over a core (react-stately `useListState` selection options of
+ * useComboBoxState): controlled by the value, `disallowEmptySelection` in single mode, duplicate
+ * selection events allowed. `onSelectionChange` must call `comboSelectionChange(core, keys)`.
+ */
+export declare function comboBoxSelectionState(core: ComboBoxCore, view: {
+    onSelectionChange: (keys: Selection) => void;
+}): MultipleSelectionState;
+/**
+ * Provides state management for a combo box component (react-stately `useComboBoxState`). Handles
+ * building a collection of items from props and manages the option selection state of the combo
+ * box. In addition, it tracks the input value, focus state, and other properties of the combo box.
+ * (Resumed components: build it from `createComboBoxCore` + `comboBoxSelectionState` with an inline arrow.)
+ */
+export declare function createComboBoxState<T = any, M extends SelectionMode = "single">(props: ComboBoxStateProps<T, M>): ComboBoxState<T, M>;
+/** The full (unfiltered) collection (upstream `collection` of useListState). Reads accessor inputs. */
+export declare function comboCollection<T>(core: ComboBoxCore<T, SelectionMode>): Collection<Node<T>>;
+/** The filter in use: `defaultFilter`, else a locale `contains` (sensitivity "base"), else none. */
+export declare function comboFilter(core: ComboBoxCore): FilterFn | undefined;
+/** The collection filtered by the input (none when items are controlled or no filter is set). Reads signals. */
+export declare function comboFilteredCollection<T>(core: ComboBoxCore<T, SelectionMode>): Collection<Node<T>>;
+/** The displayed collection (upstream `state.collection`): open → all or filtered items; closed → frozen. Reads signals. */
+export declare function comboDisplayedCollection<T>(core: ComboBoxCore<T, SelectionMode>): Collection<Node<T>>;
+/** The selection manager (upstream `state.selectionManager`) over the displayed collection. */
+export declare function comboSelectionManager(state: ComboBoxState): SelectionManager;
+/** The current value; a single combobox given an array shows its first key (upstream `displayValue`). */
+export declare function comboValue<M extends SelectionMode>(core: ComboBoxCore<any, M>): ValueType<M>;
+/** Selected keys (the list selection, value order). */
+export declare const comboSelectedKeys: (core: ComboBoxCore) => Key[];
+/** @deprecated upstream: the key of the first selected item (single mode only, else null). */
+export declare const comboSelectedKey: (core: ComboBoxCore) => Key | null;
+/** The selected item nodes (keys missing from the collection are skipped). */
+export declare function comboSelectedItems<T>(core: ComboBoxCore<T, SelectionMode>): Node<T>[];
+/** @deprecated upstream `selectedItem`: the first selected item node. */
+export declare const comboSelectedItem: <T>(core: ComboBoxCore<T, SelectionMode>) => Node<T> | null;
+/** Sets the value of the combo box input (upstream `setInputValue`). */
+export declare function setComboInputValue(core: ComboBoxCore, value: string): void;
+/** Sets the combobox value (upstream `setValue` / deprecated `setSelectedKey`). */
+export declare function setComboValue(core: ComboBoxCore, value: Key | readonly Key[] | null): void;
+/** The list selection changed (upstream useListState `onSelectionChange` of useComboBoxState). */
+export declare function comboSelectionChange(core: ComboBoxCore, keys: Selection): void;
+/** Opens the menu (upstream `open(focusStrategy, trigger)`). */
+export declare function openCombo(core: ComboBoxCore, focusStrategy?: FocusStrategy | null, trigger?: MenuTriggerAction): void;
+/** Toggles the menu (upstream `toggle(focusStrategy, trigger)`). */
+export declare function toggleCombo(core: ComboBoxCore, focusStrategy?: FocusStrategy | null, trigger?: MenuTriggerAction): void;
+/** Resets the input value to the previously selected item's text if any and closes the menu (upstream `revert`). */
+export declare function revertCombo(core: ComboBoxCore): void;
+/** Commits the value and closes the menu (upstream `state.close`, = `commitValue`). */
+export declare function closeCombo(core: ComboBoxCore): void;
+/**
+ * The menu was closed from outside the combobox's own actions (the Popover's outside press / its
+ * `OverlayTriggerStateContext` close): freeze the collection and commit (upstream: Popover calls
+ * `state.close()` = `commitValue`). Call after `isOpen` was set to false.
+ */
+export declare function comboClosedExternally(core: ComboBoxCore): void;
+/** Selects the currently focused item and updates the input value (upstream `commit`). */
+export declare function commitCombo(state: ComboBoxState): void;
+/** Sets whether the combobox is focused (upstream `setFocused`). */
+export declare function setComboFocused(core: ComboBoxCore, isFocused: boolean): void;
+/** Sets the list's focused key (upstream `selectionManager.setFocusedKey`). */
+export declare function setComboFocusedKey(core: ComboBoxCore, key: Key | null, childFocusStrategy?: FocusStrategy): void;
+/**
+ * The per-render effect of useComboBoxState (open / close on input, close when filtered empty,
+ * re-open after async items, close on single selection, clear the focused key on input, clear the
+ * value when the input is cleared, re-sync the input text with the value). Runs until stable.
+ * Actions call it; call it yourself after changing inputs outside the state (items, a value Signal).
+ */
+export declare function comboUpdate(core: ComboBoxCore): void;