@praxisjs/composables 1.0.6 → 1.1.1

package/src/__tests__/dom.test.ts

@@ -1,8 +1,6 @@
 // @vitest-environment jsdom
 import { describe, it, expect, vi, beforeEach } from "vitest";
 
-import { signal } from "@praxisjs/core/internal";
-
 import { WindowSize, ScrollPosition, ElementSize, Intersection, Focus } from "../dom";
 
 // ── WindowSize ────────────────────────────────────────────────────────────────
@@ -55,6 +53,7 @@ describe("ScrollPosition", () => {
   it("updates on scroll event for window", () => {
     const sp = new ScrollPosition(window);
     const { x, y } = sp.setup() as { x: () => number; y: () => number };
+    sp.onMount();
 
     Object.defineProperty(window, "scrollX", { value: 100, configurable: true });
     Object.defineProperty(window, "scrollY", { value: 200, configurable: true });
@@ -68,6 +67,7 @@ describe("ScrollPosition", () => {
     const el = document.createElement("div");
     const sp = new ScrollPosition(el);
     const { x, y } = sp.setup() as { x: () => number; y: () => number };
+    sp.onMount();
 
     Object.defineProperty(el, "scrollLeft", { value: 50, configurable: true });
     Object.defineProperty(el, "scrollTop", { value: 75, configurable: true });
@@ -82,6 +82,7 @@ describe("ScrollPosition", () => {
     const remove = vi.spyOn(el, "removeEventListener");
     const sp = new ScrollPosition(el);
     sp.setup();
+    sp.onMount();
     sp.onUnmount();
     expect(remove).toHaveBeenCalledWith("scroll", expect.any(Function));
   });
@@ -137,6 +138,13 @@ describe("ElementSize", () => {
     es.onUnmount();
     expect(disconnect).toHaveBeenCalled();
   });
+
+  it("onMount() with null ref is a no-op", () => {
+    const ref = { current: null };
+    const es = new ElementSize(ref);
+    es.setup();
+    expect(() => es.onMount()).not.toThrow();
+  });
 });
 
 // ── Intersection ──────────────────────────────────────────────────────────────
@@ -187,6 +195,38 @@ describe("Intersection", () => {
     int.onUnmount();
     expect(disconnect).toHaveBeenCalled();
   });
+
+  it("onMount() calls observe() with the element", () => {
+    const observeFn = vi.fn();
+    vi.stubGlobal("IntersectionObserver", class {
+      constructor(cb: IntersectionObserverCallback) { observerCallback = cb; }
+      observe = observeFn;
+      disconnect = vi.fn();
+    });
+
+    const el = document.createElement("div");
+    const ref = { current: el };
+    const int = new Intersection(ref);
+    int.setup();
+    int.onMount();
+
+    expect(observeFn).toHaveBeenCalledWith(el);
+  });
+
+  it("onMount() does nothing when ref is null", () => {
+    const observeFn = vi.fn();
+    vi.stubGlobal("IntersectionObserver", class {
+      constructor(cb: IntersectionObserverCallback) { observerCallback = cb; }
+      observe = observeFn;
+      disconnect = vi.fn();
+    });
+
+    const ref = { current: null };
+    const int = new Intersection(ref);
+    int.setup();
+    expect(() => int.onMount()).not.toThrow();
+    expect(observeFn).not.toHaveBeenCalled();
+  });
 });
 
 // ── ElementSize (additional) ──────────────────────────────────────────────────
@@ -205,6 +245,7 @@ describe("ElementSize (additional)", () => {
     const ref = { current: el1 as HTMLElement | null };
     const es = new ElementSize(ref);
     es.setup();
+    es.onMount();
 
     // Disconnect old observer and create new one for el2
     es.onUnmount();
@@ -214,6 +255,7 @@ describe("ElementSize (additional)", () => {
     ref.current = el2;
     const es2 = new ElementSize(ref);
     es2.setup();
+    es2.onMount();
     expect(observeFn).toHaveBeenCalledWith(el2);
   });
 });
@@ -251,15 +293,56 @@ describe("Intersection (additional)", () => {
   });
 });
 
+// ── ScrollPosition (ref-based) ────────────────────────────────────────────────
+
+describe("ScrollPosition (ref-based)", () => {
+  it("accepts a ref object and reads scrollLeft/scrollTop from it", () => {
+    const el = document.createElement("div");
+    const ref = { current: el };
+    const sp = new ScrollPosition(ref);
+    const { x, y } = sp.setup() as { x: () => number; y: () => number };
+    sp.onMount();
+
+    Object.defineProperty(el, "scrollLeft", { value: 30, configurable: true });
+    Object.defineProperty(el, "scrollTop", { value: 60, configurable: true });
+    el.dispatchEvent(new Event("scroll"));
+
+    expect(x()).toBe(30);
+    expect(y()).toBe(60);
+  });
+
+  it("uses ref.current at mount time — subsequent current changes do not affect the listener target", () => {
+    const el = document.createElement("div");
+    const ref = { current: el as HTMLElement | null };
+    const sp = new ScrollPosition(ref);
+    sp.setup();
+    sp.onMount();
+
+    const remove = vi.spyOn(el, "removeEventListener");
+    sp.onUnmount();
+    expect(remove).toHaveBeenCalledWith("scroll", expect.any(Function));
+  });
+
+  it("falls back to window when ref.current is null at mount time", () => {
+    const ref = { current: null as HTMLElement | null };
+    const sp = new ScrollPosition(ref);
+    sp.setup();
+    // Should not throw; _target falls back to window
+    expect(() => sp.onMount()).not.toThrow();
+    sp.onUnmount();
+  });
+});
+
 // ── ScrollPosition (additional) ───────────────────────────────────────────────
 
 describe("ScrollPosition (additional)", () => {
-  it("setup() called twice registers only one scroll listener", () => {
+  it("onMount() called twice registers only one scroll listener", () => {
     const el = document.createElement("div");
     const add = vi.spyOn(el, "addEventListener");
     const sp = new ScrollPosition(el);
     sp.setup();
-    sp.setup();
+    sp.onMount();
+    sp.onMount(); // second call must be a no-op
     const scrollCalls = add.mock.calls.filter((c) => c[0] === "scroll").length;
     expect(scrollCalls).toBe(1);
   });
@@ -282,6 +365,7 @@ describe("Focus", () => {
     const ref = { current: el };
     const focus = new Focus(ref);
     const { focused } = focus.setup() as { focused: () => boolean };
+    focus.onMount();
 
     el.dispatchEvent(new Event("focus"));
     expect(focused()).toBe(true);
@@ -295,6 +379,7 @@ describe("Focus", () => {
     const ref = { current: el };
     const focus = new Focus(ref);
     const { focused } = focus.setup() as { focused: () => boolean };
+    focus.onMount();
 
     el.dispatchEvent(new Event("focus"));
     el.dispatchEvent(new Event("blur"));
@@ -309,40 +394,46 @@ describe("Focus", () => {
     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(); } };
+  it("onMount() with null ref is a no-op", () => {
+    const ref = { current: null };
+    const focus = new Focus(ref);
+    focus.setup();
+    expect(() => focus.onMount()).not.toThrow();
+  });
 
+  it("onUnmount() with null ref is a no-op", () => {
+    const ref = { current: null };
     const focus = new Focus(ref);
     focus.setup();
+    expect(() => focus.onUnmount()).not.toThrow();
+  });
 
-    const removeEl1 = vi.spyOn(el1, "removeEventListener");
+  it("removes focus/blur listeners on unmount", () => {
+    const el = document.createElement("input");
+    document.body.appendChild(el);
+    const ref = { current: el };
+    const focus = new Focus(ref);
+    focus.setup();
+    focus.onMount();
 
-    // 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);
+    const remove = vi.spyOn(el, "removeEventListener");
+    focus.onUnmount();
 
-    expect(removeEl1).toHaveBeenCalledWith("focus", expect.any(Function));
-    expect(removeEl1).toHaveBeenCalledWith("blur", expect.any(Function));
+    expect(remove).toHaveBeenCalledWith("focus", expect.any(Function));
+    expect(remove).toHaveBeenCalledWith("blur", expect.any(Function));
 
-    document.body.removeChild(el1);
-    document.body.removeChild(el2);
+    document.body.removeChild(el);
   });
 
-  it("setup() called twice registers only one listener pair", () => {
+  it("onMount() called twice registers only one listener pair", () => {
     const el = document.createElement("input");
     document.body.appendChild(el);
     const add = vi.spyOn(el, "addEventListener");
     const ref = { current: el };
     const focus = new Focus(ref);
     focus.setup();
-    focus.setup();
+    focus.onMount();
+    focus.onMount(); // second call must be a no-op
     const focusCalls = add.mock.calls.filter((c) => c[0] === "focus").length;
     expect(focusCalls).toBe(1);
     document.body.removeChild(el);

package/src/__tests__/list.test.ts

@@ -0,0 +1,210 @@
+// @vitest-environment jsdom
+import { describe, it, expect, vi } from "vitest";
+
+import { signal } from "@praxisjs/core/internal";
+
+// Import from index to cover re-exports
+import { VirtualList, type VirtualItem } from "../index";
+
+type AnyItem = { id: number };
+
+function makeItems(count: number): AnyItem[] {
+  return Array.from({ length: count }, (_, i) => ({ id: i }));
+}
+
+// ── VirtualList ───────────────────────────────────────────────────────────────
+
+describe("VirtualList", () => {
+  const ITEM_HEIGHT = 50;
+  const VIEW_HEIGHT = 600;
+  const BUFFER = 3;
+
+  it("setup() returns computed signals for all four properties", () => {
+    const ref = { current: null };
+    const vl = new VirtualList(ref, () => makeItems(10), ITEM_HEIGHT);
+    const view = vl.setup() as {
+      visibleItems: () => VirtualItem<AnyItem>[];
+      totalHeight: () => number;
+      offsetTop: () => number;
+      offsetBottom: () => number;
+    };
+
+    expect(typeof view.visibleItems).toBe("function");
+    expect(typeof view.totalHeight).toBe("function");
+    expect(typeof view.offsetTop).toBe("function");
+    expect(typeof view.offsetBottom).toBe("function");
+  });
+
+  it("totalHeight = items.length * itemHeight", () => {
+    const ref = { current: null };
+    const vl = new VirtualList(ref, () => makeItems(100), ITEM_HEIGHT);
+    const { totalHeight } = vl.setup() as { totalHeight: () => number };
+    expect(totalHeight()).toBe(100 * ITEM_HEIGHT);
+  });
+
+  it("offsetTop = 0 when scrolled to top", () => {
+    const ref = { current: null };
+    const vl = new VirtualList(ref, () => makeItems(100), ITEM_HEIGHT);
+    const { offsetTop } = vl.setup() as { offsetTop: () => number };
+    expect(offsetTop()).toBe(0);
+  });
+
+  it("visibleItems starts at index 0 with buffer window", () => {
+    const ref = { current: null };
+    // default viewHeight=600, buffer=3, scrollTop=0
+    // startIdx = max(0, floor(0/50) - 3) = 0
+    // endIdx   = min(99, ceil((0+600)/50) + 3) = min(99, 12+3) = 15
+    const vl = new VirtualList(ref, () => makeItems(100), ITEM_HEIGHT, BUFFER);
+    const { visibleItems } = vl.setup() as { visibleItems: () => VirtualItem<AnyItem>[] };
+
+    const items = visibleItems();
+    expect(items[0].index).toBe(0);
+    expect(items[items.length - 1].index).toBe(15);
+  });
+
+  it("visibleItems contains the correct item references", () => {
+    const source = makeItems(20);
+    const ref = { current: null };
+    const vl = new VirtualList(ref, () => source, ITEM_HEIGHT, 0);
+    const { visibleItems } = vl.setup() as { visibleItems: () => VirtualItem<AnyItem>[] };
+
+    const items = visibleItems();
+    expect(items[0].item).toBe(source[0]);
+    expect(items[0].index).toBe(0);
+  });
+
+  it("offsetBottom reflects the hidden rows below the window", () => {
+    const ref = { current: null };
+    // startIdx=0, endIdx=15, total=100
+    // offsetBottom = max(0, 100-1-15) * 50 = 84 * 50 = 4200
+    const vl = new VirtualList(ref, () => makeItems(100), ITEM_HEIGHT, BUFFER);
+    const { offsetBottom } = vl.setup() as { offsetBottom: () => number };
+    expect(offsetBottom()).toBe((100 - 1 - 15) * ITEM_HEIGHT);
+  });
+
+  it("empty list: all offsets are 0 and visibleItems is empty", () => {
+    const ref = { current: null };
+    const vl = new VirtualList(ref, () => [], ITEM_HEIGHT);
+    const { visibleItems, totalHeight, offsetTop, offsetBottom } = vl.setup() as {
+      visibleItems: () => VirtualItem<AnyItem>[];
+      totalHeight: () => number;
+      offsetTop: () => number;
+      offsetBottom: () => number;
+    };
+
+    expect(visibleItems()).toHaveLength(0);
+    expect(totalHeight()).toBe(0);
+    expect(offsetTop()).toBe(0);
+    expect(offsetBottom()).toBe(0);
+  });
+});
+
+// ── VirtualList — onMount ─────────────────────────────────────────────────────
+
+describe("VirtualList — onMount", () => {
+  const ITEM_HEIGHT = 50;
+
+  it("onMount() with null ref is a no-op", () => {
+    const ref = { current: null };
+    const vl = new VirtualList(ref, () => makeItems(10), ITEM_HEIGHT);
+    vl.setup();
+    expect(() => vl.onMount()).not.toThrow();
+  });
+
+  it("onMount() sets viewHeight from container's clientHeight when > 0", () => {
+    const el = document.createElement("div");
+    Object.defineProperty(el, "clientHeight", { value: 400, configurable: true });
+
+    const ref = { current: el };
+    const vl = new VirtualList(ref, () => makeItems(100), ITEM_HEIGHT, 0);
+    const { visibleItems } = vl.setup() as { visibleItems: () => VirtualItem<AnyItem>[] };
+    vl.onMount();
+
+    // With viewHeight=400 and no buffer: endIdx = min(99, ceil(400/50)-1) = 7
+    // Visible range [0..7] = 8 items
+    const items = visibleItems();
+    expect(items.length).toBeLessThan(100);
+    expect(items.length).toBeGreaterThan(0);
+    // Specifically: ceil((0+400)/50) + 0 = 8; min(99, 8) = 8 → indices 0..8 = 9 items
+    expect(items[items.length - 1].index).toBe(8);
+  });
+
+  it("onMount() does not override default viewHeight when clientHeight is 0", () => {
+    const el = document.createElement("div");
+    Object.defineProperty(el, "clientHeight", { value: 0, configurable: true });
+
+    const ref = { current: el };
+    const vl = new VirtualList(ref, () => makeItems(100), ITEM_HEIGHT, 0);
+    const { visibleItems } = vl.setup() as { visibleItems: () => VirtualItem<AnyItem>[] };
+    vl.onMount();
+
+    // Default viewHeight=600 preserved; endIdx = min(99, ceil(600/50)) = 12
+    const items = visibleItems();
+    expect(items[items.length - 1].index).toBe(12);
+  });
+
+  it("onMount() registers a scroll listener that updates the window", () => {
+    const el = document.createElement("div");
+    Object.defineProperty(el, "clientHeight", { value: 0, configurable: true });
+
+    const ref = { current: el };
+    const vl = new VirtualList(ref, () => makeItems(100), ITEM_HEIGHT, 0);
+    const { offsetTop } = vl.setup() as { offsetTop: () => number };
+    vl.onMount();
+
+    expect(offsetTop()).toBe(0);
+
+    Object.defineProperty(el, "scrollTop", { value: 500, configurable: true });
+    el.dispatchEvent(new Event("scroll"));
+
+    // scrollTop=500, buffer=0: startIdx = floor(500/50) = 10; offsetTop = 10*50 = 500
+    expect(offsetTop()).toBe(500);
+  });
+});
+
+// ── VirtualList — onUnmount ───────────────────────────────────────────────────
+
+describe("VirtualList — onUnmount", () => {
+  const ITEM_HEIGHT = 50;
+
+  it("onUnmount() removes the scroll listener", () => {
+    const el = document.createElement("div");
+    const remove = vi.spyOn(el, "removeEventListener");
+
+    const ref = { current: el };
+    const vl = new VirtualList(ref, () => makeItems(50), ITEM_HEIGHT);
+    vl.setup();
+    vl.onMount();
+    vl.onUnmount();
+
+    expect(remove).toHaveBeenCalledWith("scroll", expect.any(Function));
+  });
+
+  it("onUnmount() without prior onMount() does not throw", () => {
+    const ref = { current: null };
+    const vl = new VirtualList(ref, () => makeItems(10), ITEM_HEIGHT);
+    vl.setup();
+    expect(() => vl.onUnmount()).not.toThrow();
+  });
+});
+
+// ── VirtualList — reactive getItems ──────────────────────────────────────────
+
+describe("VirtualList — reactive getItems", () => {
+  it("visibleItems updates when the source signal changes", () => {
+    const itemsSignal = signal(makeItems(5));
+    const ref = { current: null };
+    const vl = new VirtualList(ref, () => itemsSignal(), 50);
+    const { visibleItems, totalHeight } = vl.setup() as {
+      visibleItems: () => VirtualItem<AnyItem>[];
+      totalHeight: () => number;
+    };
+
+    expect(totalHeight()).toBe(250);
+    expect(visibleItems()).toHaveLength(5);
+
+    itemsSignal.set(makeItems(10));
+    expect(totalHeight()).toBe(500);
+    expect(visibleItems()).toHaveLength(10);
+  });
+});

package/src/dom.ts

@@ -1,5 +1,5 @@
 import { Composable } from "@praxisjs/core";
-import { signal, effect } from "@praxisjs/core/internal";
+import { signal } from "@praxisjs/core/internal";
 
 export class WindowSize extends Composable {
   declare width: number;
@@ -30,31 +30,48 @@ export class ScrollPosition extends Composable {
   declare x: number;
   declare y: number;
 
-  private readonly _target: HTMLElement | Window;
-  // eslint-disable-next-line @typescript-eslint/no-empty-function
-  private _handler = () => {};
-  private _view?: Record<string, unknown>;
+  private readonly _ref?: { current: HTMLElement | null };
+  private readonly _staticTarget?: HTMLElement | Window;
+  private _handler!: () => void;
+  private _x!: ReturnType<typeof signal<number>>;
+  private _y!: ReturnType<typeof signal<number>>;
+  private _mounted = false;
 
-  constructor(target: HTMLElement | Window = window) {
+  constructor(target: HTMLElement | Window | { current: HTMLElement | null } = window) {
     super();
-    this._target = target;
+    if (typeof target === "object" && "current" in target) {
+      this._ref = target as { current: HTMLElement | null };
+    } else {
+      this._staticTarget = target;
+    }
+  }
+
+  private get _target(): HTMLElement | Window {
+    return this._ref ? (this._ref.current ?? window) : (this._staticTarget ?? window);
   }
 
   setup() {
-    if (this._view) return this._view;
-    const x = signal(0);
-    const y = signal(0);
+    this._x = signal(0);
+    this._y = signal(0);
+    return { x: this._x, y: this._y };
+  }
+
+  onMount() {
+    if (this._mounted) return;
+    this._mounted = true;
     const t = this._target;
     this._handler = () => {
-      x.set(t === window ? window.scrollX : (t as HTMLElement).scrollLeft);
-      y.set(t === window ? window.scrollY : (t as HTMLElement).scrollTop);
+      this._x.set(t === window ? window.scrollX : (t as HTMLElement).scrollLeft);
+      this._y.set(t === window ? window.scrollY : (t as HTMLElement).scrollTop);
     };
     t.addEventListener("scroll", this._handler);
-    this._view = { x, y };
-    return this._view;
+    // set initial values
+    this._x.set(t === window ? window.scrollX : (t as HTMLElement).scrollLeft);
+    this._y.set(t === window ? window.scrollY : (t as HTMLElement).scrollTop);
   }
 
   onUnmount() {
+    this._mounted = false;
     this._target.removeEventListener("scroll", this._handler);
   }
 }
@@ -64,6 +81,8 @@ export class ElementSize extends Composable {
   declare height: number;
 
   private _observer?: ResizeObserver;
+  private _width!: ReturnType<typeof signal<number>>;
+  private _height!: ReturnType<typeof signal<number>>;
   private _view?: Record<string, unknown>;
 
   constructor(private readonly ref: { current: HTMLElement | null }) {
@@ -72,23 +91,24 @@ export class ElementSize extends Composable {
 
   setup() {
     if (this._view) return this._view;
-    const width = signal(0);
-    const height = signal(0);
+    this._width = signal(0);
+    this._height = signal(0);
     this._observer = new ResizeObserver(([entry]) => {
-      width.set(entry.contentRect.width);
-      height.set(entry.contentRect.height);
-    });
-    effect(() => {
-      if (this.ref.current) {
-        this._observer?.observe(this.ref.current);
-        width.set(this.ref.current.offsetWidth);
-        height.set(this.ref.current.offsetHeight);
-      }
+      this._width.set(entry.contentRect.width);
+      this._height.set(entry.contentRect.height);
     });
-    this._view = { width, height };
+    this._view = { width: this._width, height: this._height };
     return this._view;
   }
 
+  onMount() {
+    const el = this.ref.current;
+    if (!el) return;
+    this._observer?.observe(el);
+    this._width.set(el.offsetWidth);
+    this._height.set(el.offsetHeight);
+  }
+
   onUnmount() {
     this._observer?.disconnect();
   }
@@ -98,6 +118,7 @@ export class Intersection extends Composable {
   declare visible: boolean;
 
   private _observer?: IntersectionObserver;
+  private _visible!: ReturnType<typeof signal<boolean>>;
   private _view?: Record<string, unknown>;
 
   constructor(
@@ -109,17 +130,19 @@ export class Intersection extends Composable {
 
   setup() {
     if (this._view) return this._view;
-    const visible = signal(false);
+    this._visible = signal(false);
     this._observer = new IntersectionObserver(([entry]) => {
-      visible.set(entry.isIntersecting);
+      this._visible.set(entry.isIntersecting);
     }, this.options);
-    effect(() => {
-      if (this.ref.current) this._observer?.observe(this.ref.current);
-    });
-    this._view = { visible };
+    this._view = { visible: this._visible };
     return this._view;
   }
 
+  onMount() {
+    const el = this.ref.current;
+    if (el) this._observer?.observe(el);
+  }
+
   onUnmount() {
     this._observer?.disconnect();
   }
@@ -128,32 +151,34 @@ export class Intersection extends Composable {
 export class Focus extends Composable {
   declare focused: boolean;
 
-  private _view?: Record<string, unknown>;
+  private _focused!: ReturnType<typeof signal<boolean>>;
+  private readonly _onFocus = () => { this._focused.set(true); };
+  private readonly _onBlur = () => { this._focused.set(false); };
+  private _mounted = false;
 
   constructor(private readonly ref: { current: HTMLElement | null }) {
     super();
   }
 
   setup() {
-    if (this._view) return this._view;
-    const focused = signal(false);
-    effect(() => {
-      const el = this.ref.current;
-      if (!el) return;
-      const onFocus = () => {
-        focused.set(true);
-      };
-      const onBlur = () => {
-        focused.set(false);
-      };
-      el.addEventListener("focus", onFocus);
-      el.addEventListener("blur", onBlur);
-      return () => {
-        el.removeEventListener("focus", onFocus);
-        el.removeEventListener("blur", onBlur);
-      };
-    });
-    this._view = { focused };
-    return this._view;
+    this._focused = signal(false);
+    return { focused: this._focused };
+  }
+
+  onMount() {
+    if (this._mounted) return;
+    this._mounted = true;
+    const el = this.ref.current;
+    if (!el) return;
+    el.addEventListener("focus", this._onFocus);
+    el.addEventListener("blur", this._onBlur);
+  }
+
+  onUnmount() {
+    this._mounted = false;
+    const el = this.ref.current;
+    if (!el) return;
+    el.removeEventListener("focus", this._onFocus);
+    el.removeEventListener("blur", this._onBlur);
   }
 }

package/src/index.ts

@@ -13,3 +13,4 @@ export {
   Pagination,
   type PaginationOptions,
 } from "./utilities";
+export { VirtualList, type VirtualItem } from "./list";