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

package/selection/selectable-item.js

@@ -0,0 +1,486 @@
+// Ported from @react-aria/selection (useSelectableItem.ts), Apache-2.0, © Adobe. The press and long
+// press handling it needs from @react-aria/interactions (usePress / useLongPress) is reduced to the
+// events the selection logic reads (press start / up / press with pointerType, long press on touch);
+// the full press machine (pointer capture, cancel on leave, text selection guards) belongs to the
+// cdk-interactions port.
+//
+// Rivet shape: handler bodies `(options, event)` for delegated wiring on the collection element
+// (`closestItem` finds the item and its key), plus attribute accessors and the state flags.
+import { untrack } from "@rivetjs/reactivity";
+import { domKey } from "../collections/dom.js";
+import { isFocusedKey } from "./keyed.js";
+import { focusSafely, isOpeningLink, moveVirtualFocus, openLink, pointerTypeOf, trackModality } from "./dom-utils.js";
+import { getCollectionId, isCtrlKeyPressed, isNonContiguousSelectionModifier, refElement } from "./utils.js";
+import { isTabbable } from "../a11y/index.js";
+import { routerOpen } from "../utils/links.jsx";
+const pressOf = (e, pointerType = pointerTypeOf(e)) => {
+    const m = e;
+    return { pointerType, key: m.key, shiftKey: !!m.shiftKey, ctrlKey: !!m.ctrlKey, metaKey: !!m.metaKey, altKey: !!m.altKey };
+};
+function derive(options) {
+    const { selectionManager: manager, key, onAction } = options;
+    const linkBehavior = options.linkBehavior ?? "action";
+    const isDisabled = !!options.isDisabled || manager.isDisabled(key);
+    // With checkbox selection, onAction (i.e. navigation) becomes primary, and occurs on a single click
+    // of the row. With highlight selection, onAction is secondary, and occurs on double click. With
+    // touch, onAction occurs on single tap, and long press enters selection mode.
+    const isLink = manager.isLink(key);
+    const isLinkOverride = isLink && linkBehavior === "override";
+    const isActionOverride = !!onAction && options.UNSTABLE_itemBehavior === "action";
+    const hasLinkAction = isLink && linkBehavior !== "selection" && linkBehavior !== "none";
+    const allowsSelection = !isDisabled && manager.canSelectItem(key) && !isLinkOverride && !isActionOverride;
+    const allowsActions = (!!onAction || hasLinkAction) && !isDisabled;
+    const hasPrimaryAction = allowsActions && (manager.selectionBehavior === "replace" ? !allowsSelection : !allowsSelection || manager.isEmpty);
+    const hasSecondaryAction = allowsActions && allowsSelection && manager.selectionBehavior === "replace";
+    const hasAction = hasPrimaryAction || hasSecondaryAction;
+    return {
+        manager,
+        key,
+        isDisabled,
+        allowsSelection,
+        allowsActions,
+        hasPrimaryAction,
+        hasSecondaryAction,
+        hasAction,
+        hasLinkAction,
+        longPressEnabled: hasAction && allowsSelection,
+        linkBehavior,
+    };
+}
+/**
+ * `manager.focusedKey === key`; for a cdk `SelectionManager` a keyed read (`keyed.ts`): a binding re-runs only
+ * when this key gains or loses focus, not on every focus move.
+ */
+function focusedKeyIs(manager, key) {
+    const state = manager.selectionState;
+    return state ? isFocusedKey(state, key) : manager.focusedKey === key;
+}
+/** Item state flags (react-aria `useSelectableItem` return minus props). Reads state: use in bindings. */
+export function selectableItemStates(options) {
+    const d = derive(options);
+    const el = refElement(options.ref);
+    return {
+        isPressed: !!el && pressMemos.get(el)?.pressed === true,
+        isSelected: d.manager.isSelected(d.key),
+        // Key first: only the focused item reads (and re-runs on) the collection's isFocused.
+        isFocused: focusedKeyIs(d.manager, d.key) && d.manager.isFocused,
+        isDisabled: d.isDisabled,
+        allowsSelection: d.allowsSelection,
+        hasAction: d.hasAction,
+    };
+}
+/**
+ * Attributes of the item (`tabIndex` roving: 0 for the focused key, -1 otherwise, none with virtual
+ * focus or when disabled; `data-key`, `data-collection`, `id`). Reads state: bind as accessors.
+ */
+export function selectableItemAttrs(options) {
+    const d = derive(options);
+    const attrs = { "data-key": String(d.key), "data-collection": getCollectionId(d.manager.collection), id: options.id };
+    if (typeof d.key === "number")
+        attrs["data-key-type"] = "number";
+    if (!options.shouldUseVirtualFocus && !d.isDisabled)
+        attrs.tabIndex = focusedKeyIs(d.manager, d.key) ? 0 : -1;
+    return attrs;
+}
+const itemPropsOf = (options, d) => options.itemProps ?? d.manager.getItemProps(d.key);
+/** react-aria `router.open(ref.current, e, href, routerOptions)`; without a client router: `openLink`. */
+function open(options, item, e, href, routerOptions) {
+    if (options.router && !options.router.isNative && href != null)
+        routerOpen(options.router, item, e, href, routerOptions);
+    else
+        openLink(item, e, href);
+}
+const pressEventOf = (type, item, e, source) => {
+    const m = source;
+    const rect = item.getBoundingClientRect();
+    return {
+        ...e,
+        type,
+        target: item,
+        x: m && "clientX" in m ? m.clientX - rect.left : rect.width / 2,
+        y: m && "clientY" in m ? m.clientY - rect.top : rect.height / 2,
+        continuePropagation() { },
+    };
+};
+/** usePress callbacks chained from the item props (react-aria `collectionItemProps` chaining). */
+function itemPress(options, d, item, phase, e, source) {
+    const p = itemPropsOf(options, d);
+    if (!p)
+        return;
+    if (phase === "start") {
+        p.onPressStart?.(pressEventOf("pressstart", item, e, source));
+        p.onPressChange?.(true);
+    }
+    else if (phase === "up")
+        p.onPressUp?.(pressEventOf("pressup", item, e, source));
+    else {
+        p.onPressEnd?.(pressEventOf("pressend", item, e, source));
+        p.onPressChange?.(false);
+        p.onPress?.(pressEventOf("press", item, e, source));
+    }
+}
+function onSelect(options, d, item, e) {
+    const { manager, key } = d;
+    if (e.pointerType === "keyboard" && isNonContiguousSelectionModifier(e)) {
+        manager.toggleSelection(key);
+        return;
+    }
+    if (manager.selectionMode === "none")
+        return;
+    if (manager.isLink(key)) {
+        if (d.linkBehavior === "selection" && item) {
+            const itemProps = itemPropsOf(options, d) ?? manager.getItemProps(key);
+            open(options, item, e, itemProps?.href, itemProps?.routerOptions);
+            // Always set selected keys back to what they were so that select and combobox close.
+            manager.setSelectedKeys(manager.selectedKeys);
+            return;
+        }
+        else if (d.linkBehavior === "override" || d.linkBehavior === "none")
+            return;
+    }
+    if (manager.selectionMode === "single") {
+        if (manager.isSelected(key) && !manager.disallowEmptySelection)
+            manager.toggleSelection(key);
+        else
+            manager.replaceSelection(key);
+    }
+    else if (e && e.shiftKey)
+        manager.extendSelection(key);
+    else if (manager.selectionBehavior === "toggle" || (e && (isCtrlKeyPressed(e) || e.pointerType === "touch" || e.pointerType === "virtual"))) {
+        // Touch or virtual (VO): toggle, otherwise multi selection is impossible without modifier keys.
+        manager.toggleSelection(key);
+    }
+    else
+        manager.replaceSelection(key);
+}
+function performAction(options, d, item, e) {
+    if (options.onAction) {
+        options.onAction();
+        item?.dispatchEvent(new CustomEvent("react-aria-item-action", { bubbles: true }));
+    }
+    if (d.hasLinkAction && item) {
+        const itemProps = itemPropsOf(options, d);
+        open(options, item, e, itemProps?.href, itemProps?.routerOptions);
+    }
+}
+const isActionKey = (key) => key === "Enter";
+const isSelectionKey = (key) => key === " ";
+const pressMemos = new WeakMap();
+const memoOf = (el) => {
+    let m = pressMemos.get(el);
+    if (!m) {
+        m = {
+            pressed: false,
+            modality: null,
+            longPressEnabledOnPressStart: false,
+            hadPrimaryActionOnPressStart: false,
+            longPressTimer: undefined,
+            didLongPress: false,
+            keyboardPressed: false,
+        };
+        pressMemos.set(el, m);
+    }
+    return m;
+};
+/** Long press threshold (react-aria useLongPress default). */
+export const LONG_PRESS_THRESHOLD_MS = 500;
+function pressStart(options, d, item, e) {
+    const m = memoOf(item);
+    m.pressed = true;
+    m.modality = e.pointerType;
+    m.longPressEnabledOnPressStart = d.longPressEnabled;
+    m.hadPrimaryActionOnPressStart = d.hasPrimaryAction;
+    m.didLongPress = false;
+    // When using virtual focus, make sure the focused key gets updated on press.
+    if (options.shouldUseVirtualFocus && e.pointerType !== "touch") {
+        d.manager.setFocused(true);
+        d.manager.setFocusedKey(d.key);
+    }
+    if (options.shouldSelectOnPressUp) {
+        if (e.pointerType === "keyboard" && (!d.hasAction || isSelectionKey(e.key)))
+            onSelect(options, d, item, e);
+        return;
+    }
+    // Select on mouse down unless there is a primary action which will occur on mouse up. For
+    // keyboard, select on key down. If there is an action, the Space key selects on key down, and the
+    // Enter key performs onAction on key up.
+    if (d.allowsSelection &&
+        ((e.pointerType === "mouse" && !d.hasPrimaryAction) || (e.pointerType === "keyboard" && (!d.allowsActions || isSelectionKey(e.key))))) {
+        onSelect(options, d, item, e);
+    }
+}
+function pressUp(options, d, item, e) {
+    if (options.shouldSelectOnPressUp && options.allowsDifferentPressOrigin && !d.hasPrimaryAction) {
+        if (e.pointerType === "mouse" && d.allowsSelection)
+            onSelect(options, d, item, e);
+    }
+}
+function press(options, d, item, e) {
+    const m = memoOf(item);
+    m.pressed = false;
+    if (options.shouldUseVirtualFocus && e.pointerType === "touch") {
+        d.manager.setFocused(true);
+        d.manager.setFocusedKey(d.key);
+    }
+    if (options.shouldSelectOnPressUp) {
+        if (!options.allowsDifferentPressOrigin) {
+            if (d.hasPrimaryAction || (d.hasSecondaryAction && e.pointerType !== "mouse")) {
+                if (e.pointerType === "keyboard" && !isActionKey(e.key))
+                    return;
+                performAction(options, d, item, e);
+            }
+            else if (e.pointerType !== "keyboard" && d.allowsSelection)
+                onSelect(options, d, item, e);
+        }
+        else if (d.hasPrimaryAction)
+            performAction(options, d, item, e);
+        else if (e.pointerType !== "keyboard" && e.pointerType !== "mouse" && d.allowsSelection)
+            onSelect(options, d, item, e);
+        return;
+    }
+    // Selection occurs on touch up. Primary actions always occur on pointer up. Both primary and
+    // secondary actions occur on Enter key up. Secondary actions occur on double click with a mouse.
+    if (e.pointerType === "touch" ||
+        e.pointerType === "pen" ||
+        e.pointerType === "virtual" ||
+        (e.pointerType === "keyboard" && d.hasAction && isActionKey(e.key)) ||
+        (e.pointerType === "mouse" && m.hadPrimaryActionOnPressStart)) {
+        if (d.hasAction)
+            performAction(options, d, item, e);
+        else if (d.allowsSelection)
+            onSelect(options, d, item, e);
+    }
+}
+/** Whether `target` is an interactive child of the item, or an item of another collection. */
+function isChildInteraction(item, collectionId, target) {
+    let el = target;
+    while (el && el !== item) {
+        const elCollection = el.getAttribute("data-collection");
+        if (elCollection != null)
+            return elCollection !== collectionId;
+        el = el.parentElement;
+    }
+    return isTabbable(target);
+}
+const itemOf = (options, e) => refElement(options.ref) ?? (e.currentTarget || null);
+/** Interactive when it allows selection, has a primary action, or uses virtual focus (react-aria's press props gate). */
+const pressable = (options, d) => d.allowsSelection || d.hasPrimaryAction || (!!options.shouldUseVirtualFocus && !d.isDisabled);
+/** pointerdown on the item (press start for mouse / pen / touch; long press timer on touch). */
+export function selectableItemPointerDown(options, e) {
+    const item = itemOf(options, e);
+    if (!item)
+        return;
+    trackModality(e);
+    const d = derive(options);
+    const target = e.target;
+    if (target && target !== item && isChildInteraction(item, getCollectionId(d.manager.collection), target)) {
+        e.stopPropagation();
+        return;
+    }
+    if (d.isDisabled) {
+        // Prevent focus going to the body when clicking on a disabled item.
+        e.preventDefault();
+        return;
+    }
+    // Prevent DOM focus from moving on mouse down when using virtual focus.
+    if (options.shouldUseVirtualFocus)
+        e.preventDefault();
+    if (e.button !== 0 && e.pointerType === "mouse")
+        return;
+    if (!pressable(options, d))
+        return;
+    const pe = pressOf(e);
+    // usePress: virtual pointer events (screen readers) only record the pointer type; the click that
+    // follows performs the whole press.
+    if (pe.pointerType === "virtual") {
+        memoOf(item).virtualPointer = true;
+        return;
+    }
+    pressStart(options, d, item, pe);
+    itemPress(options, d, item, "start", pe, e);
+    const m = memoOf(item);
+    clearTimeout(m.longPressTimer);
+    if (d.longPressEnabled && pe.pointerType === "touch") {
+        m.longPressTimer = setTimeout(() => {
+            // Long pressing with touch when selectionBehavior = "replace" switches it to "toggle".
+            m.didLongPress = true;
+            onSelect(options, derive(options), item, pe);
+            d.manager.setSelectionBehavior("toggle");
+        }, LONG_PRESS_THRESHOLD_MS);
+    }
+}
+/** pointerup on the item (press up; cancels a pending long press). */
+export function selectableItemPointerUp(options, e) {
+    const item = itemOf(options, e);
+    if (!item)
+        return;
+    const m = memoOf(item);
+    clearTimeout(m.longPressTimer);
+    const d = derive(options);
+    const pe = pressOf(e);
+    if (pe.pointerType === "virtual")
+        return;
+    if (!d.isDisabled && pressable(options, d)) {
+        pressUp(options, d, item, pe);
+        if (m.pressed)
+            itemPress(options, d, item, "up", pe, e);
+    }
+}
+/** pointercancel / pointerleave: drop the press. */
+export function selectableItemPointerCancel(options, e) {
+    const item = itemOf(options, e);
+    if (!item)
+        return;
+    const m = memoOf(item);
+    clearTimeout(m.longPressTimer);
+    m.pressed = false;
+}
+/**
+ * click on the item: the press (pointer presses that started on the item, and virtual clicks from
+ * screen readers / `element.click()`); link clicks are prevented so links open exactly when the
+ * selection logic says so.
+ */
+export function selectableItemClick(options, e) {
+    const item = itemOf(options, e);
+    if (!item)
+        return;
+    const d = derive(options);
+    if (d.linkBehavior !== "none" && d.manager.isLink(d.key) && !isOpeningLink())
+        e.preventDefault();
+    if (d.isDisabled || !pressable(options, d))
+        return;
+    // usePress onClick: a click it handles (not one opening a link) stops here, after the item's own onClick.
+    if (e.button === 0 && !isOpeningLink()) {
+        itemPropsOf(options, d)?.onClick?.(e);
+        e.stopPropagation();
+    }
+    const m = memoOf(item);
+    const virtual = (e.detail === 0 || !!m.virtualPointer) && !m.pressed;
+    m.virtualPointer = false;
+    if (m.didLongPress) {
+        m.didLongPress = false;
+        m.pressed = false;
+        return;
+    }
+    if (virtual) {
+        trackModality(e);
+        const pe = pressOf(e, "virtual");
+        pressStart(options, d, item, pe);
+        itemPress(options, d, item, "start", pe, e);
+        press(options, derive(options), item, pe);
+        itemPress(options, d, item, "end", pe, e);
+        return;
+    }
+    if (!m.pressed)
+        return;
+    const pe = pressOf(e, m.modality ?? "mouse");
+    press(options, d, item, pe);
+    itemPress(options, d, item, "end", pe, e);
+}
+/** keydown on the item: Space / Enter start a keyboard press. */
+export function selectableItemKeyDown(options, e) {
+    if (e.key !== " " && e.key !== "Enter")
+        return;
+    const item = itemOf(options, e);
+    if (!item)
+        return;
+    const d = derive(options);
+    if (d.isDisabled || !pressable(options, d))
+        return;
+    // Native link Enter would navigate: the selection logic decides instead.
+    e.preventDefault();
+    if (e.repeat)
+        return;
+    trackModality(e);
+    memoOf(item).keyboardPressed = true;
+    const pe = pressOf(e, "keyboard");
+    pressStart(options, d, item, pe);
+    itemPress(options, d, item, "start", pe, e);
+}
+/** keyup on the item: Space / Enter complete a keyboard press. */
+export function selectableItemKeyUp(options, e) {
+    if (e.key !== " " && e.key !== "Enter")
+        return;
+    const item = itemOf(options, e);
+    if (!item)
+        return;
+    const m = memoOf(item);
+    if (!m.keyboardPressed)
+        return;
+    m.keyboardPressed = false;
+    const d = derive(options);
+    if (d.isDisabled || !pressable(options, d))
+        return;
+    const pe = pressOf(e, "keyboard");
+    itemPress(options, d, item, "up", pe, e);
+    press(options, d, item, pe);
+    itemPress(options, d, item, "end", pe, e);
+    // usePress triggerSyntheticClick: keyboard activation also calls the item's onClick with a synthetic click.
+    const onClick = itemPropsOf(options, d)?.onClick;
+    if (onClick) {
+        const click = new MouseEvent("click", e);
+        Object.defineProperty(click, "target", { value: item });
+        Object.defineProperty(click, "currentTarget", { value: item });
+        onClick(click);
+    }
+}
+/** dblclick: with selectionBehavior "replace", a mouse double click performs the action. */
+export function selectableItemDoubleClick(options, e) {
+    const item = itemOf(options, e);
+    if (!item)
+        return;
+    const d = derive(options);
+    if (!d.hasSecondaryAction)
+        return;
+    if (memoOf(item).modality === "mouse") {
+        e.stopPropagation();
+        e.preventDefault();
+        performAction(options, d, item, pressOf(e, "mouse"));
+    }
+}
+/** focus on the item element itself: it becomes the focused key. */
+export function selectableItemFocus(options, e) {
+    const item = itemOf(options, e);
+    const d = derive(options);
+    if (options.shouldUseVirtualFocus || d.isDisabled)
+        return;
+    if (e.target === item && untrack(() => d.manager.focusedKey) !== d.key)
+        d.manager.setFocusedKey(d.key);
+}
+/** dragstart: no native drag after a touch long press that selected. */
+export function selectableItemDragStart(options, e) {
+    const item = itemOf(options, e);
+    if (!item)
+        return;
+    const m = memoOf(item);
+    if (m.modality === "touch" && m.longPressEnabledOnPressStart)
+        e.preventDefault();
+}
+/**
+ * Focus the item when it is the focused key of a focused collection (react-aria's item effect),
+ * or move virtual focus to it. `selectableCollection*` handlers call this through `syncFocus`.
+ */
+export function focusSelectableItem(options) {
+    const item = refElement(options.ref);
+    const { selectionManager: manager, key } = options;
+    if (key !== manager.focusedKey || !manager.isFocused)
+        return;
+    if (!options.shouldUseVirtualFocus) {
+        if (options.focus)
+            options.focus();
+        else if (item && item.ownerDocument.activeElement !== item)
+            focusSafely(item);
+    }
+    else
+        moveVirtualFocus(item);
+}
+/** The collection item element containing `target` (inside `collection`), with its key. */
+export function closestItem(collection, target, selector = "[data-key]") {
+    let el = target instanceof Element ? target.closest(selector) : null;
+    while (el && !collection.contains(el))
+        el = null;
+    if (!el || el === collection)
+        return null;
+    const key = domKey(el);
+    return key == null ? null : { element: el, key };
+}

package/selection/selectable-list.d.ts

@@ -0,0 +1,42 @@
+import type { Collection, Key, KeyboardDelegate, LayoutDelegate, Node, Orientation } from "../collections/types.js";
+import { type AriaSelectableCollectionOptions, type SelectableCollectionAria } from "./selectable-collection.js";
+export interface AriaSelectableListOptions extends Omit<AriaSelectableCollectionOptions, "keyboardDelegate"> {
+    /** State of the collection. */
+    collection: Collection<Node<unknown>>;
+    /** A delegate object that implements behavior for keyboard focus movement. */
+    keyboardDelegate?: KeyboardDelegate | undefined;
+    /** A delegate object that provides layout information (default: the DOM). */
+    layoutDelegate?: LayoutDelegate | undefined;
+    /** The item keys that are disabled. */
+    disabledKeys: Set<Key>;
+    /** The primary orientation of the items. Default "vertical". */
+    orientation?: Orientation | undefined;
+    /** Locale for the typeahead collator (default: `document.documentElement.lang`). */
+    locale?: string | undefined;
+}
+/** The selectable-collection options of a list: a `ListKeyboardDelegate` unless one is given. */
+export declare function selectableListOptions(props: AriaSelectableListOptions, event?: Event): AriaSelectableCollectionOptions;
+/** keydown (capture) on the list element. */
+export declare const selectableListKeyDownCapture: (props: AriaSelectableListOptions, e: KeyboardEvent & {
+    currentTarget: EventTarget | null;
+}) => boolean;
+/** keydown on the list element. */
+export declare const selectableListKeyDown: (props: AriaSelectableListOptions, e: KeyboardEvent & {
+    currentTarget: EventTarget | null;
+}) => boolean;
+/** focusin on the list element. */
+export declare const selectableListFocus: (props: AriaSelectableListOptions, e: FocusEvent & {
+    currentTarget: EventTarget | null;
+}) => void;
+/** focusout on the list element. */
+export declare const selectableListBlur: (props: AriaSelectableListOptions, e: FocusEvent & {
+    currentTarget: EventTarget | null;
+}) => void;
+/** mousedown on the list element. */
+export declare const selectableListMouseDown: (props: AriaSelectableListOptions, e: MouseEvent & {
+    currentTarget: EventTarget | null;
+}) => void;
+/** react-aria `useSelectableList` shape (imperative wiring). */
+export declare function useSelectableList(props: AriaSelectableListOptions): {
+    listProps: SelectableCollectionAria["collectionProps"];
+};

package/selection/selectable-list.js

@@ -0,0 +1,34 @@
+import { ListKeyboardDelegate, searchCollator } from "./list-keyboard-delegate.js";
+import { selectableCollectionBlur, selectableCollectionKeyDownCapture, selectableCollectionFocus, selectableCollectionKeyDown, selectableCollectionMouseDown, useSelectableCollection, } from "./selectable-collection.js";
+import { refElement } from "./utils.js";
+import { direction as elementDirection } from "../bidi/index.js";
+/** The selectable-collection options of a list: a `ListKeyboardDelegate` unless one is given. */
+export function selectableListOptions(props, event) {
+    const ref = refElement(props.ref) ?? (event?.currentTarget || null);
+    const delegate = props.keyboardDelegate ||
+        new ListKeyboardDelegate({
+            collection: props.collection,
+            disabledKeys: props.disabledKeys,
+            disabledBehavior: props.selectionManager.disabledBehavior,
+            ref,
+            collator: searchCollator(props.locale),
+            layoutDelegate: props.layoutDelegate,
+            orientation: props.orientation,
+            direction: props.direction ?? (ref ? elementDirection(ref) : undefined),
+        });
+    return { ...props, ref, keyboardDelegate: delegate };
+}
+/** keydown (capture) on the list element. */
+export const selectableListKeyDownCapture = (props, e) => selectableCollectionKeyDownCapture(selectableListOptions(props, e), e);
+/** keydown on the list element. */
+export const selectableListKeyDown = (props, e) => selectableCollectionKeyDown(selectableListOptions(props, e), e);
+/** focusin on the list element. */
+export const selectableListFocus = (props, e) => selectableCollectionFocus(selectableListOptions(props, e), e);
+/** focusout on the list element. */
+export const selectableListBlur = (props, e) => selectableCollectionBlur(selectableListOptions(props, e), e);
+/** mousedown on the list element. */
+export const selectableListMouseDown = (props, e) => selectableCollectionMouseDown(selectableListOptions(props, e), e);
+/** react-aria `useSelectableList` shape (imperative wiring). */
+export function useSelectableList(props) {
+    return { listProps: useSelectableCollection(selectableListOptions(props)).collectionProps };
+}

package/selection/state.d.ts

@@ -0,0 +1,96 @@
+import { type Signal } from "@rivetjs/reactivity";
+import type { DisabledBehavior, FocusStrategy, Key, Selection, SelectionBehavior, SelectionMode } from "../collections/types.js";
+/**
+ * A Set of keys that also has an anchor and current key for range selection (react-stately
+ * `Selection`). Passed to `onSelectionChange`; state signals hold plain Sets.
+ */
+export declare class SelectionSet extends Set<Key> {
+    anchorKey: Key | null;
+    currentKey: Key | null;
+    constructor(keys?: Iterable<Key> | SelectionSet, anchorKey?: Key | null, currentKey?: Key | null);
+}
+export interface FocusState {
+    /** Whether the collection is currently focused. */
+    readonly isFocused: Signal<boolean>;
+    /** The current focused key in the collection. */
+    readonly focusedKey: Signal<Key | null>;
+    /** Whether the first or last child of the focused key should receive focus. */
+    readonly childFocusStrategy: Signal<FocusStrategy | null>;
+}
+export interface MultipleSelectionState extends FocusState {
+    /** The type of selection that is allowed in the collection. */
+    readonly selectionMode: SelectionMode;
+    /** The selection behavior for the collection (changes on touch long press). */
+    readonly selectionBehavior: Signal<SelectionBehavior>;
+    /** The `selectionBehavior` option (the behavior to return to once the selection is empty). */
+    readonly selectionBehaviorProp: SelectionBehavior;
+    /** Whether the collection allows empty selection. */
+    readonly disallowEmptySelection: boolean;
+    /** The currently selected keys (`"all"` or a Set). */
+    readonly selectedKeys: Signal<Selection>;
+    /** Range anchor / current key (react-stately keeps them on the Selection object). */
+    readonly anchorKey: Signal<Key | null>;
+    readonly currentKey: Signal<Key | null>;
+    /** The currently disabled keys in the collection. */
+    readonly disabledKeys: Set<Key>;
+    /** Whether `disabledKeys` applies to selection, actions, or both. */
+    readonly disabledBehavior: DisabledBehavior;
+    /** Controlled by a plain value: never written, changes only reported to `onSelectionChange`. */
+    readonly controlled: boolean;
+    /** Whether onSelectionChange should fire even if the new set of keys is the same as the last. */
+    readonly allowDuplicateSelectionEvents: boolean;
+    readonly onSelectionChange?: ((keys: Selection) => void) | undefined;
+    /**
+     * Single-key backing (react-stately `useSingleSelectListState`): when set, the selection is
+     * `selectedKey` (read and written), and `onSelectedKeyChange` reports changes.
+     */
+    readonly selectedKey?: Signal<Key | null> | undefined;
+    readonly selectedKeyControlled?: boolean | undefined;
+    readonly onSelectedKeyChange?: ((key: Key | null) => void) | undefined;
+}
+export interface MultipleSelectionStateProps {
+    /** The type of selection that is allowed in the collection. Default "none". */
+    selectionMode?: SelectionMode | undefined;
+    /** Whether the collection allows empty selection. */
+    disallowEmptySelection?: boolean | undefined;
+    /**
+     * The selected keys: a signal (two-way), a plain value or an accessor returning a `Selection` (controlled: the
+     * state never changes it, `onSelectionChange` reports requested changes).
+     */
+    selectedKeys?: Signal<Selection> | (() => Selection) | "all" | Iterable<Key> | undefined;
+    /** The initial selected keys (uncontrolled). */
+    defaultSelectedKeys?: "all" | Iterable<Key> | undefined;
+    /** Handler that is called when the selection changes. */
+    onSelectionChange?: ((keys: Selection) => void) | undefined;
+    /** The currently disabled keys in the collection. */
+    disabledKeys?: Iterable<Key> | undefined;
+    /** How multiple selection should behave in the collection. Default "toggle". */
+    selectionBehavior?: SelectionBehavior | undefined;
+    /** Whether onSelectionChange should fire even if the new set of keys is the same as the last. */
+    allowDuplicateSelectionEvents?: boolean | undefined;
+    /** Whether `disabledKeys` applies to all interactions, or only selection. Default "all". */
+    disabledBehavior?: DisabledBehavior | undefined;
+    /** Initial focused key (Rivet: focus state is plain state too). */
+    defaultFocusedKey?: Key | null | undefined;
+    /** Single-key backing (see `MultipleSelectionState.selectedKey`). */
+    selectedKey?: Signal<Key | null> | undefined;
+    selectedKeyControlled?: boolean | undefined;
+    onSelectedKeyChange?: ((key: Key | null) => void) | undefined;
+}
+/** Manages state for multiple selection and focus in a collection (react-stately `useMultipleSelectionState`). */
+export declare function createMultipleSelectionState(props?: MultipleSelectionStateProps): MultipleSelectionState;
+/** The current selection (`"all"` or a Set). Reads the signals (tracked in bindings). */
+export declare function readSelection(state: MultipleSelectionState): Selection;
+/** Sets whether the collection is focused. */
+export declare function setFocused(state: FocusState, isFocused: boolean): void;
+/** Sets the focused key, and whether the first or last child of that key should receive focus. */
+export declare function setFocusedKey(state: FocusState, key: Key | null, childFocusStrategy?: FocusStrategy): void;
+/** Sets the selection behavior for the collection. */
+export declare function setSelectionBehavior(state: MultipleSelectionState, behavior: SelectionBehavior): void;
+/**
+ * Sets the selected keys (`"all"`, a Set, or a `SelectionSet` carrying anchor / current keys).
+ * Skips unchanged selections unless `allowDuplicateSelectionEvents`.
+ */
+export declare function setSelectedKeys(state: MultipleSelectionState, keys: Selection): void;
+/** Current selection as a `SelectionSet` with anchor / current keys (or "all"). Reads the signals. */
+export declare function getSelection(state: MultipleSelectionState): Selection;