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

package/src/hooks/use-selection/use-selection.test.tsx

@@ -1,6 +1,13 @@
 import { act, renderHook } from "@testing-library/react";
-import { describe, expect, it } from "vitest";
-import { useSelection } from "../use-selection";
+import { describe, expect, it, vi } from "vitest";
+import {
+  type Key,
+  type UseSelectionOptions,
+  type UseSelectionReturn,
+  useSelection,
+} from "../use-selection";
+
+// ─── Existing tests (v1 baseline — kept for regression) ──────────────────────
 
 describe("useSelection hook", () => {
   it("initial state: isAllSelected=false, isNoneSelected=true", () => {
@@ -77,3 +84,411 @@ describe("useSelection hook", () => {
     expect(result.current.selected).toEqual([]);
   });
 });
+
+// ─── Task 1.1 — New type exports exist ───────────────────────────────────────
+
+describe("Type exports", () => {
+  it("exports Key, UseSelectionOptions, UseSelectionReturn types (compile-time)", () => {
+    // If these types don't exist the import at the top of this file will fail.
+    // This test is a runtime sentinel confirming the imports resolved.
+    const options: UseSelectionOptions<number> = { keyFn: (n) => n };
+    const { result } = renderHook(() => useSelection([1, 2, 3], options));
+    const ret: UseSelectionReturn<number> = result.current;
+    const _key: Key = 1;
+    expect(ret).toBeDefined();
+    expect(_key).toBe(1);
+  });
+});
+
+// ─── Task 1.2 — Key-based identity ───────────────────────────────────────────
+
+describe("Key-based identity", () => {
+  it("default keyFn: item itself is its key (value identity for primitives)", () => {
+    const { result } = renderHook(() => useSelection([1, 2, 3]));
+    act(() => result.current.select(2));
+    expect(result.current.isSelected(2)).toBe(true);
+    expect(result.current.isSelected(1)).toBe(false);
+  });
+
+  it("custom keyFn: selection survives items array re-creation", () => {
+    let items = [{ id: 1, name: "A" }];
+    const { result, rerender } = renderHook(() =>
+      useSelection(items, { keyFn: (item) => item.id }),
+    );
+    act(() => result.current.select({ id: 1, name: "A" }));
+    expect(result.current.isSelected({ id: 1, name: "A" })).toBe(true);
+
+    // Re-create items with same id but new reference and different name
+    items = [{ id: 1, name: "B" }];
+    rerender();
+
+    expect(result.current.isSelected({ id: 1, name: "B" })).toBe(true);
+    expect(result.current.selected).toEqual([{ id: 1, name: "B" }]);
+  });
+
+  it("custom keyFn: orphaned keys persist in selectedKeys but not in selected", () => {
+    let items = [{ id: 1 }, { id: 2 }];
+    const { result, rerender } = renderHook(() =>
+      useSelection(items, { keyFn: (item) => item.id }),
+    );
+    act(() => result.current.select({ id: 2 }));
+
+    // Remove id=2 from items
+    items = [{ id: 1 }];
+    rerender();
+
+    expect(result.current.selectedKeys.has(2)).toBe(true);
+    expect(result.current.selected).toEqual([]);
+
+    // Re-add id=2 — should reappear
+    items = [{ id: 1 }, { id: 2 }];
+    rerender();
+
+    expect(result.current.selected).toEqual([{ id: 2 }]);
+  });
+});
+
+// ─── Task 1.3 — defaultSelected ──────────────────────────────────────────────
+
+describe("defaultSelected option", () => {
+  it("seeds initial selection on mount", () => {
+    const { result } = renderHook(() =>
+      useSelection([1, 2, 3], { defaultSelected: [2, 3] }),
+    );
+    expect(result.current.selected).toEqual([2, 3]);
+    expect(result.current.isSelected(2)).toBe(true);
+    expect(result.current.isSelected(1)).toBe(false);
+  });
+
+  it("is NOT re-applied when options reference changes on re-render", () => {
+    const { result, rerender } = renderHook(
+      ({ ds }) => useSelection([1, 2, 3], { defaultSelected: ds }),
+      { initialProps: { ds: [2, 3] } },
+    );
+    // Clear selection
+    act(() => result.current.clear());
+    expect(result.current.isNoneSelected).toBe(true);
+
+    // Rerender with same defaultSelected value — should NOT re-seed
+    rerender({ ds: [2, 3] });
+    expect(result.current.isNoneSelected).toBe(true);
+  });
+});
+
+// ─── Task 1.4 — onChange ─────────────────────────────────────────────────────
+
+describe("onChange callback", () => {
+  it("does NOT fire on mount", () => {
+    const onChange = vi.fn();
+    renderHook(() => useSelection([1, 2, 3], { onChange }));
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  it("fires with selected items after select", async () => {
+    const onChange = vi.fn();
+    const { result } = renderHook(() => useSelection([1, 2, 3], { onChange }));
+    act(() => result.current.select(2));
+    // onChange fires in an effect — flush
+    await vi.waitFor(() => expect(onChange).toHaveBeenCalledTimes(1));
+    expect(onChange).toHaveBeenCalledWith([2]);
+  });
+
+  it("does NOT fire for no-op select (already selected)", async () => {
+    const onChange = vi.fn();
+    const { result } = renderHook(() => useSelection([1, 2, 3], { onChange }));
+    act(() => result.current.select(2));
+    await vi.waitFor(() => expect(onChange).toHaveBeenCalledTimes(1));
+    onChange.mockClear();
+
+    act(() => result.current.select(2));
+    // Give effects a chance to fire
+    await new Promise((r) => setTimeout(r, 10));
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  it("does NOT fire for no-op unselect (item not selected)", async () => {
+    const onChange = vi.fn();
+    const { result } = renderHook(() => useSelection([1, 2, 3], { onChange }));
+    act(() => result.current.unselect(1));
+    await new Promise((r) => setTimeout(r, 10));
+    expect(onChange).not.toHaveBeenCalled();
+  });
+});
+
+// ─── Task 1.5 — selectedKeys return value ────────────────────────────────────
+
+describe("selectedKeys return value", () => {
+  it("reflects selected item keys", () => {
+    const { result } = renderHook(() =>
+      useSelection([{ id: 1 }, { id: 2 }], { keyFn: (item) => item.id }),
+    );
+    act(() => result.current.select({ id: 1 }));
+    expect(result.current.selectedKeys.has(1)).toBe(true);
+    expect(result.current.selectedKeys.has(2)).toBe(false);
+  });
+
+  it("starts empty", () => {
+    const { result } = renderHook(() => useSelection([1, 2, 3]));
+    expect(result.current.selectedKeys.size).toBe(0);
+  });
+});
+
+// ─── Task 1.6 — selectAll + invert ───────────────────────────────────────────
+
+describe("selectAll", () => {
+  it("selects all items", () => {
+    const { result } = renderHook(() => useSelection([1, 2, 3]));
+    act(() => result.current.selectAll());
+    expect(result.current.isAllSelected).toBe(true);
+    expect(result.current.selected).toEqual([1, 2, 3]);
+  });
+
+  it("is additive — does not clear previously selected keys outside items", () => {
+    const { result } = renderHook(() => useSelection([1, 2, 3]));
+    act(() => result.current.select(1));
+    act(() => result.current.selectAll());
+    expect(result.current.isAllSelected).toBe(true);
+  });
+});
+
+describe("invert", () => {
+  it("invert on partial selection flips to complement", () => {
+    const { result } = renderHook(() => useSelection([1, 2, 3]));
+    act(() => result.current.select(1));
+    act(() => result.current.invert());
+    expect(result.current.isSelected(1)).toBe(false);
+    expect(result.current.isSelected(2)).toBe(true);
+    expect(result.current.isSelected(3)).toBe(true);
+  });
+
+  it("invert on empty selection selects all", () => {
+    const { result } = renderHook(() => useSelection([1, 2, 3]));
+    act(() => result.current.invert());
+    expect(result.current.selected).toEqual([1, 2, 3]);
+  });
+
+  it("invert on full selection clears all", () => {
+    const { result } = renderHook(() => useSelection([1, 2, 3]));
+    act(() => result.current.selectAll());
+    act(() => result.current.invert());
+    expect(result.current.selected).toEqual([]);
+    expect(result.current.isNoneSelected).toBe(true);
+  });
+});
+
+// ─── Task 1.7 — selectRange ──────────────────────────────────────────────────
+
+describe("selectRange", () => {
+  it("selects items in normal order [from, to] inclusive", () => {
+    const { result } = renderHook(() => useSelection(["a", "b", "c", "d"]));
+    act(() => result.current.selectRange(1, 3));
+    expect(result.current.selected).toEqual(["b", "c", "d"]);
+  });
+
+  it("normalizes reversed range (from > to)", () => {
+    const { result } = renderHook(() => useSelection(["a", "b", "c", "d"]));
+    act(() => result.current.selectRange(3, 1));
+    expect(result.current.selected).toEqual(["b", "c", "d"]);
+  });
+
+  it("clamps out-of-range indices", () => {
+    const { result } = renderHook(() => useSelection(["a", "b", "c"]));
+    act(() => result.current.selectRange(-5, 100));
+    expect(result.current.selected).toEqual(["a", "b", "c"]);
+  });
+
+  it("no-op on empty items", () => {
+    const { result } = renderHook(() => useSelection<string>([]));
+    expect(() => act(() => result.current.selectRange(0, 2))).not.toThrow();
+    expect(result.current.selected).toEqual([]);
+  });
+
+  it("is additive — does not replace existing selection", () => {
+    const { result } = renderHook(() => useSelection(["a", "b", "c", "d"]));
+    act(() => result.current.select("a"));
+    act(() => result.current.selectRange(2, 3));
+    expect(result.current.selected).toEqual(["a", "c", "d"]);
+  });
+
+  it("single index (from === to) selects one item", () => {
+    const { result } = renderHook(() => useSelection(["a", "b", "c"]));
+    act(() => result.current.selectRange(1, 1));
+    expect(result.current.selected).toEqual(["b"]);
+  });
+});
+
+// ─── Task 1.8 — isAllSelected / isSomeSelected / isNoneSelected ──────────────
+
+describe("derived flags", () => {
+  it("isAllSelected is false when items is empty", () => {
+    const { result } = renderHook(() => useSelection<number>([]));
+    expect(result.current.isAllSelected).toBe(false);
+  });
+
+  it("flags: nothing selected", () => {
+    const { result } = renderHook(() => useSelection([1, 2, 3]));
+    expect(result.current.isNoneSelected).toBe(true);
+    expect(result.current.isSomeSelected).toBe(false);
+    expect(result.current.isAllSelected).toBe(false);
+  });
+
+  it("flags: some selected", () => {
+    const { result } = renderHook(() => useSelection([1, 2, 3]));
+    act(() => result.current.select(1));
+    expect(result.current.isNoneSelected).toBe(false);
+    expect(result.current.isSomeSelected).toBe(true);
+    expect(result.current.isAllSelected).toBe(false);
+  });
+
+  it("flags: all selected", () => {
+    const { result } = renderHook(() => useSelection([1, 2, 3]));
+    act(() => result.current.selectAll());
+    expect(result.current.isNoneSelected).toBe(false);
+    expect(result.current.isSomeSelected).toBe(false);
+    expect(result.current.isAllSelected).toBe(true);
+  });
+
+  it("isAllSelected false when selectedKeys has orphaned keys beyond items.length", () => {
+    // Select 3 items, then reduce items to 2 — selectedKeys.size > items.length
+    // but not all PRESENT items are selected via the every() check.
+    let items = [1, 2, 3];
+    const { result, rerender } = renderHook(() => useSelection(items));
+    act(() => result.current.selectAll());
+    items = [1, 2];
+    rerender();
+    // All present items ARE selected — isAllSelected should be true here
+    expect(result.current.isAllSelected).toBe(true);
+  });
+});
+
+// ─── Task 1.9 — toggleAll ────────────────────────────────────────────────────
+
+describe("toggleAll", () => {
+  it("toggleAll when all selected → clears", () => {
+    const { result } = renderHook(() => useSelection([1, 2, 3]));
+    act(() => result.current.selectAll());
+    act(() => result.current.toggleAll());
+    expect(result.current.isNoneSelected).toBe(true);
+    expect(result.current.selected).toEqual([]);
+  });
+
+  it("toggleAll when partial → selects all", () => {
+    const { result } = renderHook(() => useSelection([1, 2, 3]));
+    act(() => result.current.select(1));
+    act(() => result.current.toggleAll());
+    expect(result.current.isAllSelected).toBe(true);
+  });
+
+  it("toggleAll when none → selects all", () => {
+    const { result } = renderHook(() => useSelection([1, 2, 3]));
+    act(() => result.current.toggleAll());
+    expect(result.current.isAllSelected).toBe(true);
+    expect(result.current.selected).toEqual([1, 2, 3]);
+  });
+});
+
+// ─── Task 1.10 — Stable refs ─────────────────────────────────────────────────
+
+describe("Stable references", () => {
+  it("selected array reference is stable across unrelated re-renders", () => {
+    // Use a stable items reference so useMemo([items, selectedKeys]) doesn't recompute.
+    const stableItems = [1, 2, 3];
+    const { result, rerender } = renderHook(() => useSelection(stableItems));
+    act(() => result.current.select(1));
+    const selectedBefore = result.current.selected;
+
+    // Re-render without changing items or selection — selected ref must be same object
+    rerender();
+
+    expect(result.current.selected).toBe(selectedBefore);
+  });
+
+  it("selected ref updates when selection changes", () => {
+    const { result } = renderHook(() => useSelection([1, 2, 3]));
+    act(() => result.current.select(1));
+    const ref1 = result.current.selected;
+    act(() => result.current.select(2));
+    const ref2 = result.current.selected;
+    expect(ref1).not.toBe(ref2);
+  });
+
+  it("isSelected function ref is stable when selection does not change", () => {
+    let items = [1, 2, 3];
+    const { result, rerender } = renderHook(() => useSelection(items));
+    const isSelectedBefore = result.current.isSelected;
+    // Re-render without changing selection — ref must be the same object
+    items = [1, 2, 3];
+    rerender();
+    expect(result.current.isSelected).toBe(isSelectedBefore);
+  });
+
+  it("isSelected function ref updates when selection changes", () => {
+    const { result } = renderHook(() => useSelection([1, 2, 3]));
+    const isSelectedBefore = result.current.isSelected;
+    act(() => result.current.select(1));
+    // ref must change so render-time usage reflects current selection
+    expect(result.current.isSelected).not.toBe(isSelectedBefore);
+  });
+
+  it("all action refs are stable when items changes", () => {
+    let items = [1, 2, 3];
+    const { result, rerender } = renderHook(() => useSelection(items));
+    const {
+      select,
+      unselect,
+      toggle,
+      setSelected,
+      selectAll,
+      toggleAll,
+      clear,
+      invert,
+      selectRange,
+    } = result.current;
+
+    items = [4, 5, 6];
+    rerender();
+
+    expect(result.current.select).toBe(select);
+    expect(result.current.unselect).toBe(unselect);
+    expect(result.current.toggle).toBe(toggle);
+    expect(result.current.setSelected).toBe(setSelected);
+    expect(result.current.selectAll).toBe(selectAll);
+    expect(result.current.toggleAll).toBe(toggleAll);
+    expect(result.current.clear).toBe(clear);
+    expect(result.current.invert).toBe(invert);
+    expect(result.current.selectRange).toBe(selectRange);
+  });
+});
+
+// ─── Task 1.11 — Dev-warn for objects without keyFn ──────────────────────────
+
+describe("dev-warn for objects without keyFn", () => {
+  it("warns once for object items without keyFn in dev", () => {
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const items = [{ id: 1 }];
+    const { rerender } = renderHook(() => useSelection(items));
+
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    expect(warnSpy.mock.calls[0][0]).toMatch(/keyFn/);
+
+    // Re-render should NOT warn again
+    rerender();
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+
+    warnSpy.mockRestore();
+  });
+
+  it("does NOT warn when keyFn is provided", () => {
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    renderHook(() => useSelection([{ id: 1 }], { keyFn: (item) => item.id }));
+    expect(warnSpy).not.toHaveBeenCalled();
+    warnSpy.mockRestore();
+  });
+
+  it("does NOT warn for primitive items", () => {
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    renderHook(() => useSelection([1, 2, 3]));
+    expect(warnSpy).not.toHaveBeenCalled();
+    warnSpy.mockRestore();
+  });
+});