@zcomponent/core 1.14.3 → 1.16.0-beta

package/lib/data/change.js

@@ -1,8 +1,20 @@
 import { generateKeyBetween, generateNKeysBetween } from '../fractionalindexing';
 import { EntityPropOverrideType } from './core';
 // Simple memoizing of computed hierarchy
+/**
+ * Represents a map of node IDs to their child node IDs.
+ */
 const computedHierarchies = new Map();
+/**
+ * Represents a map of behavior IDs to their child behavior IDs.
+ */
 const computedBehaviors = new Map();
+/**
+ * Computes and memoizes the hierarchy of nodes.
+ *
+ * @param nodes - A map of node IDs to node data.
+ * @returns The computed hierarchy of nodes.
+ */
 export function computeNodeHierarchy(nodes) {
     let existing = computedHierarchies.get(nodes);
     if (!existing) {
@@ -29,6 +41,12 @@ export function computeNodeHierarchy(nodes) {
     }
     return existing;
 }
+/**
+ * Computes and memoizes the hierarchy of behaviors.
+ *
+ * @param behaviors - A map of behavior IDs to behavior data.
+ * @returns The computed hierarchy of behaviors.
+ */
 export function computeBehaviorHierarchy(behaviors) {
     let existing = computedBehaviors.get(behaviors);
     if (!existing) {
@@ -55,6 +73,12 @@ export function computeBehaviorHierarchy(behaviors) {
     }
     return existing;
 }
+/**
+ * Adds a new node to the specified ZComponentData.
+ *
+ * @param zcomp - The ZComponentData to which the node is added.
+ * @param info - The combined data of the node to be added.
+ */
 export function addNode(zcomp, info) {
     zcomp.nodes[info.data.id] = info.data;
     addNodeLabelToRegister(zcomp, info.data.id);
@@ -62,11 +86,26 @@ export function addNode(zcomp, info) {
     addEntity(zcomp, info.data.id, info);
     computedHierarchies.delete(zcomp.nodes);
 }
+/**
+ * Adds a new behavior to the specified ZComponentData.
+ *
+ * @param zcomp - The ZComponentData to which the behavior is added.
+ * @param info - The combined data of the behavior to be added.
+ */
 export function addBehavior(zcomp, info) {
     zcomp.behaviors[info.data.id] = info.data;
     addEntity(zcomp, info.data.id, info);
     computedBehaviors.delete(zcomp.behaviors);
 }
+/**
+ * Updates a component property in the ZComponentData.
+ *
+ * @param zcomp - The ZComponentData to update.
+ * @param prop - The property name to update.
+ * @param isConstructorProp - Indicates if the property is a constructor property.
+ * @param newValue - The new value for the property.
+ * @param newIsConstructorProp - Indicates if the new value is a constructor property.
+ */
 export function updateComponentProp(zcomp, prop, isConstructorProp, newValue, newIsConstructorProp) {
     if (zcomp.constructorProps === undefined)
         zcomp.constructorProps = {};
@@ -123,14 +162,33 @@ export function addEntityPropOverride(zcomp, o) {
     o.id = idForEntityPropOverride(o);
     zcomp.entityPropOverrides[o.id] = o;
 }
+/**
+ * Deletes an entity property override from the specified ZComponentData.
+ *
+ * @param zcomp - The ZComponentData to update.
+ * @param id - The ID of the EntityPropOverride to delete.
+ */
 export function deleteEntityPropOverride(zcomp, id) {
     if (!zcomp.entityPropOverrides)
         return;
     delete zcomp.entityPropOverrides[id];
 }
+/**
+ * Generates a unique ID for an EntityPropOverride.
+ *
+ * @param override - The EntityPropOverride for which the ID is generated.
+ * @returns The unique ID for the EntityPropOverride.
+ */
 function idForEntityPropOverride(override) {
     return (override.type + ':' + (override.entityPropIsConstructor ? 'constructorprop' : 'prop') + ':' + override.entityID + ':' + override.entityPropPath.join('.'));
 }
+/**
+ * Deep clones the given object.
+ *
+ * @typeParam T - The type of the object to clone.
+ * @param obj - The object to clone.
+ * @returns A deep clone of the object.
+ */
 export function clone(obj) {
     try {
         if (typeof structuredClone !== 'undefined')
@@ -141,6 +199,14 @@ export function clone(obj) {
     }
     return JSON.parse(JSON.stringify(obj));
 }
+/**
+ * Checks if two objects are equal by comparing their JSON string representations.
+ *
+ * @typeParam T - The type of the objects to compare.
+ * @param obj1 - The first object to compare.
+ * @param obj2 - The second object to compare.
+ * @returns True if the objects are equal, otherwise false.
+ */
 export function isEqual(obj1, obj2) {
     return JSON.stringify(obj1) === JSON.stringify(obj2);
 }
@@ -148,6 +214,14 @@ export function addEntity(zcomp, id, info) {
     zcomp.entityProps[id] = info.props;
     zcomp.entityConstructorProps[id] = info.constructorProps;
 }
+/**
+ * Moves nodes to a new parent within the ZComponentData hierarchy.
+ *
+ * @param zcomp - The ZComponentData containing the nodes.
+ * @param nodeIDs - Array of node IDs to be moved.
+ * @param newParentID - The ID of the new parent node.
+ * @param indx - The index at which to insert the nodes in the new parent's child array.
+ */
 export function moveNodes(zcomp, nodeIDs, newParentID, indx) {
     const parent = zcomp.nodes[newParentID];
     if (!parent)
@@ -168,6 +242,12 @@ export function moveNodes(zcomp, nodeIDs, newParentID, indx) {
         node.parent = { id: newParentID, order: newOrders[i] };
     }
 }
+/**
+ * Deletes a node and its child nodes and associated behaviors from ZComponentData.
+ *
+ * @param zcomp - The ZComponentData from which the node will be deleted.
+ * @param id - The ID of the node to delete.
+ */
 export function deleteNode(zcomp, id) {
     // Delete child nodes
     const children = computeNodeHierarchy(zcomp.nodes)[id] ?? [];
@@ -183,11 +263,24 @@ export function deleteNode(zcomp, id) {
     delete zcomp.nodes[id];
     computedHierarchies.delete(zcomp.nodes);
 }
+/**
+ * Deletes a behavior from ZComponentData.
+ *
+ * @param zcomp - The ZComponentData from which the behavior will be deleted.
+ * @param id - The ID of the behavior to delete.
+ */
 export function deleteBehavior(zcomp, id) {
     deleteEntity(zcomp, id);
     delete zcomp.behaviors[id];
     computedBehaviors.delete(zcomp.behaviors);
 }
+/**
+ * Retrieves combined data for a specific node in ZComponentData.
+ *
+ * @param zcomp - The ZComponentData containing the node.
+ * @param id - The ID of the node.
+ * @returns Combined node data or undefined if the node doesn't exist.
+ */
 export function getNodeDataCombined(zcomp, id) {
     const data = zcomp.nodes[id];
     if (!data)
@@ -198,6 +291,13 @@ export function getNodeDataCombined(zcomp, id) {
         constructorProps: zcomp.entityConstructorProps[id] ?? {},
     };
 }
+/**
+ * Retrieves combined data for a specific behavior in ZComponentData.
+ *
+ * @param zcomp - The ZComponentData containing the behavior.
+ * @param id - The ID of the behavior.
+ * @returns Combined behavior data or undefined if the behavior doesn't exist.
+ */
 export function getBehaviorDataCombined(zcomp, id) {
     const data = zcomp.behaviors[id];
     if (!data)
@@ -208,6 +308,14 @@ export function getBehaviorDataCombined(zcomp, id) {
         constructorProps: zcomp.entityConstructorProps[id] ?? {},
     };
 }
+/**
+ * Fixes any duplicate index issues in the node hierarchy.
+ *
+ * @param zcomp - The ZComponentData containing the nodes.
+ * @param hierarchy - The computed hierarchy of nodes.
+ * @param nodeID - The ID of the parent node.
+ * @param indx - The index to start checking for duplicates.
+ */
 export function fixAnyDuplicateIndex(zcomp, hierarchy, nodeID, indx) {
     if (indx < 0)
         return;
@@ -229,6 +337,14 @@ export function fixAnyDuplicateIndex(zcomp, hierarchy, nodeID, indx) {
     const corder = c ? zcomp.nodes[c]?.parent?.order : undefined;
     nodeB.parent.order = generateKeyBetween(nodeA.parent.order, corder ?? null);
 }
+/**
+ * Fixes any duplicate index issues in the behavior hierarchy.
+ *
+ * @param zcomp - The ZComponentData containing the behaviors.
+ * @param behaviors - The computed hierarchy of behaviors.
+ * @param nodeID - The ID of the parent node.
+ * @param indx - The index to start checking for duplicates.
+ */
 export function fixAnyDuplicateBehaviorsIndex(zcomp, behaviors, nodeID, indx) {
     if (indx < 0)
         return;
@@ -250,6 +366,14 @@ export function fixAnyDuplicateBehaviorsIndex(zcomp, behaviors, nodeID, indx) {
     const corder = c ? zcomp.nodes[c]?.parent?.order : undefined;
     behaviorB.parent.order = generateKeyBetween(behaviorA.parent.order, corder ?? null);
 }
+/**
+ * Calculates the order for a node to be placed at a specific index under a parent.
+ *
+ * @param zcomp - The ZComponentData containing the nodes.
+ * @param parentID - The ID of the parent node.
+ * @param indx - The index at which the node is to be placed.
+ * @returns The order string for the node.
+ */
 export function nodeOrderForParentIndex(zcomp, parentID, indx) {
     const computed = computeNodeHierarchy(zcomp.nodes);
     const parentChildren = computed[parentID] ?? [];
@@ -261,6 +385,14 @@ export function nodeOrderForParentIndex(zcomp, parentID, indx) {
     const rightOrder = zcomp.nodes[rightID]?.parent?.order ?? null;
     return generateKeyBetween(leftOrder, rightOrder);
 }
+/**
+ * Calculates the order for a behavior to be placed at a specific index under a parent.
+ *
+ * @param zcomp - The ZComponentData containing the behaviors.
+ * @param parentID - The ID of the parent node.
+ * @param indx - The index at which the behavior is to be placed.
+ * @returns The order string for the behavior.
+ */
 export function behaviorOrderForParentIndex(zcomp, parentID, indx) {
     const computed = computeBehaviorHierarchy(zcomp.behaviors);
     const parentChildren = computed[parentID] ?? [];
@@ -272,6 +404,12 @@ export function behaviorOrderForParentIndex(zcomp, parentID, indx) {
     const rightOrder = zcomp.behaviors[rightID]?.parent?.order ?? null;
     return generateKeyBetween(leftOrder, rightOrder);
 }
+/**
+ * Adds a node's label to the ZComponentData's label register.
+ *
+ * @param zcomp - The ZComponentData to update.
+ * @param id - The ID of the node whose label is to be added.
+ */
 export function addNodeLabelToRegister(zcomp, id) {
     const node = zcomp.nodes[id];
     if (node?.label) {
@@ -282,6 +420,12 @@ export function addNodeLabelToRegister(zcomp, id) {
         zcomp.entitiesByLabel[node.label][node.id] = true;
     }
 }
+/**
+ * Removes a node's label from the ZComponentData's label register.
+ *
+ * @param zcomp - The ZComponentData to update.
+ * @param id - The ID of the node whose label is to be removed.
+ */
 export function removeNodeLabelFromRegister(zcomp, id) {
     const node = zcomp.nodes[id];
     if (!node)
@@ -295,6 +439,12 @@ export function removeNodeLabelFromRegister(zcomp, id) {
         }
     }
 }
+/**
+ * Adds a node's script name to the ZComponentData's script name register.
+ *
+ * @param zcomp - The ZComponentData to update.
+ * @param id - The ID of the node whose script name is to be added.
+ */
 export function addNodeScriptNameToRegister(zcomp, id) {
     const node = zcomp.nodes[id];
     if (node?.scriptName) {
@@ -305,6 +455,12 @@ export function addNodeScriptNameToRegister(zcomp, id) {
         zcomp.entitiesByScriptName[node.scriptName][node.id] = true;
     }
 }
+/**
+ * Removes a node's script name from the ZComponentData's script name register.
+ *
+ * @param zcomp - The ZComponentData to update.
+ * @param id - The ID of the node whose script name is to be removed.
+ */
 export function removeNodeScriptNameFromRegister(zcomp, id) {
     const node = zcomp.nodes[id];
     if (!node)
@@ -318,6 +474,13 @@ export function removeNodeScriptNameFromRegister(zcomp, id) {
         }
     }
 }
+/**
+ * Changes the label of a node in the ZComponentData.
+ *
+ * @param zcomp - The ZComponentData to update.
+ * @param id - The ID of the node whose label is to be changed.
+ * @param newLabel - The new label for the node.
+ */
 export function changeNodeLabel(zcomp, id, newLabel) {
     const node = zcomp.nodes[id];
     if (!node)
@@ -329,6 +492,13 @@ export function changeNodeLabel(zcomp, id, newLabel) {
         node.label = newLabel;
     addNodeLabelToRegister(zcomp, id);
 }
+/**
+ * Changes the script name of a node in the ZComponentData.
+ *
+ * @param zcomp - The ZComponentData to update.
+ * @param id - The ID of the node whose script name is to be changed.
+ * @param newScriptName - The new script name for the node.
+ */
 export function changeNodeScriptName(zcomp, id, newScriptName) {
     const node = zcomp.nodes[id];
     if (!node)
@@ -340,6 +510,12 @@ export function changeNodeScriptName(zcomp, id, newScriptName) {
         node.scriptName = newScriptName;
     addNodeScriptNameToRegister(zcomp, id);
 }
+/**
+ * Deletes an entity and its associated data from ZComponentData.
+ *
+ * @param zcomp - The ZComponentData to update.
+ * @param id - The ID of the entity to delete.
+ */
 export function deleteEntity(zcomp, id) {
     delete zcomp.entityProps[id];
     delete zcomp.entityConstructorProps[id];
@@ -361,6 +537,13 @@ export function deleteEntity(zcomp, id) {
         }
     }
 }
+/**
+ * Iterates over each ancestor of a node and executes a function.
+ *
+ * @param zcomp - The ZComponentData containing the node.
+ * @param id - The ID of the node.
+ * @param fn - The function to execute for each ancestor.
+ */
 export function forEachNodeAncestor(zcomp, id, fn) {
     const node = zcomp.nodes[id];
     if (!node || !node.parent)
@@ -369,6 +552,13 @@ export function forEachNodeAncestor(zcomp, id, fn) {
     forEachNodeAncestor(zcomp, node.parent.id, fn);
 }
 const lastNumberRegex = new RegExp(/[0-9]*$/);
+/**
+ * Generates a unique label for a node in ZComponentData.
+ *
+ * @param zcomp - The ZComponentData to check for existing labels.
+ * @param label - The base label to make unique.
+ * @returns A unique label for the node.
+ */
 export function getUniqueLabel(zcomp, label) {
     lastNumberRegex.lastIndex = 0;
     let startIndex = 1;

package/lib/emitter.d.ts

@@ -1,10 +1,17 @@
+/**
+ * The base class for classes that hold a set of functions to be called in response
+ * to an event or change in value, e.g. Observable and Event.
+ */
 export declare class Emitter<Args extends Array<any> = []> {
-    protected _funcs: [fn: ((...args: Args) => void), priority: number][];
+    protected _funcs: [fn: (...args: Args) => void, priority: number][];
     private _emitting;
     private _toUnbind;
     private _needsSort;
     private _next;
     private _nextFn;
+    /**
+     * Clears all listeners from the event.
+     */
     clearListeners(): void;
     /**
      * Add a new handler function

package/lib/emitter.js

@@ -1,3 +1,7 @@
+/**
+ * The base class for classes that hold a set of functions to be called in response
+ * to an event or change in value, e.g. Observable and Event.
+ */
 export class Emitter {
     constructor() {
         this._funcs = [];
@@ -5,6 +9,9 @@ export class Emitter {
         this._toUnbind = new Set();
         this._needsSort = false;
     }
+    /**
+     * Clears all listeners from the event.
+     */
     clearListeners() {
         this._funcs = [];
         this._needsSort = false;

package/lib/entity.d.ts

@@ -1,8 +1,11 @@
-import { ConstructorForComponent } from "./component";
-import { ContextManager } from "./context";
-import { Event } from "./event";
-import { Observable } from "./observable";
-import { ZComponent } from "./zcomponent";
+import { ConstructorForComponent } from './component';
+import { ContextManager } from './context';
+import { Event } from './event';
+import { Observable } from './observable';
+import { ZComponent } from './zcomponent';
+/**
+ * Base class for all components and behaviors.
+ */
 export declare class Entity {
     readonly contextManager: ContextManager;
     private _registered;
@@ -13,8 +16,21 @@ export declare class Entity {
      * An event that is fired as the last act of this entity being destroyed.
      */
     readonly onDispose: Event<[]>;
+    /**
+     * Creates an instance of Entity.
+     * @param contextManager The current ContextManager
+     */
     constructor(contextManager: ContextManager);
+    /**
+     * Gets the disposed status of the entity.
+     * @returns {boolean} The disposed status.
+     */
     get disposed(): boolean;
+    /**
+     * Sets the disposed status of the entity.
+     * @param {boolean} v - The new disposed status.
+     * @private
+     */
     private set disposed(value);
     /**
      * If `false`, this entity and its children will no longer participate in the experience.
@@ -107,7 +123,16 @@ export declare class Entity {
     dispose(): never;
     private static callSuperDispose;
 }
+/**
+ * Options that can be passed to the `register` function.
+ */
 export interface RegisterOptions {
+    /**
+     * The priority of the handler function.
+     */
     priority?: number;
+    /**
+     * If `true`, the handler function will be bound to the underlying Event or Observable even if this entity is disabled.
+     */
     bindWhenDisabled?: boolean;
 }

package/lib/entity.js

@@ -1,7 +1,14 @@
-import { Event } from "./event";
-import { Observable } from "./observable";
-import { getCurrentZComponentConstruction } from "./zcomponentconstruction";
+import { Event } from './event';
+import { Observable } from './observable';
+import { getCurrentZComponentConstruction } from './zcomponentconstruction';
+/**
+ * Base class for all components and behaviors.
+ */
 export class Entity {
+    /**
+     * Creates an instance of Entity.
+     * @param contextManager The current ContextManager
+     */
     constructor(contextManager) {
         this.contextManager = contextManager;
         this._registered = [];
@@ -68,9 +75,18 @@ export class Entity {
         this._zcomponent = getCurrentZComponentConstruction();
         this.enabledResolved.addListener(this._updateHandlers);
     }
+    /**
+     * Gets the disposed status of the entity.
+     * @returns {boolean} The disposed status.
+     */
     get disposed() {
         return this._disposed;
     }
+    /**
+     * Sets the disposed status of the entity.
+     * @param {boolean} v - The new disposed status.
+     * @private
+     */
     set disposed(v) {
         this._disposed = v;
     }
@@ -91,11 +107,11 @@ export class Entity {
             return this._zcomponent;
         if (this._zcomponent instanceof type)
             return this._zcomponent;
-        throw new Error("getZComponentInstance called in entity passing wrong kind of ZComponent");
+        throw new Error('getZComponentInstance called in entity passing wrong kind of ZComponent');
     }
     register(e, fn, priorityOrOptions) {
-        const priority = (typeof priorityOrOptions === 'number' ? priorityOrOptions : priorityOrOptions?.priority);
-        const bindWhenDisabled = (typeof priorityOrOptions === 'number' ? false : priorityOrOptions?.bindWhenDisabled);
+        const priority = typeof priorityOrOptions === 'number' ? priorityOrOptions : priorityOrOptions?.priority;
+        const bindWhenDisabled = typeof priorityOrOptions === 'number' ? false : priorityOrOptions?.bindWhenDisabled;
         for (const entry of this._registered) {
             if (entry[0] === e && entry[1] === fn)
                 return;
@@ -107,7 +123,7 @@ export class Entity {
     }
     unregister(e, fn) {
         e.removeListener(fn);
-        this._registered = this._registered.filter(entry => (entry[0] !== e || entry[1] !== fn));
+        this._registered = this._registered.filter(entry => entry[0] !== e || entry[1] !== fn);
     }
     /**
      * Destroy this entity, cleaning up any resources that it has created and

package/lib/event.d.ts

@@ -1,5 +1,8 @@
-import { Emitter } from "./emitter";
-import { Observable } from "./observable";
+import { Emitter } from './emitter';
+import { Observable } from './observable';
+/**
+ * An event emitter class used to emit events and register listeners.
+ */
 export declare class Event<Args extends Array<any> = []> extends Emitter<Args> {
     hasListeners: Observable<boolean, never>;
     /**
@@ -8,7 +11,21 @@ export declare class Event<Args extends Array<any> = []> extends Emitter<Args> {
      * @param a - The argument to pass to handler functions.
      */
     emit(...args: Args): void;
+    /**
+     * Clears all listeners from the event. If there are no listeners, it sets `this.hasListeners.value` to `true`.
+     */
     clearListeners(): void;
+    /**
+     * Adds a listener to the event. After adding the listener, it sets `this.hasListeners.value` to `true`.
+     *
+     * @param f - The listener function to add.
+     * @param priority - The priority of the listener. Higher priority listeners are called first.
+     */
     addListener(f: (...args: Args) => void, priority?: number): void;
+    /**
+     * Removes a listener from the event. If there are no more listeners after the removal, it sets `this.hasListeners.value` to `false`.
+     *
+     * @param f - The listener function to remove.
+     */
     removeListener(f: (...args: Args) => void): void;
 }

package/lib/event.js

@@ -1,5 +1,8 @@
-import { Emitter } from "./emitter";
-import { Observable } from "./observable";
+import { Emitter } from './emitter';
+import { Observable } from './observable';
+/**
+ * An event emitter class used to emit events and register listeners.
+ */
 export class Event extends Emitter {
     constructor() {
         super(...arguments);
@@ -13,15 +16,29 @@ export class Event extends Emitter {
     emit(...args) {
         super._emit(...args);
     }
+    /**
+     * Clears all listeners from the event. If there are no listeners, it sets `this.hasListeners.value` to `true`.
+     */
     clearListeners() {
         super.clearListeners();
         if (!this.hasListeners.value)
             this.hasListeners.value = true;
     }
+    /**
+     * Adds a listener to the event. After adding the listener, it sets `this.hasListeners.value` to `true`.
+     *
+     * @param f - The listener function to add.
+     * @param priority - The priority of the listener. Higher priority listeners are called first.
+     */
     addListener(f, priority) {
         super.addListener(f, priority);
         this.hasListeners.value = true;
     }
+    /**
+     * Removes a listener from the event. If there are no more listeners after the removal, it sets `this.hasListeners.value` to `false`.
+     *
+     * @param f - The listener function to remove.
+     */
     removeListener(f) {
         super.removeListener(f);
         if (this._funcs.length === 0 && this.hasListeners.value)