# Toast

> Imperative notification API (`toast.success`, `toast.error`). Differentiates `role="alert"` from `role="status"`.

- Package: `@sisyphos-ui/toast`
- Docs: https://sisyphosui.com/docs/components/toast
- npm: https://www.npmjs.com/package/@sisyphos-ui/toast

## Installation

```bash
pnpm add @sisyphos-ui/toast @sisyphos-ui/core
```

Or use the umbrella package:

```bash
pnpm add @sisyphos-ui/ui
```

## Import

```tsx
import "@sisyphos-ui/toast/styles.css";
import { Toast } from "@sisyphos-ui/toast";
```

## Examples

### Imperative API

`toast.success`, `.error`, `.warning`, `.info`. Mount `<Toaster />` once per app; fire toasts from anywhere.

```tsx
import { Button, Toaster, toast } from "@sisyphos-ui/ui";

export function Example() {
  return (
    <>
      {/* Mount the <Toaster /> once — in your root layout or App shell. */}
      <Toaster position="bottom-right" />

      <div className="flex flex-wrap items-center gap-3">
        <Button onClick={() => toast.success("Saved successfully")}>Success</Button>
        <Button color="error"   onClick={() => toast.error("Something went wrong")}>Error</Button>
        <Button color="warning" onClick={() => toast.warning("Heads up — session expiring")}>Warning</Button>
        <Button color="info" variant="outlined" onClick={() => toast.info("New update available")}>Info</Button>
      </div>
    </>
  );
}
```

### Title + description

Second argument accepts `{ description, duration, dismissible, … }`.

```tsx
import { Button, Toaster, toast } from "@sisyphos-ui/ui";

export function Example() {
  return (
    <>
      <Toaster position="bottom-right" />
      <Button
        onClick={() =>
          toast.success("Deployment finished", {
            description: "Build #4291 shipped to production in 1m 42s.",
          })
        }
      >
        Rich success toast
      </Button>
    </>
  );
}
```

### With undo action

Pass any ReactNode as `action`. Use `toast.dismiss(id)` to close from inside the action.

```tsx
import { Button, Toaster, toast } from "@sisyphos-ui/ui";

export function Example() {
  return (
    <>
      <Toaster position="bottom-right" />
      <Button
        onClick={() => {
          let id = "";
          id = toast.success("Invitation sent", {
            description: "Ada will receive an email shortly.",
            duration: 8000,
            action: (
              <Button size="sm" variant="text" onClick={() => {
                toast.dismiss(id);
                toast.info("Invitation revoked");
              }}>
                Undo
              </Button>
            ),
          });
        }}
      >
        Send invite
      </Button>
    </>
  );
}
```

### All positions

Pick any of the six anchor points. The `<Toaster />` itself drives layout.

```tsx
import { useState } from "react";
import { Button, Toaster, toast, type ToasterPosition } from "@sisyphos-ui/ui";

const ALL: ToasterPosition[] = [
  "top-left", "top-center", "top-right",
  "bottom-left", "bottom-center", "bottom-right",
];

export function Example() {
  const [position, setPosition] = useState<ToasterPosition>("bottom-right");

  return (
    <>
      <Toaster position={position} />
      {ALL.map((p) => (
        <Button key={p} size="sm" onClick={() => setPosition(p)}>{p}</Button>
      ))}
      <Button onClick={() => toast.info(`Hello from ${position}`)}>Fire toast</Button>
    </>
  );
}
```