@boxcustodia/library 2.0.0-alpha.11 → 2.0.0-alpha.13

package/src/hooks/useDebounceCallback/__doc__/useDebouncedCallback.stories.tsx

@@ -0,0 +1,84 @@
+import { Meta, StoryObj } from "@storybook/react-vite";
+import { Heading, Input } from "../../../components";
+import { createToastManager, ToastProvider } from "../../../components/toast";
+import { useDebouncedCallback } from "../../useDebounceCallback";
+
+const toastManager = createToastManager();
+
+const meta: Meta = {
+  title: "hooks/useDebouncedCallback",
+  decorators: [
+    (Story) => (
+      <ToastProvider toastManager={toastManager}>
+        <Story />
+      </ToastProvider>
+    ),
+  ],
+};
+
+export default meta;
+
+export const Basic = {
+  render: () => {
+    const handleSearch = useDebouncedCallback((value: string) => {
+      console.log("Búsqueda con:", value);
+      toastManager.add({
+        variant: "success",
+        description: `Búsqueda realizada con: ${value}`,
+      });
+    }, 600);
+
+    return (
+      <div className="space-y-2">
+        <pre className="rounded-md bg-slate-950 p-4 text-white">
+          <code className="block">
+            Escribe en el input para ver el callback debounced en acción.
+          </code>
+          <code className="block">Revisa la consola para ver los logs.</code>
+        </pre>
+        <Input
+          onChange={(value) => handleSearch(value)}
+          placeholder="Escribe para buscar..."
+        />
+      </div>
+    );
+  },
+};
+
+export const DifferentDelays: StoryObj = {
+  render: () => {
+    const handleFastDebounce = useDebouncedCallback((value: string) => {
+      toastManager.add({
+        variant: "success",
+        description: `Debounce rápido (200ms): ${value}`,
+      });
+    }, 200);
+
+    const handleSlowDebounce = useDebouncedCallback((value: string) => {
+      toastManager.add({
+        variant: "success",
+        description: `Debounce lento (1000ms): ${value}`,
+      });
+    }, 1000);
+
+    return (
+      <div className="space-y-4">
+        <div>
+          <Heading>Debounce Rápido (200ms)</Heading>
+          <Input
+            onChange={(value) => handleFastDebounce(value)}
+            placeholder="Debounce rápido..."
+          />
+        </div>
+
+        <div>
+          <Heading>Debounce Lento (1000ms)</Heading>
+          <Input
+            onChange={(value) => handleSlowDebounce(value)}
+            placeholder="Debounce lento..."
+          />
+        </div>
+      </div>
+    );
+  },
+};

package/src/hooks/useDebounceCallback/index.ts

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

package/src/hooks/useDebounceCallback/useDebouncedCallback.ts

@@ -0,0 +1,23 @@
+import { useCallback, useRef } from "react";
+
+function useDebouncedCallback<T extends (...args: any[]) => any>(
+  callback: T,
+  delay: number,
+): (...args: Parameters<T>) => void {
+  const timeoutRef = useRef<NodeJS.Timeout | null>(null);
+
+  return useCallback(
+    (...args: Parameters<T>) => {
+      if (timeoutRef.current) {
+        clearTimeout(timeoutRef.current);
+      }
+
+      timeoutRef.current = setTimeout(() => {
+        callback(...args);
+      }, delay);
+    },
+    [callback, delay],
+  );
+}
+
+export default useDebouncedCallback;

package/src/hooks/useDebounceValue/__doc__/useDebouncedValue.stories.tsx

@@ -0,0 +1,75 @@
+import { Meta, StoryObj } from "@storybook/react-vite";
+import { useState } from "react";
+import { Input } from "../../../components";
+import { useDebouncedValue } from "../../useDebounceValue";
+
+const meta: Meta = {
+  title: "hooks/useDebouncedValue",
+};
+
+export default meta;
+
+export const Basic = {
+  render: () => {
+    const [value, setValue] = useState<string>("");
+    const debouncedValue: string = useDebouncedValue(value, 400);
+
+    return (
+      <div className="space-y-2">
+        <pre className="rounded-md bg-slate-950 p-4 text-white">
+          <code className="block">
+            Valor actual: <span className="text-blue-300">{value}</span>
+          </code>
+          <code className="block">
+            Valor debounced:{" "}
+            <span className="text-blue-300">{debouncedValue}</span>
+          </code>
+        </pre>
+        <Input
+          value={value}
+          onChange={setValue}
+          placeholder="Escribe algo..."
+        />
+      </div>
+    );
+  },
+};
+
+export const MultipleDelays: StoryObj = {
+  render: () => {
+    const [value, setValue] = useState<string>("");
+    const debouncedFast: string = useDebouncedValue(value, 200);
+    const debouncedMedium: string = useDebouncedValue(value, 500);
+    const debouncedSlow: string = useDebouncedValue(value, 1000);
+
+    return (
+      <div className="space-y-4">
+        <Input
+          value={value}
+          onChange={setValue}
+          placeholder="Escribe para ver diferentes delays..."
+        />
+
+        <div className="space-y-2">
+          <pre className="rounded-md bg-slate-950 p-4 text-white">
+            <code className="block">
+              Valor actual: <span className="text-blue-300">{value}</span>
+            </code>
+            <code className="block">
+              Debounced (200ms):{" "}
+              <span className="text-blue-300">{debouncedFast}</span>
+            </code>
+            <code className="block">
+              Debounced (500ms):{" "}
+              <span className="text-blue-300">{debouncedMedium}</span>
+            </code>
+            <code className="block">
+              Debounced (1000ms):{" "}
+              <span className="text-blue-300">{debouncedSlow}</span>
+            </code>
+          </pre>
+        </div>
+      </div>
+    );
+  },
+};

package/src/hooks/useDebounceValue/index.ts

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

package/src/hooks/useDebounceValue/useDebouncedValue.ts

@@ -0,0 +1,17 @@
+import { useEffect, useState } from "react";
+
+function useDebouncedValue<T>(value: T, delay: number): T {
+  const [debouncedValue, setDebouncedValue] = useState<T>(value);
+
+  useEffect(() => {
+    const timeout = setTimeout(() => {
+      setDebouncedValue(value);
+    }, delay);
+
+    return () => clearTimeout(timeout);
+  }, [value, delay]);
+
+  return debouncedValue;
+}
+
+export default useDebouncedValue;

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

@@ -0,0 +1,39 @@
+import { Meta } from "@storybook/react-vite";
+import { Button } from "../../../components";
+import { cn } from "../../../lib";
+import useDisclosure from "../useDisclosure";
+
+/**
+ * Hook que facilita el manejo de un estado booleano. Provee métodos para abrir, cerrar y toggle el estado
+ */
+const meta: Meta = {
+  title: "hooks/useDisclosure",
+};
+
+export default meta;
+
+export const Default = {
+  render: () => {
+    const [isOpen, { open, close, toggle }] = useDisclosure();
+
+    return (
+      <div>
+        <div
+          onClick={toggle}
+          className={cn(
+            "rounded transition-colors w-32 h-32 shadow text-3xl grid place-items-center cursor-pointer",
+            { "bg-accent": isOpen },
+          )}
+        >
+          🍅
+        </div>
+
+        <div className="flex gap-2 mt-2">
+          <Button onClick={open}>Abrir</Button>
+          <Button onClick={close}>Cerrar</Button>
+          <Button onClick={toggle}>Toggle</Button>
+        </div>
+      </div>
+    );
+  },
+};

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

@@ -0,0 +1,43 @@
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import useDisclosure from "../useDisclosure";
+
+describe("useDisclosure hook", () => {
+  it("should be defined", () => {
+    const { result } = renderHook(useDisclosure);
+    expect(result.current).toBeDefined();
+  });
+
+  it("should open", () => {
+    const { result } = renderHook(useDisclosure);
+    const [state, { open }] = result.current;
+    expect(state).toBe(false);
+    act(() => open());
+
+    waitFor(() => {
+      expect(state).toBe(true);
+    });
+  });
+
+  it("should close", () => {
+    const { result } = renderHook(useDisclosure);
+    const [state, { close }] = result.current;
+    expect(state).toBe(false);
+    act(() => close());
+
+    waitFor(() => {
+      expect(state).toBe(false);
+    });
+  });
+
+  it("should toggle", () => {
+    const { result } = renderHook(useDisclosure);
+    const [state, { toggle }] = result.current;
+    expect(state).toBe(false);
+    act(() => toggle());
+
+    waitFor(() => {
+      expect(state).toBe(true);
+    });
+  });
+});

package/src/hooks/useDisclosure/index.ts

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

package/src/hooks/useDisclosure/useDisclosure.ts

@@ -0,0 +1,37 @@
+import { useCallback, useState } from "react";
+
+function useDisclosure(
+  initialState = false,
+  callbacks?: { onOpen?: () => void; onClose?: () => void },
+) {
+  const { onOpen, onClose } = callbacks || {};
+  const [isOpen, setIsOpen] = useState(initialState);
+
+  const open = useCallback(() => {
+    setIsOpen((isOpened) => {
+      if (!isOpened) {
+        onOpen?.();
+        return true;
+      }
+      return isOpened;
+    });
+  }, [onOpen]);
+
+  const close = useCallback(() => {
+    setIsOpen((isOpened) => {
+      if (isOpened) {
+        onClose?.();
+        return false;
+      }
+      return isOpened;
+    });
+  }, [onClose]);
+
+  const toggle = useCallback(() => {
+    isOpen ? close() : open();
+  }, [close, open, isOpen]);
+
+  return [isOpen, { open, close, toggle }] as const;
+}
+
+export default useDisclosure;

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

@@ -0,0 +1,26 @@
+import { Meta, StoryObj } from "@storybook/react-vite";
+import { useState } from "react";
+import { Button, Input } from "../../../components";
+import useDocumentTitle from "../useDocumentTitle";
+
+const meta: Meta = {
+  title: "hooks/useDocumentTitle",
+};
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () => {
+    const [title, setTitle] = useState("");
+    useDocumentTitle(title);
+
+    return (
+      <div className="space-y-2">
+        <Input onChange={setTitle} value={title} />
+        <Button onClick={() => setTitle(title)}>Set document title</Button>
+      </div>
+    );
+  },
+};

package/src/hooks/useDocumentTitle/index.ts

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

package/src/hooks/useDocumentTitle/useDocumentTitle.tsx

@@ -0,0 +1,11 @@
+import { useEffect } from "react";
+
+function useDocumentTitle(title: string) {
+  useEffect(() => {
+    if (typeof title === "string" && title.trim().length > 0) {
+      document.title = title.trim();
+    }
+  }, [title]);
+}
+
+export default useDocumentTitle;

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

@@ -0,0 +1,28 @@
+import { Meta } from "@storybook/react-vite";
+import { action } from "storybook/actions";
+import { Button } from "../../../components";
+import useEventListener from "../useEventListener";
+
+/**
+ * Hook que facilita el manejor de eventos
+ *
+ * Evita tener que hacer el `useEffect` con el cleanup
+ */
+const meta: Meta = {
+  title: "hooks/useEventListener",
+};
+
+export default meta;
+
+/**
+ * ```tsx
+ * const ref = useEventListener<HTMLELEMENT>("EVENT_KEY", callback);
+ * return <HTMLELEMENT ref={ref} />;
+ * ```
+ */
+export const Default = {
+  render: () => {
+    const ref = useEventListener("click", action("click"));
+    return <Button ref={ref}>click me</Button>;
+  },
+};

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

@@ -0,0 +1,26 @@
+import { screen } from "@testing-library/dom";
+import { render, waitFor } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { click } from "../../../utils";
+import useEventListener from "../useEventListener";
+
+describe("useEventListener hook", () => {
+  it("should be defined", () => {
+    expect(useEventListener).toBeDefined();
+  });
+
+  it("should handle event", () => {
+    const handleEvent = vi.fn();
+    const Component = () => {
+      const ref = useEventListener("click", handleEvent);
+      return <div ref={ref} data-testid="target" />;
+    };
+    render(<Component />);
+
+    click(screen.getByTestId("target"));
+
+    waitFor(() => {
+      expect(handleEvent).toHaveBeenCalled();
+    });
+  });
+});

package/src/hooks/useEventListener/index.ts

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

package/src/hooks/useEventListener/useEventListener.ts

@@ -0,0 +1,25 @@
+import { useEffect, useRef } from "react";
+
+function useEventListener<
+  K extends keyof HTMLElementEventMap,
+  T extends HTMLElement = any,
+>(
+  type: K,
+  listener: (this: HTMLDivElement, ev: HTMLElementEventMap[K]) => any,
+  options?: boolean | AddEventListenerOptions,
+) {
+  const ref = useRef<T | null>(null);
+
+  useEffect(() => {
+    const target = ref.current ?? document;
+
+    target.addEventListener(type, listener as EventListener, options);
+    return () => {
+      target.removeEventListener(type, listener as EventListener, options);
+    };
+  }, [type, listener, options]);
+
+  return ref;
+}
+
+export default useEventListener;

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

@@ -0,0 +1,37 @@
+import { Meta } from "@storybook/react-vite";
+import { useState } from "react";
+import { Button, Checkbox } from "../../../components";
+import useFocusTrap from "../useFocusTrap";
+
+/**
+ * Hook que atrapa el focus en un scope
+ */
+const meta: Meta = {
+  title: "hooks/useFocusTrap",
+};
+
+export default meta;
+
+export const Default = {
+  render: () => {
+    const [active, setActive] = useState(true);
+    const trapRefContainer = useFocusTrap();
+    const trapRef = useFocusTrap(active);
+
+    return (
+      <div ref={trapRefContainer} className="space-y-2">
+        <div className="py-4">
+          <Checkbox name="1" />
+          <div ref={trapRef}>
+            <Checkbox name="2" />
+            <Checkbox name="3" />
+          </div>
+          <Checkbox name="4" />
+        </div>
+        <Button onClick={() => setActive(!active)}>
+          {active ? "Desactivar" : "Activar"}
+        </Button>
+      </div>
+    );
+  },
+};

package/src/hooks/useFocusTrap/index.ts

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

package/src/hooks/useFocusTrap/scopeTab.ts

@@ -0,0 +1,38 @@
+import { findTabbableDescendants } from "./tabbable";
+
+export function scopeTab(node: HTMLElement, event: KeyboardEvent) {
+  const tabbable = findTabbableDescendants(node);
+  if (!tabbable.length) {
+    event.preventDefault();
+    return;
+  }
+  const finalTabbable = tabbable[event.shiftKey ? 0 : tabbable.length - 1];
+  const root = node.getRootNode() as unknown as DocumentOrShadowRoot;
+  let leavingFinalTabbable =
+    finalTabbable === root.activeElement || node === root.activeElement;
+
+  const activeElement = root.activeElement as Element;
+  const activeElementIsRadio =
+    activeElement.tagName === "INPUT" &&
+    activeElement.getAttribute("type") === "radio";
+  if (activeElementIsRadio) {
+    const activeRadioGroup = tabbable.filter(
+      (element) =>
+        element.getAttribute("type") === "radio" &&
+        element.getAttribute("name") === activeElement.getAttribute("name"),
+    );
+    leavingFinalTabbable = activeRadioGroup.includes(finalTabbable);
+  }
+
+  if (!leavingFinalTabbable) {
+    return;
+  }
+
+  event.preventDefault();
+
+  const target = tabbable[event.shiftKey ? tabbable.length - 1 : 0];
+
+  if (target) {
+    (target as HTMLElement).focus();
+  }
+}

package/src/hooks/useFocusTrap/tabbable.ts

@@ -0,0 +1,70 @@
+const TABBABLE_NODES = /input|select|textarea|button|object/;
+export const FOCUS_SELECTOR =
+  "a, input, select, textarea, button, object, [tabindex]";
+
+function hidden(element: HTMLElement) {
+  if (process.env.NODE_ENV === "test") {
+    return false;
+  }
+
+  return element.style.display === "none";
+}
+
+function visible(element: HTMLElement) {
+  const isHidden =
+    element.getAttribute("aria-hidden") ||
+    element.getAttribute("hidden") ||
+    element.getAttribute("type") === "hidden";
+
+  if (isHidden) {
+    return false;
+  }
+
+  let parentElement: HTMLElement = element;
+  while (parentElement) {
+    if (parentElement === document.body || parentElement.nodeType === 11) {
+      break;
+    }
+
+    if (hidden(parentElement)) {
+      return false;
+    }
+
+    parentElement = parentElement.parentNode as HTMLElement;
+  }
+
+  return true;
+}
+
+function getElementTabIndex(element: HTMLElement) {
+  let tabIndex: string | null | undefined = element.getAttribute("tabindex");
+  if (tabIndex === null) {
+    tabIndex = undefined;
+  }
+  return parseInt(tabIndex as string, 10);
+}
+
+export function focusable(element: HTMLElement) {
+  const nodeName = element.nodeName.toLowerCase();
+  const isTabIndexNotNaN = !Number.isNaN(getElementTabIndex(element));
+  const res =
+    // @ts-expect-error function accepts any html element but if it is a button, it should not be disabled to trigger the condition
+    (TABBABLE_NODES.test(nodeName) && !element.disabled) ||
+    (element instanceof HTMLAnchorElement
+      ? element.href || isTabIndexNotNaN
+      : isTabIndexNotNaN);
+
+  return res && visible(element);
+}
+
+export function tabbable(element: HTMLElement) {
+  const tabIndex = getElementTabIndex(element);
+  const isTabIndexNaN = Number.isNaN(tabIndex);
+  return (isTabIndexNaN || tabIndex >= 0) && focusable(element);
+}
+
+export function findTabbableDescendants(element: HTMLElement): HTMLElement[] {
+  return Array.from(
+    element.querySelectorAll<HTMLElement>(FOCUS_SELECTOR),
+  ).filter(tabbable);
+}