@zcomponent/core 1.23.0-beta.1 → 1.24.0-beta.1

package/lib/animation/layerclip.d.ts

@@ -86,7 +86,7 @@ export declare class LayerClip implements Stream {
      *
      * @param opts Optional play options to customize playback behavior.
      */
-    queue(opts?: LayerClipPlayOptions): void;
+    queue(opts?: LayerClipPlayOptions): this;
     /**
      * @returns The length of the clip.
      */
@@ -96,11 +96,11 @@ export declare class LayerClip implements Stream {
      *
      * @param opts Optional play options to customize playback behavior.
      */
-    play(opts?: LayerClipPlayOptions): void;
+    play(opts?: LayerClipPlayOptions): this;
     /**
      * Pauses the playback of the clip.
      */
-    pause(): void;
+    pause(): this;
     private _cancelStall;
     /**
      * Seeks to a specific time within the clip and optionally applies fade parameters.
@@ -108,7 +108,7 @@ export declare class LayerClip implements Stream {
      * @param ct The clip time to seek to.
      * @param opts Optional seek options, including fade parameters.
      */
-    seek(ct: number, opts?: LayerClipSeekOptions): void;
+    seek(ct: number, opts?: LayerClipSeekOptions): this;
     /** @internal */
     _serialize(state: AnimationState): void;
     /** @internal */
@@ -122,7 +122,7 @@ export declare class LayerClip implements Stream {
     /**
      * Stops the clip's playback.
      */
-    stop(): void;
+    stop(): this;
     /**
      * Determines if the clip is currently stalled.
      *

package/lib/animation/layerclip.js

@@ -142,6 +142,7 @@ export class LayerClip {
      */
     queue(opts) {
         this.layer.queue(this, opts);
+        return this;
     }
     /**
      * @returns The length of the clip.
@@ -156,8 +157,7 @@ export class LayerClip {
      */
     play(opts) {
         if (opts?.speed === 0) {
-            this.pause();
-            return;
+            return this.pause();
         }
         this._stopped = false;
         this._loop = opts?.loop ?? this.defaultLoop;
@@ -201,6 +201,7 @@ export class LayerClip {
         this.clip.streamTick(this._state, bt, this._rate, this.layer.active === this, this.layer.active, loop !== this._lastLoop, this._stallStartTime !== undefined, 1);
         this._lastLoop = loop;
         this.state.value = this._state;
+        return this;
     }
     /**
      * Pauses the playback of the clip.
@@ -208,13 +209,14 @@ export class LayerClip {
     pause() {
         delete this._lastLoop;
         if (this._pauseTime !== undefined || this._state !== StreamState.Playing)
-            return;
+            return this;
         this._state = StreamState.Paused;
         this.animation._pendingEvents.push({ evt: AnimationEvents.onLayerClipState, args: [this] });
         this._pauseTime = this._getTime();
         this._cancelStall();
         this.clip.streamPause(this.layer.active === this, this.layer.active);
         this.state.value = this._state;
+        return this;
     }
     _cancelStall() {
         if (this._stallStartTime === undefined)
@@ -232,14 +234,15 @@ export class LayerClip {
      * @param opts Optional seek options, including fade parameters.
      */
     seek(ct, opts) {
+        const clampedTime = Math.max(0, Math.min(ct, this.clip.length));
         const t = this._getTime();
         this._stopped = false;
         if (this._rate >= 0) {
-            this._t0 = t - ct / this._rate;
+            this._t0 = t - clampedTime / this._rate;
             this._t1 = this._t0 + this.clip.length / this._rate;
         }
         else {
-            this._t0 = t - (this.clip.length - ct) / -this._rate;
+            this._t0 = t - (this.clip.length - clampedTime) / -this._rate;
             this._t1 = this._t0 + this.clip.length / -this._rate;
         }
         if (this._pauseTime !== undefined) {
@@ -247,15 +250,16 @@ export class LayerClip {
         }
         if (this._loop)
             this._t1 = Infinity;
-        this._lastClipTime = undefined;
-        this._lastTickTime = undefined;
+        this._lastTickTime = clampedTime;
+        this._lastClipTime = clampedTime;
         if (this.layer.active !== this && !opts?.dontActivateLayer) {
             this.layer._activateLayerClip(this, { fade: opts?.fade });
         }
         delete this._lastLoop;
         delete this._stallStartTime;
-        this.clip.streamSeek(ct, this._rate, this.layer.active === this, this.layer.active);
+        this.clip.streamSeek(clampedTime, this._rate, this.layer.active === this, this.layer.active);
         this.layer._evaulate();
+        return this;
     }
     /** @internal */
     _serialize(state) {
@@ -316,6 +320,7 @@ export class LayerClip {
         this._state = StreamState.Ended;
         this.animation._pendingEvents.push({ evt: AnimationEvents.onLayerClipState, args: [this] });
         this.state.value = this._state;
+        return this;
     }
     /**
      * Determines if the clip is currently stalled.

package/lib/contexts/documentflagmanager.d.ts

@@ -0,0 +1,12 @@
+import type { EnvironmentContext } from './environmentcontext';
+import type { LoadContext } from './loadcontext';
+/**
+ * Internal context that manages the document flags.
+ */
+export declare class DocumentFlagManager {
+    private readonly _environmentContext;
+    private readonly _loadContext;
+    constructor(_environmentContext: EnvironmentContext, _loadContext: LoadContext);
+    private _update;
+    dispose(): void;
+}

package/lib/contexts/documentflagmanager.js

@@ -0,0 +1,37 @@
+/**
+ * Internal context that manages the document flags.
+ */
+export class DocumentFlagManager {
+    constructor(_environmentContext, _loadContext) {
+        this._environmentContext = _environmentContext;
+        this._loadContext = _loadContext;
+        this._update = () => {
+            if (!document?.body)
+                return;
+            document.body.classList.toggle('zcomponent-designtime', this._environmentContext.designTime.value);
+            document.body.classList.toggle('zcomponent-runtime', this._environmentContext.runTime.value);
+            document.body.classList.toggle('zcomponent-development', this._environmentContext.developmentBuild.value);
+            document.body.classList.toggle('zcomponent-production', this._environmentContext.productionBuild.value);
+            document.body.classList.toggle('zcomponent-started', this._loadContext.isStarted.value);
+            document.body.classList.toggle('zcomponent-launched', this._loadContext.isLaunched.value);
+            document.body.classList.toggle('zcomponent-loaded', this._loadContext.isLoaded.value);
+        };
+        this._update();
+        this._environmentContext.designTime.addListener(this._update);
+        this._environmentContext.runTime.addListener(this._update);
+        this._environmentContext.productionBuild.addListener(this._update);
+        this._environmentContext.developmentBuild.addListener(this._update);
+        this._loadContext.isStarted.addListener(this._update);
+        this._loadContext.isLaunched.addListener(this._update);
+        this._loadContext.isLoaded.addListener(this._update);
+    }
+    dispose() {
+        this._environmentContext.designTime.removeListener(this._update);
+        this._environmentContext.runTime.removeListener(this._update);
+        this._environmentContext.productionBuild.removeListener(this._update);
+        this._environmentContext.developmentBuild.removeListener(this._update);
+        this._loadContext.isStarted.removeListener(this._update);
+        this._loadContext.isLaunched.removeListener(this._update);
+        this._loadContext.isLoaded.removeListener(this._update);
+    }
+}

package/lib/contexts/environmentcontext.d.ts

@@ -27,6 +27,9 @@ export declare class EnvironmentContext extends Context {
      * @zprop
      * */
     readonly productionBuild: Observable<boolean, never>;
+    private readonly _documentFlagManager;
+    constructor(contextManager: ContextManager, props: {});
+    dispose(): never;
 }
 /**
  * Determines if the application is in design time.

package/lib/contexts/environmentcontext.js

@@ -1,9 +1,11 @@
 import { Context } from '../context';
 import { Observable } from '../observable';
+import { DocumentFlagManager } from './documentflagmanager';
+import { LoadContext } from './loadcontext';
 /** @zcontext */
 export class EnvironmentContext extends Context {
-    constructor() {
-        super(...arguments);
+    constructor(contextManager, props) {
+        super(contextManager, props);
         /**
          * Observable indicating if the application is in design time.
          * @zprop
@@ -29,6 +31,12 @@ export class EnvironmentContext extends Context {
          * @zprop
          * */
         this.productionBuild = new Observable(!this.developmentBuild.value);
+        const loadContext = this.contextManager.get(LoadContext);
+        this._documentFlagManager = new DocumentFlagManager(this, loadContext);
+    }
+    dispose() {
+        this._documentFlagManager.dispose();
+        return super.dispose();
     }
 }
 /**

package/lib/contexts/loadcontext.js

@@ -74,8 +74,6 @@ export class LoadContext extends Context {
     start() {
         if (this.isStarted.value)
             return;
-        if (document.body)
-            document.body.classList.add('zcomponent-started');
         this.isStarted.value = true;
         this._startedResolved?.();
     }
@@ -94,8 +92,6 @@ export class LoadContext extends Context {
     launch() {
         if (this.isLaunched.value)
             return;
-        if (document.body)
-            document.body.classList.add('zcomponent-launched');
         this.isLaunched.value = true;
         this._launchedResolved();
     }
@@ -107,8 +103,6 @@ export class LoadContext extends Context {
         }
         if (this._loadables.size === 0 && this.isLoaded.value === false) {
             this.isLoaded.value = true;
-            if (document.body)
-                document.body.classList.add('zcomponent-loaded');
         }
         this.progressPercent.value = this.isLoaded.value ? 100 : (100 * this._loadedCount) / this._totalLoadables;
         if (this._startWhenLoaded && this.isLoaded.value && !this.isStarted.value) {

package/lib/data/core.d.ts

@@ -49,6 +49,11 @@ export interface ZComponentData {
             [id: string]: boolean;
         };
     };
+    group?: string;
+    icon?: string;
+    tags?: string[];
+    allowedParents?: string[];
+    comments?: string[];
 }
 export interface NodeData {
     id: string;

package/lib/selectors.d.ts

@@ -104,7 +104,7 @@ export declare const typeDefinitionForComponent: (nodes: NodeByID, props: Props,
     [id: string]: {
         [id: string]: boolean;
     };
-} | undefined, layers: Data.ByID<Data.Layer>, behaviors: BehaviorByID) => string;
+} | undefined, layers: Data.ByID<Data.Layer>, behaviors: BehaviorByID, group: string | undefined, tags: string[] | undefined, icon: string | undefined, comments?: string[] | undefined, parents?: string[] | undefined) => string;
 /**
  * Sanitizes a key name to ensure it is safe for use in scripting.
  *

package/lib/selectors.js

@@ -288,7 +288,7 @@ function typeContainsType(p, name) {
  * @param behaviors - The behaviors of the ZComponent.
  * @returns A string containing the TypeScript type definition for the ZComponent.
  */
-export const typeDefinitionForComponent = (nodes, props, constructorProps, scriptNames, layers, behaviors) => {
+export const typeDefinitionForComponent = (nodes, props, constructorProps, scriptNames, layers, behaviors, group, tags, icon, comments, parents) => {
     const importMapping = new Map();
     let indx = 0;
     const importStrings = [];
@@ -319,6 +319,14 @@ export const typeDefinitionForComponent = (nodes, props, constructorProps, scrip
             }
         }
     }
+    const jsdoc = [
+        ...(comments ? [...comments.map(entry => entry.replaceAll('\r', '').split('\n')).flat(), ''] : []),
+        '@zcomponent',
+        `@zicon ${icon ?? 'zcomponent'}`,
+        ...(group ? [`@zgroup ${group}`] : []),
+        ...(tags ?? []).map(tag => `@ztag ${tag}`),
+        ...(parents ?? []).map(parent => `@zparents ${parent}`),
+    ];
     return `import { ZComponent, ContextManager, Observable, Animation, Layer, LayerClip, Event } from "@zcomponent/core";
 
 ${importStrings.join('\n')}
@@ -330,8 +338,7 @@ ${Object.values(constructorProps ?? {})
 }
 
 /**
-* @zcomponent
-* @zicon zcomponent
+* ${jsdoc.join('\n* ')}
 */
 declare class Comp extends ZComponent {
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zcomponent/core",
-  "version": "1.23.0-beta.1",
+  "version": "1.24.0-beta.1",
   "description": "The core component model and built-in functionality for Mattercraft.",
   "author": "Zappar Limited",
   "license": "Proprietary",