@zcomponent/core 1.29.0 → 2.0.0-alpha.2

package/lib/decorators.js

@@ -0,0 +1,239 @@
+import { registerBehaviorRunAtDesignTime } from './behavior';
+import { Event } from './event';
+import { makeObservable } from './observe';
+/**
+ * Creates an observable property that automatically triggers a callback when its value changes.
+ * This enables reactive programming patterns where property changes can update UI elements,
+ * trigger side effects, or synchronize state across components.
+ *
+ * @decorator
+ * @param withHandler - Optional callback function that executes when the property value changes.
+ *                      Receives the new value, the entity instance, and the property name.
+ * @param deep - Whether to observe nested object changes (default: true)
+ * @returns A property decorator that makes the property observable
+ *
+ * @example
+ * ```typescript
+ * // Simple observer that updates element visibility
+ * @zObserve((val, instance) => (instance.element.visible = val))
+ * public visible = true;
+ *
+ * // Observer that calls a method on change
+ * @zObserve((v, instance: Audio) => {
+ *     instance._updateVolume();
+ * })
+ * public muted = false;
+ *
+ * // Observer without handler (just makes property observable)
+ * @zObserve()
+ * public position = { x: 0, y: 0, z: 0 };
+ * ```
+ */
+export function zObserve(withHandler, deep = true) {
+    return (value, context) => {
+        context.addInitializer(function () {
+            const evt = makeObservable(this, context.name, deep, true);
+            if (withHandler) {
+                const handler = withHandler.bind(this);
+                evt.addListener(handler);
+            }
+        });
+        return function (initialValue) {
+            return initialValue;
+        };
+    };
+}
+// export function zProp<T>(opts?: ZPropOptions): (val, context) => (initialValue: T) => T {
+// 	return function (value: undefined, context) {
+// 		return function (this: Entity, initialValue: T) {
+// 			return initialValue;
+// 		};
+// 	};
+// }
+/**
+ * Exposes a property to the Mattercraft UI editor, allowing users to configure it visually.
+ * Supports various UI widget types, grouping, and value constraints.
+ *
+ * @decorator
+ * @param opts - Configuration options for how the property appears in the UI
+ * @returns A property decorator that exposes the property to the UI
+ *
+ * @example
+ * ```typescript
+ * // Simple UI property
+ * @zUI()
+ * public volume = 1;
+ *
+ * // UI property with group and priority
+ * @zUI({ group: 'Audio', priority: 20 })
+ * public muted = false;
+ *
+ * // UI property with specific widget type
+ * @zUI({ type: 'proportion' })
+ * public opacity = 0.8;
+ *
+ * // UI property with value constraints
+ * @zUI({ values: 'layerclipids' })
+ * public state?: string;
+ *
+ * // Combined with @zObserve for reactive updates
+ * @zUI({ group: 'Appearance', type: 'color-hex' })
+ * @zObserve((val, instance) => instance.updateColor(val))
+ * public color = '#FF0000';
+ * ```
+ */
+export function zUI(opts) {
+    return (value, context) => {
+        if (context.kind === 'method') {
+            return value;
+        }
+        else {
+            return function (initialValue) {
+                return initialValue;
+            };
+        }
+    };
+}
+/**
+ * Excludes a property from serialization and the Mattercraft UI.
+ * Use this for internal properties that shouldn't be exposed to users or persisted.
+ *
+ * @decorator
+ * @returns A property decorator that marks the property as ignored
+ *
+ * @example
+ * ```typescript
+ * // Internal element reference
+ * @zIgnore()
+ * public element: HTMLElement;
+ *
+ * // Private cache that shouldn't be serialized
+ * @zIgnore()
+ * private _cache: Map<string, any>;
+ *
+ * // Temporary state
+ * @zIgnore()
+ * public isProcessing = false;
+ * ```
+ */
+export function zIgnore() {
+    return (value, context) => { };
+}
+/**
+ * Registers a class as a component in Mattercraft, making it available in the editor's UI.
+ * Components are the primary building blocks for creating interactive experiences.
+ *
+ * @decorator
+ * @param opts - Configuration options for the component
+ * @returns A class decorator that registers the component
+ *
+ * @example
+ * ```typescript
+ * // Basic component registration
+ * @zComponent({ icon: 'deployed_code', group: 'Meshes' })
+ * export class Box extends Mesh {
+ *     // Component implementation
+ * }
+ *
+ * // Component with tags and parent restrictions
+ * @zComponent({
+ *     icon: 'music_note',
+ *     group: 'Media',
+ *     tags: ['core/audio'],
+ * })
+ * export class Audio extends Component {
+ *     // Audio component implementation
+ * }
+ *
+ * // Component with default children
+ * @zComponent({
+ *     icon: 'view_in_ar',
+ *     group: '3D Objects',
+ *     defaultChildren: [
+ *         {
+ *             label: 'Material',
+ *             type: '@zcomponent/three/lib/components/materials/MeshStandardMaterial#MeshStandardMaterial',
+ *             props: { color: '#FF0000' }
+ *         }
+ *     ]
+ * })
+ * export class CustomMesh extends Component {
+ *     // Mesh with default material
+ * }
+ * ```
+ */
+export function zComponent(opts) {
+    return (t) => t;
+}
+/**
+ * Registers a class as a behavior that can be attached to components.
+ * Behaviors add functionality to existing components without modifying their structure.
+ *
+ * @decorator
+ * @param opts - Configuration options for the behavior
+ * @returns A class decorator that registers the behavior
+ *
+ * @example
+ * ```typescript
+ * // Basic behavior registration
+ * @zBehavior({ icon: 'directions_run', parents: ['three/Object3D/**'] })
+ * export class Animation extends Behavior {
+ *     // Animation behavior implementation
+ * }
+ *
+ * // Behavior that runs in the editor
+ * @zBehavior({
+ *     icon: 'visibility',
+ *     group: 'Actions',
+ *     runAtDesignTime: true,
+ *     parents: ['three/Object3D/**']
+ * })
+ * export class PreviewMode extends Behavior {
+ *     // Provides preview functionality in the editor
+ * }
+ *
+ * // Action behavior with specific parent restrictions
+ * @zBehavior({
+ *     icon: 'play_circle',
+ *     group: 'Animation Actions',
+ *     parents: ['three/Object3D/GLTF'],
+ *     tags: ['animation/control']
+ * })
+ * export class PlayAnimation extends ActionBehavior {
+ *     // Plays animations on GLTF models
+ * }
+ * ```
+ */
+export function zBehavior(opts) {
+    return (t) => {
+        if (opts?.runAtDesignTime)
+            registerBehaviorRunAtDesignTime(t);
+        return t;
+    };
+}
+export function zRegister(propOrContextConstructorOrEvent, contextPropOrOpts, opts) {
+    return (originalMethod, context) => {
+        context.addInitializer(function () {
+            let evt;
+            let resolvedOpts;
+            if (typeof propOrContextConstructorOrEvent === 'string') {
+                evt = this[propOrContextConstructorOrEvent];
+                if (typeof contextPropOrOpts === 'object')
+                    resolvedOpts = contextPropOrOpts;
+            }
+            else if (propOrContextConstructorOrEvent instanceof Event) {
+                evt = propOrContextConstructorOrEvent;
+                if (typeof contextPropOrOpts === 'object')
+                    resolvedOpts = contextPropOrOpts;
+            }
+            else if (typeof contextPropOrOpts === 'string') {
+                const context = this.contextManager.get(propOrContextConstructorOrEvent);
+                evt = context[contextPropOrOpts];
+                resolvedOpts = opts;
+            }
+            if (evt)
+                this.register(evt, (...args) => this[context.name].call(this, ...args), resolvedOpts);
+        });
+        return originalMethod;
+    };
+}

package/lib/decoratorutils.d.ts

@@ -0,0 +1,3 @@
+import { RegisterOptions } from './entity';
+import { Event } from './event';
+export declare function createEventBoundDecorator(evt: Event<any>, opts?: RegisterOptions): (originalMethod: (dt: number) => any, context: ClassMethodDecoratorContext) => any;

package/lib/decoratorutils.js

@@ -0,0 +1,8 @@
+export function createEventBoundDecorator(evt, opts) {
+    return (originalMethod, context) => {
+        context.addInitializer(function () {
+            this.register(evt, (...args) => this[context.name].call(this, ...args), opts);
+        });
+        return originalMethod;
+    };
+}

package/lib/emitter.d.ts

@@ -2,10 +2,23 @@
  * The base class for classes that hold a set of functions to be called in response
  * to an event or change in value, e.g. Observable and Event.
  */
-export declare class Emitter<Args extends Array<any> = []> {
-    protected _funcs: [fn: (...args: Args) => void, priority: number][];
+export declare class Emitter<Args extends Array<any> = [
+]> {
+    /**
+     * @default []
+     */
+    protected _funcs: [
+        fn: (...args: Args) => void,
+        priority: number
+    ][];
+    /**
+     * @default false
+     */
     private _emitting;
     private _toUnbind;
+    /**
+     * @default false
+     */
     private _needsSort;
     private _next;
     private _nextFn;

package/lib/emitter.js

@@ -3,12 +3,21 @@
  * to an event or change in value, e.g. Observable and Event.
  */
 export class Emitter {
-    constructor() {
-        this._funcs = [];
-        this._emitting = false;
-        this._toUnbind = new Set();
-        this._needsSort = false;
-    }
+    /**
+     * @default []
+     */
+    _funcs = [];
+    /**
+     * @default false
+     */
+    _emitting = false;
+    _toUnbind = new Set();
+    /**
+     * @default false
+     */
+    _needsSort = false;
+    _next;
+    _nextFn;
     /**
      * Clears all listeners from the event.
      */

package/lib/entity.d.ts

@@ -2,16 +2,34 @@ import { ConstructorForComponent } from './component';
 import { ContextManager } from './context';
 import { Event } from './event';
 import { Observable } from './observable';
+import { ObserveOptions } from './observe';
 import { ZComponent } from './zcomponent';
 /**
  * Base class for all components and behaviors.
  */
 export declare class Entity {
     readonly contextManager: ContextManager;
+    /**
+     * @default []
+     */
     private _registered;
+    /**
+     * @default []
+     */
+    private _observed;
+    /**
+     * @default false
+     */
     private _handlersBound;
     private _zcomponent;
+    /**
+     * @default false
+     */
     private _disposed;
+    /**
+     * @default true
+     */
+    protected _enabledResolved: boolean;
     /**
      * An event that is fired as the last act of this entity being destroyed.
      */
@@ -24,34 +42,15 @@ export declare class Entity {
     /**
      * Gets the disposed status of the entity.
      * @returns {boolean} The disposed status.
+     * @zignore
      */
     get disposed(): boolean;
     /**
-     * Sets the disposed status of the entity.
-     * @param {boolean} v - The new disposed status.
-     * @private
-     */
-    private set disposed(value);
-    /**
-     * If `false`, this entity and its children will no longer participate in the experience.
-     *
-     * Note - to read this value, you may wish to use `enabledResolved` which will be `false` if
-     * this entity, or any of its parents, have `enabled` set to false.
-     *
-     * The precise implications of `enabled` being false will vary between entities,
-     * but in general disabled entities:
-     *  - should not emit any events,
-     *  - should not take any action, e.g. navigate the user to a different page,
-     *  - should not perform any network communication,
-     *  - should not make changes to other behaviors or components in the experience,
-     *  - should minimise any runtime performance cost (e.g. detach from any frame handlers).
-     *
-     * @zprop
-     * @zdefault true
      * @zgroup Behavior
-     * @zgrouppriority 10
+     * @zgrouppriority 5
+     * @default true
      */
-    readonly enabled: Observable<boolean, never>;
+    enabled: boolean;
     /**
      * This will have value `false` if this entity, or any of its parents, have `enabled` set to `false`.
      *
@@ -66,8 +65,9 @@ export declare class Entity {
      *  - should minimise any runtime performance cost.
      *
      * Disabled entities will typically remain visible (if they have a visible appearance).
+     * @zignore
      */
-    readonly enabledResolved: Observable<boolean, never>;
+    get enabledResolved(): boolean;
     /**
      * Get the instance of the ZComponent that constructed this entity.
      *
@@ -77,6 +77,7 @@ export declare class Entity {
      *
      * @param type The ZComponent class that you are expecting to receive
      * @returns The instance of the ZComponent that constructed this component or behavior
+     * @zignore
      */
     getZComponentInstance<T extends ZComponent = ZComponent>(type?: ConstructorForComponent<T>): T;
     /**
@@ -88,6 +89,7 @@ export declare class Entity {
      *
      * @param evt The Event or Observable to listen to
      * @param fn A function that will be called when the event fires, or the Observable value changes
+     * @zignore
      */
     register<Args extends Array<any>>(evt: Event<Args>, fn: (...args: Args) => void, priority?: number): any;
     register<Args extends Array<any>>(evt: Event<Args>, fn: (...args: Args) => void, options?: RegisterOptions): any;
@@ -98,9 +100,18 @@ export declare class Entity {
      *
      * @param evt The Event or Observable
      * @param fn The function that was passed in the call to `register`
+     * @zignore
      */
     unregister<Args extends Array<any>>(evt: Event<Args>, fn: (...args: Args) => void): any;
     unregister<Type>(observable: Observable<Type>, fn: (v: Type) => void): any;
+    /**
+     * @zignore
+     */
+    protected observe<ObjectType extends object, PropNameType extends keyof ObjectType>(object: ObjectType, prop: PropNameType, fn: (v: ObjectType[PropNameType]) => void, options?: EntityObserveOptions): void;
+    /**
+     * @zignore
+     */
+    protected unobserve<ObjectType extends object, PropNameType extends keyof ObjectType>(object: ObjectType, prop: PropNameType, fn: (v: ObjectType[PropNameType]) => void): void;
     private _updateHandlers;
     /**
      * Destroy this entity, cleaning up any resources that it has created and
@@ -119,8 +130,9 @@ export declare class Entity {
      * This ensures that the dispose implementation of the parent class runs.
      *
      * @returns The result of a call to super.dispose()
+     * @zignore
      */
-    dispose(): never;
+    dispose(): typeof Entity.callSuperDispose & never;
     private static callSuperDispose;
 }
 /**
@@ -136,3 +148,9 @@ export interface RegisterOptions {
      */
     bindWhenDisabled?: boolean;
 }
+export interface EntityObserveOptions extends ObserveOptions {
+    /**
+     * If `true`, the handler function will be bound to the underlying Event or Observable even if this entity is disabled.
+     */
+    bindWhenDisabled?: boolean;
+}

package/lib/entity.js

@@ -1,94 +1,78 @@
 import { Event } from './event';
-import { Observable } from './observable';
+import { observe, unobserve } from './observe';
 import { getCurrentZComponentConstruction } from './zcomponentconstruction';
+// import { zIgnore, zProp } from './decorators';
 /**
  * Base class for all components and behaviors.
  */
 export class Entity {
+    contextManager;
+    /**
+     * @default []
+     */
+    _registered = [];
+    /**
+     * @default []
+     */
+    _observed = [];
+    /**
+     * @default false
+     */
+    _handlersBound = false;
+    _zcomponent;
+    /**
+     * @default false
+     */
+    _disposed = false;
+    /**
+     * @default true
+     */
+    _enabledResolved = true;
+    /**
+     * An event that is fired as the last act of this entity being destroyed.
+     */
+    onDispose = new Event();
     /**
      * Creates an instance of Entity.
      * @param contextManager The current ContextManager
      */
     constructor(contextManager) {
         this.contextManager = contextManager;
-        this._registered = [];
-        this._handlersBound = false;
-        this._disposed = false;
-        /**
-         * An event that is fired as the last act of this entity being destroyed.
-         */
-        this.onDispose = new Event();
-        /**
-         * If `false`, this entity and its children will no longer participate in the experience.
-         *
-         * Note - to read this value, you may wish to use `enabledResolved` which will be `false` if
-         * this entity, or any of its parents, have `enabled` set to false.
-         *
-         * The precise implications of `enabled` being false will vary between entities,
-         * but in general disabled entities:
-         *  - should not emit any events,
-         *  - should not take any action, e.g. navigate the user to a different page,
-         *  - should not perform any network communication,
-         *  - should not make changes to other behaviors or components in the experience,
-         *  - should minimise any runtime performance cost (e.g. detach from any frame handlers).
-         *
-         * @zprop
-         * @zdefault true
-         * @zgroup Behavior
-         * @zgrouppriority 10
-         */
-        this.enabled = new Observable(true);
-        /**
-         * This will have value `false` if this entity, or any of its parents, have `enabled` set to `false`.
-         *
-         * To change the `enabled` status of this entity, use the `enabled` property instead.
-         *
-         * The precise implications of `enabled` being false will vary between entities,
-         * but in general disabled entities:
-         *  - should not emit any events,
-         *  - should not take any action, e.g. navigate the user to a different page,
-         *  - should not perform any network communication,
-         *  - should not make changes to other behaviors or components in the experience,
-         *  - should minimise any runtime performance cost.
-         *
-         * Disabled entities will typically remain visible (if they have a visible appearance).
-         */
-        this.enabledResolved = new Observable(true);
-        this._updateHandlers = (enabled) => {
-            if (enabled && !this._handlersBound) {
-                for (const [e, fn, priority, bindWhenDisabled] of this._registered) {
-                    if (bindWhenDisabled)
-                        continue;
-                    e.addListener(fn, priority);
-                }
-                this._handlersBound = true;
-            }
-            if (!enabled && this._handlersBound) {
-                for (const [e, fn, _, bindWhenDisabled] of this._registered) {
-                    if (bindWhenDisabled)
-                        continue;
-                    e.removeListener(fn);
-                }
-                this._handlersBound = false;
-            }
-        };
         this._zcomponent = getCurrentZComponentConstruction();
-        this.enabledResolved.addListener(this._updateHandlers);
+        observe(this, 'enabledResolved', this._updateHandlers, { callImmediately: true });
     }
     /**
      * Gets the disposed status of the entity.
      * @returns {boolean} The disposed status.
+     * @zignore
      */
     get disposed() {
         return this._disposed;
     }
     /**
-     * Sets the disposed status of the entity.
-     * @param {boolean} v - The new disposed status.
-     * @private
+     * @zgroup Behavior
+     * @zgrouppriority 5
+     * @default true
      */
-    set disposed(v) {
-        this._disposed = v;
+    enabled = true;
+    /**
+     * This will have value `false` if this entity, or any of its parents, have `enabled` set to `false`.
+     *
+     * To change the `enabled` status of this entity, use the `enabled` property instead.
+     *
+     * The precise implications of `enabled` being false will vary between entities,
+     * but in general disabled entities:
+     *  - should not emit any events,
+     *  - should not take any action, e.g. navigate the user to a different page,
+     *  - should not perform any network communication,
+     *  - should not make changes to other behaviors or components in the experience,
+     *  - should minimise any runtime performance cost.
+     *
+     * Disabled entities will typically remain visible (if they have a visible appearance).
+     * @zignore
+     */
+    get enabledResolved() {
+        return this._enabledResolved;
     }
     /**
      * Get the instance of the ZComponent that constructed this entity.
@@ -99,6 +83,7 @@ export class Entity {
      *
      * @param type The ZComponent class that you are expecting to receive
      * @returns The instance of the ZComponent that constructed this component or behavior
+     * @zignore
      */
     getZComponentInstance(type) {
         if (this._zcomponent === undefined)
@@ -125,6 +110,49 @@ export class Entity {
         e.removeListener(fn);
         this._registered = this._registered.filter(entry => entry[0] !== e || entry[1] !== fn);
     }
+    /**
+     * @zignore
+     */
+    observe(object, prop, fn, options) {
+        const opts = { ...options };
+        this._observed.push([object, prop, fn, opts]);
+        observe(object, prop, fn, opts);
+    }
+    /**
+     * @zignore
+     */
+    unobserve(object, prop, fn) {
+        unobserve(object, prop, fn);
+        this._observed = this._observed.filter(entry => entry[0] !== object || entry[1] !== prop || entry[2] !== fn);
+    }
+    _updateHandlers = (enabled) => {
+        if (enabled && !this._handlersBound) {
+            for (const [e, fn, priority, bindWhenDisabled] of this._registered) {
+                if (bindWhenDisabled)
+                    continue;
+                e.addListener(fn, priority);
+            }
+            for (const [e, prop, fn, opts] of this._observed) {
+                if (opts?.bindWhenDisabled)
+                    continue;
+                observe(e, prop, fn, { ...opts, callImmediately: false });
+            }
+            this._handlersBound = true;
+        }
+        if (!enabled && this._handlersBound) {
+            for (const [e, fn, _, bindWhenDisabled] of this._registered) {
+                if (bindWhenDisabled)
+                    continue;
+                e.removeListener(fn);
+            }
+            for (const [e, prop, fn, opts] of this._observed) {
+                if (opts?.bindWhenDisabled)
+                    continue;
+                unobserve(e, prop, fn);
+            }
+            this._handlersBound = false;
+        }
+    };
     /**
      * Destroy this entity, cleaning up any resources that it has created and
      * handler functions or callbacks it has registered.
@@ -142,17 +170,22 @@ export class Entity {
      * This ensures that the dispose implementation of the parent class runs.
      *
      * @returns The result of a call to super.dispose()
+     * @zignore
      */
     dispose() {
-        this.enabledResolved.removeListener(this._updateHandlers);
+        unobserve(this, 'enabledResolved', this._updateHandlers);
         for (const entry of this._registered) {
             entry[0].removeListener(entry[1]);
         }
+        for (const entry of this._observed) {
+            unobserve(entry[0], entry[1], entry[2]);
+        }
         this._registered = [];
+        this._observed = [];
         this.onDispose.emit();
         this.onDispose.clearListeners();
-        this.disposed = true;
+        this._disposed = true;
         return undefined;
     }
+    static callSuperDispose = Symbol('Calling super.dispose() is mandatory');
 }
-Entity.callSuperDispose = Symbol('Calling super.dispose() is mandatory');

package/lib/event.d.ts

@@ -3,7 +3,8 @@ import { Observable } from './observable';
 /**
  * An event emitter class used to emit events and register listeners.
  */
-export declare class Event<Args extends Array<any> = []> extends Emitter<Args> {
+export declare class Event<Args extends Array<any> = [
+]> extends Emitter<Args> {
     hasListeners: Observable<boolean, never>;
     /**
      * Emit an event.