@praxisjs/decorators 0.4.3 → 0.6.0

package/src/__tests__/until.test.ts

@@ -0,0 +1,113 @@
+import { describe, it, expect } from "vitest";
+
+import { signal, computed } from "@praxisjs/core/internal";
+
+import { Until } from "../functions/until";
+
+// Simulates TC39 decorator context for a method decorator
+function mockMethodContext(name: string) {
+  const initializers: Array<(this: object) => void> = [];
+  const ctx = {
+    name,
+    kind: "method" as const,
+    addInitializer(fn: (this: object) => void) {
+      initializers.push(fn);
+    },
+    runInitializers(instance: object) {
+      initializers.forEach((fn) => { fn.call(instance); });
+    },
+  };
+  return ctx;
+}
+
+// ── @Until ────────────────────────────────────────────────────────────────────
+
+describe("Until", () => {
+  it("resolves immediately when the signal is already truthy", async () => {
+    const s = signal(42);
+    const obj: Record<string, unknown> = { count: s };
+
+    const ctx = mockMethodContext("wait");
+    Until("count")(() => {}, ctx as unknown as ClassMethodDecoratorContext);
+    ctx.runInitializers(obj);
+
+    const result = await (obj.wait as () => Promise<number>)();
+    expect(result).toBe(42);
+  });
+
+  it("resolves when the signal becomes truthy", async () => {
+    const s = signal<number>(0);
+    const obj: Record<string, unknown> = { count: s };
+
+    const ctx = mockMethodContext("wait");
+    Until("count")(() => {}, ctx as unknown as ClassMethodDecoratorContext);
+    ctx.runInitializers(obj);
+
+    const promise = (obj.wait as () => Promise<number>)();
+    s.set(5);
+    expect(await promise).toBe(5);
+  });
+
+  it("resolves with a computed signal", async () => {
+    const s = signal(0);
+    const doubled = computed(() => s() * 2);
+    const obj: Record<string, unknown> = { doubled };
+
+    const ctx = mockMethodContext("waitDoubled");
+    Until("doubled")(() => {}, ctx as unknown as ClassMethodDecoratorContext);
+    ctx.runInitializers(obj);
+
+    const promise = (obj.waitDoubled as () => Promise<number>)();
+    s.set(3); // doubled becomes 6 (truthy)
+    expect(await promise).toBe(6);
+  });
+
+  it("each call returns a new promise", async () => {
+    const s = signal<string>("");
+    const obj: Record<string, unknown> = { name: s };
+
+    const ctx = mockMethodContext("waitName");
+    Until("name")(() => {}, ctx as unknown as ClassMethodDecoratorContext);
+    ctx.runInitializers(obj);
+
+    const wait = obj.waitName as () => Promise<string>;
+
+    const p1 = wait();
+    const p2 = wait();
+    expect(p1).not.toBe(p2);
+
+    s.set("alice");
+    expect(await p1).toBe("alice");
+    expect(await p2).toBe("alice");
+  });
+
+  it("does not resolve when signal stays falsy", async () => {
+    const s = signal<number>(0);
+    const obj: Record<string, unknown> = { count: s };
+
+    const ctx = mockMethodContext("wait");
+    Until("count")(() => {}, ctx as unknown as ClassMethodDecoratorContext);
+    ctx.runInitializers(obj);
+
+    let resolved = false;
+    (obj.wait as () => Promise<number>)().then(() => { resolved = true; });
+
+    await new Promise((res) => { setTimeout(res, 10); });
+    expect(resolved).toBe(false);
+  });
+
+  it("ignores the original method body", async () => {
+    const s = signal("hello");
+    const obj: Record<string, unknown> = { value: s };
+
+    let bodyCalled = false;
+    const original = () => { bodyCalled = true; };
+
+    const ctx = mockMethodContext("wait");
+    Until("value")(original, ctx as unknown as ClassMethodDecoratorContext);
+    ctx.runInitializers(obj);
+
+    await (obj.wait as () => Promise<string>)();
+    expect(bodyCalled).toBe(false);
+  });
+});

package/src/__tests__/virtual.test.ts

@@ -158,16 +158,16 @@ describe("Virtual decorator", () => {
     (instance as unknown as { _anchor: Comment })._anchor = anchor;
 
     instance.onMount?.();
-    // First render - populates the itemsSlot
-    instance.render();
+    // First render - sets up effects with the spacerTop/itemsSlot/spacerBottom elements
+    const outer = instance.render() as HTMLElement;
 
     // Change scrollTop to trigger effect re-run (covers the while loop removing old nodes)
     Object.defineProperty(container, "scrollTop", { configurable: true, value: 500 });
     container.dispatchEvent(new Event("scroll"));
 
-    // Verify scrollTop was updated (effect should have re-run)
-    const scrollTop = (instance as unknown as { _scrollTop: () => number })._scrollTop;
-    expect(scrollTop()).toBe(500);
+    // buffer=0, itemHeight=50, scrollTop=500 → startIdx=10 → offsetTop=500px
+    const spacerTop = outer.children[0] as HTMLElement;
+    expect(spacerTop.getAttribute("style")).toContain("500px");
 
     document.body.removeChild(container);
   });
@@ -211,6 +211,22 @@ describe("Virtual decorator", () => {
     expect(wrapper.children.length).toBe(0);
   });
 
+  it("uses empty array when items is undefined (host.items ?? [])", () => {
+    class NoItems extends StatefulComponent {
+      // items is intentionally not defined
+      renderItem() { return document.createElement("div"); }
+      render() { return null; }
+    }
+
+    const Wrapped = applyVirtual(NoItems as AnyConstructor, 50, 0);
+    const instance = new Wrapped();
+    // render() should work fine with 0 items
+    const result = instance.render() as HTMLElement;
+    expect(result).toBeInstanceOf(HTMLElement);
+    const style = result.getAttribute("style") ?? "";
+    expect(style).toContain("0px"); // totalH = 0 * 50 = 0
+  });
+
   it("onUnmount without prior onMount does not throw", () => {
     const Wrapped = applyVirtual(ListComp as AnyConstructor, 50);
     const instance = new Wrapped();
@@ -230,12 +246,124 @@ describe("Virtual decorator", () => {
     (instance as unknown as { _anchor: Comment })._anchor = anchor;
 
     instance.onMount?.();
+    // Render to set up effects that observe scrollTop
+    const outer = instance.render() as HTMLElement;
 
     Object.defineProperty(container, "scrollTop", { configurable: true, value: 200 });
     container.dispatchEvent(new Event("scroll"));
 
-    const scrollTop = (instance as unknown as { _scrollTop: () => number })._scrollTop;
-    expect(scrollTop()).toBe(200);
+    // buffer=3, itemHeight=50, scrollTop=200 → startIdx=1 → offsetTop=50px
+    const spacerTop = outer.children[0] as HTMLElement;
+    expect(spacerTop.getAttribute("style")).toContain("50px");
+    document.body.removeChild(container);
+  });
+
+  it("itemHeight = 0 throws a descriptive error on onMount", () => {
+    class ZeroHeightList extends StatefulComponent {
+      items = ["a", "b"];
+      renderItem(item: unknown) {
+        const el = document.createElement("div");
+        el.textContent = String(item);
+        return el;
+      }
+      render() { return null; }
+    }
+
+    const Wrapped = applyVirtual(ZeroHeightList as AnyConstructor, 0);
+    const instance = new Wrapped();
+
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    const anchor = document.createComment("end");
+    container.appendChild(anchor);
+    (instance as unknown as { _anchor: Comment })._anchor = anchor;
+
+    expect(() => instance.onMount?.()).toThrow(/itemHeight must be a positive number/);
+    document.body.removeChild(container);
+  });
+
+  it("itemHeight = 0 in render() does not divide by zero (no container)", () => {
+    class ZeroHeightList2 extends StatefulComponent {
+      items = ["a", "b"];
+      renderItem(item: unknown) {
+        return document.createElement("div");
+      }
+      render() { return null; }
+    }
+    // render() is called before onMount, so no throw yet — but it still computes total height
+    const Wrapped = applyVirtual(ZeroHeightList2 as AnyConstructor, 0);
+    const instance = new Wrapped();
+    // Render without mounting — no onMount guard triggered, but division happens in computed
+    // The guard is in onMount, so render still runs. Verify it doesn't produce NaN/Infinity
+    expect(() => instance.render()).not.toThrow();
+  });
+
+  it("renderItem() that throws — does not crash the entire component", () => {
+    class ThrowingList extends StatefulComponent {
+      items = ["x"];
+      renderItem(): Node {
+        throw new Error("render item failed");
+      }
+      render() { return null; }
+    }
+
+    const Wrapped = applyVirtual(ThrowingList as AnyConstructor, 50, 0);
+    const instance = new Wrapped();
+    // Render triggers the effect which calls renderItem — it should propagate the error
+    expect(() => instance.render()).toThrow("render item failed");
+  });
+
+  it("scrollTop > totalHeight renders last visible items without crash", () => {
+    class ShortList extends StatefulComponent {
+      items = [1, 2, 3]; // only 3 items × 50px = 150px total
+      renderItem(item: unknown) {
+        const el = document.createElement("div");
+        el.textContent = String(item);
+        return el;
+      }
+      render() { return null; }
+    }
+
+    const Wrapped = applyVirtual(ShortList as AnyConstructor, 50, 0);
+    const instance = new Wrapped();
+
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    const anchor = document.createComment("end");
+    container.appendChild(anchor);
+    (instance as unknown as { _anchor: Comment })._anchor = anchor;
+
+    instance.onMount?.();
+    const outer = instance.render() as HTMLElement;
+
+    // Simulate scrollTop way past end of list (e.g., 9999px for a 150px list)
+    Object.defineProperty(container, "scrollTop", { configurable: true, value: 9999 });
+    expect(() => container.dispatchEvent(new Event("scroll"))).not.toThrow();
+
+    // The outer container should still be present
+    expect(outer).toBeInstanceOf(HTMLElement);
     document.body.removeChild(container);
   });
+
+  it("buffer applied correctly — renders extra items beyond visible area", () => {
+    class BufferList extends StatefulComponent {
+      items = Array.from({ length: 20 }, (_, i) => i);
+      renderItem(item: unknown) {
+        const el = document.createElement("div");
+        el.textContent = String(item);
+        return el;
+      }
+      render() { return null; }
+    }
+
+    // itemHeight=100, buffer=2, viewHeight defaults to 600 → visible=6 items + 2 buffer each side
+    const Wrapped = applyVirtual(BufferList as AnyConstructor, 100, 2);
+    const instance = new Wrapped();
+    const outer = instance.render() as HTMLElement;
+
+    // With scrollTop=0, buffer=2: startIdx=max(0, 0-2)=0, endIdx=min(19, ceil(600/100)+2)=8
+    // So 9 items should be rendered (indices 0..8)
+    const itemsSlot = outer.children[1] as HTMLElement;
+    expect(itemsSlot.children.length).toBe(9);
+  });
 });

package/src/component/component.ts

@@ -1,25 +1,40 @@
 import { StatelessComponent } from "@praxisjs/core";
+import type { RootComponent } from "@praxisjs/core/internal";
 import type {
   ComponentConstructor,
   ComponentInstance,
 } from "@praxisjs/shared/internal";
 
+import {
+  ClassBehavior,
+  createClassDecorator,
+  type ClassEnhancement,
+} from "../create-class-decorator";
+
+class ComponentBehavior extends ClassBehavior {
+  create(_instance: RootComponent): ClassEnhancement {
+    return {};
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  initialize(Enhanced: new (...args: any[]) => unknown, original: new (...args: any[]) => unknown): void {
+    const isStateless = (original.prototype as object) instanceof StatelessComponent;
+    Object.defineProperty(Enhanced, "__isComponent", { value: true, configurable: true });
+    Object.defineProperty(Enhanced, "__isStateless", { value: isStateless, configurable: true });
+  }
+}
+
+const behavior = new ComponentBehavior();
+
 export function Component() {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   return function <T extends new (...args: any[]) => ComponentInstance>(
     constructor: T,
-    _context: ClassDecoratorContext,
+    context: ClassDecoratorContext,
   ): T & ComponentConstructor {
-    const isStateless = constructor.prototype instanceof StatelessComponent;
-    const Enhanced = class extends constructor {
-      static __isComponent = true as const;
-      static __isStateless = isStateless;
-    } as unknown as T & ComponentConstructor;
-
-    Object.defineProperty(Enhanced, "name", {
-      value: constructor.name,
-    });
-
-    return Enhanced;
+    return createClassDecorator(behavior)(
+      constructor as unknown as T & (new(...args: unknown[]) => RootComponent<Record<string, unknown>>),
+      context,
+    ) as unknown as T & ComponentConstructor;
   };
 }

package/src/component/lazy.ts

@@ -1,60 +1,56 @@
 import { type RootComponent, signal } from "@praxisjs/core/internal";
 
-export function Lazy(placeholder = 200) {
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  return function <T extends new (...args: any[]) => RootComponent<Record<string, any>>>(
-    constructor: T,
-    _context: ClassDecoratorContext,
-  ): T {
-    return class LazyWrapper extends constructor {
-      private readonly _lazyVisible = signal(false);
-      private _observer?: IntersectionObserver;
-      private readonly _originalRender: () => Node | Node[] | null =
-        // Capture the *parent* class render, not LazyWrapper's own override,
-        // to avoid infinite recursion when render() delegates here.
-        (constructor.prototype as { render(): Node | Node[] | null }).render.bind(this);
+import { ClassBehavior, createClassDecorator, type ClassEnhancement } from "../create-class-decorator";
 
-      onMount() {
-        super.onMount?.();
+class LazyBehavior extends ClassBehavior {
+  constructor(private readonly placeholder: number) {
+    super();
+  }
 
-        // Use the end anchor to find the parent element
+  create(instance: RootComponent): ClassEnhancement {
+    const placeholder = this.placeholder;
+    const visible = signal(false);
+    let observer: IntersectionObserver | undefined;
+
+    return {
+      onMount() {
         const el =
-          (this as unknown as { _anchor?: Comment })._anchor
-            ?.parentElement ?? null;
+          (instance as { _anchor?: Comment })._anchor?.parentElement ?? null;
         if (!el) return;
 
         if (!("IntersectionObserver" in window)) {
-          this._lazyVisible.set(true);
+          visible.set(true);
           return;
         }
 
-        if (!this._lazyVisible()) {
-          el.style.minHeight = `${String(placeholder)}px`;
-        }
+        if (!visible()) el.style.minHeight = `${String(placeholder)}px`;
 
-        this._observer = new IntersectionObserver(
+        observer = new IntersectionObserver(
           (entries) => {
             if (entries[0]?.isIntersecting) {
-              this._lazyVisible.set(true);
+              visible.set(true);
               el.style.minHeight = "";
-              this._observer?.disconnect();
+              observer?.disconnect();
             }
           },
           { rootMargin: "100px" },
         );
 
-        this._observer.observe(el);
-      }
+        observer.observe(el);
+      },
 
       onUnmount() {
-        super.onUnmount?.();
-        this._observer?.disconnect();
-      }
-
-      render(): Node | Node[] | null {
-        if (!this._lazyVisible()) return null;
-        return this._originalRender();
-      }
-    } as unknown as T;
-  };
+        observer?.disconnect();
+      },
+
+      render(originalRender) {
+        if (!visible()) return null;
+        return originalRender();
+      },
+    };
+  }
+}
+
+export function Lazy(placeholder = 200) {
+  return createClassDecorator(new LazyBehavior(placeholder));
 }

package/src/component/virtual.tsx

@@ -1,81 +1,81 @@
 import { computed, effect, type RootComponent, signal } from "@praxisjs/core/internal";
 
+import { ClassBehavior, createClassDecorator, type ClassEnhancement } from "../create-class-decorator";
+
 interface VirtualHost {
   _anchor?: Comment;
   items?: unknown[];
   renderItem(item: unknown, index: number): Node | Node[] | null;
 }
 
-export function Virtual(itemHeight: number, buffer = 3) {
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  return function <T extends new (...args: any[]) => RootComponent<Record<string, any>>>(
-    constructor: T,
-    _context: ClassDecoratorContext,
-  ): T {
-    return class VirtualWrapper extends constructor {
-      private readonly _scrollTop = signal(0);
-      private readonly _viewHeight = signal(600);
-      private _container?: HTMLElement;
-      private _scrollHandler?: () => void;
-      private _cleanups: Array<() => void> = [];
-
+class VirtualBehavior extends ClassBehavior {
+  constructor(
+    private readonly itemHeight: number,
+    private readonly buffer: number,
+  ) {
+    super();
+  }
+
+  create(instance: RootComponent): ClassEnhancement {
+    const { itemHeight, buffer } = this;
+    const host = instance as unknown as VirtualHost;
+    const scrollTop = signal(0);
+    const viewHeight = signal(600);
+    let container: HTMLElement | undefined;
+    let scrollHandler: (() => void) | undefined;
+    const cleanups: Array<() => void> = [];
+
+    return {
       onMount() {
-        super.onMount?.();
-
-        // Use the end anchor set by the runtime to locate the parent element
-        this._container =
-          (this as unknown as VirtualHost)._anchor?.parentElement ?? undefined;
-
-        if (!this._container) return;
-
-        this._container.style.overflowY = "auto";
-        this._container.style.position = "relative";
+        if (itemHeight <= 0) {
+          throw new Error(
+            `[Virtual] itemHeight must be a positive number, got ${String(itemHeight)}`,
+          );
+        }
+        container = host._anchor?.parentElement ?? undefined;
+        if (!container) return;
 
-        this._viewHeight.set(this._container.clientHeight || 600);
+        container.style.overflowY = "auto";
+        container.style.position = "relative";
+        viewHeight.set(container.clientHeight || 600);
 
-        this._scrollHandler = () => {
-          if (this._container) this._scrollTop.set(this._container.scrollTop);
+        scrollHandler = () => {
+          if (container) scrollTop.set(container.scrollTop);
         };
-
-        this._container.addEventListener("scroll", this._scrollHandler);
-      }
+        container.addEventListener("scroll", scrollHandler);
+      },
 
       onUnmount() {
-        super.onUnmount?.();
-        if (this._container && this._scrollHandler) {
-          this._container.removeEventListener("scroll", this._scrollHandler);
+        if (container && scrollHandler) {
+          container.removeEventListener("scroll", scrollHandler);
         }
-        this._cleanups.forEach((c) => { c(); });
-        this._cleanups = [];
-      }
+        cleanups.forEach((c) => { c(); });
+        cleanups.length = 0;
+      },
 
-      render() {
-        const host = this as unknown as VirtualHost;
+      render(originalRender) {
         const items = host.items ?? [];
         const total = items.length;
         const totalH = total * itemHeight;
 
         if (typeof host.renderItem !== "function") {
           console.warn(
-            `[Virtual] ${constructor.name} must implement renderItem(item, index)`,
+            `[Virtual] component must implement renderItem(item, index)`,
           );
-          return null;
+          return originalRender();
         }
 
         const renderItem = host.renderItem.bind(host);
 
-        const startIdx = computed(() => {
-          const start = Math.floor(this._scrollTop() / itemHeight) - buffer;
-          return Math.max(0, start);
-        });
-
-        const endIdx = computed(() => {
-          const end =
-            Math.ceil((this._scrollTop() + this._viewHeight()) / itemHeight) +
-            buffer;
-          return Math.min(total - 1, end);
-        });
-
+        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(() => {
           const result: Array<{ item: unknown; index: number }> = [];
           for (let i = startIdx(); i <= endIdx(); i++) {
@@ -83,31 +83,23 @@ export function Virtual(itemHeight: number, buffer = 3) {
           }
           return result;
         });
-
         const offsetTop = computed(() => startIdx() * itemHeight);
-        const offsetBottom = computed(
-          () => (total - 1 - endIdx()) * itemHeight,
-        );
+        const offsetBottom = computed(() => (total - 1 - endIdx()) * itemHeight);
 
         const outer = document.createElement("div");
-        outer.setAttribute(
-          "style",
-          `height:${String(totalH)}px; position:relative;`,
-        );
+        outer.setAttribute("style", `height:${String(totalH)}px; position:relative;`);
 
         const spacerTop = document.createElement("div");
-        this._cleanups.push(
+        cleanups.push(
           effect(() => {
             spacerTop.setAttribute("style", `height:${String(offsetTop())}px;`);
           }),
         );
 
         const itemsSlot = document.createElement("div");
-        this._cleanups.push(
+        cleanups.push(
           effect(() => {
-            while (itemsSlot.firstChild) {
-              itemsSlot.removeChild(itemsSlot.firstChild);
-            }
+            while (itemsSlot.firstChild) itemsSlot.removeChild(itemsSlot.firstChild);
             visibleItems().forEach(({ item, index }) => {
               const wrapper = document.createElement("div");
               wrapper.setAttribute(
@@ -116,10 +108,9 @@ export function Virtual(itemHeight: number, buffer = 3) {
               );
               const rendered = renderItem(item, index);
               if (rendered) {
-                const nodes = (
-                  Array.isArray(rendered) ? rendered.flat() : [rendered]
+                (Array.isArray(rendered) ? rendered.flat() : [rendered]).forEach(
+                  (n) => { wrapper.appendChild(n); },
                 );
-                nodes.forEach((n) => wrapper.appendChild(n));
               }
               itemsSlot.appendChild(wrapper);
             });
@@ -127,12 +118,9 @@ export function Virtual(itemHeight: number, buffer = 3) {
         );
 
         const spacerBottom = document.createElement("div");
-        this._cleanups.push(
+        cleanups.push(
           effect(() => {
-            spacerBottom.setAttribute(
-              "style",
-              `height:${String(offsetBottom())}px;`,
-            );
+            spacerBottom.setAttribute("style", `height:${String(offsetBottom())}px;`);
           }),
         );
 
@@ -141,7 +129,11 @@ export function Virtual(itemHeight: number, buffer = 3) {
         outer.appendChild(spacerBottom);
 
         return outer;
-      }
-    } as unknown as T;
-  };
+      },
+    };
+  }
+}
+
+export function Virtual(itemHeight: number, buffer = 3) {
+  return createClassDecorator(new VirtualBehavior(itemHeight, buffer));
 }