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

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

@@ -1,111 +1,277 @@
-import { Meta } from "@storybook/react-vite";
-import { FormEvent } from "react";
-import { Button, Input } from "../../components";
-import { getFormData } from "../../utils";
-import { useAsync } from "../use-async/use-async";
-import { useMutation } from "../use-mutation";
-
-/**
- * El hook `useMutation` permite manejar operaciones de mutación asincrónicas, proporcionando estados de carga, error y éxito.
- *
- * Opciones de configuración:
- * - `fn`: La función de mutación que se ejecutará.
- * - `onError`: Callback opcional que se llama cuando ocurre un error.
- * - `onSuccess`: Callback opcional que se llama cuando la mutación es exitosa.
- * - `onFinish`: Callback opcional que se llama cuando la mutación termina, sin importar si tuvo éxito o error. Es útil para hacer un `refetch` (de `useAsync`)
- *
- * Devuelve un objeto con las siguientes propiedades:
- * - `mutate`: Función para ejecutar la mutación.
- * - `loading`: Indica si la mutación está en progreso.
- * - `error`: Contiene el error si la mutación falla.
- * - `data`: Contiene los datos si la mutación es exitosa.
- */
-
-const meta: Meta = {
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useState } from "react";
+import { Button } from "../../components";
+import { type UseMutationOptions, useMutation } from "./use-mutation";
+
+// ─── Demo component ──────────────────────────────────────────────────────────
+
+interface DemoVariables {
+  value: string;
+}
+
+interface DemoData {
+  message: string;
+  timestamp: number;
+}
+
+type MutationDemoProps = UseMutationOptions<DemoVariables, DemoData> & {
+  /** Simulated async delay in ms */
+  delay?: number;
+  /** When true the mutation will reject with an error */
+  shouldFail?: boolean;
+};
+
+const MutationDemo = ({
+  delay = 800,
+  shouldFail = false,
+  onMutate,
+  onSuccess,
+  onError,
+  onSettled,
+}: MutationDemoProps) => {
+  const [log, setLog] = useState<string[]>([]);
+
+  const addLog = (msg: string) =>
+    setLog((prev) => [
+      `[${new Date().toISOString().slice(11, 23)}] ${msg}`,
+      ...prev,
+    ]);
+
+  const mutation = useMutation<DemoVariables, DemoData>({
+    fn: async (vars) => {
+      await new Promise((res, rej) =>
+        setTimeout(
+          () =>
+            shouldFail ? rej(new Error("Simulated failure")) : res(undefined),
+          delay,
+        ),
+      );
+      return { message: `Created: ${vars.value}`, timestamp: Date.now() };
+    },
+    onMutate: (vars) => {
+      addLog(`onMutate — vars: ${JSON.stringify(vars)}`);
+      onMutate?.(vars);
+    },
+    onSuccess: (data, vars) => {
+      addLog(`onSuccess — data: ${data.message}`);
+      onSuccess?.(data, vars);
+    },
+    onError: (err, vars) => {
+      addLog(`onError — ${err.message}`);
+      onError?.(err, vars);
+    },
+    onSettled: (data, err, vars) => {
+      addLog(
+        `onSettled — data: ${data?.message ?? "null"}, error: ${err?.message ?? "null"}`,
+      );
+      onSettled?.(data, err, vars);
+    },
+  });
+
+  return (
+    <div className="flex flex-col gap-4 max-w-sm">
+      <div className="flex gap-2">
+        <Button
+          onClick={() => mutation.mutate({ value: "item-1" })}
+          disabled={mutation.isPending}
+        >
+          {mutation.isPending ? "Running…" : "Mutate"}
+        </Button>
+        <Button
+          variant="outline"
+          onClick={() => mutation.reset()}
+          disabled={mutation.isPending}
+        >
+          Reset
+        </Button>
+      </div>
+
+      <pre className="rounded-md bg-slate-950 p-3 text-xs text-white leading-relaxed">
+        {JSON.stringify(
+          {
+            status: mutation.status,
+            data: mutation.data,
+            error: mutation.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) => (
+            <div key={i}>{entry}</div>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+};
+
+// ─── Meta ─────────────────────────────────────────────────────────────────────
+
+const meta: Meta<typeof MutationDemo> = {
   title: "hooks/useMutation",
+  component: MutationDemo,
   parameters: {
     docs: {
-      source: { type: "code" },
+      description: {
+        component: `
+\`useMutation\` manages async mutation lifecycle with stable callback identity.
+
+**API summary**
+
+\`\`\`ts
+const { mutate, mutateAsync, reset, status, data, error, isPending, isSuccess, isError, isIdle } =
+  useMutation({ fn, onMutate?, onSuccess?, onError?, onSettled? });
+\`\`\`
+
+**Lifecycle order (success):** \`onMutate\` → \`fn\` → \`onSuccess\` → \`onSettled\`
+
+**Lifecycle order (error):** \`onMutate\` → \`fn\` throws → \`onError\` → \`onSettled\`
+
+**Key guarantees**
+- \`mutate\` is fire-and-forget: returns \`void\`, never throws.
+- \`mutateAsync\` returns a \`Promise\` that re-throws on failure.
+- \`onSettled\` is always called — even if \`onError\` throws.
+- All callbacks read through \`useLatestRef\`, so inline functions never recreate \`mutate\`.
+        `.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 — simulates an API error. Demo control only, not a hook option.",
+      table: { category: "Demo controls" },
+    },
+    onMutate: {
+      action: "onMutate",
+      description:
+        "Called synchronously with `variables` before `fn` is awaited. Use for optimistic updates.",
+      table: {
+        category: "Hook options",
+        type: { summary: "(variables: TVariables) => void" },
+      },
+    },
+    onSuccess: {
+      action: "onSuccess",
+      description:
+        "Called with `(data, variables)` after `fn` resolves successfully.",
+      table: {
+        category: "Hook options",
+        type: { summary: "(data: TData, variables: TVariables) => void" },
+      },
+    },
+    onError: {
+      action: "onError",
+      description: "Called with `(error, variables)` when `fn` rejects.",
+      table: {
+        category: "Hook options",
+        type: { summary: "(error: Error, variables: TVariables) => void" },
+      },
+    },
+    onSettled: {
+      action: "onSettled",
+      description:
+        "Always called after `onSuccess` or `onError`, even if one of them throws.",
+      table: {
+        category: "Hook options",
+        type: {
+          summary:
+            "(data: TData | null, error: Error | null, variables: TVariables) => void",
+        },
+      },
+    },
+  },
+  render: (args) => <MutationDemo {...args} />,
 };
 
 export default meta;
+type Story = StoryObj<typeof MutationDemo>;
 
-interface FakeTodo {
-  userId: number;
-  id: number;
-  title: string;
-  completed: boolean;
-}
+// ─── Stories ──────────────────────────────────────────────────────────────────
 
-const fetchTodos = async (): Promise<FakeTodo> => {
-  const response = fetch("https://jsonplaceholder.typicode.com/todos/1").then(
-    (response) => response.json(),
-  );
-  if (!response) throw new Error("Todo not found");
-  return response;
+export const Idle: Story = {
+  args: {
+    delay: 800,
+    shouldFail: false,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Default idle state before any mutation is triggered. All booleans are false except `isIdle`.",
+      },
+    },
+  },
 };
 
-const createTodo = async (title: string): Promise<FakeTodo> => {
-  if (!title) throw new Error("Title is required");
-  return await fetch("https://jsonplaceholder.typicode.com/posts", {
-    method: "POST",
-    body: JSON.stringify({
-      title: title,
-      body: "bar",
-      userId: 1,
-    }),
-    headers: {
-      "Content-type": "application/json; charset=UTF-8",
-    },
-  })
-    .then((response) => response.json())
-    .then((json) => json);
+export const Pending: Story = {
+  args: {
+    delay: 3000,
+    shouldFail: false,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Click **Mutate** to see `isPending=true` while the operation runs. The button disables until the promise settles.",
+      },
+    },
+  },
 };
 
-const Result = ({ loading = false, data = null, error = null }: any) => (
-  <pre className="rounded-md bg-slate-950 p-4 text-white mt-2">
-    {JSON.stringify(
-      {
-        loading,
-        error,
-        data,
+export const Success: Story = {
+  args: {
+    delay: 600,
+    shouldFail: false,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "After the mutation resolves, `status` becomes `'success'` and `data` is populated. `error` remains null.",
       },
-      undefined,
-      2,
-    )}
-  </pre>
-);
-
-export const Form = {
-  render: () => {
-    const { refetch } = useAsync<FakeTodo>({
-      fn: fetchTodos,
-    });
-
-    const { mutate, loading, data, error } = useMutation({
-      fn: createTodo,
-      onFinish: () => refetch(),
-    });
-
-    const handleSubmit = (event: FormEvent<HTMLFormElement>) => {
-      event.preventDefault();
-      const data = getFormData(event);
-      if ("title" in data) mutate(data.title);
-    };
-
-    return (
-      <div>
-        <form className="space-y-2" onSubmit={handleSubmit}>
-          <Input placeholder="title" name="title" autoComplete="0" />
-          <Button type="submit" loading={loading}>
-            Enviar
-          </Button>
-        </form>
-
-        <Result loading={loading} data={data} error={error?.message} />
-      </div>
-    );
+    },
+  },
+};
+
+export const ErrorState: Story = {
+  name: "Error",
+  args: {
+    delay: 600,
+    shouldFail: true,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Toggle **shouldFail** in controls to simulate a failing API call. `status` becomes `'error'`, `error` is set, and `data` stays null. `mutate` swallows the rejection silently — use `mutateAsync` if you need to catch it.",
+      },
+    },
+  },
+};
+
+export const ResetAfterSuccess: Story = {
+  args: {
+    delay: 600,
+    shouldFail: false,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "After a successful mutation, click **Reset** to return to `idle` and clear `data`. `reset()` does not abort in-flight mutations — it only clears state.",
+      },
+    },
   },
 };