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

package/selection/selectable-collection.js

@@ -0,0 +1,560 @@
+// Ported from @react-aria/selection (useSelectableCollection.ts), Apache-2.0, © Adobe.
+//
+// Rivet shape: react-aria returns a props bag with closures; here the behaviour is a set of handler
+// bodies taking `(options, event)` — wire them as explicit `onKeyDown` / `onFocusIn` / … attributes
+// so they resume — plus attribute accessors (`collectionTabIndex`). React's effects (focus the item
+// that became `focusedKey`, scroll it into view, focus the collection when the focused item goes
+// away) run synchronously at the end of each handler (`syncFocus`). Options are cheap to rebuild per
+// event from serializable state; never capture a `SelectionManager` in a resumable closure.
+import { untrack } from "@rivetjs/reactivity";
+import { direction as elementDirection } from "../bidi/index.js";
+import { tabbables, isTabbable } from "../a11y/index.js";
+import { dispatchVirtualFocus, focusSafely, focusWithoutScrolling, getInteractionModality, isOpeningLink, moveVirtualFocus, nodeContains, openLink, scrollIntoView, scrollIntoViewport, trackModality, } from "./dom-utils.js";
+import { typeSelectKeyDown, typeSelectKeyDownCapture } from "./type-select.js";
+import { getItemElement, isCtrlKeyPressed, isNonContiguousSelectionModifier, refElement } from "./utils.js";
+import { isMac } from "../platform/index.js";
+/** Custom events for updating an autocomplete's aria-activedescendant (react-aria constants). */
+export const CLEAR_FOCUS_EVENT = "react-aria-clear-focus";
+export const FOCUS_EVENT = "react-aria-focus";
+function resolve(options, event) {
+    const ref = refElement(options.ref) ?? (event?.currentTarget || null);
+    const manager = options.selectionManager;
+    return {
+        manager,
+        delegate: options.keyboardDelegate,
+        ref,
+        scrollRef: refElement(options.scrollRef) ?? ref,
+        selectOnFocus: options.selectOnFocus ?? manager.selectionBehavior === "replace",
+        shouldFocusWrap: options.shouldFocusWrap ?? false,
+        disallowEmptySelection: options.disallowEmptySelection ?? false,
+        disallowSelectAll: options.disallowSelectAll ?? false,
+        escapeKeyBehavior: options.escapeKeyBehavior ?? "clearSelection",
+        shouldUseVirtualFocus: !!options.shouldUseVirtualFocus,
+        allowsTabNavigation: options.allowsTabNavigation ?? false,
+        linkBehavior: options.linkBehavior ?? "action",
+        direction: options.direction ?? (ref ? elementDirection(ref) : "ltr"),
+        options,
+    };
+}
+function navigateToKey(r, e, key, childFocus) {
+    const { manager, selectOnFocus, linkBehavior } = r;
+    if (key != null) {
+        if (manager.isLink(key) && linkBehavior === "selection" && selectOnFocus && !isNonContiguousSelectionModifier(e)) {
+            // Set focused key (synchronously brings the item into view), then follow the link.
+            manager.setFocusedKey(key, childFocus);
+            const item = getItemElement(r.ref, key);
+            const itemProps = manager.getItemProps(key);
+            if (item) {
+                openLink(item, e, itemProps.href);
+                return;
+            }
+            return false;
+        }
+        manager.setFocusedKey(key, childFocus);
+        if (manager.isLink(key) && linkBehavior === "override")
+            return false;
+        if (e.shiftKey && manager.selectionMode === "multiple") {
+            manager.extendSelection(key);
+            return;
+        }
+        else if (selectOnFocus && !isNonContiguousSelectionModifier(e)) {
+            manager.replaceSelection(key);
+            return;
+        }
+    }
+    return false;
+}
+function arrowDown(r, e) {
+    const { manager, delegate } = r;
+    if (delegate.getKeyBelow) {
+        let nextKey = manager.focusedKey != null ? delegate.getKeyBelow(manager.focusedKey) : delegate.getFirstKey?.();
+        if (nextKey == null && r.shouldFocusWrap)
+            nextKey = delegate.getFirstKey?.(manager.focusedKey);
+        if (nextKey != null) {
+            navigateToKey(r, e, nextKey);
+            return;
+        }
+    }
+    return false;
+}
+function arrowUp(r, e) {
+    const { manager, delegate } = r;
+    if (delegate.getKeyAbove) {
+        let nextKey = manager.focusedKey != null ? delegate.getKeyAbove(manager.focusedKey) : delegate.getLastKey?.();
+        if (nextKey == null && r.shouldFocusWrap)
+            nextKey = delegate.getLastKey?.(manager.focusedKey);
+        if (nextKey != null) {
+            navigateToKey(r, e, nextKey);
+            return;
+        }
+    }
+    return false;
+}
+function arrowLeft(r, e) {
+    const { manager, delegate, direction } = r;
+    if (delegate.getKeyLeftOf) {
+        let nextKey = manager.focusedKey != null ? delegate.getKeyLeftOf(manager.focusedKey) : delegate.getFirstKey?.();
+        if (nextKey == null && r.shouldFocusWrap)
+            nextKey = direction === "rtl" ? delegate.getFirstKey?.(manager.focusedKey) : delegate.getLastKey?.(manager.focusedKey);
+        if (nextKey != null) {
+            navigateToKey(r, e, nextKey, direction === "rtl" ? "first" : "last");
+            return;
+        }
+    }
+    return false;
+}
+function arrowRight(r, e) {
+    const { manager, delegate, direction } = r;
+    if (delegate.getKeyRightOf) {
+        let nextKey = manager.focusedKey != null ? delegate.getKeyRightOf(manager.focusedKey) : delegate.getFirstKey?.();
+        if (nextKey == null && r.shouldFocusWrap)
+            nextKey = direction === "rtl" ? delegate.getLastKey?.(manager.focusedKey) : delegate.getFirstKey?.(manager.focusedKey);
+        if (nextKey != null) {
+            navigateToKey(r, e, nextKey, direction === "rtl" ? "last" : "first");
+            return;
+        }
+    }
+    return false;
+}
+function home(r, e) {
+    const { manager, delegate } = r;
+    if (delegate.getFirstKey) {
+        if (manager.focusedKey === null && e.shiftKey)
+            return false;
+        const firstKey = delegate.getFirstKey(manager.focusedKey, isCtrlKeyPressed(e));
+        manager.setFocusedKey(firstKey);
+        if (firstKey != null) {
+            if (isCtrlKeyPressed(e) && e.shiftKey && manager.selectionMode === "multiple") {
+                manager.extendSelection(firstKey);
+                return;
+            }
+            else if (r.selectOnFocus) {
+                manager.replaceSelection(firstKey);
+                return;
+            }
+        }
+    }
+    return false;
+}
+function end(r, e) {
+    const { manager, delegate } = r;
+    if (delegate.getLastKey) {
+        if (manager.focusedKey === null && e.shiftKey)
+            return false;
+        const lastKey = delegate.getLastKey(manager.focusedKey, isCtrlKeyPressed(e));
+        manager.setFocusedKey(lastKey);
+        if (lastKey != null) {
+            if (isCtrlKeyPressed(e) && e.shiftKey && manager.selectionMode === "multiple") {
+                manager.extendSelection(lastKey);
+                return;
+            }
+            else if (r.selectOnFocus) {
+                manager.replaceSelection(lastKey);
+                return;
+            }
+        }
+    }
+    return false;
+}
+function pageDown(r, e) {
+    const { manager, delegate } = r;
+    if (delegate.getKeyPageBelow && manager.focusedKey != null) {
+        const nextKey = delegate.getKeyPageBelow(manager.focusedKey);
+        if (nextKey != null)
+            return navigateToKey(r, e, nextKey);
+    }
+    return false;
+}
+function pageUp(r, e) {
+    const { manager, delegate } = r;
+    if (delegate.getKeyPageAbove && manager.focusedKey != null) {
+        const nextKey = delegate.getKeyPageAbove(manager.focusedKey);
+        if (nextKey != null)
+            return navigateToKey(r, e, nextKey);
+    }
+    return false;
+}
+function selectAllKey(r) {
+    if (r.manager.selectionMode === "multiple" && r.disallowSelectAll !== true) {
+        r.manager.selectAll();
+        return;
+    }
+    return false;
+}
+function escape(r) {
+    if (r.escapeKeyBehavior === "clearSelection" && !r.disallowEmptySelection && r.manager.selectedKeys.size !== 0) {
+        r.manager.clearSelection();
+        return;
+    }
+    return false;
+}
+function tab(r) {
+    if (!r.allowsTabNavigation && r.ref) {
+        // Collections are a single tab stop: move focus to the last tabbable element inside, so the
+        // browser default Tab continues from there (out of the collection).
+        const list = tabbables(r.ref);
+        const next = list[list.length - 1];
+        const activeElement = r.ref.ownerDocument.activeElement;
+        // If the active element is not tabbable but is contained by a tabbable element (a cell), the
+        // browser moves focus to the container: special-case it so Tab leaves the grid.
+        if (next && (!nodeContains(next, activeElement) || (activeElement && !isTabbable(activeElement))))
+            focusWithoutScrolling(next);
+    }
+    return { shouldContinuePropagation: true, shouldPreventDefault: false };
+}
+function shiftTab(r) {
+    if (!r.allowsTabNavigation && r.ref)
+        r.ref.focus();
+    return { shouldContinuePropagation: true, shouldPreventDefault: false };
+}
+/** Shortcut match: `Key`, `Key+Shift`, `Key+Alt|Control` (non-contiguous), `Key+Shift+Alt|Control`. */
+function withShiftSel(e) {
+    // The non-contiguous modifier (Alt on Mac, Control elsewhere) and Shift are allowed; others not.
+    return isMac() ? !e.ctrlKey && !e.metaKey : !e.altKey && !e.metaKey;
+}
+function runShortcut(e, action) {
+    let result = action();
+    let handled;
+    if (result === undefined)
+        handled = { shouldContinuePropagation: false, shouldPreventDefault: true };
+    else if (typeof result === "boolean")
+        handled = { shouldContinuePropagation: !result, shouldPreventDefault: result };
+    else
+        handled = result;
+    if (handled.shouldPreventDefault)
+        e.preventDefault();
+    if (!handled.shouldContinuePropagation)
+        e.stopPropagation();
+    return !handled.shouldContinuePropagation;
+}
+/** Keys the collection handles on keydown (for `data-rk`, held while a cold chunk loads). */
+export 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 function selectableCollectionKeyDownCapture(options, e) {
+    if (options.disallowTypeAhead)
+        return false;
+    const r = resolve(options, e);
+    trackModality(e);
+    const before = untrack(() => r.manager.focusedKey);
+    const handled = typeSelectKeyDownCapture(r.ref ?? options, { keyboardDelegate: r.delegate, selectionManager: r.manager }, e);
+    if (handled)
+        syncFocus(options, before, e);
+    return handled;
+}
+/**
+ * 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 function selectableCollectionKeyDown(options, e) {
+    const r = resolve(options, e);
+    trackModality(e);
+    const before = untrack(() => r.manager.focusedKey);
+    let handled = false;
+    // Events from portals (not inside the collection element) are ignored.
+    if (!r.ref || nodeContains(r.ref, e.target)) {
+        if (!e.isComposing)
+            handled = shortcut(r, e);
+        if (!handled && !options.disallowTypeAhead)
+            handled = typeSelectKeyDown(r.ref ?? options, { keyboardDelegate: r.delegate, selectionManager: r.manager }, e);
+    }
+    syncFocus(options, before, e);
+    return handled;
+}
+function shortcut(r, e) {
+    const key = e.key;
+    const repeatable = {
+        ArrowDown: arrowDown,
+        ArrowUp: arrowUp,
+        ArrowLeft: arrowLeft,
+        ArrowRight: arrowRight,
+        PageDown: pageDown,
+        PageUp: pageUp,
+    };
+    const fn = repeatable[key];
+    if (fn)
+        return withShiftSel(e) ? runShortcut(e, () => fn(r, e)) : false;
+    if (e.repeat)
+        return false;
+    if (key === "Home" || key === "End")
+        return withShiftSel(e) ? runShortcut(e, () => (key === "Home" ? home : end)(r, e)) : false;
+    const mod = isMac() ? e.metaKey && !e.ctrlKey : e.ctrlKey && !e.metaKey;
+    if (key.toLowerCase() === "a" && mod && !e.shiftKey && !e.altKey)
+        return runShortcut(e, () => selectAllKey(r));
+    const noMods = !e.altKey && !e.ctrlKey && !e.metaKey;
+    if (key === "Escape" && noMods && !e.shiftKey)
+        return runShortcut(e, () => escape(r));
+    if (key === "Tab" && noMods)
+        return runShortcut(e, () => (e.shiftKey ? shiftTab(r) : tab(r)));
+    return false;
+}
+const memos = new WeakMap();
+const memoOf = (owner) => {
+    let m = memos.get(owner);
+    if (!m)
+        memos.set(owner, (m = { scrollTop: 0, scrollLeft: 0, shouldVirtualFocusFirst: false, lastFocusedKey: null, didAutoFocus: false, autoFocusPending: true }));
+    return m;
+};
+/** scroll on the scrollable body: remember the position (restored when focus re-enters). */
+export function selectableCollectionScroll(options, e) {
+    // RA: not for a virtualized collection (the virtualizer owns its scroll position).
+    if (options.isVirtualized)
+        return;
+    const r = resolve(options, e);
+    const m = memoOf(r.ref ?? options);
+    m.scrollTop = r.scrollRef?.scrollTop ?? 0;
+    m.scrollLeft = r.scrollRef?.scrollLeft ?? 0;
+}
+/**
+ * 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 function selectableCollectionFocus(options, e) {
+    const r = resolve(options, e);
+    const { manager, delegate } = r;
+    const target = e.target;
+    const current = (r.ref ?? e.currentTarget);
+    if (manager.isFocused) {
+        // If a focus event bubbled through a portal, reset focus state.
+        if (!nodeContains(current, target))
+            manager.setFocused(false);
+        return;
+    }
+    // Focus events can bubble through portals. Ignore these events.
+    if (!nodeContains(current, target))
+        return;
+    const modality = getInteractionModality();
+    manager.setFocused(true);
+    const navigate = (key) => {
+        if (key != null) {
+            manager.setFocusedKey(key);
+            if (r.selectOnFocus && !manager.isSelected(key))
+                manager.replaceSelection(key);
+        }
+    };
+    const m = memoOf(r.ref ?? options);
+    if (options.UNSTABLE_focusOnEntry && (modality === "keyboard" || modality === "virtual")) {
+        navigate(options.UNSTABLE_focusOnEntry === "first" ? delegate.getFirstKey?.() : delegate.getLastKey?.());
+    }
+    else if (manager.focusedKey == null) {
+        // No focused key yet: detect whether the user is tabbing forward or backward into the
+        // collection and focus the first or last item accordingly.
+        const relatedTarget = e.relatedTarget;
+        if (relatedTarget && current && current.compareDocumentPosition(relatedTarget) & Node.DOCUMENT_POSITION_FOLLOWING) {
+            navigate(manager.lastSelectedKey ?? delegate.getLastKey?.());
+        }
+        else
+            navigate(manager.firstSelectedKey ?? delegate.getFirstKey?.());
+    }
+    else if (!options.isVirtualized && r.scrollRef) {
+        // Restore the scroll position to what it was before.
+        r.scrollRef.scrollTop = m.scrollTop;
+        r.scrollRef.scrollLeft = m.scrollLeft;
+    }
+    if (manager.focusedKey != null && r.scrollRef) {
+        // Refocus and scroll the focused item into view if it exists within the scrollable region.
+        const element = getItemElement(r.ref, manager.focusedKey);
+        if (element) {
+            // This prevents a flash of focus on the first/last element in the collection, or the collection itself.
+            if (!nodeContains(element, element.ownerDocument.activeElement) && !r.shouldUseVirtualFocus)
+                focusWithoutScrolling(element);
+            if (modality === "keyboard" || (options.UNSTABLE_focusOnEntry && modality === "virtual"))
+                scrollIntoViewport(element, { containingElement: r.ref });
+        }
+    }
+    m.lastFocusedKey = manager.focusedKey;
+}
+/** blur (wire as `onFocusOut`) on the collection element. */
+export function selectableCollectionBlur(options, e) {
+    const r = resolve(options, e);
+    // Don't set blurred and then focused again if moving focus within the collection.
+    if (!nodeContains((r.ref ?? e.currentTarget), e.relatedTarget))
+        r.manager.setFocused(false);
+}
+/** mousedown on the collection element: clicking the scrollbar must not focus the collection. */
+export function selectableCollectionMouseDown(options, e) {
+    const r = resolve(options, e);
+    trackModality(e);
+    if (r.scrollRef === e.target)
+        e.preventDefault();
+}
+/** `FOCUS_EVENT` (virtual focus, autocomplete): the collection takes virtual focus. */
+export function selectableCollectionVirtualFocus(options, e) {
+    if (!options.shouldUseVirtualFocus)
+        return;
+    const r = resolve(options, e);
+    e.stopPropagation();
+    r.manager.setFocused(true);
+    // If the user is typing forwards, autofocus the first option in the list.
+    if (e.detail?.focusStrategy === "first")
+        memoOf(r.ref ?? options).shouldVirtualFocusFirst = true;
+}
+/** `CLEAR_FOCUS_EVENT` (virtual focus): drop virtual focus, optionally clearing the focused key. */
+export function selectableCollectionClearVirtualFocus(options, e) {
+    if (!options.shouldUseVirtualFocus)
+        return;
+    const r = resolve(options, e);
+    e.stopPropagation();
+    r.manager.setFocused(false);
+    if (e.detail?.clearFocusKey)
+        r.manager.setFocusedKey(null);
+}
+/**
+ * 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 function selectableCollectionUpdated(options) {
+    const r = resolve(options);
+    const m = memoOf(r.ref ?? options);
+    if (!m.shouldVirtualFocusFirst)
+        return;
+    const firstKey = r.delegate.getFirstKey?.() ?? null;
+    if (firstKey == null) {
+        const previousActiveElement = r.ref?.ownerDocument.activeElement ?? null;
+        moveVirtualFocus(r.ref);
+        if (previousActiveElement)
+            dispatchVirtualFocus(previousActiveElement, null);
+        // All keys disabled (not a loading state): stop trying.
+        if (r.manager.collection.size > 0)
+            m.shouldVirtualFocusFirst = false;
+    }
+    else {
+        r.manager.setFocusedKey(firstKey);
+        m.shouldVirtualFocusFirst = false;
+    }
+}
+/**
+ * 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 function selectableCollectionAutoFocus(options) {
+    const r = resolve(options);
+    const { manager, delegate } = r;
+    const m = memoOf(r.ref ?? options);
+    if (!options.autoFocus || !m.autoFocusPending)
+        return false;
+    let focusedKey = null;
+    if (options.autoFocus === "first")
+        focusedKey = delegate.getFirstKey?.() ?? null;
+    if (options.autoFocus === "last")
+        focusedKey = delegate.getLastKey?.() ?? null;
+    // If there are any selected keys, make the first one the new focus target.
+    const selectedKeys = manager.selectedKeys;
+    if (selectedKeys.size) {
+        for (const key of selectedKeys) {
+            if (manager.canSelectItem(key)) {
+                focusedKey = key;
+                break;
+            }
+        }
+    }
+    manager.setFocused(true);
+    manager.setFocusedKey(focusedKey);
+    if (focusedKey != null && r.selectOnFocus && !selectedKeys.size && manager.canSelectItem(focusedKey))
+        manager.replaceSelection(focusedKey);
+    // If no default focus key is selected, focus the collection itself.
+    if (focusedKey == null && !r.shouldUseVirtualFocus && r.ref)
+        focusSafely(r.ref);
+    // Wait until the collection has items to autofocus.
+    if (manager.collection.size > 0) {
+        m.autoFocusPending = false;
+        m.didAutoFocus = true;
+    }
+    syncFocus(options, null);
+    return true;
+}
+/** useSelectableItem's focus + useSelectableCollection's scroll-into-view for the focused item element. */
+function focusItem(r, element, didAutoFocus) {
+    if (!r.shouldUseVirtualFocus) {
+        if (element.ownerDocument.activeElement !== element)
+            focusSafely(element);
+    }
+    else
+        moveVirtualFocus(element);
+    const modality = getInteractionModality();
+    if ((modality === "keyboard" || didAutoFocus) && r.scrollRef) {
+        scrollIntoView(r.scrollRef, element);
+        // Avoid scroll in iOS VO, since it may cause overlay to close.
+        if (modality !== "virtual")
+            scrollIntoViewport(element, { containingElement: r.ref });
+    }
+}
+/** Virtualized collections: focus the item of `key` after the render that adds it (a microtask, then a few frames). */
+function whenRendered(r, key, didAutoFocus) {
+    let frames = 0;
+    const attempt = () => {
+        const manager = r.manager;
+        if (untrack(() => manager.focusedKey) !== key || !untrack(() => manager.isFocused) || !r.ref)
+            return;
+        const element = getItemElement(r.ref, key);
+        if (element)
+            focusItem(r, element, didAutoFocus);
+        else if (frames++ < 3)
+            requestAnimationFrame(attempt);
+    };
+    queueMicrotask(attempt);
+}
+/**
+ * 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 function syncFocus(options, previousKey, event) {
+    const r = resolve(options, event);
+    const { manager } = r;
+    const m = memoOf(r.ref ?? options);
+    const focusedKey = untrack(() => manager.focusedKey);
+    const isFocused = untrack(() => manager.isFocused);
+    const changed = focusedKey !== previousKey;
+    if (isFocused && focusedKey != null && (changed || m.didAutoFocus) && r.ref) {
+        const element = getItemElement(r.ref, focusedKey);
+        const didAutoFocus = m.didAutoFocus;
+        if (element)
+            focusItem(r, element, didAutoFocus);
+        // Virtualized: the item renders once the virtualizer persists the new focused key (RA: useSelectableItem's
+        // effect after that render) — focus and scroll it in when it appears.
+        else if (options.isVirtualized)
+            whenRendered(r, focusedKey, didAutoFocus);
+    }
+    // If the focused key becomes null (e.g. the last item is deleted), focus the whole collection.
+    if (!r.shouldUseVirtualFocus && isFocused && focusedKey == null && previousKey != null && r.ref)
+        focusSafely(r.ref);
+    m.lastFocusedKey = focusedKey;
+    m.didAutoFocus = false;
+    // Any other focused key change clears a pending "virtual focus first".
+    if (changed && manager.collection.size > 0)
+        m.shouldVirtualFocusFirst = false;
+}
+/**
+ * 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 function collectionTabIndex(manager, shouldUseVirtualFocus) {
+    if (shouldUseVirtualFocus)
+        return undefined;
+    return manager.focusedKey == null ? 0 : -1;
+}
+/**
+ * react-aria `useSelectableCollection` shape for imperative / client-only use (`addEventListener`).
+ * Resumable components wire the handler bodies above instead.
+ */
+export function useSelectableCollection(options) {
+    return {
+        collectionProps: {
+            tabIndex: collectionTabIndex(options.selectionManager, options.shouldUseVirtualFocus),
+            "data-collection": options.collectionId,
+            onKeyDownCapture: (e) => void selectableCollectionKeyDownCapture(options, e),
+            onKeyDown: (e) => void selectableCollectionKeyDown(options, e),
+            onFocusIn: (e) => selectableCollectionFocus(options, e),
+            onFocusOut: (e) => selectableCollectionBlur(options, e),
+            onMouseDown: (e) => selectableCollectionMouseDown(options, e),
+        },
+    };
+}
+export { isOpeningLink };

package/selection/selectable-item.d.ts

@@ -0,0 +1,128 @@
+import type { Key } from "../collections/types.js";
+import type { MultipleSelectionManager, PointerType } from "./manager.js";
+import { type RefLike } from "./utils.js";
+import { type Router } from "../utils/links.jsx";
+export type ItemLinkBehavior = "action" | "selection" | "override" | "none";
+export interface SelectableItemOptions {
+    /** An interface for reading and updating multiple selection state. */
+    selectionManager: MultipleSelectionManager;
+    /** A unique key for the item. */
+    key: Key;
+    /** The item element (ref or element; handlers default to the item under the event target). */
+    ref?: RefLike;
+    /** Item id (react-aria `useId(id)`). */
+    id?: string | undefined;
+    /** Select on press up instead of press down (menus). */
+    shouldSelectOnPressUp?: boolean | undefined;
+    /** Whether selection may start on another element than the one released on (menu triggers). */
+    allowsDifferentPressOrigin?: boolean | undefined;
+    /** Whether the option is contained in a virtual scroller. */
+    isVirtualized?: boolean | undefined;
+    /** Function to focus the item. */
+    focus?: (() => void) | undefined;
+    /** Whether the option should use virtual focus instead of being focused directly. */
+    shouldUseVirtualFocus?: boolean | undefined;
+    /** Whether the item is disabled. */
+    isDisabled?: boolean | undefined;
+    /** Handler that is called when a user performs an action on the item. */
+    onAction?: (() => void) | undefined;
+    /** The behavior of links in the collection. Default "action". */
+    linkBehavior?: ItemLinkBehavior | undefined;
+    /** @private RAC: actions override selection. */
+    UNSTABLE_itemBehavior?: "action" | undefined;
+    /**
+     * The router link items open through (react-aria `useRouter()`: `RouterProvider`); absent or native: the
+     * browser opens them.
+     */
+    router?: Router | undefined;
+    /**
+     * The item's own props (react-aria `manager.getItemProps(key)`): `onPressStart` / `onPressEnd` /
+     * `onPressChange` / `onPress` / `onPressUp` / `onClick` chain after the selection logic, `href` /
+     * `routerOptions` for links. Default: `selectionManager.getItemProps(key)` (a built collection's node props).
+     */
+    itemProps?: ItemPressProps | undefined;
+}
+/** Press callbacks + link props of an item (react-aria's `collectionItemProps` subset). */
+export interface ItemPressProps {
+    onPressStart?: ((e: ItemPressEventFull) => void) | undefined;
+    onPressEnd?: ((e: ItemPressEventFull) => void) | undefined;
+    onPressChange?: ((isPressed: boolean) => void) | undefined;
+    onPress?: ((e: ItemPressEventFull) => void) | undefined;
+    onPressUp?: ((e: ItemPressEventFull) => void) | undefined;
+    onClick?: ((e: MouseEvent) => void) | undefined;
+    href?: string | undefined;
+    routerOptions?: Record<string, unknown> | undefined;
+    [key: string]: unknown;
+}
+/** The press event item press callbacks receive (react-aria PressEvent fields). */
+export interface ItemPressEventFull extends ItemPressEvent {
+    type: "pressstart" | "pressend" | "pressup" | "press";
+    target: Element;
+    x: number;
+    y: number;
+    continuePropagation(): void;
+}
+export interface SelectableItemStates {
+    /** Whether the item is currently in a pressed state. */
+    isPressed: boolean;
+    /** Whether the item is currently selected. */
+    isSelected: boolean;
+    /** Whether the item is currently focused. */
+    isFocused: boolean;
+    /** Whether the item is non-interactive (selection and actions disabled, not focusable). */
+    isDisabled: boolean;
+    /** Whether the item may be selected. */
+    allowsSelection: boolean;
+    /** Whether the item has an action (onAction or link). */
+    hasAction: boolean;
+}
+/** A press event as the selection logic reads it (react-aria PressEvent subset). */
+export interface ItemPressEvent {
+    pointerType: PointerType;
+    key?: string | undefined;
+    shiftKey: boolean;
+    ctrlKey: boolean;
+    metaKey: boolean;
+    altKey: boolean;
+}
+/** Item state flags (react-aria `useSelectableItem` return minus props). Reads state: use in bindings. */
+export declare function selectableItemStates(options: SelectableItemOptions): SelectableItemStates;
+/**
+ * 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 declare function selectableItemAttrs(options: SelectableItemOptions): Record<string, unknown>;
+/** Long press threshold (react-aria useLongPress default). */
+export declare const LONG_PRESS_THRESHOLD_MS = 500;
+/** pointerdown on the item (press start for mouse / pen / touch; long press timer on touch). */
+export declare function selectableItemPointerDown(options: SelectableItemOptions, e: PointerEvent): void;
+/** pointerup on the item (press up; cancels a pending long press). */
+export declare function selectableItemPointerUp(options: SelectableItemOptions, e: PointerEvent): void;
+/** pointercancel / pointerleave: drop the press. */
+export declare function selectableItemPointerCancel(options: SelectableItemOptions, e: PointerEvent): void;
+/**
+ * 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 declare function selectableItemClick(options: SelectableItemOptions, e: MouseEvent): void;
+/** keydown on the item: Space / Enter start a keyboard press. */
+export declare function selectableItemKeyDown(options: SelectableItemOptions, e: KeyboardEvent): void;
+/** keyup on the item: Space / Enter complete a keyboard press. */
+export declare function selectableItemKeyUp(options: SelectableItemOptions, e: KeyboardEvent): void;
+/** dblclick: with selectionBehavior "replace", a mouse double click performs the action. */
+export declare function selectableItemDoubleClick(options: SelectableItemOptions, e: MouseEvent): void;
+/** focus on the item element itself: it becomes the focused key. */
+export declare function selectableItemFocus(options: SelectableItemOptions, e: FocusEvent): void;
+/** dragstart: no native drag after a touch long press that selected. */
+export declare function selectableItemDragStart(options: SelectableItemOptions, e: DragEvent): void;
+/**
+ * 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 declare function focusSelectableItem(options: SelectableItemOptions): void;
+/** The collection item element containing `target` (inside `collection`), with its key. */
+export declare function closestItem(collection: Element, target: EventTarget | null, selector?: string): {
+    element: HTMLElement;
+    key: Key;
+} | null;