@vitavision/ui 0.8.0 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vitavision/ui",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "The vitavision instrument design system: Tailwind v4 tokens, theme, and React primitives.",
   "license": "MIT OR Apache-2.0",
   "repository": {

package/src/components/ui/Toaster.tsx

@@ -0,0 +1,148 @@
+/*
+ * Where `toast()` shows up.
+ *
+ * Toasts are for news that does not need an answer — a file loaded, a bake finished, a
+ * worker failed in the background. Anything that must be acknowledged is a `Dialog`, and
+ * anything tied to one control is that control's `Field` error. So a toast never carries an
+ * action beyond dismissing it, it goes away by itself, and it holds still while someone is
+ * reading it (pointer over the stack, or focus inside it).
+ *
+ * The tones reuse the `Callout` vocabulary — the accent for a fact, the verdict colours for
+ * success, caveat and failure — on an opaque `overlay` surface, since a toast floats over
+ * whatever the viewport is drawing.
+ */
+
+import { CircleCheck, CircleX, Info, TriangleAlert, X } from "lucide-react";
+import { useEffect, useRef, useState, useSyncExternalStore } from "react";
+import type { FocusEvent } from "react";
+
+import { cn, focusRing } from "./cn";
+import { defaultToastStore, type ToastRecord, type ToastStore, type ToastTone } from "./toastStore";
+
+const TONE: Record<ToastTone, { border: string; icon: string; Icon: typeof Info }> = {
+  info: { border: "border-signal/30", icon: "text-signal", Icon: Info },
+  success: { border: "border-normal/30", icon: "text-normal", Icon: CircleCheck },
+  warn: { border: "border-warn/30", icon: "text-warn", Icon: TriangleAlert },
+  error: { border: "border-defect/30", icon: "text-defect", Icon: CircleX },
+};
+
+const NO_TOASTS: readonly ToastRecord[] = [];
+
+/** Props of `Toaster`. */
+export interface ToasterProps {
+  /** The store to show. Defaults to the one behind `toast()`. */
+  store?: ToastStore | undefined;
+  /** How many toasts are shown at once; older ones wait. Defaults to 5. */
+  limit?: number | undefined;
+  /** Merged with the stack's own classes through `cn` (it is fixed to the bottom-right corner). */
+  className?: string | undefined;
+}
+
+/**
+ * The stack of notifications raised with `toast()`. Mount it once, near the root.
+ *
+ * Fixed to the bottom-right corner, newest at the bottom. Each toast dismisses itself after
+ * its `duration`; the countdown pauses while the pointer is over the stack or focus is inside
+ * it. A `section` landmark ("Notifications") holding a polite live region, so new toasts are
+ * announced; an `error` toast is a `role="alert"`, announced at once. Each toast carries
+ * `data-tone` and a "Dismiss" button.
+ */
+export function Toaster({ store = defaultToastStore, limit = 5, className }: ToasterProps) {
+  const toasts = useSyncExternalStore(store.subscribe, store.getSnapshot, () => NO_TOASTS);
+  const [hovered, setHovered] = useState(false);
+  const [focused, setFocused] = useState(false);
+  const shown = toasts.slice(-Math.max(1, limit));
+
+  const onBlur = (event: FocusEvent<HTMLElement>) => {
+    if (!event.currentTarget.contains(event.relatedTarget)) setFocused(false);
+  };
+
+  return (
+    <section
+      aria-label="Notifications"
+      onPointerEnter={() => setHovered(true)}
+      onPointerLeave={() => setHovered(false)}
+      onFocus={() => setFocused(true)}
+      onBlur={onBlur}
+      className={cn(
+        "pointer-events-none fixed right-4 bottom-4 z-50 w-80 max-w-[calc(100vw-2rem)]",
+        className,
+      )}
+    >
+      <ol aria-live="polite" className="flex flex-col gap-2">
+        {shown.map((record) => (
+          <ToastItem
+            key={record.id}
+            record={record}
+            paused={hovered || focused}
+            onDismiss={() => store.dismiss(record.id)}
+          />
+        ))}
+      </ol>
+    </section>
+  );
+}
+
+function ToastItem({
+  record,
+  paused,
+  onDismiss,
+}: {
+  record: ToastRecord;
+  paused: boolean;
+  onDismiss: () => void;
+}) {
+  const { border, icon, Icon } = TONE[record.tone];
+  // What is left of the countdown, carried across pauses; restarted when the toast is
+  // replaced in place (a new record under the same id).
+  const remainingRef = useRef({ record, ms: record.duration });
+  const dismissRef = useRef(onDismiss);
+  useEffect(() => {
+    dismissRef.current = onDismiss;
+  });
+
+  useEffect(() => {
+    if (remainingRef.current.record !== record) remainingRef.current = { record, ms: record.duration };
+    if (paused || !Number.isFinite(remainingRef.current.ms)) return;
+    const started = Date.now();
+    const timer = setTimeout(() => dismissRef.current(), remainingRef.current.ms);
+    return () => {
+      clearTimeout(timer);
+      remainingRef.current.ms = Math.max(0, remainingRef.current.ms - (Date.now() - started));
+    };
+  }, [paused, record]);
+
+  return (
+    // The `alert` role sits on the toast inside the list item, not on the `<li>`: an item with
+    // another role is no longer a list item, and the list would be malformed.
+    <li className="pointer-events-auto">
+      <div
+        role={record.tone === "error" ? "alert" : undefined}
+        data-tone={record.tone}
+        className={cn(
+          "flex items-start gap-2.5 rounded-panel border bg-overlay px-3 py-2.5 text-sm leading-snug shadow-lg shadow-black/25",
+          "transition-[opacity,translate] duration-200 starting:translate-y-2 starting:opacity-0",
+          border,
+        )}
+      >
+        <Icon className={cn("mt-0.5 size-4 shrink-0", icon)} aria-hidden />
+        <div className="flex min-w-0 flex-1 flex-col gap-0.5">
+          <p className="font-medium text-fg">{record.title}</p>
+          {record.description && <p className="text-fg-muted">{record.description}</p>}
+        </div>
+        <button
+          type="button"
+          aria-label="Dismiss"
+          title="Dismiss"
+          onClick={onDismiss}
+          className={cn(
+            "-mr-1 grid size-6 shrink-0 place-items-center rounded-control text-fg-subtle transition-colors hover:bg-raised hover:text-fg",
+            focusRing,
+          )}
+        >
+          <X className="size-3.5" aria-hidden />
+        </button>
+      </div>
+    </li>
+  );
+}

package/src/components/ui/index.ts

@@ -53,5 +53,15 @@ export { Slider } from "./Slider";
 export { Table, type Column } from "./Table";
 export { Checkbox, Switch } from "./Toggle";
 export { ToggleChip } from "./ToggleChip";
+export { Toaster, type ToasterProps } from "./Toaster";
+export {
+  createToastStore,
+  defaultToastStore,
+  toast,
+  type ToastOptions,
+  type ToastRecord,
+  type ToastStore,
+  type ToastTone,
+} from "./toastStore";
 export { InfoHint, Tooltip, TooltipProvider } from "./Tooltip";
 export { VectorInput, type VectorInputProps } from "./VectorInput";

package/src/components/ui/toastStore.ts

@@ -0,0 +1,128 @@
+/*
+ * Notifications, as a store any module can write to.
+ *
+ * A toast is raised from wherever the news is — a file loader, a worker's error handler, a
+ * bake that finished — which is rarely a component with a context in reach. So `toast()` is
+ * a plain function over a module-level store, and `<Toaster />`, mounted once, is its only
+ * reader. The store holds no timers and touches no DOM: auto-dismissal belongs to the
+ * `Toaster`, which is what knows whether a reader is hovering it.
+ */
+
+/** A toast's kind: a fact (`info`), a completed action (`success`), a caveat (`warn`), a failure (`error`). */
+export type ToastTone = "info" | "success" | "warn" | "error";
+
+/** What `toast()` takes. */
+export interface ToastOptions {
+  /** One line: what happened. */
+  title: string;
+  /** More detail, and what to do about it. */
+  description?: string | undefined;
+  /** Defaults to `info`. */
+  tone?: ToastTone | undefined;
+  /**
+   * How long it stays, in milliseconds, while not hovered or focused. Defaults to 5000
+   * (8000 for `error`); `Infinity` keeps it until dismissed.
+   */
+  duration?: number | undefined;
+  /** Replace the toast with this id instead of adding one — for progress that updates in place. */
+  id?: string | undefined;
+}
+
+/** A toast in the store. */
+export interface ToastRecord {
+  /** Identifies the toast to `dismiss` and to `id` replacement. */
+  id: string;
+  /** One line: what happened. */
+  title: string;
+  /** More detail, if any. */
+  description: string | undefined;
+  /** Its kind. */
+  tone: ToastTone;
+  /** Milliseconds before it dismisses itself (`Infinity`: never). */
+  duration: number;
+}
+
+/**
+ * A toast store: what `toast()` writes to and `<Toaster />` reads. Every member may be called
+ * detached.
+ */
+export interface ToastStore {
+  /** Add a toast (or replace the one with `options.id`), returning its id. */
+  readonly toast: (options: ToastOptions) => string;
+  /** Remove one toast, or every toast when `id` is omitted. */
+  readonly dismiss: (id?: string) => void;
+  /** The toasts, oldest first. The same array until the store changes. */
+  readonly getSnapshot: () => readonly ToastRecord[];
+  /** Be told when the toasts change; returns the unsubscribe function. */
+  readonly subscribe: (listener: () => void) => () => void;
+}
+
+const DEFAULT_DURATION = 5000;
+const ERROR_DURATION = 8000;
+
+/**
+ * A new, empty toast store. The package keeps one (behind `toast()` and the default
+ * `<Toaster />`); create another only to isolate a region or a test.
+ *
+ * @returns The store.
+ */
+export function createToastStore(): ToastStore {
+  let toasts: readonly ToastRecord[] = [];
+  let sequence = 0;
+  const listeners = new Set<() => void>();
+  const commit = (next: readonly ToastRecord[]) => {
+    toasts = next;
+    for (const listener of [...listeners]) listener();
+  };
+
+  return {
+    toast: (options) => {
+      const tone = options.tone ?? "info";
+      sequence += 1;
+      const record: ToastRecord = {
+        id: options.id ?? `toast-${sequence}`,
+        title: options.title,
+        description: options.description,
+        tone,
+        duration: options.duration ?? (tone === "error" ? ERROR_DURATION : DEFAULT_DURATION),
+      };
+      const existing = toasts.findIndex((t) => t.id === record.id);
+      commit(existing === -1 ? [...toasts, record] : toasts.map((t, i) => (i === existing ? record : t)));
+      return record.id;
+    },
+    dismiss: (id) => {
+      if (id === undefined) {
+        if (toasts.length > 0) commit([]);
+        return;
+      }
+      if (toasts.some((t) => t.id === id)) commit(toasts.filter((t) => t.id !== id));
+    },
+    getSnapshot: () => toasts,
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+  };
+}
+
+/** The store behind `toast()` and a `<Toaster />` given no `store`. */
+export const defaultToastStore: ToastStore = createToastStore();
+
+/**
+ * Raise a notification, from anywhere — shown by the mounted `<Toaster />`.
+ *
+ * `toast({ title: "Scenario loaded", tone: "success" })`. Pass `id` to update a toast in
+ * place (a progress message that becomes a result). `toast.dismiss(id)` removes one early,
+ * `toast.dismiss()` all of them.
+ *
+ * @param options - The message, its tone and its duration.
+ * @returns The toast's id.
+ */
+export const toast: ((options: ToastOptions) => string) & {
+  /** Remove one toast, or every toast when `id` is omitted. */
+  dismiss: (id?: string) => void;
+} = Object.assign((options: ToastOptions) => defaultToastStore.toast(options), {
+  dismiss: (id?: string) => defaultToastStore.dismiss(id),
+});

package/src/styles.css

@@ -159,13 +159,30 @@
     list-style: none;
   }
 
+  /*
+   * Reduced motion makes motion synchronous, not merely short.
+   *
+   * A transition of any non-zero duration -- 0.01ms included -- is still a transition: the
+   * computed style keeps its old value until the next frame, so code that sets a style and
+   * measures in the same tick (mermaid's layout) reads stale numbers wherever an element
+   * has `transition-property: all`. A 0s transition is never started, so the new value is
+   * visible at once. Nothing in this repo waits for `transitionend`.
+   *
+   * Animations keep a name with a 0s duration rather than `animation: none`: the animation
+   * still runs to its end state and fires `animationend` immediately, which is what Radix
+   * `Presence` waits for before unmounting an overlay whose consumer gave it an exit
+   * animation (`data-[state=closed]:animate-out`). `animation: none` would unmount it at
+   * once too, but would also freeze `animate-spin` / `animate-pulse` in their first frame.
+   */
   @media (prefers-reduced-motion: reduce) {
     *,
     *::before,
     *::after {
-      animation-duration: 0.01ms !important;
+      animation-duration: 0s !important;
+      animation-delay: 0s !important;
       animation-iteration-count: 1 !important;
-      transition-duration: 0.01ms !important;
+      transition-duration: 0s !important;
+      transition-delay: 0s !important;
     }
   }
 }