premium-ds 0.1.0

package/src/components/toast/Toast.tsx

@@ -0,0 +1,349 @@
+'use client';
+
+/* Toast - the React render layer (queue + clocks live in toast-store.ts). */
+import * as React from 'react';
+import { createPortal } from 'react-dom';
+import { createRoot } from 'react-dom/client';
+import { motion, AnimatePresence, animate, useMotionValue, type PanInfo } from 'motion/react';
+import { UIMotion } from '../../tokens/motion-tokens';
+import { Icon, type IconName } from '../icon/Icon';
+import { UIToast, type ToastRecord, type ToastTone } from './toast-store';
+
+const SM = UIMotion;
+const store = UIToast;
+const { useRef, useEffect, useLayoutEffect, useState, useSyncExternalStore } = React;
+
+const VISIBLE = 3;
+const RENDERED = 6;
+const COLLAPSE_GRACE = 140;
+const SWIPE_X = 64;
+const SWIPE_V = 480;
+
+// expanded gap AND collapsed peek - read lazily (post-stylesheet), once
+let GAP = 0;
+function stackGap() {
+  if (GAP) return GAP;
+  const cs = getComputedStyle(document.documentElement);
+  const raw = cs.getPropertyValue('--space-3').trim();
+  const n = parseFloat(raw) || 0;
+  GAP = (raw.endsWith('rem') ? n * (parseFloat(cs.fontSize) || 16) : n) || 12;
+  return GAP;
+}
+
+const TONE_ICON: Record<string, IconName> = {
+  success: 'check-circle',
+  error: 'warning-circle',
+  warning: 'warning',
+  info: 'info',
+};
+
+/* useToneGesture - success glint, error headshake; the glint class is toggled with a reflow (remove - offsetWidth - add) to restart the one-shot. */
+function useToneGesture(
+  tone: ToastTone,
+  ref: React.RefObject<HTMLElement>,
+  x: ReturnType<typeof useMotionValue<number>>,
+) {
+  const prevTone = useRef<ToastTone | null>(null);
+  useEffect(() => {
+    const prev = prevTone.current;
+    prevTone.current = tone;
+    if (tone === prev) return;
+    if (tone === 'success') {
+      const el = ref.current;
+      el.classList.remove('glass-glint');
+      void el.offsetWidth;
+      el.classList.add('glass-glint');
+      const id = setTimeout(() => el.classList.remove('glass-glint'), SM.dur.slow * 1000 + 80);
+      return () => clearTimeout(id);
+    }
+    if (tone === 'error') {
+      const fall = animate(x, [0, -7, 5, -2, 0], {
+        duration: SM.dur.slow,
+        ease: SM.ease.standard,
+        delay: SM.dur.base,
+      });
+      return () => fall.stop();
+    }
+  }, [tone]);
+}
+
+function ToastItem({
+  t,
+  depth,
+  offset,
+  hidden,
+  behind,
+  frameHeight,
+  onHeight,
+}: {
+  t: ToastRecord;
+  depth: number;
+  offset: number;
+  hidden: boolean;
+  behind: boolean;
+  frameHeight: number | null;
+  onHeight: (id: string, h: number) => void;
+}) {
+  const ref = useRef<HTMLLIElement>(null);
+  const x = useMotionValue(0); // swipe travel - ours, so dismissal can finish it
+  useToneGesture(t.tone, ref, x);
+
+  // report the CONTENT height (firstChild - the li's own height is animated, so it'd read mid-tween)
+  useLayoutEffect(() => {
+    if (ref.current && ref.current.firstElementChild)
+      onHeight(t.id, (ref.current.firstElementChild as HTMLElement).offsetHeight);
+  });
+
+  const swipe = (_e: PointerEvent | MouseEvent | TouchEvent, info: PanInfo) => {
+    if (info.offset.x > SWIPE_X || info.velocity.x > SWIPE_V) {
+      // fling out the right edge, THEN remove - the exit fade plays where it landed, no snap-back
+      animate(x, 420, { duration: SM.dur.fast, ease: SM.ease.exit }).then(() =>
+        store.dismiss(t.id),
+      );
+    }
+  };
+
+  return (
+    <motion.li
+      ref={ref}
+      className="toast glass"
+      data-tone={t.tone}
+      data-behind={behind ? '' : undefined}
+      role={t.tone === 'error' ? 'alert' : 'status'}
+      aria-atomic="true"
+      style={{ x }}
+      initial={{ opacity: 0, y: 24, scale: 0.97 }}
+      animate={{
+        opacity: hidden ? 0 : 1,
+        y: -offset,
+        scale: 1 - depth * 0.05,
+        /* behind-cards adopt the front card's frame height (content faded) so a short card never drowns behind a tall one */
+        height: frameHeight || 'auto',
+        pointerEvents: hidden ? 'none' : 'auto',
+      }}
+      exit={{ opacity: 0, scale: 0.96, transition: { duration: SM.dur.fast, ease: SM.ease.exit } }}
+      transition={{ y: SM.t.settle, scale: SM.t.settle, height: SM.t.settle, opacity: SM.t.enter }}
+      drag={t.dismissible ? 'x' : false}
+      dragConstraints={{ left: 0, right: 0 }}
+      dragElastic={{ left: 0.04, right: 0.9 }}
+      dragMomentum={false}
+      onDragEnd={swipe}
+      onKeyDown={(e) => {
+        if (e.key === 'Escape' && t.dismissible) store.dismiss(t.id);
+      }}
+    >
+      {t.node ? (
+        <div className="toast__custom">{t.node as React.ReactNode}</div>
+      ) : (
+        <ToastBody t={t} />
+      )}
+    </motion.li>
+  );
+}
+
+function ToastBody({ t }: { t: ToastRecord }) {
+  return (
+    <div className="toast__inner">
+      {(t.tone !== 'default' || isFinite(t.duration)) && (
+        <span className="toast__icon">
+          {t.tone !== 'default' && (
+            /* keyed remount (not nested AnimatePresence): old glyph cuts, new springs in */
+            <motion.span
+              key={t.tone}
+              className="toast__icon-glyph"
+              initial={{ scale: 0.5, opacity: 0 }}
+              animate={{ scale: 1, opacity: 1 }}
+              transition={{ scale: SM.t.settle, opacity: SM.t.enter }}
+            >
+              {t.tone === 'loading' ? (
+                <span className="toast__spinner" aria-hidden="true"></span>
+              ) : (
+                <Icon name={TONE_ICON[t.tone]} weight="fill" />
+              )}
+            </motion.span>
+          )}
+          {isFinite(t.duration) && (
+            /* the ring - keyed to the timer so a restart re-fills it; pathLength=1 makes dashoffset a fraction */
+            <svg
+              key={'ring-' + t.timerKey}
+              className="toast__ring"
+              viewBox="0 0 36 36"
+              aria-hidden="true"
+            >
+              <circle className="toast__ring-track" cx="18" cy="18" r="16.5"></circle>
+              <circle
+                className="toast__ring-arc"
+                cx="18"
+                cy="18"
+                r="16.5"
+                pathLength={1}
+                style={{ animationDuration: t.duration + 'ms' }}
+              ></circle>
+            </svg>
+          )}
+        </span>
+      )}
+      <motion.div
+        key={String(t.message) + '-' + String(t.description)}
+        className="toast__text"
+        initial={{ opacity: 0 }}
+        animate={{ opacity: 1 }}
+        transition={SM.t.enter}
+      >
+        <p className="toast__message">{t.message}</p>
+        {t.description != null && <p className="toast__desc">{t.description}</p>}
+      </motion.div>
+      {t.count > 1 && (
+        <motion.span
+          key={t.count}
+          className="toast__count"
+          initial={{ scale: 0.6 }}
+          animate={{ scale: 1 }}
+          transition={SM.t.settle}
+        >
+          ×{t.count}
+        </motion.span>
+      )}
+      {t.action && (
+        <button
+          type="button"
+          className="btn btn--secondary btn--sm toast__action"
+          onClick={() => {
+            if (t.action.onClick) t.action.onClick();
+            store.dismiss(t.id);
+          }}
+        >
+          {t.action.label}
+        </button>
+      )}
+      {t.dismissible && (
+        <button
+          type="button"
+          className="toast__close"
+          aria-label="Dismiss"
+          onClick={() => store.dismiss(t.id)}
+        >
+          <Icon name="close" size="sm" />
+        </button>
+      )}
+    </div>
+  );
+}
+
+function ToastHost() {
+  const { toasts, paused, expanded } = useSyncExternalStore(store.subscribe, store.get);
+  const [heights, setHeights] = useState<Record<string, number>>({});
+  const collapseTimer = useRef<ReturnType<typeof setTimeout> | 0>(0);
+  const hovering = useRef(false);
+
+  const onHeight = (id: string, h: number) =>
+    setHeights((prev) => (prev[id] === h ? prev : { ...prev, [id]: h }));
+
+  // hold = fan open + freeze clocks; release = graced fold + resume
+  const onHold = () => {
+    hovering.current = true;
+    clearTimeout(collapseTimer.current);
+    store.setExpanded(true);
+    store.pause();
+  };
+  const onRelease = (graced: boolean) => {
+    hovering.current = false;
+    clearTimeout(collapseTimer.current);
+    collapseTimer.current = setTimeout(
+      () => {
+        store.setExpanded(false);
+        store.resume();
+      },
+      graced ? COLLAPSE_GRACE : 0,
+    );
+  };
+
+  // tab hidden - freeze clocks, visible - resume (visibility, not window focus: an embedded preview blurs on outside clicks).
+  useEffect(() => {
+    const onVis = () => {
+      if (document.hidden) store.pause();
+      else if (!hovering.current) store.resume();
+    };
+    document.addEventListener('visibilitychange', onVis);
+    return () => document.removeEventListener('visibilitychange', onVis);
+  }, []);
+
+  // safety net: last card removed under the cursor fires no pointerout, so release here
+  useEffect(() => {
+    if (toasts.length === 0) {
+      hovering.current = false;
+      clearTimeout(collapseTimer.current);
+      store.setExpanded(false);
+      store.resume();
+    }
+  }, [toasts.length]);
+
+  const slice = toasts.slice(-RENDERED);
+  const n = slice.length;
+  const frontH = n ? heights[slice[n - 1].id] || 0 : 0;
+  const gap = stackGap();
+
+  return createPortal(
+    <ol
+      className={'toast-viewport' + (paused ? ' is-paused' : '')}
+      aria-label="Notifications"
+      onPointerOver={(e) => {
+        if (e.pointerType !== 'touch') onHold();
+      }}
+      onPointerOut={(e) => {
+        if (!e.relatedTarget || !e.currentTarget.contains(e.relatedTarget as Node)) onRelease(true);
+      }}
+      onFocus={onHold}
+      onBlur={(e) => {
+        if (!e.relatedTarget || !e.currentTarget.contains(e.relatedTarget as Node))
+          onRelease(false);
+      }}
+    >
+      {/* initial stays true - the host mounts with the first toast, so initial={false} would skip its entrance */}
+      <AnimatePresence>
+        {slice.map((t, i) => {
+          const depth = n - 1 - i; // newest = 0, at the front
+          let offset = depth * gap; // collapsed: peek per depth
+          if (expanded) {
+            // expanded: real heights
+            offset = 0;
+            for (let j = i + 1; j < n; j++) offset += (heights[slice[j].id] || 0) + gap;
+          }
+          return (
+            <ToastItem
+              key={t.id}
+              t={t}
+              depth={expanded ? 0 : depth}
+              offset={offset}
+              hidden={!expanded && depth >= VISIBLE}
+              behind={!expanded && depth > 0}
+              frameHeight={!expanded && depth > 0 && frontH ? frontH : null}
+              onHeight={onHeight}
+            />
+          );
+        })}
+      </AnimatePresence>
+    </ol>,
+    document.body,
+  );
+}
+
+let hostMounted = false;
+function ensureToastHost() {
+  if (hostMounted) return;
+  hostMounted = true;
+  const el = document.createElement('div');
+  el.setAttribute('data-toast-host', '');
+  document.body.appendChild(el);
+  createRoot(el).render(<ToastHost />);
+}
+store.host = ensureToastHost;
+if (store.toasts.length) ensureToastHost(); // toasts fired before we loaded
+
+/* Toaster - mount once near the app root so this module loads client-side and the lazy host is registered (toast() also auto-mounts). */
+export function Toaster(): null {
+  useEffect(() => {
+    ensureToastHost();
+  }, []);
+  return null;
+}

package/src/components/toast/toast-store.ts

@@ -0,0 +1,266 @@
+// toast-store - the Toast machinery: queue, clocks, coalescing, imperative API (zero React).
+
+export type ToastTone = 'default' | 'success' | 'error' | 'warning' | 'info' | 'loading' | 'custom';
+
+export interface ToastAction {
+  label: string;
+  onClick: () => void;
+}
+
+export interface ToastOptions {
+  id?: string | number;
+  duration?: number;
+  description?: string | null;
+  action?: ToastAction | null;
+}
+
+export interface ToastRecord {
+  id: string;
+  tone: ToastTone;
+  message: string | null;
+  description: string | null;
+  action: ToastAction | null;
+  duration: number;
+  remaining: number;
+  count: number;
+  timerKey: number;
+  node: unknown; // a React node, kept opaque so this module stays React-free
+  dismissible: boolean;
+  expiresAt?: number;
+}
+
+export interface ToastSnapshot {
+  toasts: ToastRecord[];
+  paused: boolean;
+  expanded: boolean;
+}
+
+const DURATION: Record<string, number> = {
+  default: 5000,
+  success: 5000,
+  info: 5000,
+  warning: 8000,
+  error: 8000,
+  loading: Infinity, // sticky until updated/dismissed
+};
+
+let uid = 0;
+const timers = new Map<string, ReturnType<typeof setTimeout>>();
+
+interface ToastStore {
+  toasts: ToastRecord[];
+  paused: boolean;
+  expanded: boolean;
+  host: null | (() => void);
+  snap: ToastSnapshot;
+  listeners: Set<() => void>;
+  subscribe(l: () => void): () => void;
+  get(): ToastSnapshot;
+  emit(): void;
+  add(t: ToastRecord): string;
+  update(id: string, patch: Partial<ToastRecord>): string;
+  dismiss(id?: string | null): void;
+  schedule(t: ToastRecord): void;
+  pause(): void;
+  resume(): void;
+  setExpanded(v: boolean): void;
+}
+
+/* Store - the queue; the API writes, the host renders. */
+const store: ToastStore = {
+  toasts: [],
+  paused: false,
+  expanded: false,
+  host: null,
+  snap: { toasts: [], paused: false, expanded: false },
+  listeners: new Set(),
+  subscribe(l) {
+    store.listeners.add(l);
+    return () => store.listeners.delete(l);
+  },
+  get: () => store.snap,
+  emit() {
+    store.snap = { toasts: store.toasts.slice(), paused: store.paused, expanded: store.expanded };
+    store.listeners.forEach((l) => l());
+  },
+
+  add(t) {
+    // coalesce: an identical visible toast becomes a xN counter instead of a duplicate
+    const twin = store.toasts.find(
+      (x) =>
+        !x.node &&
+        !t.node &&
+        x.tone === t.tone &&
+        x.message === t.message &&
+        x.description === t.description,
+    );
+    if (twin) return store.update(twin.id, { count: twin.count + 1 });
+    store.toasts.push(t);
+    store.schedule(t);
+    store.emit();
+    return t.id;
+  },
+
+  update(id, patch) {
+    const t = store.toasts.find((x) => x.id === id);
+    if (!t) return id;
+    Object.assign(t, patch);
+    if ('tone' in patch || 'duration' in patch || 'count' in patch) {
+      t.remaining = t.duration;
+      t.timerKey++; // re-key the ring so it re-fills
+      store.schedule(t);
+    }
+    store.emit();
+    return id;
+  },
+
+  dismiss(id) {
+    const gone = id == null ? store.toasts : store.toasts.filter((t) => t.id === id);
+    gone.forEach((t) => {
+      clearTimeout(timers.get(t.id));
+      timers.delete(t.id);
+    });
+    store.toasts = id == null ? [] : store.toasts.filter((t) => t.id !== id);
+    store.emit();
+  },
+
+  schedule(t) {
+    clearTimeout(timers.get(t.id));
+    timers.delete(t.id);
+    if (!isFinite(t.duration)) return;
+    if (store.paused) return; // resume() picks it up with t.remaining
+    t.expiresAt = performance.now() + t.remaining;
+    timers.set(
+      t.id,
+      setTimeout(() => store.dismiss(t.id), t.remaining),
+    );
+  },
+
+  pause() {
+    // freeze every clock, remember what's left
+    if (store.paused) return;
+    store.paused = true;
+    store.toasts.forEach((t) => {
+      if (timers.has(t.id)) {
+        clearTimeout(timers.get(t.id));
+        timers.delete(t.id);
+        t.remaining = Math.max(0, (t.expiresAt ?? performance.now()) - performance.now());
+      }
+    });
+    store.emit();
+  },
+
+  resume() {
+    if (!store.paused) return;
+    store.paused = false;
+    store.toasts.forEach((t) => store.schedule(t));
+    store.emit();
+  },
+
+  setExpanded(v) {
+    if (v === store.expanded) return;
+    store.expanded = v;
+    store.emit();
+  },
+};
+
+function make(tone: ToastTone, message: string | null, opts: ToastOptions = {}): string {
+  if (store.host) store.host();
+  const id = opts.id != null ? String(opts.id) : 'toast-' + ++uid;
+  const duration = opts.duration != null ? opts.duration : DURATION[tone];
+  if (store.toasts.some((t) => t.id === id)) {
+    return store.update(id, {
+      tone,
+      message,
+      duration,
+      description: opts.description != null ? opts.description : null,
+      action: opts.action != null ? opts.action : null,
+    });
+  }
+  return store.add({
+    id,
+    tone,
+    message,
+    description: opts.description != null ? opts.description : null,
+    action: opts.action != null ? opts.action : null,
+    duration,
+    remaining: duration,
+    count: 1,
+    timerKey: 0,
+    node: null,
+    dismissible: true,
+  });
+}
+
+type PromiseMsg<V> = string | ((v: V) => string);
+export interface ToastPromiseMsgs<T> {
+  loading?: string;
+  success?: PromiseMsg<T>;
+  error?: PromiseMsg<unknown>;
+}
+
+export interface ToastApi {
+  (message: string, opts?: ToastOptions): string;
+  success(m: string, o?: ToastOptions): string;
+  error(m: string, o?: ToastOptions): string;
+  warning(m: string, o?: ToastOptions): string;
+  info(m: string, o?: ToastOptions): string;
+  loading(m: string, o?: ToastOptions): string;
+  dismiss(id?: string | null): void;
+  update(id: string, patch?: Partial<ToastRecord>): string;
+  promise<T>(promise: Promise<T>, msgs?: ToastPromiseMsgs<T>): Promise<T>;
+  custom(
+    node: unknown,
+    opts?: { id?: string | number; duration?: number; dismissible?: boolean },
+  ): string;
+}
+
+const toast = ((message: string, opts?: ToastOptions) =>
+  make('default', message, opts)) as ToastApi;
+toast.success = (m, o) => make('success', m, o);
+toast.error = (m, o) => make('error', m, o);
+toast.warning = (m, o) => make('warning', m, o);
+toast.info = (m, o) => make('info', m, o);
+toast.loading = (m, o) => make('loading', m, o);
+toast.dismiss = (id) => store.dismiss(id);
+
+toast.update = (id, patch = {}) => {
+  // a tone change without an explicit duration adopts that tone's clock
+  if (patch.tone && patch.duration == null) patch = { ...patch, duration: DURATION[patch.tone] };
+  return store.update(id, patch);
+};
+
+toast.promise = function <T>(promise: Promise<T>, msgs: ToastPromiseMsgs<T> = {}): Promise<T> {
+  const id = make('loading', msgs.loading != null ? msgs.loading : 'Working...');
+  const text = <V>(m: PromiseMsg<V> | undefined, fallback: string, v: V): string =>
+    typeof m === 'function' ? (m as (x: V) => string)(v) : m != null ? m : fallback;
+  promise.then(
+    (v) => toast.update(id, { tone: 'success', message: text(msgs.success, 'Done', v) }),
+    (e) =>
+      toast.update(id, { tone: 'error', message: text(msgs.error, 'Something went wrong', e) }),
+  );
+  return promise;
+};
+
+toast.custom = (node, opts = {}) => {
+  if (store.host) store.host();
+  const id = opts.id != null ? String(opts.id) : 'toast-' + ++uid;
+  const duration = opts.duration != null ? opts.duration : Infinity;
+  if (store.toasts.some((t) => t.id === id)) return store.update(id, { node });
+  return store.add({
+    id,
+    tone: 'custom',
+    node,
+    message: null,
+    description: null,
+    action: null,
+    duration,
+    remaining: duration,
+    count: 1,
+    timerKey: 0,
+    dismissible: opts.dismissible === true,
+  });
+};
+
+export { toast };
+export const UIToast = store;