entasis 0.11.0 → 0.12.0

package/dist/utils/useNavigation.svelte.js

@@ -1,363 +1,686 @@
-import { SvelteSet } from 'svelte/reactivity';
+/* eslint-disable svelte/prefer-svelte-reactivity -- the item registry and its index are DOM bookkeeping, not reactive state; `revision` publishes their changes. */
 import { useKeyDown } from './useKeyDown.svelte.js';
 import { on } from 'svelte/events';
 import { onDestroy, untrack } from 'svelte';
 import { usePointerDown } from './usePointerDown.svelte.js';
 import { useDirection } from './useDirection.svelte.js';
-import { createTypeahead } from './typeahead.js';
+import { createTypeahead, isTextEntry } from './typeahead.js';
 import { createId } from './id.js';
+import { prefersReducedMotion } from './motion.svelte.js';
+import { clampRovingKey, createRovingRestoreVersion } from './useRovingRegistry.svelte.js';
+// Every live navigation container, so a list ignores keys that a list nested inside it owns.
+const containers = new WeakSet();
+const byDocumentPosition = (a, b) => {
+    const position = a.compareDocumentPosition(b);
+    if (position & Node.DOCUMENT_POSITION_FOLLOWING)
+        return -1;
+    if (position & Node.DOCUMENT_POSITION_PRECEDING)
+        return 1;
+    return 0;
+};
+// A keyed reorder moves nodes: each moved node is removed and added again in one batch.
+const hasMovedNode = (records) => {
+    const removed = new Set();
+    for (const record of records)
+        record.removedNodes.forEach((node) => removed.add(node));
+    if (removed.size === 0)
+        return false;
+    return records.some((record) => Array.from(record.addedNodes).some((node) => removed.has(node)));
+};
+/** An attribute record whose attribute holds the value it had before the write. */
+const isUnchangedAttribute = (record) => record.type === 'attributes' &&
+    record.attributeName !== null &&
+    record.target instanceof Element &&
+    record.oldValue === record.target.getAttribute(record.attributeName);
+/** Writes an attribute only when its value differs, so unchanged items cost a read, not a write. */
+const setAttribute = (node, name, value) => {
+    if (node.getAttribute(name) !== value)
+        node.setAttribute(name, value);
+};
+const removeAttribute = (node, name) => {
+    if (node.hasAttribute(name))
+        node.removeAttribute(name);
+};
+// The caret sits at the start or end of a field with nothing selected, so an arrow pointing past
+// that edge has no text left to move through.
+const isCaretAtEdge = (event, edge) => {
+    if (event.shiftKey)
+        return false; // Shift+arrow extends a selection.
+    const field = event.target;
+    if (field instanceof HTMLInputElement || field instanceof HTMLTextAreaElement) {
+        const { selectionStart, selectionEnd, value } = field;
+        // Fields without a caret API (number, date) keep their arrows.
+        if (selectionStart === null || selectionEnd === null || selectionStart !== selectionEnd) {
+            return false;
+        }
+        return edge === 'start' ? selectionStart === 0 : selectionEnd === value.length;
+    }
+    if (!(field instanceof HTMLElement))
+        return false;
+    const selection = field.ownerDocument.getSelection();
+    if (!selection?.isCollapsed || selection.rangeCount === 0)
+        return false;
+    const caret = selection.getRangeAt(0);
+    const rest = field.ownerDocument.createRange();
+    rest.selectNodeContents(field);
+    if (edge === 'start')
+        rest.setEnd(caret.startContainer, caret.startOffset);
+    else
+        rest.setStart(caret.endContainer, caret.endOffset);
+    return rest.toString().length === 0;
+};
 export const useNavigation = (opts) => {
-    const itemsSet = new SvelteSet();
+    // The registered items in document order, and each one's position in that order. Mounting
+    // registers in document order, so registration appends; a registration out of order or a node
+    // moved inside the container marks the order stale, and the next read checks it with one pass
+    // over adjacent pairs, sorting only when that pass finds a pair out of order.
+    const registered = [];
+    const positions = new Map();
+    let orderStale = false;
+    let positionsStale = false;
+    // Bumped whenever membership, order or an item's disabled/hidden state changes; every
+    // reactive read of the list (the focused index, the attribute sync) depends on it.
+    let revision = $state(0);
+    let sequence = 0;
     let containerRef = $state(null);
-    let focusedIndex = $state(null);
+    // The highlighted item: it has DOM focus, or the pointer rests on it, or it is the item the
+    // container's aria-activedescendant names. Tracked by element, so it survives insertions,
+    // removals and reorders around it.
+    let focusedItem = $state.raw(null);
+    // Focus sits on the container itself with no item highlighted (a popup opened by pointer).
+    let containerHighlighted = $state(false);
+    let lastFocusedItem = $state.raw(null);
     let focusSource = $state(null);
     let isHovering = $state(false);
     let isFocused = $state(false);
-    let lastFocusedIndex = $state(null);
+    // The item that holds DOM focus, or held it when focus was lost to nothing during this task
+    // (the item was removed). Not reactive: only the removal of that item reads it.
+    let focusHolder = null;
+    const restoreVersion = createRovingRestoreVersion();
+    // The attributes this list last wrote, so a highlight move rewrites only the items it leaves
+    // and enters (at most four attribute writes) instead of every item.
+    let appliedTabStop = null;
+    let appliedHighlight = null;
     // Enabled by default — `enabled` is an opt-out, checked at event time so it stays reactive.
     const isEnabled = () => (opts.enabled ? opts.enabled() : true);
-    $effect(() => {
-        if (focusedIndex !== null && focusedIndex !== -1) {
-            lastFocusedIndex = focusedIndex;
-        }
-    });
+    const keepsDisabledItems = () => opts.disabledItemsFocusable === true || opts.skipDisabled === false;
     // Generate ID if not provided
     const baseId = opts.id ?? createId('nav');
     const getDirection = useDirection(() => containerRef);
+    // Get current orientation
+    const getOrientation = () => {
+        if (typeof opts.orientation === 'function') {
+            return opts.orientation();
+        }
+        return opts.orientation || 'horizontal';
+    };
+    /** The registered items in document order. */
+    const ordered = () => {
+        if (orderStale) {
+            orderStale = false;
+            for (let index = 1; index < registered.length; index += 1) {
+                if (byDocumentPosition(registered[index - 1], registered[index]) > 0) {
+                    registered.sort(byDocumentPosition);
+                    positionsStale = true;
+                    break;
+                }
+            }
+        }
+        if (positionsStale) {
+            positionsStale = false;
+            registered.forEach((item, index) => positions.set(item, index));
+        }
+        return registered;
+    };
+    const indexOf = (item) => {
+        if (!item)
+            return -1;
+        ordered();
+        return positions.get(item) ?? -1;
+    };
+    // Natively disabled items (a `disabled` attribute, or inside a disabled fieldset) can never
+    // take focus, so they are never targets.
+    const isNativelyDisabled = (item) => item.hasAttribute('disabled') || item.matches(':disabled');
+    // Announced as disabled while still able to take focus.
+    const isSoftDisabled = (item) => {
+        const dataDisabled = item.getAttribute('data-disabled');
+        return (item.getAttribute('aria-disabled') === 'true' ||
+            (dataDisabled !== null && dataDisabled !== 'false'));
+    };
+    /** Never activated: natively disabled, aria-disabled or data-disabled. */
+    const isItemDisabled = (item) => isNativelyDisabled(item) || isSoftDisabled(item);
+    /** Cannot hold focus or the tab stop. */
+    const isUnfocusable = (item) => isNativelyDisabled(item) || (!keepsDisabledItems() && isSoftDisabled(item));
+    // CSS-hidden items (`display: none`, a hidden ancestor, inert content) have no box to focus.
+    const isRendered = (item) => item.getClientRects().length > 0 && !item.closest('[inert]');
+    /** A target for arrow keys, Home/End and type-ahead. */
+    const isNavigable = (item) => !isUnfocusable(item) && isRendered(item);
+    // The registered item that is or contains `node`; the container itself is no item.
+    const itemOf = (node) => {
+        let element = node instanceof Element ? node : node instanceof Node ? node.parentElement : null;
+        while (element && element !== containerRef) {
+            if (element instanceof HTMLElement && positions.has(element))
+                return element;
+            element = element.parentElement;
+        }
+        return null;
+    };
+    const itemIndexOf = (node) => indexOf(itemOf(node));
+    // A key typed inside a navigation list nested in this one belongs to that list.
+    const ownsKeyTarget = (target) => {
+        for (let element = target instanceof Element ? target : null; element && element !== containerRef; element = element.parentElement) {
+            if (containers.has(element))
+                return false;
+        }
+        return true;
+    };
+    // The first navigable item from the start (1) or the end (-1). When nothing is rendered yet
+    // (the list sits in a hidden panel), the first item that can take focus once it shows.
+    const findEdge = (direction) => {
+        const items = ordered();
+        let fallback = -1;
+        for (let step = 0; step < items.length; step += 1) {
+            const index = direction === 1 ? step : items.length - 1 - step;
+            if (isUnfocusable(items[index]))
+                continue;
+            if (isRendered(items[index]))
+                return index;
+            if (fallback === -1)
+                fallback = index;
+        }
+        return fallback;
+    };
+    // The next navigable item after `from` in `direction`, or -1 when there is none (the end of a
+    // list that does not loop). `from: null` enters the list at the edge the key points away from.
+    const findFrom = (from, direction) => {
+        if (from === null)
+            return findEdge(direction);
+        const items = ordered();
+        const { loop = true } = opts;
+        for (let distance = 1; distance <= items.length; distance += 1) {
+            let index = from + direction * distance;
+            if (loop) {
+                index = ((index % items.length) + items.length) % items.length;
+            }
+            else if (index < 0 || index >= items.length) {
+                return -1;
+            }
+            if (isNavigable(items[index]))
+                return index;
+        }
+        return -1;
+    };
+    // The single item reachable with Tab: the highlighted item when there is one, otherwise the
+    // default/active item, otherwise the first navigable one. This makes Tab land on the
+    // meaningful item WITHOUT any element being DOM-focused on mount (which would flash a focus
+    // ring). Virtual focus keeps every item out of the tab order.
+    const resolveTabStop = () => {
+        if (opts.virtualFocus)
+            return null;
+        if (focusedItem && !isUnfocusable(focusedItem))
+            return focusedItem;
+        const items = ordered();
+        const preferredIndex = opts.defaultFocusedIndex?.();
+        const preferred = preferredIndex == null ? undefined : items[preferredIndex];
+        if (preferred && isNavigable(preferred))
+            return preferred;
+        const edge = findEdge(1);
+        if (edge !== -1 && isRendered(items[edge]))
+            return items[edge];
+        // Nothing is rendered yet: keep the stop where it belongs once the list shows.
+        if (preferred && !isUnfocusable(preferred))
+            return preferred;
+        return items[edge] ?? null;
+    };
+    /**
+     * Brings `tabindex`, `data-highlighted` and the container's `aria-activedescendant` in line
+     * with the highlighted item and the tab stop, touching only the items that changed role.
+     */
+    const sync = () => {
+        const tabStop = resolveTabStop();
+        if (appliedTabStop && appliedTabStop !== tabStop && positions.has(appliedTabStop)) {
+            setAttribute(appliedTabStop, 'tabindex', '-1');
+        }
+        if (tabStop)
+            setAttribute(tabStop, 'tabindex', '0');
+        appliedTabStop = tabStop;
+        const highlight = focusedItem;
+        if (appliedHighlight && appliedHighlight !== highlight) {
+            removeAttribute(appliedHighlight, 'data-highlighted');
+        }
+        if (highlight)
+            setAttribute(highlight, 'data-highlighted', 'true');
+        appliedHighlight = highlight;
+        if (!containerRef)
+            return;
+        if (highlight?.id)
+            setAttribute(containerRef, 'aria-activedescendant', highlight.id);
+        else
+            removeAttribute(containerRef, 'aria-activedescendant');
+    };
+    const setFocused = (item, source) => {
+        focusedItem = item;
+        focusSource = item ? source : null;
+        containerHighlighted = false;
+        if (item)
+            lastFocusedItem = item;
+    };
     const typeahead = opts.typeahead
         ? createTypeahead({
-            getItems: () => items,
+            getItems: ordered,
             getText: (item) => typeof opts.typeahead === 'object'
                 ? opts.typeahead.getText(item)
                 : (item.dataset.typeahead ?? item.textContent ?? ''),
-            getCurrentIndex: () => focusedIndex ?? -1,
+            // Search from the focused item, not from the one the pointer highlighted.
+            getCurrentIndex: () => {
+                const focused = itemIndexOf(document.activeElement);
+                return focused !== -1 ? focused : indexOf(focusedItem);
+            },
+            isItemDisabled: (item) => !isNavigable(item),
             onMatch: (index) => {
-                if (!isItemDisabled(items[index]))
-                    moveFocusTo(index);
+                const focused = itemIndexOf(document.activeElement);
+                moveFocusTo(index, focused !== -1 ? focused : indexOf(focusedItem));
             }
         })
         : null;
-    // Get current orientation
-    const getOrientation = () => {
-        if (typeof opts.orientation === 'function') {
-            return opts.orientation();
-        }
-        return opts.orientation || 'horizontal';
-    };
+    // The focused element, not its index, is what a change reports: an insertion before it moves
+    // its index without changing what has focus.
     $effect(() => {
-        if (focusedIndex === null)
+        const item = focusedItem;
+        if (!item)
             return;
-        const newFocusedIndex = focusedIndex;
         untrack(() => {
-            opts.onChange?.(newFocusedIndex);
+            const index = indexOf(item);
+            if (index !== -1)
+                opts.onChange?.(index);
         });
     });
+    // Plain functions, not deriveds: a menu switch reads these from sync() while the previous
+    // menu's effects are being destroyed, and reading a derived owned by a destroyed effect warns
+    // (derived_inert) and may return a stale value. They still track `revision` and the focus
+    // state for any reactive caller.
+    const readFocusedIndex = () => {
+        void revision;
+        if (focusedItem) {
+            const index = indexOf(focusedItem);
+            return index === -1 ? null : index;
+        }
+        return containerHighlighted ? -1 : null;
+    };
+    const readLastFocusedIndex = () => {
+        void revision;
+        const index = indexOf(lastFocusedItem);
+        return index === -1 ? null : index;
+    };
+    let observer = null;
+    // A class, style or media-query change can hide an item without touching any watched
+    // attribute. Hiding collapses its box, which a ResizeObserver reports; the tab stop then
+    // moves to an item that is still rendered. The first report of an item always counts, since an
+    // item hidden at mount reports nothing until it shows.
+    const renderedItems = new WeakMap();
+    let resizeObserver = null;
+    const watchRendered = (node) => {
+        if (typeof ResizeObserver === 'undefined')
+            return;
+        resizeObserver ??= new ResizeObserver((entries) => {
+            let changed = false;
+            for (const { target } of entries) {
+                if (!(target instanceof HTMLElement) || !positions.has(target))
+                    continue;
+                const rendered = target.getClientRects().length > 0;
+                if (renderedItems.get(target) !== rendered)
+                    changed = true;
+                renderedItems.set(target, rendered);
+            }
+            if (changed)
+                revision += 1;
+        });
+        resizeObserver.observe(node);
+    };
     const cleanUp = () => {
-        itemsSet.clear();
+        registered.length = 0;
+        positions.clear();
+        observer?.disconnect();
+        observer = null;
+        resizeObserver?.disconnect();
+        resizeObserver = null;
+        typeahead?.reset();
+        restoreVersion.bump();
         containerRef = null;
-        focusedIndex = null;
+        focusedItem = null;
         focusSource = null;
+        containerHighlighted = false;
         isHovering = false;
         isFocused = false;
-        lastFocusedIndex = null;
+        lastFocusedItem = null;
+        focusHolder = null;
+        appliedTabStop = null;
+        appliedHighlight = null;
     };
     onDestroy(() => {
         cleanUp();
     });
     const focusContainer = () => {
         if (containerRef) {
-            focusedIndex = -1;
+            setFocused(null, null);
+            containerHighlighted = true;
+            sync();
             containerRef.focus();
         }
     };
-    // Derived: Get ordered items by DOM position
-    const items = $derived.by(() => {
-        if (itemsSet.size === 0)
-            return [];
-        if (containerRef === null)
-            return [];
-        const itemsArray = Array.from(itemsSet);
-        // Sort by DOM position using compareDocumentPosition
-        return itemsArray.sort((a, b) => {
-            const position = a.compareDocumentPosition(b);
-            if (position & Node.DOCUMENT_POSITION_FOLLOWING) {
-                return -1; // a comes before b
-            }
-            else if (position & Node.DOCUMENT_POSITION_PRECEDING) {
-                return 1; // b comes before a
-            }
-            return 0;
-        });
-    });
-    // Check if item is disabled
-    const isItemDisabled = (item) => {
-        const dataDisabled = item.getAttribute('data-disabled');
-        return (item.hasAttribute('disabled') ||
-            item.getAttribute('aria-disabled') === 'true' ||
-            (dataDisabled !== null && dataDisabled !== 'false'));
-    };
-    // Find next non-disabled index
-    const findNextIndex = (currentIndex, direction) => {
-        const { loop = true } = opts;
-        const total = items.length;
-        for (let distance = 1; distance <= total; distance += 1) {
-            let nextIndex = currentIndex + direction * distance;
-            if (loop) {
-                nextIndex = ((nextIndex % total) + total) % total;
-            }
-            else if (nextIndex < 0 || nextIndex >= total) {
-                return currentIndex;
-            }
-            if (!isItemDisabled(items[nextIndex]))
-                return nextIndex;
-        }
-        return currentIndex;
-    };
-    // Find first non-disabled index
-    const findFirstIndex = () => {
-        for (let i = 0; i < items.length; i++) {
-            if (!isItemDisabled(items[i]))
-                return i;
-        }
-        return -1; // No enabled items
-    };
-    // Find last non-disabled index
-    const findLastIndex = () => {
-        for (let i = items.length - 1; i >= 0; i--) {
-            if (!isItemDisabled(items[i]))
-                return i;
-        }
-        return -1; // No enabled items
-    };
-    // Update ARIA attributes on all items
-    const updateAriaAttributes = (focusIdx) => {
-        // The roving tab-stop (the single item reachable with Tab): the focused item
-        // when there is one, otherwise the default/active item, otherwise the first
-        // enabled one. This makes Tab land on the meaningful item WITHOUT any element
-        // being DOM-focused on mount (which would flash a focus ring). Virtual focus
-        // keeps every item out of the tab order.
-        const preferredTabStop = focusIdx ?? opts.defaultFocusedIndex?.();
-        const enabledTabStop = preferredTabStop != null &&
-            items[preferredTabStop] &&
-            !isItemDisabled(items[preferredTabStop])
-            ? preferredTabStop
-            : findFirstIndex();
-        const tabStop = opts.virtualFocus ? -1 : enabledTabStop;
-        items.forEach((item, index) => {
-            const isFocused = index === focusIdx;
-            const itemId = `${baseId}-item-${index}`;
-            // Set ID
-            if (!item.id) {
-                item.id = itemId;
-            }
-            // Roving tabindex sits on the tab-stop; data-highlighted (below) tracks
-            // actual keyboard focus, which is a separate concern.
-            item.setAttribute('tabindex', index === tabStop && !isItemDisabled(item) ? '0' : '-1');
-            // Set data-highlighted for keyboard focus
-            if (isFocused) {
-                item.setAttribute('data-highlighted', 'true');
-            }
-            else {
-                item.removeAttribute('data-highlighted');
-            }
-        });
-        // Update container's aria-activedescendant to focused item
-        if (containerRef && focusIdx !== null && items[focusIdx]) {
-            containerRef.setAttribute('aria-activedescendant', items[focusIdx].id);
-        }
-        else if (containerRef) {
-            containerRef.removeAttribute('aria-activedescendant');
-        }
-    };
-    // Move focus to specific index (arrow key navigation)
-    const moveFocusTo = (index) => {
-        if (items.length === 0)
+    /**
+     * Moves the highlight and DOM focus to `index`. `from` marks a key-driven move (the index the
+     * key started from, `null` when it entered the list), which reports through `onKeyboardMove`.
+     */
+    const moveFocusTo = (index, from) => {
+        const item = ordered()[index];
+        if (!item || isUnfocusable(item))
             return;
-        if (index < 0 || index >= items.length)
-            return;
-        if (isItemDisabled(items[index]))
-            return;
-        focusSource = 'keyboard';
-        focusedIndex = index;
-        updateAriaAttributes(index);
-        if (items[index]) {
-            const item = items[index];
-            // Virtual focus (combobox pattern): DOM focus stays put, only the highlight moves.
-            if (!opts.virtualFocus) {
-                item.focus();
-            }
-            // Scroll the item into view if needed
-            item.scrollIntoView({
-                block: 'nearest',
-                inline: 'nearest',
-                behavior: 'smooth'
-            });
+        setFocused(item, 'keyboard');
+        sync();
+        // Virtual focus (combobox pattern): DOM focus stays put, only the highlight moves.
+        if (!opts.virtualFocus) {
+            item.focus();
         }
+        // Scroll the item into view if needed
+        item.scrollIntoView({
+            block: 'nearest',
+            inline: 'nearest',
+            behavior: prefersReducedMotion() ? 'auto' : 'smooth'
+        });
+        if (from !== undefined && from !== index)
+            opts.onKeyboardMove?.(index);
     };
     // Click the currently focused item (Enter/Space key)
     const clickFocused = () => {
-        if (focusedIndex === null || focusedIndex < 0 || focusedIndex >= items.length)
-            return;
-        if (isItemDisabled(items[focusedIndex]))
+        if (!focusedItem || isItemDisabled(focusedItem))
             return;
-        // Trigger click event on the focused element
-        items[focusedIndex].click();
+        focusedItem.click();
     };
     // Clear focus state when container loses focus
     const clearFocus = () => {
-        focusedIndex = null;
-        focusSource = null;
+        setFocused(null, null);
         // Restore the default roving tab stop while removing the active highlight.
-        updateAriaAttributes(null);
+        sync();
     };
     // Handle item hover - only set visual focus (no DOM focus yet)
-    const handleItemHover = (itemElement) => {
-        // Find the index of the hovered item
-        const index = items.findIndex((item) => item === itemElement);
-        if (index === -1)
-            return;
-        if (isItemDisabled(items[index]))
+    const handleItemHover = (item) => {
+        if (!positions.has(item) || isItemDisabled(item))
             return;
         // Set visual focus on hovered item (don't manipulate DOM focus)
-        focusSource = 'pointer';
-        focusedIndex = index;
-        updateAriaAttributes(index);
+        setFocused(item, 'pointer');
+        sync();
     };
-    // Handle keyboard events
-    // Batch update ARIA attributes when items or focusedIndex change
-    $effect(() => {
-        if (items.length > 0) {
-            updateAriaAttributes(focusedIndex);
+    // The navigable item nearest to `from`: `from` itself, then the item before it, the one after,
+    // and so on outward (the order a tab list picks the tab that replaces a removed one).
+    const findNearest = (from) => {
+        const items = ordered();
+        for (let distance = 0; distance < items.length; distance += 1) {
+            for (const index of [from + distance, from - distance - 1]) {
+                if (index >= 0 && index < items.length && isNavigable(items[index]))
+                    return index;
+            }
+        }
+        return -1;
+    };
+    // Removing the item that had DOM focus would drop focus to <body>. Once the change has settled
+    // (replacement items registered), focus moves to the item that took the removed one's place,
+    // or the nearest navigable item to it — unless focus has already gone somewhere else.
+    const scheduleRestore = (previous, removed) => {
+        const version = restoreVersion.bump();
+        queueMicrotask(() => {
+            if (!restoreVersion.isCurrent(version) || !containerRef)
+                return;
+            const active = document.activeElement;
+            if (active && active !== document.body && active !== document.documentElement)
+                return;
+            const neighbour = clampRovingKey(previous, removed, ordered());
+            const target = neighbour ? findNearest(indexOf(neighbour)) : -1;
+            if (target !== -1)
+                moveFocusTo(target);
+        });
+    };
+    const register = (node) => {
+        const last = registered.at(-1);
+        if (last && (!last.isConnected || byDocumentPosition(last, node) > 0))
+            orderStale = true;
+        positions.set(node, registered.length);
+        registered.push(node);
+        // Ids are assigned once, at registration: aria-activedescendant names them.
+        if (!node.id)
+            node.id = `${baseId}-item-${(sequence += 1)}`;
+        setAttribute(node, 'tabindex', '-1');
+        watchRendered(node);
+        revision += 1;
+    };
+    const unregister = (node) => {
+        if (!positions.has(node))
+            return;
+        const previous = focusHolder === node ? registered.slice() : null;
+        const index = registered.indexOf(node);
+        if (index !== -1)
+            registered.splice(index, 1);
+        positions.delete(node);
+        positionsStale = true;
+        resizeObserver?.unobserve(node);
+        renderedItems.delete(node);
+        if (appliedTabStop === node)
+            appliedTabStop = null;
+        if (appliedHighlight === node)
+            appliedHighlight = null;
+        if (lastFocusedItem === node)
+            lastFocusedItem = null;
+        if (focusedItem === node)
+            setFocused(null, null);
+        if (previous) {
+            focusHolder = null;
+            scheduleRestore(previous, node);
         }
+        revision += 1;
+    };
+    // Keep the attributes in line after every change to the list, the highlight or the default
+    // item. It runs after the DOM updates, so it also wins over a consumer's own `tabindex`.
+    $effect(() => {
+        void revision;
+        sync();
     });
     const pointerDown = usePointerDown({
         isActive: () => true
     });
-    // Use the existing useKeyDown hook - pass all possible keys, filter in handleKeyboard
-    const keyDown = useKeyDown({
-        isActive: () => {
-            if (!isEnabled())
-                return false;
-            if (isHovering && opts.enableHoverFocus) {
-                return true;
-            }
-            return true;
-        },
-        preventDefault: opts.preventKeyboardDefault,
-        onWindow: () => {
-            // return false;
-            return isHovering && !isFocused && opts.enableHoverFocus ? true : false;
-        },
-        callback: (event) => {
-            // Respect the enabled gate per-event: the element listener is attached once at mount and
-            // never re-checks isActive, so without this a disabled menu (e.g. a parent whose submenu
-            // is open) would still handle keys that bubble to it and double-navigate.
-            if (!isEnabled())
-                return;
-            // Hover-to-navigate must not hijack when focus already lives inside another menu/listbox
-            // (e.g. an open submenu portaled elsewhere): stealing focus here would yank the caret out
-            // of the submenu and navigate this container instead.
-            const active = document.activeElement;
-            if (active &&
-                !containerRef?.contains(active) &&
-                active.closest('[role="menu"],[role="listbox"]')) {
-                return;
-            }
-            // If hovering but container not focused, focus it first on arrow key
-            if (isHovering &&
-                opts.enableHoverFocus &&
-                containerRef &&
-                document.activeElement !== containerRef &&
-                !containerRef.contains(document.activeElement)) {
-                containerRef.focus();
+    // In RTL the inline arrows are mirrored: in a horizontal list ArrowRight goes to the previous
+    // item; in a vertical one ArrowLeft opens a level (onNext) and ArrowRight leaves it (onPrevious).
+    const resolveKey = (key) => {
+        const mirrored = (opts.rtl ?? true) && getDirection() === 'rtl';
+        if (mirrored && key === 'ArrowLeft')
+            return 'ArrowRight';
+        if (mirrored && key === 'ArrowRight')
+            return 'ArrowLeft';
+        return key;
+    };
+    // Move with an arrow along the list's axis; a key with nowhere to go still counts as handled,
+    // so the page does not scroll under the list.
+    const step = (from, direction) => {
+        const index = findFrom(from, direction);
+        if (index !== -1)
+            moveFocusTo(index, from);
+        return true;
+    };
+    /**
+     * Move or activate for one (already mirrored) key, starting from `from`: the index of the item
+     * the key acts on, or `null` when it comes from outside the items and enters the list at an
+     * edge. Returns whether the key did anything.
+     */
+    const navigate = (key, from) => {
+        const orientation = getOrientation();
+        switch (key) {
+            case 'ArrowLeft':
+            case 'ArrowRight': {
+                const direction = key === 'ArrowRight' ? 1 : -1;
+                if (orientation !== 'vertical')
+                    return step(from, direction);
+                // Cross axis of a vertical list: the item may open (onNext) or leave (onPrevious) a level.
+                const item = from === null ? undefined : ordered()[from];
+                if (!item)
+                    return false;
+                const node = item;
+                const handler = direction === 1 ? node.onNext : node.onPrevious;
+                if (typeof handler !== 'function')
+                    return false;
+                return handler.call(node) !== false;
             }
-            const orientation = getOrientation();
-            if (!opts.preventKeyboardDefault && event.key !== 'Escape') {
-                event.preventDefault();
+            case 'ArrowUp':
+            case 'ArrowDown':
+                if (orientation === 'horizontal')
+                    return false;
+                return step(from, key === 'ArrowDown' ? 1 : -1);
+            case 'Home':
+            case 'End': {
+                const index = findEdge(key === 'Home' ? 1 : -1);
+                if (index === -1)
+                    return false;
+                moveFocusTo(index, from);
+                return true;
             }
-            // In RTL the physical arrows are mirrored: ArrowRight goes to the previous item.
-            const mirrored = (opts.rtl ?? true) && orientation === 'horizontal' && getDirection() === 'rtl';
-            const key = mirrored && event.key === 'ArrowLeft'
-                ? 'ArrowRight'
-                : mirrored && event.key === 'ArrowRight'
-                    ? 'ArrowLeft'
-                    : event.key;
-            switch (key) {
-                case 'ArrowLeft':
-                    if (orientation === 'horizontal') {
-                        const currentIdx = focusedIndex ?? findFirstIndex();
-                        if (currentIdx !== -1) {
-                            moveFocusTo(findNextIndex(currentIdx, -1));
-                        }
-                    }
-                    else if (focusedIndex !== null) {
-                        const node = items[focusedIndex];
-                        if ('onPrevious' in node && typeof node.onPrevious === 'function') {
-                            node.onPrevious();
-                        }
-                    }
-                    break;
-                case 'ArrowRight':
-                    if (orientation === 'horizontal') {
-                        const currentIdx = focusedIndex ?? findFirstIndex();
-                        if (currentIdx !== -1) {
-                            moveFocusTo(findNextIndex(currentIdx, 1));
-                        }
-                    }
-                    else if (focusedIndex !== null) {
-                        const node = items[focusedIndex];
-                        if ('onNext' in node && typeof node.onNext === 'function') {
-                            node.onNext();
-                        }
-                    }
-                    break;
-                case 'ArrowUp':
-                    if (orientation === 'vertical') {
-                        const currentIdx = focusedIndex ?? findFirstIndex();
-                        if (currentIdx !== -1) {
-                            moveFocusTo(findNextIndex(currentIdx, -1));
-                        }
-                        else {
-                            moveFocusTo(findLastIndex());
-                        }
-                    }
-                    break;
-                case 'ArrowDown':
-                    if (orientation === 'vertical') {
-                        const currentIdx = focusedIndex ?? findFirstIndex();
-                        if (currentIdx !== -1) {
-                            moveFocusTo(findNextIndex(currentIdx, 1));
-                        }
-                        else {
-                            moveFocusTo(findFirstIndex());
-                        }
-                    }
-                    break;
-                case 'Home': {
-                    const firstIndex = findFirstIndex();
-                    if (firstIndex !== -1) {
-                        moveFocusTo(firstIndex);
-                    }
-                    break;
-                }
-                case 'End': {
-                    const lastIndex = findLastIndex();
-                    if (lastIndex !== -1) {
-                        moveFocusTo(lastIndex);
-                    }
-                    break;
+            case 'Escape':
+                if (containerRef?.contains(document.activeElement)) {
+                    clearFocus();
                 }
-                case 'Escape': {
-                    if (containerRef?.contains(document.activeElement)) {
-                        clearFocus();
-                    }
-                    break;
-                }
-                case 'Enter':
-                case ' ':
-                    clickFocused();
-                    break;
-            }
+                return true;
+            case 'Enter':
+            case ' ':
+                if (key === 'Enter' && opts.enterActivates === false)
+                    return false;
+                clickFocused();
+                return true;
+        }
+        return false;
+    };
+    // Keys act where keyboard focus is. Hover moves the highlight without moving DOM focus, so a
+    // key typed on a focused item starts from that item, not from the one under the pointer. A key
+    // typed on the container itself (a popup menu opened by pointer) keeps the highlighted item,
+    // which the container's aria-activedescendant names.
+    const syncToKeyTarget = (target) => {
+        const item = itemOf(target);
+        if (!item || item === focusedItem)
+            return;
+        setFocused(item, 'keyboard');
+        sync();
+    };
+    // The item a key typed on `target` starts from; null enters the list at an edge.
+    const keyOrigin = (target) => {
+        const index = itemIndexOf(target);
+        if (index !== -1)
+            return index;
+        if (target !== containerRef)
+            return null;
+        const highlighted = indexOf(focusedItem);
+        return highlighted === -1 ? null : highlighted;
+    };
+    // A text field keeps its editing keys: Home, End, Space and Enter never leave it. Arrows along
+    // the list's axis do, horizontal ones only from the caret edge they point past (a search field
+    // in a toolbar), vertical ones from single-line inputs (a filter field above a menu's rows).
+    const fieldReleases = (event, key) => {
+        const orientation = getOrientation();
+        switch (key) {
+            case 'ArrowLeft':
+            case 'ArrowRight':
+                return (orientation !== 'vertical' && isCaretAtEdge(event, key === 'ArrowRight' ? 'end' : 'start'));
+            case 'ArrowUp':
+            case 'ArrowDown':
+                if (orientation === 'horizontal')
+                    return false;
+                return (event.target instanceof HTMLInputElement ||
+                    isCaretAtEdge(event, key === 'ArrowDown' ? 'end' : 'start'));
+            default:
+                return false;
+        }
+    };
+    // Content inside the container that is no item (a header field or button) keeps Enter, Space
+    // and Escape; arrows along the axis and Home/End enter the list at its start or end.
+    const contentReleases = (event, key) => {
+        if (isTextEntry(event.target))
+            return fieldReleases(event, key);
+        const orientation = getOrientation();
+        switch (key) {
+            case 'Home':
+            case 'End':
+                return true;
+            case 'ArrowLeft':
+            case 'ArrowRight':
+                return orientation !== 'vertical';
+            case 'ArrowUp':
+            case 'ArrowDown':
+                return orientation !== 'horizontal';
+            default:
+                return false;
+        }
+    };
+    // Keys typed while focus is inside the container.
+    const handleContainerKey = (event) => {
+        const target = event.target;
+        if (!ownsKeyTarget(target))
+            return;
+        const key = resolveKey(event.key);
+        if (target !== containerRef && !itemOf(target)) {
+            if (!isEnabled() || !contentReleases(event, key))
+                return;
+            event.preventDefault();
+            navigate(key, null);
+            return;
+        }
+        if (isTextEntry(target) && key !== 'Escape' && !fieldReleases(event, key))
+            return;
+        // `preventKeyboardDefault: false` (menus) lets Escape reach the popup that closes on it;
+        // every other consumer keeps all of its keys.
+        if (opts.preventKeyboardDefault !== false)
+            event.preventDefault();
+        if (!isEnabled())
+            return;
+        if (event.key !== 'Escape')
+            event.preventDefault();
+        syncToKeyTarget(target);
+        navigate(key, keyOrigin(target));
+    };
+    // Only these keys may pull focus into a container the pointer merely rests on.
+    const hoverEntryKeys = ['ArrowLeft', 'ArrowRight', 'ArrowUp', 'ArrowDown', 'Home', 'End'];
+    // No element has focus: the key was typed on the page itself, not in a field or control.
+    const isPageLevel = (node) => {
+        const pageTargets = [
+            null,
+            window,
+            document,
+            document.body,
+            document.documentElement
+        ];
+        return pageTargets.includes(node);
+    };
+    // Hover-to-navigate (`enableHoverFocus`): while the pointer rests on the container and nothing
+    // on the page has focus, arrows and Home/End move focus into it, from the item highlighted
+    // under the pointer or, with none, at the edge the key points to. A key typed anywhere else (a
+    // text field, a button, an open submenu or dialog) belongs to that element, and Enter/Space
+    // never activate an item that is only highlighted under the pointer.
+    const handleHoverKey = (event) => {
+        if (event.defaultPrevented || !hoverEntryKeys.includes(event.key))
+            return;
+        if (!isPageLevel(document.activeElement) || !isPageLevel(event.target))
+            return;
+        const highlighted = indexOf(focusedItem);
+        if (navigate(resolveKey(event.key), highlighted === -1 ? null : highlighted)) {
+            event.preventDefault();
+        }
+    };
+    // Alt/Ctrl/Meta + a navigation key is a browser or OS shortcut (Alt+← is Back), never a move.
+    // useKeyDown leaves those alone; preventDefault is decided per path above.
+    const keyDown = useKeyDown({
+        isActive: isEnabled,
+        preventDefault: false,
+        ignoreModifiers: true,
+        onWindow: () => isHovering && !isFocused && !!opts.enableHoverFocus,
+        callback: (event, source) => {
+            if (source === 'window')
+                handleHoverKey(event);
+            else
+                handleContainerKey(event);
         },
         keys: ['Escape', 'ArrowLeft', 'ArrowRight', 'ArrowUp', 'ArrowDown', 'Home', 'End', 'Enter', ' ']
     });
@@ -365,28 +688,64 @@ export const useNavigation = (opts) => {
         containerReference: (node) => {
             return untrack(() => {
                 containerRef = node;
-                // Make container focusable for keyboard navigation (virtual focus keeps
-                // DOM focus on the consumer's own element, e.g. a combobox input).
-                if (!node.hasAttribute('tabindex') && !opts.virtualFocus) {
-                    node.setAttribute('tabindex', '0');
+                containers.add(node);
+                // Focusable from script (a popup focuses it and names the highlighted item through
+                // aria-activedescendant) but never a Tab stop: the roving tab stop is on an item.
+                // Virtual focus keeps DOM focus on the consumer's own element (a combobox input).
+                if (!node.hasAttribute('tabindex') &&
+                    !opts.virtualFocus &&
+                    opts.focusableContainer !== false) {
+                    node.setAttribute('tabindex', '-1');
+                }
+                // A keyed reorder moves item nodes without re-running their attachments, and an item can
+                // become disabled or hidden without registering again: both re-sync the list. Only a
+                // move (a node removed and added again in one batch) can break the order; insertions are
+                // placed as they register and removals keep it.
+                if (typeof MutationObserver !== 'undefined') {
+                    observer = new MutationObserver((records) => {
+                        // Writing an attribute with the value it already has still queues a record (a
+                        // template re-assigning `button.disabled = true`). Counting it would re-run the
+                        // attribute sync, which re-runs that template: an endless loop.
+                        if (records.every(isUnchangedAttribute))
+                            return;
+                        if (hasMovedNode(records))
+                            orderStale = true;
+                        revision += 1;
+                    });
+                    observer.observe(node, {
+                        childList: true,
+                        subtree: true,
+                        attributes: true,
+                        attributeOldValue: true,
+                        attributeFilter: ['disabled', 'aria-disabled', 'data-disabled', 'hidden', 'inert']
+                    });
                 }
                 // Apply keydown reference
-                const keyDownCleanup = keyDown.reference?.(node);
+                const keyDownCleanup = keyDown.reference(node);
                 const typeaheadCleanup = typeahead
                     ? on(node, 'keydown', (event) => {
-                        if (!isEnabled() || event.defaultPrevented)
+                        if (!isEnabled() || event.defaultPrevented || !ownsKeyTarget(event.target))
                             return;
                         if (typeahead.handleKey(event))
                             event.preventDefault();
                     })
                     : null;
-                // Handle focus event - set focus to first item when container receives focus
-                const handleFocus = () => {
+                // The container itself receiving focus (from script, or a click between items) moves
+                // focus to the default item, unless the pointer is down or a popup focused it on purpose.
+                // Focus that lands on an item, or on other content inside the list, stays there.
+                const handleFocus = (event) => {
                     isFocused = true;
-                    if (focusedIndex === null && !pointerDown.isDown) {
-                        const firstIndex = opts.defaultFocusedIndex?.() ?? findFirstIndex();
-                        if (firstIndex !== -1) {
-                            moveFocusTo(firstIndex);
+                    focusHolder = itemOf(event.target);
+                    if (event.target !== node)
+                        return;
+                    if (focusedItem === null && !containerHighlighted && !pointerDown.isDown) {
+                        const preferred = opts.defaultFocusedIndex?.();
+                        const items = ordered();
+                        const index = preferred != null && items[preferred] && isNavigable(items[preferred])
+                            ? preferred
+                            : findEdge(1);
+                        if (index !== -1) {
+                            moveFocusTo(index);
                         }
                     }
                 };
@@ -394,12 +753,25 @@ export const useNavigation = (opts) => {
                 // Handle blur event - reset focus when container loses focus
                 const handleBlur = (event) => {
                     isFocused = false;
-                    // Check if focus moved outside the container
                     const relatedTarget = event.relatedTarget;
-                    if (!relatedTarget || !node.contains(relatedTarget)) {
-                        // Focus moved outside, clear focus state
-                        clearFocus();
+                    if (relatedTarget instanceof Node && node.contains(relatedTarget))
+                        return;
+                    // Focus left the list: the type-ahead buffer starts over next time.
+                    typeahead?.reset();
+                    if (relatedTarget === null) {
+                        // Lost to nothing. Chromium blurs a focused item while removing it (still connected,
+                        // so this cannot tell yet), and its unregistration later in the same flush restores
+                        // focus. An item still in the document afterwards lost focus to the page instead.
+                        const holder = focusHolder;
+                        queueMicrotask(() => {
+                            if (focusHolder === holder && holder?.isConnected)
+                                focusHolder = null;
+                        });
+                    }
+                    else {
+                        focusHolder = null;
                     }
+                    clearFocus();
                 };
                 const blurCleanup = on(node, 'focusout', handleBlur);
                 // Handle container pointer enter - track hovering state
@@ -420,12 +792,12 @@ export const useNavigation = (opts) => {
                 // on mount — a tablist/menu must not steal focus just by existing (it
                 // caused a focus-visible ring on the first tab on page load). Consumers
                 // that want focus-on-mount opt in explicitly (e.g. Menu's `focusOnMount`
-                // via onMount). Tabbing into the container still focuses the active item
-                // through the `focusin` handler above, and the roving tab-stop
-                // (updateAriaAttributes) makes the active item directly Tab-reachable.
+                // via onMount). The roving tab-stop (sync) makes the active item directly
+                // Tab-reachable.
                 return () => {
+                    containers.delete(node);
                     cleanUp();
-                    keyDownCleanup?.();
+                    keyDownCleanup();
                     typeaheadCleanup?.();
                     focusCleanup();
                     blurCleanup();
@@ -437,28 +809,23 @@ export const useNavigation = (opts) => {
         },
         itemReference: (node) => {
             return untrack(() => {
-                // Add item to set
-                itemsSet.add(node);
-                // ARIA attributes are now batch-updated via $effect
+                register(node);
                 const handleFocus = () => {
-                    const index = items.findIndex((item) => item === node);
-                    if (index === -1 || isItemDisabled(node))
+                    if (!positions.has(node) || isUnfocusable(node))
                         return;
-                    focusSource = 'keyboard';
-                    focusedIndex = index;
-                    updateAriaAttributes(index);
+                    setFocused(node, 'keyboard');
+                    sync();
                 };
                 const focusCleanup = on(node, 'focus', handleFocus);
                 // Handle hover - only move focus if enabled
                 const handleHover = () => {
-                    if (isEnabled() && opts.enableHoverFocus !== false && !isItemDisabled(node)) {
+                    if (isEnabled() && opts.enableHoverFocus !== false) {
                         handleItemHover(node);
                     }
                 };
                 const hoverCleanup = on(node, 'pointerenter', handleHover);
                 return () => {
-                    // Remove item from set
-                    itemsSet.delete(node);
+                    unregister(node);
                     focusCleanup();
                     hoverCleanup();
                 };
@@ -466,22 +833,22 @@ export const useNavigation = (opts) => {
         },
         // Expose focused index for external use
         get focusedIndex() {
-            return focusedIndex;
+            return readFocusedIndex();
         },
         // Expose control methods
         focusItem: (index) => {
-            if (index >= 0 && index < items.length) {
+            if (index >= 0 && index < ordered().length) {
                 moveFocusTo(index);
             }
         },
         focusFirst: () => {
-            const firstIndex = findFirstIndex();
+            const firstIndex = findEdge(1);
             if (firstIndex !== -1) {
                 moveFocusTo(firstIndex);
             }
         },
         focusLast: () => {
-            const lastIndex = findLastIndex();
+            const lastIndex = findEdge(-1);
             if (lastIndex !== -1) {
                 moveFocusTo(lastIndex);
             }
@@ -496,16 +863,16 @@ export const useNavigation = (opts) => {
          * any) should be highlighted instead of the stale trigger.
          */
         syncPointerFocus: () => {
-            const hovered = items.findIndex((item) => item.matches(':hover') && !isItemDisabled(item));
-            if (hovered !== -1) {
-                handleItemHover(items[hovered]);
+            const hovered = ordered().find((item) => item.matches(':hover') && !isItemDisabled(item));
+            if (hovered) {
+                handleItemHover(hovered);
             }
             else if (focusSource === 'pointer') {
                 clearFocus();
             }
         },
         get lastFocusedIndex() {
-            return lastFocusedIndex;
+            return readLastFocusedIndex();
         },
         focusContainer: focusContainer
     };