# Toaster

> Headless queue of toast notifications a Toast.Region island subscribes to, re-rendering on change.

```ts
import { Toaster } from "@sdxc/ui/behaviors";
```

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

```ts
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

```tsx
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.

### Toaster.Toast

One queued toast.

#### Members

| 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. |

### Toaster.AddOptions

Options accepted by Toaster.add.

#### Members

| 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. |

### Toaster.UpdateOptions

Options accepted by Toaster.update.

#### Members

| 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. |

### Toaster.Init

Construction options accepted by Toaster.

#### Members

| Member | Type | Description |
| --- | --- | --- |
| `defaultDuration?` | `number` | Auto-dismiss delay, in milliseconds, used when Toaster.AddOptions.duration is omitted. Defaults to 5000. |

### Toaster.Events

Events dispatched by Toaster.

#### Members

| 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. |