@astryxdesign/core 0.1.3 → 0.1.4-canary.01e5b29

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/__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

@@ -217,6 +217,11 @@ export interface ComponentEntry {
   examples?: ExampleDoc[];
   /** When true, this sub-component is excluded from the overview page. */
   isHiddenFromOverview?: boolean;
+  /** Playground configuration for this specific component. Falls back to
+   *  the directory doc's `playground` when omitted — declare one here when
+   *  siblings must not share it (e.g. an overlay drawer whose toggle
+   *  sub-component should not inherit `overlay: true`). */
+  playground?: PlaygroundConfig;
 }
 
 /**
@@ -390,6 +395,13 @@ export interface PlaygroundConfig {
   /** Initial prop values for the playground preview.
    *  Keys are prop names. Values are primitives or ElementDescriptors. */
   defaults?: Record<string, unknown>;
+  /** The component opens as a full-viewport overlay (e.g. via
+   *  `dialog.showModal()`) and renders nothing inline while closed. The
+   *  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. */
+  overlay?: boolean;
   /** Required parent wrapper for sub-components that depend on a parent
    *  context provider (e.g. `Tab` calls `useTabListContext()` and throws
    *  standalone). The preview wraps the component in this parent before
@@ -847,6 +859,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'
@@ -877,6 +890,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();
+  });
+});

package/src/hooks/useFocusTrap.ts

@@ -5,7 +5,8 @@
 /**
  * @file useFocusTrap.ts
  * @input Uses React useCallback, useEffect, useRef
- * @output Exports useFocusTrap hook for trapping focus within a container
+ * @output Exports useFocusTrap hook for trapping focus within a container and
+ *   restoring focus to the previously-focused element on deactivation
  * @position Core hook; used by dialogs, modals, date pickers
  *
  * Based on WAI-ARIA dialog pattern:
@@ -178,6 +179,9 @@ export interface UseFocusTrapReturn<T extends HTMLElement = HTMLElement> {
  * - Listens to focus events on the document
  * - Redirects focus back into the container if it escapes
  * - Handles both Tab and Shift+Tab navigation
+ * - Restores focus to the element that was focused before activation when the
+ *   trap deactivates or unmounts, unless focus was already moved elsewhere
+ *   (so consumers that restore focus themselves are unaffected)
  *
  * @example
  * ```
@@ -217,6 +221,51 @@ export function useFocusTrap<T extends HTMLElement = HTMLElement>(
     }
   }, []);
 
+  /**
+   * Capture the element focused before the trap activated, and restore focus to
+   * it when the trap deactivates (or the component unmounts). Overlays are
+   * opened imperatively (e.g. `showPopover()`), so the browser's declarative
+   * popover focus restoration does not apply — without this, closing a Popover
+   * via Escape or light dismiss drops keyboard focus to `<body>`.
+   *
+   * The restore is guarded so it never steals focus a consumer moved on
+   * purpose: it only runs when focus would otherwise be lost — i.e. the active
+   * element is nothing, the document body/root, or still inside the (possibly
+   * now-unmounted) trap container. If focus already moved to some other element
+   * outside the trap (the user clicked elsewhere, or a consumer such as
+   * DropdownMenu already refocused its trigger), the restore is a no-op.
+   */
+  useEffect(() => {
+    if (!isActive) {
+      return;
+    }
+
+    const previouslyFocused = document.activeElement as HTMLElement | null;
+    // Snapshot the container now; by cleanup it may be detached or unmounted.
+    const container = containerRef.current;
+
+    return () => {
+      const active = document.activeElement;
+      const focusWasLost =
+        active == null ||
+        active === document.body ||
+        active === document.documentElement ||
+        (container != null && container.contains(active));
+
+      if (!focusWasLost) {
+        return;
+      }
+
+      if (
+        previouslyFocused != null &&
+        previouslyFocused.isConnected &&
+        typeof previouslyFocused.focus === 'function'
+      ) {
+        previouslyFocused.focus();
+      }
+    };
+  }, [isActive]);
+
   /**
    * Handle focus events - redirect focus back into container if it escapes.
    * Only redirects for keyboard navigation, not mouse clicks.