@primitiv-ui/react 0.1.28 → 0.1.29

package/README.md

@@ -31,6 +31,7 @@ import { Tabs } from "@primitiv-ui/react";
 | [ContextMenu](src/ContextMenu/README.md) | WAI-ARIA Menu pattern for right-click / long-press / context-key menus — native HTML `popover` compound component positioned at the cursor, with nested submenus, checkbox and radio items, `ItemIndicator` icon slot, groups and labels, keyboard navigation, typeahead, disabled-item skipping, `onSelect` escape hatch, and `asChild` composition |
 | [DirectionProvider](src/DirectionProvider/README.md) | Reading-direction context — broadcasts `ltr`/`rtl` to descendants and exposes the `useDirection` hook so direction-aware components inherit `dir` instead of each being passed it explicitly; renders no DOM |
 | [Divider](src/Divider/README.md)         | WAI-ARIA separator role — horizontal or vertical content separator, with semantic and decorative use                                                                                                                                                                                    |
+| [Drawer](src/Drawer/README.md)           | Edge-anchored dialog — a thin composition over Modal that reuses its native `<dialog>` machinery (focus trap, inert background, top layer, Esc, bounding-rect click-outside, controlled/uncontrolled state, imperative API, `asChild`, `forceMount`), adding a `side` (`top`/`right`/`bottom`/`left`) axis emitted as `data-side` for the styled layer to slide the panel from that edge |
 | [Dropdown](src/Dropdown/README.md)       | WAI-ARIA Menu Button / Menu pattern — native HTML `popover` compound component with nested submenus, checkbox and radio items, `ItemIndicator` icon slot, groups and labels, keyboard navigation, typeahead, disabled-item skipping, `onSelect` escape hatch, and `asChild` composition |
 | [EmptyState](src/EmptyState/README.md)   | Placeholder for empty collections, searches, and views — stateless compound component: a `role="status"` live region announcing on appearance, an `aria-hidden` `Media` illustration slot, `Title` and `Description` copy, an `Actions` recovery slot, and `asChild` composition on every part |
 | [Field](src/Field/README.md)             | Headless form-field coordinator — provides `FieldContext` with auto-generated `id` (via `useId`) and derived `descriptionId` / `errorId`, plus `invalid` / `disabled` / `required` cascade; sub-components for `Label` (`htmlFor`-wired), `Description`, and `ErrorText` (auto-gated by invalid state, `role="alert"`); `Input` opts in automatically when nested |
@@ -39,11 +40,14 @@ import { Tabs } from "@primitiv-ui/react";
 | [InputGroup](src/InputGroup/README.md)   | Stateless frame for `Input` (or any framed control) with named leading and trailing adornment slots — decorative icons, currency symbols, clear buttons, password-reveal toggles; `data-input-group` / `data-input-group-adornment` styling hooks, CSS-driven disabled / invalid / focus-within state via `:has()`, and `asChild` composition on every part |
 | [MillerColumns](src/MillerColumns/README.md) | Miller columns / cascading-lists pattern — a horizontal strip of `role="group"` columns of `role="treeitem"` items, authored by recursive composition with portal-projected child columns, controlled/uncontrolled active path, single-tabstop roving keyboard navigation, disabled items, and `asChild` composition |
 | [Modal](src/Modal/README.md)             | WAI-ARIA Modal Dialog pattern — native `<dialog>`-based compound component with Portal, bounding-rect click-outside, controlled/uncontrolled state, escape hatches, imperative API, `asChild`, and `forceMount` animation hooks                                                         |
+| [NavigationMenu](src/NavigationMenu/README.md) | ARIA APG Disclosure Navigation Menu pattern — the desktop dropdown site nav: `<nav>` landmark + `<ul>` of entries, one panel open at a time (`""` means closed), hover-intent open with instant switching and a nav-wide close grace, axis/RTL-aware arrow travel that keeps every entry in the tab order (not a roving tabindex), cross-axis arrow to enter a panel, Escape-to-close with focus return, an optional `Viewport` panels portal into so the open one morphs into the next, an optional `Indicator` publishing the open trigger's measured geometry as custom properties, and a `Link` carrying `aria-current` that the composed mobile nav (`Drawer` + `Collapsible`) reuses |
+| [Popover](src/Popover/README.md)         | WAI-ARIA non-modal dialog — native HTML Popover API (`popover="auto"`) compound with trigger/anchor/content/close/title/description, controlled/uncontrolled state, light-dismiss sync, focus-in-on-open + Escape focus-return (no focus trap), CSS-anchor-positioning placement, and `asChild` composition |
 | [Portal](src/Portal/README.md)           | DOM-escape utility — renders children into `document.body` (or a consumer-supplied container) via `createPortal`; compose with any component that needs to break out of the current stacking context                                                                                    |
 | [Progress](src/Progress/README.md)       | WAI-ARIA progressbar pattern — display-only compound component reflecting a consumer-supplied `value`, with determinate/indeterminate states, configurable `max`, `getValueLabel` for `aria-valuetext`, `data-*` styling hooks on the fill `Indicator`, and `asChild` composition          |
 | [Radio](src/Radio/README.md)             | Standalone — a real, visually-hidden native `<input type="radio">` in a `<label>` box, so siblings sharing a `name` form a native radio group (the browser enforces single-selection) and it participates in forms; controlled/uncontrolled state, `Indicator` dot, `disabled` with `data-disabled` styling hook, and `asChild` on the indicator (use `RadioGroup` for managed roving-tabindex sets)                                                |
 | [RadioCard](src/RadioCard/README.md)     | WAI-ARIA Radio Group pattern in a card/tile layout — the entire card surface is the interactive element, with single-selection state, roving tabindex, arrow-key navigation, disabled-item skipping, `Indicator` slot, and `asChild` composition                                        |
 | [RadioGroup](src/RadioGroup/README.md)   | WAI-ARIA Radio Group pattern — native `<button role="radio">` items with single-selection state, roving tabindex, arrow-key navigation, disabled-item skipping, `Indicator` slot, and `asChild` composition                                                                             |
+| [SegmentedControl](src/SegmentedControl/README.md) | Single-select value picker (WAI-ARIA Radio Group semantics) styled as a linear pill strip — native `<button role="radio">` segments with controlled/uncontrolled state, roving tabindex, arrow-key navigation, horizontal/vertical orientation, per-item **and** whole-control `disabled`, `data-state` / `data-orientation` / `data-disabled` styling hooks, and `asChild` composition (use `ToggleGroup` for on/off command toggles) |
 | [Select](src/Select/README.md)           | Headless wrapper over native `<select>` / `<option>` / `<optgroup>` — controlled/uncontrolled state via `onValueChange`, `Select.Placeholder` with auto-`defaultValue` inference, `Select.Group` for optgroup labelling, `data-disabled` styling hook, `asChild` composition, and Field-aware (opts into `FieldContext` for auto-wired `id` / `aria-describedby` / `aria-invalid` / `disabled` / `required`) |
 | [SkipNav](src/SkipNav/README.md)         | WCAG 2.4.1 Bypass Blocks technique — a stateless "skip to main content" link and its `tabIndex=-1` focus target, connected by a shared content id, working with no JavaScript at runtime |
 | [Slider](src/Slider/README.md)           | WAI-ARIA Slider & Multi-Thumb Slider pattern — an array-valued range input with any number of independently focusable thumbs, keyboard and pointer dragging, `min`/`max`/`step`, `minStepsBetweenThumbs`, horizontal/vertical orientation, RTL and `inverted` direction, `onValueCommit`, hidden inputs for form submission, `disabled` with `data-disabled` styling hook, and `asChild` composition                                              |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primitiv-ui/react",
-  "version": "0.1.28",
+  "version": "0.1.29",
   "description": "Headless, accessible React components built on the WAI-ARIA authoring patterns. Zero styles ship with this package — bring your own (CSS, Tailwind, CSS-in-JS, design tokens).",
   "type": "module",
   "main": "./src/index.ts",
@@ -34,6 +34,8 @@
     }
   },
   "devDependencies": {
+    "@stryker-mutator/core": "9.6.1",
+    "@stryker-mutator/vitest-runner": "9.6.1",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.2",
@@ -57,6 +59,9 @@
     "qa": "pnpm qa:units",
     "qa:units": "vitest run --coverage",
     "qa:units:watch": "vitest --coverage",
+    "mutate": "stryker run",
+    "mutate:component": "node ../../scripts/mutate.mjs",
+    "mutate:local": "node ../../scripts/mutate-local.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   }
 }

package/src/AccessibleIcon/AccessibleIcon.tsx

@@ -5,17 +5,31 @@ import { AccessibleIconProps } from "./types";
 type DecorativeIconProps = { "aria-hidden": string; focusable: string };
 
 /**
- * Gives an icon-only control an accessible name.
+ * Gives an icon-only control an accessible name without adding a visible label.
  *
- * Wraps a single decorative icon: the icon element is cloned with
- * `aria-hidden="true"` (removing it from the accessibility tree) and
- * `focusable="false"` (so legacy browsers skip the `<svg>` in the tab
- * order), and a {@link VisuallyHidden} text label is rendered alongside
- * it. The label is announced by assistive technology while the icon
- * stays the only thing on screen.
+ * Wraps a single decorative icon element and performs two mutations via
+ * `cloneElement`:
  *
- * Place it inside an interactive element — the visually hidden label
- * becomes that element's accessible name:
+ * - Sets `aria-hidden="true"` on the icon, removing the purely decorative
+ *   graphic from the accessibility tree.
+ * - Sets `focusable="false"` on the icon, so legacy browsers (IE/Edge
+ *   classic) do not place the `<svg>` in the tab order.
+ *
+ * The {@link AccessibleIconProps.label | `label`} string is rendered
+ * alongside the icon inside a {@link VisuallyHidden} span — invisible on
+ * screen but announced by assistive technology. When `AccessibleIcon` is
+ * placed inside an interactive element (`<button>`, `<a>`, etc.), the
+ * hidden label becomes that element's accessible name. A screen reader
+ * will announce, for example, "Close dialog, button" rather than nothing.
+ *
+ * **Runtime validation.** `children` must be exactly **one** React
+ * element. Passing zero, multiple, or a plain string throws a React
+ * `Children.only` error. Wrap the glyph in a single `<svg>` or component
+ * if your icon library returns a fragment.
+ *
+ * **Renders no host element.** `AccessibleIcon` returns a React fragment
+ * (`<>…</>`), so it adds no DOM node of its own. The icon element and the
+ * {@link VisuallyHidden} span are the only nodes emitted.
  *
  * @example Icon-only button
  * ```tsx
@@ -25,6 +39,15 @@ type DecorativeIconProps = { "aria-hidden": string; focusable: string };
  *   </AccessibleIcon>
  * </button>
  * ```
+ *
+ * @example Icon-only link
+ * ```tsx
+ * <a href="/home">
+ *   <AccessibleIcon label="Go to home page">
+ *     <HomeIcon />
+ *   </AccessibleIcon>
+ * </a>
+ * ```
  */
 export function AccessibleIcon({
   label,

package/src/AccessibleIcon/__tests__/AccessibleIcon.test.tsx

@@ -44,4 +44,9 @@ describe("AccessibleIcon component", () => {
     const label = screen.getByText("Search");
     expect(label).toHaveStyle({ position: "absolute", overflow: "hidden" });
   });
+
+  it('sets displayName to "AccessibleIcon" for React DevTools and stack traces', () => {
+    // Assert — an empty displayName would render it as an anonymous component.
+    expect(AccessibleIcon.displayName).toBe("AccessibleIcon");
+  });
 });

package/src/AccessibleIcon/types.ts

@@ -3,10 +3,23 @@ import { ReactElement } from "react";
 /**
  * Props for {@link AccessibleIcon} — a single icon element plus the
  * visually-hidden `label` announced as its accessible name.
+ *
+ * `AccessibleIconProps` does not extend any HTML element props: the
+ * component renders a React fragment with no host element of its own.
  */
 export type AccessibleIconProps = {
-  /** Text announced by assistive technology as the icon's accessible name. */
+  /**
+   * Text announced by assistive technology as the accessible name of the
+   * surrounding interactive control. Keep it concise and action-oriented
+   * (e.g. `"Close dialog"`, `"Go to home page"`). This string is rendered
+   * inside a {@link VisuallyHidden} span — it is never visible on screen.
+   */
   label: string;
-  /** A single icon element (e.g. an `<svg>`). */
+  /**
+   * Exactly one React element representing the icon (typically an `<svg>`
+   * or a component that renders one). The element is cloned with
+   * `aria-hidden="true"` and `focusable="false"` applied. Passing zero,
+   * multiple, or a non-element child throws a React `Children.only` error.
+   */
   children: ReactElement;
 };

package/src/Accordion/Accordion.tsx

@@ -52,6 +52,8 @@ import { useAccordionTrigger } from "./hooks/useAccordionTrigger";
  * When omitted, it is inherited from the nearest {@link DirectionProvider},
  * falling back to `"ltr"` when there is no provider.
  *
+ * @extends HTMLDivElement
+ *
  * @example Uncontrolled — single open item
  * ```tsx
  * <Accordion.Root defaultValue="item-1">
@@ -100,6 +102,7 @@ export function AccordionRoot({
 }
 
 /** @internal */
+// Stryker disable next-line StringLiteral: overwritten by the compound alias — an equivalent mutant.
 AccordionRoot.displayName = "AccordionRoot";
 
 /**
@@ -112,6 +115,8 @@ AccordionRoot.displayName = "AccordionRoot";
  * stable auto-generated ID is used via `useId()` — useful for fully anonymous
  * items where the consumer doesn't need to drive state from outside.
  *
+ * @extends HTMLDivElement
+ *
  * @example
  * ```tsx
  * <Accordion.Item value="shipping">
@@ -148,6 +153,8 @@ AccordionItem.displayName = "AccordionItem";
  * The WAI-ARIA Accordion pattern requires each trigger to be wrapped in a
  * heading at the appropriate level for its position in the document outline.
  *
+ * @extends HTMLHeadingElement
+ *
  * @example
  * ```tsx
  * <Accordion.Header level={2}>
@@ -216,6 +223,8 @@ AccordionHeader.displayName = "AccordionHeader";
  * - `data-state="open" | "closed"` on the rendered element.
  * - `data-disabled="true" | "false"`.
  *
+ * @extends HTMLButtonElement
+ *
  * @example Basic
  * ```tsx
  * <Accordion.Trigger>Shipping policy</Accordion.Trigger>
@@ -293,6 +302,8 @@ AccordionTrigger.displayName = "AccordionTrigger";
  * **Styling hooks.**
  * - `data-state="open" | "closed"` on the rendered element.
  *
+ * @extends HTMLDivElement
+ *
  * @example Default (hidden attribute)
  * ```tsx
  * <Accordion.Content>Free shipping on orders over £50.</Accordion.Content>
@@ -313,10 +324,18 @@ export function AccordionContent({
   const { panelId, buttonId, itemId, isExpanded } = useAccordionItemContext();
   const { registerPanel, unregisterPanel } = useAccordionContext();
 
-  useEffect(() => {
-    registerPanel(itemId);
-    return () => unregisterPanel(itemId);
-  }, [itemId, registerPanel, unregisterPanel]);
+  useEffect(
+    () => {
+      registerPanel(itemId);
+      return () => unregisterPanel(itemId);
+    },
+    // `registerPanel`/`unregisterPanel` are stable, and `itemId` is effectively
+    // immutable: changing an item's value produces a phantom-key validation
+    // throw (the collection keeps unmounted keys), so it is never a supported
+    // runtime transition. Emptying the deps is therefore equivalent.
+    // Stryker disable next-line ArrayDeclaration: equivalent — stable/immutable dependencies.
+    [itemId, registerPanel, unregisterPanel],
+  );
 
   return (
     <div
@@ -352,6 +371,8 @@ AccordionContent.displayName = "AccordionContent";
  * - `data-state="open" | "closed"` on the rendered `<span>`.
  * - `aria-hidden="true"` on the rendered `<span>`.
  *
+ * @extends HTMLSpanElement
+ *
  * @example Inline SVG
  * ```tsx
  * <Accordion.Trigger>

package/src/Accordion/__tests__/Accordion.asChild.test.tsx

@@ -234,4 +234,50 @@ describe("Accordion asChild tests", () => {
     // Assert — no role="button" injected on enabled asChild elements
     expect(trigger).not.toHaveAttribute("role", "button");
   });
+
+  // A plain <div> (no native button semantics, no role) fires no synthetic
+  // click on Enter/Space, so these isolate the Trigger's own keydown handler —
+  // a native <button> or anchor would toggle via click even if the handler did
+  // nothing, masking mutations in it.
+  it("toggles on Enter for a non-native asChild element", async () => {
+    const user = userEvent.setup();
+    render(
+      <Accordion.Root>
+        <Accordion.Item value="a">
+          <Accordion.Header>
+            <Accordion.Trigger asChild>
+              <div tabIndex={0} data-testid="trigger">
+                Toggle
+              </div>
+            </Accordion.Trigger>
+          </Accordion.Header>
+          <Accordion.Content data-testid="content">Content</Accordion.Content>
+        </Accordion.Item>
+      </Accordion.Root>,
+    );
+    screen.getByTestId("trigger").focus();
+    await user.keyboard("{Enter}");
+    expect(screen.getByTestId("content")).toBeVisible();
+  });
+
+  it("toggles on Space for a non-native asChild element", async () => {
+    const user = userEvent.setup();
+    render(
+      <Accordion.Root>
+        <Accordion.Item value="a">
+          <Accordion.Header>
+            <Accordion.Trigger asChild>
+              <div tabIndex={0} data-testid="trigger">
+                Toggle
+              </div>
+            </Accordion.Trigger>
+          </Accordion.Header>
+          <Accordion.Content data-testid="content">Content</Accordion.Content>
+        </Accordion.Item>
+      </Accordion.Root>,
+    );
+    screen.getByTestId("trigger").focus();
+    await user.keyboard(" ");
+    expect(screen.getByTestId("content")).toBeVisible();
+  });
 });

package/src/Accordion/__tests__/Accordion.basic-rendering.test.tsx

@@ -3,6 +3,21 @@ import { render, screen } from "@testing-library/react";
 import { Accordion } from "../Accordion";
 import { type HeadingLevel } from "../../types";
 
+describe("Accordion displayNames", () => {
+  it("sets a displayName on the compound and each sub-component", () => {
+    // Assert — empty displayNames would render each as anonymous in DevTools.
+    // `Accordion`, `Accordion.Root`, and the underlying function are one object
+    // (Object.assign compound), so the compound's "Accordion" alias is the
+    // observable Root displayName; the sub-components are distinct objects.
+    expect(Accordion.displayName).toBe("Accordion");
+    expect(Accordion.Item.displayName).toBe("AccordionItem");
+    expect(Accordion.Header.displayName).toBe("AccordionHeader");
+    expect(Accordion.Trigger.displayName).toBe("AccordionTrigger");
+    expect(Accordion.Content.displayName).toBe("AccordionContent");
+    expect(Accordion.TriggerIcon.displayName).toBe("AccordionTriggerIcon");
+  });
+});
+
 describe("Accordion basic rendering tests", () => {
   it('should apply the attribute data-orientation="vertical" to the accordion by default', () => {
     // Arrange

package/src/Accordion/__tests__/Accordion.disabled-items.test.tsx

@@ -279,6 +279,48 @@ describe("Accordion disabled items tests", () => {
     expect(trigger2).toHaveFocus();
   });
 
+  it("re-registers a trigger's disabled flag when it changes after mount", async () => {
+    // Arrange — all enabled at mount; the middle trigger becomes disabled after.
+    const user = userEvent.setup();
+    function Fixture({ middleDisabled }: { middleDisabled: boolean }) {
+      return (
+        <Accordion.Root>
+          <Accordion.Item value="a">
+            <Accordion.Header>
+              <Accordion.Trigger>Trigger 1</Accordion.Trigger>
+            </Accordion.Header>
+            <Accordion.Content>Content</Accordion.Content>
+          </Accordion.Item>
+          <Accordion.Item value="b">
+            <Accordion.Header>
+              <Accordion.Trigger disabled={middleDisabled}>
+                Trigger 2
+              </Accordion.Trigger>
+            </Accordion.Header>
+            <Accordion.Content>Content</Accordion.Content>
+          </Accordion.Item>
+          <Accordion.Item value="c">
+            <Accordion.Header>
+              <Accordion.Trigger>Trigger 3</Accordion.Trigger>
+            </Accordion.Header>
+            <Accordion.Content>Content</Accordion.Content>
+          </Accordion.Item>
+        </Accordion.Root>
+      );
+    }
+    const { rerender } = render(<Fixture middleDisabled={false} />);
+
+    // Act — disable Trigger 2 after mount, then arrow down from Trigger 1.
+    rerender(<Fixture middleDisabled />);
+    screen.getByRole("button", { name: "Trigger 1" }).focus();
+    await user.keyboard("[ArrowDown]");
+
+    // Assert — the registrar effect re-ran, so Trigger 2 is skipped and focus
+    // lands on Trigger 3. A stale registration would keep Trigger 2 navigable,
+    // landing focus on it (aria-disabled stays focusable).
+    expect(screen.getByRole("button", { name: "Trigger 3" })).toHaveFocus();
+  });
+
   it("should not throw when all triggers are disabled and arrow key is pressed", async () => {
     // Arrange
     const user = userEvent.setup();

package/src/Accordion/__tests__/Accordion.error-handling.test.tsx

@@ -92,6 +92,39 @@ describe("Accordion error handling tests", () => {
     }).toThrow(/AccordionTrigger.*no corresponding AccordionContent/);
   });
 
+  it("re-validates after a panel unmounts: a trigger left without content throws", () => {
+    // Arrange — item A valid (trigger + content); item B mountable to force a
+    // re-validation later by changing the registered trigger set.
+    function Fixture({ showAContent }: { showAContent: boolean }) {
+      return (
+        <Accordion.Root>
+          <Accordion.Item value="a">
+            <Accordion.Header>
+              <Accordion.Trigger>A</Accordion.Trigger>
+            </Accordion.Header>
+            {showAContent && <Accordion.Content>A content</Accordion.Content>}
+          </Accordion.Item>
+          {!showAContent && (
+            <Accordion.Item value="b">
+              <Accordion.Header>
+                <Accordion.Trigger>B</Accordion.Trigger>
+              </Accordion.Header>
+              <Accordion.Content>B content</Accordion.Content>
+            </Accordion.Item>
+          )}
+        </Accordion.Root>
+      );
+    }
+    const { rerender } = render(<Fixture showAContent />);
+
+    // Act & Assert — removing A's content unregisters its panel; adding B
+    // re-runs validation, which now finds A's trigger has no content. If the
+    // panel cleanup were a no-op, A would stay registered and no throw occurs.
+    expect(() => rerender(<Fixture showAContent={false} />)).toThrow(
+      /AccordionTrigger.*no corresponding AccordionContent/,
+    );
+  });
+
   it("should not throw when AccordionItem with Trigger and Content is added dynamically", () => {
     // Arrange
     function DynamicAccordion({ showItem }: { showItem: boolean }) {

package/src/Accordion/hooks/useAccordionRoot.ts

@@ -20,21 +20,35 @@ export function useAccordionRoot(
   const accordionId = useId();
   // updateKeysOnCleanup is false so trigger unmounts don't fire setState
   // outside act() after a render-time validation throw.
+  // `updateKeysOnCleanup: false` avoids a setState-outside-act warning when a
+  // trigger unmounts after a render-time validation throw (see below). Flipping
+  // it to the default (true) changes only the timing of internal keys-state on
+  // unmount; it has no user-facing behavioural difference the contract exposes,
+  // so no test can distinguish it.
+  // Stryker disable next-line all
+  const triggerCollectionOptions = { updateKeysOnCleanup: false };
   const {
     register: registerTriggerBase,
     itemsRef: triggersRef,
     keys: registeredTriggerItemIds,
-  } = useCollection<string, TriggerMeta>({ updateKeysOnCleanup: false });
+  } = useCollection<string, TriggerMeta>(triggerCollectionOptions);
   const panelsRef = useRef<Set<string>>(new Set());
 
   const registerTrigger = useCallback(
     (
       itemId: string,
       element: HTMLButtonElement | null,
+      // The default is only reached by the cleanup call `registerTrigger(id,
+      // null)`, where `element` is null and `disabled` is discarded — so its
+      // value is never observable.
+      // Stryker disable next-line BooleanLiteral
       disabled = false,
     ) => {
       registerTriggerBase(itemId, element ? { element, disabled } : null);
     },
+    // `registerTriggerBase` is a stable useCollection callback, so emptying this
+    // array yields the identical memoised function.
+    // Stryker disable next-line ArrayDeclaration: equivalent — stable dependency.
     [registerTriggerBase],
   );
 
@@ -54,8 +68,14 @@ export function useAccordionRoot(
 
   const focusTrigger = useCallback(
     (itemId: string) => {
+      // `itemId` is always sourced from the navigable set (registered triggers),
+      // so a value that reaches here is guaranteed to have a live entry.
+      // Stryker disable next-line OptionalChaining: unreachable given that invariant.
       triggersRef.current.get(itemId)?.element.focus();
     },
+    // `triggersRef` is a stable RefObject, so emptying this array yields the
+    // identical memoised function.
+    // Stryker disable next-line ArrayDeclaration: equivalent — stable dependency.
     [triggersRef],
   );
 
@@ -67,6 +87,10 @@ export function useAccordionRoot(
     Set<string>
   >(
     controlledValue !== undefined ? new Set(controlledValue) : undefined,
+    // Forcing this condition true yields `new Set([undefined])` when no
+    // defaultValue is given; `undefined` can never equal an item id (ids are
+    // `value ?? useId()`), so it is observationally identical to the empty set.
+    // Stryker disable next-line ConditionalExpression
     defaultValue !== undefined ? new Set([defaultValue]) : new Set(),
   );
 
@@ -87,6 +111,9 @@ export function useAccordionRoot(
     (itemId: string) => {
       const next = computeNext(expandedItems, itemId);
       if (isControlled) {
+        // Controlled mode requires `onValueChange` (discriminated-union prop
+        // type), so the optional call can never no-op in valid usage.
+        // Stryker disable next-line OptionalChaining: unreachable — controlled requires onValueChange.
         onValueChange?.(Array.from(next));
       } else {
         setExpandedItems(next);
@@ -100,13 +127,23 @@ export function useAccordionRoot(
   // runs all effects in a commit before flushing batched state updates, the
   // panel effect always executes (and updates panelsRef) before the re-render
   // triggered by trigger registration reaches the validation effect.
-  const registerPanel = useCallback((itemId: string) => {
-    panelsRef.current.add(itemId);
-  }, []);
+  const registerPanel = useCallback(
+    (itemId: string) => {
+      panelsRef.current.add(itemId);
+    },
+    // Empty, stable deps — filling the array yields the identical callback.
+    // Stryker disable next-line ArrayDeclaration: equivalent — stable dependencies.
+    [],
+  );
 
-  const unregisterPanel = useCallback((itemId: string) => {
-    panelsRef.current.delete(itemId);
-  }, []);
+  const unregisterPanel = useCallback(
+    (itemId: string) => {
+      panelsRef.current.delete(itemId);
+    },
+    // Empty, stable deps — filling the array yields the identical callback.
+    // Stryker disable next-line ArrayDeclaration: equivalent — stable dependencies.
+    [],
+  );
 
   useEffect(() => {
     for (const triggerId of registeredTriggerItemIds) {

package/src/Accordion/hooks/useAccordionTrigger.ts

@@ -12,7 +12,9 @@ export function useAccordionTrigger({
   ref,
   onClick,
   disabled,
-  asChild = false,
+  // No default: the `AccordionTrigger` component always supplies a resolved
+  // `asChild` boolean, so a default here would be unreachable (dead) code.
+  asChild,
   ...rest
 }: Omit<AccordionTriggerProps, "children">) {
   const { buttonId, panelId, itemId, isExpanded } = useAccordionItemContext();
@@ -35,6 +37,12 @@ export function useAccordionTrigger({
   // useRovingTabindex expects.
   useEffect(() => {
     registerTrigger(itemId, triggerRef.current, disabled);
+    // Because the collection uses `updateKeysOnCleanup: false`, an unmount
+    // clears only this trigger's ref entry without a keys change, and focusing
+    // a removed trigger is a no-op whether the entry is absent or detached —
+    // so this cleanup has no observable effect the contract exposes. (On a dep
+    // change the effect body re-registers first, overwriting it.)
+    // Stryker disable next-line ArrowFunction: equivalent — no observable effect.
     return () => registerTrigger(itemId, null);
   }, [itemId, disabled, registerTrigger]);