@praxisjs/core 1.8.1 → 1.8.3

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @praxisjs/core
 
+## 1.8.3
+
+### Patch Changes
+
+- 7d87288: Document `props` as `StatelessComponent`'s intended public API, and as an internal implementation detail on `StatefulComponent` (use `@Prop()` fields instead). No behavior change — `RootComponent.props`, `StatefulComponent.props`, and `StatelessComponent.props` all still return `_rawProps` exactly as before; this only clarifies, via JSDoc, which class each usage pattern is meant for.
+
+## 1.8.2
+
+### Patch Changes
+
+- 376e38c: Internal consolidation: move `_setProps` to `RootComponent` and mark internal fields with `@internal`.
+
+  `_setProps(props)` was implemented identically in both `StatefulComponent` and `StatelessComponent`. It is now defined once on `RootComponent` and removed from the subclasses.
+
+  The following fields on `RootComponent`, `StatefulComponent` are now annotated with `@internal` JSDoc tags and descriptions so they are hidden from TypeDoc output and IDE autocomplete:
+  - `RootComponent._rawProps` — props filled by the renderer on instantiation and update
+  - `RootComponent._mounted` — becomes `true` after `onMount` fires
+  - `RootComponent._anchor` — end-comment node set by the runtime; used by decorators to locate the parent element
+  - `StatefulComponent._defaults` — default field values used to reset props on update
+  - `StatefulComponent._stateDirty` — set by `@State` on any write; cleared by the renderer after each re-render
+
+  No public API changes.
+
 ## 1.8.1
 
 ### Patch Changes

package/dist/component/base.d.ts

@@ -1,11 +1,30 @@
 export declare abstract class RootComponent<T extends object = Record<string, never>> {
-    /** Props passed by the parent — filled by the renderer when instantiating/updating. */
+    /**
+     * Props passed by the parent — filled by the renderer when instantiating/updating.
+     * @internal
+     */
     readonly _rawProps: T;
-    /** @internal — becomes `true` after `onMount` fires */
+    /**
+     * Becomes `true` after `onMount` fires.
+     * @internal
+     */
     _mounted: boolean;
-    /** @internal — end comment anchor set by the runtime; used by decorators to locate the parent element */
+    /**
+     * End comment anchor set by the runtime; used by decorators to locate the parent element.
+     * @internal
+     */
     _anchor?: Comment;
     constructor(props?: T);
+    /**
+     * Replaces the current props with a new set; called by the renderer on every parent re-render.
+     * @internal
+     */
+    _setProps(props: Record<string, unknown>): void;
+    /**
+     * Raw props, typed. `StatelessComponent` re-exposes this as its public
+     * props API; on `StatefulComponent` it's internal — use `@Prop()` instead.
+     * @internal
+     */
     get props(): T;
     onBeforeMount?(): void;
     onMount?(): void;

package/dist/component/base.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/component/base.ts"],"names":[],"mappings":"AAAA,8BAAsB,aAAa,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC;IAC1E,uFAAuF;IACvF,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAW;IAEhC,uDAAuD;IACvD,QAAQ,UAAS;IAEjB,yGAAyG;IACzG,OAAO,CAAC,EAAE,OAAO,CAAC;gBAEN,KAAK,GAAE,CAAW;IAI9B,IAAI,KAAK,IAAI,CAAC,CAEb;IAED,aAAa,CAAC,IAAI,IAAI;IACtB,OAAO,CAAC,IAAI,IAAI;IAChB,SAAS,CAAC,IAAI,IAAI;IAElB,OAAO,CAAC,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,GAAG,IAAI,EAAE,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI;IAE/D,QAAQ,CAAC,MAAM,IAAI,IAAI,GAAG,IAAI,EAAE,GAAG,IAAI;CACxC"}
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/component/base.ts"],"names":[],"mappings":"AAAA,8BAAsB,aAAa,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC;IAC1E;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAW;IAEhC;;;OAGG;IACH,QAAQ,UAAS;IAEjB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;gBAEN,KAAK,GAAE,CAAW;IAI9B;;;OAGG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAOxC;;;;OAIG;IACH,IAAI,KAAK,IAAI,CAAC,CAEb;IAED,aAAa,CAAC,IAAI,IAAI;IACtB,OAAO,CAAC,IAAI,IAAI;IAChB,SAAS,CAAC,IAAI,IAAI;IAElB,OAAO,CAAC,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,GAAG,IAAI,EAAE,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI;IAE/D,QAAQ,CAAC,MAAM,IAAI,IAAI,GAAG,IAAI,EAAE,GAAG,IAAI;CACxC"}

package/dist/component/base.js

@@ -1,11 +1,32 @@
 export class RootComponent {
     constructor(props = {}) {
-        /** Props passed by the parent — filled by the renderer when instantiating/updating. */
+        /**
+         * Props passed by the parent — filled by the renderer when instantiating/updating.
+         * @internal
+         */
         this._rawProps = {};
-        /** @internal — becomes `true` after `onMount` fires */
+        /**
+         * Becomes `true` after `onMount` fires.
+         * @internal
+         */
         this._mounted = false;
         Object.assign(this._rawProps, props);
     }
+    /**
+     * Replaces the current props with a new set; called by the renderer on every parent re-render.
+     * @internal
+     */
+    _setProps(props) {
+        Object.keys(this._rawProps).forEach((k) => {
+            Reflect.deleteProperty(this._rawProps, k);
+        });
+        Object.assign(this._rawProps, props);
+    }
+    /**
+     * Raw props, typed. `StatelessComponent` re-exposes this as its public
+     * props API; on `StatefulComponent` it's internal — use `@Prop()` instead.
+     * @internal
+     */
     get props() {
         return this._rawProps;
     }

package/dist/component/base.js.map

@@ -1 +1 @@
-{"version":3,"file":"base.js","sourceRoot":"","sources":["../../src/component/base.ts"],"names":[],"mappings":"AAAA,MAAM,OAAgB,aAAa;IAUjC,YAAY,QAAW,EAAO;QAT9B,uFAAuF;QAC9E,cAAS,GAAM,EAAO,CAAC;QAEhC,uDAAuD;QACvD,aAAQ,GAAG,KAAK,CAAC;QAMf,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;IACvC,CAAC;IAED,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;CASF"}
+{"version":3,"file":"base.js","sourceRoot":"","sources":["../../src/component/base.ts"],"names":[],"mappings":"AAAA,MAAM,OAAgB,aAAa;IAmBjC,YAAY,QAAW,EAAO;QAlB9B;;;WAGG;QACM,cAAS,GAAM,EAAO,CAAC;QAEhC;;;WAGG;QACH,aAAQ,GAAG,KAAK,CAAC;QASf,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;IACvC,CAAC;IAED;;;OAGG;IACH,SAAS,CAAC,KAA8B;QACtC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE;YACxC,OAAO,CAAC,cAAc,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC;QAC5C,CAAC,CAAC,CAAC;QACH,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;IACvC,CAAC;IAED;;;;OAIG;IACH,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;CASF"}

package/dist/component/stateful.d.ts

@@ -1,9 +1,19 @@
 import { RootComponent } from "./base";
 export declare abstract class StatefulComponent extends RootComponent<Record<string, unknown>> {
-    /** Default values declared in the class. */
+    /**
+     * Default field values declared in the class, used to reset props on update.
+     * @internal
+     */
     readonly _defaults: Record<string, unknown>;
-    /** @internal — set to true by @State on any write; cleared by renderer after each re-render */
+    /**
+     * Set to `true` by `@State` on any write; cleared by the renderer after each re-render.
+     * @internal
+     */
     _stateDirty: boolean;
-    _setProps(props: Record<string, unknown>): void;
+    /**
+     * Raw props. Use `@Prop()` fields instead of reading this directly in user code.
+     * @internal
+     */
+    get props(): Record<string, unknown>;
 }
 //# sourceMappingURL=stateful.d.ts.map

package/dist/component/stateful.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stateful.d.ts","sourceRoot":"","sources":["../../src/component/stateful.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAEvC,8BAAsB,iBAAkB,SAAQ,aAAa,CAC3D,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CACxB;IACC,4CAA4C;IAC5C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAM;IAEjD,+FAA+F;IAC/F,WAAW,UAAS;IAEpB,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAMzC"}
+{"version":3,"file":"stateful.d.ts","sourceRoot":"","sources":["../../src/component/stateful.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAEvC,8BAAsB,iBAAkB,SAAQ,aAAa,CAC3D,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CACxB;IACC;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAM;IAEjD;;;OAGG;IACH,WAAW,UAAS;IAEpB;;;OAGG;IACH,IAAa,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE5C;CACF"}

package/dist/component/stateful.js

@@ -2,16 +2,23 @@ import { RootComponent } from "./base";
 export class StatefulComponent extends RootComponent {
     constructor() {
         super(...arguments);
-        /** Default values declared in the class. */
+        /**
+         * Default field values declared in the class, used to reset props on update.
+         * @internal
+         */
         this._defaults = {};
-        /** @internal — set to true by @State on any write; cleared by renderer after each re-render */
+        /**
+         * Set to `true` by `@State` on any write; cleared by the renderer after each re-render.
+         * @internal
+         */
         this._stateDirty = false;
     }
-    _setProps(props) {
-        Object.keys(this._rawProps).forEach((k) => {
-            Reflect.deleteProperty(this._rawProps, k);
-        });
-        Object.assign(this._rawProps, props);
+    /**
+     * Raw props. Use `@Prop()` fields instead of reading this directly in user code.
+     * @internal
+     */
+    get props() {
+        return this._rawProps;
     }
 }
 //# sourceMappingURL=stateful.js.map

package/dist/component/stateful.js.map

@@ -1 +1 @@
-{"version":3,"file":"stateful.js","sourceRoot":"","sources":["../../src/component/stateful.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAEvC,MAAM,OAAgB,iBAAkB,SAAQ,aAE/C;IAFD;;QAGE,4CAA4C;QACnC,cAAS,GAA4B,EAAE,CAAC;QAEjD,+FAA+F;QAC/F,gBAAW,GAAG,KAAK,CAAC;IAQtB,CAAC;IANC,SAAS,CAAC,KAA8B;QACtC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE;YACxC,OAAO,CAAC,cAAc,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC;QAC5C,CAAC,CAAC,CAAC;QACH,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;IACvC,CAAC;CACF"}
+{"version":3,"file":"stateful.js","sourceRoot":"","sources":["../../src/component/stateful.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAEvC,MAAM,OAAgB,iBAAkB,SAAQ,aAE/C;IAFD;;QAGE;;;WAGG;QACM,cAAS,GAA4B,EAAE,CAAC;QAEjD;;;WAGG;QACH,gBAAW,GAAG,KAAK,CAAC;IAStB,CAAC;IAPC;;;OAGG;IACH,IAAa,KAAK;QAChB,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;CACF"}

package/dist/component/stateless.d.ts

@@ -4,7 +4,8 @@ type StatelessComponentType<T> = T & {
     children?: Children;
 };
 export declare abstract class StatelessComponent<T extends object = Record<never, never>> extends RootComponent<StatelessComponentType<T>> {
-    _setProps(props: Record<string, unknown>): void;
+    /** Public props API for presentational components — see `RootComponent.props`. */
+    get props(): StatelessComponentType<T>;
 }
 export {};
 //# sourceMappingURL=stateless.d.ts.map

package/dist/component/stateless.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stateless.d.ts","sourceRoot":"","sources":["../../src/component/stateless.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAEjD,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAEvC,KAAK,sBAAsB,CAAC,CAAC,IAAI,CAAC,GAAG;IAAE,QAAQ,CAAC,EAAE,QAAQ,CAAA;CAAE,CAAC;AAE7D,8BAAsB,kBAAkB,CACtC,CAAC,SAAS,MAAM,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CACvC,SAAQ,aAAa,CAAC,sBAAsB,CAAC,CAAC,CAAC,CAAC;IAChD,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAMzC"}
+{"version":3,"file":"stateless.d.ts","sourceRoot":"","sources":["../../src/component/stateless.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAEjD,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAEvC,KAAK,sBAAsB,CAAC,CAAC,IAAI,CAAC,GAAG;IAAE,QAAQ,CAAC,EAAE,QAAQ,CAAA;CAAE,CAAC;AAE7D,8BAAsB,kBAAkB,CACtC,CAAC,SAAS,MAAM,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CACvC,SAAQ,aAAa,CAAC,sBAAsB,CAAC,CAAC,CAAC,CAAC;IAChD,kFAAkF;IAClF,IAAa,KAAK,IAAI,sBAAsB,CAAC,CAAC,CAAC,CAE9C;CACF"}

package/dist/component/stateless.js

@@ -1,10 +1,8 @@
 import { RootComponent } from "./base";
 export class StatelessComponent extends RootComponent {
-    _setProps(props) {
-        Object.keys(this._rawProps).forEach((k) => {
-            Reflect.deleteProperty(this._rawProps, k);
-        });
-        Object.assign(this._rawProps, props);
+    /** Public props API for presentational components — see `RootComponent.props`. */
+    get props() {
+        return this._rawProps;
     }
 }
 //# sourceMappingURL=stateless.js.map

package/dist/component/stateless.js.map

@@ -1 +1 @@
-{"version":3,"file":"stateless.js","sourceRoot":"","sources":["../../src/component/stateless.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAIvC,MAAM,OAAgB,kBAEpB,SAAQ,aAAwC;IAChD,SAAS,CAAC,KAA8B;QACtC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE;YACxC,OAAO,CAAC,cAAc,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC;QAC5C,CAAC,CAAC,CAAC;QACH,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;IACvC,CAAC;CACF"}
+{"version":3,"file":"stateless.js","sourceRoot":"","sources":["../../src/component/stateless.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAIvC,MAAM,OAAgB,kBAEpB,SAAQ,aAAwC;IAChD,kFAAkF;IAClF,IAAa,KAAK;QAChB,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@praxisjs/core",
-  "version": "1.8.1",
+  "version": "1.8.3",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/src/component/base.ts

@@ -1,17 +1,42 @@
 export abstract class RootComponent<T extends object = Record<string, never>> {
-  /** Props passed by the parent — filled by the renderer when instantiating/updating. */
+  /**
+   * Props passed by the parent — filled by the renderer when instantiating/updating.
+   * @internal
+   */
   readonly _rawProps: T = {} as T;
 
-  /** @internal — becomes `true` after `onMount` fires */
+  /**
+   * Becomes `true` after `onMount` fires.
+   * @internal
+   */
   _mounted = false;
 
-  /** @internal — end comment anchor set by the runtime; used by decorators to locate the parent element */
+  /**
+   * End comment anchor set by the runtime; used by decorators to locate the parent element.
+   * @internal
+   */
   _anchor?: Comment;
 
   constructor(props: T = {} as T) {
     Object.assign(this._rawProps, props);
   }
 
+  /**
+   * Replaces the current props with a new set; called by the renderer on every parent re-render.
+   * @internal
+   */
+  _setProps(props: Record<string, unknown>) {
+    Object.keys(this._rawProps).forEach((k) => {
+      Reflect.deleteProperty(this._rawProps, k);
+    });
+    Object.assign(this._rawProps, props);
+  }
+
+  /**
+   * Raw props, typed. `StatelessComponent` re-exposes this as its public
+   * props API; on `StatefulComponent` it's internal — use `@Prop()` instead.
+   * @internal
+   */
   get props(): T {
     return this._rawProps;
   }

package/src/component/stateful.ts

@@ -3,16 +3,23 @@ import { RootComponent } from "./base";
 export abstract class StatefulComponent extends RootComponent<
   Record<string, unknown>
 > {
-  /** Default values declared in the class. */
+  /**
+   * Default field values declared in the class, used to reset props on update.
+   * @internal
+   */
   readonly _defaults: Record<string, unknown> = {};
 
-  /** @internal — set to true by @State on any write; cleared by renderer after each re-render */
+  /**
+   * Set to `true` by `@State` on any write; cleared by the renderer after each re-render.
+   * @internal
+   */
   _stateDirty = false;
 
-  _setProps(props: Record<string, unknown>) {
-    Object.keys(this._rawProps).forEach((k) => {
-      Reflect.deleteProperty(this._rawProps, k);
-    });
-    Object.assign(this._rawProps, props);
+  /**
+   * Raw props. Use `@Prop()` fields instead of reading this directly in user code.
+   * @internal
+   */
+  override get props(): Record<string, unknown> {
+    return this._rawProps;
   }
 }

package/src/component/stateless.ts

@@ -7,10 +7,8 @@ type StatelessComponentType<T> = T & { children?: Children };
 export abstract class StatelessComponent<
   T extends object = Record<never, never>,
 > extends RootComponent<StatelessComponentType<T>> {
-  _setProps(props: Record<string, unknown>) {
-    Object.keys(this._rawProps).forEach((k) => {
-      Reflect.deleteProperty(this._rawProps, k);
-    });
-    Object.assign(this._rawProps, props);
+  /** Public props API for presentational components — see `RootComponent.props`. */
+  override get props(): StatelessComponentType<T> {
+    return this._rawProps;
   }
 }