@vitavision/ui 0.8.0 → 0.9.0

package/README.md

@@ -127,7 +127,8 @@ keep independent preferences.
 `SkeletonRows` · `Field` · `Input`, `NumberInput` (with an optional `unit` written in the
 field), `Textarea` · `VectorInput`, `PoseInput` · `PageHeader`, `Panel`,
 `ReadoutStrip`, `Section` · `SegmentedControl` · `Select` · `Slider` · `Table` ·
-`Checkbox`, `Switch` · `ToggleChip` · `InfoHint`, `Tooltip`, `TooltipProvider` ·
+`Checkbox`, `Switch` · `ToggleChip` · `Toaster`, `toast()` (notifications from anywhere; mount one `<Toaster />` near the root) ·
+`InfoHint`, `Tooltip`, `TooltipProvider` ·
 `ThemeToggle` · plus `cn`, `focusRing`, `focusRingInset`.
 
 `PoseInput` edits an SE(3) pose in the wire form `{ rotation: [qx, qy, qz, qw], translation:

package/dist/index.d.ts

@@ -880,6 +880,97 @@ export declare function ToggleChip({ checked, onCheckedChange, children, swatch,
   className?: string | undefined;
 }): import("react").JSX.Element;
 //#endregion
+//#region src/components/ui/toastStore.d.ts
+/** A toast's kind: a fact (`info`), a completed action (`success`), a caveat (`warn`), a failure (`error`). */
+type ToastTone = "info" | "success" | "warn" | "error";
+/** What `toast()` takes. */
+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. */
+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.
+ */
+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;
+}
+/**
+ * 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 declare function createToastStore(): ToastStore;
+/** The store behind `toast()` and a `<Toaster />` given no `store`. */
+export declare const defaultToastStore: ToastStore;
+/**
+ * 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 declare const toast: ((options: ToastOptions) => string) & {
+  /** Remove one toast, or every toast when `id` is omitted. */
+  dismiss: (id?: string) => void;
+};
+//#endregion
+//#region src/components/ui/Toaster.d.ts
+/** Props of `Toaster`. */
+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 declare function Toaster({ store, limit, className }: ToasterProps): import("react").JSX.Element;
+//#endregion
 //#region src/components/ui/Tooltip.d.ts
 /**
  * Shares one open delay (200 ms) across the tooltips below it. Mount it once near the root:
@@ -999,5 +1090,5 @@ export declare function Tabs<Id extends string>({ items, active, onSelect, label
   className?: string | undefined;
 }): import("react").JSX.Element;
 //#endregion
-export type { BackLink, ButtonSize, ButtonVariant, CalloutTone, Column, Density, MeasureTone, NumberInputProps, PoseInputProps, PoseValue, Quaternion, ReadoutItem, RotationView, SelectOption, TabItem, ThemeChoice, Tone, Vec3, VectorInputProps };
+export type { BackLink, ButtonSize, ButtonVariant, CalloutTone, Column, Density, MeasureTone, NumberInputProps, PoseInputProps, PoseValue, Quaternion, ReadoutItem, RotationView, SelectOption, TabItem, ThemeChoice, ToastOptions, ToastRecord, ToastStore, ToastTone, ToasterProps, Tone, Vec3, VectorInputProps };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,5 +1,5 @@
-import { AlertTriangle, Check, CheckCircle2, ChevronDown, ChevronRight, HelpCircle, Info, Loader2, Minus, Moon, Sun, SunMoon, XCircle } from "lucide-react";
-import { createContext, isValidElement, use, useCallback, useId, useMemo, useState, useSyncExternalStore } from "react";
+import { AlertTriangle, Check, CheckCircle2, ChevronDown, ChevronRight, CircleCheck, CircleX, HelpCircle, Info, Loader2, Minus, Moon, Sun, SunMoon, TriangleAlert, X, XCircle } from "lucide-react";
+import { createContext, isValidElement, use, useCallback, useEffect, useId, useMemo, useRef, useState, useSyncExternalStore } from "react";
 import * as RadixTooltip from "@radix-ui/react-tooltip";
 import { clsx } from "clsx";
 import { twMerge } from "tailwind-merge";
@@ -1558,6 +1558,187 @@ function ToggleChip({ checked, onCheckedChange, children, swatch, disabled = fal
 	});
 }
 //#endregion
+//#region src/components/ui/toastStore.ts
+const DEFAULT_DURATION = 5e3;
+const ERROR_DURATION = 8e3;
+/**
+* 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.
+*/
+function createToastStore() {
+	let toasts = [];
+	let sequence = 0;
+	const listeners = /* @__PURE__ */ new Set();
+	const commit = (next) => {
+		toasts = next;
+		for (const listener of [...listeners]) listener();
+	};
+	return {
+		toast: (options) => {
+			const tone = options.tone ?? "info";
+			sequence += 1;
+			const record = {
+				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 === void 0) {
+				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`. */
+const defaultToastStore = 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.
+*/
+const toast = Object.assign((options) => defaultToastStore.toast(options), { dismiss: (id) => defaultToastStore.dismiss(id) });
+//#endregion
+//#region src/components/ui/Toaster.tsx
+const TONE = {
+	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 = [];
+/**
+* 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.
+*/
+function Toaster({ store = defaultToastStore, limit = 5, className }) {
+	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) => {
+		if (!event.currentTarget.contains(event.relatedTarget)) setFocused(false);
+	};
+	return /* @__PURE__ */ jsx("section", {
+		"aria-label": "Notifications",
+		onPointerEnter: () => setHovered(true),
+		onPointerLeave: () => setHovered(false),
+		onFocus: () => setFocused(true),
+		onBlur,
+		className: cn("pointer-events-none fixed right-4 bottom-4 z-50 w-80 max-w-[calc(100vw-2rem)]", className),
+		children: /* @__PURE__ */ jsx("ol", {
+			"aria-live": "polite",
+			className: "flex flex-col gap-2",
+			children: shown.map((record) => /* @__PURE__ */ jsx(ToastItem, {
+				record,
+				paused: hovered || focused,
+				onDismiss: () => store.dismiss(record.id)
+			}, record.id))
+		})
+	});
+}
+function ToastItem({ record, paused, onDismiss }) {
+	const { border, icon, Icon } = TONE[record.tone];
+	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 /* @__PURE__ */ jsx("li", {
+		className: "pointer-events-auto",
+		children: /* @__PURE__ */ jsxs("div", {
+			role: record.tone === "error" ? "alert" : void 0,
+			"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),
+			children: [
+				/* @__PURE__ */ jsx(Icon, {
+					className: cn("mt-0.5 size-4 shrink-0", icon),
+					"aria-hidden": true
+				}),
+				/* @__PURE__ */ jsxs("div", {
+					className: "flex min-w-0 flex-1 flex-col gap-0.5",
+					children: [/* @__PURE__ */ jsx("p", {
+						className: "font-medium text-fg",
+						children: record.title
+					}), record.description && /* @__PURE__ */ jsx("p", {
+						className: "text-fg-muted",
+						children: record.description
+					})]
+				}),
+				/* @__PURE__ */ jsx("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),
+					children: /* @__PURE__ */ jsx(X, {
+						className: "size-3.5",
+						"aria-hidden": true
+					})
+				})
+			]
+		})
+	});
+}
+//#endregion
 //#region src/components/Tabs.tsx
 const NEXT_KEYS = {
 	ArrowRight: (index, length) => (index + 1) % length,
@@ -1620,6 +1801,6 @@ function Tabs({ items, active, onSelect, label, idPrefix, className }) {
 	});
 }
 //#endregion
-export { Badge, Button, ButtonLink, Callout, Checkbox, ConfirmDialog, CountRun, DEFAULT_THEME_STORAGE_KEY, DensityProvider, Dialog, DialogClose, Disclosure, Empty, ErrorBox, Field, InfoHint, Input, NumberInput, PageHeader, Panel, PoseInput, ProgressBar, ReadoutStrip, Section, SegmentedControl, Select, Skeleton, SkeletonRows, Slider, StatusDot, Switch, Table, Tabs, Textarea, ThemeToggle, ToggleChip, Tooltip, TooltipProvider, VectorInput, buttonClasses, byDensity, cn, controlClasses, focusRing, focusRingInset, initTheme, inputClasses, readThemeChoice, resolveTheme, setThemeChoice, toneColor, useControlHeight, useDensity };
+export { Badge, Button, ButtonLink, Callout, Checkbox, ConfirmDialog, CountRun, DEFAULT_THEME_STORAGE_KEY, DensityProvider, Dialog, DialogClose, Disclosure, Empty, ErrorBox, Field, InfoHint, Input, NumberInput, PageHeader, Panel, PoseInput, ProgressBar, ReadoutStrip, Section, SegmentedControl, Select, Skeleton, SkeletonRows, Slider, StatusDot, Switch, Table, Tabs, Textarea, ThemeToggle, Toaster, ToggleChip, Tooltip, TooltipProvider, VectorInput, buttonClasses, byDensity, cn, controlClasses, createToastStore, defaultToastStore, focusRing, focusRingInset, initTheme, inputClasses, readThemeChoice, resolveTheme, setThemeChoice, toast, toneColor, useControlHeight, useDensity };
 
 //# sourceMappingURL=index.js.map