gbs-add-block 1.2.11 → 1.2.12

package/README.md

@@ -1,4 +1,4 @@
-# GBS Building Blocks 2.0 (v1.2.11)
+# GBS Building Blocks 2.0 (v1.2.12)
 
 Latest and upgraded version of GBS building blocks with headless UI and removed dependencies.
 
@@ -14,9 +14,10 @@ DataGrid and Combobox use the redesigned core API and design system. Install the
 npx gbs-add-block -a DataGrid -beta
 npx gbs-add-block -a Combobox -beta
 npx gbs-add-block -a DatePicker -beta
+npx gbs-add-block -a Toaster -beta
 ```
 
-## What's New 🎉 (Ver 1.2.11)
+## What's New 🎉 (Ver 1.2.12)
 
 - Update Candidate for next major change 2.0.0
 

package/index.cjs

@@ -38,7 +38,7 @@ const CONFIG = {
   betaComponents: ["DataGrid", "Combobox", "DatePicker"],
   // Define component dependencies
   dependencies: {
-    FormRenderer: ["Select", "MultiSelect", "Input", "DatePicker"],
+    FormRenderer: ["Select", "MultiSelect", "Input", "DatePicker", "toaster"],
   },
   docs: "https://gramprokit.vercel.app/",
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gbs-add-block",
-  "version": "1.2.11",
+  "version": "1.2.12",
   "description": "React Component Library",
   "type": "module",
   "files": [

package/source/beta-components/toaster/README.md

@@ -0,0 +1,128 @@
+# Toaster
+
+Notifications for any React 19 app — Vite, Next.js, Remix or plain React — styled
+to match the DataGrid, Combobox and DatePicker. No runtime dependencies besides
+React.
+
+- **`<Toaster />`** — mount once; renders the toasts.
+- **`toast()`** — call from anywhere: components, event handlers, data layers,
+  even code outside React. No hook, context or provider.
+
+## Setup
+
+```ts
+import { toast, Toaster } from "@/components/toaster";
+import "@/components/toaster/styles.css";
+```
+
+```tsx
+// Once, near the root of the app (e.g. app/layout.tsx or App.tsx)
+<Toaster />
+
+// Anywhere
+toast.success("Settings saved");
+```
+
+Import from one path everywhere. `toast()` and `<Toaster />` meet through a
+shared store, and a bundler that sees two import paths may create two stores.
+
+## Showing toasts
+
+```tsx
+toast("Event created", { description: "Monday, 10:00" });
+toast.success("Saved");
+toast.error("Upload failed", { action: { label: "Retry", onClick: retry } });
+toast.warning("Storage almost full");
+toast.info("New version available");
+const id = toast.loading("Uploading…");       // stays until updated
+
+toast.update(id, { type: "success", title: "Uploaded" });
+toast.dismiss(id);                             // or toast.dismiss() for all
+
+toast.promise(saveUser(data), {
+  loading: "Saving…",
+  success: (user) => `${user.name} saved`,
+  error: (error) => `Could not save: ${(error as Error).message}`,
+});
+
+toast.custom(({ dismiss }) => <MyCard onClose={dismiss} />);
+```
+
+Every call returns the toast's id. Passing an `id` that is already on screen
+updates that toast instead of adding another.
+
+## Toast options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `id` | `string` | generated | Reuse to update a toast in place. |
+| `type` | `"default"` \| `"success"` \| `"error"` \| `"warning"` \| `"info"` \| `"loading"` | `"default"` | Icon, color bar and announcement. |
+| `description` | `ReactNode` | — | Second line. |
+| `duration` | `number` | `5000` (loading: stays) | Milliseconds. `0` or `Infinity` stays until dismissed. |
+| `dismissible` | `boolean` | `true` | Close button, Escape and swipe. |
+| `action` / `cancel` | `{ label, onClick(event) }` | — | Buttons. The toast closes after a click unless `event.preventDefault()` is called. |
+| `icon` | `ReactNode` | the type's icon | `null` hides it. |
+| `className` | `string` | — | Class for this toast. |
+| `render` | `({ id, dismiss }) => ReactNode` | — | Custom body (`toast.custom` sets it). |
+| `onDismiss` / `onAutoClose` | `(toast) => void` | — | Closed by someone, or because time ran out. |
+
+## Toaster props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `position` | `"top-left"` \| `"top-center"` \| `"top-right"` \| `"bottom-left"` \| `"bottom-center"` \| `"bottom-right"` | `"top-right"` | Where the stack sits. Full width on narrow screens. |
+| `limit` | `number` | `3` | Toasts on screen at once. The rest wait, with their timers held. |
+| `duration` | `number` | `5000` | Default auto-close delay. |
+| `closeButton` | `boolean` | `true` | Close button on dismissible toasts. |
+| `hotkey` | `string[]` | `["altKey", "KeyT"]` | Moves focus to the notifications. `[]` turns it off. |
+| `icons` | `Partial<Record<ToastType, ReactNode>>` | — | Replace icons per type; `null` hides one. |
+| `store` | `ToastStore` | the `toast()` store | For a separate notification area. |
+| `dir` | `"ltr"` \| `"rtl"` \| `"auto"` | inherited | Text direction. |
+| `className`, `classNames`, `style` | — | — | Slots: `region`, `list`, `toast`, `icon`, `content`, `title`, `description`, `actions`, `action`, `cancel`, `close`. |
+| `localeText` | `Partial<ToasterLocaleText>` | English | `regionLabel(hotkey)`, `close`. |
+
+## Behavior
+
+- Timers pause while the pointer is over the toasts, while focus is inside them,
+  and while the browser tab is hidden.
+- Toasts beyond `limit` wait with their full time and appear as others close.
+- Toasts render in a portal on `<body>`, so no parent's overflow, transform or
+  z-index can hide them.
+
+## Keyboard and accessibility
+
+| Keys | Action |
+| --- | --- |
+| **Alt + T** | Move focus to the notifications (configurable with `hotkey`). |
+| **Tab** | Move between toasts and their buttons. |
+| **Escape** | Dismiss the focused toast. |
+| swipe sideways | Dismiss (touch, pen or mouse). |
+
+The list is a polite live region, always in the page, so new toasts are read out
+without interrupting. Error toasts use `role="alert"` and interrupt. The region is
+a labelled landmark ("Notifications (Alt+T)").
+
+## Theming
+
+Override `--ts-*` variables (they default to the grid's `--dg-*`). Toasts render
+on `<body>`, so set shared `--dg-*` values on `:root`:
+
+```css
+.ts-region { --ts-width: 420px; --ts-success: #059669; --ts-radius: 12px; }
+```
+
+State attributes: `data-position` on the region; `data-type`, `data-state`
+(`open` / `closing`), `data-custom`, `data-swiping` on toasts.
+
+## Headless use
+
+`useToasts(store?)` returns the live snapshot (`toasts`, `paused`, `limit`) for a
+custom UI, and `visibleToasts(snapshot)` picks the ones to show.
+`createToastStore()` and `createToastApi(store)` build separate instances. All of
+`core` runs without React.
+
+## Known limits
+
+- One stack per `<Toaster />`; toasts don't collapse into an expandable pile.
+- `toast()` does nothing during a server render or in server code. Call it in
+  the browser, e.g. after a Server Action resolves.

package/source/beta-components/toaster/__tests__/core.test.ts

@@ -0,0 +1,256 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { createToastApi } from "../core/api";
+import { createToastStore, visibleToasts, type ToastStore } from "../core/store";
+import { toast, toastStore } from "../core/toast";
+
+beforeEach(() => {
+  vi.useFakeTimers();
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+const states = (store: ToastStore) =>
+  store.getSnapshot().toasts.map((item) => `${item.id}:${item.state}`);
+
+const find = (store: ToastStore, id: string) =>
+  store.getSnapshot().toasts.find((item) => item.id === id);
+
+describe("showing", () => {
+  it("adds toasts newest first, with defaults", () => {
+    const store = createToastStore();
+    const first = store.show("Saved");
+    const second = store.show("Deleted", { type: "error", description: "3 rows" });
+
+    expect([first, second]).toEqual(["toast-1", "toast-2"]);
+    const [newest, oldest] = store.getSnapshot().toasts;
+    expect(newest).toMatchObject({ id: "toast-2", type: "error", description: "3 rows" });
+    expect(oldest).toMatchObject({
+      title: "Saved",
+      type: "default",
+      duration: 5000,
+      dismissible: true,
+      state: "open",
+      version: 1,
+    });
+  });
+
+  it("updates a toast shown again with the same id, keeping its place", () => {
+    const store = createToastStore();
+    store.show("Syncing", { id: "sync" });
+    store.show("Other");
+    store.show("Synced", { id: "sync", type: "success" });
+
+    expect(states(store)).toEqual(["toast-1:open", "sync:open"]);
+    expect(find(store, "sync")).toMatchObject({ title: "Synced", type: "success", version: 2 });
+  });
+
+  it("restarts the countdown when the same id is shown again", () => {
+    const store = createToastStore();
+    store.show("Draft saved", { id: "draft" });
+    vi.advanceTimersByTime(4000);
+    store.show("Draft saved again", { id: "draft" });
+    vi.advanceTimersByTime(4000);
+    expect(find(store, "draft")?.state).toBe("open");
+    vi.advanceTimersByTime(1000);
+    expect(find(store, "draft")?.state).toBe("closing");
+  });
+
+  it("brings back a toast that is fading out instead of stacking a copy", () => {
+    const store = createToastStore();
+    store.show("Offline", { id: "net" });
+    store.dismiss("net");
+    store.show("Still offline", { id: "net" });
+    vi.advanceTimersByTime(300);
+    expect(states(store)).toEqual(["net:open"]);
+  });
+});
+
+describe("timing", () => {
+  it("closes after its duration, then leaves after the exit animation", () => {
+    const store = createToastStore();
+    const onAutoClose = vi.fn();
+    const onDismiss = vi.fn();
+    store.show("Saved", { duration: 2000, onAutoClose, onDismiss });
+
+    vi.advanceTimersByTime(1999);
+    expect(states(store)).toEqual(["toast-1:open"]);
+    vi.advanceTimersByTime(1);
+    expect(states(store)).toEqual(["toast-1:closing"]);
+    expect(onAutoClose).toHaveBeenCalledOnce();
+    expect(onDismiss).not.toHaveBeenCalled();
+    vi.advanceTimersByTime(200);
+    expect(states(store)).toEqual([]);
+  });
+
+  it("keeps sticky and loading toasts until dismissed", () => {
+    const store = createToastStore();
+    store.show("Zero", { duration: 0 });
+    store.show("Infinite", { duration: Infinity });
+    store.show("Working", { type: "loading" });
+
+    vi.advanceTimersByTime(60_000);
+    expect(states(store)).toEqual(["toast-3:open", "toast-2:open", "toast-1:open"]);
+    expect(find(store, "toast-1")?.duration).toBe(Infinity);
+  });
+
+  it("dismisses one toast or all of them", () => {
+    const store = createToastStore();
+    const onDismiss = vi.fn();
+    store.show("A", { onDismiss });
+    store.show("B");
+    store.show("C");
+
+    store.dismiss("toast-1");
+    expect(onDismiss).toHaveBeenCalledWith(expect.objectContaining({ id: "toast-1" }));
+    expect(states(store)).toEqual(["toast-3:open", "toast-2:open", "toast-1:closing"]);
+
+    store.dismiss();
+    vi.advanceTimersByTime(200);
+    expect(states(store)).toEqual([]);
+  });
+
+  it("holds the remaining time while paused", () => {
+    const store = createToastStore();
+    store.show("Saved");
+
+    vi.advanceTimersByTime(3000);
+    store.pause();
+    vi.advanceTimersByTime(10_000);
+    expect(states(store)).toEqual(["toast-1:open"]);
+
+    store.resume();
+    vi.advanceTimersByTime(1999);
+    expect(states(store)).toEqual(["toast-1:open"]);
+    vi.advanceTimersByTime(1);
+    expect(states(store)).toEqual(["toast-1:closing"]);
+  });
+
+  it("queues toasts beyond the limit with their full time", () => {
+    const store = createToastStore({ limit: 3 });
+    for (const title of ["A", "B", "C", "D"]) store.show(title);
+
+    expect(visibleToasts(store.getSnapshot()).map((item) => item.title)).toEqual(["D", "C", "B"]);
+
+    // B, C and D run out; A only starts counting once it gets a slot.
+    vi.advanceTimersByTime(5000);
+    expect(find(store, "toast-1")?.state).toBe("open");
+    expect(visibleToasts(store.getSnapshot()).map((item) => item.title)).toEqual([
+      "D",
+      "C",
+      "B",
+      "A",
+    ]);
+    vi.advanceTimersByTime(4999);
+    expect(find(store, "toast-1")?.state).toBe("open");
+    vi.advanceTimersByTime(1);
+    expect(find(store, "toast-1")?.state).toBe("closing");
+  });
+});
+
+describe("updates", () => {
+  it("gives a loading toast a normal duration once its type changes", () => {
+    const store = createToastStore();
+    const id = store.show("Uploading", { type: "loading" });
+
+    store.update(id, { description: "40%" });
+    expect(find(store, id)).toMatchObject({ duration: Infinity, description: "40%", version: 2 });
+
+    store.update(id, { type: "success", title: "Uploaded" });
+    expect(find(store, id)).toMatchObject({ type: "success", title: "Uploaded", duration: 5000 });
+    vi.advanceTimersByTime(5000);
+    expect(find(store, id)?.state).toBe("closing");
+  });
+
+  it("ignores ids that are not open", () => {
+    const store = createToastStore();
+    store.update("missing", { title: "Nope" });
+    expect(states(store)).toEqual([]);
+  });
+
+  it("applies a new limit and notifies subscribers", () => {
+    const store = createToastStore();
+    const listener = vi.fn();
+    store.subscribe(listener);
+
+    store.configure({ limit: 1, duration: undefined });
+    expect(store.getSnapshot().limit).toBe(1);
+    expect(listener).toHaveBeenCalledOnce();
+
+    store.pause();
+    store.pause();
+    expect(listener).toHaveBeenCalledTimes(2);
+  });
+
+  it("keeps the same snapshot object until something changes", () => {
+    const store = createToastStore();
+    const before = store.getSnapshot();
+    expect(store.getSnapshot()).toBe(before);
+    store.show("Hi");
+    expect(store.getSnapshot()).not.toBe(before);
+  });
+});
+
+describe("toast api", () => {
+  it("sets the type from the shortcut used", () => {
+    const store = createToastStore();
+    const api = createToastApi(store);
+    api.success("Saved");
+    api.warning("Low disk");
+    api.custom(({ id }) => id);
+
+    const [custom, warning, success] = store.getSnapshot().toasts;
+    expect(success.type).toBe("success");
+    expect(warning.type).toBe("warning");
+    expect(typeof custom.render).toBe("function");
+  });
+
+  it("turns a promise into a success toast", async () => {
+    const store = createToastStore();
+    const api = createToastApi(store);
+    const result = api.promise(Promise.resolve(42), {
+      loading: "Saving",
+      success: (value) => `Saved ${value}`,
+      error: "Failed",
+    });
+
+    expect(store.getSnapshot().toasts[0]).toMatchObject({ type: "loading", title: "Saving" });
+    await expect(result).resolves.toBe(42);
+    expect(store.getSnapshot().toasts[0]).toMatchObject({ type: "success", title: "Saved 42" });
+  });
+
+  it("turns a rejected promise into an error toast and still rejects", async () => {
+    const store = createToastStore();
+    const api = createToastApi(store);
+    const result = api.promise(() => Promise.reject(new Error("Network down")), {
+      loading: "Saving",
+      error: (error) => (error as Error).message,
+    });
+
+    await expect(result).rejects.toThrow("Network down");
+    expect(store.getSnapshot().toasts[0]).toMatchObject({ type: "error", title: "Network down" });
+  });
+
+  it("closes quietly when a promise message is left out", async () => {
+    const store = createToastStore();
+    const api = createToastApi(store);
+    await api.promise(Promise.resolve("ok"), { loading: "Checking" });
+    expect(states(store)).toEqual(["toast-1:closing"]);
+  });
+
+  it("does nothing where a toast cannot be shown", async () => {
+    const store = createToastStore();
+    const api = createToastApi(store, () => false);
+    expect(api("Hidden")).toBe("");
+    expect(api.success("Hidden", { id: "kept" })).toBe("kept");
+    await expect(api.promise(Promise.resolve(1), { loading: "…" })).resolves.toBe(1);
+    expect(states(store)).toEqual([]);
+  });
+
+  it("ignores the default toast() on a server, where there is no document", () => {
+    expect(typeof document).toBe("undefined");
+    expect(toast("Rendered on the server")).toBe("");
+    expect(toastStore.getSnapshot().toasts).toHaveLength(0);
+  });
+});

package/source/beta-components/toaster/core/api.ts

@@ -0,0 +1,87 @@
+import type { ReactNode } from "react";
+import type { ToastPatch, ToastStore } from "./store";
+import type { ToastOptions, ToastRenderProps, ToastType } from "./types";
+
+type TypedOptions = Omit<ToastOptions, "type">;
+type Message<T> = ReactNode | ((value: T) => ReactNode);
+
+export interface PromiseMessages<T> {
+  loading: ReactNode;
+  /** Omit to close the toast quietly on success. */
+  success?: Message<T>;
+  /** Omit to close the toast quietly on failure. */
+  error?: Message<unknown>;
+}
+
+export interface ToastApi {
+  (title: ReactNode, options?: ToastOptions): string;
+  success(title: ReactNode, options?: TypedOptions): string;
+  error(title: ReactNode, options?: TypedOptions): string;
+  warning(title: ReactNode, options?: TypedOptions): string;
+  info(title: ReactNode, options?: TypedOptions): string;
+  /** Stays until updated or dismissed. */
+  loading(title: ReactNode, options?: TypedOptions): string;
+  custom(
+    render: (props: ToastRenderProps) => ReactNode,
+    options?: Omit<TypedOptions, "render">,
+  ): string;
+  /** Shows a loading toast, then turns it into a success or error. Returns the same promise. */
+  promise<T>(
+    input: Promise<T> | (() => Promise<T>),
+    messages: PromiseMessages<T>,
+    options?: TypedOptions,
+  ): Promise<T>;
+  update(id: string, patch: ToastPatch): void;
+  dismiss(id?: string): void;
+}
+
+/**
+ * The `toast()` function for a store. `canShow` lets the default instance ignore
+ * calls made where nobody can see them, such as during a server render.
+ */
+export function createToastApi(store: ToastStore, canShow: () => boolean = () => true): ToastApi {
+  const show = (title: ReactNode, options?: ToastOptions) =>
+    canShow() ? store.show(title, options) : (options?.id ?? "");
+
+  const typed = (type: ToastType) => (title: ReactNode, options?: TypedOptions) =>
+    show(title, { ...options, type });
+
+  function promise<T>(
+    input: Promise<T> | (() => Promise<T>),
+    messages: PromiseMessages<T>,
+    options?: TypedOptions,
+  ): Promise<T> {
+    const pending = typeof input === "function" ? input() : input;
+    if (!canShow()) return pending;
+
+    const id = store.show(messages.loading, { ...options, type: "loading" });
+
+    function settle<V>(type: "success" | "error", message: Message<V> | undefined, value: V) {
+      if (message === undefined) store.dismiss(id);
+      else store.update(id, { type, title: typeof message === "function" ? message(value) : message });
+    }
+
+    // Handling the rejection here also stops it being reported as unhandled when
+    // the caller doesn't await the returned promise.
+    pending.then(
+      (value) => settle("success", messages.success, value),
+      (error: unknown) => settle("error", messages.error, error),
+    );
+    return pending;
+  }
+
+  return Object.assign(show, {
+    success: typed("success"),
+    error: typed("error"),
+    warning: typed("warning"),
+    info: typed("info"),
+    loading: typed("loading"),
+    custom: (
+      render: (props: ToastRenderProps) => ReactNode,
+      options?: Omit<TypedOptions, "render">,
+    ) => show(null, { ...options, render }),
+    promise,
+    update: (id: string, patch: ToastPatch) => store.update(id, patch),
+    dismiss: (id?: string) => store.dismiss(id),
+  });
+}

package/source/beta-components/toaster/core/index.ts

@@ -0,0 +1,14 @@
+// Framework-free: the store, the timers and the `toast()` API run without
+// React, so they can be called from a data layer and tested on their own.
+export { createToastApi } from "./api";
+export type { PromiseMessages, ToastApi } from "./api";
+export {
+  createToastStore,
+  DEFAULT_DURATION,
+  DEFAULT_LIMIT,
+  EXIT_DURATION,
+  visibleToasts,
+} from "./store";
+export type { ToastPatch, ToastStore, ToastStoreConfig } from "./store";
+export { toast, toastStore } from "./toast";
+export type * from "./types";