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

package/selection/manager.js

@@ -0,0 +1,340 @@
+// Ported from @react-stately/selection (SelectionManager.ts), Apache-2.0, © Adobe.
+//
+// Rivet: construct per use from a collection + the serializable `MultipleSelectionState` (inside a
+// handler, or in a binding: reads are tracked through the state signals). Never capture an instance
+// in a resumable closure; capture the state and rebuild the manager.
+import { untrack } from "@rivetjs/reactivity";
+import { compareNodeOrder, getChildNodes, getFirstItem } from "../collections/nodes.js";
+import { SelectionSet, setFocused, setFocusedKey, setSelectedKeys, setSelectionBehavior, readSelection } from "./state.js";
+import { ALL_SELECTED, IN_SELECTION, isSelectionEmpty, selectionOf } from "./keyed.js";
+/** An interface for reading and updating multiple selection state. */
+export class SelectionManager {
+    collection;
+    state;
+    allowsCellSelection;
+    _isSelectAll;
+    // The selection `_isSelectAll` was computed for (managers may be reused across selection changes).
+    _isSelectAllOf;
+    layoutDelegate;
+    fullCollection;
+    constructor(collection, state, options) {
+        this.collection = collection;
+        this.state = state;
+        this.allowsCellSelection = options?.allowsCellSelection ?? false;
+        this._isSelectAll = null;
+        this._isSelectAllOf = null;
+        this.layoutDelegate = options?.layoutDelegate || null;
+        this.fullCollection = options?.fullCollection || null;
+    }
+    /** The underlying serializable state. */
+    get selectionState() {
+        return this.state;
+    }
+    get selectionMode() {
+        return this.state.selectionMode;
+    }
+    get disallowEmptySelection() {
+        return this.state.disallowEmptySelection;
+    }
+    get selectionBehavior() {
+        return this.state.selectionBehavior();
+    }
+    setSelectionBehavior(selectionBehavior) {
+        setSelectionBehavior(this.state, selectionBehavior);
+    }
+    get isFocused() {
+        return this.state.isFocused();
+    }
+    setFocused(isFocused) {
+        setFocused(this.state, isFocused);
+    }
+    get focusedKey() {
+        return this.state.focusedKey();
+    }
+    get childFocusStrategy() {
+        return this.state.childFocusStrategy();
+    }
+    setFocusedKey(key, childFocusStrategy) {
+        if (key == null || this.collection.getItem(key))
+            setFocusedKey(this.state, key, childFocusStrategy);
+    }
+    get selectedKeys() {
+        const keys = readSelection(this.state);
+        return keys === "all" ? new Set(this.getSelectAllKeys()) : keys;
+    }
+    /** The raw selection value: "all" or a set of keys. */
+    get rawSelection() {
+        return readSelection(this.state);
+    }
+    isSelected(key) {
+        if (this.state.selectionMode === "none")
+            return false;
+        const mappedKey = this.getKey(key);
+        if (mappedKey == null)
+            return false;
+        // Keyed read (`keyed.ts`): a binding re-runs only when this key's membership changes.
+        const selected = selectionOf(this.state, mappedKey);
+        return selected === ALL_SELECTED ? this.canSelectItem(mappedKey) : selected === IN_SELECTION;
+    }
+    get isEmpty() {
+        // Keyed read: bindings re-run only when emptiness flips.
+        return isSelectionEmpty(this.state);
+    }
+    get isSelectAll() {
+        if (this.isEmpty)
+            return false;
+        const selectedKeys = readSelection(this.state);
+        if (selectedKeys === "all")
+            return true;
+        if (this._isSelectAll != null && this._isSelectAllOf === selectedKeys)
+            return this._isSelectAll;
+        const allKeys = this.getSelectAllKeys();
+        this._isSelectAllOf = selectedKeys;
+        this._isSelectAll = allKeys.every((k) => selectedKeys.has(k));
+        return this._isSelectAll;
+    }
+    get firstSelectedKey() {
+        let first = null;
+        const keys = readSelection(this.state);
+        for (const key of keys === "all" ? this.getSelectAllKeys() : keys) {
+            const item = this.collection.getItem(key);
+            if (!first || (item && compareNodeOrder(this.collection, item, first) < 0))
+                first = item;
+        }
+        return first?.key ?? null;
+    }
+    get lastSelectedKey() {
+        let last = null;
+        const keys = readSelection(this.state);
+        for (const key of keys === "all" ? this.getSelectAllKeys() : keys) {
+            const item = this.collection.getItem(key);
+            if (!last || (item && compareNodeOrder(this.collection, item, last) > 0))
+                last = item;
+        }
+        return last?.key ?? null;
+    }
+    get disabledKeys() {
+        return this.state.disabledKeys;
+    }
+    get disabledBehavior() {
+        return this.state.disabledBehavior;
+    }
+    /** Extends the selection to the given key. */
+    extendSelection(toKey) {
+        if (this.selectionMode === "none")
+            return;
+        if (this.selectionMode === "single") {
+            this.replaceSelection(toKey);
+            return;
+        }
+        const mappedToKey = this.getKey(toKey);
+        if (mappedToKey == null)
+            return;
+        let selection;
+        const raw = untrack(() => readSelection(this.state));
+        // Only select the one key if coming from a select all.
+        if (raw === "all")
+            selection = new SelectionSet([mappedToKey], mappedToKey, mappedToKey);
+        else {
+            const anchorKey = untrack(this.state.anchorKey) ?? mappedToKey;
+            const currentKey = untrack(this.state.currentKey);
+            selection = new SelectionSet(raw, anchorKey, mappedToKey);
+            for (const key of this.getKeyRange(anchorKey, currentKey ?? mappedToKey))
+                selection.delete(key);
+            for (const key of this.getKeyRange(mappedToKey, anchorKey))
+                if (this.canSelectItem(key))
+                    selection.add(key);
+        }
+        setSelectedKeys(this.state, selection);
+    }
+    getKeyRange(from, to) {
+        const fromItem = this.collection.getItem(from);
+        const toItem = this.collection.getItem(to);
+        if (fromItem && toItem) {
+            if (compareNodeOrder(this.collection, fromItem, toItem) <= 0)
+                return this.getKeyRangeInternal(from, to);
+            return this.getKeyRangeInternal(to, from);
+        }
+        return [];
+    }
+    getKeyRangeInternal(from, to) {
+        if (this.layoutDelegate?.getKeyRange)
+            return this.layoutDelegate.getKeyRange(from, to);
+        const keys = [];
+        let key = from;
+        while (key != null) {
+            const item = this.collection.getItem(key);
+            if (item && (item.type === "item" || (item.type === "cell" && this.allowsCellSelection)))
+                keys.push(key);
+            if (key === to)
+                return keys;
+            key = this.collection.getKeyAfter(key);
+        }
+        return [];
+    }
+    getKey(key) {
+        let item = this.collection.getItem(key);
+        // ¯\_(ツ)_/¯
+        if (!item)
+            return key;
+        // If cell selection is allowed, just return the key.
+        if (item.type === "cell" && this.allowsCellSelection)
+            return key;
+        // Find a parent item to select.
+        while (item && item.type !== "item" && item.parentKey != null)
+            item = this.collection.getItem(item.parentKey);
+        if (!item || item.type !== "item")
+            return null;
+        return item.key;
+    }
+    /** Toggles whether the given key is selected. */
+    toggleSelection(key) {
+        if (this.selectionMode === "none")
+            return;
+        if (this.selectionMode === "single" && !this.isSelected(key)) {
+            this.replaceSelection(key);
+            return;
+        }
+        const mappedKey = this.getKey(key);
+        if (mappedKey == null)
+            return;
+        const raw = untrack(() => readSelection(this.state));
+        const keys = new SelectionSet(raw === "all" ? this.getSelectAllKeys() : raw, untrack(this.state.anchorKey), untrack(this.state.currentKey));
+        if (keys.has(mappedKey)) {
+            keys.delete(mappedKey);
+            // TODO (upstream): move anchor to last selected key...
+        }
+        else if (this.canSelectItem(mappedKey)) {
+            keys.add(mappedKey);
+            keys.anchorKey = mappedKey;
+            keys.currentKey = mappedKey;
+        }
+        if (this.disallowEmptySelection && keys.size === 0)
+            return;
+        setSelectedKeys(this.state, keys);
+    }
+    /** Replaces the selection with only the given key. */
+    replaceSelection(key) {
+        if (this.selectionMode === "none")
+            return;
+        const mappedKey = this.getKey(key);
+        if (mappedKey == null)
+            return;
+        const selection = this.canSelectItem(mappedKey) ? new SelectionSet([mappedKey], mappedKey, mappedKey) : new SelectionSet();
+        setSelectedKeys(this.state, selection);
+    }
+    /** Replaces the selection with the given keys. */
+    setSelectedKeys(keys) {
+        if (this.selectionMode === "none")
+            return;
+        const selection = new SelectionSet();
+        for (const key of keys) {
+            const mappedKey = this.getKey(key);
+            if (mappedKey != null) {
+                selection.add(mappedKey);
+                if (this.selectionMode === "single")
+                    break;
+            }
+        }
+        setSelectedKeys(this.state, selection);
+    }
+    getSelectAllKeys() {
+        // Use the full (unfiltered) collection when available so that materializing the "all" selection
+        // includes items that are currently filtered out.
+        const collection = this.fullCollection ?? this.collection;
+        const keys = [];
+        const addKeys = (key) => {
+            while (key != null) {
+                if (this.canSelectItemIn(key, collection)) {
+                    const item = collection.getItem(key);
+                    if (item?.type === "item")
+                        keys.push(key);
+                    // Add child keys. If cell selection is allowed, then include item children too.
+                    if (item?.hasChildNodes && (this.allowsCellSelection || item.type !== "item"))
+                        addKeys(getFirstItem(getChildNodes(item, collection))?.key ?? null);
+                }
+                key = collection.getKeyAfter(key);
+            }
+        };
+        addKeys(collection.getFirstKey());
+        return keys;
+    }
+    /** Selects all items in the collection. */
+    selectAll() {
+        if (!this.isSelectAll && this.selectionMode === "multiple")
+            setSelectedKeys(this.state, "all");
+    }
+    /** Removes all keys from the selection. */
+    clearSelection() {
+        const raw = untrack(() => readSelection(this.state));
+        if (!this.disallowEmptySelection && (raw === "all" || raw.size > 0))
+            setSelectedKeys(this.state, new SelectionSet());
+    }
+    /** Toggles between select all and an empty selection. */
+    toggleSelectAll() {
+        if (this.isSelectAll)
+            this.clearSelection();
+        else
+            this.selectAll();
+    }
+    /** Toggles, replaces or extends selection depending on the event and the selection mode. */
+    select(key, e) {
+        if (this.selectionMode === "none")
+            return;
+        if (this.selectionMode === "single") {
+            if (this.isSelected(key) && !this.disallowEmptySelection)
+                this.toggleSelection(key);
+            else
+                this.replaceSelection(key);
+        }
+        else if (this.selectionBehavior === "toggle" || (e && (e.pointerType === "touch" || e.pointerType === "virtual"))) {
+            // Touch or virtual (VO): toggle, otherwise multi selection is impossible without modifier keys.
+            this.toggleSelection(key);
+        }
+        else
+            this.replaceSelection(key);
+    }
+    /** Returns whether the current selection is equal to the given selection. */
+    isSelectionEqual(selection) {
+        if (selection === readSelection(this.state))
+            return true;
+        const selectedKeys = this.selectedKeys;
+        if (selection.size !== selectedKeys.size)
+            return false;
+        for (const key of selection)
+            if (!selectedKeys.has(key))
+                return false;
+        for (const key of selectedKeys)
+            if (!selection.has(key))
+                return false;
+        return true;
+    }
+    canSelectItem(key) {
+        return this.canSelectItemIn(key, this.collection);
+    }
+    canSelectItemIn(key, collection) {
+        if (this.state.selectionMode === "none" || this.state.disabledKeys.has(key))
+            return false;
+        const item = collection.getItem(key);
+        if (!item || item?.props?.isDisabled || (item.type === "cell" && !this.allowsCellSelection))
+            return false;
+        return true;
+    }
+    isDisabled(key) {
+        const item = this.collection.getItem(key);
+        return (this.state.disabledBehavior === "all" && (this.state.disabledKeys.has(key) || !!item?.props?.isDisabled) && item?.props?.disabledBehavior !== "selection");
+    }
+    isLink(key) {
+        return !!this.collection.getItem(key)?.props?.href;
+    }
+    getItemProps(key) {
+        return this.collection.getItem(key)?.props;
+    }
+    withCollection(collection) {
+        return new SelectionManager(collection, this.state, {
+            allowsCellSelection: this.allowsCellSelection,
+            layoutDelegate: this.layoutDelegate || undefined,
+            fullCollection: this.fullCollection ?? this.collection,
+        });
+    }
+}

package/selection/selectable-collection.d.ts

@@ -0,0 +1,123 @@
+import type { Direction, FocusStrategy, Key, KeyboardDelegate } from "../collections/types.js";
+import type { MultipleSelectionManager } from "./manager.js";
+import { isOpeningLink } from "./dom-utils.js";
+import { type RefLike } from "./utils.js";
+/** Custom events for updating an autocomplete's aria-activedescendant (react-aria constants). */
+export declare const CLEAR_FOCUS_EVENT = "react-aria-clear-focus";
+export declare const FOCUS_EVENT = "react-aria-focus";
+export type LinkBehavior = "action" | "selection" | "override";
+export interface AriaSelectableCollectionOptions {
+    /** An interface for reading and updating multiple selection state. */
+    selectionManager: MultipleSelectionManager;
+    /** A delegate object that implements behavior for keyboard focus movement. */
+    keyboardDelegate: KeyboardDelegate;
+    /** The collection element (ref or element; handlers default to `event.currentTarget`). */
+    ref?: RefLike;
+    /** Whether the collection or one of its items should be automatically focused upon render. */
+    autoFocus?: boolean | FocusStrategy | undefined;
+    /** Whether focus should wrap around when the end/start is reached. */
+    shouldFocusWrap?: boolean | undefined;
+    /** Whether the collection allows empty selection. */
+    disallowEmptySelection?: boolean | undefined;
+    /** Whether the collection allows the user to select all items via keyboard shortcut. */
+    disallowSelectAll?: boolean | undefined;
+    /** Whether pressing Escape should clear selection. Default "clearSelection". */
+    escapeKeyBehavior?: "clearSelection" | "none" | undefined;
+    /** Whether selection should occur automatically on focus. Default: selectionBehavior === "replace". */
+    selectOnFocus?: boolean | undefined;
+    /** Whether typeahead is disabled. */
+    disallowTypeAhead?: boolean | undefined;
+    /** Whether the collection items should use virtual focus instead of being focused directly. */
+    shouldUseVirtualFocus?: boolean | undefined;
+    /** Whether navigation through tab key is enabled. */
+    allowsTabNavigation?: boolean | undefined;
+    /** Whether the collection items are contained in a virtual scroller. */
+    isVirtualized?: boolean | undefined;
+    /** The scrollable body (default: the collection element). */
+    scrollRef?: RefLike;
+    /** The behavior of links in the collection. Default "action". */
+    linkBehavior?: LinkBehavior | undefined;
+    /** @private Which item to focus when tabbing into the collection. */
+    UNSTABLE_focusOnEntry?: "first" | "last" | undefined;
+    /** Reading direction (default: computed from the collection element). */
+    direction?: Direction | undefined;
+}
+type Ev<E extends Event> = E & {
+    currentTarget: EventTarget | null;
+};
+/** Keys the collection handles on keydown (for `data-rk`, held while a cold chunk loads). */
+export declare const selectableCollectionKeys = "ArrowDown ArrowUp ArrowLeft ArrowRight Home End PageUp PageDown";
+/**
+ * keydown, capture phase, on the collection element (react-aria's `onKeyDownCapture` of the type
+ * select): while a search is in progress, Space extends it and is stopped before items see it.
+ * Delegated wiring calls this first; returns whether it handled the event.
+ */
+export declare function selectableCollectionKeyDownCapture(options: AriaSelectableCollectionOptions, e: Ev<KeyboardEvent>): boolean;
+/**
+ * keydown (bubble phase) on the collection element: arrow / Home / End / Page navigation, Shift
+ * range extension, Mod+A, Escape, Tab, then typeahead. Item-level Space / Enter presses belong to
+ * `selectableItemKeyDown` (on the item, before this). Returns whether the event was handled.
+ */
+export declare function selectableCollectionKeyDown(options: AriaSelectableCollectionOptions, e: Ev<KeyboardEvent>): boolean;
+/** scroll on the scrollable body: remember the position (restored when focus re-enters). */
+export declare function selectableCollectionScroll(options: AriaSelectableCollectionOptions, e: Ev<Event>): void;
+/**
+ * focus (wire as `onFocusIn`: Rivet delegates `focusin`) on the collection element. Restores the
+ * last focused item, or picks the first / last (selected) item depending on where focus came from.
+ */
+export declare function selectableCollectionFocus(options: AriaSelectableCollectionOptions, e: Ev<FocusEvent>): void;
+/** blur (wire as `onFocusOut`) on the collection element. */
+export declare function selectableCollectionBlur(options: AriaSelectableCollectionOptions, e: Ev<FocusEvent>): void;
+/** mousedown on the collection element: clicking the scrollbar must not focus the collection. */
+export declare function selectableCollectionMouseDown(options: AriaSelectableCollectionOptions, e: Ev<MouseEvent>): void;
+/** `FOCUS_EVENT` (virtual focus, autocomplete): the collection takes virtual focus. */
+export declare function selectableCollectionVirtualFocus(options: AriaSelectableCollectionOptions, e: Ev<CustomEvent<{
+    focusStrategy?: FocusStrategy;
+}>>): void;
+/** `CLEAR_FOCUS_EVENT` (virtual focus): drop virtual focus, optionally clearing the focused key. */
+export declare function selectableCollectionClearVirtualFocus(options: AriaSelectableCollectionOptions, e: Ev<CustomEvent<{
+    clearFocusKey?: boolean;
+}>>): void;
+/**
+ * Collection contents changed (call from the component's effect after a filter / load): with a
+ * pending "virtual focus first" request, focus the first key, or clear the active descendant when
+ * nothing is focusable.
+ */
+export declare function selectableCollectionUpdated(options: AriaSelectableCollectionOptions): void;
+/**
+ * Auto focus (react-aria's mount effect for `autoFocus`): focus the first selectable selected key,
+ * else the first / last key, else the collection. Call once the collection element is connected
+ * (e.g. from a `clientEffect`). Returns whether it ran (retries while the collection is empty).
+ */
+export declare function selectableCollectionAutoFocus(options: AriaSelectableCollectionOptions): boolean;
+/**
+ * react-aria's post-render effects, run after a handler changed state: move DOM (or virtual) focus
+ * to the focused item, scroll it into view (keyboard modality / after auto focus), and focus the
+ * collection when the focused item went away.
+ */
+export declare function syncFocus(options: AriaSelectableCollectionOptions, previousKey: Key | null, event?: Event): void;
+/**
+ * tabIndex of the collection element: tabbable while nothing inside is focused (marshalled to the
+ * first / last item on focus); undefined with virtual focus. Reads `focusedKey` (bind as accessor).
+ */
+export declare function collectionTabIndex(manager: Pick<MultipleSelectionManager, "focusedKey">, shouldUseVirtualFocus?: boolean): number | undefined;
+export interface SelectableCollectionAria {
+    /** Props for the collection element (client-side / imperative wiring; not resumable). */
+    collectionProps: {
+        tabIndex: number | undefined;
+        "data-collection"?: string | undefined;
+        onKeyDownCapture: (e: KeyboardEvent) => void;
+        onKeyDown: (e: KeyboardEvent) => void;
+        onFocusIn: (e: FocusEvent) => void;
+        onFocusOut: (e: FocusEvent) => void;
+        onMouseDown: (e: MouseEvent) => void;
+    };
+}
+/**
+ * react-aria `useSelectableCollection` shape for imperative / client-only use (`addEventListener`).
+ * Resumable components wire the handler bodies above instead.
+ */
+export declare function useSelectableCollection(options: AriaSelectableCollectionOptions & {
+    collectionId?: string;
+}): SelectableCollectionAria;
+export { isOpeningLink };