@eocrm/design-system 0.0.0-stage → 0.6.18

package/src/components/Toast/api.ts

@@ -0,0 +1,175 @@
+import type { ReactNode } from 'react';
+import { store, generateId, type ToastTone, type ToastPosition, type ToastInput } from './store';
+
+export interface ToastOptions {
+  /** Optional second-line content. ReactNode so consumers can embed links/icons. */
+  description?: ReactNode;
+  /** Auto-dismiss timeout (ms) or `'persistent'` for no auto-dismiss. Default: 4000. */
+  duration?: number | 'persistent';
+  /** Per-call override of the viewport's default position. */
+  position?: ToastPosition;
+  /** Stable id (else auto-generated). Reusing a live toast's id updates it in place;
+   *  reusing the id of a toast that is still animating out shows it again as new. */
+  id?: string;
+  /** Single primary action button rendered inside the toast. */
+  action?: { label: string; onClick: () => void };
+  /** Show the close (×) button. Default: true. Forced true when `duration: 'persistent'`. */
+  dismissible?: boolean;
+  /** Override the tone's default icon. Pass `null` to hide. */
+  icon?: ReactNode | null;
+}
+
+/**
+ * Partial shape accepted by `toast.update`. Any writable field of a live toast
+ * may be changed. The `id`, `createdAt`, and `status` fields are managed
+ * internally and cannot be patched directly through this type.
+ */
+export type ToastUpdateOptions = Partial<
+  Omit<ToastOptions, 'id'> & { message: ReactNode; tone: ToastTone }
+>;
+
+interface ViewportConfig {
+  position: ToastPosition;
+  duration: number;
+}
+
+/** Mutable defaults written by ToastViewport on mount. Module-level so the API
+ *  layer can read them without depending on React. If no viewport mounts, the
+ *  constants below stand in — toasts fired into the void are stored but never
+ *  rendered, which is the correct behavior. */
+let viewportConfig: ViewportConfig = { position: 'bottom-right', duration: 4000 };
+
+/** Called by ToastViewport. NOT exported from the package barrel. */
+export function _setViewportConfig(cfg: ViewportConfig): void {
+  viewportConfig = cfg;
+}
+
+function buildInput(tone: ToastTone, message: ReactNode, options: ToastOptions = {}): ToastInput {
+  const isLoading = tone === 'loading';
+  const duration = options.duration ?? (isLoading ? 'persistent' : viewportConfig.duration);
+  const isPersistent = duration === 'persistent';
+  return {
+    id: options.id ?? generateId(),
+    tone,
+    message,
+    description: options.description,
+    duration,
+    position: options.position ?? viewportConfig.position,
+    action: options.action,
+    // Persistent toasts force dismissible: true so the user has a way out.
+    dismissible: isPersistent ? true : (options.dismissible ?? true),
+    icon: options.icon,
+  };
+}
+
+function fire(tone: ToastTone, message: ReactNode, options?: ToastOptions): string {
+  return store.add(buildInput(tone, message, options));
+}
+
+type PromiseMessages<T> = {
+  loading: string;
+  success: string | ((value: T) => string);
+  error: string | ((err: unknown) => string);
+  options?: Omit<ToastOptions, 'duration'>;
+};
+
+/**
+ * Fire an informational toast (the default tone). Equivalent to `toast.info(message, options)`.
+ *
+ * All `toast.*` methods return the toast id (string) so it can be passed to
+ * `toast.update` or `toast.dismiss` later.
+ *
+ * @example
+ * // Quick one-liner
+ * toast('Profile saved');
+ *
+ * @example
+ * // With a description and action
+ * toast('File deleted', {
+ *   description: 'This action cannot be undone.',
+ *   action: { label: 'Undo', onClick: handleUndo },
+ * });
+ */
+export const toast = Object.assign(
+  (message: ReactNode, options?: ToastOptions): string => fire('info', message, options),
+  {
+    /**
+     * Fire an informational toast. Returns the toast id.
+     */
+    info: (m: ReactNode, o?: ToastOptions): string => fire('info', m, o),
+    /**
+     * Fire a success toast. Returns the toast id.
+     */
+    success: (m: ReactNode, o?: ToastOptions): string => fire('success', m, o),
+    /**
+     * Fire a warning toast. Returns the toast id.
+     */
+    warning: (m: ReactNode, o?: ToastOptions): string => fire('warning', m, o),
+    /**
+     * Fire an error toast. Returns the toast id. Error toasts use `role="alert"`
+     * and `aria-live="assertive"` for immediate screen-reader announcement.
+     */
+    error: (m: ReactNode, o?: ToastOptions): string => fire('error', m, o),
+    /**
+     * Fire a loading toast. Returns the toast id. Defaults to
+     * `duration: 'persistent'` — the toast stays until explicitly updated or
+     * dismissed (e.g. via `toast.update` once the async work completes).
+     */
+    loading: (m: ReactNode, o?: ToastOptions): string => fire('loading', m, o),
+    /**
+     * Mutate a live toast by id. Any field in `ToastUpdateOptions` may be
+     * patched. Commonly used to transition a loading toast to success/error
+     * once an async operation settles.
+     *
+     * If the id does not correspond to a currently-stored toast the call is a
+     * no-op — there is no resurrection of dismissed toasts.
+     */
+    update: (id: string, partial: ToastUpdateOptions): void => {
+      store.update(id, partial);
+    },
+    /**
+     * Dismiss a toast by id. If `id` is omitted, all currently visible toasts
+     * are dismissed at once. The toast plays its exit animation before being
+     * removed from the store.
+     */
+    dismiss: (id?: string): void => store.dismiss(id),
+    /**
+     * Track a promise with automatic loading → success/error transitions.
+     * Returns the original promise so the call is awaitable and chainable.
+     * Rejections are re-thrown after updating the toast to the error state —
+     * callers should handle them with `.catch()` if they don't want an
+     * unhandled-rejection warning.
+     *
+     * @example
+     * await toast.promise(uploadFile(file), {
+     *   loading: 'Uploading…',
+     *   success: (res) => `Uploaded ${res.filename}`,
+     *   error: (err) => `Upload failed: ${err.message}`,
+     * });
+     */
+    promise<T>(p: Promise<T>, msgs: PromiseMessages<T>): Promise<T> {
+      const id = fire('loading', msgs.loading, msgs.options);
+      return p.then(
+        (value) => {
+          const successMsg =
+            typeof msgs.success === 'function' ? msgs.success(value) : msgs.success;
+          store.update(id, {
+            tone: 'success',
+            message: successMsg,
+            duration: viewportConfig.duration,
+          });
+          return value;
+        },
+        (err) => {
+          const errorMsg = typeof msgs.error === 'function' ? msgs.error(err) : msgs.error;
+          store.update(id, {
+            tone: 'error',
+            message: errorMsg,
+            duration: viewportConfig.duration,
+          });
+          throw err;
+        },
+      );
+    },
+  },
+);

package/src/components/Toast/index.ts

@@ -0,0 +1,5 @@
+export { toast } from './api';
+export { ToastViewport } from './ToastViewport';
+export type { ToastOptions, ToastUpdateOptions } from './api';
+export type { ToastViewportProps } from './ToastViewport';
+export type { ToastTone, ToastPosition } from './store';

package/src/components/Toast/store.ts

@@ -0,0 +1,133 @@
+import type { ReactNode } from 'react';
+
+export type ToastTone = 'info' | 'success' | 'warning' | 'error' | 'loading';
+
+export type ToastPosition =
+  | 'top-left'
+  | 'top-center'
+  | 'top-right'
+  | 'bottom-left'
+  | 'bottom-center'
+  | 'bottom-right';
+
+export interface ToastEntry {
+  id: string;
+  tone: ToastTone;
+  message: ReactNode;
+  description?: ReactNode;
+  duration: number | 'persistent';
+  position: ToastPosition;
+  action?: { label: string; onClick: () => void };
+  dismissible: boolean;
+  icon?: ReactNode | null;
+  createdAt: number;
+  status: 'visible' | 'exiting';
+}
+
+/** Input shape accepted by `store.add` — `createdAt` and `status` are computed internally. */
+export type ToastInput = Omit<ToastEntry, 'createdAt' | 'status'>;
+
+/** Partial shape accepted by `store.update`. `status` is owned by `dismiss` (and a
+ *  re-`add`), so an update never resurrects a dismissed toast. */
+export type ToastUpdate = Partial<Omit<ToastEntry, 'id' | 'createdAt' | 'status'>>;
+
+type Listener = () => void;
+
+interface StoreState {
+  toasts: readonly ToastEntry[];
+}
+
+/** Duration of the exit animation. The store delays full removal by this many ms
+ *  so the viewport can animate `data-status="exiting"` before unmount. */
+export const EXIT_ANIMATION_MS = 250;
+
+let state: StoreState = { toasts: [] };
+const listeners = new Set<Listener>();
+/** Exiting id → the id set its pending removal will delete. Re-adding the id
+ *  drops it from that set, cancelling its removal. */
+const pendingExit = new Map<string, Set<string>>();
+
+function notify() {
+  listeners.forEach((l) => l());
+}
+
+let nextSeq = 0;
+/** Generates a short id with millisecond timestamp + monotonic counter so
+ *  rapid-fire calls within the same ms never collide. */
+export function generateId(): string {
+  return `t${Date.now().toString(36)}${(++nextSeq).toString(36)}`;
+}
+
+export const store = {
+  getSnapshot(): StoreState {
+    return state;
+  },
+  subscribe(listener: Listener): () => void {
+    listeners.add(listener);
+    return () => {
+      listeners.delete(listener);
+    };
+  },
+  add(input: ToastInput): string {
+    const existing = state.toasts.find((t) => t.id === input.id);
+    // Re-firing an id mid-exit shows it again as a fresh toast. The new
+    // `createdAt` is part of the viewport's React key, so it remounts with a
+    // fresh auto-dismiss timer.
+    if (existing?.status === 'exiting') {
+      pendingExit.get(input.id)?.delete(input.id);
+      pendingExit.delete(input.id);
+      const createdAt = Math.max(Date.now(), existing.createdAt + 1);
+      state = {
+        toasts: state.toasts.map((t) =>
+          t.id === input.id ? { ...input, createdAt, status: 'visible' } : t,
+        ),
+      };
+      notify();
+      return input.id;
+    }
+    // Reusing a live id is an implicit update — lets `toast.success('done', { id })`
+    // mutate an existing loading toast in place.
+    if (existing) return store.update(input.id, input);
+    const entry: ToastEntry = { ...input, createdAt: Date.now(), status: 'visible' };
+    state = { toasts: [...state.toasts, entry] };
+    notify();
+    return entry.id;
+  },
+  update(id: string, partial: ToastUpdate): string {
+    state = {
+      toasts: state.toasts.map((t) => (t.id === id ? { ...t, ...partial } : t)),
+    };
+    notify();
+    return id;
+  },
+  dismiss(id?: string): void {
+    // Capture the ids now so the deferred removal can't take toasts added
+    // during the exit window (#713). Already-exiting toasts keep their pending
+    // removal rather than arming a second one.
+    const ids = new Set(
+      state.toasts
+        .filter((t) => t.status !== 'exiting' && (id === undefined || t.id === id))
+        .map((t) => t.id),
+    );
+    if (ids.size === 0) return;
+    state = {
+      toasts: state.toasts.map((t) => (ids.has(t.id) ? { ...t, status: 'exiting' } : t)),
+    };
+    notify();
+    ids.forEach((exitId) => pendingExit.set(exitId, ids));
+    setTimeout(() => {
+      if (ids.size === 0) return;
+      ids.forEach((exitId) => pendingExit.delete(exitId));
+      state = { toasts: state.toasts.filter((t) => !ids.has(t.id)) };
+      notify();
+    }, EXIT_ANIMATION_MS);
+  },
+  /** Test-only: synchronously clears state. NOT exported from the package. */
+  _reset(): void {
+    state = { toasts: [] };
+    pendingExit.forEach((ids) => ids.clear());
+    pendingExit.clear();
+    nextSeq = 0;
+    listeners.clear();
+  },
+};

package/src/components/Toast/useToastTimer.ts

@@ -0,0 +1,94 @@
+import { useEffect, useRef } from 'react';
+
+interface UseToastTimerArgs {
+  /** Toast id — used purely as a stable dependency key. */
+  id: string;
+  /** ms or 'persistent'. Persistent skips the timer entirely. */
+  duration: number | 'persistent';
+  /** Whether the timer is currently paused (hover / focus / hidden tab). */
+  paused: boolean;
+  /** Called when the timer expires. */
+  onExpire: () => void;
+  /** Indirection so tests can mock visibility without poking jsdom internals.
+   *  Defaults to `document.visibilityState === 'visible'`. */
+  getVisible?: () => boolean;
+}
+
+/** Manages a per-toast dismiss timer with pause/resume math.
+ *
+ *  Behavior:
+ *  - duration === 'persistent': no timer ever runs.
+ *  - paused flips true: capture remaining ms, clear timeout.
+ *  - paused flips false (and document visible): re-arm with remaining ms.
+ *  - document becomes hidden: behaves like paused = true (auto).
+ *  - document becomes visible: behaves like paused = false (auto).
+ *  - On unmount: clear timeout, remove visibility listener.
+ */
+export function useToastTimer({
+  id,
+  duration,
+  paused,
+  onExpire,
+  getVisible = defaultGetVisible,
+}: UseToastTimerArgs): void {
+  const remainingRef = useRef<number>(typeof duration === 'number' ? duration : Infinity);
+  const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const startedAtRef = useRef<number>(0);
+  const onExpireRef = useRef(onExpire);
+  onExpireRef.current = onExpire;
+
+  // Track document visibility imperatively so we don't trigger React rerenders
+  // for tab focus changes.
+  const docHiddenRef = useRef(!getVisible());
+
+  useEffect(() => {
+    if (duration === 'persistent') return;
+    remainingRef.current = duration;
+  }, [duration]);
+
+  useEffect(() => {
+    if (duration === 'persistent') return;
+
+    const tick = () => {
+      onExpireRef.current();
+    };
+
+    const arm = () => {
+      if (timeoutRef.current !== null) return;
+      startedAtRef.current = Date.now();
+      timeoutRef.current = setTimeout(tick, remainingRef.current);
+    };
+
+    const disarm = () => {
+      if (timeoutRef.current === null) return;
+      clearTimeout(timeoutRef.current);
+      timeoutRef.current = null;
+      const elapsed = Date.now() - startedAtRef.current;
+      remainingRef.current = Math.max(0, remainingRef.current - elapsed);
+    };
+
+    const sync = () => {
+      const shouldRun = !paused && !docHiddenRef.current;
+      if (shouldRun) arm();
+      else disarm();
+    };
+
+    const onVisibilityChange = () => {
+      docHiddenRef.current = !getVisible();
+      sync();
+    };
+
+    sync();
+    document.addEventListener('visibilitychange', onVisibilityChange);
+
+    return () => {
+      disarm();
+      document.removeEventListener('visibilitychange', onVisibilityChange);
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [id, duration, paused]);
+}
+
+function defaultGetVisible(): boolean {
+  return typeof document === 'undefined' ? true : document.visibilityState === 'visible';
+}

package/src/components/Tooltip/Tooltip.module.scss

@@ -0,0 +1,99 @@
+@use './Tooltip.tokens';
+
+// `.content` carries the chrome AND the open-only scale-fade entrance. The
+// animation half (transition + @starting-style + per-side transform-origin
+// rules) relies on Floating UI being in `transform: false` mode (see
+// Tooltip.tsx) so the CSS `transform` property is free for the entrance.
+.content {
+  position: relative;
+  max-width: 240px;
+
+  // Long unbroken strings (URLs, IDs) would otherwise overflow the bubble.
+  overflow-wrap: anywhere;
+  padding: var(--tooltip-padding-y) var(--tooltip-padding-x);
+  background: var(--tooltip-bg);
+  color: var(--tooltip-fg);
+  border-radius: var(--tooltip-radius);
+  box-shadow: var(--tooltip-shadow);
+  font-size: var(--tooltip-font-size);
+  line-height: var(--tooltip-line-height);
+  z-index: var(--tooltip-z);
+  outline: none;
+
+  // Explicit so each per-side @starting-style transform has a defined
+  // resting target to interpolate to. Mirrors DropdownMenu's animation
+  // pattern (see DropdownMenu.module.scss for the original).
+  transform: none;
+  transition:
+    opacity var(--tooltip-transition),
+    transform var(--tooltip-transition);
+
+  // Open-only entrance — the tooltip unmounts on close, so there is no
+  // exit. @starting-style only applies while a transition is active; the
+  // prefers-reduced-motion override below disables the transition, which
+  // neutralises @starting-style (tooltip renders directly at its rest style).
+  @starting-style {
+    opacity: var(--tooltip-opacity-hidden);
+  }
+}
+
+.arrow {
+  position: absolute;
+  width: var(--tooltip-arrow-size);
+  height: var(--tooltip-arrow-size);
+  background: var(--tooltip-arrow-bg);
+
+  // 45° rotation makes the diamond's corners point along ±x and ±y axes;
+  // pairing this with `[data-side]`-based positioning of the arrow against
+  // the trigger-facing edge of the panel makes one of those corners point
+  // straight at the trigger.
+  transform: rotate(45deg);
+  pointer-events: none;
+
+  // Sit BEHIND .content's background so the half of the rotated square that
+  // overlaps the tooltip body (the upper half, given `bottom: -4px`-style
+  // positioning) is hidden by the panel bg. Only the corner poking outside
+  // the panel stays visible — which is the arrow we actually want to show.
+  // Without this the arrow peeks up through nearby content (e.g., a Kbd
+  // chip near the tooltip's edge). Standard Floating UI arrow pattern.
+  z-index: -1;
+}
+
+// --- Open-only entrance: per-side origin + starting transform -----------
+.content[data-side='top'] {
+  transform-origin: bottom center;
+
+  @starting-style {
+    transform: scale(0.92) translateY(2px);
+  }
+}
+
+.content[data-side='bottom'] {
+  transform-origin: top center;
+
+  @starting-style {
+    transform: scale(0.92) translateY(-2px);
+  }
+}
+
+.content[data-side='left'] {
+  transform-origin: right center;
+
+  @starting-style {
+    transform: scale(0.92) translateX(2px);
+  }
+}
+
+.content[data-side='right'] {
+  transform-origin: left center;
+
+  @starting-style {
+    transform: scale(0.92) translateX(-2px);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .content {
+    transition: none;
+  }
+}

package/src/components/Tooltip/Tooltip.tokens.scss

@@ -0,0 +1,23 @@
+// Tooltip.tokens.scss — Component-scoped tokens for <Tooltip>. Each token defaults to the primitive the SCSS used before this migration. Tooltip uses an inverted (dark) surface — `--color-fg` for bg and `--color-bg` for fg — so the arrow color matches the panel bg.
+:root {
+  // Panel surface (inverted: dark bg + light fg)
+  --tooltip-bg: var(--color-fg);
+  --tooltip-fg: var(--color-bg);
+  --tooltip-radius: var(--radius-md);
+  --tooltip-shadow: var(--shadow-md);
+  --tooltip-padding-y: var(--space-1);
+  --tooltip-padding-x: var(--space-2);
+  --tooltip-z: var(--z-tooltip);
+
+  // Typography
+  --tooltip-font-size: var(--font-size-sm);
+  --tooltip-line-height: var(--line-height-normal);
+
+  // Entrance transition
+  --tooltip-transition: var(--transition-base);
+  --tooltip-opacity-hidden: var(--opacity-hidden);
+
+  // Arrow (matches panel bg, no border)
+  --tooltip-arrow-size: var(--space-2);
+  --tooltip-arrow-bg: var(--color-fg);
+}