An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
'use client';
/**
* @file ToastViewport.tsx
* @input Uses React state and effects, ToastContext, the content-provider
* boundary, useAnnounce and viewport tokens. It also uses the shared layer
* text reset, the active modal outlet, the layer toast host registry and
* placement-derived motion variables
* @output Exports the ToastViewport provider, stack, live announcement dispatch
* (an open modal's containers when hosted in one, else the shared channel),
* focus handoff, safe-area-aware edge gutters, modal rehosting, and motion context
* @position Core provider/imperative viewport for useToast()
*
* SYNC: When placement, stacking, hosting, focus, announcement, or safe-area
* behavior changes, update ToastViewport.test.tsx, Toast.doc.mjs, and Toast.stories.tsx.
*/
import {
useCallback,
useEffect,
useLayoutEffect,
useMemo,
useRef,
useState,
} from 'react';
import type {ReactNode} from 'react';
import {createPortal} from 'react-dom';
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 {
announceInModal,
enclosingModalDialog,
useAnnounce,
type AnnouncePoliteness,
} from '../hooks/useAnnounce';
import {layerTextReset} from '../Layer/layerTextReset.stylex';
import {layerStructureReset} from '../Layer/layerStructureReset.stylex';
import {LayerContentBoundary} from '../Layer/layerScopedContext';
import {layerClickBoundary} from '../Layer/layerClickBoundary';
import {
getActiveModalOutlet,
subscribeModalOutlets,
type ModalOutletChange,
} from '../Layer/modalOutlet';
import {ToastSurface} from './Toast';
import {ToastContext, type ToastContextValue} from './ToastContext';
import type {ToastEntry, ToastPosition, ToastDismissReason} from './types';
import {layerInsetProperties} from '../Layer/layerInset';
import {findToastNamesake, registerToastHost} from '../Layer/toastHost';
import type {LayerInset} from '../Layer/LayerContext';
import {
registerEnglishFallback,
useComponentTranslator,
} from '../i18n/useComponentTranslator';
import english from '../i18n/generated-english/Toast/ToastViewport.generated';
registerEnglishFallback(english);
const SAFE_AREA_INLINE_START = `max(${spacingVars['--spacing-4']}, env(safe-area-inset-left, 0px))`;
const SAFE_AREA_INLINE_END = `max(${spacingVars['--spacing-4']}, env(safe-area-inset-right, 0px))`;
const SAFE_AREA_BLOCK_START = `max(${spacingVars['--spacing-4']}, env(safe-area-inset-top, 0px))`;
// On an iPhone, a downward swipe that starts in the bottom inset can pull the
// whole screen down. Keep the toast clear of that inset.
const SAFE_AREA_BLOCK_END = `calc(${spacingVars['--spacing-4']} + env(safe-area-inset-bottom, 0px))`;
// Safari reports the inset only to a page with `viewport-fit=cover`. Under a
// coarse pointer the gutter clears 34 px anyway: a Face ID iPhone's bottom
// inset in portrait.
const SAFE_AREA_BLOCK_END_TOUCH = `calc(${spacingVars['--spacing-4']} + max(env(safe-area-inset-bottom, 0px), 34px))`;
const TOAST_EDGE_DRIFT = spacingVars['--spacing-2'];
const TOAST_EDGE_DRIFT_NEGATIVE = `calc(-1 * ${TOAST_EDGE_DRIFT})`;
const styles = stylex.create({
rootOutlet: {
display: 'contents',
},
viewport: {
position: 'fixed',
zIndex: 500,
display: 'flex',
boxSizing: 'border-box',
flexDirection: 'column',
paddingBlockStart: SAFE_AREA_BLOCK_START,
paddingBlockEnd: {
default: SAFE_AREA_BLOCK_END,
'@media (pointer: coarse)': SAFE_AREA_BLOCK_END_TOUCH,
},
paddingInlineStart: {
default: SAFE_AREA_INLINE_START,
':is([dir="rtl"] *)': SAFE_AREA_INLINE_END,
},
paddingInlineEnd: {
default: SAFE_AREA_INLINE_END,
':is([dir="rtl"] *)': SAFE_AREA_INLINE_START,
},
pointerEvents: 'none',
// Reset popover styles — the popover attribute puts us in the top
// layer (above dialogs), but we don't want its default styles.
// UA stylesheet applies background-color: Canvas, margin: auto, etc.
inset: 'unset',
// `width` is part of that reset: the UA gives every popover
// `width: fit-content`, and this element is positioned by spanning the
// inline axis (`viewportInlineSpan` sets both inset-inline edges to 0) and
// then aligning within itself. A shrink-wrapped box cannot span, so both
// edges cannot be honoured — the box resolves against the start edge at
// its content width, and `align-items: flex-end` then aligns the toast to
// the right of a box that is itself sitting on the left. Measured in
// Chromium at 1200px wide: 438px box at x=0, end-positioned toast landing
// at x=19.
width: 'auto',
margin: 0,
borderWidth: 0,
borderStyle: 'none',
backgroundColor: 'transparent',
overflow: 'visible',
},
// iOS Safari colors its toolbar from a fixed element at the bottom edge. A
// toast that a swipe sends through that edge gives the viewport its color.
// Safari keeps that color while the viewport has a box, so an empty
// viewport has none.
viewportEmpty: {
display: 'none',
},
// The viewport sits at the inset the app declared on LayerProvider for a
// bar floating over that edge (spec:AST-059 FR6); unset, each reads 0px.
// A toast-only `inset` prop writes the same edges inline and wins.
viewportInlineSpan: {
insetInlineStart: 'var(--astryx-layer-inset-inline-start, 0px)',
insetInlineEnd: 'var(--astryx-layer-inset-inline-end, 0px)',
},
bottomEnd: {
bottom: 'var(--astryx-layer-inset-block-end, 0px)',
alignItems: 'flex-end',
},
bottomStart: {
bottom: 'var(--astryx-layer-inset-block-end, 0px)',
alignItems: 'flex-start',
},
topEnd: {
top: 'var(--astryx-layer-inset-block-start, 0px)',
alignItems: 'flex-end',
flexDirection: 'column-reverse',
},
topStart: {
top: 'var(--astryx-layer-inset-block-start, 0px)',
alignItems: 'flex-start',
flexDirection: 'column-reverse',
},
toastWrapper: {
pointerEvents: 'auto',
display: 'grid',
width: '100%',
maxWidth: 400,
minWidth: 0,
gridTemplateRows: '1fr',
transitionProperty: 'grid-template-rows, padding',
transitionDuration: {
default: durationVars['--duration-fast'],
'@media (prefers-reduced-motion: reduce)': '0.01ms',
},
transitionTimingFunction: easeVars['--ease-standard'],
},
// A row opens from a closed track only when it first renders. A move to
// another modal outlet renders it again, and it must not open again.
toastWrapperEntering: {
'@starting-style': {
gridTemplateRows: '0fr',
paddingBlockEnd: 0,
},
},
toastWrapperFromBottom: {
'--_toast-slide-y': TOAST_EDGE_DRIFT,
},
toastWrapperFromTop: {
'--_toast-slide-y': TOAST_EDGE_DRIFT_NEGATIVE,
},
// The inter-toast gap is padding on each wrapper so it collapses with the
// grid track. The wrapper nearest the viewport edge drops that padding; the
// child flips because top stacks use column-reverse.
toastWrapperGap: {
paddingBlockEnd: {default: spacingVars['--spacing-2'], ':last-child': 0},
},
toastWrapperGapReversed: {
paddingBlockEnd: {default: spacingVars['--spacing-2'], ':first-child': 0},
},
toastWrapperExiting: {
gridTemplateRows: '0fr',
paddingBlockEnd: 0,
},
toastWrapperInner: {
width: '100%',
maxWidth: '100%',
minWidth: 0,
minHeight: 0,
// Clip while the grid row opens and closes so the toast reads as folding
// into the stack. Once the entry transition settles, the companion style
// below releases the clip so the card's shadow can paint. `hidden` works
// in every engine and restores the exact exit paint/hit boundary that the
// viewport shipped with before the shadow fix.
overflow: 'hidden',
},
toastWrapperInnerSettled: {
overflow: 'visible',
},
});
export interface ToastViewportProps {
position?: ToastPosition;
/** Maximum number of visible toasts. @default 5 */
maxVisible?: number;
inset?: {top?: number; bottom?: number; start?: number; end?: number};
/**
* The app-declared viewport inset from LayerProvider (spec:AST-059 FR6).
* The viewport sits at it on each edge unless `inset` overrides that edge.
*/
layerInset?: LayerInset;
/**
* Promote viewport to CSS top layer via popover="manual". While a Dialog
* is open, the viewport moves into the latest one so toasts stay visible
* and clickable above it. Set to false to render in place, e.g. a viewport you mount
* inside your own top-layer element.
* @default true
*/
isTopLayer?: boolean;
children?: React.ReactNode;
}
/**
* Drop an id from a Set of ids, keeping the Set's identity when the id is not
* in it so React can skip the re-render. The viewport tracks two of these
* (exiting rows, settled rows) and each has to be pruned from more than one
* place.
*/
const withoutId =
(id: string) =>
(prev: Set<string>): Set<string> => {
if (!prev.has(id)) {
return prev;
}
const next = new Set(prev);
next.delete(id);
return next;
};
interface ToastRowProps {
entry: ToastEntry;
isExiting: boolean;
/** Top-anchored stacks grow downward and flip the row's drift and gap. */
isReversed: boolean;
onExited: (id: string) => void;
onDismiss: (id: string, reason: ToastDismissReason) => void;
/** Whether the card carries its own live region (see ToastViewport). */
isLiveRegion: boolean;
}
/**
* One row of the stack: the grid wrapper that opens and collapses, and the
* clip that releases once it is open so the card's elevation can paint.
*
* Settled state lives here, on the mounted row, rather than in a Set of ids on
* the viewport. A row leaves the DOM by more paths than dismissal — `maxVisible`
* evicts the oldest when a newer toast arrives, and a uniqueID overwrite swaps
* a new entry into a replaced toast's place — and on those paths nothing on the
* dismissal path runs to prune it. Holding the flag on the row makes every one
* of them the same event: the row unmounts, the flag goes with it, and a toast
* that resurfaces when the stack drains mounts clipped and runs its own entry
* transition. Re-clipping on dismissal is the same rule read forward, since the
* clip is released only while the row is settled *and* not exiting.
*/
function ToastRow({
entry,
isExiting,
isReversed,
onExited,
onDismiss,
isLiveRegion,
}: ToastRowProps) {
const o = entry.options;
const type = o.type ?? 'info';
const isAutoHide = o.isAutoHide ?? (type === 'error' ? false : true);
const dur = o.autoHideDuration ?? 5000;
const [isSettled, setIsSettled] = useState(false);
// Each move between modal outlets renders the row and its card again. Their
// starting styles must not apply then.
const [hasEntryStarted, setHasEntryStarted] = useState(false);
// React's transition run and cancel events have no propertyName field.
const watchEntry = useCallback((row: HTMLDivElement | null) => {
if (row == null) {
return;
}
const onTransition = (event: TransitionEvent) => {
if (event.target !== row || event.propertyName !== 'grid-template-rows') {
return;
}
setHasEntryStarted(true);
// A move cancels the entry, and the row then renders fully open. No
// transition ends, so the row settles here.
if (event.type === 'transitioncancel') {
setIsSettled(true);
}
};
row.addEventListener('transitionrun', onTransition);
row.addEventListener('transitioncancel', onTransition);
return () => {
row.removeEventListener('transitionrun', onTransition);
row.removeEventListener('transitioncancel', onTransition);
};
}, []);
return (
<div
ref={watchEntry}
data-toast-id={entry.id}
{...stylex.props(
styles.toastWrapper,
!hasEntryStarted && styles.toastWrapperEntering,
isReversed ? styles.toastWrapperFromTop : styles.toastWrapperFromBottom,
isReversed ? styles.toastWrapperGapReversed : styles.toastWrapperGap,
isExiting && styles.toastWrapperExiting,
)}
onTransitionEnd={(e: React.TransitionEvent) => {
// `grid-template-rows` is not private to this wrapper — any descendant
// may animate its own grid, and transitionend bubbles. Only the row's
// own transition says the row has finished opening or collapsing.
if (e.target !== e.currentTarget) {
return;
}
if (e.propertyName !== 'grid-template-rows') {
return;
}
if (isExiting) {
onExited(entry.id);
return;
}
// The row is fully open now. Release only the paint clip; the wrapper
// still owns pointer events and restores the clip synchronously when
// dismissal starts.
setIsSettled(true);
setHasEntryStarted(true);
}}>
<div
{...stylex.props(
styles.toastWrapperInner,
isSettled && !isExiting && styles.toastWrapperInnerSettled,
)}>
<ToastSurface
type={type}
body={o.body}
endContent={o.endContent}
isAutoHide={isAutoHide}
autoHideDuration={dur}
isExiting={isExiting}
gestureDirection={isReversed ? -1 : 1}
onDismiss={reason => onDismiss(entry.id, reason)}
renderContent={o.renderContent}
timerKey={entry.id}
isLiveRegion={isLiveRegion}
hasEntryStarted={hasEntryStarted}
/>
</div>
</div>
);
}
ToastRow.displayName = 'ToastRow';
/**
* Container that renders and manages toast notifications. Place at the root
* of your app to enable useToast(). Toasts stack with enter/exit
* animations and auto-promote to the CSS top layer.
*
* @example
* ```
* <ToastViewport position="bottomEnd" maxVisible={3}>
* <App />
* </ToastViewport>
* ```
*/
export function ToastViewport({
position = 'bottomEnd',
maxVisible = 5,
inset,
layerInset,
isTopLayer = true,
children,
}: ToastViewportProps) {
const t = useComponentTranslator();
const [toasts, setToasts] = useState<ToastEntry[]>([]);
const [exitingIds, setExitingIds] = useState<Set<string>>(new Set());
const toastsRef = useRef(toasts);
toastsRef.current = toasts;
// The list as last rendered: addToast moves toastsRef ahead of it within
// a batch, so this tells a rendered toast from one raised since.
const renderedToastsRef = useRef(toasts);
renderedToastsRef.current = toasts;
// Read by removeToast, which keeps one identity across renders.
const maxVisibleRef = useRef(maxVisible);
maxVisibleRef.current = maxVisible;
// Rendered entries a repeat has replaced in this batch: still found by a
// dismissal in the same handler, as before the swap. One replaced before it
// rendered was never shown and reports no onHide (Toast.spec.md FR3). A
// render starts a new batch.
const replacedRef = useRef<Map<string, ToastEntry>>(new Map());
replacedRef.current.clear();
const viewportRef = useRef<HTMLDivElement>(null);
// Toast ids whose exit has begun — guards onHide from double-firing (see
// removeToast). Mirrors exitingIds state, readable synchronously.
const exitingIdsRef = useRef<Set<string>>(new Set());
// Toasts dispatched since the last commit, by id: a dismiss() called
// before the toast first renders still finds it (and its onHide).
const pendingEntriesRef = useRef<Map<string, ToastEntry>>(new Map());
// The element that was focused before focus entered the viewport, by F6,
// Tab or a click. Used to restore focus once all toasts are dismissed so
// focus never falls to <body> (FR10).
const prevFocusRef = useRef<HTMLElement | null>(null);
// The element focus last reached inside the viewport's React tree,
// portaled toast content included.
const lastFocusedWithinRef = useRef<EventTarget | null>(null);
// When a toast is dismissed while focus lives inside it, we need to move
// focus to a sensible neighbor after that toast unmounts. This holds the
// id of the toast whose removal should trigger a focus handoff.
const focusHandoffIdRef = useRef<string | null>(null);
// 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
// role-based interactive elements) instead of a hand-rolled subset, then
// narrows to the first candidate that can actually receive focus —
// excluding elements opted out with `tabindex="-1"` and disabled controls.
const getFocusable = useCallback(
(container: HTMLElement | null): HTMLElement | null => {
if (!container) {
return null;
}
const candidates = container.querySelectorAll<HTMLElement>(
INTERACTIVE_SELECTORS,
);
for (const candidate of candidates) {
if (
candidate.getAttribute('tabindex') === '-1' ||
candidate.hasAttribute('disabled') ||
candidate.getAttribute('aria-disabled') === 'true'
) {
continue;
}
return candidate;
}
return null;
},
[],
);
// 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
// double-render/double-effect, viewport remounts, and unrelated list
// re-renders never re-announce). It is client-only (addToast never runs
// during SSR), so it is SSR-safe.
// The viewport is each toast's only announcement owner; the card carries no
// live role. A top-layer viewport's host moves into the latest open native
// modal, where the page's shared channel is not exposed, so it writes
// through the containers of the modal its host sits in. A
// viewport rendered in place uses `useAnnounce`, which finds an enclosing
// modal through its context.
const announceShared = useAnnounce();
// The top-layer host (below), read at write time for the modal it sits in.
const hostRef = useRef<HTMLDivElement | null>(null);
const announce = useCallback(
(text: string, politeness: AnnouncePoliteness) => {
const modal = isTopLayer ? enclosingModalDialog(hostRef.current) : null;
if (modal != null) {
announceInModal(modal, text, politeness);
return;
}
announceShared(text, politeness);
},
[announceShared, isTopLayer],
);
const addToast = useCallback(
(entry: ToastEntry) => {
const {uniqueID} = entry.options;
// A toast holds its uniqueID until it unmounts, leaving included
// (Toast.spec.md FR8): an overwrite replaces it in place, and an ignored
// namesake is dropped.
const {namesake: overwritten, isDropped} = findToastNamesake(
toastsRef.current,
entry,
);
// Resolve an ignored collision synchronously against the committed list
// so a suppressed toast is neither shown nor announced. The remaining
// announce + setToasts run outside the setToasts updater, which React may
// invoke more than once — keeping the announcement exactly-once.
if (isDropped) {
return;
}
// Only text is announced; interactive endContent is reachable via F6.
const text = getNodeText(entry.options.body);
if (text) {
// Error toasts map to the assertive region (role="alert"); everything
// else to the polite region (role="status") — mirrors Toast.tsx.
announce(text, entry.options.type === 'error' ? 'assertive' : 'polite');
}
// A leaving toast that a new one pushes out of the visible window can no
// longer finish its exit on screen, so it leaves the list now (it
// already reported onHide); otherwise its row would come back collapsed
// when the window reached it again, holding a slot and the landmark.
const committed = toastsRef.current;
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 ? 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(
projected
.filter((t, i) => i < firstVisible && exitingIdsRef.current.has(t.id))
.map(t => t.id),
);
if (cutIds.size > 0) {
// Gone from every list, so a later dismissal reports nothing more.
for (const id of cutIds) {
exitingIdsRef.current.delete(id);
pendingEntriesRef.current.delete(id);
}
setExitingIds(prev => new Set([...prev].filter(id => !cutIds.has(id))));
}
// Later toasts in the same batch see this one before the next render.
toastsRef.current = projected.filter(t => !cutIds.has(t.id));
const pending = pendingEntriesRef.current;
if (uniqueID) {
// An overwrite replaces a toast that has not rendered yet too.
for (const [pendingId, pendingEntry] of pending) {
if (pendingEntry.options.uniqueID === uniqueID) {
pending.delete(pendingId);
}
}
}
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
// every silent exit with one rule rather than one branch per path.
setToasts(prev => {
// The cut entries go first, then the choice the projection above made
// (by identity): a dismissal in the same handler may have marked the
// replaced namesake as leaving since, which must not turn the
// 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 ? placed : t))
: [...kept, placed];
});
},
[announce, maxVisible],
);
const removeToast = useCallback((id: string, reason: ToastDismissReason) => {
// An exiting toast stays in toastsRef until its exit transition ends, so
// a second dismissal inside that window (double-click, auto-timer plus
// manual dismiss()) would re-fire onHide. Track exiting ids in a ref —
// the exitingIds state dedupe below runs too late to protect onHide.
if (exitingIdsRef.current.has(id)) {
return;
}
const entry =
toastsRef.current.find(t => t.id === id) ??
replacedRef.current.get(id) ??
pendingEntriesRef.current.get(id);
if (entry == null) {
// Already gone: nothing to hide or report.
return;
}
exitingIdsRef.current.add(id);
entry.options.onHide?.(reason);
// If focus currently lives inside the toast being dismissed, remember
// that its removal must hand focus off to a neighbor (or the element
// focused before the user entered the viewport) rather than <body>.
const el = viewportRef.current;
const active = document.activeElement;
// 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
// within this handler: a toast a repeat replaced has left it, and the
// replacement holds its place, so the neighbors are taken around the
// replacement, which takes focus only when no neighbor shows.
const list = toastsRef.current;
const {uniqueID} = entry.options;
const ownIndex = list.findIndex(t => t.id === id);
const placeIndex =
ownIndex >= 0 || uniqueID == null
? ownIndex
: list.findIndex(t => t.options.uniqueID === uniqueID);
const remaining = list.filter(t => t.id !== id);
const max = maxVisibleRef.current;
const shown = new Set(max > 0 ? remaining.slice(-max) : remaining);
const isShown = (t: ToastEntry) => shown.has(t);
const replacement = ownIndex < 0 ? list[placeIndex] : undefined;
const next =
placeIndex < 0
? undefined
: (list.slice(placeIndex + 1).find(isShown) ??
list.slice(0, placeIndex).reverse().find(isShown) ??
(replacement != null && isShown(replacement)
? replacement
: undefined));
pendingFocusRef.current = next ? next.id : 'restore';
}
// A toast this handler has already pushed out of the visible window still
// has its row now, but loses it when the batch renders.
const index = toastsRef.current.findIndex(t => t.id === id);
const isPushedOut =
maxVisibleRef.current > 0 &&
index >= 0 &&
index < toastsRef.current.length - maxVisibleRef.current;
if (dismissedNode == null || isPushedOut) {
// No row is mounted for it, or none will be: it is hidden past
// `maxVisible`, or it has not rendered yet. Nothing animates out, so it
// leaves the list now.
// Waiting for its row to finish exiting would keep it forever: when it
// surfaced, its row would mount already collapsed, with no transition
// left to end, and hold a visible slot as an empty row.
// It leaves the committed list now too, so a second dismissal before
// the next render finds nothing to report (nor does a toast a repeat
// replaced in this batch).
exitingIdsRef.current.delete(id);
pendingEntriesRef.current.delete(id);
replacedRef.current.delete(id);
toastsRef.current = toastsRef.current.filter(t => t.id !== id);
setToasts(prev => prev.filter(t => t.id !== id));
return;
}
setExitingIds(prev => {
if (prev.has(id)) {
return prev;
}
return new Set(prev).add(id);
});
}, []);
const handleExited = useCallback((id: string) => {
exitingIdsRef.current.delete(id);
pendingEntriesRef.current.delete(id);
setExitingIds(withoutId(id));
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.
useLayoutEffect(() => {
const handoffId = focusHandoffIdRef.current;
const target = pendingFocusRef.current;
if (handoffId == null || target == null) {
return;
}
// Wait until the dismissed toast is actually gone from the list.
if (toasts.some(t => t.id === handoffId)) {
return;
}
focusHandoffIdRef.current = null;
pendingFocusRef.current = null;
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;
}
overwriteFocusRef.current = null;
handOffFocus(overwrite.note, overwrite.id);
}, [toasts, handOffFocus]);
const findByUniqueID = useCallback((uid: string) => {
return toastsRef.current.find(t => t.options.uniqueID === uid);
}, []);
const contextValue = useMemo<ToastContextValue>(
() => ({addToast, removeToast, findByUniqueID}),
[addToast, removeToast, findByUniqueID],
);
const visibleToasts = toasts.slice(-maxVisible);
const insetStyle: React.CSSProperties = {
...layerInsetProperties(layerInset),
};
if (inset?.top) {
insetStyle.top = inset.top;
}
if (inset?.bottom) {
insetStyle.bottom = inset.bottom;
}
if (inset?.start) {
insetStyle.insetInlineStart = inset.start;
}
if (inset?.end) {
insetStyle.insetInlineEnd = inset.end;
}
// A top-layer viewport renders into a host element this component owns, so
// the host can move into the latest open native modal and back without
// React remounting the rows: their timers and gesture state live there.
// Outside a modal the host sits at the viewport's own place in the tree.
const rootOutletRef = useRef<HTMLDivElement>(null);
const [host, setHost] = useState<HTMLDivElement | null>(null);
useLayoutEffect(() => {
if (!isTopLayer) {
return;
}
const element = document.createElement('div');
element.style.display = 'contents';
hostRef.current = element;
// eslint-disable-next-line @eslint-react/set-state-in-effect -- the host exists only on the client, so server and hydration markup carry no portal
setHost(element);
return () => {
element.remove();
hostRef.current = null;
setHost(null);
};
}, [isTopLayer]);
// Syncs the host's place with the modal outlet registry. The host moves into
// the latest open modal, and back when that modal closes.
useLayoutEffect(() => {
if (!isTopLayer || host == null) {
return;
}
const place = (change: ModalOutletChange = 'outlet') => {
const parent = getActiveModalOutlet() ?? rootOutletRef.current;
if (parent == null) {
return;
}
if (host.parentNode !== parent) {
// Moving a node blurs whatever inside it had focus.
const active = document.activeElement;
const hadFocus = active instanceof HTMLElement && host.contains(active);
parent.appendChild(host);
if (hadFocus) {
active.focus({preventScroll: true});
}
}
// Leaving the document hid the popover. Showing it again puts it above
// the modal that just opened, or above everything once the last modal
// closed. A non-modal surface that entered the top layer (`entry`)
// moved nothing, so the viewport leaves and re-enters in place to get
// above it; focus inside it is kept across the re-entry.
const el = viewportRef.current;
if (el == null || typeof el.showPopover !== 'function') {
return;
}
let isShowing = false;
try {
isShowing = el.matches(':popover-open');
} catch {
/* :popover-open unsupported */
}
if (isShowing && change === 'entry') {
const active = document.activeElement;
const hadFocus = active instanceof HTMLElement && el.contains(active);
try {
el.hidePopover();
isShowing = false;
} catch {
/* not a showing popover */
}
if (isShowing) {
return;
}
try {
el.showPopover();
} catch {
/* already showing */
}
if (hadFocus) {
active.focus({preventScroll: true});
}
return;
}
if (!isShowing) {
try {
el.showPopover();
} catch {
/* already showing */
}
}
};
place();
return subscribeModalOutlets(place);
}, [isTopLayer, host]);
// F6 jumps focus into the toast viewport — the standard "go to
// notifications" affordance. Focus the first control in the newest toast,
// or the viewport container if none. Toasts are non-modal, so this only
// moves focus in; Shift+Tab / Escape let focus leave naturally.
const hasToasts = toasts.length > 0;
useEffect(() => {
if (!hasToasts) {
return;
}
const handleKeyDown = (e: KeyboardEvent) => {
if (e.key !== 'F6') {
return;
}
const el = viewportRef.current;
if (!el) {
return;
}
// Already inside the viewport — nothing to do.
const active = document.activeElement;
if (active instanceof Node && el.contains(active)) {
return;
}
e.preventDefault();
// Remember where focus was so it can be restored on dismiss.
if (active instanceof HTMLElement) {
prevFocusRef.current = active;
}
// Newest toast is the last one rendered in the DOM.
const toastNodes = el.querySelectorAll<HTMLElement>('[data-toast-id]');
const newest = toastNodes[toastNodes.length - 1] ?? null;
const focusable = getFocusable(newest) ?? newest ?? el;
focusable.focus();
};
document.addEventListener('keydown', handleKeyDown);
return () => {
document.removeEventListener('keydown', handleKeyDown);
};
}, [hasToasts, getFocusable]);
const posStyle =
position === 'topEnd'
? styles.topEnd
: position === 'topStart'
? styles.topStart
: position === 'bottomStart'
? styles.bottomStart
: styles.bottomEnd;
const isReversed = position === 'topEnd' || position === 'topStart';
const viewport = (
<div
ref={viewportRef}
onFocus={event => {
// Focus entering from outside, however it came, is where a dismissal
// of the last toast returns it. React also delivers focus inside a
// toast's portaled content here, so focus coming back from the last
// element focused within is not an entry, though it sits outside
// this element.
const from = event.relatedTarget;
const fromWithin =
from === lastFocusedWithinRef.current ||
(from instanceof Node && event.currentTarget.contains(from));
lastFocusedWithinRef.current = event.target;
if (from instanceof HTMLElement && !fromWithin) {
prevFocusRef.current = from;
}
}}
role={hasToasts ? 'region' : undefined}
aria-label={hasToasts ? t('@astryx.toast.viewport') : undefined}
tabIndex={hasToasts ? -1 : undefined}
// popover="manual" promotes to the top layer; the host effect above
// keeps it above the latest open modal. Omitted when the caller
// renders the viewport in place.
popover={isTopLayer ? 'manual' : undefined}
{...mergeProps(
stylex.props(
layerTextReset.reset,
layerStructureReset.reset,
styles.viewport,
styles.viewportInlineSpan,
posStyle,
!hasToasts && styles.viewportEmpty,
),
{
style: Object.keys(insetStyle).length > 0 ? insetStyle : undefined,
},
)}
// Presses on toasts do not reach handlers around the viewport.
{...layerClickBoundary()}>
<LayerContentBoundary>
{visibleToasts.map(entry => (
<ToastRow
key={entry.rowKey ?? entry.id}
entry={entry}
isExiting={exitingIds.has(entry.id)}
isReversed={isReversed}
onExited={handleExited}
onDismiss={removeToast}
isLiveRegion={false}
/>
))}
</LayerContentBoundary>
</div>
);
return (
<ToastContext value={contextValue}>
{children}
{isTopLayer ? (
<>
<div ref={rootOutletRef} {...stylex.props(styles.rootOutlet)} />
{host != null ? createPortal(viewport, host) : null}
</>
) : (
viewport
)}
</ToastContext>
);
}
ToastViewport.displayName = 'ToastViewport';
// LayerProvider renders the viewport once this module loads. So an app that
// never imports Toast carries none of its code.
registerToastHost(ToastViewport);