@praxisjs/decorators 0.4.2 → 0.5.0

package/src/__tests__/resource.test.ts

@@ -0,0 +1,113 @@
+import { describe, it, expect, vi } from "vitest";
+
+import { Resource } from "../properties/resource";
+
+function makeFieldCtx(name: string) {
+  const initializers: Array<(this: unknown) => void> = [];
+  return {
+    ctx: {
+      name,
+      kind: "field" as const,
+      addInitializer(fn: (this: unknown) => void) { initializers.push(fn); },
+    } as ClassFieldDecoratorContext,
+    run(instance: unknown) { initializers.forEach((fn) => { fn.call(instance); }); },
+  };
+}
+
+describe("@Resource", () => {
+  it("binds a Resource object to the field", () => {
+    const { ctx, run } = makeFieldCtx("users");
+    Resource(() => Promise.resolve([]))(undefined, ctx);
+    const instance: Record<string, unknown> = {};
+    run(instance);
+    const r = instance.users as Record<string, unknown>;
+    expect(typeof r.data).toBe("function");
+    expect(typeof r.pending).toBe("function");
+    expect(typeof r.error).toBe("function");
+    expect(typeof r.status).toBe("function");
+    expect(typeof r.refetch).toBe("function");
+    expect(typeof r.cancel).toBe("function");
+    expect(typeof r.mutate).toBe("function");
+  });
+
+  it("starts in pending state when immediate=true (default)", () => {
+    const { ctx, run } = makeFieldCtx("data");
+    Resource(() => new Promise(() => {}))(undefined, ctx);
+    const instance: Record<string, unknown> = {};
+    run(instance);
+    const r = instance.data as { pending: () => boolean; status: () => string };
+    expect(r.pending()).toBe(true);
+    expect(r.status()).toBe("pending");
+  });
+
+  it("starts idle when immediate=false", () => {
+    const { ctx, run } = makeFieldCtx("data");
+    Resource(() => Promise.resolve(42), { immediate: false })(undefined, ctx);
+    const instance: Record<string, unknown> = {};
+    run(instance);
+    const r = instance.data as { status: () => string; pending: () => boolean };
+    expect(r.status()).toBe("idle");
+    expect(r.pending()).toBe(false);
+  });
+
+  it("resolves data asynchronously", async () => {
+    const { ctx, run } = makeFieldCtx("items");
+    Resource(() => Promise.resolve([1, 2, 3]))(undefined, ctx);
+    const instance: Record<string, unknown> = {};
+    run(instance);
+    const r = instance.items as { data: () => unknown; status: () => string };
+    await vi.waitFor(() => r.status() === "success");
+    expect(r.data()).toEqual([1, 2, 3]);
+  });
+
+  it("sets error state on rejection", async () => {
+    const { ctx, run } = makeFieldCtx("items");
+    Resource(() => Promise.reject(new Error("fetch failed")))(undefined, ctx);
+    const instance: Record<string, unknown> = {};
+    run(instance);
+    const r = instance.items as { error: () => Error | null; status: () => string };
+    await new Promise((res) => setTimeout(res, 0));
+    expect(r.status()).toBe("error");
+    expect((r.error() as Error).message).toBe("fetch failed");
+  });
+
+  it("each instance gets its own resource", () => {
+    const { ctx, run } = makeFieldCtx("r");
+    Resource(() => Promise.resolve(0))(undefined, ctx);
+    const a: Record<string, unknown> = {};
+    const b: Record<string, unknown> = {};
+    run(a);
+    run(b);
+    expect(a.r).not.toBe(b.r);
+  });
+
+  it("mutate() updates data immediately", async () => {
+    const { ctx, run } = makeFieldCtx("r");
+    Resource(() => Promise.resolve(1))(undefined, ctx);
+    const instance: Record<string, unknown> = {};
+    run(instance);
+    const r = instance.r as { mutate: (v: number) => void; data: () => number; status: () => string };
+    r.mutate(99);
+    expect(r.data()).toBe(99);
+    expect(r.status()).toBe("success");
+  });
+
+  it("cancel() stops a pending fetch", async () => {
+    const { ctx, run } = makeFieldCtx("r");
+    Resource(() => new Promise(() => {}))(undefined, ctx);
+    const instance: Record<string, unknown> = {};
+    run(instance);
+    const r = instance.r as { cancel: () => void; status: () => string };
+    r.cancel();
+    expect(r.status()).toBe("idle");
+  });
+
+  it("uses initialData option", () => {
+    const { ctx, run } = makeFieldCtx("r");
+    Resource(() => Promise.resolve("new"), { initialData: "default", immediate: false })(undefined, ctx);
+    const instance: Record<string, unknown> = {};
+    run(instance);
+    const r = instance.r as { data: () => string };
+    expect(r.data()).toBe("default");
+  });
+});

package/src/__tests__/slot.test.ts

@@ -0,0 +1,179 @@
+// @vitest-environment jsdom
+import { describe, it, expect, vi } from "vitest";
+
+import { initSlots, getSlot, Slot } from "../properties/slot";
+import { StatefulComponent } from "@praxisjs/core";
+
+// ── initSlots / getSlot ──────────────────────────────────────────────────────
+
+describe("initSlots / getSlot", () => {
+  it("returns empty default slot when children is null", () => {
+    const instance = {};
+    initSlots(instance, null);
+    expect(getSlot(instance, "default")).toEqual([]);
+  });
+
+  it("returns empty array for unknown slot", () => {
+    const instance = {};
+    initSlots(instance, null);
+    expect(getSlot(instance, "unknown")).toEqual([]);
+  });
+
+  it("puts plain children into the default slot", () => {
+    const instance = {};
+    const child = document.createElement("span");
+    initSlots(instance, child);
+    expect(getSlot(instance, "default")).toEqual([child]);
+  });
+
+  it("flattens array children into the default slot", () => {
+    const instance = {};
+    const a = document.createElement("p");
+    const b = document.createElement("div");
+    initSlots(instance, [a, b]);
+    expect(getSlot(instance, "default")).toEqual([a, b]);
+  });
+
+  it("routes element with slot attribute to named slot", () => {
+    const instance = {};
+    const el = document.createElement("div");
+    el.setAttribute("slot", "header");
+    initSlots(instance, el);
+    expect(getSlot(instance, "header")).toEqual([el]);
+    expect(getSlot(instance, "default")).toEqual([]);
+    // slot attribute should be removed
+    expect(el.hasAttribute("slot")).toBe(false);
+  });
+
+  it("handles mixed named and default children", () => {
+    const instance = {};
+    const named = document.createElement("aside");
+    named.setAttribute("slot", "sidebar");
+    const plain = document.createElement("main");
+    initSlots(instance, [named, plain]);
+    expect(getSlot(instance, "sidebar")).toEqual([named]);
+    expect(getSlot(instance, "default")).toEqual([plain]);
+  });
+
+  it("skips null children in array", () => {
+    const instance = {};
+    const el = document.createElement("span");
+    initSlots(instance, [null, el, undefined]);
+    expect(getSlot(instance, "default")).toEqual([el]);
+  });
+
+  it("appends to existing named slot when same slot name appears twice", () => {
+    const instance = {};
+    const a = document.createElement("div");
+    a.setAttribute("slot", "header");
+    const b = document.createElement("div");
+    b.setAttribute("slot", "header");
+    initSlots(instance, [a, b]);
+    const headerSlot = getSlot(instance, "header");
+    expect(headerSlot).toHaveLength(2);
+    expect(headerSlot[0]).toBe(a);
+    expect(headerSlot[1]).toBe(b);
+  });
+});
+
+// ── Slot decorator ───────────────────────────────────────────────────────────
+
+describe("Slot decorator", () => {
+  it("provides the default slot via field decorator", () => {
+    class MyComp extends StatefulComponent {
+      render() { return null; }
+    }
+
+    const initializers: Array<(this: unknown) => void> = [];
+    const ctx = {
+      name: "default",
+      kind: "field" as const,
+      addInitializer(fn: (this: unknown) => void) { initializers.push(fn); },
+    } as ClassFieldDecoratorContext<StatefulComponent>;
+
+    Slot()(undefined, ctx);
+
+    const instance = new MyComp() as unknown as Record<string, unknown>;
+    initializers.forEach((fn) => { fn.call(instance); });
+
+    // No children initialized — slot should be empty
+    const children = document.createElement("p");
+    initSlots(instance as object, children);
+
+    expect(Array.isArray((instance as Record<string, unknown>).default)).toBe(true);
+  });
+
+  it("uses custom slot name when provided", () => {
+    class MyComp extends StatefulComponent {
+      render() { return null; }
+    }
+
+    const initializers: Array<(this: unknown) => void> = [];
+    const ctx = {
+      name: "content",
+      kind: "field" as const,
+      addInitializer(fn: (this: unknown) => void) { initializers.push(fn); },
+    } as ClassFieldDecoratorContext<StatefulComponent>;
+
+    Slot("header")(undefined, ctx);
+
+    const instance = new MyComp() as unknown as Record<string, unknown>;
+    initializers.forEach((fn) => { fn.call(instance); });
+
+    const el = document.createElement("nav");
+    el.setAttribute("slot", "header");
+    initSlots(instance as object, el);
+
+    const slot = (instance as Record<string, unknown>).content as unknown[];
+    expect(slot).toHaveLength(1);
+    expect(slot[0]).toBe(el);
+  });
+
+  it("skips warn on direct assignment in production mode", () => {
+    class MyComp extends StatefulComponent {
+      render() { return null; }
+    }
+
+    const initializers: Array<(this: unknown) => void> = [];
+    const ctx = {
+      name: "default",
+      kind: "field" as const,
+      addInitializer(fn: (this: unknown) => void) { initializers.push(fn); },
+    } as ClassFieldDecoratorContext<StatefulComponent>;
+
+    Slot()(undefined, ctx);
+
+    const instance = new MyComp() as unknown as Record<string, unknown>;
+    initializers.forEach((fn) => { fn.call(instance); });
+
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    vi.stubEnv("NODE_ENV", "production");
+    (instance as Record<string, unknown>).default = "bad";
+    expect(warn).not.toHaveBeenCalled();
+    vi.unstubAllEnvs();
+    warn.mockRestore();
+  });
+
+  it("warns on direct assignment in non-production", () => {
+    class MyComp extends StatefulComponent {
+      render() { return null; }
+    }
+
+    const initializers: Array<(this: unknown) => void> = [];
+    const ctx = {
+      name: "default",
+      kind: "field" as const,
+      addInitializer(fn: (this: unknown) => void) { initializers.push(fn); },
+    } as ClassFieldDecoratorContext<StatefulComponent>;
+
+    Slot()(undefined, ctx);
+
+    const instance = new MyComp() as unknown as Record<string, unknown>;
+    initializers.forEach((fn) => { fn.call(instance); });
+
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    (instance as Record<string, unknown>).default = "bad";
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining("[Slot]"));
+    warn.mockRestore();
+  });
+});

package/src/__tests__/virtual.test.ts

@@ -0,0 +1,260 @@
+// @vitest-environment jsdom
+import { describe, it, expect, vi } from "vitest";
+
+import { StatefulComponent } from "@praxisjs/core";
+import { Virtual } from "../component/virtual";
+
+type AnyConstructor = new (...args: unknown[]) => StatefulComponent;
+
+function applyVirtual<T extends AnyConstructor>(cls: T, itemHeight: number, buffer?: number): T {
+  return buffer !== undefined
+    ? Virtual(itemHeight, buffer)(cls, {} as ClassDecoratorContext)
+    : Virtual(itemHeight)(cls, {} as ClassDecoratorContext);
+}
+
+// A base component with items and renderItem for virtual scrolling
+class ListComp extends StatefulComponent {
+  items: unknown[] = [];
+  renderItem(item: unknown, _index: number) {
+    const div = document.createElement("div");
+    (div as HTMLElement).textContent = String(item);
+    return div;
+  }
+  render() { return null; }
+}
+
+describe("Virtual decorator", () => {
+  it("warns and returns null when renderItem is not defined", () => {
+    class NoRenderItem extends StatefulComponent {
+      items = ["a", "b"];
+      render() { return null; }
+    }
+
+    const Wrapped = applyVirtual(NoRenderItem as AnyConstructor, 50);
+    const instance = new Wrapped() as unknown as { render: () => unknown };
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const result = instance.render();
+    expect(result).toBeNull();
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining("[Virtual]"));
+    warn.mockRestore();
+  });
+
+  it("renders a container div with the total height", () => {
+    class MyList extends StatefulComponent {
+      items = ["a", "b", "c"];
+      renderItem(item: unknown) {
+        const el = document.createElement("div");
+        el.textContent = String(item);
+        return el;
+      }
+      render() { return null; }
+    }
+
+    const Wrapped = applyVirtual(MyList as AnyConstructor, 50);
+    const instance = new Wrapped();
+
+    const result = instance.render() as HTMLElement;
+    expect(result).toBeInstanceOf(HTMLElement);
+    expect(result.tagName.toLowerCase()).toBe("div");
+    // Total height = 3 items * 50px
+    expect(result.getAttribute("style")).toContain("150px");
+  });
+
+  it("renders visible items within the viewport", () => {
+    class MyList extends StatefulComponent {
+      items = [1, 2, 3, 4, 5];
+      renderItem(item: unknown) {
+        const el = document.createElement("div");
+        el.textContent = String(item);
+        return el;
+      }
+      render() { return null; }
+    }
+
+    const Wrapped = applyVirtual(MyList as AnyConstructor, 100, 0);
+    const instance = new Wrapped();
+
+    const outer = instance.render() as HTMLElement;
+    // Should render some content
+    expect(outer).not.toBeNull();
+    expect(outer.children.length).toBeGreaterThan(0);
+  });
+
+  it("handles empty items list without errors", () => {
+    class EmptyList extends StatefulComponent {
+      items: unknown[] = [];
+      renderItem(_item: unknown) {
+        return document.createElement("div");
+      }
+      render() { return null; }
+    }
+
+    const Wrapped = applyVirtual(EmptyList as AnyConstructor, 50);
+    const instance = new Wrapped();
+    expect(() => instance.render()).not.toThrow();
+  });
+
+  it("onMount sets container styles when _anchor has a parent", () => {
+    const Wrapped = applyVirtual(ListComp as AnyConstructor, 50);
+    const instance = new Wrapped();
+    (instance as unknown as { items: unknown[] }).items = ["a", "b"];
+
+    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?.();
+    expect(container.style.overflowY).toBe("auto");
+    expect(container.style.position).toBe("relative");
+    document.body.removeChild(container);
+  });
+
+  it("onMount does nothing when _anchor has no parent", () => {
+    const Wrapped = applyVirtual(ListComp as AnyConstructor, 50);
+    const instance = new Wrapped();
+
+    const anchor = document.createComment("end");
+    (instance as unknown as { _anchor: Comment })._anchor = anchor;
+
+    expect(() => instance.onMount?.()).not.toThrow();
+  });
+
+  it("onUnmount disconnects scroll listener and cleans up effects", () => {
+    const Wrapped = applyVirtual(ListComp as AnyConstructor, 50);
+    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?.();
+    // Should not throw
+    expect(() => instance.onUnmount?.()).not.toThrow();
+    document.body.removeChild(container);
+  });
+
+  it("re-renders visible items when scrollTop changes (covers while loop cleanup)", () => {
+    class ScrollList 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; }
+    }
+
+    const Wrapped = applyVirtual(ScrollList 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?.();
+    // 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"));
+
+    // 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);
+  });
+
+  it("renderItem returning an array appends all child nodes", () => {
+    class ArrayItemList extends StatefulComponent {
+      items = ["item"];
+      renderItem(item: unknown) {
+        const a = document.createElement("span");
+        a.textContent = String(item) + "-1";
+        const b = document.createElement("span");
+        b.textContent = String(item) + "-2";
+        return [a, b];
+      }
+      render() { return null; }
+    }
+
+    const Wrapped = applyVirtual(ArrayItemList as AnyConstructor, 50, 0);
+    const instance = new Wrapped();
+    const outer = instance.render() as HTMLElement;
+    // outer structure: spacerTop, itemsSlot, spacerBottom
+    const itemsSlot = outer.children[1] as HTMLElement;
+    const wrapper = itemsSlot.children[0] as HTMLElement;
+    expect(wrapper.children.length).toBe(2);
+  });
+
+  it("renderItem returning null produces an empty wrapper div", () => {
+    class NullItemList extends StatefulComponent {
+      items = ["x"];
+      renderItem() { return null; }
+      render() { return null; }
+    }
+
+    const Wrapped = applyVirtual(NullItemList as AnyConstructor, 50, 0);
+    const instance = new Wrapped();
+    expect(() => instance.render()).not.toThrow();
+    const outer = instance.render() as HTMLElement;
+    const itemsSlot = outer.children[1] as HTMLElement;
+    const wrapper = itemsSlot.children[0] as HTMLElement;
+    // rendered is null — no child nodes appended
+    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();
+    // _container is undefined — onUnmount should be a no-op
+    expect(() => instance.onUnmount?.()).not.toThrow();
+  });
+
+  it("updates scrollTop on scroll event", () => {
+    const Wrapped = applyVirtual(ListComp as AnyConstructor, 50);
+    const instance = new Wrapped();
+    (instance as unknown as { items: unknown[] }).items = Array.from({ length: 20 }, (_, i) => i);
+
+    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?.();
+    // 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"));
+
+    // 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);
+  });
+});

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