@zcomponent/core 0.0.12 → 0.0.13

package/lib/behavior.d.ts

@@ -1,36 +1,22 @@
-import { Component, ConstructorForComponent } from './component';
+import { Component } from './component';
 import { ContextManager } from './context';
-import { Event } from './event';
-import { Observable } from './observable';
-import { ZComponent } from './zcomponent';
+import { Entity } from './entity';
 export type BehaviorConstructor<BehaviorType = Behavior, K extends Component = Component> = BehaviorType extends Behavior<K> ? new (contextManager: ContextManager, instance: K, ...args: any[]) => BehaviorType : never;
 export type ConstructorPropsOfBehavior<BehaviorType> = BehaviorType extends Behavior<infer R> ? R : never;
 export type BehaviorConstructorProps = {
     [id: string]: unknown;
 };
-export declare class Behavior<InstanceType extends Component = Component> {
+export declare class Behavior<InstanceType extends Component = Component> extends Entity {
     protected readonly contextManager: ContextManager;
     readonly instance: InstanceType;
-    private static callSuperDispose;
-    onDispose: Event<[]>;
-    private _registered;
-    private _zcomponent;
-    constructor(contextManager: ContextManager, instance: InstanceType);
-    getZComponentInstance<T extends ZComponent = ZComponent>(type?: ConstructorForComponent<T>): T;
-    private _updateEnabledResolved;
     /**
-     * @zprop
-     * @zdefault true
-     * @zgroup Behavior
-     * @zgrouppriority 10
+     * Constructs this behavior
+     *
+     * @param contextManager The current ContextManager
+     * @param instance The instance of the component that this behavior is attached to
      */
-    enabled: Observable<boolean, never>;
-    enabledResolved: Observable<boolean, never>;
-    register<Args extends Array<any>>(evt: Event<Args>, fn: (...args: Args) => void): any;
-    register<Type>(observable: Observable<Type>, fn: (v: Type) => void): any;
-    unregister<Args extends Array<any>>(evt: Event<Args>, fn: (...args: Args) => void): any;
-    unregister<Type>(observable: Observable<Type>, fn: (v: Type) => void): any;
-    dispose(): never;
+    constructor(contextManager: ContextManager, instance: InstanceType);
+    private _updateEnabledResolved;
 }
 export declare function shouldBehaviorRunAtDesignTime(b: BehaviorConstructor): boolean;
 export declare function registerBehaviorRunAtDesignTime(b: BehaviorConstructor): Set<new (contextManager: ContextManager, instance: Component<any, import("./component").ConstructorProps>, ...args: any[]) => Behavior<Component<any, import("./component").ConstructorProps>>>;

package/lib/behavior.js

@@ -1,12 +1,15 @@
-import { Event } from './event';
-import { Observable } from './observable';
-import { getCurrentZComponentConstruction } from './zcomponentconstruction';
-export class Behavior {
+import { Entity } from './entity';
+export class Behavior extends Entity {
+    /**
+     * Constructs this behavior
+     *
+     * @param contextManager The current ContextManager
+     * @param instance The instance of the component that this behavior is attached to
+     */
     constructor(contextManager, instance) {
+        super();
         this.contextManager = contextManager;
         this.instance = instance;
-        this.onDispose = new Event();
-        this._registered = [];
         this._updateEnabledResolved = () => {
             let newValue = this.enabled.value;
             if (this.instance.enabledResolved?.value === false)
@@ -15,55 +18,10 @@ export class Behavior {
                 this.enabledResolved.value = newValue;
             }
         };
-        /**
-         * @zprop
-         * @zdefault true
-         * @zgroup Behavior
-         * @zgrouppriority 10
-         */
-        this.enabled = new Observable(true);
-        this.enabledResolved = new Observable(true);
-        this._zcomponent = getCurrentZComponentConstruction();
         this.register(this.enabled, this._updateEnabledResolved);
         this.register(instance.enabledResolved, this._updateEnabledResolved);
     }
-    getZComponentInstance(type) {
-        if (this._zcomponent === undefined)
-            throw new Error("getZComponentInstance called in behavior that's not part of a ZComponent");
-        if (!type)
-            return this._zcomponent;
-        if (this._zcomponent instanceof type)
-            return this._zcomponent;
-        throw new Error("getZComponentInstance called in behavior passing wrong kind of ZComponent");
-    }
-    register(e, fn) {
-        if (e instanceof Event)
-            e.bindfn(fn);
-        else if (e instanceof Observable)
-            e.withValue(fn);
-        this._registered.push([e, fn]);
-    }
-    unregister(e, fn) {
-        if (e instanceof Event)
-            e.unbindfn(fn);
-        else if (e instanceof Observable)
-            e.removeWithValue(fn);
-        this._registered = this._registered.filter(entry => (entry[0] !== e || entry[1] !== fn));
-    }
-    dispose() {
-        for (const entry of this._registered) {
-            if (entry[0] instanceof Event)
-                entry[0].unbindfn(entry[1]);
-            else if (entry[0] instanceof Observable)
-                entry[0].removeWithValue(entry[1]);
-        }
-        this._registered = [];
-        this.onDispose.emit();
-        this.onDispose.clear();
-        return undefined;
-    }
 }
-Behavior.callSuperDispose = Symbol('Calling super.dispose() is mandatory');
 const behaviorsToRunAtDesignTime = new Set();
 export function shouldBehaviorRunAtDesignTime(b) {
     return behaviorsToRunAtDesignTime.has(b);

package/lib/component.d.ts

@@ -1,7 +1,6 @@
 import { ContextManager } from './context';
-import { Event } from './event';
+import { Entity } from './entity';
 import { Observable } from './observable';
-import { ZComponent } from './zcomponent';
 export type ConstructorPropsOfComponent<ComponentType> = ComponentType extends Component<any, infer R> ? R : never;
 export type ComponentConstructor<ConstructorPropsType extends ConstructorProps, ComponentType extends Component> = new (props: ConstructorPropsType, contextManager: ContextManager) => ComponentType;
 export type ConstructorForComponent<ComponentType extends Component = Component> = new (contextManager: ContextManager, props: ComponentType extends Component<any, infer PropsType> ? PropsType : never) => ComponentType;
@@ -15,45 +14,54 @@ export interface ConstructorProps {
     [id: string]: any;
     children?: ComponentChildren;
 }
-export declare class Component<ElementType = any, ConstructorPropsType extends ConstructorProps = ConstructorProps> {
+export declare class Component<ElementType = any, ConstructorPropsType extends ConstructorProps = ConstructorProps> extends Entity {
     readonly contextManager: ContextManager;
     protected constructorProps?: ConstructorPropsType | undefined;
+    /**
+     * The raw element(s) that this component exposes
+     */
     element?: ElementType;
-    readonly onDispose: Event<[]>;
     readonly children: Component[];
     parent?: Component;
-    disposed: boolean;
-    private _registered;
-    private _zcomponent;
     constructor(contextManager: ContextManager, constructorProps?: ConstructorPropsType | undefined);
     constructChildren(children: ComponentChildren, contextManager?: ContextManager): void;
-    getZComponentInstance<T extends ZComponent = ZComponent>(type?: ConstructorForComponent<T>): T | undefined;
+    /**
+     * Adds the supplied component instance as a child of this component, removing it from any existing parent.
+     *
+     * @param c The component instance to add
+     */
     appendChild(c: Component): void;
+    /**
+     * Removes the supplied component instance from the list of children.
+     * @param c The component to remove
+     */
     removeChild(c: Component): void;
+    /**
+     * Removes this component from its parent component.
+     */
     remove(): void;
-    get elementsResolved(): any[];
     /**
-     * @zprop
-     * @zdefault true
-     * @zgroup Behavior
-     * @group Behavior
-     * @zgrouppriority 10
+     * An array of the elements that this component instance exposes. In the case that this component
+     * does not expose any elements of its own, this will be an array of the elements
+     * exposed by this component's children.
      */
-    enabled: Observable<boolean, never>;
-    enabledResolved: Observable<boolean, never>;
+    get elementsResolved(): any[];
     /**
+     * An array of string 'tags' assocated with this component.
+     *
+     * The `getComponentsByTag(mgr, tag)` function can be used to get an array of components
+     * with the supplied tag.
+     *
+     * By default, tags are scoped to the ZComponent instance that a component is constructed by.
+     * Tags that begin with `global:` are scoped to the experience as a whole.
+     *
      * @zprop
      * @zgroup Other
      * @group Other
      * @zgrouppriority 0
      */
     tags: Observable<string[], never>;
-    protected register<Args extends Array<any>>(evt: Event<Args>, fn: (...args: Args) => void): any;
-    protected register<Type>(observable: Observable<Type>, fn: (v: Type) => void): any;
-    protected unregister<Args extends Array<any>>(evt: Event<Args>, fn: (...args: Args) => void): any;
-    protected unregister<Type>(observable: Observable<Type>, fn: (v: Type) => void): any;
     private _updateEnabledResolved;
     private _updateTags;
     dispose(): never;
-    private static callSuperDispose;
 }

package/lib/component.js

@@ -1,25 +1,21 @@
 import { TagContext } from './contexts/tagcontext';
-import { Event } from './event';
+import { Entity } from './entity';
 import { Observable } from './observable';
-import { getCurrentZComponentConstruction } from './zcomponentconstruction';
-export class Component {
+export class Component extends Entity {
     constructor(contextManager, constructorProps) {
+        super();
         this.contextManager = contextManager;
         this.constructorProps = constructorProps;
-        this.onDispose = new Event();
         this.children = [];
-        this.disposed = false;
-        this._registered = [];
-        /**
-         * @zprop
-         * @zdefault true
-         * @zgroup Behavior
-         * @group Behavior
-         * @zgrouppriority 10
-         */
-        this.enabled = new Observable(true);
-        this.enabledResolved = new Observable(true);
         /**
+         * An array of string 'tags' assocated with this component.
+         *
+         * The `getComponentsByTag(mgr, tag)` function can be used to get an array of components
+         * with the supplied tag.
+         *
+         * By default, tags are scoped to the ZComponent instance that a component is constructed by.
+         * Tags that begin with `global:` are scoped to the experience as a whole.
+         *
          * @zprop
          * @zgroup Other
          * @group Other
@@ -40,7 +36,6 @@ export class Component {
             const context = this.contextManager.get(TagContext);
             context.registerComponent(this, this.tags.value);
         };
-        this._zcomponent = getCurrentZComponentConstruction();
         this.constructChildren(constructorProps?.children ?? []);
         this.register(this.enabled, this._updateEnabledResolved);
         this.register(this.tags, this._updateTags);
@@ -59,29 +54,39 @@ export class Component {
             }
         }
     }
-    getZComponentInstance(type) {
-        if (this._zcomponent === undefined)
-            throw new Error("getZComponentInstance called in component that's not part of a ZComponent");
-        if (!type)
-            return this._zcomponent;
-        if (this._zcomponent instanceof type)
-            return this._zcomponent;
-        throw new Error("getZComponentInstance called in component passing wrong kind of ZComponent");
-    }
+    /**
+     * Adds the supplied component instance as a child of this component, removing it from any existing parent.
+     *
+     * @param c The component instance to add
+     */
     appendChild(c) {
         c.remove();
         this.children.push(c);
         c.parent = this;
         c._updateEnabledResolved();
     }
+    /**
+     * Removes the supplied component instance from the list of children.
+     * @param c The component to remove
+     */
     removeChild(c) {
         const indx = this.children.indexOf(c);
         if (indx >= 0)
             this.children.splice(indx, 1);
+        if (c.parent === this)
+            delete c.parent;
     }
+    /**
+     * Removes this component from its parent component.
+     */
     remove() {
         this.parent?.removeChild(this);
     }
+    /**
+     * An array of the elements that this component instance exposes. In the case that this component
+     * does not expose any elements of its own, this will be an array of the elements
+     * exposed by this component's children.
+     */
     get elementsResolved() {
         if (this.element !== undefined) {
             if (Array.isArray(this.element))
@@ -94,22 +99,7 @@ export class Component {
         }
         return ret;
     }
-    register(e, fn) {
-        if (e instanceof Event)
-            e.bindfn(fn);
-        else if (e instanceof Observable)
-            e.withValue(fn);
-        this._registered.push([e, fn]);
-    }
-    unregister(e, fn) {
-        if (e instanceof Event)
-            e.unbindfn(fn);
-        else if (e instanceof Observable)
-            e.removeWithValue(fn);
-        this._registered = this._registered.filter(entry => (entry[0] !== e || entry[1] !== fn));
-    }
     dispose() {
-        this.disposed = true;
         for (const child of this.children) {
             try {
                 child.dispose();
@@ -117,17 +107,7 @@ export class Component {
             catch (err) { }
         }
         this.children.length = 0;
-        for (const entry of this._registered) {
-            if (entry[0] instanceof Event)
-                entry[0].unbindfn(entry[1]);
-            else if (entry[0] instanceof Observable)
-                entry[0].removeWithValue(entry[1]);
-        }
-        this._registered = [];
-        this.onDispose.emit();
-        this.onDispose.clear();
         this.contextManager.get(TagContext).unregisterComponent(this);
-        return undefined;
+        return super.dispose();
     }
 }
-Component.callSuperDispose = Symbol('Calling super.dispose() is mandatory');

package/lib/entity.d.ts

@@ -0,0 +1,102 @@
+import { ConstructorForComponent } from "./component";
+import { Event } from "./event";
+import { Observable } from "./observable";
+import { ZComponent } from "./zcomponent";
+export declare class Entity {
+    private _registered;
+    private _zcomponent;
+    private _disposed;
+    /**
+     * An event that is fired as the last act of this entity being destroyed.
+     */
+    readonly onDispose: Event<[]>;
+    constructor();
+    get disposed(): boolean;
+    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
+     */
+    enabled: Observable<boolean, never>;
+    /**
+     * 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).
+     */
+    enabledResolved: Observable<boolean, never>;
+    /**
+     * Get the instance of the ZComponent that constructed this entity.
+     *
+     * If you pass the class of a ZComponent as the `type` parameter, this function will ensure that it
+     * returns an instance of that ZComponent. If this component or behavior was constructed by a different
+     * ZComponent class, or by a different entity altogether, the function with `throw` an error.
+     *
+     * @param type The ZComponent class that you are expecting to receive
+     * @returns The instance of the ZComponent that constructed this component or behavior
+     */
+    getZComponentInstance<T extends ZComponent = ZComponent>(type?: ConstructorForComponent<T>): T;
+    /**
+     * Register a function to be called when an Event is fired, or an Observable's value changes.
+     *
+     * Using this function, rather than attaching your handler directly to the Event or Observable,
+     * ensures your handler is automatically released when this entity is disposed.
+     *
+     * @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
+     */
+    register<Args extends Array<any>>(evt: Event<Args>, fn: (...args: Args) => void): any;
+    register<Type>(observable: Observable<Type>, fn: (v: Type) => void): any;
+    /**
+     * Unregisters a function that was previously registered to an Event or Observable.
+     *
+     * @param evt The Event or Observable
+     * @param fn The function that was passed in the call to `register`
+     */
+    unregister<Args extends Array<any>>(evt: Event<Args>, fn: (...args: Args) => void): any;
+    unregister<Type>(observable: Observable<Type>, fn: (v: Type) => void): any;
+    /**
+     * Destroy this entity, cleaning up any resources that it has created and
+     * handler functions or callbacks it has registered.
+     *
+     * The base class implementation automatically unregisters any handler functions registered
+     * using `register(...)`.
+     *
+     * Override this function in your own components and behaviors to clean up any resources
+     * you have created. If you do override this function, end it with:
+     *
+     * ```
+     * return super.dispose();
+     * ```
+     *
+     * This ensures that the dispose implementation of the parent class runs.
+     *
+     * @returns The result of a call to super.dispose()
+     */
+    dispose(): never;
+    private static callSuperDispose;
+}

package/lib/entity.js

@@ -0,0 +1,121 @@
+import { Event } from "./event";
+import { Observable } from "./observable";
+import { getCurrentZComponentConstruction } from "./zcomponentconstruction";
+export class Entity {
+    constructor() {
+        this._registered = [];
+        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._zcomponent = getCurrentZComponentConstruction();
+    }
+    get disposed() {
+        return this._disposed;
+    }
+    set disposed(v) {
+        this._disposed = v;
+    }
+    /**
+     * Get the instance of the ZComponent that constructed this entity.
+     *
+     * If you pass the class of a ZComponent as the `type` parameter, this function will ensure that it
+     * returns an instance of that ZComponent. If this component or behavior was constructed by a different
+     * ZComponent class, or by a different entity altogether, the function with `throw` an error.
+     *
+     * @param type The ZComponent class that you are expecting to receive
+     * @returns The instance of the ZComponent that constructed this component or behavior
+     */
+    getZComponentInstance(type) {
+        if (this._zcomponent === undefined)
+            throw new Error("getZComponentInstance called in entity that's not part of a ZComponent");
+        if (!type)
+            return this._zcomponent;
+        if (this._zcomponent instanceof type)
+            return this._zcomponent;
+        throw new Error("getZComponentInstance called in entity passing wrong kind of ZComponent");
+    }
+    register(e, fn) {
+        if (e instanceof Event)
+            e.bindfn(fn);
+        else if (e instanceof Observable)
+            e.withValue(fn);
+        this._registered.push([e, fn]);
+    }
+    unregister(e, fn) {
+        if (e instanceof Event)
+            e.unbindfn(fn);
+        else if (e instanceof Observable)
+            e.removeWithValue(fn);
+        this._registered = this._registered.filter(entry => (entry[0] !== e || entry[1] !== fn));
+    }
+    /**
+     * Destroy this entity, cleaning up any resources that it has created and
+     * handler functions or callbacks it has registered.
+     *
+     * The base class implementation automatically unregisters any handler functions registered
+     * using `register(...)`.
+     *
+     * Override this function in your own components and behaviors to clean up any resources
+     * you have created. If you do override this function, end it with:
+     *
+     * ```
+     * return super.dispose();
+     * ```
+     *
+     * This ensures that the dispose implementation of the parent class runs.
+     *
+     * @returns The result of a call to super.dispose()
+     */
+    dispose() {
+        for (const entry of this._registered) {
+            if (entry[0] instanceof Event)
+                entry[0].unbindfn(entry[1]);
+            else if (entry[0] instanceof Observable)
+                entry[0].removeWithValue(entry[1]);
+        }
+        this._registered = [];
+        this.onDispose.emit();
+        this.onDispose.clear();
+        this.disposed = true;
+        return undefined;
+    }
+}
+Entity.callSuperDispose = Symbol('Calling super.dispose() is mandatory');

package/lib/types.d.ts

@@ -23,6 +23,7 @@ export interface ArrayType extends BaseType {
 export interface TupleType extends BaseType {
     name: 'tuple';
     children: Type[];
+    names?: string[];
 }
 export interface UnionType extends BaseType {
     name: 'union';

package/lib/types.js

@@ -124,6 +124,17 @@ function mergeValueComments(a, b) {
     }
     return ret;
 }
+function mergeTupleNames(a, b) {
+    if (!a.names || !b.names)
+        return;
+    if (a.names.length !== b.names.length)
+        return;
+    for (let i = 0; i < a.names.length; i++) {
+        if (a.names[i] !== b.names[i])
+            return;
+    }
+    return a.names;
+}
 export function mergeTypes(a, b) {
     if (!areTypesCompatible(a, b))
         return;
@@ -192,6 +203,7 @@ export function mergeTypes(a, b) {
                 typeHint,
                 comments: mergeComments(a.comments ?? [], b.comments ?? []),
                 children,
+                names: mergeTupleNames(a, b),
             };
         }
         case 'union':

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zcomponent/core",
-  "version": "0.0.12",
+  "version": "0.0.13",
   "description": "",
   "main": "index.js",
   "types": "index.d.ts",