@boxcustodia/library 2.0.0-alpha.19 → 2.0.0-alpha.20

package/src/hooks/use-async/use-async.stories.tsx

@@ -1,148 +1,272 @@
-import { Meta, StoryObj } from "@storybook/react-vite";
-import { ChevronLeft, ChevronRight } from "lucide-react";
+import type { Meta, StoryObj } from "@storybook/react-vite";
 import { useState } from "react";
-import { Button, createToastManager, Input } from "../../components";
-import { LibraryProvider } from "../../providers/library-provider";
-import { useDebouncedValue } from "../use-debounce-value/use-debounced-value";
-import { useAsync } from "../use-async";
+import { Button } from "../../components";
+import { useAsync } from "./use-async";
 
-const toastManager = createToastManager();
+// ─── Types ─────────────────────────────────────────────────────────────────────
 
-const meta: Meta = {
+interface DemoData {
+  message: string;
+  timestamp: string;
+}
+
+// ─── Demo component ────────────────────────────────────────────────────────────
+
+type AsyncDemoProps = {
+  /** Simulated async delay in ms */
+  delay?: number;
+  /** When true the demo's fn rejects with a simulated error */
+  shouldFail?: boolean;
+  enabled?: boolean;
+  keepPreviousData?: boolean;
+  onSuccess?: (data: DemoData) => void;
+  onError?: (error: Error) => void;
+  onSettled?: (data: DemoData | null, error: Error | null) => void;
+};
+
+const AsyncDemo = ({
+  delay = 800,
+  shouldFail = false,
+  enabled = true,
+  keepPreviousData = false,
+  onSuccess,
+  onError,
+  onSettled,
+}: AsyncDemoProps) => {
+  const [log, setLog] = useState<string[]>([]);
+
+  const addLog = (msg: string) =>
+    setLog((prev) => [
+      `[${new Date().toISOString().slice(11, 23)}] ${msg}`,
+      ...prev,
+    ]);
+
+  const { status, data, error, loading, refetch } = useAsync<DemoData>({
+    fn: async (signal) => {
+      await new Promise<void>((res, rej) => {
+        const timer = setTimeout(() => {
+          if (shouldFail) rej(new Error("Simulated failure"));
+          else res();
+        }, delay);
+        signal.addEventListener("abort", () => clearTimeout(timer));
+      });
+      return {
+        message: "Data loaded successfully",
+        timestamp: new Date().toLocaleTimeString(),
+      };
+    },
+    enabled,
+    keepPreviousData,
+    onSuccess: (d) => {
+      addLog(`onSuccess — ${d.message} at ${d.timestamp}`);
+      onSuccess?.(d);
+    },
+    onError: (e) => {
+      addLog(`onError — ${e.message}`);
+      onError?.(e);
+    },
+    onSettled: (d, e) => {
+      addLog(
+        `onSettled — data: ${d ? d.timestamp : "null"}, error: ${e?.message ?? "null"}`,
+      );
+      onSettled?.(d, e);
+    },
+  });
+
+  return (
+    <div className="flex flex-col gap-4 max-w-sm">
+      <Button variant="outline" onClick={refetch} disabled={loading}>
+        {loading ? "Loading…" : "Refetch"}
+      </Button>
+
+      <pre className="rounded-md bg-slate-950 p-3 text-xs text-white leading-relaxed">
+        {JSON.stringify(
+          {
+            status,
+            loading,
+            data,
+            error: error?.message ?? null,
+          },
+          null,
+          2,
+        )}
+      </pre>
+
+      {log.length > 0 && (
+        <div className="rounded-md border bg-muted p-3 text-xs font-mono space-y-0.5">
+          {log.map((entry, i) => (
+            // biome-ignore lint/suspicious/noArrayIndexKey: log is append-only
+            <div key={i}>{entry}</div>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+};
+
+// ─── Meta ─────────────────────────────────────────────────────────────────────
+
+const meta: Meta<typeof AsyncDemo> = {
   title: "hooks/useAsync",
+  component: AsyncDemo,
+  parameters: {
+    docs: {
+      description: {
+        component: `
+\`useAsync\` runs an async function automatically when its \`deps\` change.
+
+**API summary**
+
+\`\`\`ts
+const { data, error, status, loading, isIdle, isSuccess, isError, refetch } =
+  useAsync({ fn, deps?, enabled?, keepPreviousData?, onSuccess?, onError?, onSettled? });
+\`\`\`
+
+**Key behaviors**
+- \`fn(signal)\` receives an \`AbortSignal\` — pass it to \`fetch\` to cancel in-flight requests on cleanup.
+- Runs on mount (when \`enabled: true\`) and re-runs whenever \`deps\` change.
+- Race-safe: if \`deps\` change before \`fn\` resolves, the stale response is silently discarded.
+- \`enabled: false\` keeps the hook in \`'idle'\` state — no request fires until \`enabled\` becomes \`true\`.
+- \`keepPreviousData: true\` retains the last resolved \`data\` while a new request is in-flight.
+- \`refetch()\` manually re-triggers without changing deps. Stable reference across renders.
+- All callbacks read through \`useLatestRef\` — inline functions never cause re-subscriptions.
+        `.trim(),
+      },
+    },
+  },
+  argTypes: {
+    delay: {
+      control: { type: "range", min: 0, max: 3000, step: 100 },
+      description:
+        "Simulated async delay in ms. Demo control only — not a hook option.",
+      table: { category: "Demo controls" },
+    },
+    shouldFail: {
+      control: "boolean",
+      description:
+        "When true the demo's fn rejects. Toggle then click Refetch to see the error state.",
+      table: { category: "Demo controls" },
+    },
+    enabled: {
+      control: "boolean",
+      description:
+        "When false the hook stays idle and no request fires. Set to true to trigger the first run.",
+      table: {
+        category: "Hook options",
+        type: { summary: "boolean" },
+        defaultValue: { summary: "true" },
+      },
+    },
+    keepPreviousData: {
+      control: "boolean",
+      description:
+        "When true, `data` is preserved while a new request is in-flight instead of being reset to null.",
+      table: {
+        category: "Hook options",
+        type: { summary: "boolean" },
+        defaultValue: { summary: "false" },
+      },
+    },
+    onSuccess: {
+      action: "onSuccess",
+      description: "Called with `data` after `fn` resolves successfully.",
+      table: {
+        category: "Hook options",
+        type: { summary: "(data: T) => void" },
+      },
+    },
+    onError: {
+      action: "onError",
+      description:
+        "Called with the thrown `Error` when `fn` rejects. Abort errors are swallowed and never reach this callback.",
+      table: {
+        category: "Hook options",
+        type: { summary: "(error: Error) => void" },
+      },
+    },
+    onSettled: {
+      action: "onSettled",
+      description:
+        "Always called after `fn` settles — regardless of success or failure.",
+      table: {
+        category: "Hook options",
+        type: { summary: "(data: T | null, error: Error | null) => void" },
+      },
+    },
+  },
+  render: (args) => <AsyncDemo {...args} />,
 };
 
 export default meta;
-type Story = StoryObj;
+type Story = StoryObj<typeof AsyncDemo>;
 
-const fetchPokemon = async (name: string) => {
-  if (!name) throw new Error("Name is required");
-  const response = await fetch(`https://pokeapi.co/api/v2/pokemon/${name}`);
-  if (!response.ok) throw new Error("Pokemon not found");
-  return response.json();
-};
+// ─── Stories ──────────────────────────────────────────────────────────────────
 
-export const Basic = {
-  render: () => {
-    const [pokemonName, setPokemonName] = useState<string>("pikachu");
-    const debouncedName = useDebouncedValue(pokemonName, 600);
-    const { loading, error, data } = useAsync({
-      fn: () => fetchPokemon(debouncedName),
-      dependencies: [debouncedName],
-    });
-
-    return (
-      <div className="space-y-4">
-        <Input
-          type="text"
-          value={pokemonName}
-          onValueChange={setPokemonName}
-          placeholder="Enter Pokémon name"
-        />
-        {loading && <p>Loading...</p>}
-        {error && <p>Error: {error.message}</p>}
-        {data && (
-          <div className="border w-fit mx-auto rounded-lg bg-muted">
-            <h3 className="capitalize text-center font-semibold">
-              {data.name}
-            </h3>
-            <img src={data.sprites.front_default} alt={data.name} />
-          </div>
-        )}
-      </div>
-    );
+export const Default: Story = {
+  args: {
+    delay: 800,
+    shouldFail: false,
+    enabled: true,
+    keepPreviousData: false,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Runs on mount, transitions through `pending` → `success`, then populates `data`. Click **Refetch** to re-trigger manually. Toggle **shouldFail** in controls then refetch to see the error path.",
+      },
+    },
   },
 };
 
-const fetchPokemonById = async (id: number) => {
-  if (id === undefined) throw new Error("id is required");
-  const response = await fetch(`https://pokeapi.co/api/v2/pokemon/${id}`);
-  if (!response.ok) throw new Error("Pokemon not found");
-  return response.json();
+export const ErrorState: Story = {
+  name: "Error",
+  args: {
+    delay: 600,
+    shouldFail: true,
+    enabled: true,
+    keepPreviousData: false,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "`fn` rejects immediately — `status` becomes `'error'`, `error` is populated, and `data` stays null. `onError` and `onSettled` both fire. Toggle **shouldFail** off then click Refetch to recover.",
+      },
+    },
+  },
 };
 
-/**
- * ```tsx
- * interface UseAsyncOptions<T> {
- *  onError?: (error: Error) => void;
- *  onSuccess?: (data: T) => void;
- *  onFinish?: () => void;
- * }
- * ```
- */
-
-export const Advanced: Story = {
-  decorators: [
-    (Story) => (
-      <LibraryProvider>
-        <Story />
-      </LibraryProvider>
-    ),
-  ],
-  render: () => {
-    const [pokemonId, setPokemonId] = useState<number>(1);
-    const [log, setLog] = useState<string[]>([]);
-
-    const handleSuccess = (data: any) => {
-      setLog((prevLog) => [...prevLog, `✅ Fetched Pokémon: ${data.name}`]);
-    };
-
-    const handleError = (error: Error) => {
-      toastManager.add({ variant: "error", description: error.message });
-      setLog((prevLog) => [...prevLog, `❌ Error: ${error.message}`]);
-    };
-
-    const handleSettled = () => {
-      setLog((prevLog) => [...prevLog, `🏁 Request settled`]);
-    };
-
-    const { loading, error, data } = useAsync({
-      fn: () => fetchPokemonById(pokemonId),
-      dependencies: [pokemonId],
-      onSuccess: handleSuccess,
-      onError: handleError,
-      onFinish: handleSettled,
-    });
-
-    return (
-      <div className="p-4">
-        <div className="flex justify-center items-center gap-x-4">
-          <Button
-            size="icon"
-            variant="ghost"
-            onClick={() => setPokemonId(pokemonId - 1)}
-          >
-            <ChevronLeft />
-          </Button>
-          <div className="font-bold">{pokemonId}</div>
-          <Button
-            size="icon"
-            variant="ghost"
-            onClick={() => setPokemonId(pokemonId + 1)}
-          >
-            <ChevronRight />
-          </Button>
-        </div>
+export const WithEnabled: Story = {
+  args: {
+    delay: 800,
+    shouldFail: false,
+    enabled: false,
+    keepPreviousData: false,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Starts with `enabled: false` — the hook is in `'idle'` state and no request fires. Flip **enabled** to true in controls to trigger the first run.",
+      },
+    },
+  },
+};
 
-        {loading && <p>Loading...</p>}
-        {error && <p>Error: {error.message}</p>}
-        {data && (
-          <div className="border w-fit mx-auto rounded-lg bg-muted">
-            <h3 className="capitalize text-center font-semibold">
-              {data.name}
-            </h3>
-            <img src={data.sprites.front_default} alt={data.name} />
-          </div>
-        )}
-        <div className="mt-4">
-          <h4 className="font-semibold">Log:</h4>
-          <ul className="list-disc">
-            {log.map((entry, index) => (
-              <li key={index}>{entry}</li>
-            ))}
-          </ul>
-        </div>
-      </div>
-    );
+export const WithKeepPreviousData: Story = {
+  args: {
+    delay: 1500,
+    shouldFail: false,
+    enabled: true,
+    keepPreviousData: true,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "With `keepPreviousData: true`, the previous `data` stays visible while the next request is in-flight (`status: 'pending'`). Click **Refetch** to see stale data persist during the 1.5 s delay.",
+      },
+    },
   },
 };