@astryxdesign/core 0.1.4 → 0.1.5-canary.76e6697

package/src/Typeahead/BaseTypeahead.doc.mjs

@@ -8,6 +8,16 @@ export const docs = {
   displayName: 'Base Typeahead',
   isHiddenFromOverview: true,
   description: 'Unstyled combobox engine providing input, search, keyboard navigation, and dropdown. No wrapper div, no border styling, no token rendering. Used by Typeahead and Tokenizer for custom compositions.',
+  usage: {
+    description: 'Unstyled combobox engine providing input, search, keyboard navigation, and dropdown. No wrapper div, no border styling, no token rendering. Used by Typeahead and Tokenizer for custom compositions.',
+    bestPractices: [
+      { guidance: true, description: 'Use Typeahead or Tokenizer for standard fields; they wrap BaseTypeahead with the wrapper div, border styling, and token rendering it intentionally omits.' },
+      { guidance: true, description: 'Provide your own wrapper div with border and layout when composing directly, since BaseTypeahead renders no visual chrome of its own.' },
+      { guidance: true, description: 'Pass anchorRef pointing to your wrapper so the dropdown positions against your custom input chrome, not just the bare input element.' },
+      { guidance: false, description: 'Expect a wrapper div, border, or token rendering. BaseTypeahead is an engine only; all visual chrome is the caller\'s responsibility.' },
+      { guidance: false, description: 'Use BaseTypeahead when Typeahead or Tokenizer would suffice; the extra wrapper and styling work is only justified for truly custom compositions.' },
+    ],
+  },
   props: [
     {
       name: 'searchSource',
@@ -226,6 +236,15 @@ export const docsDense = {
   isHiddenFromOverview: true,
   displayName: 'Base Typeahead',
   description: 'Unstyled combobox engine; input+search+keyboard nav+dropdown. No wrapper/border/token. Used by Typeahead+Tokenizer.',
+  usage: {
+    bestPractices: [
+      { guidance: true, description: 'Use Typeahead or Tokenizer for standard fields; they add the wrapper, border, and token rendering BaseTypeahead omits.' },
+      { guidance: true, description: 'Provide your own wrapper div with border and layout when composing directly; BaseTypeahead renders no chrome.' },
+      { guidance: true, description: 'Pass anchorRef to your wrapper so the dropdown positions against your input chrome, not the bare input.' },
+      { guidance: false, description: 'Expect wrapper, border, or token rendering. Engine only; chrome is the caller\'s job.' },
+      { guidance: false, description: 'Use BaseTypeahead when Typeahead or Tokenizer suffice; extra work only pays off for custom compositions.' },
+    ],
+  },
   propDescriptions: {
     searchSource: 'Data source w/ search+bootstrap methods.',
     value: 'Currently selected item.',

package/src/Typeahead/BaseTypeahead.tsx

@@ -410,7 +410,10 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
   const performSearch = useCallback(
     async (searchQuery: string) => {
       searchSource.cancel?.();
-      const gen = searchGenRef.current;
+      // Claim a new generation so overlapping searches can't race: an
+      // in-flight response for an older query fails the gen check below
+      // instead of overwriting the newer results.
+      const gen = ++searchGenRef.current;
       setIsLoading(true);
       setHasSearched(true);
       try {
@@ -451,7 +454,7 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
 
   // Perform bootstrap
   const performBootstrap = useCallback(async () => {
-    const gen = searchGenRef.current;
+    const gen = ++searchGenRef.current;
     setIsLoading(true);
     try {
       const bootstrapResults = await searchSource.bootstrap();

package/src/Typeahead/Typeahead.doc.mjs

@@ -168,7 +168,7 @@ export const docs = {
   components: [{name: 'BaseTypeahead'}, {name: 'TypeaheadItem'}],
   theming: {
     targets: [
-      {className: 'astryx-typeahead', visualProps: ['status']},
+      {className: 'astryx-typeahead', visualProps: ['status', 'size']},
       {className: 'astryx-typeahead-dropdown'},
       {className: 'astryx-typeahead-item'},
     ],

package/src/Typeahead/Typeahead.test.tsx

@@ -18,7 +18,7 @@ import {
   afterAll,
   beforeEach,
 } from 'vitest';
-import {render, screen, fireEvent, waitFor} from '@testing-library/react';
+import {render, screen, fireEvent, waitFor, act} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {Typeahead} from './Typeahead';
 import {BaseTypeahead} from './BaseTypeahead';
@@ -314,6 +314,50 @@ describe('BaseTypeahead focus-out', () => {
 });
 
 describe('Typeahead', () => {
+  describe('out-of-order async results', () => {
+    it('discards a stale response that resolves after a newer query', async () => {
+      const resolvers = new Map<string, (items: SearchableItem[]) => void>();
+      const rawSource: SearchSource = {
+        search: async (query: string) =>
+          new Promise<SearchableItem[]>(resolve => {
+            resolvers.set(query, resolve);
+          }),
+        bootstrap: () => [],
+      };
+
+      render(
+        <Typeahead
+          label="Fruit"
+          searchSource={rawSource}
+          value={null}
+          onChange={() => {}}
+          debounceMs={0}
+        />,
+      );
+
+      const input = screen.getByRole('combobox');
+      fireEvent.change(input, {target: {value: 'a'}});
+      fireEvent.change(input, {target: {value: 'ap'}});
+
+      // The newer query resolves first…
+      await act(async () => {
+        resolvers.get('ap')!([{id: 'apple', label: 'Apple'}]);
+      });
+      expect(screen.getByText('Apple')).toBeInTheDocument();
+
+      // …then the abandoned query's slow response arrives and must be
+      // discarded rather than overwriting the current results.
+      await act(async () => {
+        resolvers.get('a')!([
+          {id: 'avocado', label: 'Avocado'},
+          {id: 'apricot', label: 'Apricot'},
+        ]);
+      });
+      expect(screen.getByText('Apple')).toBeInTheDocument();
+      expect(screen.queryByText('Avocado')).not.toBeInTheDocument();
+    });
+  });
+
   it('renders with label', () => {
     render(
       <Typeahead

package/src/VisuallyHidden/VisuallyHidden.tsx

@@ -79,12 +79,9 @@ const styles = stylex.create({
  *
  * @example
  * ```
- * // Accessible name for an icon-only button
  * <IconButton icon="trash" label="">
  *   <VisuallyHidden>Delete incident</VisuallyHidden>
  * </IconButton>
- *
- * // Live region for announcements
  * <VisuallyHidden as="div" aria-live="polite">
  *   {`Moved ${task} to ${column}`}
  * </VisuallyHidden>

package/src/__tests__/TestIcon.tsx

@@ -0,0 +1,26 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file TestIcon.tsx
+ * @input Standard SVG props
+ * @output A minimal SVG React component for tests
+ * @position Test fixture; a stand-in external SVG icon for Icon component-mode tests
+ *
+ * A trivial SVG component used by tests that need to pass a custom SVG icon to
+ * `Icon` (component mode) or component `*Icon` props. It forwards all standard
+ * SVG props and its ref so tests exercising prop/ref forwarding behave the same
+ * as a real third-party icon component.
+ */
+
+import React, {type SVGProps} from 'react';
+
+export function TestIcon({
+  ref,
+  ...props
+}: SVGProps<SVGSVGElement> & {ref?: React.Ref<SVGSVGElement>}) {
+  return (
+    <svg ref={ref} viewBox="0 0 24 24" {...props}>
+      <path d="M4 4h16v16H4z" />
+    </svg>
+  );
+}

package/src/__tests__/fastRoleQueries.ts

@@ -0,0 +1,66 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file fastRoleQueries.ts
+ * @input Uses @testing-library/react screen, dom-accessibility-api
+ * @output getButton/queryButton — role+name lookups that stay O(match) in jsdom
+ * @position Shared test helper; imported by component tests that render large
+ *   always-mounted button collections (Calendar month grids)
+ *
+ * RTL's getByRole('button', {name}) computes the accessible name of EVERY
+ * role candidate before filtering, and each computation consults jsdom's slow
+ * getComputedStyle (~5ms per node). The date components keep a month grid of
+ * ~35–85 role=button nodes mounted — visible in Calendar's case, inside the
+ * closed popover for the *Input components — so a single trigger lookup cost
+ * ~450ms and dominated those suites' runtime (DateRangeInput: 34s for 34
+ * tests before this helper existed).
+ *
+ * These helpers keep RTL's exact name algorithm (dom-accessibility-api is the
+ * library RTL uses internally) but:
+ *   - collect candidates with {hidden: true}, skipping the per-node
+ *     getComputedStyle visibility checks, and
+ *   - inject a constant "visible" style stub into the name computation —
+ *     names only consult display/visibility, and under {hidden: true}
+ *     semantics visibility must not exclude candidates anyway.
+ *
+ * Trade-off vs getByRole: first match wins — no tree-wide uniqueness check.
+ *
+ * SYNC: When modified, update this header.
+ */
+
+import {screen} from '@testing-library/react';
+import {computeAccessibleName} from 'dom-accessibility-api';
+
+// The name algorithm only reads getPropertyValue (for display/visibility/
+// content), so a Pick is all we need to type honestly — no object-literal
+// cast. The widening to CSSStyleDeclaration happens at the call site, where
+// getComputedStyle's signature demands the full type.
+const visibleStyleStub: Pick<CSSStyleDeclaration, 'getPropertyValue'> = {
+  getPropertyValue: prop =>
+    prop === 'display' ? 'block' : prop === 'visibility' ? 'visible' : '',
+};
+
+function matchesName(el: Element, name: string | RegExp): boolean {
+  const accessibleName = computeAccessibleName(el, {
+    getComputedStyle: () => visibleStyleStub as CSSStyleDeclaration,
+  });
+  return typeof name === 'string'
+    ? accessibleName === name
+    : name.test(accessibleName);
+}
+
+export function queryButton(name: string | RegExp): HTMLElement | null {
+  return (
+    screen
+      .queryAllByRole('button', {hidden: true})
+      .find(el => matchesName(el, name)) ?? null
+  );
+}
+
+export function getButton(name: string | RegExp): HTMLElement {
+  const el = queryButton(name);
+  if (!el) {
+    throw new Error(`Unable to find a role=button named ${String(name)}`);
+  }
+  return el;
+}

package/src/docPropReferences.test.ts

@@ -0,0 +1,178 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/* eslint-disable @typescript-eslint/no-require-imports */
+/**
+ * @file Guards doc prose against docs/source prop mismatches (#3360).
+ *
+ * Scans every {Name}.doc.mjs for prose phrases like "the foo prop on Bar"
+ * and verifies the referenced prop is documented on the referenced
+ * component. Doc prose is LLM training signal: a reference to a prop that
+ * doesn't exist steers codegen toward hallucinated APIs (#3360 shipped a
+ * bullet pointing at a nonexistent CodeBlock syntaxTheme prop).
+ *
+ * A reference to a missing prop is allowed only when the same string
+ * explicitly negates it ("no such prop exists" / "does not exist"), the
+ * corrective-bullet pattern used to counter known hallucinations.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {readdirSync} from 'node:fs';
+import {join, relative} from 'node:path';
+
+const SRC_DIR = __dirname;
+
+type DocModule = {
+  docs?: {
+    name?: string;
+    props?: {name: string}[];
+    components?: {name?: string; props?: {name: string}[]}[];
+  };
+};
+
+/**
+ * Props intentionally omitted from doc props[]: PropDoc in docs-types.ts
+ * says to skip internal/styling props, so prose may reference them even
+ * though no doc lists them.
+ */
+const UNIVERSAL_PROPS = new Set([
+  'xstyle',
+  'className',
+  'style',
+  'ref',
+  'data-testid',
+]);
+
+/**
+ * Matches prose like "the foo prop on Bar", "foo prop of Bar", and
+ * conjunction targets: "foo prop on Bar or Baz". Group 1 is the prop
+ * (camelCase, lowercase first letter), group 2 the component name list.
+ */
+const PROP_REF_PATTERN =
+  /\b([a-z][A-Za-z0-9]*) prop (?:on|of) (?:the )?([A-Z][A-Za-z0-9]*(?:(?:,(?: and| or)?| and| or) [A-Z][A-Za-z0-9]*)*)/g;
+
+/** A same-string negation marks the reference as a deliberate counter-signal. */
+const NEGATION_PATTERN = /no such prop|does not exist|doesn't exist/i;
+
+function findDocFiles(dir: string): string[] {
+  const files: string[] = [];
+  for (const entry of readdirSync(dir, {withFileTypes: true})) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...findDocFiles(full));
+    } else if (entry.name.endsWith('.doc.mjs')) {
+      files.push(full);
+    }
+  }
+  return files;
+}
+
+/** Collect every string value reachable from a doc module export. */
+function collectStrings(value: unknown, out: string[]): void {
+  if (typeof value === 'string') {
+    out.push(value);
+  } else if (Array.isArray(value)) {
+    for (const item of value) {
+      collectStrings(item, out);
+    }
+  } else if (value && typeof value === 'object') {
+    for (const item of Object.values(value)) {
+      collectStrings(item, out);
+    }
+  }
+}
+
+const docFiles = findDocFiles(SRC_DIR);
+
+// Component name → documented prop names, from every doc file's props[]
+// (single and sub-component docs) and inline components[] entries.
+const documentedProps = new Map<string, Set<string>>();
+for (const file of docFiles) {
+  const mod = require(file) as DocModule;
+  const docs = mod.docs;
+  if (!docs) {
+    continue;
+  }
+  const entries = [
+    {name: docs.name, props: docs.props},
+    ...(docs.components || []),
+  ];
+  for (const {name, props} of entries) {
+    if (!name || !Array.isArray(props)) {
+      continue;
+    }
+    const set = documentedProps.get(name) || new Set<string>();
+    for (const prop of props) {
+      set.add(prop.name);
+    }
+    documentedProps.set(name, set);
+  }
+}
+
+interface Violation {
+  file: string;
+  component: string;
+  prop: string;
+  excerpt: string;
+}
+
+function findViolations(): Violation[] {
+  const violations: Violation[] = [];
+  for (const file of docFiles) {
+    const strings: string[] = [];
+    collectStrings(require(file), strings);
+    for (const text of strings) {
+      let match;
+      while ((match = PROP_REF_PATTERN.exec(text)) !== null) {
+        const [, prop, componentList] = match;
+        if (UNIVERSAL_PROPS.has(prop) || NEGATION_PATTERN.test(text)) {
+          continue;
+        }
+        for (const component of componentList.split(
+          /,(?: and| or)?| and | or /,
+        )) {
+          const name = component.trim();
+          if (!name) {
+            continue;
+          }
+          const known = documentedProps.get(name);
+          if (known && !known.has(prop)) {
+            violations.push({
+              file: relative(SRC_DIR, file),
+              component: name,
+              prop,
+              excerpt: text.slice(
+                Math.max(0, match.index - 40),
+                match.index + match[0].length + 20,
+              ),
+            });
+          }
+        }
+      }
+    }
+  }
+  return violations;
+}
+
+describe('doc prose prop references', () => {
+  it('sanity: discovers doc files and documented components', () => {
+    expect(docFiles.length).toBeGreaterThan(0);
+    expect(documentedProps.size).toBeGreaterThan(0);
+  });
+
+  it('every "X prop on Y" reference names a documented prop of Y', () => {
+    const violations = findViolations();
+    expect(
+      violations,
+      violations
+        .map(
+          v =>
+            `${v.file} references prop "${v.prop}" on ${v.component}, ` +
+            `which does not document it (…${v.excerpt}…). Either the prop ` +
+            `doesn't exist (fix the prose; negate with "no such prop ` +
+            `exists" if countering a known hallucination) or it exists in ` +
+            `source but is missing from the component's doc props[] (add it).`,
+        )
+        .join('\n'),
+    ).toEqual([]);
+  });
+});

package/src/docs-types.ts

@@ -400,7 +400,13 @@ export interface PlaygroundConfig {
    *  interactive preview shows an open-trigger placeholder instead of an
    *  empty stage while `isOpen` is false, and lets the real overlay render
    *  when opened. Include `isOpen: false` in `defaults` so the preview can
-   *  bridge `onOpenChange` back into playground state. */
+   *  bridge `onOpenChange` back into playground state.
+   *
+   *  Only for components with no inline containment (MobileNav, Lightbox).
+   *  Components with an `isInline` docs-preview prop (Dialog, AlertDialog,
+   *  CommandPalette) intentionally keep contained inline previews instead:
+   *  the component is visible on load and knobs stay usable, whereas a real
+   *  top-layer modal makes the rest of the page inert (#3657). */
   overlay?: boolean;
   /** Required parent wrapper for sub-components that depend on a parent
    *  context provider (e.g. `Tab` calls `useTabListContext()` and throws
@@ -859,6 +865,7 @@ export type TemplateCategory =
   | 'Tools - File Explorer'
   | 'Tools - Page Editor'
   | 'Tools - IDE'
+  | 'Tools - Incident Console'
   | 'Tools - Kanban Board'
   | 'Tools - Notebook/Report Page'
   | 'Tools - Diff Compare Viewer'
@@ -889,6 +896,7 @@ export type TemplateCategory =
   | 'Shell - Top Nav'
   | 'Shell - Top Nav + Left Sidebar'
   | 'Shell - Breadcrumb Driven Layout'
+  | 'Shell - Messaging'
   | 'Shell - Blank';
 
 interface BaseTemplateDoc {

package/src/hooks/focusableSelector.ts

@@ -22,4 +22,4 @@
  * re-declaring the string so behavior stays consistent across hooks.
  */
 export const FOCUSABLE_SELECTOR =
-  'button:not([disabled]), [href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"]):not([disabled]), [contenteditable]:not([contenteditable="false"]), audio[controls], video[controls], iframe, details > summary:first-child';
+  'button:not([disabled]), a[href], area[href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"]):not([disabled]), [contenteditable]:not([contenteditable="false"]), audio[controls], video[controls], iframe, details > summary:first-child';

package/src/hooks/index.ts

@@ -30,6 +30,9 @@ export type {
 export {useTreeFocus} from './useTreeFocus';
 export type {UseTreeFocusOptions, UseTreeFocusReturn} from './useTreeFocus';
 
+export {useHotkeys} from './useHotkeys';
+export type {Hotkey} from './useHotkeys';
+
 export {useTypeahead} from './useTypeahead';
 
 export {useKeyboardHint} from './useKeyboardHint';

package/src/hooks/useFocusTrap.doc.mjs

@@ -39,10 +39,11 @@ export const docs = {
   ],
   usage: {
     description:
-      'Traps focus within a container element following the WAI-ARIA dialog focus trap pattern. Listens to focus events on the document and redirects focus back into the container if it escapes via keyboard navigation. Handles both Tab and Shift+Tab wrapping. Mouse clicks outside the container are not intercepted; use a light-dismiss handler for that.',
+      'Traps focus within a container element following the WAI-ARIA dialog focus trap pattern. Listens to focus events on the document and redirects focus back into the container if it escapes via keyboard navigation. Handles both Tab and Shift+Tab wrapping. When the trap deactivates or unmounts, focus is restored to the element that was focused before activation, unless focus was already moved elsewhere. Mouse clicks outside the container are not intercepted; use a light-dismiss handler for that.',
     bestPractices: [
       { guidance: true, description: 'Call focusFirst() when opening a dialog/modal to move focus into the trapped region.' },
       { guidance: true, description: 'Provide an onEscape callback to close the dialog when Escape is pressed.' },
+      { guidance: true, description: 'Rely on the built-in focus restoration on close; only add your own onHide focus handling when you need to send focus somewhere other than the previously-focused element.' },
       { guidance: false, description: 'Use on non-modal content like tooltips or dropdowns; those need light-dismiss, not focus trapping.' },
     ],
   },
@@ -67,10 +68,11 @@ export const docsDense = {
   },
   usage: {
     description:
-      'Traps focus within container element following WAI-ARIA dialog focus trap pattern. Listens to document focus events + redirects focus back into container if it escapes via keyboard navigation. Handles both Tab + Shift+Tab wrapping. Mouse clicks outside container not intercepted; use light-dismiss handler for that.',
+      'Traps focus within container element following WAI-ARIA dialog focus trap pattern. Listens to document focus events + redirects focus back into container if it escapes via keyboard navigation. Handles both Tab + Shift+Tab wrapping. On deactivate/unmount, restores focus to the element focused before activation unless focus already moved elsewhere. Mouse clicks outside container not intercepted; use light-dismiss handler for that.',
     bestPractices: [
       { guidance: true, description: 'Call focusFirst() when opening dialog/modal to move focus into trapped region.' },
       { guidance: true, description: 'Provide onEscape callback to close dialog when Escape pressed.' },
+      { guidance: true, description: 'Rely on built-in focus restoration on close; add own onHide focus handling only to send focus somewhere other than previously-focused element.' },
       { guidance: false, description: 'Use on non-modal content like tooltips / dropdowns; those need light-dismiss, not focus trapping.' },
     ],
   },

package/src/hooks/useFocusTrap.test.tsx

@@ -11,6 +11,7 @@
 
 import {describe, it, expect, vi} from 'vitest';
 import {render, screen, fireEvent} from '@testing-library/react';
+import {FOCUSABLE_SELECTOR} from './focusableSelector';
 import {useFocusTrap} from './useFocusTrap';
 
 function Trap({children}: {children: React.ReactNode}) {
@@ -49,6 +50,41 @@ function EscapeTrap({
   );
 }
 
+function RestoreTrap({isActive}: {isActive: boolean}) {
+  const {containerRef} = useFocusTrap<HTMLDivElement>({isActive});
+  return (
+    <div ref={containerRef} data-testid="restore-trap">
+      <button type="button" data-testid="inside">
+        Inside trap
+      </button>
+    </div>
+  );
+}
+
+function RestoreFixture({
+  isActive,
+  showPrev = true,
+  showTrap = true,
+}: {
+  isActive: boolean;
+  showPrev?: boolean;
+  showTrap?: boolean;
+}) {
+  return (
+    <div>
+      {showPrev && (
+        <button type="button" data-testid="prev">
+          Previously focused
+        </button>
+      )}
+      <button type="button" data-testid="other">
+        Other outside
+      </button>
+      {showTrap && <RestoreTrap isActive={isActive} />}
+    </div>
+  );
+}
+
 describe('useFocusTrap tabbable model (infra-8)', () => {
   it('treats a contenteditable as focusable (focusFirst lands on it)', () => {
     render(
@@ -84,6 +120,48 @@ describe('useFocusTrap tabbable model (infra-8)', () => {
   });
 });
 
+describe('FOCUSABLE_SELECTOR href matching', () => {
+  // Only real links (<a href>/<area href>) are focusable via href. A bare
+  // [href] term also matched non-focusable elements carrying href (e.g. a
+  // <link> in the head, or a custom element), which useFocusTrap would then
+  // treat as tab stops when computing trap boundaries.
+  it('matches real links but not other elements carrying href', () => {
+    const container = document.createElement('div');
+    container.innerHTML =
+      '<a href="#a" data-testid="anchor">Anchor</a>' +
+      '<map name="m">' +
+      '<area href="#area" shape="rect" coords="0,0,1,1" data-testid="area" />' +
+      '</map>' +
+      '<span href="#span" data-testid="span">Span</span>' +
+      '<link href="#link" data-testid="link" />';
+
+    const matches = Array.from(
+      container.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR),
+    );
+    const byTestId = (id: string) =>
+      container.querySelector(`[data-testid="${id}"]`);
+
+    // Real links are focusable via href.
+    expect(matches).toContain(byTestId('anchor'));
+    expect(matches).toContain(byTestId('area'));
+    // Non-link elements carrying href are not focusable and must be excluded.
+    expect(matches).not.toContain(byTestId('span'));
+    expect(matches).not.toContain(byTestId('link'));
+  });
+
+  it('treats an <a href> inside a trap as focusable (focusFirst lands on it)', () => {
+    render(
+      <Trap>
+        <a href="#link" data-testid="anchor">
+          Link
+        </a>
+      </Trap>,
+    );
+    fireEvent.click(screen.getByTestId('focus-first'));
+    expect(screen.getByTestId('anchor')).toHaveFocus();
+  });
+});
+
 describe('useFocusTrap Escape coordination', () => {
   it('calls onEscape for a single active trap', () => {
     const onEscape = vi.fn();
@@ -125,8 +203,78 @@ describe('useFocusTrap Escape coordination', () => {
     const {rerender} = render(
       <EscapeTrap isActive onEscape={onEscape} label="toggle" />,
     );
-    rerender(<EscapeTrap isActive={false} onEscape={onEscape} label="toggle" />);
+    rerender(
+      <EscapeTrap isActive={false} onEscape={onEscape} label="toggle" />,
+    );
     fireEvent.keyDown(document, {key: 'Escape'});
     expect(onEscape).not.toHaveBeenCalled();
   });
 });
+
+describe('useFocusTrap focus restoration', () => {
+  it('restores focus to the previously-focused element when deactivated', () => {
+    const {rerender} = render(<RestoreFixture isActive={false} />);
+    const prev = screen.getByTestId('prev');
+    prev.focus();
+    expect(prev).toHaveFocus();
+
+    // Activate the trap (captures `prev` as the restore target) and move focus
+    // inside it, as auto-focus or a keyboard user would.
+    rerender(<RestoreFixture isActive={true} />);
+    screen.getByTestId('inside').focus();
+    expect(screen.getByTestId('inside')).toHaveFocus();
+
+    // Deactivating returns focus to where it was before the trap opened.
+    rerender(<RestoreFixture isActive={false} />);
+    expect(prev).toHaveFocus();
+  });
+
+  it('does not steal focus when it was moved elsewhere outside the trap', () => {
+    const {rerender} = render(<RestoreFixture isActive={false} />);
+    const prev = screen.getByTestId('prev');
+    prev.focus();
+
+    rerender(<RestoreFixture isActive={true} />);
+    // The user (or a consumer that self-restores) moves focus to a different
+    // outside control while the trap is open.
+    const other = screen.getByTestId('other');
+    other.focus();
+
+    rerender(<RestoreFixture isActive={false} />);
+    // Focus is left where the user put it — not yanked back to `prev`.
+    expect(other).toHaveFocus();
+    expect(prev).not.toHaveFocus();
+  });
+
+  it('does not crash or restore when the captured element was removed', () => {
+    const {rerender} = render(<RestoreFixture isActive={false} />);
+    const prev = screen.getByTestId('prev');
+    prev.focus();
+
+    rerender(<RestoreFixture isActive={true} />);
+    screen.getByTestId('inside').focus();
+
+    // Remove the captured element from the DOM before the trap deactivates.
+    rerender(<RestoreFixture isActive={true} showPrev={false} />);
+    expect(() =>
+      rerender(<RestoreFixture isActive={false} showPrev={false} />),
+    ).not.toThrow();
+  });
+
+  it('restores focus when the trap unmounts while active', () => {
+    const {rerender} = render(
+      <RestoreFixture isActive={true} showTrap={false} />,
+    );
+    const prev = screen.getByTestId('prev');
+    prev.focus();
+
+    // Mounting the trap active captures `prev`; then focus moves inside it.
+    rerender(<RestoreFixture isActive={true} showTrap={true} />);
+    screen.getByTestId('inside').focus();
+    expect(screen.getByTestId('inside')).toHaveFocus();
+
+    // Unmounting the trap (cleanup path, not an isActive flip) still restores.
+    rerender(<RestoreFixture isActive={true} showTrap={false} />);
+    expect(prev).toHaveFocus();
+  });
+});