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

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

@@ -0,0 +1,211 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { Button } from "../../components";
+import { cn } from "../../lib";
+import { useStep } from "./use-step";
+
+// ---------------------------------------------------------------------------
+// Meta
+// ---------------------------------------------------------------------------
+
+/**
+ * `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",
+  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;
+
+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.",
+      },
+    },
+  },
+  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 + '%'`.",
+      },
+    },
+  },
+  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.",
+      },
+    },
+  },
+  render: () => {
+    const count = 5;
+    const [index, { next, back, goTo, canGoNext, canGoBack }] = useStep(count);
+
+    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 {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(
+                "h-3 w-3 rounded-full border-2 transition-colors",
+                i === index
+                  ? "bg-primary border-primary"
+                  : "bg-transparent border-muted-foreground hover:border-primary",
+              )}
+              aria-label={`Go to step ${i + 1}`}
+            />
+          ))}
+        </div>
+
+        <div className="flex gap-2">
+          <Button variant="outline" onClick={back} disabled={!canGoBack}>
+            Back
+          </Button>
+          <Button onClick={next} disabled={!canGoNext}>
+            Next
+          </Button>
+        </div>
+
+        <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>
+          </p>
+          <p>
+            canGoNext:{" "}
+            <span className={canGoNext ? "text-green-600" : "text-red-500"}>
+              {String(canGoNext)}
+            </span>
+          </p>
+        </div>
+      </div>
+    );
+  },
+};

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

@@ -0,0 +1,198 @@
+import { act, renderHook } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+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);
+    });
+  });
+
+  // ── 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);
+    });
+  });
+
+  // ── 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);
+    });
+  });
+
+  // ── 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);
+    });
+  });
+
+  // ── 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);
+    });
+  });
+
+  // ── 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);
+    });
+  });
+
+  // ── 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);
+    });
+  });
+
+  // ── 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);
+    });
+  });
+
+  // ── 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

@@ -0,0 +1,63 @@
+import { useCallback, useState } from "react";
+
+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;
+  /** 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;
+}
+
+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),
+    },
+  ];
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from "./components";
+export * from "./hooks";
+export * from "./lib";
+export * from "./models";
+export * from "./providers";
+export * from "./utils";

package/src/lib/cn.ts

@@ -0,0 +1,8 @@
+import { type ClassValue, clsx } from "clsx";
+import { extendTailwindMerge } from "tailwind-merge";
+
+export const twMerge = extendTailwindMerge({});
+
+export function cn(...args: ClassValue[]) {
+  return twMerge(clsx(args));
+}

package/src/lib/index.ts

@@ -0,0 +1 @@
+export * from "./cn";

package/src/models/Generic.model.ts

@@ -0,0 +1,67 @@
+import {
+  Dispatch,
+  HTMLProps,
+  MutableRefObject,
+  ReactElement,
+  ReactNode,
+  SetStateAction,
+} from "react";
+
+export interface Option<TValue = string> {
+  label: string;
+  value: TValue;
+  disabled?: boolean;
+}
+
+export type ClassName = string | undefined;
+
+export type ClickEvent = React.MouseEvent<HTMLButtonElement, MouseEvent>;
+
+export type ControllableState<T> = {
+  value?: T;
+  defaultValue?: T;
+  onChange?: (state: T) => void;
+};
+
+export type Controllable<C, T extends NonNullable<unknown>> = OverrideProps<
+  HTMLProps<C>,
+  ControllableState<T>
+>;
+
+export type MaybeRef<T> = T | MutableRefObject<T>;
+
+export type ArrayUnion<V, T extends ReadonlyArray<V>> = T[number];
+
+export type ValuesUnion<T extends Record<string, any>> = T[keyof T];
+
+export type GenericObject<T = any> = { [key: string]: T };
+
+export type Nullable<T> = T | null;
+
+export type Maybe<T> = T | undefined | null;
+
+export type SetState<T> = Dispatch<SetStateAction<T>>;
+
+export type State<T> = [T, SetState<T>];
+
+export type ID = string | number;
+
+export type OverrideProps<T, TOverridden> = Omit<T, keyof TOverridden> &
+  TOverridden;
+
+export type SafeOmit<T, K extends keyof T> = Pick<T, Exclude<keyof T, K>>;
+
+export type AtLeastOne<T> = [T, ...T[]];
+
+export type Loose<T> = T | (string & {});
+
+export type Renderable<T> = ReactNode | ((props: T) => ReactElement);
+
+export type BaseEntity = {
+  id: string;
+  createdAt: Date;
+};
+
+export type Entity<T> = {
+  [K in keyof T]: T[K];
+} & BaseEntity;

package/src/models/index.ts

@@ -0,0 +1 @@
+export * from "./Generic.model";

package/src/providers/index.ts

@@ -0,0 +1,2 @@
+export * from "./library-provider";
+export * from "./theme";

package/src/providers/library-provider.tsx

@@ -0,0 +1,44 @@
+import { Tooltip as TooltipBase } from "@base-ui/react/tooltip";
+import type { ComponentPropsWithoutRef, ReactNode } from "react";
+import {
+  ToastProvider,
+  type ToastProviderProps,
+} from "../components/toast/toast";
+import { TooltipProvider } from "../components/tooltip/tooltip";
+
+export type LibraryProviderProps = {
+  children: ReactNode;
+  /**
+   * Delay in ms before a tooltip opens when no other tooltip is already visible.
+   * Once a tooltip is open, subsequent ones open instantly until the cursor leaves.
+   * @default 600
+   */
+  tooltipDelay?: ComponentPropsWithoutRef<typeof TooltipBase.Provider>["delay"];
+} & Omit<ToastProviderProps, "children">;
+
+/**
+ * Single provider that wires up all library infrastructure.
+ * Wrap your app once — no other providers needed.
+ *
+ * Includes:
+ * - `TooltipProvider` — shared hover intent and delay grouping across all tooltips
+ * - `ToastProvider` — enables `toast.*` imperative API from anywhere
+ *
+ * @example
+ * ```tsx
+ * <LibraryProvider tooltipDelay={400}>
+ *   <App />
+ * </LibraryProvider>
+ * ```
+ */
+export function LibraryProvider({
+  children,
+  tooltipDelay,
+  ...toastProps
+}: LibraryProviderProps) {
+  return (
+    <TooltipProvider delay={tooltipDelay}>
+      <ToastProvider {...toastProps}>{children}</ToastProvider>
+    </TooltipProvider>
+  );
+}

package/src/providers/theme/ThemeProvider.tsx

@@ -0,0 +1,25 @@
+import { createContext, ReactNode, useContext } from "react";
+import { Theme } from "./types";
+
+const defaultTheme: Theme = {};
+
+const ThemeContext = createContext<{ theme: Theme }>({ theme: defaultTheme });
+
+export const useTheme = () => {
+  const context = useContext(ThemeContext);
+  return context;
+};
+
+type ThemeProviderProps = {
+  children: ReactNode;
+  theme?: Theme;
+};
+
+export const ThemeProvider = ({
+  children,
+  theme = defaultTheme,
+}: ThemeProviderProps) => {
+  return (
+    <ThemeContext.Provider value={{ theme }}>{children}</ThemeContext.Provider>
+  );
+};

package/src/providers/theme/index.ts

@@ -0,0 +1,3 @@
+export * from "./ThemeProvider";
+export * from "./types";
+export * from "./useThemeProps";

package/src/providers/theme/types.ts

@@ -0,0 +1,11 @@
+import { ComponentProps } from "react";
+import { Button } from "../../components/button/button";
+import { Input } from "../../components/input/input";
+
+type ThemeProps<T, TOverridden> = Partial<Omit<T, keyof TOverridden>>;
+type PropsWithoutValue<T> = Omit<T, "value" | "onChange" | "defaultValue">;
+
+export type Theme = {
+  Button?: ThemeProps<ComponentProps<typeof Button>, "asChild" | "loading">;
+  Input?: Partial<PropsWithoutValue<ComponentProps<typeof Input>>>;
+};

package/src/providers/theme/useThemeProps.ts

@@ -0,0 +1,25 @@
+import { useTheme } from "../../providers/theme/ThemeProvider";
+import { Theme } from "../../providers/theme/types";
+
+/**
+ * Hook que permite obtener y combinar las propiedades de un componente con las del tema.
+ *
+ * El orden de prioridad de las propiedades es:
+ * 1. Props pasadas directamente al componente
+ * 2. Props definidas en el ThemeProvider
+ * 3. Props por defecto del componente
+ */
+export const useThemeProps = <TComponent extends keyof Theme, TProps>(
+  componentName: TComponent,
+  props: TProps,
+  defaultProps: Partial<TProps> = {},
+): TProps => {
+  const { theme } = useTheme();
+  const themeProps = theme[componentName] || {};
+
+  return {
+    ...defaultProps,
+    ...themeProps,
+    ...props,
+  } as TProps;
+};