@praxisjs/decorators 0.8.0 → 1.0.0

package/src/__tests__/properties.test.ts

@@ -967,7 +967,7 @@ describe("@Compose decorator — new cases", () => {
     }).toThrow("setup failed");
   });
 
-  it("string argument resolution where the instance property is undefined", () => {
+  it("string argument that matches no instance property falls back to the literal string", () => {
     class ArgComposable {
       constructor(private val: unknown) {}
       setup() { return { resolved: this.val }; }
@@ -978,11 +978,79 @@ describe("@Compose decorator — new cases", () => {
     Compose(ArgComposable as any, "missingProp")(undefined, ctx);
 
     const instance = new TestComponent();
-    // missingProp is not set on instance — resolves to undefined
+    // missingProp is not set on instance — falls back to the literal "missingProp"
     run(instance);
 
     const view = (instance as unknown as Record<string, unknown>).strArgUndef as Record<string, unknown>;
-    expect(view.resolved).toBeUndefined();
+    expect(view.resolved).toBe("missingProp");
+  });
+
+  it("string argument that matches an instance property resolves to its value", () => {
+    class ArgComposable {
+      constructor(private val: unknown) {}
+      setup() { return { resolved: this.val }; }
+    }
+
+    const { ctx, run } = fieldCtx("strArgFound");
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    Compose(ArgComposable as any, "myProp")(undefined, ctx);
+
+    const instance = new TestComponent();
+    (instance as unknown as Record<string, unknown>).myProp = 42;
+    run(instance);
+
+    const view = (instance as unknown as Record<string, unknown>).strArgFound as Record<string, unknown>;
+    expect(view.resolved).toBe(42);
+  });
+});
+
+// ── getter() helper ───────────────────────────────────────────────────────────
+
+import { getter } from "../properties/compose";
+
+describe("getter() factory", () => {
+  it("resolves to a function that reads the named property from the instance", () => {
+    class ArgComposable {
+      constructor(private getVal: () => unknown) {}
+      setup() { return { current: this.getVal() }; }
+    }
+
+    const { ctx, run } = fieldCtx("withGetter");
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    Compose(ArgComposable as any, getter("dynProp"))(undefined, ctx);
+
+    const instance = new TestComponent();
+    (instance as unknown as Record<string, unknown>).dynProp = 99;
+    run(instance);
+
+    const view = (instance as unknown as Record<string, unknown>).withGetter as Record<string, unknown>;
+    expect(view.current).toBe(99);
+  });
+
+  it("getter() produces a live reader — reads the property at call time", () => {
+    class ArgComposable {
+      constructor(private getVal: () => unknown) {}
+      setup() { return { read: this.getVal }; }
+    }
+
+    const { ctx, run } = fieldCtx("liveGetter");
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    Compose(ArgComposable as any, getter("mutableProp"))(undefined, ctx);
+
+    const instance = new TestComponent();
+    (instance as unknown as Record<string, unknown>).mutableProp = "first";
+    run(instance);
+
+    const view = (instance as unknown as Record<string, unknown>).liveGetter as Record<string, () => unknown>;
+    expect(view.read()).toBe("first");
+
+    (instance as unknown as Record<string, unknown>).mutableProp = "second";
+    expect(view.read()).toBe("second");
+  });
+
+  it("getter() is marked as a ComposeFactory (has __isComposeFactory)", () => {
+    const g = getter("foo");
+    expect((g as unknown as Record<string, unknown>).__isComposeFactory).toBe(true);
   });
 });
 

package/src/component/index.ts

@@ -1,3 +1,2 @@
 export { Component } from "./component";
 export { Lazy } from "./lazy";
-export { Virtual } from "./virtual";

package/src/component/lazy.ts

@@ -2,13 +2,26 @@ import { type RootComponent, signal } from "@praxisjs/core/internal";
 
 import { ClassBehavior, createClassDecorator, type ClassEnhancement } from "../create-class-decorator";
 
+export interface LazyOptions {
+  /** Placeholder height in pixels while the component is off-screen. */
+  placeholder?: number;
+  /**
+   * Scroll container to observe against. Defaults to the viewport (`null`).
+   * Pass a ref object `{ current: HTMLElement | null }` to scope intersection
+   * to a specific scrollable container.
+   */
+  root?: { current: HTMLElement | null } | null;
+  /** Extra margin around the root before triggering (e.g. `"200px"`). Defaults to `"100px"`. */
+  rootMargin?: string;
+}
+
 class LazyBehavior extends ClassBehavior {
-  constructor(private readonly placeholder: number) {
+  constructor(private readonly options: LazyOptions) {
     super();
   }
 
   create(instance: RootComponent): ClassEnhancement {
-    const placeholder = this.placeholder;
+    const { placeholder = 200, root, rootMargin = "100px" } = this.options;
     const visible = signal(false);
     let observer: IntersectionObserver | undefined;
 
@@ -25,6 +38,9 @@ class LazyBehavior extends ClassBehavior {
 
         if (!visible()) el.style.minHeight = `${String(placeholder)}px`;
 
+        const rootEl =
+          root === undefined || root === null ? null : root.current ?? null;
+
         observer = new IntersectionObserver(
           (entries) => {
             if (entries[0]?.isIntersecting) {
@@ -33,7 +49,7 @@ class LazyBehavior extends ClassBehavior {
               observer?.disconnect();
             }
           },
-          { rootMargin: "100px" },
+          { root: rootEl, rootMargin },
         );
 
         observer.observe(el);
@@ -44,13 +60,19 @@ class LazyBehavior extends ClassBehavior {
       },
 
       render(originalRender) {
-        if (!visible()) return null;
-        return originalRender();
+        return (() => {
+          if (!visible()) return null;
+          return originalRender();
+        }) as unknown as Node;
       },
     };
   }
 }
 
-export function Lazy(placeholder = 200) {
-  return createClassDecorator(new LazyBehavior(placeholder));
+export function Lazy(placeholderOrOptions: number | LazyOptions = 200) {
+  const options: LazyOptions =
+    typeof placeholderOrOptions === "number"
+      ? { placeholder: placeholderOrOptions }
+      : placeholderOrOptions;
+  return createClassDecorator(new LazyBehavior(options));
 }

package/src/create-class-decorator.ts

@@ -19,6 +19,12 @@ export abstract class ClassBehavior {
   initialize?(_Enhanced: new (...args: any[]) => unknown, _original: new (...args: any[]) => unknown): void;
 }
 
+// Tracks instances whose render is currently being called as `originalRender`
+// from within an enhancement. When set, the Enhanced render skips the
+// this._enh.render dispatch so stacked decorators (e.g. @Lazy + @Component)
+// don't re-enter the outermost enhancement recursively.
+const _originalRenderInProgress = new WeakSet();
+
 export function createClassDecorator(behavior: ClassBehavior) {
   return function <
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -40,12 +46,18 @@ export function createClassDecorator(behavior: ClassBehavior) {
       }
 
       render(...args: unknown[]): Node | Node[] | null {
-        const originalRender = () =>
-          (constructor.prototype as { render: (...a: unknown[]) => Node | Node[] | null }).render.apply(this, args);
-        if (this._enh.render) {
+        const originalRender = () => {
+          _originalRenderInProgress.add(this);
+          try {
+            return (constructor.prototype as { render: (...a: unknown[]) => Node | Node[] | null }).render.apply(this, args);
+          } finally {
+            _originalRenderInProgress.delete(this);
+          }
+        };
+        if (this._enh.render && !_originalRenderInProgress.has(this)) {
           return this._enh.render(originalRender);
         }
-        return originalRender();
+        return (constructor.prototype as { render: (...a: unknown[]) => Node | Node[] | null }).render.apply(this, args);
       }
     };
 

package/src/create-field-decorator.ts

@@ -18,12 +18,12 @@ export interface FieldBehavior<T = object> {
 }
 
 export function createFieldDecorator<T = StatefulComponent>(behavior: FieldBehavior<T>) {
-  return function (
+  return function <This extends T, Value = unknown>(
     _value: undefined,
-    context: ClassFieldDecoratorContext<T>,
+    context: ClassFieldDecoratorContext<This, Value>,
   ): void {
     context.addInitializer(function (this: unknown) {
-      const instance = this as T & StatefulComponent & Record<string, unknown>;
+      const instance = this as This & StatefulComponent & Record<string, unknown>;
       const name = context.name as string;
       const initialValue = instance[name];
 

package/src/index.ts

@@ -1,4 +1,4 @@
-export { Component, Lazy, Virtual } from "./component";
+export { Component, Lazy } from "./component";
 export {
   Memo,
   Bind,
@@ -23,6 +23,7 @@ export {
   History,
   type HistoryOf,
   Compose,
+  getter,
   Resource,
   type ResourceInstance,
   type ResourceOptions,
@@ -35,6 +36,7 @@ export {
   type FieldBehavior,
   type FieldBinding,
 } from "./create-field-decorator";
+export { type ReactiveHost } from "./reactive-host";
 export {
   createClassDecorator,
   ClassBehavior,

package/src/properties/compose.ts

@@ -2,9 +2,21 @@ import type { StatefulComponent, Composable } from "@praxisjs/core";
 
 import { createFieldDecorator } from "../create-field-decorator";
 
-function isReactive(
-  value: unknown,
-): value is () => unknown {
+interface ComposeFactory { __isComposeFactory: true; resolve: (instance: object) => unknown }
+
+/** Wraps a property as a live getter — passes `() => instance[propName]` to the composable. */
+export function getter(propName: string): ComposeFactory {
+  return {
+    __isComposeFactory: true,
+    resolve: (instance) => () => (instance as Record<string, unknown>)[propName],
+  };
+}
+
+function isFactory(value: unknown): value is ComposeFactory {
+  return typeof value === "object" && value !== null && "__isComposeFactory" in value;
+}
+
+function isReactive(value: unknown): value is () => unknown {
   return (
     typeof value === "function" &&
     ("__isSignal" in (value as object) || "__isComputed" in (value as object))
@@ -34,11 +46,12 @@ export function Compose(
 ) {
   return createFieldDecorator({
     bind(instance: StatefulComponent, _name: string, _initialValue: unknown) {
-      const resolvedArgs = ctorArgs.map((arg) =>
-        typeof arg === "string"
-          ? (instance as unknown as Record<string, unknown>)[arg]
-          : arg,
-      );
+      const resolvedArgs = ctorArgs.map((arg) => {
+        if (isFactory(arg)) return arg.resolve(instance);
+        if (typeof arg !== "string") return arg;
+        const prop = (instance as unknown as Record<string, unknown>)[arg];
+        return prop !== undefined ? prop : arg;
+      });
 
       const composable = new ComposableClass(...resolvedArgs);
       const view = buildView(composable.setup());

package/src/properties/deep-state.ts

@@ -2,6 +2,8 @@ import { signal } from "@praxisjs/core/internal";
 
 import { createFieldDecorator } from "../create-field-decorator";
 
+import type { ReactiveHost } from "../reactive-host";
+
 function deepProxy<T extends object>(target: T, notify: () => void): T {
   return new Proxy(target, {
     get(obj, key, receiver) {
@@ -25,7 +27,7 @@ function deepProxy<T extends object>(target: T, notify: () => void): T {
 }
 
 export function DeepState() {
-  return createFieldDecorator({
+  return createFieldDecorator<ReactiveHost>({
     bind(instance, _name, initialValue) {
       const version = signal(0);
       let current = initialValue;

package/src/properties/index.ts

@@ -4,7 +4,7 @@ export { Computed } from "./computed";
 export { Persisted } from "./persisted";
 export { Slot, initSlots } from "./slot";
 export { History, type HistoryOf } from "./history";
-export { Compose } from "./compose";
+export { Compose, getter } from "./compose";
 export { Resource, type ResourceInstance, type ResourceOptions } from "./resource";
 export { Synced } from "./synced";
 export { DeepState } from "./deep-state";

package/src/properties/state.ts

@@ -2,8 +2,10 @@ import { signal } from "@praxisjs/core/internal";
 
 import { createFieldDecorator } from "../create-field-decorator";
 
+import type { ReactiveHost } from "../reactive-host";
+
 export function State() {
-  return createFieldDecorator({
+  return createFieldDecorator<ReactiveHost>({
     bind(instance, _name, initialValue) {
       const sig = signal(initialValue);
       return {

package/src/reactive-host.ts

@@ -0,0 +1,3 @@
+export interface ReactiveHost {
+  _stateDirty: boolean;
+}

package/dist/__tests__/virtual.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=virtual.test.d.ts.map

package/dist/__tests__/virtual.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"virtual.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/virtual.test.ts"],"names":[],"mappings":""}