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

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

@@ -1,56 +1,61 @@
-import { Meta } from "@storybook/react-vite";
+import type { Meta } from "@storybook/react-vite";
 import { Trash } from "lucide-react";
 import { Button, Input } from "../../components";
 import { useLocalStorage } from "../use-local-storage";
 
 /**
- * Hook que proporciona una interfaz sencilla para interactuar con el localStorage de manera tipada.
- *
- * Este hook permite almacenar, recuperar y eliminar valores en el localStorage de manera segura,
- * utilizando una API genérica que asegura la consistencia de tipos en TypeScript. Es compatible con cualquier
- * tipo de dato, desde strings hasta objetos complejos.
- *
- * @param key - La clave del localStorage donde se almacenará el valor.
- * @param initialValue - El valor inicial que se utilizará si no hay datos almacenados bajo la clave proporcionada.
- * @returns Una tupla con el valor almacenado, una función para actualizarlo y otra para eliminarlo.
- *
- * @example
- * const [name, setName, removeName] = useLocalStorage<string>("name", "John Doe");
- *
- * @example
- * const [count, setCount, removeCount] = useLocalStorage<number>("count", 0);
- *
- * @example
- * const [items, setItems, removeItems] = useLocalStorage<string[]>("items", ["apple", "banana"]);
+ * 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>("myKey", "");
+    const [value, setValue, removeValue] = useLocalStorage<string>(
+      "demo:name",
+      "",
+    );
 
     return (
       <div className="space-y-2">
-        <Input value={value} onValueChange={setValue} />
+        <Input value={value} onValueChange={setValue} placeholder="Type…" />
         <Button onClick={removeValue}>Clear</Button>
       </div>
     );
   },
 };
 
-export const WithNumber = {
+/**
+ * `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>("count", 0);
+    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(count + 1)}>Increment</Button>
+          <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>
@@ -58,22 +63,117 @@ export const WithNumber = {
   },
 };
 
-export const WithArray = {
+/**
+ * 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[]>(
-      "oranges",
+      "demo:oranges",
       ["🍊"],
     );
 
     return (
       <div className="space-y-2">
         <ul>
-          {items.map((item, index) => (
-            <li key={index}>{item}</li>
+          {items?.map((item, index) => (
+            <li key={`${item}-${index}`}>{item}</li>
           ))}
         </ul>
         <div className="flex gap-2">
-          <Button onClick={() => setItems([...items, "🍊"])}>
+          <Button onClick={() => setItems((prev) => [...(prev ?? []), "🍊"])}>
             🍊 Add Orange
           </Button>
           <Button onClick={removeItems}>

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

@@ -1,5 +1,5 @@
 import { act, renderHook } from "@testing-library/react";
-import { beforeEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { useLocalStorage } from "../use-local-storage";
 
 describe("useLocalStorage hook", () => {
@@ -9,11 +9,16 @@ describe("useLocalStorage hook", () => {
     localStorage.clear();
   });
 
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
   it("should be defined", () => {
     expect(useLocalStorage).toBeDefined();
   });
 
-  it("should initialize with default value if localStorage is empty", () => {
+  it("returns initialValue when localStorage is empty", () => {
     const { result } = renderHook(() =>
       useLocalStorage<string>(key, "initialValue"),
     );
@@ -22,7 +27,12 @@ describe("useLocalStorage hook", () => {
     expect(storedValue).toBe("initialValue");
   });
 
-  it("should retrieve stored value from localStorage", () => {
+  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(() =>
@@ -33,14 +43,13 @@ describe("useLocalStorage hook", () => {
     expect(storedValue).toBe("storedValue");
   });
 
-  it("should update localStorage when value changes", () => {
+  it("setValue updates the value and writes to localStorage", () => {
     const { result } = renderHook(() =>
       useLocalStorage<string>(key, "initialValue"),
     );
 
-    const [, setValue] = result.current;
-
     act(() => {
+      const [, setValue] = result.current;
       setValue("newValue");
     });
 
@@ -49,54 +58,47 @@ describe("useLocalStorage hook", () => {
     expect(localStorage.getItem(key)).toBe(JSON.stringify("newValue"));
   });
 
-  it("should remove the value from localStorage when remove is called", () => {
+  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, ""));
 
-    const [, , remove] = result.current;
-
     act(() => {
+      const [, , remove] = result.current;
       remove();
     });
 
-    const [storedValue] = result.current;
-    expect(storedValue).toBe("");
+    expect(result.current[0]).toBe("");
+    expect(localStorage.getItem(key)).toBeNull();
   });
 
-  it("should handle non-JSON serializable values gracefully", () => {
+  it("falls back to initialValue and logs when stored value is not JSON", () => {
     const consoleErrorSpy = vi
       .spyOn(console, "error")
-      .mockImplementation(() => {
-        console.log("error");
-      });
+      .mockImplementation(() => {});
     localStorage.setItem(key, "non-JSON-string");
 
     const { result } = renderHook(() =>
       useLocalStorage<string>(key, "initialValue"),
     );
 
-    const [storedValue] = result.current;
-    expect(storedValue).toBe("initialValue");
+    expect(result.current[0]).toBe("initialValue");
     expect(consoleErrorSpy).toHaveBeenCalled();
-
-    consoleErrorSpy.mockRestore();
-  });
-
-  it("calls removeItem when storedValue is undefined (no initial value)", () => {
-    const removeItemMock = vi.fn();
-    vi.stubGlobal("localStorage", {
-      getItem: vi.fn().mockReturnValue(null),
-      setItem: vi.fn(),
-      removeItem: removeItemMock,
-      clear: vi.fn(),
-    });
-    renderHook(() => useLocalStorage<string>("empty-key"));
-    expect(removeItemMock).toHaveBeenCalledWith("empty-key");
-    vi.unstubAllGlobals();
   });
 
-  it("handles localStorage.setItem errors in useEffect gracefully", () => {
+  it("logs when localStorage.setItem throws during setValue", () => {
     const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
     vi.stubGlobal("localStorage", {
       getItem: vi.fn().mockReturnValue(null),
@@ -106,13 +108,20 @@ describe("useLocalStorage hook", () => {
       removeItem: vi.fn(),
       clear: vi.fn(),
     });
-    renderHook(() => useLocalStorage<string>("err-key", "value"));
+
+    const { result } = renderHook(() =>
+      useLocalStorage<string>("err-key", "value"),
+    );
+
+    act(() => {
+      const [, setValue] = result.current;
+      setValue("next");
+    });
+
     expect(errorSpy).toHaveBeenCalled();
-    vi.unstubAllGlobals();
-    errorSpy.mockRestore();
   });
 
-  it("handles localStorage.removeItem errors in remove() gracefully", () => {
+  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")),
@@ -122,10 +131,66 @@ describe("useLocalStorage hook", () => {
       }),
       clear: vi.fn(),
     });
-    const { result } = renderHook(() => useLocalStorage<string>("key", "value"));
-    act(() => result.current[2]());
+
+    const { result } = renderHook(() =>
+      useLocalStorage<string>("rm-key", "value"),
+    );
+
+    act(() => {
+      result.current[2]();
+    });
+
     expect(errorSpy).toHaveBeenCalled();
-    vi.unstubAllGlobals();
-    errorSpy.mockRestore();
+  });
+
+  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

@@ -1,56 +1,125 @@
-import { useEffect, useState } from "react";
+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) => void, () => void];
+): [
+  T | undefined,
+  (value: T | ((prev: T | undefined) => T)) => void,
+  () => void,
+];
 export function useLocalStorage<T>(
   key: string,
   initialValue: T,
-): [T, (value: T) => void, () => void];
+  options?: UseLocalStorageOptions<T>,
+): [T, (value: T | ((prev: T) => T)) => void, () => void];
 export function useLocalStorage<T>(
   key: string,
   initialValue?: T,
-): [T | undefined, (value: T) => void, () => void] {
-  const getStoredValue = (): T | undefined => {
+  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 {
-      const item = localStorage.getItem(key);
-      if (item) {
-        return JSON.parse(item) as T;
-      }
-      return initialValue !== undefined ? initialValue : undefined;
-    } catch (error) {
-      console.error(`Error parsing localStorage key "${key}":`, error);
-      return initialValue !== undefined ? initialValue : undefined;
+      return localStorage.getItem(key);
+    } catch {
+      return null;
     }
-  };
+  }, [key]);
 
-  const [storedValue, setStoredValue] = useState<T | undefined>(getStoredValue);
+  const getServerSnapshot = useCallback((): string | null => null, []);
 
-  useEffect(() => {
+  const raw = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+
+  const value = useMemo<T | undefined>(() => {
+    if (raw === null) return initialValue;
     try {
-      if (storedValue !== undefined) {
-        localStorage.setItem(key, JSON.stringify(storedValue));
-      } else {
-        localStorage.removeItem(key);
-      }
+      return serializer.read(raw);
     } catch (error) {
-      console.error(`Error setting localStorage key "${key}":`, error);
+      console.error(`Error parsing localStorage key "${key}":`, error);
+      return initialValue;
     }
-  }, [key, storedValue]);
+  }, [raw, initialValue, key, serializer]);
 
-  const setValue = (value: T) => {
-    setStoredValue(value);
-  };
+  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 = () => {
+  const remove = useCallback(() => {
     try {
       localStorage.removeItem(key);
-      setStoredValue(initialValue !== undefined ? initialValue : undefined);
+      notifyKey(key);
     } catch (error) {
       console.error(`Error removing localStorage key "${key}":`, error);
     }
-  };
+  }, [key]);
 
-  return [storedValue, setValue, remove];
+  return [value, setValue, remove];
 }
-