@boxcustodia/library 2.0.0-alpha.2 → 2.0.0-alpha.21

package/src/hooks/use-media-query/use-media-query.test.ts

@@ -0,0 +1,132 @@
+import { act, renderHook } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { useMediaQuery } from "./use-media-query";
+
+type Listener = (event: { matches: boolean }) => void;
+
+interface MockMediaQueryList {
+  matches: boolean;
+  addEventListener: ReturnType<typeof vi.fn>;
+  removeEventListener: ReturnType<typeof vi.fn>;
+  setMatches: (next: boolean) => void;
+}
+
+function createMockMatchMedia() {
+  const listeners = new Map<string, Set<Listener>>();
+  const states = new Map<string, MockMediaQueryList>();
+
+  const matchMedia = vi.fn((query: string): MockMediaQueryList => {
+    let state = states.get(query);
+    if (state) return state;
+
+    const queryListeners = new Set<Listener>();
+    listeners.set(query, queryListeners);
+
+    state = {
+      matches: false,
+      addEventListener: vi.fn((_type: string, listener: Listener) => {
+        queryListeners.add(listener);
+      }),
+      removeEventListener: vi.fn((_type: string, listener: Listener) => {
+        queryListeners.delete(listener);
+      }),
+      setMatches(next: boolean) {
+        if (this.matches === next) return;
+        this.matches = next;
+        for (const listener of queryListeners) {
+          listener({ matches: next });
+        }
+      },
+    };
+    states.set(query, state);
+    return state;
+  });
+
+  return {
+    matchMedia,
+    getState: (query: string) => states.get(query),
+  };
+}
+
+describe("useMediaQuery hook", () => {
+  let mock: ReturnType<typeof createMockMatchMedia>;
+
+  beforeEach(() => {
+    mock = createMockMatchMedia();
+    vi.stubGlobal("matchMedia", mock.matchMedia);
+    Object.defineProperty(window, "matchMedia", {
+      configurable: true,
+      value: mock.matchMedia,
+    });
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("returns the initial `matches` value from matchMedia", () => {
+    const query = "(max-width: 768px)";
+    const { result } = renderHook(() => useMediaQuery(query));
+
+    expect(result.current).toBe(false);
+    expect(mock.matchMedia).toHaveBeenCalledWith(query);
+  });
+
+  it("reflects later changes to the match state", () => {
+    const query = "(max-width: 768px)";
+    const { result } = renderHook(() => useMediaQuery(query));
+
+    act(() => {
+      mock.getState(query)?.setMatches(true);
+    });
+
+    expect(result.current).toBe(true);
+
+    act(() => {
+      mock.getState(query)?.setMatches(false);
+    });
+
+    expect(result.current).toBe(false);
+  });
+
+  it("subscribes on mount and unsubscribes on unmount", () => {
+    const query = "(max-width: 768px)";
+    const { unmount } = renderHook(() => useMediaQuery(query));
+
+    const state = mock.getState(query);
+    expect(state?.addEventListener).toHaveBeenCalledTimes(1);
+
+    unmount();
+
+    expect(state?.removeEventListener).toHaveBeenCalledTimes(1);
+  });
+
+  it("re-subscribes when the query changes", () => {
+    const { rerender } = renderHook(({ query }) => useMediaQuery(query), {
+      initialProps: { query: "(max-width: 768px)" },
+    });
+
+    rerender({ query: "(min-width: 1024px)" });
+
+    expect(
+      mock.getState("(max-width: 768px)")?.removeEventListener,
+    ).toHaveBeenCalled();
+    expect(
+      mock.getState("(min-width: 1024px)")?.addEventListener,
+    ).toHaveBeenCalled();
+  });
+
+  it("returns defaultValue when window.matchMedia is unavailable", () => {
+    vi.unstubAllGlobals();
+    Object.defineProperty(window, "matchMedia", {
+      configurable: true,
+      value: undefined,
+    });
+
+    const { result } = renderHook(() =>
+      useMediaQuery("(max-width: 768px)", { defaultValue: true }),
+    );
+
+    expect(result.current).toBe(true);
+  });
+});

package/src/hooks/use-media-query/use-media-query.ts

@@ -0,0 +1,45 @@
+import { useCallback, useSyncExternalStore } from "react";
+import { isBrowser } from "../internal";
+
+export interface UseMediaQueryOptions {
+  /**
+   * Value returned during server render and on the first client render
+   * before `matchMedia` has been read. Use this to avoid hydration
+   * mismatches in SSR consumers that already know the breakpoint.
+   * @default false
+   */
+  defaultValue?: boolean;
+}
+
+function canMatch(): boolean {
+  return isBrowser && typeof window.matchMedia === "function";
+}
+
+export function useMediaQuery(
+  query: string,
+  options: UseMediaQueryOptions = {},
+): boolean {
+  const { defaultValue = false } = options;
+
+  const subscribe = useCallback(
+    (listener: () => void) => {
+      if (!canMatch()) return () => {};
+      const mql = window.matchMedia(query);
+      mql.addEventListener("change", listener);
+      return () => mql.removeEventListener("change", listener);
+    },
+    [query],
+  );
+
+  const getSnapshot = useCallback((): boolean => {
+    if (!canMatch()) return defaultValue;
+    return window.matchMedia(query).matches;
+  }, [query, defaultValue]);
+
+  const getServerSnapshot = useCallback(
+    (): boolean => defaultValue,
+    [defaultValue],
+  );
+
+  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}

package/src/hooks/use-memoized-fn/index.ts

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

package/src/hooks/use-memoized-fn/use-memoized-fn.test.ts

@@ -0,0 +1,52 @@
+import { renderHook } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { useMemoizedFn } from "./use-memoized-fn";
+
+describe("useMemoizedFn", () => {
+  it("returns a stable function reference across re-renders", () => {
+    const fn = vi.fn();
+    const { result, rerender } = renderHook(() => useMemoizedFn(fn));
+    const first = result.current;
+    rerender();
+    expect(result.current).toBe(first);
+  });
+
+  it("calls the latest version of the function", () => {
+    const first = vi.fn(() => "first");
+    const second = vi.fn(() => "second");
+
+    const { result, rerender } = renderHook(({ fn }) => useMemoizedFn(fn), {
+      initialProps: { fn: first as () => string },
+    });
+
+    const stable = result.current;
+
+    rerender({ fn: second });
+
+    expect(stable()).toBe("second");
+    expect(first).not.toHaveBeenCalled();
+    expect(second).toHaveBeenCalledOnce();
+  });
+
+  it("forwards arguments correctly", () => {
+    const fn = vi.fn((a: number, b: string) => `${a}-${b}`);
+    const { result } = renderHook(() => useMemoizedFn(fn));
+
+    const ret = result.current(1, "hello");
+
+    expect(fn).toHaveBeenCalledWith(1, "hello");
+    expect(ret).toBe("1-hello");
+  });
+
+  it("logs error when non-function is passed", () => {
+    const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+
+    renderHook(() => useMemoizedFn("not-a-function" as any));
+
+    expect(consoleSpy).toHaveBeenCalledWith(
+      expect.stringContaining("useMemoizedFn expected parameter is a function"),
+    );
+
+    consoleSpy.mockRestore();
+  });
+});

package/src/hooks/use-memoized-fn/use-memoized-fn.ts

@@ -0,0 +1,29 @@
+import { useMemo, useRef } from "react";
+
+type noop = (this: any, ...args: any[]) => any;
+
+type PickFunction<T extends noop> = (
+  this: ThisParameterType<T>,
+  ...args: Parameters<T>
+) => ReturnType<T>;
+
+export function useMemoizedFn<T extends noop>(fn: T) {
+  if (typeof fn !== "function") {
+    console.error(
+      `useMemoizedFn expected parameter is a function, got ${typeof fn}`,
+    );
+  }
+
+  const fnRef = useRef<T>(fn);
+
+  fnRef.current = useMemo<T>(() => fn, [fn]);
+
+  const memoizedFn = useRef<PickFunction<T>>(null);
+  if (!memoizedFn.current) {
+    memoizedFn.current = function (this, ...args) {
+      return fnRef.current.apply(this, args);
+    };
+  }
+
+  return memoizedFn.current as T;
+}

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

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

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

@@ -0,0 +1,277 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useState } from "react";
+import { Button } from "../../components";
+import { type UseMutationOptions, useMutation } from "./use-mutation";
+
+// ─── Demo component ──────────────────────────────────────────────────────────
+
+interface DemoVariables {
+  value: string;
+}
+
+interface DemoData {
+  message: string;
+  timestamp: number;
+}
+
+type MutationDemoProps = UseMutationOptions<DemoVariables, DemoData> & {
+  /** Simulated async delay in ms */
+  delay?: number;
+  /** When true the mutation will reject with an error */
+  shouldFail?: boolean;
+};
+
+const MutationDemo = ({
+  delay = 800,
+  shouldFail = false,
+  onMutate,
+  onSuccess,
+  onError,
+  onSettled,
+}: MutationDemoProps) => {
+  const [log, setLog] = useState<string[]>([]);
+
+  const addLog = (msg: string) =>
+    setLog((prev) => [
+      `[${new Date().toISOString().slice(11, 23)}] ${msg}`,
+      ...prev,
+    ]);
+
+  const mutation = useMutation<DemoVariables, DemoData>({
+    fn: async (vars) => {
+      await new Promise((res, rej) =>
+        setTimeout(
+          () =>
+            shouldFail ? rej(new Error("Simulated failure")) : res(undefined),
+          delay,
+        ),
+      );
+      return { message: `Created: ${vars.value}`, timestamp: Date.now() };
+    },
+    onMutate: (vars) => {
+      addLog(`onMutate — vars: ${JSON.stringify(vars)}`);
+      onMutate?.(vars);
+    },
+    onSuccess: (data, vars) => {
+      addLog(`onSuccess — data: ${data.message}`);
+      onSuccess?.(data, vars);
+    },
+    onError: (err, vars) => {
+      addLog(`onError — ${err.message}`);
+      onError?.(err, vars);
+    },
+    onSettled: (data, err, vars) => {
+      addLog(
+        `onSettled — data: ${data?.message ?? "null"}, error: ${err?.message ?? "null"}`,
+      );
+      onSettled?.(data, err, vars);
+    },
+  });
+
+  return (
+    <div className="flex flex-col gap-4 max-w-sm">
+      <div className="flex gap-2">
+        <Button
+          onClick={() => mutation.mutate({ value: "item-1" })}
+          disabled={mutation.isPending}
+        >
+          {mutation.isPending ? "Running…" : "Mutate"}
+        </Button>
+        <Button
+          variant="outline"
+          onClick={() => mutation.reset()}
+          disabled={mutation.isPending}
+        >
+          Reset
+        </Button>
+      </div>
+
+      <pre className="rounded-md bg-slate-950 p-3 text-xs text-white leading-relaxed">
+        {JSON.stringify(
+          {
+            status: mutation.status,
+            data: mutation.data,
+            error: mutation.error?.message ?? null,
+          },
+          null,
+          2,
+        )}
+      </pre>
+
+      {log.length > 0 && (
+        <div className="rounded-md border bg-muted p-3 text-xs font-mono space-y-0.5">
+          {log.map((entry, i) => (
+            <div key={i}>{entry}</div>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+};
+
+// ─── Meta ─────────────────────────────────────────────────────────────────────
+
+const meta: Meta<typeof MutationDemo> = {
+  title: "hooks/useMutation",
+  component: MutationDemo,
+  parameters: {
+    docs: {
+      description: {
+        component: `
+\`useMutation\` manages async mutation lifecycle with stable callback identity.
+
+**API summary**
+
+\`\`\`ts
+const { mutate, mutateAsync, reset, status, data, error, isPending, isSuccess, isError, isIdle } =
+  useMutation({ fn, onMutate?, onSuccess?, onError?, onSettled? });
+\`\`\`
+
+**Lifecycle order (success):** \`onMutate\` → \`fn\` → \`onSuccess\` → \`onSettled\`
+
+**Lifecycle order (error):** \`onMutate\` → \`fn\` throws → \`onError\` → \`onSettled\`
+
+**Key guarantees**
+- \`mutate\` is fire-and-forget: returns \`void\`, never throws.
+- \`mutateAsync\` returns a \`Promise\` that re-throws on failure.
+- \`onSettled\` is always called — even if \`onError\` throws.
+- All callbacks read through \`useLatestRef\`, so inline functions never recreate \`mutate\`.
+        `.trim(),
+      },
+    },
+  },
+  argTypes: {
+    delay: {
+      control: { type: "range", min: 0, max: 3000, step: 100 },
+      description:
+        "Simulated async delay in ms — demo control only, not a hook option.",
+      table: { category: "Demo controls" },
+    },
+    shouldFail: {
+      control: "boolean",
+      description:
+        "When true the demo's fn rejects — simulates an API error. Demo control only, not a hook option.",
+      table: { category: "Demo controls" },
+    },
+    onMutate: {
+      action: "onMutate",
+      description:
+        "Called synchronously with `variables` before `fn` is awaited. Use for optimistic updates.",
+      table: {
+        category: "Hook options",
+        type: { summary: "(variables: TVariables) => void" },
+      },
+    },
+    onSuccess: {
+      action: "onSuccess",
+      description:
+        "Called with `(data, variables)` after `fn` resolves successfully.",
+      table: {
+        category: "Hook options",
+        type: { summary: "(data: TData, variables: TVariables) => void" },
+      },
+    },
+    onError: {
+      action: "onError",
+      description: "Called with `(error, variables)` when `fn` rejects.",
+      table: {
+        category: "Hook options",
+        type: { summary: "(error: Error, variables: TVariables) => void" },
+      },
+    },
+    onSettled: {
+      action: "onSettled",
+      description:
+        "Always called after `onSuccess` or `onError`, even if one of them throws.",
+      table: {
+        category: "Hook options",
+        type: {
+          summary:
+            "(data: TData | null, error: Error | null, variables: TVariables) => void",
+        },
+      },
+    },
+  },
+  render: (args) => <MutationDemo {...args} />,
+};
+
+export default meta;
+type Story = StoryObj<typeof MutationDemo>;
+
+// ─── Stories ──────────────────────────────────────────────────────────────────
+
+export const Idle: Story = {
+  args: {
+    delay: 800,
+    shouldFail: false,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Default idle state before any mutation is triggered. All booleans are false except `isIdle`.",
+      },
+    },
+  },
+};
+
+export const Pending: Story = {
+  args: {
+    delay: 3000,
+    shouldFail: false,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Click **Mutate** to see `isPending=true` while the operation runs. The button disables until the promise settles.",
+      },
+    },
+  },
+};
+
+export const Success: Story = {
+  args: {
+    delay: 600,
+    shouldFail: false,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "After the mutation resolves, `status` becomes `'success'` and `data` is populated. `error` remains null.",
+      },
+    },
+  },
+};
+
+export const ErrorState: Story = {
+  name: "Error",
+  args: {
+    delay: 600,
+    shouldFail: true,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Toggle **shouldFail** in controls to simulate a failing API call. `status` becomes `'error'`, `error` is set, and `data` stays null. `mutate` swallows the rejection silently — use `mutateAsync` if you need to catch it.",
+      },
+    },
+  },
+};
+
+export const ResetAfterSuccess: Story = {
+  args: {
+    delay: 600,
+    shouldFail: false,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "After a successful mutation, click **Reset** to return to `idle` and clear `data`. `reset()` does not abort in-flight mutations — it only clears state.",
+      },
+    },
+  },
+};