@teamofsilicons/silicon-ui 0.0.0-stage → 0.2.0

package/components/toast/toast.module.css

@@ -0,0 +1,100 @@
+.toast {
+  display: flex;
+  width: min(100%, 26rem);
+  min-width: 0;
+  align-items: flex-start;
+  gap: 0.75rem;
+  padding: 0.875rem 0.875rem 0.875rem 1rem;
+  border: 1px solid var(--border);
+  border-radius: var(--radius-container); corner-shape: var(--corner-shape);
+  background: color-mix(in oklab, var(--surface) 94%, var(--background));
+  color: var(--foreground);
+  letter-spacing: var(--tracking-body);
+  box-shadow: var(--shadow-floating);
+}
+
+.icon {
+  display: grid;
+  width: 1.875rem;
+  height: 1.875rem;
+  flex: 0 0 auto;
+  place-items: center;
+  border: 1px solid color-mix(in oklab, var(--success) 24%, var(--border));
+  border-radius: var(--radius-full); corner-shape: round;
+  background: color-mix(in oklab, var(--success) 10%, var(--surface));
+  color: var(--success);
+}
+
+.frame {
+  display: block;
+  min-width: 0;
+  flex: 1;
+}
+
+.copy {
+  position: relative;
+  display: grid;
+  min-width: 0;
+  gap: 0.125rem;
+  /* Centers the title's first line on the 30px status icon. */
+  padding-top: 0.3125rem;
+}
+
+.title {
+  position: relative;
+  display: block;
+  min-width: 0;
+  font-size: var(--text-sm);
+  font-weight: 500;
+  line-height: var(--leading-body);
+}
+
+.line {
+  display: block;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.description {
+  display: block;
+  color: var(--text-secondary);
+  font-size: var(--text-sm);
+  line-height: var(--leading-body);
+}
+
+.close {
+  display: grid;
+  width: 2rem;
+  height: 2rem;
+  flex: 0 0 auto;
+  place-items: center;
+  margin: -0.0625rem -0.125rem 0 0;
+  border: 0;
+  border-radius: var(--radius-full); corner-shape: round;
+  background: transparent;
+  color: var(--text-muted);
+  cursor: pointer;
+  transition: transform var(--duration-spring) var(--ease-spring),
+    background-color var(--duration-fast) var(--ease-standard),
+    color var(--duration-fast) var(--ease-standard);
+}
+
+@media (hover: hover) and (pointer: fine) {
+  .close:hover {
+    background: var(--surface-muted);
+    color: var(--foreground);
+  }
+}
+
+/* Quick press, spring release. */
+.close:active {
+  transform: scale(0.96);
+  transition-duration: var(--duration-instant);
+  transition-timing-function: var(--ease-standard);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .close { transition: none; }
+  .close:active { transform: none; }
+}

package/components/toast-stack/toast-stack.d.ts

@@ -0,0 +1,57 @@
+import type { ReactNode } from "react";
+export type ToastType = "success" | "info" | "warning" | "error" | "loading";
+export interface ToastAction {
+    label: string;
+    /** Runs the action. The toast closes afterwards unless the handler updates it, so an Undo can morph the toast into its result. */
+    onClick: (id: string) => void;
+}
+export interface ToastOptions {
+    /** Reuse an id to update a toast in place instead of stacking a new one. */
+    id?: string;
+    type?: ToastType;
+    title: string;
+    description?: string;
+    action?: ToastAction;
+    /** Milliseconds before the toast closes itself. Defaults by type; loading toasts wait for an update. Pass Infinity to keep it until closed. */
+    duration?: number;
+}
+export interface ToastStackApi {
+    /** Shows a toast and returns its id. */
+    toast: (options: ToastOptions) => string;
+    /** Morphs a toast in place: icon, copy, and height animate to the new content and its timer restarts. Pass `action: undefined` to remove the action. */
+    update: (id: string, patch: Partial<Omit<ToastOptions, "id">>) => void;
+    /** Dismisses one toast, or every toast when called without an id. */
+    dismiss: (id?: string) => void;
+}
+export interface ToastStackProviderProps {
+    children: ReactNode;
+    /** Base lifetime in milliseconds. Warnings and errors stay 1.6 times longer. */
+    duration?: number;
+    /** Oldest toasts beyond this count are dropped from the queue. */
+    limit?: number;
+}
+/**
+ * The viewport for a toast stack. Render it once inside a `ToastStackProvider` and call `useToastStack()` anywhere below.
+ * Use it for short, non-blocking results of what someone just did: new toasts rise from the bottom edge, older ones tuck behind,
+ * and hovering or focusing the stack fans it out into a list. Toasts pause while the stack is open or the tab is hidden, and swipe right to dismiss.
+ */
+export interface ToastStackProps {
+    /** Accessible name of the notification region. */
+    label?: string;
+    position?: "bottom-right" | "bottom-center" | "bottom-left";
+    /** Pins the stack inside the nearest positioned ancestor instead of the window, for panels and previews. */
+    contained?: boolean;
+    /** How many toasts show at once. Older ones wait behind and return as the front ones close. */
+    visibleToasts?: number;
+    /** Alt+T moves focus into the stack. */
+    hotkey?: boolean;
+    className?: string;
+}
+/** Scopes a toast queue to its subtree, so two stacks on one page never share toasts. */
+export declare function ToastStackProvider({ children, duration, limit }: ToastStackProviderProps): import("react").JSX.Element;
+/** Shows, updates, and dismisses toasts from anywhere inside the provider. `count` is how many toasts are queued. */
+export declare function useToastStack(): ToastStackApi & {
+    count: number;
+};
+export declare function ToastStack({ label, position, contained, visibleToasts, hotkey, className }: ToastStackProps): import("react").JSX.Element;
+export default ToastStack;

package/components/toast-stack/toast-stack.js

@@ -0,0 +1,399 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { createContext, useCallback, useContext, useEffect, useLayoutEffect, useRef, useState, useSyncExternalStore } from "react";
+import { AnimatePresence, animate, motion, useIsPresent, useMotionValue, usePresence, useReducedMotion, useTransform } from "motion/react";
+import { CircleCheck, CircleX, Info, TriangleAlert, X } from "lucide-react";
+import { motionTokens } from "../../lib/motion-tokens.js";
+import styles from "./toast-stack.module.css";
+/** Each tucked toast shows this many pixels above the one in front of it. */
+const PEEK = 14;
+/** Space between toasts when the stack is open. */
+const GAP = 12;
+/** Tucked toasts shrink by this much per step back. */
+const STEP = .05;
+/** The card's top and bottom borders, added to the measured content height. */
+const BORDER = 2;
+/** A swipe this far right has faded most of the way out. */
+const SWIPE_FADE = 280;
+const EMPTY = [];
+const typeLabels = { success: "Success", info: "Info", warning: "Warning", error: "Error", loading: "In progress" };
+const icons = { success: CircleCheck, info: Info, warning: TriangleAlert, error: CircleX };
+const standard = [...motionTokens.ease.standard];
+const enterEase = [...motionTokens.ease.enter];
+const fade = { duration: motionTokens.duration.fast, ease: standard };
+const enterFade = { duration: motionTokens.duration.standard, ease: enterEase };
+const reducedFade = { duration: motionTokens.duration.fast, ease: standard };
+const exitFast = { duration: motionTokens.duration.fast, ease: standard };
+const textIn = { opacity: 0, y: "0.3em", filter: `blur(${motionTokens.blur.soft}px)` };
+const textOut = { opacity: 0, y: "-0.3em", filter: `blur(${motionTokens.blur.subtle}px)`, transition: exitFast };
+const iconIn = { opacity: 0, scale: .6, filter: `blur(${motionTokens.blur.subtle}px)` };
+const shown = { opacity: 1, y: "0em", scale: 1, filter: "blur(0px)" };
+const fadeOnly = { initial: { opacity: 0 }, animate: { opacity: 1 }, exit: { opacity: 0, transition: reducedFade }, transition: reducedFade };
+const textSwap = { initial: textIn, animate: shown, exit: textOut, transition: { duration: motionTokens.duration.standard, ease: enterEase } };
+/** Scale rides the spring; opacity and blur tween so the blur never overshoots below zero. */
+const iconSwap = { initial: iconIn, animate: shown, exit: { ...iconIn, transition: exitFast }, transition: { ...motionTokens.spring.snappy, opacity: fade, filter: fade } };
+const durationFor = (type, base) => type === "loading" ? Infinity : type === "warning" || type === "error" ? base * 1.6 : base;
+/** Where a release at this velocity would come to rest, using a fast scroll deceleration. */
+const project = (velocity) => velocity / 1000 * .99 / (1 - .99);
+/** Resistance past an edge: the pull keeps moving, but less and less, the way a scroll view overscrolls. */
+const rubberBand = (distance, dimension) => (1 - 1 / (distance * .55 / dimension + 1)) * dimension;
+const subscribeVisibility = (listener) => { document.addEventListener("visibilitychange", listener); return () => document.removeEventListener("visibilitychange", listener); };
+const getServerSnapshot = () => EMPTY;
+const focusVisible = (element) => { try {
+    return element.matches(":focus-visible");
+}
+catch {
+    return true;
+} };
+/**
+ * Closed, tucked toasts take the front toast's height so their edges line up; open, each takes its own and they stack with a gap.
+ * The list is the hover target and is sized to cover the gaps, so moving between open toasts never collapses the stack.
+ */
+function layoutStack(toasts, heights, expanded, visibleToasts) {
+    const front = toasts.length ? heights[toasts[0].id] ?? 0 : 0;
+    const tops = toasts.reduce((sum, item, index) => [...sum, sum[index] + (index < visibleToasts ? (heights[item.id] ?? 0) + GAP : 0)], [0]);
+    const targets = toasts.map((item, index) => {
+        const visible = index < visibleToasts;
+        const depth = Math.min(index, visibleToasts);
+        return expanded
+            ? { y: -tops[index], scale: 1, height: heights[item.id] ?? 0, opacity: visible ? 1 : 0, content: 1 }
+            : { y: -PEEK * depth, scale: 1 - STEP * depth, height: index === 0 ? heights[item.id] ?? 0 : front, opacity: visible ? 1 : 0, content: index === 0 ? 1 : 0 };
+    });
+    const listHeight = !toasts.length ? 0 : expanded ? tops[toasts.length] - GAP : front + PEEK * (Math.min(toasts.length, visibleToasts) - 1);
+    return { targets, listHeight };
+}
+function createToastStore(base, limit) {
+    let toasts = [];
+    let seq = 0;
+    const listeners = new Set();
+    const commit = (next) => { toasts = next; listeners.forEach(listener => listener()); };
+    const update = (id, patch) => {
+        const found = toasts.find(item => item.id === id);
+        if (!found)
+            return;
+        const type = patch.type ?? found.type;
+        const record = { ...found, ...patch, type, duration: patch.duration ?? durationFor(type, base), version: found.version + 1 };
+        commit(toasts.map(item => item.id === id ? record : item));
+    };
+    const toast = ({ id, ...options }) => {
+        if (id && toasts.some(item => item.id === id)) {
+            update(id, options);
+            return id;
+        }
+        const type = options.type ?? "info";
+        seq += 1;
+        const record = { ...options, id: id ?? `toast-${seq}`, type, duration: options.duration ?? durationFor(type, base), seq, version: 0 };
+        commit([record, ...toasts].slice(0, limit));
+        return record.id;
+    };
+    const dismiss = id => {
+        if (id === undefined) {
+            if (toasts.length)
+                commit([]);
+            return;
+        }
+        if (toasts.some(item => item.id === id))
+            commit(toasts.filter(item => item.id !== id));
+    };
+    const runAction = (id) => {
+        const found = toasts.find(item => item.id === id);
+        if (!found?.action)
+            return;
+        found.action.onClick(id);
+        if (toasts.find(item => item.id === id)?.version === found.version)
+            dismiss(id);
+    };
+    return {
+        toast, update, dismiss, runAction,
+        subscribe: listener => { listeners.add(listener); return () => { listeners.delete(listener); }; },
+        getSnapshot: () => toasts,
+    };
+}
+const ToastStackContext = createContext(null);
+function useStore() {
+    const store = useContext(ToastStackContext);
+    if (!store)
+        throw new Error("Render toast stack consumers inside <ToastStackProvider>.");
+    return store;
+}
+/** Scopes a toast queue to its subtree, so two stacks on one page never share toasts. */
+export function ToastStackProvider({ children, duration = 5000, limit = 12 }) {
+    const [store] = useState(() => createToastStore(duration, limit));
+    return _jsx(ToastStackContext.Provider, { value: store, children: children });
+}
+/** Shows, updates, and dismisses toasts from anywhere inside the provider. `count` is how many toasts are queued. */
+export function useToastStack() {
+    const store = useStore();
+    const count = useSyncExternalStore(store.subscribe, () => store.getSnapshot().length, () => 0);
+    return { toast: store.toast, update: store.update, dismiss: store.dismiss, count };
+}
+/** Outgoing copies are hidden from assistive tech while they fade, so the live region reads only the current text. */
+function Swap(props) {
+    const present = useIsPresent();
+    return _jsx(motion.span, { ...props, "aria-hidden": present ? props["aria-hidden"] : true });
+}
+function ToastItem({ toast, target, expanded, front, hidden, paused, reduce, store, onMeasure, onDragChange, onTap, onHandOff }) {
+    const { id } = toast;
+    const [isPresent, safeToRemove] = usePresence();
+    const itemRef = useRef(null);
+    const cardRef = useRef(null);
+    const contentRef = useRef(null);
+    const actionRef = useRef(null);
+    const closeRef = useRef(null);
+    // Stack geometry lives in motion values, so following the stack, a finger, or a timer never re-renders React per frame.
+    const y = useMotionValue(0);
+    const scale = useMotionValue(1);
+    const height = useMotionValue(0);
+    const opacity = useMotionValue(0);
+    const contentOpacity = useMotionValue(1);
+    const x = useMotionValue(0);
+    const swipeFade = useTransform(x, value => value > 0 ? 1 - Math.min(value / SWIPE_FADE, 1) * .75 : 1);
+    /** The expanded state the last target was applied under; null until the toast has entered. */
+    const applied = useRef(null);
+    const swiped = useRef(false);
+    const remaining = useRef(toast.duration);
+    const gesture = useRef(null);
+    const suppressClick = useRef(false);
+    const pointerType = useRef("mouse");
+    // Measure before the first paint, so the toast enters from exactly its own height below the edge.
+    useLayoutEffect(() => {
+        const node = contentRef.current;
+        if (!node)
+            return;
+        onMeasure(id, node.offsetHeight + BORDER);
+        if (typeof ResizeObserver === "undefined")
+            return;
+        const observer = new ResizeObserver(() => onMeasure(id, node.offsetHeight + BORDER));
+        observer.observe(node);
+        return () => observer.disconnect();
+    }, [id, onMeasure]);
+    // Every stack change retargets the running springs from wherever they are, so rapid toasts and hover changes never queue.
+    useLayoutEffect(() => {
+        if (!isPresent || target.height <= 0)
+            return;
+        const entering = applied.current === null;
+        const morph = !entering && applied.current !== expanded;
+        applied.current = expanded;
+        if (reduce) {
+            y.jump(target.y);
+            scale.jump(target.scale);
+            height.jump(target.height);
+            animate(opacity, target.opacity, reducedFade);
+            animate(contentOpacity, target.content, reducedFade);
+            return;
+        }
+        if (entering) {
+            y.jump(target.y + target.height);
+            scale.jump(target.scale);
+            height.jump(target.height);
+            contentOpacity.jump(target.content);
+            opacity.jump(0);
+        }
+        const spring = morph ? motionTokens.spring.morph : motionTokens.spring.smooth;
+        animate(y, target.y, spring);
+        animate(scale, target.scale, spring);
+        if (!entering)
+            animate(height, target.height, spring);
+        animate(opacity, target.opacity, entering ? enterFade : fade);
+        animate(contentOpacity, target.content, fade);
+    }, [contentOpacity, expanded, height, isPresent, opacity, reduce, scale, target.content, target.height, target.opacity, target.scale, target.y, y]);
+    // An update restarts the clock; pausing keeps whatever time is left.
+    useEffect(() => { remaining.current = toast.duration; }, [toast.version, toast.duration]);
+    useEffect(() => {
+        if (!isPresent || paused || !Number.isFinite(remaining.current) || toast.duration <= 0)
+            return;
+        const started = performance.now();
+        const timer = window.setTimeout(() => store.dismiss(id), Math.max(remaining.current, 0));
+        return () => { window.clearTimeout(timer); remaining.current -= performance.now() - started; };
+    }, [id, isPresent, paused, store, toast.version, toast.duration]);
+    // Leaving: hand focus on before the toast turns inert, then fade out quickly. A closed toast sinks toward its edge; a thrown one keeps flying.
+    useEffect(() => {
+        if (isPresent)
+            return;
+        const node = itemRef.current;
+        if (node) {
+            const active = document.activeElement;
+            if (active instanceof HTMLElement && node.contains(active))
+                onHandOff(node, focusVisible(active));
+            node.setAttribute("inert", "");
+        }
+        const done = () => safeToRemove?.();
+        if (reduce) {
+            animate(opacity, 0, reducedFade).then(done);
+            return;
+        }
+        if (!swiped.current) {
+            animate(y, y.get() + 10, motionTokens.spring.smooth);
+            animate(scale, scale.get() * .96, motionTokens.spring.smooth);
+        }
+        animate(opacity, 0, { duration: swiped.current ? .22 : motionTokens.duration.exit, ease: standard }).then(done);
+    }, [isPresent, onHandOff, opacity, reduce, safeToRemove, scale, y]);
+    function onPointerDown(event) {
+        pointerType.current = event.pointerType;
+        suppressClick.current = false;
+        if (event.button !== 0 || !isPresent || event.target.closest("button, a"))
+            return;
+        // Catch a toast that is still springing back, from exactly where it is.
+        x.stop();
+        gesture.current = { pointerId: event.pointerId, startX: event.clientX, startY: event.clientY, origin: x.get(), active: false, samples: [] };
+    }
+    function onPointerMove(event) {
+        const current = gesture.current;
+        if (!current || current.pointerId !== event.pointerId)
+            return;
+        if (!current.active) {
+            const dx = event.clientX - current.startX, dy = event.clientY - current.startY;
+            if (Math.hypot(dx, dy) < 6)
+                return;
+            if (Math.abs(dy) > Math.abs(dx)) {
+                gesture.current = null;
+                return;
+            }
+            // Start following from here, so crossing the slop never makes the toast jump.
+            current.active = true;
+            current.startX = event.clientX;
+            suppressClick.current = true;
+            event.currentTarget.setPointerCapture(event.pointerId);
+            event.currentTarget.dataset.dragging = "";
+            window.getSelection()?.removeAllRanges();
+            onDragChange(true);
+        }
+        const raw = current.origin + event.clientX - current.startX;
+        // Right follows the finger 1:1; left is the wrong way, so it resists like an overscroll.
+        x.set(raw >= 0 ? raw : -rubberBand(-raw, event.currentTarget.offsetWidth));
+        current.samples.push({ t: event.timeStamp, x: raw });
+        while (current.samples.length > 2 && event.timeStamp - current.samples[0].t > 100)
+            current.samples.shift();
+    }
+    function onPointerEnd(event, cancelled) {
+        const current = gesture.current;
+        if (!current || current.pointerId !== event.pointerId)
+            return;
+        gesture.current = null;
+        if (!current.active)
+            return;
+        delete event.currentTarget.dataset.dragging;
+        onDragChange(false);
+        const first = current.samples[0], last = current.samples[current.samples.length - 1];
+        // A finger that stopped before lifting carries no throw.
+        const velocity = cancelled || !first || !last || last.t === first.t || event.timeStamp - last.t > 60 ? 0 : (last.x - first.x) / (last.t - first.t) * 1000;
+        const width = event.currentTarget.offsetWidth;
+        const offset = x.get();
+        if (!cancelled && offset > 0 && velocity > -200 && offset + project(velocity) > width * .4) {
+            swiped.current = true;
+            if (!reduce)
+                animate(x, width + 40, { type: "spring", visualDuration: .32, bounce: 0, velocity: Math.max(velocity, 0) });
+            store.dismiss(id);
+            return;
+        }
+        if (reduce)
+            x.jump(0);
+        else
+            animate(x, 0, { ...motionTokens.spring.snappy, velocity: offset < 0 ? velocity * .3 : velocity });
+    }
+    function onCardClick(event) {
+        if (suppressClick.current) {
+            suppressClick.current = false;
+            return;
+        }
+        // Touch has no hover, so a tap on the card opens or closes the stack instead.
+        if (pointerType.current !== "mouse" && !event.target.closest("button, a"))
+            onTap();
+    }
+    // An action that updates its toast usually folds itself away; keyboard focus lands on the close button instead of the page.
+    function runAction(event) {
+        const keyboard = focusVisible(event.currentTarget);
+        store.runAction(id);
+        if (keyboard && !store.getSnapshot().find(item => item.id === id)?.action)
+            closeRef.current?.focus();
+    }
+    function onKeyDown(event) {
+        if (event.key !== "Escape")
+            return;
+        event.stopPropagation();
+        store.dismiss(id);
+    }
+    const markMoving = (moving) => { if (actionRef.current)
+        actionRef.current.dataset.moving = moving ? "true" : "false"; };
+    const Icon = toast.type === "loading" ? null : icons[toast.type];
+    const swap = reduce ? fadeOnly : textSwap;
+    return _jsx(motion.li, { ref: itemRef, className: styles.item, style: { y, scale, height, opacity, zIndex: toast.seq }, "data-front": front, "data-expanded": expanded, inert: hidden, onKeyDown: onKeyDown, children: _jsx(motion.div, { ref: cardRef, className: styles.card, style: { x, opacity: swipeFade }, onPointerDown: onPointerDown, onPointerMove: onPointerMove, onPointerUp: event => onPointerEnd(event, false), onPointerCancel: event => onPointerEnd(event, true), onClick: onCardClick, children: _jsxs(motion.div, { ref: contentRef, className: styles.content, style: { opacity: contentOpacity }, children: [_jsx("span", { className: styles.icon, "data-type": toast.type, "aria-hidden": "true", children: _jsx(AnimatePresence, { mode: "popLayout", initial: false, children: _jsx(Swap, { className: styles.glyph, ...(reduce ? fadeOnly : iconSwap), children: Icon ? _jsx(Icon, { width: 18, height: 18, strokeWidth: 1.75 }) : _jsx("span", { className: styles.spinner }) }, toast.type) }) }), _jsxs("div", { className: styles.copy, children: [_jsxs("span", { className: styles.srOnly, children: [typeLabels[toast.type], ": "] }), _jsx("span", { className: styles.title, children: _jsx(AnimatePresence, { mode: "popLayout", initial: false, children: _jsx(Swap, { className: styles.line, ...swap, children: toast.title }, toast.title) }) }), _jsx(AnimatePresence, { mode: "popLayout", initial: false, children: toast.description ? _jsx(Swap, { className: styles.description, ...swap, children: toast.description }, toast.description) : null })] }), _jsx(AnimatePresence, { initial: false, children: toast.action ? _jsx(motion.div, { ref: actionRef, className: styles.actionSlot, initial: reduce ? { opacity: 0 } : { width: 0, opacity: 0 }, animate: { width: "auto", opacity: 1 }, exit: reduce ? { opacity: 0 } : { width: 0, opacity: 0 }, transition: reduce ? reducedFade : { width: motionTokens.spring.smooth, opacity: fade }, onAnimationStart: () => markMoving(true), onAnimationComplete: () => markMoving(false), children: _jsx("button", { type: "button", className: styles.action, onClick: runAction, children: toast.action.label }) }, "action") : null }), _jsx("button", { ref: closeRef, type: "button", className: styles.close, "aria-label": "Dismiss notification", onClick: () => store.dismiss(id), children: _jsx(X, { width: 16, height: 16, strokeWidth: 1.75, "aria-hidden": "true" }) })] }) }) });
+}
+export function ToastStack({ label = "Notifications", position = "bottom-right", contained = false, visibleToasts = 3, hotkey = true, className }) {
+    const store = useStore();
+    const toasts = useSyncExternalStore(store.subscribe, store.getSnapshot, getServerSnapshot);
+    const reduce = !!useReducedMotion();
+    const pageHidden = useSyncExternalStore(subscribeVisibility, () => document.visibilityState === "hidden", () => false);
+    const [hovered, setHovered] = useState(false);
+    const [focused, setFocused] = useState(false);
+    const [tapped, setTapped] = useState(false);
+    const [dragging, setDragging] = useState(false);
+    const [heights, setHeights] = useState({});
+    const regionRef = useRef(null);
+    const listRef = useRef(null);
+    const returnFocus = useRef(null);
+    if (tapped && toasts.length === 0)
+        setTapped(false);
+    const expanded = toasts.length > 0 && (hovered || focused || tapped);
+    const paused = expanded || dragging || pageHidden;
+    const measure = useCallback((id, height) => setHeights(current => current[id] === height ? current : { ...current, [id]: height }), []);
+    const prune = useCallback(() => setHeights(current => Object.fromEntries(store.getSnapshot().filter(item => item.id in current).map(item => [item.id, current[item.id]]))), [store]);
+    const toggleTap = useCallback(() => setTapped(open => !open), []);
+    /** Keyboard users land on the next toast; with none left they return to where they were before entering the stack. */
+    const handOff = useCallback((leaving, keyboard) => {
+        const items = Array.from(listRef.current?.children ?? []);
+        const at = items.indexOf(leaving);
+        const candidates = items.filter(item => item !== leaving && !item.hasAttribute("inert"));
+        const next = candidates.find(item => items.indexOf(item) > at) ?? candidates[candidates.length - 1];
+        const button = next?.querySelector("button");
+        if (keyboard && button)
+            button.focus();
+        else if (keyboard && returnFocus.current?.isConnected)
+            returnFocus.current.focus();
+        else
+            document.activeElement?.blur();
+    }, []);
+    useEffect(() => {
+        if (!hotkey)
+            return;
+        const onKey = (event) => {
+            if (!event.altKey || event.metaKey || event.ctrlKey || event.code !== "KeyT")
+                return;
+            const target = listRef.current?.querySelector(":scope > li:not([inert]) button");
+            if (!target)
+                return;
+            event.preventDefault();
+            // Browsers skip the focus ring after a modifier shortcut, so the hotkey asks for it and opens the stack itself.
+            target.focus({ focusVisible: true });
+            setFocused(true);
+        };
+        document.addEventListener("keydown", onKey);
+        return () => document.removeEventListener("keydown", onKey);
+    }, [hotkey]);
+    useEffect(() => {
+        if (!tapped)
+            return;
+        const onDown = (event) => { if (!regionRef.current?.contains(event.target))
+            setTapped(false); };
+        document.addEventListener("pointerdown", onDown);
+        return () => document.removeEventListener("pointerdown", onDown);
+    }, [tapped]);
+    const { targets, listHeight } = layoutStack(toasts, heights, expanded, visibleToasts);
+    function onFocus(event) {
+        const from = event.relatedTarget;
+        if (!(from instanceof Node) || !event.currentTarget.contains(from))
+            returnFocus.current = from instanceof HTMLElement ? from : null;
+        // Only keyboard focus opens the stack; a mouse click on a button should not pin it open.
+        if (focusVisible(event.target))
+            setFocused(true);
+    }
+    function onBlur(event) {
+        if (!(event.relatedTarget instanceof Node) || !event.currentTarget.contains(event.relatedTarget))
+            setFocused(false);
+    }
+    return _jsx("section", { ref: regionRef, className: [styles.viewport, styles[position], contained && styles.contained, className].filter(Boolean).join(" "), "aria-label": hotkey ? `${label} (Alt+T)` : label, "aria-live": "polite", "aria-relevant": "additions text", "aria-atomic": "false", onFocus: onFocus, onBlur: onBlur, children: _jsx("ol", { ref: listRef, className: styles.list, style: { height: listHeight }, "data-expanded": expanded, onPointerEnter: event => { if (event.pointerType === "mouse")
+                setHovered(true); }, onPointerMove: event => { if (event.pointerType === "mouse" && !hovered)
+                setHovered(true); }, onPointerLeave: event => { if (event.pointerType === "mouse")
+                setHovered(false); }, children: _jsx(AnimatePresence, { onExitComplete: prune, children: toasts.map((item, index) => _jsx(ToastItem, { toast: item, target: targets[index], expanded: expanded, front: index === 0, hidden: index >= visibleToasts, paused: paused, reduce: reduce, store: store, onMeasure: measure, onDragChange: setDragging, onTap: toggleTap, onHandOff: handOff }, item.id)) }) }) });
+}
+export default ToastStack;

package/components/toast-stack/toast-stack.module.css

@@ -0,0 +1,61 @@
+/* The region only holds the list; it never blocks clicks outside the toasts themselves. */
+.viewport { position: fixed; z-index: 60; bottom: var(--space-section); width: min(22.5rem, calc(100% - var(--space-block))); pointer-events: none; }
+.bottom-right { right: var(--space-section); }
+.bottom-left { left: var(--space-section); }
+.bottom-center { right: 0; left: 0; margin-inline: auto; }
+.contained { position: absolute; z-index: 2; bottom: var(--space-inset); }
+.contained.bottom-right { right: var(--space-inset); }
+.contained.bottom-left { left: var(--space-inset); }
+@media (max-width: 30rem) { .viewport:not(.contained) { right: 0; bottom: var(--space-inset); left: 0; margin-inline: auto; } }
+
+/* Toasts hang from the bottom of the list. Its height covers the gaps between open toasts, so hover survives the space between them. */
+.list { position: relative; margin: 0; padding: 0; list-style: none; pointer-events: auto; }
+/* Tucked toasts scale from their top edge, so exactly the peek shows above the toast in front. */
+.item { position: absolute; right: 0; bottom: 0; left: 0; transform-origin: 50% 0; }
+.card { position: absolute; inset: 0; overflow: hidden; border: 1px solid var(--border); border-radius: var(--radius-container); corner-shape: var(--corner-shape); background: var(--surface-raised); color: var(--foreground); box-shadow: var(--shadow-raised); container-type: inline-size; touch-action: pan-y; -webkit-tap-highlight-color: transparent; transition: background-color var(--duration-standard) var(--ease-standard), border-color var(--duration-standard) var(--ease-standard); }
+.item[data-front="true"] .card, .item[data-expanded="true"] .card { box-shadow: var(--shadow-floating); }
+/* Tucked toasts sit a step back in tone as well as scale. */
+.item[data-front="false"][data-expanded="false"] .card { background: var(--surface-muted); }
+.card[data-dragging] { cursor: grabbing; user-select: none; }
+
+.content { display: flex; align-items: flex-start; gap: var(--space-group); padding: var(--space-group) var(--space-group) var(--space-group) var(--space-inset); }
+.icon { position: relative; display: grid; width: 18px; height: 20px; flex: none; place-items: center; color: var(--text-muted); transition: color var(--duration-fast) var(--ease-standard); }
+.icon[data-type="success"] { color: var(--success); }
+.icon[data-type="info"] { color: var(--accent); }
+.icon[data-type="warning"] { color: var(--warning); }
+.icon[data-type="error"] { color: var(--danger); }
+.glyph { grid-area: 1 / 1; display: grid; place-items: center; }
+.glyph svg { display: block; }
+/* The spinner turns only while something is loading; the icon swap is its stop. */
+.spinner { display: block; width: 15px; height: 15px; border: 1.75px solid currentColor; border-right-color: transparent; border-radius: var(--radius-full); corner-shape: round; animation: spin .8s linear infinite; }
+
+.copy { position: relative; min-width: 0; flex: 1; font-size: var(--text-sm); letter-spacing: var(--tracking-body); line-height: 20px; }
+.title { position: relative; display: block; font-weight: 500; }
+.line { display: block; }
+.description { display: block; margin-top: 2px; color: var(--text-secondary); }
+
+/* Clips only while its width folds, so the focus ring stays whole at rest. */
+.actionSlot { display: flex; flex: none; justify-content: flex-end; margin-top: -4px; }
+.actionSlot[data-moving="true"] { overflow: hidden; }
+.action, .close { flex: none; border: 1px solid transparent; font: inherit; cursor: pointer; -webkit-tap-highlight-color: transparent; transition: scale var(--duration-spring) var(--ease-spring), background-color var(--duration-fast) var(--ease-standard), border-color var(--duration-fast) var(--ease-standard), color var(--duration-fast) var(--ease-standard); }
+.action { height: 28px; padding: 0 var(--space-group); border-color: var(--border); border-radius: var(--radius-full); corner-shape: round; background: var(--surface); color: var(--foreground); font-size: var(--text-sm); font-weight: 500; white-space: nowrap; }
+.close { display: grid; width: 28px; height: 28px; margin: -4px -2px 0 0; place-items: center; border-radius: var(--radius-full); corner-shape: round; background: transparent; color: var(--text-muted); }
+@media (hover: hover) and (pointer: fine) {
+  .action:hover { border-color: var(--border-strong); background: var(--surface-muted); }
+  .close:hover { background: var(--surface-muted); color: var(--foreground); }
+}
+/* Quick press, spring release. */
+.action:active, .close:active { scale: .96; transition-duration: var(--duration-instant); transition-timing-function: var(--ease-standard); }
+/* A narrow toast keeps its copy wide: the action drops under the copy instead of squeezing it. */
+@container (max-width: 21rem) {
+  .content { flex-wrap: wrap; row-gap: var(--space-related); }
+  .actionSlot { order: 1; flex-basis: 100%; justify-content: flex-start; margin-top: 0; padding-left: calc(18px + var(--space-group)); }
+}
+.srOnly { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); white-space: nowrap; }
+
+@keyframes spin { to { rotate: 360deg; } }
+@media (prefers-reduced-motion: reduce) {
+  .card, .icon, .action, .close { transition: none; }
+  .action:active, .close:active { scale: none; }
+  .spinner { animation: none; }
+}

package/components/tooltip/tooltip.d.ts

@@ -0,0 +1,8 @@
+import type { ReactElement, ReactNode } from "react";
+export interface TooltipProps {
+    content: ReactNode;
+    children: ReactElement;
+    side?: "top" | "bottom" | "left" | "right";
+}
+export declare function Tooltip({ content, children, side }: TooltipProps): import("react").JSX.Element;
+export default Tooltip;