@zcomponent/core 1.29.0 → 2.0.0-alpha.2

package/lib/contexts/usereventcontext.js

@@ -5,18 +5,18 @@ import { Observable } from '../observable';
  * Manages and tracks user events within the application context.
  */
 export class UserEventContext extends Context {
-    constructor() {
-        super(...arguments);
-        /**
-         * Event triggered when a user event occurs.
-         */
-        this.onUserEvent = new EventClass();
-        /**
-         * An observable that emits the next user event as a promise.
-         * It gets resolved with the event object when a user event occurs.
-         */
-        this.nextUserEvent = new Observable(new Promise(resolve => (this._resolveNextUserEvent = resolve)), undefined, false);
-    }
+    /**
+     * Event triggered when a user event occurs.
+     */
+    onUserEvent = new EventClass();
+    _resolveNextUserEvent;
+    /**
+     * An observable that emits the next user event as a promise.
+     * It gets resolved with the event object when a user event occurs.
+     */
+    nextUserEvent = new Observable(new Promise(resolve => {
+        this._resolveNextUserEvent = resolve;
+    }), undefined, false);
     /**
      * Registers and emits a user event.
      * @param evt The user event to register.

package/lib/data/animation.d.ts

@@ -112,14 +112,22 @@ export type Easing = null | keyof typeof predefinedCurve | string;
 /**
  * Type representing a point in a Bezier curve.
  */
-export type Point = [number, number];
+export type Point = [
+    number,
+    number
+];
 /**
  * Type representing a Bezier curve.
  *
  * @note
  * Bezier represents the four control points between this keyframe and the next
  */
-export type Bezier = [Point, Point, Point, Point];
+export type Bezier = [
+    Point,
+    Point,
+    Point,
+    Point
+];
 /**
  * Type representing a curve, which is a collection of Bezier segments.
  */

package/lib/data/change.d.ts

@@ -1,5 +1,5 @@
-import { BehaviorByID, BehaviorData, ComputedHierarchy, EntityPropOverride, NodeByID, NodeData, ZComponentData } from './core';
 import { Prop } from '../types';
+import { BehaviorByID, BehaviorData, ComputedHierarchy, EntityPropOverride, NodeByID, NodeData, ZComponentData } from './core';
 /**
  * Computes and memoizes the hierarchy of nodes.
  *

package/lib/data/change.js

@@ -134,6 +134,11 @@ export function addNode(zcomp, info) {
     addNodeScriptNameToRegister(zcomp, info.data.id);
     addEntity(zcomp, info.data.id, info);
     computedHierarchies.delete(zcomp.nodes);
+    if (!info.data.parent) {
+        if (!zcomp.topLevelComponents)
+            zcomp.topLevelComponents = {};
+        zcomp.topLevelComponents[info.data.id] = true;
+    }
 }
 /**
  * Adds a new behavior to the specified ZComponentData.
@@ -310,6 +315,8 @@ export function deleteNode(zcomp, id) {
     removeNodeLabelFromRegister(zcomp, id);
     removeNodeScriptNameFromRegister(zcomp, id);
     delete zcomp.nodes[id];
+    if (zcomp.topLevelComponents)
+        delete zcomp.topLevelComponents[id];
     computedHierarchies.delete(zcomp.nodes);
 }
 /**

package/lib/data/core.d.ts

@@ -22,7 +22,10 @@ export type ComputedHierarchy = {
     [id: string]: string[];
 };
 export type Import = string;
-export type ParsedImport = [string, string];
+export type ParsedImport = [
+    string,
+    string
+];
 export type ElementType = Import;
 export type PropType = string;
 export interface ZComponentData {
@@ -54,6 +57,9 @@ export interface ZComponentData {
     tags?: string[];
     allowedParents?: string[];
     comments?: string[];
+    topLevelComponents?: {
+        [id: string]: boolean;
+    };
 }
 export interface NodeData {
     id: string;
@@ -61,6 +67,8 @@ export interface NodeData {
     scriptName?: string;
     type: ElementType;
     locked?: boolean;
+    excludeRuntime?: boolean;
+    excludeDesignTime?: boolean;
     parent?: {
         id: string;
         order: string;

package/lib/data/index.d.ts

@@ -1,3 +1,3 @@
-export * from './core';
 export * from './animation';
 export * from './change';
+export * from './core';

package/lib/data/index.js

@@ -1,3 +1,3 @@
-export * from './core';
 export * from './animation';
 export * from './change';
+export * from './core';

package/lib/decorators.d.ts

@@ -0,0 +1,348 @@
+import { Behavior } from './behavior';
+import type { Component } from './component';
+import { Context, ContextManager } from './context';
+import type { Entity, RegisterOptions } from './entity';
+import { Event } from './event';
+import { MaterialSymbol } from './icons';
+import { Observable } from './observable';
+import { TypeHint, ValuesType } from './types';
+/**
+ * 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 declare function zObserve<EntityType extends Entity, ValueType>(withHandler?: (this: EntityType, v: ValueType, entity: EntityType, propName: string) => void, deep?: boolean): (value: undefined, context: any) => (this: EntityType, initialValue: ValueType) => ValueType;
+/**
+ * Configuration for property groups in the Mattercraft UI.
+ * Groups help organize related properties under collapsible sections.
+ */
+export interface ZPropGroup {
+    /** The display name of the group in the UI */
+    name: string;
+    /** Display order priority - higher values appear first */
+    priority?: number;
+    /** Whether the group should be collapsed by default */
+    collapsed?: boolean;
+}
+/**
+ * Configuration options for properties exposed to the Mattercraft UI.
+ */
+export interface ZPropOptions {
+    /** Property group - either a string name or full group configuration */
+    group?: string | ZPropGroup;
+    /** Display order priority within the group - higher values appear first */
+    priority?: number;
+    /** UI widget type (e.g., 'proportion', 'color-hex', 'angle-degrees', 'time-seconds') */
+    type?: keyof typeof TypeHint;
+    /** Constrains values to specific types (e.g., 'layerclipids', 'streamids', 'easings') */
+    values?: keyof typeof ValuesType | [
+        type: keyof typeof ValuesType,
+        param: string
+    ] | [
+        type: keyof typeof ValuesType,
+        param: string
+    ][];
+}
+/**
+ * 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 declare function zUI<T>(opts?: ZPropOptions): (val: any, context: any) => any;
+/**
+ * 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 declare function zIgnore(): (val: any, context: any) => void;
+export type UnwrapObservable<T> = T extends Observable<infer U, any> ? U : T;
+export type ExtractComponentConstructorProps<T extends new (...args: any[]) => Component> = T extends new (contextManager: ContextManager, props: infer P) => any ? P : {};
+export type ExtractComponentProps<T extends new (...args: any[]) => Component> = Partial<{
+    [K in keyof InstanceType<T> as K extends keyof Component | 'contextManager' | 'constructor' ? never : InstanceType<T>[K] extends Function ? never : K extends `_${string}` ? never : K]: UnwrapObservable<InstanceType<T>[K]>;
+}>;
+export type DefaultChildProps<T extends new (...args: any[]) => Component> = Partial<ExtractComponentProps<T> & ExtractComponentConstructorProps<T>>;
+/**
+ * Base configuration options for registering entities (components and behaviors) with Mattercraft.
+ */
+export interface ZEntityDecOptions {
+    /**
+     * A list of tags that can be used elsewhere to reference this type of entity.
+     * Tags help with categorization and search in the Mattercraft UI.
+     */
+    tags?: string[];
+    /**
+     * Set to a list of tags to limit where Mattercraft's user interface will allow the user to create a new instance
+     * of this entity. It's possible to use a glob pattern, e.g.: 'three/Object3D/**'
+     */
+    parents?: string[];
+    /**
+     * The icon to show for this entity when it appears in the trees and menus of Mattercraft's user interface.
+     * Icons can be chosen from the [Material Symbols icon set](https://fonts.google.com/icons).
+     */
+    icon?: MaterialSymbol;
+    /**
+     * If supplied, Mattercraft's 'New' menu will list this entity under a group of this name.
+     */
+    group?: string;
+}
+/**
+ * Configuration for default child nodes that are automatically added when a component is created.
+ */
+export interface DefaultChild {
+    /**
+     * A name for this node in the Hierarchy.
+     */
+    label: string;
+    /**
+     * The type of the node to initialize. This should be of the form of the import file, a `#`, then the export name from that file.
+     *
+     * @example `@zcomponent/three/lib/components/meshes/Box#Box`
+     */
+    type: string;
+    /**
+     * An object containing any initial values to set as props of the created node.
+     */
+    props?: {
+        [id: string]: any;
+    };
+}
+/**
+ * Configuration options specific to components registered with @zComponent.
+ */
+export interface ZComponentDecOptions extends ZEntityDecOptions {
+    /**
+     * An array of children to automatically add under this entity when it's added to the Hierarchy.
+     * Useful for creating complex components with a predefined structure.
+     */
+    defaultChildren?: DefaultChild[];
+}
+/**
+ * Configuration options specific to behaviors registered with @zBehavior.
+ */
+export interface ZBehaviorDecOptions extends ZEntityDecOptions {
+    /**
+     * If true, this behavior will be constructed and run in the editor at design time.
+     * Useful for behaviors that provide preview functionality or editor-specific features.
+     */
+    runAtDesignTime?: boolean;
+}
+type ClassDecorator<TFunction extends Function> = (target: TFunction) => TFunction | void;
+/**
+ * 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 declare function zComponent<T extends new (...args: any[]) => Component>(opts?: ZComponentDecOptions): ClassDecorator<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 declare function zBehavior<T extends new (...args: any[]) => Behavior>(opts?: ZBehaviorDecOptions): ClassDecorator<T>;
+type KeysOfType<T, KT> = Exclude<{
+    [K in keyof T]: T[K] extends KT ? K : never;
+}[keyof T], undefined>;
+type EventArgs<E> = E extends Event<infer X> ? X : never;
+/**
+ * Automatically registers a method as an event listener during entity initialization.
+ * The decorated method will be called whenever the specified event is emitted.
+ * Supports three patterns: direct event objects, events from contexts, and events from the entity itself.
+ *
+ * @decorator
+ * @param event - Direct event object to listen to
+ * @param opts - Optional registration options (e.g., priority, once)
+ * @returns A method decorator that registers the event listener
+ *
+ * @example
+ * ```typescript
+ * // Listen to a direct event object
+ * @zRegister(someEvent)
+ * private handleEvent(data: EventData) {
+ *     console.log('Event received:', data);
+ * }
+ * ```
+ */
+export declare function zRegister<EntityType extends Entity, EventType extends Event<any>, EventArgsType extends EventArgs<EventType>>(event: EventType, opts?: RegisterOptions): (originalMethod: (...args: EventArgsType) => void, context: ClassMethodDecoratorContext<EntityType>) => any;
+/**
+ * Registers a method to listen to an event from a context.
+ *
+ * @decorator
+ * @param contextConstructor - The context class constructor
+ * @param prop - The property name of the event in the context
+ * @param opts - Optional registration options
+ * @returns A method decorator that registers the event listener
+ *
+ * @example
+ * ```typescript
+ * // Listen to an event from a context
+ * @zRegister(AudioContext, 'onVolumeChange')
+ * private handleVolumeChange(volume: number) {
+ *     this.updateVolume(volume);
+ * }
+ * ```
+ */
+export declare function zRegister<EntityType extends Entity, ContextType extends Context, PropType extends KeysOfType<ContextType, Event<any>>, EventArgsType extends EventArgs<ContextType[PropType]>>(contextConstructor: new (...args: any[]) => ContextType, prop: PropType, opts?: RegisterOptions): (originalMethod: (...args: EventArgsType) => void, context: ClassMethodDecoratorContext<EntityType>) => any;
+/**
+ * Registers a method to listen to an event from the entity itself.
+ *
+ * @decorator
+ * @param prop - The property name of the event in the entity
+ * @param opts - Optional registration options
+ * @returns A method decorator that registers the event listener
+ *
+ * @example
+ * ```typescript
+ * // Listen to an event from the same entity
+ * @zRegister('onStateChange')
+ * private handleStateChange(newState: State) {
+ *     this.processStateChange(newState);
+ * }
+ *
+ * // With registration options
+ * @zRegister('onClick', { once: true })
+ * private handleFirstClick() {
+ *     this.initializeOnFirstInteraction();
+ * }
+ * ```
+ */
+export declare function zRegister<EntityType extends Entity, PropType extends KeysOfType<EntityType, Event<any>>, EventArgsType extends EventArgs<EntityType[PropType]>>(prop: PropType, opts?: RegisterOptions): (originalMethod: (...args: EventArgsType) => void, context: ClassMethodDecoratorContext<EntityType>) => any;
+export {};