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

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

@@ -0,0 +1,89 @@
+import { renderHook } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { usePreventPageClose } from "./use-prevent-page-close";
+
+describe("usePreventPageClose", () => {
+  let addSpy: ReturnType<typeof vi.spyOn>;
+  let removeSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    addSpy = vi.spyOn(window, "addEventListener");
+    removeSpy = vi.spyOn(window, "removeEventListener");
+  });
+
+  afterEach(() => {
+    addSpy.mockRestore();
+    removeSpy.mockRestore();
+  });
+
+  it("registers a beforeunload listener when enabled", () => {
+    renderHook(() => usePreventPageClose(true));
+    expect(addSpy).toHaveBeenCalledWith("beforeunload", expect.any(Function));
+  });
+
+  it("does NOT register a listener when disabled", () => {
+    renderHook(() => usePreventPageClose(false));
+    expect(addSpy).not.toHaveBeenCalledWith(
+      "beforeunload",
+      expect.any(Function),
+    );
+  });
+
+  it("removes the listener on unmount", () => {
+    const { unmount } = renderHook(() => usePreventPageClose(true));
+    unmount();
+    expect(removeSpy).toHaveBeenCalledWith(
+      "beforeunload",
+      expect.any(Function),
+    );
+  });
+
+  it("calls preventDefault inside the handler", () => {
+    renderHook(() => usePreventPageClose(true));
+
+    const handler = addSpy.mock.calls.find(
+      ([event]: [string, EventListenerOrEventListenerObject]) =>
+        event === "beforeunload",
+    )?.[1] as EventListener;
+
+    const event = new Event("beforeunload");
+    const preventSpy = vi.spyOn(event, "preventDefault");
+    handler(event);
+
+    expect(preventSpy).toHaveBeenCalled();
+  });
+
+  it("registers the listener once enabled flips to true", () => {
+    const { rerender } = renderHook(
+      ({ enabled }) => usePreventPageClose(enabled),
+      {
+        initialProps: { enabled: false },
+      },
+    );
+
+    expect(addSpy).not.toHaveBeenCalledWith(
+      "beforeunload",
+      expect.any(Function),
+    );
+
+    rerender({ enabled: true });
+
+    expect(addSpy).toHaveBeenCalledWith("beforeunload", expect.any(Function));
+  });
+
+  it("tears down the listener when enabled flips back to false", () => {
+    const { rerender } = renderHook(
+      ({ enabled }) => usePreventPageClose(enabled),
+      {
+        initialProps: { enabled: true },
+      },
+    );
+
+    rerender({ enabled: false });
+
+    expect(removeSpy).toHaveBeenCalledWith(
+      "beforeunload",
+      expect.any(Function),
+    );
+  });
+});

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

@@ -0,0 +1,27 @@
+import { useEffect } from "react";
+import { isBrowser } from "../internal";
+
+/**
+ * Shows the browser's native "Leave site?" confirmation when the user
+ * tries to close the tab or reload the page while `enabled` is `true`.
+ *
+ * Note: this only covers full-page unload (tab close / reload). It does
+ * NOT intercept SPA route changes — for that, combine with your router's
+ * navigation guard. The dialog text is controlled by the browser and
+ * cannot be customized.
+ */
+export function usePreventPageClose(enabled: boolean): void {
+  useEffect(() => {
+    if (!isBrowser || !enabled) return;
+
+    const handleBeforeUnload = (event: BeforeUnloadEvent) => {
+      event.preventDefault();
+      // Required by Chrome to trigger the native dialog. The string is
+      // ignored by modern browsers, which show their own generic message.
+      event.returnValue = "";
+    };
+
+    window.addEventListener("beforeunload", handleBeforeUnload);
+    return () => window.removeEventListener("beforeunload", handleBeforeUnload);
+  }, [enabled]);
+}

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

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

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

@@ -0,0 +1,63 @@
+import { renderHook } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { DOTS, useRangePagination } from "../use-range-pagination";
+
+describe("usePagination hook", () => {
+  it("should be defined", () => {
+    expect(useRangePagination).toBeDefined();
+  });
+
+  it("shouldn't show dots if there is not enough items", () => {
+    const { result } = renderHook(() =>
+      useRangePagination({
+        totalItems: 5,
+        pageSize: 1,
+      }),
+    );
+
+    expect(result.current.paginationRange).toEqual([1, 2, 3, 4, 5]);
+  });
+
+  it("should show right dots", () => {
+    const { result } = renderHook(() =>
+      useRangePagination({
+        totalItems: 10,
+        pageSize: 1,
+      }),
+    );
+
+    expect(result.current.paginationRange).toEqual([1, 2, 3, 4, 5, DOTS, 10]);
+  });
+
+  it("should show left dots", () => {
+    const { result } = renderHook(() =>
+      useRangePagination({
+        totalItems: 10,
+        pageSize: 1,
+        initialCurrentPage: 8,
+      }),
+    );
+
+    expect(result.current.paginationRange).toEqual([1, DOTS, 6, 7, 8, 9, 10]);
+  });
+
+  it("should show dots both sides", () => {
+    const { result } = renderHook(() =>
+      useRangePagination({
+        totalItems: 10,
+        pageSize: 1,
+        initialCurrentPage: 5,
+      }),
+    );
+
+    expect(result.current.paginationRange).toEqual([
+      1,
+      DOTS,
+      4,
+      5,
+      6,
+      DOTS,
+      10,
+    ]);
+  });
+});

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

@@ -0,0 +1,73 @@
+import { useMemo } from "react";
+
+const range = (start: number, end: number): number[] =>
+  Array.from({ length: end - start }, (_, i) => i + start);
+
+import { usePagination, type usePaginationProps } from "../../hooks";
+
+export const DOTS = "...";
+
+export type useRangePaginationProps = {
+  /**
+   * Cantidad de elementos visibles al lado de la pagina actual
+   */
+  siblingCount?: number;
+} & usePaginationProps;
+
+export const useRangePagination = ({
+  siblingCount = 1,
+  ...paginationProps
+}: useRangePaginationProps) => {
+  const pagination = usePagination(paginationProps);
+  const { currentPage, maxPage } = pagination;
+  const { totalItems, pageSize } = paginationProps;
+
+  const generateRange = () => {
+    const DOTS_THRESHOLD = 2;
+    const EXTRA_ITEMS = 3;
+    const ITEMS_UNTIL_DOTS = DOTS_THRESHOLD + EXTRA_ITEMS * siblingCount;
+    const FIRST_PAGE = 1;
+
+    // No hay suficientes elementos para agregar DOTS
+    if (ITEMS_UNTIL_DOTS >= maxPage) {
+      return range(FIRST_PAGE, maxPage + 1);
+    }
+
+    // índice de elemento de izquierda y derecha
+    const leftSiblingIndex = Math.max(currentPage - siblingCount, 1);
+    const rightSiblingIndex = Math.min(currentPage + siblingCount, maxPage);
+
+    const shouldShowLeftDots = leftSiblingIndex > DOTS_THRESHOLD;
+    const shouldShowRightDots = rightSiblingIndex < maxPage - DOTS_THRESHOLD;
+
+    // Debe mostrar DOTS de ambos lados
+    if (shouldShowLeftDots && shouldShowRightDots) {
+      const middleElements = range(leftSiblingIndex, rightSiblingIndex + 1);
+      return [FIRST_PAGE, DOTS, ...middleElements, DOTS, maxPage];
+    }
+
+    // Debe mostrar DOTS a la derecha
+    if (shouldShowRightDots) {
+      const leftElements = range(FIRST_PAGE, ITEMS_UNTIL_DOTS + 1);
+      return [...leftElements, DOTS, maxPage];
+    }
+
+    // Debe mostrar DOTS a la izquierda
+    if (shouldShowLeftDots) {
+      const rightElements = range(maxPage - ITEMS_UNTIL_DOTS + 1, maxPage + 1);
+      return [FIRST_PAGE, DOTS, ...rightElements];
+    }
+  };
+
+  const paginationRange = useMemo(generateRange, [
+    totalItems,
+    pageSize,
+    currentPage,
+    siblingCount,
+  ]);
+
+  return {
+    ...pagination,
+    paginationRange: paginationRange ?? [],
+  };
+};

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

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

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

@@ -0,0 +1,140 @@
+import { Meta, StoryObj } from "@storybook/react-vite";
+import { Trash } from "lucide-react";
+import { useMemo, useState } from "react";
+import { Button, Checkbox } from "../../components";
+import { cn } from "../../lib";
+import { useSelection } from "../use-selection";
+
+/**
+ * Gestión de la selección de elementos en una lista.
+ * Optimizado para un rendimiento eficiente, utiliza un conjunto (Set) interno para almacenar los elementos seleccionados, permitiendo consultas rápidas para verificar si un elemento está seleccionado.
+ * Proporciona funciones simples para seleccionar, deseleccionar, alternar la selección de un elemento, seleccionar todos los elementos, limpiar la selección y obtener el estado actual de la selección
+ */
+const meta: Meta = {
+  title: "hooks/useSelection",
+  tags: ["autodocs"],
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () => {
+    const items = useMemo(() => ["🍆", "🍅", "🥑", "🥬"], []);
+    const {
+      selected,
+      toggle,
+      toggleAll,
+      clear,
+      isSelected,
+      isAllSelected,
+      isNoneSelected,
+      setSelected,
+    } = useSelection(items);
+
+    return (
+      <div className="space-y-4">
+        <div className="flex gap-2">
+          {items.map((item) => (
+            <div
+              key={item}
+              onClick={() => toggle(item)}
+              className={cn(
+                "rounded transition-colors w-32 h-32 shadow text-3xl grid place-items-center cursor-pointer",
+                { "bg-accent": isSelected(item) },
+              )}
+            >
+              {item}
+            </div>
+          ))}
+        </div>
+
+        <div className="flex gap-4 my-2">
+          <Button onClick={clear}>Limpiar</Button>
+          <Button onClick={toggleAll}>Toggle all</Button>
+          <Button onClick={() => setSelected(["🍅"])}>set 🍅</Button>
+        </div>
+
+        <pre className="p-4 text-white rounded-md bg-slate-950">
+          <code className="block">
+            Selected:{" "}
+            <span className="text-blue-300">
+              {JSON.stringify(selected, null, 2)}
+            </span>
+          </code>
+          <code className="block">
+            isAllSelected:{" "}
+            <span className={isAllSelected ? "text-green-500" : "text-red-500"}>
+              {JSON.stringify(isAllSelected)}
+            </span>
+          </code>
+          <code className="block">
+            isNoneSelected:{" "}
+            <span
+              className={isNoneSelected ? "text-green-500" : "text-red-500"}
+            >
+              {JSON.stringify(isNoneSelected)}
+            </span>
+          </code>
+        </pre>
+      </div>
+    );
+  },
+};
+
+export const DynamicArray: Story = {
+  name: "Array dinamico",
+  render: () => {
+    // state o useMemo
+    const [items, setItems] = useState([
+      { id: 1, name: "Item 1" },
+      { id: 2, name: "Item 2" },
+      { id: 3, name: "Item 3" },
+    ]);
+
+    const { selected, toggle, isSelected, unselect } = useSelection(items);
+
+    const addNewItem = () => {
+      const id = new Date().getTime();
+      setItems((prevItems) => [...prevItems, { id, name: `Item ${id}` }]);
+    };
+
+    const removeItem = (item: { id: number; name: string }) => {
+      setItems((prevItems) => prevItems.filter((i) => i.id !== item.id));
+      unselect(item);
+    };
+
+    return (
+      <div>
+        {items.map((item) => (
+          <div key={item.id} className="flex items-center gap-2">
+            <Checkbox
+              name={item.id.toString()}
+              checked={isSelected(item)}
+              onCheckedChange={() => toggle(item)}
+            />
+            <span className="text-sm">{item.name}</span>
+            <Button
+              size="icon"
+              variant="ghost"
+              onClick={() => removeItem(item)}
+            >
+              <Trash />
+            </Button>
+          </div>
+        ))}
+        <Button className="my-2" onClick={addNewItem}>
+          Añadir nuevo elemento
+        </Button>
+        <pre className="p-4 text-white rounded-md bg-slate-950">
+          <code className="block">
+            Selected:{" "}
+            <span className="text-blue-300">
+              {JSON.stringify(selected, null, 2)}
+            </span>
+          </code>
+        </pre>
+      </div>
+    );
+  },
+};

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

@@ -0,0 +1,79 @@
+import { act, renderHook } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { useSelection } from "../use-selection";
+
+describe("useSelection hook", () => {
+  it("initial state: isAllSelected=false, isNoneSelected=true", () => {
+    const { result } = renderHook(() => useSelection([1, 2, 3]));
+    expect(result.current.isAllSelected).toBe(false);
+    expect(result.current.isNoneSelected).toBe(true);
+    expect(result.current.isSomeSelected).toBe(false);
+  });
+
+  it("select adds item to selected array", () => {
+    const { result } = renderHook(() => useSelection([1, 2, 3]));
+    act(() => result.current.select(2));
+    expect(result.current.isSelected(2)).toBe(true);
+    expect(result.current.selected).toEqual([2]);
+  });
+
+  it("unselect removes item from selection", () => {
+    const { result } = renderHook(() => useSelection([1, 2, 3]));
+    act(() => result.current.select(2));
+    expect(result.current.isSelected(2)).toBe(true);
+    act(() => result.current.unselect(2));
+    expect(result.current.isSelected(2)).toBe(false);
+    expect(result.current.selected).toEqual([]);
+  });
+
+  it("toggle adds unselected item", () => {
+    const { result } = renderHook(() => useSelection([1, 2, 3]));
+    act(() => result.current.toggle(1));
+    expect(result.current.isSelected(1)).toBe(true);
+  });
+
+  it("toggle removes already-selected item", () => {
+    const { result } = renderHook(() => useSelection([1, 2, 3]));
+    act(() => result.current.select(1));
+    act(() => result.current.toggle(1));
+    expect(result.current.isSelected(1)).toBe(false);
+  });
+
+  it("setSelected replaces selection with given items", () => {
+    const { result } = renderHook(() => useSelection([1, 2, 3]));
+    act(() => result.current.setSelected([1, 3]));
+    expect(result.current.isSelected(1)).toBe(true);
+    expect(result.current.isSelected(2)).toBe(false);
+    expect(result.current.isSelected(3)).toBe(true);
+  });
+
+  it("toggleAll selects all when none selected", () => {
+    const { result } = renderHook(() => useSelection([1, 2, 3]));
+    act(() => result.current.toggleAll());
+    expect(result.current.isAllSelected).toBe(true);
+    expect(result.current.isNoneSelected).toBe(false);
+  });
+
+  it("toggleAll deselects all when all selected", () => {
+    const { result } = renderHook(() => useSelection([1, 2, 3]));
+    act(() => result.current.toggleAll());
+    act(() => result.current.toggleAll());
+    expect(result.current.isAllSelected).toBe(false);
+    expect(result.current.isNoneSelected).toBe(true);
+  });
+
+  it("isSomeSelected is true when partial selection", () => {
+    const { result } = renderHook(() => useSelection([1, 2, 3]));
+    act(() => result.current.select(1));
+    expect(result.current.isSomeSelected).toBe(true);
+    expect(result.current.isAllSelected).toBe(false);
+  });
+
+  it("clear removes all selections", () => {
+    const { result } = renderHook(() => useSelection([1, 2, 3]));
+    act(() => result.current.toggleAll());
+    act(() => result.current.clear());
+    expect(result.current.isNoneSelected).toBe(true);
+    expect(result.current.selected).toEqual([]);
+  });
+});

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

@@ -0,0 +1,119 @@
+import { useCallback, useState } from "react";
+
+type Return<T> = {
+  /**
+   * Indica si todos los elementos están seleccionados.
+   */
+  isAllSelected: boolean;
+
+  /**
+   * Indica si algunos elementos están seleccionados.
+   */
+  isSomeSelected: boolean;
+
+  /**
+   * Indica si ningun elemento está seleccionado.
+   */
+  isNoneSelected: boolean;
+
+  /**
+   * Función que devuelve true si el elemento dado está seleccionado, false de lo contrario.
+   * @param item El elemento a verificar.
+   * @returns true si el elemento está seleccionado, false de lo contrario.
+   */
+  isSelected: (item: T) => boolean;
+
+  /**
+   * Array de elementos seleccionados.
+   */
+  selected: T[];
+
+  /**
+   * Establece los elementos seleccionados.
+   * @param items Los elementos seleccionados.
+   */
+  setSelected: (items: T[]) => void;
+
+  /**
+   * Selecciona un elemento.
+   * @param item El elemento a seleccionar.
+   */
+  select: (item: T) => void;
+
+  /**
+   * Deselecciona un elemento.
+   * @param item El elemento a deseleccionar.
+   */
+  unselect: (item: T) => void;
+
+  /**
+   * Alterna la selección de un elemento (si está seleccionado, lo deselecciona y viceversa).
+   * @param item El elemento cuya selección se alternará.
+   */
+  toggle: (item: T) => void;
+
+  /**
+   * Alterna la selección de todos los elementos (si todos están seleccionados, los deselecciona; de lo contrario, los selecciona).
+   */
+  toggleAll: () => void;
+
+  /**
+   * Deselecciona todos los elementos.
+   */
+  clear: () => void;
+};
+export function useSelection<T>(items: T[]): Return<T> {
+  const [selected, setSelected] = useState(new Set<T>());
+
+  const isSelected = useCallback((item: T) => selected.has(item), [selected]);
+
+  const select = useCallback((item: T) => {
+    setSelected((prevSelected) => new Set([...prevSelected, item]));
+  }, []);
+
+  const unselect = useCallback((item: T) => {
+    setSelected((prevSelected) => {
+      const newSelected = new Set(prevSelected);
+      newSelected.delete(item);
+      return newSelected;
+    });
+  }, []);
+
+  const toggle = useCallback((item: T) => {
+    setSelected((prevSelected) => {
+      const newSelected = new Set(prevSelected);
+      if (newSelected.has(item)) {
+        newSelected.delete(item);
+      } else {
+        newSelected.add(item);
+      }
+      return newSelected;
+    });
+  }, []);
+
+  const setItems = useCallback((items: T[]) => {
+    setSelected(new Set(items));
+  }, []);
+
+  const toggleAll = useCallback(() => {
+    setSelected((prevSelected) =>
+      prevSelected.size === items.length ? new Set() : new Set(items),
+    );
+  }, [items]);
+
+  const clear = useCallback(() => setSelected(new Set()), []);
+
+  return {
+    isAllSelected: selected.size === items.length,
+    isSomeSelected: selected.size > 0 && selected.size < items.length,
+    isNoneSelected: selected.size === 0,
+    isSelected,
+    selected: [...selected],
+    setSelected: setItems,
+    select,
+    unselect,
+    toggle,
+    toggleAll,
+    clear,
+  };
+}

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

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