@boxcustodia/library 2.0.0-alpha.17 → 2.0.0-alpha.19

package/src/hooks/index.ts

@@ -1,26 +1,27 @@
 export { useControllableState } from "@radix-ui/react-use-controllable-state";
-export * from "./useArray";
-export * from "./useAsync";
-export * from "./useClickOutside";
-export * from "./useClipboard";
-export * from "./useDebounceCallback";
-export * from "./useDebounceValue";
-export * from "./useDisclosure";
-export * from "./useDocumentTitle";
-export * from "./useEventListener";
-export * from "./useFocusTrap";
-export * from "./useHotkey";
-export * from "./useHover";
-export * from "./useIsVisible";
-export * from "./useLocalStorage";
-export * from "./useMediaQuery";
-export * from "./useMemoizedFn";
-export * from "./useMutation";
-export * from "./useObject";
-export * from "./usePagination";
-export * from "./usePortal";
-export * from "./usePreventCloseWindow";
-export * from "./useRangePagination";
-export * from "./useSelection";
-export * from "./useStep";
-export * from "./useToggle";
+export * from "./use-array";
+export * from "./use-async";
+export * from "./use-click-outside";
+export * from "./use-clipboard";
+export * from "./use-debounce-callback";
+export * from "./use-debounce-value";
+export * from "./use-disclosure";
+export * from "./use-document-title";
+export * from "./use-event-listener";
+export * from "./use-focus-trap";
+export * from "./use-hotkey";
+export * from "./use-hover";
+export * from "./use-is-visible";
+export * from "./use-local-storage";
+export * from "./use-media-query";
+export * from "./use-memoized-fn";
+export * from "./use-mutation";
+export * from "./use-object";
+export * from "./use-on-mount";
+export * from "./use-pagination";
+export * from "./use-portal";
+export * from "./use-prevent-close-window";
+export * from "./use-range-pagination";
+export * from "./use-selection";
+export * from "./use-step";
+export * from "./use-toggle";

package/src/hooks/internal/index.ts

@@ -0,0 +1,2 @@
+export { isBrowser } from "./is-browser";
+export { useIsomorphicLayoutEffect } from "./use-isomorphic-layout-effect";

package/src/hooks/internal/is-browser.ts

@@ -0,0 +1 @@
+export const isBrowser = typeof window !== "undefined";

package/src/hooks/internal/use-isomorphic-layout-effect.ts

@@ -0,0 +1,4 @@
+import { useEffect, useLayoutEffect } from "react";
+import { isBrowser } from "./is-browser";
+
+export const useIsomorphicLayoutEffect = isBrowser ? useLayoutEffect : useEffect;

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

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

package/src/hooks/{useArray/__doc__/useArray.stories.tsx → use-array/use-array.stories.tsx}

@@ -1,7 +1,7 @@
 import { Meta, StoryObj } from "@storybook/react-vite";
 import { Trash } from "lucide-react";
-import { Button } from "../../../components";
-import useArray from "../useArray";
+import { Button } from "../../components";
+import { useArray } from "../use-array";
 
 /**
  * Hook que facilita el manejo de estado de una lista

package/src/hooks/{useArray/__test__/useArray.test.tsx → use-array/use-array.test.tsx}

@@ -1,6 +1,6 @@
 import { act, renderHook } from "@testing-library/react";
 import { describe, expect, it } from "vitest";
-import useArray from "../useArray";
+import { useArray } from "../use-array";
 
 describe("useArray hook", () => {
   it("should initialize with default value", () => {
@@ -85,4 +85,28 @@ describe("useArray hook", () => {
 
     expect(result.current[0]).toEqual(["First", "Updated", "Third"]);
   });
+
+  it("pop removes last item", () => {
+    const { result } = renderHook(() => useArray(["a", "b", "c"]));
+    act(() => result.current[1].pop());
+    expect(result.current[0]).toEqual(["a", "b"]);
+  });
+
+  it("set replaces entire list", () => {
+    const { result } = renderHook(() => useArray(["a", "b"]));
+    act(() => result.current[1].set(["x", "y", "z"]));
+    expect(result.current[0]).toEqual(["x", "y", "z"]);
+  });
+
+  it("update with function callback transforms matched item", () => {
+    const { result } = renderHook(() => useArray([1, 2, 3]));
+    act(() => result.current[1].update((n) => n === 2, (n) => n * 10));
+    expect(result.current[0]).toEqual([1, 20, 3]);
+  });
+
+  it("update does nothing when predicate matches nothing", () => {
+    const { result } = renderHook(() => useArray([1, 2, 3]));
+    act(() => result.current[1].update((n) => n === 99, 0));
+    expect(result.current[0]).toEqual([1, 2, 3]);
+  });
 });

package/src/hooks/{useArray/useArray.ts → use-array/use-array.ts}

@@ -1,7 +1,6 @@
-import { findIndex, isFunction, ListIterateeCustom } from "lodash";
 import { useState } from "react";
 
-function useArray<T>(defaultProp: T[]) {
+export function useArray<T>(defaultProp: T[]) {
   const [list = [], setList] = useState(defaultProp);
 
   const insertAt = (index: number, item: T) => {
@@ -45,14 +44,14 @@ function useArray<T>(defaultProp: T[]) {
   };
 
   const update = (
-    predicate: ListIterateeCustom<T, boolean>,
+    predicate: (item: T) => boolean,
     newItem: T | ((item: T) => T),
   ) => {
     setList((prevList = []) => {
       const newList = [...prevList];
-      const index = findIndex(newList, predicate);
+      const index = newList.findIndex(predicate);
       if (index === -1) return newList;
-      newList[index] = isFunction(newItem) ? newItem(newList[index]) : newItem;
+      newList[index] = typeof newItem === "function" ? (newItem as (item: T) => T)(newList[index]) : newItem;
       return newList;
     });
   };
@@ -73,4 +72,3 @@ function useArray<T>(defaultProp: T[]) {
   ] as const;
 }
 
-export default useArray;

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

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

package/src/hooks/{useAsync/__doc__/useAsync.stories.tsx → use-async/use-async.stories.tsx}

@@ -1,11 +1,10 @@
 import { Meta, StoryObj } from "@storybook/react-vite";
-import { isUndefined } from "lodash";
 import { ChevronLeft, ChevronRight } from "lucide-react";
 import { useState } from "react";
-import { Button, createToastManager, Input } from "../../../components";
-import { LibraryProvider } from "../../../providers/library-provider";
-import useDebouncedValue from "../../useDebounceValue/useDebouncedValue";
-import useAsync from "../useAsync";
+import { Button, createToastManager, Input } from "../../components";
+import { LibraryProvider } from "../../providers/library-provider";
+import { useDebouncedValue } from "../use-debounce-value/use-debounced-value";
+import { useAsync } from "../use-async";
 
 const toastManager = createToastManager();
 
@@ -56,7 +55,7 @@ export const Basic = {
 };
 
 const fetchPokemonById = async (id: number) => {
-  if (isUndefined(id)) throw new Error("id is required");
+  if (id === undefined) throw new Error("id is required");
   const response = await fetch(`https://pokeapi.co/api/v2/pokemon/${id}`);
   if (!response.ok) throw new Error("Pokemon not found");
   return response.json();

package/src/hooks/{useAsync/__test__/useAsync.test.tsx → use-async/use-async.test.tsx}

@@ -1,6 +1,6 @@
 import { renderHook, waitFor } from "@testing-library/react";
 import { describe, expect, it, vi } from "vitest";
-import useAsync from "../useAsync";
+import { useAsync } from "../use-async";
 
 const mockFetchSuccess = async (data: any) => {
   return new Promise((resolve) => setTimeout(() => resolve(data), 100));

package/src/hooks/{useAsync/useAsync.ts → use-async/use-async.ts}

@@ -18,7 +18,7 @@ interface Props<T> extends UseAsyncOptions<T> {
   dependencies?: DependencyList;
 }
 
-function useAsync<T>({
+export function useAsync<T>({
   fn,
   dependencies = [],
   onError,
@@ -55,4 +55,3 @@ function useAsync<T>({
   return { loading, error, data, refetch: fnMemoized };
 }
 
-export default useAsync;

package/src/hooks/use-click-outside/index.ts

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

package/src/hooks/{useClickOutside/__doc__/useClickOutside.stories.tsx → use-click-outside/use-click-outside.stories.tsx}

@@ -1,7 +1,7 @@
 import { Meta } from "@storybook/react-vite";
 import { useState } from "react";
-import { Button } from "../../../components";
-import useClickOutside from "../useClickOutside";
+import { Button } from "../../components";
+import { useClickOutside } from "../use-click-outside";
 
 const meta: Meta = {
   title: "hooks/useClickOutside",

package/src/hooks/use-click-outside/use-click-outside.test.tsx

@@ -0,0 +1,39 @@
+import { act, render, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { useClickOutside } from "../use-click-outside";
+
+function Component({ onOutside, watch }: { onOutside: () => void; watch?: boolean }) {
+  const ref = useClickOutside<HTMLDivElement>(onOutside, watch);
+  return (
+    <div data-testid="wrapper">
+      <div ref={ref} data-testid="target" />
+    </div>
+  );
+}
+
+function fireMousedown(el: Element) {
+  el.dispatchEvent(new MouseEvent("mousedown", { bubbles: true }));
+}
+
+describe("useClickOutside", () => {
+  it("calls callback when clicking outside the ref element", () => {
+    const fn = vi.fn();
+    render(<Component onOutside={fn} />);
+    act(() => fireMousedown(screen.getByTestId("wrapper")));
+    expect(fn).toHaveBeenCalledOnce();
+  });
+
+  it("does not call callback when clicking inside the ref element", () => {
+    const fn = vi.fn();
+    render(<Component onOutside={fn} />);
+    act(() => fireMousedown(screen.getByTestId("target")));
+    expect(fn).not.toHaveBeenCalled();
+  });
+
+  it("does not attach listener when watch=false", () => {
+    const fn = vi.fn();
+    render(<Component onOutside={fn} watch={false} />);
+    act(() => fireMousedown(screen.getByTestId("wrapper")));
+    expect(fn).not.toHaveBeenCalled();
+  });
+});

package/src/hooks/{useClickOutside/useClickOutside.ts → use-click-outside/use-click-outside.ts}

@@ -1,6 +1,6 @@
 import { useEffect, useRef } from "react";
 
-const useClickOutside = <T extends HTMLElement = HTMLElement>(
+export const useClickOutside = <T extends HTMLElement = HTMLElement>(
   callback: () => void,
   watch: boolean = true,
 ) => {
@@ -23,4 +23,3 @@ const useClickOutside = <T extends HTMLElement = HTMLElement>(
   return ref;
 };
 
-export default useClickOutside;

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

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

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

@@ -0,0 +1,168 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useState } from "react";
+import { Button } from "../../components/button";
+import { Input } from "../../components/input";
+import { Stack } from "../../components/stack";
+import { useClipboard } from "./use-clipboard";
+
+/**
+ * Copy text to the clipboard without writing the same boilerplate every time.
+ *
+ * The hook gives you a `copied` flag that flips to `true` for a moment after a
+ * successful copy and then flips back on its own — perfect for the classic
+ * "Copy → Copied!" button. It also surfaces `error` so you can react when the
+ * browser blocks the operation.
+ *
+ * ```tsx
+ * const { copy, copied } = useClipboard();
+ *
+ * <Button onClick={() => copy("hello")}>
+ *   {copied ? "Copied!" : "Copy"}
+ * </Button>
+ * ```
+ *
+ * Good to know:
+ * - `copy(value)` is fire-and-forget. It will never throw — check `error` if
+ *   you need to handle failures (denied permissions, insecure context, etc.).
+ * - `copied` flips back to `false` automatically after `timeout` ms (default
+ *   `2000`). Pass `useClipboard({ timeout })` to change the duration.
+ * - Need to reset early? `reset()` clears both `copied` and `error` right away.
+ * - Unmount-safe: the internal timeout is cleared on cleanup, so you can use
+ *   it inside dialogs or conditionally rendered components without worrying.
+ */
+const meta: Meta<typeof useClipboard> = {
+  title: "hooks/useClipboard",
+  parameters: { layout: "centered" },
+  tags: ["beta"],
+};
+
+export default meta;
+type Story = StoryObj<typeof useClipboard>;
+
+/**
+ * The happy path: click the button and the label flips for two seconds before
+ * going back. That's the whole point of the hook in one story.
+ */
+export const Default: Story = {
+  render: () => {
+    const { copy, copied } = useClipboard();
+
+    return (
+      <Button onClick={() => copy("Hello from useClipboard")}>
+        {copied ? "Copied!" : "Copy greeting"}
+      </Button>
+    );
+  },
+};
+
+/**
+ * Real-world usage: copying whatever the user typed in. The button label
+ * reflects the latest copy — every click re-arms the timeout, so the "copied"
+ * feedback always lines up with the most recent action.
+ */
+export const CopyFromInput: Story = {
+  render: () => {
+    const [value, setValue] = useState("npm i @boxcustodia/library@next");
+    const { copy, copied } = useClipboard();
+
+    return (
+      <Stack direction="vertical" gap={12} style={{ minWidth: 320 }}>
+        <Input
+          value={value}
+          onValueChange={(next) => setValue(next)}
+          placeholder="Type something to copy"
+        />
+        <Button onClick={() => copy(value)} disabled={!value}>
+          {copied ? "Copied to clipboard" : "Copy value"}
+        </Button>
+      </Stack>
+    );
+  },
+};
+
+/**
+ * Two seconds is great for short labels, but for long snippets you may want
+ * the confirmation to stick around. Pass `timeout` in milliseconds to extend
+ * (or shorten) the window.
+ */
+export const CustomTimeout: Story = {
+  render: () => {
+    const { copy, copied } = useClipboard({ timeout: 5000 });
+
+    return (
+      <Stack direction="vertical" gap={8} align="center">
+        <Button onClick={() => copy("Stays copied for 5 seconds")}>
+          {copied ? "Copied (5s)" : "Copy with 5s timeout"}
+        </Button>
+        <span className="text-xs text-muted-foreground">
+          The label sticks for 5000 ms instead of the default 2000 ms.
+        </span>
+      </Stack>
+    );
+  },
+};
+
+/**
+ * Sometimes you don't want to wait for the timeout — for example, when the
+ * user takes a follow-up action. Call `reset()` and the state goes back to
+ * idle right away.
+ */
+export const ManualReset: Story = {
+  render: () => {
+    const { copy, copied, reset } = useClipboard({ timeout: 60_000 });
+
+    return (
+      <Stack gap={8}>
+        <Button onClick={() => copy("Persistent until reset")}>
+          {copied ? "Copied" : "Copy"}
+        </Button>
+        <Button variant="outline" onClick={reset} disabled={!copied}>
+          Reset
+        </Button>
+      </Stack>
+    );
+  },
+};
+
+/**
+ * Browsers can refuse to copy — denied permissions, an insecure origin, an
+ * older browser without the Clipboard API. When that happens `error` carries
+ * the reason and `copied` stays `false`, so you can branch your UI safely.
+ *
+ * ```tsx
+ * const { copy, copied, error } = useClipboard();
+ *
+ * <Button onClick={() => copy(value)}>Copy</Button>
+ * {error && <span className="text-error">{error.message}</span>}
+ * {copied && <span className="text-success">Copied!</span>}
+ * ```
+ */
+export const ErrorHandling: Story = {
+  render: () => {
+    const { copy, copied, error, reset } = useClipboard();
+
+    return (
+      <Stack direction="vertical" gap={8} style={{ minWidth: 320 }}>
+        <Stack gap={8}>
+          <Button onClick={() => copy("Try copying me")}>Copy</Button>
+          <Button
+            variant="outline"
+            onClick={reset}
+            disabled={!copied && !error}
+          >
+            Reset
+          </Button>
+        </Stack>
+        {copied && (
+          <span className="text-xs text-success">Copied to clipboard.</span>
+        )}
+        {error && <span className="text-xs text-error">{error.message}</span>}
+        {!copied && !error && (
+          <span className="text-xs text-muted-foreground">
+            Click Copy. If the browser blocks it, you'll see the error here.
+          </span>
+        )}
+      </Stack>
+    );
+  },
+};

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

@@ -0,0 +1,114 @@
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { useClipboard } from "./use-clipboard";
+
+describe("useClipboard", () => {
+  const writeText = vi.fn<(value: string) => Promise<void>>();
+
+  beforeEach(() => {
+    writeText.mockResolvedValue();
+    Object.defineProperty(navigator, "clipboard", {
+      value: { writeText },
+      configurable: true,
+    });
+  });
+
+  afterEach(() => {
+    writeText.mockReset();
+    vi.useRealTimers();
+  });
+
+  it("copies a value and flips copied to true", async () => {
+    const { result } = renderHook(() => useClipboard());
+
+    act(() => result.current.copy("test"));
+
+    await waitFor(() => expect(result.current.copied).toBe(true));
+    expect(writeText).toHaveBeenCalledWith("test");
+    expect(result.current.error).toBeNull();
+  });
+
+  it("auto-resets copied after the configured timeout", async () => {
+    vi.useFakeTimers();
+    const { result } = renderHook(() => useClipboard({ timeout: 500 }));
+
+    await act(async () => {
+      result.current.copy("test");
+      await Promise.resolve();
+    });
+
+    expect(result.current.copied).toBe(true);
+
+    act(() => vi.advanceTimersByTime(500));
+
+    expect(result.current.copied).toBe(false);
+  });
+
+  it("exposes the error when writeText rejects", async () => {
+    const failure = new Error("denied");
+    writeText.mockRejectedValueOnce(failure);
+    const { result } = renderHook(() => useClipboard());
+
+    act(() => result.current.copy("test"));
+
+    await waitFor(() => expect(result.current.error).toBe(failure));
+    expect(result.current.copied).toBe(false);
+  });
+
+  it("populates error when navigator.clipboard is unavailable", () => {
+    Object.defineProperty(navigator, "clipboard", {
+      value: undefined,
+      configurable: true,
+    });
+    const { result } = renderHook(() => useClipboard());
+
+    act(() => result.current.copy("test"));
+
+    expect(result.current.error).toBeInstanceOf(Error);
+    expect(result.current.error?.message).toMatch(/not supported/);
+    expect(result.current.copied).toBe(false);
+  });
+
+  it("resets copied to false when a later copy fails", async () => {
+    const failure = new Error("denied");
+    const { result } = renderHook(() => useClipboard());
+
+    act(() => result.current.copy("first"));
+    await waitFor(() => expect(result.current.copied).toBe(true));
+
+    writeText.mockRejectedValueOnce(failure);
+    act(() => result.current.copy("second"));
+
+    await waitFor(() => expect(result.current.error).toBe(failure));
+    expect(result.current.copied).toBe(false);
+  });
+
+  it("resets copied to false when clipboard becomes unavailable", async () => {
+    const { result } = renderHook(() => useClipboard());
+
+    act(() => result.current.copy("first"));
+    await waitFor(() => expect(result.current.copied).toBe(true));
+
+    Object.defineProperty(navigator, "clipboard", {
+      value: undefined,
+      configurable: true,
+    });
+
+    act(() => result.current.copy("second"));
+
+    expect(result.current.copied).toBe(false);
+    expect(result.current.error?.message).toMatch(/not supported/);
+  });
+
+  it("clears copied and error on reset()", async () => {
+    const { result } = renderHook(() => useClipboard());
+
+    act(() => result.current.copy("test"));
+    await waitFor(() => expect(result.current.copied).toBe(true));
+
+    act(() => result.current.reset());
+
+    expect(result.current.copied).toBe(false);
+    expect(result.current.error).toBeNull();
+  });
+});

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

@@ -0,0 +1,70 @@
+import { useEffect, useRef, useState } from "react";
+
+export interface UseClipboardInput {
+  /** Time in ms after which the copied state will reset, `2000` by default */
+  timeout?: number;
+}
+
+export interface UseClipboardReturnValue {
+  /** Function to copy a string value to the clipboard */
+  copy: (value: string) => void;
+
+  /** Function to reset copied state and error */
+  reset: () => void;
+
+  /** Error if copying failed, `null` otherwise */
+  error: Error | null;
+
+  /** Boolean indicating if the value was copied successfully */
+  copied: boolean;
+}
+
+export function useClipboard(
+  options: UseClipboardInput = {},
+): UseClipboardReturnValue {
+  const timeout = options.timeout ?? 2000;
+  const [error, setError] = useState<Error | null>(null);
+  const [copied, setCopied] = useState(false);
+  const timeoutRef = useRef<number | null>(null);
+
+  useEffect(
+    () => () => {
+      if (timeoutRef.current) window.clearTimeout(timeoutRef.current);
+    },
+    [],
+  );
+
+  const handleCopyResult = (value: boolean) => {
+    if (timeoutRef.current) window.clearTimeout(timeoutRef.current);
+    timeoutRef.current = window.setTimeout(() => setCopied(false), timeout);
+    setCopied(value);
+  };
+
+  const copy = (value: string) => {
+    if (!navigator.clipboard?.writeText) {
+      if (timeoutRef.current) window.clearTimeout(timeoutRef.current);
+      setCopied(false);
+      setError(new Error("useClipboard: navigator.clipboard is not supported"));
+      return;
+    }
+    navigator.clipboard
+      .writeText(value)
+      .then(() => {
+        setError(null);
+        handleCopyResult(true);
+      })
+      .catch((err: Error) => {
+        if (timeoutRef.current) window.clearTimeout(timeoutRef.current);
+        setCopied(false);
+        setError(err);
+      });
+  };
+
+  const reset = () => {
+    setCopied(false);
+    setError(null);
+    if (timeoutRef.current) window.clearTimeout(timeoutRef.current);
+  };
+
+  return { copy, reset, error, copied };
+}

package/src/hooks/use-debounce-callback/index.ts

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

package/src/hooks/{useDebounceCallback/__doc__/useDebouncedCallback.stories.tsx → use-debounce-callback/use-debounced-callback.stories.tsx}

@@ -1,7 +1,7 @@
 import { Meta, StoryObj } from "@storybook/react-vite";
-import { Input } from "../../../components";
-import { createToastManager, ToastProvider } from "../../../components/toast";
-import { useDebouncedCallback } from "../../useDebounceCallback";
+import { Input } from "../../components";
+import { createToastManager, ToastProvider } from "../../components/toast";
+import { useDebouncedCallback } from "./use-debounced-callback";
 
 const toastManager = createToastManager();