@zcomponent/core 1.29.0 → 2.0.0-alpha.2

package/lib/contexts/gamepadcontext.js

@@ -4,72 +4,72 @@ import { isDesignTime } from './environmentcontext';
 /**
  * Represents the axes of a gamepad.
  */
-export var GamepadAxis;
-(function (GamepadAxis) {
-    GamepadAxis["LeftStickHorizontal"] = "LeftStickHorizontal";
-    GamepadAxis["LeftStickVertical"] = "LeftStickVertical";
-    GamepadAxis["RightStickHorizontal"] = "RightStickHorizontal";
-    GamepadAxis["RightStickVertical"] = "RightStickVertical";
-})(GamepadAxis || (GamepadAxis = {}));
+export const GamepadAxis = {
+    LeftStickHorizontal: 'LeftStickHorizontal',
+    LeftStickVertical: 'LeftStickVertical',
+    RightStickHorizontal: 'RightStickHorizontal',
+    RightStickVertical: 'RightStickVertical',
+};
+Object.freeze(GamepadAxis);
 /**
  * Represents the buttons on a gamepad.
  */
-export var GamepadButton;
-(function (GamepadButton) {
-    GamepadButton["South"] = "South";
-    GamepadButton["East"] = "East";
-    GamepadButton["West"] = "West";
-    GamepadButton["North"] = "North";
-    GamepadButton["ShoulderLeft"] = "ShoulderLeft";
-    GamepadButton["ShoulderRight"] = "ShoulderRight";
-    GamepadButton["TriggerLeft"] = "TriggerLeft";
-    GamepadButton["TriggerRight"] = "TriggerRight";
-    GamepadButton["Select"] = "Select";
-    GamepadButton["Start"] = "Start";
-    GamepadButton["StickLeft"] = "StickLeft";
-    GamepadButton["StickRight"] = "StickRight";
-    GamepadButton["DUp"] = "DUp";
-    GamepadButton["DDown"] = "DDown";
-    GamepadButton["DLeft"] = "DLeft";
-    GamepadButton["DRight"] = "DRight";
-    GamepadButton["Center"] = "Center";
-})(GamepadButton || (GamepadButton = {}));
+export const GamepadButton = {
+    South: 'South',
+    East: 'East',
+    West: 'West',
+    North: 'North',
+    ShoulderLeft: 'ShoulderLeft',
+    ShoulderRight: 'ShoulderRight',
+    TriggerLeft: 'TriggerLeft',
+    TriggerRight: 'TriggerRight',
+    Select: 'Select',
+    Start: 'Start',
+    StickLeft: 'StickLeft',
+    StickRight: 'StickRight',
+    DUp: 'DUp',
+    DDown: 'DDown',
+    DLeft: 'DLeft',
+    DRight: 'DRight',
+    Center: 'Center',
+};
+Object.freeze(GamepadButton);
 /**
  * Manages and tracks gamepad connections and states.
  * @zcontext
  */
 export class GamepadContext extends Context {
+    onGamepadsChange = new Event();
+    activeGamepads = new Set();
+    _registeredGamepads = new Map();
     /**
      * Creates an instance of GamepadContext.
      * @param contextManager - The current ContextManager
      */
     constructor(contextManager) {
         super(contextManager, {});
-        this.onGamepadsChange = new Event();
-        this.activeGamepads = new Set();
-        this._registeredGamepads = new Map();
-        this._update = () => {
-            const gamepads = navigator.getGamepads();
-            let changes = false;
-            for (let i = 0; i < gamepads.length; i++) {
-                if (gamepads[i] === null && this.activeGamepads.has(i)) {
-                    this.activeGamepads.delete(i);
-                    changes = true;
-                }
-                else if (gamepads[i] !== null && !this.activeGamepads.has(i)) {
-                    this.activeGamepads.add(i);
-                    changes = true;
-                }
-            }
-            if (changes)
-                this.onGamepadsChange.emit();
-        };
         if (!isDesignTime(contextManager) && typeof navigator.getGamepads === 'function') {
             window.addEventListener('gamepadconnected', this._update);
             window.addEventListener('gamepaddisconnected', this._update);
         }
         this._update();
     }
+    _update = () => {
+        const gamepads = navigator.getGamepads();
+        let changes = false;
+        for (let i = 0; i < gamepads.length; i++) {
+            if (gamepads[i] === null && this.activeGamepads.has(i)) {
+                this.activeGamepads.delete(i);
+                changes = true;
+            }
+            else if (gamepads[i] !== null && !this.activeGamepads.has(i)) {
+                this.activeGamepads.add(i);
+                changes = true;
+            }
+        }
+        if (changes)
+            this.onGamepadsChange.emit();
+    };
     /**
      * Retrieves a gamepad instance by its index.
      * @param indx The index of the gamepad.

package/lib/contexts/gesturecontext.d.ts

@@ -1,12 +1,13 @@
-import { Context, ContextManager, Event, Observable } from '../index';
+import { Context, ContextManager, Event, Observable, ValueOf } from '../index';
 /**
  * Defines the modes for interpreting touch gestures.
  */
-export declare enum GestureMode {
-    ScaleOnly = "Scale Only",
-    RotateOnly = "Rotate Only",
-    ScaleRotate = "Scale Rotate"
-}
+export declare const GestureMode: {
+    readonly ScaleOnly: "Scale Only";
+    readonly RotateOnly: "Rotate Only";
+    readonly ScaleRotate: "Scale Rotate";
+};
+export type GestureModeValue = ValueOf<typeof GestureMode>;
 /**
  * Configuration options for GestureContext construction.
  */
@@ -24,12 +25,33 @@ interface ConstructionProps {
  **/
 export declare class GestureContext extends Context<ConstructionProps> {
     private element;
+    /**
+     * @default true
+     */
     private canScale;
+    /**
+     * @default "Scale Rotate"
+     */
     private gestureMode;
+    /**
+     * @default true
+     */
     private canRotate;
+    /**
+     * @default null
+     */
     private initialDistance;
+    /**
+     * @default null
+     */
     private initialAngle;
+    /**
+     * @default true
+     */
     private oneFingerRotateMode;
+    /**
+     * @default null
+     */
     private initialTouchX;
     /**
      * Observable representing the current rotation value.
@@ -54,14 +76,17 @@ export declare class GestureContext extends Context<ConstructionProps> {
     enabled: Observable<boolean, never>;
     /**
      * Minimum scale factor. Defaults to 0.5.
+     * @default 0.5
      */
     minScale: number;
     /**
      * Maximum scale factor. Defaults to 2.
+     * @default 2
      */
     maxScale: number;
     /**
      * Sensitivity of rotation. Defaults to 1.
+     * @default 1
      */
     rotationSensitivity: number;
     /**

package/lib/contexts/gesturecontext.js

@@ -1,19 +1,84 @@
-import { Context, Event, Observable, useCanvas, isDevelopmentBuild, isEditTime } from '../index';
+import { Context, Event, isDevelopmentBuild, isEditTime, Observable, useCanvas } from '../index';
 /**
  * Defines the modes for interpreting touch gestures.
  */
-export var GestureMode;
-(function (GestureMode) {
-    GestureMode["ScaleOnly"] = "Scale Only";
-    GestureMode["RotateOnly"] = "Rotate Only";
-    GestureMode["ScaleRotate"] = "Scale Rotate";
-})(GestureMode || (GestureMode = {}));
+export const GestureMode = {
+    ScaleOnly: 'Scale Only',
+    RotateOnly: 'Rotate Only',
+    ScaleRotate: 'Scale Rotate',
+};
+Object.freeze(GestureMode);
 /**
  * Manages touch gestures for scaling and rotating elements.
  * @deprecated Use the GestureTransform component instead. This context will be removed in the next major version.
  * @zcontext
  **/
 export class GestureContext extends Context {
+    element;
+    /**
+     * @default true
+     */
+    canScale = true;
+    /**
+     * @default "Scale Rotate"
+     */
+    gestureMode = GestureMode.ScaleRotate;
+    /**
+     * @default true
+     */
+    canRotate = true;
+    /**
+     * @default null
+     */
+    initialDistance = null;
+    /**
+     * @default null
+     */
+    initialAngle = null;
+    /**
+     * @default true
+     */
+    oneFingerRotateMode = true;
+    /**
+     * @default null
+     */
+    initialTouchX = null;
+    /**
+     * Observable representing the current rotation value.
+     */
+    rotation = new Observable(0);
+    /**
+     * Observable representing the current scale value.
+     */
+    scale = new Observable(0);
+    /**
+     * Event triggered when rotation occurs.
+     */
+    onRotate = new Event();
+    /**
+     * Event triggered when scaling occurs.
+     */
+    onScale = new Event();
+    /**
+     * Observable indicating whether gesture interactions are enabled.
+     * Defaults to true.
+     */
+    enabled = new Observable(true);
+    /**
+     * Minimum scale factor. Defaults to 0.5.
+     * @default 0.5
+     */
+    minScale = 0.5;
+    /**
+     * Maximum scale factor. Defaults to 2.
+     * @default 2
+     */
+    maxScale = 2;
+    /**
+     * Sensitivity of rotation. Defaults to 1.
+     * @default 1
+     */
+    rotationSensitivity = 1;
     /**
      * Creates an instance of GestureContext.
      * @param contextManager - The current ContextManager
@@ -21,84 +86,6 @@ export class GestureContext extends Context {
      */
     constructor(contextManager, constructorProps) {
         super(contextManager, constructorProps);
-        this.canScale = true;
-        this.gestureMode = GestureMode.ScaleRotate;
-        this.canRotate = true;
-        this.initialDistance = null;
-        this.initialAngle = null;
-        this.oneFingerRotateMode = true;
-        this.initialTouchX = null;
-        /**
-         * Observable representing the current rotation value.
-         */
-        this.rotation = new Observable(0);
-        /**
-         * Observable representing the current scale value.
-         */
-        this.scale = new Observable(0);
-        /**
-         * Event triggered when rotation occurs.
-         */
-        this.onRotate = new Event();
-        /**
-         * Event triggered when scaling occurs.
-         */
-        this.onScale = new Event();
-        /**
-         * Observable indicating whether gesture interactions are enabled.
-         * Defaults to true.
-         */
-        this.enabled = new Observable(true);
-        /**
-         * Minimum scale factor. Defaults to 0.5.
-         */
-        this.minScale = 0.5;
-        /**
-         * Maximum scale factor. Defaults to 2.
-         */
-        this.maxScale = 2;
-        /**
-         * Sensitivity of rotation. Defaults to 1.
-         */
-        this.rotationSensitivity = 1;
-        this.onTouchStart = (event) => {
-            if (this.oneFingerRotateMode && event.touches.length === 1) {
-                this.initialTouchX = event.touches[0].pageX;
-            }
-            else if (event.touches.length === 2) {
-                this.initialDistance = this.getDistanceBetweenTouches(event.touches);
-                this.initialAngle = this.getAngleBetweenTouches(event.touches);
-            }
-        };
-        this.onTouchMove = (event) => {
-            switch (this.gestureMode) {
-                case GestureMode.ScaleOnly:
-                    if (event.touches.length === 2) {
-                        this.handleScale(event);
-                    }
-                    break;
-                case GestureMode.RotateOnly:
-                    if (this.oneFingerRotateMode && event.touches.length === 1) {
-                        this.handleOneFingerRotate(event);
-                    }
-                    else if (event.touches.length === 2) {
-                        this.handleRotate(event);
-                    }
-                    break;
-                case GestureMode.ScaleRotate:
-                    if (this.oneFingerRotateMode && event.touches.length === 1) {
-                        this.handleOneFingerRotate(event);
-                    }
-                    else if (event.touches.length === 2) {
-                        this.handleTwoFingerGestures(event);
-                    }
-                    break;
-            }
-        };
-        this.onTouchEnd = (event) => {
-            this.initialDistance = null;
-            this.initialAngle = null;
-        };
         if (isDevelopmentBuild(contextManager) || isEditTime(contextManager)) {
             console.warn('GestureContext is deprecated. Please use the GestureTransform component instead. GestureContext will be removed in the next major version.');
         }
@@ -112,6 +99,40 @@ export class GestureContext extends Context {
             }
         }, undefined, true);
     }
+    onTouchStart = (event) => {
+        if (this.oneFingerRotateMode && event.touches.length === 1) {
+            this.initialTouchX = event.touches[0].pageX;
+        }
+        else if (event.touches.length === 2) {
+            this.initialDistance = this.getDistanceBetweenTouches(event.touches);
+            this.initialAngle = this.getAngleBetweenTouches(event.touches);
+        }
+    };
+    onTouchMove = (event) => {
+        switch (this.gestureMode) {
+            case GestureMode.ScaleOnly:
+                if (event.touches.length === 2) {
+                    this.handleScale(event);
+                }
+                break;
+            case GestureMode.RotateOnly:
+                if (this.oneFingerRotateMode && event.touches.length === 1) {
+                    this.handleOneFingerRotate(event);
+                }
+                else if (event.touches.length === 2) {
+                    this.handleRotate(event);
+                }
+                break;
+            case GestureMode.ScaleRotate:
+                if (this.oneFingerRotateMode && event.touches.length === 1) {
+                    this.handleOneFingerRotate(event);
+                }
+                else if (event.touches.length === 2) {
+                    this.handleTwoFingerGestures(event);
+                }
+                break;
+        }
+    };
     handleOneFingerRotate(event) {
         if (this.initialTouchX !== null) {
             const currentTouchX = event.touches[0].pageX;
@@ -141,6 +162,10 @@ export class GestureContext extends Context {
             this.rotation.value = -rotateAmount;
         }
     }
+    onTouchEnd = (event) => {
+        this.initialDistance = null;
+        this.initialAngle = null;
+    };
     getDistanceBetweenTouches(touches) {
         const dx = touches[0].pageX - touches[1].pageX;
         const dy = touches[0].pageY - touches[1].pageY;

package/lib/contexts/globaltagcontext.d.ts

@@ -9,7 +9,7 @@ export declare class GlobalTagContext extends Context {
     /**
      * A map storing the relationship between global tags and sets of components.
      */
-    readonly componentsByGlobalTag: Map<string, Set<Component<any, import("../component").ConstructorProps>>>;
+    readonly componentsByGlobalTag: Map<string, Set<Component<any, import("..").ConstructorProps>>>;
     /**
      * An event that's emitted when the set of components that constitute a tag changes.
      */

package/lib/contexts/globaltagcontext.js

@@ -5,15 +5,12 @@ import { Event } from '../event';
  * @zcontext
  */
 export class GlobalTagContext extends Context {
-    constructor() {
-        super(...arguments);
-        /**
-         * A map storing the relationship between global tags and sets of components.
-         */
-        this.componentsByGlobalTag = new Map();
-        /**
-         * An event that's emitted when the set of components that constitute a tag changes.
-         */
-        this.onTagChange = new Event();
-    }
+    /**
+     * A map storing the relationship between global tags and sets of components.
+     */
+    componentsByGlobalTag = new Map();
+    /**
+     * An event that's emitted when the set of components that constitute a tag changes.
+     */
+    onTagChange = new Event();
 }

package/lib/contexts/loadcontext.d.ts

@@ -1,4 +1,5 @@
-import { ContextManager, Context } from '../context';
+import { Context, ContextManager } from '../context';
+import { Entity } from '../entity';
 import { Observable } from '../observable';
 /**
  * LoadContext exposes to components and behaviors key moments during the initialization of the experience,
@@ -31,31 +32,26 @@ export declare class LoadContext extends Context {
     /**
      * Observable indicating whether the root component's construction is complete.
      * This is typically set to true immediately after the root component and its children are constructed.
-     * @zui
      */
     readonly isConstructed: Observable<boolean, never>;
     /**
      * Observable indicating whether all loadable processes have completed.
      * This is true when all assets and dependencies required for the experience are fully loaded.
-     * @zui
      */
     readonly isLoaded: Observable<boolean, never>;
     /**
      * Observable indicating whether the experience has started.
      * This becomes true at the point where the experience transitions from loading to active interaction.
-     * @zui
      */
     readonly isStarted: Observable<boolean, never>;
     /**
      * Observable indicating whether the experience has been launched.
      * This is set to true typically when the user interacts with a splash screen or an initial launch button.
-     * @zui
      */
     readonly isLaunched: Observable<boolean, never>;
     /**
      * Observable representing the progress percentage of loadable processes.
      * This provides a numerical value representing the completion percentage of all loading operations.
-     * @zui
      */
     readonly progressPercent: Observable<number, never>;
     private _startedResolved;
@@ -65,8 +61,17 @@ export declare class LoadContext extends Context {
     private _launchedResolved;
     readonly launched: Promise<void>;
     private _loadables;
+    /**
+     * @default false
+     */
     private _startWhenLoaded;
+    /**
+     * @default 0
+     */
     private _totalLoadables;
+    /**
+     * @default 0
+     */
     private _loadedCount;
     /**
      * Start the experience.
@@ -88,7 +93,7 @@ export declare class LoadContext extends Context {
     /**
      * Register a loadable process.
      */
-    registerLoadable(p: Promise<any>): void;
+    registerLoadable(p: Promise<any>, entity?: Entity): void;
 }
 /**
  * Returns an observable that indicates whether the experience is loaded.
@@ -129,7 +134,7 @@ export declare function useLoadPercent(mgr: ContextManager): Observable<number,
 /**
  * Register a loadable process.
  */
-export declare function registerLoadable(mgr: ContextManager, p: Promise<any>): void;
+export declare function registerLoadable(mgr: ContextManager | Entity, p: Promise<any>): void;
 /**
  * Starts the experience.
  */
@@ -159,3 +164,35 @@ export declare function launched(mgr: ContextManager): Promise<void>;
  * Marks the root component's constructor (and thus any recursive children) as finished.
  */
 export declare function constructionComplete(mgr: ContextManager): void;
+/**
+ * A decorator that registers its decorated function as a loadable process, and
+ * (by default) invokes it automatically once the experience has finished constructing.
+ *
+ * The loader will wait for the returned promise to resolve before hiding itself.
+ * The loadable is registered synchronously during construction so that `isLoaded`
+ * reflects the pending work from the moment the entity exists; the actual method
+ * call is deferred until after the full construction tree settles, so any fields
+ * assigned in subclass constructor bodies are available when it runs.
+ *
+ * Mirrors the structure of {@link zOnConstructed}, {@link zOnStart}, and {@link zOnLaunch};
+ * the only difference is that `zLoad` also registers the deferred work as a loadable.
+ *
+ * @param autoInvoke - If true (default), the method fires automatically after construction.
+ *                     If false, the method must be called manually but will still register as a loadable.
+ */
+export declare function zLoad<EntityType extends Entity>(autoInvoke?: boolean): (originalMethod: (...args: any) => Promise<any>, context: ClassMethodDecoratorContext<EntityType, (this: EntityType, ...args: any[]) => Promise<any>>) => (this: EntityType, ...args: any[]) => Promise<any>;
+/**
+ * A decorator that will automatically call its decorated function when the experience has been started.
+ */
+export declare function zOnStart<EntityType extends Entity>(): (originalMethod: (...args: [
+]) => any, context: ClassMethodDecoratorContext<EntityType>) => any;
+/**
+ * A decorator that will automatically call its decorated function when the experience has been constructed.
+ */
+export declare function zOnConstructed<EntityType extends Entity>(): (originalMethod: (...args: [
+]) => any, context: ClassMethodDecoratorContext<EntityType>) => any;
+/**
+ * A decorator that will automatically call its decorated function when the experience has been launched.
+ */
+export declare function zOnLaunch<EntityType extends Entity>(): (originalMethod: (...args: [
+]) => any, context: ClassMethodDecoratorContext<EntityType>) => any;