[ @sdxc/ui/behaviors ]
Toaster
Headless queue of toast notifications a Toast.Region island subscribes to, re-rendering on change.
import { Toaster } from "@sdxc/ui/behaviors";Usage
Owns a queue of toast notifications and each one's auto-dismiss timer. An
island subscribes to "change" and calls Toaster.pause and
Toaster.resume so a toast under the cursor stays readable.
Signature
new Toaster<Data = unknown>(init?: Toaster.Init)Parameters
| Parameter | Type | Description |
|---|---|---|
init? | Toaster.Init | Construction options; see Toaster.Init. |
Properties
| Property | Type | Description |
|---|---|---|
toasts | readonly Toaster.Toast<Data>[] | Every queued toast, in the order it was added. |
size | number | Number of toasts currently queued. |
Methods
| Method | Description |
|---|---|
get(id: string): Toaster.Toast<Data> | undefined | Looks up one queued toast by id. |
add(data: Data, options?: Toaster.AddOptions): string | Queues a toast and starts its auto-dismiss timer. Reusing an id already queued replaces that toast in place, clearing its previous timer. Dispatches "toast" and then "change". |
update(id: string, data: Data, options?: Toaster.UpdateOptions): boolean | Patches a queued toast's data in place. Passing duration also restarts its timer from full, preserving whether the toast is currently paused. |
dismiss(id: string): boolean | Removes one queued toast by id and clears its timer. |
dismissAll(): void | Empties the queue and clears every timer, dispatching "change" when it held at least one toast. |
pause(id?: string): void | Pauses the auto-dismiss timer for one toast, or every toast when id is omitted, recording how much time was left on each. Dispatches "change" only when at least one running timer paused. |
resume(id?: string): void | Resumes the auto-dismiss timer for one toast, or every toast when id is omitted, continuing from the time left when it paused. Dispatches "change" only when at least one paused timer resumed. |
dispose(): void | Empties the queue and clears every pending timer silently, for an island to call as it unmounts so each countdown ends with it. |
Examples
toaster.addEventListener("change", () => handle.update(), { signal: handle.signal });Used with it
The events, constants and types its module publishes, each imported from @sdxc/ui/behaviors too.
Interface
Toaster.Toast
One queued toast.
| Member | Type | Description |
|---|---|---|
id | readonly string | Stable id used to target this toast with Toaster.dismiss, Toaster.update, Toaster.pause, and Toaster.resume. |
data | readonly Data | Consumer-supplied payload the island renders — copy, variant, action, and any other data the toast needs. |
duration | readonly number | null | Milliseconds until this toast auto-dismisses, or null when it only leaves the queue through Toaster.dismiss. |
createdAt | readonly number | Date.now() timestamp this toast was queued at. |
paused | readonly boolean | true while this toast's auto-dismiss timer is paused. |
Interface
Toaster.AddOptions
Options accepted by Toaster.add.
| Member | Type | Description |
|---|---|---|
id? | string | Id to queue the toast under. Defaults to a generated id; reusing an id already queued replaces that toast. |
duration? | number | null | Milliseconds until auto-dismiss, or null for a toast that only leaves the queue through Toaster.dismiss. Defaults to the constructor's Toaster.Init.defaultDuration. |
Interface
Toaster.UpdateOptions
Options accepted by Toaster.update.
| Member | Type | Description |
|---|---|---|
duration? | number | null | Replacement duration. When provided, restarts the toast's auto-dismiss timer from full, preserving whether the toast is currently paused. |
Interface
Toaster.Init
Construction options accepted by Toaster.
| Member | Type | Description |
|---|---|---|
defaultDuration? | number | Auto-dismiss delay, in milliseconds, used when Toaster.AddOptions.duration is omitted. Defaults to 5000. |
Interface
Toaster.Events
Events dispatched by Toaster.
| Member | Type | Description |
|---|---|---|
change | Event | Dispatched after a toast is added, updated, dismissed (by timeout or by id), paused, resumed, or the queue is cleared. |
toast | Event | Dispatched after a new toast is added, ahead of "change", so a listener can react to the arrival alone. |