entasis 0.10.2 → 0.12.0

package/dist/components/Toast/toast.mcp.d.ts

@@ -1 +1 @@
-export declare const toastDescription = "\nThe toast function displays non-blocking notification messages to the user. It provides color-based methods (primary, secondary, success, warning, danger, info, neutral) that each return a Toast instance.\n\n\n**Usage:**\n```typescript\nimport { toast } from 'entasis/toast';\n\n// Basic toast with a color variant\ntoast.success({\n  title: 'Success!',\n  description: 'Your changes have been saved.',\n  duration: 4000\n});\n\n// Toast with custom position\ntoast.danger({\n  title: 'Error',\n  description: 'Something went wrong.',\n  position: 'top-center',\n  duration: 5000\n});\n\n// Toast with loading state\ntoast.info({\n  title: 'Processing',\n  description: 'Please wait...',\n  loading: true,\n  duration: false // Don't auto-close\n});\n\n// Toast with callbacks\ntoast.warning({\n  title: 'Warning',\n  description: 'This action cannot be undone.',\n  duration: 6000,\n  onAfterOpen: (payload) => console.log('Toast opened:', payload.id),\n  onDismiss: (payload) => console.log('Toast dismissed:', payload.id),\n  onAutoDismiss: (payload) => console.log('Toast timed out:', payload.id)\n});\n```\n\n**Available Color Methods:**\n- `toast.primary(options)` - Primary color variant\n- `toast.secondary(options)` - Secondary color variant\n- `toast.success(options)` - Success/green variant\n- `toast.warning(options)` - Warning/yellow variant\n- `toast.danger(options)` - Danger/red variant\n- `toast.info(options)` - Info/blue variant\n- `toast.neutral(options)` - Neutral color variant\n\n**Parameters (all optional):**\n- `title` (Slot or string): The toast title text\n- `description` (Slot or string) optional: The toast description/message text\n- `position` (ToastPosition, optional): Position on screen. Options: `'top-left'`, `'top-right'`, `'top-center'`, `'bottom-left'`, `'bottom-right'`, `'bottom-center'`, plus `'banner-top'` / `'banner-bottom'` which render a full screen-width bar flush to the top/bottom edge. Default: `'bottom-right'`. Swipe axis follows the anchor: left/right corners swipe horizontally, center + banner positions swipe vertically.\n- `duration` (number | false, optional): Time in milliseconds before auto-closing. Set to `false` to disable auto-close. Default: 4000ms\n- `closeOnClick` (boolean, optional): If true, clicking the toast closes it. Default: inherited from Toaster\n- `showCloseIcon` (boolean, optional): If true, shows a close button. Default: inherited from Toaster\n- `dismissible` (boolean, optional): If false, prevents user from dismissing. Default: inherited from Toaster\n- `richColors` (boolean, optional): If true, uses richer color variants. Default: inherited from Toaster\n- `loading` (boolean, optional): If true, shows a loading spinner using Theme's global `spinnerVariant`\n- `progress` (boolean, optional): If true, shows a bar counting down the remaining duration (pauses on hover). Only appears when the toast has a finite `duration`. Can also be set on `<Toaster progress />` as a default.\n- `swipeToDismiss` (boolean, optional, default true): Drag the toast toward its anchored screen edge (down for bottom-*, up for top-*) past a threshold to dismiss it; dragging the other way rubber-bands. A manual dismiss fires `onDismiss`, not `onAutoDismiss`.\n- `closeOnClick` (boolean, optional, default false): Dismiss when the toast body is clicked. Off by default now that swipe-to-dismiss exists; the close icon and swipe are the primary dismiss affordances.\n- `size` (Sizes, optional): Size of the toast \u2014 scales padding, corner radius, type and icon. Options: `'small'`, `'normal'`, `'large'` (default `'normal'`). Can be defaulted for all toasts with `<Toaster size=\"...\" />`.\n- `prefix` (Slot | false, optional): Content before the text. `false` hides the default icon\n- `suffix` (Slot, optional): Content to display after the toast text\n- `actions` (ToastAction[], optional): Buttons rendered inside the toast. `ToastAction` is full Button props plus `content` (the label) and `dismiss` (default true \u2014 clicking dismisses the toast). Each button's `onclick` runs with the native MouseEvent, then the toast fires `onDismiss`.\n- `closeIcon` (Slot, optional): Custom close button component\n- `icon` (string, optional): Icon name to display before the toast text\n- `important` (boolean, optional): Uses `role=\"alert\"` + assertive announcements for screen readers\n- `transition` (FSOProps, optional): Enter/exit transition override for this toast\n- `theme` (ToastThemeProps, optional): Theme overrides for this toast alone, layered over the `<Toaster theme>` object (`base` classes are appended, so the per-toast ones win)\n- `id` (string, optional): Custom ID for the toast. Auto-generated if not provided\n- `onAfterOpen` (function, optional): Called once the toast finishes entering: `(payload: Toast) => void`\n- `onDismiss` (function, optional): Called on manual dismiss (close button, an action, or `toast.remove()`). Not called on timeout: `(payload: Toast) => void`\n- `onAutoDismiss` (function, optional): Called only when the toast times out after `duration`. Put deferred irreversible work here; it never runs if the toast is dismissed first: `(payload: Toast) => void`\n\n### Undo / deferred-commit pattern\n\nRemove the item from the UI immediately, defer the real irreversible action to `onAutoDismiss`, and offer an `Undo` action. Undo dismisses the toast manually, so `onAutoDismiss` never fires:\n\n```ts\nfunction deleteItemWithUndo(item) {\n  removeFromUI(item);                       // optimistic\n  toast.neutral({\n    title: `Deleted \"${item.name}\"`,\n    duration: 5000,\n    actions: [{ content: 'Undo', onclick: () => restore(item) }],\n    onAutoDismiss: () => commitDelete(item)   // runs only if not undone\n  });\n}\n```\n\n**Mounting order:** `toast()` never throws when no `<Toaster />` is mounted yet \u2014 the toast is queued and shown by the first Toaster that mounts. In development, a single `console.warn` reports a queue that is still waiting a tick later. Dismissing a queued toast drops it from the queue, and a `toast()` call made during SSR is discarded instead of queued.\n\n**Returns:**\nA `Toast` instance that you can use to programmatically control the root:\n- `toast.remove()` - Remove the toast manually\n- `toast.id` - Unique identifier\n- `toast.opts` - Toast options\n\n**Notes:**\n- Toasts are non-blocking and don't prevent user interaction\n- The toaster is a `role=\"region\"` landmark named \"Notifications\" (not a `<dialog>`); pressing F6 anywhere moves focus into it. Each toast is `role=\"status\"`, or `role=\"alert\"` when `important`\n- Toasts stacked away behind the front one are `inert` (rather than `aria-hidden`), so they take no clicks or tab stops until they surface\n- Multiple toasts can be displayed simultaneously and will stack based on position\n- Toasts pause their auto-close timer when hovered\n- Toasts can be dismissed by clicking the close icon, clicking the toast (if `closeOnClick` is true), or automatically after the duration expires\n\n## Theme Customization\n\nThe Toast component uses a theme object that can be customized using the `theme` prop in toast options or by setting a global theme.\n\n### Theme Structure\n\nThe theme object contains the following parts:\n- **motion**: Enter/exit transition preset, keyed by `position` (each toast flies in from the\n  edge it is pinned to). Takes `in` / `out` FSO params plus a `duration` / `easing` motion\n  token; overrides ladder `<Theme components={{ toast }}>` \u2192 `setToastTheme` \u2192 `theme.motion`\n  \u2192 the Toaster's `transition` prop \u2192 a toast's own `transition`\n- **root**: Main toast container styles\n- **prefix**: Prefix icon/content styles\n- **suffix**: Suffix content styles\n- **content**: Content wrapper styles\n- **closeIcon**: Close button icon styles\n- **title**: Title text styles\n- **description**: Description text styles\n\n### Available Variants\n\n**root**:\n- base: Base classes for toast container\n- Variants:\n  - richColors: boolean - Rich color variant styling\n  - color: Color variants\n  - size: 'small' | 'normal' | 'large' - Toast size\n\n**prefix**:\n- base: Base classes for prefix content\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Icon size\n  - color: Color variants\n  - richColors: boolean - Rich color variant styling\n\n**suffix**:\n- base: Base classes for suffix content\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Content size\n  - color: Color variants\n  - richColors: boolean - Rich color variant styling\n\n**content**:\n- base: Base classes for content wrapper\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Content size\n  - color: Color variants\n  - richColors: boolean - Rich color variant styling\n\n**closeIcon**:\n- base: Base classes for close button\n- Variants:\n  - richColors: boolean - Rich color variant styling\n  - color: Color variants\n\n**title**:\n- base: Base classes for title text\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Text size\n  - color: Color variants\n  - richColors: boolean - Rich color variant styling\n\n**description**:\n- base: Base classes for description text\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Text size\n  - color: Color variants\n  - richColors: boolean - Rich color variant styling\n\n### Usage Examples\n\n**Basic Theme Override**:\n```typescript\nimport { toast } from 'entasis/toast';\n\ntoast.success({\n  title: 'Success',\n  description: 'Operation completed',\n  theme: {\n    root: {\n      base: 'rounded-xl raised-5',\n      size: {\n        normal: 'px-4 py-3'\n      }\n    }\n  }\n});\n```\n\n**Custom Toast Styling**:\n```typescript\ntoast.danger({\n  title: 'Error',\n  description: 'Something went wrong',\n  theme: {\n    root: {\n      base: 'border-2 border-red-500',\n      richColors: {\n        true: 'bg-red-50 border-red-500'\n      }\n    },\n    title: {\n      base: 'font-bold text-red-900'\n    }\n  }\n});\n```\n\n**Global Theme Setting**:\n```svelte\n<script>\n  import { setToastTheme } from './index.ts';\n  \n  setToastTheme({\n    root: {\n      base: 'rounded-lg raised-4',\n      size: {\n        normal: 'px-3 py-2'\n      }\n    },\n    title: {\n      base: 'font-semibold'\n    }\n  });\n</script>\n```\n";
+export declare const toastDescription = "\nThe toast function displays non-blocking notification messages to the user. It provides color-based methods (primary, secondary, success, warning, danger, info, neutral) that each return a Toast instance.\n\n\n**Usage:**\n```typescript\nimport { toast } from 'entasis/toast';\n\n// Basic toast with a color variant\ntoast.success({\n  title: 'Success!',\n  description: 'Your changes have been saved.',\n  duration: 4000\n});\n\n// Toast with custom position\ntoast.danger({\n  title: 'Error',\n  description: 'Something went wrong.',\n  position: 'top-center',\n  duration: 5000\n});\n\n// Toast with loading state\ntoast.info({\n  title: 'Processing',\n  description: 'Please wait...',\n  loading: true,\n  duration: false // Don't auto-close\n});\n\n// Toast with callbacks\ntoast.warning({\n  title: 'Warning',\n  description: 'This action cannot be undone.',\n  duration: 6000,\n  onAfterOpen: (payload) => console.log('Toast opened:', payload.id),\n  onDismiss: (payload) => console.log('Toast dismissed:', payload.id),\n  onAutoDismiss: (payload) => console.log('Toast timed out:', payload.id)\n});\n```\n\n**Available Color Methods:**\n- `toast.primary(options)` - Primary color variant\n- `toast.secondary(options)` - Secondary color variant\n- `toast.success(options)` - Success/green variant\n- `toast.warning(options)` - Warning/yellow variant\n- `toast.danger(options)` - Danger/red variant\n- `toast.info(options)` - Info/blue variant\n- `toast.neutral(options)` - Neutral color variant\n\n**Parameters (all optional):**\n- `title` (Slot or string): The toast title text\n- `description` (Slot or string) optional: The toast description/message text\n- `position` (ToastPosition, optional): Position on screen. Options: `'top-left'`, `'top-right'`, `'top-center'`, `'bottom-left'`, `'bottom-right'`, `'bottom-center'`, plus `'banner-top'` / `'banner-bottom'` which render a full screen-width bar flush to the top/bottom edge. Default: `'bottom-right'`. Swipe axis follows the anchor: left/right corners swipe horizontally, center + banner positions swipe vertically.\n- `duration` (number | false, optional): Time in milliseconds before auto-closing. Set to `false` to disable auto-close. Default: 4000ms\n- `closeOnClick` (boolean, optional): If true, clicking the toast closes it. Default: inherited from Toaster\n- `showCloseIcon` (boolean, optional): If true, shows a close button. Default: inherited from Toaster\n- `dismissible` (boolean, optional): If false, prevents user from dismissing. Default: inherited from Toaster\n- `richColors` (boolean, optional): If true, uses richer color variants. Default: inherited from Toaster\n- `loading` (boolean, optional): If true, shows a loading spinner using Theme's global `spinnerVariant`\n- `progress` (boolean, optional): If true, shows a bar counting down the remaining duration (pauses on hover, keyboard focus, a press or swipe, and while the window is inactive). Only appears when the toast has a finite `duration`. Can also be set on `<Toaster progress />` as a default.\n- `swipeToDismiss` (boolean, optional, default true): Drag the toast toward its anchored screen edge (down for bottom-*, up for top-*) past a threshold, or flick it that way, to dismiss it; dragging the other way rubber-bands. Only the primary button drags, and only from the toast's surface: a press on an action button, the close button, a link or any `[data-swipe-ignore]` element never starts a drag. A press that travels mostly across the swipe axis never moves the toast, so the page keeps scrolling along that direction (a swipeable toast sets `touch-action` to `pan-y` when it swipes sideways and `pan-x` when it swipes vertically, so a touch drag along the swipe axis of a center or banner toast swipes it instead of scrolling the page); the stack stays expanded and its timers paused while a toast is dragged; a cancelled touch snaps it back, and a mouse released outside the window ends the drag where the button was last held (it dismisses or snaps back by the same rule as a normal release); and the click that ends a drag is not a `closeOnClick` press. A manual dismiss fires `onDismiss`, not `onAutoDismiss`.\n- `closeOnClick` (boolean, optional, default false): Dismiss when the toast body is clicked. Off by default now that swipe-to-dismiss exists; the close icon and swipe are the primary dismiss affordances.\n- `size` (Sizes, optional): Size of the toast \u2014 scales padding, corner radius, type and icon. Options: `'small'`, `'normal'`, `'large'` (default `'normal'`). Can be defaulted for all toasts with `<Toaster size=\"...\" />`.\n- `prefix` (Slot | false, optional): Content before the text. `false` hides the default icon\n- `suffix` (Slot, optional): Content to display after the toast text\n- `actions` (ToastAction[], optional): Buttons rendered inside the toast. `ToastAction` is full Button props plus `content` (the label) and `dismiss` (default true \u2014 clicking dismisses the toast). Each button's `onclick` runs with the native MouseEvent, then the toast fires `onDismiss`.\n- `closeIcon` (Slot, optional): Custom close button component\n- `icon` (string, optional): Icon name to display before the toast text\n- `important` (boolean, optional): Announced through the assertive live region instead of the polite one, so screen readers interrupt for it\n- `transition` (FSOProps, optional): Enter/exit transition override for this toast\n- `theme` (ToastThemeProps, optional): Theme overrides for this toast alone, layered over the `<Toaster theme>` object (`base` classes are appended, so the per-toast ones win)\n- `dedupe` (boolean, optional, default true): Without an `id`, a toast whose color, title and description match one still on screen updates that toast (its countdown restarts) instead of stacking a duplicate, so a repeated submission shows once. It compares plain-text titles and descriptions only; a snippet, or a toast with no text, is always added. Pass `false` to opt out. An explicit `id` always wins\n- `id` (string, optional): Custom ID for the toast. Auto-generated if not provided. Calling a creator again with an id that is still on screen updates that toast instead of adding another (see Updating by id)\n- `onAfterOpen` (function, optional): Called once the toast finishes entering: `(payload: Toast) => void`\n- `onDismiss` (function, optional): Called on manual dismiss (close button, an action, or `toast.remove()`). Not called on timeout: `(payload: Toast) => void`\n- `onAutoDismiss` (function, optional): Called only when the toast times out after `duration`. Put deferred irreversible work here; it never runs if the toast is dismissed first: `(payload: Toast) => void`\n\n### Undo / deferred-commit pattern\n\nRemove the item from the UI immediately, defer the real irreversible action to `onAutoDismiss`, and offer an `Undo` action. Undo dismisses the toast manually, so `onAutoDismiss` never fires:\n\n```ts\nfunction deleteItemWithUndo(item) {\n  removeFromUI(item);                       // optimistic\n  toast.neutral({\n    title: `Deleted \"${item.name}\"`,\n    duration: 5000,\n    actions: [{ content: 'Undo', onclick: () => restore(item) }],\n    onAutoDismiss: () => commitDelete(item)   // runs only if not undone\n  });\n}\n```\n\n**Updating by id:** a creator called with the `id` of a toast that is still on screen updates that toast in place and returns the same `Toast` handle. The new options merge over the previous ones (keys you leave out keep their value; pass `undefined` to clear one), the color follows the creator you call, and the auto-dismiss timer restarts from the full `duration`. A toast with that id that is still animating out, or that was removed earlier in the same tick, is replaced by a new `Toast`: it takes the leaving toast's place a microtask later, plays its entry transition from wherever the exit had reached, and fires its own `onAfterOpen`. The old handle no longer controls it. Toasts queued before a `<Toaster />` mounts merge by id the same way.\n\n```ts\ntoast.primary({ id: 'save', title: 'Saving\u2026', loading: true, duration: false });\n// later \u2014 same id, so the toast updates in place:\ntoast.success({ id: 'save', title: 'Saved', loading: false, duration: 3000 });\n```\n\n**Changing a toast: `toast.update`, `toast.dismiss`, `toast.promise`**\n\n`update`, `dismiss` and `promise` are reserved names, not colors.\n\n- `toast.update(id, patch)` changes the toast with that id that is on screen and returns its `Toast` handle (`undefined` when there is none). `patch` is an options object, or a function that receives the toast's current options (Toaster defaults included) and returns one. Keys left out keep their value, the timer restarts from the full `duration`, and the toast's `data-update-key` attribute changes. The handle has the same method: `handle.update(patch)`. A toast that was dismissed stays dismissed: updating it does nothing, so a result that arrives after the user closed the toast never brings it back.\n- `toast.dismiss(id?)` dismisses one toast, or every toast on screen (and any still waiting for a Toaster) when called without an id. Each fires `onDismiss` once.\n- `toast.promise(promise, { loading, success, error, id? })` shows a loading toast (a spinner, no timeout, color `primary`), then turns it into the success toast (color `success`) or error toast (color `danger`) when the promise settles. Each stage is a title string, an options object, or, for `success` and `error`, a function of the result or the rejection that returns either. The text and actions of the loading stage never carry over to the result. It returns the original promise, so it can be awaited, and a rejection still rejects for the caller.\n\n```ts\nimport { toast } from 'entasis/toast';\n\nasync function save(saveRows: () => Promise<number>) {\n  const rows = await toast.promise(saveRows(), {\n    loading: { title: 'Saving\u2026', description: 'Hold on' },\n    success: (count) => ({ title: `Saved ${count} rows` }),\n    error: (error) => ({ title: 'Save failed', description: (error as Error).message })\n  });\n  return rows;\n}\n\ntoast.update('batch', (current) => ({ title: current.title + '!' }));\ntoast.dismiss(); // closes every toast\n```\n\n**Mounting order:** `toast()` never throws when no `<Toaster />` is mounted yet \u2014 the toast is queued and shown by the first Toaster that mounts. In development, a single `console.warn` reports a queue that is still waiting a tick later. Dismissing a queued toast drops it from the queue, and a `toast()` call made during SSR is discarded instead of queued.\n\n**Returns:**\nA `Toast` instance that you can use to programmatically control the root:\n- `toast.remove()` - Remove the toast manually\n- `toast.update(patch)` - Update the toast in place (see Changing a toast); ignored once the toast was dismissed\n- `toast.updateKey` - Number of updates received, rendered as `data-update-key`\n- `toast.dismissed` - Whether the toast was dismissed\n- `toast.id` - Unique identifier\n- `toast.opts` - Toast options\n\n**Notes:**\n- Toasts are non-blocking and don't prevent user interaction\n- The toaster is a `role=\"region\"` landmark named \"Notifications\" (not a `<dialog>`), always rendered and empty while no toast shows; pressing F6 anywhere moves focus into it, and Tab then reaches the toasts. Toasts are announced through two live regions inside it that exist before the first toast: a polite one, and an assertive one for `important` toasts. The text announced is the toast's rendered title and description, again whenever the toast is updated. Each toast is a labelled `role=\"group\"` (named by its title, described by its description), not a live region of its own\n- When the focused toast is dismissed, or is pushed past `visibleToasts` and turns inert, focus moves to the nearest toast that stays visible, else back to the element that was focused before F6, else to the region, instead of dropping to the page\n- Toasts stacked away behind the front one are `inert` (rather than `aria-hidden`), so they take no clicks or tab stops until they surface\n- Multiple toasts can be displayed simultaneously and will stack based on position\n- Toasts pause their auto-close timer while the pointer is over their stack (a touch tap is not a hover), while keyboard focus (`:focus-visible`) is on the stack (a mouse click or tap that focuses a toast does not pause anything), while a press or swipe is on one of its toasts, and while the browser window is blurred or its tab is hidden. The timers resume only when none of these holds them, with the time they had left. A toast shown while any of them applies starts paused\n- Toasts can be dismissed by clicking the close icon, clicking the toast (if `closeOnClick` is true), or automatically after the duration expires\n\n## Toaster props\n\n- `direction` (`'ltr' | 'rtl'`, optional): sets `dir` on the notification region, so the toasts' text and layout follow it. Inherited from the page when omitted. Positions stay physical: `left` and `right` are screen sides.\n\n## Theme Customization\n\nThe Toast component uses a theme object that can be customized using the `theme` prop in toast options or by setting a global theme.\n\n### Theme Structure\n\nThe theme object contains the following parts:\n- **motion**: Enter/exit transition preset, keyed by `position` (each toast flies in from the\n  edge it is pinned to). Takes `in` / `out` FSO params plus a `duration` / `easing` motion\n  token; overrides ladder `<Theme components={{ toast }}>` \u2192 `setToastTheme` \u2192 `theme.motion`\n  \u2192 the Toaster's `transition` prop \u2192 a toast's own `transition`\n- **root**: Main toast container styles\n- **prefix**: Prefix icon/content styles\n- **suffix**: Suffix content styles\n- **content**: Content wrapper styles\n- **closeIcon**: Close button icon styles\n- **title**: Title text styles\n- **description**: Description text styles\n\n### Available Variants\n\n**root**:\n- base: Base classes for toast container\n- Variants:\n  - richColors: boolean - Rich color variant styling\n  - color: Color variants\n  - size: 'small' | 'normal' | 'large' - Toast size\n\n**prefix**:\n- base: Base classes for prefix content\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Icon size\n  - color: Color variants\n  - richColors: boolean - Rich color variant styling\n\n**suffix**:\n- base: Base classes for suffix content\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Content size\n  - color: Color variants\n  - richColors: boolean - Rich color variant styling\n\n**content**:\n- base: Base classes for content wrapper\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Content size\n  - color: Color variants\n  - richColors: boolean - Rich color variant styling\n\n**closeIcon**:\n- base: Base classes for close button\n- Variants:\n  - richColors: boolean - Rich color variant styling\n  - color: Color variants\n\n**title**:\n- base: Base classes for title text\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Text size\n  - color: Color variants\n  - richColors: boolean - Rich color variant styling\n\n**description**:\n- base: Base classes for description text\n- Variants:\n  - size: 'small' | 'normal' | 'large' - Text size\n  - color: Color variants\n  - richColors: boolean - Rich color variant styling\n\n### Usage Examples\n\n**Basic Theme Override**:\n```typescript\nimport { toast } from 'entasis/toast';\n\ntoast.success({\n  title: 'Success',\n  description: 'Operation completed',\n  theme: {\n    root: {\n      base: 'rounded-xl raised-5',\n      size: {\n        normal: 'px-4 py-3'\n      }\n    }\n  }\n});\n```\n\n**Custom Toast Styling**:\n```typescript\ntoast.danger({\n  title: 'Error',\n  description: 'Something went wrong',\n  theme: {\n    root: {\n      base: 'border-2 border-red-500',\n      richColors: {\n        true: 'bg-red-50 border-red-500'\n      }\n    },\n    title: {\n      base: 'font-bold text-red-900'\n    }\n  }\n});\n```\n\n**Global Theme Setting**:\n```svelte\n<script>\n  import { setToastTheme } from './index.ts';\n  \n  setToastTheme({\n    root: {\n      base: 'rounded-lg raised-4',\n      size: {\n        normal: 'px-3 py-2'\n      }\n    },\n    title: {\n      base: 'font-semibold'\n    }\n  });\n</script>\n```\n";

package/dist/components/Toast/toast.mcp.js

@@ -59,8 +59,8 @@ toast.warning({
 - \`dismissible\` (boolean, optional): If false, prevents user from dismissing. Default: inherited from Toaster
 - \`richColors\` (boolean, optional): If true, uses richer color variants. Default: inherited from Toaster
 - \`loading\` (boolean, optional): If true, shows a loading spinner using Theme's global \`spinnerVariant\`
-- \`progress\` (boolean, optional): If true, shows a bar counting down the remaining duration (pauses on hover). Only appears when the toast has a finite \`duration\`. Can also be set on \`<Toaster progress />\` as a default.
-- \`swipeToDismiss\` (boolean, optional, default true): Drag the toast toward its anchored screen edge (down for bottom-*, up for top-*) past a threshold to dismiss it; dragging the other way rubber-bands. A manual dismiss fires \`onDismiss\`, not \`onAutoDismiss\`.
+- \`progress\` (boolean, optional): If true, shows a bar counting down the remaining duration (pauses on hover, keyboard focus, a press or swipe, and while the window is inactive). Only appears when the toast has a finite \`duration\`. Can also be set on \`<Toaster progress />\` as a default.
+- \`swipeToDismiss\` (boolean, optional, default true): Drag the toast toward its anchored screen edge (down for bottom-*, up for top-*) past a threshold, or flick it that way, to dismiss it; dragging the other way rubber-bands. Only the primary button drags, and only from the toast's surface: a press on an action button, the close button, a link or any \`[data-swipe-ignore]\` element never starts a drag. A press that travels mostly across the swipe axis never moves the toast, so the page keeps scrolling along that direction (a swipeable toast sets \`touch-action\` to \`pan-y\` when it swipes sideways and \`pan-x\` when it swipes vertically, so a touch drag along the swipe axis of a center or banner toast swipes it instead of scrolling the page); the stack stays expanded and its timers paused while a toast is dragged; a cancelled touch snaps it back, and a mouse released outside the window ends the drag where the button was last held (it dismisses or snaps back by the same rule as a normal release); and the click that ends a drag is not a \`closeOnClick\` press. A manual dismiss fires \`onDismiss\`, not \`onAutoDismiss\`.
 - \`closeOnClick\` (boolean, optional, default false): Dismiss when the toast body is clicked. Off by default now that swipe-to-dismiss exists; the close icon and swipe are the primary dismiss affordances.
 - \`size\` (Sizes, optional): Size of the toast — scales padding, corner radius, type and icon. Options: \`'small'\`, \`'normal'\`, \`'large'\` (default \`'normal'\`). Can be defaulted for all toasts with \`<Toaster size="..." />\`.
 - \`prefix\` (Slot | false, optional): Content before the text. \`false\` hides the default icon
@@ -68,10 +68,11 @@ toast.warning({
 - \`actions\` (ToastAction[], optional): Buttons rendered inside the toast. \`ToastAction\` is full Button props plus \`content\` (the label) and \`dismiss\` (default true — clicking dismisses the toast). Each button's \`onclick\` runs with the native MouseEvent, then the toast fires \`onDismiss\`.
 - \`closeIcon\` (Slot, optional): Custom close button component
 - \`icon\` (string, optional): Icon name to display before the toast text
-- \`important\` (boolean, optional): Uses \`role="alert"\` + assertive announcements for screen readers
+- \`important\` (boolean, optional): Announced through the assertive live region instead of the polite one, so screen readers interrupt for it
 - \`transition\` (FSOProps, optional): Enter/exit transition override for this toast
 - \`theme\` (ToastThemeProps, optional): Theme overrides for this toast alone, layered over the \`<Toaster theme>\` object (\`base\` classes are appended, so the per-toast ones win)
-- \`id\` (string, optional): Custom ID for the toast. Auto-generated if not provided
+- \`dedupe\` (boolean, optional, default true): Without an \`id\`, a toast whose color, title and description match one still on screen updates that toast (its countdown restarts) instead of stacking a duplicate, so a repeated submission shows once. It compares plain-text titles and descriptions only; a snippet, or a toast with no text, is always added. Pass \`false\` to opt out. An explicit \`id\` always wins
+- \`id\` (string, optional): Custom ID for the toast. Auto-generated if not provided. Calling a creator again with an id that is still on screen updates that toast instead of adding another (see Updating by id)
 - \`onAfterOpen\` (function, optional): Called once the toast finishes entering: \`(payload: Toast) => void\`
 - \`onDismiss\` (function, optional): Called on manual dismiss (close button, an action, or \`toast.remove()\`). Not called on timeout: \`(payload: Toast) => void\`
 - \`onAutoDismiss\` (function, optional): Called only when the toast times out after \`duration\`. Put deferred irreversible work here; it never runs if the toast is dismissed first: \`(payload: Toast) => void\`
@@ -92,22 +93,62 @@ function deleteItemWithUndo(item) {
 }
 \`\`\`
 
+**Updating by id:** a creator called with the \`id\` of a toast that is still on screen updates that toast in place and returns the same \`Toast\` handle. The new options merge over the previous ones (keys you leave out keep their value; pass \`undefined\` to clear one), the color follows the creator you call, and the auto-dismiss timer restarts from the full \`duration\`. A toast with that id that is still animating out, or that was removed earlier in the same tick, is replaced by a new \`Toast\`: it takes the leaving toast's place a microtask later, plays its entry transition from wherever the exit had reached, and fires its own \`onAfterOpen\`. The old handle no longer controls it. Toasts queued before a \`<Toaster />\` mounts merge by id the same way.
+
+\`\`\`ts
+toast.primary({ id: 'save', title: 'Saving…', loading: true, duration: false });
+// later — same id, so the toast updates in place:
+toast.success({ id: 'save', title: 'Saved', loading: false, duration: 3000 });
+\`\`\`
+
+**Changing a toast: \`toast.update\`, \`toast.dismiss\`, \`toast.promise\`**
+
+\`update\`, \`dismiss\` and \`promise\` are reserved names, not colors.
+
+- \`toast.update(id, patch)\` changes the toast with that id that is on screen and returns its \`Toast\` handle (\`undefined\` when there is none). \`patch\` is an options object, or a function that receives the toast's current options (Toaster defaults included) and returns one. Keys left out keep their value, the timer restarts from the full \`duration\`, and the toast's \`data-update-key\` attribute changes. The handle has the same method: \`handle.update(patch)\`. A toast that was dismissed stays dismissed: updating it does nothing, so a result that arrives after the user closed the toast never brings it back.
+- \`toast.dismiss(id?)\` dismisses one toast, or every toast on screen (and any still waiting for a Toaster) when called without an id. Each fires \`onDismiss\` once.
+- \`toast.promise(promise, { loading, success, error, id? })\` shows a loading toast (a spinner, no timeout, color \`primary\`), then turns it into the success toast (color \`success\`) or error toast (color \`danger\`) when the promise settles. Each stage is a title string, an options object, or, for \`success\` and \`error\`, a function of the result or the rejection that returns either. The text and actions of the loading stage never carry over to the result. It returns the original promise, so it can be awaited, and a rejection still rejects for the caller.
+
+\`\`\`ts
+import { toast } from './index.ts';
+
+async function save(saveRows: () => Promise<number>) {
+  const rows = await toast.promise(saveRows(), {
+    loading: { title: 'Saving…', description: 'Hold on' },
+    success: (count) => ({ title: \`Saved \${count} rows\` }),
+    error: (error) => ({ title: 'Save failed', description: (error as Error).message })
+  });
+  return rows;
+}
+
+toast.update('batch', (current) => ({ title: current.title + '!' }));
+toast.dismiss(); // closes every toast
+\`\`\`
+
 **Mounting order:** \`toast()\` never throws when no \`<Toaster />\` is mounted yet — the toast is queued and shown by the first Toaster that mounts. In development, a single \`console.warn\` reports a queue that is still waiting a tick later. Dismissing a queued toast drops it from the queue, and a \`toast()\` call made during SSR is discarded instead of queued.
 
 **Returns:**
 A \`Toast\` instance that you can use to programmatically control the root:
 - \`toast.remove()\` - Remove the toast manually
+- \`toast.update(patch)\` - Update the toast in place (see Changing a toast); ignored once the toast was dismissed
+- \`toast.updateKey\` - Number of updates received, rendered as \`data-update-key\`
+- \`toast.dismissed\` - Whether the toast was dismissed
 - \`toast.id\` - Unique identifier
 - \`toast.opts\` - Toast options
 
 **Notes:**
 - Toasts are non-blocking and don't prevent user interaction
-- The toaster is a \`role="region"\` landmark named "Notifications" (not a \`<dialog>\`); pressing F6 anywhere moves focus into it. Each toast is \`role="status"\`, or \`role="alert"\` when \`important\`
+- The toaster is a \`role="region"\` landmark named "Notifications" (not a \`<dialog>\`), always rendered and empty while no toast shows; pressing F6 anywhere moves focus into it, and Tab then reaches the toasts. Toasts are announced through two live regions inside it that exist before the first toast: a polite one, and an assertive one for \`important\` toasts. The text announced is the toast's rendered title and description, again whenever the toast is updated. Each toast is a labelled \`role="group"\` (named by its title, described by its description), not a live region of its own
+- When the focused toast is dismissed, or is pushed past \`visibleToasts\` and turns inert, focus moves to the nearest toast that stays visible, else back to the element that was focused before F6, else to the region, instead of dropping to the page
 - Toasts stacked away behind the front one are \`inert\` (rather than \`aria-hidden\`), so they take no clicks or tab stops until they surface
 - Multiple toasts can be displayed simultaneously and will stack based on position
-- Toasts pause their auto-close timer when hovered
+- Toasts pause their auto-close timer while the pointer is over their stack (a touch tap is not a hover), while keyboard focus (\`:focus-visible\`) is on the stack (a mouse click or tap that focuses a toast does not pause anything), while a press or swipe is on one of its toasts, and while the browser window is blurred or its tab is hidden. The timers resume only when none of these holds them, with the time they had left. A toast shown while any of them applies starts paused
 - Toasts can be dismissed by clicking the close icon, clicking the toast (if \`closeOnClick\` is true), or automatically after the duration expires
 
+## Toaster props
+
+- \`direction\` (\`'ltr' | 'rtl'\`, optional): sets \`dir\` on the notification region, so the toasts' text and layout follow it. Inherited from the page when omitted. Positions stay physical: \`left\` and \`right\` are screen sides.
+
 ## Theme Customization
 
 The Toast component uses a theme object that can be customized using the \`theme\` prop in toast options or by setting a global theme.

package/dist/components/Toast/toast.state.svelte.d.ts

@@ -21,7 +21,7 @@ export type ToastAction = ButtonProps & {
     /** Whether clicking the button dismisses the toast. @default true */
     dismiss?: boolean;
 };
-type ToastOptions = {
+export type ToastOptions = {
     /** Stable toast identifier. */
     id: string;
     /** Semantic toast geometry. */
@@ -58,6 +58,12 @@ type ToastOptions = {
     description?: Slot;
     /** Semantic palette role. */
     color: Colors;
+    /**
+     * Without an `id`, a toast whose color, title and description match one still on screen
+     * updates that toast (its timer restarts) instead of stacking a duplicate. Applies only to
+     * plain-text title and description; pass `false` to always add a new toast. Default `true`.
+     */
+    dedupe?: boolean;
     /** Announces the toast with an assertive live region. */
     important?: boolean;
     /** Icon text displayed before the toast content. */
@@ -88,7 +94,7 @@ export type ToasterProps = Pick<ToastOptions, 'size' | 'closeOnClick' | 'swipeTo
     gap?: number;
     /** Distance from the screen edge in pixels. */
     offset?: number;
-    /** Text and layout direction. */
+    /** Text and layout direction of the toast region. Inherited from the page when omitted. */
     direction?: 'ltr' | 'rtl';
     /** Responsive default screen position. */
     position?: ResponsiveProps<ToastPosition>;
@@ -102,21 +108,69 @@ type MakeRequired<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>;
 type ToastRequest = Omit<ToastOptions, 'id'> & {
     id: string;
 };
+/** Options a later call changes on a toast that is already on screen; keys left out keep their value. */
+export type ToastUpdate = Partial<Omit<ToastOptions, 'id'>>;
+/**
+ * What `toast.update()` and `Toast.update()` accept: a patch, or a function that receives the
+ * toast's current options, Toaster defaults included, and returns the patch.
+ */
+export type ToastUpdater = ToastUpdate | ((current: Readonly<ToastOptions>) => ToastUpdate);
+/** A stage of `toast.promise()`: a title, or options for the toast in that stage. */
+type ToastPromiseStage<Value> = string | ToastUpdate | ((value: Value) => string | ToastUpdate);
+export type ToastPromiseOptions<Result = unknown> = {
+    /** Shown while the promise is pending: a spinner that stays until the promise settles. */
+    loading: string | ToastUpdate;
+    /** Shown when the promise resolves, or computed from its result. */
+    success: ToastPromiseStage<Result>;
+    /** Shown when the promise rejects, or computed from the rejection. */
+    error: ToastPromiseStage<unknown>;
+    /** Identifier of the toast. Calling again with an id that is still on screen reuses that toast. */
+    id?: string;
+};
 type ToasterOptions = Omit<MakeRequired<ToasterProps, 'collapseHorizontalAxis' | 'expand' | 'visibleToasts' | 'gap' | 'offset' | 'direction' | 'position' | 'perspectiveAmount'>, 'theme'> & {
     /** The Toaster's `theme.motion` slot, forwarded by `Toaster.svelte`. */
     motion?: ToastThemeProps['motion'];
 };
-declare const Toaster_base: new (props: ToasterOptions) => {} & Omit<MakeRequired<ToasterProps, "position" | "offset" | "direction" | "expand" | "collapseHorizontalAxis" | "visibleToasts" | "gap" | "perspectiveAmount">, "theme"> & {
+declare const Toaster_base: new (props: ToasterOptions) => {} & Omit<MakeRequired<ToasterProps, "direction" | "position" | "offset" | "expand" | "collapseHorizontalAxis" | "visibleToasts" | "gap" | "perspectiveAmount">, "theme"> & {
     /** The Toaster's `theme.motion` slot, forwarded by `Toaster.svelte`. */
     motion?: ToastThemeProps["motion"];
 };
 export declare class Toaster extends Toaster_base {
     toasts: Toast[];
     element: HTMLElement | undefined;
+    /** The position whose stack the pointer is over, if any. Set with `setHovering`. */
     hovering: ToastPosition | null;
+    /**
+     * The toast holding keyboard focus (`:focus-visible`), whose stack keeps its timers paused. A
+     * touch tap or a mouse click focuses a toast without pausing anything.
+     */
+    focusedToast: Toast | null;
+    /** Focus rests on the notification region itself, where F6 puts it; every stack is held. */
+    regionFocused: boolean;
     polygon: [number, number, number, number];
     isOpen: boolean;
     theme: ThemeState;
+    liveRegions: {
+        polite: {
+            regionId: string;
+            politeness: import("../../utils/useLiveAnnouncer.svelte.js").LivePoliteness;
+            regionAttrs: import("../../utils/useLiveAnnouncer.svelte.js").LiveRegionAttributes;
+            readonly message: string;
+            announce(next: string): void;
+            reset(): void;
+        };
+        assertive: {
+            regionId: string;
+            politeness: import("../../utils/useLiveAnnouncer.svelte.js").LivePoliteness;
+            regionAttrs: import("../../utils/useLiveAnnouncer.svelte.js").LiveRegionAttributes;
+            readonly message: string;
+            announce(next: string): void;
+            reset(): void;
+        };
+        host: import("svelte/attachments").Attachment<HTMLElement>;
+        announce(message: string, politeness?: import("../../utils/useLiveAnnouncer.svelte.js").LivePoliteness): void;
+        reset(): void;
+    };
     resolveMotion: import("../../utils/motion/index.js").ComponentMotion<{
         readonly position: {
             readonly 'top-left': {
@@ -197,34 +251,132 @@ export declare class Toaster extends Toaster_base {
     toastsPerPositions: Record<ToastPosition, Toast[]>;
     shouldCollapseHorizontally: boolean;
     constructor(opts: ToasterProps & Pick<ToasterOptions, 'motion'>);
+    private windowInactive;
+    /** The reasons that currently hold the timers of the toasts at `position`. */
+    private reasonsFor;
+    private syncToastHolds;
+    /** Matches every timer's holds to the pointer, focus, swipe and window state. */
+    syncHolds: () => void;
+    /** Whether a press or a swipe is on a toast at `position`. */
+    isPressed: (position: ToastPosition) => boolean;
+    /** Whether a toast at `position` is being dragged; the stack stays expanded meanwhile. */
+    isSwiping: (position: ToastPosition) => boolean;
+    /** The pointer entered (`position`) or left (`null`) a stack. */
+    setHovering: (position: ToastPosition | null) => void;
+    /** Keyboard focus entered `toast` (`:focus-visible`), or left it (`null`, only if it holds it). */
+    setFocused: (toast: Toast | null, from?: Toast) => void;
+    /**
+     * Matches a toast's timer to its duration. `restart` counts down the full duration again
+     * even when it did not change. A new timer starts held by whatever holds its position.
+     */
+    private syncTimer;
     maybeCloseToaster: () => void;
     private resolveOptions;
     addToast: (opts: Omit<ToastOptions, "id"> & {
         id?: string;
     }) => Toast;
+    private leaving;
+    private arriving;
     /**
      * Attaches a toast to this Toaster: resolves its options against the Toaster's
      * defaults and pushes it onto the stack. Used both for a freshly created toast and
      * for one parked in the pending queue while no Toaster was mounted.
+     *
+     * A toast whose id is already on screen is not added twice (the list is keyed by id):
+     * its options are merged into the live toast, its timer restarts, and the live toast is
+     * returned. A toast whose id is still animating out joins a microtask later, once that
+     * removal has reached the DOM, and takes the leaving item over.
      */
     adoptToast: (toast: Toast) => Toast;
+    /**
+     * Resolves a live toast's options against the Toaster's defaults again after they changed, and
+     * restarts its countdown. An arriving toast gets its timer when it joins the stack.
+     */
+    refreshToast: (toast: Toast) => void;
+    /** The toast with `id` that is on screen or about to be, never one that is leaving. */
+    find: (id: string) => Toast | undefined;
+    /** Dismisses every toast on screen or about to be; each fires `onDismiss` once. */
+    dismissAll: () => void;
+    private joinStack;
     removeToast: (toast: Toast) => void;
-    toggleTimers: (position: ToastPosition, mode: "pause" | "resume") => void;
+    private focusOrigin;
+    /**
+     * F6: moves focus into the notification region, remembering where it came from. With no toast
+     * on screen there is nothing to reach, and focus stays where it is.
+     */
+    focusRegion: () => void;
+    private keyboardRegionFocus;
+    /**
+     * Focuses the region. Only keyboard focus holds the timers: a pointer or touch user whose toast
+     * left lands on the region too, and must not leave every later toast waiting on it.
+     */
+    private focusRegionElement;
+    private holdRegion;
+    /** Focus entered the region element itself: the toasts it holds wait for the user to reach them. */
+    onRegionFocusIn: (event: FocusEvent) => void;
+    /**
+     * Focus left the region element, or left the region and everything in it. The element F6 came
+     * from is forgotten once focus is somewhere else on its own, so it cannot pull focus back later.
+     */
+    onRegionFocusOut: (event: FocusEvent) => void;
+    /**
+     * Called while `toast` still holds focus and is about to leave: it was dismissed, or it is
+     * pushed past `visibleToasts` and turns inert. Focus moves to the toast nearest to it in the
+     * stack that stays visible, else back to the element F6 left, else to the region, rather than
+     * dropping to the document body.
+     */
+    moveFocusFrom: (toast: Toast) => void;
+    private pendingAnnouncements;
+    private announceTimer;
+    /** Announces a toast's text in the persistent live regions; `important` ones are assertive. */
+    announce: (message: string, important?: boolean) => void;
 }
 export declare class Toast {
     id: string;
     toaster: Toaster | null;
     theme: ThemeState | null;
-    /** The caller's own options; a Toaster layers its defaults over them on adoption. */
-    readonly requested: ToastRequest;
+    /**
+     * The caller's own options; a Toaster layers its defaults over them on adoption. A later
+     * `toast()` call with the same id merges its options in (see `merge`).
+     */
+    requested: ToastRequest;
     element: HTMLElement | undefined;
     height: number;
     loading: boolean;
+    /**
+     * Counts the updates this toast received after it was created, by `toast()` with its id,
+     * `toast.update()` or `update()`. Rendered as `data-update-key`.
+     */
+    updateKey: number;
+    /**
+     * Counts the times this toast was shown again while on screen (a `toast()` call with its id, or
+     * the same message deduplicated). Each one plays a short bounce to draw the eye back to it.
+     */
+    attentionKey: number;
+    /** A pointer is down on the toast, or it is being swiped; its stack's timers are held. */
+    pressed: boolean;
+    /** The toast is being dragged; its stack stays expanded meanwhile. */
+    dragging: boolean;
     timer: Timer | undefined;
     index: number;
     opts: MakeRequired<ToastOptions, "position">;
     position: ToastPosition;
     constructor(opts: ToastRequest);
+    /**
+     * Merges the options of a later `toast()` call with this id over the ones this toast
+     * was created with; keys the call leaves out keep their value. The owning Toaster
+     * resolves its defaults over the result.
+     */
+    merge: (request: Partial<ToastRequest>) => void;
+    /**
+     * Updates the toast in place: a patch, or a function that receives the current options and
+     * returns one. Keys left out keep their value, the countdown restarts from the full duration,
+     * and `data-update-key` changes. A toast that was dismissed stays dismissed: updating it, such
+     * as when a promise settles after the user closed its toast, does nothing.
+     */
+    update: (patch: ToastUpdater) => this;
+    /** Whether the toast was dismissed, by the user, a timeout or `remove()`. */
+    get dismissed(): boolean;
     animations: import("../../utils/motion/index.js").ResolvedMotion;
     private lastStack;
     indexInStack: {
@@ -257,6 +409,20 @@ type ToastCreator = {
     [key in Colors]: (t: Omit<Partial<ToastOptions>, 'color' | 'id'> & {
         id?: string;
     }) => Toast;
+} & {
+    /**
+     * Updates the toast with `id` that is on screen: a patch, or a function of its current options.
+     * Returns the toast, or `undefined` when none with that id is on screen.
+     */
+    update: (id: string, patch: ToastUpdater) => Toast | undefined;
+    /** Dismisses the toast with `id`, or every toast on screen when called without one. */
+    dismiss: (id?: string) => void;
+    /**
+     * Shows a loading toast, then turns it into a success or error toast when `promise` settles.
+     * Returns `promise`, so it can still be awaited. A toast the user dismissed while the promise
+     * was pending is not shown again.
+     */
+    promise: <Result>(promise: Promise<Result>, options: ToastPromiseOptions<Result>) => Promise<Result>;
 };
 export declare const toast: ToastCreator;
 export {};