@astryxdesign/core 0.7.3 → 0.7.4-canary.1a552f2

package/src/hooks/__tests__/MenuPressShadowRoot.a11y.chromium.spec.ts

@@ -0,0 +1,50 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file MenuPressShadowRoot.a11y.chromium.spec.ts
+ * @input The `a11y/Menu press in a shadow root` story in a built Storybook and
+ *   real mouse input.
+ * @output Real-engine proof that a menu rendered inside a shadow root acts on
+ *   the row under a released pointer (module:DropdownMenu/useMenuPress FR1).
+ * @position Run with `pnpm test:a11y-contract`. Only a real engine resolves a
+ *   point inside a shadow root to the shadow host at the document level.
+ */
+
+import {expect, test} from '@playwright/test';
+import {
+  DEFAULT_STORYBOOK_DIR,
+  serveStorybook,
+  type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+
+let storybook: StaticServer;
+
+test.beforeAll(async () => {
+  storybook = await serveStorybook(
+    process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+  );
+});
+
+test.afterAll(async () => {
+  await storybook?.close();
+});
+
+const STORY = 'a11y-menu-press-in-a-shadow-root--selector-in-shadow-root';
+
+test('a mouse click on an option inside a shadow root selects it', async ({
+  page,
+}) => {
+  await page.goto(`${storybook.origin}/iframe.html?id=${STORY}&viewMode=story`);
+  // Playwright's role locators pierce open shadow roots.
+  await page.getByRole('combobox', {name: 'Fruit'}).click();
+  const option = page.getByRole('option', {name: 'Banana'});
+  await expect(option).toBeVisible();
+  const box = await option.boundingBox();
+  if (box == null) {
+    throw new Error('the Banana option has no layout box');
+  }
+
+  await page.mouse.click(box.x + box.width / 2, box.y + box.height / 2);
+
+  await expect(page.getByTestId('selected-value')).toHaveText('Banana');
+});

package/src/hooks/useBusyAnnouncement.ts

@@ -0,0 +1,100 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useBusyAnnouncement.ts
+ * @input Whether the owning control is busy, the words to announce, and a ref
+ *   to an element inside the control
+ * @output Announces each busy start once, through the shared polite channel
+ *   or a persistent region inside the open modal dialog holding the control
+ * @position Core a11y hook for controls that show a decorative busy Spinner
+ *
+ * The busy Spinner inside a control is decorative (hidden, no live role); the
+ * control announces its busy state instead (`spec:AST-086` FR8), once per busy
+ * start (FR6): rerenders and StrictMode replay do not repeat it, and settling
+ * re-arms it. While a native modal is open, the body-level channel is not
+ * exposed, so a control inside it announces through one persistent polite
+ * region in that dialog, inserted empty and filled a frame later (Platform
+ * support, FR3).
+ *
+ * SYNC: deliberately NOT exported from /packages/core/src/hooks/index.ts —
+ * this is a shared implementation detail of Astryx's busy controls.
+ */
+
+import {useEffect, useRef, type RefObject} from 'react';
+import {useAnnounce} from './useAnnounce';
+
+const REGION_ATTR = 'data-astryx-modal-busy-region';
+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;';
+const CLEAR_DELAY_MS = 2000; // Matches useAnnounce.
+
+// The pending write and clear of each in-dialog region; a new write cancels
+// them so an earlier message can neither land late nor clear a later one.
+const pendingByRegion = new WeakMap<
+  HTMLElement,
+  {frame: number; timer?: ReturnType<typeof setTimeout>}
+>();
+
+function announceInModal(dialog: HTMLDialogElement, message: string): void {
+  let region = dialog.querySelector<HTMLElement>(`:scope > [${REGION_ATTR}]`);
+  if (region == null) {
+    region = document.createElement('div');
+    region.setAttribute(REGION_ATTR, '');
+    region.setAttribute('role', 'status');
+    region.setAttribute('aria-live', 'polite');
+    region.setAttribute('aria-atomic', 'true');
+    region.style.cssText = VISUALLY_HIDDEN_CSS;
+    dialog.appendChild(region);
+  }
+  const target = region;
+  const previous = pendingByRegion.get(target);
+  if (previous != null) {
+    cancelAnimationFrame(previous.frame);
+    clearTimeout(previous.timer);
+  }
+  target.textContent = '';
+  const pending: {frame: number; timer?: ReturnType<typeof setTimeout>} = {
+    frame: 0,
+  };
+  pending.frame = requestAnimationFrame(() => {
+    target.textContent = message;
+    pending.timer = setTimeout(() => {
+      target.textContent = '';
+      pendingByRegion.delete(target);
+    }, CLEAR_DELAY_MS);
+  });
+  pendingByRegion.set(target, pending);
+}
+
+export function useBusyAnnouncement(
+  isBusy: boolean,
+  message: string,
+  elementRef: RefObject<Element | null>,
+): void {
+  const announce = useAnnounce();
+  const hasAnnouncedRef = useRef(false);
+  useEffect(() => {
+    if (!isBusy) {
+      hasAnnouncedRef.current = false;
+      return;
+    }
+    if (hasAnnouncedRef.current) {
+      return;
+    }
+    // Choose the route a frame later: a Dialog opening in the same commit
+    // calls showModal() in its own Effect, which runs after this one.
+    const frame = requestAnimationFrame(() => {
+      hasAnnouncedRef.current = true;
+      const dialog = elementRef.current?.closest('dialog');
+      if (dialog?.open && dialog.matches(':modal')) {
+        announceInModal(dialog, message);
+      } else {
+        announce(message, 'polite');
+      }
+    });
+    return () => cancelAnimationFrame(frame);
+  }, [announce, elementRef, isBusy, message]);
+}

package/src/hooks/useMenuPress.test.tsx

@@ -11,7 +11,7 @@
  */
 
 import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
-import {act, fireEvent, render, screen} from '@testing-library/react';
+import {act, fireEvent, render, screen, within} from '@testing-library/react';
 import {useRef, useState} from 'react';
 import {
   MENU_PRESS_AUTOSCROLL_ZONE_PX,
@@ -145,6 +145,32 @@ describe('useMenuPress — tracking inside the menu', () => {
     expect(onSelect).toHaveBeenCalledTimes(1);
   });
 
+  it('hit-tests in the shadow root that holds the menu, not the document', () => {
+    const host = document.createElement('div');
+    document.body.append(host);
+    const shadow = host.attachShadow({mode: 'open'});
+    const container = document.createElement('div');
+    shadow.append(container);
+    const onSelect = vi.fn();
+    render(<Harness onSelect={onSelect} />, {container});
+    const inShadow = (label: string) =>
+      within(container).getByRole('menuitem', {name: label});
+    // As in a browser: the document answers with the shadow host; only the
+    // shadow root knows the row under the point.
+    Object.assign(document, {elementFromPoint: () => host});
+    Object.assign(shadow, {elementFromPoint: () => inShadow('C')});
+    try {
+      const events = {...mouse(), composed: true, bubbles: true};
+      fireEvent.pointerDown(inShadow('A'), events);
+      fireEvent.pointerUp(inShadow('A'), events);
+      expect(onSelect).toHaveBeenCalledWith('C');
+      expect(onSelect).toHaveBeenCalledTimes(1);
+    } finally {
+      delete (document as {elementFromPoint?: unknown}).elementFromPoint;
+      host.remove();
+    }
+  });
+
   it('moves the highlight as focus with preventScroll', () => {
     render(<Harness />);
     const b = row('B');

package/src/hooks/useMenuPress.ts

@@ -209,8 +209,8 @@ export interface UseMenuPressOptions {
   getScroller?: () => HTMLElement | null;
   /**
    * Resolve the element under a viewport point. Defaults to
-   * `document.elementFromPoint`, falling back to the event target where the
-   * document lacks it (jsdom). A test seam.
+   * `elementFromPoint` on the menu's own document or shadow root, falling back
+   * to the event target where the document lacks it (jsdom). A test seam.
    */
   hitTest?: (x: number, y: number) => Element | null;
   /** @default 500 */
@@ -364,7 +364,16 @@ export function useMenuPress(options: UseMenuPressOptions): UseMenuPressReturn {
       if (hitTest != null) {
         element = hitTest(event.clientX, event.clientY);
       } else if (typeof doc.elementFromPoint === 'function') {
-        element = doc.elementFromPoint(event.clientX, event.clientY);
+        // Hit-test in the menu's own tree: inside a shadow root the document
+        // answers with the shadow host, never the row under the pointer.
+        const tree = menu?.getRootNode();
+        const scope: Pick<Document, 'elementFromPoint'> =
+          tree != null &&
+          tree !== doc &&
+          typeof (tree as ShadowRoot).elementFromPoint === 'function'
+            ? (tree as ShadowRoot)
+            : doc;
+        element = scope.elementFromPoint(event.clientX, event.clientY);
       } else {
         element = event.target instanceof Element ? event.target : null;
       }

package/src/hooks/useTypeahead.test.tsx

@@ -10,7 +10,8 @@
  */
 
 import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
-import {renderHook} from '@testing-library/react';
+import {Activity, type ReactNode} from 'react';
+import {render, renderHook} from '@testing-library/react';
 import {useTypeahead} from './useTypeahead';
 
 const LABELS = ['Apple', 'Apricot', 'Banana', 'Cherry'] as const;
@@ -86,6 +87,46 @@ describe('useTypeahead', () => {
     expect(onMatch).toHaveBeenLastCalledWith(2);
   });
 
+  it('clears the pending buffer reset when the component unmounts', () => {
+    const {result, unmount} = renderHook(() =>
+      useTypeahead({getItemLabels: () => LABELS, onMatch: vi.fn()}),
+    );
+    result.current.onKeyDown(key('a'));
+    expect(vi.getTimerCount()).toBe(1);
+    unmount();
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it('empties the buffer when an Activity boundary hides the collection', () => {
+    const latest: {api: ReturnType<typeof useTypeahead> | null} = {api: null};
+    function Probe(): ReactNode {
+      latest.api = useTypeahead({
+        getItemLabels: () => LABELS,
+        onMatch: vi.fn(),
+      });
+      return null;
+    }
+    const {rerender} = render(
+      <Activity mode="visible">
+        <Probe />
+      </Activity>,
+    );
+    latest.api?.onKeyDown(key('a'));
+    rerender(
+      <Activity mode="hidden">
+        <Probe />
+      </Activity>,
+    );
+    expect(vi.getTimerCount()).toBe(0);
+    rerender(
+      <Activity mode="visible">
+        <Probe />
+      </Activity>,
+    );
+    // The typed prefix went with the hide, so a bare Space is not typeahead.
+    expect(latest.api?.onKeyDown(key(' '))).toBe(false);
+  });
+
   it('skips disabled items', () => {
     const {onMatch, api} = setup({disabledIndices: [0]}); // Apple disabled
     api.onKeyDown(key('a'));

package/src/hooks/useTypeahead.ts

@@ -4,7 +4,7 @@
 
 /**
  * @file useTypeahead.ts
- * @input Uses React useCallback/useRef
+ * @input Uses React useCallback/useEffect/useRef
  * @output Exports useTypeahead hook for first-character (type-to-focus) search
  * @position Core hook; adds APG typeahead to menus, listboxes, and other
  *   collections. Composes with useListFocus/useGridFocus (or any collection)
@@ -14,7 +14,7 @@
  * - /packages/core/src/hooks/index.ts
  */
 
-import {useCallback, useRef} from 'react';
+import {useCallback, useEffect, useRef} from 'react';
 
 export interface UseTypeaheadOptions {
   /**
@@ -135,6 +135,11 @@ export function useTypeahead(options: UseTypeaheadOptions): UseTypeaheadReturn {
     }
   }, []);
 
+  // A collection that unmounts, or that an `<Activity>` boundary hides,
+  // mid-typing leaves no reset timer running and comes back with an empty
+  // buffer, as the reset would have left it.
+  useEffect(() => reset, [reset]);
+
   const scheduleReset = useCallback(() => {
     if (timeoutRef.current) {
       clearTimeout(timeoutRef.current);

package/src/i18n/generated-locales/en.generated.ts

@@ -340,6 +340,7 @@ const runtimeCatalog: Readonly<Record<string, string>> = {
   '@astryx.chatToolCalls.status.complete': 'Complete',
   '@astryx.chatToolCalls.status.error': 'Failed',
   '@astryx.chatToolCalls.groupLabel': '{count} tool calls',
+  '@astryx.chatTriggerMenu.searching': 'Searching…',
   '@astryx.chatTriggerMenu.suggestions': 'Suggestions',
   '@astryx.citation.label': 'Citation {number}: {title}',
   '@astryx.codeBlock.copied': 'Copied',

package/src/i18n/generated-locales/pseudo.generated.ts

@@ -347,6 +347,7 @@ const runtimeCatalog: Readonly<Record<string, string>> = {
   '@astryx.chatToolCalls.status.complete': '⟦Çóɱþłéţé⟧',
   '@astryx.chatToolCalls.status.error': '⟦Ƒàíłéð⟧',
   '@astryx.chatToolCalls.groupLabel': '⟦{count} ţóół çàłłš⟧',
+  '@astryx.chatTriggerMenu.searching': '⟦Šéàřçĥíñĝ…⟧',
   '@astryx.chatTriggerMenu.suggestions': '⟦Šúĝĝéšţíóñš⟧',
   '@astryx.citation.label': '⟦Çíţàţíóñ {number}: {title}⟧',
   '@astryx.codeBlock.copied': '⟦Çóþíéð⟧',