@zcomponent/core 0.0.12 → 0.0.14

package/lib/entity.d.ts

@@ -0,0 +1,104 @@
+import { ConstructorForComponent } from "./component";
+import { ContextManager } from "./context";
+import { Event } from "./event";
+import { Observable } from "./observable";
+import { ZComponent } from "./zcomponent";
+export declare class Entity {
+    readonly contextManager: ContextManager;
+    private _registered;
+    private _zcomponent;
+    private _disposed;
+    /**
+     * An event that is fired as the last act of this entity being destroyed.
+     */
+    readonly onDispose: Event<[]>;
+    constructor(contextManager: ContextManager);
+    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,126 @@
+import { Event } from "./event";
+import { Observable } from "./observable";
+import { getCurrentZComponentConstruction } from "./zcomponentconstruction";
+export class Entity {
+    constructor(contextManager) {
+        this.contextManager = contextManager;
+        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) {
+        for (const entry of this._registered) {
+            if (entry[0] === e && entry[1] === fn)
+                return;
+        }
+        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/interfaces.d.ts

@@ -29,15 +29,12 @@ export interface ZComponentData {
     nodes: NodeByID;
     root: string;
     props: Props;
+    constructorProps?: Props;
     entityProps: PropsByID;
     entityConstructorProps: PropsByID;
     preview: Import;
-    propEntityOverrides?: {
-        [propName: string]: {
-            [entityID: string]: {
-                [propName: string]: boolean;
-            };
-        };
+    entityPropOverrides?: {
+        [id: string]: EntityPropOverride;
     };
     behaviors: BehaviorByID;
     animation?: Animation;
@@ -70,3 +67,30 @@ export interface BehaviorData {
         order: string;
     };
 }
+export type EntityPropOverride = PropEntityPropOverride | ImportEntityPropOverride | ContextValueEntityPropOverride;
+export declare enum EntityPropOverrideType {
+    ComponentProp = "componentprop",
+    Import = "import",
+    ContextValue = "contextvalue"
+}
+export interface BaseEntityPropOverride {
+    id: string;
+    entityID: string;
+    entityPropPath: (string | number)[];
+    entityPropIsConstructor: boolean;
+    type: EntityPropOverrideType;
+}
+export interface PropEntityPropOverride extends BaseEntityPropOverride {
+    propName: string;
+    isConstructorProp: boolean;
+    type: EntityPropOverrideType.ComponentProp;
+}
+export interface ImportEntityPropOverride extends BaseEntityPropOverride {
+    imp: string;
+    type: EntityPropOverrideType.Import;
+}
+export interface ContextValueEntityPropOverride extends BaseEntityPropOverride {
+    imp: string;
+    val: string;
+    type: EntityPropOverrideType.ContextValue;
+}

package/lib/interfaces.js

@@ -1 +1,6 @@
-export {};
+export var EntityPropOverrideType;
+(function (EntityPropOverrideType) {
+    EntityPropOverrideType["ComponentProp"] = "componentprop";
+    EntityPropOverrideType["Import"] = "import";
+    EntityPropOverrideType["ContextValue"] = "contextvalue";
+})(EntityPropOverrideType || (EntityPropOverrideType = {}));

package/lib/selectors.d.ts

@@ -1,4 +1,4 @@
-import { Import, NodeByID, ParsedImport, Props } from './interfaces';
+import { EntityPropOverride, Import, NodeByID, ParsedImport, Props } from './interfaces';
 export declare function parseImport(i: Import): ParsedImport;
 export declare function constructImport(from: string, destFile: string, imp: string): string;
 export declare function getScriptName(n: string, requireUniqueIn: {
@@ -6,8 +6,20 @@ export declare function getScriptName(n: string, requireUniqueIn: {
 }): string;
 export declare function isValidVariableName(n: string): boolean;
 export declare function variableNameFromImport(imp: ParsedImport): string;
-export declare const typeDefinitionForComponent: (nodes: NodeByID, props: Props, scriptNames: {
+export type EntityPropOverrideByEntityPropPath = {
+    [entityID: string]: {
+        [propName: string]: {
+            [path: string]: EntityPropOverride;
+        };
+    };
+};
+export declare function entityPropOverrideByEntityAndProp(entityPropOverrides: {
+    [id: string]: EntityPropOverride;
+}): EntityPropOverrideByEntityPropPath;
+export declare function summaryForEntityPropOverrideDestination(o: EntityPropOverride): string;
+export declare const typeDefinitionForComponent: (nodes: NodeByID, props: Props, constructorProps: Props | undefined, scriptNames: {
     [id: string]: {
         [id: string]: boolean;
     };
-}, url: string) => string;
+} | undefined, url: string) => string;
+export declare function getSafeKeyName(n: string): string;

package/lib/selectors.js

@@ -1,3 +1,4 @@
+import { EntityPropOverrideType } from './interfaces';
 import * as path from 'path';
 import { outputForType } from './types';
 export function parseImport(i) {
@@ -117,11 +118,52 @@ export function variableNameFromImport(imp) {
         return imp[1];
     return 'unknown';
 }
-export const typeDefinitionForComponent = (nodes, props, scriptNames, url) => {
+export function entityPropOverrideByEntityAndProp(entityPropOverrides) {
+    const ret = Object.create(null);
+    for (const val of Object.values(entityPropOverrides)) {
+        if (!Array.isArray(val.entityPropPath) || val.entityPropPath.length < 1)
+            continue;
+        const obj = ret[val.entityID] || Object.create(null);
+        ret[val.entityID] = obj;
+        const propName = val.entityPropPath[0];
+        const arr = obj[propName] || Object.create(null);
+        obj[propName] = arr;
+        arr[val.entityPropPath.join('.')] = val;
+    }
+    return ret;
+}
+export function summaryForEntityPropOverrideDestination(o) {
+    switch (o.type) {
+        case EntityPropOverrideType.ComponentProp:
+            return 'Component Prop: ' + o.propName;
+        case EntityPropOverrideType.ContextValue: {
+            const imp = parseImport(o.imp);
+            if (imp[1] === 'default' && typeof imp[0] === 'string') {
+                const parts = imp[0].split(path.sep);
+                return parts[parts.length - 1] + '.' + o.val;
+            }
+            if (typeof imp[1] === 'string')
+                return imp[1] + '.' + o.val;
+            return `?.` + o.val;
+        }
+        case EntityPropOverrideType.Import: {
+            return o.imp;
+            // const imp = parseImport(o.imp);
+            // if (imp[1] === 'default' && typeof imp[0] === 'string') {
+            // 	const parts = imp[0].split(path.sep);
+            // 	return parts[parts.length - 1];
+            // }
+            // if (typeof imp[1] === 'string') return imp[1];
+            // return '?';
+        }
+    }
+    return '?';
+}
+export const typeDefinitionForComponent = (nodes, props, constructorProps, scriptNames, url) => {
     const importMapping = new Map();
     let indx = 0;
     let importStrings = [];
-    for (const scriptNameNodes of Object.values(scriptNames)) {
+    for (const scriptNameNodes of Object.values(scriptNames ?? {})) {
         for (const nodeID of Object.keys(scriptNameNodes)) {
             const node = nodes[nodeID];
             if (!node)
@@ -139,15 +181,20 @@ export const typeDefinitionForComponent = (nodes, props, scriptNames, url) => {
 
 ${importStrings.join('\n')}
 
+interface ConstructorProps {
+${Object.values(constructorProps ?? {}).map(typeOutputForConstructorProp).join('\n\n')}
+}
+
 /**
 * @zcomponent
+* @zicon zcomponent
 */
 declare class Comp extends ZComponent {
 
-	constructor(contextManager: ContextManager, constructorProps: {});
+	constructor(contextManager: ContextManager, constructorProps: ConstructorProps);
 
 	nodes: {
-${Object.entries(scriptNames).map(entry => {
+${Object.entries(scriptNames ?? {}).map(entry => {
         const values = Object.keys(entry[1]);
         if (values.length > 1) {
             return `\t\t${entry[0]}: {${values.map(e => `${JSON.stringify(e)}: ${importMapping.get(nodes[e].type)}`).join(', ')}},`;
@@ -158,16 +205,40 @@ ${Object.entries(scriptNames).map(entry => {
     }).join("\n")}
 	};
 
-${Object.values(props).map(typeOutputForProp).join('\n')}
+${Object.values(props).map(typeOutputForProp).join('\n\n')}
 }
 
 export default Comp;
 `;
 };
+function makeCommentSafe(c) {
+    return c.replaceAll('*/', '').split('\n').join('\n\t* ');
+}
 function typeOutputForProp(prop) {
-    return `	/**
+    const comments = (prop.comments && prop.comments.length > 0) ? '\n\t* ' + prop.comments.map(makeCommentSafe).join('\n\t*\n\t* ') + '\n\t* ' : '';
+    return `	/**${comments}
 	* @zprop
-	* ${prop.default && `@zdefault ${JSON.stringify(prop.default)}`}
+	* ${prop.default ? `@zdefault ${JSON.stringify(prop.default)}` : ''}
 	*/
 	public ${prop.name}: Observable<${outputForType(prop.type, true)}>;`;
 }
+function typeOutputForConstructorProp(prop) {
+    const comments = (prop.comments && prop.comments.length > 0) ? '\n\t* ' + prop.comments.map(makeCommentSafe).join('\n\t*\n\t* ') + '\n\t* ' : '';
+    return `	/**${comments}
+	* @zprop
+	* ${prop.default && `@zdefault ${JSON.stringify(prop.default)}`}
+	*/
+	${prop.name}: ${outputForType(prop.type, true)};`;
+}
+export function getSafeKeyName(n) {
+    if (n.length === 0)
+        return '_';
+    let scriptname = n.replace(' ', '_');
+    scriptname = scriptname.replace('-', '_');
+    scriptname = scriptname.replace('.', '_');
+    scriptname = scriptname.replace(/[^a-zA-Z0-9_]/g, '');
+    if (scriptname.match(/^[0-9]/)) {
+        scriptname = 'n' + scriptname;
+    }
+    return scriptname;
+}

package/lib/types.d.ts

@@ -1,3 +1,4 @@
+import { EntityPropOverride } from "./interfaces";
 export interface BaseType {
     comments?: string[];
     typeHint?: TypeHint;
@@ -23,6 +24,7 @@ export interface ArrayType extends BaseType {
 export interface TupleType extends BaseType {
     name: 'tuple';
     children: Type[];
+    names?: string[];
 }
 export interface UnionType extends BaseType {
     name: 'union';
@@ -68,10 +70,18 @@ export interface Prop {
     groupPriority?: number;
     values?: Values[];
 }
+export interface DefaultChild {
+    label: string;
+    type: string;
+    initialProps: {
+        [id: string]: any;
+    };
+}
+export type ComponentInfoType = "component" | "behavior" | "context";
 export interface ComponentInfo {
     name: string;
     file: string;
-    type: "component" | "behavior";
+    type: ComponentInfoType;
     isDefault?: boolean;
     constructorProps: {
         [id: string]: Prop;
@@ -85,10 +95,23 @@ export interface ComponentInfo {
     tags: string[];
     allowedChildren: string[];
     allowedParents?: string[];
+    defaultChildren?: DefaultChild[];
+}
+export interface ValueInfo {
+    name: string;
+    file: string;
+    isDefault?: boolean;
+    type: Type;
+    comments?: string[];
+}
+export interface SourceFileTypeInfo {
+    components: {
+        [id: string]: ComponentInfo;
+    };
+    values: {
+        [id: string]: ValueInfo;
+    };
 }
-export type SourceFileTypeInfo = {
-    [id: string]: ComponentInfo;
-};
 export type TypeInfoByFileName = {
     [id: string]: SourceFileTypeInfo;
 };
@@ -104,3 +127,8 @@ export interface TemplateInfo {
 export declare function symbolPathFromFilename(f: string): string;
 export declare function isValidValueForType(def: any, t: Type, allowUndefined?: boolean): boolean;
 export declare function outputForType(t: Type, alwaysBasic?: boolean): string;
+export declare function overridesAreCompatible(a: {
+    [path: string]: EntityPropOverride;
+}, b: {
+    [path: string]: EntityPropOverride;
+}): boolean;

package/lib/types.js

@@ -1,3 +1,5 @@
+import { EntityPropOverrideType } from "./interfaces";
+import { getSafeKeyName } from "./selectors";
 export var TypeHint;
 (function (TypeHint) {
     TypeHint["proportion"] = "proportion";
@@ -124,6 +126,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 +205,7 @@ export function mergeTypes(a, b) {
                 typeHint,
                 comments: mergeComments(a.comments ?? [], b.comments ?? []),
                 children,
+                names: mergeTupleNames(a, b),
             };
         }
         case 'union':
@@ -279,6 +293,9 @@ function getBasicType(t) {
         case 'array':
             return outputForType(t.child) + '[]';
         case 'tuple':
+            if (Array.isArray(t.names) && t.names.length === t.children.length) {
+                return `[${t.children.map((c, indx) => `${getSafeKeyName(t.names[indx])}: ${outputForType(c)}`).join(', ')}]`;
+            }
             return `[${t.children.map(c => outputForType(c)).join(', ')}]`;
         case 'unknown':
             return 'any';
@@ -298,3 +315,59 @@ function getBasicType(t) {
             return 'Event';
     }
 }
+export function overridesAreCompatible(a, b) {
+    const bkeys = new Set(Object.keys(b));
+    for (const [p, obj] of Object.entries(a)) {
+        if (!b[p])
+            return false;
+        if (!overrideAreCompatible(obj, b[p]))
+            return false;
+        bkeys.delete(p);
+    }
+    if (bkeys.size > 0)
+        return false;
+    return true;
+}
+function overrideAreCompatible(a, b) {
+    if (a && b) {
+        if (a.type !== b.type)
+            return false;
+        if (a.entityPropPath.length !== b.entityPropPath.length)
+            return false;
+        if (a.entityPropIsConstructor !== b.entityPropIsConstructor)
+            return false;
+        for (let i = 0; i < a.entityPropPath.length; i++) {
+            if (a.entityPropPath[i] !== b.entityPropPath[i])
+                return false;
+        }
+        switch (a.type) {
+            case EntityPropOverrideType.ComponentProp: {
+                const bt = b;
+                if (a.isConstructorProp !== bt.isConstructorProp)
+                    return false;
+                if (a.propName !== bt.propName)
+                    return false;
+                return true;
+            }
+            case EntityPropOverrideType.ContextValue: {
+                const bt = b;
+                if (a.imp !== bt.imp)
+                    return false;
+                if (a.val !== bt.val)
+                    return false;
+                return true;
+            }
+            case EntityPropOverrideType.Import: {
+                const bt = b;
+                if (a.imp !== bt.imp)
+                    return false;
+                return true;
+            }
+        }
+    }
+    if (!a && b)
+        return false;
+    if (a && !b)
+        return false;
+    return true;
+}

package/lib/zcomponent.d.ts

@@ -1,5 +1,6 @@
 import { Component, ComponentChildren, ConstructorProps } from './component';
 import { ContextManager, Context } from './context';
+import { Entity } from './entity';
 import { ZComponentData } from './interfaces';
 export interface ZComponentOptions {
     data: ZComponentData;
@@ -35,21 +36,25 @@ export declare class ZComponent<RootType = any> extends Component<RootType> {
     nodes: {
         [id: string]: Component | Component[];
     };
-    entityByID: Map<string, any>;
-    entityByLabel: Map<string, any>;
+    entityByID: Map<string, Entity>;
+    entityByLabel: Map<string, Entity>;
     private _constructedResolve;
     constructed: Promise<void>;
     isConstructed: boolean;
     private _nodesById;
     private _behaviorsToInitialize;
+    private _constructorPropOverridesByEntityID;
     constructor(contextManager: ContextManager, constructorProps: ConstructorProps, _opts: ZComponentOptions);
     private _constructorForNode;
     private _constructorForBehavior;
     private _inflateBehaviors;
     private _wrapBehaviors;
     notifyPropsChanged(entries: Map<string, Set<string>>): void;
+    private _initializeOverrides;
+    private _initializeConstructorPropOverrides;
     private _initializeComponentProps;
     private _setEntityProp;
+    private _setEntityPropPath;
     _getNodeById(id: string): Component | undefined;
     dispose(): never;
 }