entasis 0.10.2 → 0.12.0

package/dist/components/NavigationMenu/navigationMenu.state.svelte.js

@@ -0,0 +1,721 @@
+// Behaviour of a NavigationMenu: which panel is open and why, hover switching, the layer that
+// dismisses it, Tab order between the triggers and the inline panel area, the arrow keys along
+// the bar and inside the open panel, placement of that area under the active trigger, and the
+// enter, exit and switch animations.
+//
+// Keyboard follows the WAI-ARIA APG disclosure navigation pattern, with Base UI's choices where
+// the pattern leaves room (ArrowDown opens a trigger without moving focus, arrows inside a panel
+// wrap) and menubar-style inline arrows: with a panel open, moving along the bar, from the bar or
+// from inside the panel, switches the open panel to the focused trigger (no wrap).
+//
+// The panel area is one viewport rendered inline inside the `<nav>`, after the trigger list. It
+// is never portaled, so the document order stays the reading order; `useTabBridge` carries Tab
+// from the open trigger into the panel and on to whatever follows the trigger.
+import { getContext, setContext, tick, untrack } from 'svelte';
+import { on } from 'svelte/events';
+import { SvelteMap, SvelteSet } from 'svelte/reactivity';
+import { useTheme } from '../Theme/theme.state.svelte.js';
+import { easingBezierStrings, easingFunctions } from '../../transitions/easingFunctions.js';
+import { createOpenChangeDetails } from '../../utils/openChange.js';
+import { useOpenLifecycle } from '../../utils/openLifecycle.svelte.js';
+import { useSafeArea } from '../../utils/safeArea.svelte.js';
+import { useTabBridge } from '../../utils/useTabBridge.svelte.js';
+import { useDirection } from '../../utils/useDirection.svelte.js';
+import { hasShortcutModifier } from '../../utils/useKeyDown.svelte.js';
+import { composedContains, getDeepActiveElement, getTabbableAfter, getTabbableElements, isTextField } from '../../utils/focus.js';
+import { useNavigationMenuMotion } from './navigationMenu.theme.js';
+/** Space in px kept between the panel area and the edges of the layout viewport. */
+const COLLISION_PADDING = 8;
+/** Distance in px a panel travels when it replaces another (in) or is replaced (out). */
+const SWITCH_DISTANCE = 24;
+/** How long a panel switch counts as under way: the window in which size and slide animations run. */
+const SWITCH_WINDOW = 300;
+const FOCUS_VISIBLE = { preventScroll: true, focusVisible: true };
+const ITEM_SELECTOR = '[data-slot="navigation-menu-trigger"], [data-slot="navigation-menu-link"]';
+const isPanel = (item) => item.type === 'panel';
+/** Reasons after which focus that sat inside the panel area goes back to the trigger. */
+const RESTORING_REASONS = new Set(['escape-key', 'item-press', 'close-press']);
+export function useNavigationMenuState(options) {
+    const theme = useTheme();
+    const resolveMotion = useNavigationMenuMotion();
+    const panels = $derived(options.items().filter(isPanel));
+    const panelIndex = (value) => value === null ? -1 : panels.findIndex((panel) => panel.value === value);
+    // The open panel: the one the value names, as long as it exists and is enabled.
+    const activeItem = $derived(panels.find((panel) => panel.value === options.value() && !panel.disabled) ?? null);
+    // The open panel's value, compared by value: a parent that rebuilds `items` on every render
+    // hands out new objects for the same panel, and that is not a change.
+    const activeValue = $derived(activeItem?.value ?? null);
+    const isOpen = $derived(activeValue !== null);
+    // The panel the area shows. It keeps the last open one through the exit animation, so the
+    // popup does not empty itself while it fades out.
+    let displayValue = $state(untrack(() => activeValue));
+    $effect.pre(() => {
+        if (activeValue !== null)
+            displayValue = activeValue;
+    });
+    const triggers = new SvelteMap();
+    const panelElements = new SvelteMap();
+    const activeTrigger = $derived(displayValue === null ? null : (triggers.get(displayValue) ?? null));
+    const activePanel = $derived(displayValue === null ? null : (panelElements.get(displayValue) ?? null));
+    /** The nested inline panels that are expanded, keyed by their value. */
+    const nestedOpen = new SvelteSet();
+    let navElement = $state.raw(null);
+    let viewportElement = $state.raw(null);
+    let popupElement = $state.raw(null);
+    const getDirection = useDirection(() => navElement, () => options.dir());
+    // The panel that hovering opened (or switched to) and that nothing has pinned since: it closes
+    // when the pointer leaves. A press, the keyboard or code leaves `null`, and the panel then
+    // stays until dismissed. Plain fields: read by handlers.
+    let hoverValue = null;
+    // Set by a request just before it writes the value and consumed by the effect that sees the
+    // panel change, so a value the parent assigns by itself never counts as a hover.
+    let pendingHover = null;
+    let switchedAt = -Infinity;
+    let activationDirection = $state(null);
+    const now = () => (typeof performance === 'undefined' ? Date.now() : performance.now());
+    const isSwitching = () => now() - switchedAt < SWITCH_WINDOW;
+    // Notices a panel replacing another (a switch) as opposed to opening from closed. Runs before
+    // the DOM update so the panel and size animations that start with it see the flag.
+    let previousValue = untrack(() => activeValue);
+    $effect.pre(() => {
+        const next = activeValue;
+        untrack(() => {
+            const from = previousValue;
+            previousValue = next;
+            hoverValue = next !== null && pendingHover === next ? next : null;
+            pendingHover = null;
+            if (next === null) {
+                switchedAt = -Infinity;
+                activationDirection = null;
+                return;
+            }
+            if (from === null) {
+                switchedAt = -Infinity;
+                activationDirection = null;
+                return;
+            }
+            if (from === next)
+                return;
+            switchedAt = now();
+            const later = panelIndex(next) > panelIndex(from);
+            const physical = (later ? 'right' : 'left');
+            activationDirection =
+                getDirection() === 'rtl' ? (physical === 'right' ? 'left' : 'right') : physical;
+        });
+    });
+    // ---- requesting a change ------------------------------------------------------------
+    const insideChildLayer = (node) => !!node &&
+        theme.layers.open.some((open) => open !== layer && open.parent === layer && [...open.nodes].some((n) => n.contains(node)));
+    /**
+     * The one path to a change of the open panel: `onValueChange` runs first and may cancel.
+     * Returns whether the change was applied.
+     */
+    function requestChange(next, init) {
+        const current = options.value();
+        if (next === current)
+            return false;
+        // A panel that is missing or disabled cannot be opened.
+        if (next !== null && !panels.some((panel) => panel.value === next && !panel.disabled)) {
+            return false;
+        }
+        const details = createOpenChangeDetails(init);
+        options.onValueChange()?.({ value: next, details });
+        if (details.isCanceled)
+            return false;
+        const previous = displayValue;
+        const doc = navElement?.ownerDocument ?? document;
+        const active = getDeepActiveElement(doc);
+        // Safari does not focus a link or button on click, so the press target counts as well.
+        const target = init.event?.target;
+        const focusInside = !!popupElement &&
+            ((!!active && composedContains(popupElement, active)) ||
+                (target instanceof Node && composedContains(popupElement, target)));
+        // Safari does not focus a button on click either, so a panel opened by the pointer has
+        // focus on the page body: Escape still hands it back to the trigger, since nothing else holds it.
+        const focusAdrift = init.reason === 'escape-key' &&
+            (!active || active === doc.body || active === doc.documentElement);
+        if (next !== null && init.reason === 'trigger-hover') {
+            pendingHover = next;
+            // A parent that refuses the value leaves the flag unconsumed; it must not outlive this task.
+            setTimeout(() => (pendingHover = null));
+        }
+        options.setValue(next);
+        if (next === null) {
+            nestedOpen.clear();
+            if ((focusInside || focusAdrift) && RESTORING_REASONS.has(init.reason) && previous !== null) {
+                const trigger = triggers.get(previous);
+                trigger?.focus(details.interaction === 'keyboard' ? FOCUS_VISIBLE : { preventScroll: true });
+            }
+        }
+        return true;
+    }
+    /** Closes every level of the menu. */
+    const close = (init = {}) => requestChange(null, { reason: 'close-press', ...init });
+    /** A link press anywhere in the tree closes every level, once. */
+    const pressLink = (event) => {
+        if (options.value() === null)
+            return;
+        requestChange(null, { reason: 'item-press', event });
+    };
+    function pressTrigger(value, event) {
+        const trigger = triggers.get(value);
+        // Safari does not focus a button on click. Focus it, so Tab, ArrowDown and Escape carry on
+        // from the trigger as they do after a click in every other engine.
+        if (trigger && event.detail > 0) {
+            const active = getDeepActiveElement(trigger.ownerDocument);
+            if (active !== trigger) {
+                trigger.focus({ preventScroll: true, focusVisible: false });
+            }
+        }
+        const current = options.value();
+        if (current === value) {
+            // A pointer press on a panel that hovering opened turns it into a pressed one; the next
+            // press closes it. Enter and Space (a click with no pointer, `detail` 0) toggle as usual.
+            if (hoverValue === value && event.detail > 0) {
+                hoverValue = null;
+                return;
+            }
+            requestChange(null, { reason: 'trigger-press', event, trigger });
+            return;
+        }
+        requestChange(value, { reason: 'trigger-press', event, trigger });
+    }
+    function hoverTrigger(value, event) {
+        if (!options.openOnHover())
+            return;
+        requestChange(value, {
+            reason: 'trigger-hover',
+            event,
+            trigger: triggers.get(value),
+            interaction: 'mouse'
+        });
+    }
+    // ---- layer: Escape and outside presses -------------------------------------------------
+    const layer = theme.layers.register({
+        kind: 'popover',
+        isOpen: () => isOpen,
+        isModal: () => false,
+        dismissOnEscape: () => true,
+        dismissOnOutside: () => true,
+        onDismiss: (request) => requestChange(null, request)
+    });
+    function handleFocusOut(event) {
+        if (!isOpen || !navElement)
+            return;
+        const next = event.relatedTarget;
+        // `null` is focus leaving the window or going to the page body: nothing to follow.
+        if (!(next instanceof Node) || navElement.contains(next) || insideChildLayer(next))
+            return;
+        requestChange(null, { reason: 'focus-out', event, interaction: 'keyboard' });
+    }
+    // ---- hover: closing --------------------------------------------------------------------
+    const isPointerOver = () => !!(activeTrigger?.matches(':hover') || popupElement?.matches(':hover'));
+    const safeArea = useSafeArea({
+        isActive: () => isOpen && options.openOnHover(),
+        callback: (event) => {
+            // Only a panel the pointer opened closes when the pointer leaves it.
+            if (hoverValue === null || !isOpen)
+                return;
+            // A trigger the pointer has just entered re-anchors the area; a pause there is no exit.
+            if (isPointerOver())
+                return;
+            // Focus inside the panel means the keyboard took over from the pointer.
+            const active = getDeepActiveElement(navElement?.ownerDocument ?? document);
+            if (active && popupElement && composedContains(popupElement, active))
+                return;
+            requestChange(null, { reason: 'trigger-hover', event, interaction: 'mouse' });
+        },
+        offset: COLLISION_PADDING,
+        closeDelay: () => options.closeDelay()
+    });
+    // ---- Tab order -------------------------------------------------------------------------
+    useTabBridge({
+        isActive: () => isOpen,
+        anchor: () => activeTrigger,
+        panel: () => activePanel,
+        onLeave: (event) => {
+            requestChange(null, { reason: 'focus-out', event, interaction: 'keyboard' });
+        }
+    });
+    // ---- lifecycle and animation -----------------------------------------------------------
+    const lifecycle = useOpenLifecycle({
+        isOpen: () => isOpen,
+        animated: () => popupElement,
+        onAfterOpen: () => options.onAfterOpen()?.(),
+        onAfterClose: () => options.onAfterClose()?.()
+    });
+    /** Whether the popup is in the DOM at all. */
+    const rendered = $derived(options.keepMounted() || isOpen || lifecycle.status !== 'closed');
+    /** Whether the popup shows. A kept-mounted one stays in the DOM under `hidden` when closed. */
+    const visible = $derived(isOpen || lifecycle.status === 'exiting');
+    let handledOpen = untrack(() => isOpen);
+    let exitAnimation = null;
+    const playPopup = (element, direction) => {
+        const spec = resolveMotion(undefined, {
+            motion: options.motion(),
+            transition: options.transition()
+        })[direction];
+        const duration = spec.duration ?? 0;
+        if (!duration || typeof element.animate !== 'function')
+            return null;
+        const hiddenFrame = {
+            opacity: spec.opacity ?? 0,
+            transform: `translate(${typeof spec.x === 'number' ? spec.x : 0}px, ${typeof spec.y === 'number' ? spec.y : 0}px) scale(${spec.scale ?? 1})`
+        };
+        const shownFrame = { opacity: 1, transform: 'translate(0px, 0px) scale(1)' };
+        return element.animate(direction === 'in' ? [hiddenFrame, shownFrame] : [shownFrame, hiddenFrame], {
+            duration,
+            easing: easingBezierStrings[spec.easing ?? 'cubicOut'],
+            fill: direction === 'out' ? 'forwards' : 'none'
+        });
+    };
+    $effect(() => {
+        const open = isOpen;
+        const element = popupElement;
+        untrack(() => {
+            // No popup to animate yet: a mounting popup runs this again once it exists.
+            if (!element || open === handledOpen)
+                return;
+            handledOpen = open;
+            exitAnimation?.cancel();
+            exitAnimation = playPopup(element, open ? 'in' : 'out');
+            if (open)
+                exitAnimation = null;
+        });
+    });
+    /** Slides a panel in from the side of the trigger that was open before it. */
+    // A switch is staged like a cross-slide: the old panel leaves first (`panelOut`, the motion's
+    // out duration), then the new one slides in over twice the in duration while the popup is still
+    // resizing, so each step can be seen. It waits invisible (`fill: backwards`) until its turn.
+    const animatePanel = (element) => {
+        if (!isSwitching() || activationDirection === null)
+            return;
+        const resolved = resolveMotion(undefined, {
+            motion: options.motion(),
+            transition: options.transition()
+        });
+        const duration = (resolved.in.duration ?? 0) * 2;
+        if (!duration || typeof element.animate !== 'function')
+            return;
+        const from = activationDirection === 'right' ? SWITCH_DISTANCE : -SWITCH_DISTANCE;
+        return element.animate([
+            { opacity: 0, transform: `translateX(${from}px)` },
+            { opacity: 1, transform: 'translateX(0px)' }
+        ], {
+            duration,
+            delay: resolved.out.duration ?? 0,
+            fill: 'backwards',
+            easing: easingBezierStrings[resolved.in.easing ?? 'cubicOut']
+        });
+    };
+    /**
+     * The outgoing panel of a switch: it leaves toward the side away from the new trigger while the
+     * new one slides in from the other side. It is taken out of the layout first, at the place and
+     * width it occupied, so only the incoming panel sizes the popup. Closing the menu does not run
+     * it (the panel stays until the popup is gone), and neither does a panel kept mounted.
+     */
+    const panelOut = (element) => {
+        // Runs as the old panel leaves the DOM, before the effect that records the switch, so the
+        // direction comes from the panels themselves: where the leaving one sits relative to the new.
+        const next = activeValue;
+        const leaving = [...panelElements].find(([, panel]) => panel === element)?.[0];
+        if (next === null || leaving === undefined || leaving === next)
+            return { duration: 0 };
+        const later = panelIndex(next) > panelIndex(leaving);
+        const physical = later ? 'right' : 'left';
+        const toward = getDirection() === 'rtl' ? (physical === 'right' ? 'left' : 'right') : physical;
+        const spec = resolveMotion(undefined, {
+            motion: options.motion(),
+            transition: options.transition()
+        }).out;
+        const duration = spec.duration ?? 0;
+        if (!duration)
+            return { duration: 0 };
+        const to = toward === 'right' ? -SWITCH_DISTANCE : SWITCH_DISTANCE;
+        const { offsetTop, offsetLeft, offsetWidth } = element;
+        element.style.position = 'absolute';
+        element.style.top = `${offsetTop}px`;
+        element.style.left = `${offsetLeft}px`;
+        element.style.width = `${offsetWidth}px`;
+        element.style.pointerEvents = 'none';
+        const easing = easingFunctions[spec.easing ?? 'cubicOut'] ?? easingFunctions.cubicOut;
+        return {
+            duration,
+            easing,
+            css: (t) => `opacity: ${t}; transform: translateX(${(1 - t) * to}px);`
+        };
+    };
+    // ---- placement -------------------------------------------------------------------------
+    // The popup lines up with the active trigger's inline edge and is clamped to the layout
+    // viewport (pinch-zoom does not move it). The clamp is done in CSS from these px values, so
+    // it holds while the popup animates its size.
+    $effect(() => {
+        const nav = navElement;
+        const trigger = activeTrigger;
+        const viewport = viewportElement;
+        if (!nav || !trigger || !viewport || !visible)
+            return;
+        const place = () => {
+            const navRect = nav.getBoundingClientRect();
+            const rect = trigger.getBoundingClientRect();
+            const left = navRect.left + nav.clientLeft;
+            const top = navRect.top + nav.clientTop;
+            const width = nav.ownerDocument.documentElement.clientWidth;
+            const style = viewport.style;
+            style.setProperty('--navigation-menu-anchor-start', `${rect.left - left}px`);
+            style.setProperty('--navigation-menu-anchor-end', `${rect.right - left}px`);
+            style.setProperty('--navigation-menu-anchor-bottom', `${rect.bottom - top}px`);
+            style.setProperty('--navigation-menu-min-x', `${COLLISION_PADDING - left}px`);
+            style.setProperty('--navigation-menu-max-x', `${width - COLLISION_PADDING - left}px`);
+            style.setProperty('--anchor-width', `${rect.width}px`);
+            style.setProperty('--anchor-height', `${rect.height}px`);
+        };
+        place();
+        const observer = typeof ResizeObserver === 'undefined' ? null : new ResizeObserver(place);
+        observer?.observe(nav);
+        observer?.observe(trigger);
+        const offResize = on(nav.ownerDocument.defaultView ?? window, 'resize', place);
+        return () => {
+            observer?.disconnect();
+            offResize();
+        };
+    });
+    // ---- value that disappears --------------------------------------------------------------
+    // The open panel was removed or disabled: the menu cannot stay open on nothing.
+    $effect(() => {
+        const current = options.value();
+        const enabled = panels.some((panel) => panel.value === current && !panel.disabled);
+        if (current === null || enabled)
+            return;
+        untrack(() => {
+            // Not cancelable: there is nothing left to keep.
+            requestChange(null, { reason: 'trigger-unmount', cancelable: false });
+        });
+    });
+    // ---- keyboard --------------------------------------------------------------------------
+    function enabledItems(list) {
+        return Array.from(list.querySelectorAll(ITEM_SELECTOR)).filter((element) => !element.matches(':disabled') && element.getAttribute('aria-disabled') !== 'true');
+    }
+    /** The step an arrow key takes along a line of items, mirrored in right-to-left. */
+    function arrowStep(key, vertical) {
+        const rtl = getDirection() === 'rtl';
+        if (key === 'ArrowRight')
+            return rtl ? -1 : 1;
+        if (key === 'ArrowLeft')
+            return rtl ? 1 : -1;
+        if (vertical && key === 'ArrowDown')
+            return 1;
+        if (vertical && key === 'ArrowUp')
+            return -1;
+        return 0;
+    }
+    /**
+     * Tab from an entry of the bar that is not the open trigger, where the next stop in the page is
+     * the panel area (it follows the list in the document): the panel belongs to its trigger, so
+     * focus skips it and goes on after the menu. Without this, focus would wander through a panel
+     * that is not this entry's and then jump back to the entry after the open trigger.
+     */
+    function skipForeignPanel(event, current) {
+        const viewport = viewportElement;
+        if (!isOpen || event.shiftKey || !viewport || current === activeTrigger)
+            return;
+        const next = getTabbableAfter(current);
+        if (!next || !composedContains(viewport, next))
+            return;
+        const after = getTabbableAfter(current, { exclude: viewport });
+        if (!after)
+            return;
+        event.preventDefault();
+        after.focus(FOCUS_VISIBLE);
+    }
+    /**
+     * Arrow keys, Home and End move between the bar's triggers and links; Tab still visits each.
+     * While a panel is open the open panel follows focus: a trigger switches to its panel (focus
+     * stays on the trigger) and a link closes it. With no panel open they only move focus.
+     */
+    let listElement = null;
+    const list = (node) => {
+        listElement = node;
+        const off = on(node, 'keydown', (event) => {
+            if (event.defaultPrevented)
+                return;
+            const current = event.target.closest(ITEM_SELECTOR);
+            if (!current || !node.contains(current))
+                return;
+            if (event.key === 'Tab') {
+                if (!event.ctrlKey && !event.metaKey)
+                    skipForeignPanel(event, current);
+                return;
+            }
+            if (hasShortcutModifier(event))
+                return;
+            const step = arrowStep(event.key, false);
+            const edge = event.key === 'Home' ? 'first' : event.key === 'End' ? 'last' : null;
+            if (!step && !edge)
+                return;
+            const items = enabledItems(node);
+            const index = items.indexOf(current);
+            if (index === -1)
+                return;
+            const target = edge === 'first' ? items[0] : edge === 'last' ? items.at(-1) : items[index + step];
+            event.preventDefault();
+            if (!target || target === current)
+                return;
+            if (isOpen)
+                followFocusWithPanel(event, target);
+            target.focus(FOCUS_VISIBLE);
+        });
+        return () => {
+            off();
+            if (listElement === node)
+                listElement = null;
+        };
+    };
+    function followFocusWithPanel(event, target) {
+        const value = [...triggers].find(([, element]) => element === target)?.[0];
+        if (value === undefined) {
+            requestChange(null, { reason: 'list-navigation', event, interaction: 'keyboard' });
+            return;
+        }
+        requestChange(value, {
+            reason: 'list-navigation',
+            event,
+            trigger: target,
+            interaction: 'keyboard'
+        });
+    }
+    /** Whether the arrow keys belong to the control itself: it edits text or picks an option. */
+    const ownsArrowKeys = (element) => isTextField(element) || element.matches('select');
+    /**
+     * From inside the open panel, the inline arrows go to the neighbouring entry of the bar, as in
+     * a menubar: a trigger opens its panel and focus lands on that panel's first control (so the
+     * arrows keep walking across menus); a link closes the panel and takes focus. The bar's ends do
+     * not wrap.
+     */
+    function moveToAdjacentEntry(event, step) {
+        const bar = listElement;
+        const current = activeTrigger;
+        if (!bar || !current)
+            return;
+        event.preventDefault();
+        const items = enabledItems(bar);
+        const target = items[items.indexOf(current) + step];
+        if (!target)
+            return;
+        const value = [...triggers].find(([, element]) => element === target)?.[0];
+        if (value === undefined) {
+            if (requestChange(null, { reason: 'list-navigation', event, interaction: 'keyboard' }))
+                target.focus(FOCUS_VISIBLE);
+            return;
+        }
+        const opened = requestChange(value, {
+            reason: 'list-navigation',
+            event,
+            trigger: target,
+            interaction: 'keyboard'
+        });
+        if (!opened)
+            return;
+        void tick().then(() => {
+            const first = activePanel ? getTabbableElements(activePanel)[0] : undefined;
+            (first ?? target).focus(FOCUS_VISIBLE);
+        });
+    }
+    /**
+     * Inside the open panel, ArrowDown and ArrowUp move between its links and buttons (wrapping at
+     * either end), the inline arrows move to the neighbouring menu of the bar (see
+     * `moveToAdjacentEntry`), and Home and End jump to the first and last. Disabled links and collapsed nested
+     * levels are not tab stops, so they are skipped. A text field keeps its arrow keys, and a
+     * control that handles them itself (it calls `preventDefault()`) wins.
+     */
+    function panelKeydown(event) {
+        if (event.defaultPrevented)
+            return;
+        const panel = activePanel;
+        const target = event.target;
+        if (!isOpen || !panel || !(target instanceof HTMLElement))
+            return;
+        if (!composedContains(panel, target))
+            return;
+        if (event.key === 'Tab') {
+            leaveAtPageEnd(event, panel, target);
+            return;
+        }
+        if (hasShortcutModifier(event) || ownsArrowKeys(target))
+            return;
+        if (event.key === 'ArrowLeft' || event.key === 'ArrowRight') {
+            moveToAdjacentEntry(event, arrowStep(event.key, false));
+            return;
+        }
+        const step = arrowStep(event.key, true);
+        const edge = event.key === 'Home' ? 'first' : event.key === 'End' ? 'last' : null;
+        if (!step && !edge)
+            return;
+        const items = getTabbableElements(panel).filter((element) => !ownsArrowKeys(element));
+        const index = items.indexOf(target);
+        if (index === -1 || items.length === 0)
+            return;
+        const next = edge === 'first'
+            ? items[0]
+            : edge === 'last'
+                ? items[items.length - 1]
+                : items[(index + step + items.length) % items.length];
+        event.preventDefault();
+        if (next !== target)
+            next.focus(FOCUS_VISIBLE);
+    }
+    /**
+     * Tab past the panel's last control when nothing in the page follows the trigger: the Tab
+     * bridge leaves the key to the engine, which moves focus out of the page, and the panel closes
+     * as it does when Tab moves on to anything else.
+     */
+    function leaveAtPageEnd(event, panel, target) {
+        const anchor = activeTrigger;
+        if (event.shiftKey || event.ctrlKey || event.metaKey || !anchor)
+            return;
+        if (getTabbableElements(panel).at(-1) !== target)
+            return;
+        if (getTabbableAfter(anchor, { exclude: viewportElement }))
+            return;
+        requestChange(null, { reason: 'focus-out', event, interaction: 'keyboard' });
+    }
+    function triggerKeydown(value, event) {
+        if (event.defaultPrevented || event.key !== 'ArrowDown' || hasShortcutModifier(event))
+            return;
+        event.preventDefault();
+        if (options.value() === value) {
+            // Already open: move into it.
+            const first = activePanel ? getTabbableElements(activePanel)[0] : undefined;
+            first?.focus(FOCUS_VISIBLE);
+            return;
+        }
+        // Opening keeps focus on the trigger; Tab or ArrowDown again enters the panel.
+        requestChange(value, {
+            reason: 'list-navigation',
+            event,
+            trigger: triggers.get(value),
+            interaction: 'keyboard'
+        });
+    }
+    // ---- attachments -----------------------------------------------------------------------
+    const root = (node) => {
+        navElement = node;
+        const offLayer = layer.node(node);
+        return () => {
+            offLayer();
+            if (navElement === node)
+                navElement = null;
+        };
+    };
+    const trigger = (value) => (node) => untrack(() => {
+        triggers.set(value, node);
+        const offKeydown = on(node, 'keydown', (event) => triggerKeydown(value, event));
+        return () => {
+            offKeydown();
+            if (triggers.get(value) === node)
+                triggers.delete(value);
+        };
+    });
+    const viewport = (node) => untrack(() => {
+        viewportElement = node;
+        const offSafeArea = safeArea.floatingReference(node);
+        return () => {
+            offSafeArea();
+            if (viewportElement === node)
+                viewportElement = null;
+        };
+    });
+    const popup = (node) => untrack(() => {
+        popupElement = node;
+        const offKeydown = on(node, 'keydown', panelKeydown);
+        return () => {
+            offKeydown();
+            if (popupElement === node)
+                popupElement = null;
+        };
+    });
+    const panel = (value) => (node) => {
+        untrack(() => panelElements.set(value, node));
+        // Reads the state it animates for: a kept-mounted panel runs again when it becomes active.
+        const active = displayValue === value && isOpen;
+        const animation = active ? untrack(() => animatePanel(node)) : undefined;
+        return () => {
+            animation?.cancel();
+            untrack(() => {
+                if (panelElements.get(value) === node)
+                    panelElements.delete(value);
+            });
+        };
+    };
+    return {
+        get panels() {
+            return panels;
+        },
+        get isOpen() {
+            return isOpen;
+        },
+        get value() {
+            return activeValue;
+        },
+        get displayValue() {
+            return displayValue;
+        },
+        get displayItem() {
+            return panels.find((panel) => panel.value === displayValue) ?? null;
+        },
+        get rendered() {
+            return rendered;
+        },
+        get visible() {
+            return visible;
+        },
+        get status() {
+            return lifecycle.status;
+        },
+        get activationDirection() {
+            return activationDirection;
+        },
+        get direction() {
+            return getDirection();
+        },
+        get openOnHover() {
+            return options.openOnHover();
+        },
+        get keepMounted() {
+            return options.keepMounted();
+        },
+        get delay() {
+            return options.delay();
+        },
+        isSwitching,
+        panelOut,
+        panelIndex,
+        triggerId: (value) => `${options.id}-trigger-${panelIndex(value)}`,
+        panelId: (value) => `${options.id}-panel-${panelIndex(value)}`,
+        /** Whether the panel for `value` has its element in the DOM now. */
+        hasPanel: (value) => panelElements.has(value),
+        isOpenFor: (value) => activeValue === value,
+        safeArea,
+        nestedOpen,
+        close,
+        pressLink,
+        pressTrigger,
+        hoverTrigger,
+        handleFocusOut,
+        layer,
+        root,
+        list,
+        trigger,
+        viewport,
+        popup,
+        panel
+    };
+}
+const CONTEXT = Symbol('entasis:navigation-menu');
+export function setNavigationMenuState(state) {
+    setContext(CONTEXT, state);
+    return state;
+}
+export function getNavigationMenuState() {
+    return getContext(CONTEXT);
+}