@praxisjs/composables 0.1.4 → 1.0.0

package/src/__tests__/browser.test.ts

@@ -1,118 +1,227 @@
 // @vitest-environment jsdom
-import { describe, it, expect, vi } from "vitest";
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+import { MediaQuery, ColorScheme, Mouse, KeyCombo, Idle } from "../browser";
+
+function mockMatchMedia(matches: boolean, onAdd?: (_: string, fn: (e: MediaQueryListEvent) => void) => void) {
+  const mql = {
+    matches,
+    addEventListener: onAdd ?? vi.fn(),
+    removeEventListener: vi.fn(),
+  } as unknown as MediaQueryList;
+  vi.stubGlobal("matchMedia", () => mql);
+  return mql;
+}
+
+// ── MediaQuery ────────────────────────────────────────────────────────────────
+
+describe("MediaQuery", () => {
+  beforeEach(() => { vi.restoreAllMocks(); });
+
+  it("reads initial match state", () => {
+    mockMatchMedia(true);
+    const mq = new MediaQuery("(min-width: 768px)");
+    const { matches } = mq.setup() as { matches: () => boolean };
+    expect(matches()).toBe(true);
+  });
 
-import { useMediaQuery, useColorScheme, useMouse, useKeyCombo, useIdle } from "../browser";
+  it("updates matches when change event fires", () => {
+    let changeHandler: ((e: MediaQueryListEvent) => void) | undefined;
+    mockMatchMedia(false, (_: string, fn) => { changeHandler = fn; });
 
-// ---------- useMediaQuery ----------
+    const mq = new MediaQuery("(min-width: 768px)");
+    const { matches } = mq.setup() as { matches: () => boolean };
+    expect(matches()).toBe(false);
 
-describe("useMediaQuery", () => {
-  it("returns computed that reflects matchMedia result", () => {
-    Object.defineProperty(window, "matchMedia", {
-      writable: true,
-      value: vi.fn((query: string) => ({
-        matches: query === "(prefers-color-scheme: dark)",
-        addEventListener: vi.fn(),
-        removeEventListener: vi.fn(),
-      })),
-    });
+    changeHandler!({ matches: true } as MediaQueryListEvent);
+    expect(matches()).toBe(true);
+  });
 
-    const isDark = useMediaQuery("(prefers-color-scheme: dark)");
-    expect(isDark()).toBe(true);
+  it("removes event listener on unmount", () => {
+    const mql = mockMatchMedia(false);
+    const mq = new MediaQuery("(min-width: 768px)");
+    mq.setup();
+    mq.onUnmount();
+    expect((mql.removeEventListener as ReturnType<typeof vi.fn>)).toHaveBeenCalledWith("change", expect.any(Function));
+  });
 
-    const isLight = useMediaQuery("(prefers-color-scheme: light)");
-    expect(isLight()).toBe(false);
+  it("onUnmount is safe to call without setup (covers false branch)", () => {
+    const mq = new MediaQuery("(min-width: 768px)");
+    expect(() => mq.onUnmount()).not.toThrow();
   });
 });
 
-// ---------- useColorScheme ----------
+// ── ColorScheme ───────────────────────────────────────────────────────────────
 
-describe("useColorScheme", () => {
-  it("isDark and isLight are complementary", () => {
-    Object.defineProperty(window, "matchMedia", {
-      writable: true,
-      value: vi.fn(() => ({
-        matches: true,
-        addEventListener: vi.fn(),
-        removeEventListener: vi.fn(),
-      })),
-    });
+describe("ColorScheme", () => {
+  beforeEach(() => { vi.restoreAllMocks(); });
 
-    const { isDark, isLight } = useColorScheme();
+  it("exposes isDark and isLight as computed inverses", () => {
+    let changeHandler: ((e: MediaQueryListEvent) => void) | undefined;
+    mockMatchMedia(false, (_: string, fn) => { changeHandler = fn; });
+
+    const cs = new ColorScheme();
+    const { isDark, isLight } = cs.setup() as { isDark: () => boolean; isLight: () => boolean };
+
+    expect(isDark()).toBe(false);
+    expect(isLight()).toBe(true);
+
+    changeHandler!({ matches: true } as MediaQueryListEvent);
     expect(isDark()).toBe(true);
     expect(isLight()).toBe(false);
   });
+
+  it("removes event listener on unmount", () => {
+    const mql = mockMatchMedia(false);
+    const cs = new ColorScheme();
+    cs.setup();
+    cs.onUnmount();
+    expect((mql.removeEventListener as ReturnType<typeof vi.fn>)).toHaveBeenCalledWith("change", expect.any(Function));
+  });
+
+  it("onUnmount is safe to call without setup (covers false branch)", () => {
+    const cs = new ColorScheme();
+    expect(() => cs.onUnmount()).not.toThrow();
+  });
 });
 
-// ---------- useMouse ----------
+// ── Mouse ─────────────────────────────────────────────────────────────────────
 
-describe("useMouse", () => {
+describe("Mouse", () => {
   it("starts at (0, 0)", () => {
-    const { x, y } = useMouse();
+    const mouse = new Mouse();
+    const { x, y } = mouse.setup() as { x: () => number; y: () => number };
     expect(x()).toBe(0);
     expect(y()).toBe(0);
   });
 
-  it("updates on mousemove event", () => {
-    const { x, y } = useMouse();
-    window.dispatchEvent(
-      new MouseEvent("mousemove", { clientX: 100, clientY: 200 }),
-    );
-    expect(x()).toBe(100);
-    expect(y()).toBe(200);
+  it("updates x and y on mousemove", () => {
+    const mouse = new Mouse();
+    const { x, y } = mouse.setup() as { x: () => number; y: () => number };
+
+    window.dispatchEvent(new MouseEvent("mousemove", { clientX: 120, clientY: 80 }));
+    expect(x()).toBe(120);
+    expect(y()).toBe(80);
+  });
+
+  it("removes listener on unmount", () => {
+    const remove = vi.spyOn(window, "removeEventListener");
+    const mouse = new Mouse();
+    mouse.setup();
+    mouse.onUnmount();
+    expect(remove).toHaveBeenCalledWith("mousemove", expect.any(Function));
   });
 });
 
-// ---------- useKeyCombo ----------
+// ── KeyCombo ──────────────────────────────────────────────────────────────────
 
-describe("useKeyCombo", () => {
-  it("starts as false", () => {
-    const pressed = useKeyCombo("ctrl+s");
+describe("KeyCombo", () => {
+  it("starts as not pressed", () => {
+    const kc = new KeyCombo("ctrl+s");
+    const { pressed } = kc.setup() as { pressed: () => boolean };
     expect(pressed()).toBe(false);
   });
 
-  it("becomes true on matching keydown", () => {
-    const pressed = useKeyCombo("ctrl+s");
-    window.dispatchEvent(
-      new KeyboardEvent("keydown", { key: "s", ctrlKey: true }),
-    );
+  it("sets pressed=true when matching combo is pressed", () => {
+    const kc = new KeyCombo("ctrl+s");
+    const { pressed } = kc.setup() as { pressed: () => boolean };
+
+    window.dispatchEvent(new KeyboardEvent("keydown", { ctrlKey: true, key: "s" }));
     expect(pressed()).toBe(true);
   });
 
-  it("resets to false on keyup", () => {
-    const pressed = useKeyCombo("ctrl+s");
-    window.dispatchEvent(
-      new KeyboardEvent("keydown", { key: "s", ctrlKey: true }),
-    );
+  it("resets pressed on keyup", () => {
+    const kc = new KeyCombo("ctrl+s");
+    const { pressed } = kc.setup() as { pressed: () => boolean };
+
+    window.dispatchEvent(new KeyboardEvent("keydown", { ctrlKey: true, key: "s" }));
     window.dispatchEvent(new KeyboardEvent("keyup"));
     expect(pressed()).toBe(false);
   });
+
+  it("does not set pressed for wrong key", () => {
+    const kc = new KeyCombo("ctrl+s");
+    const { pressed } = kc.setup() as { pressed: () => boolean };
+
+    window.dispatchEvent(new KeyboardEvent("keydown", { ctrlKey: true, key: "z" }));
+    expect(pressed()).toBe(false);
+  });
+
+  it("removes listeners on unmount", () => {
+    const remove = vi.spyOn(window, "removeEventListener");
+    const kc = new KeyCombo("ctrl+s");
+    kc.setup();
+    kc.onUnmount();
+    expect(remove).toHaveBeenCalledWith("keydown", expect.any(Function));
+    expect(remove).toHaveBeenCalledWith("keyup", expect.any(Function));
+  });
+
+  it("matches combo without ctrl modifier (ctrl branch: `: true`)", () => {
+    const kc = new KeyCombo("s");
+    const { pressed } = kc.setup() as { pressed: () => boolean };
+    // No ctrlKey needed — parts doesn't include "ctrl" so ctrl = true always
+    window.dispatchEvent(new KeyboardEvent("keydown", { key: "s" }));
+    expect(pressed()).toBe(true);
+  });
+
+  it("matches combo with shift modifier (shift branch: `e.shiftKey`)", () => {
+    const kc = new KeyCombo("ctrl+shift+s");
+    const { pressed } = kc.setup() as { pressed: () => boolean };
+    window.dispatchEvent(new KeyboardEvent("keydown", { ctrlKey: true, shiftKey: true, key: "s" }));
+    expect(pressed()).toBe(true);
+  });
+
+  it("does not match when shift is required but not pressed", () => {
+    const kc = new KeyCombo("ctrl+shift+s");
+    const { pressed } = kc.setup() as { pressed: () => boolean };
+    window.dispatchEvent(new KeyboardEvent("keydown", { ctrlKey: true, shiftKey: false, key: "s" }));
+    expect(pressed()).toBe(false);
+  });
+
+  it("matches combo with alt modifier (alt branch: `e.altKey`)", () => {
+    const kc = new KeyCombo("ctrl+alt+s");
+    const { pressed } = kc.setup() as { pressed: () => boolean };
+    window.dispatchEvent(new KeyboardEvent("keydown", { ctrlKey: true, altKey: true, key: "s" }));
+    expect(pressed()).toBe(true);
+  });
 });
 
-// ---------- useIdle ----------
+// ── Idle ──────────────────────────────────────────────────────────────────────
 
-describe("useIdle", () => {
+describe("Idle", () => {
   it("starts as not idle", () => {
     vi.useFakeTimers();
-    const idle = useIdle(500);
-    expect(idle()).toBe(false);
+    const idle = new Idle(500);
+    const { idle: isIdle } = idle.setup() as { idle: () => boolean };
+    expect(isIdle()).toBe(false);
     vi.useRealTimers();
   });
 
-  it("becomes idle after the timeout elapses", () => {
+  it("becomes idle after timeout", () => {
     vi.useFakeTimers();
-    const idle = useIdle(500);
+    const composable = new Idle(500);
+    const { idle: isIdle } = composable.setup() as { idle: () => boolean };
     vi.advanceTimersByTime(500);
-    expect(idle()).toBe(true);
+    expect(isIdle()).toBe(true);
     vi.useRealTimers();
   });
 
-  it("resets idle on user activity", () => {
+  it("resets idle timer on activity", () => {
     vi.useFakeTimers();
-    const idle = useIdle(500);
-    vi.advanceTimersByTime(300);
+    const composable = new Idle(500);
+    const { idle: isIdle } = composable.setup() as { idle: () => boolean };
+    vi.advanceTimersByTime(400);
     window.dispatchEvent(new MouseEvent("mousemove"));
-    vi.advanceTimersByTime(300); // not enough since activity reset the timer
-    expect(idle()).toBe(false);
+    vi.advanceTimersByTime(400);
+    expect(isIdle()).toBe(false);
     vi.useRealTimers();
   });
+
+  it("removes listeners on unmount", () => {
+    const remove = vi.spyOn(window, "removeEventListener");
+    const composable = new Idle(500);
+    composable.setup();
+    composable.onUnmount();
+    expect(remove).toHaveBeenCalled();
+  });
 });

package/src/__tests__/dom.test.ts

@@ -1,103 +1,261 @@
 // @vitest-environment jsdom
-import { describe, it, expect } from "vitest";
+import { describe, it, expect, vi, beforeEach } from "vitest";
 
-import { createRef, useWindowSize, useScrollPosition, useFocus } from "../dom";
+import { signal } from "@praxisjs/core/internal";
 
-// ---------- createRef ----------
+import { WindowSize, ScrollPosition, ElementSize, Intersection, Focus } from "../dom";
 
-describe("createRef", () => {
-  it("starts with current = null", () => {
-    const ref = createRef();
-    expect(ref.current).toBeNull();
-  });
-
-  it("can be assigned an element", () => {
-    const ref = createRef();
-    const el = document.createElement("div");
-    ref.current = el;
-    expect(ref.current).toBe(el);
-  });
-});
-
-// ---------- useWindowSize ----------
+// ── WindowSize ────────────────────────────────────────────────────────────────
 
-describe("useWindowSize", () => {
-  it("returns the current window dimensions", () => {
-    Object.defineProperty(window, "innerWidth", { writable: true, configurable: true, value: 1024 });
-    Object.defineProperty(window, "innerHeight", { writable: true, configurable: true, value: 768 });
+describe("WindowSize", () => {
+  it("reads initial window dimensions", () => {
+    Object.defineProperty(window, "innerWidth", { value: 1024, configurable: true });
+    Object.defineProperty(window, "innerHeight", { value: 768, configurable: true });
 
-    const { width, height } = useWindowSize();
+    const ws = new WindowSize();
+    const { width, height } = ws.setup() as { width: () => number; height: () => number };
     expect(width()).toBe(1024);
     expect(height()).toBe(768);
   });
 
   it("updates on resize event", () => {
-    Object.defineProperty(window, "innerWidth", { writable: true, configurable: true, value: 800 });
-    Object.defineProperty(window, "innerHeight", { writable: true, configurable: true, value: 600 });
+    Object.defineProperty(window, "innerWidth", { value: 800, configurable: true });
+    Object.defineProperty(window, "innerHeight", { value: 600, configurable: true });
 
-    const { width, height } = useWindowSize();
+    const ws = new WindowSize();
+    const { width, height } = ws.setup() as { width: () => number; height: () => number };
 
-    Object.defineProperty(window, "innerWidth", { writable: true, configurable: true, value: 1280 });
-    Object.defineProperty(window, "innerHeight", { writable: true, configurable: true, value: 720 });
+    Object.defineProperty(window, "innerWidth", { value: 1280, configurable: true });
+    Object.defineProperty(window, "innerHeight", { value: 900, configurable: true });
     window.dispatchEvent(new Event("resize"));
 
     expect(width()).toBe(1280);
-    expect(height()).toBe(720);
+    expect(height()).toBe(900);
+  });
+
+  it("removes listener on unmount", () => {
+    const remove = vi.spyOn(window, "removeEventListener");
+    const ws = new WindowSize();
+    ws.setup();
+    ws.onUnmount();
+    expect(remove).toHaveBeenCalledWith("resize", expect.any(Function));
   });
 });
 
-// ---------- useScrollPosition ----------
+// ── ScrollPosition ────────────────────────────────────────────────────────────
 
-describe("useScrollPosition", () => {
+describe("ScrollPosition", () => {
   it("starts at (0, 0)", () => {
-    const { x, y } = useScrollPosition(window);
+    const sp = new ScrollPosition(window);
+    const { x, y } = sp.setup() as { x: () => number; y: () => number };
     expect(x()).toBe(0);
     expect(y()).toBe(0);
   });
 
-  it("updates on element scroll", () => {
+  it("updates on scroll event for window", () => {
+    const sp = new ScrollPosition(window);
+    const { x, y } = sp.setup() as { x: () => number; y: () => number };
+
+    Object.defineProperty(window, "scrollX", { value: 100, configurable: true });
+    Object.defineProperty(window, "scrollY", { value: 200, configurable: true });
+    window.dispatchEvent(new Event("scroll"));
+
+    expect(x()).toBe(100);
+    expect(y()).toBe(200);
+  });
+
+  it("updates on scroll event for element", () => {
     const el = document.createElement("div");
-    const { x, y } = useScrollPosition(el);
+    const sp = new ScrollPosition(el);
+    const { x, y } = sp.setup() as { x: () => number; y: () => number };
 
-    Object.defineProperty(el, "scrollLeft", { configurable: true, value: 50 });
-    Object.defineProperty(el, "scrollTop", { configurable: true, value: 80 });
+    Object.defineProperty(el, "scrollLeft", { value: 50, configurable: true });
+    Object.defineProperty(el, "scrollTop", { value: 75, configurable: true });
     el.dispatchEvent(new Event("scroll"));
 
     expect(x()).toBe(50);
-    expect(y()).toBe(80);
+    expect(y()).toBe(75);
+  });
+
+  it("removes listener on unmount", () => {
+    const el = document.createElement("div");
+    const remove = vi.spyOn(el, "removeEventListener");
+    const sp = new ScrollPosition(el);
+    sp.setup();
+    sp.onUnmount();
+    expect(remove).toHaveBeenCalledWith("scroll", expect.any(Function));
+  });
+});
+
+// ── ElementSize ───────────────────────────────────────────────────────────────
+
+describe("ElementSize", () => {
+  let observerCallback: ResizeObserverCallback;
+
+  beforeEach(() => {
+    vi.stubGlobal("ResizeObserver", class {
+      constructor(cb: ResizeObserverCallback) { observerCallback = cb; }
+      observe = vi.fn();
+      disconnect = vi.fn();
+    });
+  });
+
+  it("starts at (0, 0) with no element", () => {
+    const ref = { current: null };
+    const es = new ElementSize(ref);
+    const { width, height } = es.setup() as { width: () => number; height: () => number };
+    expect(width()).toBe(0);
+    expect(height()).toBe(0);
+  });
+
+  it("updates via ResizeObserver callback", () => {
+    const el = document.createElement("div");
+    const ref = { current: el };
+    const es = new ElementSize(ref);
+    const { width, height } = es.setup() as { width: () => number; height: () => number };
+
+    observerCallback(
+      [{ contentRect: { width: 300, height: 150 } } as ResizeObserverEntry],
+      {} as ResizeObserver,
+    );
+
+    expect(width()).toBe(300);
+    expect(height()).toBe(150);
+  });
+
+  it("disconnects observer on unmount", () => {
+    const disconnect = vi.fn();
+    vi.stubGlobal("ResizeObserver", class {
+      constructor(cb: ResizeObserverCallback) { observerCallback = cb; }
+      observe = vi.fn();
+      disconnect = disconnect;
+    });
+
+    const ref = { current: null };
+    const es = new ElementSize(ref);
+    es.setup();
+    es.onUnmount();
+    expect(disconnect).toHaveBeenCalled();
   });
 });
 
-// ---------- useFocus ----------
+// ── Intersection ──────────────────────────────────────────────────────────────
+
+describe("Intersection", () => {
+  let observerCallback: IntersectionObserverCallback;
 
-describe("useFocus", () => {
+  beforeEach(() => {
+    vi.stubGlobal("IntersectionObserver", class {
+      constructor(cb: IntersectionObserverCallback) { observerCallback = cb; }
+      observe = vi.fn();
+      disconnect = vi.fn();
+    });
+  });
+
+  it("starts as not visible", () => {
+    const ref = { current: null };
+    const int = new Intersection(ref);
+    const { visible } = int.setup() as { visible: () => boolean };
+    expect(visible()).toBe(false);
+  });
+
+  it("becomes visible when intersecting", () => {
+    const el = document.createElement("div");
+    const ref = { current: el };
+    const int = new Intersection(ref);
+    const { visible } = int.setup() as { visible: () => boolean };
+
+    observerCallback(
+      [{ isIntersecting: true } as IntersectionObserverEntry],
+      {} as IntersectionObserver,
+    );
+
+    expect(visible()).toBe(true);
+  });
+
+  it("disconnects on unmount", () => {
+    const disconnect = vi.fn();
+    vi.stubGlobal("IntersectionObserver", class {
+      constructor(cb: IntersectionObserverCallback) { observerCallback = cb; }
+      observe = vi.fn();
+      disconnect = disconnect;
+    });
+
+    const ref = { current: null };
+    const int = new Intersection(ref);
+    int.setup();
+    int.onUnmount();
+    expect(disconnect).toHaveBeenCalled();
+  });
+});
+
+// ── Focus ─────────────────────────────────────────────────────────────────────
+
+describe("Focus", () => {
   it("starts as not focused", () => {
     const el = document.createElement("input");
-    document.body.appendChild(el);
     const ref = { current: el };
-    const focused = useFocus(ref);
+    const focus = new Focus(ref);
+    const { focused } = focus.setup() as { focused: () => boolean };
     expect(focused()).toBe(false);
-    document.body.removeChild(el);
   });
 
-  it("becomes true on focus event", () => {
+  it("sets focused=true on focus event", () => {
     const el = document.createElement("input");
     document.body.appendChild(el);
     const ref = { current: el };
-    const focused = useFocus(ref);
-    el.dispatchEvent(new FocusEvent("focus"));
+    const focus = new Focus(ref);
+    const { focused } = focus.setup() as { focused: () => boolean };
+
+    el.dispatchEvent(new Event("focus"));
     expect(focused()).toBe(true);
+
     document.body.removeChild(el);
   });
 
-  it("becomes false on blur event", () => {
+  it("sets focused=false on blur event", () => {
     const el = document.createElement("input");
     document.body.appendChild(el);
     const ref = { current: el };
-    const focused = useFocus(ref);
-    el.dispatchEvent(new FocusEvent("focus"));
-    el.dispatchEvent(new FocusEvent("blur"));
+    const focus = new Focus(ref);
+    const { focused } = focus.setup() as { focused: () => boolean };
+
+    el.dispatchEvent(new Event("focus"));
+    el.dispatchEvent(new Event("blur"));
     expect(focused()).toBe(false);
+
     document.body.removeChild(el);
   });
+
+  it("does not throw when ref is null", () => {
+    const ref = { current: null };
+    const focus = new Focus(ref);
+    expect(() => focus.setup()).not.toThrow();
+  });
+
+  it("removes focus/blur listeners when reactive ref changes (effect cleanup)", () => {
+    const el1 = document.createElement("input");
+    document.body.appendChild(el1);
+
+    // Make ref.current reactive so the effect tracks it and re-runs on change
+    const refSignal = signal<HTMLElement | null>(el1);
+    const ref = { get current() { return refSignal(); } };
+
+    const focus = new Focus(ref);
+    focus.setup();
+
+    const removeEl1 = vi.spyOn(el1, "removeEventListener");
+
+    // Changing the signal causes the effect to re-run, calling cleanup for el1
+    // This covers the cleanup function at dom.ts:134-135
+    const el2 = document.createElement("input");
+    document.body.appendChild(el2);
+    refSignal.set(el2);
+
+    expect(removeEl1).toHaveBeenCalledWith("focus", expect.any(Function));
+    expect(removeEl1).toHaveBeenCalledWith("blur", expect.any(Function));
+
+    document.body.removeChild(el1);
+    document.body.removeChild(el2);
+  });
 });