@vitavision/ui 0.8.0 → 0.10.0

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/VectorInput.tsx

@@ -52,8 +52,8 @@ export interface VectorInputProps {
  * A row of number fields editing one small vector, with the axis labels before the fields
  * and the unit once after them.
  *
- * Controlled. A `role="group"` named by `aria-label`, each field named by its label and
- * described by the unit. While a field has focus it shows what is typed; on blur or Enter it
+ * Controlled. A `role="group"` named by `aria-label`. Each field is named by the group and its
+ * label ("Translation x"), so two vectors on one screen stay apart, and is described by the unit. While a field has focus it shows what is typed; on blur or Enter it
  * shows the value at `precision`; Escape restores the value it had on focus. With `readOnly`
  * it renders a `ReadoutStrip` (`x 0.100 m · y …`) instead. The row carries `data-readonly`
  * and `data-disabled`.
@@ -106,6 +106,7 @@ export function VectorInput({
         <label key={index} className="flex min-w-0 flex-1 items-center gap-1">
           <span className="shrink-0 font-mono text-[11px] text-fg-subtle">{labelOf(index)}</span>
           <ComponentField
+            name={`${ariaLabel} ${labelOf(index)}`}
             value={component}
             precision={precision}
             step={step}
@@ -128,6 +129,7 @@ export function VectorInput({
 
 /** One component: formatted at rest, the typed text while focused. */
 function ComponentField({
+  name,
   value,
   precision,
   step,
@@ -137,6 +139,7 @@ function ComponentField({
   describedBy,
   onCommit,
 }: {
+  name: string;
   value: number;
   precision: number;
   step: number | undefined;
@@ -167,6 +170,7 @@ function ComponentField({
       min={min}
       max={max}
       disabled={disabled}
+      aria-label={name}
       aria-describedby={describedBy}
       onFocus={() => setDraft({ text: formatted, initial: value })}
       onBlur={() => setDraft(null)}

package/src/components/ui/index.ts

@@ -12,6 +12,16 @@ export { Button, ButtonLink, buttonClasses, type ButtonSize, type ButtonVariant
 export { DensityProvider, byDensity, useDensity, type Density } from "./Density";
 export { ConfirmDialog, Dialog, DialogClose } from "./Dialog";
 export { Disclosure } from "./Disclosure";
+export {
+  DropdownMenu,
+  MenuCheckboxItem,
+  MenuItem,
+  MenuLabel,
+  MenuSeparator,
+  type DropdownMenuProps,
+  type MenuCheckboxItemProps,
+  type MenuItemProps,
+} from "./DropdownMenu";
 export {
   Callout,
   type CalloutTone,
@@ -31,6 +41,14 @@ export {
   useControlHeight,
   type NumberInputProps,
 } from "./Input";
+export { Kbd } from "./Kbd";
+export {
+  Listbox,
+  type ListboxOption,
+  type ListboxOptionState,
+  type ListboxProps,
+} from "./Listbox";
+export { formatNumber, parseNumber } from "./numberText";
 export {
   PageHeader,
   type BackLink,
@@ -39,6 +57,7 @@ export {
   Section,
   type ReadoutItem,
 } from "./Panel";
+export { Popover, PopoverClose, type PopoverProps } from "./Popover";
 export {
   PoseInput,
   type PoseInputProps,
@@ -53,5 +72,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/listboxModel.ts

@@ -0,0 +1,63 @@
+/*
+ * Keyboard movement in a single-select listbox, as a pure function so it is tested without a
+ * DOM. `Listbox` calls it on every key press.
+ */
+
+/** The keys that move the active option. */
+export type ListboxKey = "ArrowDown" | "ArrowUp" | "Home" | "End" | "PageDown" | "PageUp";
+
+/**
+ * The option a key moves the active one to, skipping disabled options.
+ *
+ * Arrows move by one and stop at the ends (no wrap: a long list that wraps loses its place).
+ * Home and End go to the first and last enabled option. Page keys move by `page` options.
+ * From no active option (`-1`), Down and Page Down go to the first enabled option, and Up and
+ * Page Up to the last.
+ *
+ * @param disabled - Per option, whether it is disabled.
+ * @param from - The active index, or -1.
+ * @param key - The key pressed.
+ * @param page - Options per page, for Page Up/Down. Defaults to 10.
+ * @returns The new active index; `from` when there is nowhere to go; -1 when every option is
+ *   disabled.
+ */
+export function moveActive(
+  disabled: readonly boolean[],
+  from: number,
+  key: ListboxKey,
+  page = 10,
+): number {
+  const enabled = disabled.flatMap((off, index) => (off ? [] : [index]));
+  if (enabled.length === 0) return -1;
+  const first = enabled[0]!;
+  const last = enabled[enabled.length - 1]!;
+  if (key === "Home") return first;
+  if (key === "End") return last;
+  if (from < 0) return key === "ArrowDown" || key === "PageDown" ? first : last;
+
+  const forward = key === "ArrowDown" || key === "PageDown";
+  const steps = key === "PageDown" || key === "PageUp" ? Math.max(1, page) : 1;
+  let target = from;
+  let moved = 0;
+  for (let index = from + (forward ? 1 : -1); index >= 0 && index < disabled.length; index += forward ? 1 : -1) {
+    if (disabled[index]) continue;
+    target = index;
+    moved += 1;
+    if (moved === steps) break;
+  }
+  return target;
+}
+
+/**
+ * The first enabled option at or after `index`, or before it when none is after. Used to place
+ * the active option when the list opens or changes.
+ *
+ * @param disabled - Per option, whether it is disabled.
+ * @param index - The preferred index.
+ * @returns An enabled index, or -1 when every option is disabled.
+ */
+export function nearestEnabled(disabled: readonly boolean[], index: number): number {
+  for (let i = Math.max(0, index); i < disabled.length; i += 1) if (!disabled[i]) return i;
+  for (let i = Math.min(index, disabled.length) - 1; i >= 0; i -= 1) if (!disabled[i]) return i;
+  return -1;
+}

package/src/components/ui/numberText.ts

@@ -1,6 +1,6 @@
 /*
- * Numbers as a field shows them and as a person types them. Internal to this package (used by
- * `VectorInput` and `PoseInput`); not exported.
+ * Numbers as a field shows them and as a person types them. Used by `NumberInput`'s
+ * number-valued mode, `VectorInput` and `PoseInput`, and exported for an app's own fields.
  *
  * A field bound straight to a number re-formats under the cursor: typing `0.` into a field
  * showing `0.000` becomes `0` before the next digit arrives. So the multi-number fields keep

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;
     }
   }
 }