arrmatura 6.2.1 → 6.3.1

package/src/{ctx/Ctx.ts → core/Entitron.ts}

@@ -1,58 +1,50 @@
 import { areEqual, capitalize, identity } from "ultimus";
 import { stringify } from "../utils/stringify";
 import type { Delta, Fn, Hash, Proc, Uid } from "ultimus/types";
-import type {
-  EProcedure,
-  ICtx,
-  ICtxNode,
-  IComponent,
-  IPlatform,
-} from "arrmatura-api/types";
+import type { IEntitron, IManifestNode, IComponent, IPlatform } from "arrmatura/types";
+
+type EProcedure = (c: IEntitron) => void;
 
 /**
- * The Component Context class.
- * It creates, refers and manages a component instance.
- *
- * A component instance gets reference to its context in 2nd constructor parameter.
+ * The Entitron is the essential the framework concept.
+ * 
+ * It creates a own component instance,
+ * manages its state and behavior, 
+ * and ties it up with others.
  */
-export class Ctx<T extends ICtxNode = ICtxNode> implements ICtx {
+export class Entitron<T extends IManifestNode = IManifestNode> implements IEntitron {
   readonly component: IComponent;
-  $children?: Map<Uid, ICtx>;
-  readonly root: ICtx;
-  readonly scope: ICtx;
+  $children?: Map<Uid, IEntitron>;
+  readonly root: IEntitron;
+  readonly scope: IEntitron;
   isDone = false;
 
   #isInited = false;
   #state: Hash = {};
   #initialState: Hash = {};
-  #listeners?: Set<(c: Ctx) => void>;
+  #listeners?: Set<(c: Entitron) => void>;
   #defered?: EProcedure[] = [];
   #weak?: Map<string, number>;
-  #refs?: Hash<ICtx>;
+  #refs?: Hash<IEntitron>;
   #propFnMap?: Map<string, Proc>;
 
-  constructor(
-    readonly platform: IPlatform,
-    protected readonly node: T,
-    private _parent?: ICtx,
-    scope?: ICtx
-  ) {
+  constructor(readonly platform: IPlatform, protected readonly manifest: T, private _parent?: IEntitron, scope?: IEntitron) {
     this.scope = scope ?? this;
     this.root = scope?.root ?? this;
-    this.#initialState = this.node.resolveInitialProps(this);
+    this.#initialState = this.manifest.resolveInitialProps(this);
     this.component = this.createComponent(this.#initialState);
 
     if (this.refId) {
-      this.scope.addEntityReference(this.refId, this);
+      this.scope.addReference(this.refId, this);
     }
   }
 
-  get parent(): ICtx | undefined {
+  get parent(): IEntitron | undefined {
     return this._parent;
   }
 
   get uid(): string {
-    return this.node.uid;
+    return this.manifest.uid;
   }
 
   get displayName(): string {
@@ -60,6 +52,7 @@ export class Ctx<T extends ICtxNode = ICtxNode> implements ICtx {
   }
 
   createComponent(initials: Hash): IComponent {
+    // by default, a component is just a plain object.
     return { ...initials };
   }
 
@@ -80,11 +73,7 @@ export class Ctx<T extends ICtxNode = ICtxNode> implements ICtx {
     Object.entries(Δ).forEach(([k, v]) => {
       if (v instanceof Promise) {
         this.upAsync(v, k);
-      } else if (
-        k &&
-        typeof v !== "undefined" &&
-        !areEqual(v, this.#state[k])
-      ) {
+      } else if (k && typeof v !== "undefined" && !areEqual(v, this.#state[k])) {
         this.#state[k] = v;
         changes.set(k, v);
       }
@@ -148,14 +137,9 @@ export class Ctx<T extends ICtxNode = ICtxNode> implements ICtx {
         fn = () => val;
       } else {
         const gettr = impl[`get${capitalize(pk)}`];
-        const fn0 =
-          typeof gettr === "function"
-            ? () => gettr.call(impl) ?? null
-            : () => impl[pk] ?? null;
-
-        fn = !path.length
-          ? fn0
-          : () => path.reduce((r, p) => r?.[p] ?? null, fn0());
+        const fn0 = typeof gettr === "function" ? () => gettr.call(impl) ?? null : () => impl[pk] ?? null;
+
+        fn = !path.length ? fn0 : () => path.reduce((r, p) => r?.[p] ?? null, fn0());
       }
     }
 
@@ -175,7 +159,7 @@ export class Ctx<T extends ICtxNode = ICtxNode> implements ICtx {
   }
 
   // add listener to componet state changes
-  subscribe(handler: (src: Ctx) => any): Proc {
+  subscribe(handler: (src: Entitron) => any): Proc {
     const listeners = this.#listeners ?? (this.#listeners = new Set());
     listeners.add(handler);
     return () => {
@@ -187,38 +171,46 @@ export class Ctx<T extends ICtxNode = ICtxNode> implements ICtx {
 
   // emits action event to this component
   emit(key: string, data: Delta): void {
-    if (!key || !key.includes(".")) {
-      this.up(key ? { [key]: data } : data);
-      return;
-    }
-
-    const [refId, target] = key.split(".");
     try {
+      // when key.endsWith("...") it will produce empty target, so don't need to hande it peculiarly 
+      let [refId, target] = key.split(".");
+      if (!target) {
+        target = refId;
+        refId = 'this'
+      }
+
       const ref = this.getByRef(refId);
       if (!ref) {
         throw new Error(`No such reference: ${refId}`);
       }
-      if (!target) {
+
+      if (!target) { // spread '...'
         ref.up(data);
         return;
       }
 
-      const propId = `on${capitalize(target)}`;
+      if (target[0] === "@") {
+        ref.up({ [target.slice(1)]: data });
+        return;
+      }
+
       const impl = ref.component;
-      const method = impl[propId];
+      const method = impl[target] ?? impl[`on${capitalize(target)}`];
 
+      // deprecated. Use @-prefix instead.
       if (!method) {
-        ref.up({ [target]: data });
+        const propKey = target[0] === "@" ? target.slice(1) : target;
+        ref.up({ [propKey]: data });
         return;
       }
 
-      if (!method || !(typeof method === "function")) {
-        throw new Error(`No such method ${refId}.${propId}`);
+      if (!(typeof method === "function")) {
+        throw new Error(`Not a method: ${refId}.${target}`);
       }
 
       const result = method.call(impl, data, impl, ref);
 
-      this.log(`-> ${refId}.${propId}`, result, data, impl);
+      this.log(`-> ${refId}.${target}`, result, data, impl);
 
       ref.up(result);
     } catch (ex) {
@@ -246,13 +238,13 @@ export class Ctx<T extends ICtxNode = ICtxNode> implements ICtx {
   }
 
   // map of children contexts
-  get children(): Map<Uid, ICtx> | undefined {
+  get children(): Map<Uid, IEntitron> | undefined {
     return this.$children;
   }
 
   // map of chidren of its node
-  get content() {
-    return this.node.getContent(this.platform);
+  get contentManifests() {
+    return this.manifest.getSubNodes(this.platform);
   }
 
   // actual scope for re-content
@@ -270,13 +262,13 @@ export class Ctx<T extends ICtxNode = ICtxNode> implements ICtx {
 
       this.up(this.component.init?.(this));
     } else {
-      void this.up(this.node.resolveProps(this), true);
+      void this.up(this.manifest.resolveProps(this), true);
     }
   }
 
   // perform children instantiation and updates
   private recontent() {
-    const nodes = this.content;
+    const nodes = this.contentManifests;
 
     this.platform.redraw(this, this.root);
 
@@ -286,12 +278,10 @@ export class Ctx<T extends ICtxNode = ICtxNode> implements ICtx {
       }
     });
 
-    const children = new Map<Uid, ICtx>();
+    const children = new Map<Uid, IEntitron>();
 
-    nodes?.forEach((node: ICtxNode, uid: Uid) => {
-      const e =
-        this.children?.get(uid) ??
-        node.createContext(this.platform, this, this.recontentScope);
+    nodes?.forEach((node: IManifestNode, uid: Uid) => {
+      const e = this.children?.get(uid) ?? node.createEntitron(this.platform, this, this.recontentScope);
       children.set(e.uid, e);
     });
 
@@ -305,11 +295,11 @@ export class Ctx<T extends ICtxNode = ICtxNode> implements ICtx {
   // --- Referencing.
 
   get refId() {
-    return this.node.refId;
+    return this.manifest.refId;
   }
 
   // gets any context instance in current or upper scope by key
-  getByRef(refId: string): ICtx | undefined {
+  getByRef(refId: string): IEntitron | undefined {
     if (!refId) return undefined;
 
     if (refId === "this") {
@@ -320,41 +310,39 @@ export class Ctx<T extends ICtxNode = ICtxNode> implements ICtx {
       return local;
     }
     const ref = this === this.scope ? null : this.scope.getByRef(refId);
-    return ref as Ctx;
+    return ref as Entitron;
   }
 
-  addEntityReference(refId: string, c: ICtx) {
+  addReference(refId: string, c: IEntitron) {
     (this.#refs ?? (this.#refs = {}))[refId] = c;
   }
 
   // --- Routines -------------------------
 
   private initConnectors() {
-    if (this.node.connectors) {
-      for (const [key, pipes] of this.node.connectors.entries()) {
+    if (this.manifest.connectors) {
+      for (const [key, pipes] of this.manifest.connectors.entries()) {
         const [srcIds, targetPropName] = key.split("|");
-        const [refId, ...propIds] = srcIds.split(".");
+        const [refId, sourcePropName] = srcIds.split(".");
 
-        const ref = this.scope.getByRef(refId) as Ctx;
+        const ref = this.scope.getByRef(refId) as Entitron;
         if (!ref) {
           this.logError(`Connect: No such ref: ${refId}`);
           continue;
         }
 
-        if (!propIds.length) {
+        if (!sourcePropName) {
           this.logError(`Connect: No prop specified: ${key}`);
           continue;
         }
 
-        const propId = propIds.join(".");
-        const applicator = targetPropName
-          ? (rr: any) => ({ [targetPropName]: rr })
-          : identity;
+        const propName = sourcePropName[0] === '@' ? sourcePropName.slice(1) : sourcePropName;
+        const applicator = targetPropName ? (rr: any) => ({ [targetPropName]: rr }) : identity;
 
         this.defer(
-          ref.subscribe((source: Ctx) => {
+          ref.subscribe((source: Entitron) => {
             try {
-              const r = applicator(pipes(this, source.get(propId)));
+              const r = applicator(pipes(this, source.get(propName)));
               this.up(r as Delta);
             } catch (ex) {
               source.logError("Notify ", ex);
@@ -363,10 +351,7 @@ export class Ctx<T extends ICtxNode = ICtxNode> implements ICtx {
         );
 
         // hot subscription
-        Object.assign(
-          this.#initialState,
-          applicator(pipes(ref, ref.get(propId)))
-        );
+        Object.assign(this.#initialState, applicator(pipes(ref, ref.get(propName))));
       }
     }
   }
@@ -405,10 +390,7 @@ export class Ctx<T extends ICtxNode = ICtxNode> implements ICtx {
       level: "error",
       source: `${this.displayName}:${this.uid}`,
       error,
-      message: `${String(error.message || error)}\n${this.toString().slice(
-        0,
-        120
-      )}`,
+      message: `${String(error.message || error)}\n${this.toString().slice(0, 120)}`,
       params: args,
     });
   }

package/src/core/ManifestNode.ts

@@ -0,0 +1,139 @@
+import { nextId } from "ultimus";
+import { compilePipeExpression } from "../utils/compileExpression";
+import type { Delta, ExpressionText, Hash, Uid } from "ultimus/types";
+import type { IPlatform, IEntitron, IManifestNode } from "arrmatura/types";
+import { resolveExpression } from "./resolveExpression";
+
+type PropertyResolver = (c: IEntitron, acc: Delta) => Delta;
+
+type PropertyGetter = (c: IEntitron) => unknown;
+
+/**
+ * ManifestNode is a abstract factory for Entitron.
+ * 
+ * Each specific kind of Entitron has its own descending implementation of ManifestNode.
+ */
+export abstract class ManifestNode implements IManifestNode {
+  protected $content?: Map<Uid, IManifestNode> | undefined;
+  uid: Uid = nextId("N");
+  refId?: string;
+  private readonly propertyResolvers: PropertyResolver[] = [];
+  private initialState: Hash<(c: IEntitron) => any> = {};
+  connectors?: Map<string, (c: IEntitron, x: unknown) => unknown>;
+  tag: any;
+
+  abstract get EntitronConstructor(): new (platform: IPlatform, node: typeof this, parent?: IEntitron, scope?: IEntitron) => IEntitron;
+
+  /**
+   * Create a context object.
+   *
+   * @param {IPlatform} platform - The platform object.
+   * @param {IEntitron} parent - The parent context object (optional).
+   * @param {IEntitron} scope - The scope context object (optional).
+   * @return {IEntitron} The created context object.
+   */
+  createEntitron(platform: IPlatform, parent?: IEntitron, scope?: IEntitron): IEntitron {
+    return new this.EntitronConstructor(platform, this, parent, scope);
+  }
+
+  getSubNodes(_platform: IPlatform): Map<Uid, IManifestNode> | undefined {
+    return this.$content;
+  }
+
+  addPropertyResolver(getter: PropertyGetter, propKey: string) {
+    this.propertyResolvers.push((c: IEntitron, delta: Delta) => {
+      delta[propKey] = getter(c);
+      return delta;
+    });
+    return this;
+  }
+
+  private addDataPropertyResolver(getter: PropertyGetter, propKey: string) {
+    this.propertyResolvers.push((c: IEntitron, delta: Delta) => {
+      const val = getter(c);
+      delta.data = Object.assign((delta.data as object) || {}, {
+        [propKey]: val,
+      });
+      return delta;
+    });
+    return this;
+  }
+
+  private addPropertiesResolver(getter: PropertyGetter) {
+    this.propertyResolvers.push((c: IEntitron, delta: Delta) => {
+      const value = getter(c);
+      if (value && typeof value === "object") {
+        Object.entries(value).forEach(([key, val]) => {
+          delta[key] = val;
+        });
+      }
+      return delta;
+    });
+    return this;
+  }
+
+  addConnector(expr: ExpressionText, propName: string) {
+    const { key, pipec } = compilePipeExpression(expr);
+    (this.connectors ?? (this.connectors = new Map())).set(`${key}|${propName}`, pipec);
+  }
+
+  private addEmitter(expr: ExpressionText, k: string) {
+    const { key, pipec } = compilePipeExpression(expr);
+    this.initialState[k] = (c) => (data: unknown) => c.scope?.emit(key, pipec(c, data) as Delta);
+  }
+
+  resolveInitialProps(c: IEntitron) {
+    return this.propertyResolvers.reduce(
+      (delta, resolver) => resolver(c, delta),
+      Object.entries(this.initialState).reduce((acc, [key, fn]) => {
+        acc[key] = fn(c);
+        return acc;
+      }, {} as Hash)
+    );
+  }
+
+  resolveProps(c: IEntitron) {
+    return this.propertyResolvers.reduce((delta, resolver) => resolver(c, delta), {});
+  }
+
+  compileAttribute(k: string, v: unknown) {
+    if (k.startsWith("data-")) {
+      this.addDataPropertyResolver(resolveExpression(v), k.slice(5));
+    } else if (k === "ref") {
+      this.refId = String(v);
+    } else if (k === "props" || k.startsWith('{...')) {
+      const sv = k.startsWith('{...') ? k.slice(4, -1) : String(v);
+      if (sv[0] === "<" && sv[1] === "-") {
+        this.addConnector(sv.slice(2), "");
+      } else {
+        this.addPropertiesResolver(resolveExpression(sv));
+      }
+    } else {
+      if (typeof v !== "string") {
+        this.initialState[k] = () => v;
+      } else {
+        if (v[0] === "<" && v[1] === "-") {
+          this.addConnector(v.slice(2), k);
+        } else if (v[0] === "-" && v[1] === ">") {
+          this.addEmitter(v.slice(2), k);
+        } else {
+          if (!v.includes("{") && v[0] !== "@") {
+            this.initialState[k] = () => v;
+          } else {
+            if (v[0] === "@" && v[1] === "@" && v.match(/^@@[a-z0-9\-_.]+$/i) != null) {
+              this.initialState[k] = (c) => c.platform.getResource(v.slice(2));
+            } else {
+              this.addPropertyResolver(resolveExpression(v), k);
+            }
+          }
+        }
+      }
+    }
+  }
+
+  compileAttributes(attrs?: Hash) {
+    if (attrs) {
+      Object.entries(attrs).forEach((keyValue) => this.compileAttribute(...keyValue));
+    }
+  }
+}

package/src/core/resolveExpression.ts

@@ -0,0 +1,20 @@
+import { createStringInterpolator } from "ultimus/src/parsing/createStringInterpolator";
+import { compileConstant, compileJsExpression, compilePlaceholder } from "../utils/compileExpression";
+
+const CACHE = new Map();
+
+function compileExpression(v: unknown) {
+  if (typeof v !== "string") return () => v;
+
+  if (v[0] === "@") return compilePlaceholder(v);
+
+  if (v.startsWith("js:")) return compileJsExpression(v.slice(3));
+
+  if (v.includes("{")) return createStringInterpolator(v.replace(/\s+/g, " "), compilePlaceholder);
+
+  return compileConstant(v);
+}
+
+export const resolveExpression = (x: unknown) => {
+  return CACHE.has(x) ? CACHE.get(x) : CACHE.set(x, compileExpression(x)).get(x);
+}

package/src/{core → registry}/composition.ts

@@ -1,31 +1,31 @@
-import { CtxNode } from "../ctx/CtxNode";
-import { Ctx } from "../ctx/Ctx";
+import { ManifestNode } from "../core/ManifestNode";
+import { Entitron } from "../core/Entitron";
 import type { Hash, XmlNode } from "ultimus/types";
-import type { EContent, ICtxNode, IPlatform } from "arrmatura-api/types";
+import type { EContent, IManifestNode, IPlatform } from "arrmatura/types";
 
-export class Composite extends Ctx<CCompositeNode> {
+export class Composite extends Entitron<CCompositeNode> {
   get displayName(): string {
-    return `💠${this.node.tag}`;
+    return `💠${this.manifest.tag}`;
   }
 
-  get recontentScope(): Ctx {
+  get recontentScope(): Entitron {
     return this;
   }
 
   slotContent(slotId?: string): EContent | undefined {
-    return this.node.getSlotContent(this.platform, slotId);
+    return this.manifest.getSlotContent(this.platform, slotId);
   }
 
   createComponent(initials: Hash) {
-    return this.platform.createComponent(this.node.tag, initials, this);
+    return this.platform.createComponent(this.manifest.tag, initials, this);
   }
 }
 
-export class CCompositeNode extends CtxNode {
+export class CCompositeNode extends ManifestNode {
   slotContent: Hash<EContent> | null = null;
   tag: string;
   nodes?: XmlNode["nodes"];
-  #content: Map<string, ICtxNode>;
+  #content?: Map<string, IManifestNode>;
 
   constructor({ tag, attrs, nodes }: XmlNode) {
     super();
@@ -43,29 +43,24 @@ export class CCompositeNode extends CtxNode {
           gId = e.tag.split(":")[1];
           isContainer = true;
         }
-        groups[gId] = (groups[gId] || []).concat(
-          isContainer ? e.nodes ?? [] : e
-        );
+        groups[gId] = (groups[gId] || []).concat(isContainer ? e.nodes ?? [] : e);
         return groups;
       }, {});
 
-      this.slotContent = Object.entries(slots ?? {}).reduce<Hash<EContent>>(
-        (groups, [gId, nodes]) => {
-          groups[gId] = platform.getCompiledNodes(nodes);
-          return groups;
-        },
-        {}
-      );
+      this.slotContent = Object.entries(slots ?? {}).reduce<Hash<EContent>>((groups, [gId, nodes]) => {
+        groups[gId] = platform.getCompiledNodes(nodes);
+        return groups;
+      }, {});
     }
 
     return this.slotContent[slotId ?? "default"] ?? undefined;
   }
 
-  getContent(platform: IPlatform) {
+  getSubNodes(platform: IPlatform) {
     return this.#content ?? (this.#content = platform.getCompiledNodes(this.tag));
   }
 
-  get EntityConstructor() {
+  get EntitronConstructor() {
     return Composite;
   }
 }

package/src/{core → registry}/conditionals.ts

@@ -1,13 +1,13 @@
-import { CtxNode } from "../ctx/CtxNode";
+import { ManifestNode } from "../core/ManifestNode";
 import { Composite } from "./composition";
-import { Ctx } from "../ctx/Ctx";
-import type { EContent, ICtx, IPlatform } from "arrmatura-api/types";
+import { Entitron } from "../core/Entitron";
+import type { EContent, IEntitron, IPlatform } from "arrmatura/types";
 import type { XmlNode } from "ultimus/types";
 import { compilePlaceholder } from "../utils/compileExpression";
 
-class Conditional extends Ctx<CIfNode> {
-  get content() {
-    const branches = this.node.getBranches(this.platform);
+class Conditional extends Entitron<CIfNode> {
+  get contentManifests() {
+    const branches = this.manifest.getBranches(this.platform);
     return this.component.condition ? branches.then : branches.else;
   }
 
@@ -16,7 +16,7 @@ class Conditional extends Ctx<CIfNode> {
   }
 }
 
-export class CIfNode extends CtxNode {
+export class CIfNode extends ManifestNode {
   #xml: XmlNode;
   #branches?: { then?: EContent; else?: EContent };
   constructor(xml: XmlNode, expr: string) {
@@ -25,7 +25,7 @@ export class CIfNode extends CtxNode {
     this.compileCondition(expr);
   }
 
-  get EntityConstructor() {
+  get EntitronConstructor() {
     return Conditional;
   }
 
@@ -43,16 +43,14 @@ export class CIfNode extends CtxNode {
       const ifElse = nodes.find((e) => e.tag === "Else");
       const ifThen = nodes.find((e) => e.tag === "Then");
       if (ifElse) {
-        this.#branches.else = ifElse.nodes
-          ? platform.getCompiledNodes(ifElse.nodes)
-          : undefined;
+        this.#branches.else = ifElse.nodes ? platform.getCompiledNodes(ifElse.nodes) : undefined;
         $then = ifThen
           ? ifThen.nodes
           : [
-              Object.assign(this.#xml, {
-                nodes: nodes.filter((e) => e !== ifElse),
-              }),
-            ];
+            Object.assign(this.#xml, {
+              nodes: nodes.filter((e) => e !== ifElse),
+            }),
+          ];
       } else if (ifThen) {
         $then = ifThen.nodes;
       }
@@ -68,10 +66,7 @@ export class CIfNode extends CtxNode {
     } else if (expr.slice(0, 5) === "slot(") {
       const slotId = expr.slice(5, -1);
       // DO NOT place inside iterations.
-      this.addPropertyResolver(
-        (c: ICtx) => !!(c.scope as Composite).slotContent?.(slotId)?.size,
-        "condition"
-      );
+      this.addPropertyResolver((c: IEntitron) => !!(c.scope as Composite).slotContent?.(slotId)?.size, "condition");
     } else {
       const resolver = compilePlaceholder(expr);
       this.addPropertyResolver((c) => !!resolver(c), "condition");

package/src/registry/elementary.ts

@@ -0,0 +1,36 @@
+import { ManifestNode } from "../core/ManifestNode";
+import { Entitron } from "../core/Entitron";
+import type { Hash, XmlNode } from "ultimus/types";
+import { IPlatform } from "arrmatura/types";
+
+class NativeElementEntitron extends Entitron<CElementNode> {
+  get displayName(): string {
+    return this.manifest.tag;
+  }
+
+  createComponent(initials: Hash) {
+    return this.platform.createComponent({ tag: this.manifest.tag, native: true }, initials, this);
+  }
+}
+
+export class CElementNode extends ManifestNode {
+  #nodes: XmlNode[] | undefined;
+
+  constructor({ tag, attrs, nodes, text }: XmlNode) {
+    super();
+    this.tag = tag;
+    this.compileAttributes(attrs);
+    if (text) {
+      this.compileAttribute("#text", text);
+    }
+    this.#nodes = nodes;
+  }
+
+  getSubNodes(platform: IPlatform) {
+    return this.#nodes ? platform.getCompiledNodes(this.#nodes) : undefined;
+  }
+
+  get EntitronConstructor() {
+    return NativeElementEntitron;
+  }
+}