@zcomponent/core 1.14.3 → 1.16.0-beta

package/README.md

@@ -1,7 +1 @@
 # @zcomponent/core
-
-## Tests
-
-- Requires node 16 for ESM support.
-- `npx playwright install`
-- `npm run test`

package/lib/actionbehavior.d.ts

@@ -1,6 +1,6 @@
-import { Behavior } from "./behavior";
-import { Component } from "./component";
-import { ContextManager } from "./context";
+import { Behavior } from './behavior';
+import { Component } from './component';
+import { ContextManager } from './context';
 export interface ActionBehaviorConstructorProps {
     /** @zprop
      * @zvalues events
@@ -12,8 +12,17 @@ export interface ActionBehaviorConstructorProps {
      */
     runAtEditTime: boolean;
 }
+/**
+ * Base class for all behaviors that perform an action in response to an event.
+ */
 export declare abstract class ActionBehavior<ConstructorProps extends ActionBehaviorConstructorProps = ActionBehaviorConstructorProps> extends Behavior<Component> {
     protected constructorProps: ConstructorProps;
+    /**
+     * Creates an instance of ActionBehavior.
+     * @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: ContextManager, instance: Component, constructorProps: ConstructorProps);
     private _updateRegistration;
     private _perform;

package/lib/actionbehavior.js

@@ -1,7 +1,16 @@
-import { Behavior } from "./behavior";
-import { EnvironmentContext, isEditTime } from "./contexts/environmentcontext";
-import { Event } from "./event";
+import { Behavior } from './behavior';
+import { EnvironmentContext, isEditTime } from './contexts/environmentcontext';
+import { Event } from './event';
+/**
+ * Base class for all behaviors that perform an action in response to an event.
+ */
 export class ActionBehavior extends Behavior {
+    /**
+     * Creates an instance of ActionBehavior.
+     * @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) {
         super(contextManager, instance);
         this.constructorProps = constructorProps;

package/lib/animation/animation.d.ts

@@ -11,11 +11,23 @@ export declare enum AnimationEvents {
     onLayerClipActive = "onLayerClipActive",
     onLayerClipState = "onLayerClipState"
 }
+/**
+ * Manages animations through layers, clips, and tracks.
+ * Provides functionality for serialization and restoration of animation states.
+ * Handles adding and removing layers, and controls animation updates via a tick method.
+ * Ensures proper initialization, disposal, and entity property influence, and emits events based on animation progression.
+ */
 export declare class Animation {
     private _initialize;
+    /**
+     * Collection of layers indexed by ID.
+     */
     layers: {
         [id: string]: Layer;
     };
+    /**
+     *  Collection of clips indexed by ID.
+     */
     clips: {
         [id: string]: Clip;
     };
@@ -25,13 +37,31 @@ export declare class Animation {
     onTick: Event<[]>;
     onLayerClipActive: Event<[layerClip: LayerClip]>;
     onLayerClipState: Event<[layerClip: LayerClip]>;
+    /**
+     * Map for quick access to animation elements by ID.
+     */
     clipByID: Map<string, Clip>;
+    /**
+     * Map for quick access to animation elements by ID.
+     */
     layerByID: Map<string, Layer>;
+    /**
+     * Map for quick access to animation elements by ID.
+     */
     layerClipByID: Map<string, LayerClip>;
+    /**
+     * Map for quick access to animation elements by ID.
+     */
     trackByID: Map<string, Track>;
+    /**
+     * Observable indicating whether there are any layers.
+     */
     hasLayers: Observable<boolean, never>;
     private _layers;
     private _spotlightLayer?;
+    /**
+     * Source of time for the animation.
+     */
     timeSource: (() => number) | undefined;
     private _entityPaths;
     private _defaultValuesByPath;
@@ -40,24 +70,86 @@ export declare class Animation {
         evt: AnimationEvents;
         args: any[];
     }[];
+    /**
+     * Creates an instance of Animation.
+     * @param _initialize Whether to initialize the animation. Defaults to true.
+     */
     constructor(_initialize?: boolean);
+    /**
+     * Serializes the current state of the animation.
+     *
+     * @returns The serialized state of the animation.
+     */
     serializeState(): AnimationState;
+    /**
+     * Restores the animation state from a serialized state.
+     *
+     * @param state The serialized state to restore.
+     */
     restoreState(state: AnimationState): void;
+    /**
+     * Disposes of the animation, clearing listeners and internal state.
+     */
     dispose(): void;
+    /**
+     * Adds a new layer to the animation.
+     *
+     * @param l The layer to add.
+     */
     addLayer(l: Layer): void;
+    /**
+     * Inserts a layer at a specified index.
+     *
+     * @param l The layer to insert.
+     * @param indx The index at which to insert the layer.
+     */
     insertLayer(l: Layer, indx: number): void;
+    /**
+     * Removes a layer from the animation.
+     *
+     * @param l The layer to remove.
+     */
     removeLayer(l: Layer): void;
+    /**
+     * Initializes the animation, evaluating paths and preparing state.
+     */
     initialize(): void;
+    /**
+     * Updates the animation state based on the current time.
+     */
     tick(): void;
+    /** @internal */
     registerEntityProperty(path: string, entity: any, property: string | number): void;
+    /**
+     * Evaluates touched paths and updates entity values based on the current time.
+     *
+     * @param paths The paths to evaluate.
+     * @param t Optional current time.
+     */
     evaluateTouchedPaths(paths: string[], t?: number): void;
+    /**
+     * Gets the current spotlight layer.
+     *
+     * @returns The current spotlight layer, if any.
+     */
     get spotlightLayer(): Layer | undefined;
+    /**
+     * Sets the spotlight layer, influencing the rendering of layers.
+     *
+     * @param l The layer to set as the spotlight layer.
+     */
     set spotlightLayer(l: Layer | undefined);
+    /**
+     * Clears cached default values for a specified entity and property.
+     *
+     * @param entityID The ID of the entity.
+     * @param prop The property to clear.
+     */
     clearCachedDefault(entityID: string, prop: string): void;
     private _emitPendingEvents;
+    /**
+     *
+     * Starts the animation, playing clips that are set to play at the start.
+     */
     start(): void;
 }
-export interface EntityPath {
-    entity: any;
-    property: string | number;
-}

package/lib/animation/animation.js

@@ -6,19 +6,50 @@ export var AnimationEvents;
     AnimationEvents["onLayerClipActive"] = "onLayerClipActive";
     AnimationEvents["onLayerClipState"] = "onLayerClipState";
 })(AnimationEvents || (AnimationEvents = {}));
+/**
+ * Manages animations through layers, clips, and tracks.
+ * Provides functionality for serialization and restoration of animation states.
+ * Handles adding and removing layers, and controls animation updates via a tick method.
+ * Ensures proper initialization, disposal, and entity property influence, and emits events based on animation progression.
+ */
 export class Animation {
+    /**
+     * Creates an instance of Animation.
+     * @param _initialize Whether to initialize the animation. Defaults to true.
+     */
     constructor(_initialize = true) {
         this._initialize = _initialize;
+        /**
+         * Collection of layers indexed by ID.
+         */
         this.layers = Object.create(null);
+        /**
+         *  Collection of clips indexed by ID.
+         */
         this.clips = Object.create(null);
         this.curves = Object.create(null);
         this.onTick = new Event();
         this.onLayerClipActive = new Event();
         this.onLayerClipState = new Event();
+        /**
+         * Map for quick access to animation elements by ID.
+         */
         this.clipByID = new Map();
+        /**
+         * Map for quick access to animation elements by ID.
+         */
         this.layerByID = new Map();
+        /**
+         * Map for quick access to animation elements by ID.
+         */
         this.layerClipByID = new Map();
+        /**
+         * Map for quick access to animation elements by ID.
+         */
         this.trackByID = new Map();
+        /**
+         * Observable indicating whether there are any layers.
+         */
         this.hasLayers = new Observable(false);
         this._layers = [];
         this._entityPaths = new Map();
@@ -26,6 +57,11 @@ export class Animation {
         /** @internal */
         this._pendingEvents = [];
     }
+    /**
+     * Serializes the current state of the animation.
+     *
+     * @returns The serialized state of the animation.
+     */
     serializeState() {
         const state = {
             byLayer: {},
@@ -37,17 +73,30 @@ export class Animation {
         this._spotlightLayer?._serialize(state);
         return state;
     }
+    /**
+     * Restores the animation state from a serialized state.
+     *
+     * @param state The serialized state to restore.
+     */
     restoreState(state) {
         for (const layer of this._layers) {
             layer._restore(state);
         }
         this._spotlightLayer?._restore(state);
     }
+    /**
+     * Disposes of the animation, clearing listeners and internal state.
+     */
     dispose() {
         this.onTick.clearListeners();
         this.onLayerClipActive.clearListeners();
         this.onLayerClipState.clearListeners();
     }
+    /**
+     * Adds a new layer to the animation.
+     *
+     * @param l The layer to add.
+     */
     addLayer(l) {
         this._layers.push(l);
         if (!this.hasLayers.value)
@@ -57,6 +106,12 @@ export class Animation {
         if (l.id)
             this.layerByID.set(l.id, l);
     }
+    /**
+     * Inserts a layer at a specified index.
+     *
+     * @param l The layer to insert.
+     * @param indx The index at which to insert the layer.
+     */
     insertLayer(l, indx) {
         this._layers.splice(indx, 0, l);
         if (!this.hasLayers.value)
@@ -66,6 +121,11 @@ export class Animation {
         if (l.id)
             this.layerByID.set(l.id, l);
     }
+    /**
+     * Removes a layer from the animation.
+     *
+     * @param l The layer to remove.
+     */
     removeLayer(l) {
         const indx = this._layers.indexOf(l);
         if (indx >= 0)
@@ -78,12 +138,18 @@ export class Animation {
         if (l.id)
             this.layerByID.delete(l.id);
     }
+    /**
+     * Initializes the animation, evaluating paths and preparing state.
+     */
     initialize() {
         if (this._initialize === true)
             return;
         this._initialize = true;
         this.evaluateTouchedPaths(Object.keys(this._entityPaths));
     }
+    /**
+     * Updates the animation state based on the current time.
+     */
     tick() {
         if (!this._initialize)
             return;
@@ -100,9 +166,16 @@ export class Animation {
         this.evaluateTouchedPaths(touchedPaths, t);
         this.onTick.emit();
     }
+    /** @internal */
     registerEntityProperty(path, entity, property) {
         this._entityPaths.set(path, { entity, property });
     }
+    /**
+     * Evaluates touched paths and updates entity values based on the current time.
+     *
+     * @param paths The paths to evaluate.
+     * @param t Optional current time.
+     */
     evaluateTouchedPaths(paths, t) {
         if (!this._initialize)
             return;
@@ -134,9 +207,19 @@ export class Animation {
         }
         this._emitPendingEvents();
     }
+    /**
+     * Gets the current spotlight layer.
+     *
+     * @returns The current spotlight layer, if any.
+     */
     get spotlightLayer() {
         return this._spotlightLayer;
     }
+    /**
+     * Sets the spotlight layer, influencing the rendering of layers.
+     *
+     * @param l The layer to set as the spotlight layer.
+     */
     set spotlightLayer(l) {
         if (l === this._spotlightLayer)
             return;
@@ -154,6 +237,12 @@ export class Animation {
         if (this.hasLayers.value !== hasLayers)
             this.hasLayers.value = hasLayers;
     }
+    /**
+     * Clears cached default values for a specified entity and property.
+     *
+     * @param entityID The ID of the entity.
+     * @param prop The property to clear.
+     */
     clearCachedDefault(entityID, prop) {
         this._defaultValuesByPath.delete(entityID + '.' + prop);
     }
@@ -165,6 +254,10 @@ export class Animation {
             this[entry.evt].emit(...entry.args);
         }
     }
+    /**
+     *
+     * Starts the animation, playing clips that are set to play at the start.
+     */
     start() {
         for (const layer of this._layers) {
             for (const clip of Object.values(layer.clips)) {

package/lib/animation/animationstate.d.ts

@@ -1,27 +1,77 @@
-import { QueueEntry } from "./layer";
-import { StreamState } from "./stream";
+import { QueueEntry } from './layer';
+import { StreamState } from './stream';
+/**
+ * Defines the structure for storing the state of an animation.
+ * Contains information about the state of layers and layer clips within the animation.
+ */
 export interface AnimationState {
+    /**
+     *  Stores the state of each layer by its ID.
+     */
     byLayer: {
         [id: string]: LayerState;
     };
+    /**
+     *  Stores the state of each layer clip by its ID.
+     */
     byLayerClip: {
         [id: string]: LayerClipState;
     };
+    /**
+     * ptional ID of the spotlight layer, if any.
+     */
     spotlightLayer?: string;
 }
+/**
+ * Represents the state of an individual layer within an animation.
+ */
 export interface LayerState {
+    /**
+     *  Queue state entries for the layer.
+     */
     queue: LayerQueueEntryState[];
+    /**
+     *  Index of the currently active queue entry, if any.
+     */
     active?: number | null;
 }
+/**
+ * Defines the state of a queue entry within a layer.
+ * Excludes the 'layerClip' object itself, instead referencing it by ID.
+ */
 export type LayerQueueEntryState = Omit<QueueEntry, 'layerClip'> & {
     layerClip: string | null | undefined;
 };
+/**
+ * Describes the state of a LayerClip within an animation.
+ */
 export interface LayerClipState {
+    /**
+     *  Start time of the clip.
+     */
     t0: number;
+    /**
+     * End time of the clip, or null to indicate an indefinite duration.
+     */
     t1: number | null;
+    /**
+     *  The time at which the clip was paused, if applicable.
+     */
     pauseTime?: number;
+    /**
+     * Playback rate of the clip.
+     */
     rate: number;
+    /**
+     * Indicates whether the clip is set to loop.
+     */
     loop: boolean;
+    /**
+     * Indicates whether the clip is stopped.
+     */
     stopped: boolean;
+    /**
+     *  The current stream state of the clip.
+     */
     state: StreamState;
 }

package/lib/animation/bezier.d.ts

@@ -1,9 +1,20 @@
-import { Bezier as BezierData, predefinedCurve } from "../data";
+import { Bezier as BezierData, predefinedCurve } from '../data';
 export type Easing = keyof typeof predefinedCurve | null | Bezier;
+/**
+ * Cass to generate and evaluate multiple Bezier curve segments based on provided control points.
+ */
 export declare class Bezier {
     private _curves;
     private _curveEvaluator;
+    /**
+     * Creates an instance of Bezier.
+     * @param _curves An array of control points for each Bezier curve segment.
+     */
     constructor(_curves: BezierData[]);
     evaluate(t: number, epsilon?: number): number;
 }
+/**
+ * Applies easing to a given time value using pre-defined curves, custom Bezier instances, or returns linear progression if no easing is specified.
+ * A cache is implemented to store and reuse Bezier instances for pre-defined easing types to enhance performance.
+ */
 export declare function computeEasing(t: number, easing?: Easing): number;

package/lib/animation/bezier.js

@@ -1,21 +1,13 @@
-import { predefinedCurve } from "../data";
+import { predefinedCurve } from '../data';
 function BezierFactory(p0x, p0y, p1x, p1y, p2x, p2y, p3x, p3y) {
     function sampleCurveX(t) {
-        return (Math.pow(1 - t, 3) * p0x +
-            3 * Math.pow(1 - t, 2) * t * p1x +
-            3 * (1 - t) * t * t * p2x +
-            t * t * t * p3x);
+        return Math.pow(1 - t, 3) * p0x + 3 * Math.pow(1 - t, 2) * t * p1x + 3 * (1 - t) * t * t * p2x + t * t * t * p3x;
     }
     function sampleCurveY(t) {
-        return (Math.pow(1 - t, 3) * p0y +
-            3 * Math.pow(1 - t, 2) * t * p1y +
-            3 * (1 - t) * t * t * p2y +
-            t * t * t * p3y);
+        return Math.pow(1 - t, 3) * p0y + 3 * Math.pow(1 - t, 2) * t * p1y + 3 * (1 - t) * t * t * p2y + t * t * t * p3y;
     }
     function sampleCurveDerivativeX(t) {
-        return (3 * Math.pow(1 - t, 2) * (p1x - p0x) +
-            6 * (1 - t) * t * (p2x - p1x) +
-            3 * t * t * (p3x - p2x));
+        return 3 * Math.pow(1 - t, 2) * (p1x - p0x) + 6 * (1 - t) * t * (p2x - p1x) + 3 * t * t * (p3x - p2x);
     }
     function solveCurveX(x, epsilon) {
         let t2 = x;
@@ -57,7 +49,14 @@ function BezierFactory(p0x, p0y, p1x, p1y, p2x, p2y, p3x, p3y) {
         return sampleCurveY(solveCurveX(x, epsilon));
     };
 }
+/**
+ * Cass to generate and evaluate multiple Bezier curve segments based on provided control points.
+ */
 export class Bezier {
+    /**
+     * Creates an instance of Bezier.
+     * @param _curves An array of control points for each Bezier curve segment.
+     */
     constructor(_curves) {
         this._curves = _curves;
         this._curveEvaluator = [];
@@ -74,6 +73,10 @@ export class Bezier {
     }
 }
 const bezierCache = new Map();
+/**
+ * Applies easing to a given time value using pre-defined curves, custom Bezier instances, or returns linear progression if no easing is specified.
+ * A cache is implemented to store and reuse Bezier instances for pre-defined easing types to enhance performance.
+ */
 export function computeEasing(t, easing) {
     if (easing === null || easing === undefined)
         return 0;

package/lib/animation/clips/clip.d.ts

@@ -7,12 +7,26 @@ import { ClipTrack } from '../tracks/cliptrack';
 import { FunctionTrack } from '../tracks/functiontrack';
 import { StreamTrack } from '../tracks/streamtrack';
 import { Track } from '../tracks/track';
+/**
+ * Represents an animation clip managing a collection of animation tracks within an animation sequence.
+ * Handles adding and clearing tracks, computing property values, and managing streaming content.
+ * Utilizes observables for change notifications and supports identification through optional script names and IDs.
+ *
+ * @param animation The associated Animation instance.
+ * @param length The duration of the clip.
+ * @param scriptName Optional name for script identification.
+ * @param id Optional unique identifier for the clip.
+ */
 export declare class Clip {
     animation: Animation;
     length: number;
     readonly scriptName?: string | undefined;
     readonly id?: string | undefined;
+    /** @internal */
     influencedPathsDirty: Observable<boolean, never>;
+    /**
+     *  Optional default parameters for fading animation properties.
+     */
     defaultFadeParameters?: Partial<Data.FadeParameters>;
     /** @internal */
     _streamTracks: (StreamTrack | ClipTrack | FunctionTrack)[];
@@ -20,19 +34,76 @@ export declare class Clip {
     private _tracksByPath;
     private _tracksByPathDirty;
     private _tracks;
+    /**
+     * Creates an instance of Clip.
+     * @param animation - The associated Animation instance.
+     * @param length - The duration of the clip.
+     * @param scriptName - Optional name for script identification.
+     * @param id - Optional unique identifier for the clip.
+     */
     constructor(animation: Animation, length: number, scriptName?: string | undefined, id?: string | undefined);
+    /**
+     * Computes the property value for a given path at a specific time.
+     *
+     * @param t The time at which to compute the property.
+     * @param p The path of the property to compute.
+     * @param valueBefore The initial value of the property before computation.
+     * @param parentWeight Optional weight from the parent track.
+     * @returns The computed property value.
+     */
     computePathProperty(t: number, p: string, valueBefore: any, parentWeight?: number): any;
+    /**
+     * Adds a track to the clip and updates the influenced paths.
+     *
+     * @param t The track to be added.
+     */
     addTrack(t: Track): void;
+    /**
+     * Clears all tracks from the clip and resets influenced paths.
+     */
     clearTracks(): void;
     private _dirty;
+    /**
+     * Getter for the mapping of tracks by path.
+     *
+     * @returns A map of paths to their respective tracks.
+     */
     get tracksByPath(): Map<string, Track[]>;
+    /**
+     * Getter for the list of paths influenced by the clip's tracks.
+     *
+     * @returns An array of influenced paths.
+     */
     get influencedPaths(): string[];
+    /**
+     * Applies fading parameters to properties by their path.
+     *
+     * @param props A dictionary of paths and their associated fade parameters.
+     */
     fadePropertiesByPath(props: {
         [id: string]: Partial<Data.FadeParameters>;
     }): void;
+    /**
+     * Resolves the clip time considering looping and play rate.
+     *
+     * @param t The current time.
+     * @param t0 The start time.
+     * @param s0 The initial state time.
+     * @param rate The rate of play.
+     * @param t1 Optional end time.
+     * @returns The resolved clip time.
+     */
     resolveClipTime(t: number, t0: number, s0: number, rate: number, t1?: number): number;
+    /** @internal */
     streamPause(isActive: boolean, active: LayerClip | null | undefined): void;
+    /** @internal */
     streamSeek(t: number, rate: number, isActive: boolean, active: LayerClip | null | undefined): void;
+    /** @internal */
     streamTick(clipState: StreamState, t: number, rate: number, isActive: boolean, active: LayerClip | null | undefined, force?: boolean, stalled?: boolean, parentWeight?: number): void;
+    /**
+     * Determines if any track within the clip is stalled.
+     *
+     * @returns A boolean indicating if the clip is stalled.
+     */
     isStalled(): boolean;
 }