@boxcustodia/library 2.0.0-alpha.22 → 2.0.0-alpha.24

package/src/hooks/{use-mutation/use-mutation.test.ts → use-action/use-action.test.ts}

@@ -1,8 +1,8 @@
 import { act, renderHook } from "@testing-library/react";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { useMutation } from "../use-mutation";
+import { useAction } from "../use-action";
 
-describe("useMutation", () => {
+describe("useAction", () => {
   beforeEach(() => {
     vi.useFakeTimers();
   });
@@ -14,7 +14,7 @@ describe("useMutation", () => {
   // 1 — Initial state
   it("initializes with idle status and null data/error", () => {
     const { result } = renderHook(() =>
-      useMutation({ fn: () => Promise.resolve("x") }),
+      useAction({ fn: () => Promise.resolve("x") }),
     );
 
     expect(result.current.status).toBe("idle");
@@ -33,10 +33,10 @@ describe("useMutation", () => {
       resolve = res;
     });
 
-    const { result } = renderHook(() => useMutation({ fn: () => deferred }));
+    const { result } = renderHook(() => useAction({ fn: () => deferred }));
 
     act(() => {
-      result.current.mutate(undefined);
+      result.current.execute(undefined);
     });
 
     expect(result.current.status).toBe("pending");
@@ -54,11 +54,11 @@ describe("useMutation", () => {
   // 3 — Success path
   it("sets status=success and data on successful mutation", async () => {
     const { result } = renderHook(() =>
-      useMutation({ fn: () => Promise.resolve("ok") }),
+      useAction({ fn: () => Promise.resolve("ok") }),
     );
 
     await act(async () => {
-      await result.current.mutateAsync(undefined);
+      await result.current.executeAsync(undefined);
     });
 
     expect(result.current.status).toBe("success");
@@ -71,11 +71,11 @@ describe("useMutation", () => {
   it("sets status=error and error on failed mutation", async () => {
     const err = new Error("boom");
     const { result } = renderHook(() =>
-      useMutation({ fn: () => Promise.reject(err) }),
+      useAction({ fn: () => Promise.reject(err) }),
     );
 
     await act(async () => {
-      await result.current.mutateAsync(undefined).catch(() => {});
+      await result.current.executeAsync(undefined).catch(() => {});
     });
 
     expect(result.current.status).toBe("error");
@@ -84,30 +84,30 @@ describe("useMutation", () => {
     expect(result.current.data).toBeNull();
   });
 
-  // 5 — mutateAsync resolves with data
-  it("mutateAsync resolves with the value returned by fn", async () => {
+  // 5 — executeAsync resolves with data
+  it("executeAsync resolves with the value returned by fn", async () => {
     const { result } = renderHook(() =>
-      useMutation({ fn: () => Promise.resolve(42) }),
+      useAction({ fn: () => Promise.resolve(42) }),
     );
 
     let resolved: number | undefined;
     await act(async () => {
-      resolved = await result.current.mutateAsync(undefined);
+      resolved = await result.current.executeAsync(undefined);
     });
 
     expect(resolved).toBe(42);
   });
 
-  // 6 — mutateAsync re-throws on error
-  it("mutateAsync re-throws on error", async () => {
+  // 6 — executeAsync re-throws on error
+  it("executeAsync re-throws on error", async () => {
     const err = new Error("rethrow-me");
     const { result } = renderHook(() =>
-      useMutation({ fn: () => Promise.reject(err) }),
+      useAction({ fn: () => Promise.reject(err) }),
     );
 
     let caught: Error | undefined;
     await act(async () => {
-      caught = await result.current.mutateAsync(undefined).catch((e) => e);
+      caught = await result.current.executeAsync(undefined).catch((e) => e);
     });
 
     expect(caught).toBe(err);
@@ -116,12 +116,12 @@ describe("useMutation", () => {
   // 7 — mutate is fire-and-forget (void, no throw)
   it("mutate returns void and does not throw on error", async () => {
     const fn = vi.fn().mockRejectedValue(new Error("ignored"));
-    const { result } = renderHook(() => useMutation({ fn }));
+    const { result } = renderHook(() => useAction({ fn }));
 
     let threw = false;
     await act(async () => {
       try {
-        result.current.mutate(undefined);
+        result.current.execute(undefined);
         await Promise.resolve();
       } catch {
         threw = true;
@@ -131,8 +131,8 @@ describe("useMutation", () => {
     expect(threw).toBe(false);
   });
 
-  // 8 — onMutate called before fn resolves
-  it("calls onMutate(variables) before fn resolves", async () => {
+  // 8 — onExecute called before fn resolves
+  it("calls onExecute(variables) before fn resolves", async () => {
     const callOrder: string[] = [];
     let resolveFn!: () => void;
     const fn = vi.fn(
@@ -141,20 +141,20 @@ describe("useMutation", () => {
           resolveFn = () => res("done");
         }),
     );
-    const onMutate = vi.fn(() => {
-      callOrder.push("onMutate");
+    const onExecute = vi.fn(() => {
+      callOrder.push("onExecute");
     });
 
-    const { result } = renderHook(() => useMutation({ fn, onMutate }));
+    const { result } = renderHook(() => useAction({ fn, onExecute }));
 
     act(() => {
-      result.current.mutate(undefined);
+      result.current.execute(undefined);
     });
 
-    // onMutate called synchronously — fn has not resolved yet
-    expect(onMutate).toHaveBeenCalledTimes(1);
+    // onExecute called synchronously — fn has not resolved yet
+    expect(onExecute).toHaveBeenCalledTimes(1);
     expect(fn).toHaveBeenCalledTimes(1);
-    expect(callOrder).toEqual(["onMutate"]);
+    expect(callOrder).toEqual(["onExecute"]);
 
     await act(async () => {
       resolveFn();
@@ -168,14 +168,14 @@ describe("useMutation", () => {
     const vars = { id: 99 };
 
     const { result } = renderHook(() =>
-      useMutation({
+      useAction({
         fn: (v: { id: number }) => Promise.resolve(`result-${v.id}`),
         onSuccess,
       }),
     );
 
     await act(async () => {
-      await result.current.mutateAsync(vars);
+      await result.current.executeAsync(vars);
     });
 
     expect(onSuccess).toHaveBeenCalledOnce();
@@ -189,14 +189,14 @@ describe("useMutation", () => {
     const vars = { id: 7 };
 
     const { result } = renderHook(() =>
-      useMutation({
+      useAction({
         fn: (_v: { id: number }) => Promise.reject(err),
         onError,
       }),
     );
 
     await act(async () => {
-      await result.current.mutateAsync(vars).catch(() => {});
+      await result.current.executeAsync(vars).catch(() => {});
     });
 
     expect(onError).toHaveBeenCalledOnce();
@@ -209,14 +209,14 @@ describe("useMutation", () => {
     const vars = { id: 1 };
 
     const { result } = renderHook(() =>
-      useMutation({
+      useAction({
         fn: (v: { id: number }) => Promise.resolve(`ok-${v.id}`),
         onSettled,
       }),
     );
 
     await act(async () => {
-      await result.current.mutateAsync(vars);
+      await result.current.executeAsync(vars);
     });
 
     expect(onSettled).toHaveBeenCalledOnce();
@@ -230,14 +230,14 @@ describe("useMutation", () => {
     const vars = { id: 2 };
 
     const { result } = renderHook(() =>
-      useMutation({
+      useAction({
         fn: (_v: { id: number }) => Promise.reject(err),
         onSettled,
       }),
     );
 
     await act(async () => {
-      await result.current.mutateAsync(vars).catch(() => {});
+      await result.current.executeAsync(vars).catch(() => {});
     });
 
     expect(onSettled).toHaveBeenCalledOnce();
@@ -247,11 +247,11 @@ describe("useMutation", () => {
   // 13 — reset after success
   it("reset() after success returns to idle and clears data", async () => {
     const { result } = renderHook(() =>
-      useMutation({ fn: () => Promise.resolve("done") }),
+      useAction({ fn: () => Promise.resolve("done") }),
     );
 
     await act(async () => {
-      await result.current.mutateAsync(undefined);
+      await result.current.executeAsync(undefined);
     });
 
     expect(result.current.status).toBe("success");
@@ -268,11 +268,11 @@ describe("useMutation", () => {
   // 14 — reset after error
   it("reset() after error returns to idle and clears error", async () => {
     const { result } = renderHook(() =>
-      useMutation({ fn: () => Promise.reject(new Error("e")) }),
+      useAction({ fn: () => Promise.reject(new Error("e")) }),
     );
 
     await act(async () => {
-      await result.current.mutateAsync(undefined).catch(() => {});
+      await result.current.executeAsync(undefined).catch(() => {});
     });
 
     expect(result.current.status).toBe("error");
@@ -290,14 +290,14 @@ describe("useMutation", () => {
   it("mutate reference is stable when inline fn changes", () => {
     let fn = vi.fn().mockResolvedValue("a");
 
-    const { result, rerender } = renderHook(() => useMutation({ fn }));
+    const { result, rerender } = renderHook(() => useAction({ fn }));
 
-    const mutateRef1 = result.current.mutate;
+    const executeRef1 = result.current.execute;
 
     fn = vi.fn().mockResolvedValue("b");
     rerender();
 
-    expect(result.current.mutate).toBe(mutateRef1);
+    expect(result.current.execute).toBe(executeRef1);
   });
 
   // 16 — mutate stable when onSuccess changes
@@ -305,35 +305,35 @@ describe("useMutation", () => {
     let onSuccess = vi.fn();
 
     const { result, rerender } = renderHook(() =>
-      useMutation({ fn: () => Promise.resolve("x"), onSuccess }),
+      useAction({ fn: () => Promise.resolve("x"), onSuccess }),
     );
 
-    const mutateRef1 = result.current.mutate;
+    const executeRef1 = result.current.execute;
 
     onSuccess = vi.fn();
     rerender();
 
-    expect(result.current.mutate).toBe(mutateRef1);
+    expect(result.current.execute).toBe(executeRef1);
   });
 
   // 17 — variables forwarded to fn and all callbacks
-  it("forwards variables to fn, onMutate, onSuccess, and onSettled", async () => {
+  it("forwards variables to fn, onExecute, onSuccess, and onSettled", async () => {
     const vars = { userId: 42, name: "Alice" };
     const fn = vi.fn().mockResolvedValue("created");
-    const onMutate = vi.fn();
+    const onExecute = vi.fn();
     const onSuccess = vi.fn();
     const onSettled = vi.fn();
 
     const { result } = renderHook(() =>
-      useMutation({ fn, onMutate, onSuccess, onSettled }),
+      useAction({ fn, onExecute, onSuccess, onSettled }),
     );
 
     await act(async () => {
-      await result.current.mutateAsync(vars);
+      await result.current.executeAsync(vars);
     });
 
     expect(fn).toHaveBeenCalledWith(vars);
-    expect(onMutate).toHaveBeenCalledWith(vars);
+    expect(onExecute).toHaveBeenCalledWith(vars);
     expect(onSuccess).toHaveBeenCalledWith("created", vars);
     expect(onSettled).toHaveBeenCalledWith("created", null, vars);
   });
@@ -347,11 +347,11 @@ describe("useMutation", () => {
     const onSettled = vi.fn();
 
     const { result } = renderHook(() =>
-      useMutation({ fn: () => Promise.reject(err), onError, onSettled }),
+      useAction({ fn: () => Promise.reject(err), onError, onSettled }),
     );
 
     await act(async () => {
-      await result.current.mutateAsync(undefined).catch(() => {});
+      await result.current.executeAsync(undefined).catch(() => {});
     });
 
     expect(onSettled).toHaveBeenCalledOnce();

package/src/hooks/{use-mutation/use-mutation.ts → use-action/use-action.ts}

@@ -1,11 +1,11 @@
 import { useCallback, useState } from "react";
 import { useLatestRef } from "../internal/use-latest-ref";
 
-type MutationStatus = "idle" | "pending" | "success" | "error";
+type ActionStatus = "idle" | "pending" | "success" | "error";
 
-export interface UseMutationOptions<TVariables = void, TData = unknown> {
+export interface UseActionOptions<TVariables = void, TData = unknown> {
   fn: (variables: TVariables) => Promise<TData>;
-  onMutate?: (variables: TVariables) => void;
+  onExecute?: (variables: TVariables) => void;
   onSuccess?: (data: TData, variables: TVariables) => void;
   onError?: (error: Error, variables: TVariables) => void;
   onSettled?: (
@@ -15,35 +15,35 @@ export interface UseMutationOptions<TVariables = void, TData = unknown> {
   ) => void;
 }
 
-export interface UseMutationReturn<TVariables = void, TData = unknown> {
-  mutate: (variables: TVariables) => void;
-  mutateAsync: (variables: TVariables) => Promise<TData>;
+export interface UseActionReturn<TVariables = void, TData = unknown> {
+  execute: (variables: TVariables) => void;
+  executeAsync: (variables: TVariables) => Promise<TData>;
   reset: () => void;
   data: TData | null;
   error: Error | null;
-  status: MutationStatus;
+  status: ActionStatus;
   isIdle: boolean;
   isPending: boolean;
   isSuccess: boolean;
   isError: boolean;
 }
 
-export const useMutation = <TVariables = void, TData = unknown>(
-  options: UseMutationOptions<TVariables, TData>,
-): UseMutationReturn<TVariables, TData> => {
-  const [status, setStatus] = useState<MutationStatus>("idle");
+export const useAction = <TVariables = void, TData = unknown>(
+  options: UseActionOptions<TVariables, TData>,
+): UseActionReturn<TVariables, TData> => {
+  const [status, setStatus] = useState<ActionStatus>("idle");
   const [data, setData] = useState<TData | null>(null);
   const [error, setError] = useState<Error | null>(null);
 
   const fnRef = useLatestRef(options.fn);
-  const onMutateRef = useLatestRef(options.onMutate);
+  const onExecuteRef = useLatestRef(options.onExecute);
   const onSuccessRef = useLatestRef(options.onSuccess);
   const onErrorRef = useLatestRef(options.onError);
   const onSettledRef = useLatestRef(options.onSettled);
 
-  const mutateAsync = useCallback(
+  const executeAsync = useCallback(
     async (variables: TVariables): Promise<TData> => {
-      onMutateRef.current?.(variables);
+      onExecuteRef.current?.(variables);
       setStatus("pending");
       setData(null);
       setError(null);
@@ -66,14 +66,14 @@ export const useMutation = <TVariables = void, TData = unknown>(
         onSettledRef.current?.(result, caught, variables);
       }
     },
-    [fnRef, onMutateRef, onSuccessRef, onErrorRef, onSettledRef],
+    [fnRef, onExecuteRef, onSuccessRef, onErrorRef, onSettledRef],
   );
 
-  const mutate = useCallback(
+  const execute = useCallback(
     (variables: TVariables): void => {
-      mutateAsync(variables).catch(() => {});
+      executeAsync(variables).catch(() => {});
     },
-    [mutateAsync],
+    [executeAsync],
   );
 
   const reset = useCallback(() => {
@@ -83,8 +83,8 @@ export const useMutation = <TVariables = void, TData = unknown>(
   }, []);
 
   return {
-    mutate,
-    mutateAsync,
+    execute,
+    executeAsync,
     reset,
     data,
     error,

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

@@ -36,7 +36,6 @@ import { useClickOutside } from "./use-click-outside";
 const meta: Meta = {
   title: "hooks/useClickOutside",
   parameters: { layout: "centered" },
-  tags: ["beta"],
 };
 
 export default meta;

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

@@ -33,7 +33,6 @@ import { useClipboard } from "./use-clipboard";
 const meta: Meta<typeof useClipboard> = {
   title: "hooks/useClipboard",
   parameters: { layout: "centered" },
-  tags: ["beta"],
 };
 
 export default meta;

package/src/hooks/use-document-title/use-document-title.stories.tsx

@@ -35,7 +35,6 @@ import { useDocumentTitle } from "./use-document-title";
 const meta: Meta<typeof useDocumentTitle> = {
   title: "hooks/useDocumentTitle",
   parameters: { layout: "centered" },
-  tags: ["beta"],
 };
 
 export default meta;

package/src/hooks/use-is-visible/use-is-visible.test.tsx

@@ -1,5 +1,5 @@
 import { act, render, screen } from "@testing-library/react";
-import { describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { useIsVisible } from "./use-is-visible";
 
 // IntersectionObserver isn't available in jsdom. Provide a controllable mock.

package/src/hooks/use-local-storage/use-local-storage.stories.tsx

@@ -13,7 +13,6 @@ import { useLocalStorage } from "../use-local-storage";
  */
 const meta: Meta = {
   title: "hooks/useLocalStorage",
-  tags: ["beta"],
 };
 
 export default meta;

package/src/hooks/use-local-storage/use-local-storage.ts

@@ -1,10 +1,7 @@
 import { useCallback, useMemo, useSyncExternalStore } from "react";
-import { isBrowser } from "../internal";
+import { isBrowser, type Serializer } from "../internal";
 
-export interface Serializer<T> {
-  read: (raw: string) => T;
-  write: (value: T) => string;
-}
+export type { Serializer };
 
 export interface UseLocalStorageOptions<T> {
   serializer?: Serializer<T>;

package/src/hooks/use-media-query/use-media-query.stories.tsx

@@ -10,7 +10,6 @@ import { useMediaQuery } from "../use-media-query";
  */
 const meta: Meta = {
   title: "hooks/useMediaQuery",
-  tags: ["beta"],
 };
 
 export default meta;