@primitiv-ui/react 0.1.38 → 0.1.40

package/dist/NavigationMenu/NavigationMenuContext.js

@@ -0,0 +1,34 @@
+"use client";
+import { createContext } from "react";
+import { createStrictContext } from "../utils/index.js";
+const navigationMenuContextPair = createStrictContext("Component must be rendered as a child of NavigationMenu.Root", "NavigationMenuContext");
+/** Strict React context carrying the {@link NavigationMenuContextValue} from
+ * `NavigationMenu.Root` to its descendants. `null` outside a Root. */
+export const NavigationMenuContext = navigationMenuContextPair[0];
+/** Reads the {@link NavigationMenuContextValue}; throws outside a
+ * `NavigationMenu.Root`. */
+export const useNavigationMenuContext = navigationMenuContextPair[1];
+/** Provider for {@link NavigationMenuContext}, used by `NavigationMenu.Root`. */
+const NavigationMenuProvider = NavigationMenuContext.Provider;
+export { NavigationMenuProvider };
+const navigationMenuItemContextPair = createStrictContext("Component must be rendered as a child of NavigationMenu.Item", "NavigationMenuItemContext");
+/** Strict React context carrying the {@link NavigationMenuItemContextValue}
+ * from `NavigationMenu.Item` to its Trigger and Content. `null` outside an
+ * Item. */
+export const NavigationMenuItemContext = navigationMenuItemContextPair[0];
+/** Reads the {@link NavigationMenuItemContextValue}; throws outside a
+ * `NavigationMenu.Item`. */
+export const useNavigationMenuItemContext = navigationMenuItemContextPair[1];
+/** Provider for {@link NavigationMenuItemContext}, used by
+ * `NavigationMenu.Item`. */
+const NavigationMenuItemProvider = NavigationMenuItemContext.Provider;
+export { NavigationMenuItemProvider };
+/** Marks its subtree as being inside a `NavigationMenu.Content` panel.
+ * Deliberately **not** strict: the default `false` is the meaningful "I am a
+ * top-level entry" answer, so a Link outside any panel must read it without
+ * throwing. */
+export const NavigationMenuPanelContext = createContext(false);
+/** Provider for {@link NavigationMenuPanelContext}, used by
+ * `NavigationMenu.Content`. */
+const NavigationMenuPanelProvider = NavigationMenuPanelContext.Provider;
+export { NavigationMenuPanelProvider };

package/dist/NavigationMenu/constants.d.ts

@@ -0,0 +1,4 @@
+/** Focusable descendants a panel can hand focus to when the keyboard opens it
+ * with the enter-panel arrow. Deliberately narrow: nav panels hold links and
+ * the occasional button, and the first of those is the useful landing spot. */
+export declare const PANEL_FOCUSABLE_SELECTOR = "a[href], button:not([disabled]), [tabindex]:not([tabindex=\"-1\"])";

package/dist/NavigationMenu/constants.js

@@ -0,0 +1,5 @@
+"use client";
+/** Focusable descendants a panel can hand focus to when the keyboard opens it
+ * with the enter-panel arrow. Deliberately narrow: nav panels hold links and
+ * the occasional button, and the first of those is the useful landing spot. */
+export const PANEL_FOCUSABLE_SELECTOR = 'a[href], button:not([disabled]), [tabindex]:not([tabindex="-1"])';

package/dist/NavigationMenu/hooks/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./useNavigationMenuEntry.js";
+export * from "./useNavigationMenuIndicator.js";
+export * from "./useNavigationMenuLink.js";
+export * from "./useNavigationMenuRoot.js";
+export * from "./useNavigationMenuTopLevelEntry.js";
+export * from "./useNavigationMenuTrigger.js";
+export * from "./useNavigationMenuViewport.js";

package/dist/NavigationMenu/hooks/index.js

@@ -0,0 +1,7 @@
+export * from "./useNavigationMenuEntry.js";
+export * from "./useNavigationMenuIndicator.js";
+export * from "./useNavigationMenuLink.js";
+export * from "./useNavigationMenuRoot.js";
+export * from "./useNavigationMenuTopLevelEntry.js";
+export * from "./useNavigationMenuTrigger.js";
+export * from "./useNavigationMenuViewport.js";

package/dist/NavigationMenu/hooks/useNavigationMenuEntry.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Resolves everything a Trigger and its Content both need: the entry's value
+ * (from the enclosing Item), the paired ids, and whether this entry is the
+ * open one. Keeping it in one place is what guarantees the two sides agree on
+ * the ids they cross-reference.
+ */
+export declare function useNavigationMenuEntry(): {
+    value: string;
+    triggerId: string;
+    panelId: string;
+    open: boolean;
+    state: "open" | "closed";
+};

package/dist/NavigationMenu/hooks/useNavigationMenuEntry.js

@@ -0,0 +1,21 @@
+"use client";
+import { useNavigationMenuContext, useNavigationMenuItemContext, } from "../NavigationMenuContext.js";
+import { getTriggerAndPanelIds } from "../utils.js";
+/**
+ * Resolves everything a Trigger and its Content both need: the entry's value
+ * (from the enclosing Item), the paired ids, and whether this entry is the
+ * open one. Keeping it in one place is what guarantees the two sides agree on
+ * the ids they cross-reference.
+ */
+export function useNavigationMenuEntry() {
+    const { navigationMenuId, openValue } = useNavigationMenuContext();
+    const { value: itemValue } = useNavigationMenuItemContext();
+    if (itemValue === undefined) {
+        throw new Error("NavigationMenu.Trigger and NavigationMenu.Content require a `value` on their NavigationMenu.Item. " +
+            "Omit the value only for a plain link entry, which has no panel to open.");
+    }
+    const value = itemValue;
+    const { triggerId, panelId } = getTriggerAndPanelIds(navigationMenuId, value);
+    const open = openValue !== "" && openValue === value;
+    return { value, triggerId, panelId, open, state: open ? "open" : "closed" };
+}

package/dist/NavigationMenu/hooks/useNavigationMenuIndicator.d.ts

@@ -0,0 +1,16 @@
+import type { CSSProperties } from "react";
+/**
+ * Measures the open trigger and hands back the geometry as custom properties.
+ *
+ * The library ships no styles, so the Indicator can't position itself — but
+ * only it can know *where* the open trigger is. Publishing the measurement as
+ * `--primitiv-navigation-menu-indicator-position` / `-size` splits that
+ * correctly: the component measures, the stylesheet decides whether that means
+ * `translate`, `left`, a border, or nothing at all.
+ */
+export declare function useNavigationMenuIndicator(): {
+    open: boolean;
+    openValue: string;
+    orientation: "horizontal" | "vertical";
+    style: CSSProperties;
+};

package/dist/NavigationMenu/hooks/useNavigationMenuIndicator.js

@@ -0,0 +1,53 @@
+"use client";
+import { useCallback, useEffect, useState } from "react";
+import { useNavigationMenuContext } from "../NavigationMenuContext.js";
+import { getTriggerAndPanelIds } from "../utils.js";
+/**
+ * Measures the open trigger and hands back the geometry as custom properties.
+ *
+ * The library ships no styles, so the Indicator can't position itself — but
+ * only it can know *where* the open trigger is. Publishing the measurement as
+ * `--primitiv-navigation-menu-indicator-position` / `-size` splits that
+ * correctly: the component measures, the stylesheet decides whether that means
+ * `translate`, `left`, a border, or nothing at all.
+ */
+export function useNavigationMenuIndicator() {
+    const { orientation, openValue, navigationMenuId } = useNavigationMenuContext();
+    const open = openValue !== "";
+    const [geometry, setGeometry] = useState(null);
+    const measure = useCallback(() => {
+        // Closed and open-but-unrendered are the same measurement problem, so they
+        // share one path: `openValue === ""` derives a trigger id no element
+        // carries, and the missing-element branch below clears the geometry.
+        const { triggerId } = getTriggerAndPanelIds(navigationMenuId, openValue);
+        const trigger = document.getElementById(triggerId);
+        if (!trigger) {
+            setGeometry(null);
+            return;
+        }
+        setGeometry(orientation === "horizontal"
+            ? { position: trigger.offsetLeft, size: trigger.offsetWidth }
+            : { position: trigger.offsetTop, size: trigger.offsetHeight });
+    }, [navigationMenuId, openValue, orientation]);
+    useEffect(() => {
+        measure();
+    }, [measure]);
+    // Offsets are layout-dependent, so a reflow invalidates them. Re-measuring on
+    // resize is what stops the indicator drifting off its trigger after the nav
+    // rewraps.
+    useEffect(() => {
+        window.addEventListener("resize", measure);
+        return () => window.removeEventListener("resize", measure);
+    }, [measure]);
+    // An `undefined` value is dropped by React, so a closed indicator simply
+    // carries no geometry rather than a stale or zeroed one.
+    const style = {
+        "--primitiv-navigation-menu-indicator-position": geometry
+            ? `${geometry.position}px`
+            : undefined,
+        "--primitiv-navigation-menu-indicator-size": geometry
+            ? `${geometry.size}px`
+            : undefined,
+    };
+    return { open, openValue, orientation, style };
+}

package/dist/NavigationMenu/hooks/useNavigationMenuLink.d.ts

@@ -0,0 +1,8 @@
+import type { KeyboardEvent, MouseEvent, PointerEvent, RefObject } from "react";
+import type { NavigationMenuLinkProps } from "../types.js";
+export declare function useNavigationMenuLink({ onKeyDown, onClick, onPointerEnter, }: Pick<NavigationMenuLinkProps, "onKeyDown" | "onClick" | "onPointerEnter">): {
+    linkRef: RefObject<HTMLAnchorElement | null>;
+    handleKeyDown: (event: KeyboardEvent<HTMLAnchorElement>) => void;
+    handleClick: (event: MouseEvent<HTMLAnchorElement>) => void;
+    handlePointerEnter: (event: PointerEvent<HTMLAnchorElement>) => void;
+};

package/dist/NavigationMenu/hooks/useNavigationMenuLink.js

@@ -0,0 +1,37 @@
+"use client";
+import { useContext } from "react";
+import { composeEventHandlers } from "../../Slot/index.js";
+import { NavigationMenuPanelContext, useNavigationMenuContext, } from "../NavigationMenuContext.js";
+import { useNavigationMenuTopLevelEntry } from "./useNavigationMenuTopLevelEntry.js";
+export function useNavigationMenuLink({ onKeyDown, onClick, onPointerEnter, }) {
+    const { setOpenValue, cancelOpen, openOnHover } = useNavigationMenuContext();
+    // A link directly inside an Item is a top-level entry and joins the
+    // arrow-key travel order; a link inside a Content panel is reached by Tab
+    // instead, so it must stay out of that order.
+    const insidePanel = useContext(NavigationMenuPanelContext);
+    const { entryRef: linkRef, handleKeyDown: handleArrowKeyDown } = useNavigationMenuTopLevelEntry(!insidePanel);
+    const handleKeyDown = composeEventHandlers(onKeyDown, handleArrowKeyDown);
+    // Following a link ends the interaction, so the menu closes — whether the
+    // link was in a panel or a top-level entry alongside one. Leaving a panel
+    // hanging open over the page the user just navigated to is the bug this
+    // avoids.
+    const handleClick = composeEventHandlers(onClick, () => {
+        cancelOpen();
+        setOpenValue("");
+    });
+    // Hovering a top-level link dismisses whatever is open, so travelling along the
+    // bar past a plain entry behaves like travelling onto another trigger. Without
+    // this, moving from an open trigger onto a link beside it leaves that panel
+    // hanging over the page with the pointer nowhere near it.
+    //
+    // Panel links are exempt for the obvious reason: hovering a row inside a panel
+    // must not close the panel it lives in. And it follows `openOnHover`, so a
+    // click-only nav stays click-only in both directions.
+    const handlePointerEnter = composeEventHandlers(onPointerEnter, () => {
+        if (insidePanel || !openOnHover)
+            return;
+        cancelOpen();
+        setOpenValue("");
+    });
+    return { linkRef, handleKeyDown, handleClick, handlePointerEnter };
+}

package/dist/NavigationMenu/hooks/useNavigationMenuRoot.d.ts

@@ -0,0 +1,26 @@
+import type { CSSProperties, FocusEvent, KeyboardEvent } from "react";
+import type { NavigationMenuContextValue, NavigationMenuOrientation, NavigationMenuReadingDirection, NavigationMenuRootProps } from "../types.js";
+/** The presentation props arrive **resolved**: `NavigationMenu.Root` applies
+ * its own documented defaults (and inherits `dir` from `DirectionProvider`)
+ * before calling the hook, so they are required here rather than defaulted a
+ * second time — one set of defaults, in the place consumers read them from. */
+type UseNavigationMenuRootArgs = {
+    orientation: NavigationMenuOrientation;
+    dir: NavigationMenuReadingDirection;
+    openOnHover: boolean;
+    delayDuration: number;
+    closeDelay: number;
+} & Pick<NavigationMenuRootProps, "defaultValue" | "value" | "onValueChange">;
+export declare function useNavigationMenuRoot({ orientation, dir, openOnHover, delayDuration, closeDelay, defaultValue, value, onValueChange, }: UseNavigationMenuRootArgs): {
+    contextValue: NavigationMenuContextValue;
+    cancelClose: () => void;
+    closeWithDelay: () => void;
+    closeOnFocusOutside: (event: FocusEvent<HTMLElement>) => void;
+    handleKeyDown: (event: KeyboardEvent<HTMLElement>) => void;
+    /** Publishes the open entry's trigger `anchor-name` as
+     * `--primitiv-navigation-menu-active-trigger-anchor`, so the shared
+     * Viewport's `position-anchor` can target whichever trigger is open. Unset
+     * (dropped by React) while nothing is open. */
+    style: CSSProperties;
+};
+export {};

package/dist/NavigationMenu/hooks/useNavigationMenuRoot.js

@@ -0,0 +1,202 @@
+"use client";
+import { useCallback, useEffect, useId, useMemo, useRef, useState } from "react";
+import { useCollection, useControllableState } from "../../hooks/index.js";
+import { getTriggerAnchorName, getTriggerAndPanelIds } from "../utils.js";
+export function useNavigationMenuRoot({ orientation, dir, openOnHover, delayDuration, closeDelay, defaultValue, value, onValueChange, }) {
+    const navigationMenuId = useId();
+    const [openValue, setOpenValue] = useControllableState(value, defaultValue ?? "", onValueChange);
+    // What was open before the current value, so a panel can tell which way the
+    // pointer travelled. Adjusted during render — the pattern React documents for
+    // deriving state from a changed input — rather than in an effect: an effect
+    // lands a frame late, by which time the panel has already begun animating with
+    // no direction to animate in.
+    const [trackedValue, setTrackedValue] = useState(openValue);
+    // The seed is only ever fed to `itemValues.indexOf()`, which rejects "" and any
+    // other unregistered string identically — so its value is unobservable. It has to
+    // be "" rather than `openValue`, though: seeding it with the open value would give
+    // a nav mounted with a `defaultValue` a spurious travel direction on first paint.
+    // Stryker disable next-line StringLiteral: equivalent — see above.
+    const [previousValue, setPreviousValue] = useState("");
+    if (trackedValue !== openValue) {
+        setPreviousValue(trackedValue);
+        setTrackedValue(openValue);
+    }
+    const { register: registerEntry, itemsRef: entriesRef, keys: entryKeys, } = useCollection();
+    // A second registry, keyed by the Item's own `value`. The entry registry above
+    // can't serve this: it keys by a generated id because plain link entries join it
+    // too and have no value. Registration order is mount order, which for siblings is
+    // DOM order — so `itemValues` is the left-to-right order of the disclosure
+    // entries, which is what a panel needs to know which way it is travelling.
+    const { register: registerItem, itemsRef: itemElementsRef, keys: registeredValues, } = useCollection();
+    // Sorted by document position, not registration order. `useCollection` keys are
+    // insertion-ordered, which matches the DOM only while nothing changes: re-register
+    // an entry (a `value` that changes) and its key is appended, so the order silently
+    // stops describing the layout and panels slide the wrong way. Asking the DOM is the
+    // only source that cannot drift.
+    const itemValues = useMemo(() => [...registeredValues].sort((a, b) => {
+        // Non-null: `register` writes the element and the key in the same call, so a
+        // key present in `registeredValues` always has a live element in the map —
+        // the same invariant Tree's root relies on for its own registry reads.
+        const first = itemElementsRef.current.get(a);
+        const second = itemElementsRef.current.get(b);
+        return first.compareDocumentPosition(second) &
+            Node.DOCUMENT_POSITION_FOLLOWING
+            ? -1
+            : 1;
+    }), [registeredValues, itemElementsRef]);
+    const focusEntry = useCallback((key) => {
+        // `key` only ever arrives from `entryKeys`, and `useCollection`'s
+        // register() writes `entriesRef` and the `keys` state in the same call —
+        // so a key that reaches here always has a live element in the map.
+        // Stryker disable next-line OptionalChaining: unreachable given that invariant.
+        entriesRef.current.get(key)?.focus();
+    }, 
+    // `entriesRef` is a stable RefObject, so emptying this array yields the
+    // identical memoised function.
+    // Stryker disable next-line ArrayDeclaration: equivalent — stable dependency.
+    [entriesRef]);
+    // Held as state, not a ref, because Content has to re-render once the
+    // viewport exists in order to portal into it. The Viewport hands its element
+    // over in a ref callback, which React runs before paint — so the one commit
+    // where Content still renders in place never reaches the screen. `setViewport`
+    // *is* the registrar: it already has the ref-callback signature and a stable
+    // identity, so wrapping it would only add indirection.
+    const [viewport, setViewport] = useState(null);
+    // `undefined` rather than `null` for "no timer pending", because
+    // `clearTimeout(undefined)` is a spec'd no-op — cancelling is then one
+    // unconditional clear instead of a guarded one, with nothing to get wrong.
+    const openTimerRef = useRef(undefined);
+    const closeTimerRef = useRef(undefined);
+    // `openValue` is read inside callbacks that must not be re-created on every
+    // open/close — a fresh `openWithIntent` identity would re-run the Trigger's
+    // handlers. A ref keeps the reads current without widening the deps.
+    const openValueRef = useRef(openValue);
+    openValueRef.current = openValue;
+    const cancelOpen = useCallback(() => {
+        clearTimeout(openTimerRef.current);
+        openTimerRef.current = undefined;
+    }, 
+    // Stryker's only mutation of an empty dependency array is
+    // `["Stryker was here"]` — a string literal React compares `===`-equal on
+    // every render, so the memoised identity is unchanged either way.
+    // Stryker disable next-line ArrayDeclaration: equivalent — no dependency to freeze.
+    []);
+    const cancelClose = useCallback(() => {
+        clearTimeout(closeTimerRef.current);
+        closeTimerRef.current = undefined;
+    }, 
+    // Stryker disable next-line ArrayDeclaration: equivalent — no dependency to freeze (see cancelOpen).
+    []);
+    const openWithIntent = useCallback((next) => {
+        cancelClose();
+        cancelOpen();
+        // Once one panel is open the nav is already "active", so crossing to a
+        // sibling trigger swaps panels instantly — waiting again would feel
+        // broken. The delay only guards the first open.
+        if (openValueRef.current !== "" || delayDuration === 0) {
+            setOpenValue(next);
+            return;
+        }
+        openTimerRef.current = setTimeout(() => {
+            openTimerRef.current = undefined;
+            setOpenValue(next);
+        }, delayDuration);
+    }, [cancelClose, cancelOpen, delayDuration, setOpenValue]);
+    // Escape is handled once, at the `<nav>`, because it must work from anywhere
+    // inside the menu — including from a link deep in an open panel — and
+    // returning focus to the trigger is what stops the user being stranded on an
+    // element that just went `hidden`.
+    const closeAndRefocusTrigger = useCallback(() => {
+        const value = openValueRef.current;
+        if (value === "")
+            return;
+        cancelOpen();
+        const { triggerId } = getTriggerAndPanelIds(navigationMenuId, value);
+        document.getElementById(triggerId)?.focus();
+        setOpenValue("");
+    }, [cancelOpen, navigationMenuId, setOpenValue]);
+    const closeWithDelay = useCallback(() => {
+        cancelOpen();
+        closeTimerRef.current = setTimeout(() => {
+            closeTimerRef.current = undefined;
+            setOpenValue("");
+        }, closeDelay);
+    }, [cancelOpen, closeDelay, setOpenValue]);
+    // Keyboard focus leaving the `<nav>` entirely — Tab past the last entry, or
+    // into an unrelated element such as a second, independent NavigationMenu —
+    // means the open panel is no longer where focus is. Unlike Escape this
+    // doesn't refocus the trigger: focus already chose where it's going, and
+    // fighting that would break Tab order. `relatedTarget` is `null` for some
+    // focus transitions (e.g. the browser chrome); treated as "outside", the
+    // same call Carousel's own blur handler makes.
+    const closeOnFocusOutside = useCallback((event) => {
+        if (openValueRef.current === "")
+            return;
+        const next = event.relatedTarget;
+        if (next && event.currentTarget.contains(next))
+            return;
+        cancelOpen();
+        setOpenValue("");
+    }, [cancelOpen, setOpenValue]);
+    useEffect(() => () => {
+        cancelOpen();
+        cancelClose();
+    }, 
+    // Both are `useCallback(..., [])`, so their identities are fixed for the
+    // component's lifetime: emptying this array subscribes the cleanup exactly
+    // once either way.
+    // Stryker disable next-line ArrayDeclaration: equivalent — stable dependencies.
+    [cancelOpen, cancelClose]);
+    const contextValue = useMemo(() => ({
+        orientation,
+        dir,
+        navigationMenuId,
+        openValue,
+        previousValue,
+        setOpenValue,
+        openOnHover,
+        openWithIntent,
+        cancelOpen,
+        registerEntry,
+        entryKeys,
+        registerItem,
+        itemValues,
+        focusEntry,
+        viewport,
+        registerViewport: setViewport,
+    }), [
+        orientation,
+        dir,
+        navigationMenuId,
+        openValue,
+        previousValue,
+        setOpenValue,
+        openOnHover,
+        openWithIntent,
+        cancelOpen,
+        registerEntry,
+        entryKeys,
+        registerItem,
+        itemValues,
+        focusEntry,
+        viewport,
+    ]);
+    const handleKeyDown = useCallback((event) => {
+        if (event.key !== "Escape")
+            return;
+        closeAndRefocusTrigger();
+    }, [closeAndRefocusTrigger]);
+    const style = {
+        "--primitiv-navigation-menu-active-trigger-anchor": openValue === ""
+            ? undefined
+            : getTriggerAnchorName(getTriggerAndPanelIds(navigationMenuId, openValue).triggerId),
+    };
+    return {
+        contextValue,
+        cancelClose,
+        closeWithDelay,
+        closeOnFocusOutside,
+        handleKeyDown,
+        style,
+    };
+}

package/dist/NavigationMenu/hooks/useNavigationMenuTopLevelEntry.d.ts

@@ -0,0 +1,21 @@
+import type { KeyboardEvent, RefObject } from "react";
+/**
+ * Joins an element to the nav's top-level travel order: registers it so the
+ * arrow keys can reach it, and returns the keydown handler that does the
+ * reaching.
+ *
+ * Despite building on `useRovingTabindex`, this is deliberately **not** a
+ * roving tabindex — no `tabIndex={-1}` is handed back, so every top-level
+ * entry stays in the tab order. That is the ARIA APG *Disclosure Navigation
+ * Menu* contract: these are links to pages, and a keyboard user must be able
+ * to Tab through them without learning that arrows are required. The hook
+ * uses `useRovingTabindex` purely for its orientation/RTL-aware keymap.
+ *
+ * @param enabled Whether this element is a top-level entry at all. A
+ *   `NavigationMenu.Link` inside a `NavigationMenu.Content` passes `false`:
+ *   panel links are reached by Tab, not by the top-level arrow keys.
+ */
+export declare function useNavigationMenuTopLevelEntry<T extends HTMLElement>(enabled?: boolean): {
+    entryRef: RefObject<T | null>;
+    handleKeyDown: (event: KeyboardEvent<HTMLElement>) => void;
+};

package/dist/NavigationMenu/hooks/useNavigationMenuTopLevelEntry.js

@@ -0,0 +1,54 @@
+"use client";
+import { useEffect, useId, useRef } from "react";
+import { useRovingTabindex } from "../../hooks/index.js";
+import { useNavigationMenuContext } from "../NavigationMenuContext.js";
+/** Keydown handler for an element that is not a top-level entry: every travel
+ * key is left to the browser, so `Home` inside an open panel still scrolls the
+ * page rather than jumping out of the panel. */
+function ignoreTravelKeys() { }
+/**
+ * Joins an element to the nav's top-level travel order: registers it so the
+ * arrow keys can reach it, and returns the keydown handler that does the
+ * reaching.
+ *
+ * Despite building on `useRovingTabindex`, this is deliberately **not** a
+ * roving tabindex — no `tabIndex={-1}` is handed back, so every top-level
+ * entry stays in the tab order. That is the ARIA APG *Disclosure Navigation
+ * Menu* contract: these are links to pages, and a keyboard user must be able
+ * to Tab through them without learning that arrows are required. The hook
+ * uses `useRovingTabindex` purely for its orientation/RTL-aware keymap.
+ *
+ * @param enabled Whether this element is a top-level entry at all. A
+ *   `NavigationMenu.Link` inside a `NavigationMenu.Content` passes `false`:
+ *   panel links are reached by Tab, not by the top-level arrow keys.
+ */
+export function useNavigationMenuTopLevelEntry(enabled = true) {
+    const { orientation, dir, registerEntry, entryKeys, focusEntry } = useNavigationMenuContext();
+    const key = useId();
+    const entryRef = useRef(null);
+    useEffect(() => {
+        if (!enabled)
+            return;
+        registerEntry(key, entryRef.current);
+        return () => registerEntry(key, null);
+        // `key` is a `useId`, `registerEntry` a stable context callback, and
+        // `enabled` is fixed by this element's position in the tree (inside a
+        // Content panel or not) — none can change while the entry stays mounted.
+        // Stryker disable next-line ArrayDeclaration: equivalent — stable dependencies.
+    }, [enabled, key, registerEntry]);
+    const { handleKeyDown: travel } = useRovingTabindex({
+        orientation,
+        dir,
+        navigable: entryKeys,
+        currentKey: key,
+        includeHomeEnd: true,
+        // Enter/Space must reach the element as a native activation — a button's
+        // click, a link's navigation. Claiming them here would preventDefault
+        // both.
+        includeActivate: false,
+        onNavigate: (target) => focusEntry(target),
+    });
+    // A panel link must not be able to reach the top-level order — not with the
+    // arrows, and not with Home/End either — so it gets no travel handler at all.
+    return { entryRef, handleKeyDown: enabled ? travel : ignoreTravelKeys };
+}

package/dist/NavigationMenu/hooks/useNavigationMenuTrigger.d.ts

@@ -0,0 +1,16 @@
+import type { KeyboardEvent, MouseEvent, PointerEvent, RefObject } from "react";
+import type { NavigationMenuTriggerProps } from "../types.js";
+export declare function useNavigationMenuTrigger({ onClick, onPointerEnter, onPointerLeave, onKeyDown, }: Pick<NavigationMenuTriggerProps, "onClick" | "onPointerEnter" | "onPointerLeave" | "onKeyDown">): {
+    triggerRef: RefObject<HTMLButtonElement | null>;
+    triggerId: string;
+    panelId: string;
+    open: boolean;
+    state: "open" | "closed";
+    /** This trigger's own `anchor-name`, so the shared Viewport can position
+     * its panel relative to whichever trigger opened it. */
+    anchorName: string;
+    handleClick: (event: MouseEvent<HTMLButtonElement>) => void;
+    handlePointerEnter: (event: PointerEvent<HTMLButtonElement>) => void;
+    handlePointerLeave: (event: PointerEvent<HTMLButtonElement>) => void;
+    handleKeyDown: (event: KeyboardEvent<HTMLButtonElement>) => void;
+};

package/dist/NavigationMenu/hooks/useNavigationMenuTrigger.js

@@ -0,0 +1,100 @@
+"use client";
+import { useCallback, useEffect, useRef } from "react";
+import { composeEventHandlers } from "../../Slot/index.js";
+import { PANEL_FOCUSABLE_SELECTOR } from "../constants.js";
+import { useNavigationMenuContext } from "../NavigationMenuContext.js";
+import { getTriggerAnchorName } from "../utils.js";
+import { useNavigationMenuEntry } from "./useNavigationMenuEntry.js";
+import { useNavigationMenuTopLevelEntry } from "./useNavigationMenuTopLevelEntry.js";
+export function useNavigationMenuTrigger({ onClick, onPointerEnter, onPointerLeave, onKeyDown, }) {
+    const { orientation, dir, setOpenValue, openOnHover, openWithIntent, cancelOpen, } = useNavigationMenuContext();
+    const { value, triggerId, panelId, open, state } = useNavigationMenuEntry();
+    const { entryRef: triggerRef, handleKeyDown: handleArrowKeyDown } = useNavigationMenuTopLevelEntry();
+    // What `open` was when the pointer arrived, or `undefined` when no pointer
+    // is over the trigger. A pointer that comes to click first fires
+    // `pointerenter`, which — with hover-to-open — opens the panel *before* the
+    // click lands. Toggling against the live `open` would then close it again on
+    // that same click. Toggling against the pre-hover value is what makes a
+    // click mean "toggle what I saw", not "undo my own hover".
+    const openOnPointerEnterRef = useRef(undefined);
+    const toggle = useCallback(() => {
+        // A click is a decision, so it bypasses hover intent entirely — including
+        // any open timer already ticking from the pointer that arrived to click.
+        cancelOpen();
+        const wasOpen = openOnPointerEnterRef.current ?? open;
+        // Cleared so a second click on a still-hovered trigger toggles against
+        // live state rather than replaying the stale arrival value.
+        openOnPointerEnterRef.current = undefined;
+        setOpenValue(wasOpen ? "" : value);
+    }, [cancelOpen, open, setOpenValue, value]);
+    const hoverOpen = useCallback(() => {
+        openOnPointerEnterRef.current = open;
+        if (openOnHover)
+            openWithIntent(value);
+    }, [open, openOnHover, openWithIntent, value]);
+    const pointerLeave = useCallback(() => {
+        openOnPointerEnterRef.current = undefined;
+        cancelOpen();
+    }, 
+    // `cancelOpen` is a `useCallback(..., [])` on the Root, so its identity is
+    // fixed for the nav's lifetime — emptying this array yields the identical
+    // memoised function.
+    // Stryker disable next-line ArrayDeclaration: equivalent — stable dependency.
+    [cancelOpen]);
+    // The arrow that "goes into" the panel is the one pointing across the list's
+    // axis: down out of a horizontal bar, sideways out of a vertical rail (and
+    // that sideways key mirrors under RTL).
+    const enterPanelKey = orientation === "horizontal"
+        ? "ArrowDown"
+        : dir === "rtl"
+            ? "ArrowLeft"
+            : "ArrowRight";
+    // Focus can only land in the panel once it has actually rendered unhidden, so
+    // the keypress records the intent and this effect spends it.
+    const enterPanelPendingRef = useRef(false);
+    useEffect(() => {
+        if (!enterPanelPendingRef.current || !open)
+            return;
+        enterPanelPendingRef.current = false;
+        document
+            .getElementById(panelId)
+            ?.querySelector(PANEL_FOCUSABLE_SELECTOR)
+            ?.focus();
+    }, [open, panelId]);
+    const enterPanel = useCallback((event) => {
+        if (event.key !== enterPanelKey)
+            return;
+        event.preventDefault();
+        cancelOpen();
+        enterPanelPendingRef.current = true;
+        // Already-open panels never re-run the effect (`open` doesn't change), so
+        // move focus straight away in that case.
+        if (open) {
+            enterPanelPendingRef.current = false;
+            document
+                .getElementById(panelId)
+                ?.querySelector(PANEL_FOCUSABLE_SELECTOR)
+                ?.focus();
+            return;
+        }
+        setOpenValue(value);
+    }, [cancelOpen, enterPanelKey, open, panelId, setOpenValue, value]);
+    const handleClick = composeEventHandlers(onClick, toggle);
+    const handlePointerEnter = composeEventHandlers(onPointerEnter, hoverOpen);
+    const handlePointerLeave = composeEventHandlers(onPointerLeave, pointerLeave);
+    // enterPanel runs first and claims its arrow with preventDefault; the travel
+    // keymap only sees keys it left alone.
+    const handleKeyDown = composeEventHandlers(onKeyDown, composeEventHandlers(enterPanel, handleArrowKeyDown));
+    return {
+        triggerRef,
+        triggerId,
+        panelId,
+        open,
+        state,
+        anchorName: getTriggerAnchorName(triggerId),
+        handleClick,
+        handlePointerEnter,
+        handlePointerLeave,
+        handleKeyDown,
+    };
+}