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

package/collections/dom.js

@@ -0,0 +1,127 @@
+// DOM as collection: the server-rendered items are the collection. Builds a react-aria-components
+// style `BaseCollection` from elements carrying `data-key`, so selection managers and keyboard
+// delegates work on resumed pages without serializing an item model.
+//
+// Element → node mapping:
+//   key         `data-key` (+ `data-key-type="number"` for numeric keys, see `keyAttrs`)
+//   type        `data-type`, else by role: option / menuitem* / treeitem / tab / row / radio /
+//               checkbox / link / listitem → "item"; group → "section"; presentation heading
+//               (`role=presentation` / `heading` inside a group) → "header"; separator →
+//               "separator"; gridcell / cell / rowheader / columnheader → "cell"; else "item"
+//   textValue   `data-text-value`, `data-text`, `aria-label`, else trimmed textContent
+//   props       isDisabled (`aria-disabled="true"`, `disabled`, `data-disabled`, `data-rv-disabled`: the item's own
+//               `isDisabled` prop, kept while `disabledBehavior="selection"` leaves it focusable), href (`href` or
+//               `data-href`), target, rel, download, `data-*` passthrough is not attempted
+//   parent      nearest ancestor (inside `root`) that is itself a collection node
+//   hidden      `[hidden]` subtrees (not popovers) are left out, like RAC's hidden nodes
+import { BaseCollection, buildCollection } from "./base.js";
+import { cssEscape } from "../utils/dom.js";
+/** Attributes that encode `key` for `domKey` (numeric keys keep their type). */
+export function keyAttrs(key) {
+    return typeof key === "number" ? { "data-key": String(key), "data-key-type": "number" } : { "data-key": key };
+}
+/** The key an element encodes (`keyAttrs`), or null. */
+export function domKey(element) {
+    const raw = element.getAttribute("data-key");
+    if (raw == null)
+        return null;
+    return element.getAttribute("data-key-type") === "number" ? Number(raw) : raw;
+}
+const ROLE_TYPES = {
+    option: "item",
+    menuitem: "item",
+    menuitemcheckbox: "item",
+    menuitemradio: "item",
+    treeitem: "item",
+    tab: "item",
+    row: "item",
+    radio: "item",
+    checkbox: "item",
+    link: "item",
+    listitem: "item",
+    button: "item",
+    group: "section",
+    presentation: "header",
+    heading: "header",
+    separator: "separator",
+    gridcell: "cell",
+    cell: "cell",
+    rowheader: "cell",
+    columnheader: "column",
+};
+/** Node type of a collection element. */
+export function domNodeType(element) {
+    return element.getAttribute("data-type") ?? ROLE_TYPES[element.getAttribute("role") ?? ""] ?? "item";
+}
+/** Typeahead text of a collection element. */
+export function domTextValue(element) {
+    return (element.getAttribute("data-text-value") ?? element.getAttribute("data-text") ?? element.getAttribute("aria-label") ?? element.textContent?.trim() ?? "");
+}
+const isHidden = (element, root) => {
+    for (let el = element; el && el !== root; el = el.parentElement) {
+        if (el.hidden && !el.hasAttribute("popover"))
+            return true;
+    }
+    return false;
+};
+/**
+ * Build a frozen `BaseCollection` from the DOM under `root`. Cheap enough to run per handler call
+ * (one `querySelectorAll` + one pass); cache per event if a handler needs it repeatedly.
+ */
+export function domCollection(root, options = {}) {
+    const selector = options.selector ?? "[data-key]";
+    const collectionId = root.getAttribute("data-collection");
+    const scoped = options.scoped ?? collectionId != null;
+    const elements = [...root.querySelectorAll(selector)].filter((el) => !isHidden(el, root) && (!scoped || el.closest("[data-collection]") === root || el.getAttribute("data-collection") === collectionId));
+    const specs = new Map();
+    const top = [];
+    for (const el of elements) {
+        const key = domKey(el);
+        if (key == null)
+            continue;
+        const disabled = el.getAttribute("aria-disabled") === "true" ||
+            el.disabled === true ||
+            el.hasAttribute("data-disabled") ||
+            el.hasAttribute("data-rv-disabled");
+        const href = el.getAttribute("href") ?? el.getAttribute("data-href");
+        const props = {};
+        if (disabled)
+            props.isDisabled = true;
+        if (href != null) {
+            props.href = href;
+            for (const name of ["target", "rel", "download", "hreflang", "ping", "referrerpolicy"]) {
+                const v = el.getAttribute(name);
+                if (v != null)
+                    props[name === "hreflang" ? "hrefLang" : name === "referrerpolicy" ? "referrerPolicy" : name] = v;
+            }
+        }
+        const colSpan = el.getAttribute("aria-colspan") ?? el.getAttribute("colspan");
+        if (colSpan != null)
+            props.colSpan = Number(colSpan);
+        const spec = { type: domNodeType(el), id: key, textValue: domTextValue(el), props, children: [] };
+        specs.set(el, spec);
+        let parent = el.parentElement;
+        while (parent && parent !== root && !specs.has(parent))
+            parent = parent.parentElement;
+        if (parent && parent !== root)
+            specs.get(parent).children.push(spec);
+        else
+            top.push(spec);
+    }
+    return buildCollection(top);
+}
+/** Element of `key` inside the collection element (react-aria `getItemElement`). */
+export function getItemElement(collection, key) {
+    if (!collection)
+        return null;
+    let selector = `[data-key="${cssEscape(String(key))}"]`;
+    const id = collection.dataset?.collection;
+    if (id)
+        selector = `[data-collection="${cssEscape(id)}"]${selector}`;
+    return collection.querySelector(selector);
+}
+/** Node of `element` in `collection`, if any. */
+export function nodeOf(collection, element) {
+    const key = domKey(element);
+    return key == null ? null : collection.getItem(key);
+}

package/collections/grid.d.ts

@@ -0,0 +1,45 @@
+import type { Collection, Key, Node } from "./types.js";
+export interface IGridCollection<T> extends Collection<GridNode<T>> {
+    /** The number of columns in the grid. */
+    columnCount: number;
+    /** A list of rows in the grid. */
+    rows: GridNode<T>[];
+}
+export interface GridRow<T> extends Partial<GridNode<T>> {
+    key?: Key;
+    type: string;
+    childNodes: Iterable<Node<T>>;
+}
+export interface GridNode<T> extends Node<T> {
+    column?: GridNode<T> | undefined;
+    /** @deprecated Use `colSpan` instead. */
+    colspan?: number | undefined;
+    /** The number of columns spanned by this cell. */
+    colSpan?: number | null | undefined;
+    /** The column index of this cell, accounting for any colSpans. */
+    colIndex?: number | null | undefined;
+    /** The index of this node within its parent, ignoring sibling nodes that aren't of the same type. */
+    indexOfType?: number | undefined;
+}
+export interface GridCollectionOptions<T> {
+    columnCount: number;
+    items: GridRow<T>[];
+    visitNode?: (cell: GridNode<T>) => GridNode<T>;
+}
+/** Rows of cells with colSpan / colIndex bookkeeping. */
+export declare class GridCollection<T> implements IGridCollection<T> {
+    keyMap: Map<Key, GridNode<T>>;
+    columnCount: number;
+    rows: GridNode<T>[];
+    constructor(opts: GridCollectionOptions<T>);
+    [Symbol.iterator](): IterableIterator<GridNode<T>>;
+    get size(): number;
+    getKeys(): IterableIterator<Key>;
+    getKeyBefore(key: Key): Key | null;
+    getKeyAfter(key: Key): Key | null;
+    getFirstKey(): Key | null;
+    getLastKey(): Key | null;
+    getItem(key: Key): GridNode<T> | null;
+    at(idx: number): GridNode<T> | null;
+    getChildren(key: Key): Iterable<GridNode<T>>;
+}

package/collections/grid.js

@@ -0,0 +1,125 @@
+/** Rows of cells with colSpan / colIndex bookkeeping. */
+export class GridCollection {
+    keyMap = new Map();
+    columnCount;
+    rows;
+    constructor(opts) {
+        this.keyMap = new Map();
+        this.columnCount = opts?.columnCount;
+        this.rows = [];
+        const visit = (node) => {
+            // If the node is the same object as the previous node for the same key, we can skip this node
+            // and its children. We always visit columns though, because we depend on order to build the
+            // columns array.
+            const prevNode = this.keyMap.get(node.key);
+            if (opts.visitNode)
+                node = opts.visitNode(node);
+            this.keyMap.set(node.key, node);
+            const childKeys = new Set();
+            let last = null;
+            let rowHasCellWithColSpan = false;
+            if (node.type === "item") {
+                for (const child of node.childNodes) {
+                    if (child.props?.colSpan !== undefined) {
+                        rowHasCellWithColSpan = true;
+                        break;
+                    }
+                }
+            }
+            for (const child of node.childNodes) {
+                if (child.type === "cell" && rowHasCellWithColSpan) {
+                    child.colspan = child.props?.colSpan;
+                    child.colSpan = child.props?.colSpan;
+                    child.colIndex = !last ? child.index : (last.colIndex ?? last.index) + (last.colSpan ?? 1);
+                }
+                // If child is a cell and its parent key isn't already established by the collection, match
+                // child node to parent row.
+                if (child.type === "cell" && child.parentKey == null)
+                    child.parentKey = node.key;
+                childKeys.add(child.key);
+                if (last) {
+                    last.nextKey = child.key;
+                    child.prevKey = last.key;
+                }
+                else
+                    child.prevKey = null;
+                visit(child);
+                last = child;
+            }
+            if (last)
+                last.nextKey = null;
+            // Remove deleted nodes and their children from the key map.
+            if (prevNode)
+                for (const child of prevNode.childNodes)
+                    if (!childKeys.has(child.key))
+                        remove(child);
+        };
+        const remove = (node) => {
+            this.keyMap.delete(node.key);
+            for (const child of node.childNodes)
+                if (this.keyMap.get(child.key) === child)
+                    remove(child);
+        };
+        let last = null;
+        for (const [i, node] of opts.items.entries()) {
+            const rowNode = {
+                ...node,
+                level: node.level ?? 0,
+                key: node.key ?? "row-" + i,
+                type: node.type ?? "row",
+                value: node.value ?? null,
+                hasChildNodes: true,
+                childNodes: [...node.childNodes],
+                rendered: node.rendered,
+                textValue: node.textValue ?? "",
+                index: node.index ?? i,
+            };
+            if (last) {
+                last.nextKey = rowNode.key;
+                rowNode.prevKey = last.key;
+            }
+            else
+                rowNode.prevKey = null;
+            this.rows.push(rowNode);
+            visit(rowNode);
+            last = rowNode;
+        }
+        if (last)
+            last.nextKey = null;
+    }
+    *[Symbol.iterator]() {
+        yield* [...this.rows];
+    }
+    get size() {
+        return [...this.rows].length;
+    }
+    getKeys() {
+        return this.keyMap.keys();
+    }
+    getKeyBefore(key) {
+        const node = this.keyMap.get(key);
+        return node ? (node.prevKey ?? null) : null;
+    }
+    getKeyAfter(key) {
+        const node = this.keyMap.get(key);
+        return node ? (node.nextKey ?? null) : null;
+    }
+    getFirstKey() {
+        return [...this.rows][0]?.key ?? null;
+    }
+    getLastKey() {
+        const rows = [...this.rows];
+        return rows[rows.length - 1]?.key ?? null;
+    }
+    getItem(key) {
+        return this.keyMap.get(key) ?? null;
+    }
+    at(idx) {
+        const keys = [...this.getKeys()];
+        return this.getItem(keys[idx]);
+    }
+    getChildren(key) {
+        const node = this.keyMap.get(key);
+        return node?.childNodes || [];
+    }
+}

package/collections/hidden.d.ts

@@ -0,0 +1,4 @@
+/** RAC `HiddenContext`: true while content renders in build mode (the hidden collection tree). */
+export declare const HiddenContext: import("@rivetjs/reactivity").Context<boolean>;
+/** RAC `useIsHidden` for hideable parts (`createHideableComponent`): render nothing while true. */
+export declare function isHiddenPart(): boolean;

package/collections/hidden.js

@@ -0,0 +1,12 @@
+// Ported from react-aria-components Hidden.tsx (`HiddenContext`, `useIsHidden`), Apache-2.0, © Adobe.
+// Rivet: split from `components.tsx` so hideable parts (Text, Label, Input, TextArea, Keyboard) can ask
+// whether they render in the collection build pass without importing the collection builder (zero-cost).
+// `components.tsx` provides `HiddenContext` (true) around every build pass. The server field slot probe flag
+// (`slotProbing`) lives in `./server-on.tsx` (cdk `#server` import: the constant `false` in browsers).
+import { createContext, useContext } from "@rivetjs/reactivity";
+/** RAC `HiddenContext`: true while content renders in build mode (the hidden collection tree). */
+export const HiddenContext = createContext(false);
+/** RAC `useIsHidden` for hideable parts (`createHideableComponent`): render nothing while true. */
+export function isHiddenPart() {
+    return useContext(HiddenContext);
+}

package/collections/index.d.ts

@@ -0,0 +1,45 @@
+import { type Signal } from "@rivetjs/reactivity";
+import type { Key, SelectionMode } from "./types.js";
+/** Item key (`./types.ts`): serializable, rendered as `data-key`. */
+export type { Key, SelectionMode };
+/** Items of a DOM collection: elements matching `selector` inside `root`, in DOM order, skipping hidden ones. */
+export declare function domItems(root: Element, selector: string): HTMLElement[];
+/** `data-key` of `element` (string; compare state keys with `sameKey`). */
+export declare const keyOf: (element: Element) => string | null;
+/** Keys compare as strings: `data-key` attributes are strings, state keys may be numbers. */
+export declare const sameKey: (a: Key | null | undefined, b: Key | null | undefined) => boolean;
+/** Whether a DOM item is disabled (`aria-disabled="true"` or a disabled control). */
+export declare const isDisabledItem: (element: Element) => boolean;
+/** Text used for typeahead: `data-text`, else trimmed text content. */
+export declare const itemText: (element: Element) => string;
+/** Escape a key into an id fragment (`<listId>-<key>`): word characters kept, others `_<hex>`. */
+export declare const keyId: (base: string, key: Key) => string;
+export interface Selection {
+    readonly selected: Signal<Set<Key>>;
+    readonly mode: SelectionMode;
+    /** Range anchor for Shift+click / Shift+Arrow (multiple). */
+    readonly anchor: Signal<Key | null>;
+    /** Single mode: whether selecting the selected key again clears it (default false). */
+    readonly toggleSingle: boolean;
+}
+/** Selection state: `selected` (two-way) or `defaultSelected` (internal signal). */
+export declare function createSelection(options?: {
+    mode?: SelectionMode;
+    selected?: Signal<Set<Key>>;
+    defaultSelected?: Iterable<Key>;
+    toggleSingle?: boolean;
+}): Selection;
+/** Whether `key` is selected (reads the signal: use inside bindings). */
+export declare function isSelected(selection: Selection, key: Key): boolean;
+/** First selected key (single mode value), or null. */
+export declare function firstSelected(selection: Selection): Key | null;
+/** Replace the selection with `key` (single) or toggle `key` (multiple). Mode "none": no-op. */
+export declare function selectKey(selection: Selection, key: Key): void;
+/** Toggle `key` (multiple; single behaves like `selectKey` with toggling). */
+export declare function toggleKey(selection: Selection, key: Key): void;
+/** Select the range from the anchor (or `key`) to `key` among `keys` (collection order); multiple only. */
+export declare function extendTo(selection: Selection, keys: readonly Key[], key: Key): void;
+/** Select every key in `keys` (multiple only). */
+export declare function selectAll(selection: Selection, keys: readonly Key[]): void;
+/** Clear the selection. */
+export declare function clearSelection(selection: Selection): void;

package/collections/index.js

@@ -0,0 +1,105 @@
+// Collections and selection. DOM as collection (default): the server-rendered items are the
+// collection — handlers query `[role=option]` (etc.) and read `data-key`; no item model is serialized.
+// Selection is plain serializable state: a `Signal<Set<Key>>` plus mode strings.
+import { signal, untrack } from "@rivetjs/reactivity";
+/** Items of a DOM collection: elements matching `selector` inside `root`, in DOM order, skipping hidden ones. */
+export function domItems(root, selector) {
+    return [...root.querySelectorAll(selector)].filter((el) => !el.hidden && !el.closest("[hidden]:not([popover])"));
+}
+/** `data-key` of `element` (string; compare state keys with `sameKey`). */
+export const keyOf = (element) => element.getAttribute("data-key");
+/** Keys compare as strings: `data-key` attributes are strings, state keys may be numbers. */
+export const sameKey = (a, b) => a != null && b != null && String(a) === String(b);
+/** Whether a DOM item is disabled (`aria-disabled="true"` or a disabled control). */
+export const isDisabledItem = (element) => element.getAttribute("aria-disabled") === "true" || element.disabled === true;
+/** Text used for typeahead: `data-text`, else trimmed text content. */
+export const itemText = (element) => element.getAttribute("data-text") ?? element.textContent?.trim() ?? "";
+/** Escape a key into an id fragment (`<listId>-<key>`): word characters kept, others `_<hex>`. */
+export const keyId = (base, key) => base + "-" + String(key).replace(/[^\w-]/g, (c) => "_" + c.charCodeAt(0).toString(16));
+/** Selection state: `selected` (two-way) or `defaultSelected` (internal signal). */
+export function createSelection(options = {}) {
+    return {
+        selected: options.selected ?? signal(new Set(options.defaultSelected ?? [])),
+        mode: options.mode ?? "single",
+        anchor: signal(null),
+        toggleSingle: options.toggleSingle ?? false,
+    };
+}
+/** Whether `key` is selected (reads the signal: use inside bindings). */
+export function isSelected(selection, key) {
+    return holds(selection.selected(), key);
+}
+/**
+ * `sameKey` membership without a `String()` per element: `has` answers same-type keys (String is injective on strings
+ * and numbers, `has` covers `0` / `-0` and `NaN`), so the loop only compares keys of the other type (`1` vs `"1"`).
+ */
+function holds(set, key) {
+    if (key == null)
+        return false;
+    if (set.has(key))
+        return true;
+    for (const k of set)
+        if (typeof k !== typeof key && sameKey(k, key))
+            return true;
+    return false;
+}
+/** First selected key (single mode value), or null. */
+export function firstSelected(selection) {
+    for (const key of selection.selected())
+        return key;
+    return null;
+}
+function without(set, key) {
+    const out = new Set();
+    for (const k of set)
+        if (!sameKey(k, key))
+            out.add(k);
+    return out;
+}
+/** Replace the selection with `key` (single) or toggle `key` (multiple). Mode "none": no-op. */
+export function selectKey(selection, key) {
+    if (selection.mode === "none")
+        return;
+    const current = untrack(selection.selected);
+    if (selection.mode === "single") {
+        const on = holds(current, key);
+        if (on && !selection.toggleSingle)
+            return;
+        selection.selected.set(on ? new Set() : new Set([key]));
+    }
+    else
+        toggleKey(selection, key);
+    selection.anchor.set(key);
+}
+/** Toggle `key` (multiple; single behaves like `selectKey` with toggling). */
+export function toggleKey(selection, key) {
+    if (selection.mode === "none")
+        return;
+    const current = untrack(selection.selected);
+    const on = holds(current, key);
+    if (selection.mode === "single")
+        selection.selected.set(on ? new Set() : new Set([key]));
+    else
+        selection.selected.set(on ? without(current, key) : new Set(current).add(key));
+    selection.anchor.set(key);
+}
+/** Select the range from the anchor (or `key`) to `key` among `keys` (collection order); multiple only. */
+export function extendTo(selection, keys, key) {
+    if (selection.mode !== "multiple")
+        return selectKey(selection, key);
+    const anchor = untrack(selection.anchor) ?? key;
+    const a = keys.findIndex((k) => sameKey(k, anchor)), b = keys.findIndex((k) => sameKey(k, key));
+    if (a < 0 || b < 0)
+        return selectKey(selection, key);
+    const [from, to] = a < b ? [a, b] : [b, a];
+    selection.selected.set(new Set([...untrack(selection.selected), ...keys.slice(from, to + 1)]));
+}
+/** Select every key in `keys` (multiple only). */
+export function selectAll(selection, keys) {
+    if (selection.mode === "multiple")
+        selection.selected.set(new Set(keys));
+}
+/** Clear the selection. */
+export function clearSelection(selection) {
+    selection.selected.set(new Set());
+}

package/collections/list-state.d.ts

@@ -0,0 +1,99 @@
+import { type Signal } from "@rivetjs/reactivity";
+import type { Collection, CollectionChildren, CollectionElement, Key, LayoutDelegate, Node } from "@rivetjs/cdk/collections/types";
+import { SelectionManager } from "@rivetjs/cdk/selection/manager";
+import { type MultipleSelectionState, type MultipleSelectionStateProps } from "@rivetjs/cdk/selection/state";
+export type { Key, SelectionMode } from "@rivetjs/cdk/collections/types";
+/** An item of a data-driven collection (Rivet shorthand: rendered with a default `Item`). */
+export interface Item {
+    readonly key: Key;
+    /** Visible label (default render) and typeahead / filter text. */
+    readonly label: string;
+    readonly disabled?: boolean;
+    /** Link items (Menu): rendered as `<a href>`. */
+    readonly href?: string;
+    /** Secondary text (rendered as the description slot). */
+    readonly description?: string;
+}
+export interface ListProps<T> extends MultipleSelectionStateProps {
+    /** Item objects (array or accessor of one). */
+    items?: readonly T[] | (() => readonly T[]) | undefined;
+    /**
+     * Collection elements, or a renderer `(item) => Item({...})` for `items`. Default: items render
+     * as `Item({ key: item.key ?? item.id, textValue: item.textValue ?? item.label ?? item.name,
+     * children: item.label ?? item.name, isDisabled: item.isDisabled ?? item.disabled, href })`.
+     */
+    children?: CollectionChildren<NoInfer<T>> | ((...args: any[]) => unknown) | undefined;
+    /**
+     * A pre-constructed collection (RAC hosts: `collectionOf(content)` accessor, BaseCollection, …).
+     * Without `collection` / `items` / `children` the collection is read from the DOM of the host
+     * element (live RAC parts, `listCollection(state, root)`).
+     */
+    collection?: Collection<Node<T>> | (() => Collection<Node<T>>) | undefined;
+    /** Filter function to generate a filtered list of nodes. */
+    filter?: ((nodes: Iterable<Node<T>>) => Iterable<Node<T>>) | undefined;
+    /** @private */
+    suppressTextValueWarning?: boolean | undefined;
+    /** A delegate object that provides layout information (overrides shift selection ranges). */
+    layoutDelegate?: LayoutDelegate | undefined;
+    /** Rivet: id of the collection element (`data-collection`); option ids are `<id>-option-<key>`. */
+    id?: string | undefined;
+}
+export interface ListState<T = any> {
+    /** Id of the collection element. */
+    readonly id: string;
+    /** Selection + focus state (serializable). */
+    readonly selectionState: MultipleSelectionState;
+    /** A set of items that are disabled. */
+    readonly disabledKeys: Set<Key>;
+    /** Builder inputs (kept so handlers can rebuild the collection after resume). */
+    readonly items: readonly T[] | (() => readonly T[]) | undefined;
+    readonly children: CollectionChildren<T> | undefined;
+    readonly collection: Collection<Node<T>> | (() => Collection<Node<T>>) | undefined;
+    readonly filter: ((nodes: Iterable<Node<T>>) => Iterable<Node<T>>) | undefined;
+    readonly suppressTextValueWarning: boolean;
+    readonly layoutDelegate: LayoutDelegate | undefined;
+}
+/** Default renderer for `items` without `children`: `{ key | id, label | name | textValue, … }` objects. */
+export declare function defaultItemRenderer(item: any): CollectionElement;
+/**
+ * Provides state management for list-like components (react-stately `useListState`): builds the
+ * collection inputs, and manages multiple selection + focus state.
+ */
+export declare function createListState<T = Item>(options: ListProps<T>): ListState<T>;
+/**
+ * The collection of a list state (react-stately `state.collection`). Rebuilt when the items array
+ * changes; reads `items` when it is an accessor (tracked in bindings).
+ */
+export declare function listCollection<T>(state: ListState<T>, root?: Element | null): Collection<Node<T>>;
+/** The selection manager of a list state (react-stately `state.selectionManager`). */
+export declare function listSelectionManager<T>(state: ListState<T>, collection?: Collection<Node<T>>): SelectionManager;
+/**
+ * Reset the focused key when its item left the collection (react-stately `useFocusedKeyReset`):
+ * walk forward in the previous collection to the next key still present and enabled, else
+ * backward. Call from an effect when the items change.
+ */
+export declare function resetFocusedKey<T>(state: ListState<T>, previous: Collection<Node<T>>, collection?: Collection<Node<T>>): void;
+/** Filters a list state's collection (react-stately `UNSTABLE_useFilteredListState`). */
+export declare function filteredListCollection<T>(state: ListState<T>, filterFn: ((nodeValue: string, node: Node<T>) => boolean) | null | undefined): Collection<Node<T>>;
+export interface SingleSelectListProps<T> extends Omit<ListProps<T>, "selectionMode" | "selectedKeys" | "defaultSelectedKeys" | "onSelectionChange" | "disallowEmptySelection" | "selectedKey" | "selectedKeyControlled" | "onSelectedKeyChange"> {
+    /** The selected key: a signal (two-way) or a plain value (controlled). */
+    selectedKey?: Signal<Key | null> | Key | null | undefined;
+    /** The initial selected key (uncontrolled). */
+    defaultSelectedKey?: Key | null | undefined;
+    /** Handler that is called when the selection changes (always, even for the same key). */
+    onSelectionChange?: ((key: Key | null) => void) | undefined;
+}
+export interface SingleSelectListState<T = any> extends ListState<T> {
+    /** The key for the currently selected item. */
+    readonly selectedKey: Signal<Key | null>;
+}
+/**
+ * Provides state management for list-like components with single selection (react-stately
+ * `useSingleSelectListState`): the selection is backed by `selectedKey`; disallowEmptySelection,
+ * and onSelectionChange fires even when the same key is chosen again.
+ */
+export declare function createSingleSelectListState<T = Item>(options: SingleSelectListProps<T>): SingleSelectListState<T>;
+/** The selected item node (react-stately `state.selectedItem`). Reads the selection. */
+export declare function selectedItem<T>(state: SingleSelectListState<T>, collection?: Collection<Node<T>>): Node<T> | null;
+/** Sets the selected key (react-stately `state.setSelectedKey`). */
+export declare function setSelectedKey<T>(state: SingleSelectListState<T>, key: Key | null): void;