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

package/state/table-column-resize.js

@@ -0,0 +1,76 @@
+// Ported from @react-stately/table (useTableColumnResizeState.ts), Apache-2.0, © Adobe. The column
+// width math (TableColumnLayout.ts + TableUtils.ts) is the shared port in
+// `../virtualizer/table-column-layout.ts`.
+//
+// Rivet:
+// - `createTableColumnResizeState(props)` returns the serializable part (signals: table width, the
+//   resizing column, the uncontrolled widths `Map` + the column keys they belong to);
+//   `tableColumnResizeState(data, state)` derives react-stately's `TableColumnResizeState` view over a
+//   `TableState` view (`./table.ts`): widths are rebuilt per use from the collection's columns
+//   (`TableColumnLayout.buildColumnWidths`, O(columns)).
+// - Upstream resets the uncontrolled widths when the columns change (by key, during render); here the
+//   stored widths are used only while the column keys match, else the initial widths apply (no write
+//   during a read); the next `updateResizedColumns` stores widths for the new columns.
+// - `getDefaultWidth` / `getDefaultMinWidth` must be resumable functions (inline arrows / local consts).
+import { batch, signal, untrack } from "@rivetjs/reactivity";
+import { TableColumnLayout } from "../virtualizer/table-column-layout.js";
+/** Column width state for a table with column resizing (react-stately `useTableColumnResizeState`). */
+export function createTableColumnResizeState(props) {
+    return {
+        tableWidth: props.tableWidth ?? 0,
+        getDefaultWidth: props.getDefaultWidth,
+        getDefaultMinWidth: props.getDefaultMinWidth,
+        resizingColumn: signal(null),
+        uncontrolled: signal(null),
+    };
+}
+const readWidth = (w) => (typeof w === "function" ? w() : w) ?? 0;
+const columnsId = (columns) => columns.map((c) => typeof c.key + ":" + String(c.key)).join("\u0000");
+/** The uncontrolled widths in effect for `columns` (stored ones while the column keys match, else initial). */
+function uncontrolledWidths(data, layout, columns) {
+    const [, uncontrolledColumns] = layout.splitColumnsIntoControlledAndUncontrolled(columns);
+    const stored = data.uncontrolled();
+    if (stored && stored.columns === columnsId(columns))
+        return stored.widths;
+    return layout.getInitialUncontrolledWidths(uncontrolledColumns);
+}
+/** `startResize(key)`. */
+export function startColumnResize(data, key) {
+    data.resizingColumn.set(key);
+}
+/** `endResize()`. */
+export function endColumnResize(data) {
+    data.resizingColumn.set(null);
+}
+/**
+ * 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 function tableColumnResizeState(data, state) {
+    const layout = new TableColumnLayout({ getDefaultWidth: data.getDefaultWidth, getDefaultMinWidth: data.getDefaultMinWidth });
+    const columns = state.collection.columns;
+    const [controlledColumns, uncontrolledColumns] = layout.splitColumnsIntoControlledAndUncontrolled(columns);
+    const widths = uncontrolledWidths(data, layout, columns);
+    // combine columns back into one map that maintains same order as the columns
+    const colWidths = layout.recombineColumns(columns, widths, uncontrolledColumns, controlledColumns);
+    const columnWidths = layout.buildColumnWidths(readWidth(data.tableWidth), state.collection, colWidths);
+    const updateResizedColumns = (key, width) => {
+        const current = untrack(() => uncontrolledWidths(data, layout, columns));
+        const newSizes = layout.resizeColumnWidth(state.collection, current, key, width);
+        const map = new Map(Array.from(uncontrolledColumns).map(([key]) => [key, newSizes.get(key)]));
+        map.set(key, width);
+        batch(() => data.uncontrolled.set({ columns: columnsId(columns), widths: map }));
+        return newSizes;
+    };
+    return {
+        resizingColumn: data.resizingColumn(),
+        updateResizedColumns,
+        startResize: (key) => startColumnResize(data, key),
+        endResize: () => endColumnResize(data),
+        getColumnWidth: (key) => layout.getColumnWidth(key),
+        getColumnMinWidth: (key) => layout.getColumnMinWidth(key),
+        getColumnMaxWidth: (key) => layout.getColumnMaxWidth(key),
+        tableState: state,
+        columnWidths,
+    };
+}

package/state/table.d.ts

@@ -0,0 +1,81 @@
+import { type Signal } from "@rivetjs/reactivity";
+import { type ControlledState } from "../interactions/controllable.js";
+import { type ITableCollection } from "../collections/table.js";
+import type { CollectionChildren, Key, Node, SortDescriptor, SortDirection } from "../collections/types.js";
+import type { SelectionManagerOptions } from "../selection/manager.js";
+import { type GridState, type GridStateData, type GridStateOptions } from "./grid.js";
+export type { ITableCollection } from "../collections/table.js";
+export interface TableState<T> extends GridState<T, ITableCollection<T>> {
+    /** A collection of rows and columns in the table. */
+    collection: ITableCollection<T>;
+    /** Whether the row selection checkboxes should be displayed. */
+    showSelectionCheckboxes: boolean;
+    /** The current sorted column and direction. */
+    sortDescriptor: SortDescriptor | null;
+    /** Calls the provided onSortChange handler with the provided column key and sort direction. */
+    sort(columnKey: Key, direction?: "ascending" | "descending"): void;
+    /** Whether keyboard navigation is disabled, such as when the arrow keys should be handled by a component within a cell. */
+    isKeyboardNavigationDisabled: boolean;
+    /** Set whether keyboard navigation is disabled, such as when the arrow keys should be handled by a component within a cell. */
+    setKeyboardNavigationDisabled: (val: boolean) => void;
+    /** A set of keys for items that are expanded. */
+    expandedKeys: Set<Key>;
+    /** Toggles the expanded state for a row by its key. */
+    toggleKey(key: Key): void;
+    /** The id of the column that displays hierarchical data. */
+    treeColumn: Key | null;
+}
+export interface TableStateProps<T> extends GridStateOptions {
+    /** The elements that make up the table (react-stately builders: TableHeader, TableBody, Column, Row, Cell). */
+    children?: CollectionChildren<T> | undefined;
+    /** A pre-constructed collection to use instead of building one from children. */
+    collection?: ITableCollection<T> | undefined;
+    /** Whether the row selection checkboxes should be displayed. */
+    showSelectionCheckboxes?: boolean | undefined;
+    /** @private Whether the row drag button should be displayed. */
+    showDragButtons?: boolean | undefined;
+    /** The id of the column that displays hierarchical data. */
+    treeColumn?: Key | undefined;
+    /** The current sorted column and direction (plain: controlled; Signal: two-way). */
+    sortDescriptor?: SortDescriptor | Signal<SortDescriptor | null> | null | undefined;
+    /** Handler that is called when the sorted column or direction changes. */
+    onSortChange?: ((descriptor: SortDescriptor) => any) | undefined;
+    /** The currently expanded keys in the collection (controlled). */
+    expandedKeys?: Iterable<Key> | Signal<Set<Key>> | undefined;
+    /** The initial expanded keys in the collection (uncontrolled). */
+    defaultExpandedKeys?: Iterable<Key> | undefined;
+    /** Handler that is called when items are expanded or collapsed. */
+    onExpandedChange?: ((keys: Set<Key>) => any) | undefined;
+}
+/** The serializable part of a table state. */
+export interface TableStateData extends GridStateData {
+    readonly showSelectionCheckboxes: boolean;
+    readonly showDragButtons: boolean;
+    readonly treeColumn: Key | null;
+    readonly sortDescriptor: ControlledState<SortDescriptor | null, SortDescriptor>;
+    readonly expandedKeys: ControlledState<Set<Key>>;
+    readonly keyboardNavigationDisabled: Signal<boolean>;
+}
+/**
+ * Provides state management for a table component (react-stately `useTableState`): row selection,
+ * sort order changes, expanded rows, keyboard-navigation-disabled flag.
+ */
+export declare function createTableState<T>(props?: TableStateProps<T>): TableStateData;
+/** `state.sort(columnKey, direction?)`: calls `onSortChange` (and writes a Signal `sortDescriptor`). */
+export declare function sortTable(data: TableStateData, columnKey: Key, direction?: SortDirection): void;
+/** `state.toggleKey(key)`: toggles the expanded state of a row. */
+export declare function toggleTableKey(data: TableStateData, key: Key): void;
+/** `state.setKeyboardNavigationDisabled(val)`. */
+export declare function setTableKeyboardNavigationDisabled(data: TableStateData, val: boolean): void;
+/** The react-stately `TableState` view over `collection` (build per handler / binding; reads signals). */
+export declare function tableState<T>(data: TableStateData, collection: ITableCollection<T>, options?: SelectionManagerOptions): TableState<T>;
+/**
+ * Builds the table collection of `useTableState` from `children` (react-stately builders) unless a
+ * `collection` is given. Pass the same `cache` object across calls to reuse cached nodes.
+ */
+export declare function tableCollection<T>(props: TableStateProps<T>, cache?: object): ITableCollection<T>;
+/**
+ * Filters a collection using the provided filter function and returns a new TableState
+ * (react-stately `UNSTABLE_useFilteredTableState`).
+ */
+export declare function filteredTableState<T>(state: TableState<T>, filterFn: ((nodeValue: string, node: Node<T>) => boolean) | null | undefined): TableState<T>;

package/state/table.js

@@ -0,0 +1,114 @@
+// Ported from @react-stately/table (useTableState.ts: useTableState, UNSTABLE_useFilteredTableState),
+// Apache-2.0, © Adobe.
+//
+// Rivet:
+// - Split like `./grid.ts`: `createTableState(props)` returns the serializable part (grid data +
+//   sort / expansion controlled states + keyboard-navigation-disabled signal); `tableState(data,
+//   collection)` derives react-stately's `TableState` view per use (collection + SelectionManager are
+//   class instances). `sort`, `toggleKey`, `setKeyboardNavigationDisabled` on the view call the free
+//   functions `sortTable`, `toggleTableKey`, `setTableKeyboardNavigationDisabled`.
+// - `sortDescriptor` / `expandedKeys`: plain value (controlled: only `onSortChange` /
+//   `onExpandedChange` are called) or Signal (two-way) — `../interactions/controllable.ts`.
+//   Upstream `sortDescriptor` is controlled only (no `defaultSortDescriptor`); same here.
+// - Collection: `props.collection`, or built from `children` with the react-stately builders of
+//   `../collections/table.ts` (`TableHeader` / `Column` / `TableBody` / `Row` / `Cell`) —
+//   `tableCollection(props)`.
+// - `UNSTABLE_useTreeGridState` (feature-flagged Spectrum treegrid) is not ported: RAC tables expand
+//   rows through `expandedKeys` on this state (RAC `TableInner`).
+import { signal, untrack } from "@rivetjs/reactivity";
+import { controllable, controlledValue, setControlledValue } from "../interactions/controllable.js";
+import { CollectionBuilder } from "../collections/builder.js";
+import { TableCollection as StatelyTableCollection, tableBuilderContext } from "../collections/table.js";
+import { createGridState, gridState } from "./grid.js";
+const isSignal = (v) => typeof v === "function" && typeof v.set === "function";
+/**
+ * Provides state management for a table component (react-stately `useTableState`): row selection,
+ * sort order changes, expanded rows, keyboard-navigation-disabled flag.
+ */
+export function createTableState(props = {}) {
+    const grid = createGridState({ ...props, disabledBehavior: props.disabledBehavior || "selection" });
+    const expanded = props.expandedKeys;
+    return {
+        ...grid,
+        showSelectionCheckboxes: props.showSelectionCheckboxes || false,
+        showDragButtons: !!props.showDragButtons,
+        treeColumn: props.treeColumn ?? null,
+        sortDescriptor: controllable(props.sortDescriptor ?? null, null, props.onSortChange),
+        expandedKeys: controllable(
+        // A Signal is two-way; an accessor (live prop, `liveKeys`: a Set) is controlled, read live.
+        expanded == null ? undefined : typeof expanded === "function" ? expanded : new Set(expanded), props.defaultExpandedKeys ? new Set(props.defaultExpandedKeys) : new Set(), props.onExpandedChange),
+        keyboardNavigationDisabled: signal(false),
+    };
+}
+const OPPOSITE_SORT_DIRECTION = { ascending: "descending", descending: "ascending" };
+/** `state.sort(columnKey, direction?)`: calls `onSortChange` (and writes a Signal `sortDescriptor`). */
+export function sortTable(data, columnKey, direction) {
+    const current = untrack(() => controlledValue(data.sortDescriptor));
+    setControlledValue(data.sortDescriptor, {
+        column: columnKey,
+        direction: direction ?? (current?.column === columnKey ? OPPOSITE_SORT_DIRECTION[current.direction] : "ascending"),
+    });
+}
+/** `state.toggleKey(key)`: toggles the expanded state of a row. */
+export function toggleTableKey(data, key) {
+    setControlledValue(data.expandedKeys, (keys) => {
+        const newKeys = new Set(keys);
+        if (newKeys.has(key))
+            newKeys.delete(key);
+        else
+            newKeys.add(key);
+        return newKeys;
+    });
+}
+/** `state.setKeyboardNavigationDisabled(val)`. */
+export function setTableKeyboardNavigationDisabled(data, val) {
+    data.keyboardNavigationDisabled.set(val);
+}
+/** The react-stately `TableState` view over `collection` (build per handler / binding; reads signals). */
+export function tableState(data, collection, options) {
+    const grid = gridState(data, collection, options);
+    return {
+        ...grid,
+        collection,
+        showSelectionCheckboxes: data.showSelectionCheckboxes,
+        sortDescriptor: data.sortDescriptor.value() ?? null,
+        isKeyboardNavigationDisabled: collection.size === 0 || data.keyboardNavigationDisabled(),
+        setKeyboardNavigationDisabled: (val) => setTableKeyboardNavigationDisabled(data, val),
+        sort: (columnKey, direction) => sortTable(data, columnKey, direction),
+        expandedKeys: data.expandedKeys.value(),
+        toggleKey: (key) => toggleTableKey(data, key),
+        treeColumn: data.treeColumn,
+    };
+}
+const builders = new WeakMap();
+/**
+ * Builds the table collection of `useTableState` from `children` (react-stately builders) unless a
+ * `collection` is given. Pass the same `cache` object across calls to reuse cached nodes.
+ */
+export function tableCollection(props, cache) {
+    if (props.collection)
+        return props.collection;
+    const context = tableBuilderContext({
+        showSelectionCheckboxes: props.showSelectionCheckboxes,
+        showDragButtons: props.showDragButtons,
+        selectionMode: props.selectionMode,
+    });
+    let builder = cache ? builders.get(cache) : undefined;
+    if (!builder) {
+        builder = new CollectionBuilder();
+        if (cache)
+            builders.set(cache, builder);
+    }
+    const nodes = builder.build({ children: (props.children ?? null) }, context);
+    return new StatelyTableCollection(nodes, null, context);
+}
+/**
+ * Filters a collection using the provided filter function and returns a new TableState
+ * (react-stately `UNSTABLE_useFilteredTableState`).
+ */
+export function filteredTableState(state, filterFn) {
+    const collection = (filterFn ? state.collection.filter?.(filterFn) ?? state.collection : state.collection);
+    const selectionManager = state.selectionManager.withCollection(collection);
+    // TODO (upstream): handle focus key reset? That logic is in useGridState
+    return { ...state, collection, selectionManager };
+}

package/state/tabs.d.ts

@@ -0,0 +1,85 @@
+import { type Signal } from "@rivetjs/reactivity";
+import { type MultipleSelectionState } from "../_adapters/grid-selection.js";
+import type { Key, Orientation } from "../_adapters/collection.js";
+export type { Key } from "../_adapters/collection.js";
+/** A tab the state knows of at creation (default selection): its key and whether it is disabled. */
+export interface TabKey {
+    readonly id: Key;
+    readonly isDisabled?: boolean | undefined;
+}
+export type KeyboardActivation = "automatic" | "manual";
+export interface TabListStateOptions {
+    /** Base of the generated ids (tabs `<id>-tab-<key>`, panels `<id>-tabpanel-<key>`); default a fresh id. */
+    id?: string | undefined;
+    /** The currently selected key: a two-way signal, a plain value or an accessor (controlled; live props). */
+    selectedKey?: Key | null | Signal<Key | null> | Signal<Key> | (() => Key | null) | undefined;
+    /** The initial selected key (uncontrolled). */
+    defaultSelectedKey?: Key | undefined;
+    /** Handler that is called when the selection changes (also on re-selecting the selected tab). */
+    onSelectionChange?: ((key: Key) => void) | undefined;
+    /** The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with. An accessor stays live (read through `tabsDisabledKeys`). */
+    disabledKeys?: Iterable<Key> | (() => Iterable<Key> | undefined) | undefined;
+    /** Whether the whole tab list is disabled (an accessor: live props, read at use through `isTabsDisabled`). */
+    isDisabled?: boolean | (() => boolean | undefined) | undefined;
+    /** @default "horizontal". An accessor stays live (read through `tabsOrientation`). */
+    orientation?: Orientation | (() => Orientation | undefined) | undefined;
+    /** @default "automatic". An accessor stays live (read through `tabsKeyboardActivation`). */
+    keyboardActivation?: KeyboardActivation | (() => KeyboardActivation | undefined) | undefined;
+    /**
+     * Rivet: the tabs in order, for the default selection (first enabled tab, else the first tab) when no tab is
+     * selected or the selected key is not a tab (not for a plain controlled `selectedKey`). Read once, at creation;
+     * omit to keep the given selection as is.
+     */
+    tabs?: (() => readonly TabKey[]) | undefined;
+}
+export interface TabListState {
+    /** Base id: tabs are `<id>-tab-<key>`, panels `<id>-tabpanel-<key>`. */
+    readonly id: string;
+    /** The selected key (a read-only cell for a plain controlled value, the accessor for a live one: `controlled`, never written). */
+    readonly selectedKey: Signal<Key | null>;
+    /** A plain controlled `selectedKey`: never written. */
+    readonly controlled: boolean;
+    readonly focusedKey: Signal<Key | null>;
+    /** Selection the focused key was set under (see effectiveFocusedKey). */
+    readonly focusedSelection: Signal<Key | null>;
+    readonly isFocused: Signal<boolean>;
+    readonly disabledKeys: Set<Key>;
+    /** Whether the whole tab list was disabled at creation; read `isTabsDisabled(state)` (follows a live `disabled`). */
+    readonly isDisabled: boolean;
+    /** A live `isDisabled` (live props). */
+    readonly disabled?: (() => boolean | undefined) | undefined;
+    readonly orientation: Orientation;
+    readonly keyboardActivation: KeyboardActivation;
+    /** Rivet (live props): accessors of a live `orientation` / `keyboardActivation` / `disabledKeys` (the fields above
+     *  hold the creation values); read through `tabsOrientation` / `tabsKeyboardActivation` / `tabsDisabledKeys`. */
+    readonly live?: TabListLive | undefined;
+    readonly onSelectionChange?: ((key: Key) => void) | undefined;
+}
+/** Live accessors of a tab list state (live props). */
+export interface TabListLive {
+    readonly orientation?: () => Orientation | undefined;
+    readonly keyboardActivation?: () => KeyboardActivation | undefined;
+    readonly disabledKeys?: () => Iterable<Key> | undefined;
+}
+/** The tab list's current orientation (a live one, else the creation value). */
+export declare const tabsOrientation: (state: TabListState) => Orientation;
+/** The tab list's current keyboard activation. */
+export declare const tabsKeyboardActivation: (state: TabListState) => KeyboardActivation;
+/** The tab list's current disabled keys (a live one is read into a new Set). */
+export declare const tabsDisabledKeys: (state: TabListState) => Set<Key>;
+/** Whether the whole tab list is disabled (reads a live `isDisabled`). */
+export declare const isTabsDisabled: (state: TabListState) => boolean;
+/** react-stately findDefaultSelectedKey: first enabled tab, else the first tab. */
+export declare function findDefaultSelectedKey(tabs: readonly TabKey[], disabledKeys: Set<Key>, isDisabled?: boolean): Key | null;
+export declare function createTabListState(options: TabListStateOptions): TabListState;
+/** The key that is the tab stop (reads signals): the focused key, or the selection when it changed from outside while unfocused. */
+export declare function effectiveFocusedKey(state: TabListState): Key | null;
+/** Select `key` (and focus it), firing `onSelectionChange` (always, like useSingleSelectListState). */
+export declare function selectTab(state: TabListState, key: Key): void;
+/** Set the focused tab (records the selection it was set under). */
+export declare function setTabFocusedKey(state: TabListState, key: Key | null): void;
+/**
+ * Transient MultipleSelectionState view of the tabs state for the SelectionManager
+ * (useSingleSelectListState: single, disallowEmptySelection, duplicate events allowed). Event time only.
+ */
+export declare function tabsSelectionState(state: TabListState): MultipleSelectionState;

package/state/tabs.js

@@ -0,0 +1,161 @@
+// Tabs state (react-stately useTabListState over useSingleSelectListState): the selected key, the
+// focused key, disabled keys, orientation and keyboard activation. Serializable (signals + JSON).
+// Ported from react-spectrum (Apache-2.0, © Adobe): packages/react-stately/src/tabs/useTabListState.ts,
+// list/useSingleSelectListState.ts.
+//
+// Rivet:
+// - `selectedKey` is the source of truth: a two-way `Signal<Key | null>`, a plain value (RAC controlled:
+//   never written, `onSelectionChange` still fires) or absent (uncontrolled, `defaultSelectedKey`). The
+//   SelectionManager runs on a transient lens (`tabsSelectionState`) at event time.
+// - useTabListState's effect "a tab is always selected" runs once, at creation, over the tab keys the
+//   caller found (`TabListStateOptions.tabs`: `Tabs` builds them from its children, the `items` preset
+//   from its items). It writes the selection without calling `onSelectionChange` (the original fires it
+//   from a mount effect; Rivet creates the state on the server).
+// - Its second effect (focus follows selection while the tablist is not focused) is the
+//   `effectiveFocusedKey` read: `focusedSelection` remembers the selection the focused key was set
+//   under, so a selection change from outside moves the tab stop like the original's effect.
+import { signal, untrack } from "@rivetjs/reactivity";
+import { createId } from "@rivetjs/cdk/id";
+import { hasKey } from "../_adapters/grid-selection.js";
+/** The tab list's current orientation (a live one, else the creation value). */
+export const tabsOrientation = (state) => (state.live?.orientation ? (state.live.orientation() ?? "horizontal") : state.orientation);
+/** The tab list's current keyboard activation. */
+export const tabsKeyboardActivation = (state) => state.live?.keyboardActivation ? (state.live.keyboardActivation() ?? "automatic") : state.keyboardActivation;
+/** The tab list's current disabled keys (a live one is read into a new Set). */
+export const tabsDisabledKeys = (state) => state.live?.disabledKeys ? new Set(state.live.disabledKeys() ?? []) : state.disabledKeys;
+const isSignal = (value) => typeof value === "function" && typeof value.set === "function";
+/** Whether the whole tab list is disabled (reads a live `isDisabled`). */
+export const isTabsDisabled = (state) => (state.disabled ? !!state.disabled() : state.isDisabled);
+/** react-stately findDefaultSelectedKey: first enabled tab, else the first tab. */
+export function findDefaultSelectedKey(tabs, disabledKeys, isDisabled = false) {
+    if (!tabs.length)
+        return null;
+    const enabled = isDisabled ? undefined : tabs.find((tab) => !tab.isDisabled && !hasKey(disabledKeys, tab.id));
+    return (enabled ?? tabs[0]).id;
+}
+const sameKey = (a, b) => (a == null || b == null ? a == b : String(a) === String(b));
+export function createTabListState(options) {
+    // Rivet (live props): an accessor `orientation` / `keyboardActivation` / `disabledKeys` stays live (`live`).
+    let live;
+    const now = (key) => {
+        const v = options[key];
+        if (typeof v !== "function")
+            return v;
+        (live ??= {})[key] = v;
+        return untrack(v);
+    };
+    const disabledKeys = new Set(now("disabledKeys") ?? []);
+    const orientation = now("orientation") ?? "horizontal";
+    const keyboardActivation = now("keyboardActivation") ?? "automatic";
+    const disabled = typeof options.isDisabled === "function" ? options.isDisabled : undefined;
+    const isDisabled = disabled ? !!untrack(disabled) : !!options.isDisabled;
+    const given = options.selectedKey;
+    const controlled = given !== undefined && !isSignal(given);
+    let selectedKey;
+    if (isSignal(given))
+        selectedKey = given;
+    // A live controlled value (accessor; live props): kept as is (resumable), only read — `controlled` writes nothing.
+    else if (typeof given === "function")
+        selectedKey = given;
+    else if (controlled) {
+        const value = given;
+        // A plain controlled value: a read-only cell (useControlledState: writes only call onSelectionChange).
+        const cell = Object.assign(() => value, { set: () => value, update: () => value });
+        selectedKey = cell;
+    }
+    else
+        selectedKey = signal(options.defaultSelectedKey ?? null);
+    // "Ensure a tab is always selected": none selected / the selected key is not a tab → first enabled tab.
+    const tabs = options.tabs;
+    if (tabs && !controlled) {
+        const current = untrack(selectedKey);
+        const list = tabs();
+        if (current == null || !list.some((tab) => sameKey(tab.id, current))) {
+            const key = findDefaultSelectedKey(list, disabledKeys, isDisabled);
+            if (key != null)
+                selectedKey.set(key);
+        }
+    }
+    const initial = untrack(selectedKey);
+    return {
+        id: options.id ?? createId(),
+        selectedKey,
+        controlled,
+        focusedKey: signal(initial),
+        focusedSelection: signal(initial),
+        isFocused: signal(false),
+        disabledKeys,
+        isDisabled,
+        disabled,
+        orientation,
+        keyboardActivation,
+        ...(live ? { live: live } : {}),
+        onSelectionChange: options.onSelectionChange,
+    };
+}
+/** The key that is the tab stop (reads signals): the focused key, or the selection when it changed from outside while unfocused. */
+export function effectiveFocusedKey(state) {
+    const selected = state.selectedKey(), focused = state.focusedKey();
+    if (!state.isFocused() && !sameKey(selected, state.focusedSelection()))
+        return selected;
+    return focused;
+}
+/** Select `key` (and focus it), firing `onSelectionChange` (always, like useSingleSelectListState). */
+export function selectTab(state, key) {
+    if (!state.controlled)
+        state.selectedKey.set(key);
+    setTabFocusedKey(state, key);
+    state.onSelectionChange?.(key);
+}
+/** Set the focused tab (records the selection it was set under). */
+export function setTabFocusedKey(state, key) {
+    state.focusedKey.set(key);
+    state.focusedSelection.set(untrack(state.selectedKey));
+}
+/**
+ * Transient MultipleSelectionState view of the tabs state for the SelectionManager
+ * (useSingleSelectListState: single, disallowEmptySelection, duplicate events allowed). Event time only.
+ */
+export function tabsSelectionState(state) {
+    const keys = () => {
+        const key = state.selectedKey();
+        return new Set(key == null ? [] : [key]);
+    };
+    const lens = Object.assign(keys, {
+        set(value) {
+            if (value === "all")
+                return value;
+            const key = value.values().next().value ?? null;
+            if (key != null)
+                selectTab(state, key);
+            return value;
+        },
+        update(fn) {
+            return lens.set(fn(untrack(keys)));
+        },
+    });
+    const focusLens = Object.assign(() => state.focusedKey(), {
+        set(value) {
+            setTabFocusedKey(state, value);
+            return value;
+        },
+        update(fn) {
+            return focusLens.set(fn(untrack(state.focusedKey)));
+        },
+    });
+    return {
+        selectionMode: "single",
+        disallowEmptySelection: true,
+        selectionBehaviorProp: "toggle",
+        selectionBehavior: signal("toggle"),
+        selectedKeys: lens,
+        anchorKey: signal(null),
+        currentKey: signal(null),
+        disabledKeys: tabsDisabledKeys(state),
+        disabledBehavior: "all",
+        allowDuplicateSelectionEvents: true,
+        isFocused: state.isFocused,
+        focusedKey: focusLens,
+        childFocusStrategy: signal(null),
+    };
+}

package/state/time-field.d.ts

@@ -0,0 +1,32 @@
+import { type DateValueString, type Time } from "@rivetjs/cdk/date";
+import type { ValidationFunction } from "./form-validation.js";
+import { type DateFieldBaseOptions, type DateValueProp, type MappedTimeValue, type StandaloneDateFieldState, type TimeValue } from "./date-field.js";
+export type { MappedTimeValue, TimeValue } from "./date-field.js";
+/** useTimeFieldState props (TimePickerProps + `locale`). */
+export interface TimeFieldStateOptions<T extends TimeValue = TimeValue> extends Omit<DateFieldBaseOptions, "minValue" | "maxValue" | "placeholderValue" | "granularity" | "createCalendar"> {
+    /** Controlled value: a time value, or a two-way signal of its string form. */
+    value?: DateValueProp<T>;
+    /** Uncontrolled initial value. */
+    defaultValue?: T | DateValueString | null;
+    /** Handler that is called when the value changes. */
+    onChange?: (value: MappedTimeValue<T> | null) => void;
+    /** The minimum allowed time that a user may select. */
+    minValue?: TimeValue | DateValueString | null;
+    /** The maximum allowed time that a user may select. */
+    maxValue?: TimeValue | DateValueString | null;
+    /** A placeholder time that influences the format of the placeholder shown when no value is selected. Defaults to 12:00 AM or 00:00 depending on the hour cycle. */
+    placeholderValue?: TimeValue | DateValueString | null;
+    /** Determines the smallest unit that is displayed in the time picker. @default 'minute' */
+    granularity?: "hour" | "minute" | "second";
+    /** Custom client validation of the value (a time object). */
+    validate?: ValidationFunction<MappedTimeValue<T>>;
+    id?: string;
+}
+/** A TimeField's state (DateFieldState with `kind: "time"`). */
+export type TimeFieldState = StandaloneDateFieldState;
+/**
+ * `useTimeFieldState`: state of a time field (time values entered and edited segment by segment).
+ */
+export declare function createTimeFieldState<T extends TimeValue = TimeValue>(options?: TimeFieldStateOptions<T>): TimeFieldState;
+/** The current time value (React Stately `state.timeValue`). Reads. */
+export declare function timeValue(state: TimeFieldState): Time | null;

package/state/time-field.js

@@ -0,0 +1,34 @@
+// Ported from react-stately (react-spectrum) src/datepicker/useTimeFieldState.ts, Apache-2.0, © Adobe.
+// Rivet:
+// - The state is a standalone date field state (`./date-field.ts`) with `kind: "time"`: `value`
+//   holds the TimeValue's string form (`Time` "11:45:00", or a date-time when it has a date);
+//   the field edits it as a date-time on the value's date (else today), as React Stately's
+//   `convertValue` does, and emits a `Time` unless the value / placeholder has a date or the
+//   default value has a time zone.
+// - Methods are the date field's functions (`increment(state, "hour")` …); `timeValue(state)` is
+//   React Stately's `state.timeValue`.
+// Deviation: none in behaviour; the date-time conversion runs on read instead of per render.
+import { parseDateValue, toTime } from "@rivetjs/cdk/date";
+import { dateValueSignal, fieldState, } from "./date-field.js";
+/**
+ * `useTimeFieldState`: state of a time field (time values entered and edited segment by segment).
+ */
+export function createTimeFieldState(options = {}) {
+    const value = dateValueSignal(options.value, options.defaultValue);
+    const defaultValue = typeof options.defaultValue === "string" ? parseDateValue(options.defaultValue) : options.defaultValue;
+    const defaultTimeZone = defaultValue && "timeZone" in defaultValue ? defaultValue.timeZone : undefined;
+    return fieldState({
+        ...options,
+        granularity: options.granularity || "minute",
+        maxGranularity: "hour",
+        ...(defaultTimeZone ? { defaultTimeZone } : {}),
+    }, value, "time");
+}
+/** The current time value (React Stately `state.timeValue`). Reads. */
+export function timeValue(state) {
+    const text = state.value();
+    if (!text)
+        return null;
+    const value = parseDateValue(text);
+    return "day" in value ? toTime(value) : value;
+}