@thi.ng/rdom 0.9.20 → 0.10.1

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2022-11-23T22:46:54Z
+- **Last updated**: 2022-12-10T14:04:38Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,18 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+## [0.10.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/rdom@0.10.0) (2022-11-30)
+
+#### 🚀 Features
+
+- add DOM comment support ([#367](https://github.com/thi-ng/umbrella/issues/367)), other refactorings ([3fd5f8e](https://github.com/thi-ng/umbrella/commit/3fd5f8e))
+  - add $comment(), isComment()
+  - add Component.$comment() syntax sugar
+  - add comment check/branch in $tree()
+  - update args for $addChild(), $remove(), $moveTo()
+  - update $text(), $html() to support SVG elements
+  - add doc strings
+
 ## [0.9.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/rdom@0.9.0) (2022-07-12)
 
 #### 🚀 Features

package/README.md

@@ -173,7 +173,7 @@ node --experimental-repl-await
 > const rdom = await import("@thi.ng/rdom");
 ```
 
-Package sizes (gzipped, pre-treeshake): ESM: 4.08 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 3.81 KB
 
 ## Dependencies
 

package/checks.d.ts

@@ -1,3 +1,19 @@
 import type { IComponent } from "./api.js";
+/**
+ * Returns true if given hiccup component describes a comment node. I.e. is of
+ * the form `[COMMENT, "foo"...]`.
+ *
+ * @remarks
+ * See thi.ng/hiccup docs for reference:
+ * - https://docs.thi.ng/umbrella/hiccup/functions/serialize.html
+ *
+ * @param tree
+ */
+export declare const isComment: (tree: any[]) => boolean;
+/**
+ * Returns true, if given value has a {@link IComponent.mount} function.
+ *
+ * @param x
+ */
 export declare const isComponent: (x: any) => x is IComponent<any>;
 //# sourceMappingURL=checks.d.ts.map

package/checks.js

@@ -1,2 +1,19 @@
 import { implementsFunction } from "@thi.ng/checks/implements-function";
+import { COMMENT } from "@thi.ng/hiccup/api";
+/**
+ * Returns true if given hiccup component describes a comment node. I.e. is of
+ * the form `[COMMENT, "foo"...]`.
+ *
+ * @remarks
+ * See thi.ng/hiccup docs for reference:
+ * - https://docs.thi.ng/umbrella/hiccup/functions/serialize.html
+ *
+ * @param tree
+ */
+export const isComment = (tree) => tree[0] === COMMENT;
+/**
+ * Returns true, if given value has a {@link IComponent.mount} function.
+ *
+ * @param x
+ */
 export const isComponent = (x) => implementsFunction(x, "mount");

package/component.d.ts

@@ -10,15 +10,102 @@ export declare abstract class Component<T = any> implements IComponent<T> {
     abstract mount(parent: Element, index?: NumOrElement, ...xs: any[]): Promise<Element>;
     unmount(): Promise<void>;
     update(state?: T): void;
+    /**
+     * Syntax sugar for {@link $el}, using this component's
+     * {@link IComponent.el} as default `parent`.
+     *
+     * @param tag
+     * @param attribs
+     * @param body
+     * @param parent
+     * @param idx
+     */
     $el(tag: string, attribs?: any, body?: any, parent?: Element | undefined, idx?: NumOrElement): Element;
+    /**
+     * Syntax sugar for {@link $comment}, creates a new comment DOM node using
+     * this component's {@link IComponent.el} as default `parent`.
+     *
+     * @param body
+     * @param parent
+     * @param idx
+     */
+    $comment(body: string | string[], parent?: Element | undefined, idx?: NumOrElement): Comment;
+    /**
+     * Syntax sugar for {@link $clear}, using this component's
+     * {@link IComponent.el} as default element to clear.
+     *
+     * @param el
+     */
     $clear(el?: Element): Element;
+    /**
+     * Same as {@link $compile}.
+     *
+     * @param tree
+     */
     $compile(tree: any): IComponent<any>;
+    /**
+     * Same as {@link $tree}.
+     *
+     * @param tree
+     * @param root
+     * @param index
+     */
     $tree(tree: any, root?: Element, index?: NumOrElement): Promise<any>;
-    $text(body: any): void;
-    $html(body: MaybeDeref<string>): void;
+    /**
+     * Syntax sugar for {@link $text}, using this component's
+     * {@link IComponent.el} as default element to edit.
+     *
+     * @remarks
+     * If using the default element, assumes `this.el` is an existing
+     * `HTMLElement`.
+     *
+     * @param body
+     * @param el
+     */
+    $text(body: any, el?: HTMLElement): void;
+    /**
+     * Syntax sugar for {@link $html}, using this component's
+     * {@link IComponent.el} as default element to edit.
+     *
+     * @remarks
+     * If using the default element, assumes `this.el` is an existing
+     * `HTMLElement` or `SVGElement`.
+     *
+     * @param body
+     * @param el
+     */
+    $html(body: MaybeDeref<string>, el?: HTMLElement | SVGElement): void;
+    /**
+     * Syntax sugar for {@link $attribs}, using this component's
+     * {@link IComponent.el} as default element to edit.
+     *
+     * @param attribs
+     * @param el
+     */
     $attribs(attribs: any, el?: Element): void;
+    /**
+     * Syntax sugar for {@link $style}, using this component's
+     * {@link IComponent.el} as default element to edit.
+     *
+     * @param rules
+     * @param el
+     */
     $style(rules: any, el?: Element): void;
+    /**
+     * Syntax sugar for {@link $remove}, using this component's
+     * {@link IComponent.el} as default element to remove.
+     *
+     * @param el
+     */
     $remove(el?: Element): void;
+    /**
+     * Syntax sugar for {@link $moveTo}, using this component's
+     * {@link IComponent.el} as default element to migrate.
+     *
+     * @param newParent
+     * @param el
+     * @param idx
+     */
     $moveTo(newParent: Element, el?: Element, idx?: NumOrElement): void;
 }
 //# sourceMappingURL=component.d.ts.map

package/component.js

@@ -1,5 +1,5 @@
 import { $compile } from "./compile.js";
-import { $attribs, $clear, $el, $html, $moveTo, $remove, $style, $text, $tree, } from "./dom.js";
+import { $attribs, $clear, $comment, $el, $html, $moveTo, $remove, $style, $text, $tree, } from "./dom.js";
 /**
  * Abstract base class / {@link IComponent} implementation. Provides
  * additional convenience methods for DOM element creation &
@@ -12,33 +12,122 @@ export class Component {
     }
     // @ts-ignore args
     update(state) { }
+    /**
+     * Syntax sugar for {@link $el}, using this component's
+     * {@link IComponent.el} as default `parent`.
+     *
+     * @param tag
+     * @param attribs
+     * @param body
+     * @param parent
+     * @param idx
+     */
     $el(tag, attribs, body, parent = this.el, idx) {
         return $el(tag, attribs, body, parent, idx);
     }
+    /**
+     * Syntax sugar for {@link $comment}, creates a new comment DOM node using
+     * this component's {@link IComponent.el} as default `parent`.
+     *
+     * @param body
+     * @param parent
+     * @param idx
+     */
+    $comment(body, parent = this.el, idx) {
+        return $comment(body, parent, idx);
+    }
+    /**
+     * Syntax sugar for {@link $clear}, using this component's
+     * {@link IComponent.el} as default element to clear.
+     *
+     * @param el
+     */
     $clear(el = this.el) {
         return $clear(el);
     }
+    /**
+     * Same as {@link $compile}.
+     *
+     * @param tree
+     */
     $compile(tree) {
         return $compile(tree);
     }
+    /**
+     * Same as {@link $tree}.
+     *
+     * @param tree
+     * @param root
+     * @param index
+     */
     $tree(tree, root = this.el, index) {
         return $tree(tree, root, index);
     }
-    $text(body) {
-        this.el && $text(this.el, body);
+    /**
+     * Syntax sugar for {@link $text}, using this component's
+     * {@link IComponent.el} as default element to edit.
+     *
+     * @remarks
+     * If using the default element, assumes `this.el` is an existing
+     * `HTMLElement`.
+     *
+     * @param body
+     * @param el
+     */
+    $text(body, el = this.el) {
+        $text(el, body);
     }
-    $html(body) {
-        this.el && $html(this.el, body);
+    /**
+     * Syntax sugar for {@link $html}, using this component's
+     * {@link IComponent.el} as default element to edit.
+     *
+     * @remarks
+     * If using the default element, assumes `this.el` is an existing
+     * `HTMLElement` or `SVGElement`.
+     *
+     * @param body
+     * @param el
+     */
+    $html(body, el = this.el) {
+        $html(el, body);
     }
+    /**
+     * Syntax sugar for {@link $attribs}, using this component's
+     * {@link IComponent.el} as default element to edit.
+     *
+     * @param attribs
+     * @param el
+     */
     $attribs(attribs, el = this.el) {
         $attribs(el, attribs);
     }
+    /**
+     * Syntax sugar for {@link $style}, using this component's
+     * {@link IComponent.el} as default element to edit.
+     *
+     * @param rules
+     * @param el
+     */
     $style(rules, el = this.el) {
         $style(el, rules);
     }
+    /**
+     * Syntax sugar for {@link $remove}, using this component's
+     * {@link IComponent.el} as default element to remove.
+     *
+     * @param el
+     */
     $remove(el = this.el) {
         $remove(el);
     }
+    /**
+     * Syntax sugar for {@link $moveTo}, using this component's
+     * {@link IComponent.el} as default element to migrate.
+     *
+     * @param newParent
+     * @param el
+     * @param idx
+     */
     $moveTo(newParent, el = this.el, idx) {
         $moveTo(newParent, el, idx);
     }

package/dom.d.ts

@@ -1,22 +1,26 @@
 import { MaybeDeref } from "@thi.ng/api/deref";
 import type { NumOrElement } from "./api.js";
 /**
- * hdom-style DOM tree creation from hiccup format. Returns DOM element
- * of `tree` root. See {@link $el} for further details.
+ * hdom-style DOM tree creation from hiccup format. Returns DOM element of
+ * `tree` root. See {@link $el} for further details.
  *
  * @remarks
  * Supports elements given in these forms:
  *
  * - {@link IComponent} instance
- * - {@link IDeref} instance (must resolve to another supported type in
- *   this list)
+ * - {@link IDeref} instance (must resolve to another supported type in this
+ *   list)
  * - `["div#id.class", {...attribs}, ...children]`
+ * - `[COMMENT, "foo", "bar"...]` (DOM comment node)
  * - `[IComponent, ...mountargs]`
  * - `[function, ...args]`
  * - ES6 iterable of the above (for child values only!)
  *
- * Any other values will be cast to strings and added as spans to
- * current `parent`.
+ * Any other values will be cast to strings and added as spans to current
+ * `parent`.
+ *
+ * Note: `COMMENT` is defined as constant in thi.ng/hiccup package. Also see
+ * {@link $comment} function to create comments directly.
  *
  * @param tree -
  * @param parent -
@@ -41,9 +45,50 @@ export declare const $tree: (tree: any, parent: Element, idx?: NumOrElement) =>
  * @param idx -
  */
 export declare const $el: (tag: string, attribs: any, body?: any, parent?: Element, idx?: NumOrElement) => Element;
-export declare const $addChild: (parent: Element, child: Element, idx?: NumOrElement) => void;
-export declare const $remove: (el: Element) => void;
-export declare const $moveTo: (newParent: Element, el: Element, idx?: NumOrElement) => void;
+/**
+ * Similar to {@link $el}, but creates a new comment DOM node using provided
+ * body. If `parent` is given, the comment will be attached or inserted as child
+ * at `idx`. Returns comment node.
+ *
+ * @remarks
+ * See thi.ng/hiccup docs for reference:
+ * - https://docs.thi.ng/umbrella/hiccup/functions/serialize.html
+ *
+ * @param body
+ * @param parent
+ * @param idx
+ */
+export declare const $comment: (body: string | string[], parent?: Element, idx?: NumOrElement) => Comment;
+/**
+ * Appends or inserts `child` as child element of `parent`. The default `idx` of
+ * -1 means the child will be appended, else uses `parent.insertBefore()` to
+ * insert at given index.
+ *
+ * @param parent
+ * @param child
+ * @param idx
+ */
+export declare const $addChild: (parent: Element, child: Element | Comment, idx?: NumOrElement) => void;
+/**
+ * Removes given element or comment from the DOM.
+ *
+ * @param el
+ */
+export declare const $remove: (el: Element | Comment) => void;
+/**
+ * Migrates given element to `newParent`, following the same append or insertion
+ * logic as {@link $addChild}.
+ *
+ * @param newParent
+ * @param el
+ * @param idx
+ */
+export declare const $moveTo: (newParent: Element, el: Element | Comment, idx?: NumOrElement) => void;
+/**
+ * Removes all content from given element.
+ *
+ * @param el
+ */
 export declare const $clear: (el: Element) => Element;
 /**
  * Same as `el.innerText = body`, however if `body` is an
@@ -53,7 +98,7 @@ export declare const $clear: (el: Element) => Element;
  * @param el -
  * @param body -
  */
-export declare const $text: (el: HTMLElement, body: any) => void;
+export declare const $text: (el: HTMLElement | SVGElement, body: any) => void;
 /**
  * Same as `el.innerHtml = body`, use with caution! If `body` is an
  * {@link @thi.ng/api#IDeref} it'll be automatically deref'd.
@@ -61,7 +106,7 @@ export declare const $text: (el: HTMLElement, body: any) => void;
  * @param el -
  * @param body -
  */
-export declare const $html: (el: HTMLElement, body: MaybeDeref<string>) => void;
+export declare const $html: (el: HTMLElement | SVGElement, body: MaybeDeref<string>) => void;
 /**
  * Takes an object of attributes and applies them to given DOM element.
  *

package/dom.js

@@ -11,31 +11,37 @@ import { ATTRIB_JOIN_DELIMS, NO_SPANS, RE_TAG, SVG_TAGS, } from "@thi.ng/hiccup/
 import { mergeClasses, mergeEmmetAttribs } from "@thi.ng/hiccup/attribs";
 import { formatPrefixes } from "@thi.ng/hiccup/prefix";
 import { XML_SVG, XML_XLINK, XML_XMLNS } from "@thi.ng/prefixes/xml";
-import { isComponent } from "./checks.js";
+import { isComment, isComponent } from "./checks.js";
 /**
- * hdom-style DOM tree creation from hiccup format. Returns DOM element
- * of `tree` root. See {@link $el} for further details.
+ * hdom-style DOM tree creation from hiccup format. Returns DOM element of
+ * `tree` root. See {@link $el} for further details.
  *
  * @remarks
  * Supports elements given in these forms:
  *
  * - {@link IComponent} instance
- * - {@link IDeref} instance (must resolve to another supported type in
- *   this list)
+ * - {@link IDeref} instance (must resolve to another supported type in this
+ *   list)
  * - `["div#id.class", {...attribs}, ...children]`
+ * - `[COMMENT, "foo", "bar"...]` (DOM comment node)
  * - `[IComponent, ...mountargs]`
  * - `[function, ...args]`
  * - ES6 iterable of the above (for child values only!)
  *
- * Any other values will be cast to strings and added as spans to
- * current `parent`.
+ * Any other values will be cast to strings and added as spans to current
+ * `parent`.
+ *
+ * Note: `COMMENT` is defined as constant in thi.ng/hiccup package. Also see
+ * {@link $comment} function to create comments directly.
  *
  * @param tree -
  * @param parent -
  * @param idx -
  */
 export const $tree = async (tree, parent, idx = -1) => isArray(tree)
-    ? $treeElem(tree, parent, idx)
+    ? isComment(tree)
+        ? $comment(tree.slice(1), parent, idx)
+        : $treeElem(tree, parent, idx)
     : isComponent(tree)
         ? tree.mount(parent, idx)
         : isDeref(tree)
@@ -121,6 +127,37 @@ export const $el = (tag, attribs, body, parent, idx = -1) => {
     parent && $addChild(parent, el, idx);
     return el;
 };
+/**
+ * Similar to {@link $el}, but creates a new comment DOM node using provided
+ * body. If `parent` is given, the comment will be attached or inserted as child
+ * at `idx`. Returns comment node.
+ *
+ * @remarks
+ * See thi.ng/hiccup docs for reference:
+ * - https://docs.thi.ng/umbrella/hiccup/functions/serialize.html
+ *
+ * @param body
+ * @param parent
+ * @param idx
+ */
+export const $comment = (body, parent, idx = -1) => {
+    const comment = document.createComment(isString(body)
+        ? body
+        : body.length < 2
+            ? body[0] || ""
+            : ["", ...body, ""].join("\n"));
+    parent && $addChild(parent, comment, idx);
+    return comment;
+};
+/**
+ * Appends or inserts `child` as child element of `parent`. The default `idx` of
+ * -1 means the child will be appended, else uses `parent.insertBefore()` to
+ * insert at given index.
+ *
+ * @param parent
+ * @param child
+ * @param idx
+ */
 export const $addChild = (parent, child, idx = -1) => {
     isNumber(idx)
         ? idx < 0 || idx >= parent.children.length
@@ -128,11 +165,29 @@ export const $addChild = (parent, child, idx = -1) => {
             : parent.insertBefore(child, parent.children[idx])
         : parent.insertBefore(child, idx);
 };
+/**
+ * Removes given element or comment from the DOM.
+ *
+ * @param el
+ */
 export const $remove = (el) => el.remove();
+/**
+ * Migrates given element to `newParent`, following the same append or insertion
+ * logic as {@link $addChild}.
+ *
+ * @param newParent
+ * @param el
+ * @param idx
+ */
 export const $moveTo = (newParent, el, idx = -1) => {
     $remove(el);
     $addChild(newParent, el, idx);
 };
+/**
+ * Removes all content from given element.
+ *
+ * @param el
+ */
 export const $clear = (el) => ((el.innerHTML = ""), el);
 /**
  * Same as `el.innerText = body`, however if `body` is an

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/rdom",
-  "version": "0.9.20",
+  "version": "0.10.1",
   "description": "Lightweight, reactive, VDOM-less UI/DOM components with async lifecycle and @thi.ng/hiccup compatible",
   "type": "module",
   "module": "./index.js",
@@ -35,18 +35,18 @@
     "test": "testament test"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.5.0",
-    "@thi.ng/checks": "^3.3.3",
-    "@thi.ng/errors": "^2.2.4",
-    "@thi.ng/hiccup": "^4.2.24",
-    "@thi.ng/paths": "^5.1.23",
-    "@thi.ng/prefixes": "^2.1.13",
-    "@thi.ng/rstream": "^7.2.29",
-    "@thi.ng/strings": "^3.3.18"
+    "@thi.ng/api": "^8.5.1",
+    "@thi.ng/checks": "^3.3.4",
+    "@thi.ng/errors": "^2.2.5",
+    "@thi.ng/hiccup": "^4.2.25",
+    "@thi.ng/paths": "^5.1.24",
+    "@thi.ng/prefixes": "^2.1.14",
+    "@thi.ng/rstream": "^7.2.30",
+    "@thi.ng/strings": "^3.3.19"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.33.5",
-    "@thi.ng/testament": "^0.3.5",
+    "@thi.ng/testament": "^0.3.6",
     "rimraf": "^3.0.2",
     "tools": "^0.0.1",
     "typedoc": "^0.23.20",
@@ -140,5 +140,5 @@
     "status": "beta",
     "year": 2020
   },
-  "gitHead": "75ec32ff7f1b7b5e72e7a04ace24732cd5d6c774\n"
+  "gitHead": "5178ea1d7f4b2de86cf5101bdd73f6567518c0bd\n"
 }