@astryxdesign/core 0.1.9 → 0.2.0-canary.136a00f

package/src/Typeahead/BaseTypeahead.tsx

@@ -157,6 +157,16 @@ export interface BaseTypeaheadProps<T extends SearchableItem> extends Omit<
    */
   inputXStyle?: StyleXStyles;
 
+  /**
+   * Tab-order override for the input element. Typeahead passes `-1` while
+   * its selected-value token is shown: the input is visually collapsed
+   * (width 0 / opacity 0) but must stay programmatically focusable for
+   * token edit/clear interactions, so removing it from the Tab order is
+   * what prevents an invisible tab stop (WCAG 2.4.3 / 2.4.7). The input
+   * remains focusable via `.focus()` regardless of this value.
+   */
+  inputTabIndex?: number;
+
   /**
    * Ref to the anchor element for dropdown positioning.
    * The dropdown will be positioned relative to this element.
@@ -230,7 +240,7 @@ const styles = stylex.create({
     outline: 'none',
     backgroundColor: 'transparent',
     border: 'none',
-    textAlign: 'left',
+    textAlign: 'start',
   },
   itemHighlighted: {
     backgroundColor: colorVars['--color-overlay-hover'],
@@ -316,6 +326,7 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
   ariaDescribedBy,
   ariaLabelledBy,
   inputXStyle,
+  inputTabIndex,
   anchorRef,
   onKeyDown: externalOnKeyDown,
   debounceMs = 150,
@@ -431,7 +442,7 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
         resultsGenRef.current = gen;
         const shown = searchResults.slice(0, maxMenuItems);
         setResults(shown);
-        setHighlightedIndex(searchResults.length > 0 ? 0 : -1);
+        setHighlightedIndex(shown.length > 0 ? 0 : -1);
         if (searchResults.length > 0 || searchQuery.length > 0) {
           showLayer();
         }
@@ -469,8 +480,9 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
         return;
       }
       resultsGenRef.current = gen;
-      setResults(bootstrapResults.slice(0, maxMenuItems));
-      setHighlightedIndex(bootstrapResults.length > 0 ? 0 : -1);
+      const shown = bootstrapResults.slice(0, maxMenuItems);
+      setResults(shown);
+      setHighlightedIndex(shown.length > 0 ? 0 : -1);
       if (bootstrapResults.length > 0) {
         showLayer();
       }
@@ -637,15 +649,19 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
       switch (e.key) {
         case 'ArrowDown':
           e.preventDefault();
-          setHighlightedIndex(prev =>
-            prev < results.length - 1 ? prev + 1 : 0,
-          );
+          if (results.length > 0) {
+            setHighlightedIndex(prev =>
+              prev < results.length - 1 ? prev + 1 : 0,
+            );
+          }
           break;
         case 'ArrowUp':
           e.preventDefault();
-          setHighlightedIndex(prev =>
-            prev > 0 ? prev - 1 : results.length - 1,
-          );
+          if (results.length > 0) {
+            setHighlightedIndex(prev =>
+              prev > 0 ? prev - 1 : results.length - 1,
+            );
+          }
           break;
         case 'Enter':
           e.preventDefault();
@@ -660,13 +676,17 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
         case 'Home':
           if (popover.isOpen) {
             e.preventDefault();
-            setHighlightedIndex(0);
+            if (results.length > 0) {
+              setHighlightedIndex(0);
+            }
           }
           break;
         case 'End':
           if (popover.isOpen) {
             e.preventDefault();
-            setHighlightedIndex(results.length - 1);
+            if (results.length > 0) {
+              setHighlightedIndex(results.length - 1);
+            }
           }
           break;
       }
@@ -694,13 +714,17 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
   // cursor walks off-screen once navigation passes the visible window. Mirrors
   // CommandPaletteItem's scrollIntoView({block: 'nearest'}) behavior.
   useEffect(() => {
-    if (!popover.isOpen || highlightedIndex < 0) {
+    if (
+      !popover.isOpen ||
+      highlightedIndex < 0 ||
+      highlightedIndex >= results.length
+    ) {
       return;
     }
     document
       .getElementById(getItemId(highlightedIndex))
       ?.scrollIntoView?.({block: 'nearest'});
-  }, [popover.isOpen, highlightedIndex, getItemId]);
+  }, [popover.isOpen, highlightedIndex, getItemId, results.length]);
 
   const selectedKey =
     value == null ? null : getKey(value.id, () => results.indexOf(value));
@@ -725,7 +749,9 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
         aria-expanded={popover.isOpen}
         aria-controls={listboxId}
         aria-activedescendant={
-          popover.isOpen && highlightedIndex >= 0
+          popover.isOpen &&
+          highlightedIndex >= 0 &&
+          highlightedIndex < results.length
             ? getItemId(highlightedIndex)
             : undefined
         }
@@ -733,6 +759,7 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
         aria-describedby={ariaDescribedBy}
         aria-labelledby={ariaLabelledBy}
         aria-disabled={isFocusableDisabled ? 'true' : undefined}
+        tabIndex={inputTabIndex}
         value={query}
         onChange={handleInputChange}
         onPointerDown={() => {

package/src/Typeahead/Typeahead.doc.mjs

@@ -89,6 +89,13 @@ export const docs = {
       description:
         'Validation status object with type and message for error/warning/success states.',
     },
+    {
+      name: 'statusVariant',
+      type: "'attached' | 'detached'",
+      description:
+        'How the status message is placed relative to the input. attached overlaps directly below the input (bordered treatment); detached floats below as a separate element with spacing.',
+      default: "'attached'",
+    },
     {
       name: 'renderItem',
       type: '(item: T) => ReactNode',
@@ -158,6 +165,12 @@ export const docs = {
       type: '(isOpen: boolean) => void',
       description: 'Callback when the dropdown opens or closes.',
     },
+    {
+      name: 'width',
+      type: 'SizeValue',
+      description:
+        'Width of the field (number = pixels, string used as-is, e.g. "100%"). Sizes the whole field (label, control, and status) so they stay aligned.',
+    },
     {
       name: 'xstyle',
       type: 'StyleXStyles',

package/src/Typeahead/Typeahead.test.tsx

@@ -171,6 +171,33 @@ describe('BaseTypeahead', () => {
     });
   });
 
+  describe('empty results active descendant (#4059)', () => {
+    it('does not set aria-activedescendant when search has 0 results', async () => {
+      render(
+        <BaseTypeahead
+          searchSource={fruitSource}
+          value={null}
+          onChange={() => {}}
+          debounceMs={0}
+        />,
+      );
+      const input = screen.getByRole('combobox');
+      fireEvent.change(input, {target: {value: 'zzzzz'}});
+
+      await waitFor(() => {
+        expect(input).not.toHaveAttribute('aria-activedescendant');
+      });
+
+      // Press ArrowDown — should NOT set aria-activedescendant to option-0
+      fireEvent.keyDown(input, {key: 'ArrowDown'});
+      expect(input).not.toHaveAttribute('aria-activedescendant');
+
+      // Press Home — should NOT set aria-activedescendant
+      fireEvent.keyDown(input, {key: 'Home'});
+      expect(input).not.toHaveAttribute('aria-activedescendant');
+    });
+  });
+
   it('disables input when isDisabled', () => {
     render(
       <BaseTypeahead
@@ -710,6 +737,68 @@ describe('Typeahead edit mode', () => {
   });
 });
 
+describe('Typeahead collapsed input tab order', () => {
+  it('removes the invisible input from the Tab order while a token is shown', () => {
+    render(
+      <Typeahead
+        label="Fruit"
+        searchSource={fruitSource}
+        value={fruits[0]}
+        onChange={() => {}}
+      />,
+    );
+    // While the token is shown the input is collapsed (width 0 / opacity 0);
+    // it must stay programmatically focusable for token interactions but must
+    // not be an invisible Tab stop (WCAG 2.4.3 / 2.4.7).
+    expect(screen.getByRole('combobox')).toHaveAttribute('tabindex', '-1');
+  });
+
+  it('Tab from the token skips the invisible input', async () => {
+    const user = userEvent.setup();
+    render(
+      <Typeahead
+        label="Fruit"
+        searchSource={fruitSource}
+        value={fruits[0]}
+        onChange={() => {}}
+      />,
+    );
+    // Focus the token's internal button, then Tab away — focus must not land
+    // on the visually hidden combobox input.
+    const tokenButton = screen.getByRole('button', {name: fruits[0].label});
+    tokenButton.focus();
+    await user.tab();
+    expect(screen.getByRole('combobox')).not.toHaveFocus();
+  });
+
+  it('keeps the input in the Tab order when no token is shown', () => {
+    render(
+      <Typeahead
+        label="Fruit"
+        searchSource={fruitSource}
+        value={null}
+        onChange={() => {}}
+      />,
+    );
+    expect(screen.getByRole('combobox')).not.toHaveAttribute('tabindex');
+  });
+
+  it('restores the input to the Tab order in edit mode', () => {
+    render(
+      <Typeahead
+        label="Fruit"
+        searchSource={fruitSource}
+        value={fruits[0]}
+        onChange={() => {}}
+      />,
+    );
+    // Entering edit mode removes the token and uncollapses the input
+    const tokenText = screen.getByText(fruits[0].label);
+    fireEvent.click(tokenText.closest('div')!);
+    expect(screen.getByRole('combobox')).not.toHaveAttribute('tabindex');
+  });
+});
+
 describe('BaseTypeahead paste behavior', () => {
   it('pasting text triggers search results like typing', async () => {
     const user = userEvent.setup();
@@ -948,3 +1037,26 @@ describe('Typeahead disabledMessage', () => {
     expect(input).not.toHaveAttribute('aria-disabled');
   });
 });
+
+
+describe('Typeahead statusVariant forwarding', () => {
+  it('defaults to attached (status renders with data-variant="attached")', () => {
+    const {container} = render(
+      <Typeahead label="Fruit" searchSource={fruitSource} value={null} onChange={() => {}} status={{type: 'error', message: 'Required'}} />,
+    );
+    expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+      'data-variant',
+      'attached',
+    );
+  });
+
+  it('forwards statusVariant="detached" to the underlying Field status', () => {
+    const {container} = render(
+      <Typeahead label="Fruit" searchSource={fruitSource} value={null} onChange={() => {}} status={{type: 'error', message: 'Required'}} statusVariant="detached" />,
+    );
+    expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+      'data-variant',
+      'detached',
+    );
+  });
+});

package/src/Typeahead/Typeahead.tsx

@@ -36,6 +36,7 @@ import {
   inputStatusBorderStyles,
   inputStatusHoverShadowStyles,
   inputStatusFocusWithinStyles,
+  type FieldStatusVariant,
 } from '../Field';
 import {Token} from '../Token';
 import {useTooltip} from '../Tooltip';
@@ -75,6 +76,13 @@ export interface TypeaheadProps<T extends SearchableItem> extends Omit<
   isOptional?: boolean;
   /** Validation status. */
   status?: InputStatus;
+  /**
+   * How the status message is placed relative to the input.
+   * - 'attached': message overlaps directly below the input (bordered treatment)
+   * - 'detached': message floats below as a separate element with spacing
+   * @default 'attached'
+   */
+  statusVariant?: FieldStatusVariant;
   /**
    * Icon to display at the start of the input.
    * Accepts a ReactNode (e.g. `<Icon icon={SearchIcon} />`) or an SVG icon component directly.
@@ -226,6 +234,7 @@ export function Typeahead<T extends SearchableItem>({
   isRequired = false,
   isOptional = false,
   status,
+  statusVariant = 'attached',
   startIcon,
   labelTooltip,
   searchSource,
@@ -412,7 +421,7 @@ export function Typeahead<T extends SearchableItem>({
             styles.wrapper,
             sizeStyle,
             status && inputStatusBorderStyles[status.type],
-            status && inputStatusHoverShadowStyles[status.type],
+            status && !isDisabled && inputStatusHoverShadowStyles[status.type],
             status && inputStatusFocusWithinStyles[status.type],
             isDisabled && inputWrapperStyles.disabled,
             inputGroup && groupStyles.inGroup,
@@ -458,6 +467,12 @@ export function Typeahead<T extends SearchableItem>({
           anchorRef={wrapperRef}
           onKeyDown={handleKeyDown}
           inputXStyle={showToken ? styles.inputHidden : undefined}
+          // While the token is shown the input is collapsed (width 0 /
+          // opacity 0) — take it out of the Tab order so keyboard users
+          // don't hit an invisible stop (WCAG 2.4.3 / 2.4.7). It stays
+          // programmatically focusable: entering edit mode and clearing
+          // both refocus it after it uncollapses.
+          inputTabIndex={showToken ? -1 : undefined}
           size={size}
         />
         {hasClear && value && !isDisabled && (
@@ -500,6 +515,7 @@ export function Typeahead<T extends SearchableItem>({
             }
           : undefined
       }
+      statusVariant={statusVariant}
       labelTooltip={labelTooltip}
       width={width}
       xstyle={xstyle}

package/src/Typeahead/TypeaheadItem.tsx

@@ -132,6 +132,7 @@ export function TypeaheadItem<T extends SearchableItem>({
   icon,
   description,
   isDisabled = false,
+  xstyle,
 }: TypeaheadItemProps<T>) {
   // If item has a pre-rendered element, use it
   if (item.element) {
@@ -143,7 +144,7 @@ export function TypeaheadItem<T extends SearchableItem>({
       ref={ref}
       {...mergeProps(
         themeProps('typeahead-item'),
-        stylex.props(styles.container, isDisabled && styles.disabled),
+        stylex.props(styles.container, isDisabled && styles.disabled, xstyle),
       )}>
       {icon}
       <div {...stylex.props(styles.content)}>

package/src/__tests__/forcedColors.ts

@@ -0,0 +1,60 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file forcedColors.ts
+ * @input Uses the jsdom document (StyleX dev runtime injects rules into it)
+ * @output Exports getForcedColorsRules, getAllInjectedCss test helpers
+ * @position Shared test utility for asserting forced-colors style output
+ *
+ * jsdom cannot emulate `@media (forced-colors: active)` rendering, so
+ * component tests assert the next-best thing: that the StyleX dev runtime
+ * (runtimeInjection in vitest.config.ts) actually injected the forced-colors
+ * rules a component relies on for Windows High Contrast support (WCAG 1.4.11).
+ * Visual behavior needs manual verification in a forced-colors environment.
+ */
+
+/**
+ * Collects the cssText of every injected CSS rule scoped to
+ * `@media (forced-colors: active)`, including rules nested in other
+ * conditions. Returns one string for substring assertions.
+ */
+export function getForcedColorsRules(): string {
+  const chunks: string[] = [];
+  for (const sheet of Array.from(document.styleSheets)) {
+    let rules: CSSRule[];
+    try {
+      rules = Array.from(sheet.cssRules);
+    } catch {
+      continue;
+    }
+    for (const rule of rules) {
+      if (rule.cssText.includes('forced-colors: active')) {
+        chunks.push(rule.cssText);
+      }
+    }
+  }
+  return chunks.join('\n');
+}
+
+/**
+ * Collects the cssText of every injected CSS rule, regardless of condition.
+ * Use to assert declarations that live OUTSIDE `@media (forced-colors: active)`
+ * yet still exist for forced-colors support — e.g. `forced-color-adjust: none`
+ * (an unconditional declaration) or a hover tint gated behind
+ * `(forced-colors: none)` so it cannot override the forced-colors state.
+ */
+export function getAllInjectedCss(): string {
+  const chunks: string[] = [];
+  for (const sheet of Array.from(document.styleSheets)) {
+    let rules: CSSRule[];
+    try {
+      rules = Array.from(sheet.cssRules);
+    } catch {
+      continue;
+    }
+    for (const rule of rules) {
+      chunks.push(rule.cssText);
+    }
+  }
+  return chunks.join('\n');
+}

package/src/__tests__/inputWidthContract.test.tsx

@@ -0,0 +1,62 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+
+import {docs as CheckboxInputDocs} from '../CheckboxInput/CheckboxInput.doc.mjs';
+import {docs as CheckboxListDocs} from '../CheckboxList/CheckboxList.doc.mjs';
+import {docs as DateInputDocs} from '../DateInput/DateInput.doc.mjs';
+import {docs as DateRangeInputDocs} from '../DateRangeInput/DateRangeInput.doc.mjs';
+import {docs as DateTimeInputDocs} from '../DateTimeInput/DateTimeInput.doc.mjs';
+import {docs as FileInputDocs} from '../FileInput/FileInput.doc.mjs';
+import {docs as MultiSelectorDocs} from '../MultiSelector/MultiSelector.doc.mjs';
+import {docs as NumberInputDocs} from '../NumberInput/NumberInput.doc.mjs';
+import {docs as RadioListDocs} from '../RadioList/RadioList.doc.mjs';
+import {docs as SelectorDocs} from '../Selector/Selector.doc.mjs';
+import {docs as SliderDocs} from '../Slider/Slider.doc.mjs';
+import {docs as SwitchDocs} from '../Switch/Switch.doc.mjs';
+import {docs as TextAreaDocs} from '../TextArea/TextArea.doc.mjs';
+import {docs as TextInputDocs} from '../TextInput/TextInput.doc.mjs';
+import {docs as TimeInputDocs} from '../TimeInput/TimeInput.doc.mjs';
+import {docs as TokenizerDocs} from '../Tokenizer/Tokenizer.doc.mjs';
+import {docs as TypeaheadDocs} from '../Typeahead/Typeahead.doc.mjs';
+
+const inputDocsSuite = [
+  {name: 'CheckboxInput', docs: CheckboxInputDocs},
+  {name: 'CheckboxList', docs: CheckboxListDocs},
+  {name: 'DateInput', docs: DateInputDocs},
+  {name: 'DateRangeInput', docs: DateRangeInputDocs},
+  {name: 'DateTimeInput', docs: DateTimeInputDocs},
+  {name: 'FileInput', docs: FileInputDocs},
+  {name: 'MultiSelector', docs: MultiSelectorDocs},
+  {name: 'NumberInput', docs: NumberInputDocs},
+  {name: 'RadioList', docs: RadioListDocs},
+  {name: 'Selector', docs: SelectorDocs},
+  {name: 'Slider', docs: SliderDocs},
+  {name: 'Switch', docs: SwitchDocs},
+  {name: 'TextArea', docs: TextAreaDocs},
+  {name: 'TextInput', docs: TextInputDocs},
+  {name: 'TimeInput', docs: TimeInputDocs},
+  {name: 'Tokenizer', docs: TokenizerDocs},
+  {name: 'Typeahead', docs: TypeaheadDocs},
+];
+
+describe('Input Family width Prop Contract (#4163)', () => {
+  inputDocsSuite.forEach(({name, docs}) => {
+    it(`documents the width prop for ${name}`, () => {
+      const propsList = (docs.props || docs.components?.[0]?.props) as {
+        name: string;
+        type: string;
+      }[];
+      expect(
+        propsList,
+        `${name}.doc.mjs must expose a props array`,
+      ).toBeDefined();
+      const widthProp = propsList.find(p => p.name === 'width');
+      expect(
+        widthProp,
+        `${name}.doc.mjs must document the width prop`,
+      ).toBeDefined();
+      expect(widthProp?.type).toBe('SizeValue');
+    });
+  });
+});

package/src/doc-mjs.d.ts

@@ -0,0 +1,19 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Ambient module declaration for `*.doc.mjs` imports.
+ *
+ * Component contract tests (packages/core/src/__tests__/*Contract.test.tsx)
+ * import `{Name}.doc.mjs` files directly to assert their documented props
+ * stay in sync with the component's real API. Without this declaration,
+ * TypeScript has no way to type a `.mjs` import and fails with
+ * TS7016 ("Could not find a declaration file for module").
+ */
+
+declare module '*.doc.mjs' {
+  import type {ComponentDoc, TranslationDoc} from './docs-types';
+
+  export const docs: ComponentDoc;
+  export const docsZh: ComponentDoc;
+  export const docsDense: TranslationDoc;
+}

package/src/hooks/index.ts

@@ -76,6 +76,12 @@ export type {
 export {useInputContainer} from './useInputContainer';
 export type {UseInputContainerOptions} from './useInputContainer';
 
+export {useInputStatusIcon} from './useInputStatusIcon';
+export type {
+  UseInputStatusIconOptions,
+  UseInputStatusIconReturn,
+} from './useInputStatusIcon';
+
 export {useInteractiveRole} from './useInteractiveRole';
 export type {
   InteractiveRole,

package/src/hooks/isRtlElement.ts

@@ -0,0 +1,27 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file isRtlElement.ts
+ * @input DOM element (nullable)
+ * @output Exports isRtlElement helper resolving an element's computed text
+ *   direction
+ * @position Internal hook utility; used by useListFocus and useGridFocus to
+ *   auto-detect RTL for arrow-key navigation (same getComputedStyle precedent
+ *   as Resizable's ResizeHandle drag deltas).
+ */
+
+/**
+ * Whether `el` renders right-to-left, per its computed `direction`.
+ *
+ * SSR-safe: returns false when `el` is null or no DOM is available. Callers
+ * should invoke this lazily (on keydown, not on render) so getComputedStyle
+ * runs only when a horizontal arrow key is actually handled.
+ */
+export function isRtlElement(el: HTMLElement | null): boolean {
+  if (!el || typeof window === 'undefined') {
+    return false;
+  }
+  return window.getComputedStyle(el).direction === 'rtl';
+}

package/src/hooks/useAnnounce.test.tsx

@@ -9,8 +9,8 @@
  * 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 {describe, it, expect, afterEach, vi} from 'vitest';
+import {act, renderHook, waitFor} from '@testing-library/react';
 import {useAnnounce, __resetLiveRegionsForTest} from './useAnnounce';
 
 afterEach(() => {
@@ -82,6 +82,79 @@ describe('useAnnounce', () => {
     expect(politeRegion()).toBeNull();
   });
 
+  it('clears the region after the clear delay, but not before', () => {
+    vi.useFakeTimers();
+    try {
+      const {result} = renderHook(() => useAnnounce());
+      result.current('Saved');
+      // Flush the rAF that re-sets the message.
+      act(() => {
+        vi.advanceTimersByTime(50);
+      });
+      expect(politeRegion()?.textContent).toBe('Saved');
+
+      // The message survives long enough for AT to finish reading it.
+      act(() => {
+        vi.advanceTimersByTime(1000);
+      });
+      expect(politeRegion()?.textContent).toBe('Saved');
+
+      // After the clear delay, stale status text is removed from the DOM.
+      act(() => {
+        vi.advanceTimersByTime(10_000);
+      });
+      expect(politeRegion()?.textContent).toBe('');
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('resets the clear timer on each announce', () => {
+    vi.useFakeTimers();
+    try {
+      const {result} = renderHook(() => useAnnounce());
+      result.current('first');
+      act(() => {
+        vi.advanceTimersByTime(1500);
+      });
+      // Announcing again must reset the pending clear, not inherit it.
+      result.current('second');
+      act(() => {
+        vi.advanceTimersByTime(1900);
+      });
+      // 3.4s after 'first' (past its clear point) but only 1.9s after
+      // 'second' — the newer message must still be present.
+      expect(politeRegion()?.textContent).toBe('second');
+      act(() => {
+        vi.advanceTimersByTime(10_000);
+      });
+      expect(politeRegion()?.textContent).toBe('');
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('re-announces normally after a clear', () => {
+    vi.useFakeTimers();
+    try {
+      const {result} = renderHook(() => useAnnounce());
+      result.current('gone soon');
+      act(() => {
+        vi.advanceTimersByTime(10_000);
+      });
+      expect(politeRegion()?.textContent).toBe('');
+
+      // The clear-then-rAF re-announce pattern still works after a clear.
+      result.current('back again');
+      act(() => {
+        vi.advanceTimersByTime(50);
+      });
+      expect(politeRegion()?.textContent).toBe('back again');
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
   it('reuses the same singleton regions across hook instances', async () => {
     const {result: a} = renderHook(() => useAnnounce());
     a.current('first');