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

package/tree/intl.d.ts

@@ -0,0 +1,2 @@
+import type { LocalizedStrings } from "../_adapters/intl.js";
+export declare const strings: LocalizedStrings;

package/tree/intl.js

@@ -0,0 +1,36 @@
+export const strings = {
+    "ar-AE": { collapse: "طي", expand: "تمديد" },
+    "bg-BG": { collapse: "Свиване", expand: "Разширяване" },
+    "cs-CZ": { collapse: "Sbalit", expand: "Roztáhnout" },
+    "da-DK": { collapse: "Skjul", expand: "Udvid" },
+    "de-DE": { collapse: "Reduzieren", expand: "Erweitern" },
+    "el-GR": { collapse: "Σύμπτυξη", expand: "Ανάπτυξη" },
+    "en-US": { expand: "Expand", collapse: "Collapse" },
+    "es-ES": { collapse: "Contraer", expand: "Expandir" },
+    "et-EE": { collapse: "Ahenda", expand: "Laienda" },
+    "fi-FI": { collapse: "Pienennä", expand: "Laajenna" },
+    "fr-FR": { collapse: "Réduire", expand: "Développer" },
+    "he-IL": { collapse: "כווץ", expand: "הרחב" },
+    "hr-HR": { collapse: "Sažmi", expand: "Proširi" },
+    "hu-HU": { collapse: "Összecsukás", expand: "Kibontás" },
+    "it-IT": { collapse: "Comprimi", expand: "Espandi" },
+    "ja-JP": { collapse: "折りたたむ", expand: "展開" },
+    "ko-KR": { collapse: "접기", expand: "펼치기" },
+    "lt-LT": { collapse: "Sutraukti", expand: "Išskleisti" },
+    "lv-LV": { collapse: "Sakļaut", expand: "Izvērst" },
+    "nb-NO": { collapse: "Skjul", expand: "Utvid" },
+    "nl-NL": { collapse: "Samenvouwen", expand: "Uitvouwen" },
+    "pl-PL": { collapse: "Zwiń", expand: "Rozwiń" },
+    "pt-BR": { collapse: "Recolher", expand: "Expandir" },
+    "pt-PT": { collapse: "Colapsar", expand: "Expandir" },
+    "ro-RO": { collapse: "Restrângeți", expand: "Extindeți" },
+    "ru-RU": { collapse: "Свернуть", expand: "Развернуть" },
+    "sk-SK": { collapse: "Zbaliť", expand: "Rozbaliť" },
+    "sl-SI": { collapse: "Strni", expand: "Razširi" },
+    "sr-SP": { collapse: " Skupi", expand: "Proširi" },
+    "sv-SE": { collapse: "Dölj", expand: "Expandera" },
+    "tr-TR": { collapse: "Daralt", expand: "Genişlet" },
+    "uk-UA": { collapse: "Згорнути", expand: "Розгорнути" },
+    "zh-CN": { collapse: "折叠", expand: "扩展" },
+    "zh-TW": { collapse: "收合", expand: "展開" },
+};

package/tree/navigation-context.d.ts

@@ -0,0 +1,44 @@
+import { type Signal } from "@rivetjs/reactivity";
+import type { Collection, Key, Node } from "../collections/types.js";
+import type { RouterOptions } from "../utils/links.jsx";
+/** NavigationTree → its items: the current route and the focus-sync bookkeeping. */
+export interface InternalNavigationTreeContextValue {
+    /** The route that is currently selected (accessor). */
+    selectedRoute: () => string | null | undefined;
+    /** The last route the focused key was synced to; dedupes the focus sync across items. */
+    syncedRoute: {
+        current: string | undefined;
+    };
+}
+export declare const InternalNavigationTreeContext: import("@rivetjs/reactivity").Context<InternalNavigationTreeContextValue | null>;
+/** The link props a NavigationTreeItem hands its NavigationTreeItemContent's `Link`. */
+export interface NavigationTreeItemLinkContextValue {
+    href?: string | undefined;
+    hrefLang?: string | undefined;
+    target?: string | undefined;
+    rel?: string | undefined;
+    download?: string | boolean | undefined;
+    ping?: string | undefined;
+    referrerPolicy?: ReferrerPolicy | undefined;
+    routerOptions?: RouterOptions | undefined;
+    isCurrent: () => boolean;
+    /** Whether the item's link (as opposed to another focusable child such as a button) is focused. */
+    isLinkFocused: Signal<boolean>;
+}
+export declare const NavigationTreeItemLinkContext: import("@rivetjs/reactivity").Context<NavigationTreeItemLinkContextValue | null>;
+/** RAC `NavigationTreeItemStateContext` (Rivet: `isCurrentAncestor` is an accessor). */
+export declare const NavigationTreeItemStateContext: import("@rivetjs/reactivity").Context<{
+    isCurrentAncestor: () => boolean;
+}>;
+/** The collection key of the item whose href matches `route`, or null. */
+export declare function findKeyForRoute(collection: Collection<Node<unknown>>, route: string): Key | null;
+/**
+ * Walks up from `key` to the closest ancestor that is actually rendered (all ancestors expanded).
+ * Returns `key` unchanged when already visible. A collapsed ancestor hides everything beneath it,
+ * so the highest collapsed ancestor is the closest visible row.
+ */
+export declare function closestVisibleKey(collection: Collection<Node<unknown>>, expandedKeys: Set<Key>, key: Key): Key;
+/** The set of collection keys that are ancestors of the item matching `selectedRoute`. */
+export declare function getSelectedAncestors(collection: Collection<Node<unknown>>, selectedRoute: string): Set<Key>;
+/** Whether the row `id` is an ancestor of the item matching `selectedRoute`. */
+export declare function hasSelectedDescendant(id: Key | undefined, collection: Collection<Node<unknown>>, selectedRoute: string | undefined | null): boolean;

package/tree/navigation-context.jsx

@@ -0,0 +1,63 @@
+// Ported from react-aria-components (src/NavigationTree.tsx: InternalNavigationTreeContext,
+// NavigationTreeItemLinkContext, NavigationTreeItemStateContext, findKeyForRoute, closestVisibleKey,
+// getSelectedAncestors), Apache-2.0, © Adobe.
+// Rivet:
+// - Lives next to TreeItem (not in `navigation-tree/`): RAC NavigationTreeItem wraps TreeItem's `render`
+//   prop to add `data-current` / `data-current-ancestor` / link focus-visible and a context around the row
+//   children. Rivet does not wrap TreeItem's `render` here: TreeItem itself applies them when an enclosing NavigationTree
+//   provides `InternalNavigationTreeContext` (render props stay accessors).
+// - Contexts are resumable (`rv-navigation-tree*`); values are plain data, signals and inline arrows.
+// - `syncedRoute` is a plain `{ current }` object (RAC `syncedRouteRef`).
+import { createContext } from "@rivetjs/reactivity";
+import { resumableContext } from "../slots/index.jsx";
+export const InternalNavigationTreeContext = resumableContext(createContext(null, { id: "rv-navigation-tree" }));
+export const NavigationTreeItemLinkContext = resumableContext(createContext(null, { id: "rv-navigation-tree-item-link" }));
+/** RAC `NavigationTreeItemStateContext` (Rivet: `isCurrentAncestor` is an accessor). */
+export const NavigationTreeItemStateContext = resumableContext(createContext({ isCurrentAncestor: () => false }, { id: "rv-navigation-tree-item-state" }));
+/** The collection key of the item whose href matches `route`, or null. */
+export function findKeyForRoute(collection, route) {
+    for (const key of collection.getKeys()) {
+        if (collection.getItem(key)?.props?.href === route)
+            return key;
+    }
+    return null;
+}
+/**
+ * Walks up from `key` to the closest ancestor that is actually rendered (all ancestors expanded).
+ * Returns `key` unchanged when already visible. A collapsed ancestor hides everything beneath it,
+ * so the highest collapsed ancestor is the closest visible row.
+ */
+export function closestVisibleKey(collection, expandedKeys, key) {
+    let target = key;
+    let node = collection.getItem(key);
+    while (node?.parentKey != null) {
+        const parent = collection.getItem(node.parentKey);
+        if (parent?.type === "item" && !expandedKeys.has(node.parentKey))
+            target = node.parentKey;
+        node = parent;
+    }
+    return target;
+}
+// Cache so each row doesn't have to walk up the tree every time.
+const selectedAncestorsCache = new WeakMap();
+/** The set of collection keys that are ancestors of the item matching `selectedRoute`. */
+export function getSelectedAncestors(collection, selectedRoute) {
+    const cached = selectedAncestorsCache.get(collection);
+    if (cached && cached.selection === selectedRoute)
+        return cached.ancestors;
+    const matchKey = findKeyForRoute(collection, selectedRoute);
+    const ancestors = new Set();
+    let node = matchKey != null ? collection.getItem(matchKey) : null;
+    while (node?.parentKey != null && !ancestors.has(node.parentKey)) {
+        ancestors.add(node.parentKey);
+        node = collection.getItem(node.parentKey);
+    }
+    selectedAncestorsCache.set(collection, { selection: selectedRoute, ancestors });
+    return ancestors;
+}
+/** Whether the row `id` is an ancestor of the item matching `selectedRoute`. */
+export function hasSelectedDescendant(id, collection, selectedRoute) {
+    if (id == null || selectedRoute == null)
+        return false;
+    return getSelectedAncestors(collection, selectedRoute).has(id);
+}

package/tree/tree-key-manager.d.ts

@@ -0,0 +1,149 @@
+import { Subject, type Subscription } from "../a11y/key-manager.js";
+/** Anything with an RxJS-style `subscribe` (Rivet `Subject`, an RxJS Observable…). */
+export interface Subscribable<T> {
+    subscribe(next: (value: T) => void): Subscription | {
+        unsubscribe(): void;
+    } | (() => void) | void;
+}
+/** Represents an item within a tree that can be passed to a TreeKeyManager. */
+export interface TreeKeyManagerItem {
+    /** Whether the item is disabled. */
+    isDisabled?: (() => boolean) | boolean;
+    /** The user-facing label for this item. */
+    getLabel?(): string;
+    /** Perform the main action (i.e. selection) for this item. */
+    activate(): void;
+    /** Retrieves the parent for this item. This is `null` if there is no parent. */
+    getParent(): TreeKeyManagerItem | null;
+    /** Retrieves the children for this item. */
+    getChildren(): TreeKeyManagerItem[] | Subscribable<TreeKeyManagerItem[]>;
+    /** Determines if the item is currently expanded. */
+    isExpanded: (() => boolean) | boolean;
+    /** Collapses the item, hiding its children. */
+    collapse(): void;
+    /** Expands the item, showing its children. */
+    expand(): void;
+    /** Focuses the item. This should provide some indication to the user that this item is focused. */
+    focus(): void;
+    /** Unfocus the item. This should remove the focus state. */
+    unfocus(): void;
+    /** Sets the item to be focusable without actually focusing it. */
+    makeFocusable?(): void;
+}
+/** Configuration for the TreeKeyManager. */
+export interface TreeKeyManagerOptions<T extends TreeKeyManagerItem> {
+    /** If true, the key manager calls `activate` in addition to `focus` when an item is focused. */
+    shouldActivationFollowFocus?: boolean;
+    /** The direction in which the tree items are laid out horizontally (which key expands / collapses). */
+    horizontalOrientation?: "rtl" | "ltr";
+    /** If provided, navigation "skips" over items that pass the given predicate. */
+    skipPredicate?: (item: T) => boolean;
+    /** Determines how the key manager decides whether two items are equivalent. */
+    trackBy?: (treeItem: T) => unknown;
+    /** Enables typeahead; a number is the debounce interval, `true` the default (200 ms). */
+    typeAheadDebounceInterval?: true | number;
+}
+export interface TreeKeyManagerStrategy<T extends TreeKeyManagerItem> {
+    /** Stream that emits any time the focused item changes. */
+    readonly change: Subject<T | null>;
+    /** Cleans up the key manager. */
+    destroy(): void;
+    /** Handles a keyboard event on the tree. */
+    onKeydown(event: KeyboardEvent): void;
+    /** Index of the currently active item. */
+    getActiveItemIndex(): number | null;
+    /** The currently active item. */
+    getActiveItem(): T | null;
+    /** Focus the provided item (by index, or by `trackBy` equality). */
+    focusItem(index: number, options?: {
+        emitChangeEvent?: boolean;
+    }): void;
+    focusItem(item: T, options?: {
+        emitChangeEvent?: boolean;
+    }): void;
+    focusItem(itemOrIndex: number | T, options?: {
+        emitChangeEvent?: boolean;
+    }): void;
+}
+export type TreeKeyManagerItems<T> = T[] | readonly T[] | (() => T[] | readonly T[]) | Subscribable<T[]>;
+export type TreeKeyManagerFactory<T extends TreeKeyManagerItem> = (items: TreeKeyManagerItems<T>, options: TreeKeyManagerOptions<T>) => TreeKeyManagerStrategy<T>;
+/**
+ * Manages keyboard events for trees: given a list of tree items, sets the active item, focus,
+ * handles expansion and typeahead when keyboard events occur.
+ */
+export declare class TreeKeyManager<T extends TreeKeyManagerItem> implements TreeKeyManagerStrategy<T> {
+    /** The index of the currently active (focused) item. */
+    private _activeItemIndex;
+    /** The currently active (focused) item. */
+    private _activeItem;
+    /** Whether or not we activate the item when it's focused. */
+    private _shouldActivationFollowFocus;
+    /** In `rtl` mode, the behavior of Left and Right arrow are switched. */
+    private _horizontalOrientation;
+    /**
+     * Skips nothing by default, to keep tree items focusable when disabled (ARIA guidelines:
+     * focusability of disabled controls).
+     */
+    private _skipPredicateFn;
+    /** Function to determine equivalent items. */
+    private _trackByFn;
+    /** Synchronous cache of the items to manage. */
+    private _items;
+    private _typeahead?;
+    private _typeaheadSubscription;
+    private _hasInitialFocused;
+    private _effect;
+    private _itemsSubscription;
+    private _initializeFocus;
+    /**
+     * @param items Items to manage: an array, an accessor / signal of one, or a subscribable.
+     * @param config By default 'ltr', skips nothing, only calls `focus` (not `activate`) on focus;
+     * `typeAheadDebounceInterval: true` uses a 200 ms interval.
+     */
+    constructor(items: TreeKeyManagerItems<T>, config: TreeKeyManagerOptions<T>);
+    /** Stream that emits any time the focused item changes. */
+    readonly change: Subject<T | null>;
+    /** Cleans up the key manager. */
+    destroy(): void;
+    /** Handles a keyboard event on the tree. */
+    onKeydown(event: KeyboardEvent): void;
+    /** Index of the currently active item. */
+    getActiveItemIndex(): number | null;
+    /** The currently active item. */
+    getActiveItem(): T | null;
+    /** Called when the list of items has changed. */
+    private _itemsChanged;
+    /** Focus the first available item. */
+    private _focusFirstItem;
+    /** Focus the last available item. */
+    private _focusLastItem;
+    /** Focus the next available item. */
+    private _focusNextItem;
+    /** Focus the previous available item. */
+    private _focusPreviousItem;
+    /** Focus the provided item by index, or by `trackBy` equality. */
+    focusItem(index: number, options?: {
+        emitChangeEvent?: boolean;
+    }): void;
+    focusItem(item: T, options?: {
+        emitChangeEvent?: boolean;
+    }): void;
+    focusItem(itemOrIndex: number | T, options?: {
+        emitChangeEvent?: boolean;
+    }): void;
+    private _updateActiveItemIndex;
+    private _setTypeAhead;
+    private _findNextAvailableItemIndex;
+    private _findPreviousAvailableItemIndex;
+    /** If the item is expanded, collapse it; otherwise focus the parent. */
+    private _collapseCurrentItem;
+    /** If the item is collapsed, expand it; otherwise focus the first child. */
+    private _expandCurrentItem;
+    private _isCurrentItemExpanded;
+    private _isItemDisabled;
+    /** For all items that are the same level as the current item, expand those items. */
+    private _expandAllItemsAtCurrentItemLevel;
+    private _activateCurrentItem;
+}
+/** The default key manager factory (Angular's `TREE_KEY_MANAGER` injection token default). */
+export declare const TREE_KEY_MANAGER: TreeKeyManagerFactory<any>;

package/tree/tree-key-manager.js

@@ -0,0 +1,336 @@
+// Ported from Angular CDK a11y (src/cdk/a11y/key-manager/tree-key-manager.ts,
+// tree-key-manager-strategy.ts), MIT, © Google LLC.
+//
+// TreeKeyManager: keyboard navigation of a tree — Up / Down move, Right / Left expand / collapse or
+// move to the first child / parent (swapped in RTL), Home / End, Enter / Space activate, `*` expands
+// all siblings of the active item, debounced typeahead, Tab returns early, `change` stream.
+// Rivet:
+// - `QueryList` / `Observable<T[]>` items → an array, an accessor / signal (QueryList semantics:
+//   tracked with an effect, later runs = `changes`), or a subscribable (`{ subscribe(fn) }`).
+// - `getChildren()` may return an array or a subscribable; RxJS `take(1)` → first emission only.
+// - `TREE_KEY_MANAGER` InjectionToken → `TREE_KEY_MANAGER` default factory constant (no DI).
+// - Instances are browser-side objects: create them in a handler or client effect.
+import { effect } from "@rivetjs/reactivity";
+import { Subject, Typeahead } from "../a11y/key-manager.js";
+const isSubscribable = (value) => value != null && typeof value === "object" && typeof value.subscribe === "function";
+/** First emission of an array or subscribable (RxJS `coerceObservable(x).pipe(take(1))`). */
+function takeFirst(value, next) {
+    if (!isSubscribable(value))
+        return next(value);
+    let done = false;
+    let sync = true;
+    let subscription = undefined;
+    const unsubscribe = () => {
+        if (typeof subscription === "function")
+            subscription();
+        else
+            subscription?.unsubscribe();
+    };
+    subscription = value.subscribe((items) => {
+        if (done)
+            return;
+        done = true;
+        if (!sync)
+            unsubscribe();
+        next(items);
+    });
+    sync = false;
+    if (done)
+        unsubscribe();
+}
+/**
+ * Manages keyboard events for trees: given a list of tree items, sets the active item, focus,
+ * handles expansion and typeahead when keyboard events occur.
+ */
+export class TreeKeyManager {
+    /** The index of the currently active (focused) item. */
+    _activeItemIndex = -1;
+    /** The currently active (focused) item. */
+    _activeItem = null;
+    /** Whether or not we activate the item when it's focused. */
+    _shouldActivationFollowFocus = false;
+    /** In `rtl` mode, the behavior of Left and Right arrow are switched. */
+    _horizontalOrientation = "ltr";
+    /**
+     * Skips nothing by default, to keep tree items focusable when disabled (ARIA guidelines:
+     * focusability of disabled controls).
+     */
+    _skipPredicateFn = (_item) => false;
+    /** Function to determine equivalent items. */
+    _trackByFn = (item) => item;
+    /** Synchronous cache of the items to manage. */
+    _items = [];
+    _typeahead;
+    _typeaheadSubscription = { unsubscribe() { } };
+    _hasInitialFocused = false;
+    _effect;
+    _itemsSubscription = undefined;
+    _initializeFocus() {
+        if (this._hasInitialFocused || this._items.length === 0)
+            return;
+        let activeIndex = 0;
+        for (let i = 0; i < this._items.length; i++) {
+            if (!this._skipPredicateFn(this._items[i]) && !this._isItemDisabled(this._items[i])) {
+                activeIndex = i;
+                break;
+            }
+        }
+        const activeItem = this._items[activeIndex];
+        // `makeFocusable`: the item only becomes focusable, it doesn't capture focus (#29628).
+        if (activeItem.makeFocusable) {
+            this._activeItem?.unfocus();
+            this._activeItemIndex = activeIndex;
+            this._activeItem = activeItem;
+            this._typeahead?.setCurrentSelectedItemIndex(activeIndex);
+            activeItem.makeFocusable();
+        }
+        else {
+            // Backwards compatibility for items that don't implement `makeFocusable`.
+            this.focusItem(activeIndex);
+        }
+        this._hasInitialFocused = true;
+    }
+    /**
+     * @param items Items to manage: an array, an accessor / signal of one, or a subscribable.
+     * @param config By default 'ltr', skips nothing, only calls `focus` (not `activate`) on focus;
+     * `typeAheadDebounceInterval: true` uses a 200 ms interval.
+     */
+    constructor(items, config) {
+        // Items may be an array or a live source because the consumer may not have a QueryList of them.
+        if (typeof items === "function") {
+            // QueryList: the current items now, `_itemsChanged` on every later change.
+            let first = true;
+            this._effect = effect(() => {
+                const next = [...items()];
+                if (first) {
+                    first = false;
+                    this._items = next;
+                }
+                else
+                    this._itemsChanged(next);
+            });
+        }
+        else if (isSubscribable(items)) {
+            this._itemsSubscription = items.subscribe((newItems) => this._itemsChanged(newItems));
+        }
+        else {
+            this._items = items;
+            this._initializeFocus();
+        }
+        if (typeof config.shouldActivationFollowFocus === "boolean")
+            this._shouldActivationFollowFocus = config.shouldActivationFollowFocus;
+        if (config.horizontalOrientation)
+            this._horizontalOrientation = config.horizontalOrientation;
+        if (config.skipPredicate)
+            this._skipPredicateFn = config.skipPredicate;
+        if (config.trackBy)
+            this._trackByFn = config.trackBy;
+        if (typeof config.typeAheadDebounceInterval !== "undefined")
+            this._setTypeAhead(config.typeAheadDebounceInterval);
+    }
+    /** Stream that emits any time the focused item changes. */
+    change = new Subject();
+    /** Cleans up the key manager. */
+    destroy() {
+        this._typeaheadSubscription.unsubscribe();
+        this._typeahead?.destroy();
+        this._effect?.();
+        if (typeof this._itemsSubscription === "function")
+            this._itemsSubscription();
+        else
+            this._itemsSubscription?.unsubscribe();
+        this.change.complete();
+    }
+    /** Handles a keyboard event on the tree. */
+    onKeydown(event) {
+        const key = event.key;
+        switch (key) {
+            case "Tab":
+                // Return early, so Tab actually tabs out of the tree.
+                return;
+            case "ArrowDown":
+                this._focusNextItem();
+                break;
+            case "ArrowUp":
+                this._focusPreviousItem();
+                break;
+            case "ArrowRight":
+                if (this._horizontalOrientation === "rtl")
+                    this._collapseCurrentItem();
+                else
+                    this._expandCurrentItem();
+                break;
+            case "ArrowLeft":
+                if (this._horizontalOrientation === "rtl")
+                    this._expandCurrentItem();
+                else
+                    this._collapseCurrentItem();
+                break;
+            case "Home":
+                this._focusFirstItem();
+                break;
+            case "End":
+                this._focusLastItem();
+                break;
+            case "Enter":
+            case " ":
+                this._activateCurrentItem();
+                break;
+            default:
+                if (event.key === "*") {
+                    this._expandAllItemsAtCurrentItemLevel();
+                    break;
+                }
+                this._typeahead?.handleKey(event);
+                // Don't prevent the default action of non-navigational keys or reset the typed letters.
+                return;
+        }
+        // Reset the typeahead since the user has used a navigational key.
+        this._typeahead?.reset();
+        event.preventDefault();
+    }
+    /** Index of the currently active item. */
+    getActiveItemIndex() {
+        return this._activeItemIndex;
+    }
+    /** The currently active item. */
+    getActiveItem() {
+        return this._activeItem;
+    }
+    /** Called when the list of items has changed. */
+    _itemsChanged(newItems) {
+        if (this._hasInitialFocused && this._activeItem && !newItems.includes(this._activeItem)) {
+            this._activeItem = null;
+            this._hasInitialFocused = false;
+        }
+        this._items = newItems;
+        this._typeahead?.setItems(this._items);
+        this._updateActiveItemIndex(this._items);
+        this._initializeFocus();
+    }
+    /** Focus the first available item. */
+    _focusFirstItem() {
+        this.focusItem(this._findNextAvailableItemIndex(-1));
+    }
+    /** Focus the last available item. */
+    _focusLastItem() {
+        this.focusItem(this._findPreviousAvailableItemIndex(this._items.length));
+    }
+    /** Focus the next available item. */
+    _focusNextItem() {
+        this.focusItem(this._findNextAvailableItemIndex(this._activeItemIndex));
+    }
+    /** Focus the previous available item. */
+    _focusPreviousItem() {
+        this.focusItem(this._findPreviousAvailableItemIndex(this._activeItemIndex));
+    }
+    focusItem(itemOrIndex, options = {}) {
+        options.emitChangeEvent ??= true;
+        const index = typeof itemOrIndex === "number" ? itemOrIndex : this._items.findIndex((item) => this._trackByFn(item) === this._trackByFn(itemOrIndex));
+        if (index < 0 || index >= this._items.length)
+            return;
+        const activeItem = this._items[index];
+        // If we're just setting the same item, don't re-call activate or focus.
+        if (this._activeItem !== null && this._trackByFn(activeItem) === this._trackByFn(this._activeItem))
+            return;
+        const previousActiveItem = this._activeItem;
+        this._activeItem = activeItem ?? null;
+        this._activeItemIndex = index;
+        this._typeahead?.setCurrentSelectedItemIndex(index);
+        this._activeItem?.focus();
+        previousActiveItem?.unfocus();
+        if (options.emitChangeEvent)
+            this.change.next(this._activeItem);
+        if (this._shouldActivationFollowFocus)
+            this._activateCurrentItem();
+    }
+    _updateActiveItemIndex(newItems) {
+        const activeItem = this._activeItem;
+        if (!activeItem)
+            return;
+        const newIndex = newItems.findIndex((item) => this._trackByFn(item) === this._trackByFn(activeItem));
+        if (newIndex > -1 && newIndex !== this._activeItemIndex) {
+            this._activeItemIndex = newIndex;
+            this._typeahead?.setCurrentSelectedItemIndex(newIndex);
+        }
+    }
+    _setTypeAhead(debounceInterval) {
+        this._typeahead = new Typeahead(this._items, {
+            debounceInterval: typeof debounceInterval === "number" ? debounceInterval : undefined,
+            skipPredicate: (item) => this._skipPredicateFn(item),
+        });
+        this._typeaheadSubscription = this._typeahead.selectedItem.subscribe((item) => {
+            this.focusItem(item);
+        });
+    }
+    _findNextAvailableItemIndex(startingIndex) {
+        for (let i = startingIndex + 1; i < this._items.length; i++) {
+            if (!this._skipPredicateFn(this._items[i]))
+                return i;
+        }
+        return startingIndex;
+    }
+    _findPreviousAvailableItemIndex(startingIndex) {
+        for (let i = startingIndex - 1; i >= 0; i--) {
+            if (!this._skipPredicateFn(this._items[i]))
+                return i;
+        }
+        return startingIndex;
+    }
+    /** If the item is expanded, collapse it; otherwise focus the parent. */
+    _collapseCurrentItem() {
+        if (!this._activeItem)
+            return;
+        if (this._isCurrentItemExpanded()) {
+            this._activeItem.collapse();
+        }
+        else {
+            const parent = this._activeItem.getParent();
+            if (!parent || this._skipPredicateFn(parent))
+                return;
+            this.focusItem(parent);
+        }
+    }
+    /** If the item is collapsed, expand it; otherwise focus the first child. */
+    _expandCurrentItem() {
+        if (!this._activeItem)
+            return;
+        if (!this._isCurrentItemExpanded()) {
+            this._activeItem.expand();
+        }
+        else {
+            takeFirst(this._activeItem.getChildren(), (children) => {
+                const firstChild = children.find((child) => !this._skipPredicateFn(child));
+                if (!firstChild)
+                    return;
+                this.focusItem(firstChild);
+            });
+        }
+    }
+    _isCurrentItemExpanded() {
+        if (!this._activeItem)
+            return false;
+        return typeof this._activeItem.isExpanded === "boolean" ? this._activeItem.isExpanded : this._activeItem.isExpanded();
+    }
+    _isItemDisabled(item) {
+        return typeof item.isDisabled === "boolean" ? item.isDisabled : item.isDisabled?.();
+    }
+    /** For all items that are the same level as the current item, expand those items. */
+    _expandAllItemsAtCurrentItemLevel() {
+        if (!this._activeItem)
+            return;
+        const parent = this._activeItem.getParent();
+        const itemsToExpand = !parent
+            ? this._items.filter((item) => item.getParent() === null)
+            : parent.getChildren();
+        takeFirst(itemsToExpand, (items) => {
+            for (const item of items)
+                item.expand();
+        });
+    }
+    _activateCurrentItem() {
+        this._activeItem?.activate();
+    }
+}
+/** The default key manager factory (Angular's `TREE_KEY_MANAGER` injection token default). */
+export const TREE_KEY_MANAGER = (items, options) => new TreeKeyManager(items, options);

package/utils/animation.d.ts

@@ -0,0 +1,32 @@
+/** An element accessor: a `ref()` from `@rivetjs/runtime/dom`, or a function returning the element. */
+export type AnimationRef = () => HTMLElement | null | undefined;
+type MaybeAccessor<T> = T | (() => T);
+/**
+ * Entry animation state of `ref` (react-aria `useEnterAnimation`): true from creation until the element's
+ * running CSS animations / transitions and the promise `onEnter` returns have finished. While `isReady`
+ * is false the element is hidden with non-layout styles and the animation waits (popovers before placement).
+ */
+export declare function createEnterAnimation(ref: AnimationRef, isReady?: MaybeAccessor<boolean>, onEnter?: (element: HTMLElement) => void | Promise<void>): () => boolean;
+/**
+ * Exit animation state of `ref` (react-aria `useExitAnimation`): true from the moment `isOpen` turns false
+ * until the element's running animations and the promise `onExit` returns have finished — keep the element
+ * mounted while it is true. Reopening interrupts the exit.
+ */
+export declare function createExitAnimation(ref: AnimationRef, isOpen: MaybeAccessor<boolean>, onExit?: (element: HTMLElement) => void | Promise<void>): () => boolean;
+/** The state half of {@link createExitAnimation}: `isExiting` + `end` (no client effect). */
+export interface ExitAnimationState {
+    /** True while exiting (keep the element mounted). */
+    readonly isExiting: () => boolean;
+    /** Ends the running exit (closes the state machine). */
+    readonly end: () => void;
+}
+/**
+ * Rivet: {@link createExitAnimation} without its client effect — create the state where the open / exiting
+ * condition is read, call {@link watchExitAnimation} where the element exists (inside the branch that stays
+ * mounted while exiting). A closed overlay then records no client effect, so a resumed page with closed
+ * tooltips does not boot the runtime at load.
+ */
+export declare function createExitAnimationState(isOpen: MaybeAccessor<boolean>): ExitAnimationState;
+/** The effect half of {@link createExitAnimation}: waits for the exit animations of `ref`, then `exit.end()`. */
+export declare function watchExitAnimation(ref: AnimationRef, exit: ExitAnimationState, onExit?: (element: HTMLElement) => void | Promise<void>): void;
+export {};