@astryxdesign/core 0.7.7-canary.c0929c8 → 0.7.7-canary.c19ca12

package/src/Table/BaseTable.tsx

@@ -14,7 +14,14 @@
  * - /packages/cli/assets/templates/blocks/components/Table/ (showcase blocks)
  */
 
-import {memo, useRef, type ReactElement, type ReactNode, type Ref} from 'react';
+import {
+  memo,
+  useId,
+  useRef,
+  type ReactElement,
+  type ReactNode,
+  type Ref,
+} from 'react';
 import {isRenderable} from '../utils/isRenderable';
 import * as stylex from '@stylexjs/stylex';
 import {spacingVars} from '../theme/tokens.stylex';
@@ -423,6 +430,7 @@ function BaseTableInner<T extends Record<string, unknown>>({
   } satisfies TableRenderProps);
 
   // --- Plugin pipeline: header cells ---
+  const headerLabelIdBase = useId();
   const headerCells = resolvedColumns.map((col, columnIndex) => {
     const headerContent = col.header ?? col.key;
 
@@ -477,28 +485,54 @@ function BaseTableInner<T extends Record<string, unknown>>({
     const hasSlots =
       before != null || after != null || overlay != null || below != null;
 
-    const headerInner = hasSlots ? (
+    const labelRow = isRenderable(after) ? (
+      <div {...stylex.props(styles.headerLabelRow)}>
+        {resolvedContent}
+        {after}
+      </div>
+    ) : (
+      resolvedContent
+    );
+
+    // The overlay is a control of its own. Keep its name and value out of the
+    // header's name.
+    const namesOwnHeader =
+      isRenderable(overlay) &&
+      mergedHtmlProps['aria-label'] == null &&
+      mergedHtmlProps['aria-labelledby'] == null;
+    const labelId = `${headerLabelIdBase}-label-${columnIndex}`;
+    const belowId = `${headerLabelIdBase}-below-${columnIndex}`;
+    const hasBelow = isRenderable(below);
+
+    const headerInner = !hasSlots ? (
+      resolvedContent
+    ) : namesOwnHeader ? (
+      <>
+        {/* Inline, so the cell's text-overflow still reaches the label. */}
+        <span id={labelId}>
+          {before}
+          {labelRow}
+        </span>
+        {overlay}
+        {hasBelow && <div id={belowId}>{below}</div>}
+      </>
+    ) : (
       <>
         {before}
-        {isRenderable(after) ? (
-          <div {...stylex.props(styles.headerLabelRow)}>
-            {resolvedContent}
-            {after}
-          </div>
-        ) : (
-          resolvedContent
-        )}
+        {labelRow}
         {overlay}
         {below}
       </>
-    ) : (
-      resolvedContent
     );
+    const headerNameProps = namesOwnHeader
+      ? {'aria-labelledby': hasBelow ? `${labelId} ${belowId}` : labelId}
+      : {};
 
     return (
       <HeaderCellComponent
         key={col.key}
         {...mergedHtmlProps}
+        {...headerNameProps}
         {...headerTitleProp}
         contextMenuActions={cellRenderProps.contextMenuActions}
         xstyle={cellRenderProps.xstyle}>

package/src/TextInput/TextInput.tsx

@@ -35,21 +35,22 @@ import {
   typographyVars,
   typeScaleVars,
 } from '../theme/tokens.stylex';
+import {Field} from '../Field/Field';
+import {InputClearButton} from '../Field/InputClearButton';
 import {
-  Field,
-  InputClearButton,
-  type InputStatus,
   inputWrapperStyles,
   inputStatusBorderStyles,
   inputStatusHoverShadowStyles,
   inputStatusFocusWithinStyles,
-} from '../Field';
-import {renderIconSlot, type IconType} from '../Icon';
+} from '../Field/inputStyles.stylex';
+import type {InputStatus} from '../Field/types';
+import {renderIconSlot, type IconType} from '../Icon/Icon';
 import {isRenderable} from '../utils/isRenderable';
-import {Spinner} from '../Spinner';
-import {useTooltip} from '../Tooltip';
-import {VisuallyHidden} from '../VisuallyHidden';
-import {getInputARIA, isImeKeyEvent} from '../utils';
+import {Spinner} from '../Spinner/Spinner';
+import {useTooltip} from '../Tooltip/useTooltip';
+import {VisuallyHidden} from '../VisuallyHidden/VisuallyHidden';
+import {getInputARIA} from '../utils/inputAria';
+import {isImeKeyEvent} from '../utils/ime';
 import {
   textEntryTraitAttributes,
   type TextEntryTraitProps,
@@ -109,7 +110,7 @@ export type {
   InputStatus as TextInputStatus,
   InputStatusType as TextInputStatusType,
 } from '../Field';
-import {mergeProps} from '../utils';
+import {mergeProps} from '../utils/mergeProps';
 import {useSize} from '../SizeContext/SizeContext';
 import {useInputContainer} from '../hooks/useInputContainer';
 import {useInputStatusIcon} from '../hooks/useInputStatusIcon';

package/src/Toast/Toast.doc.mjs

@@ -89,7 +89,7 @@ export const docs = {
       name: 'renderContent',
       type: '(toast: ToastContentRenderProps) => ReactNode',
       description:
-        "Replaces the content of this toast's card with your own layout. Astryx keeps the card, its astryx-toast theme target, the live-region role and auto-hide behavior, then hands the renderer the message, endContent, resolved toast settings and a dismiss callback. The custom renderer owns every control in its layout: compose the control you want and call dismiss from it. Astryx does not inject a fallback close into custom content. Per-toast: an app shares one layout by wrapping useToast and passing it on every call, while a toast raised by library code that never passes it renders as an ordinary Astryx toast. The argument is {body, endContent, type, isAutoHide, autoHideDuration, dismiss}, where type is 'info' | 'error'.",
+        "Replaces the content of this toast's card with your own layout. Astryx keeps the card, its astryx-toast theme target and auto-hide behavior (inside a ToastViewport the viewport announces the toast, and while a modal hosts the viewport the card announces itself), then hands the renderer the message, endContent, resolved toast settings and a dismiss callback. The custom renderer owns every control in its layout: compose the control you want and call dismiss from it. Astryx does not inject a fallback close into custom content. Per-toast: an app shares one layout by wrapping useToast and passing it on every call, while a toast raised by library code that never passes it renders as an ordinary Astryx toast. The argument is {body, endContent, type, isAutoHide, autoHideDuration, dismiss}, where type is 'info' | 'error'.",
     },
   ],
   theming: {
@@ -211,7 +211,7 @@ export const docsZh = {
     collisionBehavior: '当已存在相同 uniqueID 的 toast 时的行为。',
     onHide: '当 toast 被移除时触发的回调。',
     renderContent:
-      "用你自己的布局替换该 toast 卡片内部的内容。Astryx 保留卡片本身、astryx-toast 主题目标、实时区域角色和自动关闭行为，并把消息、endContent、解析后的 toast 设置和 dismiss 回调交给渲染函数。自定义渲染函数完全拥有布局中的控件：请组合所需的控件并通过它调用 dismiss。Astryx 不会向自定义内容注入后备关闭按钮。按 toast 单独设置：应用可通过封装 useToast 并在每次调用时传入来共享同一套布局；而由库代码发起、从不传入该参数的 toast 会渲染为普通的 Astryx toast。传入参数为 {body, endContent, type, isAutoHide, autoHideDuration, dismiss}，其中 type 为 'info' | 'error'。",
+      "用你自己的布局替换该 toast 卡片内部的内容。Astryx 保留卡片本身、astryx-toast 主题目标和自动关闭行为（在 ToastViewport 中由视口播报该 toast；当模态框承载视口时由卡片自行播报），并把消息、endContent、解析后的 toast 设置和 dismiss 回调交给渲染函数。自定义渲染函数完全拥有布局中的控件：请组合所需的控件并通过它调用 dismiss。Astryx 不会向自定义内容注入后备关闭按钮。按 toast 单独设置：应用可通过封装 useToast 并在每次调用时传入来共享同一套布局；而由库代码发起、从不传入该参数的 toast 会渲染为普通的 Astryx toast。传入参数为 {body, endContent, type, isAutoHide, autoHideDuration, dismiss}，其中 type 为 'info' | 'error'。",
   },
   usage: {
     description:
@@ -328,6 +328,7 @@ export const docsDense = {
     uniqueID: 'unique id for dedup',
     collisionBehavior: 'behavior when matching uniqueID exists',
     onHide: 'callback when toast removed',
-    renderContent: 'custom inner layout; receives content, resolved settings + dismiss callback; no injected fallback control',
+    renderContent:
+      'custom inner layout; receives content, resolved settings + dismiss callback; no injected fallback control',
   },
 };

package/src/Toast/Toast.tsx

@@ -154,6 +154,16 @@ export interface ToastProps {
 
 interface ToastSurfaceProps extends ToastProps {
   gestureDirection: ToastGestureDirection;
+  /**
+   * Changes when a uniqueID overwrite updates this card in place: the new
+   * toast's auto-hide timer starts over.
+   */
+  timerKey?: string;
+  /**
+   * False when the viewport announces the toast: the card then carries no
+   * live region of its own, so an update in place is announced once.
+   */
+  isLiveRegion?: boolean;
 }
 
 /**
@@ -193,6 +203,8 @@ export function ToastSurface({
   onDismiss,
   renderContent,
   gestureDirection,
+  timerKey,
+  isLiveRegion = true,
 }: ToastSurfaceProps) {
   const t = useComponentTranslator();
   const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
@@ -226,34 +238,28 @@ export function ToastSurface({
     }, remainingRef.current);
   }, [isAutoHide]);
 
-  const pauseTimer = useCallback(
-    (source: PauseSource) => {
-      if (!isAutoHide) {
-        return;
-      }
-      const sources = pauseSourcesRef.current;
-      const wasRunning = sources.size === 0;
-      sources.add(source);
-      if (!wasRunning) {
-        return;
-      }
-      if (timerRef.current) {
-        clearTimeout(timerRef.current);
-        timerRef.current = null;
-      }
-      if (startTimeRef.current != null) {
-        const elapsed = Date.now() - startTimeRef.current;
-        remainingRef.current = Math.max(remainingRef.current - elapsed, 1000);
-      }
-    },
-    [isAutoHide],
-  );
+  // Pointer, focus and gesture holds are tracked whatever isAutoHide is: an
+  // overwrite can turn a toast that does not auto-hide into one that does
+  // while a hold is in place. The window hold leaves with its listeners.
+  const pauseTimer = useCallback((source: PauseSource) => {
+    const sources = pauseSourcesRef.current;
+    const wasRunning = sources.size === 0;
+    sources.add(source);
+    if (!wasRunning) {
+      return;
+    }
+    if (timerRef.current) {
+      clearTimeout(timerRef.current);
+      timerRef.current = null;
+    }
+    if (startTimeRef.current != null) {
+      const elapsed = Date.now() - startTimeRef.current;
+      remainingRef.current = Math.max(remainingRef.current - elapsed, 1000);
+    }
+  }, []);
 
   const resumeTimer = useCallback(
     (source: PauseSource) => {
-      if (!isAutoHide) {
-        return;
-      }
       const sources = pauseSourcesRef.current;
       if (!sources.delete(source)) {
         return;
@@ -271,20 +277,31 @@ export function ToastSurface({
       }
       startTimer();
     },
-    [isAutoHide, startTimer],
+    [startTimer],
   );
 
   useEffect(() => {
     remainingRef.current = autoHideDuration;
+    // An update in place can remove the focused control, which fires no blur:
+    // a focus hold whose focus has left the card is stale.
+    const root = cardRootRef.current?.current;
+    if (
+      pauseSourcesRef.current.has('focus') &&
+      root != null &&
+      !root.contains(root.ownerDocument.activeElement)
+    ) {
+      pauseSourcesRef.current.delete('focus');
+    }
     startTimer();
     return () => {
       if (timerRef.current) {
         clearTimeout(timerRef.current);
       }
     };
-    // startTimer's identity is stable per isAutoHide, so this runs on mount
-    // and on a genuine duration change — not on unrelated viewport renders.
-  }, [autoHideDuration, startTimer]);
+    // startTimer's identity is stable per isAutoHide, so this runs on mount,
+    // on a genuine duration change and on an overwrite (timerKey), not on
+    // unrelated viewport renders.
+  }, [autoHideDuration, startTimer, timerKey]);
 
   // Pause the auto-hide timer while the window is not focused, so a toast
   // doesn't silently expire while the user is in another window or tab.
@@ -292,13 +309,21 @@ export function ToastSurface({
     if (!isAutoHide) {
       return;
     }
+    const pauseSources = pauseSourcesRef.current;
     const pauseForWindow = () => pauseTimer('window');
     const resumeForWindow = () => resumeTimer('window');
     window.addEventListener('blur', pauseForWindow);
     window.addEventListener('focus', resumeForWindow);
+    // A toast raised while the window is already blurred gets no blur event,
+    // so it starts held, and the window's next focus resumes it.
+    if (!document.hasFocus()) {
+      pauseForWindow();
+    }
     return () => {
       window.removeEventListener('blur', pauseForWindow);
       window.removeEventListener('focus', resumeForWindow);
+      // With the listeners gone, no focus event would clear the window hold.
+      pauseSources.delete('window');
     };
   }, [isAutoHide, pauseTimer, resumeTimer]);
 
@@ -363,9 +388,9 @@ export function ToastSurface({
   return (
     <div
       ref={rootRef}
-      role={isError ? 'alert' : 'status'}
-      aria-live={isError ? 'assertive' : 'polite'}
-      aria-atomic="true"
+      role={isLiveRegion ? (isError ? 'alert' : 'status') : undefined}
+      aria-live={isLiveRegion ? (isError ? 'assertive' : 'polite') : undefined}
+      aria-atomic={isLiveRegion ? 'true' : undefined}
       onMouseEnter={pauseForPointer}
       onMouseLeave={resumeForPointer}
       onFocusCapture={pauseForFocus}

package/src/Toast/ToastViewport.tsx

@@ -21,6 +21,7 @@ import {
   useMemo,
   useRef,
   useState,
+  useSyncExternalStore,
 } from 'react';
 import type {ReactNode} from 'react';
 import {createPortal} from 'react-dom';
@@ -28,6 +29,11 @@ import * as stylex from '@stylexjs/stylex';
 import {spacingVars, durationVars, easeVars} from '../theme/tokens.stylex';
 import {mergeProps} from '../utils';
 import {getNodeText} from '../utils/getNodeText';
+import {
+  moveFocusLeftBehind,
+  noteFocusWithin,
+  type FocusWithin,
+} from '../utils/focusReturn';
 import {INTERACTIVE_SELECTORS} from '../hooks/useClickableContainer';
 import {useAnnounce} from '../hooks/useAnnounce';
 import {layerTextReset} from '../Layer/layerTextReset.stylex';
@@ -224,6 +230,8 @@ interface ToastRowProps {
   isReversed: boolean;
   onExited: (id: string) => void;
   onDismiss: (id: string, reason: ToastDismissReason) => void;
+  /** Whether the card carries its own live region (see ToastViewport). */
+  isLiveRegion: boolean;
 }
 
 /**
@@ -246,6 +254,7 @@ function ToastRow({
   isReversed,
   onExited,
   onDismiss,
+  isLiveRegion,
 }: ToastRowProps) {
   const o = entry.options;
   const type = o.type ?? 'info';
@@ -296,6 +305,8 @@ function ToastRow({
           gestureDirection={isReversed ? -1 : 1}
           onDismiss={reason => onDismiss(entry.id, reason)}
           renderContent={o.renderContent}
+          timerKey={entry.id}
+          isLiveRegion={isLiveRegion}
         />
       </div>
     </div>
@@ -303,6 +314,9 @@ function ToastRow({
 }
 ToastRow.displayName = 'ToastRow';
 
+const hasActiveModalOutlet = (): boolean => getActiveModalOutlet() != null;
+const hasNoModalOutlet = (): boolean => false;
+
 /**
  * Container that renders and manages toast notifications. Place at the root
  * of your app to enable useToast(). Toasts stack with enter/exit
@@ -363,6 +377,13 @@ export function ToastViewport({
   // The next toast id that should receive focus once the dismissed toast has
   // unmounted, or 'restore' to fall back to the previously-focused element.
   const pendingFocusRef = useRef<string | 'restore' | null>(null);
+  // The id of a toast whose overwrite updated a row that held focus. If the
+  // update removed the focused control, the commit hands focus off.
+  const overwriteFocusRef = useRef<{id: string; note: FocusWithin} | null>(
+    null,
+  );
+  // Where focus was inside a toast whose dismissal hands focus off.
+  const dismissFocusNoteRef = useRef<FocusWithin | null>(null);
 
   // Collect a focusable control within a toast node, if any.
   // Reuses the canonical INTERACTIVE_SELECTORS list (native controls plus
@@ -392,13 +413,9 @@ export function ToastViewport({
     [],
   );
 
-  // Announce toasts through the persistent singleton live regions. Each
-  // <Toast> also renders its own role="status"/"alert" region, but that region
-  // is "born with content" — mounted together with its text — which many
-  // screen readers do not announce (see useAnnounce.ts); the singleton regions
-  // are mounted empty and only mutated afterwards, so they are what actually
-  // guarantees the announcement (the per-toast markup is kept for browse-mode
-  // discoverability). The announcement happens in addToast — the imperative
+  // Announce toasts through the persistent singleton live regions. They are
+  // mounted empty and only mutated afterwards, which screen readers announce
+  // (see useAnnounce.ts). The announcement happens in addToast — the imperative
   // dispatch path invoked once per useToast() call from an event handler,
   // never from render — so each toast is announced exactly once by
   // construction, independent of the React render lifecycle (StrictMode
@@ -406,6 +423,16 @@ export function ToastViewport({
   // re-renders never re-announce). It is client-only (addToast never runs
   // during SSR), so it is SSR-safe.
   const announce = useAnnounce();
+  // An open native modal hides the body-level channel above from assistive
+  // technology, so while the viewport is hosted in one, each card announces
+  // itself through its own live region instead. Outside a modal the cards
+  // carry none, so a card updated in place is announced once.
+  const hasModalOutlet = useSyncExternalStore(
+    subscribeModalOutlets,
+    hasActiveModalOutlet,
+    hasNoModalOutlet,
+  );
+  const isModalHosted = isTopLayer && hasModalOutlet;
 
   const addToast = useCallback(
     (entry: ToastEntry) => {
@@ -441,9 +468,29 @@ export function ToastViewport({
       if (overwritten && renderedToastsRef.current.includes(overwritten)) {
         replacedRef.current.set(overwritten.id, overwritten);
       }
+      // An overwrite of a toast that is not leaving keeps its row, so the card
+      // updates in place and focus inside it stays. A leaving namesake
+      // is replaced by a new row, which enters again.
+      const keepsRow =
+        overwritten != null && !exitingIdsRef.current.has(overwritten.id);
+      const placed: ToastEntry = keepsRow
+        ? {...entry, rowKey: overwritten.rowKey ?? overwritten.id}
+        : entry;
+      if (keepsRow) {
+        // If the update removes the focused control, the commit hands focus
+        // off as a dismissal does.
+        const note = noteFocusWithin(
+          viewportRef.current?.querySelector<HTMLElement>(
+            `[data-toast-id="${overwritten.id}"]`,
+          ),
+        );
+        if (note != null) {
+          overwriteFocusRef.current = {id: placed.id, note};
+        }
+      }
       const projected = overwritten
-        ? committed.map(t => (t === overwritten ? entry : t))
-        : [...committed, entry];
+        ? committed.map(t => (t === overwritten ? placed : t))
+        : [...committed, placed];
       // `maxVisible={0}` shows every toast (FR7): nothing leaves the window.
       const firstVisible = maxVisible > 0 ? projected.length - maxVisible : 0;
       const cutIds = new Set(
@@ -470,7 +517,7 @@ export function ToastViewport({
           }
         }
       }
-      pending.set(entry.id, entry);
+      pending.set(entry.id, placed);
       // An overwrite swaps a new entry, with a new id, into the replaced
       // toast's place, so the old row leaves the DOM without ever being
       // dismissed. Its settled id is dropped by the prune below, which covers
@@ -482,8 +529,8 @@ export function ToastViewport({
         // overwrite into an append. An ignored collision already returned.
         const kept = prev.filter(t => !cutIds.has(t.id));
         return overwritten && kept.includes(overwritten)
-          ? kept.map(t => (t === overwritten ? entry : t))
-          : [...kept, entry];
+          ? kept.map(t => (t === overwritten ? placed : t))
+          : [...kept, placed];
       });
     },
     [announce, maxVisible],
@@ -512,14 +559,23 @@ export function ToastViewport({
     // focused before the user entered the viewport) rather than <body>.
     const el = viewportRef.current;
     const active = document.activeElement;
-    const dismissedNode =
-      el?.querySelector<HTMLElement>(`[data-toast-id="${id}"]`) ?? null;
+    // A toast an overwrite replaced in place no longer owns its row: the
+    // replacement does, so dismissing the replaced toast leaves the row, and
+    // focus in it, to the replacement.
+    const rowKey = entry.rowKey ?? entry.id;
+    const isReplacedInPlace =
+      !toastsRef.current.some(t => t.id === id) &&
+      toastsRef.current.some(t => t.rowKey === rowKey);
+    const dismissedNode = isReplacedInPlace
+      ? null
+      : (el?.querySelector<HTMLElement>(`[data-toast-id="${id}"]`) ?? null);
     if (
       dismissedNode &&
       active instanceof Node &&
       dismissedNode.contains(active)
     ) {
       focusHandoffIdRef.current = id;
+      dismissFocusNoteRef.current = noteFocusWithin(dismissedNode);
       // Pick the toast to receive focus while the DOM is still intact: the
       // nearest one after it, then before it, that shows once it is gone
       // (FR10), else restore. The list may already run ahead of the render
@@ -587,6 +643,41 @@ export function ToastViewport({
     setToasts(prev => prev.filter(t => t.id !== id));
   }, []);
 
+  // Moves focus to a control in the target toast, else in another toast that
+  // shows (newest first), else back to the element focused before focus
+  // entered the viewport, so a handoff never drops focus to <body>.
+  const handOffFocus = useCallback(
+    (note: FocusWithin | null, targetId: string | null) => {
+      const el = viewportRef.current;
+      const rowFor = (id: string) =>
+        el?.querySelector<HTMLElement>(`[data-toast-id="${id}"]`) ?? null;
+      const shownIds = toastsRef.current
+        .slice(maxVisibleRef.current > 0 ? -maxVisibleRef.current : 0)
+        .map(t => t.id)
+        .reverse();
+      const candidates =
+        targetId == null
+          ? []
+          : [targetId, ...shownIds.filter(id => id !== targetId)];
+      let target: HTMLElement | null = null;
+      for (const id of candidates) {
+        target = getFocusable(rowFor(id));
+        if (target != null) {
+          break;
+        }
+      }
+      const prev = prevFocusRef.current;
+      const isReturning = target == null && prev != null && prev.isConnected;
+      if (target == null) {
+        target = isReturning ? prev : el;
+      }
+      if (moveFocusLeftBehind(note, target) && isReturning) {
+        prevFocusRef.current = null;
+      }
+    },
+    [getFocusable],
+  );
+
   // After a dismissed toast unmounts, hand focus off so it never falls to
   // <body>. Runs in a layout effect once the toast list no longer contains
   // the dismissed toast.
@@ -602,27 +693,21 @@ export function ToastViewport({
     }
     focusHandoffIdRef.current = null;
     pendingFocusRef.current = null;
-    const el = viewportRef.current;
-    if (target !== 'restore' && el) {
-      const nextNode = el.querySelector<HTMLElement>(
-        `[data-toast-id="${target}"]`,
-      );
-      const focusable = getFocusable(nextNode) ?? nextNode;
-      if (focusable) {
-        focusable.focus();
-        return;
-      }
-    }
-    // No remaining toast to receive focus — restore the previously-focused
-    // element if it's still connected, else fall back to the container.
-    const prev = prevFocusRef.current;
-    prevFocusRef.current = null;
-    if (prev && prev.isConnected) {
-      prev.focus();
-    } else if (el) {
-      el.focus();
+    const note = dismissFocusNoteRef.current;
+    dismissFocusNoteRef.current = null;
+    handOffFocus(note, target === 'restore' ? null : target);
+  }, [toasts, handOffFocus]);
+
+  // After an overwrite updated a row that held focus: focus stays on the same
+  // control, or, if the update removed it, moves as a dismissal hands it off.
+  useLayoutEffect(() => {
+    const overwrite = overwriteFocusRef.current;
+    if (overwrite == null) {
+      return;
     }
-  }, [toasts, getFocusable]);
+    overwriteFocusRef.current = null;
+    handOffFocus(overwrite.note, overwrite.id);
+  }, [toasts, handOffFocus]);
 
   const findByUniqueID = useCallback((uid: string) => {
     return toastsRef.current.find(t => t.options.uniqueID === uid);
@@ -830,12 +915,13 @@ export function ToastViewport({
       <LayerContentBoundary>
         {visibleToasts.map(entry => (
           <ToastRow
-            key={entry.id}
+            key={entry.rowKey ?? entry.id}
             entry={entry}
             isExiting={exitingIds.has(entry.id)}
             isReversed={isReversed}
             onExited={handleExited}
             onDismiss={removeToast}
+            isLiveRegion={isModalHosted}
           />
         ))}
       </LayerContentBoundary>

package/src/Toast/types.ts

@@ -38,9 +38,10 @@ export interface ToastOptions {
   /**
    * Replaces the content of this toast's card with your own layout.
    *
-   * Astryx keeps the card, live-region role and auto-hide behavior, then hands
-   * the renderer this toast's content, resolved settings and `dismiss`
-   * callback. The renderer owns every control inside its layout; call
+   * Astryx keeps the card and its auto-hide behavior (inside a
+   * `ToastViewport` the viewport announces the toast, and while a modal hosts
+   * the viewport the card announces itself), then hands the
+   * renderer this toast's content, resolved settings and `dismiss` callback. The renderer owns every control inside its layout; call
    * `dismiss` from the control that should close the toast. Astryx does not
    * inject a fallback control into custom content.
    *
@@ -100,4 +101,9 @@ export interface ToastEntry {
   id: string;
   options: ToastOptions;
   createdAt: number;
+  /**
+   * The row's identity in the stack. A uniqueID overwrite keeps the replaced
+   * toast's, so the card updates in place and focus inside it stays.
+   */
+  rowKey?: string;
 }