@astryxdesign/core 0.0.0-bootstrap.0 → 0.1.0-canary.08d4cf4

package/src/Toast/Toast.tsx

@@ -0,0 +1,218 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useCallback, useEffect, useRef} from 'react';
+import type {ReactNode} 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 {useTheme} from '../theme';
+import {MediaTheme} from '../theme/MediaTheme';
+import type {ToastType, ToastDismissReason} from './types';
+import {themeProps} from '../utils/themeProps';
+
+const styles = stylex.create({
+  root: {
+    paddingBlock: spacingVars['--spacing-4'],
+    paddingInline: spacingVars['--spacing-4'],
+    borderRadius: radiusVars['--radius-container'],
+    width: 400,
+    maxWidth: 'min(100%, calc(100vw - 32px))',
+    boxShadow: shadowVars['--shadow-med'],
+    opacity: 1,
+    fontFamily: typographyVars['--font-family-body'],
+    fontSize: typeScaleDefaults['--text-body-size'],
+    lineHeight: typeScaleDefaults['--text-body-leading'],
+    transform: 'translateY(0)',
+    transitionProperty: 'opacity, transform',
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0.01ms',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
+    '@starting-style': {
+      opacity: 0,
+      transform: 'translateY(8px)',
+    },
+  },
+  variantDefault: {
+    backgroundColor: colorVars['--color-background-inverted'],
+  },
+  inner: {
+    display: 'flex',
+    alignItems: 'flex-start',
+    gap: spacingVars['--spacing-3'],
+    width: '100%',
+  },
+  variantError: {
+    backgroundColor: colorVars['--color-background-error-inverted'],
+  },
+  content: {
+    flex: 1,
+    minWidth: 0,
+  },
+  exiting: {
+    opacity: 0,
+    transform: 'translateY(-8px)',
+  },
+  endContent: {
+    flexShrink: 0,
+    display: 'flex',
+    alignItems: 'center',
+    gap: spacingVars['--spacing-2'],
+    marginBlock: `calc(${spacingVars['--spacing-1']} * -1)`,
+    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;
+}
+
+/**
+ * Individual toast notification.
+ *
+ * Renders with inverted surface colors for the default variant,
+ * and error-inverted for the error variant. Uses MediaTheme
+ * to set the correct token context for children. 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({
+  type,
+  body,
+  endContent,
+  isAutoHide,
+  autoHideDuration,
+  isExiting = false,
+  onDismiss,
+}: ToastProps) {
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const isPausedRef = useRef(false);
+  const remainingRef = useRef(autoHideDuration);
+  // Will be initialized by startTimer when actually used
+  const startTimeRef = useRef<number | null>(null);
+
+  const startTimer = useCallback(() => {
+    if (!isAutoHide) {
+      return;
+    }
+    if (timerRef.current) {
+      clearTimeout(timerRef.current);
+    }
+    startTimeRef.current = Date.now();
+    timerRef.current = setTimeout(() => {
+      onDismiss('auto');
+    }, remainingRef.current);
+  }, [isAutoHide, onDismiss]);
+
+  const pauseTimer = useCallback(() => {
+    if (!isAutoHide || isPausedRef.current) {
+      return;
+    }
+    isPausedRef.current = true;
+    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]);
+
+  const resumeTimer = useCallback(() => {
+    if (!isAutoHide || !isPausedRef.current) {
+      return;
+    }
+    isPausedRef.current = false;
+    startTimer();
+  }, [isAutoHide, startTimer]);
+
+  useEffect(() => {
+    remainingRef.current = autoHideDuration;
+    startTimer();
+    return () => {
+      if (timerRef.current) {
+        clearTimeout(timerRef.current);
+      }
+    };
+  }, [autoHideDuration, startTimer]);
+
+  const handleDismiss = useCallback(() => {
+    onDismiss('manual');
+  }, [onDismiss]);
+
+  const isError = type === 'error';
+  // Determine media mode: inverted surface is always dark in light mode,
+  // always light in dark mode. Error toast is always on a dark surface.
+  const {mode} = useTheme();
+  const mediaMode = isError || mode === 'light' ? 'dark' : 'light';
+
+  return (
+    <div
+      role={isError ? 'alert' : 'status'}
+      aria-live={isError ? 'assertive' : 'polite'}
+      aria-atomic="true"
+      onMouseEnter={pauseTimer}
+      onMouseLeave={resumeTimer}
+      onFocusCapture={pauseTimer}
+      onBlurCapture={resumeTimer}
+      {...mergeProps(
+        themeProps('toast', {type}),
+        stylex.props(
+          styles.root,
+          isError ? styles.variantError : styles.variantDefault,
+          isExiting && styles.exiting,
+        ),
+      )}>
+      <MediaTheme mode={mediaMode}>
+        <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="Dismiss notification"
+              onClick={handleDismiss}
+              isIconOnly
+            />
+          </div>
+        </div>
+      </MediaTheme>
+    </div>
+  );
+}
+
+Toast.displayName = 'Toast';

package/src/Toast/ToastContext.ts

@@ -0,0 +1,23 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {createContext} from 'react';
+import type {ToastEntry, ToastDismissReason} from './types';
+
+/** Internal context value for toast state management. */
+export interface ToastContextValue {
+  /** Add a toast. */
+  addToast: (entry: ToastEntry) => void;
+  /** Remove a toast by ID with a reason. */
+  removeToast: (id: string, reason: ToastDismissReason) => void;
+  /** Find a toast by uniqueID. */
+  findByUniqueID: (uniqueID: string) => ToastEntry | undefined;
+}
+
+/**
+ * React context for toast state. Default is null — the hook
+ * falls back to a self-mounting viewport when no provider exists.
+ */
+export const ToastContext = createContext<ToastContextValue | null>(null);
+ToastContext.displayName = 'ToastContext';

package/src/Toast/ToastViewport.tsx

@@ -0,0 +1,257 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useCallback, useEffect, useMemo, useRef, useState} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {spacingVars, durationVars, easeVars} from '../theme/tokens.stylex';
+import {mergeProps} from '../utils';
+import {Toast} from './Toast';
+import {ToastContext, type ToastContextValue} from './ToastContext';
+import type {
+  ToastEntry,
+  ToastPosition,
+  ToastDismissReason,
+} from './types';
+
+const styles = stylex.create({
+  viewport: {
+    position: 'fixed',
+    zIndex: 500,
+    display: 'flex',
+    flexDirection: 'column',
+    padding: spacingVars['--spacing-4'],
+    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',
+    margin: 0,
+    border: 'none',
+    background: 'none',
+    backgroundColor: 'transparent',
+    overflow: 'visible',
+  },
+  bottomEnd: {bottom: 0, insetInlineEnd: 0, alignItems: 'flex-end'},
+  bottomStart: {bottom: 0, insetInlineStart: 0, alignItems: 'flex-start'},
+  topEnd: {
+    top: 0,
+    insetInlineEnd: 0,
+    alignItems: 'flex-end',
+    flexDirection: 'column-reverse',
+  },
+  topStart: {
+    top: 0,
+    insetInlineStart: 0,
+    alignItems: 'flex-start',
+    flexDirection: 'column-reverse',
+  },
+  toastWrapper: {
+    pointerEvents: 'auto',
+    display: 'grid',
+    gridTemplateRows: '1fr',
+    paddingBlockEnd: spacingVars['--spacing-3'],
+    transitionProperty: 'grid-template-rows, padding',
+    transitionDuration: {
+      default: durationVars['--duration-fast'],
+      '@media (prefers-reduced-motion: reduce)': '0.01ms',
+    },
+    transitionTimingFunction: easeVars['--ease-standard'],
+    '@starting-style': {
+      gridTemplateRows: '0fr',
+      paddingBlockEnd: 0,
+    },
+  },
+  toastWrapperExiting: {
+    gridTemplateRows: '0fr',
+    paddingBlockEnd: 0,
+  },
+  toastWrapperInner: {
+    overflow: 'hidden',
+  },
+});
+
+export interface ToastViewportProps {
+  position?: ToastPosition;
+  maxVisible?: number;
+  inset?: {top?: number; bottom?: number; start?: number; end?: number};
+  /**
+   * Promote viewport to CSS top layer via popover="manual".
+   * Set to false when inside a dialog or other top-layer element.
+   * @default true
+   */
+  isTopLayer?: boolean;
+  children?: React.ReactNode;
+}
+
+/**
+ * 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,
+  isTopLayer = true,
+  children,
+}: ToastViewportProps) {
+  const [toasts, setToasts] = useState<ToastEntry[]>([]);
+  const [exitingIds, setExitingIds] = useState<Set<string>>(new Set());
+  const toastsRef = useRef(toasts);
+  toastsRef.current = toasts;
+
+  const addToast = useCallback((entry: ToastEntry) => {
+    setToasts(prev => {
+      const {uniqueID, collisionBehavior = 'overwrite'} = entry.options;
+      if (uniqueID) {
+        const existing = prev.find(t => t.options.uniqueID === uniqueID);
+        if (existing) {
+          if (collisionBehavior === 'ignore') {
+            return prev;
+          }
+          return prev.map(t => (t.options.uniqueID === uniqueID ? entry : t));
+        }
+      }
+      return [...prev, entry];
+    });
+  }, []);
+
+  const removeToast = useCallback(
+    (id: string, reason: ToastDismissReason) => {
+      const entry = toastsRef.current.find(t => t.id === id);
+      if (entry) {
+        entry.options.onHide?.(reason);
+      }
+      setExitingIds(prev => {
+        if (prev.has(id)) {
+          return prev;
+        }
+        return new Set(prev).add(id);
+      });
+    },
+    [],
+  );
+
+  const handleExited = useCallback((id: string) => {
+    setExitingIds(prev => {
+      if (!prev.has(id)) {
+        return prev;
+      }
+      const next = new Set(prev);
+      next.delete(id);
+      return next;
+    });
+    setToasts(prev => prev.filter(t => t.id !== id));
+  }, []);
+
+  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 = {};
+  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;
+  }
+
+  // Show the popover on mount so it enters the top layer
+  const viewportRef = useRef<HTMLDivElement>(null);
+  useEffect(() => {
+    if (!isTopLayer) {
+      return;
+    }
+    const el = viewportRef.current;
+    if (el && typeof el.showPopover === 'function') {
+      try {
+        el.showPopover();
+      } catch {
+        /* already showing */
+      }
+    }
+  }, [isTopLayer]);
+
+  const posStyle =
+    position === 'topEnd'
+      ? styles.topEnd
+      : position === 'topStart'
+        ? styles.topStart
+        : position === 'bottomStart'
+          ? styles.bottomStart
+          : styles.bottomEnd;
+
+  return (
+    <ToastContext value={contextValue}>
+      {children}
+      <div
+        ref={viewportRef}
+        role="region"
+        aria-label="Notifications"
+        // popover="manual" promotes to the top layer (above dialogs).
+        // Omitted inside dialogs where the viewport is already in a top layer.
+        popover={isTopLayer ? 'manual' : undefined}
+        {...mergeProps(stylex.props(styles.viewport, posStyle), {
+          style: Object.keys(insetStyle).length > 0 ? insetStyle : undefined,
+        })}>
+        {visibleToasts.map(entry => {
+          const o = entry.options;
+          const type = o.type ?? 'info';
+          const isAutoHide = o.isAutoHide ?? (type === 'error' ? false : true);
+          const dur = o.autoHideDuration ?? 5000;
+          const isExiting = exitingIds.has(entry.id);
+          return (
+            <div
+              key={entry.id}
+              {...stylex.props(
+                styles.toastWrapper,
+                isExiting && styles.toastWrapperExiting,
+              )}
+              onTransitionEnd={
+                isExiting
+                  ? (e: React.TransitionEvent) => {
+                      if (e.propertyName === 'grid-template-rows') {
+                        handleExited(entry.id);
+                      }
+                    }
+                  : undefined
+              }>
+              <div {...stylex.props(styles.toastWrapperInner)}>
+                <Toast
+                  type={type}
+                  body={o.body}
+                  endContent={o.endContent}
+                  isAutoHide={isAutoHide}
+                  autoHideDuration={dur}
+                  isExiting={isExiting}
+                  onDismiss={reason => removeToast(entry.id, reason)}
+                />
+              </div>
+            </div>
+          );
+        })}
+      </div>
+    </ToastContext>
+  );
+}
+ToastViewport.displayName = 'ToastViewport';

package/src/Toast/index.ts

@@ -0,0 +1,23 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+export {useToast} from './useToast';
+
+export type {
+  ToastType,
+  ToastPosition,
+  ToastCollisionBehavior,
+  ToastDismissReason,
+  ToastOptions,
+  ToastDismissFn,
+  ShowToastFn,
+} from './types';
+
+// Exported for LayerProvider integration
+export {ToastViewport} from './ToastViewport';
+export type {ToastViewportProps} from './ToastViewport';
+
+// Exported for inline rendering in previews and documentation
+export {Toast} from './Toast';
+export type {ToastProps} from './Toast';

package/src/Toast/types.ts

@@ -0,0 +1,65 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import type {ReactNode} from 'react';
+
+/** Toast status type. Controls color scheme. */
+export type ToastType = 'info' | 'error';
+
+/** Position for the toast stack relative to the viewport. */
+export type ToastPosition =
+  | 'topEnd'
+  | 'topStart'
+  | 'bottomEnd'
+  | 'bottomStart';
+
+/** Behavior when a toast with the same uniqueID already exists. */
+export type ToastCollisionBehavior = 'overwrite' | 'ignore';
+
+/** Reason why a toast was dismissed. */
+export type ToastDismissReason = 'auto' | 'manual';
+
+/** Options for showing a toast. */
+export interface ToastOptions {
+  /** Primary message content. */
+  body: ReactNode;
+  /**
+   * Toast type controlling color.
+   * @default 'info'
+   */
+  type?: ToastType;
+  /**
+   * Whether the toast auto-dismisses.
+   * Defaults to true for info, false for error.
+   */
+  isAutoHide?: boolean;
+  /**
+   * Duration in ms before auto-dismiss.
+   * @default 5000
+   */
+  autoHideDuration?: number;
+  /** Content rendered at the end of the toast (trailing slot). */
+  endContent?: ReactNode;
+
+  /** Unique identifier for deduplication. */
+  uniqueID?: string;
+  /**
+   * Behavior when a toast with matching uniqueID already exists.
+   * @default 'overwrite'
+   */
+  collisionBehavior?: ToastCollisionBehavior;
+  /** Callback fired when the toast is removed. */
+  onHide?: (reason: ToastDismissReason) => void;
+}
+
+/** Function to programmatically dismiss a toast. */
+export type ToastDismissFn = () => void;
+
+/** Function returned by useToast to show toasts. */
+export type ShowToastFn = (options: ToastOptions) => ToastDismissFn;
+
+/** Internal toast state with ID and metadata. */
+export interface ToastEntry {
+  id: string;
+  options: ToastOptions;
+  createdAt: number;
+}

package/src/Toast/useToast.doc.mjs

@@ -0,0 +1,49 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').HookDoc} */
+export const docs = {
+  name: 'useToast',
+  displayName: 'useToast',
+  group: 'Toast',
+  keywords: ['toast', 'notification', 'snackbar', 'alert', 'message', 'feedback', 'flash'],
+  params: [
+    // useToast takes no arguments; returns a show function
+  ],
+  returns: [
+    {
+      name: 'showToast',
+      type: '(options: ToastOptions) => () => void',
+      description: 'Show a toast notification. Returns a dismiss function. Options include body (ReactNode), type ("info" | "error"), isAutoHide, autoHideDuration, endContent, uniqueID, and collisionBehavior.',
+    },
+  ],
+  usage: {
+    description: 'Hook for showing toast notifications from anywhere in your component tree. Returns a function that accepts toast options and shows the notification. Works automatically with LayerProvider or self-mounts a fallback viewport.',
+    bestPractices: [
+      {guidance: true, description: 'Use for transient success/error feedback that does not require user action.'},
+      {guidance: true, description: 'Set uniqueID to deduplicate toasts from rapid user actions.'},
+      {guidance: false, description: 'Use for critical errors that require acknowledgment; use AlertDialog instead.'},
+      {guidance: false, description: 'Call useToast in the same component that renders LayerProvider; it must be called from a child component inside the provider.'},
+    ],
+  },
+  relatedComponents: ['Toast', 'Banner', 'AlertDialog'],
+  relatedHooks: [],
+  importPath: '@astryxdesign/core/Toast',
+  category: 'interaction',
+};
+
+/** @type {import('../docs-types').HookTranslationDoc} */
+export const docsDense = {
+  description: 'Show toast notifications from anywhere in component tree. Returns function accepting toast options + showing notification. Works automatically w/ LayerProvider / self-mounts fallback viewport.',
+  returnDescriptions: {
+    showToast: 'show toast notification. Returns dismiss function. Options: body (ReactNode), type ("info" | "error"), isAutoHide, autoHideDuration, endContent, uniqueID, collisionBehavior.',
+  },
+  usage: {
+    description: 'Show toast notifications from anywhere in component tree. Returns function accepting toast options + showing notification. Works automatically w/ LayerProvider / self-mounts fallback viewport.',
+    bestPractices: [
+      {guidance: true, description: 'Use for transient success/error feedback not requiring user action.'},
+      {guidance: true, description: 'Set uniqueID to deduplicate toasts from rapid user actions.'},
+      {guidance: false, description: 'Use for critical errors requiring acknowledgment; use AlertDialog instead.'},
+      {guidance: false, description: 'Call useToast in same component that renders LayerProvider; must be called from child component inside provider.'},
+    ],
+  },
+};