@praxisjs/decorators 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @praxisjs/decorators
 
+## 1.4.0
+
+### Minor Changes
+
+- bcaad96: Add `@Ref<T>()` decorator, `createRef<T>()` helper, and `Ref<T>` type for typed DOM element refs.
+
+  Replaces the manual `{ current: null as T | null }` field with a decorator that produces a callable ref — pass it directly to the JSX `ref` prop and read `.current` to access the element. Works transparently with `@Compose` via the existing string-name resolution. Use `createRef<T>()` for module-level refs outside of classes.
+
+### Patch Changes
+
+- Updated dependencies [376e38c]
+  - @praxisjs/core@1.8.2
+
+## 1.3.1
+
+### Patch Changes
+
+- Updated dependencies [dc031d0]
+  - @praxisjs/core@1.8.1
+
 ## 1.3.0
 
 ### Minor Changes

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

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

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

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

package/dist/__tests__/ref.test.js

@@ -0,0 +1,106 @@
+// @vitest-environment jsdom
+import { describe, it, expect } from "vitest";
+import { StatefulComponent } from "@praxisjs/core";
+import { Ref, createRef } from "../properties/ref";
+function fieldCtx(name) {
+    const initializers = [];
+    return {
+        ctx: {
+            name,
+            kind: "field",
+            addInitializer(fn) {
+                initializers.push(fn);
+            },
+        },
+        run(instance) {
+            initializers.forEach((fn) => { fn.call(instance); });
+        },
+    };
+}
+class TestComponent extends StatefulComponent {
+    render() { return null; }
+}
+describe("Ref decorator", () => {
+    it("initializes .current to null", () => {
+        const { ctx, run } = fieldCtx("elRef");
+        Ref()(undefined, ctx);
+        const instance = new TestComponent();
+        run(instance);
+        const ref = instance.elRef;
+        expect(ref.current).toBeNull();
+    });
+    it("is callable and sets .current", () => {
+        const { ctx, run } = fieldCtx("elRef");
+        Ref()(undefined, ctx);
+        const instance = new TestComponent();
+        run(instance);
+        const ref = instance.elRef;
+        const fakeEl = document.createElement("div");
+        ref(fakeEl);
+        expect(ref.current).toBe(fakeEl);
+    });
+    it("calling with null clears .current", () => {
+        const { ctx, run } = fieldCtx("elRef");
+        Ref()(undefined, ctx);
+        const instance = new TestComponent();
+        run(instance);
+        const ref = instance.elRef;
+        const fakeEl = document.createElement("div");
+        ref(fakeEl);
+        expect(ref.current).toBe(fakeEl);
+        ref(null);
+        expect(ref.current).toBeNull();
+    });
+    it("returns the same ref object on every access", () => {
+        const { ctx, run } = fieldCtx("elRef");
+        Ref()(undefined, ctx);
+        const instance = new TestComponent();
+        run(instance);
+        const inst = instance;
+        expect(inst.elRef).toBe(inst.elRef);
+    });
+    it("each instance gets its own independent ref", () => {
+        const { ctx: ctx1, run: run1 } = fieldCtx("elRef");
+        const { ctx: ctx2, run: run2 } = fieldCtx("elRef");
+        Ref()(undefined, ctx1);
+        Ref()(undefined, ctx2);
+        const a = new TestComponent();
+        const b = new TestComponent();
+        run1(a);
+        run2(b);
+        const refA = a.elRef;
+        const refB = b.elRef;
+        const el = document.createElement("div");
+        refA(el);
+        expect(refA.current).toBe(el);
+        expect(refB.current).toBeNull();
+    });
+});
+describe("createRef", () => {
+    it("initializes .current to null", () => {
+        const ref = createRef();
+        expect(ref.current).toBeNull();
+    });
+    it("is callable and sets .current", () => {
+        const ref = createRef();
+        const el = document.createElement("div");
+        ref(el);
+        expect(ref.current).toBe(el);
+    });
+    it("calling with null clears .current", () => {
+        const ref = createRef();
+        const el = document.createElement("div");
+        ref(el);
+        ref(null);
+        expect(ref.current).toBeNull();
+    });
+    it("each call creates an independent ref", () => {
+        const a = createRef();
+        const b = createRef();
+        const el = document.createElement("div");
+        a(el);
+        expect(a.current).toBe(el);
+        expect(b.current).toBeNull();
+    });
+});
+//# sourceMappingURL=ref.test.js.map

package/dist/__tests__/ref.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ref.test.js","sourceRoot":"","sources":["../../src/__tests__/ref.test.ts"],"names":[],"mappings":"AAAA,4BAA4B;AAC5B,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAE9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAEnD,SAAS,QAAQ,CAAC,IAAY;IAC5B,MAAM,YAAY,GAAmC,EAAE,CAAC;IACxD,OAAO;QACL,GAAG,EAAE;YACH,IAAI;YACJ,IAAI,EAAE,OAAgB;YACtB,cAAc,CAAC,EAA2B;gBACxC,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACxB,CAAC;SAC4B;QAC/B,GAAG,CAAC,QAAiB;YACnB,YAAY,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACvD,CAAC;KACF,CAAC;AACJ,CAAC;AAED,MAAM,aAAc,SAAQ,iBAAiB;IAC3C,MAAM,KAAK,OAAO,IAAI,CAAC,CAAC,CAAC;CAC1B;AAED,QAAQ,CAAC,eAAe,EAAE,GAAG,EAAE;IAC7B,EAAE,CAAC,8BAA8B,EAAE,GAAG,EAAE;QACtC,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;QACvC,GAAG,EAAE,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;QAEtB,MAAM,QAAQ,GAAG,IAAI,aAAa,EAAE,CAAC;QACrC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAEd,MAAM,GAAG,GAAI,QAA+C,CAAC,KAA6B,CAAC;QAC3F,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,CAAC;IACjC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,+BAA+B,EAAE,GAAG,EAAE;QACvC,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;QACvC,GAAG,EAAkB,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;QAEtC,MAAM,QAAQ,GAAG,IAAI,aAAa,EAAE,CAAC;QACrC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAEd,MAAM,GAAG,GAAI,QAA+C,CAAC,KAAmF,CAAC;QACjJ,MAAM,MAAM,GAAG,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAmB,CAAC;QAC/D,GAAG,CAAC,MAAM,CAAC,CAAC;QAEZ,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACnC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,mCAAmC,EAAE,GAAG,EAAE;QAC3C,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;QACvC,GAAG,EAAkB,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;QAEtC,MAAM,QAAQ,GAAG,IAAI,aAAa,EAAE,CAAC;QACrC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAEd,MAAM,GAAG,GAAI,QAA+C,CAAC,KAAmF,CAAC;QACjJ,MAAM,MAAM,GAAG,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAmB,CAAC;QAC/D,GAAG,CAAC,MAAM,CAAC,CAAC;QACZ,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAEjC,GAAG,CAAC,IAAI,CAAC,CAAC;QACV,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,CAAC;IACjC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,6CAA6C,EAAE,GAAG,EAAE;QACrD,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;QACvC,GAAG,EAAE,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;QAEtB,MAAM,QAAQ,GAAG,IAAI,aAAa,EAAE,CAAC;QACrC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAEd,MAAM,IAAI,GAAG,QAA8C,CAAC;QAC5D,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACtC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,4CAA4C,EAAE,GAAG,EAAE;QACpD,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;QACnD,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;QACnD,GAAG,EAAkB,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;QACvC,GAAG,EAAkB,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;QAEvC,MAAM,CAAC,GAAG,IAAI,aAAa,EAAE,CAAC;QAC9B,MAAM,CAAC,GAAG,IAAI,aAAa,EAAE,CAAC;QAC9B,IAAI,CAAC,CAAC,CAAC,CAAC;QACR,IAAI,CAAC,CAAC,CAAC,CAAC;QAER,MAAM,IAAI,GAAI,CAAwC,CAAC,KAAmF,CAAC;QAC3I,MAAM,IAAI,GAAI,CAAwC,CAAC,KAAmF,CAAC;QAE3I,MAAM,EAAE,GAAG,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAmB,CAAC;QAC3D,IAAI,CAAC,EAAE,CAAC,CAAC;QAET,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC9B,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,CAAC;IAClC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,WAAW,EAAE,GAAG,EAAE;IACzB,EAAE,CAAC,8BAA8B,EAAE,GAAG,EAAE;QACtC,MAAM,GAAG,GAAG,SAAS,EAAkB,CAAC;QACxC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,CAAC;IACjC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,+BAA+B,EAAE,GAAG,EAAE;QACvC,MAAM,GAAG,GAAG,SAAS,EAAkB,CAAC;QACxC,MAAM,EAAE,GAAG,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAmB,CAAC;QAC3D,GAAG,CAAC,EAAE,CAAC,CAAC;QACR,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC/B,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,mCAAmC,EAAE,GAAG,EAAE;QAC3C,MAAM,GAAG,GAAG,SAAS,EAAkB,CAAC;QACxC,MAAM,EAAE,GAAG,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAmB,CAAC;QAC3D,GAAG,CAAC,EAAE,CAAC,CAAC;QACR,GAAG,CAAC,IAAI,CAAC,CAAC;QACV,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,CAAC;IACjC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,sCAAsC,EAAE,GAAG,EAAE;QAC9C,MAAM,CAAC,GAAG,SAAS,EAAkB,CAAC;QACtC,MAAM,CAAC,GAAG,SAAS,EAAkB,CAAC;QACtC,MAAM,EAAE,GAAG,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAmB,CAAC;QAC3D,CAAC,CAAC,EAAE,CAAC,CAAC;QACN,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC3B,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,CAAC;IAC/B,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { Component, Lazy } from "./component";
 export { Memo, Bind, Log, Once, Retry, Debounce, Throttle, When, Until, Watch, type WatchVal, type WatchVals, } from "./functions";
-export { Prop, State, Computed, Persisted, Slot, initSlots, History, type HistoryOf, Compose, getter, Resource, invalidateResource, type ResourceInstance, type ResourceOptions, Synced, DeepState, } from "./properties";
+export { Prop, State, Computed, Persisted, Slot, initSlots, History, type HistoryOf, Compose, getter, Resource, invalidateResource, type ResourceInstance, type ResourceOptions, Synced, DeepState, Ref, createRef, } from "./properties";
 export { type Command, createCommand, Emit, OnCommand } from "./events";
 export { createFieldDecorator, type FieldBehavior, type FieldBinding, } from "./create-field-decorator";
 export { type ReactiveHost } from "./reactive-host";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EACL,IAAI,EACJ,IAAI,EACJ,GAAG,EACH,IAAI,EACJ,KAAK,EACL,QAAQ,EACR,QAAQ,EACR,IAAI,EACJ,KAAK,EACL,KAAK,EACL,KAAK,QAAQ,EACb,KAAK,SAAS,GACf,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,IAAI,EACJ,KAAK,EACL,QAAQ,EACR,SAAS,EACT,IAAI,EACJ,SAAS,EACT,OAAO,EACP,KAAK,SAAS,EACd,OAAO,EACP,MAAM,EACN,QAAQ,EACR,kBAAkB,EAClB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,MAAM,EACN,SAAS,GACV,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,KAAK,OAAO,EAAE,aAAa,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACxE,OAAO,EACL,oBAAoB,EACpB,KAAK,aAAa,EAClB,KAAK,YAAY,GAClB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EACL,oBAAoB,EACpB,aAAa,EACb,KAAK,gBAAgB,GACtB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,qBAAqB,EACrB,KAAK,cAAc,GACpB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,8BAA8B,EAC9B,KAAK,uBAAuB,GAC7B,MAAM,qCAAqC,CAAC;AAC7C,OAAO,EACL,qBAAqB,EACrB,KAAK,cAAc,EACnB,6BAA6B,EAC7B,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,6BAA6B,EAC7B,KAAK,sBAAsB,GAC5B,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,uBAAuB,EACvB,KAAK,gBAAgB,EACrB,KAAK,eAAe,GACrB,MAAM,6BAA6B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EACL,IAAI,EACJ,IAAI,EACJ,GAAG,EACH,IAAI,EACJ,KAAK,EACL,QAAQ,EACR,QAAQ,EACR,IAAI,EACJ,KAAK,EACL,KAAK,EACL,KAAK,QAAQ,EACb,KAAK,SAAS,GACf,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,IAAI,EACJ,KAAK,EACL,QAAQ,EACR,SAAS,EACT,IAAI,EACJ,SAAS,EACT,OAAO,EACP,KAAK,SAAS,EACd,OAAO,EACP,MAAM,EACN,QAAQ,EACR,kBAAkB,EAClB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,MAAM,EACN,SAAS,EACT,GAAG,EACH,SAAS,GACV,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,KAAK,OAAO,EAAE,aAAa,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACxE,OAAO,EACL,oBAAoB,EACpB,KAAK,aAAa,EAClB,KAAK,YAAY,GAClB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EACL,oBAAoB,EACpB,aAAa,EACb,KAAK,gBAAgB,GACtB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,qBAAqB,EACrB,KAAK,cAAc,GACpB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,8BAA8B,EAC9B,KAAK,uBAAuB,GAC7B,MAAM,qCAAqC,CAAC;AAC7C,OAAO,EACL,qBAAqB,EACrB,KAAK,cAAc,EACnB,6BAA6B,EAC7B,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,6BAA6B,EAC7B,KAAK,sBAAsB,GAC5B,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,uBAAuB,EACvB,KAAK,gBAAgB,EACrB,KAAK,eAAe,GACrB,MAAM,6BAA6B,CAAC"}

package/dist/index.js

@@ -1,6 +1,6 @@
 export { Component, Lazy } from "./component";
 export { Memo, Bind, Log, Once, Retry, Debounce, Throttle, When, Until, Watch, } from "./functions";
-export { Prop, State, Computed, Persisted, Slot, initSlots, History, Compose, getter, Resource, invalidateResource, Synced, DeepState, } from "./properties";
+export { Prop, State, Computed, Persisted, Slot, initSlots, History, Compose, getter, Resource, invalidateResource, Synced, DeepState, Ref, createRef, } from "./properties";
 export { createCommand, Emit, OnCommand } from "./events";
 export { createFieldDecorator, } from "./create-field-decorator";
 export { createClassDecorator, ClassBehavior, } from "./create-class-decorator";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EACL,IAAI,EACJ,IAAI,EACJ,GAAG,EACH,IAAI,EACJ,KAAK,EACL,QAAQ,EACR,QAAQ,EACR,IAAI,EACJ,KAAK,EACL,KAAK,GAGN,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,IAAI,EACJ,KAAK,EACL,QAAQ,EACR,SAAS,EACT,IAAI,EACJ,SAAS,EACT,OAAO,EAEP,OAAO,EACP,MAAM,EACN,QAAQ,EACR,kBAAkB,EAGlB,MAAM,EACN,SAAS,GACV,MAAM,cAAc,CAAC;AACtB,OAAO,EAAgB,aAAa,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACxE,OAAO,EACL,oBAAoB,GAGrB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EACL,oBAAoB,EACpB,aAAa,GAEd,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,qBAAqB,GAEtB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,8BAA8B,GAE/B,MAAM,qCAAqC,CAAC;AAC7C,OAAO,EACL,qBAAqB,EAErB,6BAA6B,EAG7B,6BAA6B,GAE9B,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,uBAAuB,GAGxB,MAAM,6BAA6B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EACL,IAAI,EACJ,IAAI,EACJ,GAAG,EACH,IAAI,EACJ,KAAK,EACL,QAAQ,EACR,QAAQ,EACR,IAAI,EACJ,KAAK,EACL,KAAK,GAGN,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,IAAI,EACJ,KAAK,EACL,QAAQ,EACR,SAAS,EACT,IAAI,EACJ,SAAS,EACT,OAAO,EAEP,OAAO,EACP,MAAM,EACN,QAAQ,EACR,kBAAkB,EAGlB,MAAM,EACN,SAAS,EACT,GAAG,EACH,SAAS,GACV,MAAM,cAAc,CAAC;AACtB,OAAO,EAAgB,aAAa,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACxE,OAAO,EACL,oBAAoB,GAGrB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EACL,oBAAoB,EACpB,aAAa,GAEd,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,qBAAqB,GAEtB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,8BAA8B,GAE/B,MAAM,qCAAqC,CAAC;AAC7C,OAAO,EACL,qBAAqB,EAErB,6BAA6B,EAG7B,6BAA6B,GAE9B,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,uBAAuB,GAGxB,MAAM,6BAA6B,CAAC"}

package/dist/properties/index.d.ts

@@ -8,4 +8,5 @@ export { Compose, getter } from "./compose";
 export { Resource, invalidateResource, type ResourceInstance, type ResourceOptions } from "./resource";
 export { Synced } from "./synced";
 export { DeepState } from "./deep-state";
+export { Ref, createRef } from "./ref";
 //# sourceMappingURL=index.d.ts.map

package/dist/properties/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/properties/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,kBAAkB,EAAE,KAAK,gBAAgB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AACvG,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/properties/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,kBAAkB,EAAE,KAAK,gBAAgB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AACvG,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC"}

package/dist/properties/index.js

@@ -8,4 +8,5 @@ export { Compose, getter } from "./compose";
 export { Resource, invalidateResource } from "./resource";
 export { Synced } from "./synced";
 export { DeepState } from "./deep-state";
+export { Ref, createRef } from "./ref";
 //# sourceMappingURL=index.js.map

package/dist/properties/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/properties/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACzC,OAAO,EAAE,OAAO,EAAkB,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,kBAAkB,EAA+C,MAAM,YAAY,CAAC;AACvG,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/properties/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACzC,OAAO,EAAE,OAAO,EAAkB,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,kBAAkB,EAA+C,MAAM,YAAY,CAAC;AACvG,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC"}

package/dist/properties/ref.d.ts

@@ -0,0 +1,7 @@
+export type Ref<T extends Element = Element> = ((el: T | null) => void) & {
+    current: T | null;
+};
+/** Creates a standalone ref object for use outside of class fields (e.g. module-level or passed to @Lazy). */
+export declare function createRef<T extends Element = Element>(): Ref<T>;
+export declare function Ref<T extends Element = Element>(): <This extends import("@praxisjs/core").StatefulComponent, Value = unknown>(_value: undefined, context: ClassFieldDecoratorContext<This, Value>) => void;
+//# sourceMappingURL=ref.d.ts.map

package/dist/properties/ref.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ref.d.ts","sourceRoot":"","sources":["../../src/properties/ref.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,GAAG,CAAC,CAAC,SAAS,OAAO,GAAG,OAAO,IAAI,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,IAAI,KAAK,IAAI,CAAC,GAAG;IACxE,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC;CACnB,CAAC;AAEF,8GAA8G;AAE9G,wBAAgB,SAAS,CAAC,CAAC,SAAS,OAAO,GAAG,OAAO,KAAK,GAAG,CAAC,CAAC,CAAC,CAM/D;AAGD,wBAAgB,GAAG,CAAC,CAAC,SAAS,OAAO,GAAG,OAAO,6JAS9C"}

package/dist/properties/ref.js

@@ -0,0 +1,21 @@
+import { createFieldDecorator } from "../create-field-decorator";
+/** Creates a standalone ref object for use outside of class fields (e.g. module-level or passed to @Lazy). */
+export function createRef() {
+    function refFn(el) {
+        refFn.current = el;
+    }
+    refFn.current = null;
+    return refFn;
+}
+// eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters
+export function Ref() {
+    return createFieldDecorator({
+        bind(_instance, _name, _initialValue) {
+            const ref = createRef();
+            return {
+                descriptor: { get: () => ref },
+            };
+        },
+    });
+}
+//# sourceMappingURL=ref.js.map

package/dist/properties/ref.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ref.js","sourceRoot":"","sources":["../../src/properties/ref.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAMjE,8GAA8G;AAE9G,MAAM,UAAU,SAAS;IACvB,SAAS,KAAK,CAAC,EAAY;QACxB,KAAgB,CAAC,OAAO,GAAG,EAAE,CAAC;IACjC,CAAC;IACA,KAAgB,CAAC,OAAO,GAAG,IAAI,CAAC;IACjC,OAAO,KAAe,CAAC;AACzB,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,GAAG;IACjB,OAAO,oBAAoB,CAAC;QAC1B,IAAI,CAAC,SAAS,EAAE,KAAK,EAAE,aAAa;YAClC,MAAM,GAAG,GAAG,SAAS,EAAK,CAAC;YAC3B,OAAO;gBACL,UAAU,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,GAAG,EAAE;aAC/B,CAAC;QACJ,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@praxisjs/decorators",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -15,7 +15,7 @@
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "@praxisjs/core": "1.8.0",
+    "@praxisjs/core": "1.8.2",
     "@praxisjs/shared": "0.3.0"
   },
   "scripts": {

package/src/__tests__/ref.test.ts

@@ -0,0 +1,131 @@
+// @vitest-environment jsdom
+import { describe, it, expect } from "vitest";
+
+import { StatefulComponent } from "@praxisjs/core";
+import { Ref, createRef } from "../properties/ref";
+
+function fieldCtx(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); });
+    },
+  };
+}
+
+class TestComponent extends StatefulComponent {
+  render() { return null; }
+}
+
+describe("Ref decorator", () => {
+  it("initializes .current to null", () => {
+    const { ctx, run } = fieldCtx("elRef");
+    Ref()(undefined, ctx);
+
+    const instance = new TestComponent();
+    run(instance);
+
+    const ref = (instance as unknown as Record<string, unknown>).elRef as { current: unknown };
+    expect(ref.current).toBeNull();
+  });
+
+  it("is callable and sets .current", () => {
+    const { ctx, run } = fieldCtx("elRef");
+    Ref<HTMLDivElement>()(undefined, ctx);
+
+    const instance = new TestComponent();
+    run(instance);
+
+    const ref = (instance as unknown as Record<string, unknown>).elRef as ((el: HTMLDivElement | null) => void) & { current: HTMLDivElement | null };
+    const fakeEl = document.createElement("div") as HTMLDivElement;
+    ref(fakeEl);
+
+    expect(ref.current).toBe(fakeEl);
+  });
+
+  it("calling with null clears .current", () => {
+    const { ctx, run } = fieldCtx("elRef");
+    Ref<HTMLDivElement>()(undefined, ctx);
+
+    const instance = new TestComponent();
+    run(instance);
+
+    const ref = (instance as unknown as Record<string, unknown>).elRef as ((el: HTMLDivElement | null) => void) & { current: HTMLDivElement | null };
+    const fakeEl = document.createElement("div") as HTMLDivElement;
+    ref(fakeEl);
+    expect(ref.current).toBe(fakeEl);
+
+    ref(null);
+    expect(ref.current).toBeNull();
+  });
+
+  it("returns the same ref object on every access", () => {
+    const { ctx, run } = fieldCtx("elRef");
+    Ref()(undefined, ctx);
+
+    const instance = new TestComponent();
+    run(instance);
+
+    const inst = instance as unknown as Record<string, unknown>;
+    expect(inst.elRef).toBe(inst.elRef);
+  });
+
+  it("each instance gets its own independent ref", () => {
+    const { ctx: ctx1, run: run1 } = fieldCtx("elRef");
+    const { ctx: ctx2, run: run2 } = fieldCtx("elRef");
+    Ref<HTMLDivElement>()(undefined, ctx1);
+    Ref<HTMLDivElement>()(undefined, ctx2);
+
+    const a = new TestComponent();
+    const b = new TestComponent();
+    run1(a);
+    run2(b);
+
+    const refA = (a as unknown as Record<string, unknown>).elRef as ((el: HTMLDivElement | null) => void) & { current: HTMLDivElement | null };
+    const refB = (b as unknown as Record<string, unknown>).elRef as ((el: HTMLDivElement | null) => void) & { current: HTMLDivElement | null };
+
+    const el = document.createElement("div") as HTMLDivElement;
+    refA(el);
+
+    expect(refA.current).toBe(el);
+    expect(refB.current).toBeNull();
+  });
+});
+
+describe("createRef", () => {
+  it("initializes .current to null", () => {
+    const ref = createRef<HTMLDivElement>();
+    expect(ref.current).toBeNull();
+  });
+
+  it("is callable and sets .current", () => {
+    const ref = createRef<HTMLDivElement>();
+    const el = document.createElement("div") as HTMLDivElement;
+    ref(el);
+    expect(ref.current).toBe(el);
+  });
+
+  it("calling with null clears .current", () => {
+    const ref = createRef<HTMLDivElement>();
+    const el = document.createElement("div") as HTMLDivElement;
+    ref(el);
+    ref(null);
+    expect(ref.current).toBeNull();
+  });
+
+  it("each call creates an independent ref", () => {
+    const a = createRef<HTMLDivElement>();
+    const b = createRef<HTMLDivElement>();
+    const el = document.createElement("div") as HTMLDivElement;
+    a(el);
+    expect(a.current).toBe(el);
+    expect(b.current).toBeNull();
+  });
+});

package/src/index.ts

@@ -30,6 +30,8 @@ export {
   type ResourceOptions,
   Synced,
   DeepState,
+  Ref,
+  createRef,
 } from "./properties";
 export { type Command, createCommand, Emit, OnCommand } from "./events";
 export {

package/src/properties/index.ts

@@ -8,3 +8,4 @@ export { Compose, getter } from "./compose";
 export { Resource, invalidateResource, type ResourceInstance, type ResourceOptions } from "./resource";
 export { Synced } from "./synced";
 export { DeepState } from "./deep-state";
+export { Ref, createRef } from "./ref";

package/src/properties/ref.ts

@@ -0,0 +1,27 @@
+import { createFieldDecorator } from "../create-field-decorator";
+
+export type Ref<T extends Element = Element> = ((el: T | null) => void) & {
+  current: T | null;
+};
+
+/** Creates a standalone ref object for use outside of class fields (e.g. module-level or passed to @Lazy). */
+ 
+export function createRef<T extends Element = Element>(): Ref<T> {
+  function refFn(el: T | null): void {
+    (refFn as Ref<T>).current = el;
+  }
+  (refFn as Ref<T>).current = null;
+  return refFn as Ref<T>;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters
+export function Ref<T extends Element = Element>() {
+  return createFieldDecorator({
+    bind(_instance, _name, _initialValue) {
+      const ref = createRef<T>();
+      return {
+        descriptor: { get: () => ref },
+      };
+    },
+  });
+}