@boxcustodia/library 2.0.0-alpha.10 → 2.0.0-alpha.12

package/src/hooks/useRangePagination/__test__/useRangePagination.test.tsx

@@ -0,0 +1,63 @@
+import { renderHook } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import useRangePagination, { DOTS } from "../useRangePagination";
+
+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/useRangePagination/index.ts

@@ -0,0 +1,2 @@
+export * from "./useRangePagination";
+export { default as useRangePagination } from "./useRangePagination";

package/src/hooks/useRangePagination/useRangePagination.tsx

@@ -0,0 +1,72 @@
+import { range } from "lodash";
+import { useMemo } from "react";
+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;
+
+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 ?? [],
+  };
+};
+
+export default useRangePagination;

package/src/hooks/useSelection/__doc__/useSelection.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 "../useSelection";
+
+/**
+ * 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/useSelection/__test__/useSelection.test.tsx

@@ -0,0 +1,57 @@
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import useSelection from "../useSelection";
+
+describe("useSelection hook", () => {
+  it("should be defined", () => {
+    const items = [1, 2, 3];
+    const { result } = renderHook(() => useSelection(items));
+    const { isAllSelected, isNoneSelected } = result.current;
+
+    expect(isAllSelected).toBe(false);
+    expect(isNoneSelected).toBe(true);
+  });
+
+  it("should select all", () => {
+    const items = [1, 2, 3];
+    const { result } = renderHook(() => useSelection(items));
+    const { toggleAll } = result.current;
+
+    act(() => toggleAll());
+    expect(result.current.isAllSelected).toBe(true);
+    expect(result.current.isNoneSelected).toBe(false);
+  });
+
+  it("should select item", () => {
+    const items = [1, 2, 3];
+    const { result } = renderHook(() => useSelection(items));
+    const { select } = result.current;
+
+    act(() => select(2));
+    expect(result.current.isSelected(2)).toBe(true);
+  });
+
+  it("should unselect item", () => {
+    const items = [1, 2, 3];
+    const { result } = renderHook(() => useSelection(items));
+    const { select } = result.current;
+
+    act(() => select(2));
+    expect(result.current.isSelected(2)).toBe(true);
+
+    act(() => select(2));
+    waitFor(() => {
+      expect(result.current.isSelected(2)).toBe(false);
+    });
+  });
+
+  it("should clear selections", () => {
+    const items = [1, 2, 3];
+    const { result } = renderHook(() => useSelection(items));
+    const { clear } = result.current;
+
+    act(() => clear());
+    expect(result.current.isAllSelected).toBe(false);
+    expect(result.current.isNoneSelected).toBe(true);
+  });
+});

package/src/hooks/useSelection/index.ts

@@ -0,0 +1 @@
+export { default as useSelection } from "./useSelection";

package/src/hooks/useSelection/useSelection.ts

@@ -0,0 +1,121 @@
+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;
+};
+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,
+  };
+}
+
+export default useSelection;

package/src/hooks/useStep/__doc__/useStep.stories.tsx

@@ -0,0 +1,98 @@
+import { Meta } from "@storybook/react-vite";
+import { Button } from "../../../components";
+import { cn } from "../../../lib";
+import useStep from "../useStep";
+
+/**
+ * Hook que recibe un array de elementos `T` y facita el manejo de vistas/formularios con múltiples pasos
+ */
+const meta: Meta = {
+  title: "hooks/useStep",
+  tags: ["autodocs"],
+};
+
+export default meta;
+
+export const Default = {
+  render: () => {
+    const data = [
+      {
+        id: 1,
+        content: "🚌",
+      },
+      {
+        id: 2,
+        content: "🚗",
+      },
+      {
+        id: 3,
+        content: "🚕",
+      },
+    ];
+    const {
+      steps,
+      back,
+      next,
+      goTo,
+      step,
+      isLastStep,
+      isFirstStep,
+      currentStepIndex,
+    } = useStep(data);
+
+    return (
+      <div>
+        <div className="flex gap-x-12">
+          {data.map((transporte) => (
+            <div
+              key={transporte.id}
+              className={cn(
+                "bg-popover grow rounded text-center shadow p-14 text-3xl",
+                step.id === transporte.id && "bg-accent",
+              )}
+            >
+              {transporte.content}
+            </div>
+          ))}
+        </div>
+
+        <div className="my-2 flex flex-wrap gap-2">
+          <Button onClick={back} disabled={isFirstStep}>
+            Back
+          </Button>
+          <Button onClick={next} disabled={isLastStep}>
+            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)}
+            </span>
+          </code>
+          <code className="block">
+            isLastStep:{" "}
+            <span className={isLastStep ? "text-green-500" : "text-red-500"}>
+              {JSON.stringify(isLastStep)}
+            </span>
+          </code>
+        </pre>
+      </div>
+    );
+  },
+};

package/src/hooks/useStep/__test__/useStep.test.ts

@@ -0,0 +1,51 @@
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { useStep } from "../../../hooks";
+
+describe("useStep hook", () => {
+  it("should be defined", () => {
+    expect(useStep).toBeDefined();
+  });
+
+  it("should return the current step", () => {
+    const steps = ["step1", "step2", "step3"];
+    const { result } = renderHook(() => useStep(steps));
+
+    expect(result.current.currentStepIndex).toBe(0);
+    expect(result.current.isFirstStep).toBe(true);
+  });
+
+  it("should go to the next and prev step", () => {
+    const steps = ["step1", "step2", "step3"];
+    const { result } = renderHook(() => useStep(steps));
+
+    // go next
+    act(() => result.current.next());
+
+    waitFor(() => {
+      expect(result.current.currentStepIndex).toBe(1);
+      expect(result.current.isFirstStep).toBe(false);
+    });
+
+    // go back
+    act(() => result.current.back());
+
+    waitFor(() => {
+      expect(result.current.currentStepIndex).toBe(0);
+      expect(result.current.isFirstStep).toBe(true);
+    });
+  });
+
+  it("should go to specified step", () => {
+    const steps = ["step1", "step2", "step3"];
+    const { result } = renderHook(() => useStep(steps));
+
+    act(() => result.current.goTo(2));
+
+    waitFor(() => {
+      expect(result.current.currentStepIndex).toBe(2);
+      expect(result.current.isFirstStep).toBe(false);
+      expect(result.current.isLastStep).toBe(true);
+    });
+  });
+});

package/src/hooks/useStep/index.ts

@@ -0,0 +1 @@
+export { default as useStep } from "./useStep";

package/src/hooks/useStep/useStep.ts

@@ -0,0 +1,57 @@
+import { findIndex, ListIterateeCustom } from "lodash";
+import { ReactNode, useState } from "react";
+
+interface Return<T = ReactNode> {
+  currentStepIndex: number;
+  step: T;
+  steps: T[];
+  isFirstStep: boolean;
+  isLastStep: boolean;
+  goTo: (i: number) => void;
+  next: () => void;
+  back: () => void;
+  findAndGo: (callback: ListIterateeCustom<T, boolean>) => void;
+}
+
+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 = (t: ListIterateeCustom<T, boolean>): void => {
+    const stepIndex = findIndex(steps, t);
+    if (stepIndex === -1) return;
+    goTo(stepIndex);
+  };
+
+  return {
+    currentStepIndex,
+    step: steps[currentStepIndex],
+    steps,
+    isFirstStep: currentStepIndex === 0,
+    isLastStep: currentStepIndex === length - 1,
+    goTo,
+    next,
+    back,
+    findAndGo,
+  };
+}
+
+export default useStep;

package/src/hooks/useToggle/__doc__/useToggle.stories.tsx

@@ -0,0 +1,25 @@
+import { Meta } from "@storybook/react-vite";
+import { Button, Checkbox } from "../../../components";
+import useToggle from "../useToggle";
+
+/**
+ * Hook que facilita el manejo de un estado booleano. Provee métodos para abrir, cerrar y toggle el estado
+ */
+const meta: Meta = {
+  title: "hooks/useToggle",
+};
+
+export default meta;
+
+export const Default = {
+  render: () => {
+    const [isOpen, toggle] = useToggle();
+
+    return (
+      <div className="space-y-2">
+        <Checkbox name="open" checked={isOpen} />
+        <Button onClick={() => toggle()}>Toggle</Button>
+      </div>
+    );
+  },
+};