@praxisjs/decorators 0.4.2 → 0.5.0

package/src/__tests__/lazy.test.ts

@@ -0,0 +1,218 @@
+// @vitest-environment jsdom
+import { beforeEach, afterEach, describe, it, expect, vi } from "vitest";
+
+import { StatefulComponent } from "@praxisjs/core";
+import { Lazy } from "../component/lazy";
+
+type AnyConstructor = new (...args: unknown[]) => StatefulComponent;
+
+function applyLazy<T extends AnyConstructor>(cls: T, placeholder?: number): T {
+  return placeholder !== undefined
+    ? Lazy(placeholder)(cls, {} as ClassDecoratorContext)
+    : Lazy()(cls, {} as ClassDecoratorContext);
+}
+
+class BaseComp extends StatefulComponent {
+  render() {
+    return document.createTextNode("content");
+  }
+}
+
+describe("Lazy decorator", () => {
+  let intersectionCallback: IntersectionObserverCallback = () => {};
+  let mockObserve: ReturnType<typeof vi.fn>;
+  let mockDisconnect: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    intersectionCallback = () => {};
+    mockObserve = vi.fn();
+    mockDisconnect = vi.fn();
+
+    globalThis.IntersectionObserver = class {
+      constructor(cb: IntersectionObserverCallback) {
+        intersectionCallback = cb;
+      }
+      observe = mockObserve;
+      disconnect = mockDisconnect;
+    } as unknown as typeof IntersectionObserver;
+  });
+
+  afterEach(() => {
+    // @ts-expect-error – removing test stub
+    delete globalThis.IntersectionObserver;
+  });
+
+  it("returns null from render before visibility", () => {
+    const Wrapped = applyLazy(BaseComp as AnyConstructor);
+    const instance = new Wrapped();
+    expect(instance.render()).toBeNull();
+  });
+
+  it("sets _lazyVisible to true when IntersectionObserver is not supported", () => {
+    // Remove IntersectionObserver to simulate unsupported environment
+    // @ts-expect-error – removing test stub
+    delete globalThis.IntersectionObserver;
+
+    const Wrapped = applyLazy(BaseComp as AnyConstructor);
+    const instance = new Wrapped();
+
+    // Simulate anchor with parent element
+    const parent = document.createElement("div");
+    document.body.appendChild(parent);
+    const anchor = document.createComment("end");
+    parent.appendChild(anchor);
+    (instance as unknown as { _anchor: Comment })._anchor = anchor;
+
+    instance.onMount?.();
+    // Without IntersectionObserver, component should immediately become visible
+    expect(instance.render()).not.toBeNull();
+    document.body.removeChild(parent);
+  });
+
+  it("sets minHeight placeholder on mount", () => {
+    const Wrapped = applyLazy(BaseComp as AnyConstructor, 300);
+    const instance = new Wrapped();
+
+    const parent = document.createElement("div");
+    document.body.appendChild(parent);
+    const anchor = document.createComment("end");
+    parent.appendChild(anchor);
+    (instance as unknown as { _anchor: Comment })._anchor = anchor;
+
+    instance.onMount?.();
+    expect(parent.style.minHeight).toBe("300px");
+    document.body.removeChild(parent);
+  });
+
+  it("sets _lazyVisible and clears minHeight when intersecting", () => {
+    const Wrapped = applyLazy(BaseComp as AnyConstructor, 200);
+    const instance = new Wrapped();
+
+    const parent = document.createElement("div");
+    document.body.appendChild(parent);
+    const anchor = document.createComment("end");
+    parent.appendChild(anchor);
+    (instance as unknown as { _anchor: Comment })._anchor = anchor;
+
+    instance.onMount?.();
+    expect(instance.render()).toBeNull();
+
+    intersectionCallback(
+      [{ isIntersecting: true } as IntersectionObserverEntry],
+      null as unknown as IntersectionObserver,
+    );
+
+    expect(parent.style.minHeight).toBe("");
+    expect(instance.render()).not.toBeNull(); // component became visible after intersection
+    expect(mockDisconnect).toHaveBeenCalled();
+    document.body.removeChild(parent);
+  });
+
+  it("does nothing when _anchor has no parent", () => {
+    const Wrapped = applyLazy(BaseComp as AnyConstructor);
+    const instance = new Wrapped();
+
+    const anchor = document.createComment("end");
+    (instance as unknown as { _anchor: Comment })._anchor = anchor;
+
+    // Should not throw even though anchor has no parent
+    expect(() => instance.onMount?.()).not.toThrow();
+  });
+
+  it("disconnects observer on unmount", () => {
+    const Wrapped = applyLazy(BaseComp as AnyConstructor);
+    const instance = new Wrapped();
+
+    const parent = document.createElement("div");
+    document.body.appendChild(parent);
+    const anchor = document.createComment("end");
+    parent.appendChild(anchor);
+    (instance as unknown as { _anchor: Comment })._anchor = anchor;
+
+    instance.onMount?.();
+    instance.onUnmount?.();
+    expect(mockDisconnect).toHaveBeenCalled();
+    document.body.removeChild(parent);
+  });
+
+  it("onMount does nothing when _anchor is undefined", () => {
+    const Wrapped = applyLazy(BaseComp as AnyConstructor);
+    const instance = new Wrapped();
+    // _anchor is undefined by default
+    expect(() => instance.onMount?.()).not.toThrow();
+  });
+
+  it("render() returns original content after becoming visible", () => {
+    const Wrapped = applyLazy(BaseComp as AnyConstructor, 200);
+    const instance = new Wrapped();
+
+    const parent = document.createElement("div");
+    document.body.appendChild(parent);
+    const anchor = document.createComment("end");
+    parent.appendChild(anchor);
+    (instance as unknown as { _anchor: Comment })._anchor = anchor;
+
+    instance.onMount?.();
+    expect(instance.render()).toBeNull(); // not yet visible
+
+    intersectionCallback(
+      [{ isIntersecting: true } as IntersectionObserverEntry],
+      null as unknown as IntersectionObserver,
+    );
+
+    // Now visible: render() must delegate to the original render()
+    const result = instance.render();
+    expect(result).not.toBeNull();
+    document.body.removeChild(parent);
+  });
+
+  it("observer stays active and minHeight is preserved when entry is not intersecting", () => {
+    const Wrapped = applyLazy(BaseComp as AnyConstructor, 200);
+    const instance = new Wrapped();
+
+    const parent = document.createElement("div");
+    document.body.appendChild(parent);
+    const anchor = document.createComment("end");
+    parent.appendChild(anchor);
+    (instance as unknown as { _anchor: Comment })._anchor = anchor;
+
+    instance.onMount?.();
+
+    // Fire callback with isIntersecting=false — should be a no-op
+    intersectionCallback(
+      [{ isIntersecting: false } as IntersectionObserverEntry],
+      null as unknown as IntersectionObserver,
+    );
+
+    expect(instance.render()).toBeNull();
+    expect(mockDisconnect).not.toHaveBeenCalled();
+    expect(parent.style.minHeight).toBe("200px");
+    document.body.removeChild(parent);
+  });
+
+  it("does not re-apply minHeight on remount when already visible", () => {
+    const Wrapped = applyLazy(BaseComp as AnyConstructor, 300);
+    const instance = new Wrapped();
+
+    const parent = document.createElement("div");
+    document.body.appendChild(parent);
+    const anchor = document.createComment("end");
+    parent.appendChild(anchor);
+    (instance as unknown as { _anchor: Comment })._anchor = anchor;
+
+    // First mount — become visible
+    instance.onMount?.();
+    intersectionCallback(
+      [{ isIntersecting: true } as IntersectionObserverEntry],
+      null as unknown as IntersectionObserver,
+    );
+    instance.onUnmount?.();
+
+    // Second mount — _lazyVisible is already true
+    instance.onMount?.();
+
+    // minHeight must NOT be re-applied because _lazyVisible() is true
+    expect(parent.style.minHeight).toBe("");
+    document.body.removeChild(parent);
+  });
+});

package/src/__tests__/memo.test.ts

@@ -1,74 +1,141 @@
 import { describe, it, expect, vi } from "vitest";
 
+import { signal } from "@praxisjs/core/internal";
 import { Memo } from "../functions/memo";
 
 function mockCtx(name: string) {
-  return { name, kind: "method" as const } as ClassMethodDecoratorContext;
+  const initializers: Array<(this: object) => void> = [];
+  return {
+    name,
+    kind: "method" as const,
+    addInitializer(fn: (this: object) => void) {
+      initializers.push(fn);
+    },
+    runInitializers(instance: object) {
+      initializers.forEach((fn) => { fn.call(instance); });
+    },
+  } as unknown as ClassMethodDecoratorContext & { runInitializers(instance: object): void };
 }
 
 describe("Memo", () => {
   it("returns the computed value", () => {
     const fn = vi.fn((x: unknown) => (x as number) * 2);
-    const wrapped = Memo()(fn, mockCtx("double"));
+    const ctx = mockCtx("double");
+    Memo()(fn, ctx);
+
     const obj = {};
-    expect(wrapped.call(obj, 5)).toBe(10);
+    ctx.runInitializers(obj);
+    const method = (obj as Record<string, (...a: unknown[]) => unknown>).double;
+
+    expect(method(5)).toBe(10);
   });
 
   it("caches result for same args — calls original only once", () => {
     const fn = vi.fn((x: unknown) => (x as number) + 1);
-    const wrapped = Memo()(fn, mockCtx("inc"));
+    const ctx = mockCtx("inc");
+    Memo()(fn, ctx);
+
     const obj = {};
-    wrapped.call(obj, 3);
-    wrapped.call(obj, 3);
-    wrapped.call(obj, 3);
+    ctx.runInitializers(obj);
+    const method = (obj as Record<string, (...a: unknown[]) => unknown>).inc;
+
+    method(3);
+    method(3);
+    method(3);
     expect(fn).toHaveBeenCalledTimes(1);
   });
 
   it("computes separately for different args", () => {
     const fn = vi.fn((x: unknown) => (x as number) * 10);
-    const wrapped = Memo()(fn, mockCtx("mul"));
+    const ctx = mockCtx("mul");
+    Memo()(fn, ctx);
+
     const obj = {};
-    expect(wrapped.call(obj, 2)).toBe(20);
-    expect(wrapped.call(obj, 3)).toBe(30);
+    ctx.runInitializers(obj);
+    const method = (obj as Record<string, (...a: unknown[]) => unknown>).mul;
+
+    expect(method(2)).toBe(20);
+    expect(method(3)).toBe(30);
     expect(fn).toHaveBeenCalledTimes(2);
   });
 
   it("is per-instance — different instances have separate caches", () => {
     const fn = vi.fn(() => Math.random());
-    const wrapped = Memo()(fn, mockCtx("rand"));
+    const ctx = mockCtx("rand");
+    Memo()(fn, ctx);
+
     const a = {};
     const b = {};
-    const v1 = wrapped.call(a);
-    const v2 = wrapped.call(b);
+    ctx.runInitializers(a);
+    ctx.runInitializers(b);
+
+    const methodA = (a as Record<string, () => unknown>).rand;
+    const methodB = (b as Record<string, () => unknown>).rand;
+    const v1 = methodA();
+    const v2 = methodB();
     expect(fn).toHaveBeenCalledTimes(2);
     expect(v1).not.toBe(v2); // different random values per instance
   });
 
   it("serializes no-args calls with __no_args__ key", () => {
     const fn = vi.fn(() => 42);
-    const wrapped = Memo()(fn, mockCtx("noop"));
+    const ctx = mockCtx("noop");
+    Memo()(fn, ctx);
+
     const obj = {};
-    wrapped.call(obj);
-    wrapped.call(obj);
+    ctx.runInitializers(obj);
+    const method = (obj as Record<string, () => unknown>).noop;
+
+    method();
+    method();
     expect(fn).toHaveBeenCalledTimes(1);
   });
 
   it("serializes object args via JSON.stringify", () => {
     const fn = vi.fn((o: unknown) => JSON.stringify(o));
-    const wrapped = Memo()(fn, mockCtx("obj"));
+    const ctx = mockCtx("obj");
+    Memo()(fn, ctx);
+
     const obj = {};
-    wrapped.call(obj, { a: 1 });
-    wrapped.call(obj, { a: 1 }); // same key
+    ctx.runInitializers(obj);
+    const method = (obj as Record<string, (...a: unknown[]) => unknown>).obj;
+
+    method({ a: 1 });
+    method({ a: 1 }); // same key
     expect(fn).toHaveBeenCalledTimes(1);
   });
 
+  it("re-evaluates when a reactive signal read inside the method changes", () => {
+    const s = signal(1);
+    const fn = vi.fn(() => s() * 10);
+    const ctx = mockCtx("reactive");
+    Memo()(fn, ctx);
+
+    const obj = {};
+    ctx.runInitializers(obj);
+    const method = (obj as Record<string, () => unknown>).reactive;
+
+    expect(method()).toBe(10);
+    expect(fn).toHaveBeenCalledTimes(1);
+
+    s.set(5);
+    // The computed tracks s() — next read triggers recomputation
+    expect(method()).toBe(50);
+    expect(fn).toHaveBeenCalledTimes(2);
+  });
+
   it("serializes symbol args via toString()", () => {
     const fn = vi.fn((s: unknown) => String(s));
-    const wrapped = Memo()(fn, mockCtx("sym"));
+    const ctx = mockCtx("sym");
+    Memo()(fn, ctx);
+
     const obj = {};
+    ctx.runInitializers(obj);
+    const method = (obj as Record<string, (...a: unknown[]) => unknown>).sym;
+
     const sym = Symbol("test");
-    wrapped.call(obj, sym);
-    wrapped.call(obj, sym);
+    method(sym);
+    method(sym);
     expect(fn).toHaveBeenCalledTimes(1);
   });
 });

package/src/__tests__/properties.test.ts

@@ -1,7 +1,7 @@
 import { describe, it, expect, vi } from "vitest";
 
 import { StatefulComponent } from "@praxisjs/core";
-import { signal } from "@praxisjs/core/internal";
+import { signal, computed } from "@praxisjs/core/internal";
 
 import { Watch } from "../functions/watch";
 import { When } from "../functions/when";
@@ -76,6 +76,36 @@ describe("State decorator", () => {
     (instance as unknown as Record<string, unknown>).value = "world";
     expect(instance._stateDirty).toBe(true);
   });
+
+  it("accepts null as initial value", () => {
+    const { ctx, run } = fieldCtx("nullable");
+    State()(undefined, ctx);
+
+    const instance = new TestComponent();
+    (instance as unknown as Record<string, unknown>).nullable = null;
+    run(instance);
+
+    expect((instance as unknown as Record<string, unknown>).nullable).toBeNull();
+    (instance as unknown as Record<string, unknown>).nullable = "set";
+    expect((instance as unknown as Record<string, unknown>).nullable).toBe("set");
+  });
+
+  it("multiple State fields on same class are independent", () => {
+    const { ctx: ctxA, run: runA } = fieldCtx("a");
+    const { ctx: ctxB, run: runB } = fieldCtx("b");
+    State()(undefined, ctxA);
+    State()(undefined, ctxB);
+
+    const instance = new TestComponent();
+    (instance as unknown as Record<string, unknown>).a = 1;
+    (instance as unknown as Record<string, unknown>).b = 2;
+    runA(instance);
+    runB(instance);
+
+    (instance as unknown as Record<string, unknown>).a = 10;
+    expect((instance as unknown as Record<string, unknown>).a).toBe(10);
+    expect((instance as unknown as Record<string, unknown>).b).toBe(2);
+  });
 });
 
 // ── Prop ──────────────────────────────────────────────────────────────────────
@@ -474,4 +504,222 @@ describe("When decorator", () => {
     expect(mountSpy).toHaveBeenCalled();
     expect(unmountSpy).toHaveBeenCalled();
   });
+
+  it("works when the watched prop is a computed value", () => {
+    const { ctx, run } = methodCtxFor("onComputed");
+    const handler = vi.fn();
+    When("doubled")(handler, ctx as unknown as ClassMethodDecoratorContext);
+
+    const s = signal(0);
+    const c = computed(() => s() * 2);
+    const instance = new TestComponent();
+    // Store the computed itself (not the result) so When can call isComputed on it
+    (instance as unknown as Record<string, unknown>).doubled = c;
+    run(instance);
+
+    (instance as unknown as { onMount: () => void }).onMount?.();
+
+    s.set(5); // doubled becomes 10 (truthy)
+    expect(handler).toHaveBeenCalledTimes(1);
+  });
+});
+
+// ── Prop (additional branches) ────────────────────────────────────────────────
+
+describe("Prop decorator — additional branches", () => {
+  it("set() updates the default value (used when no _rawProps entry)", () => {
+    const { ctx, run } = fieldCtx("size");
+    Prop()(undefined, ctx);
+
+    const instance = new TestComponent();
+    (instance as unknown as Record<string, unknown>).size = "sm";
+    run(instance);
+
+    // Setter path: updates _defaults
+    (instance as unknown as Record<string, unknown>).size = "lg";
+    expect((instance as unknown as Record<string, unknown>).size).toBe("lg");
+  });
+});
+
+// ── History (additional branches) ────────────────────────────────────────────
+
+describe("History decorator — undo with no previous value", () => {
+  it("undo() does nothing when there is no previous value", () => {
+    const { ctx, run } = fieldCtx("pts");
+    History()(undefined, ctx);
+
+    const s = signal(0);
+    const instance = new TestComponent();
+    Object.defineProperty(instance, "pts", {
+      get: () => s(),
+      set: (v: number) => { s.set(v); },
+      configurable: true,
+    });
+    run(instance);
+
+    const h = (instance as unknown as Record<string, unknown>).ptsHistory as {
+      undo: () => void;
+      canUndo: () => boolean;
+    };
+
+    // No changes yet — undo should be a no-op
+    expect(h.canUndo()).toBe(false);
+    expect(() => h.undo()).not.toThrow();
+    expect(s()).toBe(0);
+  });
+});
+
+// ── History decorator — multiple fields ───────────────────────────────────────
+
+describe("History decorator — multiple History properties on same instance", () => {
+  it("two History fields are independent", () => {
+    const { ctx: ctxX, run: runX } = fieldCtx("x");
+    const { ctx: ctxY, run: runY } = fieldCtx("y");
+    History()(undefined, ctxX);
+    History()(undefined, ctxY);
+
+    const sx = signal(0);
+    const sy = signal(0);
+    const instance = new TestComponent();
+    Object.defineProperty(instance, "x", {
+      get: () => sx(), set: (v: number) => { sx.set(v); }, configurable: true,
+    });
+    Object.defineProperty(instance, "y", {
+      get: () => sy(), set: (v: number) => { sy.set(v); }, configurable: true,
+    });
+    runX(instance);
+    runY(instance);
+
+    // Access history first to trigger lazy creation and subscribe to signals
+    const hx = (instance as unknown as Record<string, unknown>).xHistory as {
+      canUndo: () => boolean; current: () => number;
+    };
+    const hy = (instance as unknown as Record<string, unknown>).yHistory as {
+      canUndo: () => boolean; current: () => number;
+    };
+
+    sx.set(5);
+    sy.set(10);
+
+    expect(hx.canUndo()).toBe(true);
+    expect(hy.canUndo()).toBe(true);
+    expect(hx.current()).toBe(5);
+    expect(hy.current()).toBe(10);
+  });
+
+  it("clear() after undo removes redo entries", () => {
+    const { ctx, run } = fieldCtx("val");
+    History()(undefined, ctx);
+
+    const s = signal(0);
+    const instance = new TestComponent();
+    Object.defineProperty(instance, "val", {
+      get: () => s(), set: (v: number) => { s.set(v); }, configurable: true,
+    });
+    run(instance);
+
+    const h = (instance as unknown as Record<string, unknown>).valHistory as {
+      undo: () => void; clear: () => void;
+      canUndo: () => boolean; canRedo: () => boolean;
+    };
+
+    s.set(1);
+    s.set(2);
+    h.undo();
+    expect(h.canRedo()).toBe(true);
+    h.clear();
+    expect(h.canRedo()).toBe(false);
+    expect(h.canUndo()).toBe(false);
+  });
+});
+
+// ── Watch (cleanup + multi-prop non-watched) ──────────────────────────────────
+
+describe("Watch decorator — onUnmount cleanup", () => {
+  it("stops firing after onUnmount is called", () => {
+    const { ctx, run } = methodCtx("onCount");
+    const handler = vi.fn();
+    Watch("count" as never)(handler, ctx as unknown as ClassMethodDecoratorContext);
+
+    const s = signal(0);
+    const instance = new TestComponent();
+    Object.defineProperty(instance, "count", { get: () => s(), configurable: true });
+    run(instance);
+    (instance as unknown as { onMount: () => void }).onMount?.();
+
+    s.set(1);
+    expect(handler).toHaveBeenCalledTimes(1);
+
+    (instance as unknown as { onUnmount: () => void }).onUnmount?.();
+    s.set(2);
+
+    // After unmount the effect is stopped — handler must NOT fire again
+    expect(handler).toHaveBeenCalledTimes(1);
+  });
+
+  it("preserves existing onUnmount when adding cleanup", () => {
+    const { ctx, run } = methodCtx("onVal");
+    const handler = vi.fn();
+    Watch("val" as never)(handler, ctx as unknown as ClassMethodDecoratorContext);
+
+    const s = signal(0);
+    const instance = new TestComponent();
+    Object.defineProperty(instance, "val", { get: () => s(), configurable: true });
+    run(instance);
+
+    const unmountSpy = vi.fn();
+    const prevUnmount = instance.onUnmount?.bind(instance);
+    instance.onUnmount = function () { unmountSpy(); prevUnmount?.(); };
+
+    (instance as unknown as { onMount: () => void }).onMount?.();
+    instance.onUnmount?.();
+    expect(unmountSpy).toHaveBeenCalled();
+  });
+
+  it("multi-prop watch does NOT fire when an unwatched prop changes", () => {
+    const { ctx, run } = methodCtx("onAB");
+    const handler = vi.fn();
+    Watch("a" as never, "b" as never)(handler, ctx as unknown as ClassMethodDecoratorContext);
+
+    const sa = signal(0);
+    const sb = signal(0);
+    const sc = signal(0); // not watched
+
+    const instance = new TestComponent();
+    Object.defineProperty(instance, "a", { get: () => sa(), configurable: true });
+    Object.defineProperty(instance, "b", { get: () => sb(), configurable: true });
+    Object.defineProperty(instance, "c", { get: () => sc(), configurable: true });
+    run(instance);
+    (instance as unknown as { onMount: () => void }).onMount?.();
+
+    sc.set(99); // unwatched prop — handler must NOT fire
+    expect(handler).not.toHaveBeenCalled();
+
+    sa.set(1); // watched — handler fires
+    expect(handler).toHaveBeenCalledTimes(1);
+  });
+});
+
+// ── Watch (additional branches — computed readValue) ──────────────────────────
+
+describe("Watch decorator — reading computed values", () => {
+  it("reads the value of a computed field (not the computed object)", () => {
+    const { ctx, run } = methodCtx("onDoubled");
+    const handler = vi.fn();
+    Watch("doubled" as never)(handler, ctx as unknown as ClassMethodDecoratorContext);
+
+    const s = signal(1);
+    const c = computed(() => s() * 2);
+    const instance = new TestComponent();
+    // Watch reads instance["doubled"] — if it's a computed, it calls it
+    Object.defineProperty(instance, "doubled", {
+      get: () => c,
+      configurable: true,
+    });
+    run(instance);
+    (instance as unknown as { onMount: () => void }).onMount?.();
+
+    s.set(5); // c() goes from 2 to 10 → triggers handler
+    expect(handler).toHaveBeenCalledTimes(1);
+  });
 });