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

package/src/hooks/use-on-mount/use-on-mount.stories.tsx

@@ -0,0 +1,85 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useState } from "react";
+import { Button } from "../../components/button";
+import { Stack } from "../../components/stack";
+import { useOnMount } from "./use-on-mount";
+
+/**
+ * Run a callback exactly once, when the component mounts.
+ *
+ * It's basically `useEffect(fn, [])` with two improvements: the callback
+ * never re-runs even if React's StrictMode replays effects in dev, and
+ * the intent ("on mount") is right there in the name — no `// biome-ignore`
+ * for an empty deps array.
+ *
+ * ```tsx
+ * useOnMount(() => {
+ *   trackPageView("/dashboard");
+ * });
+ * ```
+ *
+ * Good to know:
+ * - Returning a function from the callback registers a cleanup that runs
+ *   on unmount — same contract as `useEffect`.
+ * - The callback identity is captured on first run. Passing a new function
+ *   on later renders does **not** re-fire the hook, so you don't need to
+ *   memoize it.
+ * - For "do something on every update except the first one" use a different
+ *   pattern (a ref-guarded `useEffect` with deps) — this hook is mount-only.
+ */
+const meta: Meta<typeof useOnMount> = {
+  title: "hooks/useOnMount",
+  parameters: { layout: "centered" },
+  tags: ["new"],
+};
+
+export default meta;
+type Story = StoryObj<typeof useOnMount>;
+
+/**
+ * The hook stamps a timestamp on the first render and never touches it
+ * again. Click "Force re-render" as many times as you want — the
+ * "Mounted at" value stays frozen while the render counter ticks up.
+ * That's the proof that `useOnMount` fires exactly once.
+ */
+export const Default: Story = {
+  render: () => {
+    const [mountedAt, setMountedAt] = useState("");
+    const [renderCount, setRenderCount] = useState(0);
+
+    useOnMount(() => {
+      setMountedAt(
+        new Date().toLocaleTimeString(undefined, {
+          hour12: false,
+          hour: "2-digit",
+          minute: "2-digit",
+          second: "2-digit",
+        }),
+      );
+    });
+
+    return (
+      <Stack
+        direction="vertical"
+        gap={16}
+        style={{ minWidth: 360, padding: 20, borderRadius: 12 }}
+        className="border border-border bg-card"
+      >
+        <Stack direction="vertical" gap={4}>
+          <span className="text-sm">
+            <strong>Mounted at:</strong>{" "}
+            <code className="text-success">{mountedAt || "..."}</code>
+          </span>
+          <span className="text-xs text-muted-foreground">
+            Re-rendered {renderCount} time{renderCount === 1 ? "" : "s"} —
+            timestamp stays the same.
+          </span>
+        </Stack>
+
+        <Button onClick={() => setRenderCount((n) => n + 1)}>
+          Force re-render
+        </Button>
+      </Stack>
+    );
+  },
+};

package/src/hooks/use-on-mount/use-on-mount.test.tsx

@@ -0,0 +1,51 @@
+import { renderHook } from "@testing-library/react";
+import { StrictMode } from "react";
+import { describe, expect, it, vi } from "vitest";
+import { useOnMount } from "./use-on-mount";
+
+describe("useOnMount", () => {
+  it("runs the callback once on mount", () => {
+    const fn = vi.fn();
+    renderHook(() => useOnMount(fn));
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not re-run on subsequent renders", () => {
+    const fn = vi.fn();
+    const { rerender } = renderHook(() => useOnMount(fn));
+    rerender();
+    rerender();
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not re-run when the callback identity changes", () => {
+    const fn1 = vi.fn();
+    const fn2 = vi.fn();
+    const { rerender } = renderHook(({ cb }) => useOnMount(cb), {
+      initialProps: { cb: fn1 },
+    });
+    rerender({ cb: fn2 });
+    expect(fn1).toHaveBeenCalledTimes(1);
+    expect(fn2).not.toHaveBeenCalled();
+  });
+
+  it("runs the returned cleanup function on unmount", () => {
+    const cleanup = vi.fn();
+    const { unmount } = renderHook(() => useOnMount(() => cleanup));
+    expect(cleanup).not.toHaveBeenCalled();
+
+    unmount();
+    expect(cleanup).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not throw when the callback returns nothing", () => {
+    const { unmount } = renderHook(() => useOnMount(() => undefined));
+    expect(() => unmount()).not.toThrow();
+  });
+
+  it("guard prevents double-run in React StrictMode", () => {
+    const fn = vi.fn();
+    renderHook(() => useOnMount(fn), { wrapper: StrictMode });
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+});

package/src/hooks/use-on-mount/use-on-mount.tsx

@@ -0,0 +1,13 @@
+import { useEffect, useRef } from "react";
+
+export type UseOnMountCallback = () => void | (() => void);
+
+export function useOnMount(callback: UseOnMountCallback): void {
+  const hasRunRef = useRef(false);
+
+  useEffect(() => {
+    if (hasRunRef.current) return;
+    hasRunRef.current = true;
+    return callback();
+  }, []);
+}

package/src/hooks/use-pagination/index.ts

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

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

@@ -0,0 +1,72 @@
+import { Meta } from "@storybook/react-vite";
+import { useState } from "react";
+import { action } from "storybook/actions";
+import { Button } from "../../components";
+import { usePagination } from "../use-pagination";
+
+const TABLE_PAGE_SIZES = [5, 10, 20, 50, 100];
+/**
+ * Hook que facilita el manejo de paginaciones, recibe como param la cantidad de elementos, la cantidad de elementos por página y una función
+ * que se ejecuta cuando cambia la pagina
+ */
+const meta: Meta = {
+  title: "hooks/usePagination",
+  tags: ["autodocs"],
+};
+
+export default meta;
+
+export const Default = () => {
+  const [pageSize, setPageSize] = useState(TABLE_PAGE_SIZES[0]);
+  const { currentPage, maxPage, isLastPage, isFirstPage, prev, next, goTo } =
+    usePagination({
+      totalItems: 100,
+      pageSize: pageSize,
+      onChange: action("change"),
+      initialCurrentPage: 1,
+    });
+
+  return (
+    <div className="space-y-2">
+      <pre className="rounded-md bg-slate-950 p-4 text-white">
+        <code className="block">
+          CurrentPage:{" "}
+          <span className="text-blue-300">
+            {JSON.stringify(currentPage, null, 2)}
+          </span>
+        </code>
+        <code className="block">PageSize: {pageSize}</code>
+        <code className="block">Maxpage: {maxPage}</code>
+        <code className="block">
+          isLastPage:{" "}
+          <span className={isLastPage ? "text-green-500" : "text-red-500"}>
+            {JSON.stringify(isLastPage)}
+          </span>
+        </code>
+        <code className="block">
+          IsFirstPage:{" "}
+          <span className={isFirstPage ? "text-green-500" : "text-red-500"}>
+            {JSON.stringify(isFirstPage)}
+          </span>
+        </code>
+      </pre>
+
+      <div className="flex gap-2">
+        <select
+          className="border rounded w-24 px-2"
+          value={pageSize}
+          onChange={(event) => setPageSize(Number(event.target.value))}
+        >
+          {TABLE_PAGE_SIZES.map((option: number, index) => (
+            <option key={index} value={option}>
+              {option}
+            </option>
+          ))}
+        </select>
+        <Button onClick={prev}>Página anterior</Button>
+        <Button onClick={next}>Siguiente pagina</Button>
+        <Button onClick={() => goTo(10)}>Ir a la pagina 10</Button>
+      </div>
+    </div>
+  );
+};

package/src/hooks/use-pagination/use-pagination.test.tsx

@@ -0,0 +1,98 @@
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { usePagination } from "../use-pagination";
+
+describe("usePagination hook", () => {
+  it("should be defined", () => {
+    expect(usePagination).toBeDefined();
+  });
+
+  it("should show total items and items per page", () => {
+    const { result } = renderHook(() =>
+      usePagination({
+        totalItems: 100,
+        pageSize: 10,
+      }),
+    );
+    const { maxPage, currentPage } = result.current;
+
+    expect(maxPage).toBe(10);
+    expect(currentPage).toBe(1);
+  });
+
+  it("should recive initial current page", () => {
+    const { result } = renderHook(() =>
+      usePagination({
+        totalItems: 100,
+        pageSize: 10,
+        initialCurrentPage: 5,
+      }),
+    );
+    const { currentPage } = result.current;
+    expect(currentPage).toBe(5);
+  });
+
+  it("should go next", () => {
+    const { result } = renderHook(() =>
+      usePagination({
+        totalItems: 100,
+        pageSize: 10,
+      }),
+    );
+    const { next } = result.current;
+    act(() => next());
+
+    const { currentPage } = result.current;
+    expect(currentPage).toBe(2);
+  });
+
+  it("should go previous", () => {
+    const { result } = renderHook(() =>
+      usePagination({
+        totalItems: 100,
+        pageSize: 10,
+        initialCurrentPage: 3,
+      }),
+    );
+    const { prev } = result.current;
+    act(() => prev());
+
+    const { currentPage } = result.current;
+    expect(currentPage).toBe(2);
+  });
+
+  it("should go to page number", () => {
+    const { result } = renderHook(() =>
+      usePagination({
+        totalItems: 100,
+        pageSize: 10,
+      }),
+    );
+    const { goTo, currentPage } = result.current;
+    act(() => goTo(5));
+
+    waitFor(() => {
+      expect(currentPage).toBe(5);
+    });
+  });
+
+  it("should show isFirstPage and isLastPage", () => {
+    const { result } = renderHook(() =>
+      usePagination({
+        totalItems: 100,
+        pageSize: 10,
+        initialCurrentPage: 5,
+      }),
+    );
+
+    const { isFirstPage, isLastPage, goTo, maxPage } = result.current;
+    expect(isFirstPage).toBe(false);
+    expect(isLastPage).toBe(false);
+
+    act(() => goTo(maxPage));
+
+    waitFor(() => {
+      expect(isLastPage).toBe(true);
+    });
+  });
+});

package/src/hooks/use-pagination/use-pagination.tsx

@@ -0,0 +1,84 @@
+import { useControllableState } from "@radix-ui/react-use-controllable-state";
+
+export type usePaginationProps = {
+  /**
+   * Cantidad total de elementos
+   */
+  totalItems: number;
+  /**
+   * Cantidad de elementos por página
+   */
+  pageSize: number;
+  /**
+   * Página controlada
+   */
+  currentPage?: number;
+  /**
+   * Página inicial (uncontrolled)
+   */
+  defaultCurrentPage?: number;
+  /**
+   * Callback cuando cambia la página
+   */
+  onCurrentPageChange?: (page: number) => void;
+  /**
+   * @deprecated Usá `defaultCurrentPage`
+   */
+  initialCurrentPage?: number;
+  /**
+   * @deprecated Usá `onCurrentPageChange`
+   */
+  onChange?: (value: { currentPage: number; pageSize: number }) => void;
+};
+
+export function usePagination({
+  totalItems,
+  pageSize,
+  currentPage: currentPageProp,
+  defaultCurrentPage,
+  onCurrentPageChange,
+  initialCurrentPage,
+  onChange,
+}: usePaginationProps) {
+  const [currentPage = 1, setCurrentPage] = useControllableState<number>({
+    prop: currentPageProp,
+    defaultProp: defaultCurrentPage ?? initialCurrentPage ?? 1,
+    onChange: (page) => {
+      onCurrentPageChange?.(page);
+      onChange?.({ currentPage: page, pageSize });
+    },
+  });
+
+  const maxPage = Math.max(1, Math.ceil(totalItems / pageSize));
+  const isLastPage = currentPage >= maxPage;
+  const isFirstPage = currentPage <= 1;
+  const start = (currentPage - 1) * pageSize + 1;
+  const end = Math.min(currentPage * pageSize, totalItems);
+
+  const next = () => {
+    if (isLastPage) return;
+    setCurrentPage(Math.min(currentPage + 1, maxPage));
+  };
+
+  const prev = () => {
+    if (isFirstPage) return;
+    setCurrentPage(Math.max(currentPage - 1, 1));
+  };
+
+  const goTo = (page: number) => {
+    const clamped = Math.min(Math.max(1, page), maxPage);
+    if (clamped === currentPage) return;
+    setCurrentPage(clamped);
+  };
+
+  return {
+    next,
+    prev,
+    goTo,
+    currentPage,
+    maxPage,
+    isFirstPage,
+    isLastPage,
+    range: { start, end },
+  };
+}

package/src/hooks/use-portal/index.ts

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

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

@@ -0,0 +1,19 @@
+import { Meta } from "@storybook/react-vite";
+import { usePortal } from "../use-portal";
+
+const meta: Meta = {
+  title: "hooks/usePortal",
+};
+
+export default meta;
+
+export const Default = {
+  render: () => {
+    const { render } = usePortal("id");
+    return render(
+      <div className="fixed-center bg-primary text-primary-foreground rounded p-4">
+        Este contenido se muestra en un portal 🧱
+      </div>,
+    );
+  },
+};

package/src/hooks/use-portal/use-portal.test.tsx

@@ -0,0 +1,77 @@
+import { render, renderHook, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+import { usePortal } from "../use-portal";
+
+describe("usePortal hook", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  it("should be defined", () => {
+    const { result } = renderHook(() => usePortal("id"));
+    expect(result.current).toBeDefined();
+  });
+
+  it("should render element", () => {
+    const Component = () => {
+      const { render } = usePortal("id2");
+      return render(<div>Hello World</div>);
+    };
+
+    render(<Component />);
+    expect(screen.getByText("Hello World")).toBeInTheDocument();
+  });
+
+  it("removes the wrapper from the DOM when the hook unmounts", () => {
+    const Component = () => {
+      const { render } = usePortal("created-by-hook");
+      return render(<span>portal child</span>);
+    };
+
+    const view = render(<Component />);
+    expect(document.getElementById("created-by-hook")).not.toBeNull();
+
+    view.unmount();
+    expect(document.getElementById("created-by-hook")).toBeNull();
+  });
+
+  it("does not remove a wrapper that already existed in the DOM", () => {
+    const preExisting = document.createElement("div");
+    preExisting.id = "pre-existing";
+    preExisting.textContent = "external";
+    document.body.appendChild(preExisting);
+
+    const Component = () => {
+      const { render } = usePortal("pre-existing");
+      return render(<span>child</span>);
+    };
+
+    const view = render(<Component />);
+    view.unmount();
+
+    expect(document.getElementById("pre-existing")).toBe(preExisting);
+    expect(preExisting.textContent).toContain("external");
+  });
+
+  it("shares a wrapper across multiple instances and removes it only after the last unmount", () => {
+    const A = () => {
+      const { render } = usePortal("shared");
+      return render(<span>a</span>);
+    };
+    const B = () => {
+      const { render } = usePortal("shared");
+      return render(<span>b</span>);
+    };
+
+    const viewA = render(<A />);
+    const viewB = render(<B />);
+
+    expect(document.getElementById("shared")).not.toBeNull();
+
+    viewA.unmount();
+    expect(document.getElementById("shared")).not.toBeNull();
+
+    viewB.unmount();
+    expect(document.getElementById("shared")).toBeNull();
+  });
+});

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

@@ -0,0 +1,59 @@
+import type { ReactNode, ReactPortal } from "react";
+import { useEffect, useState } from "react";
+import { createPortal } from "react-dom";
+
+type PortalEntry = {
+  node: HTMLElement;
+  count: number;
+  createdByHook: boolean;
+};
+
+const portals = new Map<string, PortalEntry>();
+
+function acquire(id: string): HTMLElement {
+  const existing = portals.get(id);
+  if (existing) {
+    existing.count += 1;
+    return existing.node;
+  }
+
+  const preExisting = document.getElementById(id);
+  if (preExisting) {
+    portals.set(id, { node: preExisting, count: 1, createdByHook: false });
+    return preExisting;
+  }
+
+  const node = document.createElement("div");
+  node.id = id;
+  document.body.appendChild(node);
+  portals.set(id, { node, count: 1, createdByHook: true });
+  return node;
+}
+
+function release(id: string) {
+  const entry = portals.get(id);
+  if (!entry) return;
+  entry.count -= 1;
+  if (entry.count > 0) return;
+  if (entry.createdByHook && entry.node.parentNode) {
+    entry.node.parentNode.removeChild(entry.node);
+  }
+  portals.delete(id);
+}
+
+export function usePortal(id: string) {
+  const [wrapper, setWrapper] = useState<HTMLElement | null>(null);
+
+  useEffect(() => {
+    const node = acquire(id);
+    setWrapper(node);
+    return () => {
+      release(id);
+    };
+  }, [id]);
+
+  return {
+    render: (children: ReactNode): ReactPortal | null =>
+      wrapper ? createPortal(children, wrapper) : null,
+  };
+}

package/src/hooks/use-prevent-page-close/index.ts

@@ -0,0 +1 @@
+export * from "./use-prevent-page-close";

package/src/hooks/use-prevent-page-close/use-prevent-page-close.stories.tsx

@@ -0,0 +1,39 @@
+import type { Meta } from "@storybook/react-vite";
+import { usePreventPageClose } from "./use-prevent-page-close";
+
+/**
+ * Prompts the browser's native "Leave site?" confirmation when the user
+ * tries to close the tab or reload while `enabled` is `true`. Typical
+ * use: block accidental navigation away from a form with unsaved
+ * changes. Only covers full-page unload — SPA route changes need a
+ * router guard. The dialog text is controlled by the browser and cannot
+ * be customized.
+ */
+const meta: Meta = {
+  title: "hooks/usePreventPageClose",
+  tags: ["beta"],
+  args: {
+    enabled: true,
+  },
+  argTypes: {
+    enabled: {
+      control: "boolean",
+      description:
+        "When true, closing or reloading the tab triggers the native confirmation dialog.",
+    },
+  },
+};
+
+export default meta;
+
+export const Default = {
+  render: (args: { enabled: boolean }) => {
+    usePreventPageClose(args.enabled);
+    return (
+      <p className="text-sm">
+        Try to close or reload this tab — the browser will ask for confirmation
+        while <code>enabled</code> is on.
+      </p>
+    );
+  },
+};