# Toaster

Stacked toast notifications fired by a command.

Source: https://www.zazz.sh/api/primitives/toaster/

## Installation

```bash
pnpm dlx zazz-ui add toaster
```

Also adds `fields`, `kbd`, `button`, `popover`, which it depends on.

Run `zazz-ui init` first if the project has no `zazz/` folder yet.

## Examples

### Default

```html
<div
  style="
    --display: flex;
    --flex-wrap: wrap;
    --items: center;
    --gap: 4;
  "
>
  <button
    data-ui="button"
    type="button"
    commandfor="toaster-example"
    command="--toast"
    data-toaster-title="Event created"
    data-toaster-description="Monday, July 13 at 9:00 AM"
  >
    Show toast
  </button>
  <button
    data-ui="button"
    type="button"
    commandfor="toaster-example"
    command="--toast-success"
    data-toaster-title="Changes saved"
  >
    Success
  </button>
  <button
    data-ui="button"
    type="button"
    commandfor="toaster-example"
    command="--toast-info"
    data-toaster-title="Update available"
  >
    Info
  </button>
  <button
    data-ui="button"
    type="button"
    commandfor="toaster-example"
    command="--toast-warning"
    data-toaster-title="Storage almost full"
  >
    Warning
  </button>
  <button
    data-ui="button"
    type="button"
    commandfor="toaster-example"
    command="--toast-destructive"
    data-toaster-title="Something went wrong"
    data-toaster-description="The request could not be completed."
  >
    Error
  </button>
  <button data-ui="button" data-button-variant="primary" type="button" id="toaster-action-example">
    With action
  </button>
</div>

<ui-toaster id="toaster-example" popover="manual"></ui-toaster>

<script type="module">
  // An action callback can't live in a data attribute, so it needs the imperative API.
  await customElements.whenDefined("ui-toaster");

  const toastTrigger = document.getElementById("toaster-action-example");
  const handler = () => {
    window.Toaster.toast({
      title: "Email archived",
      description: "The conversation was moved to the archive.",
      action: { label: "Undo", onClick: () => window.Toaster.success("Email restored") },
    });
  };

  toastTrigger.addEventListener("click", handler);

  window.addEventListener("unload", () => {
    toastTrigger.removeEventListener("click", handler);
  });
</script>
```

## Behavior

`primitives/toaster/toaster.js`

`<ui-toaster>`: HTML web component for stacked toast notifications.
Light-DOM custom element that hosts a top-layer toast stack, plus
the `window.Toaster` imperative API. Timers pause on hover, during a swipe,
and in hidden tabs.

The region is a `popover="manual"` element: it enters the top layer via
`showPopover()` when the first toast arrives and leaves it after the last
toast's exit transition. Toasts are plain `<li>` children, so the collapsed
stack offsets in `toaster.css` work with normal CSS transforms.

Fire toasts two ways:
- Declaratively, from any button, via a custom Invoker Command:
  `command="--toast"` (or `--toast-success|info|warning|destructive`) with
  `commandfor="<region id>"`. Toast content comes from the button's
  `data-toaster-title`, `data-toaster-description`, `data-toaster-variant`,
  `data-toaster-duration`, and `data-toaster-close-button` attributes.
- Imperatively: `window.Toaster.toast({ title, description, variant, … })`
  and the `.success()/.info()/.warning()/.error()` shorthands.

Swipe a toast to dismiss it, with a finger or the mouse: toward the edge it
entered from (down for the bottom positions, up for the top ones), or
sideways toward the nearest inline edge (either way when centered). A swipe
past 45px dismisses, and so does a quick flick; anything less springs back,
and the other directions resist. In the collapsed stack only the front toast
swipes.

Region attributes:
- `data-toaster-position`: `top-start | top-center | top-end | bottom-start |
  bottom-center | bottom-end` (logical; default `bottom-end`).

## Attributes

| Attribute | Kind | Values |
| --- | --- | --- |
| `data-ui="toaster"` | identity | free value |
| `<ui-toaster>` | tag | free value |
| `data-toaster-variant` | preset | `destructive` `info` `success` `warning` |
| `data-toaster-slot` | slot | `action` `close` `content` `description` `icon` `list` `title` `toast` |
| `data-toaster-state` | state | `expanded` `front` `removed` `swiped` `swiping` `visible` |
| `data-toaster-close-button` | config | free value |
| `data-toaster-description` | config | free value |
| `data-toaster-duration` | config | free value |
| `data-toaster-id` | config | free value |
| `data-toaster-position` | config | free value |
| `data-toaster-title` | config | free value |

Requires: popover, button.

## Hooks

| Hook | Default | State |
| --- | --- | --- |
| `--ui-toaster-accent` | `var(--color-popover-foreground)` | — |
| `--ui-toaster-bg` | `var(--color-popover)` | — |
| `--ui-toaster-border-color` | `var(--color-border)` | — |
| `--ui-toaster-corner-shape` | `var(--radius-corner-shape)` | — |
| `--ui-toaster-description-font-size` | `var(--font-size-sm)` | — |
| `--ui-toaster-description-text` | `var(--color-muted-foreground)` | — |
| `--ui-toaster-gap` | `calc(var(--spacing) * 3.5)` | — |
| `--ui-toaster-icon-size` | `calc(var(--spacing) * 5)` | — |
| `--ui-toaster-inset` | `var(--gutters)` | — |
| `--ui-toaster-opacity--end` | `1` | end |
| `--ui-toaster-opacity--start` | `0` | start |
| `--ui-toaster-p` | `calc(var(--spacing) * 4)` | — |
| `--ui-toaster-radius` | `var(--radius-md)` | — |
| `--ui-toaster-scale-step` | `0.05` | — |
| `--ui-toaster-shadow` | `var(--shadow-md)` | — |
| `--ui-toaster-text` | `var(--color-popover-foreground)` | — |
| `--ui-toaster-title-font-size` | `var(--font-size-sm)` | — |
| `--ui-toaster-title-font-weight` | `var(--font-weight-strong)` | — |
| `--ui-toaster-transition-duration` | `calc(var(--default-transition-duration) * 1.5)` | — |
| `--ui-toaster-transition-timing-function` | `var(--default-transition-timing-function)` | — |
| `--ui-toaster-w` | `min(356px, calc(100vi - var(--gutters) * 2))` | — |
