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

package/state/grid.js

@@ -0,0 +1,127 @@
+// Ported from @react-stately/grid (useGridState.ts), Apache-2.0, © Adobe.
+//
+// Rivet:
+// - The state is split like every cdk list state: `createGridState(props)` returns the serializable
+//   part (selection + focus signals, disabled keys, focus mode); `gridState(data, collection)`
+//   derives react-stately's `GridState` view (`{ collection, disabledKeys, selectionManager,
+//   isKeyboardNavigationDisabled }`) per use — inside a handler or a binding — because the
+//   collection and the `SelectionManager` are class instances (never captured in resumable
+//   closures).
+// - react-stately overrides `selectionState.setFocusedKey` for `focusMode: "cell"` (an item key
+//   focuses its first / last cell); here `GridSelectionManager.setFocusedKey` does the same.
+// - The "reset focused key when the focused item is deleted" effect is `resetGridFocusedKey(state,
+//   previousCollection, collection)`: call it when the collection changes (component region
+//   re-render / after a data update), with the previous collection.
+import { untrack } from "@rivetjs/reactivity";
+import { getChildNodes, getFirstItem, getLastItem } from "../collections/nodes.js";
+import { SelectionManager } from "../selection/manager.js";
+import { createMultipleSelectionState, setFocusedKey as setStateFocusedKey, } from "../selection/state.js";
+/**
+ * Provides state management for a grid component (react-stately `useGridState`). Handles row
+ * selection and focusing a grid cell's focusable child if applicable.
+ */
+export function createGridState(props = {}) {
+    const selectionState = props.UNSAFE_selectionState ?? createMultipleSelectionState(props);
+    return {
+        selectionState,
+        disabledKeys: props.disabledKeys ? new Set(props.disabledKeys) : new Set(),
+        focusMode: props.focusMode,
+    };
+}
+/**
+ * A `SelectionManager` whose `setFocusedKey` focuses a row's first / last cell when the grid's
+ * focus mode is "cell" (react-stately overrides `selectionState.setFocusedKey`).
+ */
+export class GridSelectionManager extends SelectionManager {
+    focusMode;
+    gridCollection;
+    managerOptions;
+    constructor(collection, state, focusMode, options) {
+        super(collection, state, options);
+        this.focusMode = focusMode;
+        this.gridCollection = collection;
+        this.managerOptions = options;
+    }
+    setFocusedKey(key, childFocusStrategy) {
+        if (key != null && !this.collection.getItem(key))
+            return;
+        setStateFocusedKey(this.selectionState, gridFocusKey(this.gridCollection, this.focusMode, key, childFocusStrategy), childFocusStrategy);
+    }
+    withCollection(collection) {
+        return new GridSelectionManager(collection, this.selectionState, this.focusMode, {
+            ...this.managerOptions,
+            fullCollection: this.managerOptions?.fullCollection ?? this.gridCollection,
+        });
+    }
+}
+/** The key `setFocusedKey(key, child)` really focuses: in "cell" focus mode an item key → its first / last cell. */
+export function gridFocusKey(collection, focusMode, key, child) {
+    // If focusMode is cell and an item is focused, focus a child cell instead.
+    if (focusMode === "cell" && key != null) {
+        const item = collection.getItem(key);
+        if (item?.type === "item") {
+            const children = getChildNodes(item, collection);
+            if (child === "last")
+                key = getLastItem(children)?.key ?? null;
+            else
+                key = getFirstItem(children)?.key ?? null;
+        }
+    }
+    return key;
+}
+/** The react-stately `GridState` view of `data` over `collection` (build per handler / binding). */
+export function gridState(data, collection, options) {
+    return {
+        collection,
+        disabledKeys: data.disabledKeys,
+        selectionManager: new GridSelectionManager(collection, data.selectionState, data.focusMode, options),
+        isKeyboardNavigationDisabled: false,
+    };
+}
+/**
+ * Reset the focused key if that item was deleted from the collection (react-stately's effect):
+ * focus the nearest focusable row at or after the deleted position, else before it, keeping the
+ * cell index when a cell was focused.
+ */
+export function resetGridFocusedKey(data, cachedCollection, collection) {
+    const selectionState = data.selectionState;
+    const focusedKey = untrack(selectionState.focusedKey);
+    if (focusedKey == null || !cachedCollection || collection.getItem(focusedKey))
+        return;
+    const manager = gridState(data, collection).selectionManager;
+    const set = (key) => setStateFocusedKey(selectionState, gridFocusKey(collection, data.focusMode, key));
+    const node = cachedCollection.getItem(focusedKey);
+    const parentNode = node?.parentKey != null && (node.type === "cell" || node.type === "rowheader" || node.type === "column") ? cachedCollection.getItem(node.parentKey) : node;
+    if (!parentNode) {
+        set(null);
+        return;
+    }
+    const cachedRows = cachedCollection.rows;
+    const rows = collection.rows;
+    const diff = cachedRows.length - rows.length;
+    const index = Math.min(diff > 1 ? Math.max(parentNode.index - diff + 1, 0) : parentNode.index, rows.length - 1);
+    let newRow = null;
+    // Find the nearest focusable row at or after the deleted position...
+    for (let i = Math.max(0, index); i < rows.length; i++) {
+        if (!manager.isDisabled(rows[i].key) && rows[i].type !== "headerrow") {
+            newRow = rows[i];
+            break;
+        }
+    }
+    // ...otherwise the nearest focusable row before it. (Mirrors useListState's getKeyAfter/getKeyBefore walk.)
+    if (newRow === null) {
+        for (let i = index - 1; i >= 0; i--) {
+            if (!manager.isDisabled(rows[i].key) && rows[i].type !== "headerrow") {
+                newRow = rows[i];
+                break;
+            }
+        }
+    }
+    if (newRow) {
+        const childNodes = newRow.hasChildNodes ? [...getChildNodes(newRow, collection)] : [];
+        const keyToFocus = newRow.hasChildNodes && parentNode !== node && node && node.index < childNodes.length ? childNodes[node.index].key : newRow.key;
+        set(keyToFocus);
+    }
+    else
+        set(null);
+}

package/state/list.d.ts

@@ -0,0 +1,58 @@
+import { type Signal } from "@rivetjs/reactivity";
+import { type CollectionEntry, type CollectionItem, type Key, type MultipleSelectionStateProps, type SelectionBehavior } from "../_adapters/collections.js";
+import type { LinkBehavior, SelectableCollection, SelectableOptions } from "../_adapters/selection.js";
+export type { Key, Selection, SelectionMode, SelectionBehavior, DisabledBehavior, Orientation, CollectionEntry, CollectionItem } from "../_adapters/collections.js";
+export type { CollectionSection } from "../_adapters/collections.js";
+export type { SelectableOptions, LinkBehavior } from "../_adapters/selection.js";
+export { isSection, textOf, flatItems } from "../_adapters/collections.js";
+/** An item of a data-driven collection (alias of `CollectionItem`). */
+export type Item = CollectionItem;
+export interface ListState extends SelectableCollection {
+    /** Id of the collection element; option ids are `<id>-option-<key>`. */
+    readonly id: string;
+}
+export interface ListProps extends MultipleSelectionStateProps, SelectableOptions {
+    /** Data items: their `disabled` flags join `disabledKeys`; the first enabled / selected item is the initial tab stop. */
+    items?: readonly CollectionEntry[] | (() => readonly CollectionEntry[]);
+    id?: string;
+    onAction?: (key: Key) => void;
+    /** Initial focused key (default: none for virtual focus, else the first selected or first enabled item). */
+    focusedKey?: Key | null;
+    /** @deprecated use `selectedKeys`. */
+    selected?: Signal<Set<Key>>;
+    /** @deprecated use `defaultSelectedKeys`. */
+    defaultSelected?: Iterable<Key>;
+    /** @deprecated use `selectOnFocus` (or `selectionBehavior: "replace"`). */
+    followFocus?: boolean;
+}
+/** react-stately `useListState`: multiple selection + focus over a collection. */
+export declare function createListState(props: ListProps): ListState;
+export interface SingleSelectListProps extends Omit<ListProps, "selectionMode" | "selectedKeys" | "defaultSelectedKeys" | "onSelectionChange" | "disallowEmptySelection"> {
+    /** Two-way selected key (RAC controlled `selectedKey`). */
+    selectedKey?: Signal<Key | null>;
+    defaultSelectedKey?: Key | null;
+    /** Called with the selected key (also when the same key is selected again). */
+    onSelectionChange?: (key: Key | null) => void;
+}
+export interface SingleSelectListState extends ListState {
+    readonly selectedKey: Signal<Key | null>;
+}
+/** react-stately `useSingleSelectListState`: single selection, never empty by user action. */
+export declare function createSingleSelectListState(props: SingleSelectListProps): SingleSelectListState;
+/** react-aria `getItemId`: `<list id>-option-<key without whitespace>`. */
+export declare const getItemId: (state: {
+    id: string;
+}, key: Key) => string;
+/** `aria-selected` of an option: absent with selection mode "none". */
+export declare const itemSelected: (state: ListState, key: Key, disabled?: boolean) => boolean | undefined;
+/** Whether the item is disabled for every interaction (`aria-disabled`, `data-disabled`). */
+export declare const itemDisabled: (state: ListState, key: Key, disabled?: boolean) => boolean;
+/** Roving `tabindex` of an item (none with virtual focus or when disabled). */
+export declare const itemTabIndex: (state: ListState, key: Key, disabled?: boolean) => number | undefined;
+/** `data-focused` of an item: the collection is focused and this is its focused key (keyed read first: only the
+ * focused item re-runs when the collection's focus changes). */
+export declare const itemFocused: (state: ListState, key: Key) => boolean;
+/** `tabindex` of the collection element: tabbable while no item is the focus target. */
+export declare const collectionTabIndex: (state: ListState) => number | undefined;
+/** RAC `linkBehavior` default of a ListBox: "action" with `selectionBehavior="replace"`, else "override". */
+export declare function listBoxLinkBehavior(selectionBehavior?: SelectionBehavior, linkBehavior?: LinkBehavior): LinkBehavior;

package/state/list.js

@@ -0,0 +1,124 @@
+// Ported from react-spectrum (react-stately: list/useListState, list/useSingleSelectListState), Apache-2.0,
+// © Adobe.
+//
+// List state of ListBox, Select, ComboBox, Menu and Autocomplete: selection + focus (signals + JSON,
+// resumable) and the collection's static options. Items are not stored: on the server the data
+// items render the collection; in the browser handlers read it back from the DOM ("DOM as
+// collection"), so filtering / async items need no state change here.
+import { signal, untrack } from "@rivetjs/reactivity";
+import { createId } from "@rivetjs/cdk/id";
+import { createMultipleSelectionState, flatItems, isKeyDisabled, isKeySelected, readSelection, } from "../_adapters/collections.js";
+import { isFocusedKey } from "../selection/keyed.js";
+export { isSection, textOf, flatItems } from "../_adapters/collections.js";
+const entriesOf = (items) => typeof items === "function" ? untrack(items) : (items ?? []);
+/** react-stately `useListState`: multiple selection + focus over a collection. */
+export function createListState(props) {
+    const items = flatItems(entriesOf(props.items));
+    const disabledKeys = new Set(props.disabledKeys ?? []);
+    for (const item of items)
+        if (item.disabled)
+            disabledKeys.add(item.key);
+    const selectionProps = {
+        ...props,
+        selectionMode: props.selectionMode ?? "single",
+        disabledKeys,
+        ...(props.selected && !props.selectedKeys ? { selectedKeys: props.selected } : {}),
+        ...(props.defaultSelected && !props.defaultSelectedKeys ? { defaultSelectedKeys: props.defaultSelected } : {}),
+    };
+    const selection = createMultipleSelectionState(selectionProps);
+    return withList(selection, props, items, disabledKeys);
+}
+/** react-stately `useSingleSelectListState`: single selection, never empty by user action. */
+export function createSingleSelectListState(props) {
+    const items = flatItems(entriesOf(props.items));
+    const disabledKeys = new Set(props.disabledKeys ?? []);
+    for (const item of items)
+        if (item.disabled)
+            disabledKeys.add(item.key);
+    const { onSelectionChange: onChange, ...rest } = props;
+    const selectedKey = props.selectedKey ?? signal(props.defaultSelectedKey ?? null);
+    const selection = createMultipleSelectionState({
+        ...rest,
+        selectionMode: "single",
+        disallowEmptySelection: true,
+        allowDuplicateSelectionEvents: true,
+        disabledKeys,
+        selectedKey,
+        ...(onChange ? { onSelectionChange: (keys) => onChange(keys === "all" ? null : (keys.values().next().value ?? null)) } : {}),
+    });
+    return withList(selection, props, items, disabledKeys);
+}
+function withList(selection, props, items, disabledKeys) {
+    const options = {};
+    const source = props;
+    for (const name of OPTION_NAMES)
+        if (source[name] !== undefined)
+            options[name] = source[name];
+    if (props.followFocus && options.selectOnFocus === undefined)
+        options.selectOnFocus = true;
+    // Initial tab stop (roving tabindex in the server HTML): first selected enabled item, else first enabled.
+    if (props.focusedKey !== undefined)
+        selection.focusedKey.set(props.focusedKey);
+    else if (!options.shouldUseVirtualFocus) {
+        const chosen = untrack(() => readSelection(selection));
+        // One pass, no copy of the item list: the first enabled chosen item ends it, else the first enabled one stays.
+        let first;
+        for (const item of items) {
+            if (disabledKeys.has(item.key))
+                continue;
+            if (chosen === "all" || chosen.has(item.key)) {
+                first = item;
+                break;
+            }
+            first ??= item;
+        }
+        if (first)
+            selection.focusedKey.set(first.key);
+    }
+    return {
+        ...selection,
+        id: props.id ?? createId(),
+        options,
+        ...(props.onAction ? { onAction: props.onAction } : {}),
+    };
+}
+const OPTION_NAMES = [
+    "shouldFocusWrap",
+    "disallowEmptySelection",
+    "disallowSelectAll",
+    "escapeKeyBehavior",
+    "selectOnFocus",
+    "disallowTypeAhead",
+    "shouldUseVirtualFocus",
+    "allowsTabNavigation",
+    "linkBehavior",
+    "orientation",
+    "layout",
+    "shouldSelectOnPressUp",
+    "allowsDifferentPressOrigin",
+    "shouldFocusOnHover",
+];
+// ---------------------------------------------------------------------------------------------
+// Render accessors (server + bindings). They read signals: call them inside attribute bindings.
+// ---------------------------------------------------------------------------------------------
+/** react-aria `getItemId`: `<list id>-option-<key without whitespace>`. */
+export const getItemId = (state, key) => `${state.id}-option-${typeof key === "string" ? key.replace(/\s*/g, "") : String(key)}`;
+/** `aria-selected` of an option: absent with selection mode "none". */
+export const itemSelected = (state, key, disabled = false) => state.selectionMode === "none" ? undefined : isKeySelected(state, key, disabled);
+/** Whether the item is disabled for every interaction (`aria-disabled`, `data-disabled`). */
+export const itemDisabled = (state, key, disabled = false) => isKeyDisabled(state, key, disabled);
+/** Roving `tabindex` of an item (none with virtual focus or when disabled). */
+export const itemTabIndex = (state, key, disabled = false) => state.options.shouldUseVirtualFocus || isKeyDisabled(state, key, disabled) ? undefined : isFocusedKey(state, key) ? 0 : -1;
+/** `data-focused` of an item: the collection is focused and this is its focused key (keyed read first: only the
+ * focused item re-runs when the collection's focus changes). */
+export const itemFocused = (state, key) => isFocusedKey(state, key) && state.isFocused();
+/** `tabindex` of the collection element: tabbable while no item is the focus target. */
+export const collectionTabIndex = (state) => state.options.shouldUseVirtualFocus ? undefined : state.focusedKey() == null ? 0 : -1;
+/** RAC `linkBehavior` default of a ListBox: "action" with `selectionBehavior="replace"`, else "override". */
+export function listBoxLinkBehavior(selectionBehavior = "toggle", linkBehavior) {
+    let behavior = linkBehavior || (selectionBehavior === "replace" ? "action" : "override");
+    // "action" cannot work with "toggle" (no way to start selecting): links are not selectable then.
+    if (selectionBehavior === "toggle" && behavior === "action")
+        behavior = "override";
+    return behavior;
+}

package/state/menu.d.ts

@@ -0,0 +1,162 @@
+import { type Signal } from "@rivetjs/reactivity";
+import { type FocusStrategy, type MultipleSelectionState } from "../_adapters/collections.js";
+import type { PressEvent } from "../interactions/press.jsx";
+import type { HoverEvent } from "../interactions/hover.jsx";
+import type { VirtualCollection } from "../_adapters/selection.js";
+import { type OverlayTriggerProps, type OverlayTriggerState } from "./overlays.js";
+import { type Key, type ListProps, type ListState, type Selection, type SelectionMode } from "./list.js";
+export type { Key, Selection, SelectionMode, FocusStrategy };
+/** RAC `MenuTriggerType`. */
+export type MenuTriggerType = "press" | "longPress" | "contextMenu";
+/** Per-item callbacks / options of a rendered MenuItem (RAC `MenuItem` props), registered at render by key. */
+export interface MenuItemCallbacks {
+    /** Item action (RAC `MenuItem onAction`), called before the menu's `onAction`. */
+    onAction?: () => void;
+    /** Overrides the section's / menu's `shouldCloseOnSelect`. */
+    shouldCloseOnSelect?: boolean;
+    /** Router options of a link item (`routerOptions`). */
+    routerOptions?: Record<string, unknown>;
+    onPressStart?: (e: PressEvent) => void;
+    onPressEnd?: (e: PressEvent) => void;
+    onPressUp?: (e: PressEvent) => void;
+    onPress?: (e: PressEvent) => void;
+    onPressChange?: (isPressed: boolean) => void;
+    onHoverStart?: (e: HoverEvent) => void;
+    onHoverEnd?: (e: HoverEvent) => void;
+    onHoverChange?: (isHovering: boolean) => void;
+    onFocus?: (e: FocusEvent) => void;
+    onBlur?: (e: FocusEvent) => void;
+    onFocusChange?: (isFocused: boolean) => void;
+    /** Interaction-state signals of the item, when its render props are functions (the menu's handler writes them with the `data-*` attributes). */
+    states?: MenuItemStateSignals;
+}
+/** RAC MenuItem render-prop states written from the delegated handler (`data-hovered` / `data-pressed` / `data-focus-visible`). */
+export interface MenuItemStateSignals {
+    hovered: Signal<boolean>;
+    pressed: Signal<boolean>;
+    focusVisible: Signal<boolean>;
+}
+/** Options of a rendered MenuSection, by section key. */
+export interface MenuSectionOptions {
+    shouldCloseOnSelect?: boolean;
+}
+export interface MenuTriggerStateProps extends OverlayTriggerProps {
+    /** RAC `trigger`: "press" (default), "longPress" or "contextMenu". */
+    trigger?: MenuTriggerType;
+}
+/** react-stately `RootMenuTriggerState` (methods: `openMenu`, `toggleMenu`, `closeMenu`, `openSubmenuKey`, `closeSubmenuKey`). */
+export interface MenuTriggerState extends OverlayTriggerState {
+    /** Trigger element id. */
+    readonly triggerId: string;
+    /** Root menu element id. */
+    readonly menuId: string;
+    readonly trigger: MenuTriggerType;
+    /** Where focus goes when the menu opens (RAC `focusStrategy`; null: the menu / its selection). */
+    readonly focusStrategy: Signal<FocusStrategy | null>;
+    /** Trigger keys of the open submenus, by level (RAC `expandedKeysStack`). */
+    readonly expandedKeysStack: Signal<readonly Key[]>;
+}
+/** react-stately `useMenuTriggerState`. */
+export declare function createMenuTriggerState(props?: MenuTriggerStateProps & {
+    id?: string;
+}): MenuTriggerState;
+/** `open(focusStrategy = null)`. */
+export declare function openMenu(state: MenuTriggerState, focusStrategy?: FocusStrategy | null): void;
+/** `toggle(focusStrategy = null)`. */
+export declare function toggleMenu(state: MenuTriggerState, focusStrategy?: FocusStrategy | null): void;
+/** `close()` = `closeAll`: closes every submenu and the menu. */
+export declare function closeMenu(state: MenuTriggerState): void;
+/** `openSubmenu(triggerKey, level)`: the stack keeps levels below `level`, then this key. */
+export declare function openSubmenuKey(state: MenuTriggerState, triggerKey: Key, level: number): void;
+/** `closeSubmenu(triggerKey, level)`: closes this level (and the ones above) when it is open. */
+export declare function closeSubmenuKey(state: MenuTriggerState, triggerKey: Key, level: number): void;
+/** Whether the submenu of `triggerKey` at `level` is open (binding accessor). */
+export declare const isSubmenuOpen: (state: MenuTriggerState, triggerKey: Key, level: number) => boolean;
+/** react-stately `SubmenuTriggerState` (methods: `openSubmenu`, `closeSubmenu`, `toggleSubmenu`, `closeAllSubmenus`). */
+export interface SubmenuTriggerState {
+    readonly root: MenuTriggerState;
+    /** The trigger item's key (Rivet: set by the trigger MenuItem when it renders, `bindSubmenuTrigger`). */
+    triggerKey: Key;
+    /** The level of the submenu (the stack length when the trigger was created). */
+    readonly submenuLevel: number;
+    /** Whether the submenu is open (accessor). */
+    readonly isOpen: () => boolean;
+    readonly focusStrategy: Signal<FocusStrategy | null>;
+}
+/** react-stately `useSubmenuTriggerState({ triggerKey }, rootState)`; `level` defaults to the current stack length. */
+export declare function createSubmenuTriggerState(props: {
+    triggerKey: Key;
+}, root: MenuTriggerState, level?: number): SubmenuTriggerState;
+/** Rivet: the trigger item of a SubmenuTrigger renders with its own key: bind it (before anything opens). */
+export declare function bindSubmenuTrigger(state: SubmenuTriggerState, triggerKey: Key): void;
+/** Submenu `open(focusStrategy)`. */
+export declare function openSubmenu(state: SubmenuTriggerState, focusStrategy?: FocusStrategy | null): void;
+/** Submenu `close()`. */
+export declare function closeSubmenu(state: SubmenuTriggerState): void;
+/** Submenu `toggle(focusStrategy)`. */
+export declare function toggleSubmenu(state: SubmenuTriggerState, focusStrategy?: FocusStrategy | null): void;
+/** Submenu `closeAll()`: the root `close`. */
+export declare const closeAllSubmenus: (state: SubmenuTriggerState) => void;
+export interface MenuState extends ListState {
+    /** 0: root menu; n: submenu depth. */
+    readonly level: number;
+    /** The root trigger state (a standalone menu creates its own). */
+    readonly root: MenuTriggerState;
+    /** Submenu: its trigger's state and the parent menu's id. */
+    readonly submenuTrigger?: SubmenuTriggerState | undefined;
+    readonly parentId?: string | undefined;
+    /** RAC `Menu onAction(key)` (useMenu `menuData.onAction`). */
+    readonly menuAction?: ((key: Key) => void) | undefined;
+    /** RAC `Menu onClose` (default: the trigger's close). */
+    readonly onClose?: (() => void) | undefined;
+    readonly shouldCloseOnSelect?: boolean | undefined;
+    /** Item callbacks / options, by key (registered by MenuItem at render). */
+    readonly items: Record<string, MenuItemCallbacks>;
+    /** Section options, by section key (registered by MenuSection). */
+    readonly sections: Record<string, MenuSectionOptions>;
+    /** Submenu trigger states of this menu's SubmenuTrigger items, by trigger key. */
+    readonly submenus: Record<string, SubmenuTriggerState>;
+    /** Hover-open delays of submenu trigger items, by key (ms). */
+    readonly delays: Record<string, number>;
+    /** Rivet: number of rendered items (live collection: RAC `collection.size` for `isEmpty`). */
+    readonly itemCount: Signal<number>;
+}
+export interface MenuProps extends Omit<ListProps, "items" | "selectionBehavior" | "shouldSelectOnPressUp" | "allowsDifferentPressOrigin" | "linkBehavior" | "followFocus" | "selected" | "defaultSelected" | "onAction" | "selectedKeys"> {
+    /** The currently selected keys (a Signal: two-way; a plain value: the initial selection, changes reported to `onSelectionChange`). */
+    selectedKeys?: Signal<Selection> | "all" | Iterable<Key>;
+    onAction?: (key: Key) => void;
+    onClose?: () => void;
+    shouldCloseOnSelect?: boolean;
+}
+/** react-stately `useTreeState` for a menu + RAC menu context (`menuData`: action, close; section selection). */
+export declare function createMenuState(props: MenuProps, context?: {
+    root?: MenuTriggerState;
+    level?: number;
+    submenuTrigger?: SubmenuTriggerState;
+    parentId?: string;
+    id?: string;
+    /** Rivet: a Menu inside a `CollectionVirtualizer` (its built collection + the layout delegate). */
+    virtual?: VirtualCollection;
+}): MenuState;
+/** Register a rendered MenuItem's callbacks / disabled flag (RAC: the collection node's props). */
+export declare function registerMenuItem(state: MenuState, key: Key, item: MenuItemCallbacks & {
+    isDisabled?: boolean;
+}): void;
+/** Register a MenuSection: its close rule and own selection (RAC `GroupSelectionManager`). */
+export declare function registerMenuSection(state: MenuState, key: Key, section: MenuSectionOptions & {
+    selectionMode?: SelectionMode;
+    selectedKeys?: Signal<Selection> | "all" | Iterable<Key>;
+    defaultSelectedKeys?: "all" | Iterable<Key>;
+    onSelectionChange?: (keys: Selection) => void;
+    disallowEmptySelection?: boolean;
+}): void;
+/** Register a SubmenuTrigger item of `state` (its trigger state + hover delay). */
+export declare function registerSubmenu(state: MenuState, key: Key, sub: SubmenuTriggerState, delay?: number): void;
+/** Id of the submenu of `key` in menu `parent` (its trigger item is `getItemId(parent, key)`). */
+export declare const submenuId: (parent: {
+    id: string;
+}, key: Key) => string;
+/** The selection state an item renders from: its section's own, else the menu's. */
+export declare function selectionOf(state: MenuState, sectionKey: Key | undefined): MultipleSelectionState & {
+    selectionMode: SelectionMode;
+};

package/state/menu.js

@@ -0,0 +1,185 @@
+// Ported from react-spectrum (react-stately: menu/useMenuTriggerState, menu/useSubmenuTriggerState,
+// tree/useTreeState for menus; react-aria-components Menu.tsx MenuSection selection), Apache-2.0, © Adobe.
+//
+// Menu state: the trigger's overlay state (open, focus strategy, the stack of open submenus), one
+// submenu trigger state per SubmenuTrigger, and one list state per menu (root and each submenu):
+// selection, focus, actions. Signals + JSON only.
+// Rivet:
+// - methods are free functions (`openMenu`, `toggleMenu`, `closeMenu`, `openSubmenuKey`, `openSubmenu`, …).
+// - the menu's collection is the rendered DOM (items need no serialized model): MenuItem / MenuSection /
+//   SubmenuTrigger register their callbacks, disabled flags, section selection and submenu states into
+//   the menu state at render (`registerMenuItem`, `registerMenuSection`, `registerSubmenu`).
+import { computed, signal, untrack, _regionState } from "@rivetjs/reactivity";
+import { createId } from "@rivetjs/cdk/id";
+import { createMultipleSelectionState } from "../_adapters/collections.js";
+import { closeOverlay, createOverlayTriggerState, openOverlay, toggleOverlay } from "./overlays.js";
+import { createListState, getItemId } from "./list.js";
+/** react-stately `useMenuTriggerState`. */
+export function createMenuTriggerState(props = {}) {
+    // Region state: a resumed page re-creating the menu's region (its first open) keeps it.
+    return _regionState(() => {
+        const menuId = props.id ?? createId();
+        return {
+            ...createOverlayTriggerState(props),
+            triggerId: menuId + "-trigger",
+            menuId,
+            trigger: props.trigger ?? "press",
+            focusStrategy: signal(null),
+            expandedKeysStack: signal([]),
+        };
+    });
+}
+/** `open(focusStrategy = null)`. */
+export function openMenu(state, focusStrategy = null) {
+    state.focusStrategy.set(focusStrategy);
+    openOverlay(state);
+}
+/** `toggle(focusStrategy = null)`. */
+export function toggleMenu(state, focusStrategy = null) {
+    state.focusStrategy.set(focusStrategy);
+    toggleOverlay(state);
+}
+/** `close()` = `closeAll`: closes every submenu and the menu. */
+export function closeMenu(state) {
+    state.expandedKeysStack.set([]);
+    closeOverlay(state);
+}
+/** `openSubmenu(triggerKey, level)`: the stack keeps levels below `level`, then this key. */
+export function openSubmenuKey(state, triggerKey, level) {
+    const stack = untrack(state.expandedKeysStack);
+    if (level > stack.length)
+        return;
+    state.expandedKeysStack.set([...stack.slice(0, level), triggerKey]);
+}
+/** `closeSubmenu(triggerKey, level)`: closes this level (and the ones above) when it is open. */
+export function closeSubmenuKey(state, triggerKey, level) {
+    const stack = untrack(state.expandedKeysStack);
+    if (stack[level] === triggerKey)
+        state.expandedKeysStack.set(stack.slice(0, level));
+}
+/** Whether the submenu of `triggerKey` at `level` is open (binding accessor). */
+export const isSubmenuOpen = (state, triggerKey, level) => state.expandedKeysStack()[level] === triggerKey;
+/** react-stately `useSubmenuTriggerState({ triggerKey }, rootState)`; `level` defaults to the current stack length. */
+export function createSubmenuTriggerState(props, root, level) {
+    return _regionState(() => {
+        const submenuLevel = level ?? untrack(root.expandedKeysStack).length;
+        const sub = {
+            root,
+            triggerKey: props.triggerKey,
+            submenuLevel,
+            // Reads `triggerKey` at evaluation: the trigger item may bind its own key after creation.
+            isOpen: computed(() => String(root.expandedKeysStack()[submenuLevel]) === String(sub.triggerKey)),
+            focusStrategy: signal(null),
+        };
+        return sub;
+    });
+}
+/** Rivet: the trigger item of a SubmenuTrigger renders with its own key: bind it (before anything opens). */
+export function bindSubmenuTrigger(state, triggerKey) {
+    state.triggerKey = triggerKey;
+}
+/** Submenu `open(focusStrategy)`. */
+export function openSubmenu(state, focusStrategy) {
+    state.focusStrategy.set(focusStrategy ?? null);
+    openSubmenuKey(state.root, state.triggerKey, state.submenuLevel);
+}
+/** Submenu `close()`. */
+export function closeSubmenu(state) {
+    state.focusStrategy.set(null);
+    closeSubmenuKey(state.root, state.triggerKey, state.submenuLevel);
+}
+/** Submenu `toggle(focusStrategy)`. */
+export function toggleSubmenu(state, focusStrategy) {
+    state.focusStrategy.set(focusStrategy ?? null);
+    if (untrack(state.isOpen))
+        closeSubmenu(state);
+    else
+        openSubmenu(state, focusStrategy);
+}
+/** Submenu `closeAll()`: the root `close`. */
+export const closeAllSubmenus = (state) => closeMenu(state.root);
+/** react-stately `useTreeState` for a menu + RAC menu context (`menuData`: action, close; section selection). */
+export function createMenuState(props, context = {}) {
+    // Region state: a resumed page re-creating the menu's region (its first open) keeps it.
+    return _regionState(() => {
+        const { onAction, selectedKeys, ...listProps } = props;
+        const list = createListState({
+            ...listProps,
+            ...(selectedKeys !== undefined ? { selectedKeys: toSelectionSignal(selectedKeys) } : {}),
+            ...(context.id ? { id: context.id } : {}),
+            selectionMode: props.selectionMode ?? "none",
+            // useMenu: wrap focus; useMenuItem: select on press up, from a press that started elsewhere (the
+            // trigger); links are handled by the menu item (linkBehavior "none").
+            shouldFocusWrap: props.shouldFocusWrap ?? true,
+            linkBehavior: "none",
+            shouldSelectOnPressUp: true,
+            allowsDifferentPressOrigin: true,
+            // Menus open with focus on the menu (or the strategy's item): no server tab stop.
+            focusedKey: props.focusedKey ?? null,
+        });
+        return {
+            ...list,
+            level: context.level ?? 0,
+            root: context.root ?? createMenuTriggerState({ id: list.id }),
+            submenuTrigger: context.submenuTrigger,
+            parentId: context.parentId,
+            menuAction: onAction,
+            onClose: props.onClose,
+            shouldCloseOnSelect: props.shouldCloseOnSelect,
+            items: {},
+            sections: {},
+            submenus: {},
+            delays: {},
+            groups: {},
+            itemCount: signal(0),
+            ...(context.virtual ? { virtual: context.virtual } : {}),
+        };
+    });
+}
+/** Register a rendered MenuItem's callbacks / disabled flag (RAC: the collection node's props). */
+export function registerMenuItem(state, key, item) {
+    const { isDisabled, ...callbacks } = item;
+    if (isDisabled)
+        state.disabledKeys.add(key);
+    let any = false;
+    for (const name in callbacks)
+        if (callbacks[name] !== undefined)
+            any = true;
+    if (any)
+        state.items[String(key)] = callbacks;
+}
+/** Register a MenuSection: its close rule and own selection (RAC `GroupSelectionManager`). */
+export function registerMenuSection(state, key, section) {
+    if (section.shouldCloseOnSelect !== undefined)
+        state.sections[String(key)] = { shouldCloseOnSelect: section.shouldCloseOnSelect };
+    if (section.selectionMode == null)
+        return;
+    state.groups[String(key)] = createMultipleSelectionState({
+        selectionMode: section.selectionMode,
+        ...(section.selectedKeys ? { selectedKeys: toSelectionSignal(section.selectedKeys) } : {}),
+        ...(section.defaultSelectedKeys ? { defaultSelectedKeys: section.defaultSelectedKeys } : {}),
+        ...(section.onSelectionChange ? { onSelectionChange: section.onSelectionChange } : {}),
+        ...(section.disallowEmptySelection !== undefined ? { disallowEmptySelection: section.disallowEmptySelection } : {}),
+        disabledKeys: state.disabledKeys,
+    });
+}
+/** Register a SubmenuTrigger item of `state` (its trigger state + hover delay). */
+export function registerSubmenu(state, key, sub, delay) {
+    state.submenus[String(key)] = sub;
+    if (delay !== undefined)
+        state.delays[String(key)] = delay;
+}
+const isSignal = (v) => typeof v === "function" && typeof v.set === "function";
+/** A controlled selection: a Signal as is; a plain value → a signal starting at it (Deviation: the adapter selection writes it). */
+function toSelectionSignal(keys) {
+    // A Signal (two-way) or a read-only accessor (live prop, `liveKeys`: controlled, never written) as is.
+    if (typeof keys === "function")
+        return keys;
+    return signal(keys === "all" ? "all" : new Set(keys));
+}
+/** Id of the submenu of `key` in menu `parent` (its trigger item is `getItemId(parent, key)`). */
+export const submenuId = (parent, key) => getItemId(parent, key) + "-menu";
+/** The selection state an item renders from: its section's own, else the menu's. */
+export function selectionOf(state, sectionKey) {
+    return (sectionKey !== undefined && state.groups?.[String(sectionKey)]) || state;
+}