## toast (`poetry_toast`)

A brief, auto-dismissing notification message.

Class: Poetry::Ui::Toast::Component - BEM block `poetry-ui-toast`.
Slot REQUIRED: with_title (the message) - a call without it raises.
- `variant:` (symbol) - one of default|success|info|warning|destructive|loading, default "default", required - The intent axis: it picks the icon, and :destructive announces assertively while :loading defaults to persistent.
- `duration:` (integer) - nil = derived: 5000ms, or PERSISTENT when an action slot is present (the missable-undo guard). <= 0 = persistent.
- `politeness:` (symbol) - one of polite|assertive, default "dynamic" - Derived from the variant: destructive announces assertively.
- `show_close_button:` (boolean) - default true - The corner dismiss button - named as the dialog family names it.
Slots: title (The message (REQUIRED - the announced payload's first line).), description (Supporting copy under the title.), action (Typed Button slot (undo / view / retry): clicking it dismisses the toast with reason "action". Its presence makes the toast persistent by default.; takes poetry_button props, not a block; with_action yields NOTHING to the block - no |param|, write content directly).
- PART `toast` - The notification item itself (<li>, role=status) - variant, open state, and the toaster's stack facts all ride here | states: data-open (toast is showing (the server-rendered state; the dismiss exit flips the pair before removal)); data-closed (toast is animating out); data-variant=default|success|info|warning|destructive|loading (always - the resolved variant); data-queued (the toaster holds it hidden past the visible limit (timer paused until a slot frees up)) | vars: --poetry-toast-index (stack position written by the toaster's reflow (newest visible toast = 0))
- PART `toast-icon` - The variant's icon well (aria-hidden; the default variant renders none)
- PART `toast-title` - The message - the announced payload's first line (required slot)
- PART `toast-description` - Supporting copy under the title
- WIRING root: `poetry--core--toast` registers; values duration, politeness; actions pause on mouseenter/focusin, resume on mouseleave/focusout
- WIRING action: `poetry--core--toast` actions dismiss on click; targets action
- WIRING close: `poetry--core--toast` actions dismiss on click; targets close
- RULE: Server-side toasts go through turbo_stream.poetry_toast / the flash recipe - never hand-append into #poetry-toaster.
- RULE: Undo/consequence toasts MUST carry an action slot - action-bearing toasts default to persistent (duration nil); give an explicit duration only when missing the action is safe.
- RULE: variant: :destructive is for failures the user must hear about (it announces ASSERTIVELY); do not use it for styling.
- RULE: Never put required interactions in a toast (toasts are missable) - that is AlertDialog.
- RULE: Toasts are supplementary: never the only place an outcome is recorded.