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

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

@@ -1,97 +1,210 @@
-import { Meta } from "@storybook/react-vite";
+import type { Meta, StoryObj } from "@storybook/react-vite";
 import { Button } from "../../components";
 import { cn } from "../../lib";
-import { useStep } from "../use-step";
+import { useStep } from "./use-step";
+
+// ---------------------------------------------------------------------------
+// Meta
+// ---------------------------------------------------------------------------
 
 /**
- * Hook que recibe un array de elementos `T` y facita el manejo de vistas/formularios con múltiples pasos
+ * `useStep` manages a numeric step index with bounded navigation.
+ *
+ * It owns **position only** — consumers index their own data array with the
+ * returned `index`. Always starts at index 0. All action callbacks are
+ * referentially stable after mount.
+ *
+ * ```ts
+ * const [index, { next, back, goTo, reset, canGoNext, canGoBack, isFirstStep, isLastStep, progress }] =
+ *   useStep(4)
+ * ```
  */
 const meta: Meta = {
-  title: "hooks/useStep",
+  title: "Hooks/useStep",
   tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+\`useStep\` manages a numeric step index with bounded navigation.
+
+It owns **position only** — consumers index their own data array with the returned \`index\`.
+Always starts at index 0. All action callbacks (\`next\`, \`back\`, \`goTo\`, \`reset\`) are referentially stable after mount.
+
+\`\`\`ts
+const [index, { next, back, goTo, reset, canGoNext, canGoBack, isFirstStep, isLastStep, progress }] =
+  useStep(4)
+\`\`\`
+        `.trim(),
+      },
+    },
+  },
+  argTypes: {
+    count: {
+      control: { type: "number", min: 1, step: 1 },
+      description: "Total number of steps. Source of truth for boundaries.",
+      table: { defaultValue: { summary: "—" } },
+    },
+  },
+  args: {
+    count: 4,
+  },
 };
 
 export default meta;
 
-export const Default = {
-  render: () => {
-    const data = [
-      {
-        id: 1,
-        content: "🚌",
+type Story = StoryObj<typeof meta>;
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+// ── Default ───────────────────────────────────────────────────────────────────
+
+/**
+ * Basic uncontrolled usage. `useStep` starts at index 0. Back and Next buttons
+ * navigate through the steps; the current position is shown as "Step X of N".
+ */
+export const Default: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Basic uncontrolled usage. The hook starts at index 0 and manages its own state. Click Back / Next to navigate.",
       },
-      {
-        id: 2,
-        content: "🚗",
+    },
+  },
+  render: () => {
+    const [index, { next, back, isFirstStep, isLastStep }] = useStep(4);
+
+    return (
+      <div className="flex flex-col gap-4 w-72">
+        <div className="flex h-20 items-center justify-center rounded-lg border-2 border-dashed text-lg font-semibold">
+          Step {index + 1} of 4
+        </div>
+        <div className="flex gap-2">
+          <Button variant="outline" onClick={back} disabled={isFirstStep}>
+            Back
+          </Button>
+          <Button onClick={next} disabled={isLastStep}>
+            Next
+          </Button>
+        </div>
+      </div>
+    );
+  },
+};
+
+// ── WithProgress ──────────────────────────────────────────────────────────────
+
+/**
+ * Shows the `progress` ratio (0–1) as a visual progress bar.
+ * `progress` equals `index / (count - 1)` and is 0 when `count <= 1`.
+ */
+export const WithProgress: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "`progress` is a ratio in `[0, 1]` equal to `index / (count - 1)`. Drive a progress bar width directly: `progress * 100 + '%'`.",
       },
-      {
-        id: 3,
-        content: "🚕",
+    },
+  },
+  render: () => {
+    const [index, { next, back, progress, isFirstStep, isLastStep }] =
+      useStep(5);
+
+    return (
+      <div className="flex flex-col gap-4 w-72">
+        {/* Progress bar */}
+        <div className="w-full h-2 rounded-full bg-muted overflow-hidden">
+          <div
+            className="h-full rounded-full bg-primary transition-all duration-300"
+            style={{ width: `${progress * 100}%` }}
+          />
+        </div>
+        <p className="text-sm text-muted-foreground text-center">
+          Step {index + 1} of 5 — progress: {progress.toFixed(2)}
+        </p>
+        <div className="flex gap-2">
+          <Button variant="outline" onClick={back} disabled={isFirstStep}>
+            Back
+          </Button>
+          <Button onClick={next} disabled={isLastStep}>
+            Next
+          </Button>
+        </div>
+      </div>
+    );
+  },
+};
+
+// ── BoundaryBehavior ──────────────────────────────────────────────────────────
+
+/**
+ * Demonstrates `canGoNext` and `canGoBack` driving button disabled state, plus
+ * dot indicators calling `goTo(i)` to jump to a specific step directly.
+ */
+export const BoundaryBehavior: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "`canGoNext` and `canGoBack` are derived from `index` and `count`. Use them to disable navigation controls at the boundaries. Dot indicators call `goTo(i)` for direct jumps.",
       },
-    ];
-    const {
-      steps,
-      back,
-      next,
-      goTo,
-      step,
-      isLastStep,
-      isFirstStep,
-      currentStepIndex,
-    } = useStep(data);
+    },
+  },
+  render: () => {
+    const count = 5;
+    const [index, { next, back, goTo, canGoNext, canGoBack }] = useStep(count);
 
     return (
-      <div>
-        <div className="flex gap-x-12">
-          {data.map((transporte) => (
-            <div
-              key={transporte.id}
+      <div className="flex flex-col gap-4 w-72">
+        <div className="flex h-20 items-center justify-center rounded-lg border-2 border-dashed text-lg font-semibold">
+          Step {index + 1} of {count}
+        </div>
+
+        {/* Dot indicators */}
+        <div className="flex justify-center gap-2">
+          {Array.from({ length: count }, (_, i) => (
+            <button
+              key={i}
+              type="button"
+              onClick={() => goTo(i)}
               className={cn(
-                "bg-popover grow rounded text-center shadow p-14 text-3xl",
-                step.id === transporte.id && "bg-accent",
+                "h-3 w-3 rounded-full border-2 transition-colors",
+                i === index
+                  ? "bg-primary border-primary"
+                  : "bg-transparent border-muted-foreground hover:border-primary",
               )}
-            >
-              {transporte.content}
-            </div>
+              aria-label={`Go to step ${i + 1}`}
+            />
           ))}
         </div>
 
-        <div className="my-2 flex flex-wrap gap-2">
-          <Button onClick={back} disabled={isFirstStep}>
+        <div className="flex gap-2">
+          <Button variant="outline" onClick={back} disabled={!canGoBack}>
             Back
           </Button>
-          <Button onClick={next} disabled={isLastStep}>
+          <Button onClick={next} disabled={!canGoNext}>
             Next
           </Button>
-          <Button onClick={() => goTo(0)}>Go to first step</Button>
-          <Button onClick={() => goTo(1)}>Go to second step</Button>
-          <Button onClick={() => goTo(2)}>Go to third step</Button>
         </div>
 
-        <pre className="mt-2 rounded-md bg-slate-950 p-4 text-white">
-          <code className="block">
-            Steps: <span>{JSON.stringify(steps, null, 2)}</span>
-          </code>
-          <code className="block">Current step index: {currentStepIndex}</code>
-          <code className="block">
-            Current step:{" "}
-            <span className="text-blue-300">
-              {JSON.stringify(step, null, 2)}
-            </span>
-          </code>
-          <code className="block">
-            isFirstStep:{" "}
-            <span className={isFirstStep ? "text-green-500" : "text-red-500"}>
-              {JSON.stringify(isFirstStep)}
+        <div className="rounded-md bg-muted/40 px-3 py-2 text-xs font-mono space-y-1">
+          <p>
+            canGoBack:{" "}
+            <span className={canGoBack ? "text-green-600" : "text-red-500"}>
+              {String(canGoBack)}
             </span>
-          </code>
-          <code className="block">
-            isLastStep:{" "}
-            <span className={isLastStep ? "text-green-500" : "text-red-500"}>
-              {JSON.stringify(isLastStep)}
+          </p>
+          <p>
+            canGoNext:{" "}
+            <span className={canGoNext ? "text-green-600" : "text-red-500"}>
+              {String(canGoNext)}
             </span>
-          </code>
-        </pre>
+          </p>
+        </div>
       </div>
     );
   },

package/src/hooks/use-step/use-step.test.ts

@@ -1,73 +1,198 @@
 import { act, renderHook } from "@testing-library/react";
 import { describe, expect, it } from "vitest";
-import { useStep } from "../../hooks";
-
-describe("useStep hook", () => {
-  const steps = ["step1", "step2", "step3"];
-
-  it("starts at index 0 with isFirstStep=true", () => {
-    const { result } = renderHook(() => useStep(steps));
-    expect(result.current.currentStepIndex).toBe(0);
-    expect(result.current.step).toBe("step1");
-    expect(result.current.isFirstStep).toBe(true);
-    expect(result.current.isLastStep).toBe(false);
-    expect(result.current.steps).toBe(steps);
+import { useStep } from "../use-step";
+
+describe("useStep", () => {
+  // ── 1. Default start ──────────────────────────────────────────────────────
+  describe("default start", () => {
+    it("starts at index 0, isFirstStep true, isLastStep false", () => {
+      const { result } = renderHook(() => useStep(5));
+      const [index, { isFirstStep, isLastStep }] = result.current;
+      expect(index).toBe(0);
+      expect(isFirstStep).toBe(true);
+      expect(isLastStep).toBe(false);
+    });
   });
 
-  it("next advances to next step", () => {
-    const { result } = renderHook(() => useStep(steps));
-    act(() => result.current.next());
-    expect(result.current.currentStepIndex).toBe(1);
-    expect(result.current.step).toBe("step2");
-    expect(result.current.isFirstStep).toBe(false);
+  // ── 2. next() ─────────────────────────────────────────────────────────────
+  describe("next()", () => {
+    it("increments index when not at last step", async () => {
+      const { result } = renderHook(() => useStep(3));
+      await act(async () => {
+        result.current[1].next();
+      });
+      expect(result.current[0]).toBe(1);
+    });
+
+    it("is a no-op at the last step", async () => {
+      const { result } = renderHook(() => useStep(1));
+      await act(async () => {
+        result.current[1].next();
+      });
+      expect(result.current[0]).toBe(0);
+    });
   });
 
-  it("back returns to previous step", () => {
-    const { result } = renderHook(() => useStep(steps));
-    act(() => result.current.next());
-    act(() => result.current.back());
-    expect(result.current.currentStepIndex).toBe(0);
-    expect(result.current.isFirstStep).toBe(true);
+  // ── 3. back() ─────────────────────────────────────────────────────────────
+  describe("back()", () => {
+    it("decrements index when not at first step", async () => {
+      const { result } = renderHook(() => useStep(3));
+      await act(async () => {
+        result.current[1].goTo(1);
+      });
+      await act(async () => {
+        result.current[1].back();
+      });
+      expect(result.current[0]).toBe(0);
+    });
+
+    it("is a no-op at the first step", async () => {
+      const { result } = renderHook(() => useStep(3));
+      await act(async () => {
+        result.current[1].back();
+      });
+      expect(result.current[0]).toBe(0);
+    });
+  });
+
+  // ── 4. goTo() ─────────────────────────────────────────────────────────────
+  describe("goTo()", () => {
+    it("jumps to a valid index", async () => {
+      const { result } = renderHook(() => useStep(5));
+      await act(async () => {
+        result.current[1].goTo(3);
+      });
+      expect(result.current[0]).toBe(3);
+    });
+
+    it("clamps negative target to 0", async () => {
+      const { result } = renderHook(() => useStep(5));
+      await act(async () => {
+        result.current[1].goTo(-2);
+      });
+      expect(result.current[0]).toBe(0);
+    });
+
+    it("clamps over-bound target to count - 1", async () => {
+      const { result } = renderHook(() => useStep(5));
+      await act(async () => {
+        result.current[1].goTo(99);
+      });
+      expect(result.current[0]).toBe(4);
+    });
   });
 
-  it("next does not advance past last step", () => {
-    const { result } = renderHook(() => useStep(steps));
-    act(() => result.current.goTo(2));
-    expect(result.current.isLastStep).toBe(true);
-    act(() => result.current.next());
-    expect(result.current.currentStepIndex).toBe(2);
+  // ── 5. reset() ────────────────────────────────────────────────────────────
+  describe("reset()", () => {
+    it("returns to index 0", async () => {
+      const { result } = renderHook(() => useStep(5));
+      await act(async () => {
+        result.current[1].goTo(3);
+      });
+      await act(async () => {
+        result.current[1].reset();
+      });
+      expect(result.current[0]).toBe(0);
+    });
   });
 
-  it("back does not go before first step", () => {
-    const { result } = renderHook(() => useStep(steps));
-    act(() => result.current.back());
-    expect(result.current.currentStepIndex).toBe(0);
+  // ── 6. canGoNext / canGoBack ──────────────────────────────────────────────
+  describe("canGoNext / canGoBack", () => {
+    it("canGoNext is false and canGoBack is true at the last step", async () => {
+      const { result } = renderHook(() => useStep(3));
+      await act(async () => {
+        result.current[1].goTo(2);
+      });
+      const [, { canGoNext, canGoBack }] = result.current;
+      expect(canGoNext).toBe(false);
+      expect(canGoBack).toBe(true);
+    });
+
+    it("canGoBack is false and canGoNext is true at the first step", () => {
+      const { result } = renderHook(() => useStep(3));
+      const [, { canGoBack, canGoNext }] = result.current;
+      expect(canGoBack).toBe(false);
+      expect(canGoNext).toBe(true);
+    });
   });
 
-  it("goTo jumps to specified index", () => {
-    const { result } = renderHook(() => useStep(steps));
-    act(() => result.current.goTo(2));
-    expect(result.current.currentStepIndex).toBe(2);
-    expect(result.current.isLastStep).toBe(true);
+  // ── 7. progress ───────────────────────────────────────────────────────────
+  describe("progress", () => {
+    it("is 0.5 at the mid-step of a 5-step sequence", async () => {
+      const { result } = renderHook(() => useStep(5));
+      await act(async () => {
+        result.current[1].goTo(2);
+      });
+      expect(result.current[1].progress).toBe(0.5);
+    });
+
+    it("is 0 at the first step", () => {
+      const { result } = renderHook(() => useStep(5));
+      expect(result.current[1].progress).toBe(0);
+    });
+
+    it("is 1 at the last step", async () => {
+      const { result } = renderHook(() => useStep(5));
+      await act(async () => {
+        result.current[1].goTo(4);
+      });
+      expect(result.current[1].progress).toBe(1);
+    });
+
+    it("is 0 when count is 1", () => {
+      const { result } = renderHook(() => useStep(1));
+      expect(result.current[1].progress).toBe(0);
+    });
   });
 
-  it("findAndGo jumps to step matching predicate", () => {
-    const { result } = renderHook(() => useStep(steps));
-    act(() => result.current.findAndGo((s) => s === "step3"));
-    expect(result.current.currentStepIndex).toBe(2);
+  // ── 8. isFirstStep / isLastStep ───────────────────────────────────────────
+  describe("isFirstStep / isLastStep", () => {
+    it("isLastStep is true and isFirstStep is false at the last step", async () => {
+      const { result } = renderHook(() => useStep(3));
+      await act(async () => {
+        result.current[1].goTo(2);
+      });
+      const [, { isLastStep, isFirstStep }] = result.current;
+      expect(isLastStep).toBe(true);
+      expect(isFirstStep).toBe(false);
+    });
+
+    it("isFirstStep and isLastStep are both true when count is 1", () => {
+      const { result } = renderHook(() => useStep(1));
+      const [, { isFirstStep, isLastStep }] = result.current;
+      expect(isFirstStep).toBe(true);
+      expect(isLastStep).toBe(true);
+    });
   });
 
-  it("findAndGo does nothing when predicate matches nothing", () => {
-    const { result } = renderHook(() => useStep(steps));
-    act(() => result.current.findAndGo((s) => s === "nonexistent"));
-    expect(result.current.currentStepIndex).toBe(0);
+  // ── 9. Action reference stability ─────────────────────────────────────────
+  describe("action reference stability", () => {
+    it("next, back, goTo, and reset are the same references across re-renders", async () => {
+      const { result, rerender } = renderHook(() => useStep(3));
+      const [, { next, back, goTo, reset }] = result.current;
+
+      rerender();
+
+      expect(result.current[1].next).toBe(next);
+      expect(result.current[1].back).toBe(back);
+      expect(result.current[1].goTo).toBe(goTo);
+      expect(result.current[1].reset).toBe(reset);
+    });
   });
 
-  it("respects amountSteps override for boundary checks", () => {
-    const { result } = renderHook(() => useStep(steps, 2));
-    act(() => result.current.goTo(1));
-    expect(result.current.isLastStep).toBe(true);
-    act(() => result.current.next());
-    expect(result.current.currentStepIndex).toBe(1);
+  // ── 10. Cleanup on unmount ────────────────────────────────────────────────
+  describe("cleanup on unmount", () => {
+    it("does not throw after unmount when calling actions", async () => {
+      const { result, unmount } = renderHook(() => useStep(3));
+      unmount();
+      await act(async () => {
+        try {
+          result.current[1].next();
+        } catch {
+          // suppress unmount-related errors
+        }
+      });
+      // no assertion needed — test passes if no error is thrown
+    });
   });
 });

package/src/hooks/use-step/use-step.ts

@@ -1,55 +1,63 @@
-import { ReactNode, useState } from "react";
+import { useCallback, useState } from "react";
 
-interface Return<T = ReactNode> {
-  currentStepIndex: number;
-  step: T;
-  steps: T[];
-  isFirstStep: boolean;
-  isLastStep: boolean;
-  goTo: (i: number) => void;
+export interface UseStepActions {
+  /** Advance one step. No-op at the last step. Stable reference. */
   next: () => void;
+  /** Go back one step. No-op at the first step. Stable reference. */
   back: () => void;
-  findAndGo: (predicate: (item: T) => boolean) => void;
+  /** Jump to an index, clamped to [0, count - 1]. Stable reference. */
+  goTo: (index: number) => void;
+  /** Return to index 0. Stable reference. */
+  reset: () => void;
+  /** True when there is a next step to advance to. */
+  canGoNext: boolean;
+  /** True when there is a previous step to go back to. */
+  canGoBack: boolean;
+  /** True when the current index is the first step. */
+  isFirstStep: boolean;
+  /** True when the current index is the last step. */
+  isLastStep: boolean;
+  /** Ratio of progress in [0, 1]. 0 when count <= 1. */
+  progress: number;
 }
 
-export function useStep<T = ReactNode>(steps: T[], amountSteps?: number): Return<T> {
-  const [currentStepIndex, setCurrentStepIndex] = useState(0);
-  const length = amountSteps ?? steps.length;
-
-  const next = (): void => {
-    setCurrentStepIndex((i: number) => {
-      if (i >= length - 1) return i;
-      return i + 1;
-    });
-  };
-
-  const back = (): void => {
-    setCurrentStepIndex((i: number) => {
-      if (i <= 0) return i;
-      return i - 1;
-    });
-  };
-
-  const goTo = (i: number): void => {
-    setCurrentStepIndex(i);
-  };
-
-  const findAndGo = (predicate: (item: T) => boolean): void => {
-    const stepIndex = steps.findIndex(predicate);
-    if (stepIndex === -1) return;
-    goTo(stepIndex);
-  };
-
-  return {
-    currentStepIndex,
-    step: steps[currentStepIndex],
-    steps,
-    isFirstStep: currentStepIndex === 0,
-    isLastStep: currentStepIndex === length - 1,
-    goTo,
-    next,
-    back,
-    findAndGo,
-  };
+const clamp = (value: number, min: number, max: number) =>
+  Math.min(Math.max(value, min), max);
+
+export function useStep(count: number): [number, UseStepActions] {
+  const [index, setIndex] = useState(0);
+  const lastIndex = Math.max(count - 1, 0);
+  const currentIndex = clamp(index, 0, lastIndex);
+
+  const next = useCallback(
+    () => setIndex((i) => Math.min(i + 1, lastIndex)),
+    [lastIndex],
+  );
+
+  const back = useCallback(() => setIndex((i) => Math.max(i - 1, 0)), []);
+
+  const goTo = useCallback(
+    (target: number) => setIndex(clamp(target, 0, lastIndex)),
+    [lastIndex],
+  );
+
+  const reset = useCallback(() => setIndex(0), []);
+
+  const isFirstStep = currentIndex <= 0;
+  const isLastStep = currentIndex >= lastIndex;
+
+  return [
+    currentIndex,
+    {
+      next,
+      back,
+      goTo,
+      reset,
+      canGoNext: !isLastStep,
+      canGoBack: !isFirstStep,
+      isFirstStep,
+      isLastStep,
+      progress: count <= 1 ? 0 : currentIndex / (count - 1),
+    },
+  ];
 }
-