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

package/state/overlays.d.ts

@@ -0,0 +1,35 @@
+import { type Signal } from "@rivetjs/reactivity";
+import { type ControlledState } from "../interactions/controllable.js";
+export interface OverlayTriggerProps {
+    /** Whether the overlay is open (controlled): a plain value, a two-way Signal, or a read-only accessor (never written: dismissing only calls `onOpenChange`). */
+    isOpen?: boolean | Signal<boolean> | (() => boolean);
+    /** Whether the overlay is open by default (uncontrolled). */
+    defaultOpen?: boolean;
+    /** Handler that is called when the overlay's open state changes (resumed pages: an inline arrow or a local function). */
+    onOpenChange?: (isOpen: boolean) => void;
+}
+export interface Point {
+    x: number;
+    y: number;
+}
+export interface OverlayTriggerState {
+    /** Whether the overlay is currently open (signal of the shown value). */
+    readonly isOpen: Signal<boolean>;
+    /** The cursor position when the overlay was triggered, relative to the window viewport. */
+    readonly point: Signal<Point | null>;
+    /** @internal The controlled-state record behind `isOpen` (`controllable`). */
+    readonly open: ControlledState<boolean>;
+}
+/** Manages state for an overlay trigger (react-stately `useOverlayTriggerState`). Region state: a
+ * resumed page re-creating the overlay's region (its first open) keeps it. */
+export declare function createOverlayTriggerState(props?: OverlayTriggerProps): OverlayTriggerState;
+/** Sets whether the overlay is open (calls `onOpenChange` when the value changes). */
+export declare function setOpen(state: OverlayTriggerState, isOpen: boolean): void;
+/** Opens the overlay. */
+export declare const openOverlay: (state: OverlayTriggerState) => void;
+/** Closes the overlay. */
+export declare const closeOverlay: (state: OverlayTriggerState) => void;
+/** Toggles the overlay's visibility. */
+export declare const toggleOverlay: (state: OverlayTriggerState) => void;
+/** Sets the cursor position relative to the window viewport. */
+export declare const setPoint: (state: OverlayTriggerState, point: Point) => void;

package/state/overlays.js

@@ -0,0 +1,29 @@
+// Ported from React Stately (@react-stately/overlays useOverlayTriggerState), Apache-2.0, © Adobe.
+// Modifications: React state → `controllable` (react-stately useControlledState: `isOpen` plain value OR a
+// two-way Signal, or a read-only accessor `() => boolean`, `defaultOpen`, `onOpenChange`); the methods are free functions (`setOpen(state, v)`, …)
+// so state stays JSON (signals + plain data) and handlers resume. `state.isOpen` is the shown value's
+// signal (read it in bindings: `state.isOpen()`); never `.set` it — use `setOpen` / `openOverlay` / …
+import { signal, untrack, _regionState } from "@rivetjs/reactivity";
+import { controllable, controlledValue, setControlledValue } from "../interactions/controllable.js";
+/** Manages state for an overlay trigger (react-stately `useOverlayTriggerState`). Region state: a
+ * resumed page re-creating the overlay's region (its first open) keeps it. */
+export function createOverlayTriggerState(props = {}) {
+    return _regionState(() => {
+        const open = controllable(props.isOpen, props.defaultOpen || false, props.onOpenChange);
+        return { isOpen: open.value, point: signal(null), open };
+    });
+}
+/** Sets whether the overlay is open (calls `onOpenChange` when the value changes). */
+export function setOpen(state, isOpen) {
+    untrack(() => setControlledValue(state.open, isOpen));
+}
+/** Opens the overlay. */
+export const openOverlay = (state) => setOpen(state, true);
+/** Closes the overlay. */
+export const closeOverlay = (state) => setOpen(state, false);
+/** Toggles the overlay's visibility. */
+export const toggleOverlay = (state) => setOpen(state, !untrack(() => controlledValue(state.open)));
+/** Sets the cursor position relative to the window viewport. */
+export const setPoint = (state, point) => {
+    state.point.set(point);
+};

package/state/radio-group.d.ts

@@ -0,0 +1,58 @@
+import { type Signal } from "@rivetjs/reactivity";
+import { type FormValidationOptions, type FormValidationState } from "./form-validation.js";
+export interface RadioGroupStateOptions extends Omit<FormValidationOptions<string | null>, "name"> {
+    /** Selected value (controlled): a two-way Signal, a plain value or an accessor (read live, never written). */
+    value?: Signal<string | null> | (() => string | null) | string | null;
+    defaultValue?: string | null;
+    onChange?: (value: string) => void;
+    name?: string;
+    /** Rivet (live props): an accessor stays live (`state.disabled`, read `isRadioGroupDisabled`). */
+    isDisabled?: boolean | (() => boolean | undefined);
+    /** Rivet (live props): an accessor stays live (`state.readOnly`, read `isRadioGroupReadOnly`). */
+    isReadOnly?: boolean | (() => boolean | undefined);
+    /** Rivet (live props): an accessor stays live (`state.required`, read `isRadioGroupRequired`). */
+    isRequired?: boolean | (() => boolean | undefined);
+}
+export interface RadioGroupState {
+    /** Group name shared by the radios (generated when omitted). */
+    readonly name: string;
+    /** The selected value (read it; write through `setSelectedValue`: a fixed one is never `.set`). */
+    readonly selectedValue: Signal<string | null>;
+    /** A plain / accessor controlled value: never written (changes only call `onChange`). */
+    readonly fixed: boolean;
+    readonly defaultSelectedValue: string | null;
+    /** Last focused radio (roving tab stop while nothing is selected). */
+    readonly lastFocusedValue: Signal<string | null>;
+    /** Disabled at creation; read `isRadioGroupDisabled(state)` (follows a live `disabled`). */
+    readonly isDisabled: boolean;
+    /** Read-only at creation; read `isRadioGroupReadOnly(state)` (follows a live `readOnly`). */
+    readonly isReadOnly: boolean;
+    /** Live `isDisabled` / `isReadOnly` accessors (live props). */
+    readonly disabled?: (() => boolean | undefined) | undefined;
+    readonly readOnly?: (() => boolean | undefined) | undefined;
+    /** Required at creation; read `isRadioGroupRequired(state)` (follows a live `required`). */
+    readonly isRequired: boolean;
+    readonly required?: (() => boolean | undefined) | undefined;
+    readonly onChange: ((value: string) => void) | undefined;
+    readonly validation: FormValidationState;
+    /** RA `radioGroupData` (module WeakMap in RA): set by the compound `RadioGroup` for its radios (`radio-group/parts.tsx`). */
+    data?: {
+        form?: string;
+        descriptionId: unknown;
+        errorMessageId: unknown;
+        validationBehavior: "aria" | "native";
+    };
+}
+export declare function createRadioGroupState(options?: RadioGroupStateOptions): RadioGroupState;
+/** Whether the group is disabled now (its live `isDisabled` accessor, else the creation value). */
+export declare const isRadioGroupDisabled: (state: RadioGroupState) => boolean;
+/** Whether the group is required now (its live `isRequired` accessor, else the creation value). */
+export declare const isRadioGroupRequired: (state: RadioGroupState) => boolean;
+/** Whether the group is read-only now (its live `isReadOnly` accessor, else the creation value). */
+export declare const isRadioGroupReadOnly: (state: RadioGroupState) => boolean;
+/** RA `setSelectedValue`: ignored while read-only / disabled; commits validation. */
+export declare function setSelectedValue(state: RadioGroupState, value: string | null): void;
+export declare function setLastFocusedValue(state: RadioGroupState, value: string | null): void;
+export declare const isRadioInvalid: (state: RadioGroupState) => boolean;
+/** RA useRadio tab index: the selected radio, else the last focused (or every radio when none). */
+export declare function radioTabIndex(state: RadioGroupState, value: string, isDisabled: boolean): number | undefined;

package/state/radio-group.js

@@ -0,0 +1,68 @@
+// Ported from react-stately `useRadioGroupState` (packages/react-stately/src/radio/useRadioGroupState.ts), Apache-2.0, © Adobe.
+// Rivet: `value` is a two-way Signal, a plain value or an accessor (live prop `value={v()}`); plain / accessor values
+// are controlled as upstream (`state.fixed`: never written, a change only calls `onChange`).
+import { _regionState, signal, untrack } from "@rivetjs/reactivity";
+import { createId } from "@rivetjs/cdk/id";
+import { commitValidation, createFormValidationState, displayValidation } from "./form-validation.js";
+export function createRadioGroupState(options = {}) {
+    const given = options.value;
+    const isSignal = typeof given === "function" && typeof given.set === "function";
+    const fixed = given !== undefined && !isSignal;
+    // useControlledState: a Signal is two-way, an accessor is read as is, a plain value is a never-written signal.
+    const selectedValue = (isSignal || typeof given === "function"
+        ? given
+        : fixed
+            ? signal(given)
+            : _regionState(() => signal(options.defaultValue ?? null)));
+    const name = options.name ?? createId();
+    const disabled = typeof options.isDisabled === "function" ? options.isDisabled : undefined;
+    const readOnly = typeof options.isReadOnly === "function" ? options.isReadOnly : undefined;
+    return {
+        name,
+        selectedValue,
+        fixed,
+        defaultSelectedValue: options.value !== undefined ? untrack(selectedValue) : (options.defaultValue ?? null),
+        lastFocusedValue: signal(null),
+        isDisabled: disabled ? !!untrack(disabled) : !!options.isDisabled,
+        isReadOnly: readOnly ? !!untrack(readOnly) : !!options.isReadOnly,
+        ...(disabled ? { disabled } : {}),
+        ...(readOnly ? { readOnly } : {}),
+        isRequired: typeof options.isRequired === "function" ? !!untrack(options.isRequired) : (options.isRequired ?? false),
+        ...(typeof options.isRequired === "function" ? { required: options.isRequired } : {}),
+        onChange: options.onChange,
+        validation: createFormValidationState({ ...options, name: options.name, value: selectedValue }),
+    };
+}
+/** Whether the group is disabled now (its live `isDisabled` accessor, else the creation value). */
+export const isRadioGroupDisabled = (state) => (state.disabled ? !!state.disabled() : state.isDisabled);
+/** Whether the group is required now (its live `isRequired` accessor, else the creation value). */
+export const isRadioGroupRequired = (state) => (state.required ? !!state.required() : state.isRequired);
+/** Whether the group is read-only now (its live `isReadOnly` accessor, else the creation value). */
+export const isRadioGroupReadOnly = (state) => (state.readOnly ? !!state.readOnly() : state.isReadOnly);
+/** RA `setSelectedValue`: ignored while read-only / disabled; commits validation. */
+export function setSelectedValue(state, value) {
+    if (isRadioGroupReadOnly(state) || isRadioGroupDisabled(state))
+        return;
+    if (untrack(state.selectedValue) !== value) {
+        if (!state.fixed)
+            state.selectedValue.set(value);
+        if (value !== null)
+            state.onChange?.(value);
+    }
+    commitValidation(state.validation);
+}
+export function setLastFocusedValue(state, value) {
+    if (untrack(state.lastFocusedValue) !== value)
+        state.lastFocusedValue.set(value);
+}
+export const isRadioInvalid = (state) => displayValidation(state.validation).isInvalid;
+/** RA useRadio tab index: the selected radio, else the last focused (or every radio when none). */
+export function radioTabIndex(state, value, isDisabled) {
+    if (isDisabled)
+        return undefined;
+    const selected = state.selectedValue();
+    if (selected != null)
+        return selected === value ? 0 : -1;
+    const last = state.lastFocusedValue();
+    return last === value || last == null ? 0 : -1;
+}

package/state/search-field.d.ts

@@ -0,0 +1,20 @@
+import type { Signal } from "@rivetjs/reactivity";
+import { type ControlledState } from "../interactions/controllable.js";
+export interface SearchFieldStateProps {
+    /** The current value (controlled): a plain value, a two-way Signal, or an accessor read live. */
+    value?: string | Signal<string> | (() => string);
+    /** The default value (uncontrolled). */
+    defaultValue?: string;
+    /** Handler that is called when the value changes. */
+    onChange?: (value: string) => void;
+}
+export interface SearchFieldState {
+    /** The current value of the search field. */
+    readonly value: ControlledState<string>;
+}
+/** Provides state management for a search field. */
+export declare function createSearchFieldState(props: SearchFieldStateProps): SearchFieldState;
+/** The current value of the search field. */
+export declare const searchFieldValue: (state: SearchFieldState) => string;
+/** Sets the value of the search field. */
+export declare function setSearchFieldValue(state: SearchFieldState, value: string): void;

package/state/search-field.js

@@ -0,0 +1,21 @@
+import { controllable, setControlledValue } from "../interactions/controllable.js";
+function toString(val) {
+    if (val == null) {
+        return;
+    }
+    return String(val);
+}
+/** Provides state management for a search field. */
+export function createSearchFieldState(props) {
+    const value = props.value;
+    return {
+        // Signals / accessors pass through (`controllable`); plain values stringify like upstream.
+        value: controllable(typeof value === "function" ? value : toString(value), toString(props.defaultValue) || "", props.onChange),
+    };
+}
+/** The current value of the search field. */
+export const searchFieldValue = (state) => state.value.value();
+/** Sets the value of the search field. */
+export function setSearchFieldValue(state, value) {
+    setControlledValue(state.value, value);
+}

package/state/select.d.ts

@@ -0,0 +1,150 @@
+import { type Signal } from "@rivetjs/reactivity";
+import { type ControlledState } from "../interactions/controllable.js";
+import { ListCollection, type FocusStrategy } from "../_adapters/collections.js";
+import { type OverlayTriggerProps, type OverlayTriggerState } from "./overlays.js";
+import { type FormValidationState, type MaybeAccessor, type ValidationBehavior, type ValidationErrors, type ValidationFunction } from "./form-validation.js";
+import { type CollectionEntry, type Item, type Key } from "./list.js";
+import type { Collection as BuiltCollection, Node as BuiltNode, SelectionMode as SharedSelectionMode } from "../collections/types.js";
+export type { Key, Item, CollectionEntry, FocusStrategy };
+/** Select has no `"none"` mode (react-stately `SelectProps`); derived from the shared `SelectionMode`. */
+export type SelectionMode = Exclude<SharedSelectionMode, "none">;
+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 : Key[];
+export interface SelectStateProps<M extends SelectionMode = "single"> extends OverlayTriggerProps {
+    /** Items and sections (RAC `<ListBox items>`); a function for items that change. */
+    items?: readonly CollectionEntry[] | (() => readonly CollectionEntry[]) | undefined;
+    /**
+     * RAC parts mode: the collection built from the Select's children (`collectionOf`, the ListBox items), as an
+     * accessor (an inline arrow: region state keeps it). Items are read from it when `items` is not given.
+     */
+    collection?: (() => BuiltCollection<BuiltNode<unknown>>) | undefined;
+    /** Whether single or multiple selection is enabled. @default 'single'. Read once at mount (picks the value shape). */
+    selectionMode?: M;
+    /** The current value (controlled): a plain value (shown until the caller re-renders; `onChange` reports changes) or a two-way Signal. */
+    value?: ValueType<M> | Signal<ValueType<M>>;
+    /** The default value (uncontrolled). */
+    defaultValue?: ValueType<M>;
+    /** Handler that is called when the value changes (resumed pages: an inline arrow or a local function). */
+    onChange?: (value: ChangeValueType<M>) => void;
+    /** @deprecated use `value`. The currently selected key in the collection (controlled): plain or a two-way Signal. */
+    selectedKey?: Key | null | Signal<Key | null>;
+    /** @deprecated use `defaultValue`. The initial selected key in the collection (uncontrolled). */
+    defaultSelectedKey?: Key | null;
+    /** @deprecated use `onChange`. Handler that is called when the selection changes. */
+    onSelectionChange?: (key: Key | null) => void;
+    /**
+     * The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with. Read once
+     * at mount (the listbox's selection manager copies them); a live item uses `ListBoxItem isDisabled={…}`.
+     */
+    disabledKeys?: Iterable<Key>;
+    /** Whether the Select should close when an item is selected. Defaults to true if selectionMode is single, false otherwise. Read once at mount. */
+    shouldCloseOnSelect?: boolean;
+    /** Whether the select should be allowed to be open when the collection is empty. Read once at mount. */
+    allowsEmptyCollection?: boolean;
+    /** Whether the select is disabled. Rivet (live props): the parts pass an accessor that stays live (internal). */
+    isDisabled?: boolean;
+    /** Whether a value is required. Rivet (live props): the parts pass an accessor that stays live (internal). */
+    isRequired?: boolean;
+    /** Controlled invalid state; an accessor stays live. */
+    isInvalid?: MaybeAccessor<boolean | undefined>;
+    validate?: ValidationFunction<ValidationType<M>>;
+    /** @default 'aria' (the Select component defaults to 'native', RAC) */
+    validationBehavior?: ValidationBehavior;
+    /** The name of the hidden select submitted with a form. Read once at mount (form identity). */
+    name?: string;
+    /** The `<form>` id of the hidden select. Read once at mount. */
+    form?: string;
+    /** Server errors (from `<Form validationErrors>`). */
+    validationErrors?: MaybeAccessor<ValidationErrors | undefined>;
+    /** Base id of the parts (`<id>-trigger`, `<id>-listbox`, …); generated when omitted. */
+    id?: string;
+}
+export interface SelectState<M extends SelectionMode = "single"> extends OverlayTriggerState {
+    readonly id: string;
+    readonly selectionMode: M;
+    /** The value: a key (single) or keys (multiple). A single select given an array shows its first key. Read-only: write with `setSelectValue`. */
+    readonly value: Signal<Key | null | readonly Key[]>;
+    /** useControlledState of the value (plain controlled / Signal / uncontrolled + `onChange`). */
+    readonly control: ControlledState<Key | null | readonly Key[], any>;
+    /** The value restored on form reset (`defaultValue` ?? the initial value). */
+    readonly defaultValue: ValueType<M>;
+    readonly items: SelectStateProps<M>["items"];
+    /** RAC parts mode: the built collection accessor (see `SelectStateProps.collection`). */
+    readonly collection?: SelectStateProps<M>["collection"];
+    readonly disabledKeys: readonly Key[];
+    readonly shouldCloseOnSelect: boolean;
+    readonly allowsEmptyCollection: boolean;
+    readonly isDisabled: boolean;
+    /** Rivet: the caller's `isDisabled` accessor (live props), when it passed one; read `isSelectDisabled(state)`. */
+    readonly disabled?: () => boolean | undefined;
+    readonly isRequired: boolean;
+    /** Rivet: the caller's `isRequired` accessor (live props), when it passed one; read `isSelectRequired(state)`. */
+    readonly required?: () => boolean | undefined;
+    readonly name?: string | undefined;
+    readonly form?: string | undefined;
+    /** Controls which item will be auto focused when the menu opens. */
+    readonly focusStrategy: Signal<FocusStrategy | null>;
+    /** Whether the select is currently focused. */
+    readonly isFocused: Signal<boolean>;
+    /** Whether focus is keyboard focus (RAC `useFocusRing({within: true})`). */
+    readonly isFocusVisible: Signal<boolean>;
+    /** Focused key of the closed trigger's typeahead (react-stately: the list's `focusedKey`). */
+    readonly focusedKey: Signal<Key | null>;
+    readonly validation: FormValidationState;
+    readonly onSelectionChange?: ((key: Key | null) => void) | undefined;
+}
+/**
+ * Provides state management for a select component (react-stately `useSelectState`). Handles the
+ * open state for the popup menu and the single / multiple value. Region state: a resumed page
+ * re-creating the select's region keeps it.
+ */
+export declare function createSelectState<M extends SelectionMode = "single">(props: SelectStateProps<M>): SelectState<M>;
+/** Whether the select is disabled now (its live `isDisabled` accessor, else the creation value). */
+export declare const isSelectDisabled: (state: {
+    isDisabled: boolean;
+    disabled?: () => boolean | undefined;
+}) => boolean;
+/** Whether the select is required now (its live `isRequired` accessor, else the creation value). */
+export declare const isSelectRequired: (state: {
+    isRequired: boolean;
+    required?: () => boolean | undefined;
+}) => boolean;
+/**
+ * A built-collection item read as a data entry (RAC parts mode): `label` / `textValue` = the node's `textValue`,
+ * `disabled` = `isDisabled`, plus the node's object `value` and `content` (its children: SelectValue renders them).
+ */
+export interface BuiltItem extends Item {
+    readonly value: unknown;
+    readonly content: unknown;
+}
+/** The item nodes of a built collection as entries (sections → `{ key, title, children }`), cached per collection. */
+export declare function builtEntries(collection: BuiltCollection<BuiltNode<unknown>>): readonly CollectionEntry[];
+/** The data items: `items`, else the built collection's items (RAC parts mode), else none. */
+export declare const selectEntries: (state: SelectState<SelectionMode>) => readonly CollectionEntry[];
+/** Every item (sections flattened). */
+export declare const selectItems: (state: SelectState<SelectionMode>) => Item[];
+/** react-stately `ListCollection` of the items (typeahead, arrow keys, size). */
+export declare const selectCollection: (state: SelectState<SelectionMode>) => ListCollection;
+/** The displayed value: the first key when a single select holds an array (reads `value`). */
+export declare function selectValue<M extends SelectionMode>(state: SelectState<M>): ValueType<M>;
+/** Selected keys, in value order (react-stately `convertValue`). */
+export declare function selectedKeys(state: SelectState<SelectionMode>): Key[];
+/** The key of the first selected item (`selectedKey`). */
+export declare const selectedKey: (state: SelectState<SelectionMode>) => Key | null;
+/** The selected items, in value order (`selectedItems`; keys missing from the collection are skipped). */
+export declare function selectedItems(state: SelectState<SelectionMode>): Item[];
+/**
+ * Rivet helper (no upstream equivalent; `selectedItems` over any data): the items of `keys`, in key
+ * order, from entries (sections flattened). For selected items shown outside the Select, from the
+ * same items + a shared `value` signal.
+ */
+export declare function selectedItemsOf(entries: readonly CollectionEntry[], keys: Iterable<Key> | Key | null | undefined): Item[];
+/** Sets the select value (react-stately `setValue` / `setSelectedKey`). */
+export declare function setSelectValue(state: SelectState<SelectionMode>, value: Key | readonly Key[] | null): void;
+/** Whether the select may open: a non-empty collection, or `allowsEmptyCollection`. */
+export declare const canOpen: (state: SelectState<SelectionMode>) => boolean;
+/** Opens the menu (not when the collection is empty, unless `allowsEmptyCollection`). */
+export declare function openSelect(state: SelectState<SelectionMode>, focusStrategy?: FocusStrategy | null): void;
+/** Toggles the menu (not when the collection is empty, unless `allowsEmptyCollection`). */
+export declare function toggleSelect(state: SelectState<SelectionMode>, focusStrategy?: FocusStrategy | null): void;

package/state/select.js

@@ -0,0 +1,187 @@
+// Ported from React Stately (@react-stately/select useSelectState), Apache-2.0, © Adobe.
+//
+// Select state: the overlay (open) state, the value (single key or keys), focus flags and form
+// validation. Signals + JSON only (resumable); the methods are free functions taking the state. The
+// collection is the data items (`items`): the closed trigger needs it for typeahead and the arrow
+// keys, the hidden `<select>` for its options, SelectValue for the selected items' text. RAC parts mode (no
+// `items`): `collection` = the Select's built collection (react-stately `useSelectState({ collection })`); its
+// item nodes are read as data entries (`selectEntries`), `value` = the node's object value, `content` = its children.
+import { signal, untrack, _regionState } from "@rivetjs/reactivity";
+import { controllable, setControlledValue } from "../interactions/controllable.js";
+import { createId } from "@rivetjs/cdk/id";
+import { buildNodes, ListCollection } from "../_adapters/collections.js";
+import { createOverlayTriggerState, openOverlay, toggleOverlay } from "./overlays.js";
+import { createFormValidationState, } from "./form-validation.js";
+import { flatItems } from "./list.js";
+/**
+ * Provides state management for a select component (react-stately `useSelectState`). Handles the
+ * open state for the popup menu and the single / multiple value. Region state: a resumed page
+ * re-creating the select's region keeps it.
+ */
+export function createSelectState(props) {
+    return _regionState(() => {
+        const selectionMode = (props.selectionMode ?? "single");
+        const single = selectionMode === "single";
+        // Rivet (live props): the parts pass a live `isDisabled` accessor (the public type stays boolean).
+        const givenDisabled = props.isDisabled;
+        const givenRequired = props.isRequired;
+        const read = (v) => (typeof v === "function" ? v() : v);
+        const defaultValue = (props.defaultValue !== undefined ? props.defaultValue : single ? (props.defaultSelectedKey ?? null) : []);
+        // useSelectState: `value` wins over the deprecated `selectedKey` (single only); undefined = uncontrolled.
+        const controlled = (props.value !== undefined ? props.value : single ? props.selectedKey : undefined);
+        const control = controllable(controlled, defaultValue, props.onChange);
+        const value = control.value;
+        const initial = untrack(value);
+        return {
+            ...createOverlayTriggerState(props),
+            id: props.id ?? createId(),
+            selectionMode,
+            value,
+            control,
+            defaultValue: (defaultValue ?? initial),
+            items: props.items,
+            ...(props.collection ? { collection: props.collection } : {}),
+            disabledKeys: [...(props.disabledKeys ?? [])],
+            shouldCloseOnSelect: props.shouldCloseOnSelect ?? single,
+            allowsEmptyCollection: !!props.allowsEmptyCollection,
+            isDisabled: !!untrack(() => read(givenDisabled)),
+            ...(typeof givenDisabled === "function" ? { disabled: givenDisabled } : {}),
+            isRequired: !!untrack(() => read(givenRequired)),
+            ...(typeof givenRequired === "function" ? { required: givenRequired } : {}),
+            ...(props.name !== undefined ? { name: props.name } : {}),
+            ...(props.form !== undefined ? { form: props.form } : {}),
+            focusStrategy: signal(null),
+            isFocused: signal(false),
+            isFocusVisible: signal(false),
+            focusedKey: signal(null),
+            validation: createFormValidationState({
+                isInvalid: props.isInvalid,
+                validate: props.validate,
+                validationBehavior: props.validationBehavior ?? "aria",
+                name: props.name,
+                validationErrors: props.validationErrors,
+                value,
+            }),
+            ...(props.onSelectionChange ? { onSelectionChange: props.onSelectionChange } : {}),
+        };
+    });
+}
+/** Whether the select is disabled now (its live `isDisabled` accessor, else the creation value). */
+export const isSelectDisabled = (state) => state.disabled ? !!state.disabled() : state.isDisabled;
+/** Whether the select is required now (its live `isRequired` accessor, else the creation value). */
+export const isSelectRequired = (state) => state.required ? !!state.required() : state.isRequired;
+/** The collection entries (reads the items accessor). */
+const EMPTY_ENTRIES = [];
+const derived = new WeakMap();
+/** The item nodes of a built collection as entries (sections → `{ key, title, children }`), cached per collection. */
+export function builtEntries(collection) {
+    const cached = derived.get(collection);
+    if (cached)
+        return cached;
+    const item = (node) => {
+        const props = (node.props ?? {});
+        return {
+            key: node.key,
+            label: node.textValue,
+            textValue: node.textValue,
+            ...(props.isDisabled ? { disabled: true } : {}),
+            ...(props.href ? { href: props.href, target: props.target, rel: props.rel } : {}),
+            ...(node["aria-label"] ? { "aria-label": node["aria-label"] } : {}),
+            value: node.value,
+            content: props.children,
+        };
+    };
+    const out = [];
+    for (const node of collection) {
+        if (node.type === "item")
+            out.push(item(node));
+        else if (node.type === "section") {
+            const children = [];
+            let title;
+            for (const child of collection.getChildren?.(node.key) ?? []) {
+                if (child.type === "item")
+                    children.push(item(child));
+                else if (child.type === "header" && title === undefined)
+                    title = child.textValue;
+            }
+            out.push({ key: node.key, ...(title ? { title } : {}), ...(node["aria-label"] ? { "aria-label": node["aria-label"] } : {}), children });
+        }
+    }
+    derived.set(collection, out);
+    return out;
+}
+/** The data items: `items`, else the built collection's items (RAC parts mode), else none. */
+export const selectEntries = (state) => {
+    if (state.items === undefined && state.collection)
+        return builtEntries(state.collection());
+    return (typeof state.items === "function" ? state.items() : state.items) ?? EMPTY_ENTRIES;
+};
+/** Every item (sections flattened). */
+export const selectItems = (state) => flatItems(selectEntries(state));
+/** react-stately `ListCollection` of the items (typeahead, arrow keys, size). */
+export const selectCollection = (state) => new ListCollection(buildNodes(selectEntries(state)));
+/** The displayed value: the first key when a single select holds an array (reads `value`). */
+export function selectValue(state) {
+    const value = state.value();
+    return (state.selectionMode === "single" && Array.isArray(value) ? (value[0] ?? null) : value);
+}
+/** Selected keys, in value order (react-stately `convertValue`). */
+export function selectedKeys(state) {
+    const value = selectValue(state);
+    if (value == null)
+        return [];
+    return Array.isArray(value) ? [...value] : [value];
+}
+/** The key of the first selected item (`selectedKey`). */
+export const selectedKey = (state) => selectedKeys(state)[0] ?? null;
+/** The selected items, in value order (`selectedItems`; keys missing from the collection are skipped). */
+export function selectedItems(state) {
+    return selectedItemsOf(selectEntries(state), selectedKeys(state));
+}
+/**
+ * Rivet helper (no upstream equivalent; `selectedItems` over any data): the items of `keys`, in key
+ * order, from entries (sections flattened). For selected items shown outside the Select, from the
+ * same items + a shared `value` signal.
+ */
+export function selectedItemsOf(entries, keys) {
+    const byKey = new Map();
+    for (const item of flatItems(entries ?? EMPTY_ENTRIES))
+        byKey.set(item.key, item);
+    const list = keys == null ? [] : typeof keys === "object" && Symbol.iterator in keys ? [...keys] : [keys];
+    return list.map((key) => byKey.get(key)).filter((item) => item != null);
+}
+/** Sets the select value (react-stately `setValue` / `setSelectedKey`). */
+export function setSelectValue(state, value) {
+    const current = untrack(() => selectValue(state));
+    if (state.selectionMode === "single") {
+        const key = Array.isArray(value) ? (value[0] ?? null) : value;
+        // useControlledState: onChange only when the value changes (plain controlled: onChange only).
+        setControlledValue(state.control, key);
+        if (key !== current)
+            state.onSelectionChange?.(key);
+    }
+    else {
+        let keys = [];
+        if (Array.isArray(value))
+            keys = [...value];
+        else if (value != null)
+            keys = [value];
+        setControlledValue(state.control, keys);
+    }
+}
+/** Whether the select may open: a non-empty collection, or `allowsEmptyCollection`. */
+export const canOpen = (state) => untrack(() => selectCollection(state).size) !== 0 || state.allowsEmptyCollection;
+/** Opens the menu (not when the collection is empty, unless `allowsEmptyCollection`). */
+export function openSelect(state, focusStrategy = null) {
+    if (!canOpen(state))
+        return;
+    state.focusStrategy.set(focusStrategy);
+    openOverlay(state);
+}
+/** Toggles the menu (not when the collection is empty, unless `allowsEmptyCollection`). */
+export function toggleSelect(state, focusStrategy = null) {
+    if (!canOpen(state))
+        return;
+    state.focusStrategy.set(focusStrategy);
+    toggleOverlay(state);
+}

package/state/selection.d.ts

@@ -0,0 +1,3 @@
+export { createMultipleSelectionState, getSelection, readSelection, SelectionSet, setFocused, setFocusedKey, setSelectedKeys, setSelectionBehavior, type FocusState, type MultipleSelectionState, type MultipleSelectionStateProps, } from "@rivetjs/cdk/selection/state";
+export { SelectionManager, type MultipleSelectionManager, type SelectionManagerOptions, type SelectionEvent, type PointerType } from "@rivetjs/cdk/selection/manager";
+export type { DisabledBehavior, FocusStrategy, Key, Selection, SelectionBehavior, SelectionMode } from "@rivetjs/cdk/collections/types";

package/state/selection.js

@@ -0,0 +1,5 @@
+// Ported from @react-stately/selection (index): multiple selection + focus state and the
+// SelectionManager. Implementation lives in @rivetjs/cdk/selection (shared with cdk behaviours);
+// this module is the react-stately-shaped entry point (`@rivetjs/cdk/state/selection`).
+export { createMultipleSelectionState, getSelection, readSelection, SelectionSet, setFocused, setFocusedKey, setSelectedKeys, setSelectionBehavior, } from "@rivetjs/cdk/selection/state";
+export { SelectionManager } from "@rivetjs/cdk/selection/manager";

package/state/table-column-resize.d.ts

@@ -0,0 +1,58 @@
+import { type Signal } from "@rivetjs/reactivity";
+import { type ColumnSize } from "../virtualizer/table-column-layout.js";
+import type { GridNode } from "../collections/grid.js";
+import type { Key } from "../collections/types.js";
+import type { TableState } from "./table.js";
+export type { ColumnSize } from "../virtualizer/table-column-layout.js";
+export interface TableColumnResizeStateProps<T> {
+    /** Current width of the table or table viewport that the columns should be calculated against. */
+    tableWidth: number | Signal<number> | (() => number);
+    /** A function that is called to find the default width for a given column. */
+    getDefaultWidth?: ((node: GridNode<T>) => ColumnSize | null | undefined) | undefined;
+    /** A function that is called to find the default minWidth for a given column. */
+    getDefaultMinWidth?: ((node: GridNode<T>) => ColumnSize | null | undefined) | undefined;
+}
+export interface TableColumnResizeState<T> {
+    /** Called to update the state that a resize event has occurred. Returns the new widths for all columns based on the resized column. */
+    updateResizedColumns: (key: Key, width: number) => Map<Key, ColumnSize>;
+    /** Callback for when onColumnResize has started. */
+    startResize: (key: Key) => void;
+    /** Callback for when onColumnResize has ended. */
+    endResize: () => void;
+    /** Gets the current width for the specified column. */
+    getColumnWidth: (key: Key) => number;
+    /** Gets the current minWidth for the specified column. */
+    getColumnMinWidth: (key: Key) => number;
+    /** Gets the current maxWidth for the specified column. */
+    getColumnMaxWidth: (key: Key) => number;
+    /** Key of the currently resizing column. */
+    resizingColumn: Key | null;
+    /** A reference to the table state. */
+    tableState: TableState<T>;
+    /** A map of the current column widths. */
+    columnWidths: Map<Key, number>;
+}
+/** The serializable part of a column resize state. */
+export interface TableColumnResizeStateData<T = unknown> {
+    readonly tableWidth: number | Signal<number> | (() => number);
+    readonly getDefaultWidth: ((node: GridNode<T>) => ColumnSize | null | undefined) | undefined;
+    readonly getDefaultMinWidth: ((node: GridNode<T>) => ColumnSize | null | undefined) | undefined;
+    /** Key of the currently resizing column. */
+    readonly resizingColumn: Signal<Key | null>;
+    /** Uncontrolled column widths, and the column keys (joined) they were computed for. */
+    readonly uncontrolled: Signal<{
+        columns: string;
+        widths: Map<Key, ColumnSize>;
+    } | null>;
+}
+/** Column width state for a table with column resizing (react-stately `useTableColumnResizeState`). */
+export declare function createTableColumnResizeState<T>(props: TableColumnResizeStateProps<T>): TableColumnResizeStateData<T>;
+/** `startResize(key)`. */
+export declare function startColumnResize(data: TableColumnResizeStateData<any>, key: Key): void;
+/** `endResize()`. */
+export declare function endColumnResize(data: TableColumnResizeStateData<any>): void;
+/**
+ * The react-stately `TableColumnResizeState` view over a `TableState` view: current column widths
+ * for the table width, min / max widths, resizing column, and the update callbacks.
+ */
+export declare function tableColumnResizeState<T>(data: TableColumnResizeStateData<T>, state: TableState<T>): TableColumnResizeState<T>;