arrmatura 5.2.0 → 6.3.1

package/src/core/Entitron.ts

@@ -0,0 +1,406 @@
+import { areEqual, capitalize, identity } from "ultimus";
+import { stringify } from "../utils/stringify";
+import type { Delta, Fn, Hash, Proc, Uid } from "ultimus/types";
+import type { IEntitron, IManifestNode, IComponent, IPlatform } from "arrmatura/types";
+
+type EProcedure = (c: IEntitron) => void;
+
+/**
+ * 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 Entitron<T extends IManifestNode = IManifestNode> implements IEntitron {
+  readonly component: IComponent;
+  $children?: Map<Uid, IEntitron>;
+  readonly root: IEntitron;
+  readonly scope: IEntitron;
+  isDone = false;
+
+  #isInited = false;
+  #state: Hash = {};
+  #initialState: Hash = {};
+  #listeners?: Set<(c: Entitron) => void>;
+  #defered?: EProcedure[] = [];
+  #weak?: Map<string, number>;
+  #refs?: Hash<IEntitron>;
+  #propFnMap?: Map<string, Proc>;
+
+  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.manifest.resolveInitialProps(this);
+    this.component = this.createComponent(this.#initialState);
+
+    if (this.refId) {
+      this.scope.addReference(this.refId, this);
+    }
+  }
+
+  get parent(): IEntitron | undefined {
+    return this._parent;
+  }
+
+  get uid(): string {
+    return this.manifest.uid;
+  }
+
+  get displayName(): string {
+    return "🔹";
+  }
+
+  createComponent(initials: Hash): IComponent {
+    // by default, a component is just a plain object.
+    return { ...initials };
+  }
+
+  // --- State
+
+  // updates component state
+  up(Δ?: Delta | Promise<any> | null | void | unknown, force = false): void {
+    if (!Δ || this.isDone) {
+      return;
+    }
+
+    if (Δ instanceof Promise) {
+      this.upAsync(Δ, "*");
+      return;
+    }
+
+    const changes = new Map<string, unknown>();
+    Object.entries(Δ).forEach(([k, v]) => {
+      if (v instanceof Promise) {
+        this.upAsync(v, k);
+      } else if (k && typeof v !== "undefined" && !areEqual(v, this.#state[k])) {
+        this.#state[k] = v;
+        changes.set(k, v);
+      }
+    });
+
+    if (changes.size || force) {
+      this.stateChanged(changes);
+    }
+  }
+
+  private upAsync(promise: Promise<any>, key: string): void {
+    const racer = this.raceCondition(`set:${key}`);
+    if (key[0] !== "*") {
+      const akey = key.replace("Promise", "");
+      void promise.then((val) => racer(() => this.up({ [akey]: val })));
+    } else {
+      void promise.then((r: Delta) => racer(() => this.up(r)));
+    }
+  }
+
+  private stateChanged(changes: Map<string, unknown>) {
+    if (this.component.stateChanged) {
+      this.component.stateChanged(changes);
+    } else {
+      changes.forEach((v, k) => {
+        const setter = this.component[`set${capitalize(k)}`];
+        if (typeof setter === "function") {
+          setter.call(this.component, v);
+        } else {
+          this.component[k] = v;
+        }
+      });
+    }
+    this.touch();
+  }
+
+  // do recontent and notify all
+  touch() {
+    this.recontent();
+    this.notify();
+  }
+
+  // gets component property by key
+  get(propId: string): unknown {
+    const map = this.#propFnMap ?? (this.#propFnMap = new Map());
+    if (map.has(propId)) {
+      return map.get(propId)();
+    }
+
+    let fn: Fn | null = null;
+    const impl = this.component;
+    const instant = impl[propId];
+    if (instant && typeof instant === "function") {
+      const bound = instant.bind(impl);
+      fn = () => bound;
+    } else {
+      const [pk, ...path] = propId.split(".");
+      if (pk[0] === "@") {
+        path.unshift(pk.slice(1));
+        const val = this.platform.getResource(path) ?? null;
+        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());
+      }
+    }
+
+    map.set(propId, fn);
+
+    return fn();
+  }
+
+  getFromScope(propId: string): unknown {
+    return this.scope.get(propId);
+  }
+
+  // --- Left Arrow.
+
+  notify() {
+    this.#listeners?.forEach((fn) => fn(this));
+  }
+
+  // add listener to componet state changes
+  subscribe(handler: (src: Entitron) => any): Proc {
+    const listeners = this.#listeners ?? (this.#listeners = new Set());
+    listeners.add(handler);
+    return () => {
+      listeners.delete(handler);
+    };
+  }
+
+  // --- Right Arrow.
+
+  // emits action event to this component
+  emit(key: string, data: Delta): void {
+    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) { // spread '...'
+        ref.up(data);
+        return;
+      }
+
+      if (target[0] === "@") {
+        ref.up({ [target.slice(1)]: data });
+        return;
+      }
+
+      const impl = ref.component;
+      const method = impl[target] ?? impl[`on${capitalize(target)}`];
+
+      // deprecated. Use @-prefix instead.
+      if (!method) {
+        const propKey = target[0] === "@" ? target.slice(1) : target;
+        ref.up({ [propKey]: data });
+        return;
+      }
+
+      if (!(typeof method === "function")) {
+        throw new Error(`Not a method: ${refId}.${target}`);
+      }
+
+      const result = method.call(impl, data, impl, ref);
+
+      this.log(`-> ${refId}.${target}`, result, data, impl);
+
+      ref.up(result);
+    } catch (ex) {
+      this.logError(`emit ${key}:`, ex);
+    }
+    return;
+  }
+
+  // Done life-cycle hook.
+  done() {
+    if (this.isDone) {
+      return;
+    }
+    this.isDone = true;
+
+    this.component.done?.(this);
+
+    this.children?.forEach((c) => c.done());
+
+    this.#defered?.forEach((f) => f(this));
+    this.#defered = undefined;
+
+    this._parent?.children?.delete(this.uid);
+    this._parent = undefined;
+  }
+
+  // map of children contexts
+  get children(): Map<Uid, IEntitron> | undefined {
+    return this.$children;
+  }
+
+  // map of chidren of its node
+  get contentManifests() {
+    return this.manifest.getSubNodes(this.platform);
+  }
+
+  // actual scope for re-content
+  get recontentScope() {
+    return this.scope;
+  }
+
+  settleAsChild() {
+    if (!this.#isInited) {
+      this.#isInited = true;
+
+      this.initConnectors();
+
+      this.up(this.#initialState, true);
+
+      this.up(this.component.init?.(this));
+    } else {
+      void this.up(this.manifest.resolveProps(this), true);
+    }
+  }
+
+  // perform children instantiation and updates
+  private recontent() {
+    const nodes = this.contentManifests;
+
+    this.platform.redraw(this, this.root);
+
+    this.children?.forEach((e, uid) => {
+      if (!nodes?.get(uid)) {
+        e.done();
+      }
+    });
+
+    const children = new Map<Uid, IEntitron>();
+
+    nodes?.forEach((node: IManifestNode, uid: Uid) => {
+      const e = this.children?.get(uid) ?? node.createEntitron(this.platform, this, this.recontentScope);
+      children.set(e.uid, e);
+    });
+
+    this.$children = children;
+
+    for (const ch of children.values()) {
+      ch.settleAsChild();
+    }
+  }
+
+  // --- Referencing.
+
+  get refId() {
+    return this.manifest.refId;
+  }
+
+  // gets any context instance in current or upper scope by key
+  getByRef(refId: string): IEntitron | undefined {
+    if (!refId) return undefined;
+
+    if (refId === "this") {
+      return this;
+    }
+    const local = this.#refs?.[refId];
+    if (local) {
+      return local;
+    }
+    const ref = this === this.scope ? null : this.scope.getByRef(refId);
+    return ref as Entitron;
+  }
+
+  addReference(refId: string, c: IEntitron) {
+    (this.#refs ?? (this.#refs = {}))[refId] = c;
+  }
+
+  // --- Routines -------------------------
+
+  private initConnectors() {
+    if (this.manifest.connectors) {
+      for (const [key, pipes] of this.manifest.connectors.entries()) {
+        const [srcIds, targetPropName] = key.split("|");
+        const [refId, sourcePropName] = srcIds.split(".");
+
+        const ref = this.scope.getByRef(refId) as Entitron;
+        if (!ref) {
+          this.logError(`Connect: No such ref: ${refId}`);
+          continue;
+        }
+
+        if (!sourcePropName) {
+          this.logError(`Connect: No prop specified: ${key}`);
+          continue;
+        }
+
+        const propName = sourcePropName[0] === '@' ? sourcePropName.slice(1) : sourcePropName;
+        const applicator = targetPropName ? (rr: any) => ({ [targetPropName]: rr }) : identity;
+
+        this.defer(
+          ref.subscribe((source: Entitron) => {
+            try {
+              const r = applicator(pipes(this, source.get(propName)));
+              this.up(r as Delta);
+            } catch (ex) {
+              source.logError("Notify ", ex);
+            }
+          })
+        );
+
+        // hot subscription
+        Object.assign(this.#initialState, applicator(pipes(ref, ref.get(propName))));
+      }
+    }
+  }
+
+  raceCondition(key: string) {
+    const COUNTERS = this.#weak ?? (this.#weak = new Map<string, number>());
+    let counter = 1 + (COUNTERS.get(key) ?? 0);
+    COUNTERS.set(key, counter);
+    return (fn: () => unknown) => {
+      if (counter === COUNTERS.get(key)) {
+        counter = 0;
+        return fn();
+      }
+    };
+  }
+
+  // register callback to be called on done
+  defer(fn: EProcedure) {
+    if (fn && typeof fn === "function") {
+      (this.#defered ?? (this.#defered = [])).push(fn);
+    }
+  }
+
+  log(val: any, ...args: unknown[]) {
+    this.platform.log({
+      level: "log",
+      source: `${this.displayName}:${this.uid}`,
+      message: val,
+      params: args,
+    });
+    return val;
+  }
+
+  logError(error: any, ...args: unknown[]) {
+    this.platform.log({
+      level: "error",
+      source: `${this.displayName}:${this.uid}`,
+      error,
+      message: `${String(error.message || error)}\n${this.toString().slice(0, 120)}`,
+      params: args,
+    });
+  }
+
+  // access to resource by key
+  res(key: string | string[]) {
+    return this.platform.getResource(key);
+  }
+
+  toString(): string {
+    return stringify(this);
+  }
+}

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/registry/composition.ts

@@ -0,0 +1,66 @@
+import { ManifestNode } from "../core/ManifestNode";
+import { Entitron } from "../core/Entitron";
+import type { Hash, XmlNode } from "ultimus/types";
+import type { EContent, IManifestNode, IPlatform } from "arrmatura/types";
+
+export class Composite extends Entitron<CCompositeNode> {
+  get displayName(): string {
+    return `💠${this.manifest.tag}`;
+  }
+
+  get recontentScope(): Entitron {
+    return this;
+  }
+
+  slotContent(slotId?: string): EContent | undefined {
+    return this.manifest.getSlotContent(this.platform, slotId);
+  }
+
+  createComponent(initials: Hash) {
+    return this.platform.createComponent(this.manifest.tag, initials, this);
+  }
+}
+
+export class CCompositeNode extends ManifestNode {
+  slotContent: Hash<EContent> | null = null;
+  tag: string;
+  nodes?: XmlNode["nodes"];
+  #content?: Map<string, IManifestNode>;
+
+  constructor({ tag, attrs, nodes }: XmlNode) {
+    super();
+    this.tag = tag;
+    this.nodes = nodes;
+    this.compileAttributes(attrs);
+  }
+
+  getSlotContent(platform: IPlatform, slotId?: string): EContent | undefined {
+    if (!this.slotContent) {
+      const slots = this.nodes?.reduce<Hash<XmlNode[]>>((groups, e) => {
+        let gId = "default";
+        let isContainer = false;
+        if (e.tag.startsWith(`${this.tag}:`)) {
+          gId = e.tag.split(":")[1];
+          isContainer = true;
+        }
+        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;
+      }, {});
+    }
+
+    return this.slotContent[slotId ?? "default"] ?? undefined;
+  }
+
+  getSubNodes(platform: IPlatform) {
+    return this.#content ?? (this.#content = platform.getCompiledNodes(this.tag));
+  }
+
+  get EntitronConstructor() {
+    return Composite;
+  }
+}

package/src/registry/conditionals.ts

@@ -0,0 +1,75 @@
+import { ManifestNode } from "../core/ManifestNode";
+import { Composite } from "./composition";
+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 Entitron<CIfNode> {
+  get contentManifests() {
+    const branches = this.manifest.getBranches(this.platform);
+    return this.component.condition ? branches.then : branches.else;
+  }
+
+  get displayName(): string {
+    return "🔹if";
+  }
+}
+
+export class CIfNode extends ManifestNode {
+  #xml: XmlNode;
+  #branches?: { then?: EContent; else?: EContent };
+  constructor(xml: XmlNode, expr: string) {
+    super();
+    this.#xml = xml;
+    this.compileCondition(expr);
+  }
+
+  get EntitronConstructor() {
+    return Conditional;
+  }
+
+  getBranches(platform: IPlatform) {
+    if (this.#branches) {
+      return this.#branches;
+    }
+
+    this.#branches = {};
+
+    const { nodes } = this.#xml;
+
+    let $then: XmlNode[] | undefined = [this.#xml];
+    if (nodes?.length) {
+      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;
+        $then = ifThen
+          ? ifThen.nodes
+          : [
+            Object.assign(this.#xml, {
+              nodes: nodes.filter((e) => e !== ifElse),
+            }),
+          ];
+      } else if (ifThen) {
+        $then = ifThen.nodes;
+      }
+    }
+    this.#branches.then = $then ? platform.getCompiledNodes($then) : undefined;
+
+    return this.#branches;
+  }
+
+  compileCondition(expr: string): void {
+    if (expr[0] === "<" && expr[1] === "-") {
+      this.addConnector(expr.slice(2), "condition");
+    } else if (expr.slice(0, 5) === "slot(") {
+      const slotId = expr.slice(5, -1);
+      // DO NOT place inside iterations.
+      this.addPropertyResolver((c: IEntitron) => !!(c.scope as Composite).slotContent?.(slotId)?.size, "condition");
+    } else {
+      const resolver = compilePlaceholder(expr);
+      this.addPropertyResolver((c) => !!resolver(c), "condition");
+    }
+  }
+}