@cplieger/ui 0.0.0-stage → 1.0.0-dev.1

package/src/primitives/toast/engine.ts

@@ -0,0 +1,327 @@
+// engine.ts — Pure timer/queue state machine for toasts. No DOM: it drives an
+// injected `ToastView` port, so it is fully testable headless. Owns the queue,
+// the visible set, promotion, per-toast timers, and pause/resume math.
+
+/** Severity of a toast. It selects the skin modifier class, the politeness of
+ *  the screen-reader announcement, and the default duration — `"error"` is
+ *  sticky, the other two auto-dismiss. */
+export type ToastLevel = "info" | "success" | "error";
+
+/** A retry affordance rendered inside the toast: a button the user can press to
+ *  re-attempt whatever failed. */
+export interface ToastRetry {
+  /** Button text. Default `"Retry"`. */
+  readonly label?: string;
+  /** Runs on press, after the toast has been dismissed. The result is not
+   *  awaited: a throw or a rejection is logged and swallowed, so reporting the
+   *  retry's own outcome is the caller's job. */
+  readonly onClick: () => void | Promise<void>;
+}
+
+/** Per-toast overrides, all optional: the level defaults to `"info"` and the
+ *  duration to that level's default, so `show(message)` alone is a complete
+ *  call. */
+export interface ToastOptions {
+  /** Severity. Default `"info"`. */
+  level?: ToastLevel;
+  /** Auto-dismiss after this many ms. `0` = sticky (manual dismiss only). */
+  duration?: number;
+  retry?: ToastRetry;
+}
+
+const DEFAULT_MAX_VISIBLE = 3;
+const DEFAULT_MAX_QUEUE = 20;
+const DEFAULT_DURATION_MS = 4000;
+const ERROR_DURATION_MS = 0;
+
+/** The per-level default duration: sticky (0) for errors, `fallback` otherwise. */
+function defaultDurationFor(level: ToastLevel, fallback: number): number {
+  return level === "error" ? ERROR_DURATION_MS : fallback;
+}
+
+/** Immutable data the view needs to render one toast. */
+export interface ToastRenderData {
+  readonly message: string;
+  readonly level: ToastLevel;
+  readonly duration: number;
+  readonly retry?: ToastRetry;
+}
+
+/** Per-toast callbacks the view wires to DOM events. */
+export interface ToastCallbacks {
+  dismiss(): void;
+  pause(): void;
+  resume(): void;
+}
+
+/** DOM port. The engine holds handles of type `H` opaquely. */
+export interface ToastView<H> {
+  mount(data: ToastRenderData, ctx: ToastCallbacks): H;
+  /** Animate out, then call `done()` once the node is gone. */
+  scheduleLeave(handle: H, done: () => void): void;
+  /** Remove immediately, no animation. */
+  remove(handle: H): void;
+  pauseProgress(handle: H): void;
+  resumeProgress(handle: H): void;
+  /** Tear down any shared container. */
+  dispose(): void;
+}
+
+/** Construction options for {@link ToastEngine}: the view port it drives, plus
+ *  the capacity, duration and mode knobs a `Toaster` forwards from its own
+ *  options. `view` is the only required field. */
+export interface ToastEngineOptions<H> {
+  view: ToastView<H>;
+  maxVisible?: number;
+  maxQueue?: number;
+  defaultDuration?: number;
+  /** `"stack"` (default): up to `maxVisible` toasts show at once, the rest
+   *  queue. `"replace"`: single-slot latest-wins — a new toast instantly
+   *  replaces the visible one (no leave animation, no queue), the embeddable-
+   *  widget semantics where a stale "Copied" queue would be wrong. */
+  mode?: "stack" | "replace";
+}
+
+interface ActiveToast<H> {
+  readonly id: number;
+  readonly duration: number;
+  remaining: number;
+  startedAt: number;
+  timer: ReturnType<typeof setTimeout> | null;
+  handle: H;
+  dismissed: boolean;
+}
+
+interface QueuedToast {
+  readonly id: number;
+  readonly message: string;
+  readonly level: ToastLevel;
+  readonly duration: number;
+  readonly retry?: ToastRetry;
+  bindDismiss(dismiss: () => void): void;
+}
+
+/** The toast state machine, holding the queue, the visible set, per-toast
+ *  timers and the pause/resume math, and driving an injected {@link ToastView}.
+ *  Touches no DOM itself: handles of type `H` come from the view and are held
+ *  opaquely. */
+export class ToastEngine<H> {
+  private readonly view: ToastView<H>;
+  private readonly maxVisible: number;
+  private readonly maxQueue: number;
+  private readonly defaultDuration: number;
+  private readonly replace: boolean;
+  private readonly visible: ActiveToast<H>[] = [];
+  private readonly queue: QueuedToast[] = [];
+  private idSeq = 0;
+
+  constructor(opts: ToastEngineOptions<H>) {
+    this.view = opts.view;
+    this.replace = opts.mode === "replace";
+    this.maxVisible = this.replace ? 1 : Math.max(1, opts.maxVisible ?? DEFAULT_MAX_VISIBLE);
+    this.maxQueue = Math.max(0, opts.maxQueue ?? DEFAULT_MAX_QUEUE);
+    this.defaultDuration = opts.defaultDuration ?? DEFAULT_DURATION_MS;
+  }
+
+  /** Show a toast (or queue it if the visible set is full). Returns a dismiss fn. */
+  show(message: string, opts?: ToastOptions): () => void {
+    const level = opts?.level ?? "info";
+    const duration = opts?.duration ?? defaultDurationFor(level, this.defaultDuration);
+    const retry = opts?.retry;
+    const id = ++this.idSeq;
+
+    // No leave animation — the new message must not coexist with or wait for the old one.
+    if (this.replace && this.visible.length > 0) {
+      for (const t of [...this.visible]) {
+        if (t.timer !== null) {
+          clearTimeout(t.timer);
+          t.timer = null;
+        }
+        t.dismissed = true;
+        this.view.remove(t.handle);
+      }
+      this.visible.length = 0;
+    }
+
+    if (this.visible.length < this.maxVisible) {
+      this.mountToast(id, message, level, duration, retry);
+      return () => {
+        this.dismiss(id);
+      };
+    }
+
+    let mountedDismiss: (() => void) | null = null;
+    let cancelled = false;
+    const queued: QueuedToast = {
+      id,
+      message,
+      level,
+      duration,
+      ...(retry !== undefined ? { retry } : {}),
+      bindDismiss: (dismiss) => {
+        if (cancelled) {
+          dismiss();
+        } else {
+          mountedDismiss = dismiss;
+        }
+      },
+    };
+    this.enqueue(queued);
+    return () => {
+      if (mountedDismiss !== null) {
+        mountedDismiss();
+        return;
+      }
+      cancelled = true;
+      const i = this.queue.indexOf(queued);
+      if (i !== -1) {
+        this.queue.splice(i, 1);
+      }
+    };
+  }
+
+  /** Dismiss the newest visible toast (Escape handler target). */
+  dismissNewest(): void {
+    const newest = this.visible[this.visible.length - 1];
+    if (newest !== undefined) {
+      this.dismiss(newest.id);
+    }
+  }
+
+  /** Immediately remove all visible toasts and clear the queue (test-friendly). */
+  clear(): void {
+    for (const t of [...this.visible]) {
+      if (t.timer !== null) {
+        clearTimeout(t.timer);
+        t.timer = null;
+      }
+      t.dismissed = true;
+      this.view.remove(t.handle);
+    }
+    this.visible.length = 0;
+    this.queue.length = 0;
+  }
+
+  private mountToast(
+    id: number,
+    message: string,
+    level: ToastLevel,
+    duration: number,
+    retry: ToastRetry | undefined,
+  ): void {
+    const data: ToastRenderData = {
+      message,
+      level,
+      duration,
+      ...(retry !== undefined ? { retry } : {}),
+    };
+    const ctx: ToastCallbacks = {
+      dismiss: () => {
+        this.dismiss(id);
+      },
+      pause: () => {
+        this.pause(id);
+      },
+      resume: () => {
+        this.resume(id);
+      },
+    };
+    const handle = this.view.mount(data, ctx);
+    const record: ActiveToast<H> = {
+      id,
+      duration,
+      remaining: duration,
+      startedAt: Date.now(),
+      timer: null,
+      handle,
+      dismissed: false,
+    };
+    this.visible.push(record);
+    this.startTimer(record);
+  }
+
+  private enqueue(entry: QueuedToast): void {
+    if (this.maxQueue <= 0) {
+      return;
+    }
+    while (this.queue.length >= this.maxQueue) {
+      this.queue.shift();
+    }
+    this.queue.push(entry);
+  }
+
+  private promote(): void {
+    while (this.visible.length < this.maxVisible) {
+      const next = this.queue.shift();
+      if (next === undefined) {
+        return;
+      }
+      this.mountToast(next.id, next.message, next.level, next.duration, next.retry);
+      next.bindDismiss(() => {
+        this.dismiss(next.id);
+      });
+    }
+  }
+
+  private startTimer(t: ActiveToast<H>): void {
+    if (t.duration <= 0 || t.remaining <= 0) {
+      return;
+    }
+    t.startedAt = Date.now();
+    t.timer = setTimeout(() => {
+      this.dismiss(t.id);
+    }, t.remaining);
+  }
+
+  private pause(id: number): void {
+    const t = this.find(id);
+    if (t === undefined || t.duration <= 0 || t.timer === null) {
+      return;
+    }
+    clearTimeout(t.timer);
+    t.timer = null;
+    const elapsed = Date.now() - t.startedAt;
+    t.remaining = Math.max(0, t.remaining - elapsed);
+    this.view.pauseProgress(t.handle);
+  }
+
+  private resume(id: number): void {
+    const t = this.find(id);
+    if (t === undefined || t.duration <= 0 || t.timer !== null) {
+      return;
+    }
+    if (t.remaining <= 0) {
+      // A backgrounded tab can let the wall clock pass the deadline before the
+      // pending timeout runs, draining `remaining` to 0 with no timer left to
+      // fire. Releasing the hold is the last chance to run the promised
+      // auto-dismiss, or it stays on screen until clicked/Escaped/cleared.
+      this.dismiss(id);
+      return;
+    }
+    this.startTimer(t);
+    this.view.resumeProgress(t.handle);
+  }
+
+  private dismiss(id: number): void {
+    const record = this.visible.find((t) => t.id === id);
+    if (record === undefined || record.dismissed) {
+      return;
+    }
+    record.dismissed = true;
+    if (record.timer !== null) {
+      clearTimeout(record.timer);
+      record.timer = null;
+    }
+    this.view.scheduleLeave(record.handle, () => {
+      const i = this.visible.indexOf(record);
+      if (i !== -1) {
+        this.visible.splice(i, 1);
+      }
+      this.promote();
+    });
+  }
+
+  private find(id: number): ActiveToast<H> | undefined {
+    return this.visible.find((t) => t.id === id);
+  }
+}

package/src/primitives/toast/index.ts

@@ -0,0 +1,139 @@
+/**
+ * toast/index.ts — Public toast surface: the `Toaster` factory + a default
+ * module singleton for convenience, with `info` / `success` / `error` free
+ * functions bound to it.
+ *
+ * @module
+ */
+
+import { ToastEngine } from "./engine.js";
+import type { ToastLevel, ToastOptions, ToastRetry } from "./engine.js";
+import { createToastView } from "./view.js";
+import type { ToastHandle } from "./view.js";
+
+export type { ToastLevel, ToastOptions, ToastRetry };
+
+/** One toast stack: its own container, queue and Escape listener. Every show
+ *  variant returns a function that dismisses the toast it created, so a caller
+ *  can retract a message whose cause has gone away. */
+export interface Toaster {
+  /** Show a toast; returns a function that dismisses it. */
+  show(message: string, opts?: ToastOptions): () => void;
+  info(message: string): () => void;
+  success(message: string): () => void;
+  error(message: string, retry?: ToastRetry): () => void;
+  /** Dismiss all visible toasts and clear the queue. */
+  clear(): void;
+  /** Tear down this toaster: remove its document keydown (Escape) listener,
+   *  clear all toasts, and remove its stack container. Call this for any
+   *  per-component `createToaster()` so its listener doesn't outlive the
+   *  component. (The module `toast` singleton lives for the app's lifetime, so
+   *  it is never disposed.) */
+  dispose(): void;
+}
+
+/** How one stack behaves: how many toasts show and queue, how long a
+ *  non-error toast lives, where the stack mounts, and whether an arriving
+ *  toast queues behind the visible ones or replaces them. All optional. */
+export interface ToasterOptions {
+  /** Maximum simultaneously-visible toasts (`"stack"` mode). Default `3`. */
+  maxVisible?: number;
+  /** Overflow queue capacity (`"stack"` mode; oldest dropped). Default `20`. */
+  maxQueue?: number;
+  /** Auto-dismiss window (ms) for non-error toasts. Default `4000`. */
+  defaultDuration?: number;
+  /** Mount the toast stack inside this element instead of `document.body` —
+   *  for an embeddable widget that must confine its chrome to its own root. */
+  container?: HTMLElement;
+  /** `"stack"` (default): up to `maxVisible` show, the rest queue.
+   *  `"replace"`: single-slot latest-wins — a new toast instantly replaces the
+   *  visible one; nothing queues. */
+  mode?: "stack" | "replace";
+}
+
+function build(opts?: ToasterOptions): Toaster {
+  const view = createToastView(opts?.container);
+  const engine = new ToastEngine<ToastHandle>({
+    view,
+    ...(opts?.maxVisible !== undefined ? { maxVisible: opts.maxVisible } : {}),
+    ...(opts?.maxQueue !== undefined ? { maxQueue: opts.maxQueue } : {}),
+    ...(opts?.defaultDuration !== undefined ? { defaultDuration: opts.defaultDuration } : {}),
+    ...(opts?.mode !== undefined ? { mode: opts.mode } : {}),
+  });
+
+  const onKeyDown = (e: KeyboardEvent): void => {
+    if (e.key === "Escape") {
+      engine.dismissNewest();
+    }
+  };
+  document.addEventListener("keydown", onKeyDown);
+
+  return {
+    show: (message, showOpts) => engine.show(message, showOpts),
+    info: (message) => engine.show(message, { level: "info" }),
+    success: (message) => engine.show(message, { level: "success" }),
+    error: (message, retry) =>
+      engine.show(message, retry !== undefined ? { level: "error", retry } : { level: "error" }),
+    clear: () => {
+      engine.clear();
+    },
+    dispose: () => {
+      document.removeEventListener("keydown", onKeyDown);
+      engine.clear();
+      view.dispose();
+    },
+  };
+}
+
+/** Create an isolated toaster with its own stack container and queue. */
+export function createToaster(opts?: ToasterOptions): Toaster {
+  return build(opts);
+}
+
+// Built lazily, so a page that only calls createToaster never builds the
+// default stack or its document listener.
+let singleton: Toaster | null = null;
+
+function getSingleton(): Toaster {
+  singleton ??= build();
+  return singleton;
+}
+
+/** Default shared toaster (built lazily on first use; lives for the app's
+ *  lifetime — never dispose it). */
+export const toast: Toaster = {
+  show: (message, opts) => getSingleton().show(message, opts),
+  info: (message) => getSingleton().info(message),
+  success: (message) => getSingleton().success(message),
+  error: (message, retry) => getSingleton().error(message, retry),
+  clear: (): void => {
+    getSingleton().clear();
+  },
+  dispose: (): void => {
+    getSingleton().dispose();
+  },
+};
+
+/** Show an info toast on the default toaster. */
+export function info(message: string): () => void {
+  return getSingleton().info(message);
+}
+
+/** Show a success toast on the default toaster. */
+export function success(message: string): () => void {
+  return getSingleton().success(message);
+}
+
+/** Show an error toast on the default toaster. */
+export function error(message: string, retry?: ToastRetry): () => void {
+  return getSingleton().error(message, retry);
+}
+
+/** Test-only: tear down the default toaster entirely (listener included); the
+ *  next use lazily rebuilds it fresh. */
+export function _resetForTest(): void {
+  if (singleton !== null) {
+    singleton.dispose();
+    singleton = null;
+  }
+}

package/src/primitives/toast/view.ts

@@ -0,0 +1,244 @@
+// view.ts — DOM implementation of the toast `ToastView` port. Enter/leave
+// lifecycle via `is-entering` → `is-shown` → `is-leaving` state classes.
+// Screen-reader announcement is delegated to `announce()`, so neither the
+// stack nor a toast node is a live region and no live region nests inside
+// another.
+
+import { el } from "../../dom/el.js";
+
+import { announce } from "../announce.js";
+import { topmostOpenDialog } from "../modal-host.js";
+import { cancelTransition, runTransition } from "../transition.js";
+import type { ToastCallbacks, ToastRenderData, ToastView } from "./engine.js";
+
+/** What this view hands the engine for one mounted toast. The engine stores it
+ *  and passes it back; only this module reads the fields. */
+export interface ToastHandle {
+  /** The node `mount` built and appended to the stack. Detaching it is this
+   *  module's alone — from `scheduleLeave`'s settle, from `remove`, or from
+   *  `dispose`, which removes the whole stack container and takes any node
+   *  still mounted inside it — so the engine must not remove it itself, and a
+   *  handle is spent once any of the three has run: the reference still reads,
+   *  but the node is out of the document. */
+  readonly el: HTMLElement;
+  /** The progress bar, or `null` for a sticky toast (no duration to show). */
+  readonly progressEl: HTMLElement | null;
+  /** Handle of the pending enter `requestAnimationFrame`, or `null` once it has
+   *  run (or been cancelled). Cancelled on leave/remove so a late enter frame
+   *  can't re-apply `is-shown` mid-leave. */
+  enterRaf: number | null;
+}
+
+/** Create a DOM-backed toast view whose stack is created on first `mount`.
+ *  It mounts on `host` when given, else on `document.body`, moving into the
+ *  topmost open modal `<dialog>` while one is open (`showModal()` inerts
+ *  everything outside it) and back to the body after. */
+export function createToastView(host?: HTMLElement): ToastView<ToastHandle> {
+  let container: HTMLElement | null = null;
+  // The modal <dialog> currently auto-hosting the stack, if any. Its `close`
+  // event re-runs syncHost so a sticky toast is evacuated before it hides.
+  let adoptedDialog: HTMLDialogElement | null = null;
+
+  const onAdoptedClose = (): void => {
+    syncHost();
+  };
+
+  const releaseAdopted = (): void => {
+    if (adoptedDialog !== null) {
+      adoptedDialog.removeEventListener("close", onAdoptedClose);
+      adoptedDialog = null;
+    }
+  };
+
+  /** Move the stack to `host`, else the topmost open modal dialog, else
+   *  `document.body`. `appendChild` MOVES the stack, so live toasts (timers,
+   *  listeners, progress state) ride along untouched. */
+  const syncHost = (): void => {
+    if (container === null) {
+      return;
+    }
+    const desired: HTMLElement = host ?? topmostOpenDialog() ?? document.body;
+    if (container.parentElement !== desired) {
+      desired.appendChild(container);
+    }
+    const dialog = host === undefined && desired instanceof HTMLDialogElement ? desired : null;
+    if (dialog !== adoptedDialog) {
+      releaseAdopted();
+      if (dialog !== null) {
+        adoptedDialog = dialog;
+        dialog.addEventListener("close", onAdoptedClose);
+      }
+    }
+  };
+
+  const ensureContainer = (): HTMLElement => {
+    container ??= el("div", { className: "uip-toast-stack" });
+    // Re-resolve on every mount: a modal may have opened/closed, or its host
+    // dialog may have been removed, since the last toast.
+    syncHost();
+    return container;
+  };
+
+  return {
+    mount(data: ToastRenderData, ctx: ToastCallbacks): ToastHandle {
+      const stack = ensureContainer();
+
+      // The node itself stays non-live, so the message is announced once.
+      announce(data.message, data.level === "error" ? "assertive" : "polite");
+
+      const node = el("div", {
+        className: `uip-toast uip-toast--${data.level} is-entering`,
+        tabindex: "0",
+      });
+
+      // Visually-hidden (not aria-hidden) dismiss hint: the node is
+      // tabindex=0 but not a live region, so a tabbed-to toast needs its own
+      // description of how to dismiss it.
+      node.appendChild(el("span", { className: "uip-toast-msg" }, data.message));
+      node.appendChild(el("span", { className: "uip-visually-hidden" }, "Click to dismiss."));
+
+      const retry = data.retry;
+      if (retry !== undefined) {
+        const btn = el(
+          "button",
+          { type: "button", className: "uip-toast-retry" },
+          retry.label ?? "Retry",
+        );
+        btn.addEventListener("click", (e) => {
+          e.stopPropagation();
+          ctx.dismiss();
+          runRetry(retry.onClick);
+        });
+        node.appendChild(btn);
+      }
+
+      let progressEl: HTMLElement | null = null;
+      if (data.duration > 0) {
+        // The CSS animates the progress bar off this property (no inline transition-duration).
+        node.style.setProperty("--uip-toast-duration", `${data.duration}ms`);
+        progressEl = el("span", { className: "uip-toast-progress", "aria-hidden": "true" });
+        node.appendChild(progressEl);
+      }
+
+      node.addEventListener("click", () => {
+        ctx.dismiss();
+      });
+      // Escape only targets the newest toast, so make the focused one
+      // dismissable by keyboard too; guard to the node so it doesn't swallow
+      // the retry button's Enter.
+      node.addEventListener("keydown", (e) => {
+        if (e.target !== node) {
+          return;
+        }
+        if (e.key === "Enter" || e.key === " " || e.key === "Spacebar") {
+          e.preventDefault();
+          ctx.dismiss();
+        }
+      });
+
+      // Ref-count hover + focus (two pause sources, one engine timer): resume
+      // only when both release, or un-hovering a still-focused toast would
+      // resume the countdown while focused.
+      let pauseCount = 0;
+      const addPause = (): void => {
+        pauseCount++;
+        if (pauseCount === 1) {
+          ctx.pause();
+        }
+      };
+      const removePause = (): void => {
+        if (pauseCount === 0) {
+          return;
+        }
+        pauseCount--;
+        if (pauseCount === 0) {
+          ctx.resume();
+        }
+      };
+      node.addEventListener("mouseenter", addPause);
+      node.addEventListener("mouseleave", removePause);
+      node.addEventListener("focusin", addPause);
+      node.addEventListener("focusout", removePause);
+
+      const handle: ToastHandle = { el: node, progressEl, enterRaf: null };
+      stack.appendChild(node);
+      // Deferred a frame so the resting is-entering state resolves before
+      // is-shown is applied — the node's first style resolution has nothing
+      // to transition from otherwise.
+      handle.enterRaf = requestAnimationFrame(() => {
+        handle.enterRaf = null;
+        node.classList.remove("is-entering");
+        node.classList.add("is-shown");
+      });
+
+      return handle;
+    },
+
+    scheduleLeave(handle: ToastHandle, done: () => void): void {
+      const node = handle.el;
+      // A dismiss can land before the enter frame runs. Force is-shown now so
+      // the leave has a defined start state — is-entering has no stylesheet
+      // rule (opacity 0, same as is-leaving), so that pairing is no change and
+      // starts no transition.
+      if (handle.enterRaf !== null) {
+        cancelAnimationFrame(handle.enterRaf);
+        handle.enterRaf = null;
+        node.classList.remove("is-entering");
+        node.classList.add("is-shown");
+      }
+      runTransition(node, {
+        change: () => {
+          node.classList.remove("is-shown");
+          node.classList.add("is-leaving");
+        },
+        settled: () => {
+          node.remove();
+          done();
+        },
+      });
+    },
+
+    remove(handle: ToastHandle): void {
+      if (handle.enterRaf !== null) {
+        cancelAnimationFrame(handle.enterRaf);
+        handle.enterRaf = null;
+      }
+      cancelTransition(handle.el);
+      handle.el.remove();
+    },
+
+    pauseProgress(handle: ToastHandle): void {
+      if (handle.progressEl !== null) {
+        handle.progressEl.style.animationPlayState = "paused";
+      }
+    },
+
+    resumeProgress(handle: ToastHandle): void {
+      if (handle.progressEl !== null) {
+        handle.progressEl.style.animationPlayState = "running";
+      }
+    },
+
+    dispose(): void {
+      releaseAdopted();
+      if (container !== null) {
+        container.remove();
+        container = null;
+      }
+    },
+  };
+}
+
+/** Invoke a retry handler, guarding both sync throws and async rejections. */
+function runRetry(onClick: () => void | Promise<void>): void {
+  try {
+    const result = onClick();
+    if (result instanceof Promise) {
+      result.catch((err: unknown) => {
+        console.error("[uip-toast] retry handler rejected", err);
+      });
+    }
+  } catch (err) {
+    console.error("[uip-toast] retry handler threw", err);
+  }
+}