@zcomponent/core 1.14.3 → 1.16.0-beta

package/lib/animation/clips/clip.js

@@ -3,12 +3,30 @@ import { ClipTrack } from '../tracks/cliptrack';
 import { FunctionTrack } from '../tracks/functiontrack';
 import { PropertyTrack } from '../tracks/propertytrack';
 import { StreamTrack } from '../tracks/streamtrack';
+/**
+ * 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 class Clip {
+    /**
+     * 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, length, scriptName, id) {
         this.animation = animation;
         this.length = length;
         this.scriptName = scriptName;
         this.id = id;
+        /** @internal */
         this.influencedPathsDirty = new Observable(false);
         /** @internal */
         this._streamTracks = [];
@@ -25,6 +43,15 @@ export class Clip {
         if (scriptName)
             this.animation.clips[scriptName] = this;
     }
+    /**
+     * 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, p, valueBefore, parentWeight) {
         const tracks = this.tracksByPath.get(p);
         if (!tracks)
@@ -34,6 +61,11 @@ export class Clip {
         }
         return valueBefore;
     }
+    /**
+     * Adds a track to the clip and updates the influenced paths.
+     *
+     * @param t The track to be added.
+     */
     addTrack(t) {
         this._tracks.push(t);
         t.influencedPathsDirty.addListener(this._dirty);
@@ -42,6 +74,9 @@ export class Clip {
         if (t instanceof StreamTrack || t instanceof ClipTrack || t instanceof FunctionTrack)
             this._streamTracks.push(t);
     }
+    /**
+     * Clears all tracks from the clip and resets influenced paths.
+     */
     clearTracks() {
         const existingPaths = this._influencedPaths;
         for (const track of this._tracks) {
@@ -53,6 +88,11 @@ export class Clip {
         this._streamTracks = [];
         this.animation.evaluateTouchedPaths(existingPaths);
     }
+    /**
+     * Getter for the mapping of tracks by path.
+     *
+     * @returns A map of paths to their respective tracks.
+     */
     get tracksByPath() {
         if (!this._tracksByPathDirty)
             return this._tracksByPath;
@@ -68,6 +108,11 @@ export class Clip {
         this._tracksByPathDirty = false;
         return this._tracksByPath;
     }
+    /**
+     * Getter for the list of paths influenced by the clip's tracks.
+     *
+     * @returns An array of influenced paths.
+     */
     get influencedPaths() {
         if (!this.influencedPathsDirty.value)
             return this._influencedPaths;
@@ -79,6 +124,11 @@ export class Clip {
         this.influencedPathsDirty.value = false;
         return this._influencedPaths;
     }
+    /**
+     * Applies fading parameters to properties by their path.
+     *
+     * @param props A dictionary of paths and their associated fade parameters.
+     */
     fadePropertiesByPath(props) {
         if (this.defaultFadeParameters) {
             // Replace any existing fade properties with our defaults
@@ -101,6 +151,16 @@ export class Clip {
             }
         }
     }
+    /**
+     * 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, t0, s0, rate, t1 = Infinity) {
         // return this.resolveClipTimeLoops(t, t0, s0, rate, t1)[0];
         if (this.length === 0)
@@ -116,21 +176,29 @@ export class Clip {
             bounded += this.length;
         return bounded;
     }
+    /** @internal */
     streamPause(isActive, active) {
         for (const track of this._streamTracks) {
             track.streamPause(isActive, active);
         }
     }
+    /** @internal */
     streamSeek(t, rate, isActive, active) {
         for (const track of this._streamTracks) {
             track.streamSeek(t, rate, isActive, active);
         }
     }
+    /** @internal */
     streamTick(clipState, t, rate, isActive, active, force = false, stalled = false, parentWeight) {
         for (const track of this._streamTracks) {
             track.streamTick(clipState, t, rate, isActive, active, force, stalled, parentWeight);
         }
     }
+    /**
+     * Determines if any track within the clip is stalled.
+     *
+     * @returns A boolean indicating if the clip is stalled.
+     */
     isStalled() {
         for (const track of this._tracks) {
             if (track.isStalled())

package/lib/animation/interpolate.d.ts

@@ -1,2 +1,19 @@
+/**
+ * Interpolates between two values based on a given proportion.
+ * Supports interpolation of numbers, arrays, or defaults to step interpolation for other types.
+ *
+ * @param a The starting value.
+ * @param b The ending value.
+ * @param prop The proportion for interpolation (0 to 1).
+ * @returns The interpolated value.
+ */
 export declare function interpolate(a: any, b: any, prop: number): any;
+/**
+ * Adds a scaled value to another value, supporting numbers, arrays, or step addition for other types.
+ *
+ * @param a - The base value.
+ * @param b - The value to add, scaled by the proportion.
+ * @param prop - The scaling proportion for the value to add.
+ * @returns The result of adding the scaled value to the base value.
+ */
 export declare function addBlend(a: any, b: any, prop: number): any;

package/lib/animation/interpolate.js

@@ -1,3 +1,12 @@
+/**
+ * Interpolates between two values based on a given proportion.
+ * Supports interpolation of numbers, arrays, or defaults to step interpolation for other types.
+ *
+ * @param a The starting value.
+ * @param b The ending value.
+ * @param prop The proportion for interpolation (0 to 1).
+ * @returns The interpolated value.
+ */
 export function interpolate(a, b, prop) {
     if (typeof a === 'number' && typeof b === 'number')
         return interpNumber(a, b, prop);
@@ -5,12 +14,39 @@ export function interpolate(a, b, prop) {
         return interpArray(a, b, prop);
     return interpStep(a, b, prop);
 }
+/**
+ * Performs linear interpolation between two numbers.
+ *
+ * @param a - The starting number.
+ * @param b - The ending number.
+ * @param prop - The proportion for interpolation (0 to 1).
+ * @returns The interpolated number.
+ */
 function interpNumber(a, b, prop) {
     return (1 - prop) * a + prop * b;
 }
+/**
+ * Performs step interpolation between two values.
+ * Returns the second value if the proportion is greater than 0, otherwise returns the first value.
+ *
+ * @typeParam T - The type of the first value.
+ * @typeParam Q - The type of the second value.
+ * @param a - The first value.
+ * @param b - The second value.
+ * @param prop - The proportion for interpolation.
+ * @returns Either the first or second value based on the proportion.
+ */
 function interpStep(a, b, prop) {
     return prop > 0 ? b : a;
 }
+/**
+ * Performs interpolation between two arrays element-wise.
+ *
+ * @param a - The starting array.
+ * @param b - The ending array.
+ * @param prop - The proportion for interpolation (0 to 1).
+ * @returns An array containing interpolated values.
+ */
 function interpArray(a, b, prop) {
     if (a.length !== b.length)
         return interpStep(a, b, prop);
@@ -20,6 +56,14 @@ function interpArray(a, b, prop) {
     }
     return ret;
 }
+/**
+ * Adds a scaled value to another value, supporting numbers, arrays, or step addition for other types.
+ *
+ * @param a - The base value.
+ * @param b - The value to add, scaled by the proportion.
+ * @param prop - The scaling proportion for the value to add.
+ * @returns The result of adding the scaled value to the base value.
+ */
 export function addBlend(a, b, prop) {
     if (typeof a === 'number' && typeof b === 'number')
         return addBlendNumber(a, b, prop);
@@ -27,12 +71,39 @@ export function addBlend(a, b, prop) {
         return addBlendArray(a, b, prop);
     return addBlendStep(a, b, prop);
 }
+/**
+ * Adds a scaled number to another number.
+ *
+ * @param a - The base number.
+ * @param b - The number to add, scaled by the proportion.
+ * @param prop - The scaling proportion for the number to add.
+ * @returns The sum of the base number and the scaled number.
+ */
 function addBlendNumber(a, b, prop) {
     return a + prop * b;
 }
+/**
+ * Performs step addition between two values.
+ * Returns the second value if the proportion is equal to or greater than 0.5, otherwise returns the first value.
+ *
+ * @typeParam T - The type of the first value.
+ * @typeParam Q - The type of the second value.
+ * @param a - The first value.
+ * @param b - The second value.
+ * @param prop - The proportion for addition.
+ * @returns Either the first or second value based on the proportion.
+ */
 function addBlendStep(a, b, prop) {
     return prop >= 0.5 ? b : a;
 }
+/**
+ * Adds a scaled array to another array element-wise.
+ *
+ * @param a - The base array.
+ * @param b - The array to add, with each element scaled by the proportion.
+ * @param prop - The scaling proportion for the array to add.
+ * @returns An array containing the sum of the base array and the scaled array.
+ */
 function addBlendArray(a, b, prop) {
     if (a.length !== b.length)
         return interpStep(a, b, prop);

package/lib/animation/keyframe.d.ts

@@ -1,8 +1,31 @@
-import { Easing } from "./bezier";
+import { Easing } from './bezier';
+/**
+ * Represents a single keyframe in an animation sequence.
+ * @property {string} id - Unique identifier for the keyframe.
+ * @property {any} v - The value of the property being animated at this keyframe.
+ * @property {number} t - The timestamp of the keyframe in the animation.
+ * @property {string} [label] - Optional label for the keyframe.
+ * @property {Easing} [easing] - Optional easing function to apply between this keyframe and the next.
+ */
 export interface Keyframe {
+    /**
+     * Unique identifier for the keyframe.
+     */
     id: string;
+    /**
+     * The value of the property being animated at this keyframe.
+     */
     v: any;
+    /**
+     * The timestamp of the keyframe in the animation.
+     */
     t: number;
+    /**
+     * Optional label for the keyframe.
+     */
     label?: string;
+    /**
+     * Optional easing function to apply between this keyframe and the next.
+     */
     easing?: Easing;
 }

package/lib/animation/layer.d.ts

@@ -3,34 +3,98 @@ import { Animation } from './animation';
 import { AnimationState } from './animationstate';
 import { Easing } from './bezier';
 import { LayerClip, LayerClipPlayOptions } from './layerclip';
+/**
+ * Defines the parameters for a fade effect.
+ *
+ * @interface
+ * @property time - The duration of the fade effect in seconds.
+ * @property pin - Optional. This value (between 0 and 1) indicates if this fade takes place at the beginning (0), middle (0.5) or end (1) of the transition.
+ * @property easing - Optional. The easing function to be used for the fade effect.
+ * @property reverse - Optional. A boolean indicating if the fade effect should be reversed.
+ */
 export interface FadeParameters {
     time: number;
     pin?: number;
     easing?: Easing;
     reverse?: boolean;
 }
+/**
+ * Represents a layer within an animation. Manages a collection of LayerClips and their playback within the layer.
+ * Supports queuing of clips, computation of path properties, and handling fade parameters.
+ */
 export declare class Layer {
     readonly animation: Animation;
     readonly scriptName?: string | undefined;
     readonly id?: string | undefined;
+    /**
+     * Collection of LayerClips indexed by ID.
+     */
     clips: {
         [id: string]: LayerClip;
     };
+    /**
+     *  Optional default fade parameters for the layer.
+     */
     defaultFadeParameters?: FadeParameters;
+    /**
+     * Observable indicating if the influenced paths are dirty.
+     */
     influencedPathsDirty: Observable<boolean, never>;
     private _influencedPaths;
     private _active;
     private _queue;
     private _layerClips;
+    /**
+     * Creates an instance of Layer.
+     * @param animation - The animation that the layer belongs to.
+     * @param scriptName - Optional. The name of the script that the layer belongs to.
+     * @param id - Optional. The ID of the layer.
+     */
     constructor(animation: Animation, scriptName?: string | undefined, id?: string | undefined);
+    /**
+     * Computes the property value for a given path at a specified time.
+     * Applies fade parameters and clip-specific computations.
+     *
+     * @param t The current time.
+     * @param p The path of the property to compute.
+     * @param valueBefore The initial value of the property before computation.
+     * @returns The computed property value.
+     */
     computePathProperty(t: number, p: string, valueBefore: any): any;
+    /** @internal */
     tick(t: number, touchedPaths: string[]): void;
+    /**
+     * Pauses the currently active LayerClip, if any.
+     */
     pause(): void;
     /** @internal */
     _registerLayerClip(layerClip: LayerClip): void;
+    /**
+     * Queues a LayerClip for playback with optional play options.
+     *
+     * @param layerClip The LayerClip to queue.
+     * @param playOptions Optional play options for the clip.
+     * @returns The created QueueEntry.
+     */
     queue(layerClip: LayerClip | null, playOptions?: LayerClipPlayOptions): QueueEntry;
+    /**
+     * Gets the currently active LayerClip.
+     *
+     * @returns The active LayerClip, if any.
+     */
     get active(): LayerClip | null | undefined;
+    /**
+     * Sets the active LayerClip for the layer.
+     *
+     * @param layerClip The LayerClip to set as active.
+     */
     set active(layerClip: LayerClip | null | undefined);
+    /**
+     * Sets the active LayerClip with optional play options.
+     *
+     * @param layerClip The LayerClip to set as active.
+     * @param playOptions Optional play options for the clip.
+     */
     setActive(layerClip: LayerClip | null, playOptions?: LayerClipPlayOptions): void;
     /** @internal */
     _activateLayerClip(layerClip: LayerClip | null | undefined, playOptions?: LayerClipPlayOptions): void;
@@ -40,9 +104,17 @@ export declare class Layer {
     _serialize(state: AnimationState): void;
     /** @internal */
     _restore(state: AnimationState): void;
+    /**
+     * Gets the set of paths influenced by the layer.
+     *
+     * @returns A set of strings representing the influenced paths.
+     */
     get influencedPaths(): Set<string>;
 }
-/** @internal */
+/**
+ * Represents an entry in the queue of a Layer, containing a LayerClip and related playback options.
+ * @internal
+ */
 export interface QueueEntry {
     layerClip: LayerClip | null;
     playOptions?: LayerClipPlayOptions;

package/lib/animation/layer.js

@@ -3,18 +3,43 @@ import { AnimationEvents } from './animation';
 import { computeEasing } from './bezier';
 import { interpolate } from './interpolate';
 import { StreamState } from './stream';
+/**
+ * Represents a layer within an animation. Manages a collection of LayerClips and their playback within the layer.
+ * Supports queuing of clips, computation of path properties, and handling fade parameters.
+ */
 export class Layer {
+    /**
+     * Creates an instance of Layer.
+     * @param animation - The animation that the layer belongs to.
+     * @param scriptName - Optional. The name of the script that the layer belongs to.
+     * @param id - Optional. The ID of the layer.
+     */
     constructor(animation, scriptName, id) {
         this.animation = animation;
         this.scriptName = scriptName;
         this.id = id;
+        /**
+         * Collection of LayerClips indexed by ID.
+         */
         this.clips = Object.create(null);
+        /**
+         * Observable indicating if the influenced paths are dirty.
+         */
         this.influencedPathsDirty = new Observable(false);
         this._influencedPaths = new Set();
         this._active = null;
         this._queue = [];
         this._layerClips = [];
     }
+    /**
+     * Computes the property value for a given path at a specified time.
+     * Applies fade parameters and clip-specific computations.
+     *
+     * @param t The current time.
+     * @param p The path of the property to compute.
+     * @param valueBefore The initial value of the property before computation.
+     * @returns The computed property value.
+     */
     computePathProperty(t, p, valueBefore) {
         let fadeValue = valueBefore;
         for (let i = 0; i < this._queue.length; i++) {
@@ -35,6 +60,7 @@ export class Layer {
         }
         return fadeValue;
     }
+    /** @internal */
     tick(t, touchedPaths) {
         for (let i = this._queue.length - 1; i >= 0; i--) {
             const entry = this._queue[i];
@@ -54,6 +80,9 @@ export class Layer {
             }
         }
     }
+    /**
+     * Pauses the currently active LayerClip, if any.
+     */
     pause() {
         if (!this._active)
             return;
@@ -70,6 +99,13 @@ export class Layer {
         });
         this.influencedPathsDirty.value = true;
     }
+    /**
+     * Queues a LayerClip for playback with optional play options.
+     *
+     * @param layerClip The LayerClip to queue.
+     * @param playOptions Optional play options for the clip.
+     * @returns The created QueueEntry.
+     */
     queue(layerClip, playOptions) {
         const fadeByPath = {};
         layerClip?.clip?.fadePropertiesByPath(fadeByPath);
@@ -89,13 +125,29 @@ export class Layer {
         this._queue.push(ret);
         return ret;
     }
+    /**
+     * Gets the currently active LayerClip.
+     *
+     * @returns The active LayerClip, if any.
+     */
     get active() {
         return this._active?.layerClip;
     }
+    /**
+     * Sets the active LayerClip for the layer.
+     *
+     * @param layerClip The LayerClip to set as active.
+     */
     set active(layerClip) {
         this._activateLayerClip(layerClip);
         this._evaulate();
     }
+    /**
+     * Sets the active LayerClip with optional play options.
+     *
+     * @param layerClip The LayerClip to set as active.
+     * @param playOptions Optional play options for the clip.
+     */
     setActive(layerClip, playOptions) {
         this._activateLayerClip(layerClip, playOptions);
         this._evaulate();
@@ -181,6 +233,11 @@ export class Layer {
         else
             this._active = entry.active;
     }
+    /**
+     * Gets the set of paths influenced by the layer.
+     *
+     * @returns A set of strings representing the influenced paths.
+     */
     get influencedPaths() {
         if (!this.influencedPathsDirty.value)
             return this._influencedPaths;
@@ -192,6 +249,18 @@ export class Layer {
         return this._influencedPaths;
     }
 }
+/**
+ * Computes the faded value of a property based on the provided parameters and current time.
+ *
+ * @param defaults Default fade parameters.
+ * @param params Specific fade parameters for a path.
+ * @param override Override parameters for fading.
+ * @param t The current time.
+ * @param fadeTime The total fade time.
+ * @param before The value before fading.
+ * @param after The value after fading.
+ * @returns The faded value.
+ */
 function computeFade(defaults, params, override, t, fadeTime, before, after) {
     // TODO further implementation
     const paramTime = override?.time ?? params?.time ?? defaults?.time ?? 0;

package/lib/animation/layerclip.d.ts

@@ -6,15 +6,35 @@ import { AnimationState } from './animationstate';
 import { Clip } from './clips/clip';
 import { Layer } from './layer';
 import { PlayOptions, Stream, StreamState } from './stream';
+/**
+ * Represents a clip within a layer of an animation.
+ * Manages playback, state transitions, and property computations for the clip.
+ *
+ */
 export declare class LayerClip implements Stream {
     readonly layer: Layer;
     readonly clip: Clip;
     readonly scriptName?: string | undefined;
     readonly id?: string | undefined;
+    /**
+     * Default behavior for whether the clip loops when it reaches the end.
+     */
     defaultLoop: boolean;
+    /**
+     * Default speed at which the clip plays.
+     */
     defaultPlaySpeed: number;
+    /**
+     * Indicates if the clip should automatically start playing at the beginning of the animation.
+     */
     playAtStart: boolean;
+    /**
+     * Function providing the current time, used for synchronizing the clip's playback.
+     */
     timeSource: (() => number) | undefined;
+    /**
+     * Reference to the animation that this layer clip is a part of.
+     */
     readonly animation: Animation;
     private _t0;
     private _pauseTime;
@@ -34,25 +54,80 @@ export declare class LayerClip implements Stream {
     onPaused: Event<[LayerClip]>;
     onEnded: Event<[LayerClip]>;
     onLoop: Event<[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: Layer, clip: Clip, scriptName?: string | undefined, id?: string | undefined);
     private _clipDirty;
+    /** @internal */
     tick(touchedPaths: string[], force?: boolean): void;
+    /**
+     * 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: string, valueBefore: any): any;
+    /**
+     * Estimates the remaining time for the clip to finish playing.
+     *
+     * @returns The estimated remaining time in milliseconds.
+     */
     getRemainingTimeEstimate(): number;
     private _getTime;
     private _stateUpdate;
+    /**
+     * Queues the LayerClip for playback with optional play options.
+     *
+     * @param opts Optional play options to customize playback behavior.
+     */
     queue(opts?: LayerClipPlayOptions): void;
+    /**
+     * @returns The length of the clip.
+     */
     length(): number;
+    /**
+     * Plays the clip, optionally with specified play options.
+     *
+     * @param opts Optional play options to customize playback behavior.
+     */
     play(opts?: LayerClipPlayOptions): void;
+    /**
+     * Pauses the playback of the clip.
+     */
     pause(): void;
     private _cancelStall;
+    /**
+     * 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: number, opts?: LayerClipSeekOptions): void;
     /** @internal */
     _serialize(state: AnimationState): void;
     /** @internal */
     _restore(state: AnimationState): void;
+    /**
+     * Gets the current clip time.
+     *
+     * @returns The current time within the clip.
+     */
     get clipTime(): number;
+    /**
+     * Stops the clip's playback.
+     */
     stop(): void;
+    /**
+     * Determines if the clip is currently stalled.
+     *
+     * @returns True if the clip is stalled, false otherwise.
+     */
     isStalled(): boolean;
 }
 export interface LayerClipSeekOptions {