@sakaniui/react 0.8.13 → 0.9.0

package/AGENTS.md

@@ -78,7 +78,7 @@ import { Button, Card } from '@sakaniui/react';
    (`aria-label`, or `label` on `socialLinks`). Status changes use live regions (`Alert`, `Toast`,
    `Spinner`, `EmptyState` are `role="status"`/`alert`). Never remove focus rings.
 7. **Don't fake what the system doesn't do.** `Toast` is presentational — you own queueing and
-   positioning. `Menu` is a surface — you own anchoring (pair it with `Popover`). Dragging is a
+   positioning (for a ready-made stack, use `Toaster` and `toast()`). `Menu` is a surface — you own anchoring (pair it with `Popover`). Dragging is a
    look, not a behaviour. Check "Behaviour you must supply" in the table below before assuming.
 8. **Compose in slots, don't fork.** Components expose slots (`leading`, `trailing`, `meta`,
    `assignees`, `icon`, `actions`). Fill a slot with other system components rather than copying a
@@ -153,7 +153,7 @@ CSS of a component into your own file.
 Format: **Use for** · **Why it is built this way** · **Not for / instead**.
 
 **Looking for a component by another name?** SakaniUI uses its own names. A *dialog* or *alert dialog* is
-`Modal`; a *snackbar* is `Toast`; a *dropdown menu* is `Menu`; a *navbar* or *app bar* is `TopBar`; a
+`Modal`; a *snackbar* is `Toast` (or `Toaster` + `toast()` for a managed stack); a *dropdown menu* is `Menu`; a *navbar* or *app bar* is `TopBar`; a
 *date picker* is `Calendar`; a *loader* is `Spinner`; a *toggle* is `Switch`; a *banner* is `Announcement`;
 *autocomplete* is `Combobox`. There is no `Dialog`, `AlertDialog`, `Snackbar` or `Navbar`. Each component
 lists its other names under `aliases` in `manifest.json`, and `search_components` understands them.
@@ -174,6 +174,11 @@ lists its other names under `aliases` in `manifest.json`, and `search_components
 - **Toast** — Use for short-lived confirmation or error after an action. *Why:* presentational only;
   queueing and positioning are the app's job, so it fits any notification system. *Not for* anything the user
   must act on — a toast disappears.
+- **Toaster + toast()** — Use for notifications you trigger from code: mount one `<Toaster />`, call
+  `toast.success('Saved')` from anywhere. *Why:* it owns queueing, position (6), the 4s timer, the pile that
+  spreads on hover and swipe-to-dismiss, so the app does not. `toast.promise` turns one toast from loading
+  into success or error. *Not for* anything the user must act on — a toast disappears; a plain static card
+  → `Toast`. Needs `Toaster` mounted once, and `toast()` is a function, not a component.
 - **Badge** — Use for a short status, category or count. *Why:* 6 colours × subtle/solid, no sizes, no
   borders — it is a label, not a control. *Not for* clickable filters → `FilterChip`.
 - **Tooltip** — Use for brief supplementary text on hover/focus. *Why:* pure CSS, so it works with
@@ -261,7 +266,8 @@ and **tell the user when you are composing** rather than implying a dedicated co
 
 | Component | You own |
 |---|---|
-| Toast | queueing, positioning, auto-dismiss timing |
+| Toast | queueing, positioning, auto-dismiss timing (or use `Toaster`) |
+| Toaster | mounting it once; it handles the rest |
 | Menu | anchoring/positioning (pair with Popover) |
 | BoardCard `dragging` | drag-and-drop logic and drop targets |
 | BoardColumn `loading` | the skeleton cards inside it |

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to `@sakaniui/react` are documented here.
 
+## 0.9.0
+
+- **New: `Toaster` and `toast()`**, a managed toast stack (Sonner-style) built from the new *↳ Sonner* page in Figma.
+  Mount one `<Toaster />`, then call `toast()`, `toast.success()`, `.info()`, `.warning()`, `.error()`,
+  `.loading()`, `.promise()` and `.dismiss()` from anywhere.
+  - New toasts rise in from the edge; older ones pile up behind the newest (lifted 14px, shrunk 5% per level,
+    content hidden, three visible). Hover or focus spreads the pile into a list and pauses the 4s timers;
+    leaving folds it back. Swipe a toast towards its edge to dismiss it (past 45px, or a quick flick, it flies
+    out in 200ms; otherwise it springs back in 400ms). Motion is 400ms `ease`.
+  - Options per toast: `description`, `icon`, `action`, `cancel`, `closeButton`, `duration`, `dismissible`,
+    `richColors`, `id` (update in place), `onDismiss`, `onAutoClose`. On `Toaster`: `position` (six),
+    `richColors`, `closeButton`, `expand`, `visibleToasts`, `duration`, `gap`, `offset`, `mobileOffset`,
+    `hotkey` (alt+T focuses the stack; Escape folds it).
+  - Light, dark and glass surfaces through the existing tokens; reduced motion keeps the fades only; errors
+    are announced assertively.
+  - The existing `Toast` is unchanged: it stays the static, presentational card.
+- Agent contract: `Toaster` is in the manifest with recipes (show a toast, a promise toast) and the aliases
+  *sonner*, *toast stack*, *toast provider*. (`toaster` now means this component, not `Toast`.)
+
 ## 0.8.13
 
 A user reported the MCP server "didn't work". Reproduced: on a Node older than 16.9 the server connected

package/README.md

@@ -262,7 +262,7 @@ Change a semantic token and every component follows — in both the design file
 
 **Forms** — Input · Textarea · Select · Checkbox · Radio · Switch · Slider · Combobox (single/multi, async loading) · File Upload
 
-**Composite** — Card · Alert · Toast · Accordion · Tabs · Breadcrumb · Table (generic, selectable) · Stat Card (sparklines) · Stepper · Calendar (single + range, dropdown navigation) · Pagination · Popover · Segmented Control · List Item
+**Composite** — Card · Alert · Toast · Toaster (Sonner-style `toast()` stack) · Accordion · Tabs · Breadcrumb · Table (generic, selectable) · Stat Card (sparklines) · Stepper · Calendar (single + range, dropdown navigation) · Pagination · Popover · Segmented Control · List Item
 
 **Sidebar kit** — Sidebar · Header · Search · Item · Sub Item · Group Label · Divider · Promo · Footer — nine standalone parts that compose into full navigation
 

package/bin/sakaniui-mcp.mjs

@@ -468,8 +468,10 @@ function checkCode(source) {
     if (imp.def) errors.push({ line: imp.line, message: `${entry} has no default export; use a named import: import { ${imp.def} } from '${entry}';` });
     for (const n of imp.names) {
       if (n.typeOnly) continue;
-      const c = byName.get(n.imported.toLowerCase());
-      const isUtility = manifest.utilities?.some((u) => u.name === n.imported);
+      const util = manifest.utilities?.find((u) => u.name === n.imported);
+      const isUtility = !!util;
+      // an exact helper name (toast) is not a mis-cased component (Toast)
+      const c = isUtility ? undefined : byName.get(n.imported.toLowerCase());
       if (entry === '@sakaniui/react/icons') {
         if (!iconNames.has(n.imported) && !iconOtherExports.has(n.imported)) {
           const hint = searchIcons(n.imported, 3).map((i) => i.name);
@@ -489,6 +491,7 @@ function checkCode(source) {
         errors.push({ line: imp.line, message: `${n.imported} is not exported by @sakaniui/react.${aliasHint(n.imported)}${near.length ? ` Did you mean: ${near.join(', ')}?` : ''} Use search_components.` });
       }
       if (c && inInstalled(c) === false) errors.push({ line: imp.line, message: `${c.name} was added in ${c.since}; the project has ${projectVersion}.` });
+      if (util && inInstalled(util) === false) errors.push({ line: imp.line, message: `${util.name} was added in ${util.since}; the project has ${projectVersion}.` });
     }
   }
 

package/dist/components/Sonner/Sonner.d.ts

@@ -0,0 +1,30 @@
+import { default as React } from 'react';
+export type ToastPosition = 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';
+export interface ToasterProps {
+    /** Corner or edge the stack sits on. Defaults to "bottom-right". */
+    position?: ToastPosition;
+    /** Tints success, info, warning and error toasts by type. */
+    richColors?: boolean;
+    /** Shows the round close button on every toast. */
+    closeButton?: boolean;
+    /** Keeps the stack spread out instead of piled up. */
+    expand?: boolean;
+    /** How many toasts show at once; older ones fade out. Defaults to 3. */
+    visibleToasts?: number;
+    /** Milliseconds before a toast closes itself. Defaults to 4000. */
+    duration?: number;
+    /** Space between toasts when spread out, in px. Defaults to 14. */
+    gap?: number;
+    /** Distance from the viewport edge, in px or any CSS length. Defaults to 24. */
+    offset?: number | string;
+    /** Distance from the viewport edge on screens 600px wide or less. Defaults to 16. */
+    mobileOffset?: number | string;
+    /** Keys that focus the stack. Defaults to alt+T (`['altKey', 'KeyT']`). */
+    hotkey?: string[];
+    /** Accessible name of the notifications region. The hotkey is appended. Defaults to "Notifications". */
+    containerAriaLabel?: string;
+    className?: string;
+    style?: React.CSSProperties;
+}
+export declare const Toaster: React.FC<ToasterProps>;
+export default Toaster;

package/dist/components/Sonner/index.d.ts

@@ -0,0 +1,4 @@
+export { Toaster, default } from './Sonner';
+export type { ToasterProps, ToastPosition } from './Sonner';
+export { toast } from './state';
+export type { ToastType, ToastId, ToastOptions, ToastData, ToastAction, ToastCancel, ToastPromiseMessages } from './state';

package/dist/components/Sonner/state.d.ts

@@ -0,0 +1,106 @@
+import { default as React } from 'react';
+export type ToastType = 'default' | 'success' | 'info' | 'warning' | 'error' | 'loading';
+export type ToastId = string | number;
+export interface ToastAction {
+    /** Button text. */
+    label: React.ReactNode;
+    /** Called on click. The toast closes afterwards unless you call `event.preventDefault()`. */
+    onClick: (event: React.MouseEvent<HTMLButtonElement>) => void;
+}
+export interface ToastCancel {
+    /** Button text. */
+    label: React.ReactNode;
+    /** Called on click, before the toast closes. */
+    onClick?: (event: React.MouseEvent<HTMLButtonElement>) => void;
+}
+export interface ToastOptions {
+    /** Reuse an id to update a toast in place instead of adding a new one. */
+    id?: ToastId;
+    /** Secondary line under the title. */
+    description?: React.ReactNode;
+    /** Replaces the type icon. Pass `null` to show no icon. */
+    icon?: React.ReactNode;
+    /** Primary button, right-most. */
+    action?: ToastAction;
+    /** Secondary button, left of the action. */
+    cancel?: ToastCancel;
+    /** Milliseconds before the toast closes itself. Overrides the Toaster's `duration`. `Infinity` keeps it open. */
+    duration?: number;
+    /** Shows the round close button on this toast. Overrides the Toaster's `closeButton`. */
+    closeButton?: boolean;
+    /** When false the toast cannot be swiped away or closed by the user. Defaults to true. */
+    dismissible?: boolean;
+    /** Announces the toast assertively (interrupting the screen reader). Errors are announced this way by default. */
+    important?: boolean;
+    /** Tints this toast by its type. Overrides the Toaster's `richColors`. */
+    richColors?: boolean;
+    /** Called when the toast is closed by the user (close button, cancel, swipe) or by `toast.dismiss()`. */
+    onDismiss?: (toast: ToastData) => void;
+    /** Called when the toast closes itself after its duration. */
+    onAutoClose?: (toast: ToastData) => void;
+    /** Extra class on the toast element. */
+    className?: string;
+}
+export interface ToastData extends ToastOptions {
+    id: ToastId;
+    type: ToastType;
+    title: React.ReactNode;
+    /** @internal set by toast.dismiss(); the Toaster plays the exit motion, then removes it */
+    delete?: boolean;
+    /** @internal bumped on every update so the timer restarts */
+    version: number;
+}
+export interface ToastPromiseMessages<T> extends Omit<ToastOptions, 'id'> {
+    id?: ToastId;
+    /** Shown while the promise is pending. Leave it out to show nothing until it settles. */
+    loading?: React.ReactNode;
+    /** Shown when it resolves. A function receives the resolved value. */
+    success?: React.ReactNode | ((data: T) => React.ReactNode);
+    /** Shown when it rejects. A function receives the error. */
+    error?: React.ReactNode | ((error: unknown) => React.ReactNode);
+    /** Called after it settles either way. */
+    finally?: () => void;
+}
+type Event = {
+    kind: 'upsert';
+    toast: ToastData;
+} | {
+    kind: 'dismiss';
+    id?: ToastId;
+};
+type Listener = (event: Event) => void;
+/** @internal */
+export declare const store: {
+    subscribe(listener: Listener): () => void;
+    /** Toasts that are open right now, newest first. */
+    active: () => ToastData[];
+    /** @internal the Toaster calls this once a toast has finished its exit motion */
+    remove(id: ToastId): void;
+};
+declare function dismiss(id?: ToastId): ToastId | undefined;
+declare function promise<T>(input: Promise<T> | (() => Promise<T>), messages: ToastPromiseMessages<T>): ToastId;
+type ToastFn = (title: React.ReactNode, options?: ToastOptions) => ToastId;
+/**
+ * Shows a toast. Needs one `<Toaster />` mounted somewhere in the app.
+ *
+ *   toast('Event has been created', { description: 'Monday, January 3rd at 6:00pm' })
+ *   toast.success('Saved')
+ *   toast.error('Upload failed', { action: { label: 'Retry', onClick: retry } })
+ *   toast.promise(save(), { loading: 'Saving…', success: 'Saved', error: 'Could not save' })
+ *   toast.dismiss(id)
+ *
+ * Every call returns the toast's id; pass it back as `id` to update that toast in place.
+ */
+export declare const toast: ToastFn & {
+    message: ToastFn;
+    success: ToastFn;
+    info: ToastFn;
+    warning: ToastFn;
+    error: ToastFn;
+    /** Stays open (no timer) until you update it with the same `id` or dismiss it. */
+    loading: ToastFn;
+    promise: typeof promise;
+    /** Closes one toast, or every toast when called without an id. */
+    dismiss: typeof dismiss;
+};
+export {};