@astryxdesign/core 0.1.2-canary.bd8c3d3 → 0.1.2-canary.bfcbf64

package/src/Typeahead/Typeahead.test.tsx

@@ -122,6 +122,47 @@ describe('BaseTypeahead', () => {
     });
   });
 
+  it('announces the result count to a live region (comboboxes-6)', async () => {
+    render(
+      <BaseTypeahead
+        searchSource={fruitSource}
+        value={null}
+        onChange={() => {}}
+        debounceMs={0}
+      />,
+    );
+    const input = screen.getByRole('combobox');
+    fireEvent.change(input, {target: {value: 'Ap'}});
+
+    await waitFor(() => {
+      const region = document.querySelector(
+        '[data-astryx-live-region="polite"]',
+      );
+      expect(region?.textContent).toMatch(/\d+ results?/);
+    });
+  });
+
+  it('announces "no results found" when the search is empty (comboboxes-6)', async () => {
+    render(
+      <BaseTypeahead
+        searchSource={fruitSource}
+        value={null}
+        onChange={() => {}}
+        debounceMs={0}
+        emptySearchResultsText="No results found"
+      />,
+    );
+    const input = screen.getByRole('combobox');
+    fireEvent.change(input, {target: {value: 'zzzzz'}});
+
+    await waitFor(() => {
+      const region = document.querySelector(
+        '[data-astryx-live-region="polite"]',
+      );
+      expect(region).toHaveTextContent('No results found');
+    });
+  });
+
   it('disables input when isDisabled', () => {
     render(
       <BaseTypeahead
@@ -180,6 +221,90 @@ describe('BaseTypeahead', () => {
   });
 });
 
+describe('BaseTypeahead focus-out', () => {
+  it('closes the dropdown when focus leaves the input', async () => {
+    render(
+      <>
+        <BaseTypeahead
+          searchSource={fruitSource}
+          value={null}
+          onChange={() => {}}
+          debounceMs={0}
+        />
+        <button type="button">Outside</button>
+      </>,
+    );
+    const input = screen.getByRole('combobox');
+    fireEvent.change(input, {target: {value: 'App'}});
+
+    await waitFor(() => {
+      expect(input).toHaveAttribute('aria-expanded', 'true');
+    });
+
+    // Focus moves to an element outside the field/dropdown → menu closes.
+    const outside = screen.getByRole('button', {name: 'Outside'});
+    fireEvent.blur(input, {relatedTarget: outside});
+
+    await waitFor(() => {
+      expect(input).toHaveAttribute('aria-expanded', 'false');
+    });
+  });
+
+  it('keeps the dropdown open when focus moves into the anchor wrapper', async () => {
+    const anchor = document.createElement('div');
+    document.body.appendChild(anchor);
+    const anchorRef = {current: anchor};
+    render(
+      <BaseTypeahead
+        searchSource={fruitSource}
+        value={null}
+        onChange={() => {}}
+        anchorRef={anchorRef}
+        debounceMs={0}
+      />,
+    );
+    const input = screen.getByRole('combobox');
+    // The input lives inside the wrapper we hand to anchorRef.
+    anchor.appendChild(input.closest('div') ?? input);
+    fireEvent.change(input, {target: {value: 'App'}});
+
+    await waitFor(() => {
+      expect(input).toHaveAttribute('aria-expanded', 'true');
+    });
+
+    // A sibling control inside the field (e.g. a clear button) receives focus.
+    const sibling = document.createElement('button');
+    anchor.appendChild(sibling);
+    fireEvent.blur(input, {relatedTarget: sibling});
+
+    // Menu stays open because focus is still within the field.
+    expect(input).toHaveAttribute('aria-expanded', 'true');
+    document.body.removeChild(anchor);
+  });
+
+  it('does not close when a dropdown option receives focus', async () => {
+    render(
+      <BaseTypeahead
+        searchSource={fruitSource}
+        value={null}
+        onChange={() => {}}
+        debounceMs={0}
+      />,
+    );
+    const input = screen.getByRole('combobox');
+    fireEvent.change(input, {target: {value: 'App'}});
+
+    await waitFor(() => {
+      expect(input).toHaveAttribute('aria-expanded', 'true');
+    });
+
+    const option = screen.getByRole('option', {hidden: true});
+    fireEvent.blur(input, {relatedTarget: option});
+
+    expect(input).toHaveAttribute('aria-expanded', 'true');
+  });
+});
+
 describe('Typeahead', () => {
   it('renders with label', () => {
     render(

package/src/hooks/index.ts

@@ -14,11 +14,24 @@
 export {useFocusTrap} from './useFocusTrap';
 export type {UseFocusTrapOptions, UseFocusTrapReturn} from './useFocusTrap';
 
+export {useAnnounce} from './useAnnounce';
+export type {AnnounceFn, AnnouncePoliteness} from './useAnnounce';
+
 export {useGridFocus} from './useGridFocus';
 export type {UseGridFocusOptions, UseGridFocusReturn} from './useGridFocus';
 
 export {useListFocus} from './useListFocus';
-export type {UseListFocusOptions, UseListFocusReturn} from './useListFocus';
+export type {
+  UseListFocusOptions,
+  UseListFocusReturn,
+  ListFocusOrientation,
+} from './useListFocus';
+
+export {useTreeFocus} from './useTreeFocus';
+export type {UseTreeFocusOptions, UseTreeFocusReturn} from './useTreeFocus';
+
+export {useTypeahead} from './useTypeahead';
+export type {UseTypeaheadOptions, UseTypeaheadReturn} from './useTypeahead';
 
 export {useMediaQuery} from './useMediaQuery';
 
@@ -41,7 +54,7 @@ export type {
 export {useImageMode} from './useImageMode';
 export type {ImageSampleRegion, UseImageModeOptions} from './useImageMode';
 
-export {useClickableContainer} from './useClickableContainer';
+export {useClickableContainer, INTERACTIVE_SELECTORS} from './useClickableContainer';
 export type {
   UseClickableContainerOptions,
   ClickableContainerResult,
@@ -55,3 +68,9 @@ export type {
   InteractiveRole,
   UseInteractiveRoleOptions,
 } from './useInteractiveRole';
+
+export {useLongPress} from './useLongPress';
+export type {
+  UseLongPressOptions,
+  UseLongPressHandlers,
+} from './useLongPress';

package/src/hooks/useAnnounce.test.tsx

@@ -0,0 +1,101 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file useAnnounce.test.tsx
+ * @input Uses vitest, @testing-library/react, useAnnounce hook
+ * @output Unit tests for useAnnounce live-region announcements
+ * @position Testing; validates useAnnounce.ts
+ *
+ * SYNC: When useAnnounce.ts changes, update tests to match new behavior
+ */
+
+import {describe, it, expect, afterEach} from 'vitest';
+import {renderHook, waitFor} from '@testing-library/react';
+import {useAnnounce, __resetLiveRegionsForTest} from './useAnnounce';
+
+afterEach(() => {
+  __resetLiveRegionsForTest();
+});
+
+function politeRegion(): HTMLElement | null {
+  return document.querySelector('[data-astryx-live-region="polite"]');
+}
+function assertiveRegion(): HTMLElement | null {
+  return document.querySelector('[data-astryx-live-region="assertive"]');
+}
+
+describe('useAnnounce', () => {
+  it('mounts empty polite and assertive live regions on first announce', async () => {
+    const {result} = renderHook(() => useAnnounce());
+    // Regions do not exist until first use.
+    expect(politeRegion()).toBeNull();
+
+    result.current('Saved');
+
+    // Both regions exist after the first announce, before content settles.
+    expect(politeRegion()).not.toBeNull();
+    expect(assertiveRegion()).not.toBeNull();
+    expect(politeRegion()).toHaveAttribute('aria-live', 'polite');
+    expect(politeRegion()).toHaveAttribute('aria-atomic', 'true');
+    expect(politeRegion()).toHaveAttribute('role', 'status');
+    expect(assertiveRegion()).toHaveAttribute('aria-live', 'assertive');
+    expect(assertiveRegion()).toHaveAttribute('role', 'alert');
+  });
+
+  it('announces a polite message into the polite region', async () => {
+    const {result} = renderHook(() => useAnnounce());
+    result.current('12 results');
+    await waitFor(() => {
+      expect(politeRegion()).toHaveTextContent('12 results');
+    });
+    // Assertive region stays empty.
+    expect(assertiveRegion()).toHaveTextContent('');
+  });
+
+  it('routes assertive messages to the assertive region', async () => {
+    const {result} = renderHook(() => useAnnounce());
+    result.current('Upload failed', 'assertive');
+    await waitFor(() => {
+      expect(assertiveRegion()).toHaveTextContent('Upload failed');
+    });
+    expect(politeRegion()).toHaveTextContent('');
+  });
+
+  it('re-announces an identical message (clears then re-sets)', async () => {
+    const {result} = renderHook(() => useAnnounce());
+    result.current('No results found');
+    await waitFor(() => {
+      expect(politeRegion()).toHaveTextContent('No results found');
+    });
+    // Second identical announce should still land (region is cleared first).
+    result.current('No results found');
+    expect(politeRegion()).toHaveTextContent('');
+    await waitFor(() => {
+      expect(politeRegion()).toHaveTextContent('No results found');
+    });
+  });
+
+  it('ignores empty messages', () => {
+    const {result} = renderHook(() => useAnnounce());
+    result.current('');
+    // No regions created for an empty announce.
+    expect(politeRegion()).toBeNull();
+  });
+
+  it('reuses the same singleton regions across hook instances', async () => {
+    const {result: a} = renderHook(() => useAnnounce());
+    a.current('first');
+    const region = politeRegion();
+
+    const {result: b} = renderHook(() => useAnnounce());
+    b.current('second');
+    await waitFor(() => {
+      expect(politeRegion()).toHaveTextContent('second');
+    });
+    // Same DOM node, not a duplicate.
+    expect(politeRegion()).toBe(region);
+    expect(
+      document.querySelectorAll('[data-astryx-live-region="polite"]').length,
+    ).toBe(1);
+  });
+});

package/src/hooks/useAnnounce.ts

@@ -0,0 +1,168 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useAnnounce.ts
+ * @input Uses React useCallback; DOM APIs for a singleton live-region pair
+ * @output Exports useAnnounce hook and AnnouncePoliteness type
+ * @position Core a11y hook; provides imperative screen-reader announcements
+ *   via persistently-mounted polite/assertive live regions
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/hooks/index.ts
+ */
+
+import {useCallback} from 'react';
+
+/**
+ * Announcement urgency:
+ * - `'polite'` (default): announced when the screen reader is idle. Use for
+ *   status updates, result counts, "no results", non-urgent confirmations.
+ * - `'assertive'`: interrupts the current announcement. Reserve for errors and
+ *   time-sensitive alerts.
+ */
+export type AnnouncePoliteness = 'polite' | 'assertive';
+
+/**
+ * Imperative screen-reader announcement function.
+ */
+export type AnnounceFn = (
+  message: string,
+  politeness?: AnnouncePoliteness,
+) => void;
+
+const CONTAINER_ATTR = 'data-astryx-live-region';
+
+// Visually-hidden clip block (matches the VisuallyHidden primitive). Applied
+// inline so the regions work without any stylesheet being present.
+const VISUALLY_HIDDEN_CSS =
+  'position:absolute;width:1px;height:1px;margin:-1px;padding:0;' +
+  'overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0;' +
+  'inset-block-start:0;inset-inline-start:0;pointer-events:none;' +
+  'user-select:none;';
+
+interface LiveRegions {
+  polite: HTMLElement;
+  assertive: HTMLElement;
+}
+
+// Singleton: the live regions are created ONCE and stay mounted for the
+// lifetime of the document. This is the crux of reliable announcements — many
+// screen readers will not announce content injected into a live region that is
+// created together with its content ("born with content"). By mounting empty
+// regions up front and only mutating their text later, updates are announced.
+let regions: LiveRegions | null = null;
+
+function createRegion(politeness: AnnouncePoliteness): HTMLElement {
+  const el = document.createElement('div');
+  el.setAttribute(CONTAINER_ATTR, politeness);
+  el.setAttribute('aria-live', politeness);
+  el.setAttribute('aria-atomic', 'true');
+  el.setAttribute('role', politeness === 'assertive' ? 'alert' : 'status');
+  el.style.cssText = VISUALLY_HIDDEN_CSS;
+  document.body.appendChild(el);
+  return el;
+}
+
+function getRegions(): LiveRegions | null {
+  if (typeof document === 'undefined') {
+    return null;
+  }
+  if (regions) {
+    // Re-attach if a region was removed from the DOM (e.g. by a test cleanup).
+    if (!regions.polite.isConnected) {
+      document.body.appendChild(regions.polite);
+    }
+    if (!regions.assertive.isConnected) {
+      document.body.appendChild(regions.assertive);
+    }
+    return regions;
+  }
+  regions = {
+    polite: createRegion('polite'),
+    assertive: createRegion('assertive'),
+  };
+  return regions;
+}
+
+function announceMessage(
+  message: string,
+  politeness: AnnouncePoliteness,
+): void {
+  const r = getRegions();
+  if (!r) {
+    return;
+  }
+  const target = politeness === 'assertive' ? r.assertive : r.polite;
+  // Clearing first guarantees the mutation is observed even when the new
+  // message equals the current text — some AT deduplicate identical content.
+  target.textContent = '';
+  // A microtask/rAF-free re-set in the next frame is more reliable across AT
+  // than an immediate re-set, which can be coalesced with the clear.
+  requestAnimationFrame(() => {
+    target.textContent = message;
+  });
+}
+
+/**
+ * Clear any pending announcement from a region without announcing anything new.
+ * Used when the triggering context goes away (e.g. a search query is cleared),
+ * so stale status text does not linger in the accessibility tree.
+ */
+function clearRegion(politeness: AnnouncePoliteness): void {
+  if (!regions) {
+    return;
+  }
+  const target =
+    politeness === 'assertive' ? regions.assertive : regions.polite;
+  target.textContent = '';
+}
+
+/**
+ * Returns an imperative `announce(message, politeness?)` function that speaks a
+ * message through a persistently-mounted, visually-hidden live region.
+ *
+ * The polite and assertive regions are created once on first use and kept
+ * mounted, so announcements are reliable even for messages that appear
+ * immediately (unlike a live region rendered together with its content).
+ *
+ * @example
+ * ```
+ * function Search() {
+ *   const announce = useAnnounce();
+ *   const onResults = (n: number) => {
+ *     announce(n === 0 ? 'No results found' : `${n} results`);
+ *   };
+ *   // ...
+ * }
+ * ```
+ */
+export function useAnnounce(): AnnounceFn {
+  return useCallback(
+    (message: string, politeness: AnnouncePoliteness = 'polite') => {
+      if (!message) {
+        // An empty message clears any lingering status from the region rather
+        // than announcing nothing — useful when the triggering context ends.
+        clearRegion(politeness);
+        return;
+      }
+      announceMessage(message, politeness);
+    },
+    [],
+  );
+}
+
+/**
+ * Test-only helper: removes the singleton live regions and resets state so
+ * each test starts clean. Not part of the public runtime API.
+ *
+ * @internal
+ */
+export function __resetLiveRegionsForTest(): void {
+  if (regions) {
+    regions.polite.remove();
+    regions.assertive.remove();
+    regions = null;
+  }
+}

package/src/hooks/useClickableContainer.ts

@@ -5,18 +5,30 @@
 /**
  * @file useClickableContainer.ts
  * @input Container ref, interactive element ref, click/href handlers
- * @output onClick and onMouseUp handlers for the container
+ * @output onClick and onMouseUp handlers for the container; INTERACTIVE_SELECTORS list
  * @position Core hook for clickable containers that safely handle nested interactive elements
  *
  * Solves the "nested interactive elements" problem: when a card is clickable
  * but contains buttons/links, clicking those should NOT trigger the card's action.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/hooks/index.ts (export)
  */
 
 import {useCallback, useEffect, type RefObject, type MouseEvent} from 'react';
 
-// Interactive element selectors — clicks on these (or their descendants)
-// should NOT bubble to the container's click handler.
-const INTERACTIVE_SELECTORS = [
+/**
+ * Canonical list of interactive element selectors — native controls plus
+ * role-based interactive elements. Clicks on these (or their descendants)
+ * should NOT bubble to a clickable container's click handler.
+ *
+ * Exported so other focus/interaction utilities can share one comprehensive
+ * definition of "interactive target" rather than hand-rolling divergent lists.
+ * Note: this list is about "don't bubble clicks", not focus-eligibility —
+ * consumers that need focusable elements must additionally exclude
+ * unfocusable/disabled targets (e.g. `[tabindex="-1"]`, `:disabled`).
+ */
+export const INTERACTIVE_SELECTORS = [
   'button',
   'a',
   'input',

package/src/hooks/useFocusTrap.test.tsx

@@ -3,13 +3,13 @@
 /**
  * @file useFocusTrap.test.tsx
  * @input Uses vitest, @testing-library/react, useFocusTrap hook
- * @output Unit tests for useFocusTrap tabbable-element model
- * @position Testing; validates useFocusTrap.ts focusable detection
+ * @output Unit tests for useFocusTrap tabbable-element model + Escape/IME guard
+ * @position Testing; validates useFocusTrap.ts focusable detection + dismissal coordination
  *
  * SYNC: When useFocusTrap.ts changes, update tests to match new behavior
  */
 
-import {describe, it, expect} from 'vitest';
+import {describe, it, expect, vi} from 'vitest';
 import {render, screen, fireEvent} from '@testing-library/react';
 import {useFocusTrap} from './useFocusTrap';
 
@@ -32,6 +32,23 @@ function Trap({children}: {children: React.ReactNode}) {
   );
 }
 
+function EscapeTrap({
+  isActive,
+  onEscape,
+  label,
+}: {
+  isActive: boolean;
+  onEscape: () => void;
+  label: string;
+}) {
+  const {containerRef} = useFocusTrap<HTMLDivElement>({isActive, onEscape});
+  return (
+    <div ref={containerRef} data-testid={label}>
+      <button type="button">{label}-btn</button>
+    </div>
+  );
+}
+
 describe('useFocusTrap tabbable model (infra-8)', () => {
   it('treats a contenteditable as focusable (focusFirst lands on it)', () => {
     render(
@@ -66,3 +83,50 @@ describe('useFocusTrap tabbable model (infra-8)', () => {
     expect(screen.getByTestId('real-btn')).toHaveFocus();
   });
 });
+
+describe('useFocusTrap Escape coordination', () => {
+  it('calls onEscape for a single active trap', () => {
+    const onEscape = vi.fn();
+    render(<EscapeTrap isActive onEscape={onEscape} label="only" />);
+    fireEvent.keyDown(document, {key: 'Escape'});
+    expect(onEscape).toHaveBeenCalledTimes(1);
+  });
+
+  it('only the top-most trap responds to Escape when nested', () => {
+    const outer = vi.fn();
+    const inner = vi.fn();
+    render(
+      <>
+        <EscapeTrap isActive onEscape={outer} label="outer" />
+        <EscapeTrap isActive onEscape={inner} label="inner" />
+      </>,
+    );
+    // The most recently activated trap (inner) is on top.
+    fireEvent.keyDown(document, {key: 'Escape'});
+    expect(inner).toHaveBeenCalledTimes(1);
+    expect(outer).not.toHaveBeenCalled();
+  });
+
+  it('ignores Escape during IME composition', () => {
+    const onEscape = vi.fn();
+    render(<EscapeTrap isActive onEscape={onEscape} label="ime" />);
+    fireEvent.keyDown(document, {key: 'Escape', isComposing: true});
+    expect(onEscape).not.toHaveBeenCalled();
+    // keyCode 229 (composition) is also ignored
+    fireEvent.keyDown(document, {key: 'Escape', keyCode: 229});
+    expect(onEscape).not.toHaveBeenCalled();
+    // a normal Escape still works
+    fireEvent.keyDown(document, {key: 'Escape'});
+    expect(onEscape).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not respond after the trap is deactivated', () => {
+    const onEscape = vi.fn();
+    const {rerender} = render(
+      <EscapeTrap isActive onEscape={onEscape} label="toggle" />,
+    );
+    rerender(<EscapeTrap isActive={false} onEscape={onEscape} label="toggle" />);
+    fireEvent.keyDown(document, {key: 'Escape'});
+    expect(onEscape).not.toHaveBeenCalled();
+  });
+});

package/src/hooks/useFocusTrap.ts

@@ -19,6 +19,56 @@ import {useCallback, useEffect, useRef} from 'react';
 
 import {FOCUSABLE_SELECTOR} from './focusableSelector';
 
+/**
+ * Module-level stack of active focus-trap Escape handlers.
+ *
+ * Every active `useFocusTrap` used to attach its own document-level `keydown`
+ * listener with no coordination, so a single Escape press closed *every* open
+ * layer at once (e.g. a popover nested inside a Dialog closed both). Tracking
+ * traps in a shared stack lets only the most recently activated (top-most)
+ * trap respond to Escape.
+ */
+const escapeStack: (() => void)[] = [];
+
+function pushEscapeHandler(handler: () => void): void {
+  escapeStack.push(handler);
+}
+
+function removeEscapeHandler(handler: () => void): void {
+  const index = escapeStack.lastIndexOf(handler);
+  if (index !== -1) {
+    escapeStack.splice(index, 1);
+  }
+}
+
+function isTopEscapeHandler(handler: () => void): boolean {
+  return escapeStack[escapeStack.length - 1] === handler;
+}
+
+/**
+ * Whether any focus-trap Escape handler is currently active (i.e. a popover
+ * layer is open). Other overlay primitives that manage their own Escape (e.g.
+ * Dialog) can consult this to defer to a popover layered on top of them,
+ * giving topmost-only dismissal until a full layer stack exists.
+ */
+export function hasActiveFocusTrapEscape(): boolean {
+  return escapeStack.length > 0;
+}
+
+/**
+ * Whether an Escape keydown should be ignored because it is cancelling an
+ * in-progress IME composition. CJK/IME users press Escape to cancel
+ * composition; that must not close the surrounding overlay. `keyCode === 229`
+ * covers browsers that fire keydown before `isComposing` is set. Exported so
+ * other overlays (Dialog, Drawer, CommandPalette) share one definition.
+ */
+export function isImeKeyEvent(event: {
+  isComposing?: boolean;
+  keyCode?: number;
+}): boolean {
+  return event.isComposing === true || event.keyCode === 229;
+}
+
 /**
  * Whether an element is currently perceivable/focusable — excludes ones hidden
  * via `display:none`/`visibility:hidden` or inside an `inert`/`hidden` subtree,
@@ -222,6 +272,16 @@ export function useFocusTrap<T extends HTMLElement = HTMLElement>(
       return;
     }
 
+    // Register this trap on the shared Escape stack so only the top-most
+    // active trap responds to Escape. A stable identity per active period is
+    // enough — we push on activate and remove on cleanup.
+    const escapeHandler = () => {
+      onEscape?.();
+    };
+    if (onEscape) {
+      pushEscapeHandler(escapeHandler);
+    }
+
     const handleKeyDown = (event: KeyboardEvent) => {
       const container = containerRef.current;
       if (!container) {
@@ -229,7 +289,19 @@ export function useFocusTrap<T extends HTMLElement = HTMLElement>(
       }
 
       if (event.key === 'Escape' && onEscape) {
+        // Ignore Escape that is cancelling an IME composition, already handled
+        // by a nested handler, or not targeting the top-most trap.
+        if (
+          event.defaultPrevented ||
+          isImeKeyEvent(event) ||
+          !isTopEscapeHandler(escapeHandler)
+        ) {
+          return;
+        }
+        // Mark handled and stop propagation so an outer layer (e.g. a Dialog
+        // hosting this popover) does not also dismiss on the same press.
         event.preventDefault();
+        event.stopPropagation();
         onEscape();
         return;
       }
@@ -266,6 +338,9 @@ export function useFocusTrap<T extends HTMLElement = HTMLElement>(
 
     return () => {
       document.removeEventListener('keydown', handleKeyDown);
+      if (onEscape) {
+        removeEscapeHandler(escapeHandler);
+      }
     };
   }, [isActive, onEscape]);