@zcomponent/core 1.14.3 → 1.16.0-beta

package/lib/animation/layerclip.js

@@ -3,14 +3,35 @@ import { Observable } from '../observable';
 import { AnimationEvents } from './animation';
 import { StreamState } from './stream';
 import { resolveClipTimeLoops } from './tracks/track';
+/**
+ * Represents a clip within a layer of an animation.
+ * Manages playback, state transitions, and property computations for the clip.
+ *
+ */
 export class LayerClip {
+    /**
+     * Creates an instance of LayerClip.
+     * @param layer - The layer that this clip belongs to.
+     * @param clip - The clip that this layer clip is based on.
+     * @param scriptName - The name of the script that created this layer clip.
+     * @param id - The ID of the layer clip.
+     */
     constructor(layer, clip, scriptName, id) {
         this.layer = layer;
         this.clip = clip;
         this.scriptName = scriptName;
         this.id = id;
+        /**
+         * Default behavior for whether the clip loops when it reaches the end.
+         */
         this.defaultLoop = false;
+        /**
+         * Default speed at which the clip plays.
+         */
         this.defaultPlaySpeed = 1;
+        /**
+         * Indicates if the clip should automatically start playing at the beginning of the animation.
+         */
         this.playAtStart = false;
         this._t0 = 0;
         this._pauseTime = 0;
@@ -52,6 +73,7 @@ export class LayerClip {
             layer.animation.layerClipByID.set(id, this);
         this.state.addListener(this._stateUpdate);
     }
+    /** @internal */
     tick(touchedPaths, force) {
         const t = this._getTime();
         if (this._stallStartTime !== undefined) {
@@ -85,6 +107,13 @@ export class LayerClip {
                 this.onLoop.emit(this);
         }
     }
+    /**
+     * Computes the property value for a specific path based on the current state of the clip.
+     *
+     * @param p The path of the property to compute.
+     * @param valueBefore The initial value before applying clip-specific computations.
+     * @returns The computed property value.
+     */
     computePathProperty(p, valueBefore) {
         const t = this._getTime();
         const t0 = this._t0 + (t - (this._pauseTime ?? t)) + (t - (this._stallStartTime ?? t));
@@ -93,6 +122,11 @@ export class LayerClip {
         this._lastClipTime = ct;
         return this.clip.computePathProperty(ct ?? 0, p, valueBefore);
     }
+    /**
+     * Estimates the remaining time for the clip to finish playing.
+     *
+     * @returns The estimated remaining time in milliseconds.
+     */
     getRemainingTimeEstimate() {
         const t = this._getTime();
         const t1 = this._t1 + (t - (this._pauseTime ?? t)) + (t - (this._stallStartTime ?? t));
@@ -101,12 +135,25 @@ export class LayerClip {
     _getTime() {
         return Math.floor(this.timeSource?.() ?? this.animation.timeSource?.() ?? performance.now());
     }
+    /**
+     * Queues the LayerClip for playback with optional play options.
+     *
+     * @param opts Optional play options to customize playback behavior.
+     */
     queue(opts) {
         this.layer.queue(this, opts);
     }
+    /**
+     * @returns The length of the clip.
+     */
     length() {
         return this.clip.length;
     }
+    /**
+     * Plays the clip, optionally with specified play options.
+     *
+     * @param opts Optional play options to customize playback behavior.
+     */
     play(opts) {
         if (opts?.speed === 0) {
             this.pause();
@@ -155,6 +202,9 @@ export class LayerClip {
         this._lastLoop = loop;
         this.state.value = this._state;
     }
+    /**
+     * Pauses the playback of the clip.
+     */
     pause() {
         delete this._lastLoop;
         if (this._pauseTime !== undefined || this._state !== StreamState.Playing)
@@ -175,6 +225,12 @@ export class LayerClip {
         delete this._stallStartTime;
         this.stalled.value = false;
     }
+    /**
+     * Seeks to a specific time within the clip and optionally applies fade parameters.
+     *
+     * @param ct The clip time to seek to.
+     * @param opts Optional seek options, including fade parameters.
+     */
     seek(ct, opts) {
         const t = this._getTime();
         this._stopped = false;
@@ -237,9 +293,17 @@ export class LayerClip {
         this._state = entry.state;
         this.state.value = this._state;
     }
+    /**
+     * Gets the current clip time.
+     *
+     * @returns The current time within the clip.
+     */
     get clipTime() {
         return this._lastTickTime !== undefined ? this._lastTickTime : this.defaultPlaySpeed > 0 ? 0 : this.clip.length;
     }
+    /**
+     * Stops the clip's playback.
+     */
     stop() {
         this._stopped = true;
         this._pauseTime = this._t0;
@@ -253,6 +317,11 @@ export class LayerClip {
         this.animation._pendingEvents.push({ evt: AnimationEvents.onLayerClipState, args: [this] });
         this.state.value = this._state;
     }
+    /**
+     * Determines if the clip is currently stalled.
+     *
+     * @returns True if the clip is stalled, false otherwise.
+     */
     isStalled() {
         return this._stallStartTime !== undefined;
     }

package/lib/animation/stream.d.ts

@@ -1,17 +1,59 @@
+/**
+ * Enum representing the different states of a Stream.
+ */
 export declare enum StreamState {
-    'Playing' = "Playing",
-    'Paused' = "Paused",
-    'Ended' = "Ended"
+    Playing = "Playing",
+    Paused = "Paused",
+    Ended = "Ended"
 }
+/**
+ * Interface defining the basic functionality of a Stream.
+ * Streams are typically associated with media playback, such as audio or animation.
+ */
 export interface Stream {
-    play: (opts?: PlayOptions) => void;
-    pause: () => void;
-    seek: (t: number) => void;
-    stop: () => void;
+    /**
+     * Starts or resumes playback of the Stream.
+     *
+     * @param opts Optional playback options to customize behavior.
+     */
+    play(opts?: PlayOptions): void;
+    /**
+     * Pauses playback of the Stream.
+     */
+    pause(): void;
+    /**
+     * Seeks to a specific time within the Stream.
+     *
+     * @param t The time (in milliseconds) to seek to.
+     */
+    seek(t: number): void;
+    /**
+     * Stops playback of the Stream and resets its position.
+     */
+    stop(): void;
+    /**
+     * Optionally defines a method to get the length of the Stream.
+     *
+     * @returns The length of the Stream in milliseconds.
+     */
     length?: () => number | undefined;
+    /**
+     * Optionally defines a method to check if the Stream is currently stalled.
+     *
+     * @returns True if the Stream is stalled, false otherwise.
+     */
     isStalled?: () => boolean;
 }
+/**
+ * Interface defining options for playing a Stream.
+ */
 export interface PlayOptions {
+    /**
+     * Speed multiplier for playback. A value of 1 plays at normal speed.
+     */
     speed?: number;
+    /**
+     * Whether the Stream should loop when it reaches the end.
+     */
     loop?: boolean;
 }

package/lib/animation/stream.js

@@ -1,3 +1,6 @@
+/**
+ * Enum representing the different states of a Stream.
+ */
 export var StreamState;
 (function (StreamState) {
     StreamState["Playing"] = "Playing";

package/lib/animation/tracks/cliptrack.d.ts

@@ -4,6 +4,12 @@ import { Keyframe } from '../keyframe';
 import { LayerClip } from '../layerclip';
 import { StreamState } from '../stream';
 import { Track } from './track';
+/**
+ * Embeds another clip as a track within a clip.
+ *
+ * @param clip The associated clip to embed.
+ * @param id Optional unique identifier for the ClipTrack.
+ */
 export declare class ClipTrack extends Track {
     readonly clip: Clip;
     private _weights;
@@ -14,22 +20,80 @@ export declare class ClipTrack extends Track {
     private _entitiesDirty;
     private _lastTick?;
     private _lastLoopNumber?;
+    /**
+     * Creates an instance of ClipTrack.
+     * @param clip - The associated Clip to embed.
+     * @param id - Optional unique identifier for the ClipTrack.
+     */
     constructor(clip: Clip, id?: string);
+    /**
+     * Getter for the list of paths influenced by the clip's tracks.
+     *
+     * @returns An array of influenced paths.
+     */
     get influencedPaths(): string[];
+    /**
+     * Adds a weight keyframe to the track.
+     *
+     * @param k The keyframe to be added.
+     */
     addWeight(k: Keyframe): void;
+    /**
+     * Sets the weight keyframes for the track using an id-indexed object.
+     *
+     * @param weights An object mapping keyframe IDs to keyframes.
+     */
     setWeightsById(weights: {
         [id: string]: Keyframe;
     }): void;
+    /**
+     * Getter for sorted weight keyframes by their time values.
+     *
+     * @returns A sorted array of keyframes.
+     */
     get sortedWeights(): Keyframe[];
+    /**
+     * Adds a block (ClipTrackEntity) representing an instance of the embedded clip in the timeline.
+     *
+     * @param k The block to be added.
+     */
     addBlock(k: ClipTrackEntity): void;
+    /**
+     * Sets the blocks for the track using an id-indexed object.
+     *
+     * @param blocks An object mapping block IDs to ClipTrackEntities.
+     */
     setBlocksById(weights: {
         [id: string]: ClipTrackEntity;
     }): void;
+    /**
+     * Getter for sorted blocks by their start time.
+     *
+     * @returns A sorted array of ClipTrackEntities.
+     */
     get sortedBlocks(): ClipTrackEntity[];
+    /**
+     * Computes the property value for a given path at a specific time.
+     * Incorporates weights and blocks to determine the final value.
+     *
+     * @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;
+    /** @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;
     private _resolveBlock;
+    /**
+     * Determines if the track is stalled.
+     *
+     * @returns A boolean indicating if the track is stalled.
+     */
     isStalled(): boolean;
 }

package/lib/animation/tracks/cliptrack.js

@@ -1,5 +1,16 @@
 import { resolveClipTimeLoops, resolveKeyframes, resolveKeyframeValue, Track } from './track';
+/**
+ * Embeds another clip as a track within a clip.
+ *
+ * @param clip The associated clip to embed.
+ * @param id Optional unique identifier for the ClipTrack.
+ */
 export class ClipTrack extends Track {
+    /**
+     * Creates an instance of ClipTrack.
+     * @param clip - The associated Clip to embed.
+     * @param id - Optional unique identifier for the ClipTrack.
+     */
     constructor(clip, id) {
         super(clip.animation, id);
         this.clip = clip;
@@ -14,17 +25,37 @@ export class ClipTrack extends Track {
                 this.influencedPathsDirty.value = true;
         });
     }
+    /**
+     * Getter for the list of paths influenced by the clip's tracks.
+     *
+     * @returns An array of influenced paths.
+     */
     get influencedPaths() {
         return this.clip.influencedPaths;
     }
+    /**
+     * Adds a weight keyframe to the track.
+     *
+     * @param k The keyframe to be added.
+     */
     addWeight(k) {
         this._weightsById[k.id] = k;
         this._weightsDirty = true;
     }
+    /**
+     * Sets the weight keyframes for the track using an id-indexed object.
+     *
+     * @param weights An object mapping keyframe IDs to keyframes.
+     */
     setWeightsById(weights) {
         this._weightsById = weights;
         this._weightsDirty = true;
     }
+    /**
+     * Getter for sorted weight keyframes by their time values.
+     *
+     * @returns A sorted array of keyframes.
+     */
     get sortedWeights() {
         if (!this._weightsDirty)
             return this._weights;
@@ -33,14 +64,29 @@ export class ClipTrack extends Track {
         this._weightsDirty = false;
         return this._weights;
     }
+    /**
+     * Adds a block (ClipTrackEntity) representing an instance of the embedded clip in the timeline.
+     *
+     * @param k The block to be added.
+     */
     addBlock(k) {
         this._entitiesById[k.id] = k;
         this._entitiesDirty = true;
     }
+    /**
+     * Sets the blocks for the track using an id-indexed object.
+     *
+     * @param blocks An object mapping block IDs to ClipTrackEntities.
+     */
     setBlocksById(weights) {
         this._entitiesById = weights;
         this._entitiesDirty = true;
     }
+    /**
+     * Getter for sorted blocks by their start time.
+     *
+     * @returns A sorted array of ClipTrackEntities.
+     */
     get sortedBlocks() {
         if (!this._entitiesDirty)
             return this._entities;
@@ -49,6 +95,16 @@ export class ClipTrack extends Track {
         this._entitiesDirty = false;
         return this._entities;
     }
+    /**
+     * Computes the property value for a given path at a specific time.
+     * Incorporates weights and blocks to determine the final value.
+     *
+     * @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, p, valueBefore, parentWeight) {
         let weight = 1;
         const [weightBefore, weightAfter] = resolveKeyframes(this.sortedWeights, t);
@@ -65,9 +121,11 @@ export class ClipTrack extends Track {
         }
         return valueBefore;
     }
+    /** @internal */
     streamPause(isActive, active) {
         this.clip.streamPause(isActive, active);
     }
+    /** @internal */
     streamSeek(t, rate, isActive, active) {
         const blocks = this.sortedBlocks;
         for (let i = blocks.length - 1; i >= 0; i--) {
@@ -79,6 +137,7 @@ export class ClipTrack extends Track {
             return;
         }
     }
+    /** @internal */
     streamTick(clipState, t, rate, isActive, active, force = false, stalled = false, parentWeight) {
         if (force)
             delete this._lastLoopNumber;
@@ -89,7 +148,7 @@ export class ClipTrack extends Track {
             this.clip.streamPause(isActive, active);
         }
         else {
-            const [bt, loopNumber] = resolveClipTimeLoops(t, block.t0, block.s0, block.rate, this.clip.length, (rate * block.rate) < 0, block.t1);
+            const [bt, loopNumber] = resolveClipTimeLoops(t, block.t0, block.s0, block.rate, this.clip.length, rate * block.rate < 0, block.t1);
             if ((t === block.t1 && rate >= +0) || (t === block.t0 && rate < 0)) {
                 this.clip.streamPause(isActive, active);
             }
@@ -113,6 +172,11 @@ export class ClipTrack extends Track {
         }
         return undefined;
     }
+    /**
+     * Determines if the track is stalled.
+     *
+     * @returns A boolean indicating if the track is stalled.
+     */
     isStalled() {
         return this.clip.isStalled();
     }

package/lib/animation/tracks/functiontrack.d.ts

@@ -10,22 +10,82 @@ export interface ResolvedFunctionTrackEntity {
     t0: number;
     args: ByID<any>;
 }
+/**
+ * Manages the execution of functions at specific times during animation playback.
+ * Maintains a sorted list of function entities, allowing for seeking, pausing, and ticking in the animation stream.
+ * Handles looping and track time boundaries, ensuring functions are triggered at the correct moments.
+ *
+ * @param animation The associated Animation instance.
+ */
 export declare class FunctionTrack extends Track {
     readonly animation: Animation;
     private _entities;
     private _entitiesById;
     private _entitiesDirty;
     private _lastTick?;
+    /**
+     *  Creates an instance of FunctionTrack.
+     * @param animation The associated Animation instance.
+     */
     constructor(animation: Animation);
+    /**
+     * Getter for the list of paths influenced by the track.
+     * As this track does not influence any paths, it returns an empty array.
+     *
+     * @returns An empty array.
+     */
     get influencedPaths(): string[];
     computePathProperty(t: number, p: string, valueBefore: any, parentWeight?: number): any;
+    /**
+     * Adds a function entity to the track. Marks the entities list as dirty.
+     *
+     * @param k The ResolvedFunctionTrackEntity to be added.
+     */
     addBlock(k: ResolvedFunctionTrackEntity): void;
+    /**
+     * Sets the function entities for the track using an id-indexed object. Marks the entities list as dirty.
+     *
+     * @param entities An object mapping entity IDs to ResolvedFunctionTrackEntities.
+     */
     setBlocksById(weights: {
         [id: string]: ResolvedFunctionTrackEntity;
     }): void;
+    /**
+     * Getter for sorted function entities by their start time.
+     *
+     * @returns A sorted array of ResolvedFunctionTrackEntities.
+     */
     get sortedBlocks(): ResolvedFunctionTrackEntity[];
+    /**
+     * Seeks to a specific time in the track's stream.
+     * Updates the last tick time to the specified time.
+     *
+     * @param t The time to seek to.
+     * @param rate The rate of play.
+     * @param isActive Indicates if the streaming is active.
+     * @param active The current active LayerClip, null, or undefined.
+     */
     streamSeek(t: number, rate: number, isActive: boolean, active: LayerClip | null | undefined): void;
+    /**
+     * Updates the track's stream based on the current state and time.
+     * Intended to trigger functions at specific times during the animation playback.
+     *
+     * @param clipState The current state of the stream.
+     * @param t The current time.
+     * @param rate The rate of play.
+     * @param isActive Indicates if the streaming is active.
+     * @param active The current active LayerClip, null, or undefined.
+     * @param force Optional flag to force an update.
+     * @param stalled Optional flag indicating if the stream is stalled.
+     * @param parentWeight Optional weight from the parent track.
+     */
     streamTick(clipState: StreamState, t: number, rate: number, isActive: boolean, active: LayerClip | null | undefined, force?: boolean, stalled?: boolean, parentWeight?: number): void;
+    /**
+     * Pauses the streaming of this track. This implementation is a no-op for FunctionTrack.
+     *
+     * @param isActive Indicates if the streaming is active.
+     * @param active The current active LayerClip, null, or undefined.
+     */
     streamPause(isActive: boolean, active: LayerClip | null | undefined): void;
     private _resolveBlocksBetween;
     private _getBoundedT;

package/lib/animation/tracks/functiontrack.js

@@ -1,5 +1,16 @@
 import { Track } from './track';
+/**
+ * Manages the execution of functions at specific times during animation playback.
+ * Maintains a sorted list of function entities, allowing for seeking, pausing, and ticking in the animation stream.
+ * Handles looping and track time boundaries, ensuring functions are triggered at the correct moments.
+ *
+ * @param animation The associated Animation instance.
+ */
 export class FunctionTrack extends Track {
+    /**
+     *  Creates an instance of FunctionTrack.
+     * @param animation The associated Animation instance.
+     */
     constructor(animation) {
         super(animation);
         this.animation = animation;
@@ -7,20 +18,41 @@ export class FunctionTrack extends Track {
         this._entitiesById = {};
         this._entitiesDirty = false;
     }
+    /**
+     * Getter for the list of paths influenced by the track.
+     * As this track does not influence any paths, it returns an empty array.
+     *
+     * @returns An empty array.
+     */
     get influencedPaths() {
         return [];
     }
     computePathProperty(t, p, valueBefore, parentWeight) {
         // n/a
     }
+    /**
+     * Adds a function entity to the track. Marks the entities list as dirty.
+     *
+     * @param k The ResolvedFunctionTrackEntity to be added.
+     */
     addBlock(k) {
         this._entitiesById[k.id] = k;
         this._entitiesDirty = true;
     }
+    /**
+     * Sets the function entities for the track using an id-indexed object. Marks the entities list as dirty.
+     *
+     * @param entities An object mapping entity IDs to ResolvedFunctionTrackEntities.
+     */
     setBlocksById(weights) {
         this._entitiesById = weights;
         this._entitiesDirty = true;
     }
+    /**
+     * Getter for sorted function entities by their start time.
+     *
+     * @returns A sorted array of ResolvedFunctionTrackEntities.
+     */
     get sortedBlocks() {
         if (!this._entitiesDirty)
             return this._entities;
@@ -29,9 +61,31 @@ export class FunctionTrack extends Track {
         this._entitiesDirty = false;
         return this._entities;
     }
+    /**
+     * Seeks to a specific time in the track's stream.
+     * Updates the last tick time to the specified time.
+     *
+     * @param t The time to seek to.
+     * @param rate The rate of play.
+     * @param isActive Indicates if the streaming is active.
+     * @param active The current active LayerClip, null, or undefined.
+     */
     streamSeek(t, rate, isActive, active) {
         this._lastTick = t;
     }
+    /**
+     * Updates the track's stream based on the current state and time.
+     * Intended to trigger functions at specific times during the animation playback.
+     *
+     * @param clipState The current state of the stream.
+     * @param t The current time.
+     * @param rate The rate of play.
+     * @param isActive Indicates if the streaming is active.
+     * @param active The current active LayerClip, null, or undefined.
+     * @param force Optional flag to force an update.
+     * @param stalled Optional flag indicating if the stream is stalled.
+     * @param parentWeight Optional weight from the parent track.
+     */
     streamTick(clipState, t, rate, isActive, active, force = false, stalled = false, parentWeight) {
         // if (clipState !== StreamState.Playing || this._lastTick === undefined) {
         // 	this._lastTick = t;
@@ -50,8 +104,13 @@ export class FunctionTrack extends Track {
         // }
         // this._lastTick = t;
     }
-    streamPause(isActive, active) {
-    }
+    /**
+     * Pauses the streaming of this track. This implementation is a no-op for FunctionTrack.
+     *
+     * @param isActive Indicates if the streaming is active.
+     * @param active The current active LayerClip, null, or undefined.
+     */
+    streamPause(isActive, active) { }
     _resolveBlocksBetween(tstart, tend, rate, clipLength) {
         const blocks = this.sortedBlocks;
         if (rate < 0) {
@@ -63,7 +122,7 @@ export class FunctionTrack extends Track {
         let [bounded, loopNo] = this._getBoundedT(tstart, clipLength, rate);
         const ret = [];
         while (loopNo < loopNoEnd || (loopNo === loopNoEnd && bounded <= boundedEnd)) {
-            const t1 = (loopNoEnd > loopNo) ? Infinity : boundedEnd;
+            const t1 = loopNoEnd > loopNo ? Infinity : boundedEnd;
             for (let i = 0; i < blocks.length; i++) {
                 const b = blocks[i];
                 if (b.t0 >= bounded && b.t0 <= t1) {