@astryxdesign/core 0.1.9 → 0.2.0-canary.0e01213

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/containerReveal.pool.stylex.ts

@@ -0,0 +1,464 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file containerReveal.pool.stylex.ts
+ * @input Uses StyleX, theme tokens
+ * @output A fixed pool of scoped markers, each paired with its reveal style
+ *   blocks (reveal / conceal, each with a layout-preserved variant) compiled
+ *   against that marker.
+ * @position Internal to useContainerReveal.
+ *
+ * WHY A POOL OF LITERAL BLOCKS: `stylex.when.ancestor(':hover', marker)` is
+ * resolved by the StyleX compiler, which welds the marker's class into the
+ * emitted selector (`.marker:hover *`). A marker and the styles referencing it
+ * are therefore inseparable at build time — the marker cannot be passed as a
+ * runtime argument, so the blocks cannot be produced by a loop or a helper and
+ * must be written out literally per marker. A single shared marker would leak
+ * hover/focus across NESTED reveal containers (an ancestor container's :hover
+ * matches a descendant container's revealed content), so useContainerReveal
+ * hands each concurrently mounted container a distinct marker from this pool
+ * (see the free-list there).
+ *
+ * The reveal recipe hides content with `position: absolute` (removed from
+ * layout flow, so it reserves no space) plus `opacity: 0`. Both keep the
+ * content in the accessibility tree and tab order — unlike display/visibility
+ * — so it stays reachable by keyboard and assistive tech while hidden.
+ */
+
+import * as stylex from '@stylexjs/stylex';
+import {durationVars, easeVars} from '../theme/tokens.stylex';
+
+export const POOL_SIZE = 6;
+
+export const m0 = stylex.defineMarker();
+const s0 = stylex.create({
+  // Hidden at rest via position + opacity (kept in the a11y tree and tab
+  // order); on container :hover (fine pointer) or :focus-within it returns to
+  // flow and fades in. Always shown on touch.
+  reveal: {
+    transitionProperty: 'opacity',
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
+    opacity: {
+      default: 0,
+      [stylex.when.ancestor(':hover', m0)]: {'@media (hover: hover)': 1},
+      [stylex.when.ancestor(':focus-within', m0)]: 1,
+      '@media (any-pointer: coarse)': 1,
+    },
+    position: {
+      default: 'absolute',
+      [stylex.when.ancestor(':hover', m0)]: {'@media (hover: hover)': 'static'},
+      [stylex.when.ancestor(':focus-within', m0)]: 'static',
+      '@media (any-pointer: coarse)': 'static',
+    },
+  },
+  // Opacity-only reveal that keeps the box reserved (no layout shift). Use for
+  // content that is already positioned (e.g. an absolute overlay).
+  revealLayoutPreserved: {
+    transitionProperty: 'opacity',
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
+    opacity: {
+      default: 0,
+      [stylex.when.ancestor(':hover', m0)]: {'@media (hover: hover)': 1},
+      [stylex.when.ancestor(':focus-within', m0)]: 1,
+      '@media (any-pointer: coarse)': 1,
+    },
+  },
+  // Inverted: visible at rest, fades OUT on :hover only. Deliberately ignores
+  // :focus-within (a keyboard user must never watch content vanish) and stays
+  // visible on touch. Never leaves the a11y tree.
+  conceal: {
+    transitionProperty: 'opacity',
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
+    opacity: {
+      default: 1,
+      [stylex.when.ancestor(':hover', m0)]: {'@media (hover: hover)': 0},
+    },
+  },
+  concealLayoutPreserved: {
+    transitionProperty: 'opacity',
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
+    opacity: {
+      default: 1,
+      [stylex.when.ancestor(':hover', m0)]: {'@media (hover: hover)': 0},
+    },
+  },
+});
+
+export const m1 = stylex.defineMarker();
+const s1 = stylex.create({
+  // Hidden at rest via position + opacity (kept in the a11y tree and tab
+  // order); on container :hover (fine pointer) or :focus-within it returns to
+  // flow and fades in. Always shown on touch.
+  reveal: {
+    transitionProperty: 'opacity',
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
+    opacity: {
+      default: 0,
+      [stylex.when.ancestor(':hover', m1)]: {'@media (hover: hover)': 1},
+      [stylex.when.ancestor(':focus-within', m1)]: 1,
+      '@media (any-pointer: coarse)': 1,
+    },
+    position: {
+      default: 'absolute',
+      [stylex.when.ancestor(':hover', m1)]: {'@media (hover: hover)': 'static'},
+      [stylex.when.ancestor(':focus-within', m1)]: 'static',
+      '@media (any-pointer: coarse)': 'static',
+    },
+  },
+  // Opacity-only reveal that keeps the box reserved (no layout shift). Use for
+  // content that is already positioned (e.g. an absolute overlay).
+  revealLayoutPreserved: {
+    transitionProperty: 'opacity',
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
+    opacity: {
+      default: 0,
+      [stylex.when.ancestor(':hover', m1)]: {'@media (hover: hover)': 1},
+      [stylex.when.ancestor(':focus-within', m1)]: 1,
+      '@media (any-pointer: coarse)': 1,
+    },
+  },
+  // Inverted: visible at rest, fades OUT on :hover only. Deliberately ignores
+  // :focus-within (a keyboard user must never watch content vanish) and stays
+  // visible on touch. Never leaves the a11y tree.
+  conceal: {
+    transitionProperty: 'opacity',
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
+    opacity: {
+      default: 1,
+      [stylex.when.ancestor(':hover', m1)]: {'@media (hover: hover)': 0},
+    },
+  },
+  concealLayoutPreserved: {
+    transitionProperty: 'opacity',
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
+    opacity: {
+      default: 1,
+      [stylex.when.ancestor(':hover', m1)]: {'@media (hover: hover)': 0},
+    },
+  },
+});
+
+export const m2 = stylex.defineMarker();
+const s2 = stylex.create({
+  // Hidden at rest via position + opacity (kept in the a11y tree and tab
+  // order); on container :hover (fine pointer) or :focus-within it returns to
+  // flow and fades in. Always shown on touch.
+  reveal: {
+    transitionProperty: 'opacity',
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
+    opacity: {
+      default: 0,
+      [stylex.when.ancestor(':hover', m2)]: {'@media (hover: hover)': 1},
+      [stylex.when.ancestor(':focus-within', m2)]: 1,
+      '@media (any-pointer: coarse)': 1,
+    },
+    position: {
+      default: 'absolute',
+      [stylex.when.ancestor(':hover', m2)]: {'@media (hover: hover)': 'static'},
+      [stylex.when.ancestor(':focus-within', m2)]: 'static',
+      '@media (any-pointer: coarse)': 'static',
+    },
+  },
+  // Opacity-only reveal that keeps the box reserved (no layout shift). Use for
+  // content that is already positioned (e.g. an absolute overlay).
+  revealLayoutPreserved: {
+    transitionProperty: 'opacity',
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
+    opacity: {
+      default: 0,
+      [stylex.when.ancestor(':hover', m2)]: {'@media (hover: hover)': 1},
+      [stylex.when.ancestor(':focus-within', m2)]: 1,
+      '@media (any-pointer: coarse)': 1,
+    },
+  },
+  // Inverted: visible at rest, fades OUT on :hover only. Deliberately ignores
+  // :focus-within (a keyboard user must never watch content vanish) and stays
+  // visible on touch. Never leaves the a11y tree.
+  conceal: {
+    transitionProperty: 'opacity',
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
+    opacity: {
+      default: 1,
+      [stylex.when.ancestor(':hover', m2)]: {'@media (hover: hover)': 0},
+    },
+  },
+  concealLayoutPreserved: {
+    transitionProperty: 'opacity',
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
+    opacity: {
+      default: 1,
+      [stylex.when.ancestor(':hover', m2)]: {'@media (hover: hover)': 0},
+    },
+  },
+});
+
+export const m3 = stylex.defineMarker();
+const s3 = stylex.create({
+  // Hidden at rest via position + opacity (kept in the a11y tree and tab
+  // order); on container :hover (fine pointer) or :focus-within it returns to
+  // flow and fades in. Always shown on touch.
+  reveal: {
+    transitionProperty: 'opacity',
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
+    opacity: {
+      default: 0,
+      [stylex.when.ancestor(':hover', m3)]: {'@media (hover: hover)': 1},
+      [stylex.when.ancestor(':focus-within', m3)]: 1,
+      '@media (any-pointer: coarse)': 1,
+    },
+    position: {
+      default: 'absolute',
+      [stylex.when.ancestor(':hover', m3)]: {'@media (hover: hover)': 'static'},
+      [stylex.when.ancestor(':focus-within', m3)]: 'static',
+      '@media (any-pointer: coarse)': 'static',
+    },
+  },
+  // Opacity-only reveal that keeps the box reserved (no layout shift). Use for
+  // content that is already positioned (e.g. an absolute overlay).
+  revealLayoutPreserved: {
+    transitionProperty: 'opacity',
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
+    opacity: {
+      default: 0,
+      [stylex.when.ancestor(':hover', m3)]: {'@media (hover: hover)': 1},
+      [stylex.when.ancestor(':focus-within', m3)]: 1,
+      '@media (any-pointer: coarse)': 1,
+    },
+  },
+  // Inverted: visible at rest, fades OUT on :hover only. Deliberately ignores
+  // :focus-within (a keyboard user must never watch content vanish) and stays
+  // visible on touch. Never leaves the a11y tree.
+  conceal: {
+    transitionProperty: 'opacity',
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
+    opacity: {
+      default: 1,
+      [stylex.when.ancestor(':hover', m3)]: {'@media (hover: hover)': 0},
+    },
+  },
+  concealLayoutPreserved: {
+    transitionProperty: 'opacity',
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
+    opacity: {
+      default: 1,
+      [stylex.when.ancestor(':hover', m3)]: {'@media (hover: hover)': 0},
+    },
+  },
+});
+
+export const m4 = stylex.defineMarker();
+const s4 = stylex.create({
+  // Hidden at rest via position + opacity (kept in the a11y tree and tab
+  // order); on container :hover (fine pointer) or :focus-within it returns to
+  // flow and fades in. Always shown on touch.
+  reveal: {
+    transitionProperty: 'opacity',
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
+    opacity: {
+      default: 0,
+      [stylex.when.ancestor(':hover', m4)]: {'@media (hover: hover)': 1},
+      [stylex.when.ancestor(':focus-within', m4)]: 1,
+      '@media (any-pointer: coarse)': 1,
+    },
+    position: {
+      default: 'absolute',
+      [stylex.when.ancestor(':hover', m4)]: {'@media (hover: hover)': 'static'},
+      [stylex.when.ancestor(':focus-within', m4)]: 'static',
+      '@media (any-pointer: coarse)': 'static',
+    },
+  },
+  // Opacity-only reveal that keeps the box reserved (no layout shift). Use for
+  // content that is already positioned (e.g. an absolute overlay).
+  revealLayoutPreserved: {
+    transitionProperty: 'opacity',
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
+    opacity: {
+      default: 0,
+      [stylex.when.ancestor(':hover', m4)]: {'@media (hover: hover)': 1},
+      [stylex.when.ancestor(':focus-within', m4)]: 1,
+      '@media (any-pointer: coarse)': 1,
+    },
+  },
+  // Inverted: visible at rest, fades OUT on :hover only. Deliberately ignores
+  // :focus-within (a keyboard user must never watch content vanish) and stays
+  // visible on touch. Never leaves the a11y tree.
+  conceal: {
+    transitionProperty: 'opacity',
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
+    opacity: {
+      default: 1,
+      [stylex.when.ancestor(':hover', m4)]: {'@media (hover: hover)': 0},
+    },
+  },
+  concealLayoutPreserved: {
+    transitionProperty: 'opacity',
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
+    opacity: {
+      default: 1,
+      [stylex.when.ancestor(':hover', m4)]: {'@media (hover: hover)': 0},
+    },
+  },
+});
+
+export const m5 = stylex.defineMarker();
+const s5 = stylex.create({
+  // Hidden at rest via position + opacity (kept in the a11y tree and tab
+  // order); on container :hover (fine pointer) or :focus-within it returns to
+  // flow and fades in. Always shown on touch.
+  reveal: {
+    transitionProperty: 'opacity',
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
+    opacity: {
+      default: 0,
+      [stylex.when.ancestor(':hover', m5)]: {'@media (hover: hover)': 1},
+      [stylex.when.ancestor(':focus-within', m5)]: 1,
+      '@media (any-pointer: coarse)': 1,
+    },
+    position: {
+      default: 'absolute',
+      [stylex.when.ancestor(':hover', m5)]: {'@media (hover: hover)': 'static'},
+      [stylex.when.ancestor(':focus-within', m5)]: 'static',
+      '@media (any-pointer: coarse)': 'static',
+    },
+  },
+  // Opacity-only reveal that keeps the box reserved (no layout shift). Use for
+  // content that is already positioned (e.g. an absolute overlay).
+  revealLayoutPreserved: {
+    transitionProperty: 'opacity',
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
+    opacity: {
+      default: 0,
+      [stylex.when.ancestor(':hover', m5)]: {'@media (hover: hover)': 1},
+      [stylex.when.ancestor(':focus-within', m5)]: 1,
+      '@media (any-pointer: coarse)': 1,
+    },
+  },
+  // Inverted: visible at rest, fades OUT on :hover only. Deliberately ignores
+  // :focus-within (a keyboard user must never watch content vanish) and stays
+  // visible on touch. Never leaves the a11y tree.
+  conceal: {
+    transitionProperty: 'opacity',
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
+    opacity: {
+      default: 1,
+      [stylex.when.ancestor(':hover', m5)]: {'@media (hover: hover)': 0},
+    },
+  },
+  concealLayoutPreserved: {
+    transitionProperty: 'opacity',
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0s',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
+    opacity: {
+      default: 1,
+      [stylex.when.ancestor(':hover', m5)]: {'@media (hover: hover)': 0},
+    },
+  },
+});
+
+// The compiled StyleX objects carry `when.ancestor` conditionals the public
+// `StyleXStyles` type does not model, so the slot shape is inferred.
+export const POOL = [
+  {marker: m0, reveal: s0.reveal, revealLayoutPreserved: s0.revealLayoutPreserved, conceal: s0.conceal, concealLayoutPreserved: s0.concealLayoutPreserved},
+  {marker: m1, reveal: s1.reveal, revealLayoutPreserved: s1.revealLayoutPreserved, conceal: s1.conceal, concealLayoutPreserved: s1.concealLayoutPreserved},
+  {marker: m2, reveal: s2.reveal, revealLayoutPreserved: s2.revealLayoutPreserved, conceal: s2.conceal, concealLayoutPreserved: s2.concealLayoutPreserved},
+  {marker: m3, reveal: s3.reveal, revealLayoutPreserved: s3.revealLayoutPreserved, conceal: s3.conceal, concealLayoutPreserved: s3.concealLayoutPreserved},
+  {marker: m4, reveal: s4.reveal, revealLayoutPreserved: s4.revealLayoutPreserved, conceal: s4.conceal, concealLayoutPreserved: s4.concealLayoutPreserved},
+  {marker: m5, reveal: s5.reveal, revealLayoutPreserved: s5.revealLayoutPreserved, conceal: s5.conceal, concealLayoutPreserved: s5.concealLayoutPreserved},
+] as const;
+
+export type RevealSlot = (typeof POOL)[number];

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,
@@ -86,3 +92,10 @@ export {useLongPress} from './useLongPress';
 export type {UseLongPressOptions, UseLongPressHandlers} from './useLongPress';
 
 export {useDevWarning} from './useDevWarning';
+
+export {useContainerReveal} from './useContainerReveal';
+export type {
+  UseContainerRevealOptions,
+  UseContainerRevealReturn,
+  ContentRevealOptions,
+} from './useContainerReveal';

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');