@quenk/wml 2.14.0 → 2.15.0

package/lib/view/frame.ts

@@ -71,12 +71,96 @@ class SetList {
 }
 
 /**
- * ViewFrame serves as a container for a View's rendered template.
+ * Frame serves as a container for the DOM elements a View's template
+ * renders.
  *
- * This class containers helper methods for retreiving elements by id or
+ * Each time the render() method is called a new Frame is created and passed
+ * to the rendering logic so that a DOM tree is built along with accesible
+ * wml ids and groups.
+ */
+export interface Frame {
+  /**
+   * tree when sets is the rendered DOM content of the view
+   */
+  tree?: Content;
+
+  /**
+   * root sets the root element of a View's tree.
+   */
+  root(el: Content): void;
+
+  /**
+   * node constructs a DOM node to be used in the View's tree.
+   *
+   * Any id or group assignment will be honored.
+   */
+  node(tag: string, attrs: Attrs, children: Content[]): Content;
+
+  /**
+   * widget constructs a DOM sub-tree for a Widget in the View's tree.
+   *
+   * Any id or group assignment will be honored.
+   */
+  widget(w: Widget, attrs: Attrs): Content;
+
+  /**
+   * view renders the content of another view, saving its ids and groups to
+   * this one.
+   */
+  view(view: View): Content;
+
+  /**
+   * register content and widget under the specified id.
+   */
+  register(id: WMLId, node: Content, widget?: Widget): void;
+
+  /**
+   * registerGroupMember registers a content and widget as a member of a group.
+   */
+  registerGroupMember(id: WMLId, node: Content, widget?: Widget): void;
+
+  /**
+   * findById returns the entry stored for the specified wml element.
+   */
+  findById(id: WMLId): Maybe<Entry>;
+
+  /**
+   * findByGroup returns all the entries stored fro a group.
+   */
+  findByGroup(id: WMLId): Entry[];
+
+  /**
+   * replaceByIndex performs the heavy work of replacing a WMLElement
+   * with the corresponding index from another ViewFrame.
+   *
+   * The replaced element will have its DOM content redrawn if a parentNode
+   * is detected.
+   */
+  replaceByIndex(next: ViewFrame, idx: Index): void;
+
+  /**
+   * replaceById allows WMLElement replacement by using an id.
+   */
+  replaceById(next: ViewFrame, id: WMLId): void;
+
+  /**
+   * replaceByGroup allows WMLElement replaced by using a group identifier.
+   */
+  replaceByGroup(next: ViewFrame, id: WMLId): void;
+
+  /**
+   * destroy the frame.
+   *
+   * Currently a no-op but may be used in the future.
+   */
+  destroy(): void;
+}
+
+/**
+ * ViewFrame contains helper methods for retreiving elements by id or
  * group freeing the View class of such logic.
  */
-export class ViewFrame {
+export class ViewFrame implements Frame {
   constructor(
     public nodes = new SetList(),
     public widgets = new Map<Index, Widget>(),
@@ -86,7 +170,7 @@ export class ViewFrame {
     public tree?: Content,
   ) {}
 
-  _register(id: WMLId, node: Content, widget?: Widget) {
+  register(id: WMLId, node: Content, widget?: Widget) {
     let idx = this.nodes.add(node);
     this.ids.set(id, idx);
     this.indexes.set(idx, id);
@@ -95,7 +179,7 @@ export class ViewFrame {
     }
   }
 
-  _registerGroupMember(id: WMLId, node: Content, widget?: Widget) {
+  registerGroupMember(id: WMLId, node: Content, widget?: Widget) {
     let group = this.groups.get(id) ?? [];
     let idx = this.nodes.add(node);
     group.push(idx);
@@ -105,18 +189,10 @@ export class ViewFrame {
     this.groups.set(id, group);
   }
 
-  /**
-   * root sets the root element of a View's tree.
-   */
   root(el: Content) {
     this.tree = el;
   }
 
-  /**
-   * node constructs a DOM node to be used in the View's tree.
-   *
-   * Any id or group assignment will be honored.
-   */
   node(tag: string, attrs: Attrs, children: Content[]): Content {
     let elm = dom.createElement(
       tag,
@@ -125,34 +201,25 @@ export class ViewFrame {
       (attrs.wml && attrs.wml.ns) || "",
     );
 
-    if (attrs?.wml?.id) this._register(attrs.wml.id, elm);
+    if (attrs?.wml?.id) this.register(attrs.wml.id, elm);
 
-    if (attrs?.wml?.group) this._registerGroupMember(attrs.wml.group, elm);
+    if (attrs?.wml?.group) this.registerGroupMember(attrs.wml.group, elm);
 
     return elm;
   }
 
-  /**
-   * widget constructs a DOM sub-tree for a Widget in the View's tree.
-   *
-   * Any id or group assignment will be honored.
-   */
   widget(w: Widget, attrs: Attrs): Content {
     let tree = w.render();
 
     DOMMonitor.getInstance().monitor(tree, w);
 
-    if (attrs?.wml?.id) this._register(attrs.wml.id, tree, w);
+    if (attrs?.wml?.id) this.register(attrs.wml.id, tree, w);
 
-    if (attrs?.wml?.group) this._registerGroupMember(attrs.wml.group, tree, w);
+    if (attrs?.wml?.group) this.registerGroupMember(attrs.wml.group, tree, w);
 
     return tree;
   }
 
-  /**
-   * view renders the content of another view, saving its ids and groups to
-   * this one.
-   */
   view(view: View): Content {
     let { root } = this;
     let tree = view.render(this);
@@ -160,9 +227,6 @@ export class ViewFrame {
     return tree;
   }
 
-  /**
-   * findById returns the entry stored for the specified wml element.
-   */
   findById(id: WMLId): Maybe<Entry> {
     let idx = this.ids.get(id) ?? -1;
     let node = this.nodes.get(idx);
@@ -173,9 +237,6 @@ export class ViewFrame {
     });
   }
 
-  /**
-   * findByGroup returns all the entries stored fro a group.
-   */
   findByGroup(id: WMLId): Entry[] {
     let result = [];
     for (let idx of this.groups.get(id) ?? []) {
@@ -187,19 +248,11 @@ export class ViewFrame {
     return result;
   }
 
-  /**
-   * replaceByIndex performs the heavy work of replacing a WMLElement
-   * with the corresponding index from another ViewFrame.
-   *
-   * The replaced element will have its DOM content redrawn if a parentNode
-   * is detected.
-   */
   replaceByIndex(next: ViewFrame, idx: Index) {
     let originalNode = this.nodes.get(idx);
-    let id = this.indexes.get(idx) ?? "";
 
     if (idx == null || originalNode == null) {
-      console.warn(`Not replacing missing WMLElement for id "${id}"!`);
+      console.warn(`Not replacing missing element by index ${idx}!`);
       return;
     }
 
@@ -207,12 +260,16 @@ export class ViewFrame {
 
     let node = next.nodes.get(idx);
     let widget = next.widgets.get(idx);
+
     if (node == null) {
       // Remove references since the node no longer exists.
       this.nodes.delete(idx);
       this.widgets.delete(idx);
+
+      let id = this.indexes.get(idx) ?? "";
       this.ids.delete(id);
       this.indexes.delete(idx);
+
       if (parentNode) parentNode.removeChild(originalNode);
       return;
     }
@@ -225,16 +282,10 @@ export class ViewFrame {
     if (parentNode) parentNode.replaceChild(node, originalNode);
   }
 
-  /**
-   * replaceById allows WMLElement replacement by using an id.
-   */
   replaceById(next: ViewFrame, id: WMLId) {
     this.replaceByIndex(next, this.ids.get(id) ?? -1);
   }
 
-  /**
-   * replaceByGroup allows WMLElement replaced by using a group identifier.
-   */
   replaceByGroup(next: ViewFrame, id: WMLId) {
     let group = this.groups.get(id) ?? [];
 
@@ -246,4 +297,6 @@ export class ViewFrame {
 
     this.groups.set(id, newGroup);
   }
+
+  destroy() {}
 }

package/lib/view/index.d.ts

@@ -1,10 +1,10 @@
 import { Maybe } from "@quenk/noni/lib/data/maybe";
 import { Content, WMLElement, WMLId } from "..";
-import { ViewFrame } from "./frame";
+import { Frame, ViewFrame } from "./frame";
 /**
  * Renderer is a function that builds up a ViewFrame on behalf of the view.
  */
-export type Renderer = (frame: ViewFrame) => ViewFrame;
+export type Renderer = (frame: Frame) => void;
 /**
  * View instances are compiled from wml template files.
  *
@@ -15,10 +15,11 @@ export interface View {
     /**
      * render the View.
      *
-     * If a ViewFrame is provided, it will be used instead of creating a new one
-     * internally. In this case the View itself will not be mutated internally.
+     * If parent is provided, it is treated as the parent Frame to the internal
+     * frame the view will be created. This allows ids from this frame to be
+     * accessed in the parent scope.
      */
-    render(frame?: ViewFrame): Content;
+    render(parent?: ViewFrame): Content;
     /**
      * invalidate this View causing the DOM to be re-rendered.
      *
@@ -49,10 +50,10 @@ export interface View {
 export declare class BaseView implements View {
     context: object;
     renderer: Renderer;
-    frame: ViewFrame;
-    constructor(context: object, renderer: Renderer, frame?: ViewFrame);
+    frame: Frame;
+    constructor(context: object, renderer: Renderer, frame?: Frame);
     findById<E extends WMLElement>(id: string): Maybe<E>;
     findGroupById<E extends WMLElement>(name: string): E[];
     invalidate(id?: WMLId): void;
-    render(frame?: ViewFrame): Content;
+    render(): Content;
 }

package/lib/view/index.js

@@ -27,7 +27,8 @@ class BaseView {
         if (frame.tree == null || frame.tree.parentNode == null)
             return console.warn("invalidate(): cannot invalidate this view, it has no parent node!");
         if (id) {
-            let next = this.renderer(new frame_1.ViewFrame());
+            let next = new frame_1.ViewFrame();
+            this.renderer(next);
             if (id[0] === "$")
                 frame.replaceByGroup(next, id.slice(1));
             else
@@ -37,10 +38,10 @@ class BaseView {
             frame.tree.parentNode.replaceChild(this.render(), frame.tree);
         }
     }
-    render(frame) {
-        if (frame)
-            return this.renderer(frame).tree;
-        this.frame = this.renderer(new frame_1.ViewFrame());
+    render() {
+        this.frame?.destroy();
+        this.frame = new frame_1.ViewFrame();
+        this.renderer(this.frame);
         return this.frame.tree;
     }
 }

package/lib/view/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":";;;AAGA,mCAA2C;AA8C3C;;;;;GAKG;AACH,MAAa,QAAQ;IACnB,YACS,OAAe,EACf,QAAkB,EAClB,QAAQ,IAAI,iBAAS,EAAE;QAFvB,YAAO,GAAP,OAAO,CAAQ;QACf,aAAQ,GAAR,QAAQ,CAAU;QAClB,UAAK,GAAL,KAAK,CAAkB;IAC7B,CAAC;IAEJ,QAAQ,CAAuB,EAAU;QACvC,OAAO,IAAI,CAAC,KAAK;aACd,QAAQ,CAAC,EAAE,CAAC;aACZ,GAAG,CAAC,CAAC,GAAU,EAAE,EAAE,CAAI,CAAC,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;IACtD,CAAC;IAED,aAAa,CAAuB,IAAY;QAC9C,OAAY,CACV,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,IAAI,CAAC,CACxE,CAAC;IACJ,CAAC;IAED,UAAU,CAAC,EAAU;QACnB,IAAI,EAAE,KAAK,EAAE,GAAG,IAAI,CAAC;QAErB,IAAI,KAAK,CAAC,IAAI,IAAI,IAAI,IAAI,KAAK,CAAC,IAAI,CAAC,UAAU,IAAI,IAAI;YACrD,OAAO,OAAO,CAAC,IAAI,CACjB,mEAAmE,CACpE,CAAC;QAEJ,IAAI,EAAE,EAAE,CAAC;YACP,IAAI,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,iBAAS,EAAE,CAAC,CAAC;YAC1C,IAAI,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG;gBAAE,KAAK,CAAC,cAAc,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;;gBACtD,KAAK,CAAC,WAAW,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACnC,CAAC;aAAM,CAAC;YACN,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QAChE,CAAC;IACH,CAAC;IAED,MAAM,CAAC,KAAiB;QACtB,IAAI,KAAK;YAAE,OAAgB,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC;QACrD,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,iBAAS,EAAE,CAAC,CAAC;QAC5C,OAAgB,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IAClC,CAAC;CACF;AAzCD,4BAyCC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":";;;AAGA,mCAAkD;AA+ClD;;;;;GAKG;AACH,MAAa,QAAQ;IACnB,YACS,OAAe,EACf,QAAkB,EAClB,QAAe,IAAI,iBAAS,EAAE;QAF9B,YAAO,GAAP,OAAO,CAAQ;QACf,aAAQ,GAAR,QAAQ,CAAU;QAClB,UAAK,GAAL,KAAK,CAAyB;IACpC,CAAC;IAEJ,QAAQ,CAAuB,EAAU;QACvC,OAAO,IAAI,CAAC,KAAK;aACd,QAAQ,CAAC,EAAE,CAAC;aACZ,GAAG,CAAC,CAAC,GAAU,EAAE,EAAE,CAAI,CAAC,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;IACtD,CAAC;IAED,aAAa,CAAuB,IAAY;QAC9C,OAAY,CACV,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,IAAI,CAAC,CACxE,CAAC;IACJ,CAAC;IAED,UAAU,CAAC,EAAU;QACnB,IAAI,EAAE,KAAK,EAAE,GAAG,IAAI,CAAC;QAErB,IAAI,KAAK,CAAC,IAAI,IAAI,IAAI,IAAI,KAAK,CAAC,IAAI,CAAC,UAAU,IAAI,IAAI;YACrD,OAAO,OAAO,CAAC,IAAI,CACjB,mEAAmE,CACpE,CAAC;QAEJ,IAAI,EAAE,EAAE,CAAC;YACP,IAAI,IAAI,GAAG,IAAI,iBAAS,EAAE,CAAC;YAC3B,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;YACpB,IAAI,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG;gBAAE,KAAK,CAAC,cAAc,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;;gBACtD,KAAK,CAAC,WAAW,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACnC,CAAC;aAAM,CAAC;YACN,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QAChE,CAAC;IACH,CAAC;IAED,MAAM;QACJ,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,CAAC;QACtB,IAAI,CAAC,KAAK,GAAG,IAAI,iBAAS,EAAE,CAAC;QAC7B,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC1B,OAAgB,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IAClC,CAAC;CACF;AA3CD,4BA2CC"}

package/lib/view/index.ts

@@ -1,12 +1,12 @@
 import { Maybe } from "@quenk/noni/lib/data/maybe";
 
 import { Content, WMLElement, WMLId } from "..";
-import { Entry, ViewFrame } from "./frame";
+import { Entry, Frame, ViewFrame } from "./frame";
 
 /**
  * Renderer is a function that builds up a ViewFrame on behalf of the view.
  */
-export type Renderer = (frame: ViewFrame) => ViewFrame;
+export type Renderer = (frame: Frame) => void;
 
 /**
  * View instances are compiled from wml template files.
@@ -18,10 +18,11 @@ export interface View {
   /**
    * render the View.
    *
-   * If a ViewFrame is provided, it will be used instead of creating a new one
-   * internally. In this case the View itself will not be mutated internally.
+   * If parent is provided, it is treated as the parent Frame to the internal
+   * frame the view will be created. This allows ids from this frame to be
+   * accessed in the parent scope.
    */
-  render(frame?: ViewFrame): Content;
+  render(parent?: ViewFrame): Content;
 
   /**
    * invalidate this View causing the DOM to be re-rendered.
@@ -57,7 +58,7 @@ export class BaseView implements View {
   constructor(
     public context: object,
     public renderer: Renderer,
-    public frame = new ViewFrame(),
+    public frame: Frame = new ViewFrame(),
   ) {}
 
   findById<E extends WMLElement>(id: string): Maybe<E> {
@@ -81,7 +82,8 @@ export class BaseView implements View {
       );
 
     if (id) {
-      let next = this.renderer(new ViewFrame());
+      let next = new ViewFrame();
+      this.renderer(next);
       if (id[0] === "$") frame.replaceByGroup(next, id.slice(1));
       else frame.replaceById(next, id);
     } else {
@@ -89,9 +91,10 @@ export class BaseView implements View {
     }
   }
 
-  render(frame?: ViewFrame): Content {
-    if (frame) return <Content>this.renderer(frame).tree;
-    this.frame = this.renderer(new ViewFrame());
+  render(): Content {
+    this.frame?.destroy();
+    this.frame = new ViewFrame();
+    this.renderer(this.frame);
     return <Content>this.frame.tree;
   }
 }

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@quenk/wml",
-  "version": "2.14.0",
+  "version": "2.15.0",
   "description": "(WML) is a DSL for describing user interfaces in web applications.",
   "main": "lib/index.js",
   "scripts": {
-    "test": "./node_modules/.bin/mocha $(find -name *_test.ts)"
+    "test": "./node_modules/.bin/jest test"
   },
   "types": "lib/index.d.ts",
   "files": [
@@ -16,13 +16,17 @@
   "author": "Quenk Technologies Limited <info@quenk.com> (https://quenk.com)",
   "license": "Apache-2.0",
   "devDependencies": {
+    "@jest/globals": "^30.2.0",
     "@quenk/test": "^2.4.0",
     "@types/docopt": "^0.6.31",
+    "@types/jest": "^30.0.0",
     "@types/mocha": "^8.2.2",
     "@types/node": "^24.3.0",
+    "jest": "^30.2.0",
     "jison-gho": "^0.6.1-216",
     "mocha": "^9.0.0",
     "prettier": "^3.5.3",
+    "ts-jest": "^29.4.6",
     "ts-node": "^10.5.0",
     "typescript": "^5.9.2"
   },