# Toast

## Overview

_[Design to fill]_

- **When to use**: _[Design to fill]_
- **When not to use**: _[Design to fill]_

## Anatomy

_[Design to fill]_

## Variants

Toasts support different visual styles via the `type` option, each with its own icon and color:

| `type`           | Intent                                     |
| ---------------- | ------------------------------------------ |
| `information`    | Neutral, informational feedback.           |
| `success`        | Confirms an action completed successfully. |
| `critical`       | Signals an error or failure.               |
| `warning`        | Signals a caution state.                   |
| `automation-on`  | Automation (AI) enabled.                   |
| `automation-off` | Automation (AI) disabled.                  |

## Props / API

### `ToastProvider`

Wrap your application or component tree with `ToastProvider` to enable toasts. It creates the toast manager and renders the portal, viewport, and toast list.

| Prop       | Type              | Default | Description                                           |
| ---------- | ----------------- | ------- | ----------------------------------------------------- |
| `children` | `React.ReactNode` | -       | The application/component tree that can raise toasts. |

### `useToastManager`

Hook that returns methods to manage toasts. Must be called within a `ToastProvider`.

| Method   | Signature                                           | Description                                       |
| -------- | --------------------------------------------------- | ------------------------------------------------- |
| `add`    | `(options: AddToastOptions) => string`              | Adds a toast; returns its `id`.                   |
| `update` | `(id: string, options: UpdateToastOptions) => void` | Updates the `message` and/or `action` of a toast. |
| `close`  | `(id: string) => void`                              | Dismisses a toast programmatically.               |

`AddToastOptions`:

| Field      | Type              | Default | Description                                                                                                                                                     |
| ---------- | ----------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`     | `ToastType`       | -       | Visual/semantic style (see Variants).                                                                                                                           |
| `message`  | `string`          | -       | The toast text/description.                                                                                                                                     |
| `action`   | `ButtonProps`     | -       | Optional action button.                                                                                                                                         |
| `priority` | `"low" \| "high"` | `"low"` | Announcement urgency: `low` announces politely (`aria-live="polite"`), `high` announces assertively (`aria-live="assertive"`), interrupting the current output. |
| `timeout`  | `0 \| 8000`       | -       | Auto-dismiss duration in ms; `0` keeps the toast until closed manually.                                                                                         |

`UpdateToastOptions`: `Partial<Pick<AddToastOptions, "message" | "action">>` — only `message` and `action` can be updated.

## Code examples

```tsx
import {
  Button,
  ToastProvider,
  useToastManager,
} from "@mylighthouse/prism-react";

export default function ToastExample(): React.JSX.Element {
  return (
    <ToastProvider>
      <ToastTrigger />
    </ToastProvider>
  );
}

function ToastTrigger(): React.JSX.Element {
  const { add } = useToastManager();

  function showToast(): void {
    add({
      type: "success",
      message: "Changes saved",
      action: {
        children: "Undo",
        onClick() {
          console.log("Undo clicked");
        },
      },
    });
  }

  return (
    <Button buttonType="secondary" onClick={showToast}>
      Save
    </Button>
  );
}
```

## A11y intent

_[Design to fill]_

- Built on Base UI's Toast primitive, which renders toasts in an off-screen-managed live region so new toasts are announced by assistive technology.
- Each toast has a real close control with an `aria-label` of `Close` so it is operable and named for keyboard and screen reader users.
- `timeout: 0` creates a persistent toast for messages that must not disappear before the user can act on them; auto-dismissing toasts should not carry information the user needs to retain.

## Cross-references

- **[Button](./button.md)**: the action and close controls inside a toast are rendered as ghost buttons; `action` accepts `ButtonProps`.