@primitiv-ui/react 0.1.29 → 0.1.31

package/src/Tooltip/hooks/useTooltipContent.ts

@@ -29,6 +29,9 @@ export function useTooltipContent({
   useEffect(() => {
     if (!open) return;
     const handlePointerDown = (event: PointerEvent) => {
+      // Stryker disable next-line OptionalChaining: equivalent — this listener
+      // is only attached while `open` is true, and the Content `<div>` (and
+      // therefore internalRef.current) is always mounted whenever open is true.
       if (internalRef.current?.contains(event.target as Node)) return;
       onPointerDownOutside?.(event);
       if (event.defaultPrevented) return;

package/src/Tooltip/hooks/useTooltipProvider.ts

@@ -14,15 +14,32 @@ export function useTooltipProvider({
   const [isOpenGlobally, setIsOpenGlobally] = useState(false);
   const skipDelayTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
 
-  const onOpenGlobally = useCallback(() => {
-    if (skipDelayTimerRef.current !== null) {
-      clearTimeout(skipDelayTimerRef.current);
-      skipDelayTimerRef.current = null;
-    }
-    setIsOpenGlobally(true);
-  }, []);
+  const onOpenGlobally = useCallback(
+    () => {
+      // Stryker disable next-line ConditionalExpression: equivalent —
+      // clearTimeout(null) is a spec'd no-op, so forcing this guard true is
+      // harmless when no skip-delay timer is pending; the false / never-clear
+      // variant is killed by the "clears a pending skip-delay timer when a
+      // tooltip opens again within the skip window" test.
+      if (skipDelayTimerRef.current !== null) {
+        clearTimeout(skipDelayTimerRef.current);
+        skipDelayTimerRef.current = null;
+      }
+      setIsOpenGlobally(true);
+    },
+    // Stryker disable next-line ArrayDeclaration: equivalent — no dependency to freeze.
+    [],
+  );
 
   const onCloseGlobally = useCallback(() => {
+    // Cancel before re-scheduling. The ref tracks only the newest timer, so
+    // overwriting it without cancelling orphans the previous one: it survives,
+    // fires unobserved, and can no longer be cancelled by a later open. Two
+    // closes in a row is not hypothetical — `closeImmediate` is unguarded and
+    // both Escape and blur are wired straight to it, so pressing Escape and then
+    // tabbing away leaks a timer. `clearTimeout(undefined)` is a spec'd no-op, so
+    // this needs no guard for the first close.
+    clearTimeout(skipDelayTimerRef.current ?? undefined);
     skipDelayTimerRef.current = setTimeout(() => {
       setIsOpenGlobally(false);
       skipDelayTimerRef.current = null;
@@ -33,13 +50,22 @@ export function useTooltipProvider({
   // component it was scheduled from unless explicitly cancelled — without
   // this, an in-flight timer fires after unmount and can throw once its
   // surrounding environment (e.g. a test's jsdom `window`) is gone.
-  useEffect(() => {
-    return () => {
-      if (skipDelayTimerRef.current !== null) {
-        clearTimeout(skipDelayTimerRef.current);
-      }
-    };
-  }, []);
+  useEffect(
+    () => {
+      return () => {
+        // Stryker disable next-line ConditionalExpression: equivalent —
+        // clearTimeout(null) is a spec'd no-op, so forcing this guard true is
+        // harmless when no skip-delay timer is pending; the false / never-clear
+        // variant is killed by the "clears the pending skip-delay timeout on
+        // unmount" test.
+        if (skipDelayTimerRef.current !== null) {
+          clearTimeout(skipDelayTimerRef.current);
+        }
+      };
+    },
+    // Stryker disable next-line ArrayDeclaration: equivalent — no dependency to freeze (mount/unmount only).
+    [],
+  );
 
   const contextValue: TooltipProviderContextValue = {
     delayDuration,

package/src/Tooltip/hooks/useTooltipRoot.ts

@@ -31,6 +31,11 @@ export function useTooltipRoot({
   const gracePeriodTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
 
   const openImmediate = useCallback(() => {
+    // Stryker disable next-line ConditionalExpression: equivalent —
+    // clearTimeout(null) is a spec'd no-op, so forcing this guard true is
+    // harmless when no open timer is pending; the false / never-clear variant
+    // is killed by the "cancels a pending hover-delay open timer when the
+    // trigger is focused before it elapses" test.
     if (openTimerRef.current !== null) {
       clearTimeout(openTimerRef.current);
       openTimerRef.current = null;
@@ -52,6 +57,11 @@ export function useTooltipRoot({
   }, [openImmediate, effectiveDelayDuration, providerCtx.isOpenGlobally]);
 
   const closeImmediate = useCallback(() => {
+    // Stryker disable next-line ConditionalExpression: equivalent —
+    // clearTimeout(null) is a spec'd no-op, so forcing this guard true is
+    // harmless when no grace timer is pending; the false / never-clear variant
+    // is killed by the "cancels a pending grace-period timer when the tooltip
+    // closes immediately during the grace window" test.
     if (gracePeriodTimerRef.current !== null) {
       clearTimeout(gracePeriodTimerRef.current);
       gracePeriodTimerRef.current = null;
@@ -60,14 +70,28 @@ export function useTooltipRoot({
     providerCtx.onCloseGlobally();
   }, [setOpen, providerCtx]);
 
-  const cancelGrace = useCallback(() => {
-    if (gracePeriodTimerRef.current !== null) {
-      clearTimeout(gracePeriodTimerRef.current);
-      gracePeriodTimerRef.current = null;
-    }
-  }, []);
+  const cancelGrace = useCallback(
+    () => {
+      // Stryker disable next-line ConditionalExpression: equivalent —
+      // clearTimeout(null) is a spec'd no-op, so forcing this guard true is
+      // harmless when no grace timer is pending; the false / never-clear
+      // variant is killed by the "cancels the grace-period close timer when
+      // the pointer moves into the content" test.
+      if (gracePeriodTimerRef.current !== null) {
+        clearTimeout(gracePeriodTimerRef.current);
+        gracePeriodTimerRef.current = null;
+      }
+    },
+    // Stryker disable next-line ArrayDeclaration: equivalent — no dependency to freeze.
+    [],
+  );
 
   const closeWithGrace = useCallback(() => {
+    // Stryker disable next-line ConditionalExpression: equivalent —
+    // clearTimeout(null) is a spec'd no-op, so forcing this guard true is
+    // harmless when no open timer is pending; the false / never-clear variant
+    // is killed by the "cancels a pending hover-delay open timer when the
+    // pointer leaves before it elapses" test.
     if (openTimerRef.current !== null) {
       clearTimeout(openTimerRef.current);
       openTimerRef.current = null;

package/src/Tree/README.md

@@ -56,7 +56,7 @@ Passing both `default*` and the controlled prop is a type error.
 
 ```ts
 // Uncontrolled
-<Tree.Root defaultExpandedValues={["src"]} onExpandedChange={(v) => …}>
+<Tree.Root defaultExpandedValues={["src"]} onExpandedChange={(v) => ...}>
 
 // Controlled
 <Tree.Root expandedValues={values} onExpandedChange={setValues}>
@@ -70,14 +70,14 @@ The selection shape depends on `selectionMode`:
 
 ```ts
 // Single (default) — selectedValue is `string | null`
-<Tree.Root defaultSelectedValue="readme" onSelectedValueChange={(v) => …}>
+<Tree.Root defaultSelectedValue="readme" onSelectedValueChange={(v) => ...}>
 <Tree.Root selectedValue={v} onSelectedValueChange={setV}>
 
 // Multiple — selectedValues is `string[]`
 <Tree.Root
   selectionMode="multiple"
   defaultSelectedValues={["readme", "index"]}
-  onSelectedValuesChange={(v) => …}
+  onSelectedValuesChange={(v) => ...}
 >
 <Tree.Root
   selectionMode="multiple"
@@ -187,7 +187,7 @@ styles.
 > [role="treeitem"][data-depth="2"] > .row {
 >   padding-inline-start: 3rem;
 > }
-> /* …extend as deep as your tree can go */
+> /* ...extend as deep as your tree can go */
 > ```
 >
 > **2. Set a CSS variable inline from the render layer** — the
@@ -223,6 +223,70 @@ styles.
 > }
 > ```
 
+## Wrapping Tree in a styled layer
+
+`Tree.Branch` finds its control and content by **inspecting its children before
+rendering them**, so it sees the component you wrote — not what that component
+renders. A styling layer that wraps each part in its own component to attach
+classes is therefore invisible to it, and the branch throws:
+
+```
+A Tree.Branch must contain a <Tree.BranchControl>.
+```
+
+Set `TREE_PART` on the wrapper and it partitions like the part it renders:
+
+```tsx
+import { TREE_PART, Tree } from "@primitiv-ui/react";
+
+function StyledBranchControl(props: TreeBranchControlProps) {
+  return <Tree.BranchControl {...props} className="row" />;
+}
+StyledBranchControl[TREE_PART] = "branch-control";
+
+function StyledBranchContent(props: TreeBranchContentProps) {
+  return <Tree.BranchContent {...props} className="group" />;
+}
+StyledBranchContent[TREE_PART] = "branch-content";
+```
+
+The accepted names are `"branch-control"` and `"branch-content"`
+(`TreePartName`). Only these two parts need it — every other part is found by
+position or context, not by inspection. The one-control and one-content rules
+still apply: two marked controls in a branch is still an error.
+
+This is what the registry `tree` component does; no other primitive in the
+library needs a marker, because none of the others read their children's types.
+
+### Indenting without `attr()`
+
+`useTreeLevel()` returns `{ depth }` — `0` directly under `Tree.Root`, one
+deeper per enclosing `BranchContent`. A styling layer needs the depth as a
+*number* to apply the indent as the **row's own padding**, which is what keeps
+each row's box full-width so a hover or selected band runs edge to edge rather
+than starting at the nested level. Reading `data-depth` back in CSS would need
+`attr(data-depth type(<integer>))` — Chrome 133+ / Safari 18.2+, unsupported in
+Firefox — so the depth is exposed here instead.
+
+```tsx
+function StyledItem(props: TreeItemProps) {
+  const { depth } = useTreeLevel();
+  return (
+    <Tree.Item
+      {...props}
+      style={{ "--depth": depth } as CSSProperties}
+      className="row"
+    />
+  );
+}
+```
+
+```css
+.row {
+  padding-inline-start: calc(var(--depth, 0) * 1.25rem + 0.5rem);
+}
+```
+
 ## Selection path
 
 `Tree.Item` and `Tree.Branch` accept an optional `label` prop. It does
@@ -256,7 +320,7 @@ import { Tree } from "@primitiv-ui/react";
 import { ChevronRight } from "@primitiv-ui/icons";
 
 <Tree.Root defaultSelectedValue="index">
-  …
+  ...
   <Tree.SelectionPath separator={<ChevronRight />} />
 </Tree.Root>;
 ```

package/src/Tree/Tree.tsx

@@ -88,7 +88,7 @@ import type {
  *   selectionMode="multiple"
  *   onSelectedValuesChange={(values) => console.log(values)}
  * >
- *   {…}
+ *   {...}
  * </Tree.Root>
  * ```
  */

package/src/Tree/__tests__/Tree.styled-wrapper.test.tsx

@@ -0,0 +1,159 @@
+import { render, screen } from "@testing-library/react";
+import type { ComponentPropsWithRef } from "react";
+import { describe, expect, it } from "vitest";
+
+import { Tree, TREE_PART, useTreeLevel } from "../index";
+
+/**
+ * A styled layer wraps every part in its own component to attach classes — the
+ * shape `primitiv add tree` copies into a consumer repo. `Tree.Branch` finds its
+ * control and content by inspecting its children, so those wrappers have to be
+ * recognisable as the parts they render; without that, Tree is the one primitive
+ * in the library that cannot be wrapped at all.
+ */
+function StyledBranchControl(props: ComponentPropsWithRef<typeof Tree.BranchControl>) {
+  return <Tree.BranchControl {...props} className="styled-control" />;
+}
+StyledBranchControl[TREE_PART] = "branch-control";
+
+function StyledBranchContent(props: ComponentPropsWithRef<typeof Tree.BranchContent>) {
+  return <Tree.BranchContent {...props} className="styled-content" />;
+}
+StyledBranchContent[TREE_PART] = "branch-content";
+
+describe("Tree — styled wrappers", () => {
+  it("accepts a wrapper component in place of Tree.BranchControl", () => {
+    // Arrange / Act
+    render(
+      <Tree.Root defaultExpandedValues={["src"]}>
+        <Tree.Branch value="src">
+          <StyledBranchControl>src</StyledBranchControl>
+          <StyledBranchContent>
+            <Tree.Item value="index.ts">index.ts</Tree.Item>
+          </StyledBranchContent>
+        </Tree.Branch>
+      </Tree.Root>,
+    );
+
+    // Assert
+    expect(screen.getByText("src")).toHaveClass("styled-control");
+    expect(screen.getByRole("group")).toHaveClass("styled-content");
+  });
+
+  it("labels the branch by its wrapped control, so the name is just the row", () => {
+    // Arrange / Act
+    render(
+      <Tree.Root defaultExpandedValues={["src"]}>
+        <Tree.Branch value="src">
+          <StyledBranchControl>src</StyledBranchControl>
+          <StyledBranchContent>
+            <Tree.Item value="index.ts">index.ts</Tree.Item>
+          </StyledBranchContent>
+        </Tree.Branch>
+      </Tree.Root>,
+    );
+
+    // Assert — the branch treeitem takes its accessible name from the control
+    // row alone, not from the whole subtree.
+    expect(screen.getByRole("treeitem", { name: "src" })).toHaveAttribute(
+      "aria-expanded",
+      "true",
+    );
+  });
+
+  it("reads forceMount from the wrapper element, not from what it renders", () => {
+    // A styled layer animates the open/close transition, which needs the group
+    // to stay mounted while closed. Tree.Branch reads `forceMount` off the
+    // element it is handed, so setting it *inside* the wrapper is invisible —
+    // the subtree unmounts and there is nothing left to animate. This is the
+    // contract the registry surface depends on.
+
+    // Arrange / Act — closed, with forceMount on the wrapper element
+    const { rerender } = render(
+      <Tree.Root>
+        <Tree.Branch value="src">
+          <StyledBranchControl>src</StyledBranchControl>
+          <StyledBranchContent forceMount>
+            <Tree.Item value="index.ts">index.ts</Tree.Item>
+          </StyledBranchContent>
+        </Tree.Branch>
+      </Tree.Root>,
+    );
+
+    // Assert — still in the DOM, marked closed and hidden from AT
+    const group = document.querySelector('[role="group"]');
+    expect(group).toHaveAttribute("data-state", "closed");
+    expect(group).toHaveAttribute("aria-hidden", "true");
+
+    // Act — without it, the branch drops the subtree entirely
+    rerender(
+      <Tree.Root>
+        <Tree.Branch value="src">
+          <StyledBranchControl>src</StyledBranchControl>
+          <StyledBranchContent>
+            <Tree.Item value="index.ts">index.ts</Tree.Item>
+          </StyledBranchContent>
+        </Tree.Branch>
+      </Tree.Root>,
+    );
+
+    // Assert
+    expect(document.querySelector('[role="group"]')).toBeNull();
+  });
+
+  it("still rejects two controls when both are wrappers", () => {
+    // Arrange / Act / Assert
+    expect(() =>
+      render(
+        <Tree.Root>
+          <Tree.Branch value="src">
+            <StyledBranchControl>one</StyledBranchControl>
+            <StyledBranchControl>two</StyledBranchControl>
+          </Tree.Branch>
+        </Tree.Root>,
+      ),
+    ).toThrow("A Tree.Branch may contain at most one <Tree.BranchControl>.");
+  });
+});
+
+describe("useTreeLevel", () => {
+  function Depth() {
+    const { depth } = useTreeLevel();
+    return <span data-testid={`depth-${depth}`}>{depth}</span>;
+  }
+
+  it("reports the nesting depth so a styled layer can indent without attr()", () => {
+    // A styled layer needs the depth as a NUMBER to compute a row's indent.
+    // Reading it back off `data-depth` in CSS needs `attr(... type(<integer>))`,
+    // which Firefox does not support — so the depth is exposed here instead.
+
+    // Arrange / Act
+    render(
+      <Tree.Root defaultExpandedValues={["a", "b"]}>
+        <Depth />
+        <Tree.Branch value="a">
+          <StyledBranchControl>a</StyledBranchControl>
+          <StyledBranchContent>
+            <Depth />
+            <Tree.Branch value="b">
+              <StyledBranchControl>b</StyledBranchControl>
+              <StyledBranchContent>
+                <Depth />
+              </StyledBranchContent>
+            </Tree.Branch>
+          </StyledBranchContent>
+        </Tree.Branch>
+      </Tree.Root>,
+    );
+
+    // Assert — 0 at the root, one deeper per BranchContent
+    expect(screen.getByTestId("depth-0")).toBeInTheDocument();
+    expect(screen.getByTestId("depth-1")).toBeInTheDocument();
+    expect(screen.getByTestId("depth-2")).toBeInTheDocument();
+  });
+
+  it("throws outside a Tree", () => {
+    // Arrange / Act / Assert
+    expect(() => render(<Depth />)).toThrow();
+  });
+});

package/src/Tree/hooks/useTreePath.ts

@@ -1,4 +1,4 @@
-import { useTreeContext } from "../TreeContext";
+import { useTreeContext, useTreeLevelContext } from "../TreeContext";
 
 import type { TreePathSegment } from "../types";
 
@@ -66,3 +66,35 @@ export function useTreeSelectionPaths(): TreePathSegment[][] {
   const { selectedOrder, getPath } = useTreeContext();
   return selectedOrder.map((value) => getPath(value));
 }
+
+/**
+ * Read the current nesting depth inside a `Tree` — `0` for a node directly
+ * under {@link TreeRoot | `Tree.Root`}, one deeper per enclosing
+ * {@link TreeBranchContent | `Tree.BranchContent`}.
+ *
+ * A styling layer needs the depth as a *number* to compute a row's indent, and
+ * so to make the row span the tree's full width (a hover or selected band that
+ * runs edge to edge, as VS Code and most file trees do). Reading it back off
+ * the `data-depth` attribute in CSS requires `attr(data-depth type(<integer>))`,
+ * which Firefox does not support — hence this hook.
+ *
+ * @throws If called outside a `Tree.Root`.
+ *
+ * @example Indenting a row so its background still spans the full width
+ * ```tsx
+ * function StyledItem(props: TreeItemProps) {
+ *   const { depth } = useTreeLevel();
+ *   return (
+ *     <Tree.Item
+ *       {...props}
+ *       style={{ "--depth": depth } as CSSProperties}
+ *       className="row"
+ *     />
+ *   );
+ * }
+ * ```
+ */
+export function useTreeLevel(): { depth: number } {
+  const { depth } = useTreeLevelContext();
+  return { depth };
+}

package/src/Tree/index.ts

@@ -1,3 +1,8 @@
 export * from "./Tree";
 export * from "./types";
-export { useTreePath, useTreeSelectionPaths } from "./hooks/useTreePath";
+export { TREE_PART, type TreePartName } from "./utils";
+export {
+  useTreeLevel,
+  useTreePath,
+  useTreeSelectionPaths,
+} from "./hooks/useTreePath";

package/src/Tree/utils.ts

@@ -3,14 +3,56 @@ import type { ReactElement, ReactNode } from "react";
 
 import { TreeBranchControl, TreeBranchContent } from "./Tree";
 
-/** Whether `node` is a `Tree.BranchControl` element. */
+/**
+ * The property a component sets on itself to declare which `Tree` part it
+ * stands in for.
+ *
+ * `Tree.Branch` finds its control and content by inspecting its children before
+ * rendering them, so it sees the component the consumer wrote — not what that
+ * component renders. A styled layer wraps every part in its own component to
+ * attach classes (that is exactly what `primitiv add tree` copies), and without
+ * a marker those wrappers are unrecognisable, making `Tree` the one primitive
+ * in the library that cannot be wrapped at all.
+ *
+ * Set it on the wrapper and it partitions like the part it renders:
+ *
+ * ```tsx
+ * function StyledBranchControl(props: TreeBranchControlProps) {
+ *   return <Tree.BranchControl {...props} className="row" />;
+ * }
+ * StyledBranchControl[TREE_PART] = "branch-control";
+ * ```
+ */
+export const TREE_PART: "__primitivTreePart" = "__primitivTreePart";
+
+/** The part names {@link TREE_PART} accepts. */
+export type TreePartName = "branch-control" | "branch-content";
+
+/** Read a component's {@link TREE_PART} marker, if it declares one. */
+function treePartOf(type: unknown): TreePartName | undefined {
+  return (type as Record<string, TreePartName | undefined> | null)?.[TREE_PART];
+}
+
+/**
+ * Whether `node` is a `Tree.BranchControl` element — either the part itself, or
+ * a component that marks itself as standing in for it (see {@link TREE_PART}).
+ */
 export function isBranchControlElement(node: ReactNode): node is ReactElement {
-  return isValidElement(node) && node.type === TreeBranchControl;
+  return (
+    isValidElement(node) &&
+    (node.type === TreeBranchControl || treePartOf(node.type) === "branch-control")
+  );
 }
 
-/** Whether `node` is a `Tree.BranchContent` element. */
+/**
+ * Whether `node` is a `Tree.BranchContent` element — either the part itself, or
+ * a component that marks itself as standing in for it (see {@link TREE_PART}).
+ */
 export function isBranchContentElement(node: ReactNode): node is ReactElement {
-  return isValidElement(node) && node.type === TreeBranchContent;
+  return (
+    isValidElement(node) &&
+    (node.type === TreeBranchContent || treePartOf(node.type) === "branch-content")
+  );
 }
 
 /**

package/src/VisuallyHidden/VisuallyHidden.tsx

@@ -61,7 +61,7 @@ const visuallyHiddenStyle: CSSProperties = {
  * ```tsx
  * <nav aria-labelledby="nav-label">
  *   <VisuallyHidden id="nav-label">Primary navigation</VisuallyHidden>
- *   …
+ *   ...
  * </nav>
  * ```
  *

package/src/hooks/index.ts

@@ -1,3 +1,4 @@
 export { useControllableState } from "./useControllableState";
 export { useCollection } from "./useCollection";
 export { useRovingTabindex } from "./useRovingTabindex";
+export { useTypeahead } from "./useTypeahead";

package/src/hooks/useTypeahead.ts

@@ -0,0 +1,95 @@
+import { useCallback, useRef, type KeyboardEvent } from "react";
+
+type UseTypeaheadArgs = {
+  /** Reads the navigable (enabled) option values in current DOM order. Called
+   * per keystroke so an in-place reorder is picked up. */
+  getNavigable: () => string[];
+  /** Reads an option's visible label, used for prefix matching. */
+  getLabel: (optionValue: string) => string;
+  /** The option the cursor is on, or `undefined` before it is seeded. */
+  currentKey: string | undefined;
+  /** Moves the cursor to the matched option. */
+  onMatch: (optionValue: string) => void;
+  /** Milliseconds of inactivity after which the accumulated query resets. */
+  resetMs: number;
+};
+
+/**
+ * Printable-character typeahead for a list cursor, per APG's
+ * recommendation for lists longer than about seven options. Shared by
+ * `Listbox` and `MillerColumns` (which scopes it to the focused column).
+ *
+ * Keystrokes accumulate into a query that resets after `resetMs` of
+ * inactivity. A query of all-identical
+ * characters is treated as a repeat of that single character, which cycles
+ * through the options starting with it rather than searching for a literal
+ * run — so pressing "a" three times walks the "a" options instead of looking
+ * for "aaa". Matching is a case-insensitive prefix test against the option's
+ * text, and the search wraps.
+ */
+export function useTypeahead({
+  getNavigable,
+  getLabel,
+  currentKey,
+  onMatch,
+  resetMs,
+}: UseTypeaheadArgs): {
+  handleTypeahead: (event: KeyboardEvent<HTMLElement>) => void;
+} {
+  const stateRef = useRef<{ query: string; timer: number | null }>({
+    query: "",
+    timer: null,
+  });
+
+  const handleTypeahead = useCallback(
+    (event: KeyboardEvent<HTMLElement>) => {
+      if (event.key.length !== 1) return;
+
+      const navigable = getNavigable();
+      // Stryker disable next-line ConditionalExpression: equivalent — the match loop is bounded by navigable.length, so an empty list exits immediately anyway.
+      if (navigable.length === 0) return;
+
+      const state = stateRef.current;
+      // Stryker disable next-line ConditionalExpression,EqualityOperator: equivalent — keystroke handling is synchronous, so clearing (or not clearing) the pending reset cannot change this search's outcome.
+      if (state.timer !== null) window.clearTimeout(state.timer);
+      state.query = (state.query + event.key).toLowerCase();
+      state.timer = window.setTimeout(() => {
+        state.query = "";
+        state.timer = null;
+      }, resetMs);
+
+      const isRepeat =
+        // Stryker disable next-line ConditionalExpression,EqualityOperator: equivalent — for a single character `every()` is trivially true, so both forms yield the same isRepeat.
+        state.query.length > 1 &&
+        state.query.split("").every((char) => char === state.query[0]);
+      const searchQuery = isRepeat ? state.query[0] : state.query;
+
+      // A single character (or a repeat of one) advances past the current
+      // option so pressing the same letter walks the matches; a genuine
+      // multi-character query narrows in place instead. With no cursor at all
+      // there is nothing to advance past, so the search starts at the top.
+      const currentIndex =
+        // Stryker disable next-line ConditionalExpression: equivalent — indexOf(undefined) is itself -1.
+        currentKey === undefined ? -1 : navigable.indexOf(currentKey);
+      // Stryker disable next-line ConditionalExpression,EqualityOperator: equivalent — with no cursor the two spellings produce the same scan: startIndex -1 with offset 1 and startIndex 0 with offset 0 both begin at index 0 and step identically.
+      const hasCursor = currentIndex >= 0;
+      const startIndex = hasCursor ? currentIndex : 0;
+      const offset =
+        hasCursor && (searchQuery.length === 1 || isRepeat) ? 1 : 0;
+
+      // Stryker disable next-line EqualityOperator: equivalent — the index wraps modulo navigable.length, so an extra iteration only re-checks an already-visited option.
+      for (let i = 0; i < navigable.length; i++) {
+        const index = (startIndex + offset + i) % navigable.length;
+        const label = getLabel(navigable[index]).trim().toLowerCase();
+        if (label.startsWith(searchQuery)) {
+          event.preventDefault();
+          onMatch(navigable[index]);
+          return;
+        }
+      }
+    },
+    [getNavigable, getLabel, currentKey, onMatch, resetMs],
+  );
+
+  return { handleTypeahead };
+}