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

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

@@ -0,0 +1,186 @@
+import type { Meta } from "@storybook/react-vite";
+import { Trash } from "lucide-react";
+import { Button, Input } from "../../components";
+import { useLocalStorage } from "../use-local-storage";
+
+/**
+ * Persists a value in `window.localStorage` and stays in sync across
+ * every instance reading the same key (in the same tab and across tabs
+ * via the `storage` event). Returns `[value, setValue, remove]`. SSR-safe:
+ * during server render the value falls back to `initialValue` and nothing
+ * is written. Values are JSON-serialized by default; pass a `serializer`
+ * option to customize.
+ */
+const meta: Meta = {
+  title: "hooks/useLocalStorage",
+  tags: ["beta"],
+};
+
+export default meta;
+
+export const Default = {
+  render: () => {
+    const [value, setValue, removeValue] = useLocalStorage<string>(
+      "demo:name",
+      "",
+    );
+
+    return (
+      <div className="space-y-2">
+        <Input value={value} onValueChange={setValue} placeholder="Type…" />
+        <Button onClick={removeValue}>Clear</Button>
+      </div>
+    );
+  },
+};
+
+/**
+ * `setValue` accepts a functional updater that receives the previous
+ * value, matching the `useState` signature. Safe for rapid consecutive
+ * updates because the closure always reads the latest value.
+ */
+export const FunctionalUpdater = {
+  render: () => {
+    const [count, setCount, removeCount] = useLocalStorage<number>(
+      "demo:count",
+      0,
+    );
+
+    return (
+      <div className="space-y-2">
+        <p>Count: {count}</p>
+        <div className="flex gap-2">
+          <Button onClick={() => setCount((prev) => (prev ?? 0) + 1)}>
+            Increment
+          </Button>
+          <Button onClick={() => setCount((prev) => (prev ?? 0) - 1)}>
+            Decrement
+          </Button>
+          <Button onClick={removeCount}>Reset</Button>
+        </div>
+      </div>
+    );
+  },
+};
+
+/**
+ * Two hooks reading the same key stay synchronized in the same tab.
+ * Updating from one component updates the other on the next render —
+ * no prop drilling required.
+ */
+export const CrossInstanceSync = {
+  render: () => {
+    const [a, setA] = useLocalStorage<string>("demo:shared", "");
+    const [b, setB] = useLocalStorage<string>("demo:shared", "");
+
+    return (
+      <div className="space-y-4">
+        <div className="space-y-1">
+          <p className="text-muted-foreground text-sm">Instance A</p>
+          <Input value={a} onValueChange={setA} />
+        </div>
+        <div className="space-y-1">
+          <p className="text-muted-foreground text-sm">Instance B</p>
+          <Input value={b} onValueChange={setB} />
+        </div>
+      </div>
+    );
+  },
+};
+
+/**
+ * Open this story in two browser tabs at the same URL and edit the
+ * input in one tab. The other tab updates immediately via the native
+ * `storage` event.
+ */
+export const CrossTabSync = {
+  render: () => {
+    const [value, setValue, removeValue] = useLocalStorage<string>(
+      "demo:cross-tab",
+      "",
+    );
+
+    return (
+      <div className="space-y-2">
+        <Input
+          value={value}
+          onValueChange={setValue}
+          placeholder="Edit in one tab, watch the other"
+        />
+        <Button onClick={removeValue}>Clear</Button>
+      </div>
+    );
+  },
+};
+
+/**
+ * Provide a custom `serializer` to control how values are written to
+ * and read from storage. Useful for non-JSON formats, date objects,
+ * or encrypted payloads.
+ *
+ * ```tsx
+ * const dateSerializer = {
+ *   read: (raw: string) => new Date(raw),
+ *   write: (value: Date) => value.toISOString(),
+ * };
+ *
+ * useLocalStorage<Date>("demo:date", new Date(), {
+ *   serializer: dateSerializer,
+ * });
+ * ```
+ */
+export const CustomSerializer = {
+  render: () => {
+    const upperCase = {
+      read: (raw: string) => raw.toUpperCase(),
+      write: (value: string) => value.toLowerCase(),
+    };
+
+    const [value, setValue, remove] = useLocalStorage<string>(
+      "demo:upper",
+      "INITIAL",
+      { serializer: upperCase },
+    );
+
+    return (
+      <div className="space-y-2">
+        <Input value={value} onValueChange={setValue} />
+        <p className="text-muted-foreground text-sm">
+          Stored on disk: written lowercase, read uppercase.
+        </p>
+        <Button onClick={remove}>Clear</Button>
+      </div>
+    );
+  },
+};
+
+/**
+ * Works with any JSON-serializable shape. Reading a non-JSON value
+ * logs a console error and falls back to `initialValue`.
+ */
+export const ArrayValue = {
+  render: () => {
+    const [items, setItems, removeItems] = useLocalStorage<string[]>(
+      "demo:oranges",
+      ["🍊"],
+    );
+
+    return (
+      <div className="space-y-2">
+        <ul>
+          {items?.map((item, index) => (
+            <li key={`${item}-${index}`}>{item}</li>
+          ))}
+        </ul>
+        <div className="flex gap-2">
+          <Button onClick={() => setItems((prev) => [...(prev ?? []), "🍊"])}>
+            🍊 Add Orange
+          </Button>
+          <Button onClick={removeItems}>
+            <Trash /> Clear List
+          </Button>
+        </div>
+      </div>
+    );
+  },
+};

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

@@ -0,0 +1,196 @@
+import { act, renderHook } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { useLocalStorage } from "../use-local-storage";
+
+describe("useLocalStorage hook", () => {
+  const key = "testKey";
+
+  beforeEach(() => {
+    localStorage.clear();
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  it("should be defined", () => {
+    expect(useLocalStorage).toBeDefined();
+  });
+
+  it("returns initialValue when localStorage is empty", () => {
+    const { result } = renderHook(() =>
+      useLocalStorage<string>(key, "initialValue"),
+    );
+
+    const [storedValue] = result.current;
+    expect(storedValue).toBe("initialValue");
+  });
+
+  it("does NOT write initialValue to localStorage on mount", () => {
+    renderHook(() => useLocalStorage<string>(key, "initialValue"));
+    expect(localStorage.getItem(key)).toBeNull();
+  });
+
+  it("reads an existing stored value from localStorage", () => {
+    localStorage.setItem(key, JSON.stringify("storedValue"));
+
+    const { result } = renderHook(() =>
+      useLocalStorage<string>(key, "initialValue"),
+    );
+
+    const [storedValue] = result.current;
+    expect(storedValue).toBe("storedValue");
+  });
+
+  it("setValue updates the value and writes to localStorage", () => {
+    const { result } = renderHook(() =>
+      useLocalStorage<string>(key, "initialValue"),
+    );
+
+    act(() => {
+      const [, setValue] = result.current;
+      setValue("newValue");
+    });
+
+    const [storedValue] = result.current;
+    expect(storedValue).toBe("newValue");
+    expect(localStorage.getItem(key)).toBe(JSON.stringify("newValue"));
+  });
+
+  it("setValue accepts a functional updater", () => {
+    const { result } = renderHook(() => useLocalStorage<number>(key, 1));
+
+    act(() => {
+      const [, setValue] = result.current;
+      setValue((prev) => (prev ?? 0) + 5);
+    });
+
+    expect(result.current[0]).toBe(6);
+    expect(localStorage.getItem(key)).toBe("6");
+  });
+
+  it("remove() deletes the key and falls back to initialValue", () => {
+    localStorage.setItem(key, JSON.stringify("storedValue"));
+
+    const { result } = renderHook(() => useLocalStorage<string>(key, ""));
+
+    act(() => {
+      const [, , remove] = result.current;
+      remove();
+    });
+
+    expect(result.current[0]).toBe("");
+    expect(localStorage.getItem(key)).toBeNull();
+  });
+
+  it("falls back to initialValue and logs when stored value is not JSON", () => {
+    const consoleErrorSpy = vi
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+    localStorage.setItem(key, "non-JSON-string");
+
+    const { result } = renderHook(() =>
+      useLocalStorage<string>(key, "initialValue"),
+    );
+
+    expect(result.current[0]).toBe("initialValue");
+    expect(consoleErrorSpy).toHaveBeenCalled();
+  });
+
+  it("logs when localStorage.setItem throws during setValue", () => {
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    vi.stubGlobal("localStorage", {
+      getItem: vi.fn().mockReturnValue(null),
+      setItem: vi.fn().mockImplementation(() => {
+        throw new Error("Storage full");
+      }),
+      removeItem: vi.fn(),
+      clear: vi.fn(),
+    });
+
+    const { result } = renderHook(() =>
+      useLocalStorage<string>("err-key", "value"),
+    );
+
+    act(() => {
+      const [, setValue] = result.current;
+      setValue("next");
+    });
+
+    expect(errorSpy).toHaveBeenCalled();
+  });
+
+  it("logs when localStorage.removeItem throws during remove()", () => {
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    vi.stubGlobal("localStorage", {
+      getItem: vi.fn().mockReturnValue(JSON.stringify("value")),
+      setItem: vi.fn(),
+      removeItem: vi.fn().mockImplementation(() => {
+        throw new Error("remove error");
+      }),
+      clear: vi.fn(),
+    });
+
+    const { result } = renderHook(() =>
+      useLocalStorage<string>("rm-key", "value"),
+    );
+
+    act(() => {
+      result.current[2]();
+    });
+
+    expect(errorSpy).toHaveBeenCalled();
+  });
+
+  it("syncs two instances of the hook on the same key in the same tab", () => {
+    const a = renderHook(() => useLocalStorage<string>(key, "init"));
+    const b = renderHook(() => useLocalStorage<string>(key, "init"));
+
+    act(() => {
+      a.result.current[1]("from-a");
+    });
+
+    expect(a.result.current[0]).toBe("from-a");
+    expect(b.result.current[0]).toBe("from-a");
+  });
+
+  it("reacts to a cross-tab `storage` event", () => {
+    const { result } = renderHook(() =>
+      useLocalStorage<string>(key, "initial"),
+    );
+
+    act(() => {
+      localStorage.setItem(key, JSON.stringify("changed-externally"));
+      // jsdom rejects `storageArea` in StorageEventInit, so assign it after
+      // construction to satisfy the hook's `event.storageArea === localStorage`
+      // guard.
+      const event = new StorageEvent("storage", {
+        key,
+        newValue: JSON.stringify("changed-externally"),
+      });
+      Object.defineProperty(event, "storageArea", { value: localStorage });
+      window.dispatchEvent(event);
+    });
+
+    expect(result.current[0]).toBe("changed-externally");
+  });
+
+  it("supports a custom serializer", () => {
+    const serializer = {
+      read: (raw: string) => raw.toUpperCase(),
+      write: (value: string) => value.toLowerCase(),
+    };
+
+    const { result } = renderHook(() =>
+      useLocalStorage<string>(key, "INITIAL", { serializer }),
+    );
+
+    act(() => {
+      result.current[1]("MixedCase");
+    });
+
+    expect(localStorage.getItem(key)).toBe("mixedcase");
+    expect(result.current[0]).toBe("MIXEDCASE");
+  });
+});

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

@@ -0,0 +1,125 @@
+import { useCallback, useMemo, useSyncExternalStore } from "react";
+import { isBrowser } from "../internal";
+
+export interface Serializer<T> {
+  read: (raw: string) => T;
+  write: (value: T) => string;
+}
+
+export interface UseLocalStorageOptions<T> {
+  serializer?: Serializer<T>;
+}
+
+const defaultSerializer: Serializer<unknown> = {
+  read: (raw) => JSON.parse(raw) as unknown,
+  write: (value) => JSON.stringify(value),
+};
+
+type Listener = () => void;
+const listeners = new Map<string, Set<Listener>>();
+
+function notifyKey(key: string): void {
+  listeners.get(key)?.forEach((listener) => listener());
+}
+
+function subscribeKey(key: string, listener: Listener): () => void {
+  if (!isBrowser) return () => {};
+
+  let bucket = listeners.get(key);
+  if (!bucket) {
+    bucket = new Set();
+    listeners.set(key, bucket);
+  }
+  bucket.add(listener);
+
+  const onStorage = (event: StorageEvent) => {
+    if (event.storageArea !== localStorage) return;
+    if (event.key === key || event.key === null) listener();
+  };
+  window.addEventListener("storage", onStorage);
+
+  return () => {
+    bucket.delete(listener);
+    if (bucket.size === 0) listeners.delete(key);
+    window.removeEventListener("storage", onStorage);
+  };
+}
+
+export function useLocalStorage<T>(
+  key: string,
+): [
+  T | undefined,
+  (value: T | ((prev: T | undefined) => T)) => void,
+  () => void,
+];
+export function useLocalStorage<T>(
+  key: string,
+  initialValue: T,
+  options?: UseLocalStorageOptions<T>,
+): [T, (value: T | ((prev: T) => T)) => void, () => void];
+export function useLocalStorage<T>(
+  key: string,
+  initialValue?: T,
+  options: UseLocalStorageOptions<T> = {},
+): [
+  T | undefined,
+  (value: T | ((prev: T | undefined) => T)) => void,
+  () => void,
+] {
+  const serializer = (options.serializer ?? defaultSerializer) as Serializer<T>;
+
+  const subscribe = useCallback(
+    (listener: Listener) => subscribeKey(key, listener),
+    [key],
+  );
+
+  const getSnapshot = useCallback((): string | null => {
+    if (!isBrowser) return null;
+    try {
+      return localStorage.getItem(key);
+    } catch {
+      return null;
+    }
+  }, [key]);
+
+  const getServerSnapshot = useCallback((): string | null => null, []);
+
+  const raw = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+
+  const value = useMemo<T | undefined>(() => {
+    if (raw === null) return initialValue;
+    try {
+      return serializer.read(raw);
+    } catch (error) {
+      console.error(`Error parsing localStorage key "${key}":`, error);
+      return initialValue;
+    }
+  }, [raw, initialValue, key, serializer]);
+
+  const setValue = useCallback(
+    (next: T | ((prev: T | undefined) => T)) => {
+      try {
+        const resolved =
+          typeof next === "function"
+            ? (next as (prev: T | undefined) => T)(value)
+            : next;
+        localStorage.setItem(key, serializer.write(resolved));
+        notifyKey(key);
+      } catch (error) {
+        console.error(`Error setting localStorage key "${key}":`, error);
+      }
+    },
+    [key, value, serializer],
+  );
+
+  const remove = useCallback(() => {
+    try {
+      localStorage.removeItem(key);
+      notifyKey(key);
+    } catch (error) {
+      console.error(`Error removing localStorage key "${key}":`, error);
+    }
+  }, [key]);
+
+  return [value, setValue, remove];
+}

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

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

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

@@ -0,0 +1,99 @@
+import type { Meta } from "@storybook/react-vite";
+import { useMediaQuery } from "../use-media-query";
+
+/**
+ * Subscribes to a CSS media query and returns whether it currently
+ * matches. Powered by `useSyncExternalStore` so multiple subscribers
+ * stay in sync and updates fire from the native `change` event. SSR-safe:
+ * pass `defaultValue` to control what is returned during server render
+ * and on the first client render, which avoids hydration mismatches.
+ */
+const meta: Meta = {
+  title: "hooks/useMediaQuery",
+  tags: ["beta"],
+};
+
+export default meta;
+
+/**
+ * Resize the preview to cross each breakpoint and watch the active row
+ * light up. Each row is an independent `useMediaQuery` subscription.
+ */
+export const Default = {
+  render: () => {
+    const breakpoints = [
+      { label: "Small", emoji: "📱", query: "(max-width: 768px)" },
+      {
+        label: "Medium",
+        emoji: "💻",
+        query: "(min-width: 769px) and (max-width: 992px)",
+      },
+      {
+        label: "Large",
+        emoji: "🖥️",
+        query: "(min-width: 993px) and (max-width: 1200px)",
+      },
+      { label: "Extra large", emoji: "🖥️", query: "(min-width: 1201px)" },
+    ];
+
+    return (
+      <div className="flex w-full max-w-sm flex-col gap-2">
+        {breakpoints.map((bp) => (
+          <BreakpointRow key={bp.query} {...bp} />
+        ))}
+      </div>
+    );
+  },
+};
+
+function BreakpointRow({
+  label,
+  emoji,
+  query,
+}: {
+  label: string;
+  emoji: string;
+  query: string;
+}) {
+  const matches = useMediaQuery(query);
+
+  return (
+    <div
+      className={`flex items-center justify-between rounded-md border px-3 py-2 text-sm transition-colors ${
+        matches
+          ? "border-primary bg-primary/10 font-medium text-foreground"
+          : "border-input text-muted-foreground"
+      }`}
+    >
+      <span>
+        {emoji} {label}
+      </span>
+      <code className="text-xs">{query}</code>
+    </div>
+  );
+}
+
+/**
+ * Pass `defaultValue` to align the first render with whatever the
+ * server rendered. Common pattern for responsive layouts under SSR
+ * where the breakpoint is known from the request user-agent or a cookie.
+ *
+ * ```tsx
+ * const isMobile = useMediaQuery("(max-width: 768px)", {
+ *   defaultValue: serverIsMobile,
+ * });
+ * ```
+ */
+export const WithDefaultValue = {
+  render: () => {
+    const isMobile = useMediaQuery("(max-width: 768px)", {
+      defaultValue: true,
+    });
+
+    return (
+      <p className="text-sm">
+        Layout: <strong>{isMobile ? "mobile" : "desktop"}</strong>
+      </p>
+    );
+  },
+};