@eocrm/design-system 0.0.0-stage → 0.6.17

package/src/components/Toast/Toast.module.scss

@@ -0,0 +1,299 @@
+@use '../../styles/mixins' as *;
+@use './Toast.tokens';
+
+// ─── Viewport stacks ─────────────────────────────────────────────────────
+.stack {
+  // stylelint-disable-next-line declaration-property-value-disallowed-list -- viewport owns its own positioning, not a flow component
+  position: fixed;
+  z-index: var(--z-toast);
+  display: flex;
+  flex-direction: column;
+  list-style: none;
+  // stylelint-disable-next-line property-disallowed-list -- stack resets browser default list margin; not consumer layout
+  margin: 0;
+  padding: 0;
+  pointer-events: none; // stack itself doesn't intercept clicks
+  max-width: calc(100vw - 2 * var(--toast-viewport-inset));
+  width: 360px;
+}
+
+.stack > li {
+  pointer-events: auto;
+}
+
+// Position variants — fixed positioning. Top-anchored stacks grow downward
+// (newest farther from edge); bottom-anchored grow upward via column-reverse.
+
+.posTopLeft {
+  top: var(--toast-viewport-inset);
+  left: var(--toast-viewport-inset);
+}
+
+.posTopCenter {
+  top: var(--toast-viewport-inset);
+  left: 50%;
+  transform: translateX(-50%);
+}
+
+.posTopRight {
+  top: var(--toast-viewport-inset);
+  right: var(--toast-viewport-inset);
+}
+
+.posBottomLeft {
+  bottom: var(--toast-viewport-inset);
+  left: var(--toast-viewport-inset);
+  flex-direction: column-reverse;
+}
+
+.posBottomCenter {
+  bottom: var(--toast-viewport-inset);
+  left: 50%;
+  transform: translateX(-50%);
+  flex-direction: column-reverse;
+}
+
+.posBottomRight {
+  bottom: var(--toast-viewport-inset);
+  right: var(--toast-viewport-inset);
+  flex-direction: column-reverse;
+}
+
+// Gap between stacked toasts. column-reverse stacks need margin-bottom
+// instead of margin-top to space the same way visually.
+.gapSm > li + li {
+  // stylelint-disable-next-line property-disallowed-list -- gap between sibling toasts; internal to viewport stack
+  margin-top: var(--toast-viewport-gap-sm);
+}
+
+.gapMd > li + li {
+  // stylelint-disable-next-line property-disallowed-list -- gap between sibling toasts; internal to viewport stack
+  margin-top: var(--toast-viewport-gap-md);
+}
+
+.posBottomLeft.gapSm > li + li,
+.posBottomCenter.gapSm > li + li,
+.posBottomRight.gapSm > li + li {
+  // stylelint-disable-next-line property-disallowed-list -- gap between sibling toasts in reversed stack; internal
+  margin-top: 0;
+  // stylelint-disable-next-line property-disallowed-list -- gap between sibling toasts in reversed stack; internal
+  margin-bottom: var(--toast-viewport-gap-sm);
+}
+
+.posBottomLeft.gapMd > li + li,
+.posBottomCenter.gapMd > li + li,
+.posBottomRight.gapMd > li + li {
+  // stylelint-disable-next-line property-disallowed-list -- gap between sibling toasts in reversed stack; internal
+  margin-top: 0;
+  // stylelint-disable-next-line property-disallowed-list -- gap between sibling toasts in reversed stack; internal
+  margin-bottom: var(--toast-viewport-gap-md);
+}
+
+// ─── Toast card ─────────────────────────────────────────────────────────
+.toast {
+  display: grid;
+  grid-template-columns: auto 1fr auto;
+  gap: var(--toast-gap);
+
+  // Centers the icon and close button against the body (vs. top-aligned
+  // start, which left the leading visually high relative to the message's
+  // line-height: 1.4 baseline). For 2-line toasts (message + description)
+  // the icon centers between the two lines — same pattern as Sonner /
+  // react-hot-toast.
+  align-items: center;
+  padding: var(--toast-padding);
+  background: var(--toast-bg);
+  border-radius: var(--toast-radius);
+  box-shadow: var(--toast-shadow);
+  border-left: var(--toast-border-width) solid var(--toast-border-color); // overridden per tone
+  color: var(--toast-fg);
+  transition: transform 200ms ease-out;
+}
+
+.toneInfo {
+  border-left-color: var(--toast-border-color-info);
+}
+
+.toneSuccess {
+  border-left-color: var(--toast-border-color-success);
+}
+
+.toneWarning {
+  border-left-color: var(--toast-border-color-warning);
+}
+
+.toneError {
+  border-left-color: var(--toast-border-color-danger);
+}
+
+.toneLoading {
+  border-left-color: var(--toast-border-color-loading);
+}
+
+.icon {
+  color: var(--toast-icon);
+  display: grid;
+  place-items: center;
+}
+
+.toneInfo .icon {
+  color: var(--toast-icon-info);
+}
+
+.toneSuccess .icon {
+  color: var(--toast-icon-success);
+}
+
+.toneWarning .icon {
+  color: var(--toast-icon-warning);
+}
+
+.toneError .icon {
+  color: var(--toast-icon-danger);
+}
+
+.body {
+  min-width: 0; // allow text truncation inside grid
+}
+
+.message {
+  font-size: var(--toast-message-font-size);
+  font-weight: var(--toast-message-font-weight);
+  line-height: 1.4;
+}
+
+.description {
+  font-size: var(--toast-description-font-size);
+  color: var(--toast-description-fg);
+  // stylelint-disable-next-line property-disallowed-list -- internal spacing within the toast body; not consumer layout
+  margin-top: var(--toast-description-gap);
+  display: -webkit-box;
+  -webkit-line-clamp: 2;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+}
+
+.tail {
+  display: flex;
+  align-items: center;
+  gap: var(--toast-tail-gap);
+}
+
+// ─── Enter / exit animations ─────────────────────────────────────────────
+// Slide direction depends on the position. We expose six keyframes and pick
+// via [data-position] on the parent stack.
+
+@keyframes enter-from-right {
+  from {
+    transform: translateX(30px);
+    opacity: var(--toast-opacity-enter-exit);
+  }
+}
+
+@keyframes enter-from-left {
+  from {
+    transform: translateX(-30px);
+    opacity: var(--toast-opacity-enter-exit);
+  }
+}
+
+@keyframes enter-from-top {
+  from {
+    transform: translateY(-30px);
+    opacity: var(--toast-opacity-enter-exit);
+  }
+}
+
+@keyframes enter-from-bottom {
+  from {
+    transform: translateY(30px);
+    opacity: var(--toast-opacity-enter-exit);
+  }
+}
+
+@keyframes exit-to-right {
+  to {
+    transform: translateX(30px);
+    opacity: var(--toast-opacity-enter-exit);
+  }
+}
+
+@keyframes exit-to-left {
+  to {
+    transform: translateX(-30px);
+    opacity: var(--toast-opacity-enter-exit);
+  }
+}
+
+[data-position='top-left'] .toast[data-status='visible'],
+[data-position='bottom-left'] .toast[data-status='visible'] {
+  animation: enter-from-left 300ms cubic-bezier(0.22, 1, 0.36, 1);
+}
+
+[data-position='top-right'] .toast[data-status='visible'],
+[data-position='bottom-right'] .toast[data-status='visible'] {
+  animation: enter-from-right 300ms cubic-bezier(0.22, 1, 0.36, 1);
+}
+
+[data-position='top-center'] .toast[data-status='visible'] {
+  animation: enter-from-top 300ms cubic-bezier(0.22, 1, 0.36, 1);
+}
+
+[data-position='bottom-center'] .toast[data-status='visible'] {
+  animation: enter-from-bottom 300ms cubic-bezier(0.22, 1, 0.36, 1);
+}
+
+[data-position='top-left'] .toast[data-status='exiting'],
+[data-position='bottom-left'] .toast[data-status='exiting'] {
+  animation: exit-to-left 250ms ease-in forwards;
+}
+
+[data-position='top-right'] .toast[data-status='exiting'],
+[data-position='bottom-right'] .toast[data-status='exiting'] {
+  animation: exit-to-right 250ms ease-in forwards;
+}
+
+[data-position='top-center'] .toast[data-status='exiting'],
+[data-position='bottom-center'] .toast[data-status='exiting'] {
+  animation: exit-to-right 250ms ease-in forwards;
+}
+
+// Peek-collapsed toasts (beyond maxVisible). Compressed and dimmed.
+.toast[data-peek='true'] {
+  transform: scale(0.95) translateY(8px);
+  opacity: var(--toast-opacity-peek);
+  pointer-events: none;
+}
+
+.stack[data-expanded='true'] .toast[data-peek='true'] {
+  transform: none;
+  opacity: var(--toast-opacity-peek-expanded);
+  pointer-events: auto;
+}
+
+// ─── Reduced motion — kill enter/exit animations + the reflow transition ─
+@media (prefers-reduced-motion: reduce) {
+  .toast,
+  [data-position] .toast[data-status='visible'],
+  [data-position] .toast[data-status='exiting'] {
+    animation: none;
+    transition: none;
+  }
+
+  // The loading spinner rotates continuously — exactly the kind of persistent
+  // motion that causes issues for vestibular-sensitivity and migraine sufferers.
+  .spin {
+    animation: none;
+  }
+}
+
+// ─── Loading spinner ─────────────────────────────────────────────────────
+.spin {
+  animation: spin 1s linear infinite;
+}
+
+@keyframes spin {
+  to {
+    transform: rotate(360deg);
+  }
+}

package/src/components/Toast/Toast.tokens.scss

@@ -0,0 +1,65 @@
+// Toast.tokens.scss — Component-scoped tokens for <Toast>. Per-tone border + icon color pairs (info/success/warning/danger), plus shared shape, sizing, and viewport-stack spacing. Each token defaults to the primitive the SCSS used before this migration.
+:root {
+  // Toast card surface
+  --toast-bg: var(--color-bg);
+  --toast-fg: var(--color-fg);
+  --toast-border-color: var(--color-fg-muted);
+  --toast-border-width: var(--border-width-strong);
+  --toast-radius: var(--radius-md);
+  --toast-shadow: var(--shadow-md);
+  --toast-padding: var(--space-3);
+  --toast-gap: var(--space-2);
+
+  // Toast typography
+  --toast-message-font-size: var(--font-size-md);
+  --toast-message-font-weight: var(--font-weight-medium);
+  --toast-description-font-size: var(--font-size-sm);
+  --toast-description-fg: var(--color-fg-muted);
+  --toast-description-gap: var(--space-1);
+
+  // Leading icon
+  --toast-icon: var(--color-fg-muted);
+
+  // Tail (action + close cluster)
+  --toast-tail-gap: var(--space-2);
+
+  // Per-tone surfaces (background + border + icon + fg)
+  --toast-bg-info: var(--color-bg);
+  --toast-fg-info: var(--color-fg);
+  --toast-icon-info: var(--color-info);
+  --toast-border-color-info: var(--color-info);
+
+  --toast-bg-success: var(--color-bg);
+  --toast-fg-success: var(--color-fg);
+  --toast-icon-success: var(--color-success);
+  --toast-border-color-success: var(--color-success);
+
+  --toast-bg-warning: var(--color-bg);
+  --toast-fg-warning: var(--color-fg);
+
+  // @contrast --color-warning on --color-bg = 2.14:1 light
+  // @contrast --color-warning-strong on --color-bg = 5.95:1 light
+  // warning uses --color-warning-strong; the bare --color-warning measures 2.14:1 here, below
+  // WCAG AA for text and below 1.4.11's 3:1 for a graphical object. See #481.
+  --toast-icon-warning: var(--color-warning-strong);
+  --toast-border-color-warning: var(--color-warning-strong);
+
+  --toast-bg-danger: var(--color-bg);
+  --toast-fg-danger: var(--color-fg);
+  --toast-icon-danger: var(--color-danger);
+  --toast-border-color-danger: var(--color-danger);
+
+  // Loading tone (spinner state) — non-semantic tone, kept for parity
+  --toast-icon-loading: var(--color-fg-muted);
+  --toast-border-color-loading: var(--color-fg-muted);
+
+  // Viewport stack — edge insets + inter-toast gaps
+  --toast-viewport-inset: var(--space-3);
+  --toast-viewport-gap-sm: var(--space-2);
+  --toast-viewport-gap-md: var(--space-3);
+
+  // Animation + peek opacity
+  --toast-opacity-enter-exit: var(--opacity-hidden);
+  --toast-opacity-peek: var(--opacity-subtle);
+  --toast-opacity-peek-expanded: var(--opacity-visible);
+}

package/src/components/Toast/Toast.tsx

@@ -0,0 +1,122 @@
+import { useState } from 'react';
+import { AlertTriangle, CheckCircle2, Info, Loader2, X, XCircle } from 'lucide-react';
+import clsx from 'clsx';
+import { Button } from '../Button';
+import { useTranslation } from '../../i18n/useTranslation';
+import { store, type ToastEntry } from './store';
+import { useToastTimer } from './useToastTimer';
+import styles from './Toast.module.scss';
+
+interface ToastProps {
+  entry: ToastEntry;
+  /** Whether this toast is rendered as a peek-collapsed card (beyond maxVisible). */
+  isPeek: boolean;
+  /** Default fallback duration when entry.duration is 'persistent' but rendered;
+   *  forwarded by the viewport for completeness, unused here today. */
+  // viewportDuration: number;  // (reserved for future use; not in v1)
+}
+
+const DEFAULT_ICONS: Record<ToastEntry['tone'], typeof Info> = {
+  info: Info,
+  success: CheckCircle2,
+  warning: AlertTriangle,
+  error: XCircle,
+  loading: Loader2,
+};
+
+/**
+ * Single toast card. NOT exported from the package — internal to ToastViewport.
+ *
+ * Spread order: Pattern B (component owns ARIA contract — role, aria-live,
+ * data-* cannot be overridden by consumer props).
+ */
+export function Toast({ entry, isPeek }: ToastProps) {
+  const t = useTranslation();
+  // Local "should the timer run" — flips when the user hovers OR a child has focus.
+  const [paused, setPaused] = useState(false);
+
+  useToastTimer({
+    id: entry.id,
+    duration: entry.duration,
+    paused,
+    onExpire: () => store.dismiss(entry.id),
+  });
+
+  const role = entry.tone === 'error' ? 'alert' : 'status';
+  const ariaLive = entry.tone === 'error' ? 'assertive' : 'polite';
+
+  const IconComponent = DEFAULT_ICONS[entry.tone];
+  const renderedIcon =
+    entry.icon === null
+      ? null
+      : (entry.icon ?? (
+          <IconComponent
+            size={16}
+            aria-hidden="true"
+            className={entry.tone === 'loading' ? styles.spin : undefined}
+          />
+        ));
+
+  const toneClass = {
+    info: styles.toneInfo,
+    success: styles.toneSuccess,
+    warning: styles.toneWarning,
+    error: styles.toneError,
+    loading: styles.toneLoading,
+  }[entry.tone];
+
+  return (
+    <li
+      role={role}
+      aria-live={ariaLive}
+      aria-atomic="true"
+      data-status={entry.status}
+      data-peek={isPeek ? 'true' : undefined}
+      data-tone={entry.tone}
+      className={clsx(styles.toast, toneClass)}
+      onMouseEnter={() => setPaused(true)}
+      onMouseLeave={() => setPaused(false)}
+      onFocus={() => setPaused(true)}
+      onBlur={(e) => {
+        // Only un-pause when focus leaves the toast entirely, not when moving
+        // from action button to close button.
+        if (!e.currentTarget.contains(e.relatedTarget as Node | null)) {
+          setPaused(false);
+        }
+      }}
+    >
+      {renderedIcon && <div className={styles.icon}>{renderedIcon}</div>}
+
+      <div className={styles.body}>
+        <div className={styles.message}>{entry.message}</div>
+        {entry.description && <div className={styles.description}>{entry.description}</div>}
+      </div>
+
+      <div className={styles.tail}>
+        {entry.action && (
+          <Button
+            variant="secondary"
+            size="xs"
+            onClick={() => {
+              entry.action!.onClick();
+              store.dismiss(entry.id);
+            }}
+          >
+            {entry.action.label}
+          </Button>
+        )}
+        {entry.dismissible && (
+          <Button
+            variant="ghost"
+            size="xs"
+            iconOnly
+            aria-label={t('toast.dismiss')}
+            onClick={() => store.dismiss(entry.id)}
+          >
+            <X size={14} aria-hidden="true" />
+          </Button>
+        )}
+      </div>
+    </li>
+  );
+}

package/src/components/Toast/ToastViewport.tsx

@@ -0,0 +1,166 @@
+import { useEffect, useLayoutEffect, useRef, useState, useSyncExternalStore } from 'react';
+import { createPortal } from 'react-dom';
+import clsx from 'clsx';
+import { useTranslation } from '../../i18n/useTranslation';
+import { _setViewportConfig } from './api';
+import { store, type ToastEntry, type ToastPosition } from './store';
+import { Toast } from './Toast';
+import styles from './Toast.module.scss';
+
+const POSITIONS: readonly ToastPosition[] = [
+  'top-left',
+  'top-center',
+  'top-right',
+  'bottom-left',
+  'bottom-center',
+  'bottom-right',
+];
+
+const POSITION_CLASS: Record<ToastPosition, string> = {
+  'top-left': styles.posTopLeft,
+  'top-center': styles.posTopCenter,
+  'top-right': styles.posTopRight,
+  'bottom-left': styles.posBottomLeft,
+  'bottom-center': styles.posBottomCenter,
+  'bottom-right': styles.posBottomRight,
+};
+
+// Committed viewports in mount order; the first one renders. Registered in a
+// layout effect, never during render: a render React discards (Suspense,
+// StrictMode, concurrent restarts) runs no effects, so it can't leak a slot
+// and silence every toast (#562).
+let viewports: readonly object[] = [];
+const viewportListeners = new Set<() => void>();
+function setViewports(next: readonly object[]) {
+  viewports = next;
+  viewportListeners.forEach((l) => l());
+}
+function subscribeViewports(listener: () => void) {
+  viewportListeners.add(listener);
+  return () => viewportListeners.delete(listener);
+}
+
+export interface ToastViewportProps {
+  /**
+   * Default position for toasts that don't specify one. Default: 'bottom-right'.
+   * All 6 positions are supported; a per-call `position` is an escape hatch —
+   * a single global position is the recommended UX.
+   */
+  position?: ToastPosition;
+  /** Default duration (ms) for toasts without explicit duration. Default: 4000. */
+  duration?: number;
+  /** How many toasts are fully visible per position bucket. Default: 3. */
+  maxVisible?: number;
+  /** Spacing between stacked toasts. Default: 'sm' (8px). */
+  gap?: 'sm' | 'md';
+  /** false (default): peek-collapsed stack, hover to fan out. true: always fanned. */
+  expand?: boolean;
+}
+
+/**
+ * The single Toast portal; mount exactly one at the app root.
+ * @see docs/components/ToastViewport.md
+ */
+export function ToastViewport({
+  position = 'bottom-right',
+  duration = 4000,
+  maxVisible = 3,
+  gap = 'sm',
+  expand = false,
+}: ToastViewportProps) {
+  const t = useTranslation();
+  const [id] = useState(() => ({}));
+  const isFirstViewport = useSyncExternalStore(
+    subscribeViewports,
+    () => viewports[0] === id,
+    () => false,
+  );
+
+  useLayoutEffect(() => {
+    setViewports([...viewports, id]);
+    if (viewports[0] !== id && process.env.NODE_ENV !== 'production') {
+      console.error(
+        '[ToastViewport] Multiple <ToastViewport> instances detected. Only the first one renders. Mount exactly one at your app root.',
+      );
+    }
+    return () => setViewports(viewports.filter((v) => v !== id));
+  }, [id]);
+
+  useEffect(() => {
+    _setViewportConfig({ position, duration });
+  }, [position, duration]);
+
+  const state = useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot);
+
+  const [hovered, setHovered] = useState<Set<ToastPosition>>(() => new Set());
+  // useRef instead of state so we don't trigger an extra render
+  // when the portal target appears.
+  const portalTargetRef = useRef<HTMLElement | null>(null);
+  if (portalTargetRef.current === null && typeof document !== 'undefined') {
+    portalTargetRef.current = document.body;
+  }
+
+  if (!isFirstViewport) return null;
+  if (portalTargetRef.current === null) return null;
+
+  const buckets = groupByPosition(state.toasts);
+
+  const content = (
+    <>
+      {POSITIONS.map((pos) => {
+        const list = buckets[pos];
+        if (!list || list.length === 0) return null;
+        const isExpanded = expand || hovered.has(pos);
+        return (
+          <ol
+            key={pos}
+            className={clsx(
+              styles.stack,
+              POSITION_CLASS[pos],
+              gap === 'sm' ? styles.gapSm : styles.gapMd,
+            )}
+            aria-label={t('toast.notifications')}
+            data-position={pos}
+            data-expanded={isExpanded ? 'true' : 'false'}
+            onMouseEnter={() => {
+              setHovered((prev) => {
+                if (prev.has(pos)) return prev;
+                const next = new Set(prev);
+                next.add(pos);
+                return next;
+              });
+            }}
+            onMouseLeave={() => {
+              setHovered((prev) => {
+                if (!prev.has(pos)) return prev;
+                const next = new Set(prev);
+                next.delete(pos);
+                return next;
+              });
+            }}
+          >
+            {list.map((entry, idx) => (
+              <Toast
+                key={`${entry.id}:${entry.createdAt}`}
+                entry={entry}
+                isPeek={!isExpanded && idx >= maxVisible}
+              />
+            ))}
+          </ol>
+        );
+      })}
+    </>
+  );
+
+  return createPortal(content, portalTargetRef.current);
+}
+
+function groupByPosition(
+  toasts: readonly ToastEntry[],
+): Partial<Record<ToastPosition, ToastEntry[]>> {
+  const out: Partial<Record<ToastPosition, ToastEntry[]>> = {};
+  for (const t of toasts) {
+    (out[t.position] ??= []).push(t);
+  }
+  return out;
+}