Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
14.6 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

'use client';

/**
 * @file Toast.tsx
 * @input Uses React timers, touch/pen gesture events, Toast options, Button/Icon,
 *   MediaTheme, tokens, and placement motion inherited from ToastViewport
 * @output Exports the rendered Toast surface and its pause/swipe/dismiss behavior
 * @position Core implementation; rendered by ToastViewport and documented by Toast.doc.mjs
 *
 * SYNC: When Toast layout, timer pause, media theme, or dismissal behavior changes,
 *   update these files to stay in sync:
 * - /packages/core/src/Toast/ToastViewport.test.tsx
 * - /packages/core/src/Toast/Toast.doc.mjs
 * - /apps/storybook/stories/Toast.stories.tsx
 * - /packages/cli/assets/templates/blocks/components/Toast/ (showcase blocks)
 */

import {useCallback, useEffect, useRef} from 'react';
import type {FocusEvent, ReactNode, RefObject} from 'react';
import * as stylex from '@stylexjs/stylex';
import {Button} from '../Button';
import {Icon} from '../Icon';
import {
  colorVars,
  spacingVars,
  radiusVars,
  durationVars,
  easeVars,
  shadowVars,
  typographyVars,
  typeScaleDefaults,
} from '../theme/tokens.stylex';
import {mergeProps} from '../utils';
import {INTERACTIVE_SELECTORS} from '../hooks/useClickableContainer';
import {useTheme} from '../theme';
import {MediaTheme} from '../theme/MediaTheme';
import type {
  ToastType,
  ToastDismissReason,
  ToastContentRenderFn,
} from './types';
import {themeProps} from '../utils/themeProps';
import {useToastGesture, type ToastGestureDirection} from './useToastGesture';
import {
  registerEnglishFallback,
  useComponentTranslator,
} from '../i18n/useComponentTranslator';
import english from '../i18n/generated-english/Toast/Toast.generated';

registerEnglishFallback(english);

const SWIPE_INTERACTIVE_TARGET_SELECTOR = `${INTERACTIVE_SELECTORS},[tabindex],[contenteditable]:not([contenteditable="false"])`;

function isInteractiveTarget(
  target: EventTarget | null,
  root: HTMLElement,
): boolean {
  if (!(target instanceof Element)) {
    return false;
  }
  let current: Element | null = target;
  while (current != null && current !== root && current !== document.body) {
    if (current.matches(SWIPE_INTERACTIVE_TARGET_SELECTOR)) {
      return true;
    }
    current = current.parentElement;
  }
  return false;
}

const TOAST_EDGE_DRIFT = spacingVars['--spacing-2'];
const styles = stylex.create({
  root: {
    paddingBlock: spacingVars['--spacing-4'],
    paddingInline: spacingVars['--spacing-4'],
    borderRadius: radiusVars['--radius-container'],
    boxSizing: 'border-box',
    width: 400,
    maxWidth: '100%',
    boxShadow: shadowVars['--shadow-med'],
    opacity: 'var(--_toast-swipe-opacity, 1)',
    fontFamily: typographyVars['--font-family-body'],
    fontSize: typeScaleDefaults['--text-body-size'],
    lineHeight: typeScaleDefaults['--text-body-leading'],
    transform:
      'translateY(var(--_toast-swipe-y, 0px)) scale(var(--_toast-swipe-scale, 1))',
    transitionProperty: 'opacity, transform',
    transitionDuration: {
      default: durationVars['--duration-fast'],
      '@media (prefers-reduced-motion: reduce)': '0.01ms',
    },
    transitionTimingFunction: easeVars['--ease-standard'],
  },
  // A card enters from its edge only when it first renders. A move between
  // modal outlets renders it again, and it must not enter again.
  entering: {
    '@starting-style': {
      opacity: 0,
      transform: `translateY(var(--_toast-slide-y, ${TOAST_EDGE_DRIFT}))`,
    },
  },
  variantDefault: {
    backgroundColor: colorVars['--color-background-inverted'],
  },

  inner: {
    display: 'flex',
    alignItems: 'flex-start',
    flexWrap: 'nowrap',
    gap: spacingVars['--spacing-3'],
    width: '100%',
  },
  variantError: {
    backgroundColor: colorVars['--color-background-error-inverted'],
  },
  content: {
    flex: 1,
    minWidth: 0,
    overflowWrap: 'anywhere',
    // Text inside keeps `anywhere` too (Text FR3).
    '--_astryx-text-overflow-wrap': 'anywhere',
  },
  exiting: {
    opacity: 0,
    transform: `translateY(var(--_toast-swipe-exit-y, var(--_toast-swipe-y, var(--_toast-slide-y, ${TOAST_EDGE_DRIFT})))) scale(var(--_toast-swipe-scale, 1))`,
  },
  endContent: {
    flexShrink: 0,
    display: 'flex',
    alignItems: 'center',
    gap: spacingVars['--spacing-2'],
    // Keep every trailing control centered on the first 20px body line, even
    // when the body wraps or a consumer supplies a control taller than the
    // built-in 28px dismiss button. The action label should still stay short;
    // the wrappers above let it break rather than widen the Toast.
    blockSize: `calc(${typeScaleDefaults['--text-body-size']} * ${typeScaleDefaults['--text-body-leading']})`,
    marginInlineEnd: `calc(${spacingVars['--spacing-1']} * -1)`,
  },
});

export interface ToastProps {
  type: ToastType;
  body: ReactNode;
  endContent?: ReactNode;
  isAutoHide: boolean;
  autoHideDuration: number;
  isExiting?: boolean;
  onDismiss: (reason: ToastDismissReason) => void;
  /**
   * Replaces the content of this toast's card with your own layout. Direct
   * `Toast` renders use the same contract as `ToastOptions.renderContent`;
   * apps normally set it per toast in the options passed to `useToast()`.
   */
  renderContent?: ToastContentRenderFn;
}

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;
  /**
   * True once the toast's row has started to open. The card then has no
   * starting style, so a move between modal outlets starts no transition.
   */
  hasEntryStarted?: boolean;
}

/**
 * Individual toast notification.
 *
 * Renders with inverted surface colors for the default variant,
 * and error-inverted for the error variant. Applies MediaTheme for that
 * surface, unless the painted colors make the chosen side unreadable —
 * a theme is free to define an "inverted" background that is not.
 * Pauses auto-dismiss on hover and focus.
 *
 * @example
 * ```
 * <Toast
 *   type="info"
 *   body="Saved successfully"
 *   isAutoHide={true}
 *   autoHideDuration={5000}
 *   onDismiss={(reason) => removeToast(id, reason)}
 * />
 * ```
 */
export function Toast(props: ToastProps) {
  return <ToastSurface {...props} gestureDirection={1} />;
}

/** A condition that holds a toast's auto-hide timer. */
type PauseSource = 'pointer' | 'focus' | 'gesture' | 'window';

export function ToastSurface({
  type,
  body,
  endContent,
  isAutoHide,
  autoHideDuration,
  isExiting = false,
  onDismiss,
  renderContent,
  gestureDirection,
  timerKey,
  isLiveRegion = true,
  hasEntryStarted = false,
}: ToastSurfaceProps) {
  const t = useComponentTranslator();
  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
  // Every condition that holds the auto-hide timer (pointer over the card,
  // focus inside it, a touch or pen gesture, the window blurred) is tracked on
  // its own, so one ending resumes the timer only when no other still holds.
  const pauseSourcesRef = useRef<Set<PauseSource>>(new Set());
  // The card's root, read when a hold ends to drop a focus hold whose focused
  // control was removed: an unmounting control fires no blur.
  const cardRootRef = useRef<RefObject<HTMLDivElement | null> | null>(null);
  const remainingRef = useRef(autoHideDuration);
  // Will be initialized by startTimer when actually used
  const startTimeRef = useRef<number | null>(null);

  // Read onDismiss through a ref: the viewport re-creates it on every render
  // (another toast arriving/exiting), and a startTimer that depends on it
  // would restart — and un-pause — this toast's timer on unrelated renders.
  const onDismissRef = useRef(onDismiss);
  onDismissRef.current = onDismiss;

  const startTimer = useCallback(() => {
    if (!isAutoHide || pauseSourcesRef.current.size > 0) {
      return;
    }
    if (timerRef.current) {
      clearTimeout(timerRef.current);
    }
    startTimeRef.current = Date.now();
    timerRef.current = setTimeout(() => {
      onDismissRef.current('auto');
    }, remainingRef.current);
  }, [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) => {
      const sources = pauseSourcesRef.current;
      if (!sources.delete(source)) {
        return;
      }
      const root = cardRootRef.current?.current;
      if (
        sources.has('focus') &&
        root != null &&
        !root.contains(document.activeElement)
      ) {
        sources.delete('focus');
      }
      if (sources.size > 0) {
        return;
      }
      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,
    // 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.
  useEffect(() => {
    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]);

  const isGesturePausing = useCallback(
    () => pauseSourcesRef.current.has('gesture'),
    [],
  );
  const pauseForGesture = useCallback(
    () => pauseTimer('gesture'),
    [pauseTimer],
  );
  const resumeForGesture = useCallback(
    () => resumeTimer('gesture'),
    [resumeTimer],
  );
  const pauseForPointer = useCallback(
    () => pauseTimer('pointer'),
    [pauseTimer],
  );
  const resumeForPointer = useCallback(
    () => resumeTimer('pointer'),
    [resumeTimer],
  );
  const pauseForFocus = useCallback(() => pauseTimer('focus'), [pauseTimer]);
  const resumeForFocus = useCallback(
    (event: FocusEvent<HTMLDivElement>) => {
      // Focus moving between controls inside the card keeps it held.
      const next = event.relatedTarget;
      if (next instanceof Node && event.currentTarget.contains(next)) {
        return;
      }
      resumeTimer('focus');
    },
    [resumeTimer],
  );
  const dismissFromGesture = useCallback(() => {
    onDismissRef.current('manual');
  }, []);
  const {rootRef, bindings: gestureBindings} = useToastGesture({
    direction: gestureDirection,
    enabled: !isExiting,
    canPauseTimer: isAutoHide,
    isTimerPaused: isGesturePausing,
    pauseTimer: pauseForGesture,
    resumeTimer: resumeForGesture,
    dismiss: dismissFromGesture,
    shouldIgnoreTarget: isInteractiveTarget,
  });
  cardRootRef.current = rootRef;

  const handleDismiss = useCallback(() => {
    onDismiss('manual');
  }, [onDismiss]);

  const isError = type === 'error';
  // The surface is *usually* dark in light mode and light in dark mode, but a
  // theme can define --color-background-inverted as anything — so the mode is
  // measured, not assumed. This is only the pre-measurement fallback.
  const {mode} = useTheme();
  const fallbackMediaMode = isError || mode === 'light' ? 'dark' : 'light';

  return (
    <div
      ref={rootRef}
      role={isLiveRegion ? (isError ? 'alert' : 'status') : undefined}
      aria-live={isLiveRegion ? (isError ? 'assertive' : 'polite') : undefined}
      aria-atomic={isLiveRegion ? 'true' : undefined}
      onMouseEnter={pauseForPointer}
      onMouseLeave={resumeForPointer}
      onFocusCapture={pauseForFocus}
      onBlurCapture={resumeForFocus}
      {...gestureBindings}
      {...mergeProps(
        themeProps('toast', {type}),
        stylex.props(
          styles.root,
          !hasEntryStarted && styles.entering,
          isError ? styles.variantError : styles.variantDefault,
          isExiting && styles.exiting,
        ),
      )}>
      <MediaTheme mode="auto" fallback={fallbackMediaMode}>
        {renderContent ? (
          renderContent({
            body,
            endContent,
            type,
            isAutoHide,
            autoHideDuration,
            dismiss: handleDismiss,
          })
        ) : (
          <div {...stylex.props(styles.inner)}>
            <div {...stylex.props(styles.content)}>{body}</div>

            <div {...stylex.props(styles.endContent)}>
              {endContent}
              <Button
                variant="ghost"
                size="sm"
                icon={<Icon icon="close" size="sm" color="inherit" />}
                label={t('@astryx.toast.dismiss')}
                onClick={handleDismiss}
                isIconOnly
              />
            </div>
          </div>
        )}
      </MediaTheme>
    </div>
  );
}

Toast.displayName = 'Toast';
ToastSurface.displayName = 'ToastSurface';