@zcomponent/core 1.14.3 → 1.16.0-beta

package/lib/behaviors/stream/SeekStream.d.ts

@@ -1,7 +1,8 @@
-import { ActionBehavior, ActionBehaviorConstructorProps } from "../../actionbehavior";
-import { Component } from "../../component";
-import { ContextManager } from "../../context";
+import { ActionBehavior, ActionBehaviorConstructorProps } from '../../actionbehavior';
+import { Component } from '../../component';
+import { ContextManager } from '../../context';
 /**
+ * Behavior to seek a specified stream to a specific time.
  * @zbehavior
  * @zicon fast_forward
  * @zgroup Stream Actions
@@ -9,6 +10,7 @@ import { ContextManager } from "../../context";
 export declare class SeekStream extends ActionBehavior {
     private zcomponent;
     /**
+     * The ID of the stream to seek.
      * @zprop
      * @zgroup Stop Settings
      * @zgrouppriority 20
@@ -16,6 +18,7 @@ export declare class SeekStream extends ActionBehavior {
      */
     stream: string | undefined;
     /**
+     * The time in milliseconds to seek to in the stream.
      * @zprop
      * @zgroup Stop Settings
      * @zgrouppriority 20
@@ -23,6 +26,12 @@ export declare class SeekStream extends ActionBehavior {
      * @ztype time-milliseconds
      */
     time: number;
+    /**
+     * Creates an instance of SeekStream.
+     * @param contextManager - The current ContextManager
+     * @param instance - The instance of the component that this behavior is attached to
+     * @param props - The constructor properties.
+     */
     constructor(contextManager: ContextManager, instance: Component, props: ActionBehaviorConstructorProps);
     /** @zprop */
     perform(): void;

package/lib/behaviors/stream/SeekStream.js

@@ -1,15 +1,23 @@
-import { ActionBehavior, } from "../../actionbehavior";
-import { registerBehaviorRunAtDesignTime } from "../../behavior";
+import { ActionBehavior } from '../../actionbehavior';
+import { registerBehaviorRunAtDesignTime } from '../../behavior';
 /**
+ * Behavior to seek a specified stream to a specific time.
  * @zbehavior
  * @zicon fast_forward
  * @zgroup Stream Actions
  */
 export class SeekStream extends ActionBehavior {
+    /**
+     * Creates an instance of SeekStream.
+     * @param contextManager - The current ContextManager
+     * @param instance - The instance of the component that this behavior is attached to
+     * @param props - The constructor properties.
+     */
     constructor(contextManager, instance, props) {
         super(contextManager, instance, props);
         this.zcomponent = this.getZComponentInstance();
         /**
+         * The time in milliseconds to seek to in the stream.
          * @zprop
          * @zgroup Stop Settings
          * @zgrouppriority 20

package/lib/behaviors/stream/StopStream.d.ts

@@ -1,7 +1,8 @@
-import { ActionBehavior, ActionBehaviorConstructorProps } from "../../actionbehavior";
-import { Component } from "../../component";
-import { ContextManager } from "../../context";
+import { ActionBehavior, ActionBehaviorConstructorProps } from '../../actionbehavior';
+import { Component } from '../../component';
+import { ContextManager } from '../../context';
 /**
+ * Behavior to stop a specified stream.
  * @zbehavior
  * @zicon stop_circle
  * @zgroup Stream Actions
@@ -9,12 +10,19 @@ import { ContextManager } from "../../context";
 export declare class StopStream extends ActionBehavior {
     private zcomponent;
     /**
+     * The ID of the stream to be stopped.
      * @zprop
      * @zgroup Stop Settings
      * @zgrouppriority 20
      * @zvalues streamids
      */
     stream: string | undefined;
+    /**
+     * Creates an instance of StopStream.
+     * @param contextManager - The current ContextManager
+     * @param instance - The instance of the component that this behavior is attached to
+     * @param props - The constructor properties.
+     */
     constructor(contextManager: ContextManager, instance: Component, props: ActionBehaviorConstructorProps);
     /** @zprop */
     perform(): void;

package/lib/behaviors/stream/StopStream.js

@@ -1,11 +1,18 @@
-import { ActionBehavior, } from "../../actionbehavior";
-import { registerBehaviorRunAtDesignTime } from "../../behavior";
+import { ActionBehavior } from '../../actionbehavior';
+import { registerBehaviorRunAtDesignTime } from '../../behavior';
 /**
+ * Behavior to stop a specified stream.
  * @zbehavior
  * @zicon stop_circle
  * @zgroup Stream Actions
  */
 export class StopStream extends ActionBehavior {
+    /**
+     * Creates an instance of StopStream.
+     * @param contextManager - The current ContextManager
+     * @param instance - The instance of the component that this behavior is attached to
+     * @param props - The constructor properties.
+     */
     constructor(contextManager, instance, props) {
         super(contextManager, instance, props);
         this.zcomponent = this.getZComponentInstance();

package/lib/component.d.ts

@@ -2,29 +2,86 @@ import { ContextManager } from './context';
 import { Entity } from './entity';
 import { Observable } from './observable';
 import type { Behavior, BehaviorConstructor } from './behavior';
+/**
+ * Type representing the constructor properties of a given component type.
+ *
+ * This type extracts the constructor properties of a component if the component extends from `Component<any, R>`. Otherwise, it results in `never`.
+ * @typeParam ComponentType - The component type to extract the constructor properties from.
+ */
 export type ConstructorPropsOfComponent<ComponentType> = ComponentType extends Component<any, infer R> ? R : never;
+/**
+ * Type representing the constructor function for a component.
+ *
+ * It defines a constructor type for a component given its constructor properties and component type.
+ * @typeParam ConstructorPropsType - The constructor properties type.
+ * @typeParam ComponentType - The type of the component.
+ */
 export type ComponentConstructor<ConstructorPropsType extends ConstructorProps, ComponentType extends Component> = new (props: ConstructorPropsType, contextManager: ContextManager) => ComponentType;
+/**
+ * Type representing a constructor for a specific component.
+ *
+ * It defines a constructor type that takes a context manager and the constructor properties of the component.
+ * @typeParam ComponentType - The component type for which the constructor is defined.
+ */
 export type ConstructorForComponent<ComponentType extends Component = Component> = new (contextManager: ContextManager, props: ComponentType extends Component<any, infer PropsType> ? PropsType : never) => ComponentType;
-export type ComponentChild<ComponentType extends Component> = [ConstructorForComponent<ComponentType>, ComponentType extends Component<any, infer U> ? U : never] | [
-    ConstructorForComponent<ComponentType>,
-    ComponentType extends Component<any, infer U> ? U : never,
-    Observable<ComponentType | undefined>
-];
+/**
+ * Type representing a child of a component.
+ *
+ * It defines a tuple representing a child component, which includes its constructor, properties, and an optional observable reference.
+ * @typeParam ComponentType - The type of the component which the child belongs to.
+ */
+export type ComponentChild<ComponentType extends Component> = [ConstructorForComponent<ComponentType>, ComponentType extends Component<any, infer U> ? U : never] | [ConstructorForComponent<ComponentType>, ComponentType extends Component<any, infer U> ? U : never, Observable<ComponentType | undefined>];
+/**
+ * Type representing an array of component children.
+ *
+ * This type is used to define an array of children for a component, where each child is represented by the `ComponentChild` type.
+ */
 export type ComponentChildren = ComponentChild<Component>[];
+/**
+ * Interface representing the constructor properties of a component.
+ *
+ * This interface defines a standard structure for properties that can be passed to a component's constructor, including an optional `children` property.
+ */
 export interface ConstructorProps {
     [id: string]: any;
     children?: ComponentChildren;
 }
+/**
+ * Base class for all components.
+ *
+ * Components define the different types of nodes you can have in your project.
+ * Each component provides a set of functionalities and properties that you can add as nodes in your project’s Hierarchy, as many times as you like.
+ * While there are many components included with Mattercraft (such as `Box` and `Group`), you can also create your own by extending the Component class.
+ *
+ * @link [custom-components](https://docs.zap.works/mattercraft/scripting/custom-components/)
+ */
 export declare class Component<ElementType = any, ConstructorPropsType extends ConstructorProps = ConstructorProps> extends Entity {
     protected constructorProps?: ConstructorPropsType | undefined;
     /**
      * The raw element(s) that this component exposes
      */
     element?: ElementType;
+    /**
+     * The children of this component.
+     */
     readonly children: Component[];
+    /**
+     * The behaviors attached to this component.
+     */
     readonly behaviors: Behavior[];
+    /**
+     * The parent of this component.
+     */
     parent?: Component;
+    /**
+     * Creates an instance of Component.
+     * @param contextManager The current ContextManager
+     * @param constructorProps - The constructor properties.
+     */
     constructor(contextManager: ContextManager, constructorProps?: ConstructorPropsType | undefined);
+    /**
+     * Constructs the children of this component.
+     */
     constructChildren(children: ComponentChildren, contextManager?: ContextManager): void;
     /**
      * Adds the supplied component instance as a child of this component, removing it from any existing parent.
@@ -41,9 +98,29 @@ export declare class Component<ElementType = any, ConstructorPropsType extends C
      * Removes this component from its parent component.
      */
     remove(): void;
+    /**
+     * Adds a behavior to the component.
+     * @param {Behavior} b - The behavior to add.
+     */
     addBehavior(b: Behavior): void;
+    /**
+     * Removes a behavior from the component.
+     * @param {Behavior} b - The behavior to remove.
+     */
     removeBehavior(b: Behavior): void;
+    /**
+     * Gets a behavior of a specific type from the component.
+     * @param {T} type - The type of behavior to get.
+     * @returns {InstanceType<T> | undefined} The behavior of the specified type, or undefined if no such behavior exists.
+     * @template T The behavior type.
+     */
     getBehavior<T extends BehaviorConstructor>(type: T): InstanceType<T> | undefined;
+    /**
+     * Gets all behaviors of a specific type from the component.
+     * @param {T} type - The type of behaviors to get.
+     * @returns {InstanceType<T>[]} An array of behaviors of the specified type.
+     * @template T The behavior type.
+     */
     getBehaviors<T extends BehaviorConstructor>(type: T): InstanceType<T>[];
     /**
      * An array of the elements that this component instance exposes. In the case that this component
@@ -68,5 +145,8 @@ export declare class Component<ElementType = any, ConstructorPropsType extends C
     readonly tags: Observable<string[], never>;
     private _updateEnabledResolved;
     private _updateTags;
+    /**
+     * Dispose of this component and all of its children.
+     */
     dispose(): never;
 }

package/lib/component.js

@@ -1,11 +1,31 @@
 import { TagContext } from './contexts/tagcontext';
 import { Entity } from './entity';
 import { Observable } from './observable';
+/**
+ * Base class for all components.
+ *
+ * Components define the different types of nodes you can have in your project.
+ * Each component provides a set of functionalities and properties that you can add as nodes in your project’s Hierarchy, as many times as you like.
+ * While there are many components included with Mattercraft (such as `Box` and `Group`), you can also create your own by extending the Component class.
+ *
+ * @link [custom-components](https://docs.zap.works/mattercraft/scripting/custom-components/)
+ */
 export class Component extends Entity {
+    /**
+     * Creates an instance of Component.
+     * @param contextManager The current ContextManager
+     * @param constructorProps - The constructor properties.
+     */
     constructor(contextManager, constructorProps) {
         super(contextManager);
         this.constructorProps = constructorProps;
+        /**
+         * The children of this component.
+         */
         this.children = [];
+        /**
+         * The behaviors attached to this component.
+         */
         this.behaviors = [];
         /**
          * An array of string 'tags' assocated with this component.
@@ -40,6 +60,9 @@ export class Component extends Entity {
         this.register(this.enabled, this._updateEnabledResolved, { bindWhenDisabled: true });
         this.register(this.tags, this._updateTags, { bindWhenDisabled: true });
     }
+    /**
+     * Constructs the children of this component.
+     */
     constructChildren(children, contextManager) {
         contextManager = contextManager ?? this.contextManager;
         for (const [constructor, props, ref] of children) {
@@ -82,20 +105,40 @@ export class Component extends Entity {
     remove() {
         this.parent?.removeChild(this);
     }
+    /**
+     * Adds a behavior to the component.
+     * @param {Behavior} b - The behavior to add.
+     */
     addBehavior(b) {
         this.behaviors.push(b);
     }
+    /**
+     * Removes a behavior from the component.
+     * @param {Behavior} b - The behavior to remove.
+     */
     removeBehavior(b) {
         const indx = this.behaviors.indexOf(b);
         if (indx >= 0)
             this.behaviors.splice(indx, 1);
     }
+    /**
+     * Gets a behavior of a specific type from the component.
+     * @param {T} type - The type of behavior to get.
+     * @returns {InstanceType<T> | undefined} The behavior of the specified type, or undefined if no such behavior exists.
+     * @template T The behavior type.
+     */
     getBehavior(type) {
         for (const behavior of this.behaviors) {
             if (behavior instanceof type)
                 return behavior;
         }
     }
+    /**
+     * Gets all behaviors of a specific type from the component.
+     * @param {T} type - The type of behaviors to get.
+     * @returns {InstanceType<T>[]} An array of behaviors of the specified type.
+     * @template T The behavior type.
+     */
     getBehaviors(type) {
         return this.behaviors.filter(entry => entry instanceof type);
     }
@@ -116,12 +159,17 @@ export class Component extends Entity {
         }
         return ret;
     }
+    /**
+     * Dispose of this component and all of its children.
+     */
     dispose() {
         for (const child of this.children) {
             try {
                 child.dispose();
             }
-            catch (err) { }
+            catch (err) {
+                // Fail silently
+            }
         }
         this.children.length = 0;
         this.contextManager.get(TagContext).unregisterComponent(this);

package/lib/components/Audio.d.ts

@@ -1,8 +1,8 @@
-import { PlayOptions, Stream } from "../animation";
-import { Component } from "../component";
-import { ContextManager } from "../context";
-import { Event } from "../event";
-import { Observable } from "../observable";
+import { PlayOptions, Stream } from '../animation';
+import { Component } from '../component';
+import { ContextManager } from '../context';
+import { Event } from '../event';
+import { Observable } from '../observable';
 export interface AudioConstructorProps {
     /** @zprop
      * @zvalues files *.+(mp3|wav)
@@ -19,6 +19,10 @@ export interface AudioConstructorProps {
     autoplay?: boolean;
 }
 /**
+ * The Audio class represents an audio component that can be controlled.
+ * It provides methods to play, pause, stop, and seek the audio.
+ * It also provides observables for volume and mute state, and events for when the audio ends, stops, pauses, and plays.
+ *
  * @zcomponent
  * @ztag core/audio
  * @zgroup Media
@@ -38,6 +42,11 @@ export declare class Audio extends Component<undefined, AudioConstructorProps> i
     private _playhead;
     private _rate;
     private _session?;
+    /**
+     * Creates a new Audio component.
+     * @param mgr - The current ContextManager
+     * @param props - The constructor properties.
+     */
     constructor(mgr: ContextManager, props: AudioConstructorProps);
     private _load;
     private _updateVolume;

package/lib/components/Audio.js

@@ -1,10 +1,14 @@
-import { Component } from "../component";
-import { AudioContextContext, useAudioContext } from "../contexts/audiocontextcontext";
-import { isDesignTime } from "../contexts/environmentcontext";
-import { registerLoadable, started } from "../contexts/loadcontext";
-import { Event } from "../event";
-import { Observable } from "../observable";
+import { Component } from '../component';
+import { AudioContextContext, useAudioContext } from '../contexts/audiocontextcontext';
+import { isDesignTime } from '../contexts/environmentcontext';
+import { registerLoadable, started } from '../contexts/loadcontext';
+import { Event } from '../event';
+import { Observable } from '../observable';
 /**
+ * The Audio class represents an audio component that can be controlled.
+ * It provides methods to play, pause, stop, and seek the audio.
+ * It also provides observables for volume and mute state, and events for when the audio ends, stops, pauses, and plays.
+ *
  * @zcomponent
  * @ztag core/audio
  * @zgroup Media
@@ -12,6 +16,11 @@ import { Observable } from "../observable";
  * @zstream
  */
 export class Audio extends Component {
+    /**
+     * Creates a new Audio component.
+     * @param mgr - The current ContextManager
+     * @param props - The constructor properties.
+     */
     constructor(mgr, props) {
         super(mgr, props);
         /** @zui */ this.onEnded = new Event();
@@ -92,9 +101,9 @@ export class Audio extends Component {
         source.playbackRate.value = Math.abs(this._rate);
         source.buffer = this._rate < 0 ? this._getReversed(this.audioBuffer) : this.audioBuffer;
         source.connect(this.destination);
-        const startedAt = this.audioContext.currentTime - (resolvedPlayhead / source.playbackRate.value);
+        const startedAt = this.audioContext.currentTime - resolvedPlayhead / source.playbackRate.value;
         source.start(0, resolvedPlayhead);
-        source.addEventListener("ended", () => this.onEnded.emit(this));
+        source.addEventListener('ended', () => this.onEnded.emit(this));
         this._session = { source, startedAt };
         this.onPlay.emit(this);
     }
@@ -130,7 +139,7 @@ export class Audio extends Component {
      * @zui
      */
     seek(/** @ztype time-milliseconds */ t) {
-        let previousSession = this._session;
+        const previousSession = this._session;
         if (previousSession)
             this._pause();
         this._playhead = t / 1000;
@@ -138,7 +147,7 @@ export class Audio extends Component {
             this.play({ speed: this._rate });
     }
     length() {
-        return this.audioBuffer ? (this.audioBuffer.duration * 1000) : undefined;
+        return this.audioBuffer ? this.audioBuffer.duration * 1000 : undefined;
     }
     dispose() {
         this.stop();

package/lib/components/AudioLayerSettings.d.ts

@@ -1,6 +1,6 @@
-import { Component } from "../component";
-import { ContextManager } from "../context";
-import { Observable } from "../observable";
+import { Component } from '../component';
+import { ContextManager } from '../context';
+import { Observable } from '../observable';
 interface AudioLayerSettingsConstuctorProps {
     /**
      * @zprop
@@ -9,12 +9,18 @@ interface AudioLayerSettingsConstuctorProps {
     layer?: string;
 }
 /**
+ * Audio layer settings.
  * @zcomponent
  * @ztag core/audiolayersettings
  * @zgroup Media
  * @zicon volume_up
  */
 export declare class AudioLayerSettings extends Component<undefined, AudioLayerSettingsConstuctorProps> {
+    /**
+     * Creates a new AudioLayerSettings component.
+     * @param contextManager - The current ContextManager
+     * @param props - The constructor properties.
+     */
     constructor(contextManager: ContextManager, props: AudioLayerSettingsConstuctorProps);
     /**
      * @zprop

package/lib/components/AudioLayerSettings.js

@@ -1,13 +1,19 @@
-import { Component } from "../component";
-import { AudioContextContext } from "../contexts/audiocontextcontext";
-import { Observable } from "../observable";
+import { Component } from '../component';
+import { AudioContextContext } from '../contexts/audiocontextcontext';
+import { Observable } from '../observable';
 /**
+ * Audio layer settings.
  * @zcomponent
  * @ztag core/audiolayersettings
  * @zgroup Media
  * @zicon volume_up
  */
 export class AudioLayerSettings extends Component {
+    /**
+     * Creates a new AudioLayerSettings component.
+     * @param contextManager - The current ContextManager
+     * @param props - The constructor properties.
+     */
     constructor(contextManager, props) {
         super(contextManager, props);
         /**

package/lib/components/Children.d.ts

@@ -1,10 +1,15 @@
-import { Component, ConstructorProps } from "../component";
-import { ContextManager } from "../context";
+import { Component, ConstructorProps } from '../component';
+import { ContextManager } from '../context';
 /**
  * @zcomponent
  * @zgroup Advanced
  * @zicon list
  */
 export declare class Children extends Component {
+    /**
+     * Creates an instance of Children.
+     * @param contextManager - The current ContextManager
+     * @param props - The constructor properties.
+     */
     constructor(contextManager: ContextManager, props: ConstructorProps);
 }

package/lib/components/Children.js

@@ -1,10 +1,15 @@
-import { Component } from "../component";
+import { Component } from '../component';
 /**
  * @zcomponent
  * @zgroup Advanced
  * @zicon list
  */
 export class Children extends Component {
+    /**
+     * Creates an instance of Children.
+     * @param contextManager - The current ContextManager
+     * @param props - The constructor properties.
+     */
     constructor(contextManager, props) {
         super(contextManager, props);
         const zcomponent = this.getZComponentInstance();

package/lib/components/DefaultCookieConsent.d.ts

@@ -1,6 +1,6 @@
-import { Component } from "../component";
-import { ContextManager } from "../context";
-import { Observable } from "../observable";
+import { Component } from '../component';
+import { ContextManager } from '../context';
+import { Observable } from '../observable';
 export interface DefaultCookieConsentConstructorProps {
     /**
      * Show the cookie consent dialog when the experience starts, rather than when the component is initialized.
@@ -22,6 +22,11 @@ export interface DefaultCookieConsentConstructorProps {
     preview: boolean;
 }
 /**
+ * The CookieConsent component is responsible for displaying a cookie consent banner to the user.
+ *
+ * This banner informs the user about the use of cookies on the website and asks for their consent.
+ * The component handles the logic for displaying the banner, receiving the user's consent, and storing this consent.
+ * It also provides methods to check if the user has already given their consent.
  * @zcomponent
  * @zgroup Cookie Consent
  * @zicon cookie
@@ -144,6 +149,11 @@ export declare class DefaultCookieConsent extends Component {
     private _functional;
     private _performance;
     private _marketing;
+    /**
+     * Creates an instance of DefaultCookieConsent.
+     * @param contextManager - The current ContextManager
+     * @param constructorProps - The properties of the component
+     */
     constructor(contextManager: ContextManager, constructorProps: DefaultCookieConsentConstructorProps);
     private _loadDOM;
     private _save;