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

package/_adapters/collections.d.ts

@@ -0,0 +1,325 @@
+import { type Signal } from "@rivetjs/reactivity";
+import type { Direction, DisabledBehavior, FocusStrategy, Key, Orientation, Selection, SelectionBehavior, SelectionMode } from "../collections/types.js";
+export type { Direction, DisabledBehavior, FocusStrategy, Key, Orientation, Selection, SelectionBehavior, SelectionMode };
+/** Collection node (react-types `Node`). */
+export interface Node {
+    readonly type: "item" | "section" | "header" | "separator" | "loader";
+    readonly key: Key;
+    index: number;
+    readonly level: number;
+    readonly parentKey: Key | null;
+    readonly textValue: string;
+    readonly hasChildNodes: boolean;
+    readonly childNodes: Iterable<Node>;
+    /** Item props the behaviours read: `isDisabled`, `href`, `target`, `rel`, `download`, … */
+    readonly props: NodeProps;
+    prevKey?: Key | undefined;
+    nextKey?: Key | undefined;
+}
+export interface NodeProps {
+    isDisabled?: boolean;
+    href?: string;
+    target?: string;
+    rel?: string;
+    download?: string | boolean;
+    [name: string]: unknown;
+}
+/** react-types `Collection`. */
+export interface Collection {
+    readonly size: number;
+    getKeys(): Iterable<Key>;
+    getItem(key: Key): Node | null;
+    getKeyBefore(key: Key): Key | null;
+    getKeyAfter(key: Key): Key | null;
+    getFirstKey(): Key | null;
+    getLastKey(): Key | null;
+    getChildren(key: Key): Iterable<Node>;
+    [Symbol.iterator](): IterableIterator<Node>;
+}
+export declare class ListCollection implements Collection {
+    private keyMap;
+    private iterable;
+    private firstKey;
+    private lastKey;
+    private _size;
+    constructor(nodes: Iterable<Node>);
+    [Symbol.iterator](): IterableIterator<Node>;
+    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): Node | null;
+    at(idx: number): Node | null;
+    getChildren(key: Key): Iterable<Node>;
+}
+/** Attribute marking a collection root (value: its id); items belong to their nearest root. */
+export declare const COLLECTION_ATTR = "data-collection";
+/** `data-key` (+ `data-key-type="number"`) encoding: ONE implementation in `../collections/dom.ts`. */
+export { domKey, keyAttrs } from "../collections/dom.js";
+/**
+ * Collection over the DOM under `root`: items are `[data-key]` elements whose nearest collection root
+ * (`[data-collection]`) is `root` and that are not `hidden`; sections are `[data-section]` elements
+ * (their `data-key` is the section key). Text: `data-text`, else the text content. Disabled:
+ * `aria-disabled="true"` or `data-disabled`. Links: `href` of `<a>` items.
+ */
+export declare function domCollection(root: Element): Collection;
+/** A data-driven item (RAC `<ListBoxItem>` / `<MenuItem>` props as data). */
+export interface CollectionItem {
+    /** RAC `id`. */
+    readonly key: Key;
+    /** Visible label (default render) and, unless `textValue` is set, the typeahead / filter text. */
+    readonly label: string;
+    /** RAC `textValue`: typeahead / filter / announced text when `label` is not plain text. */
+    readonly textValue?: string;
+    /** RAC `isDisabled`. */
+    readonly disabled?: boolean;
+    /** Link items: rendered as `<a href>`. */
+    readonly href?: string;
+    readonly target?: string;
+    readonly rel?: string;
+    readonly download?: string | boolean;
+    /** Secondary text (RAC `<Text slot="description">`). */
+    readonly description?: string;
+    /** RAC `aria-label` of the item. */
+    readonly "aria-label"?: string;
+}
+/** A section (RAC `<ListBoxSection>` / `<MenuSection>` with a `<Header>`). */
+export interface CollectionSection<I extends CollectionItem = CollectionItem> {
+    readonly key: Key;
+    /** Header text (RAC `<Header>`); without it, give the group an `aria-label`. */
+    readonly title?: string;
+    readonly "aria-label"?: string;
+    readonly children: readonly I[];
+}
+export type CollectionEntry<I extends CollectionItem = CollectionItem> = I | CollectionSection<I>;
+export declare const isSection: <I extends CollectionItem>(entry: CollectionEntry<I>) => entry is CollectionSection<I>;
+/** Text of an item for typeahead / filtering. */
+export declare const textOf: (item: CollectionItem) => string;
+/** Nodes of data entries (sections with their items), for `ListCollection`. */
+export declare function buildNodes(entries: readonly CollectionEntry[]): Node[];
+/** Every item of `entries` (sections flattened). */
+export declare function flatItems<I extends CollectionItem>(entries: readonly CollectionEntry<I>[]): I[];
+export declare function getChildNodes(node: Node, collection: Collection): Iterable<Node>;
+export declare function getFirstItem<T>(iterable: Iterable<T>): T | undefined;
+export declare function getItemCount(collection: Collection): number;
+export declare function compareNodeOrder(collection: Collection, a: Node, b: Node): number;
+export interface MultipleSelectionState {
+    readonly selectionMode: SelectionMode;
+    readonly disallowEmptySelection: boolean;
+    /** Current behaviour (long press on touch switches `replace` → `toggle`). */
+    readonly selectionBehavior: Signal<SelectionBehavior>;
+    /** The `selectionBehavior` prop. */
+    readonly selectionBehaviorProp: SelectionBehavior;
+    readonly allowDuplicateSelectionEvents: boolean;
+    /** Multiple storage: the selection. Absent when `selectedKey` stores a single key. */
+    readonly selectedKeys?: Signal<Selection>;
+    /** Single storage (Select / ComboBox): the selected key. */
+    readonly selectedKey?: Signal<Key | null>;
+    /** Range anchor / current key of the selection (react-stately `Selection.anchorKey` / `currentKey`). */
+    readonly anchorKey: Signal<Key | null>;
+    readonly currentKey: Signal<Key | null>;
+    readonly disabledKeys: Set<Key>;
+    readonly disabledBehavior: DisabledBehavior;
+    readonly isFocused: Signal<boolean>;
+    readonly focusedKey: Signal<Key | null>;
+    readonly childFocusStrategy: Signal<FocusStrategy | null>;
+    /** Called with the new selection (RAC `onSelectionChange`). */
+    readonly onSelectionChange?: ((keys: Selection) => void) | undefined;
+}
+export interface MultipleSelectionStateProps {
+    selectionMode?: SelectionMode;
+    disallowEmptySelection?: boolean;
+    selectionBehavior?: SelectionBehavior;
+    allowDuplicateSelectionEvents?: boolean;
+    /** Two-way selection (RAC controlled `selectedKeys`). */
+    selectedKeys?: Signal<Selection>;
+    /** Initial selection (RAC `defaultSelectedKeys`). */
+    defaultSelectedKeys?: "all" | Iterable<Key>;
+    onSelectionChange?: (keys: Selection) => void;
+    disabledKeys?: Iterable<Key>;
+    disabledBehavior?: DisabledBehavior;
+}
+/** Selection + focus state. `selectedKey` (a single-key signal) replaces the key-set storage. */
+export declare function createMultipleSelectionState(props: MultipleSelectionStateProps & {
+    selectedKey?: Signal<Key | null>;
+}): MultipleSelectionState;
+/** Current selection (reads the signal: tracked inside bindings). */
+export declare function readSelection(state: MultipleSelectionState): Selection;
+/** Write the selection (react-stately `setSelectedKeys`: skips equal sets unless duplicates are allowed). */
+export declare function writeSelection(state: MultipleSelectionState, keys: Selection, anchorKey?: Key | null, currentKey?: Key | null): void;
+/** Whether `key` is selected (binding accessor). `disabled`: the item's own disabled flag. */
+export declare function isKeySelected(state: MultipleSelectionState, key: Key, disabled?: boolean): boolean;
+/** Whether `key` is disabled for every interaction (react-stately `SelectionManager.isDisabled`). */
+export declare const isKeyDisabled: (state: MultipleSelectionState, key: Key, disabled?: boolean) => boolean;
+interface SelectionManagerOptions {
+    allowsCellSelection?: boolean;
+    layoutDelegate?: LayoutDelegate;
+    fullCollection?: Collection;
+}
+export declare class SelectionManager {
+    collection: Collection;
+    private state;
+    private allowsCellSelection;
+    private layoutDelegate;
+    private fullCollection;
+    constructor(collection: Collection, state: MultipleSelectionState, options?: SelectionManagerOptions);
+    get selectionMode(): SelectionMode;
+    get disallowEmptySelection(): boolean;
+    get selectionBehavior(): SelectionBehavior;
+    setSelectionBehavior(selectionBehavior: SelectionBehavior): void;
+    get isFocused(): boolean;
+    setFocused(isFocused: boolean): void;
+    get focusedKey(): Key | null;
+    get childFocusStrategy(): FocusStrategy | null;
+    setFocusedKey(key: Key | null, childFocusStrategy?: FocusStrategy): void;
+    private get raw();
+    get selectedKeys(): Set<Key>;
+    get rawSelection(): Selection;
+    isSelected(key: Key): boolean;
+    get isEmpty(): boolean;
+    get isSelectAll(): boolean;
+    get firstSelectedKey(): Key | null;
+    get lastSelectedKey(): Key | null;
+    get disabledKeys(): Set<Key>;
+    get disabledBehavior(): DisabledBehavior;
+    extendSelection(toKey: Key): void;
+    private getKeyRange;
+    private getKeyRangeInternal;
+    private getKey;
+    toggleSelection(key: Key): void;
+    replaceSelection(key: Key): void;
+    setSelectedKeys(keys: Iterable<Key>): void;
+    private getSelectAllKeys;
+    selectAll(): void;
+    clearSelection(): void;
+    toggleSelectAll(): void;
+    select(key: Key, e?: {
+        pointerType?: string;
+    }): void;
+    isSelectionEqual(selection: Set<Key>): boolean;
+    canSelectItem(key: Key): boolean;
+    private canSelectItemIn;
+    isDisabled(key: Key): boolean;
+    isLink(key: Key): boolean;
+    getItemProps(key: Key): NodeProps | undefined;
+    withCollection(collection: Collection): SelectionManager;
+}
+/**
+ * RAC `GroupSelectionManager` (Menu.tsx): a section with its own selection (`MenuSection
+ * selectionMode`) — local selection state, focus forwarded to the parent collection's manager.
+ */
+export declare class GroupSelectionManager extends SelectionManager {
+    private parent;
+    constructor(parent: SelectionManager, state: MultipleSelectionState);
+    get focusedKey(): Key | null;
+    get isFocused(): boolean;
+    setFocusedKey(key: Key | null, childFocusStrategy?: FocusStrategy): void;
+    setFocused(isFocused: boolean): void;
+    get childFocusStrategy(): FocusStrategy | null;
+}
+export interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface LayoutDelegate {
+    getItemRect(key: Key): Rect | null;
+    getVisibleRect(): Rect;
+    getContentSize(): {
+        width: number;
+        height: number;
+    };
+    getKeyRange?(from: Key, to: Key): Key[];
+    getKeyRightOf?(key: Key): Key | null;
+    getKeyLeftOf?(key: Key): Key | null;
+}
+export interface KeyboardDelegate {
+    getKeyBelow?(key: Key): Key | null;
+    getKeyAbove?(key: Key): Key | null;
+    getKeyLeftOf?(key: Key): Key | null;
+    getKeyRightOf?(key: Key): Key | null;
+    getKeyPageBelow?(key: Key): Key | null;
+    getKeyPageAbove?(key: Key): Key | null;
+    getFirstKey?(key?: Key | null, global?: boolean): Key | null;
+    getLastKey?(key?: Key | null, global?: boolean): Key | null;
+    getKeyForSearch?(search: string, fromKey?: Key | null): Key | null;
+}
+/** Element of `key` inside the collection `root` (react-aria `getItemElement`). */
+export declare function getItemElement(root: Element | null | undefined, key: Key): HTMLElement | null;
+export declare class DOMLayoutDelegate implements LayoutDelegate {
+    private root;
+    constructor(root: HTMLElement | null);
+    getItemRect(key: Key): Rect | null;
+    getContentSize(): {
+        width: number;
+        height: number;
+    };
+    getVisibleRect(): Rect;
+}
+/** Whether `node` scrolls (react-aria `isScrollable`). */
+export declare function isScrollable(node: Element | null, checkForOverflow?: boolean): boolean;
+interface ListKeyboardDelegateOptions {
+    collection: Collection;
+    ref: HTMLElement | null;
+    collator?: Intl.Collator;
+    layout?: "stack" | "grid";
+    orientation?: Orientation;
+    direction?: Direction;
+    disabledKeys?: Set<Key>;
+    disabledBehavior?: DisabledBehavior;
+    layoutDelegate?: LayoutDelegate;
+}
+export declare class ListKeyboardDelegate implements KeyboardDelegate {
+    private collection;
+    private disabledKeys;
+    private disabledBehavior;
+    private ref;
+    private collator;
+    private layout;
+    private orientation;
+    private direction;
+    private layoutDelegate;
+    getKeyRightOf?: (key: Key, options?: {
+        includeDisabled?: boolean;
+    }) => Key | null;
+    getKeyLeftOf?: (key: Key, options?: {
+        includeDisabled?: boolean;
+    }) => Key | null;
+    constructor(opts: ListKeyboardDelegateOptions);
+    private isDisabled;
+    private findNextNonDisabled;
+    getNextKey(key: Key, options?: {
+        includeDisabled?: boolean;
+    }): Key | null;
+    getPreviousKey(key: Key, options?: {
+        includeDisabled?: boolean;
+    }): Key | null;
+    private findKey;
+    private isSameRow;
+    private isSameColumn;
+    private isReversed;
+    getKeyBelow(key: Key, options?: {
+        includeDisabled?: boolean;
+    }): Key | null;
+    getKeyAbove(key: Key, options?: {
+        includeDisabled?: boolean;
+    }): Key | null;
+    private getNextColumn;
+    private keyRightOf;
+    private keyLeftOf;
+    getFirstKey(): Key | null;
+    getLastKey(): Key | null;
+    getKeyPageAbove(key: Key): Key | null;
+    getKeyPageBelow(key: Key): Key | null;
+    getKeyForSearch(search: string, fromKey?: Key | null): Key | null;
+}
+/** `useCollator({ usage: "search", sensitivity: "base" })`. */
+export declare const getSearchCollator: () => Intl.Collator;
+/** react-aria `isNonContiguousSelectionModifier`: Alt on Apple platforms, Ctrl elsewhere. */
+export declare const isNonContiguousSelectionModifier: (e: {
+    altKey: boolean;
+    ctrlKey: boolean;
+}) => boolean;