@stonedogcode/style 0.17.0 → 0.20.0

package/src/components/StyledToaster.tsx

@@ -0,0 +1,325 @@
+"use client";
+
+import React, { useEffect, useRef, useState, useSyncExternalStore } from "react";
+import { createPortal } from "react-dom";
+import { toastRecipe } from "styled-system/recipes";
+import { cx } from "styled-system/css";
+
+import StyledButton from "./StyledButton";
+import StyledSpinner from "./StyledSpinner";
+import StyledText from "./StyledText";
+import type { Toast, ToasterStore, ToastType } from "./toaster-store";
+
+/**
+ * Draws whatever is in a toaster store.
+ *
+ * Mount **one** of these, once, near the root of the application, and hand it
+ * the same store your `create()` calls go to. It renders nothing until there is
+ * something to show.
+ *
+ * ```tsx
+ * export const toaster = createToaster();
+ * // …somewhere near the root:
+ * <StyledToaster toaster={toaster} />
+ * // …anywhere at all:
+ * toaster.create({ title: "Saved.", type: "success" });
+ * ```
+ *
+ * ## The three things that make this SSR-safe
+ *
+ * All three were failure modes before they were requirements, and none of them
+ * shows up in a client-only test:
+ *
+ * 1. **`getServerSnapshot`** — `useSyncExternalStore` throws during hydration
+ *    without one. The store supplies a frozen empty array, the same reference
+ *    every time, so React sees no change between the server render and the
+ *    first client one.
+ * 2. **The portal waits for mount.** `createPortal(…, document.body)` is a
+ *    `document is not defined` crash on the server. `mounted` below is false
+ *    for the server render *and* for the first client render, which is what
+ *    keeps the two identical — checking `typeof document` instead would make
+ *    them differ and produce a hydration mismatch rather than a crash.
+ * 3. **The store refuses to queue on the server**, so a toast created during a
+ *    render cannot leak into the next request. That one lives in the store; see
+ *    its header.
+ *
+ * ## Timers start here, not in the store
+ *
+ * A toast created before this component mounts — during a redirect, a slow
+ * hydration, an early event handler — must still be seen. Because each toast's
+ * countdown is an effect *in the toast's own element*, it cannot start before
+ * that element exists, so an early toast waits rather than expiring unseen.
+ */
+export interface StyledToasterProps {
+  /** The store to draw. Create it with `createToaster()`. */
+  toaster: ToasterStore;
+  /**
+   * The glyph for each kind of toast.
+   *
+   * **This package ships no icon artwork**, deliberately — see CLAUDE.md. The
+   * defaults are text characters, which work everywhere and are nobody's
+   * favourite. Pass your own icon set here to replace them; pass `null` for a
+   * type to render no glyph at all.
+   *
+   * Whatever you pass is `aria-hidden`: the toast's role already tells a screen
+   * reader what kind of message it is, and reading "check mark" before the text
+   * is the same information twice.
+   */
+  icons?: Partial<Record<ToastType, React.ReactNode>> | undefined;
+  /** The glyph inside the close control. Text by default, for the same reason. */
+  closeIcon?: React.ReactNode;
+  /**
+   * The close control's accessible name. It is a button whose only content is a
+   * glyph, so without a name it announces as "button" and nothing else.
+   */
+  closeLabel?: string;
+  /**
+   * Names the region for a screen reader listing landmarks.
+   *
+   * Not the toasts themselves — those announce individually as they arrive.
+   */
+  regionLabel?: string;
+}
+
+/**
+ * Text stand-ins for the artwork this package will not ship.
+ *
+ * `default` has none on purpose: it is the type for a message with no status,
+ * and inventing a glyph for "no particular kind" would say something the
+ * message does not.
+ */
+const DEFAULT_ICONS: Partial<Record<ToastType, React.ReactNode>> = {
+  success: "✓",
+  error: "✕",
+  warning: "!",
+  info: "i",
+};
+
+/**
+ * One toast, and the only place a dismissal timer exists.
+ *
+ * The timer is an effect keyed on `paused`, which gives pause-and-resume for
+ * free: pausing tears the effect down, and the cleanup subtracts the elapsed
+ * time from what is left, so resuming schedules the remainder rather than
+ * restarting the whole duration. Unmounting runs the same cleanup, so a toast
+ * removed mid-countdown cannot fire a state update into a component that is no
+ * longer there.
+ */
+function ToastItem({
+  toast,
+  paused,
+  onDismiss,
+  icons,
+  closeIcon,
+  closeLabel,
+}: {
+  toast: Toast;
+  paused: boolean;
+  onDismiss: (id: string) => void;
+  icons: Partial<Record<ToastType, React.ReactNode>>;
+  closeIcon: React.ReactNode;
+  closeLabel: string;
+}) {
+  /**
+   * Resolved PER TOAST, with this toast's type.
+   *
+   * The first version called `toastRecipe()` once for the whole region and
+   * shared the result, so every card came out as `toast__root--type_default`
+   * and no status accent was ever painted — the recipe was correct, its
+   * stylesheet was correct, and nothing rendered it. Neither the unit tier
+   * (which asserts roles and text) nor the token-contract test (which reads the
+   * stylesheet) could see it; the component test comparing three computed
+   * accent colours found all three identical.
+   */
+  const classes = toastRecipe({ type: toast.type });
+
+  const remaining = useRef(toast.duration);
+
+  useEffect(() => {
+    // `loading` and anything given `Infinity` stay until something dismisses
+    // them. Scheduling a timeout for Infinity is not merely pointless — the
+    // value overflows a 32-bit delay and fires immediately, which would make
+    // "stays until dismissed" mean "vanishes at once".
+    if (paused || toast.dismissed || !Number.isFinite(remaining.current)) return;
+
+    const startedAt = Date.now();
+    const timer = setTimeout(() => onDismiss(toast.id), remaining.current);
+
+    return () => {
+      clearTimeout(timer);
+      remaining.current -= Date.now() - startedAt;
+    };
+  }, [paused, toast.dismissed, toast.id, onDismiss]);
+
+  const glyph = icons[toast.type];
+
+  return (
+    <div
+      // `status` rather than `alert`: polite, so it waits for a gap in whatever
+      // the reader is already saying instead of cutting across it. An
+      // interruption is right for a fire alarm and wrong for "Saved."
+      //
+      // `aria-atomic` makes the whole toast read as one message. Without it a
+      // reader announces only the part of the subtree that changed, which for a
+      // toast updated in place is a fragment with no context.
+      role="status"
+      aria-atomic="true"
+      data-state={toast.dismissed ? "closed" : "open"}
+      data-type={toast.type}
+      className={classes.root}
+    >
+      {/*
+        `aria-hidden` on the whole indicator, spinner included.
+
+        The glyph is hidden because the toast's role has already told the reader
+        what kind of message this is, and "check mark, Saved." is the same thing
+        twice. The SPINNER is hidden for a sharper reason: `StyledSpinner`
+        carries its own `role="status"`, so rendering it bare nests one live
+        region inside another — the message is announced twice, and the outer
+        `aria-atomic` no longer describes one coherent thing. What tells a
+        reader the work is still going is the toast's own text ("Uploading…"),
+        which is the part worth reading anyway.
+      */}
+      {(toast.type === "loading" || glyph != null) && (
+        <div className={classes.indicator} aria-hidden="true">
+          {toast.type === "loading" ? <StyledSpinner loadText="" /> : glyph}
+        </div>
+      )}
+
+      <div className={classes.content}>
+        {toast.title != null && (
+          <StyledText className={classes.title}>{toast.title}</StyledText>
+        )}
+        {toast.description != null && (
+          <StyledText className={classes.description}>
+            {toast.description}
+          </StyledText>
+        )}
+      </div>
+
+      {toast.action && (
+        <div className={classes.action}>
+          <StyledButton
+            onClick={() => {
+              toast.action?.onClick();
+              // A toast whose button has been pressed has done its job. Leaving
+              // it up invites a second press on an action that has already run.
+              onDismiss(toast.id);
+            }}
+          >
+            {toast.action.label}
+          </StyledButton>
+        </div>
+      )}
+
+      {toast.closable && (
+        <button
+          type="button"
+          aria-label={closeLabel}
+          className={classes.close}
+          onClick={() => onDismiss(toast.id)}
+        >
+          <span aria-hidden="true">{closeIcon}</span>
+        </button>
+      )}
+    </div>
+  );
+}
+
+export const StyledToaster: React.FC<StyledToasterProps> = ({
+  toaster,
+  icons,
+  closeIcon = "✕",
+  closeLabel = "Dismiss notification",
+  regionLabel = "Notifications",
+}) => {
+  const toasts = useSyncExternalStore(
+    toaster.subscribe,
+    toaster.getSnapshot,
+    toaster.getServerSnapshot,
+  );
+
+  const [mounted, setMounted] = useState(false);
+  useEffect(() => setMounted(true), []);
+
+  /**
+   * Pointer or keyboard inside the region, and the tab being hidden, all stop
+   * the clock. They are one boolean rather than three because the resume
+   * condition is "none of them", and three independent flags is how a toast
+   * ends up pinned forever by a hover the pointer left through a portal.
+   */
+  const [hovered, setHovered] = useState(false);
+  const [focused, setFocused] = useState(false);
+  const [pageHidden, setPageHidden] = useState(false);
+
+  useEffect(() => {
+    if (typeof document === "undefined") return;
+    // A countdown that runs in a background tab is a message the user never had
+    // the chance to read. Chakra's store called this `pauseOnPageIdle` and had
+    // it on; this keeps that, without the option, because no consumer wanted
+    // the other behaviour.
+    const sync = () => setPageHidden(document.hidden);
+    sync();
+    document.addEventListener("visibilitychange", sync);
+    return () => document.removeEventListener("visibilitychange", sync);
+  }, []);
+
+  const paused = hovered || focused || pageHidden;
+
+  // Stable identity so it is not a fresh dependency on every render of every
+  // toast — each toast's timer effect lists it.
+  const onDismiss = React.useCallback(
+    (id: string) => toaster.remove(id),
+    [toaster],
+  );
+
+  // Only the region slot is read here; every card resolves its own, above.
+  const classes = toastRecipe();
+  const resolvedIcons = icons ?? DEFAULT_ICONS;
+
+  if (!mounted) return null;
+
+  return createPortal(
+    <div
+      className={cx(classes.region)}
+      // The region is present from mount and stays, whether or not it holds
+      // anything. A live region created at the same moment as its content is
+      // announced inconsistently across screen readers; one that was already
+      // there is not.
+      aria-label={regionLabel}
+      onMouseEnter={() => setHovered(true)}
+      onMouseLeave={() => setHovered(false)}
+      onFocus={() => setFocused(true)}
+      onBlur={(event) => {
+        // Only when focus has actually left the region — moving between the
+        // action and the close button inside one toast fires blur too, and
+        // treating that as "focus left" would restart the countdown under the
+        // keyboard user's hands.
+        if (!event.currentTarget.contains(event.relatedTarget as Node | null)) {
+          setFocused(false);
+        }
+      }}
+    >
+      {/*
+        Rendered oldest-last so the newest toast sits nearest the corner, which
+        is where the eye already is. The store keeps them newest-first because
+        that is the order its priority rules work in; the reversal is a
+        presentation decision and belongs here.
+      */}
+      {[...toasts].reverse().map((toast) => (
+        <ToastItem
+          key={toast.id}
+          toast={toast}
+          paused={paused}
+          onDismiss={onDismiss}
+          icons={resolvedIcons}
+          closeIcon={closeIcon}
+          closeLabel={closeLabel}
+        />
+      ))}
+    </div>,
+    document.body,
+  );
+};
+
+export default StyledToaster;

package/src/components/toaster-store.ts

@@ -0,0 +1,334 @@
+/**
+ * The toast queue: a subscribable store, with no React and no DOM in it.
+ *
+ * ## Why this is a store and not a component
+ *
+ * A toast is created from places that are not rendering — an event handler, a
+ * `.catch()`, a module-level helper called before anything has mounted. So the
+ * thing callers reach for cannot be a hook. It has to be a plain object with a
+ * `create()` on it, and the component that draws toasts has to *subscribe* to
+ * that object rather than own it.
+ *
+ * That shape is what `useSyncExternalStore` exists for, and the three methods
+ * below (`subscribe`, `getSnapshot`, `getServerSnapshot`) are exactly its
+ * contract. Two of its rules are easy to break and fail loudly but obscurely:
+ *
+ * - **`getSnapshot` must return the identical reference when nothing changed.**
+ *   Returning a fresh array each call makes React re-render forever. `toasts`
+ *   below is therefore replaced only on mutation, never rebuilt on read.
+ * - **`getServerSnapshot` is mandatory** for anything server-rendered, and must
+ *   also be reference-stable. `EMPTY` is a single frozen array shared by every
+ *   call for that reason.
+ *
+ * ## Why `create()` does nothing on the server
+ *
+ * A module-level array lives for the lifetime of the Node process, not the
+ * request. A toast created during SSR would therefore still be sitting in the
+ * queue when the *next* user is served by that same instance — one person's
+ * "Saved." announced to a stranger. There is no request boundary available here
+ * to scope it to, and a toast has no meaning without a browser to show it in,
+ * so the honest answer is to refuse to queue one at all.
+ *
+ * `create()` still returns the id it would have used, so a caller that stores
+ * or logs the result behaves identically in both environments.
+ *
+ * ## Timers are deliberately NOT here
+ *
+ * Auto-dismiss lives in the renderer, per toast, starting when that toast first
+ * mounts. Putting it here would start the clock at `create()` time — so a toast
+ * fired before the toaster mounted (a redirect, a slow hydration, a `create()`
+ * in a module body) could expire before it was ever drawn. It would look like
+ * the toast was silently dropped, which is the failure this whole component is
+ * most likely to be blamed for and least likely to be caught doing.
+ *
+ * What *is* here is the exit delay, because it is a property of leaving the
+ * queue rather than of being on screen: `remove()` marks a toast `dismissed`
+ * and purges it `removeDelay` ms later, so the renderer has a state to animate
+ * out of.
+ */
+
+import type { ReactNode } from "react";
+
+/**
+ * The kinds of toast, matching what the extracted application already used.
+ *
+ * `default` is a toast with no status at all — no accent, no glyph. It is not a
+ * synonym for `info`; a message that means something should say which thing it
+ * means.
+ */
+export type ToastType =
+  | "success"
+  | "error"
+  | "warning"
+  | "info"
+  | "loading"
+  | "default";
+
+/** A single button on a toast. Rendered after the message. */
+export interface ToastAction {
+  label: string;
+  onClick: () => void;
+}
+
+export interface ToastOptions {
+  /**
+   * Supply one to make `create()` idempotent — creating with an id that is
+   * already on screen updates that toast in place rather than stacking a
+   * duplicate. Useful for progress ("Uploading…" → "Uploaded").
+   */
+  id?: string | undefined;
+  title?: ReactNode;
+  description?: ReactNode;
+  type?: ToastType | undefined;
+  /**
+   * Milliseconds on screen. Omit to use the per-type default below.
+   * `Infinity` pins the toast until it is dismissed.
+   */
+  duration?: number | undefined;
+  action?: ToastAction | undefined;
+  /** Render a close control. */
+  closable?: boolean | undefined;
+}
+
+export interface Toast extends ToastOptions {
+  id: string;
+  type: ToastType;
+  duration: number;
+  /**
+   * Set the moment `remove()` is called and the toast starts animating out.
+   * It stays in the snapshot while true so the renderer has something to
+   * animate; it is purged `removeDelay` ms later.
+   */
+  dismissed: boolean;
+}
+
+export interface ToasterStoreOptions {
+  /**
+   * How many toasts may be on screen at once. Further ones wait in a queue and
+   * are admitted as room appears.
+   *
+   * 24 is not a considered number — it is the value the store this replaces
+   * used, kept so that the behaviour at overflow does not change silently along
+   * with everything else.
+   */
+  max?: number;
+  /** How long a dismissed toast stays in the snapshot so it can animate out. */
+  removeDelay?: number;
+}
+
+export interface ToasterStore {
+  /**
+   * Show a toast. Returns its id.
+   *
+   * Named `create` rather than `show` or `toast` because that is the name the
+   * 345 call sites in the application this was extracted from already use.
+   */
+  create: (options: ToastOptions) => string;
+  /**
+   * Dismiss one toast, or every toast when called with no argument.
+   *
+   * The toast animates out first — it is marked `dismissed` immediately and
+   * leaves the snapshot `removeDelay` ms later.
+   */
+  remove: (id?: string) => void;
+  subscribe: (listener: () => void) => () => void;
+  getSnapshot: () => readonly Toast[];
+  getServerSnapshot: () => readonly Toast[];
+}
+
+/**
+ * How long each kind stays up, in milliseconds.
+ *
+ * These are not invented. They are the values `@zag-js/toast` uses, read out of
+ * the installed package rather than guessed, so that swapping the
+ * implementation underneath an application does not quietly retime every
+ * message in it. Note `success` is much shorter than the rest — a confirmation
+ * has been read the moment it is seen, whereas a warning is asking for a
+ * decision.
+ */
+export const DEFAULT_DURATIONS: Record<ToastType, number> = {
+  success: 2000,
+  error: 5000,
+  warning: 5000,
+  info: 5000,
+  loading: Infinity,
+  default: 5000,
+};
+
+/**
+ * Which toast wins a place on screen when more than `max` are pending.
+ *
+ * Lower sorts first. Errors outrank confirmations because a failure the user
+ * never sees is the expensive one, and within a type an *actionable* toast
+ * outranks a passive one — there is nothing to miss on a toast with no button.
+ *
+ * Only consulted past `max` simultaneous toasts, which in practice means a loop
+ * that has gone wrong. It exists so that what survives that is the half worth
+ * reading.
+ */
+const PRIORITY: Record<ToastType, [actionable: number, passive: number]> = {
+  error: [1, 2],
+  warning: [3, 6],
+  loading: [4, 5],
+  success: [5, 7],
+  info: [6, 8],
+  default: [6, 8],
+};
+
+const priorityOf = (toast: Toast): number =>
+  PRIORITY[toast.type][toast.action ? 0 : 1];
+
+/**
+ * One frozen array, returned by every server render and by any snapshot taken
+ * of an empty store. `useSyncExternalStore` compares snapshots by reference, so
+ * a fresh `[]` here would be a new value on every read.
+ */
+const EMPTY: readonly Toast[] = Object.freeze([]);
+
+/** `window` is the only reliable "is there a user in front of this" signal. */
+const inBrowser = (): boolean => typeof window !== "undefined";
+
+export function createToaster(options: ToasterStoreOptions = {}): ToasterStore {
+  const { max = 24, removeDelay = 200 } = options;
+
+  let toasts: readonly Toast[] = EMPTY;
+  let queued: Toast[] = [];
+  let listeners: Array<() => void> = [];
+  let counter = 0;
+
+  /**
+   * Ids are a counter, not a random or time-based value, so that a test can
+   * assert on one and so two toasts created in the same millisecond cannot
+   * collide. They are scoped to this store and never leave it.
+   */
+  const nextId = (): string => `toast-${++counter}`;
+
+  const emit = (): void => {
+    // Copied before iterating: a listener that unsubscribes itself while being
+    // notified would otherwise shorten the array mid-loop and skip its
+    // neighbour.
+    for (const listener of [...listeners]) listener();
+  };
+
+  /** Admit queued toasts until the screen is full again. */
+  const drain = (): void => {
+    if (queued.length === 0 || toasts.length >= max) return;
+    queued.sort((a, b) => priorityOf(a) - priorityOf(b));
+    const admitted = queued.splice(0, max - toasts.length);
+    // Queued toasts were created after everything on screen, so they go in
+    // front; among themselves the highest priority leads.
+    toasts = [...admitted, ...toasts];
+  };
+
+  const purge = (id: string): void => {
+    const next = toasts.filter((toast) => toast.id !== id);
+    if (next.length === toasts.length) return;
+    toasts = next.length === 0 ? EMPTY : next;
+    drain();
+    emit();
+  };
+
+  const create = (options: ToastOptions): string => {
+    const id = options.id ?? nextId();
+
+    // See the header: never queue on the server.
+    if (!inBrowser()) return id;
+
+    const existing = toasts.find((toast) => toast.id === id);
+    if (existing) {
+      const type = options.type ?? existing.type;
+      const updated: Toast = {
+        ...existing,
+        ...options,
+        id,
+        type,
+        // A change of TYPE re-derives the duration, and that is the whole point
+        // of this branch. The progress case — `loading` ("Uploading…") updated
+        // in place to `success` ("Uploaded.") — carries no explicit duration,
+        // and `loading` means `Infinity`. Simply keeping the old value leaves
+        // the finished toast pinned to the screen forever, which reads as the
+        // upload never having completed. Only an explicit `duration` overrides.
+        duration:
+          options.duration ??
+          (type === existing.type ? existing.duration : DEFAULT_DURATIONS[type]),
+        // Re-creating an id that is on its way out brings it back.
+        dismissed: false,
+      };
+      toasts = toasts.map((toast) => (toast.id === id ? updated : toast));
+      emit();
+      return id;
+    }
+
+    const type = options.type ?? "info";
+    const toast: Toast = {
+      ...options,
+      id,
+      type,
+      duration: options.duration ?? DEFAULT_DURATIONS[type],
+      dismissed: false,
+    };
+
+    if (toasts.length >= max) {
+      queued.push(toast);
+      return id;
+    }
+
+    toasts = [toast, ...toasts];
+    emit();
+    return id;
+  };
+
+  const remove = (id?: string): void => {
+    if (id === undefined) {
+      queued = [];
+      if (toasts.length === 0) return;
+      toasts = toasts.map((toast) => ({ ...toast, dismissed: true }));
+      emit();
+      const ids = toasts.map((toast) => toast.id);
+      schedulePurge(() => ids.forEach(purge));
+      return;
+    }
+
+    const target = toasts.find((toast) => toast.id === id);
+    if (!target) {
+      // It may still be waiting for a slot; drop it before it ever appears.
+      queued = queued.filter((toast) => toast.id !== id);
+      return;
+    }
+    if (target.dismissed) return;
+
+    toasts = toasts.map((toast) =>
+      toast.id === id ? { ...toast, dismissed: true } : toast,
+    );
+    emit();
+    schedulePurge(() => purge(id));
+  };
+
+  /**
+   * The exit delay, skipped entirely off-browser.
+   *
+   * A `setTimeout` on the server would keep the event loop alive and fire into
+   * a store nothing is subscribed to. There is nothing to animate there, so the
+   * removal is immediate.
+   */
+  const schedulePurge = (run: () => void): void => {
+    if (!inBrowser() || removeDelay <= 0) {
+      run();
+      return;
+    }
+    setTimeout(run, removeDelay);
+  };
+
+  return {
+    create,
+    remove,
+    subscribe: (listener) => {
+      listeners = [...listeners, listener];
+      return () => {
+        listeners = listeners.filter((candidate) => candidate !== listener);
+      };
+    },
+    getSnapshot: () => toasts,
+    getServerSnapshot: () => EMPTY,
+  };
+}