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

package/src/hooks/useFocusTrap/useFocusTrap.ts

@@ -0,0 +1,78 @@
+import { useCallback, useEffect, useRef } from "react";
+import { scopeTab } from "./scopeTab";
+import { FOCUS_SELECTOR, focusable, tabbable } from "./tabbable";
+
+function useFocusTrap(active = true): (instance: HTMLElement | null) => void {
+  const ref = useRef<HTMLElement | null>(null);
+
+  const focusNode = (node: HTMLElement) => {
+    let focusElement: HTMLElement | null =
+      node.querySelector("[data-autofocus]");
+
+    if (!focusElement) {
+      const children = Array.from<HTMLElement>(
+        node.querySelectorAll(FOCUS_SELECTOR),
+      );
+      focusElement =
+        children.find(tabbable) || children.find(focusable) || null;
+      if (!focusElement && focusable(node)) {
+        focusElement = node;
+      }
+    }
+
+    if (focusElement) {
+      focusElement.focus({ preventScroll: true });
+    }
+  };
+
+  const setRef = useCallback(
+    (node: HTMLElement | null) => {
+      if (!active) {
+        return;
+      }
+
+      if (node === null) {
+        return;
+      }
+
+      if (ref.current === node) {
+        return;
+      }
+
+      if (node) {
+        // Delay processing the HTML node by a frame. This ensures focus is assigned correctly.
+        setTimeout(() => {
+          if (node.getRootNode()) {
+            focusNode(node);
+          }
+        });
+
+        ref.current = node;
+      } else {
+        ref.current = null;
+      }
+    },
+    [active],
+  );
+
+  useEffect(() => {
+    if (!active) {
+      return undefined;
+    }
+
+    ref.current && setTimeout(() => focusNode(ref.current!));
+
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key === "Tab" && ref.current) {
+        scopeTab(ref.current, event);
+      }
+    };
+
+    document.addEventListener("keydown", handleKeyDown);
+    return () => document.removeEventListener("keydown", handleKeyDown);
+  }, [active]);
+
+  return setRef;
+}
+
+export default useFocusTrap;

package/src/hooks/useHotkey/__docs__/useHotkey.stories.tsx

@@ -0,0 +1,116 @@
+import { Meta, StoryObj } from "@storybook/react-vite";
+import { HTMLProps, ReactNode, useState } from "react";
+import { cn } from "../../../lib";
+import useHotkey from "../useHotkey";
+
+const meta: Meta = {
+  title: "hooks/useHotkey",
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const generateRandomColor = () => {
+  const letters = "0123456789ABCDEF";
+  let color = "#";
+  for (let i = 0; i < 6; i++) {
+    color += letters[Math.floor(Math.random() * 16)];
+  }
+  return color;
+};
+
+const Kbd = (props: HTMLProps<HTMLDivElement>) => (
+  <kbd
+    {...props}
+    className="inline-block px-3 py-1 text-sm font-semibold text-gray-800 bg-gray-200 border rounded-md shadow-inner border-input"
+  />
+);
+
+const Wrapper = ({ children }: { children: ReactNode }) => (
+  <div>
+    <div className="space-y-2">
+      <div className="flex gap-2">
+        <span>Usa</span>
+        <Kbd>C</Kbd>
+        <span>+</span>
+        <Kbd>R</Kbd>
+        <span>para cambiar el color</span>
+      </div>
+      <div className="flex gap-2">
+        <span>Usa</span>
+        <Kbd>w</Kbd>
+        <Kbd>a</Kbd>
+        <Kbd>s</Kbd>
+        <Kbd>d</Kbd>
+        <span>o</span>
+        <Kbd>&#8593;</Kbd>
+        <Kbd>&#8592;</Kbd>
+        <Kbd>&#8595;</Kbd>
+        <Kbd>&#8594;</Kbd>
+        <span>Para moverte</span>
+      </div>
+    </div>
+    <div className="flex items-center justify-center w-80 h-52">{children}</div>
+  </div>
+);
+
+/**
+ * Opciones
+ *
+ * ```tsx
+ * type HotkeyOptions = {
+ * // Es el evento que se va a utilizar; Keydown, Keyup, Keypress
+ * eventName?: HotkeyEventName;
+ * @default "keydown"
+ * // si se debe prevenir los comandos por defecto del navegador
+ * preventDefault?: boolean;
+ * @default true
+ * // si los comandos se deberían ejecutar mientras el usuario está escribiendo en un input o textarea
+ * ignoreInputFields?: boolean;
+ * @default false
+ * };
+ * ```
+ **/
+export const Default: Story = {
+  render: () => {
+    const [posX, setPosX] = useState(0);
+    const [posY, setPosY] = useState(0);
+    const [color, setColor] = useState("#333333");
+    const [spacePressed, setSpacePressed] = useState(false);
+
+    useHotkey(["ctrl+r"], () => setColor(generateRandomColor()));
+
+    useHotkey(" ", () => {
+      setSpacePressed(true);
+      setTimeout(() => {
+        setSpacePressed(false);
+      }, 300);
+    });
+
+    useHotkey(
+      ["w", "s", "a", "d", "ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight"],
+      (e) => {
+        const { key } = e;
+        if (["w", "ArrowUp"].includes(key)) return setPosY((y) => y - 20);
+        if (["s", "ArrowDown"].includes(key)) return setPosY((y) => y + 20);
+        if (["a", "ArrowLeft"].includes(key)) return setPosX((x) => x - 20);
+        if (["d", "ArrowRight"].includes(key)) return setPosX((x) => x + 20);
+      },
+    );
+
+    return (
+      <Wrapper>
+        <div
+          className={cn(
+            "w-10 h-10 rounded-full",
+            spacePressed && "ring ring-offset-2",
+          )}
+          style={{
+            backgroundColor: color,
+            transform: `translate(${posX}px, ${posY}px)`,
+          }}
+        />
+      </Wrapper>
+    );
+  },
+};

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

@@ -0,0 +1,105 @@
+import { render, waitFor } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { keyboard } from "../../../utils/tests/keyboard";
+import useHotkey, { HotkeyOptions } from "../useHotkey";
+
+describe("useHotkey hook", () => {
+  it("should be defined", () => {
+    expect(useHotkey).toBeDefined();
+  });
+
+  it("should call handler on keydown event", async () => {
+    const handler = vi.fn();
+    const TestComponent = () => {
+      useHotkey("a", handler);
+      return null;
+    };
+
+    render(<TestComponent />);
+
+    keyboard(document, {
+      key: "a",
+    });
+
+    await waitFor(() => {
+      expect(handler).toHaveBeenCalled();
+    });
+  });
+
+  it("should call handler with correct key combination", async () => {
+    const handler = vi.fn();
+    const TestComponent = () => {
+      useHotkey("ctrl+a", handler);
+      return null;
+    };
+
+    render(<TestComponent />);
+
+    keyboard(document, {
+      key: "a",
+      ctrlKey: true,
+    });
+
+    await waitFor(() => {
+      expect(handler).toHaveBeenCalled();
+    });
+  });
+
+  it("should prevent default action if preventDefault is true", async () => {
+    const handler = vi.fn();
+    const TestComponent = () => {
+      useHotkey("b", handler);
+      return null;
+    };
+
+    render(<TestComponent />);
+
+    const event = new KeyboardEvent("keydown", { key: "b" });
+    Object.defineProperty(event, "preventDefault", { value: vi.fn() });
+    document.dispatchEvent(event);
+
+    await waitFor(() => {
+      expect(event.preventDefault).toHaveBeenCalled();
+    });
+  });
+
+  it("should not prevent default action if preventDefault is false", async () => {
+    const handler = vi.fn();
+    const options: HotkeyOptions = { preventDefault: false };
+    const TestComponent = () => {
+      useHotkey("c", handler, options);
+      return null;
+    };
+
+    render(<TestComponent />);
+    const event = new KeyboardEvent("keydown", { key: "c" });
+    Object.defineProperty(event, "preventDefault", { value: vi.fn() });
+    document.dispatchEvent(event);
+
+    await waitFor(() => {
+      expect(event.preventDefault).not.toHaveBeenCalled();
+    });
+  });
+
+  it("should handle multiple keys", async () => {
+    const handler = vi.fn();
+    const TestComponent = () => {
+      useHotkey(["d", "e"], handler);
+      return null;
+    };
+
+    render(<TestComponent />);
+
+    keyboard(document, {
+      key: "d",
+    });
+
+    keyboard(document, {
+      key: "e",
+    });
+
+    await waitFor(() => {
+      expect(handler).toHaveBeenCalledTimes(2);
+    });
+  });
+});

package/src/hooks/useHotkey/__utils__/create-hotkey-listener.ts

@@ -0,0 +1,25 @@
+import { shouldIgnoreEvent } from "./is-input-field";
+import { matchKeyModifiers } from "./match-key-modifiers";
+
+export const createListener = (
+  keys: string | string[],
+  handler: (event: KeyboardEvent) => void,
+  preventDefault: boolean,
+  ignoreInputFields: boolean,
+  watch: boolean,
+) => {
+  return (event: KeyboardEvent) => {
+    if (!watch) return;
+    if (shouldIgnoreEvent(event, ignoreInputFields)) {
+      return;
+    }
+
+    const keyArray = Array.isArray(keys) ? keys : [keys];
+    const match = keyArray.some((key) => matchKeyModifiers(event, key));
+
+    if (match) {
+      preventDefault && event.preventDefault();
+      handler(event);
+    }
+  };
+};

package/src/hooks/useHotkey/__utils__/index.ts

@@ -0,0 +1,3 @@
+export * from "./create-hotkey-listener";
+export * from "./is-input-field";
+export * from "./match-key-modifiers";

package/src/hooks/useHotkey/__utils__/is-input-field.ts

@@ -0,0 +1,14 @@
+export const isInputField = (element: HTMLElement): boolean => {
+  return (
+    element.tagName === "INPUT" ||
+    element.tagName === "TEXTAREA" ||
+    element.isContentEditable
+  );
+};
+
+export const shouldIgnoreEvent = (
+  event: KeyboardEvent,
+  ignoreInputFields: boolean,
+): boolean => {
+  return ignoreInputFields && isInputField(event.target as HTMLElement);
+};

package/src/hooks/useHotkey/__utils__/match-key-modifiers.ts

@@ -0,0 +1,25 @@
+export const getKeyModifiers = (key: string) => {
+  const parts = key.toLowerCase().split("+");
+  const mainKey = parts.pop()!;
+  return {
+    mainKey,
+    isShift: parts.includes("shift"),
+    isCtrl: parts.includes("ctrl"),
+    isAlt: parts.includes("alt"),
+    isMeta: parts.includes("meta"),
+  };
+};
+
+export const matchKeyModifiers = (
+  event: KeyboardEvent,
+  key: string,
+): boolean => {
+  const { mainKey, isShift, isCtrl, isAlt, isMeta } = getKeyModifiers(key);
+  return (
+    event.key.toLowerCase() === mainKey &&
+    event.shiftKey === isShift &&
+    event.ctrlKey === isCtrl &&
+    event.altKey === isAlt &&
+    event.metaKey === isMeta
+  );
+};

package/src/hooks/useHotkey/index.ts

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

package/src/hooks/useHotkey/useHotkey.ts

@@ -0,0 +1,34 @@
+import { useCallback } from "react";
+import { useEventListener } from "../useEventListener";
+import { createListener } from "./__utils__";
+
+export type Keys = string | string[];
+export type HotkeyEventName = "keydown" | "keypress" | "keyup";
+export type HotkeyOptions = {
+  watch?: boolean;
+  eventName?: HotkeyEventName;
+  preventDefault?: boolean;
+  ignoreInputFields?: boolean;
+};
+
+function useHotkey(
+  keys: string | string[],
+  handler: (event: KeyboardEvent) => void,
+  options: HotkeyOptions = {},
+) {
+  const {
+    eventName = "keydown",
+    preventDefault = true,
+    ignoreInputFields = true,
+    watch = true,
+  } = options;
+
+  const listener = useCallback(
+    createListener(keys, handler, preventDefault, ignoreInputFields, watch),
+    [keys, handler, preventDefault, ignoreInputFields, watch],
+  );
+
+  return useEventListener(eventName, listener);
+}
+
+export default useHotkey;

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

@@ -0,0 +1,41 @@
+import { Meta } from "@storybook/react-vite";
+import { cn } from "../../../lib";
+import useHover from "../useHover";
+
+/**
+ * Hook que facilita el manejo de un estado booleano. Provee métodos para abrir, cerrar y toggle el estado
+ */
+const meta: Meta = {
+  title: "hooks/useHover",
+};
+
+export default meta;
+
+export const Default = {
+  render: () => {
+    const { ref, isHovering } = useHover<HTMLDivElement>();
+
+    return (
+      <div className="space-y-2">
+        <div
+          ref={ref}
+          className={cn(
+            "rounded transition-colors w-32 h-32 shadow text-3xl grid place-items-center cursor-pointer",
+            { "bg-accent": isHovering },
+          )}
+        >
+          🍅
+        </div>
+
+        <pre className="rounded-md bg-slate-950 p-4 text-white">
+          <code className="block">
+            hover?:{" "}
+            <span className={isHovering ? "text-green-500" : "text-red-500"}>
+              {JSON.stringify(isHovering, null, 2)}
+            </span>
+          </code>
+        </pre>
+      </div>
+    );
+  },
+};

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

@@ -0,0 +1,45 @@
+import { fireEvent } from "@testing-library/dom";
+import { render, screen, waitFor } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import useHover from "../useHover";
+
+describe("useHover hook", () => {
+  it("should be defined", () => {
+    expect(useHover).toBeDefined();
+  });
+
+  it("should handle hover start and end events", async () => {
+    const handleHoverStart = vi.fn();
+    const handleHoverEnd = vi.fn();
+
+    const Component = () => {
+      const { ref, isHovering } = useHover<HTMLDivElement>({
+        onHoverStart: handleHoverStart,
+        onHoverEnd: handleHoverEnd,
+      });
+      return (
+        <div ref={ref} data-testid="hover-target">
+          {isHovering ? "Hovering" : "Not Hovering"}
+        </div>
+      );
+    };
+
+    render(<Component />);
+
+    const target = screen.getByTestId("hover-target");
+
+    fireEvent.mouseOver(target);
+
+    await waitFor(() => {
+      expect(handleHoverStart).toHaveBeenCalled();
+      expect(target.textContent).toBe("Hovering");
+    });
+
+    fireEvent.mouseOut(target);
+
+    await waitFor(() => {
+      expect(handleHoverEnd).toHaveBeenCalled();
+      expect(target.textContent).toBe("Not Hovering");
+    });
+  });
+});

package/src/hooks/useHover/index.ts

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

package/src/hooks/useHover/useHover.tsx

@@ -0,0 +1,40 @@
+import { useEffect, useRef, useState } from "react";
+
+type UseHoverOptions = {
+  onHoverStart?: (event: MouseEvent) => void;
+  onHoverEnd?: (event: MouseEvent) => void;
+};
+
+function useHover<T extends HTMLElement>(
+  options?: UseHoverOptions,
+): { ref: React.RefObject<T | null>; isHovering: boolean } {
+  const [isHovering, setIsHovering] = useState(false);
+  const ref = useRef<T | null>(null);
+
+  useEffect(() => {
+    const handleMouseOver = (event: MouseEvent) => {
+      setIsHovering(true);
+      options?.onHoverStart?.(event);
+    };
+
+    const handleMouseOut = (event: MouseEvent) => {
+      setIsHovering(false);
+      options?.onHoverEnd?.(event);
+    };
+
+    const node = ref.current;
+    if (node) {
+      node.addEventListener("mouseover", handleMouseOver);
+      node.addEventListener("mouseout", handleMouseOut);
+
+      return () => {
+        node.removeEventListener("mouseover", handleMouseOver);
+        node.removeEventListener("mouseout", handleMouseOut);
+      };
+    }
+  }, [options]);
+
+  return { ref, isHovering };
+}
+
+export default useHover;

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

@@ -0,0 +1,60 @@
+import { Meta, StoryObj } from "@storybook/react-vite";
+import { ArrowDown } from "lucide-react";
+import { ReactNode } from "react";
+import { createToastManager, ToastProvider } from "../../../components/toast";
+import useIsVisible from "../useIsVisible";
+
+const toastManager = createToastManager();
+
+/**
+ * Hook que permite detectar si un elemento es visible para el usuario
+ *
+ * Extiende la API de `IntersectionObserver`
+ */
+const meta: Meta = {
+  title: "hooks/useIsVisible",
+  decorators: [
+    (Story) => (
+      <ToastProvider toastManager={toastManager}>
+        <Story />
+      </ToastProvider>
+    ),
+  ],
+};
+
+export default meta;
+
+const Wrapper = ({ children }: { children: ReactNode }) => {
+  return (
+    <div className="h-[200px] border rounded overflow-y-scroll">{children}</div>
+  );
+};
+export const Default: StoryObj = {
+  render: () => {
+    const { ref, isVisible } = useIsVisible<HTMLDivElement>({
+      onVisible: () =>
+        toastManager.add({
+          variant: "success",
+          description: "El elemento es visible",
+        }),
+    });
+
+    return (
+      <>
+        <div className="flex items-center gap-x-2">
+          <span>Scroll</span>
+          <ArrowDown className="animate-bounce" />
+        </div>
+
+        <Wrapper>
+          <div
+            ref={ref}
+            className={`transition-colors p-2 rounded text-primary-foreground duration-1000 mt-[400px] ${isVisible ? "bg-primary" : "bg-error"}`}
+          >
+            {isVisible ? "El elemento es visible" : "El elemento no es visible"}
+          </div>
+        </Wrapper>
+      </>
+    );
+  },
+};

package/src/hooks/useIsVisible/index.ts

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

package/src/hooks/useIsVisible/useIsVisible.tsx

@@ -0,0 +1,50 @@
+import { RefObject, useCallback, useEffect, useRef, useState } from "react";
+
+interface UseIsVisibleProps extends IntersectionObserverInit {
+  onVisible?: () => void;
+}
+
+interface UseIsVisibleReturn<T> {
+  ref: RefObject<T | null>;
+  isVisible: boolean;
+}
+
+function useIsVisible<T extends HTMLElement>({
+  onVisible,
+  root = null,
+  rootMargin = "0px",
+  threshold = 0,
+}: UseIsVisibleProps = {}): UseIsVisibleReturn<T> {
+  const [isVisible, setIsVisible] = useState<boolean>(false);
+  const ref = useRef<T | null>(null);
+
+  const handleIntersect: IntersectionObserverCallback = useCallback(
+    ([entry]) => {
+      const isIntersecting = entry.isIntersecting;
+      setIsVisible(isIntersecting);
+    },
+    [onVisible],
+  );
+
+  useEffect(() => {
+    if (ref.current == null) return;
+    const observer = new IntersectionObserver(handleIntersect, {
+      root,
+      rootMargin,
+      threshold,
+    });
+    observer.observe(ref.current);
+    return () => {
+      if (ref.current == null) return;
+      observer.unobserve(ref.current);
+    };
+  }, [ref, root, rootMargin, threshold, handleIntersect]);
+
+  useEffect(() => {
+    isVisible && onVisible?.();
+  }, [isVisible]);
+
+  return { ref, isVisible };
+}
+
+export default useIsVisible;