@primitiv-ui/react 0.1.27 → 0.1.29

package/src/NavigationMenu/__tests__/NavigationMenu.viewport.test.tsx

@@ -0,0 +1,113 @@
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { NavigationMenu } from "../NavigationMenu";
+import type { NavigationMenuViewportProps } from "../types";
+
+function NavWithViewport(props: NavigationMenuViewportProps) {
+  return (
+    <NavigationMenu.Root>
+      <NavigationMenu.List>
+        <NavigationMenu.Item value="concepts">
+          <NavigationMenu.Trigger>Concepts</NavigationMenu.Trigger>
+          <NavigationMenu.Content data-testid="concepts-panel">
+            <NavigationMenu.Link href="/tokens">Tokens</NavigationMenu.Link>
+          </NavigationMenu.Content>
+        </NavigationMenu.Item>
+        <NavigationMenu.Item value="registry">
+          <NavigationMenu.Trigger>Registry</NavigationMenu.Trigger>
+          <NavigationMenu.Content data-testid="registry-panel">
+            <NavigationMenu.Link href="/cli">CLI</NavigationMenu.Link>
+          </NavigationMenu.Content>
+        </NavigationMenu.Item>
+      </NavigationMenu.List>
+      <NavigationMenu.Viewport data-testid="viewport" {...props} />
+    </NavigationMenu.Root>
+  );
+}
+
+describe("NavigationMenu.Viewport", () => {
+  it("hosts every panel so they share one box", async () => {
+    render(<NavWithViewport />);
+
+    const viewport = screen.getByTestId("viewport");
+
+    // Panels portal into an inner clip element, not the outer box itself — the
+    // split that lets the outer box host the hover-forgiveness collar (which
+    // must extend past its own edges) while the inner one clips a sliding
+    // panel to the visible box. See the registry stylesheet.
+    await waitFor(() => {
+      const clip = screen.getByTestId("concepts-panel").parentElement;
+      expect(clip).toHaveAttribute("data-navigation-menu-viewport-clip");
+      expect(clip?.parentElement).toBe(viewport);
+    });
+    expect(
+      screen.getByTestId("registry-panel").parentElement?.parentElement,
+    ).toBe(viewport);
+  });
+
+  it("leaves panels in place when there is no Viewport", () => {
+    render(
+      <NavigationMenu.Root>
+        <NavigationMenu.List>
+          <NavigationMenu.Item value="concepts">
+            <NavigationMenu.Trigger>Concepts</NavigationMenu.Trigger>
+            <NavigationMenu.Content data-testid="concepts-panel" />
+          </NavigationMenu.Item>
+        </NavigationMenu.List>
+      </NavigationMenu.Root>,
+    );
+
+    expect(screen.getByTestId("concepts-panel").parentElement?.tagName).toBe(
+      "LI",
+    );
+  });
+
+  it("reports its own open state and hides itself while nothing is open", async () => {
+    const user = userEvent.setup();
+    render(<NavWithViewport />);
+
+    const viewport = screen.getByTestId("viewport");
+
+    expect(viewport).toHaveAttribute("data-state", "closed");
+    expect(viewport).toHaveAttribute("hidden");
+
+    await user.click(screen.getByRole("button", { name: "Concepts" }));
+
+    expect(viewport).toHaveAttribute("data-state", "open");
+    expect(viewport).not.toHaveAttribute("hidden");
+  });
+
+  it("carries the open entry's value so the box can size per panel", async () => {
+    const user = userEvent.setup();
+    render(<NavWithViewport />);
+
+    await user.click(screen.getByRole("button", { name: "Registry" }));
+
+    expect(screen.getByTestId("viewport")).toHaveAttribute(
+      "data-value",
+      "registry",
+    );
+  });
+
+  it("stays mounted and unhidden with forceMount", () => {
+    render(<NavWithViewport forceMount />);
+
+    const viewport = screen.getByTestId("viewport");
+
+    expect(viewport).not.toHaveAttribute("hidden");
+    expect(viewport).toHaveAttribute("data-state", "closed");
+  });
+
+  it("still lands keyboard focus inside a hosted panel", async () => {
+    const user = userEvent.setup();
+    render(<NavWithViewport />);
+
+    screen.getByRole("button", { name: "Concepts" }).focus();
+    await user.keyboard("{ArrowDown}");
+
+    await waitFor(() =>
+      expect(screen.getByRole("link", { name: "Tokens" })).toHaveFocus(),
+    );
+  });
+});

package/src/NavigationMenu/constants.ts

@@ -0,0 +1,5 @@
+/** 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/src/NavigationMenu/hooks/index.ts

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

package/src/NavigationMenu/hooks/useNavigationMenuEntry.ts

@@ -0,0 +1,33 @@
+import {
+  useNavigationMenuContext,
+  useNavigationMenuItemContext,
+} from "../NavigationMenuContext";
+import { getTriggerAndPanelIds } from "../utils";
+
+/**
+ * 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(): {
+  value: string;
+  triggerId: string;
+  panelId: string;
+  open: boolean;
+  state: "open" | "closed";
+} {
+  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/src/NavigationMenu/hooks/useNavigationMenuIndicator.ts

@@ -0,0 +1,70 @@
+import { useCallback, useEffect, useState } from "react";
+import type { CSSProperties } from "react";
+
+import { useNavigationMenuContext } from "../NavigationMenuContext";
+import { getTriggerAndPanelIds } from "../utils";
+
+type Geometry = { position: number; size: number } | null;
+
+/**
+ * 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(): {
+  open: boolean;
+  openValue: string;
+  orientation: "horizontal" | "vertical";
+  style: CSSProperties;
+} {
+  const { orientation, openValue, navigationMenuId } =
+    useNavigationMenuContext();
+  const open = openValue !== "";
+  const [geometry, setGeometry] = useState<Geometry>(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,
+  } as CSSProperties;
+
+  return { open, openValue, orientation, style };
+}

package/src/NavigationMenu/hooks/useNavigationMenuLink.ts

@@ -0,0 +1,72 @@
+import { useContext } from "react";
+import type {
+  KeyboardEvent,
+  MouseEvent,
+  PointerEvent,
+  RefObject,
+} from "react";
+
+import { composeEventHandlers } from "../../Slot/index.ts";
+import {
+  NavigationMenuPanelContext,
+  useNavigationMenuContext,
+} from "../NavigationMenuContext";
+import type { NavigationMenuLinkProps } from "../types";
+
+import { useNavigationMenuTopLevelEntry } from "./useNavigationMenuTopLevelEntry";
+
+export 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;
+} {
+  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<HTMLAnchorElement>(!insidePanel);
+
+  const handleKeyDown = composeEventHandlers<KeyboardEvent<HTMLAnchorElement>>(
+    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<MouseEvent<HTMLAnchorElement>>(
+    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<
+    PointerEvent<HTMLAnchorElement>
+  >(onPointerEnter, () => {
+    if (insidePanel || !openOnHover) return;
+    cancelOpen();
+    setOpenValue("");
+  });
+
+  return { linkRef, handleKeyDown, handleClick, handlePointerEnter };
+}

package/src/NavigationMenu/hooks/useNavigationMenuRoot.ts

@@ -0,0 +1,301 @@
+import { useCallback, useEffect, useId, useMemo, useRef, useState } from "react";
+import type { CSSProperties, FocusEvent, KeyboardEvent } from "react";
+
+import { useCollection, useControllableState } from "../../hooks/index.ts";
+
+import type {
+  NavigationMenuContextValue,
+  NavigationMenuOrientation,
+  NavigationMenuReadingDirection,
+  NavigationMenuRootProps,
+} from "../types";
+import { getTriggerAnchorName, getTriggerAndPanelIds } from "../utils";
+
+/** 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 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;
+} {
+  const navigationMenuId = useId();
+  const [openValue, setOpenValue] = useControllableState<string>(
+    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<string, HTMLElement>();
+
+  // 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<string, HTMLLIElement>();
+
+  // 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: string) => {
+      // `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<HTMLDivElement | null>(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<ReturnType<typeof setTimeout> | undefined>(
+    undefined,
+  );
+  const closeTimerRef = useRef<ReturnType<typeof setTimeout> | undefined>(
+    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: string) => {
+      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: FocusEvent<HTMLElement>) => {
+    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<NavigationMenuContextValue>(
+    () => ({
+      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: KeyboardEvent<HTMLElement>) => {
+      if (event.key !== "Escape") return;
+      closeAndRefocusTrigger();
+    },
+    [closeAndRefocusTrigger],
+  );
+
+  const style = {
+    "--primitiv-navigation-menu-active-trigger-anchor":
+      openValue === ""
+        ? undefined
+        : getTriggerAnchorName(
+            getTriggerAndPanelIds(navigationMenuId, openValue).triggerId,
+          ),
+  } as CSSProperties;
+
+  return {
+    contextValue,
+    cancelClose,
+    closeWithDelay,
+    closeOnFocusOutside,
+    handleKeyDown,
+    style,
+  };
+}

package/src/NavigationMenu/hooks/useNavigationMenuTopLevelEntry.ts

@@ -0,0 +1,65 @@
+import { useEffect, useId, useRef } from "react";
+import type { KeyboardEvent, RefObject } from "react";
+
+import { useRovingTabindex } from "../../hooks/index.ts";
+import { useNavigationMenuContext } from "../NavigationMenuContext";
+
+/** 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(): void {}
+
+/**
+ * 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<T extends HTMLElement>(
+  enabled = true,
+): {
+  entryRef: RefObject<T | null>;
+  handleKeyDown: (event: KeyboardEvent<HTMLElement>) => void;
+} {
+  const { orientation, dir, registerEntry, entryKeys, focusEntry } =
+    useNavigationMenuContext();
+  const key = useId();
+  const entryRef = useRef<T | null>(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<string>({
+    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 };
+}