# Toast

A transient notification region driven imperatively by a `Toaster`.

## Usage

Use standalone, driven by a `Toaster` from `createToaster()`.
```svelte
<Toast {toaster} {...props}>
  {#snippet children(item)}{item.message}{/snippet}
</Toast>
```

## Anatomy

The `class` attribute values represent part names, and `conditional` indicates elements that are rendered conditionally. Other attributes represent their corresponding props.

```svelte
<div class="whole" popover="manual">
  {#each toaster.toasts as item (item.id)}
    <div class="middle" animate:flip={{ duration: motion }}>
      <div class="main" role aria-label>
        {children(item, variant)}
      </div>
    </div>
  {/each}
</div>
```

## Props

| Name | Type | Default | Description |
|---|---|---|---|
| `toaster*` | `Toaster` | - | A `Toaster` from `createToaster()` used to drive the component imperatively |
| `children*` | `Snippet` | - | Renders each `ToastItem` |
| `motion` | `number` | `200` | Flip animation duration |
| `styling` | `SVSClass` | - | Styling override |
| `variant` | `SVSVariant` | `NEUTRAL` | Variant |
`*` required.

`assertive: true` on `createToaster()` or `Toaster.add()` switches toast items from polite to assertive announcement.

## Styling

To learn more, see [Styling](/docs/styling).

### Variant Management

While a toast is visible, the component `variant` is applied; while it animates out, `inactive` is applied.

### Default Class Name

`svs-toast`

## Accessibility

### Keyboard Interactions

| Key | Description |
| --- | --- |
| `F6` | When the toast region is open and the key event is not composed, moves focus to the toast region |
### ARIA Roles and Attributes

The component applies these automatically:

- Toast region (`whole`): `role="region"`, `tabindex="-1"`, and `aria-label` with the current notification count.
- Toast item (`main`): `role="status"` by default for polite announcement, or `role="alert"` when `assertive` is true, plus `tabindex="0"` and `aria-label` derived from the toast type (`"<type> message"`) or `"message"`.

No separate label prop is required for the generated region or toast item names. Provide meaningful rendered toast content through `children`, because the generated item label describes the message category, not the full message body.

## Exports

### Types

```ts
interface ToasterOptions {
  duration?: number;
  assertive?: boolean;
}
interface ToastAddOptions {
  type?: string;
  duration?: number;
  assertive?: boolean;
}
interface ToastItem {
  readonly id: string;
  readonly message: string;
  readonly type: string;
  readonly assertive: boolean;
  readonly visible: boolean;
}
interface ToastProps {
  toaster: Toaster;
  children: Snippet<[ToastItem, string]>; // Snippet<[item,variant]>
  motion?: number; // (200) flip animation duration
  styling?: SVSClass;
  variant?: SVSVariant; // (VARIANT.NEUTRAL)
}
type ToastReqdProps = "toaster" | "children";
type ToastBindProps = never;
```

### Others

```ts
// Creates an isolated toast store to pass to <Toast> and drive imperatively.
function createToaster(options?: ToasterOptions): Toaster;

class Toaster {
  readonly toasts: ToastItem[]; // reactive list of current toasts
  add(message: string, options?: ToastAddOptions): string; // enqueue a toast; options include type/duration/assertive; returns its id
  dismiss(id: string): void; // start the hide animation (auto-removes afterward)
  remove(id: string): void; // remove immediately without animation
  clear(): void; // dismiss all toasts
  pause(id: string): void; // pause the auto-dismiss timer (e.g. on hover)
  resume(id: string, extend?: boolean): void; // restart the auto-dismiss timer; extend lengthens the duration
}
```

## Examples

The example code uses Tailwind CSS along with `SVSClass`.

### Basic

**Code**

```svelte src=ToastBasic.svelte
<script lang="ts">
  import { Toast, createToaster } from "svseeds";

  import type { ToastItem } from "svseeds";

  const toaster = createToaster({ duration: 5000 });
  const styling = {
    whole: "inset-auto right-4 bottom-4 z-50 flex flex-col items-end gap-2 p-0 outline-hidden",
    middle: "transition-opacity",
    main: {
      base: "rounded-md bg-white px-4 py-3 text-sm text-gray-900 shadow-lg ring-1 ring-gray-200",
      inactive: "opacity-0",
    },
  };
  const myProps = {
    toaster,
    styling,
  };
</script>

<button type="button" class="rounded-md bg-teal-500 px-4 py-2 text-white cursor-pointer" onclick={() => toaster.add("Hello!!")}>
  Show toast
</button>

<Toast {...myProps}>
  {#snippet children(item: ToastItem)}
    {item.message}
  {/snippet}
</Toast>
```
### Toast Types

**Code**

```svelte src=ToastVariant.svelte
<script lang="ts">
  import { Toast, createToaster } from "svseeds";

  import type { ToastItem } from "svseeds";

  type ToastType = "success" | "error" | "info";

  const toaster = createToaster({ duration: 6000 });
  const actions: { type: ToastType; label: string; message: string }[] = [
    { type: "success", label: "Success", message: "Profile updated" },
    { type: "error", label: "Error", message: "Upload failed" },
    { type: "info", label: "Info", message: "Sync is still running" },
  ];
  const styling = {
    whole: "inset-auto right-4 bottom-4 z-50 flex flex-col items-end gap-2 p-0 outline-hidden",
    middle: "transition-opacity",
    main: {
      base: "rounded-md bg-white p-0 text-sm text-gray-900 shadow-lg ring-1 ring-gray-200",
      inactive: "opacity-0",
    },
  };
  const myProps = {
    toaster,
    styling,
  };

  function typeClass(type: string): string {
    if (type === "success") return "border-teal-500 bg-teal-50 text-teal-900";
    if (type === "error") return "border-red-500 bg-red-50 text-red-900";
    return "border-blue-500 bg-blue-50 text-blue-900";
  }
</script>

<div class="flex flex-wrap justify-center gap-2">
  {#each actions as action}
    <button
      type="button"
      class="rounded-md border px-3 py-1.5 text-sm cursor-pointer"
      onclick={() => toaster.add(action.message, { type: action.type })}
    >
      {action.label}
    </button>
  {/each}
</div>

<Toast {...myProps}>
  {#snippet children(item: ToastItem)}
    <div class={`border-s-4 px-4 py-3 ${typeClass(item.type)}`}>
      <div class="font-medium capitalize">{item.type || "message"}</div>
      <div>{item.message}</div>
    </div>
  {/snippet}
</Toast>
```