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

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

@@ -1,102 +1,281 @@
 import { act, renderHook } from "@testing-library/react";
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, vi } from "vitest";
 import { useObject } from "../use-object";
 
-describe("useObject hook", () => {
-  it("should initialize with default state", () => {
-    const initialValue = { count: 0 };
-    const { result } = renderHook(() => useObject(initialValue));
+describe("useObject", () => {
+  // ─── initialization ───────────────────────────────────────────────────────
 
-    expect(result.current[0]).toEqual(initialValue);
+  describe("initialization", () => {
+    it("returns [state, actions] tuple where state deep-equals initialValue", () => {
+      const init = { name: "Alice", age: 30 };
+      const { result } = renderHook(() => useObject(init));
+
+      expect(result.current[0]).toEqual(init);
+    });
+
+    it("actions object exposes set, replace, reset, setKey", () => {
+      const { result } = renderHook(() => useObject({ x: 1 }));
+      const actions = result.current[1];
+
+      expect(typeof actions.set).toBe("function");
+      expect(typeof actions.replace).toBe("function");
+      expect(typeof actions.reset).toBe("function");
+      expect(typeof actions.setKey).toBe("function");
+    });
   });
 
-  it("should handle object updates", () => {
-    const initialValue = { count: 0 };
-    const { result } = renderHook(() => useObject<{}>(initialValue));
+  // ─── set (merge) ──────────────────────────────────────────────────────────
 
-    act(() => {
-      result.current[1]({ count: 1 });
+  describe("set", () => {
+    it("set(partial) shallow-merges and preserves untouched keys", () => {
+      const { result } = renderHook(() =>
+        useObject({ name: "Alice", email: "a@a.com" }),
+      );
+
+      act(() => result.current[1].set({ name: "Bob" }));
+
+      expect(result.current[0]).toEqual({ name: "Bob", email: "a@a.com" });
     });
 
-    expect(result.current[0]).toEqual({ count: 1 });
+    it("set(fn) functional updater receives prev and merges returned partial", () => {
+      const { result } = renderHook(() => useObject({ count: 3 }));
 
-    act(() => {
-      result.current[1]({ name: "test" });
+      act(() => result.current[1].set((s) => ({ count: s.count + 1 })));
+
+      expect(result.current[0]).toEqual({ count: 4 });
     });
 
-    expect(result.current[0]).toEqual({ count: 1, name: "test" });
+    it("set({}) empty partial produces a new state reference", () => {
+      const { result } = renderHook(() => useObject({ x: 1 }));
+      const before = result.current[0];
+
+      act(() => result.current[1].set({}));
+
+      expect(result.current[0]).not.toBe(before);
+    });
   });
 
-  it("should handle function updates", () => {
-    const initialValue = { count: 0 };
-    const { result } = renderHook(() => useObject(initialValue));
+  // ─── replace ──────────────────────────────────────────────────────────────
+
+  describe("replace", () => {
+    it("replace(value) swaps the whole object and discards unmentioned keys", () => {
+      const { result } = renderHook(() => useObject({ a: 1, b: 2 }));
+
+      act(() =>
+        result.current[1].replace({ a: 99 } as { a: number; b: number }),
+      );
 
-    act(() => {
-      result.current[1]((state) => ({ count: (state?.count ?? 0) + 1 }));
+      expect(result.current[0]).toEqual({ a: 99 });
+      expect((result.current[0] as { b?: number }).b).toBeUndefined();
     });
 
-    expect(result.current[0]).toEqual({ count: 1 });
+    it("replace(fn) functional variant receives prev and fully replaces", () => {
+      const { result } = renderHook(() => useObject({ count: 5 }));
 
-    act(() => {
-      result.current[1]((state) => ({ count: (state?.count ?? 0) + 1 }));
+      act(() => result.current[1].replace((s) => ({ count: s.count * 2 })));
+
+      expect(result.current[0]).toEqual({ count: 10 });
     });
 
-    expect(result.current[0]).toEqual({ count: 2 });
-  });
+    it("replace with identical values still produces a new state reference", () => {
+      const { result } = renderHook(() => useObject({ x: 1 }));
+      const before = result.current[0];
 
-  it("should reset to initial value", () => {
-    const initialValue = { count: 0 };
-    const { result } = renderHook(() => useObject(initialValue));
+      act(() => result.current[1].replace({ x: 1 }));
 
-    act(() => {
-      result.current[1]({ count: 1 });
+      expect(result.current[0]).not.toBe(before);
     });
+  });
+
+  // ─── reset ────────────────────────────────────────────────────────────────
 
-    expect(result.current[0]).toEqual({ count: 1 });
+  describe("reset", () => {
+    it("reset() restores mount-time value after mutation", () => {
+      const { result } = renderHook(() => useObject({ count: 0 }));
 
-    act(() => {
-      result.current[2](); // reset
+      act(() => result.current[1].set({ count: 5 }));
+      expect(result.current[0]).toEqual({ count: 5 });
+
+      act(() => result.current[1].reset());
+
+      expect(result.current[0]).toEqual({ count: 0 });
     });
 
-    expect(result.current[0]).toEqual(initialValue);
+    it("reset() ignores prop changes after mount (frozen ref)", () => {
+      const { result, rerender } = renderHook(
+        ({ iv }: { iv: { count: number } }) => useObject(iv),
+        { initialProps: { iv: { count: 0 } } },
+      );
+
+      // Change the prop after mount
+      rerender({ iv: { count: 99 } });
+      act(() => result.current[1].set({ count: 5 }));
+      act(() => result.current[1].reset());
+
+      // Must restore the mount-time value, NOT the re-rendered prop
+      expect(result.current[0]).toEqual({ count: 0 });
+    });
   });
 
-  it("should initialize with undefined if no initial value is provided", () => {
-    const { result } = renderHook(() => useObject());
+  // ─── setKey ───────────────────────────────────────────────────────────────
+
+  describe("setKey", () => {
+    it("setKey(key, value) updates one key and preserves the others", () => {
+      const { result } = renderHook(() =>
+        useObject({ name: "Alice", age: 30 }),
+      );
+
+      act(() => result.current[1].setKey("age", 31));
+
+      expect(result.current[0]).toEqual({ name: "Alice", age: 31 });
+    });
+
+    it("setKey only touches the specified key", () => {
+      const { result } = renderHook(() =>
+        useObject({ a: "x", b: "y", c: "z" }),
+      );
 
-    expect(result.current[0]).toBeUndefined();
+      act(() => result.current[1].setKey("b", "updated"));
+
+      expect(result.current[0].a).toBe("x");
+      expect(result.current[0].b).toBe("updated");
+      expect(result.current[0].c).toBe("z");
+    });
   });
 
-  it("should handle partial updates", () => {
-    const initialValue = { count: 0, name: "initial" };
-    const { result } = renderHook(() => useObject(initialValue));
+  // ─── action stability ─────────────────────────────────────────────────────
 
-    act(() => {
-      result.current[1]({ count: 1 });
+  describe("action stability", () => {
+    it("actions object reference is stable across re-renders", () => {
+      const { result, rerender } = renderHook(() => useObject({ x: 1 }));
+      const before = result.current[1];
+
+      rerender();
+
+      expect(result.current[1]).toBe(before);
     });
 
-    expect(result.current[0]).toEqual({ count: 1, name: "initial" });
+    it("each individual action fn is stable across re-renders", () => {
+      const { result, rerender } = renderHook(() => useObject({ x: 1 }));
+      const { set, replace, reset, setKey } = result.current[1];
 
-    act(() => {
-      result.current[1]({ name: "updated" });
+      rerender();
+
+      expect(result.current[1].set).toBe(set);
+      expect(result.current[1].replace).toBe(replace);
+      expect(result.current[1].reset).toBe(reset);
+      expect(result.current[1].setKey).toBe(setKey);
     });
 
-    expect(result.current[0]).toEqual({ count: 1, name: "updated" });
+    it("changing onChange reference does not invalidate action refs", () => {
+      const { result, rerender } = renderHook(
+        ({ onChange }: { onChange: (s: { x: number }) => void }) =>
+          useObject({ x: 1 }, { onChange }),
+        { initialProps: { onChange: vi.fn() } },
+      );
+      const before = result.current[1];
+
+      rerender({ onChange: vi.fn() }); // new function reference
+
+      expect(result.current[1]).toBe(before);
+    });
   });
 
-  it("function update returning non-object keeps previous state", () => {
-    const { result } = renderHook(() => useObject({ count: 1 }));
-    act(() => {
-      result.current[1]((_state) => null as any);
+  // ─── onChange ─────────────────────────────────────────────────────────────
+
+  describe("onChange", () => {
+    it("does NOT fire on initial mount", () => {
+      const onChange = vi.fn();
+      renderHook(() => useObject({ x: 1 }, { onChange }));
+
+      expect(onChange).not.toHaveBeenCalled();
+    });
+
+    it("fires after set with the new state", () => {
+      const onChange = vi.fn();
+      const { result } = renderHook(() => useObject({ x: 1 }, { onChange }));
+
+      act(() => result.current[1].set({ x: 2 }));
+
+      expect(onChange).toHaveBeenCalledTimes(1);
+      expect(onChange).toHaveBeenCalledWith({ x: 2 });
+    });
+
+    it("fires after replace with the new state", () => {
+      const onChange = vi.fn();
+      const { result } = renderHook(() =>
+        useObject({ x: 1, y: 2 }, { onChange }),
+      );
+
+      act(() =>
+        result.current[1].replace({ x: 99 } as { x: number; y: number }),
+      );
+
+      expect(onChange).toHaveBeenCalledTimes(1);
+      expect(onChange).toHaveBeenCalledWith({ x: 99 });
+    });
+
+    it("fires after reset with the mount-time state", () => {
+      const onChange = vi.fn();
+      const { result } = renderHook(() => useObject({ x: 1 }, { onChange }));
+
+      act(() => result.current[1].set({ x: 5 }));
+      onChange.mockClear();
+
+      act(() => result.current[1].reset());
+
+      expect(onChange).toHaveBeenCalledTimes(1);
+      expect(onChange).toHaveBeenCalledWith({ x: 1 });
+    });
+
+    it("fires after setKey with the new state", () => {
+      const onChange = vi.fn();
+      const { result } = renderHook(() =>
+        useObject({ name: "Alice", age: 30 }, { onChange }),
+      );
+
+      act(() => result.current[1].setKey("age", 31));
+
+      expect(onChange).toHaveBeenCalledTimes(1);
+      expect(onChange).toHaveBeenCalledWith({ name: "Alice", age: 31 });
+    });
+
+    it("new inline onChange reference between renders does not double-fire", () => {
+      const spy = vi.fn();
+      const { rerender } = renderHook(
+        ({ onChange }: { onChange: (s: { x: number }) => void }) =>
+          useObject({ x: 1 }, { onChange }),
+        { initialProps: { onChange: () => spy() } },
+      );
+
+      // Re-render with a fresh inline function — no state change
+      rerender({ onChange: () => spy() });
+
+      expect(spy).not.toHaveBeenCalled();
     });
-    expect(result.current[0]).toEqual({ count: 1 });
   });
 
-  it("non-function non-object arg keeps previous state", () => {
-    const { result } = renderHook(() => useObject({ count: 1 }));
-    act(() => {
-      result.current[1](42 as any);
+  // ─── edge cases ───────────────────────────────────────────────────────────
+
+  describe("edge cases", () => {
+    it("set({}) with empty partial is valid and produces a new reference", () => {
+      const { result } = renderHook(() => useObject({ a: 1 }));
+      const before = result.current[0];
+
+      act(() => result.current[1].set({}));
+
+      expect(result.current[0]).not.toBe(before);
+      expect(result.current[0]).toEqual({ a: 1 });
+    });
+
+    it("replace with identical values still produces a new reference", () => {
+      const { result } = renderHook(() => useObject({ x: 42 }));
+      const before = result.current[0];
+
+      act(() => result.current[1].replace({ x: 42 }));
+
+      expect(result.current[0]).not.toBe(before);
+      expect(result.current[0]).toEqual({ x: 42 });
     });
-    expect(result.current[0]).toEqual({ count: 1 });
   });
 });

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

@@ -0,0 +1,59 @@
+import { useEffect, useMemo, useRef, useState } from "react";
+import { useLatestRef } from "../internal/use-latest-ref";
+
+export interface UseObjectOptions<T> {
+  /** Called after every state change. NOT called on initial mount. */
+  onChange?: (state: T) => void;
+}
+
+export interface UseObjectActions<T> {
+  /** Shallow-merge a partial (or functional updater returning a partial). */
+  set(partial: Partial<T> | ((state: T) => Partial<T>)): void;
+  /** Replace the entire object (no merge). Functional variant receives prev. */
+  replace(value: T | ((state: T) => T)): void;
+  /** Restore the mount-time value (frozen ref). */
+  reset(): void;
+  /** Update a single typed key. */
+  setKey<K extends keyof T>(key: K, value: T[K]): void;
+}
+
+export function useObject<T extends object>(
+  initialValue: T,
+  options?: UseObjectOptions<T>,
+): readonly [T, UseObjectActions<T>] {
+  const [state, setState] = useState<T>(initialValue);
+
+  // Frozen on mount — reset always restores the original value.
+  const initialRef = useRef(initialValue);
+  // Always the latest handler — never a memo/effect dep.
+  const onChangeRef = useLatestRef(options?.onChange);
+
+  // Fire onChange on every change EXCEPT the initial mount.
+  const mountedRef = useRef(false);
+  useEffect(() => {
+    if (!mountedRef.current) {
+      mountedRef.current = true;
+      return;
+    }
+    onChangeRef.current?.(state);
+  }, [state]);
+
+  const actions = useMemo<UseObjectActions<T>>(
+    () => ({
+      set: (partial) =>
+        setState((prev) => ({
+          ...prev,
+          ...(typeof partial === "function" ? partial(prev) : partial),
+        })),
+      replace: (value) =>
+        setState((prev) =>
+          typeof value === "function" ? (value as (s: T) => T)(prev) : value,
+        ),
+      reset: () => setState(initialRef.current),
+      setKey: (key, value) => setState((prev) => ({ ...prev, [key]: value })),
+    }),
+    [setState],
+  );
+
+  return [state, actions] as const;
+}

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

@@ -82,4 +82,3 @@ export function usePagination({
     range: { start, end },
   };
 }
-

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

@@ -0,0 +1 @@
+export * from "./use-prevent-page-close";

package/src/hooks/use-prevent-page-close/use-prevent-page-close.stories.tsx

@@ -0,0 +1,39 @@
+import type { Meta } from "@storybook/react-vite";
+import { usePreventPageClose } from "./use-prevent-page-close";
+
+/**
+ * Prompts the browser's native "Leave site?" confirmation when the user
+ * tries to close the tab or reload while `enabled` is `true`. Typical
+ * use: block accidental navigation away from a form with unsaved
+ * changes. Only covers full-page unload — SPA route changes need a
+ * router guard. The dialog text is controlled by the browser and cannot
+ * be customized.
+ */
+const meta: Meta = {
+  title: "hooks/usePreventPageClose",
+  tags: ["beta"],
+  args: {
+    enabled: true,
+  },
+  argTypes: {
+    enabled: {
+      control: "boolean",
+      description:
+        "When true, closing or reloading the tab triggers the native confirmation dialog.",
+    },
+  },
+};
+
+export default meta;
+
+export const Default = {
+  render: (args: { enabled: boolean }) => {
+    usePreventPageClose(args.enabled);
+    return (
+      <p className="text-sm">
+        Try to close or reload this tab — the browser will ask for confirmation
+        while <code>enabled</code> is on.
+      </p>
+    );
+  },
+};

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/use-range-pagination.test.tsx

@@ -1,6 +1,6 @@
 import { renderHook } from "@testing-library/react";
 import { describe, expect, it } from "vitest";
-import { useRangePagination, DOTS } from "../use-range-pagination";
+import { DOTS, useRangePagination } from "../use-range-pagination";
 
 describe("usePagination hook", () => {
   it("should be defined", () => {

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

@@ -2,6 +2,7 @@ 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 = "...";
@@ -70,4 +71,3 @@ export const useRangePagination = ({
     paginationRange: paginationRange ?? [],
   };
 };
-

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

@@ -117,4 +117,3 @@ export function useSelection<T>(items: T[]): Return<T> {
     clear,
   };
 }
-