@boxcustodia/library 2.0.0-alpha.2 → 2.0.0-alpha.21

package/src/components/toast/toast.stories.tsx

@@ -0,0 +1,393 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { LibraryProvider } from "../../providers";
+import { Button } from "../button";
+import {
+  createToastManager,
+  ToastProvider,
+  toast,
+  useToastManager,
+} from "./toast";
+
+/**
+ * Imperative toast notification system built on `@base-ui/react/toast`.
+ * Toasts stack in the bottom-right corner with enter/exit animations,
+ * swipe-to-dismiss, and expand-on-hover.
+ *
+ * ## Usage
+ *
+ * Call `toast` or `toast.*` from anywhere — components, services, stores, event handlers.
+ * A `string` renders as the prominent title; an object accepts:
+ *
+ * | Prop | Type | Description |
+ * |------|------|-------------|
+ * | `variant` | `"default" \| "success" \| "error" \| "warning" \| "info"` | Color and icon |
+ * | `title` | `string` | Primary text (`font-medium`) |
+ * | `description` | `string \| ReactNode` | Secondary text (muted) |
+ * | `content` | `ReactNode` | Replaces the entire toast layout |
+ * | `actions` | `ButtonProps[]` | Action buttons below the message |
+ * | `id` | `string` | Stable ID — prevents duplicates, triggers bump animation |
+ * | `timeout` | `number \| null` | Duration in ms. `null` = persistent |
+ *
+ * ```ts
+ * toast("Notification");                    // default — no variant or color
+ * toast.success("Changes saved");
+ * toast.error("Something went wrong");
+ * toast.warning({ title: "Warning", description: "File exceeds maximum size" });
+ * toast.info("Update available");
+ *
+ * toast.promise(saveData(), {
+ *   loading: { description: "Saving..." },
+ *   success: () => ({ variant: "success", description: "Saved" }),
+ *   error:   (e) => ({ variant: "error",   description: e.message }),
+ * });
+ * ```
+ *
+ * ## Setup
+ *
+ * **Requires `<LibraryProvider>` at the app root.** It includes `ToastProvider` automatically — no
+ * extra wrapping needed:
+ *
+ * ```tsx
+ * // app.tsx
+ * import { LibraryProvider } from "@boxcustodia/library";
+ *
+ * export function App() {
+ *   return (
+ *     <LibraryProvider>
+ *       <Router />
+ *     </LibraryProvider>
+ *   );
+ * }
+ * ```
+ */
+const meta: Meta<typeof ToastProvider> = {
+  title: "Components/Toast",
+  component: ToastProvider,
+  parameters: { layout: "centered" },
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ─── Basic ────────────────────────────────────────────────────────────────────
+
+export const Default: Story = {
+  render: () => (
+    <Button
+      variant="outline"
+      onClick={() => toast("Notification without variant.")}
+    >
+      Default
+    </Button>
+  ),
+};
+
+export const TitleOnly: Story = {
+  render: () => (
+    <Button variant="outline" onClick={() => toast({ title: "Title only" })}>
+      Title only
+    </Button>
+  ),
+};
+
+export const DescriptionOnly: Story = {
+  render: () => (
+    <Button
+      variant="outline"
+      onClick={() => toast({ description: "Description only, no title." })}
+    >
+      Description only
+    </Button>
+  ),
+};
+
+// ─── Variants ─────────────────────────────────────────────────────────────────
+
+export const Success: Story = {
+  render: () => (
+    <Button
+      variant="outline"
+      onClick={() => toast.success("Changes saved successfully.")}
+    >
+      Success
+    </Button>
+  ),
+};
+
+export const Error: Story = {
+  render: () => (
+    <Button
+      variant="outline"
+      onClick={() => toast.error("Could not complete the operation.")}
+    >
+      Error
+    </Button>
+  ),
+};
+
+export const Warning: Story = {
+  render: () => (
+    <Button
+      variant="outline"
+      onClick={() =>
+        toast.warning({
+          title: "Warning",
+          description: "File exceeds the maximum allowed size.",
+        })
+      }
+    >
+      Warning
+    </Button>
+  ),
+};
+
+export const Info: Story = {
+  render: () => (
+    <Button
+      variant="outline"
+      onClick={() =>
+        toast.info({
+          title: "Update available",
+          description: "v2.4.0 is ready to install.",
+        })
+      }
+    >
+      Info
+    </Button>
+  ),
+};
+
+// ─── Composition ──────────────────────────────────────────────────────────────
+
+/**
+ * `content` replaces the entire toast layout — useful for custom layouts,
+ * image previews, or any arbitrary JSX inside the toast container.
+ */
+export const CustomContent: Story = {
+  render: () => (
+    <Button
+      variant="outline"
+      onClick={() =>
+        toast.info({
+          content: (
+            <div className="flex flex-col gap-1 pr-6">
+              <span className="text-[0.975rem] font-medium leading-5">
+                Custom layout
+              </span>
+              <span className="text-[0.925rem] leading-5 text-muted-foreground">
+                Any JSX can go inside the toast.
+              </span>
+              <code className="mt-1 rounded bg-muted px-1.5 py-0.5 text-xs">
+                content: ReactNode
+              </code>
+            </div>
+          ),
+        })
+      }
+    >
+      Custom content
+    </Button>
+  ),
+};
+
+/**
+ * `actions` renders buttons below the message. Accepts the same API as `<Button>`.
+ * Useful for inline confirmations without opening a dialog.
+ *
+ * To dismiss the toast from an action, capture the ID returned by `add()` and call `remove(id)`:
+ *
+ * ```tsx
+ * const { add, close } = useToastManager();
+ *
+ * let id: string;
+ * id = add({
+ *   variant: "warning",
+ *   title: "Unsaved changes",
+ *   actions: [
+ *     { children: "Discard", onClick: () => close(id) },
+ *     { children: "Save",    onClick: () => { save(); close(id); } },
+ *   ],
+ * });
+ * ```
+ */
+export const WithActions: Story = {
+  render: () => {
+    const { add, close } = useToastManager();
+    return (
+      <Button
+        variant="outline"
+        onClick={() => {
+          let id: string;
+          id = add({
+            variant: "warning",
+            title: "Unsaved changes",
+            description: "They will be lost if you leave this page.",
+            actions: [
+              {
+                children: "Discard",
+                variant: "outline",
+                size: "sm",
+                onClick: () => close(id),
+              },
+              {
+                children: "Save",
+                variant: "default",
+                size: "sm",
+                onClick: () => close(id),
+              },
+            ],
+          });
+        }}
+      >
+        With actions
+      </Button>
+    );
+  },
+};
+
+/**
+ * `toast.promise()` handles all three promise states automatically:
+ * shows a loading toast while pending, then transitions to success or error on settle.
+ */
+const Deferred = globalThis.Promise;
+const NativeError = globalThis.Error;
+
+const mockPurchaseSuccess = () =>
+  new Deferred<{ message: string }>((resolve) =>
+    setTimeout(
+      () =>
+        resolve({
+          message:
+            "Order #4821 confirmed. A summary has been sent to your email.",
+        }),
+      2000,
+    ),
+  );
+
+const mockPurchaseError = () =>
+  new Deferred<{ message: string }>((_, reject) =>
+    setTimeout(
+      () => reject(new NativeError("Insufficient funds on the card.")),
+      2000,
+    ),
+  );
+
+export const PromiseToast: Story = {
+  render: () => (
+    <div className="flex gap-2">
+      <Button
+        variant="outline"
+        onClick={() =>
+          toast.promise(mockPurchaseSuccess(), {
+            loading: { description: "Processing payment..." },
+            success: (data: any) => ({
+              variant: "success",
+              title: "Purchase complete",
+              description: data.message,
+            }),
+            error: (err: Error) => ({
+              variant: "error",
+              title: "Payment failed",
+              description: err.message,
+            }),
+          })
+        }
+      >
+        Confirm purchase
+      </Button>
+      <Button
+        variant="outline"
+        onClick={() =>
+          toast.promise(mockPurchaseError(), {
+            loading: { description: "Processing payment..." },
+            success: (data: any) => ({
+              variant: "success",
+              title: "Purchase complete",
+              description: data.message,
+            }),
+            error: (err: Error) => ({
+              variant: "error",
+              title: "Payment failed",
+              description: err.message,
+            }),
+          })
+        }
+      >
+        Pay (insufficient funds)
+      </Button>
+    </div>
+  ),
+};
+
+// ─── Advanced ─────────────────────────────────────────────────────────────────
+
+/**
+ * `useToastManager()` exposes the full manager inside a component.
+ * Useful when you need access to `update()`, `toasts[]`, or `promise()` with local state.
+ * For most cases, the `toast.*` singleton is enough.
+ */
+export const WithHook: Story = {
+  render: () => {
+    const { add, toasts } = useToastManager();
+    return (
+      <div className="flex items-center gap-3">
+        <Button
+          variant="outline"
+          onClick={() =>
+            add({
+              variant: "info",
+              title: "From the hook",
+              description:
+                "useToastManager() gives full access to the manager.",
+            })
+          }
+        >
+          Add toast
+        </Button>
+        <span className="text-sm text-muted-foreground">
+          {toasts.length} active
+        </span>
+      </div>
+    );
+  },
+};
+
+/**
+ * `createToastManager()` creates an isolated manager instance — useful in tests
+ * or microfrontends that need a separate toast stack from the global singleton.
+ *
+ * ```tsx
+ * const myManager = createToastManager();
+ *
+ * <ToastProvider toastManager={myManager}>
+ *   <App />
+ * </ToastProvider>
+ *
+ * myManager.add({ variant: "success", title: "Isolated instance" });
+ * ```
+ */
+const isolatedManager = createToastManager();
+
+export const IsolatedManager: Story = {
+  decorators: [
+    (Story) => (
+      <LibraryProvider toastManager={isolatedManager}>
+        <Story />
+      </LibraryProvider>
+    ),
+  ],
+  render: () => (
+    <Button
+      variant="outline"
+      onClick={() =>
+        isolatedManager.add({
+          variant: "info",
+          title: "Isolated manager",
+          description: "Independent instance from the global singleton.",
+        })
+      }
+    >
+      Trigger isolated
+    </Button>
+  ),
+};