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

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

@@ -1,119 +1,229 @@
-import { useCallback, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useLatestRef } from "../internal/use-latest-ref";
 
-type Return<T> = {
-  /**
-   * Indica si todos los elementos están seleccionados.
-   */
-  isAllSelected: boolean;
+/** Stable identity projected from an item. */
+export type Key = string | number | symbol;
 
+export interface UseSelectionOptions<T> {
   /**
-   * Indica si algunos elementos están seleccionados.
+   * Projects a stable key from an item. Frozen on mount.
+   * When omitted, the item itself is used as its key (reference identity for
+   * objects, value identity for primitives). Pass this for object lists that
+   * are re-created across renders (e.g. after a fetch) so selection survives.
    */
-  isSomeSelected: boolean;
+  keyFn?: (item: T) => Key;
+  /** Initial selection. Frozen on mount — never re-applied on re-render. */
+  defaultSelected?: T[];
+  /** Called after every selection change. NOT called on initial mount. */
+  onChange?: (selected: T[]) => void;
+}
 
-  /**
-   * Indica si ningun elemento está seleccionado.
-   */
+export interface UseSelectionReturn<T> {
+  /** Currently-selected items present in `items`. Stable reference. */
+  selected: T[];
+  /** All selected keys, including keys whose item is absent (sticky). */
+  selectedKeys: ReadonlySet<Key>;
+  /** True when every item in `items` is selected (false when empty). */
+  isAllSelected: boolean;
+  /** True when at least one — but not all — items are selected. */
+  isSomeSelected: boolean;
+  /** True when nothing is selected. */
   isNoneSelected: boolean;
-
-  /**
-   * Función que devuelve true si el elemento dado está seleccionado, false de lo contrario.
-   * @param item El elemento a verificar.
-   * @returns true si el elemento está seleccionado, false de lo contrario.
-   */
+  /** Stable fn ref: true if `item` is selected. */
   isSelected: (item: T) => boolean;
-
-  /**
-   * Array de elementos seleccionados.
-   */
-  selected: T[];
-
-  /**
-   * Establece los elementos seleccionados.
-   * @param items Los elementos seleccionados.
-   */
-  setSelected: (items: T[]) => void;
-
-  /**
-   * Selecciona un elemento.
-   * @param item El elemento a seleccionar.
-   */
+  /** Selects one item. No-op if already selected. */
   select: (item: T) => void;
-
-  /**
-   * Deselecciona un elemento.
-   * @param item El elemento a deseleccionar.
-   */
+  /** Unselects one item. No-op if not selected. */
   unselect: (item: T) => void;
-
-  /**
-   * Alterna la selección de un elemento (si está seleccionado, lo deselecciona y viceversa).
-   * @param item El elemento cuya selección se alternará.
-   */
+  /** Toggles one item's selection. */
   toggle: (item: T) => void;
-
-  /**
-   * Alterna la selección de todos los elementos (si todos están seleccionados, los deselecciona; de lo contrario, los selecciona).
-   */
+  /** Replaces the entire selection with `items`. */
+  setSelected: (items: T[]) => void;
+  /** Selects every item currently in `items` (additive). */
+  selectAll: () => void;
+  /** Selects all if not all selected, otherwise clears. */
   toggleAll: () => void;
-
-  /**
-   * Deselecciona todos los elementos.
-   */
+  /** Clears the entire selection (including sticky orphaned keys). */
   clear: () => void;
-};
-export function useSelection<T>(items: T[]): Return<T> {
-  const [selected, setSelected] = useState(new Set<T>());
-
-  const isSelected = useCallback((item: T) => selected.has(item), [selected]);
-
-  const select = useCallback((item: T) => {
-    setSelected((prevSelected) => new Set([...prevSelected, item]));
-  }, []);
-
-  const unselect = useCallback((item: T) => {
-    setSelected((prevSelected) => {
-      const newSelected = new Set(prevSelected);
-      newSelected.delete(item);
-      return newSelected;
-    });
-  }, []);
-
-  const toggle = useCallback((item: T) => {
-    setSelected((prevSelected) => {
-      const newSelected = new Set(prevSelected);
-      if (newSelected.has(item)) {
-        newSelected.delete(item);
-      } else {
-        newSelected.add(item);
-      }
-      return newSelected;
-    });
-  }, []);
-
-  const setItems = useCallback((items: T[]) => {
-    setSelected(new Set(items));
-  }, []);
-
-  const toggleAll = useCallback(() => {
-    setSelected((prevSelected) =>
-      prevSelected.size === items.length ? new Set() : new Set(items),
-    );
-  }, [items]);
-
-  const clear = useCallback(() => setSelected(new Set()), []);
+  /** Inverts selection relative to current `items`. */
+  invert: () => void;
+  /** Selects items in the inclusive index range [from, to] of `items` (additive). */
+  selectRange: (from: number, to: number) => void;
+}
+
+const defaultGetKey = <T>(item: T): Key => item as unknown as Key;
+
+export function useSelection<T>(
+  items: T[],
+  options?: UseSelectionOptions<T>,
+): UseSelectionReturn<T> {
+  // Frozen on mount — caller passes a stable function; re-passing is a no-op.
+  const getKeyRef = useRef<(item: T) => Key>(options?.keyFn ?? defaultGetKey);
+  const getKey = getKeyRef.current;
+
+  const [selectedKeys, setSelectedKeys] = useState<Set<Key>>(
+    // Frozen initial selection — seeded once.
+    () => new Set((options?.defaultSelected ?? []).map(getKeyRef.current)),
+  );
+
+  // Always current — actions and the onChange effect read the live list
+  // without taking `items` as a memo/effect dependency.
+  const itemsRef = useLatestRef(items);
+  // Always current selection — lets `isSelected` stay a stable fn ref.
+  const keysRef = useLatestRef(selectedKeys);
+  // Always the latest handler — never a memo/effect dep.
+  const onChangeRef = useLatestRef(options?.onChange);
+
+  // Fire onChange on every selection change EXCEPT initial mount.
+  const mountedRef = useRef(false);
+  useEffect(() => {
+    if (!mountedRef.current) {
+      mountedRef.current = true;
+      return;
+    }
+    const live = itemsRef.current;
+    const fn = getKeyRef.current;
+    onChangeRef.current?.(live.filter((item) => selectedKeys.has(fn(item))));
+    // Keyed on selectedKeys only: "onChange = selection changed".
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [selectedKeys]);
+
+  // Dev-only: warn once per instance when object items lack a keyFn (DEF-2).
+  const warnedRef = useRef(false);
+  useEffect(() => {
+    if (
+      process.env.NODE_ENV !== "production" &&
+      !options?.keyFn &&
+      !warnedRef.current &&
+      items.length > 0 &&
+      typeof items[0] === "object" &&
+      items[0] !== null
+    ) {
+      warnedRef.current = true;
+      console.warn(
+        "useSelection: items are objects but no `keyFn` was provided. " +
+          "Selection is tracked by object reference and will be lost when " +
+          "`items` is re-created (e.g. after a fetch). Pass `keyFn` to track " +
+          "by a stable key.",
+      );
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [items, options?.keyFn]);
+
+  // Closes over `selectedKeys` state — must reflect current selection during render.
+  // A new fn ref on each selection change is intentional and correct.
+  const isSelected = useCallback(
+    (item: T) => selectedKeys.has(getKey(item)),
+    [selectedKeys],
+  );
+
+  const actions = useMemo(
+    () => ({
+      select: (item: T) =>
+        setSelectedKeys((prev) => {
+          const key = getKeyRef.current(item);
+          if (prev.has(key)) return prev;
+          const next = new Set(prev);
+          next.add(key);
+          return next;
+        }),
+
+      unselect: (item: T) =>
+        setSelectedKeys((prev) => {
+          const key = getKeyRef.current(item);
+          if (!prev.has(key)) return prev;
+          const next = new Set(prev);
+          next.delete(key);
+          return next;
+        }),
+
+      toggle: (item: T) =>
+        setSelectedKeys((prev) => {
+          const key = getKeyRef.current(item);
+          const next = new Set(prev);
+          if (next.has(key)) next.delete(key);
+          else next.add(key);
+          return next;
+        }),
+
+      setSelected: (next: T[]) =>
+        setSelectedKeys(new Set(next.map(getKeyRef.current))),
+
+      selectAll: () =>
+        setSelectedKeys((prev) => {
+          const next = new Set(prev);
+          for (const item of itemsRef.current)
+            next.add(getKeyRef.current(item));
+          return next;
+        }),
+
+      toggleAll: () =>
+        setSelectedKeys((prev) => {
+          const live = itemsRef.current;
+          const fn = getKeyRef.current;
+          const allSelected =
+            live.length > 0 && live.every((item) => prev.has(fn(item)));
+          if (allSelected) {
+            const next = new Set(prev);
+            for (const item of live) next.delete(fn(item));
+            return next;
+          }
+          const next = new Set(prev);
+          for (const item of live) next.add(fn(item));
+          return next;
+        }),
+
+      clear: () => setSelectedKeys(new Set()),
+
+      invert: () =>
+        setSelectedKeys((prev) => {
+          const fn = getKeyRef.current;
+          const next = new Set(prev);
+          for (const item of itemsRef.current) {
+            const key = fn(item);
+            if (next.has(key)) next.delete(key);
+            else next.add(key);
+          }
+          return next;
+        }),
+
+      selectRange: (from: number, to: number) =>
+        setSelectedKeys((prev) => {
+          const live = itemsRef.current;
+          if (live.length === 0) return prev;
+          const fn = getKeyRef.current;
+          const lo = Math.max(0, Math.min(from, to));
+          const hi = Math.min(live.length - 1, Math.max(from, to));
+          const next = new Set(prev);
+          for (let i = lo; i <= hi; i++) next.add(fn(live[i]));
+          return next;
+        }),
+    }),
+    // keysRef/getKeyRef/itemsRef are stable refs → memo computes once.
+    // setSelectedKeys is stable for component lifetime.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [keysRef, itemsRef],
+  );
+
+  // Stable `selected` reference: recomputes only on items/selection change.
+  const selected = useMemo(
+    () => items.filter((item) => selectedKeys.has(getKey(item))),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [items, selectedKeys],
+  );
+
+  const isAllSelected =
+    items.length > 0 && items.every((item) => selectedKeys.has(getKey(item)));
+  const isNoneSelected = selectedKeys.size === 0;
+  const isSomeSelected = !isNoneSelected && !isAllSelected;
 
   return {
-    isAllSelected: selected.size === items.length,
-    isSomeSelected: selected.size > 0 && selected.size < items.length,
-    isNoneSelected: selected.size === 0,
+    selected,
+    selectedKeys,
+    isAllSelected,
+    isSomeSelected,
+    isNoneSelected,
     isSelected,
-    selected: [...selected],
-    setSelected: setItems,
-    select,
-    unselect,
-    toggle,
-    toggleAll,
-    clear,
+    ...actions,
   };
 }

package/src/hooks/use-session-storage/index.ts

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

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

@@ -0,0 +1,122 @@
+import type { Meta } from "@storybook/react-vite";
+import { Trash } from "lucide-react";
+import { Button, Input } from "../../components";
+import { useSessionStorage } from "../use-session-storage";
+
+/**
+ * Persists a value in `window.sessionStorage` for the lifetime of the browser
+ * tab — cleared automatically when the tab is closed. Syncs across every
+ * instance reading the same key within the same tab. 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.
+ *
+ * Prefer `useSessionStorage` over `useLocalStorage` for temporary drafts
+ * (wizards, multi-step forms) that should not persist across sessions.
+ */
+const meta: Meta = {
+  title: "hooks/useSessionStorage",
+  tags: ["new"],
+};
+
+export default meta;
+
+export const Default = {
+  render: () => {
+    const [value, setValue, removeValue] = useSessionStorage<string>(
+      "demo:session-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.
+ */
+export const FunctionalUpdater = {
+  render: () => {
+    const [count, setCount, removeCount] = useSessionStorage<number>(
+      "demo:session-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.
+ * Unlike `useLocalStorage`, changes do NOT propagate to other tabs —
+ * each tab has its own isolated sessionStorage.
+ */
+export const CrossInstanceSync = {
+  render: () => {
+    const [a, setA] = useSessionStorage<string>("demo:session-shared", "");
+    const [b, setB] = useSessionStorage<string>("demo:session-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>
+    );
+  },
+};
+
+/**
+ * Works with any JSON-serializable shape. Useful for persisting a multi-step
+ * form draft per step.
+ */
+export const ObjectValue = {
+  render: () => {
+    const [draft, setDraft, clearDraft] = useSessionStorage<{
+      nombre: string;
+      apellido: string;
+    }>("demo:session-draft", { nombre: "", apellido: "" });
+
+    return (
+      <div className="space-y-2">
+        <Input
+          value={draft.nombre}
+          onValueChange={(v) => setDraft((prev) => ({ ...prev!, nombre: v }))}
+          placeholder="Nombre"
+        />
+        <Input
+          value={draft.apellido}
+          onValueChange={(v) => setDraft((prev) => ({ ...prev!, apellido: v }))}
+          placeholder="Apellido"
+        />
+        <Button onClick={clearDraft}>
+          <Trash /> Clear draft
+        </Button>
+      </div>
+    );
+  },
+};

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

@@ -0,0 +1,164 @@
+import { act, renderHook } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { useSessionStorage } from "../use-session-storage";
+
+describe("useSessionStorage hook", () => {
+  const key = "testKey";
+
+  beforeEach(() => {
+    sessionStorage.clear();
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  it("should be defined", () => {
+    expect(useSessionStorage).toBeDefined();
+  });
+
+  it("returns initialValue when sessionStorage is empty", () => {
+    const { result } = renderHook(() =>
+      useSessionStorage<string>(key, "initialValue"),
+    );
+    expect(result.current[0]).toBe("initialValue");
+  });
+
+  it("does NOT write initialValue to sessionStorage on mount", () => {
+    renderHook(() => useSessionStorage<string>(key, "initialValue"));
+    expect(sessionStorage.getItem(key)).toBeNull();
+  });
+
+  it("reads an existing stored value from sessionStorage", () => {
+    sessionStorage.setItem(key, JSON.stringify("storedValue"));
+    const { result } = renderHook(() =>
+      useSessionStorage<string>(key, "initialValue"),
+    );
+    expect(result.current[0]).toBe("storedValue");
+  });
+
+  it("setValue updates the value and writes to sessionStorage", () => {
+    const { result } = renderHook(() =>
+      useSessionStorage<string>(key, "initialValue"),
+    );
+
+    act(() => {
+      result.current[1]("newValue");
+    });
+
+    expect(result.current[0]).toBe("newValue");
+    expect(sessionStorage.getItem(key)).toBe(JSON.stringify("newValue"));
+  });
+
+  it("setValue accepts a functional updater", () => {
+    const { result } = renderHook(() => useSessionStorage<number>(key, 1));
+
+    act(() => {
+      result.current[1]((prev) => (prev ?? 0) + 5);
+    });
+
+    expect(result.current[0]).toBe(6);
+    expect(sessionStorage.getItem(key)).toBe("6");
+  });
+
+  it("remove() deletes the key and falls back to initialValue", () => {
+    sessionStorage.setItem(key, JSON.stringify("storedValue"));
+    const { result } = renderHook(() => useSessionStorage<string>(key, ""));
+
+    act(() => {
+      result.current[2]();
+    });
+
+    expect(result.current[0]).toBe("");
+    expect(sessionStorage.getItem(key)).toBeNull();
+  });
+
+  it("falls back to initialValue and logs when stored value is not JSON", () => {
+    const consoleErrorSpy = vi
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+    sessionStorage.setItem(key, "non-JSON-string");
+
+    const { result } = renderHook(() =>
+      useSessionStorage<string>(key, "initialValue"),
+    );
+
+    expect(result.current[0]).toBe("initialValue");
+    expect(consoleErrorSpy).toHaveBeenCalled();
+  });
+
+  it("logs when sessionStorage.setItem throws during setValue", () => {
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    vi.stubGlobal("sessionStorage", {
+      getItem: vi.fn().mockReturnValue(null),
+      setItem: vi.fn().mockImplementation(() => {
+        throw new Error("Storage full");
+      }),
+      removeItem: vi.fn(),
+      clear: vi.fn(),
+    });
+
+    const { result } = renderHook(() =>
+      useSessionStorage<string>("err-key", "value"),
+    );
+
+    act(() => {
+      result.current[1]("next");
+    });
+
+    expect(errorSpy).toHaveBeenCalled();
+  });
+
+  it("logs when sessionStorage.removeItem throws during remove()", () => {
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    vi.stubGlobal("sessionStorage", {
+      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(() =>
+      useSessionStorage<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(() => useSessionStorage<string>(key, "init"));
+    const b = renderHook(() => useSessionStorage<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("supports a custom serializer", () => {
+    const serializer = {
+      read: (raw: string) => raw.toUpperCase(),
+      write: (value: string) => value.toLowerCase(),
+    };
+
+    const { result } = renderHook(() =>
+      useSessionStorage<string>(key, "INITIAL", { serializer }),
+    );
+
+    act(() => {
+      result.current[1]("MixedCase");
+    });
+
+    expect(sessionStorage.getItem(key)).toBe("mixedcase");
+    expect(result.current[0]).toBe("MIXEDCASE");
+  });
+});