@primitiv-ui/react 0.1.28 → 0.1.29

package/src/NavigationMenu/hooks/useNavigationMenuTrigger.ts

@@ -0,0 +1,158 @@
+import { useCallback, useEffect, useRef } from "react";
+import type { KeyboardEvent, MouseEvent, PointerEvent, RefObject } from "react";
+
+import { composeEventHandlers } from "../../Slot/index.ts";
+import { PANEL_FOCUSABLE_SELECTOR } from "../constants";
+import { useNavigationMenuContext } from "../NavigationMenuContext";
+import type { NavigationMenuTriggerProps } from "../types";
+import { getTriggerAnchorName } from "../utils";
+
+import { useNavigationMenuEntry } from "./useNavigationMenuEntry";
+import { useNavigationMenuTopLevelEntry } from "./useNavigationMenuTopLevelEntry";
+
+export 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;
+} {
+  const {
+    orientation,
+    dir,
+    setOpenValue,
+    openOnHover,
+    openWithIntent,
+    cancelOpen,
+  } = useNavigationMenuContext();
+  const { value, triggerId, panelId, open, state } = useNavigationMenuEntry();
+  const { entryRef: triggerRef, handleKeyDown: handleArrowKeyDown } =
+    useNavigationMenuTopLevelEntry<HTMLButtonElement>();
+
+  // 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<boolean | undefined>(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<HTMLElement>(PANEL_FOCUSABLE_SELECTOR)
+      ?.focus();
+  }, [open, panelId]);
+
+  const enterPanel = useCallback(
+    (event: KeyboardEvent<HTMLButtonElement>) => {
+      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<HTMLElement>(PANEL_FOCUSABLE_SELECTOR)
+          ?.focus();
+        return;
+      }
+      setOpenValue(value);
+    },
+    [cancelOpen, enterPanelKey, open, panelId, setOpenValue, value],
+  );
+
+  const handleClick = composeEventHandlers<MouseEvent<HTMLButtonElement>>(
+    onClick,
+    toggle,
+  );
+  const handlePointerEnter = composeEventHandlers<
+    PointerEvent<HTMLButtonElement>
+  >(onPointerEnter, hoverOpen);
+  const handlePointerLeave = composeEventHandlers<
+    PointerEvent<HTMLButtonElement>
+  >(onPointerLeave, pointerLeave);
+  // enterPanel runs first and claims its arrow with preventDefault; the travel
+  // keymap only sees keys it left alone.
+  const handleKeyDown = composeEventHandlers<KeyboardEvent<HTMLButtonElement>>(
+    onKeyDown,
+    composeEventHandlers<KeyboardEvent<HTMLButtonElement>>(
+      enterPanel,
+      handleArrowKeyDown,
+    ),
+  );
+
+  return {
+    triggerRef,
+    triggerId,
+    panelId,
+    open,
+    state,
+    anchorName: getTriggerAnchorName(triggerId),
+    handleClick,
+    handlePointerEnter,
+    handlePointerLeave,
+    handleKeyDown,
+  };
+}

package/src/NavigationMenu/hooks/useNavigationMenuViewport.ts

@@ -0,0 +1,101 @@
+import { useCallback, useEffect, useState } from "react";
+import type { CSSProperties } from "react";
+
+import { useNavigationMenuContext } from "../NavigationMenuContext";
+
+type Size = { width: number; height: number } | null;
+
+/**
+ * Measures the open panel and hands its size back as custom properties.
+ *
+ * The same division of labour as the Indicator: the library ships no styles, so
+ * the Viewport can't size itself — but only it can see which panel is open and
+ * how big that panel is. Publishing the measurement as
+ * `--primitiv-navigation-menu-viewport-width` / `-height` lets a stylesheet
+ * transition the shared box between panels (the one-box morph), while leaving it
+ * free to ignore both and let the box hug its content instead.
+ *
+ * The measurement is **kept through the close**: clearing it would collapse the
+ * box to nothing at the very moment the exit animation needs its size, so the
+ * last open panel's dimensions stay published until another panel opens.
+ */
+export function useNavigationMenuViewport(): {
+  open: boolean;
+  openValue: string;
+  orientation: "horizontal" | "vertical";
+  style: CSSProperties;
+} {
+  const { orientation, openValue, viewport } = useNavigationMenuContext();
+  const open = openValue !== "";
+  const [size, setSize] = useState<Size>(null);
+
+  const measure = useCallback(() => {
+    // Nothing open: hold the last measurement so the exit animates from the size
+    // it was, rather than snapping to zero before it starts.
+    if (openValue === "") return;
+    if (!viewport) {
+      setSize(null);
+      return;
+    }
+    // Only a Content carries data-state inside the viewport, and only direct
+    // children are projected panels — so this finds the open panel without the
+    // headless layer needing a class to look for.
+    const panel = Array.from(viewport.children).find(
+      (child): child is HTMLElement =>
+        child instanceof HTMLElement && child.dataset.state === "open",
+    );
+    if (!panel) {
+      setSize(null);
+      return;
+    }
+    setSize({ width: panel.offsetWidth, height: panel.offsetHeight });
+  }, [openValue, viewport]);
+
+  useEffect(() => {
+    measure();
+    // A panel's very first paint can still be mid a browser-internal multi-pass
+    // layout — confirmed live: a multi-line description's true wrapped height
+    // was consistently one frame behind this effect's own synchronous read (a
+    // CSS Grid intrinsic-sizing quirk on a genuinely new subtree), publishing a
+    // too-short height that only self-corrected on the next real open. One
+    // rAF-deferred re-measurement catches that up; it's harmless to repeat on
+    // an already-settled panel, since re-measuring just republishes the same
+    // numbers.
+    const raf = requestAnimationFrame(measure);
+    return () => cancelAnimationFrame(raf);
+  }, [measure]);
+
+  // Panel size is layout-dependent, so a reflow invalidates it — the same reason
+  // the Indicator re-measures here.
+  useEffect(() => {
+    window.addEventListener("resize", measure);
+    return () => window.removeEventListener("resize", measure);
+  }, [measure]);
+
+  // A web font (e.g. Google Fonts' display=swap) can still be loading when this
+  // effect's own measurement runs, and the swap's reflow lands asynchronously,
+  // after — nothing else invalidates the published size when that happens, so it
+  // stays locked to the pre-swap layout until some unrelated event (a resize, or
+  // the next open) happens to re-measure. `document.fonts` is absent in jsdom
+  // (and, historically, some very old browsers), hence the guard.
+  useEffect(() => {
+    const fonts = document.fonts;
+    if (!fonts) return;
+    fonts.addEventListener("loadingdone", measure);
+    return () => fonts.removeEventListener("loadingdone", measure);
+  }, [measure]);
+
+  // `undefined` is dropped by React, so a viewport that has never hosted an open
+  // panel publishes nothing at all rather than a zeroed size the stylesheet would
+  // have to special-case.
+  const style = {
+    "--primitiv-navigation-menu-viewport-width": size
+      ? `${size.width}px`
+      : undefined,
+    "--primitiv-navigation-menu-viewport-height": size
+      ? `${size.height}px`
+      : undefined,
+  } as CSSProperties;
+
+  return { open, openValue, orientation, style };
+}

package/src/NavigationMenu/index.ts

@@ -0,0 +1,3 @@
+export * from "./NavigationMenu";
+export * from "./NavigationMenuContext";
+export * from "./types";

package/src/NavigationMenu/types.ts

@@ -0,0 +1,259 @@
+import { ComponentProps, Ref } from "react";
+
+/** Layout axis of the navigation list. `"horizontal"` binds
+ * ArrowLeft/ArrowRight between top-level entries; `"vertical"` binds
+ * ArrowUp/ArrowDown. */
+export type NavigationMenuOrientation = "horizontal" | "vertical";
+
+/** Reading direction of the navigation list. In `"rtl"` the horizontal arrow
+ * pair is mirrored so navigation follows the visual order. */
+export type NavigationMenuReadingDirection = "ltr" | "rtl";
+
+/** Uncontrolled `NavigationMenu.Root` props: the component owns which panel is
+ * open, seeded by an optional `defaultValue`. */
+export type UncontrolledNavigationMenuRootProps = {
+  /** Value of the entry whose panel is open on first render. Omit (or pass
+   * `""`) to start with everything closed. */
+  defaultValue?: string;
+  value?: never;
+  onValueChange?: never;
+};
+
+/** Controlled `NavigationMenu.Root` props: the caller owns which panel is open
+ * via `value`, and is notified of open/close requests through
+ * `onValueChange`. */
+export type ControlledNavigationMenuRootProps = {
+  /** Value of the entry whose panel is open. `""` means every panel is
+   * closed. */
+  value: string;
+  /** Called with the requested open value — the entry's value to open it, or
+   * `""` to close whatever is open. */
+  onValueChange: (value: string) => void;
+  defaultValue?: never;
+};
+
+/**
+ * Props for {@link NavigationMenuRoot | `NavigationMenu.Root`} — the `<nav>`
+ * landmark and the owner of which panel is open. Extends the native `<nav>`
+ * props and resolves to either the
+ * {@link UncontrolledNavigationMenuRootProps | uncontrolled} or the
+ * {@link ControlledNavigationMenuRootProps | controlled} shape, never a mix.
+ *
+ * `defaultValue` and `dir` are `Omit`-ted from the inherited `<nav>` props
+ * before being re-declared: both narrow a same-named native attribute
+ * (`defaultValue` to the open-panel value, `dir` to `"ltr" | "rtl"`), and
+ * leaving the native declarations in place would resolve them to intersection
+ * artifacts that leak into consumer types and the generated prop tables.
+ *
+ * @extends HTMLElement
+ */
+export type NavigationMenuRootProps = Omit<
+  ComponentProps<"nav">,
+  "defaultValue" | "dir"
+> & {
+  /** Layout axis; see {@link NavigationMenuOrientation}.
+   * @default "horizontal" */
+  orientation?: NavigationMenuOrientation;
+  /** Reading direction; see {@link NavigationMenuReadingDirection}. Inherited
+   * from the nearest `DirectionProvider` when omitted, falling back to
+   * `"ltr"`. */
+  dir?: NavigationMenuReadingDirection;
+  /** Whether hovering a trigger opens its panel. Set `false` for a
+   * click-only nav — hover-to-open is the desktop convention, but it has no
+   * touch equivalent and some products prefer to opt out.
+   * @default true */
+  openOnHover?: boolean;
+  /** Milliseconds a trigger must be hovered before its panel opens — the
+   * hover-intent delay that stops a panel flashing open as the pointer
+   * crosses the nav on its way somewhere else. `0` opens immediately.
+   * Ignored once a panel is already open: moving between triggers always
+   * switches without delay. Ignored entirely when
+   * {@link NavigationMenuRootProps.openOnHover | `openOnHover`} is `false`.
+   * @default 200 */
+  delayDuration?: number;
+  /** Milliseconds the open panel survives after the pointer leaves the
+   * `<nav>`, so a pointer that clips the edge of a panel on its way back
+   * doesn't dismiss it. Returning to the nav within the window cancels the
+   * close.
+   * @default 150 */
+  closeDelay?: number;
+} & (
+    | UncontrolledNavigationMenuRootProps
+    | ControlledNavigationMenuRootProps
+  );
+
+/**
+ * Props for {@link NavigationMenuList | `NavigationMenu.List`} — all native
+ * `<ul>` attributes. No props are added; content is
+ * {@link NavigationMenuItem | `NavigationMenu.Item`}s.
+ *
+ * @extends HTMLUListElement
+ */
+export type NavigationMenuListProps = ComponentProps<"ul">;
+
+/**
+ * Props for {@link NavigationMenuItem | `NavigationMenu.Item`} — all native
+ * `<li>` attributes plus the entry's `value`.
+ *
+ * `value` is `Omit`-ted from the inherited `<li>` props before being
+ * re-declared: `<li value>` is a native ordinal number attribute, and leaving
+ * it in place resolves this prop to an intersection artifact
+ * (`string | (readonly string[] & string)`) that leaks into consumer hovers and
+ * the generated prop tables.
+ *
+ * @extends HTMLLIElement
+ */
+export type NavigationMenuItemProps = Omit<ComponentProps<"li">, "value"> & {
+  /** Identifies the entry's panel. Required for an entry that has a
+   * `NavigationMenu.Trigger`; omit it for a plain link entry. */
+  value?: string;
+};
+
+/**
+ * Props for {@link NavigationMenuTrigger | `NavigationMenu.Trigger`} — the
+ * `<button>` that opens an entry's panel. The element type defaults to
+ * `HTMLButtonElement` and can be overridden through `asChild` and the `ref`
+ * type parameter.
+ *
+ * `ref` is `Omit`-ted from the inherited `<button>` props before being
+ * re-declared, so narrowing it to a different element under `asChild` yields a
+ * usable `Ref<T>` rather than an unusable intersection of both.
+ *
+ * @extends HTMLButtonElement
+ */
+export type NavigationMenuTriggerProps<
+  T extends HTMLElement = HTMLButtonElement,
+> = Omit<ComponentProps<"button">, "ref"> & {
+  /** Renders the child element instead of the default `<button>`. All
+   * disclosure ARIA attributes, the hover-intent and keyboard handlers, and
+   * the internal ref are merged onto the child via {@link Slot}. The child
+   * must be a single React element that accepts a `ref`.
+   * @default false */
+  asChild?: boolean;
+  /** Ref to the rendered element. Defaults to `HTMLButtonElement`; when using
+   * `asChild`, specify the child's element type. */
+  ref?: Ref<T>;
+};
+
+/**
+ * Props for {@link NavigationMenuContent | `NavigationMenu.Content`} — all
+ * native `<div>` attributes plus `forceMount`.
+ *
+ * @extends HTMLDivElement
+ */
+export type NavigationMenuContentProps = ComponentProps<"div"> & {
+  /** Keeps the closed panel out of the `hidden` state so CSS can animate it
+   * in and out, marking it `aria-hidden` instead so assistive technology
+   * still ignores it. Without this the panel is `hidden` when closed, which no
+   * transition can animate away from.
+   * @default false */
+  forceMount?: boolean;
+};
+
+/**
+ * Props for {@link NavigationMenuViewport | `NavigationMenu.Viewport`} — all
+ * native `<div>` attributes plus `forceMount`.
+ *
+ * @extends HTMLDivElement
+ */
+export type NavigationMenuViewportProps = ComponentProps<"div"> & {
+  /** Keeps the viewport unhidden while nothing is open so CSS can animate the
+   * box collapsing and expanding. Mirrors
+   * {@link NavigationMenuContentProps.forceMount | `Content`'s `forceMount`}.
+   * @default false */
+  forceMount?: boolean;
+};
+
+/**
+ * Props for {@link NavigationMenuIndicator | `NavigationMenu.Indicator`} — all
+ * native `<div>` attributes plus `forceMount`. The measured geometry arrives as
+ * inline custom properties on `style`; a consumer `style` is merged over the
+ * top, so it can override everything except the two geometry properties it
+ * doesn't set.
+ *
+ * @extends HTMLDivElement
+ */
+export type NavigationMenuIndicatorProps = ComponentProps<"div"> & {
+  /** Keeps the indicator unhidden while nothing is open so CSS can animate it
+   * out rather than having it vanish.
+   * @default false */
+  forceMount?: boolean;
+  /** Renders the child element instead of the default `<div>`, merging the
+   * `data-*` state hooks and the geometry custom properties onto it via
+   * {@link Slot}. Use it to make the marker an icon — an `<svg>` arrow, a
+   * `<Chevron />` component — rather than a styled box. The child must be a
+   * single React element that accepts a `ref`.
+   * @default false */
+  asChild?: boolean;
+};
+
+/**
+ * Props for {@link NavigationMenuLink | `NavigationMenu.Link`} — all native
+ * `<a>` attributes plus `active` and the `asChild` escape hatch.
+ *
+ * @extends HTMLAnchorElement
+ */
+export type NavigationMenuLinkProps = ComponentProps<"a"> & {
+  /** Marks this link as the page the user is currently on, setting
+   * `aria-current="page"` and the `data-active` styling hook. The component
+   * does no route matching of its own — the consumer owns the router, so it
+   * owns the comparison.
+   * @default false */
+  active?: boolean;
+  /** Renders the child element instead of a native `<a>`, merging all of
+   * `NavigationMenu.Link`'s props — `aria-current`, `data-active`, the
+   * panel-dismissing click handler, `ref` — onto it via {@link Slot}. Use for
+   * routing-library link components.
+   * @default false */
+  asChild?: boolean;
+};
+
+/** Whether the surrounding subtree is inside a `NavigationMenu.Content`
+ * panel. A `NavigationMenu.Link` uses it to tell a top-level entry (which
+ * joins the arrow-key travel order) from a link inside a panel (which does
+ * not). */
+export type NavigationMenuPanelContextValue = boolean;
+
+/** The value shared by `NavigationMenu.Root` with its descendants. */
+export type NavigationMenuContextValue = {
+  orientation: NavigationMenuOrientation;
+  dir: NavigationMenuReadingDirection;
+  navigationMenuId: string;
+  openValue: string;
+  /** The entry that was open immediately before {@link openValue}, or `""` when
+   * the menu was closed. Together with `entryKeys` this is what lets a panel
+   * derive its travel direction; see `getPanelMotion`. */
+  previousValue: string;
+  setOpenValue: (next: string) => void;
+  openOnHover: boolean;
+  /** Opens `value` after the hover-intent delay, or immediately when another
+   * panel is already open. */
+  openWithIntent: (value: string) => void;
+  /** Abandons a hover-intent open that hasn't fired yet. */
+  cancelOpen: () => void;
+  /** Adds (or, with `null`, removes) a top-level entry's element from the
+   * registry that arrow-key navigation walks. */
+  registerEntry: (key: string, element: HTMLElement | null) => void;
+  /** Registry keys in DOM order — the arrow-key travel order. */
+  entryKeys: string[];
+  /** Adds (or, with `null`, removes) a disclosure entry's `<li>` from the
+   * value-keyed registry. */
+  registerItem: (value: string, element: HTMLLIElement | null) => void;
+  /** The disclosure entries' `value`s in DOM order. Distinct from
+   * {@link NavigationMenuContextValue.entryKeys | `entryKeys`}, which is keyed by
+   * generated id so plain link entries can join it — this one is what a panel
+   * uses to work out which direction the open entry moved. */
+  itemValues: string[];
+  /** Moves DOM focus to a registered top-level entry. */
+  focusEntry: (key: string) => void;
+  /** The mounted `NavigationMenu.Viewport` element, or `null` when the nav
+   * doesn't use one. Panels project into it when it exists. */
+  viewport: HTMLDivElement | null;
+  /** Ref callback a `NavigationMenu.Viewport` hands its element to. */
+  registerViewport: (element: HTMLDivElement | null) => void;
+};
+
+/** The value shared by `NavigationMenu.Item` with its descendants. */
+export type NavigationMenuItemContextValue = {
+  value: string | undefined;
+};

package/src/NavigationMenu/utils.ts

@@ -0,0 +1,89 @@
+import { deriveId } from "../utils/index.ts";
+
+/** Derives the paired trigger / panel ids for one entry, so `aria-controls`
+ * and `aria-labelledby` line up without either side constructing the
+ * template literal itself. */
+export function getTriggerAndPanelIds(
+  navigationMenuId: string,
+  value: string,
+): { triggerId: string; panelId: string } {
+  return {
+    triggerId: deriveId(navigationMenuId, "trigger", value),
+    panelId: deriveId(navigationMenuId, "panel", value),
+  };
+}
+
+/** Turns an id into a CSS `<custom-ident>`-safe fragment for use inside an
+ * `anchor-name`. `deriveId`'s output carries React 18's colon-bracketed
+ * `useId()` root (e.g. `:r0:-trigger-concepts`), and colons aren't valid
+ * there — each character outside `[A-Za-z0-9_-]` becomes a hyphen instead. */
+export function toAnchorIdentFragment(id: string): string {
+  return id.replace(/[^A-Za-z0-9_-]/g, "-");
+}
+
+/** The `anchor-name` a disclosure trigger publishes, and the value the
+ * shared Viewport's `position-anchor` targets once that trigger's panel is
+ * open. Derived from the trigger's own id, so it stays unique per entry and
+ * per `NavigationMenu.Root` instance without any extra bookkeeping. */
+export function getTriggerAnchorName(triggerId: string): string {
+  return `--primitiv-navigation-menu-trigger-${toAnchorIdentFragment(triggerId)}`;
+}
+
+/** Which way a panel is travelling as the open entry changes — the hook a
+ * stylesheet needs to slide panels in the direction of the pointer rather than
+ * cross-fading every switch. `from-*` is an entering panel, `to-*` a leaving
+ * one, and the suffix is the side it moves from / toward. */
+export type NavigationMenuPanelMotion =
+  | "from-start"
+  | "from-end"
+  | "to-start"
+  | "to-end";
+
+/**
+ * Derives a panel's motion from the disclosure-entry order (`itemValues`, in DOM
+ * order) and which entry was open before.
+ *
+ * Returns `undefined` — meaning "no direction, just fade" — for the two cases
+ * that genuinely have none: the first open (nothing to travel from) and the full
+ * close (nothing to travel to). Also for an entry missing from the registry,
+ * since a direction derived from an unknown position would be a guess.
+ */
+export function getPanelMotion({
+  value,
+  openValue,
+  previousValue,
+  itemValues,
+}: {
+  value: string;
+  openValue: string;
+  previousValue: string;
+  itemValues: readonly string[];
+}): NavigationMenuPanelMotion | undefined {
+  const opening = value === openValue;
+  const closing = value === previousValue;
+  // A panel that is neither the current nor the outgoing one is a bystander.
+  if (!opening && !closing) return undefined;
+
+  // No `value !== ""` guard: the empty string is never a registered entry, so the
+  // lookup below rejects it on the same path as any other unknown value.
+  const selfIndex = itemValues.indexOf(value);
+  if (selfIndex === -1) return undefined;
+
+  if (opening) {
+    const fromIndex = itemValues.indexOf(previousValue);
+    if (fromIndex === -1) return undefined;
+    // Travelling toward the end means the new panel arrives from the end side.
+    // The two indices can only be equal if previousValue === openValue, and Root
+    // records a previous value only when the open value *changes* — so `<` and `<=`
+    // agree on every input that can actually reach here.
+    // Stryker disable next-line EqualityOperator: equivalent — see above.
+    return fromIndex < selfIndex ? "from-end" : "from-start";
+  }
+
+  const toIndex = itemValues.indexOf(openValue);
+  if (toIndex === -1) return undefined;
+  // The outgoing panel leaves opposite the direction of travel. Equal indices are
+  // unreachable for the same reason as the entering branch above.
+  // Stryker disable next-line EqualityOperator: equivalent — see above.
+  return toIndex > selfIndex ? "to-start" : "to-end";
+}