@zcomponent/core 1.14.3 → 1.16.0-beta

package/lib/fractionalindexing.js

@@ -1,9 +1,9 @@
 // License: CC0 (no rights reserved).
 // From https://github.com/rocicorp/fractional-indexing
 // This is based on https://observablehq.com/@dgreensp/implementing-fractional-indexing
-export const BASE_62_DIGITS = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
-const SMALLEST_INTEGER = "A00000000000000000000000000";
-const INTEGER_ZERO = "a0";
+export const BASE_62_DIGITS = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
+const SMALLEST_INTEGER = 'A00000000000000000000000000';
+const INTEGER_ZERO = 'a0';
 // `a` may be empty string, `b` is null or non-empty string.
 // `a < b` lexicographically if `b` is non-null.
 // no trailing zeros allowed.
@@ -17,17 +17,17 @@ const INTEGER_ZERO = "a0";
  */
 function midpoint(a, b, digits) {
     if (b != null && a >= b) {
-        throw new Error(a + " >= " + b);
+        throw new Error(a + ' >= ' + b);
     }
-    if (a.slice(-1) === "0" || (b && b.slice(-1) === "0")) {
-        throw new Error("trailing zero");
+    if (a.slice(-1) === '0' || (b && b.slice(-1) === '0')) {
+        throw new Error('trailing zero');
     }
     if (b) {
         // remove longest common prefix.  pad `a` with 0s as we
         // go.  note that we don't need to pad `b`, because it can't
         // end before `a` while traversing the common prefix.
         let n = 0;
-        while ((a[n] || "0") === b[n]) {
+        while ((a[n] || '0') === b[n]) {
             n++;
         }
         if (n > 0) {
@@ -63,7 +63,7 @@ function midpoint(a, b, digits) {
  */
 function validateInteger(int) {
     if (int.length !== getIntegerLength(int[0])) {
-        throw new Error("invalid integer part of order key: " + int);
+        throw new Error('invalid integer part of order key: ' + int);
     }
 }
 /**
@@ -71,14 +71,14 @@ function validateInteger(int) {
  * @return {number}
  */
 function getIntegerLength(head) {
-    if (head >= "a" && head <= "z") {
-        return head.charCodeAt(0) - "a".charCodeAt(0) + 2;
+    if (head >= 'a' && head <= 'z') {
+        return head.charCodeAt(0) - 'a'.charCodeAt(0) + 2;
     }
-    else if (head >= "A" && head <= "Z") {
-        return "Z".charCodeAt(0) - head.charCodeAt(0) + 2;
+    else if (head >= 'A' && head <= 'Z') {
+        return 'Z'.charCodeAt(0) - head.charCodeAt(0) + 2;
     }
     else {
-        throw new Error("invalid order key head: " + head);
+        throw new Error('invalid order key head: ' + head);
     }
 }
 /**
@@ -88,7 +88,7 @@ function getIntegerLength(head) {
 function getIntegerPart(key) {
     const integerPartLength = getIntegerLength(key[0]);
     if (integerPartLength > key.length) {
-        throw new Error("invalid order key: " + key);
+        throw new Error('invalid order key: ' + key);
     }
     return key.slice(0, integerPartLength);
 }
@@ -98,15 +98,15 @@ function getIntegerPart(key) {
  */
 function validateOrderKey(key) {
     if (key === SMALLEST_INTEGER) {
-        throw new Error("invalid order key: " + key);
+        throw new Error('invalid order key: ' + key);
     }
     // getIntegerPart will throw if the first character is bad,
     // or the key is too short.  we'd call it to check these things
     // even if we didn't need the result
     const i = getIntegerPart(key);
     const f = key.slice(i.length);
-    if (f.slice(-1) === "0") {
-        throw new Error("invalid order key: " + key);
+    if (f.slice(-1) === '0') {
+        throw new Error('invalid order key: ' + key);
     }
 }
 // note that this may return null, as there is a largest integer
@@ -117,12 +117,12 @@ function validateOrderKey(key) {
  */
 function incrementInteger(x, digits) {
     validateInteger(x);
-    const [head, ...digs] = x.split("");
+    const [head, ...digs] = x.split('');
     let carry = true;
     for (let i = digs.length - 1; carry && i >= 0; i--) {
         const d = digits.indexOf(digs[i]) + 1;
         if (d === digits.length) {
-            digs[i] = "0";
+            digs[i] = '0';
         }
         else {
             digs[i] = digits[d];
@@ -130,23 +130,23 @@ function incrementInteger(x, digits) {
         }
     }
     if (carry) {
-        if (head === "Z") {
-            return "a0";
+        if (head === 'Z') {
+            return 'a0';
         }
-        if (head === "z") {
+        if (head === 'z') {
             return null;
         }
         const h = String.fromCharCode(head.charCodeAt(0) + 1);
-        if (h > "a") {
-            digs.push("0");
+        if (h > 'a') {
+            digs.push('0');
         }
         else {
             digs.pop();
         }
-        return h + digs.join("");
+        return h + digs.join('');
     }
     else {
-        return head + digs.join("");
+        return head + digs.join('');
     }
 }
 // note that this may return null, as there is a smallest integer
@@ -157,7 +157,7 @@ function incrementInteger(x, digits) {
  */
 function decrementInteger(x, digits) {
     validateInteger(x);
-    const [head, ...digs] = x.split("");
+    const [head, ...digs] = x.split('');
     let borrow = true;
     for (let i = digs.length - 1; borrow && i >= 0; i--) {
         const d = digits.indexOf(digs[i]) - 1;
@@ -170,23 +170,23 @@ function decrementInteger(x, digits) {
         }
     }
     if (borrow) {
-        if (head === "a") {
-            return "Z" + digits.slice(-1);
+        if (head === 'a') {
+            return 'Z' + digits.slice(-1);
         }
-        if (head === "A") {
+        if (head === 'A') {
             return null;
         }
         const h = String.fromCharCode(head.charCodeAt(0) - 1);
-        if (h < "Z") {
+        if (h < 'Z') {
             digs.push(digits.slice(-1));
         }
         else {
             digs.pop();
         }
-        return h + digs.join("");
+        return h + digs.join('');
     }
     else {
-        return head + digs.join("");
+        return head + digs.join('');
     }
 }
 // `a` is an order key or null (START).
@@ -208,7 +208,7 @@ export function generateKeyBetween(a, b, digits = BASE_62_DIGITS) {
         validateOrderKey(b);
     }
     if (a != null && b != null && a >= b) {
-        throw new Error(a + " >= " + b);
+        throw new Error(a + ' >= ' + b);
     }
     if (a == null) {
         if (b == null) {
@@ -217,14 +217,14 @@ export function generateKeyBetween(a, b, digits = BASE_62_DIGITS) {
         const ib = getIntegerPart(b);
         const fb = b.slice(ib.length);
         if (ib === SMALLEST_INTEGER) {
-            return ib + midpoint("", fb, digits);
+            return ib + midpoint('', fb, digits);
         }
         if (ib < b) {
             return ib;
         }
         const res = decrementInteger(ib, digits);
         if (res == null) {
-            throw new Error("cannot decrement any more");
+            throw new Error('cannot decrement any more');
         }
         return res;
     }
@@ -243,7 +243,7 @@ export function generateKeyBetween(a, b, digits = BASE_62_DIGITS) {
     }
     const i = incrementInteger(ia, digits);
     if (i == null) {
-        throw new Error("cannot increment any more");
+        throw new Error('cannot increment any more');
     }
     if (i < b) {
         return i;
@@ -292,9 +292,5 @@ export function generateNKeysBetween(a, b, n, digits = BASE_62_DIGITS) {
     }
     const mid = Math.floor(n / 2);
     const c = generateKeyBetween(a, b, digits);
-    return [
-        ...generateNKeysBetween(a, c, mid, digits),
-        c,
-        ...generateNKeysBetween(c, b, n - mid - 1, digits),
-    ];
+    return [...generateNKeysBetween(a, c, mid, digits), c, ...generateNKeysBetween(c, b, n - mid - 1, digits)];
 }

package/lib/inflate.d.ts

@@ -8,13 +8,81 @@ import { Layer } from './animation/layer';
 import { ByID } from './data';
 import { Bezier } from './animation/bezier';
 import { Keyframe } from './animation/keyframe';
+/**
+ * Creates a track from the provided data.
+ *
+ * This function processes the given track data and creates an appropriate track instance based on the track type.
+ * @param zcomp - The ZComponent instance.
+ * @param anim - The Animation instance to which the track will belong.
+ * @param data - The data object defining the track.
+ * @returns A Track instance if successful, or undefined if the track cannot be created.
+ */
 export declare function createTrackFromData(zcomp: ZComponent, anim: Animation, data: Data.Track): Track | undefined;
+/**
+ * Processes keyframe data to handle easing via bezier curves.
+ *
+ * This function iterates over the provided keyframes and applies bezier curve transformations to keyframes with defined easing properties.
+ * @param keyframes - The object containing keyframe data.
+ * @param beziers - The object containing bezier curve definitions.
+ * @returns A transformed set of keyframes with bezier curves applied.
+ */
 export declare function processKeyframes(keyframes: ByID<Data.Keyframe>, beziers: ByID<Bezier>): {
     [id: string]: Keyframe;
 };
+/**
+ * Creates a Clip instance from provided data.
+ *
+ * This function constructs a new Clip instance using the given data, determining its length either from the data or by calculating it from track keyframes.
+ * @param zcomp - The ZComponent instance.
+ * @param anim - The Animation instance to which the clip will belong.
+ * @param data - The data object defining the clip.
+ * @returns A new Clip instance.
+ */
 export declare function createClipFromData(zcomp: ZComponent, anim: Animation, data: Data.Clip): Clip;
+/**
+ * Updates a Clip instance with data from a Data.Clip object.
+ *
+ * This function modifies an existing Clip instance, updating its properties and tracks based on the provided data.
+ * @param zcomp - The ZComponent instance.
+ * @param clip - The Clip instance to update.
+ * @param data - The data object defining the updates for the clip.
+ */
 export declare function updateClipFromData(zcomp: ZComponent, clip: Clip, data: Data.Clip): void;
+/**
+ * Creates a LayerClip from provided data.
+ *
+ * This function constructs a new LayerClip instance using the given data, setting properties like playback speed, looping, and play-at-start.
+ * @param zcomp - The ZComponent instance.
+ * @param layer - The Layer instance to which the LayerClip will belong.
+ * @param data - The data object defining the LayerClip.
+ * @returns A new LayerClip instance if successful, or undefined if the clip cannot be created.
+ */
 export declare function createLayerClipFromData(zcomp: ZComponent, layer: Layer, data: Data.LayerClip): LayerClip | undefined;
+/**
+ * Creates a Layer from provided data.
+ *
+ * This function constructs a new Layer instance using the given data, setting properties like active state and default fade parameters.
+ * @param zcomp - The ZComponent instance.
+ * @param anim - The Animation instance to which the layer will belong.
+ * @param data - The data object defining the Layer.
+ * @returns A new Layer instance if successful, or undefined if the layer cannot be created.
+ */
 export declare function createLayerFromData(zcomp: ZComponent, anim: Animation, data: Data.Layer): Layer | undefined;
+/**
+ * Populates an Animation instance with tracks from provided data.
+ *
+ * This function iterates over the provided animation data, creating and adding tracks to the animation's clips.
+ * @param zcomp - The ZComponent instance.
+ * @param anim - The Animation instance to populate.
+ * @param data - The data object containing information about the animation.
+ */
 export declare function populateAnimationTracksFromData(zcomp: ZComponent, anim: Animation, data: Data.Animation): void;
+/**
+ * Constructs the structure of an Animation instance from provided data.
+ *
+ * This function builds the structure of an animation, including creating clips, layers, and setting up bezier curves.
+ * @param zcomp - The ZComponent instance.
+ * @param anim - The Animation instance to construct.
+ * @param data - The data object containing information about the animation.
+ */
 export declare function populateAnimationStructureFromData(zcomp: ZComponent, anim: Animation, data: Data.Animation): void;

package/lib/inflate.js

@@ -7,6 +7,15 @@ import { ClipTrack } from './animation/tracks/cliptrack';
 import { Bezier } from './animation/bezier';
 import { StreamTrack } from './animation/tracks/streamtrack';
 import { FunctionTrack } from './animation/tracks/functiontrack';
+/**
+ * Creates a track from the provided data.
+ *
+ * This function processes the given track data and creates an appropriate track instance based on the track type.
+ * @param zcomp - The ZComponent instance.
+ * @param anim - The Animation instance to which the track will belong.
+ * @param data - The data object defining the track.
+ * @returns A Track instance if successful, or undefined if the track cannot be created.
+ */
 export function createTrackFromData(zcomp, anim, data) {
     switch (data.type) {
         case Data.TrackType.Property: {
@@ -63,6 +72,14 @@ export function createTrackFromData(zcomp, anim, data) {
     }
     return undefined;
 }
+/**
+ * Processes keyframe data to handle easing via bezier curves.
+ *
+ * This function iterates over the provided keyframes and applies bezier curve transformations to keyframes with defined easing properties.
+ * @param keyframes - The object containing keyframe data.
+ * @param beziers - The object containing bezier curve definitions.
+ * @returns A transformed set of keyframes with bezier curves applied.
+ */
 export function processKeyframes(keyframes, beziers) {
     let needsNew = false;
     const keyframeArray = Object.values(keyframes);
@@ -97,6 +114,15 @@ export function processKeyframes(keyframes, beziers) {
     }
     return ret;
 }
+/**
+ * Creates a Clip instance from provided data.
+ *
+ * This function constructs a new Clip instance using the given data, determining its length either from the data or by calculating it from track keyframes.
+ * @param zcomp - The ZComponent instance.
+ * @param anim - The Animation instance to which the clip will belong.
+ * @param data - The data object defining the clip.
+ * @returns A new Clip instance.
+ */
 export function createClipFromData(zcomp, anim, data) {
     let length = data.length;
     if (length === undefined) {
@@ -137,6 +163,14 @@ export function createClipFromData(zcomp, anim, data) {
     zcomp.animation.clipByID.set(data.id, ret);
     return ret;
 }
+/**
+ * Resolves fade parameters with bezier curves.
+ *
+ * This function checks if the provided fade parameters include easing and, if so, applies the corresponding bezier curve.
+ * @param fade - The fade parameters, potentially including easing.
+ * @param beziers - The object containing bezier curve definitions.
+ * @returns The resolved fade parameters.
+ */
 function resolvedFadeParameters(fade, beziers) {
     if (!fade?.easing)
         return fade;
@@ -148,6 +182,14 @@ function resolvedFadeParameters(fade, beziers) {
         easing: bezier,
     };
 }
+/**
+ * Updates a Clip instance with data from a Data.Clip object.
+ *
+ * This function modifies an existing Clip instance, updating its properties and tracks based on the provided data.
+ * @param zcomp - The ZComponent instance.
+ * @param clip - The Clip instance to update.
+ * @param data - The data object defining the updates for the clip.
+ */
 export function updateClipFromData(zcomp, clip, data) {
     clip.defaultFadeParameters = resolvedFadeParameters(data.defaultFadeParameters, zcomp.animation.curves);
     clip.length = data.length;
@@ -170,6 +212,15 @@ export function updateClipFromData(zcomp, clip, data) {
             clip.addTrack(instance);
     }
 }
+/**
+ * Creates a LayerClip from provided data.
+ *
+ * This function constructs a new LayerClip instance using the given data, setting properties like playback speed, looping, and play-at-start.
+ * @param zcomp - The ZComponent instance.
+ * @param layer - The Layer instance to which the LayerClip will belong.
+ * @param data - The data object defining the LayerClip.
+ * @returns A new LayerClip instance if successful, or undefined if the clip cannot be created.
+ */
 export function createLayerClipFromData(zcomp, layer, data) {
     const clip = zcomp.animation.clipByID.get(data.clipId);
     if (!clip)
@@ -182,6 +233,15 @@ export function createLayerClipFromData(zcomp, layer, data) {
     ret.playAtStart = data.playAtStart ?? false;
     return ret;
 }
+/**
+ * Creates a Layer from provided data.
+ *
+ * This function constructs a new Layer instance using the given data, setting properties like active state and default fade parameters.
+ * @param zcomp - The ZComponent instance.
+ * @param anim - The Animation instance to which the layer will belong.
+ * @param data - The data object defining the Layer.
+ * @returns A new Layer instance if successful, or undefined if the layer cannot be created.
+ */
 export function createLayerFromData(zcomp, anim, data) {
     const ret = new Layer(anim, data.scriptName, data.id);
     ret.active = undefined;
@@ -199,6 +259,14 @@ export function createLayerFromData(zcomp, anim, data) {
     }
     return ret;
 }
+/**
+ * Populates an Animation instance with tracks from provided data.
+ *
+ * This function iterates over the provided animation data, creating and adding tracks to the animation's clips.
+ * @param zcomp - The ZComponent instance.
+ * @param anim - The Animation instance to populate.
+ * @param data - The data object containing information about the animation.
+ */
 export function populateAnimationTracksFromData(zcomp, anim, data) {
     const clips = resolveClipDependencies(data.clips).reverse();
     for (const clipData of Object.values(clips)) {
@@ -224,6 +292,14 @@ export function populateAnimationTracksFromData(zcomp, anim, data) {
         }
     }
 }
+/**
+ * Constructs the structure of an Animation instance from provided data.
+ *
+ * This function builds the structure of an animation, including creating clips, layers, and setting up bezier curves.
+ * @param zcomp - The ZComponent instance.
+ * @param anim - The Animation instance to construct.
+ * @param data - The data object containing information about the animation.
+ */
 export function populateAnimationStructureFromData(zcomp, anim, data) {
     const clips = resolveClipDependencies(data.clips).reverse();
     for (const clip of Object.values(clips)) {

package/lib/observable.d.ts

@@ -1,4 +1,4 @@
-import { Emitter } from "./emitter";
+import { Emitter } from './emitter';
 type Resolved<T, M> = [T] extends [never] ? M : T;
 /**
  * A class that holds a value and watches it for changes (deeply by default).
@@ -44,8 +44,8 @@ export declare class Observable<Type = never, TypeInternal extends any[] | [] |
      * @param withHandler - A function that will be called when the value (or any of its recursive descendent keys or elements) is changed
      * @param deep - Set to false to only track changes to the top level `value` itself (and not any of its descendent keys or elements)
      */
-    constructor(def: TypeInternal, withHandler?: ((v: TypeInternal) => void), deep?: boolean, callWithImmediately?: boolean);
-    constructor(def: Type, withHandler?: ((v: Type) => void), deep?: boolean, callWithImmediately?: boolean);
+    constructor(def: TypeInternal, withHandler?: (v: TypeInternal) => void, deep?: boolean, callWithImmediately?: boolean);
+    constructor(def: Type, withHandler?: (v: Type) => void, deep?: boolean, callWithImmediately?: boolean);
     /**
      * Access the current value for this Observable. Changing this value (or, unless deep inspection is disabled, its recursive elements and keys) will trigger any registered handlers to be called with the new value.
      *

package/lib/observable.js

@@ -1,4 +1,4 @@
-import { Emitter } from "./emitter";
+import { Emitter } from './emitter';
 /**
  * A class that holds a value and watches it for changes (deeply by default).
  *
@@ -60,7 +60,7 @@ export class Observable extends Emitter {
                     const val = target[p];
                     if (!shouldWrap(val))
                         return val;
-                    if (Array.isArray(target) && p === "splice") {
+                    if (Array.isArray(target) && p === 'splice') {
                         return function (...args) {
                             for (let i = 2; i < args.length; i++) {
                                 args[i] = clone(args[i], true);
@@ -88,8 +88,8 @@ export class Observable extends Emitter {
                     if (changed)
                         that._emitValue();
                     return true;
-                }
-            })
+                },
+            }),
         };
     }
     set value(v) {

package/lib/profile.d.ts

@@ -1,13 +1,40 @@
+/**
+ * The user device type. Can be either desktop or mobile.
+ */
 export declare enum DeviceType {
     DESKTOP = "desktop",
     MOBILE = "mobile"
 }
+/**
+ * A helper class to store the user device type and other profile related information.
+ */
 export declare class Profile {
+    /**
+     * Whether the user is using a desktop device.
+     */
     isDesktop: boolean;
+    /**
+     * Whether the user is muted by default.
+     */
     muteByDefault: boolean;
+    /**
+     * The client language. This is the language of the browser.
+     */
     clientLanguage: string;
+    /**
+     * The URL search parameters from the current window location.
+     */
     urlSearchParams: URLSearchParams;
+    /**
+     * Whether the debug mode is enabled. This is enabled by adding the `debug=true` query parameter to the URL.
+     */
     debugMode: boolean;
+    /**
+     * Creates an instance of Profile.
+     */
     constructor();
+    /**
+     * Returns the user agent type.
+     */
     get userAgent(): DeviceType;
 }

package/lib/profile.js

@@ -1,8 +1,16 @@
+/**
+ * The user device type. Can be either desktop or mobile.
+ */
 export var DeviceType;
 (function (DeviceType) {
     DeviceType["DESKTOP"] = "desktop";
     DeviceType["MOBILE"] = "mobile";
 })(DeviceType || (DeviceType = {}));
+/**
+ * Determines the device type based on the user agent string.
+ *
+ * @returns The detected `DeviceType`.
+ */
 function getDeviceType() {
     const userAgent = window.navigator.userAgent;
     const mobileKeywords = /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i;
@@ -11,15 +19,33 @@ function getDeviceType() {
     }
     return DeviceType.DESKTOP;
 }
+/**
+ * A helper class to store the user device type and other profile related information.
+ */
 export class Profile {
+    /**
+     * Creates an instance of Profile.
+     */
     constructor() {
+        /**
+         * Whether the user is muted by default.
+         */
         this.muteByDefault = false;
+        /**
+         * The client language. This is the language of the browser.
+         */
         this.clientLanguage = window.navigator.language;
+        /**
+         * Whether the debug mode is enabled. This is enabled by adding the `debug=true` query parameter to the URL.
+         */
         this.debugMode = false;
         this.urlSearchParams = new URLSearchParams(window.location.search);
         this.debugMode = this.urlSearchParams.has('debug') && this.urlSearchParams.get('debug') === 'true';
         this.isDesktop = getDeviceType() === DeviceType.DESKTOP;
     }
+    /**
+     * Returns the user agent type.
+     */
     get userAgent() {
         return this.isDesktop ? DeviceType.DESKTOP : DeviceType.MOBILE;
     }