@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/hooks/useAnnounceRenderedText.adopters.test.tsx

@@ -0,0 +1,226 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file useAnnounceRenderedText.adopters.test.tsx
+ * @input Every core component that announces its own rendered content, with
+ *   the shared own-content module replaced by a recorder
+ * @output architecture:react-component-runtime INV10 test: each adopter hands
+ *   its own-content announcement to the shared module and announces none of it
+ *   itself
+ * @position Shared adopter test for the own-content announcement module
+ *
+ * With the module replaced by a recorder that never announces, an adopter that
+ * still announced its own content would be holding an Effect, observer, timer
+ * or listener of its own for it, which INV10 rules out. The registry check at
+ * the end keeps this list in step with every file that imports the module, so
+ * a new adopter cannot skip the test.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import {useEffect, useRef, type HTMLAttributes, type RefObject} from 'react';
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
+import {fireEvent, render, screen, waitFor} from '@testing-library/react';
+
+interface ModuleCall {
+  isShown: boolean;
+  text: string;
+}
+
+const calls: ModuleCall[] = [];
+const announce = vi.hoisted(() => vi.fn());
+
+vi.mock('./useAnnounceRenderedText', async importOriginal => ({
+  ...(await importOriginal<Record<string, unknown>>()),
+  useAnnounceRenderedText: (
+    ref: RefObject<HTMLElement | null>,
+    isShown: boolean,
+  ) => {
+    // Read after commit, the way the real module does.
+    useEffect(() => {
+      calls.push({isShown, text: ref.current?.textContent ?? ''});
+    });
+  },
+}));
+vi.mock('./AnnounceRenderedText', () => ({
+  AnnounceRenderedText: (props: HTMLAttributes<HTMLDivElement>) => {
+    const ref = useRef<HTMLDivElement>(null);
+    useEffect(() => {
+      calls.push({isShown: true, text: ref.current?.textContent ?? ''});
+    });
+    return <div ref={ref} {...props} />;
+  },
+}));
+vi.mock('./useAnnounce', async importOriginal => ({
+  ...(await importOriginal<Record<string, unknown>>()),
+  useAnnounce: () => announce,
+}));
+
+const {EmptyState} = await import('../EmptyState');
+const {ChatComposer} = await import('../Chat');
+const {Selector} = await import('../Selector');
+const {MultiSelector} = await import('../MultiSelector');
+const {CommandPalette} = await import('../CommandPalette');
+const {BaseTypeahead} = await import('../Typeahead/BaseTypeahead');
+const {TokenizerWithPresentation} =
+  await import('../internal/tokenizer-presentation');
+const {createStaticSource} = await import('../Typeahead/createStaticSource');
+
+const source = createStaticSource([{id: 'apple', label: 'Apple'}]);
+
+beforeEach(() => {
+  calls.length = 0;
+  announce.mockClear();
+  // jsdom does not implement the modal dialog methods CommandPalette uses.
+  HTMLDialogElement.prototype.showModal = vi.fn(function (
+    this: HTMLDialogElement,
+  ) {
+    this.setAttribute('open', '');
+  });
+  HTMLDialogElement.prototype.close = vi.fn(function (this: HTMLDialogElement) {
+    this.removeAttribute('open');
+  });
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+/**
+ * The adopter showed `text` through the module, and announced none of it
+ * through its own channel calls.
+ */
+async function expectDelegated(text: string) {
+  await waitFor(() =>
+    expect(calls.some(call => call.isShown && call.text.includes(text))).toBe(
+      true,
+    ),
+  );
+  const own = announce.mock.calls.filter(([message]) =>
+    String(message).includes(text),
+  );
+  expect(own).toEqual([]);
+}
+
+/** Each adopter, shown in the state where its own content appears. */
+const ADOPTERS: Record<string, () => Promise<void>> = {
+  'EmptyState/EmptyState.tsx': async () => {
+    render(<EmptyState title="Nothing here" description="Add an item" />);
+    await expectDelegated('Nothing here');
+  },
+  'Chat/ChatComposer.tsx': async () => {
+    const composer = (status?: {
+      type: 'error' | 'warning';
+      message: string;
+    }) => <ChatComposer onSubmit={() => {}} input={<div />} status={status} />;
+    const {rerender} = render(composer());
+    rerender(composer({type: 'error', message: 'Send failed'}));
+    await expectDelegated('Send failed');
+    rerender(composer({type: 'warning', message: 'Offline'}));
+    await expectDelegated('Offline');
+  },
+  'Selector/Selector.tsx': async () => {
+    render(
+      <Selector
+        label="Fruit"
+        options={[] as string[]}
+        value=""
+        onChange={() => {}}
+      />,
+    );
+    fireEvent.click(screen.getByRole('combobox'));
+    await expectDelegated('No options');
+  },
+  'MultiSelector/MultiSelector.tsx': async () => {
+    render(
+      <MultiSelector
+        label="Fruits"
+        options={[] as string[]}
+        value={[]}
+        onChange={() => {}}
+      />,
+    );
+    fireEvent.click(screen.getByRole('combobox'));
+    await expectDelegated('No options');
+  },
+  'CommandPalette/CommandPalette.tsx': async () => {
+    render(
+      <CommandPalette isOpen onOpenChange={() => {}} searchSource={source} />,
+    );
+    fireEvent.change(screen.getByRole('combobox'), {target: {value: 'zzz'}});
+    await expectDelegated('No results');
+  },
+  'Typeahead/BaseTypeahead.tsx': async () => {
+    render(
+      <BaseTypeahead
+        searchSource={source}
+        value={null}
+        onChange={() => {}}
+        debounceMs={0}
+      />,
+    );
+    fireEvent.change(screen.getByRole('combobox'), {target: {value: 'zzz'}});
+    await expectDelegated('No results found');
+  },
+  'Tokenizer/TokenizerBottomSheet.tsx': async () => {
+    // The sheet's own content is a caller's `emptySearchText` element; the
+    // default EmptyState announces itself.
+    render(
+      <TokenizerWithPresentation
+        label="Tags"
+        searchSource={source}
+        value={[]}
+        onChange={() => {}}
+        debounceMs={0}
+        emptySearchText={<em>Nothing called that</em>}
+        experimental={{presentation: 'bottom-sheet'}}
+      />,
+    );
+    fireEvent.click(screen.getByRole('button', {name: 'Tags'}));
+    fireEvent.change(await screen.findByLabelText('Search Tags'), {
+      target: {value: 'zzz'},
+    });
+    await expectDelegated('Nothing called that');
+  },
+};
+
+describe('own-content announcement adopters (react-component-runtime INV10)', () => {
+  it.each(Object.entries(ADOPTERS))(
+    '%s hands its own content to the shared module and announces none of it itself',
+    async (_file, run) => {
+      await run();
+    },
+  );
+
+  it('covers every core file that imports the module', () => {
+    const src = path.resolve(import.meta.dirname, '..');
+    const importers: string[] = [];
+    const walk = (dir: string) => {
+      for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+          walk(full);
+        } else if (
+          /\.tsx?$/.test(entry.name) &&
+          !/\.(test|spec|stories)\.tsx?$/.test(entry.name) &&
+          /from '[./]*(hooks\/)?(useAnnounceRenderedText|AnnounceRenderedText)'/.test(
+            fs.readFileSync(full, 'utf8'),
+          )
+        ) {
+          importers.push(path.relative(src, full));
+        }
+      }
+    };
+    walk(src);
+    const modules = [
+      'hooks/useAnnounceRenderedText.ts',
+      'hooks/AnnounceRenderedText.tsx',
+    ];
+    expect(
+      importers
+        .filter(file => !modules.includes(file))
+        .map(file => file.split(path.sep).join('/'))
+        .sort(),
+    ).toEqual(Object.keys(ADOPTERS).sort());
+  });
+});

package/src/hooks/useAnnounceRenderedText.ts

@@ -32,7 +32,7 @@
  * (see `FieldStatus` and `TimeInput`): a live region that mounts together
  * with its content is not reliably announced.
  *
- * Content hidden from the accessibility tree with `aria-hidden` is excluded,
+ * Content hidden with `aria-hidden` or `hidden` is excluded,
  * so a decorative icon stays out of the announcement exactly as it stays out
  * of what a screen reader reads. An `aria-label` renaming a descendant is NOT
  * substituted — the region speaks the rendered text.
@@ -43,17 +43,61 @@
  * admission. Import it by path from inside the package.
  */
 
-import {useEffect, useRef, type RefObject} from 'react';
-import {useAnnounce} from './useAnnounce';
+import {useEffect, useRef, useState, type RefObject} from 'react';
+import {useAnnounce, type AnnouncePoliteness} from './useAnnounce';
+import {useIsHydrating} from './useIsHydrating';
+
+const LIVE_CONTAINER =
+  '[role="log"], [role="status"], [role="alert"], [aria-live="polite"], [aria-live="assertive"]';
+const HIDDEN = '[aria-hidden="true"], [hidden]';
+const BLOCKS = 'p, div, li, br, h1, h2, h3, h4, h5, h6';
+
+/**
+ * Each child element's rendered text as its own block, joined by spaces. Text
+ * placed directly in the element, beside its child elements, counts as a block
+ * too (a status bar is an icon followed by its bare message).
+ */
+function blockText(element: HTMLElement): string {
+  return Array.from(element.childNodes)
+    .map(child => {
+      if (child.nodeType === Node.TEXT_NODE) {
+        return (child.textContent ?? '').replace(/\s+/g, ' ').trim();
+      }
+      // By node type, not `instanceof`: an element from another document's
+      // window (a portal into a same-origin iframe) fails this window's
+      // constructor checks.
+      if (child.nodeType === Node.ELEMENT_NODE) {
+        const part = child as HTMLElement;
+        return part.matches(HIDDEN) ? '' : renderedText(part);
+      }
+      return '';
+    })
+    .filter(part => part !== '')
+    .join(' ');
+}
+
+export interface AnnounceRenderedTextOptions {
+  /**
+   * Text present or changed while the document loads or hydrates is silent;
+   * text that appears or changes later is announced once (`spec:AST-086`
+   * FR11). A mounted live container speaks its own content (FR4); each child is
+   * a block; a reveal without a re-render is read on the next render (FR13).
+   */
+  skipFirstRender?: boolean;
+  /**
+   * The channel's urgency: errors and time-critical failures are assertive,
+   * every other message polite (`spec:AST-086` FR5). Defaults to polite.
+   */
+  politeness?: AnnouncePoliteness;
+}
 
 /** The rendered text an assistive technology would read from `element`. */
-function renderedText(element: HTMLElement): string {
+export function renderedText(element: HTMLElement): string {
   // Clone so removing the hidden parts cannot disturb what is on screen. The
   // clone is never attached to the document.
   const copy = element.cloneNode(true) as HTMLElement;
-  for (const hidden of copy.querySelectorAll('[aria-hidden="true"]')) {
-    hidden.remove();
-  }
+  copy.querySelectorAll(HIDDEN).forEach(node => node.remove());
+  copy.querySelectorAll(BLOCKS).forEach(node => node.after(' ')); // blocks apart
   return (copy.textContent ?? '').replace(/\s+/g, ' ').trim();
 }
 
@@ -81,9 +125,20 @@ export function useAnnounceRenderedText(
   ref: RefObject<HTMLElement | null>,
   isShown: boolean,
   occasion: string,
+  {
+    skipFirstRender = false,
+    politeness = 'polite',
+  }: AnnounceRenderedTextOptions = {},
 ): void {
   const announce = useAnnounce();
   const spokenRef = useRef<string | null>(null);
+  const isHydrating = useIsHydrating();
+  // Captured once: an owner rendered before the document finished loading, or
+  // hydrated from server HTML, is part of the page the person arrived at.
+  const [renderedWithPage] = useState(
+    () => isHydrating || document.readyState !== 'complete',
+  );
+  const isFirstRunRef = useRef(true);
 
   // Deliberately no dependency array. The text lives in the DOM, so there is
   // no React value to depend on that changes when it does — a caller can
@@ -91,15 +146,24 @@ export function useAnnounceRenderedText(
   // one element's text per render is cheap, and the dedupe below makes every
   // render after the first a no-op.
   useEffect(() => {
-    if (!isShown) {
+    const isFirstRun = isFirstRunRef.current;
+    isFirstRunRef.current = false;
+    const element = ref.current;
+    if (
+      !isShown ||
+      element?.closest(HIDDEN) ||
+      element?.checkVisibility?.() === false
+    ) {
       spokenRef.current = null;
       return;
     }
-    const element = ref.current;
     if (!element) {
       return;
     }
-    const text = renderedText(element);
+    if (skipFirstRender && element.parentElement?.closest(LIVE_CONTAINER)) {
+      return;
+    }
+    const text = skipFirstRender ? blockText(element) : renderedText(element);
     if (text === '') {
       // Nothing readable on screen either, so there is no announcement that
       // would match what the sighted user is seeing.
@@ -110,6 +174,12 @@ export function useAnnounceRenderedText(
       return;
     }
     spokenRef.current = spoken;
-    announce(text);
+    const isPageLoad =
+      (isFirstRun && renderedWithPage) || document.readyState !== 'complete';
+    if (skipFirstRender && isPageLoad) {
+      // Part of the page the person arrived at: remember it, say nothing.
+      return;
+    }
+    announce(text, politeness);
   });
 }

package/src/hooks/useBusyAnnouncement.adopters.test.tsx

@@ -0,0 +1,69 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file useBusyAnnouncement.adopters.test.tsx
+ * @input Uses vitest, @testing-library/react, BaseTypeahead, CommandPalette
+ * @output Tests that search controls settle their busy start when a search ends
+ * @position Testing; validates the settle wiring in useBusyAnnouncement adopters
+ */
+
+import {beforeEach, describe, expect, it, vi} from 'vitest';
+import {fireEvent, render, screen, waitFor} from '@testing-library/react';
+import {BaseTypeahead} from '../Typeahead/BaseTypeahead';
+import {CommandPalette} from '../CommandPalette';
+import {createStaticSource} from '../Typeahead/createStaticSource';
+
+const settle = vi.hoisted(() => vi.fn());
+vi.mock('./useBusyAnnouncement', () => ({
+  useBusyAnnouncement: () => settle,
+}));
+
+const source = createStaticSource([
+  {id: 'apple', label: 'Apple'},
+  {id: 'banana', label: 'Banana'},
+]);
+
+// jsdom does not implement the modal dialog methods CommandPalette uses.
+beforeEach(() => {
+  HTMLDialogElement.prototype.showModal = vi.fn(function (
+    this: HTMLDialogElement,
+  ) {
+    this.setAttribute('open', '');
+  });
+  HTMLDialogElement.prototype.close = vi.fn(function (this: HTMLDialogElement) {
+    this.removeAttribute('open');
+  });
+});
+
+describe('busy-start settle wiring (AST-086 FR8)', () => {
+  it("BaseTypeahead settles its busy start when a typed query's search settles", async () => {
+    render(
+      <BaseTypeahead
+        searchSource={source}
+        value={null}
+        onChange={() => {}}
+        debounceMs={0}
+      />,
+    );
+    settle.mockClear();
+    fireEvent.change(screen.getByRole('combobox'), {target: {value: 'Ap'}});
+    await waitFor(() => expect(settle).toHaveBeenCalled());
+    // An empty result is announced from the rendered row; it settles too.
+    settle.mockClear();
+    fireEvent.change(screen.getByRole('combobox'), {target: {value: 'zzz'}});
+    await waitFor(() => expect(settle).toHaveBeenCalled());
+  });
+
+  it("CommandPalette settles its input busy start when a typed query's search settles", async () => {
+    render(
+      <CommandPalette isOpen onOpenChange={() => {}} searchSource={source} />,
+    );
+    await waitFor(() => expect(screen.getByText('Apple')).toBeInTheDocument());
+    settle.mockClear();
+    fireEvent.change(screen.getByRole('combobox'), {target: {value: 'ban'}});
+    await waitFor(() => expect(settle).toHaveBeenCalled());
+    settle.mockClear();
+    fireEvent.change(screen.getByRole('combobox'), {target: {value: 'zzz'}});
+    await waitFor(() => expect(settle).toHaveBeenCalled());
+  });
+});

package/src/hooks/useBusyAnnouncement.test.tsx

@@ -0,0 +1,112 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file useBusyAnnouncement.test.tsx
+ * @input Uses vitest, @testing-library/react, useBusyAnnouncement
+ * @output Unit tests for the busy-start announcement and its settle function
+ * @position Testing; validates useBusyAnnouncement.ts
+ */
+
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
+import {act, renderHook} from '@testing-library/react';
+import {useRef} from 'react';
+import {useBusyAnnouncement} from './useBusyAnnouncement';
+import {__resetLiveRegionsForTest} from './useAnnounce';
+
+function politeText(): string {
+  return (
+    document.querySelector('[data-astryx-live-region="polite"]')?.textContent ??
+    ''
+  );
+}
+
+interface BusyProps {
+  isBusy: boolean;
+  message?: string;
+}
+
+function renderBusy() {
+  return renderHook<() => void, BusyProps>(
+    ({isBusy, message = 'Loading'}) =>
+      useBusyAnnouncement(isBusy, message, useRef(null)),
+    {initialProps: {isBusy: true}},
+  );
+}
+
+function runFrames() {
+  act(() => {
+    vi.advanceTimersByTime(50);
+  });
+}
+
+describe('useBusyAnnouncement', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+  afterEach(() => {
+    __resetLiveRegionsForTest();
+    vi.useRealTimers();
+  });
+
+  it('announces a busy start a frame after it begins', () => {
+    renderBusy();
+    runFrames();
+    expect(politeText()).toBe('Loading');
+  });
+
+  it('drops a busy start its owner settled before it was announced (AST-086 FR8)', () => {
+    const {result} = renderBusy();
+    act(() => {
+      result.current();
+    });
+    runFrames();
+    expect(politeText()).toBe('');
+  });
+
+  it('withdraws a busy start written to the channel but not yet exposed (AST-086 FR8)', () => {
+    const {result} = renderBusy();
+    // The busy frame writes "Loading" to the channel; its exposing frame has
+    // not run yet when the outcome announces and settles.
+    act(() => {
+      vi.advanceTimersToNextFrame();
+    });
+    act(() => {
+      result.current();
+    });
+    runFrames();
+    expect(politeText()).toBe('');
+  });
+
+  it('withdraws only its own busy start when another owner wrote the same words (AST-086 FR8, FR9)', () => {
+    const first = renderBusy();
+    const second = renderBusy();
+    // Both busy frames write "Loading" to the channel before it is exposed.
+    act(() => {
+      vi.advanceTimersToNextFrame();
+    });
+    // The first owner's search settles; the second is still busy.
+    act(() => {
+      first.result.current();
+    });
+    runFrames();
+    expect(politeText()).toBe('Loading');
+    second.unmount();
+  });
+
+  it('keeps a settled busy start dropped until the next busy start', () => {
+    const {result, rerender} = renderBusy();
+    act(() => {
+      result.current();
+    });
+    // Still busy until the settled state commits: nothing is rescheduled,
+    // even when the busy message changes (a locale switch, say).
+    rerender({isBusy: true, message: 'Chargement'});
+    runFrames();
+    expect(politeText()).toBe('');
+
+    rerender({isBusy: false});
+    rerender({isBusy: true});
+    runFrames();
+    expect(politeText()).toBe('Loading');
+  });
+});