@zcomponent/core 0.0.8 → 0.0.9

package/lib/observable.d.ts

@@ -1,5 +1,37 @@
-declare type Resolved<T, M> = [T] extends [never] ? M : T;
-export declare class Observable<T = never, M extends any[] | [] | never = never> {
+type Resolved<T, M> = [T] extends [never] ? M : T;
+/**
+ * A class that holds a value and watches it for changes (deeply by default).
+ *
+ * An Observable can be constructed with a default value like this:
+ *
+ * ```ts
+ * const myVariable = new Observable(false);
+ * ```
+ *
+ * Observable will automatically infer the type from the default value. You may also specify the type using the first template parameter:
+ *
+ * ```ts
+ * const myVariable = new Observable<boolean|string>(false);
+ * ```
+ *
+ * The value of the Observable may be accessed and changed using the `value` parameter:
+ * ```ts
+ * console.log(myVariable.value);
+ *
+ * myVariable.value = 4;
+ * ```
+ *
+ * Setting `value` to `undefined` restores the value to the default specified in the constructor.
+ *
+ * A function can be registered to receive changes to the value (or any of its recursive descendent keys or elements):
+ * ```ts
+ * const myVariable = new Observable(false, newValue => console.log(newValue));
+ * ```
+ *
+ * @typeParam Type - The type of the contained value
+ * @typeParam TypeInternal - An internal type used to improve automatic type detection
+ */
+export declare class Observable<Type = never, TypeInternal extends any[] | [] | never = never> {
     private _default;
     private _deep;
     private _proxies;
@@ -7,13 +39,25 @@ export declare class Observable<T = never, M extends any[] | [] | never = never>
     private _nextToken;
     private _handlersByToken;
     private _tokenByHandler;
-    constructor(def: M, withHandler?: ((v: M) => void), deep?: boolean);
-    constructor(def: T, withHandler?: ((v: T) => void), deep?: boolean);
-    get value(): Resolved<T, M>;
+    /**
+     * Constructs a new Observable
+     *
+     * @param def - The default (and initial) value of the Observable.
+     * @param withHandler - A function that will be called when the value (or any of its recursive descendent keys or elements) is changed
+     * @param deep - Set to false to only track changes to the top level `value` itself (and not any of its descendent keys or elements)
+     */
+    constructor(def: TypeInternal, withHandler?: ((v: TypeInternal) => void), deep?: boolean);
+    constructor(def: Type, withHandler?: ((v: Type) => void), deep?: boolean);
+    /**
+     * Access the current value for this Observable. Changing this value (or, unless deep inspection is disabled, its recursive elements and keys) will trigger any registered handlers to be called with the new value.
+     *
+     * Setting `value` to `undefined` will restore the value to the default specified in the constructor.
+     */
+    get value(): Resolved<Type, TypeInternal>;
     private _wrap;
-    set value(v: Resolved<T, M> | undefined);
-    withValue(fn: (v: Resolved<T, M>) => void): number;
-    removeWithValue(fnOrToken: number | ((v: Resolved<T, M>) => void)): void;
+    set value(v: Resolved<Type, TypeInternal> | undefined);
+    withValue(fn: (v: Resolved<Type, TypeInternal>) => void): number;
+    removeWithValue(fnOrToken: number | ((v: Resolved<Type, TypeInternal>) => void)): void;
     private _emitValue;
 }
 export {};

package/lib/observable.js

@@ -1,3 +1,35 @@
+/**
+ * A class that holds a value and watches it for changes (deeply by default).
+ *
+ * An Observable can be constructed with a default value like this:
+ *
+ * ```ts
+ * const myVariable = new Observable(false);
+ * ```
+ *
+ * Observable will automatically infer the type from the default value. You may also specify the type using the first template parameter:
+ *
+ * ```ts
+ * const myVariable = new Observable<boolean|string>(false);
+ * ```
+ *
+ * The value of the Observable may be accessed and changed using the `value` parameter:
+ * ```ts
+ * console.log(myVariable.value);
+ *
+ * myVariable.value = 4;
+ * ```
+ *
+ * Setting `value` to `undefined` restores the value to the default specified in the constructor.
+ *
+ * A function can be registered to receive changes to the value (or any of its recursive descendent keys or elements):
+ * ```ts
+ * const myVariable = new Observable(false, newValue => console.log(newValue));
+ * ```
+ *
+ * @typeParam Type - The type of the contained value
+ * @typeParam TypeInternal - An internal type used to improve automatic type detection
+ */
 export class Observable {
     constructor(_default, withHandler, _deep = true) {
         this._default = _default;
@@ -19,6 +51,11 @@ export class Observable {
         if (withHandler)
             this.withValue(withHandler);
     }
+    /**
+     * Access the current value for this Observable. Changing this value (or, unless deep inspection is disabled, its recursive elements and keys) will trigger any registered handlers to be called with the new value.
+     *
+     * Setting `value` to `undefined` will restore the value to the default specified in the constructor.
+     */
     get value() {
         return this._value.proxy;
     }

package/lib/selectors.js

@@ -139,9 +139,12 @@ export const typeDefinitionForComponent = (nodes, props, scriptNames, url) => {
 
 ${importStrings.join('\n')}
 
+/**
+* @zcomponent
+*/
 declare class Comp extends ZComponent {
 
-	constructor(constructorProps: {}, ctx: ContextManager);
+	constructor(contextManager: ContextManager, constructorProps: {});
 
 	nodes: {
 ${Object.entries(scriptNames).map(entry => {
@@ -158,9 +161,6 @@ ${Object.entries(scriptNames).map(entry => {
 ${Object.values(props).map(typeOutputForProp).join('\n')}
 }
 
-/**
-* @zcomponent
-*/
 export default Comp;
 `;
 };

package/lib/types.d.ts

@@ -48,7 +48,7 @@ export interface FunctionType extends BaseType {
 export interface EventType extends BaseType {
     name: 'event';
 }
-export declare type Type = StringPrimitiveType | NumberPrimitiveType | BooleanPrimitiveType | ArrayType | TupleType | UnknownType | EnumType | UnionType | LiteralType | FunctionType | EventType;
+export type Type = StringPrimitiveType | NumberPrimitiveType | BooleanPrimitiveType | ArrayType | TupleType | UnknownType | EnumType | UnionType | LiteralType | FunctionType | EventType;
 export declare enum TypeHint {
     "proportion" = "proportion",
     'color-norm-rgb' = "color-norm-rgb",
@@ -86,10 +86,10 @@ export interface ComponentInfo {
     allowedChildren: string[];
     allowedParents?: string[];
 }
-export declare type SourceFileTypeInfo = {
+export type SourceFileTypeInfo = {
     [id: string]: ComponentInfo;
 };
-export declare type TypeInfoByFileName = {
+export type TypeInfoByFileName = {
     [id: string]: SourceFileTypeInfo;
 };
 export declare function areTypesCompatible(a: Type, b: Type): boolean;

package/lib/zcomponent.d.ts

@@ -1,5 +1,5 @@
-import { Component, ComponentConstructor, ConstructorProps } from './component';
-import { ContextManager } from './context';
+import { Component, ComponentChildren, ConstructorProps } from './component';
+import { ContextManager, Context } from './context';
 import { ZComponentData } from './interfaces';
 export interface ZComponentOptions {
     data: ZComponentData;
@@ -18,16 +18,20 @@ export interface ZComponentOptions {
     };
     onConstructingNode?: (id: string | undefined) => void;
 }
-export interface ZComponentContext {
+export interface ZComponentContextConstructorProps {
     zcomponent: ZComponent;
+    children: ComponentChildren;
 }
-export declare const ZComponentContext: import("./context").ContextTypeWithDefault<ZComponentContext, [zcomponent: ZComponent<any>]>;
-export declare function useZComponentInstance<T extends ZComponent>(ctx: ContextManager, comp?: ComponentConstructor<T>): T;
-export declare function useConstructed(ctx: ContextManager): Promise<void>;
-export declare class ZComponent<RootType = any> extends Component<ConstructorProps, RootType> {
+export declare class ZComponentContext extends Context {
+    zcomponent: ZComponent;
+    children: ComponentChildren;
+    constructor(contextManager: ContextManager, props: ZComponentContextConstructorProps);
+}
+export declare class ZComponent<RootType = any> extends Component<RootType> {
+    constructorProps: ConstructorProps;
     private _opts;
     id: string;
-    idByRoot: Map<any, string>;
+    idByElement: Map<any, string>;
     nodes: {
         [id: string]: Component | Component[];
     };
@@ -36,11 +40,8 @@ export declare class ZComponent<RootType = any> extends Component<ConstructorPro
     constructed: Promise<void>;
     isConstructed: boolean;
     private _nodesById;
-    private _rootComponent;
     private _behaviorsToInitialize;
-    constructor(constructorProps: {
-        [id: string]: any;
-    }, contextManager: ContextManager, _opts: ZComponentOptions);
+    constructor(contextManager: ContextManager, constructorProps: ConstructorProps, _opts: ZComponentOptions);
     private _constructorForNode;
     private _constructorForBehavior;
     private _inflateBehaviors;

package/lib/zcomponent.js

@@ -1,36 +1,36 @@
 import { shouldBehaviorRunAtDesignTime } from './behavior';
 import { Component } from './component';
-import { defineContextType } from './context';
+import { Context } from './context';
 import { isDesignTime } from './contexts/environmentcontext';
+import { TagContext } from './contexts/tagcontext';
 import { Observable } from './observable';
-export const ZComponentContext = defineContextType((ctx, zcomponent) => {
-    return { zcomponent };
-});
-export function useZComponentInstance(ctx, comp) {
-    return ctx.getOrThrow(ZComponentContext)?.zcomponent;
-}
-export function useConstructed(ctx) {
-    return ctx.getOrThrow(ZComponentContext)?.zcomponent.constructed;
+import { setCurrentZComponentConstruction } from './zcomponentconstruction';
+export class ZComponentContext extends Context {
+    constructor(contextManager, props) {
+        super(contextManager, props);
+        this.zcomponent = props.zcomponent;
+        this.children = props.children;
+    }
 }
 export class ZComponent extends Component {
-    constructor(constructorProps, contextManager, _opts) {
-        contextManager = contextManager.fork(ZComponentContext, undefined)[0];
-        super(constructorProps, contextManager, { dontConstructChildren: true });
+    constructor(contextManager, constructorProps, _opts) {
+        super(contextManager, { ...constructorProps, children: [] });
+        this.constructorProps = constructorProps;
         this._opts = _opts;
-        this.idByRoot = new Map();
+        this.idByElement = new Map();
         this.nodes = {};
         this.entityByID = new Map();
         this.constructed = new Promise(resolve => this._constructedResolve = resolve);
         this.isConstructed = false;
         this._nodesById = new Map();
         this._behaviorsToInitialize = [];
-        contextManager.getOrThrow(ZComponentContext).zcomponent = this;
+        const contextManagerForChildren = contextManager.forkMultiple([ZComponentContext, { zcomponent: this }], [TagContext, {}])[0];
         this.id = this._opts.data.id;
         const rootConstructor = this._constructorForNode(this._opts.data.root);
         if (rootConstructor) {
-            this._constructChildren([
+            this.constructChildren([
                 [rootConstructor, {}]
-            ]);
+            ], contextManagerForChildren);
         }
         this._inflateBehaviors();
         this._initializeComponentProps();
@@ -50,7 +50,7 @@ export class ZComponent extends Component {
         }
         const that = this;
         return class extends construct {
-            constructor(constructorProps, contextManager) {
+            constructor(contextManager, constructorProps) {
                 that._opts.onConstructingNode?.(nodeId);
                 const children = constructorProps.children ?? [];
                 for (const child of node?.children ?? []) {
@@ -62,17 +62,15 @@ export class ZComponent extends Component {
                     ...constructorProps,
                     ...(that._opts.data.entityConstructorProps?.[nodeId] ?? {}),
                     ...(that._opts.constructorPropReplacement?.[nodeId] ?? {}),
-                    children,
+                    children
                 };
-                super(constructorProps, contextManager);
+                setCurrentZComponentConstruction(that);
+                super(contextManager, constructorProps);
                 that.entityByID.set(nodeId, this);
                 that._nodesById.set(nodeId, this);
-                if (nodeId === that._opts.data.root) {
-                    that._rootComponent = this;
-                    that.root = this.root;
+                for (const element of this.elementsResolved) {
+                    that.idByElement.set(element, nodeId);
                 }
-                if (this.root)
-                    that.idByRoot.set(this.root, nodeId);
                 if (node?.scriptName) {
                     const entriesForScriptName = that._opts.data.entitiesByScriptName?.[node.scriptName] ?? {};
                     let moreThanOne = false;
@@ -91,7 +89,7 @@ export class ZComponent extends Component {
                         that.nodes[node.scriptName] = this;
                     }
                 }
-                that._behaviorsToInitialize.push([nodeId, this, contextManager]);
+                that._behaviorsToInitialize.push([nodeId, this, this.contextManager]);
                 const props = {
                     ...(that._opts.data.entityProps?.[nodeId] ?? {}),
                     ...(that._opts.propReplacement?.[nodeId] ?? {}),
@@ -112,8 +110,9 @@ export class ZComponent extends Component {
             dispose() {
                 that.entityByID.delete(nodeId);
                 that._nodesById.delete(nodeId);
-                if (this.root)
-                    that.idByRoot.delete(this.root);
+                for (const element of this.elementsResolved) {
+                    that.idByElement.delete(element);
+                }
                 return super.dispose();
             }
         };
@@ -134,13 +133,14 @@ export class ZComponent extends Component {
             return;
         const that = this;
         return class extends construct {
-            constructor(constructorProps, contextManager) {
+            constructor(contextManager, instance, constructorProps) {
                 constructorProps = {
                     ...constructorProps,
                     ...(that._opts.data.entityConstructorProps?.[behaviorId] ?? {}),
                     ...(that._opts.constructorPropReplacement?.[behaviorId] ?? {}),
                 };
-                super(constructorProps, contextManager);
+                setCurrentZComponentConstruction(that);
+                super(contextManager, instance, constructorProps);
                 that.entityByID.set(behaviorId, this);
                 const props = {
                     ...(that._opts.data.entityProps?.[behaviorId] ?? {}),
@@ -157,6 +157,7 @@ export class ZComponent extends Component {
                 }
             }
             dispose() {
+                that.entityByID.delete(behaviorId);
                 return super.dispose();
             }
         };
@@ -170,17 +171,9 @@ export class ZComponent extends Component {
     _wrapBehaviors(nodeID, impl, ctx) {
         const behaviors = this._opts.data.behaviorsByNode?.[nodeID] ?? [];
         for (const behaviorID of behaviors) {
-            const behavior = this._opts.data.behaviors?.[behaviorID];
-            if (!behavior)
-                continue;
-            const constructorProps = {
-                ...(this._opts.data.entityConstructorProps?.[behaviorID] ?? {}),
-                ...(this._opts.constructorPropReplacement?.[behaviorID] ?? {}),
-                instance: impl
-            };
             const constructor = this._constructorForBehavior(behaviorID);
             if (constructor)
-                new constructor(constructorProps, ctx);
+                new constructor(ctx, impl);
         }
     }
     notifyPropsChanged(entries) {

package/lib/zcomponentconstruction.d.ts

@@ -0,0 +1,3 @@
+import { ZComponent } from "./zcomponent";
+export declare function getCurrentZComponentConstruction(): ZComponent<any> | undefined;
+export declare function setCurrentZComponentConstruction(z: ZComponent | undefined): void;

package/lib/zcomponentconstruction.js

@@ -0,0 +1,7 @@
+let currentZComponentConstruction;
+export function getCurrentZComponentConstruction() {
+    return currentZComponentConstruction;
+}
+export function setCurrentZComponentConstruction(z) {
+    currentZComponentConstruction = z;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zcomponent/core",
-  "version": "0.0.8",
+  "version": "0.0.9",
   "description": "",
   "main": "index.js",
   "types": "index.d.ts",
@@ -29,7 +29,7 @@
     "@playwright/test": "^1.25.0",
     "@types/ua-parser-js": "^0.7.36",
     "parcel": "^2.8.2",
-    "typescript": "^4.6.3",
+    "typescript": "^4.9.4",
     "ua-parser-js": "^1.0.2"
   },
   "zexports": [