@astryxdesign/core 0.2.0 → 0.3.0

package/src/Timestamp/TimestampHoverCard.tsx

@@ -0,0 +1,283 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file TimestampHoverCard.tsx
+ * @input Uses React, HoverCard, IconButton, Icon, formatted lines
+ * @output Default-exports the lazily-loaded copyable hover card for Timestamp
+ * @position Split out of Timestamp so the overlay (HoverCard) and the copy
+ *   affordance's Icon/IconButton load only when a card is actually shown — the
+ *   default, card-less Timestamp never bundles this chunk.
+ *
+ * Layout: a semantic `<dl>` laid out as a grid. Labelled cards use three
+ *   columns — label, value, and a trailing action column for copy buttons —
+ *   so the buttons align down a single column no matter how wide each value
+ *   is. The action column is only added when at least one row is copyable, so
+ *   a fully read-only card carries no dangling gutter. Label-less cards drop
+ *   the label column and stack to whatever columns remain.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/Timestamp/Timestamp.tsx (the lazy() + Suspense wrapper)
+ * - /packages/core/src/Timestamp/Timestamp.doc.mjs (theming.targets)
+ * - /packages/core/src/Timestamp/Timestamp.test.tsx
+ */
+
+import type {ReactNode} from 'react';
+import {useCallback, useEffect, useRef, useState} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {HoverCard} from '../HoverCard';
+import {IconButton} from '../IconButton';
+import {Icon} from '../Icon';
+import {useAnnounce} from '../hooks/useAnnounce';
+import {useTranslator} from '../i18n';
+import {themeProps} from '../utils/themeProps';
+import {
+  colorVars,
+  spacingVars,
+  typeScaleVars,
+  fontWeightVars,
+} from '../theme/tokens.stylex';
+import type {TimestampTooltipLine} from './tooltipEntries';
+
+const styles = stylex.create({
+  // The card is a definition list laid out as a grid so cells align into
+  // columns across rows. `gridTemplateColumns` is set per-card (below) to add
+  // or drop the label and action columns; the row/column gaps live here.
+  dl: {
+    display: 'grid',
+    alignItems: 'center',
+    columnGap: spacingVars['--spacing-4'],
+    rowGap: spacingVars['--spacing-2'],
+    margin: 0,
+    padding: 0,
+  },
+  // Each row spans the full grid so its cells land in the shared columns.
+  // `display: contents` lets the <dt>/<dd> participate directly in the grid.
+  row: {
+    display: 'contents',
+  },
+  // Label: the design system's `supporting` role — secondary colour, the
+  // supporting size/leading, normal weight. This matches Timestamp's own
+  // default `type` ('supporting'), so the card's labels read at the same
+  // register as the component itself.
+  label: {
+    color: colorVars['--color-text-secondary'],
+    fontSize: typeScaleVars['--text-supporting-size'],
+    lineHeight: typeScaleVars['--text-supporting-leading'],
+    fontWeight: fontWeightVars['--font-weight-normal'],
+    margin: 0,
+    padding: 0,
+    whiteSpace: 'nowrap',
+  },
+  // Value: the `body` role — primary colour, body size/leading, normal weight.
+  value: {
+    color: colorVars['--color-text-primary'],
+    fontSize: typeScaleVars['--text-body-size'],
+    lineHeight: typeScaleVars['--text-body-leading'],
+    fontWeight: fontWeightVars['--font-weight-normal'],
+    margin: 0,
+    padding: 0,
+    whiteSpace: 'nowrap',
+  },
+  // The trailing action cell holds the copy button (or nothing, on a
+  // read-only row). It lives in its own grid column so buttons align.
+  action: {
+    display: 'flex',
+    justifyContent: 'flex-end',
+    alignItems: 'center',
+  },
+});
+
+// Grid templates, selected per-card by which columns are present.
+// - hasAnyLabel + hasAnyCopyable → label | value | action
+// - hasAnyLabel only             → label | value
+// - hasAnyCopyable only          → value | action
+// - neither                      → value
+const gridTemplates = stylex.create({
+  labelValueAction: {gridTemplateColumns: 'auto 1fr auto'},
+  labelValue: {gridTemplateColumns: 'auto 1fr'},
+  valueAction: {gridTemplateColumns: '1fr auto'},
+  value: {gridTemplateColumns: '1fr'},
+});
+
+/** How long the copied checkmark stays before reverting to the copy icon. */
+const COPY_FEEDBACK_MS = 1500;
+
+/**
+ * The per-row copy affordance: a compact ghost `IconButton` that writes the
+ * row's value to the clipboard, flips `copy` → `check` for a moment, and
+ * announces the copy to a polite live region (a swapped aria-label alone
+ * isn't reliably announced). A clipboard rejection is a silent no-op.
+ *
+ * Kept as its own component so its state/timer/effect only exist for rows that
+ * actually opt into copying — read-only rows render no button and carry none
+ * of this machinery.
+ */
+function CopyButton({value}: {value: string}) {
+  const t = useTranslator();
+  const announce = useAnnounce();
+  const [copied, setCopied] = useState(false);
+  const resetTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(() => {
+    return () => {
+      if (resetTimerRef.current != null) {
+        clearTimeout(resetTimerRef.current);
+      }
+    };
+  }, []);
+
+  const handleCopy = useCallback(async () => {
+    try {
+      await navigator.clipboard.writeText(value);
+      setCopied(true);
+      announce(t('@astryx.timestamp.copied'));
+      // Restart the reset timer on every copy so a rapid re-copy isn't
+      // reverted early by the previous click's timer.
+      if (resetTimerRef.current != null) {
+        clearTimeout(resetTimerRef.current);
+      }
+      resetTimerRef.current = setTimeout(() => {
+        resetTimerRef.current = null;
+        setCopied(false);
+      }, COPY_FEEDBACK_MS);
+    } catch {
+      // Clipboard failures leave the copied state unchanged.
+    }
+  }, [value, announce, t]);
+
+  return (
+    <IconButton
+      variant="ghost"
+      size="sm"
+      icon={<Icon icon={copied ? 'check' : 'copy'} size="sm" color="inherit" />}
+      // Visible hover/focus hint via Button's built-in tooltip: 'Copy',
+      // flipping to 'Copied' after a successful copy in step with the icon.
+      // The full 'Copy <value>' string stays the aria-label for assistive tech.
+      tooltip={t(
+        copied ? '@astryx.timestamp.copied' : '@astryx.timestamp.copy',
+      )}
+      label={
+        copied
+          ? t('@astryx.timestamp.copied')
+          : t('@astryx.timestamp.copyValue', {value})
+      }
+      onClick={() => {
+        void handleCopy();
+      }}
+      {...themeProps('timestamp-copy-button')}
+    />
+  );
+}
+
+/**
+ * One row of the hover card: an optional label, the formatted instant, and —
+ * when the card reserves an action column — a trailing action cell holding the
+ * copy button (for a copyable row) or nothing (for a read-only row, so the
+ * columns stay aligned). Pure presentation: the copy state lives in
+ * {@link CopyButton}, which only copyable rows render.
+ */
+function EntryRow({
+  line,
+  hasLabelColumn,
+  hasActionColumn,
+}: {
+  line: TimestampTooltipLine;
+  hasLabelColumn: boolean;
+  hasActionColumn: boolean;
+}) {
+  return (
+    <div {...stylex.props(styles.row)}>
+      {hasLabelColumn && (
+        <dt {...stylex.props(styles.label)}>{line.label ?? ''}</dt>
+      )}
+      <dd {...stylex.props(styles.value)}>{line.value}</dd>
+      {hasActionColumn && (
+        <div {...stylex.props(styles.action)}>
+          {line.isCopyable && <CopyButton value={line.value} />}
+        </div>
+      )}
+    </div>
+  );
+}
+
+export interface TimestampHoverCardProps {
+  /** The rows to render, each a labelled instant, optionally copyable. */
+  lines: ReadonlyArray<TimestampTooltipLine>;
+  /** Accessible name for the card. */
+  label: string;
+  /** The anchor the card is attached to (the `<time>` element). */
+  children: ReactNode;
+}
+
+function gridTemplateFor(
+  hasLabelColumn: boolean,
+  hasActionColumn: boolean,
+): stylex.StyleXStyles {
+  if (hasLabelColumn && hasActionColumn) {
+    return gridTemplates.labelValueAction;
+  }
+  if (hasLabelColumn) {
+    return gridTemplates.labelValue;
+  }
+  if (hasActionColumn) {
+    return gridTemplates.valueAction;
+  }
+  return gridTemplates.value;
+}
+
+/**
+ * The copyable hover card for Timestamp. Renders a semantic `<dl>` as a grid:
+ * an optional label column, the value, and — when any row is copyable — a
+ * trailing action column carrying that row's copy button, so buttons align
+ * down one column. With a single default line this is a one-row card carrying
+ * the full absolute time, copyable. Opens on hover and on keyboard focus (the
+ * anchor's tab stop), with a dashed-underline affordance signalling it is
+ * interactive.
+ */
+export default function TimestampHoverCard({
+  lines,
+  label,
+  children,
+}: TimestampHoverCardProps): ReactNode {
+  // A label column is only reserved when some row is labelled; otherwise the
+  // value sits flush at the card's leading edge. An action column is only
+  // reserved when some row is copyable (option B), so a fully read-only card
+  // has no trailing gutter.
+  const hasLabelColumn = lines.some(
+    line => line.label != null && line.label !== '',
+  );
+  const hasActionColumn = lines.some(line => line.isCopyable);
+
+  const cardContent = (
+    <dl
+      {...stylex.props(
+        styles.dl,
+        gridTemplateFor(hasLabelColumn, hasActionColumn),
+      )}>
+      {lines.map((line, index) => (
+        <EntryRow
+          // eslint-disable-next-line @eslint-react/no-array-index-key -- rows are fixed positional slots and two entries may legitimately be identical
+          key={index}
+          line={line}
+          hasLabelColumn={hasLabelColumn}
+          hasActionColumn={hasActionColumn}
+        />
+      ))}
+    </dl>
+  );
+
+  return (
+    <HoverCard
+      content={cardContent}
+      placement="above"
+      focusTrigger="always"
+      hasHoverIndication
+      label={label}>
+      {children}
+    </HoverCard>
+  );
+}
+
+TimestampHoverCard.displayName = 'TimestampHoverCard';

package/src/Timestamp/formatInstant.ts

@@ -41,12 +41,11 @@ import type {TimestampFormat} from './Timestamp';
  * style ("February 19, 2026 at 5:00:00 PM UTC") that backs a relative
  * timestamp's accessible name and the tooltip's default line.
  *
- * `'relative'` and `'auto'` are excluded: a relative phrase names no instant,
- * so a zone could not change what it says.
+ * `'relative'`, `'relative_short'`, and `'auto'` are excluded: a relative
+ * phrase names no instant, so a zone could not change what it says.
  */
 export type InstantFormat =
-  | Exclude<TimestampFormat, 'relative' | 'auto'>
-  | 'full';
+  Exclude<TimestampFormat, 'relative' | 'relative_short' | 'auto'> | 'full';
 
 export interface FormatInstantOptions {
   /**
@@ -214,5 +213,11 @@ export function formatInstant(
       const w = getWallClock(date, timeZone);
       return `${pad(w.hour)}:${pad(w.minute)}:${pad(w.second)}`;
     }
+
+    case 'unix_seconds':
+      // Unix time in whole seconds since the epoch. The epoch is an absolute
+      // instant, so this is zone-independent — `timeZone` is intentionally
+      // ignored (a wall-clock zone can't change how many seconds have elapsed).
+      return String(Math.floor(date.getTime() / 1000));
   }
 }

package/src/Timestamp/tooltipEntries.test.ts

@@ -512,6 +512,15 @@ describe('formatTooltipLines', () => {
     expect(line.label).toBe('');
   });
 
+  it('marks lines read-only by default and copyable only when opted in', () => {
+    const lines = formatTooltipLines(INSTANT, [
+      {label: 'Local'},
+      {label: 'ISO', format: 'system_date_time', isCopyable: true},
+      {label: 'Off', isCopyable: false},
+    ]);
+    expect(lines.map(l => l.isCopyable)).toEqual([false, true, false]);
+  });
+
   // --- Ordering and arity ---
 
   it('preserves entry order', () => {

package/src/Timestamp/tooltipEntries.ts

@@ -34,8 +34,9 @@ import type {InstantFormat} from './formatInstant';
  *
  * Every `TimestampFormat` that names a fixed instant, plus `'full'` — the long
  * absolute style the tooltip has always shown ("February 19, 2026 at 5:00:00 PM
- * UTC"). `'relative'` and `'auto'` are excluded: a relative phrase ignores any
- * zone, which would make `timezoneID` silently inert on that line.
+ * UTC"). `'relative'`, `'relative_short'`, and `'auto'` are excluded: a
+ * relative phrase ignores any zone, which would make `timezoneID` silently
+ * inert on that line.
  *
  * `'full'` lives only in this vocabulary, never in `TimestampFormat` — nothing
  * asked for it as a visible display format, and keeping it out means new
@@ -71,12 +72,26 @@ export interface TimestampTooltipEntry {
    * Supplied already translated; Timestamp never invents or localizes labels.
    */
   label?: string;
+  /**
+   * Whether this row shows a copy-to-clipboard button, rendered in a dedicated
+   * trailing action column so the buttons line up across rows regardless of
+   * each value's width. The action column is only reserved when at least one
+   * row is copyable, so a fully read-only card has no trailing gutter.
+   *
+   * Defaults to `false` — rows are read-only unless opted in. Set `true` for a
+   * row whose value is worth pasting elsewhere, such as a machine-readable
+   * `system_date_time` value shown beside human-readable zones that only need
+   * to be read.
+   * @default false
+   */
+  isCopyable?: boolean;
 }
 
 /** A rendered tooltip line. */
 export interface TimestampTooltipLine {
   label?: string;
   value: string;
+  isCopyable: boolean;
 }
 
 // =============================================================================
@@ -197,6 +212,7 @@ export function formatTooltipLines(
 
     return {
       ...(entry.label === undefined ? {} : {label: entry.label}),
+      isCopyable: entry.isCopyable ?? false,
       value: formatInstant(date, format, {
         timeZone,
         isTimezoneShown: shouldShowZoneName(

package/src/Toast/Toast.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'Toast',
@@ -92,7 +92,7 @@ export const docs = {
 // See .context/decisions/dense-compression-protocol.md
 // -------------------------------------------------------
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsZh = {
   propDescriptions: {
     body: '主要消息内容。',
@@ -124,7 +124,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'toast notification w/ auto-dismiss, stacking, dedup, smooth animations; MediaTheme inverted surface',

package/src/Toast/ToastViewport.test.tsx

@@ -3,19 +3,56 @@
 /**
  * @file ToastViewport.test.tsx
  * @input Uses vitest, @testing-library/react, ToastViewport + useToast
- * @output Unit tests for toast keyboard reach and focus management
- * @position Testing; validates ToastViewport.tsx + Toast.tsx focus behavior
+ * @output Unit tests for toast keyboard reach, focus management, and
+ *   screen-reader announcements
+ * @position Testing; validates ToastViewport.tsx + Toast.tsx focus behavior and
+ *   the announce-at-dispatch flow through the singleton live regions
  *
- * SYNC: When ToastViewport.tsx or Toast.tsx focus handling changes, update these tests
+ * SYNC: When ToastViewport.tsx / Toast.tsx focus handling or the toast
+ *   announcement flow changes, update these tests
  */
 
-import {describe, it, expect, vi, beforeAll} from 'vitest';
-import {render, screen, fireEvent, act} from '@testing-library/react';
+import {describe, it, expect, vi, beforeAll, afterEach} from 'vitest';
+import {
+  render,
+  screen,
+  fireEvent,
+  act,
+  waitFor,
+  within,
+} from '@testing-library/react';
 import React from 'react';
+import {type AnnounceFn, __resetLiveRegionsForTest} from '../hooks/useAnnounce';
 import {ToastViewport} from './ToastViewport';
 import {useToast} from './useToast';
 import type {ToastOptions} from './types';
 
+// Spy on the announcement sink so tests can prove a toast is announced exactly
+// once. The mock wraps the real useAnnounce, so the singleton live regions are
+// still populated (the region-content assertions below depend on it) while
+// every call is also recorded on announceSpy.
+const {announceSpy} = vi.hoisted(() => ({announceSpy: vi.fn()}));
+vi.mock('../hooks/useAnnounce', async importActual => {
+  const actual = await importActual<{
+    useAnnounce: () => AnnounceFn;
+    __resetLiveRegionsForTest: () => void;
+  }>();
+  const {useCallback} = await import('react');
+  return {
+    ...actual,
+    useAnnounce: (): AnnounceFn => {
+      const realAnnounce = actual.useAnnounce();
+      return useCallback<AnnounceFn>(
+        (message, politeness) => {
+          announceSpy(message, politeness);
+          realAnnounce(message, politeness);
+        },
+        [realAnnounce],
+      );
+    },
+  };
+});
+
 // Popover API is not implemented in jsdom.
 beforeAll(() => {
   if (typeof HTMLElement.prototype.showPopover === 'undefined') {
@@ -24,6 +61,13 @@ beforeAll(() => {
   }
 });
 
+// Toast text is mirrored into the singleton live regions, which outlive each
+// render — reset them so text from one test never leaks into the next.
+afterEach(() => {
+  __resetLiveRegionsForTest();
+  announceSpy.mockClear();
+});
+
 // Module-level constant default props (avoids unstable-default-props lint).
 const EMPTY_OPTIONS: ToastOptions = {body: 'placeholder'};
 
@@ -169,7 +213,10 @@ describe('Toast blur timer pause', () => {
       act(() => {
         fireEvent.click(screen.getByText('Trigger Auto'));
       });
-      expect(screen.getByText('Auto toast')).toBeInTheDocument();
+      // Scope to the viewport: the toast text is also mirrored into the
+      // singleton live region, which lives outside the notifications region.
+      const viewport = screen.getByRole('region', {name: 'Notifications'});
+      expect(within(viewport).getByText('Auto toast')).toBeInTheDocument();
 
       // Window loses focus — timer should pause.
       act(() => {
@@ -179,7 +226,7 @@ describe('Toast blur timer pause', () => {
         vi.advanceTimersByTime(5000);
       });
       // Still present because the timer was paused while blurred.
-      expect(screen.getByText('Auto toast')).toBeInTheDocument();
+      expect(within(viewport).getByText('Auto toast')).toBeInTheDocument();
 
       // Window regains focus — timer resumes and the toast dismisses.
       act(() => {
@@ -196,7 +243,9 @@ describe('Toast blur timer pause', () => {
           completeExit(toastId);
         });
       }
-      expect(screen.queryByText('Auto toast')).not.toBeInTheDocument();
+      expect(
+        within(viewport).queryByText('Auto toast'),
+      ).not.toBeInTheDocument();
     } finally {
       vi.useRealTimers();
     }
@@ -213,6 +262,167 @@ describe('ToastViewport region ARIA', () => {
   });
 });
 
+describe('toast announcements via singleton live regions', () => {
+  function politeRegion(): HTMLElement | null {
+    return document.querySelector('[data-astryx-live-region="polite"]');
+  }
+  function assertiveRegion(): HTMLElement | null {
+    return document.querySelector('[data-astryx-live-region="assertive"]');
+  }
+
+  const RICH_INFO: ToastOptions = {
+    body: (
+      <>
+        <strong>Update ready</strong>
+        <div>Restart to apply</div>
+      </>
+    ),
+  };
+  const ERROR_TOAST: ToastOptions = {body: 'Upload failed', type: 'error'};
+  const SAVING_V1: ToastOptions = {uniqueID: 'save', body: 'Saving changes'};
+  const SAVING_V2: ToastOptions = {uniqueID: 'save', body: 'Changes saved'};
+  const IGNORE_KEPT: ToastOptions = {
+    uniqueID: 'dup',
+    collisionBehavior: 'ignore',
+    body: 'Kept',
+  };
+  const IGNORE_DROPPED: ToastOptions = {
+    uniqueID: 'dup',
+    collisionBehavior: 'ignore',
+    body: 'Dropped',
+  };
+
+  it('announces an info toast politely with its flattened text content', async () => {
+    renderViewport(<ShowToastButton options={RICH_INFO} triggerLabel="Show" />);
+    act(() => {
+      fireEvent.click(screen.getByText('Show'));
+    });
+    // Announced synchronously at dispatch, exactly once.
+    expect(announceSpy).toHaveBeenCalledTimes(1);
+    expect(announceSpy).toHaveBeenCalledWith(
+      'Update ready Restart to apply',
+      'polite',
+    );
+    // The flattened text reaches the polite singleton region (the sink).
+    await waitFor(() => {
+      expect(politeRegion()).toHaveTextContent('Update ready Restart to apply');
+    });
+    // Status toasts never touch the assertive region.
+    expect(assertiveRegion()).toHaveTextContent('');
+  });
+
+  it('announces an error toast assertively', async () => {
+    renderViewport(
+      <ShowToastButton options={ERROR_TOAST} triggerLabel="Show" />,
+    );
+    act(() => {
+      fireEvent.click(screen.getByText('Show'));
+    });
+    expect(announceSpy).toHaveBeenCalledTimes(1);
+    expect(announceSpy).toHaveBeenCalledWith('Upload failed', 'assertive');
+    await waitFor(() => {
+      expect(assertiveRegion()).toHaveTextContent('Upload failed');
+    });
+    expect(politeRegion()).toHaveTextContent('');
+  });
+
+  it('announces exactly once at dispatch, even under StrictMode', () => {
+    render(
+      <React.StrictMode>
+        <ToastViewport isTopLayer={false}>
+          <ShowToastButton options={INFO_A} triggerLabel="Show" />
+        </ToastViewport>
+      </React.StrictMode>,
+    );
+    act(() => {
+      fireEvent.click(screen.getByText('Show'));
+    });
+    // The announcement lives in the imperative dispatch path (addToast), not a
+    // render effect, so StrictMode's double render and double-invoked state
+    // updater cannot announce the same toast twice.
+    expect(announceSpy).toHaveBeenCalledTimes(1);
+    expect(announceSpy).toHaveBeenCalledWith('Toast A', 'polite');
+  });
+
+  it('re-announces a uniqueID toast when its content is overwritten', async () => {
+    renderViewport(
+      <>
+        <ShowToastButton options={SAVING_V1} triggerLabel="Show v1" />
+        <ShowToastButton options={SAVING_V2} triggerLabel="Show v2" />
+      </>,
+    );
+    act(() => {
+      fireEvent.click(screen.getByText('Show v1'));
+    });
+    expect(announceSpy).toHaveBeenCalledTimes(1);
+    expect(announceSpy).toHaveBeenLastCalledWith('Saving changes', 'polite');
+    // Overwriting via uniqueID replaces the toast in place — the new content is
+    // a fresh dispatch and must be announced again.
+    act(() => {
+      fireEvent.click(screen.getByText('Show v2'));
+    });
+    expect(announceSpy).toHaveBeenCalledTimes(2);
+    expect(announceSpy).toHaveBeenLastCalledWith('Changes saved', 'polite');
+    await waitFor(() => {
+      expect(politeRegion()).toHaveTextContent('Changes saved');
+    });
+    // Still a single toast on screen — overwritten in place, not stacked.
+    const viewport = screen.getByRole('region', {name: 'Notifications'});
+    expect(
+      within(viewport).queryAllByText(/Saving changes|Changes saved/),
+    ).toHaveLength(1);
+  });
+
+  it('does not re-announce an unchanged toast when an unrelated render occurs', () => {
+    renderViewport(
+      <>
+        <ShowToastButton options={INFO_A} triggerLabel="Show A" />
+        <ShowToastButton options={ERROR_TOAST} triggerLabel="Show B" />
+      </>,
+    );
+    act(() => {
+      fireEvent.click(screen.getByText('Show A'));
+    });
+    expect(announceSpy).toHaveBeenCalledTimes(1);
+    // A second toast arriving re-renders the viewport with a new toast list.
+    // Toast A is not re-dispatched, so it must not be announced again — only
+    // the newly dispatched toast produces a call.
+    act(() => {
+      fireEvent.click(screen.getByText('Show B'));
+    });
+    expect(announceSpy).toHaveBeenCalledTimes(2);
+    expect(announceSpy).toHaveBeenNthCalledWith(1, 'Toast A', 'polite');
+    expect(announceSpy).toHaveBeenNthCalledWith(
+      2,
+      'Upload failed',
+      'assertive',
+    );
+  });
+
+  it('does not announce a toast whose uniqueID collision is ignored', () => {
+    renderViewport(
+      <>
+        <ShowToastButton options={IGNORE_KEPT} triggerLabel="Show 1" />
+        <ShowToastButton options={IGNORE_DROPPED} triggerLabel="Show 2" />
+      </>,
+    );
+    act(() => {
+      fireEvent.click(screen.getByText('Show 1'));
+    });
+    expect(announceSpy).toHaveBeenCalledTimes(1);
+    expect(announceSpy).toHaveBeenLastCalledWith('Kept', 'polite');
+    // The colliding toast is suppressed (collisionBehavior: 'ignore'), so it is
+    // neither shown nor announced.
+    act(() => {
+      fireEvent.click(screen.getByText('Show 2'));
+    });
+    expect(announceSpy).toHaveBeenCalledTimes(1);
+    const viewport = screen.getByRole('region', {name: 'Notifications'});
+    expect(within(viewport).getByText('Kept')).toBeInTheDocument();
+    expect(within(viewport).queryByText('Dropped')).not.toBeInTheDocument();
+  });
+});
+
 describe('toast timer lifecycle (#3589)', () => {
   it('fires onHide exactly once when dismissed twice during the exit window', () => {
     const onHide = vi.fn();