@praxisjs/composables 1.0.6 → 1.1.0

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";

package/src/list.ts

@@ -0,0 +1,77 @@
+import { Composable } from "@praxisjs/core";
+import { computed, signal } from "@praxisjs/core/internal";
+
+export interface VirtualItem<T> {
+  item: T;
+  index: number;
+}
+
+export class VirtualList<T = unknown> extends Composable {
+  declare visibleItems: Array<VirtualItem<T>>;
+  declare totalHeight: number;
+  declare offsetTop: number;
+  declare offsetBottom: number;
+
+  private readonly _scrollTop = signal(0);
+  private readonly _viewHeight = signal(600);
+  private _scrollCleanup?: () => void;
+
+  constructor(
+    private readonly containerRef: { current: HTMLElement | null },
+    private readonly getItems: () => T[],
+    private readonly itemHeight: number,
+    private readonly buffer = 3,
+  ) {
+    super();
+  }
+
+  setup() {
+    const { _scrollTop, _viewHeight, itemHeight, buffer, getItems } = this;
+
+    const items = computed(getItems);
+    const total = computed(() => items().length);
+
+    const startIdx = computed(() =>
+      Math.max(0, Math.floor(_scrollTop() / itemHeight) - buffer),
+    );
+    const endIdx = computed(() =>
+      Math.min(
+        total() - 1,
+        Math.ceil((_scrollTop() + _viewHeight()) / itemHeight) + buffer,
+      ),
+    );
+
+    const visibleItems = computed<Array<VirtualItem<T>>>(() => {
+      const arr = items();
+      const result: Array<VirtualItem<T>> = [];
+      for (let i = startIdx(); i <= endIdx(); i++) {
+        result.push({ item: arr[i], index: i });
+      }
+      return result;
+    });
+
+    const totalHeight = computed(() => total() * itemHeight);
+    const offsetTop = computed(() => startIdx() * itemHeight);
+    const offsetBottom = computed(() =>
+      Math.max(0, total() - 1 - endIdx()) * itemHeight,
+    );
+
+    return { visibleItems, totalHeight, offsetTop, offsetBottom };
+  }
+
+  onMount() {
+    const el = this.containerRef.current;
+    if (!el) return;
+
+    const h = el.clientHeight;
+    if (h > 0) this._viewHeight.set(h);
+
+    const handler = () => { this._scrollTop.set(el.scrollTop); };
+    el.addEventListener("scroll", handler);
+    this._scrollCleanup = () => { el.removeEventListener("scroll", handler); };
+  }
+
+  onUnmount() {
+    this._scrollCleanup?.();
+  }
+}