entasis 0.11.0 → 0.12.0

package/dist/components/Toast/toast.state.svelte.js

@@ -1,17 +1,45 @@
 import { ThemeState, useTheme } from '../Theme/theme.state.svelte.js';
-import { Timer } from '../../utils/timer.svelte.js';
+import { Timer, WINDOW_INACTIVE_REASON, watchWindowActivity } from '../../utils/timer.svelte.js';
+import { useLiveRegions } from '../../utils/useLiveAnnouncer.svelte.js';
 import { DEV } from 'esm-env';
-import { onMount, untrack } from 'svelte';
+import { onMount, tick, untrack } from 'svelte';
 import { createId } from '../../utils/id.js';
 import { createBindableStateClass } from '../../utils/state.svelte.js';
 import { useToastMotion } from './toast.theme.js';
+const HOVER_REASON = 'hover';
+const FOCUS_REASON = 'focus';
+const SWIPE_REASON = 'swipe';
+/** Whether `element` shows keyboard focus; engines without `:focus-visible` count every focus. */
+const isFocusVisible = (element) => {
+    if (!element)
+        return false;
+    try {
+        return element.matches(':focus-visible');
+    }
+    catch {
+        return true;
+    }
+};
+const HOLD_REASONS = [WINDOW_INACTIVE_REASON, HOVER_REASON, FOCUS_REASON, SWIPE_REASON];
 export class Toaster extends createBindableStateClass() {
     toasts = $state([]);
     element = $state();
+    /** The position whose stack the pointer is over, if any. Set with `setHovering`. */
     hovering = $state(null);
+    /**
+     * The toast holding keyboard focus (`:focus-visible`), whose stack keeps its timers paused. A
+     * touch tap or a mouse click focuses a toast without pausing anything.
+     */
+    focusedToast = $state(null);
+    /** Focus rests on the notification region itself, where F6 puts it; every stack is held. */
+    regionFocused = $state(false);
     polygon = $state([0, 0, 0, 0]);
     isOpen = $state(false);
     theme = useTheme();
+    // Persistent polite and assertive regions that announce toasts: they exist before the first
+    // toast and outlive every one, which live regions inserted with their text already filled in
+    // do not (NVDA and JAWS often skip those). Attached to the section in `Toaster.svelte`.
+    liveRegions = useLiveRegions(createId('toaster'));
     // Per-position preset from `toastTheme.motion`, through the override ladder
     // (registry → `setToastTheme` → Toaster `theme.motion` → per-toast `transition`).
     // Lives on the Toaster because `useComponentMotion` must run during init, while
@@ -41,7 +69,14 @@ export class Toaster extends createBindableStateClass() {
         onMount(() => {
             window.toaster = this;
             flushPendingToasts(this);
+            const stopWatchingWindow = watchWindowActivity((inactive) => {
+                this.windowInactive = inactive;
+                this.syncHolds();
+            });
             return () => {
+                stopWatchingWindow();
+                clearTimeout(this.announceTimer);
+                this.announceTimer = undefined;
                 // Don't leave a dangling reference if this Toaster unmounts (another
                 // mounted Toaster may have already replaced it).
                 if (window.toaster === this)
@@ -50,35 +85,103 @@ export class Toaster extends createBindableStateClass() {
         });
         // Track duration configuration changes
         $effect(() => {
-            const timersAndDurations = this.toasts.map((toast) => {
-                return {
-                    toast,
-                    position: toast.opts.position,
-                    duration: toast.opts.duration || 0,
-                    // Timeout is the only path that fires onAutoDismiss (the deferred-commit hook).
-                    callback: () => toast.remove('auto')
-                };
-            });
+            const durations = this.toasts.map((toast) => ({
+                toast,
+                duration: toast.opts.duration || 0
+            }));
             untrack(() => {
-                timersAndDurations.forEach(({ toast, position, duration, callback }) => {
-                    if (!toast.timer && duration > 0) {
-                        toast.timer = new Timer(callback, duration);
-                        if (this.hovering === position) {
-                            toast.timer.pause();
-                        }
-                    }
-                    else if (duration !== toast.timer?.delay && duration > 0 && toast.timer) {
-                        toast.timer.update(duration);
-                    }
-                    else if (toast.timer && duration <= 0) {
-                        // duration switched to false/0: the toast became persistent.
-                        toast.timer.destroy();
-                        toast.timer = undefined;
+                durations.forEach(({ toast, duration }) => {
+                    // No timer reads as a delay of 0, so a new finite duration creates one.
+                    if (duration !== (toast.timer?.delay ?? 0)) {
+                        this.syncTimer(toast);
                     }
                 });
             });
         });
     }
+    // Several things hold a toast's countdown at once, each under its own reason, and it runs only
+    // while none does: the pointer over its stack, keyboard focus in it, a press or swipe on one of
+    // its toasts, and an inactive window. Frames stop in a hidden tab while `performance.now()`
+    // keeps counting, so without the window reason every pending toast would expire on the first
+    // frame after the user comes back.
+    windowInactive = false;
+    /** The reasons that currently hold the timers of the toasts at `position`. */
+    reasonsFor = (position) => {
+        const reasons = [];
+        if (this.windowInactive)
+            reasons.push(WINDOW_INACTIVE_REASON);
+        if (this.hovering === position)
+            reasons.push(HOVER_REASON);
+        if (this.regionFocused || this.focusedToast?.opts.position === position) {
+            reasons.push(FOCUS_REASON);
+        }
+        if (this.isPressed(position))
+            reasons.push(SWIPE_REASON);
+        return reasons;
+    };
+    syncToastHolds = (toast) => {
+        const timer = toast.timer;
+        if (!timer)
+            return;
+        const wanted = this.reasonsFor(toast.opts.position);
+        for (const reason of HOLD_REASONS) {
+            if (wanted.includes(reason))
+                timer.hold(reason);
+            else
+                timer.release(reason);
+        }
+    };
+    /** Matches every timer's holds to the pointer, focus, swipe and window state. */
+    syncHolds = () => untrack(() => {
+        for (const toast of this.toasts)
+            this.syncToastHolds(toast);
+    });
+    /** Whether a press or a swipe is on a toast at `position`. */
+    isPressed = (position) => this.toasts.some((toast) => toast.pressed && toast.opts.position === position);
+    /** Whether a toast at `position` is being dragged; the stack stays expanded meanwhile. */
+    isSwiping = (position) => this.toasts.some((toast) => toast.dragging && toast.opts.position === position);
+    /** The pointer entered (`position`) or left (`null`) a stack. */
+    setHovering = (position) => {
+        if (this.hovering === position)
+            return;
+        this.hovering = position;
+        this.syncHolds();
+    };
+    /** Keyboard focus entered `toast` (`:focus-visible`), or left it (`null`, only if it holds it). */
+    setFocused = (toast, from) => {
+        if (from && this.focusedToast !== from)
+            return;
+        if (this.focusedToast === toast)
+            return;
+        this.focusedToast = toast;
+        this.syncHolds();
+    };
+    /**
+     * Matches a toast's timer to its duration. `restart` counts down the full duration again
+     * even when it did not change. A new timer starts held by whatever holds its position.
+     */
+    syncTimer = (toast, restart = false) => {
+        const duration = toast.opts.duration || 0;
+        if (duration <= 0) {
+            // duration switched to false/0: the toast became persistent.
+            toast.timer?.destroy();
+            toast.timer = undefined;
+            return;
+        }
+        if (!toast.timer) {
+            // Timeout is the only path that fires onAutoDismiss (the deferred-commit hook).
+            toast.timer = new Timer(() => toast.remove('auto'), duration, {
+                heldBy: this.reasonsFor(toast.opts.position)
+            });
+            return;
+        }
+        if (!restart && duration === toast.timer.delay)
+            return;
+        // `update` keeps the holds; an upsert can also have moved the toast to another position,
+        // whose pointer, focus and swipe state differ.
+        toast.timer.update(duration);
+        this.syncToastHolds(toast);
+    };
     maybeCloseToaster = () => {
         if (this.toasts.length === 0) {
             this.isOpen = false;
@@ -99,30 +202,248 @@ export class Toaster extends createBindableStateClass() {
         showCloseIcon: opts.showCloseIcon ?? this.showCloseIcon ?? true,
         progress: opts.progress ?? this.progress ?? false
     });
-    addToast = (opts) => this.adoptToast(new Toast({ ...opts, id: opts.id || createId('toast') }));
+    addToast = (opts) => this.adoptToast(new Toast({ ...opts, id: toastId(opts) }));
+    // Removed toasts whose exit transition may still be playing, by id. The list keys its
+    // items by id, so a toast re-added with that id resumes the leaving item instead of
+    // mounting a new one; see `adoptToast`.
+    // eslint-disable-next-line svelte/prefer-svelte-reactivity -- bookkeeping read imperatively, never rendered
+    leaving = new Map();
+    // Toasts re-added over a leaving one, by id, waiting for that removal to reach the DOM.
+    // eslint-disable-next-line svelte/prefer-svelte-reactivity -- bookkeeping read imperatively, never rendered
+    arriving = new Map();
     /**
      * Attaches a toast to this Toaster: resolves its options against the Toaster's
      * defaults and pushes it onto the stack. Used both for a freshly created toast and
      * for one parked in the pending queue while no Toaster was mounted.
+     *
+     * A toast whose id is already on screen is not added twice (the list is keyed by id):
+     * its options are merged into the live toast, its timer restarts, and the live toast is
+     * returned. A toast whose id is still animating out joins a microtask later, once that
+     * removal has reached the DOM, and takes the leaving item over.
      */
-    adoptToast = (toast) => {
+    adoptToast = (toast) => 
+    // `toast()` is often called from an effect. Reading the stack here would subscribe that
+    // effect to it, and the push below would then re-run it without end.
+    untrack(() => {
+        const live = this.toasts.find((candidate) => candidate.id === toast.id) ?? this.arriving.get(toast.id);
+        if (live) {
+            if (live !== toast) {
+                live.merge(toast.requested);
+                // Shown again while already on screen: the update alone would go unnoticed.
+                if (this.toasts.includes(live))
+                    live.attentionKey += 1;
+            }
+            this.refreshToast(live);
+            return live;
+        }
         toast.toaster = this;
         toast.theme = this.theme;
         toast.opts = this.resolveOptions(toast.requested);
+        const leaving = this.leaving.get(toast.id);
+        if (leaving && leaving !== toast && leaving.element?.isConnected) {
+            // The same id is animating out, or is about to: its removal may not have reached
+            // the DOM yet. Joined in the same tick, the toast would only swap the item's value
+            // in place, with no entry transition and no `onAfterOpen`. Joined once the removal
+            // has flushed, Svelte resumes the leaving item and plays the entry again.
+            this.arriving.set(toast.id, toast);
+            tick().then(() => {
+                // Dismissed before it joined.
+                if (this.arriving.get(toast.id) !== toast)
+                    return;
+                this.arriving.delete(toast.id);
+                this.joinStack(toast);
+            });
+            return toast;
+        }
+        this.joinStack(toast);
+        return toast;
+    });
+    /**
+     * Resolves a live toast's options against the Toaster's defaults again after they changed, and
+     * restarts its countdown. An arriving toast gets its timer when it joins the stack.
+     */
+    refreshToast = (toast) => untrack(() => {
+        if (toast.toaster !== this)
+            return;
+        toast.opts = this.resolveOptions(toast.requested);
+        if (this.toasts.includes(toast))
+            this.syncTimer(toast, true);
+    });
+    /** The toast with `id` that is on screen or about to be, never one that is leaving. */
+    find = (id) => untrack(() => this.toasts.find((toast) => toast.id === id) ?? this.arriving.get(id));
+    /** Dismisses every toast on screen or about to be; each fires `onDismiss` once. */
+    dismissAll = () => untrack(() => {
+        for (const toast of [...this.toasts, ...this.arriving.values()])
+            toast.remove();
+    });
+    joinStack = (toast) => {
+        const leaving = this.leaving.get(toast.id);
+        this.leaving.delete(toast.id);
+        // Svelte resumes a leaving item with this toast as its value. The component keeps its
+        // element, whose one-shot `bind:this` and size bindings do not follow the new value.
+        if (leaving && leaving !== toast && leaving.element?.isConnected) {
+            toast.element = leaving.element;
+            toast.height = leaving.height;
+        }
         this.toasts.push(toast);
         this.isOpen = true;
-        return toast;
     };
-    removeToast = (toast) => {
-        this.toasts = this.toasts.filter((t) => t.id !== toast.id);
+    removeToast = (toast) => untrack(() => {
+        if (this.arriving.get(toast.id) === toast) {
+            this.arriving.delete(toast.id);
+            return;
+        }
+        if (!this.toasts.includes(toast))
+            return;
+        this.moveFocusFrom(toast);
+        this.toasts = this.toasts.filter((t) => t !== toast);
+        // Drop entries whose exit already finished so the map only holds leaving toasts.
+        for (const [id, leaving] of this.leaving) {
+            if (!leaving.element?.isConnected)
+                this.leaving.delete(id);
+        }
+        this.leaving.set(toast.id, toast);
+        // A leaving toast's timers are gone, and the hold it kept on its stack goes with it.
+        if (this.focusedToast === toast)
+            this.focusedToast = null;
+        // Nothing left to hover: the pointer cannot leave a stack that is gone.
+        const position = toast.opts.position;
+        if (this.hovering === position && !this.toasts.some((t) => t.opts.position === position)) {
+            this.hovering = null;
+        }
+        this.syncHolds();
+    });
+    // The element focused before F6 sent focus to the region; focus returns there once no toast
+    // is left to hold it.
+    focusOrigin = null;
+    /**
+     * F6: moves focus into the notification region, remembering where it came from. With no toast
+     * on screen there is nothing to reach, and focus stays where it is.
+     */
+    focusRegion = () => {
+        const region = this.element;
+        if (!region || untrack(() => this.toasts.length) === 0)
+            return;
+        const active = region.ownerDocument.activeElement;
+        if (active instanceof HTMLElement && active !== region.ownerDocument.body) {
+            if (!region.contains(active))
+                this.focusOrigin = active;
+        }
+        this.focusRegionElement(true);
     };
-    toggleTimers = (position, mode) => {
-        this.toasts.forEach((toast) => {
-            if (toast.opts.position === position) {
-                toast.timer?.[mode]?.();
-            }
+    // Set while focus is being sent to the region on behalf of a keyboard user (F6, or the toast
+    // they had focused leaving): that focus holds every stack even where `:focus-visible` is unsure.
+    keyboardRegionFocus = false;
+    /**
+     * Focuses the region. Only keyboard focus holds the timers: a pointer or touch user whose toast
+     * left lands on the region too, and must not leave every later toast waiting on it.
+     */
+    focusRegionElement = (keyboard) => {
+        const region = this.element;
+        if (!region)
+            return;
+        this.keyboardRegionFocus = keyboard;
+        try {
+            region.focus({ preventScroll: true });
+            // Already focused: no focus event announces the keyboard user's intent.
+            if (keyboard && region.ownerDocument.activeElement === region)
+                this.holdRegion();
+        }
+        finally {
+            this.keyboardRegionFocus = false;
+        }
+    };
+    holdRegion = () => {
+        if (this.regionFocused)
+            return;
+        this.regionFocused = true;
+        this.syncHolds();
+    };
+    /** Focus entered the region element itself: the toasts it holds wait for the user to reach them. */
+    onRegionFocusIn = (event) => {
+        const region = this.element;
+        if (event.target !== region)
+            return;
+        if (this.keyboardRegionFocus || isFocusVisible(region))
+            this.holdRegion();
+    };
+    /**
+     * Focus left the region element, or left the region and everything in it. The element F6 came
+     * from is forgotten once focus is somewhere else on its own, so it cannot pull focus back later.
+     */
+    onRegionFocusOut = (event) => {
+        if (event.target === this.element && this.regionFocused) {
+            this.regionFocused = false;
+            this.syncHolds();
+        }
+        const next = event.relatedTarget;
+        if (!(next instanceof Node) || !this.element?.contains(next))
+            this.focusOrigin = null;
+    };
+    /**
+     * Called while `toast` still holds focus and is about to leave: it was dismissed, or it is
+     * pushed past `visibleToasts` and turns inert. Focus moves to the toast nearest to it in the
+     * stack that stays visible, else back to the element F6 left, else to the region, rather than
+     * dropping to the document body.
+     */
+    moveFocusFrom = (toast) => {
+        const element = toast.element;
+        const ownerDocument = element?.ownerDocument;
+        if (!element ||
+            !ownerDocument?.activeElement ||
+            !element.contains(ownerDocument.activeElement)) {
+            return;
+        }
+        const stack = this.toastsPerPositions[toast.opts.position] ?? [];
+        const former = stack.indexOf(toast);
+        // Read before the toast leaves: a pointer user's focus is not keyboard focus.
+        const keyboard = isFocusVisible(ownerDocument.activeElement);
+        tick().then(() => {
+            const active = ownerDocument.activeElement;
+            // Focus went somewhere else on its own in the meantime.
+            if (active && active !== ownerDocument.body && !element.contains(active))
+                return;
+            const remaining = (this.toastsPerPositions[toast.opts.position] ?? []).filter((candidate) => candidate !== toast);
+            // The newest toasts show; a candidate may only be inert until this update settles.
+            const visible = remaining.slice(Math.max(0, remaining.length - this.visibleToasts));
+            const order = (candidate) => Math.abs(stack.indexOf(candidate) - former);
+            const next = visible
+                .filter((candidate) => candidate.element?.isConnected)
+                .sort((a, b) => order(a) - order(b) || stack.indexOf(b) - stack.indexOf(a))[0];
+            const origin = this.focusOrigin?.isConnected ? this.focusOrigin : null;
+            const target = next?.element ?? origin;
+            if (target)
+                target.focus({ preventScroll: true });
+            else
+                this.focusRegionElement(keyboard);
         });
     };
+    // Toasts created in the same tick are spoken together: the live regions hold one message at a
+    // time, and each announcement replaces the one before it within the same frame.
+    pendingAnnouncements = {
+        polite: [],
+        assertive: []
+    };
+    announceTimer;
+    /** Announces a toast's text in the persistent live regions; `important` ones are assertive. */
+    announce = (message, important = false) => {
+        if (!message)
+            return;
+        this.pendingAnnouncements[important ? 'assertive' : 'polite'].push(message);
+        if (this.announceTimer !== undefined)
+            return;
+        // A macrotask, so every toast of the burst has reached its announce call by then.
+        this.announceTimer = setTimeout(() => {
+            this.announceTimer = undefined;
+            for (const politeness of ['polite', 'assertive']) {
+                const messages = this.pendingAnnouncements[politeness];
+                if (!messages.length)
+                    continue;
+                this.pendingAnnouncements[politeness] = [];
+                this.liveRegions.announce(messages.join('. '), politeness);
+            }
+        }, 0);
+    };
 }
 export class Toast {
     id;
@@ -132,11 +453,28 @@ export class Toast {
     // `<Toaster />` mounts parks the instance in `pendingToasts` first.
     toaster = $state(null);
     theme = null;
-    /** The caller's own options; a Toaster layers its defaults over them on adoption. */
+    /**
+     * The caller's own options; a Toaster layers its defaults over them on adoption. A later
+     * `toast()` call with the same id merges its options in (see `merge`).
+     */
     requested;
     element = $state();
     height = $state(0);
     loading = $state(false);
+    /**
+     * Counts the updates this toast received after it was created, by `toast()` with its id,
+     * `toast.update()` or `update()`. Rendered as `data-update-key`.
+     */
+    updateKey = $state(0);
+    /**
+     * Counts the times this toast was shown again while on screen (a `toast()` call with its id, or
+     * the same message deduplicated). Each one plays a short bounce to draw the eye back to it.
+     */
+    attentionKey = $state(0);
+    /** A pointer is down on the toast, or it is being swiped; its stack's timers are held. */
+    pressed = $state(false);
+    /** The toast is being dragged; its stack stays expanded meanwhile. */
+    dragging = $state(false);
     timer = $state(undefined);
     index = $state(0);
     opts = $state({
@@ -155,6 +493,40 @@ export class Toast {
         // flip `toast.loading` later (e.g. resolve a pending action to a result).
         this.loading = opts.loading ?? false;
     }
+    /**
+     * Merges the options of a later `toast()` call with this id over the ones this toast
+     * was created with; keys the call leaves out keep their value. The owning Toaster
+     * resolves its defaults over the result.
+     */
+    merge = (request) => {
+        this.updateKey += 1;
+        this.requested = { ...this.requested, ...request, id: this.id };
+        // Provisional, like the constructor's: `adoptToast` resolves the Toaster defaults.
+        this.opts = { ...this.requested, position: this.requested.position ?? 'bottom-right' };
+        if ('loading' in request)
+            this.loading = request.loading ?? false;
+    };
+    /**
+     * Updates the toast in place: a patch, or a function that receives the current options and
+     * returns one. Keys left out keep their value, the countdown restarts from the full duration,
+     * and `data-update-key` changes. A toast that was dismissed stays dismissed: updating it, such
+     * as when a promise settles after the user closed its toast, does nothing.
+     */
+    update = (patch) => {
+        if (this.removed)
+            return this;
+        // Like `toast()`, often called from an effect, which must not subscribe to this toast.
+        untrack(() => {
+            const next = typeof patch === 'function' ? patch(this.opts) : patch;
+            this.merge(next);
+            this.toaster?.refreshToast(this);
+        });
+        return this;
+    };
+    /** Whether the toast was dismissed, by the user, a timeout or `remove()`. */
+    get dismissed() {
+        return this.removed;
+    }
     // `$derived.by` (not `$derived`): `toaster` is assigned on adoption, so the
     // reference has to sit inside a function the initializer only stores. Only ever read
     // while the toast is rendered, i.e. once a Toaster owns it.
@@ -183,7 +555,7 @@ export class Toast {
         const position = this.opts.position;
         if (position === 'banner-top' || position === 'banner-bottom')
             return false;
-        return !this.toaster?.expand && !this.hovered;
+        return !this.toaster?.expand && !this.hovered && !this.toaster?.isSwiping(position);
     });
     absolutePosition = $derived.by(() => (this.toaster?.toastsPerPositions?.[this.position] || [])
         .toReversed()
@@ -235,18 +607,21 @@ export class Toast {
         if (this.removed)
             return;
         this.removed = true;
-        // A toast dismissed before any Toaster mounted is still parked in the pending queue.
-        // Leaving it there would have the first Toaster adopt an already-dismissed toast that
-        // nothing can dismiss again, since this method is idempotent.
-        dropPendingToast(this);
-        this.toaster?.removeToast(this);
-        this.timer?.destroy();
-        if (reason === 'auto') {
-            this.opts?.onAutoDismiss?.(this);
-        }
-        else {
-            this.opts?.onDismiss?.(this);
-        }
+        // Like `toast()`, often called from an effect, which must not subscribe to this toast.
+        untrack(() => {
+            // A toast dismissed before any Toaster mounted is still parked in the pending queue.
+            // Leaving it there would have the first Toaster adopt an already-dismissed toast that
+            // nothing can dismiss again, since this method is idempotent.
+            dropPendingToast(this);
+            this.toaster?.removeToast(this);
+            this.timer?.destroy();
+            if (reason === 'auto') {
+                this.opts?.onAutoDismiss?.(this);
+            }
+            else {
+                this.opts?.onDismiss?.(this);
+            }
+        });
     };
 }
 // `toast()` can legitimately run before any `<Toaster />` has mounted — module
@@ -284,28 +659,98 @@ const warnIfNothingMounts = () => {
         console.warn(`entasis: ${pendingToasts.length} toast(s) are queued because no <Toaster /> is mounted. Add <Toaster /> to your root layout; they will appear as soon as one mounts.`);
     }, 0);
 };
+// The id a toast gets: the one the caller supplied, else one derived from what the toast says, so
+// the same message submitted twice is one toast. A snippet title or description cannot be compared,
+// so such a toast, one with no text at all, and one with `dedupe: false` are always new.
+const toastId = (opts) => {
+    if (opts.id)
+        return opts.id;
+    const { title, description } = opts;
+    const comparable = (value) => value === undefined || typeof value === 'string';
+    const hasText = typeof title === 'string' || typeof description === 'string';
+    if (opts.dedupe === false || !hasText || !comparable(title) || !comparable(description)) {
+        return createId('toast');
+    }
+    return `dedupe:${opts.color ?? ''}:${title ?? ''}\u0000${description ?? ''}`;
+};
+const createToast = (color, payload) => {
+    const toast = new Toast({
+        color,
+        ...payload,
+        id: toastId({ ...payload, color })
+    });
+    // On the server nothing ever mounts a Toaster, so the queue would only retain
+    // toasts for the lifetime of the process. The caller still gets its handle.
+    if (typeof window === 'undefined')
+        return toast;
+    // A toast whose id is already shown is updated in place (see `adoptToast`).
+    if (window.toaster)
+        return window.toaster.adoptToast(toast);
+    // Same for one still queued: the first Toaster adopts a single toast per id.
+    const queued = pendingToasts.find((candidate) => candidate.id === toast.id);
+    if (queued) {
+        queued.merge(toast.requested);
+        return queued;
+    }
+    pendingToasts.push(toast);
+    if (pendingToasts.length > pendingToastLimit)
+        pendingToasts.shift();
+    if (DEV)
+        warnIfNothingMounts();
+    return toast;
+};
+/** The live toast with `id`: on screen, about to join the stack, or still waiting for a Toaster. */
+const findToast = (id) => {
+    if (typeof window === 'undefined')
+        return undefined;
+    return window.toaster?.find(id) ?? pendingToasts.find((candidate) => candidate.id === id);
+};
+const updateToast = (id, patch) => findToast(id)?.update(patch);
+const dismissToast = (id) => {
+    if (id !== undefined) {
+        findToast(id)?.remove();
+        return;
+    }
+    if (typeof window !== 'undefined')
+        window.toaster?.dismissAll();
+    for (const queued of [...pendingToasts])
+        queued.remove();
+};
+// A stage's patch starts from a clean slate so the pending toast's text and actions never leak into
+// its result; the stage's own options win.
+const stageUpdate = (stage) => {
+    const options = typeof stage === 'string' ? { title: stage } : stage;
+    return { title: undefined, description: undefined, actions: undefined, ...options };
+};
+const promiseToast = (promise, options) => {
+    const handle = createToast('primary', {
+        ...stageUpdate(options.loading),
+        id: options.id,
+        loading: true,
+        duration: false
+    });
+    const settle = (color, stage, value) => {
+        const resolved = typeof stage === 'function' ? stage(value) : stage;
+        // `update` leaves a toast the user dismissed in the meantime alone.
+        handle.update({ color, loading: false, duration: undefined, ...stageUpdate(resolved) });
+        // The result arrives in a toast the user may have stopped watching: bounce it once, as a
+        // toast shown again does. A dismissed toast stays gone.
+        if (!handle.dismissed)
+            handle.attentionKey += 1;
+    };
+    promise.then((result) => settle('success', options.success, result), (error) => settle('danger', options.error, error));
+    return promise;
+};
 export const toast = new Proxy({}, {
     get(_obj, key) {
+        if (key === 'update')
+            return updateToast;
+        if (key === 'dismiss')
+            return dismissToast;
+        if (key === 'promise')
+            return promiseToast;
         if (typeof key === 'string') {
-            return (payload) => {
-                const toast = new Toast({
-                    color: key,
-                    ...payload,
-                    id: payload?.id || createId('toast')
-                });
-                // On the server nothing ever mounts a Toaster, so the queue would only retain
-                // toasts for the lifetime of the process. The caller still gets its handle.
-                if (typeof window === 'undefined')
-                    return toast;
-                if (window.toaster)
-                    return window.toaster.adoptToast(toast);
-                pendingToasts.push(toast);
-                if (pendingToasts.length > pendingToastLimit)
-                    pendingToasts.shift();
-                if (DEV)
-                    warnIfNothingMounts();
-                return toast;
-            };
+            return (payload) => createToast(key, payload);
         }
     }
 });