@praxisjs/decorators 1.4.1 → 1.5.1

package/src/__tests__/events.test.ts

@@ -1,6 +1,7 @@
 import { describe, it, expect, vi } from "vitest";
 
 import { StatefulComponent } from "@praxisjs/core";
+import { setComponentDefault } from "@praxisjs/core/internal";
 
 import { createCommand } from "../events/command";
 import { Emit } from "../events/emit";
@@ -65,14 +66,14 @@ describe("createCommand", () => {
 // ── readProp ──────────────────────────────────────────────────────────────────
 
 describe("readProp", () => {
-  it("returns value from _rawProps when defined", () => {
+  it("returns value from raw props when defined", () => {
     const instance = new TestComponent({ myProp: "fromParent" });
     expect(readProp(instance, "myProp")).toBe("fromParent");
   });
 
-  it("falls back to _defaults when _rawProps does not define the prop", () => {
+  it("falls back to defaults when raw props do not define the prop", () => {
     const instance = new TestComponent();
-    instance._defaults.myProp = "default";
+    setComponentDefault(instance, "myProp", "default");
     expect(readProp(instance, "myProp")).toBe("default");
   });
 

package/src/__tests__/lazy.test.ts

@@ -2,6 +2,7 @@
 import { beforeEach, afterEach, describe, it, expect, vi } from "vitest";
 
 import { StatefulComponent } from "@praxisjs/core";
+import { setComponentAnchor } from "@praxisjs/core/internal";
 import { Lazy } from "../component/lazy";
 import type { LazyOptions } from "../component/lazy";
 
@@ -55,7 +56,7 @@ describe("Lazy decorator", () => {
     expect(resolveRender(instance)).toBeNull();
   });
 
-  it("sets _lazyVisible to true when IntersectionObserver is not supported", () => {
+  it("sets lazy visibility to true when IntersectionObserver is not supported", () => {
     // Remove IntersectionObserver to simulate unsupported environment
     // @ts-expect-error – removing test stub
     delete globalThis.IntersectionObserver;
@@ -68,7 +69,7 @@ describe("Lazy decorator", () => {
     document.body.appendChild(parent);
     const anchor = document.createComment("end");
     parent.appendChild(anchor);
-    (instance as unknown as { _anchor: Comment })._anchor = anchor;
+    setComponentAnchor(instance, anchor);
 
     instance.onMount?.();
     // Without IntersectionObserver, component should immediately become visible
@@ -84,7 +85,7 @@ describe("Lazy decorator", () => {
     document.body.appendChild(parent);
     const anchor = document.createComment("end");
     parent.appendChild(anchor);
-    (instance as unknown as { _anchor: Comment })._anchor = anchor;
+    setComponentAnchor(instance, anchor);
 
     instance.onMount?.();
     expect(parent.style.minHeight).toBe("300px");
@@ -99,7 +100,7 @@ describe("Lazy decorator", () => {
     document.body.appendChild(parent);
     const anchor = document.createComment("end");
     parent.appendChild(anchor);
-    (instance as unknown as { _anchor: Comment })._anchor = anchor;
+    setComponentAnchor(instance, anchor);
 
     instance.onMount?.();
     expect(resolveRender(instance)).toBeNull();
@@ -115,12 +116,12 @@ describe("Lazy decorator", () => {
     document.body.removeChild(parent);
   });
 
-  it("does nothing when _anchor has no parent", () => {
+  it("does nothing when the 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;
+    setComponentAnchor(instance, anchor);
 
     // Should not throw even though anchor has no parent
     expect(() => instance.onMount?.()).not.toThrow();
@@ -134,7 +135,7 @@ describe("Lazy decorator", () => {
     document.body.appendChild(parent);
     const anchor = document.createComment("end");
     parent.appendChild(anchor);
-    (instance as unknown as { _anchor: Comment })._anchor = anchor;
+    setComponentAnchor(instance, anchor);
 
     instance.onMount?.();
     instance.onUnmount?.();
@@ -142,10 +143,9 @@ describe("Lazy decorator", () => {
     document.body.removeChild(parent);
   });
 
-  it("onMount does nothing when _anchor is undefined", () => {
+  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();
   });
 
@@ -157,7 +157,7 @@ describe("Lazy decorator", () => {
     document.body.appendChild(parent);
     const anchor = document.createComment("end");
     parent.appendChild(anchor);
-    (instance as unknown as { _anchor: Comment })._anchor = anchor;
+    setComponentAnchor(instance, anchor);
 
     instance.onMount?.();
     expect(resolveRender(instance)).toBeNull(); // not yet visible
@@ -181,7 +181,7 @@ describe("Lazy decorator", () => {
     document.body.appendChild(parent);
     const anchor = document.createComment("end");
     parent.appendChild(anchor);
-    (instance as unknown as { _anchor: Comment })._anchor = anchor;
+    setComponentAnchor(instance, anchor);
 
     instance.onMount?.();
 
@@ -205,7 +205,7 @@ describe("Lazy decorator", () => {
     document.body.appendChild(parent);
     const anchor = document.createComment("end");
     parent.appendChild(anchor);
-    (instance as unknown as { _anchor: Comment })._anchor = anchor;
+    setComponentAnchor(instance, anchor);
 
     instance.onMount?.();
     expect(parent.style.minHeight).toBe("150px");
@@ -233,7 +233,7 @@ describe("Lazy decorator", () => {
     document.body.appendChild(parent);
     const anchor = document.createComment("end");
     parent.appendChild(anchor);
-    (instance as unknown as { _anchor: Comment })._anchor = anchor;
+    setComponentAnchor(instance, anchor);
 
     instance.onMount?.();
     expect(capturedInit?.root).toBe(rootEl);
@@ -260,7 +260,7 @@ describe("Lazy decorator", () => {
     document.body.appendChild(parent);
     const anchor = document.createComment("end");
     parent.appendChild(anchor);
-    (instance as unknown as { _anchor: Comment })._anchor = anchor;
+    setComponentAnchor(instance, anchor);
 
     instance.onMount?.();
     expect(capturedInit?.root).toBeNull();
@@ -276,7 +276,7 @@ describe("Lazy decorator", () => {
     document.body.appendChild(parent);
     const anchor = document.createComment("end");
     parent.appendChild(anchor);
-    (instance as unknown as { _anchor: Comment })._anchor = anchor;
+    setComponentAnchor(instance, anchor);
 
     // First mount — become visible
     instance.onMount?.();
@@ -286,10 +286,10 @@ describe("Lazy decorator", () => {
     );
     instance.onUnmount?.();
 
-    // Second mount — _lazyVisible is already true
+    // Second mount — lazy visibility is already true
     instance.onMount?.();
 
-    // minHeight must NOT be re-applied because _lazyVisible() is true
+    // minHeight must NOT be re-applied because lazy visibility is true
     expect(parent.style.minHeight).toBe("");
     document.body.removeChild(parent);
   });

package/src/__tests__/properties.test.ts

@@ -1,7 +1,12 @@
 import { describe, it, expect, vi } from "vitest";
 
 import { StatefulComponent } from "@praxisjs/core";
-import { signal, computed } from "@praxisjs/core/internal";
+import {
+  computed,
+  isStateDirty,
+  setStateDirty,
+  signal,
+} from "@praxisjs/core/internal";
 
 import { createFieldDecorator } from "../create-field-decorator";
 import { createGetterDecorator } from "../create-getter-decorator";
@@ -11,6 +16,7 @@ import { When } from "../functions/when";
 import { Compose } from "../properties/compose";
 import { Computed } from "../properties/computed";
 import { History } from "../properties/history";
+import { FunctionProp } from "../properties/function-prop";
 import { Prop } from "../properties/prop";
 import { State } from "../properties/state";
 
@@ -68,7 +74,7 @@ describe("State decorator", () => {
     expect((instance as unknown as Record<string, unknown>).count).toBe(20);
   });
 
-  it("sets _stateDirty on write", () => {
+  it("sets state dirty on write", () => {
     const { ctx, run } = fieldCtx("value");
     State()(undefined, ctx);
 
@@ -76,9 +82,9 @@ describe("State decorator", () => {
     (instance as unknown as Record<string, unknown>).value = "hello";
     run(instance);
 
-    instance._stateDirty = false;
+    setStateDirty(instance, false);
     (instance as unknown as Record<string, unknown>).value = "world";
-    expect(instance._stateDirty).toBe(true);
+    expect(isStateDirty(instance)).toBe(true);
   });
 
   it("accepts null as initial value", () => {
@@ -115,7 +121,7 @@ describe("State decorator", () => {
 // ── Prop ──────────────────────────────────────────────────────────────────────
 
 describe("Prop decorator", () => {
-  it("reads from _rawProps when set by parent", () => {
+  it("reads from raw props when set by parent", () => {
     const { ctx, run } = fieldCtx("label");
     Prop()(undefined, ctx);
 
@@ -125,7 +131,7 @@ describe("Prop decorator", () => {
     expect((instance as unknown as Record<string, unknown>).label).toBe("hello");
   });
 
-  it("falls back to default value when not in _rawProps", () => {
+  it("falls back to default value when not in raw props", () => {
     const { ctx, run } = fieldCtx("size");
     Prop()(undefined, ctx);
 
@@ -150,6 +156,81 @@ describe("Prop decorator", () => {
   });
 });
 
+// ── FunctionProp ──────────────────────────────────────────────────────────────
+
+describe("FunctionProp decorator", () => {
+  it("reads function values from raw props without invoking them", () => {
+    const { ctx, run } = fieldCtx("filter");
+    FunctionProp()(undefined, ctx);
+
+    const filter = vi.fn((value: number) => value > 1);
+    const instance = new TestComponent({ filter });
+    run(instance);
+
+    const received = (instance as unknown as Record<string, unknown>).filter;
+    expect(received).toBe(filter);
+    expect(filter).not.toHaveBeenCalled();
+    expect((received as (value: number) => boolean)(2)).toBe(true);
+    expect(filter).toHaveBeenCalledWith(2);
+  });
+
+  it("falls back to the default function when not in raw props", () => {
+    const { ctx, run } = fieldCtx("filter");
+    FunctionProp()(undefined, ctx);
+
+    const defaultFilter = vi.fn((value: number) => value % 2 === 0);
+    const instance = new TestComponent();
+    (instance as unknown as Record<string, unknown>).filter = defaultFilter;
+    run(instance);
+
+    const received = (instance as unknown as Record<string, unknown>).filter;
+    expect(received).toBe(defaultFilter);
+    expect((received as (value: number) => boolean)(4)).toBe(true);
+    expect(defaultFilter).toHaveBeenCalledWith(4);
+  });
+
+  it("set() updates the default function used without a raw prop", () => {
+    const { ctx, run } = fieldCtx("filter");
+    FunctionProp()(undefined, ctx);
+
+    const instance = new TestComponent();
+    run(instance);
+
+    const nextFilter = (value: number) => value < 10;
+    (instance as unknown as Record<string, unknown>).filter = nextFilter;
+
+    expect((instance as unknown as Record<string, unknown>).filter).toBe(nextFilter);
+  });
+
+  it("warns on a non-function raw prop in non-production", () => {
+    const { ctx, run } = fieldCtx("filter");
+    FunctionProp()(undefined, ctx);
+
+    const instance = new TestComponent({ filter: "not-a-function" });
+    run(instance);
+
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    expect((instance as unknown as Record<string, unknown>).filter).toBe("not-a-function");
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining("[FunctionProp]"));
+    warn.mockRestore();
+  });
+
+  it("does not warn in production", () => {
+    const { ctx, run } = fieldCtx("filter");
+    FunctionProp()(undefined, ctx);
+
+    const instance = new TestComponent({ filter: "not-a-function" });
+    run(instance);
+
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    vi.stubEnv("NODE_ENV", "production");
+    expect((instance as unknown as Record<string, unknown>).filter).toBe("not-a-function");
+    expect(warn).not.toHaveBeenCalled();
+    vi.unstubAllEnvs();
+    warn.mockRestore();
+  });
+});
+
 // ── Computed ──────────────────────────────────────────────────────────────────
 
 describe("Computed decorator", () => {
@@ -832,7 +913,7 @@ describe("When decorator", () => {
 // ── Prop (additional branches) ────────────────────────────────────────────────
 
 describe("Prop decorator — additional branches", () => {
-  it("set() updates the default value (used when no _rawProps entry)", () => {
+  it("set() updates the default value (used when no raw props entry)", () => {
     const { ctx, run } = fieldCtx("size");
     Prop()(undefined, ctx);
 
@@ -840,7 +921,7 @@ describe("Prop decorator — additional branches", () => {
     (instance as unknown as Record<string, unknown>).size = "sm";
     run(instance);
 
-    // Setter path: updates _defaults
+    // Setter path: updates defaults.
     (instance as unknown as Record<string, unknown>).size = "lg";
     expect((instance as unknown as Record<string, unknown>).size).toBe("lg");
   });

package/src/component/lazy.ts

@@ -1,4 +1,8 @@
-import { type RootComponent, signal } from "@praxisjs/core/internal";
+import {
+  getComponentAnchor,
+  type RootComponent,
+  signal,
+} from "@praxisjs/core/internal";
 
 import { ClassBehavior, createClassDecorator, type ClassEnhancement } from "../create-class-decorator";
 
@@ -27,8 +31,7 @@ class LazyBehavior extends ClassBehavior {
 
     return {
       onMount() {
-        const el =
-          (instance as { _anchor?: Comment })._anchor?.parentElement ?? null;
+        const el = getComponentAnchor(instance)?.parentElement ?? null;
         if (!el) return;
 
         if (!("IntersectionObserver" in window)) {

package/src/events/helper.ts

@@ -1,10 +1,14 @@
-import type { StatefulComponent } from "@praxisjs/core";
+import {
+  getComponentDefault,
+  getComponentRawProp,
+  type RootComponent,
+} from "@praxisjs/core/internal";
 
 export function readProp(
-  instance: StatefulComponent,
+  instance: RootComponent<Record<string, unknown>>,
   propName: string,
 ): unknown {
-  const fromParent = instance._rawProps[propName];
+  const fromParent = getComponentRawProp(instance, propName);
   if (fromParent !== undefined) return fromParent;
-  return instance._defaults[propName];
+  return getComponentDefault(instance, propName);
 }

package/src/index.ts

@@ -15,6 +15,7 @@ export {
 } from "./functions";
 export {
   Prop,
+  FunctionProp,
   State,
   Computed,
   Persisted,
@@ -39,7 +40,7 @@ export {
   type FieldBehavior,
   type FieldBinding,
 } from "./create-field-decorator";
-export { type ReactiveHost } from "./reactive-host";
+export { reactiveHostType, type ReactiveHost } from "./reactive-host";
 export {
   createClassDecorator,
   ClassBehavior,

package/src/properties/deep-state.ts

@@ -1,4 +1,4 @@
-import { signal } from "@praxisjs/core/internal";
+import { markStateDirty, signal } from "@praxisjs/core/internal";
 
 import { createFieldDecorator } from "../create-field-decorator";
 
@@ -37,7 +37,7 @@ export function DeepState() {
           : current;
 
       function notify() {
-        instance._stateDirty = true;
+        markStateDirty(instance);
         version.update((v) => v + 1);
       }
 

package/src/properties/function-prop.ts

@@ -0,0 +1,37 @@
+import {
+  getComponentDefault,
+  getComponentRawProp,
+  setComponentDefault,
+} from "@praxisjs/core/internal";
+
+import { createFieldDecorator } from "../create-field-decorator";
+
+export function FunctionProp() {
+  return createFieldDecorator({
+    bind(instance, name, initialValue) {
+      setComponentDefault(instance, name, initialValue);
+      return {
+        descriptor: {
+          get() {
+            const fromParent = getComponentRawProp(instance, name);
+            if (fromParent !== undefined) {
+              if (
+                process.env.NODE_ENV !== "production" &&
+                typeof fromParent !== "function"
+              ) {
+                console.warn(
+                  `[FunctionProp] "${name}" received a non-function value (${typeof fromParent}). @FunctionProp() expects a function.`,
+                );
+              }
+              return fromParent;
+            }
+            return getComponentDefault(instance, name);
+          },
+          set(value: unknown) {
+            setComponentDefault(instance, name, value);
+          },
+        },
+      };
+    },
+  });
+}

package/src/properties/index.ts

@@ -1,4 +1,5 @@
 export { Prop } from "./prop";
+export { FunctionProp } from "./function-prop";
 export { State } from "./state";
 export { Computed } from "./computed";
 export { Persisted } from "./persisted";

package/src/properties/prop.ts

@@ -1,22 +1,28 @@
+import {
+  getComponentDefault,
+  getComponentRawProp,
+  setComponentDefault,
+} from "@praxisjs/core/internal";
+
 import { createFieldDecorator } from "../create-field-decorator";
 
 export function Prop() {
   return createFieldDecorator({
     bind(instance, name, initialValue) {
-      instance._defaults[name] = initialValue;
+      setComponentDefault(instance, name, initialValue);
       return {
         descriptor: {
           get() {
-            const fromParent = (instance._rawProps)[name];
+            const fromParent = getComponentRawProp(instance, name);
             if (fromParent !== undefined) {
               return typeof fromParent === "function"
                 ? (fromParent as () => unknown)()
                 : fromParent;
             }
-            return instance._defaults[name];
+            return getComponentDefault(instance, name);
           },
           set(value: unknown) {
-            instance._defaults[name] = value;
+            setComponentDefault(instance, name, value);
           },
         },
       };

package/src/properties/state.ts

@@ -1,4 +1,4 @@
-import { signal } from "@praxisjs/core/internal";
+import { markStateDirty, signal } from "@praxisjs/core/internal";
 
 import { createFieldDecorator } from "../create-field-decorator";
 
@@ -12,7 +12,7 @@ export function State() {
         descriptor: {
           get: () => sig(),
           set: (value: unknown) => {
-            instance._stateDirty = true;
+            markStateDirty(instance);
             sig.set(value);
           },
         },

package/src/reactive-host.ts

@@ -1,3 +1,7 @@
-export interface ReactiveHost {
-  _stateDirty: boolean;
-}
+import type { componentPropsType } from "@praxisjs/core/internal";
+
+export const reactiveHostType: unique symbol = Symbol("praxis.reactiveHostType");
+
+export type ReactiveHost =
+  | { readonly [componentPropsType]: object }
+  | { readonly [reactiveHostType]: true };

package/tsconfig.json

@@ -2,7 +2,8 @@
   "extends": "../../../tsconfig.base.json",
   "compilerOptions": {
     "outDir": "./dist",
-    "rootDir": "./src"
+    "rootDir": "./src",
+    "types": ["node"]
   },
   "include": ["src"]
 }