@zcomponent/core 1.14.3 → 1.16.0-beta

package/lib/zcomponent.d.ts

@@ -27,22 +27,54 @@ export interface ZComponentContextConstructorProps {
 export declare class ZComponentContext extends Context {
     zcomponent: ZComponent;
     children: ComponentChildren;
+    /**
+     * Creates an instance of ZComponentContext.
+     * @param contextManager - The current ContextManager
+     * @param props - The constructor properties.
+     */
     constructor(contextManager: ContextManager, props: ZComponentContextConstructorProps);
 }
 export declare class ZComponent<RootType = any> extends Component<RootType> {
     constructorProps: ConstructorProps;
     private _opts;
+    /**
+     * The id of the component.
+     */
     id: string;
+    /**
+     * A map of elements to node IDs.
+     */
     idByElement: Map<any, string>;
+    /**
+     * Object that maps node script names to scripts.
+     */
     nodes: {
         [id: string]: Component | Component[];
     };
+    /**
+     * Map of entites  by ID.
+     */
     entityByID: Map<string, Entity>;
+    /**
+     * A map of entity labels to components.
+     */
     entityByLabel: Map<string, Entity>;
+    /**
+     * A map of node labels to components.
+     */
     nodeByLabel: Map<string, Component<any, ConstructorProps>>;
     private _constructedResolve;
+    /**
+     * A promise that is resolved once construction of this component is complete.
+     */
     constructed: Promise<void>;
+    /**
+     * A boolean indicating if construction of this component is complete.
+     */
     isConstructed: boolean;
+    /**
+     * The animation object for this component.
+     */
     animation: Animation;
     /**
      * @zstreams layerclipids
@@ -53,24 +85,64 @@ export declare class ZComponent<RootType = any> extends Component<RootType> {
     private _nodesById;
     private _behaviorsToInitialize;
     private _constructorPropOverridesByEntityID;
+    /**
+     * Creates an instance of ZComponent.
+     * @param contextManager - The current ContextManager
+     * @param constructorProps  - The constructor properties.
+     * @param _opts - The options for the component.
+     */
     constructor(contextManager: ContextManager, constructorProps: ConstructorProps, _opts: ZComponentOptions);
     private _updateAnimationRegistrations;
     private _animationTick;
     private _constructorForNode;
     private _constructorForBehavior;
+    /**
+     * This function returns the component with the given ID. If the component is not found, it will return undefined.
+     * This function is used to get a component from a node ID, which is a string representation of a node.
+     * The node ID is used to identify a node in the graph.
+     * If a component constructor is passed as `type`, this function will ensure that the node that's returned
+     * is an instance of that component, or return undefined if it is not.
+     */
     resolveNodeID<T extends Component = Component>(id: string, type?: ConstructorForComponent<T>): T | undefined;
+    /**
+     * Resolves an entity ID to an entity instance.
+     *
+     * @param id - The ID of the entity to resolve.
+     * @returns The resolved entity as an instance of T (which extends Entity), or undefined if the entity could not be resolved.
+     * @template T The entity type.
+     */
     resolveEntityID<T extends Entity = Entity>(id: string): T | undefined;
     private _inflateBehaviors;
     private _wrapBehaviors;
     private _wrapFunctionCall;
+    /**
+     * Notifies the component that the properties of certain entities have changed.
+     *
+     * @param entries - A map where the keys are entity IDs and the values are sets of property names.
+     */
     notifyPropsChanged(entries: Map<string, Set<string>>): void;
+    /**
+     * The animation editor will call this function when the user changes
+     * the list of clips in the animation. We need to update the clip
+     * data for each clip that was changed.
+     */
     notifyClipsChanged(clips: Set<string>): void;
     private _initializeOverrides;
     private _initializeConstructorPropOverrides;
     private _initializeComponentProps;
     private _setEntityProp;
     private _setEntityPropPath;
+    /**
+     * Returns the node with the specified ID.
+     */
     _getNodeById(id: string): Component | undefined;
+    /**
+     * Rsolves a stream ID to a stream object. The stream ID is a string that
+     * is constructed from the entity ID of the stream's parent entity, followed by a
+     * period, followed by the name of the stream. This function splits the string into
+     * parts, and then uses the parts to traverse the entity tree until it finds the
+     * named stream.
+     */
     resolveStreamID(id: string): Stream | undefined;
     /**
      * Traverses the component tree starting from the current component,

package/lib/zcomponent.js

@@ -1,3 +1,4 @@
+/* eslint-disable @typescript-eslint/no-this-alias */
 import { Animation } from './animation/index';
 import { shouldBehaviorRunAtDesignTime } from './behavior';
 import { Component } from './component';
@@ -13,6 +14,11 @@ import { EntityPropOverrideType, FunctionCallType } from './data/core';
 import { Observable } from './observable';
 import { setCurrentZComponentConstruction } from './zcomponentconstruction';
 export class ZComponentContext extends Context {
+    /**
+     * Creates an instance of ZComponentContext.
+     * @param contextManager - The current ContextManager
+     * @param props - The constructor properties.
+     */
     constructor(contextManager, props) {
         super(contextManager, props);
         this.zcomponent = props.zcomponent;
@@ -20,17 +26,47 @@ export class ZComponentContext extends Context {
     }
 }
 export class ZComponent extends Component {
+    /**
+     * Creates an instance of ZComponent.
+     * @param contextManager - The current ContextManager
+     * @param constructorProps  - The constructor properties.
+     * @param _opts - The options for the component.
+     */
     constructor(contextManager, constructorProps, _opts) {
         super(contextManager, { ...constructorProps, children: [] });
         this.constructorProps = constructorProps;
         this._opts = _opts;
+        /**
+         * A map of elements to node IDs.
+         */
         this.idByElement = new Map();
+        /**
+         * Object that maps node script names to scripts.
+         */
         this.nodes = {};
+        /**
+         * Map of entites  by ID.
+         */
         this.entityByID = new Map();
+        /**
+         * A map of entity labels to components.
+         */
         this.entityByLabel = new Map();
+        /**
+         * A map of node labels to components.
+         */
         this.nodeByLabel = new Map();
+        /**
+         * A promise that is resolved once construction of this component is complete.
+         */
         this.constructed = new Promise(resolve => (this._constructedResolve = resolve));
+        /**
+         * A boolean indicating if construction of this component is complete.
+         */
         this.isConstructed = false;
+        /**
+         * The animation object for this component.
+         */
         this.animation = new Animation(false);
         /**
          * @zstreams layerclipids
@@ -89,6 +125,11 @@ export class ZComponent extends Component {
         }
         const that = this;
         return class extends construct {
+            /**
+             *  Creates an instance of the component.
+             * @param contextManager - The current ContextManager
+             * @param constructorProps - The constructor properties.
+             */
             constructor(contextManager, constructorProps) {
                 that._opts.onConstructingNode?.(nodeId);
                 const children = constructorProps.children ?? [];
@@ -182,6 +223,12 @@ export class ZComponent extends Component {
             return;
         const that = this;
         return class extends construct {
+            /**
+             * Creates an instance of the behavior.
+             * @param contextManager - The current ContextManager
+             * @param instance - The instance of the component that this behavior is attached to
+             * @param constructorProps - The constructor properties.
+             */
             constructor(contextManager, instance, constructorProps) {
                 constructorProps = {
                     ...constructorProps,
@@ -221,6 +268,13 @@ export class ZComponent extends Component {
             }
         };
     }
+    /**
+     * This function returns the component with the given ID. If the component is not found, it will return undefined.
+     * This function is used to get a component from a node ID, which is a string representation of a node.
+     * The node ID is used to identify a node in the graph.
+     * If a component constructor is passed as `type`, this function will ensure that the node that's returned
+     * is an instance of that component, or return undefined if it is not.
+     */
     resolveNodeID(id, type) {
         const entity = this.entityByID.get(id);
         if (!entity)
@@ -233,6 +287,13 @@ export class ZComponent extends Component {
             return entity;
         return undefined;
     }
+    /**
+     * Resolves an entity ID to an entity instance.
+     *
+     * @param id - The ID of the entity to resolve.
+     * @returns The resolved entity as an instance of T (which extends Entity), or undefined if the entity could not be resolved.
+     * @template T The entity type.
+     */
     resolveEntityID(id) {
         const entity = this.entityByID.get(id);
         if (!entity)
@@ -311,6 +372,11 @@ export class ZComponent extends Component {
                 };
         }
     }
+    /**
+     * Notifies the component that the properties of certain entities have changed.
+     *
+     * @param entries - A map where the keys are entity IDs and the values are sets of property names.
+     */
     notifyPropsChanged(entries) {
         for (const [entityID, propSet] of entries.entries()) {
             const entity = this.entityByID.get(entityID);
@@ -327,6 +393,11 @@ export class ZComponent extends Component {
             }
         }
     }
+    /**
+     * The animation editor will call this function when the user changes
+     * the list of clips in the animation. We need to update the clip
+     * data for each clip that was changed.
+     */
     notifyClipsChanged(clips) {
         for (const clipId of clips.values()) {
             const clip = this.animation.clipByID.get(clipId);
@@ -442,9 +513,19 @@ export class ZComponent extends Component {
             v = this._wrapFunctionCall(v);
         parent[currentKey] = v;
     }
+    /**
+     * Returns the node with the specified ID.
+     */
     _getNodeById(id) {
         return this._nodesById.get(id);
     }
+    /**
+     * Rsolves a stream ID to a stream object. The stream ID is a string that
+     * is constructed from the entity ID of the stream's parent entity, followed by a
+     * period, followed by the name of the stream. This function splits the string into
+     * parts, and then uses the parts to traverse the entity tree until it finds the
+     * named stream.
+     */
     resolveStreamID(id) {
         const parts = id.split('.');
         let obj = this.entityByID.get(parts[0]);

package/lib/zcomponentconstruction.d.ts

@@ -1,3 +1,13 @@
-import { ZComponent } from "./zcomponent";
+import { ZComponent } from './zcomponent';
+/**
+ * Retrieves the current `ZComponent` that is under construction.
+ *
+ * @returns The `ZComponent` currently under construction, or undefined if there isn't one.
+ */
 export declare function getCurrentZComponentConstruction(): ZComponent<any> | undefined;
+/**
+ * Sets the current `ZComponent` that is under construction.
+ *
+ * @param z - The `ZComponent` to set as currently under construction, or undefined to clear the current construction.
+ */
 export declare function setCurrentZComponentConstruction(z: ZComponent | undefined): void;

package/lib/zcomponentconstruction.js

@@ -1,7 +1,17 @@
 let currentZComponentConstruction;
+/**
+ * Retrieves the current `ZComponent` that is under construction.
+ *
+ * @returns The `ZComponent` currently under construction, or undefined if there isn't one.
+ */
 export function getCurrentZComponentConstruction() {
     return currentZComponentConstruction;
 }
+/**
+ * Sets the current `ZComponent` that is under construction.
+ *
+ * @param z - The `ZComponent` to set as currently under construction, or undefined to clear the current construction.
+ */
 export function setCurrentZComponentConstruction(z) {
     currentZComponentConstruction = z;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zcomponent/core",
-  "version": "1.14.3",
+  "version": "1.16.0-beta",
   "description": "The core component model and built-in functionality for Mattercraft.",
   "main": "index.js",
   "types": "index.d.ts",
@@ -23,14 +23,19 @@
     "build": "rm -rf lib && tsc",
     "build-animation-tests": "tsc -p ./tsconfig.test.animation.json",
     "test": "env TS_NODE_PROJECT=\"tsconfig.testing.json\" mocha --es-module-specifier-resolution=node",
-    "watch": "tsc -w"
+    "watch": "tsc -w",
+    "predocs": "tsc",
+    "docs": "typedoc"
   },
   "author": "Zappar Limited",
   "license": "Proprietary",
   "devDependencies": {
     "@types/mocha": "^10.0.1",
+    "@zappar/typedoc-plugin-mattercraft": "^0.0.4",
     "mocha": "^10.2.0",
     "ts-node": "^10.9.1",
+    "typedoc": "^0.24.8",
+    "typedoc-plugin-mdn-links": "^3.1.7",
     "typescript": "^4.9.4"
   },
   "zexports": [