@thi.ng/rdom 0.12.22 → 0.13.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2023-11-09T10:28:19Z
+- **Last updated**: 2023-11-12T16:43:31Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,14 @@ 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.13.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/rdom@0.13.0) (2023-11-12)
+
+#### 🚀 Features
+
+- add $wrapEl() DOM element component wrapper ([298e9a1](https://github.com/thi-ng/umbrella/commit/298e9a1))
+- update $compile() to support existing DOM elements ([859521a](https://github.com/thi-ng/umbrella/commit/859521a))
+- update $attribs() to return element ([1f82021](https://github.com/thi-ng/umbrella/commit/1f82021))
+
 ### [0.12.21](https://github.com/thi-ng/umbrella/tree/@thi.ng/rdom@0.12.21) (2023-11-09)
 
 #### ♻️ Refactoring

package/README.md

@@ -278,7 +278,7 @@ For Node.js REPL:
 const rdom = await import("@thi.ng/rdom");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 4.07 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 4.12 KB
 
 ## Dependencies
 
@@ -309,8 +309,10 @@ directory are using this package:
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/lispy-repl.png" width="240"/>          | Browser REPL for a Lispy S-expression based mini language                                               | [Demo](https://demo.thi.ng/umbrella/lispy-repl/)          | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/lispy-repl)          |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/mastodon-feed.jpg" width="240"/>       | Mastodon API feed reader with support for different media types, fullscreen media modal, HTML rewriting | [Demo](https://demo.thi.ng/umbrella/mastodon-feed/)       | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/mastodon-feed)       |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/parse-playground.png" width="240"/>    | Parser grammar livecoding editor/playground & codegen                                                   | [Demo](https://demo.thi.ng/umbrella/parse-playground/)    | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/parse-playground)    |
+| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/pixel-colormatrix.jpg" width="240"/>   | Matrix-based image color adjustments                                                                    | [Demo](https://demo.thi.ng/umbrella/pixel-colormatrix/)   | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/pixel-colormatrix)   |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/pixel-gradients.jpg" width="240"/>     | Randomized 4-point 2D color gradient image generator                                                    | [Demo](https://demo.thi.ng/umbrella/pixel-gradients/)     | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/pixel-gradients)     |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/pixel-sorting.png" width="240"/>       | Interactive pixel sorting tool using thi.ng/color & thi.ng/pixel                                        | [Demo](https://demo.thi.ng/umbrella/pixel-sorting/)       | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/pixel-sorting)       |
+| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/pixel-waveform.jpg" width="240"/>      | RGB waveform image analysis                                                                             | [Demo](https://demo.thi.ng/umbrella/pixel-waveform/)      | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/pixel-waveform)      |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/pointfree-geom.jpg" width="240"/>      | Live coding playground for 2D geometry generation using @thi.ng/pointfree-lang                          | [Demo](https://demo.thi.ng/umbrella/pointfree-geom/)      | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/pointfree-geom)      |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/poly-subdiv.jpg" width="240"/>         | Animated, iterative polygon subdivisions & visualization                                                | [Demo](https://demo.thi.ng/umbrella/poly-subdiv/)         | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/poly-subdiv)         |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/procedural-text.jpg" width="240"/>     | Procedural stochastic text generation via custom DSL, parse grammar & AST transformation                | [Demo](https://demo.thi.ng/umbrella/procedural-text/)     | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/procedural-text)     |

package/checks.d.ts

@@ -11,9 +11,15 @@ import type { IComponent } from "./api.js";
  */
 export declare const isComment: (tree: any[]) => boolean;
 /**
- * Returns true, if given value has a {@link IComponent.mount} function.
+ * Returns true if given value has a {@link IComponent.mount} function.
  *
  * @param x
  */
 export declare const isComponent: (x: any) => x is IComponent<any>;
+/**
+ * Returns true if given value is a DOM element.
+ *
+ * @param x
+ */
+export declare const isElement: (x: any) => x is Element;
 //# sourceMappingURL=checks.d.ts.map

package/checks.js

@@ -12,8 +12,14 @@ import { COMMENT } from "@thi.ng/hiccup/api";
  */
 export const isComment = (tree) => tree[0] === COMMENT;
 /**
- * Returns true, if given value has a {@link IComponent.mount} function.
+ * Returns true if given value has a {@link IComponent.mount} function.
  *
  * @param x
  */
 export const isComponent = (x) => implementsFunction(x, "mount");
+/**
+ * Returns true if given value is a DOM element.
+ *
+ * @param x
+ */
+export const isElement = (x) => x instanceof Element;

package/compile.d.ts

@@ -4,10 +4,11 @@ import type { IComponent } from "./api.js";
  * state values into a single, nested {@link IComponent}.
  *
  * @remarks
- * Supported formats:
+ * Supported formats/values:
  *
  * - hiccup component trees, i.e. `["tag#id.class", attribs, [...]]`
  * - {@link IComponent} instances
+ * - pre-existing DOM elements
  * - [`ISubscribable`](https://docs.thi.ng/umbrella/rstream/interfaces/ISubscribable.html)
  *   instances
  * - [`IDeref`](https://docs.thi.ng/umbrella/api/interfaces/IDeref.html)

package/compile.js

@@ -1,20 +1,21 @@
 import { isArray } from "@thi.ng/checks/is-array";
 import { isPlainObject } from "@thi.ng/checks/is-plain-object";
 import { isSubscribable } from "@thi.ng/rstream/checks";
-import { isComponent } from "./checks.js";
+import { isComponent, isElement } from "./checks.js";
 import { $el, $remove, $tree } from "./dom.js";
 import { SCHEDULER } from "./scheduler.js";
-import { $sub, $SubA } from "./sub.js";
-import { $wrapText } from "./wrap.js";
+import { $SubA, $sub } from "./sub.js";
+import { $wrapEl, $wrapText } from "./wrap.js";
 /**
  * Compiles a tree of components given in any supported format incl. reactive
  * state values into a single, nested {@link IComponent}.
  *
  * @remarks
- * Supported formats:
+ * Supported formats/values:
  *
  * - hiccup component trees, i.e. `["tag#id.class", attribs, [...]]`
  * - {@link IComponent} instances
+ * - pre-existing DOM elements
  * - [`ISubscribable`](https://docs.thi.ng/umbrella/rstream/interfaces/ISubscribable.html)
  *   instances
  * - [`IDeref`](https://docs.thi.ng/umbrella/api/interfaces/IDeref.html)
@@ -36,7 +37,9 @@ export const $compile = (tree) => isArray(tree)
         ? tree
         : isSubscribable(tree)
             ? $sub(tree, "span")
-            : $wrapText("span", null, tree);
+            : tree instanceof Element
+                ? $wrapEl(tree)
+                : $wrapText("span", null, tree);
 const walk = (f, x, path = []) => {
     if (isPlainObject(x)) {
         for (const k in x) {
@@ -58,7 +61,7 @@ const isComplexComponent = (x) => {
                 return true;
         }
     }
-    return isSubscribable(x) || isComponent(x);
+    return isSubscribable(x) || isComponent(x) || isElement(x);
 };
 const complexComponent = (tree) => ({
     async mount(parent, index = -1) {

package/dom.d.ts

@@ -145,7 +145,7 @@ export declare const $html: (el: HTMLElement | SVGElement, body: MaybeDeref<stri
  * @param el -
  * @param attribs -
  */
-export declare const $attribs: (el: Element, attribs: any) => void;
+export declare const $attribs: (el: Element, attribs: any) => Element;
 /**
  * Takes an object (or string) of CSS properties, compiles them into a single
  * CSS string and sets it as `style` attribute on the given element.

package/dom.js

@@ -253,6 +253,7 @@ export const $attribs = (el, attribs) => {
     for (let id in attribs) {
         setAttrib(el, id, attribs[id], attribs);
     }
+    return el;
 };
 const setAttrib = (el, id, val, attribs) => {
     implementsFunction(val, "deref") && (val = val.deref());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/rdom",
-  "version": "0.12.22",
+  "version": "0.13.0",
   "description": "Lightweight, reactive, VDOM-less UI/DOM components with async lifecycle and @thi.ng/hiccup compatible",
   "type": "module",
   "module": "./index.js",
@@ -40,7 +40,7 @@
     "@thi.ng/hiccup": "^5.0.7",
     "@thi.ng/paths": "^5.1.49",
     "@thi.ng/prefixes": "^2.2.4",
-    "@thi.ng/rstream": "^8.2.9",
+    "@thi.ng/rstream": "^8.2.10",
     "@thi.ng/strings": "^3.6.6"
   },
   "devDependencies": {
@@ -141,5 +141,5 @@
     ],
     "year": 2020
   },
-  "gitHead": "669a3151e4302480244fe3e60eff5e732ea5b7a7\n"
+  "gitHead": "2be4c38c9680da929339bd164acfb69ebb1fd3d0\n"
 }

package/wrap.d.ts

@@ -1,4 +1,4 @@
-import type { IMountWithState } from "./api.js";
+import type { IComponent, IMountWithState } from "./api.js";
 /**
  * Returns a component wrapper for a single DOM element whose TEXT body can be
  * later updated/replaced via `.update()`, similarly to setting `.innerText`.
@@ -17,4 +17,11 @@ export declare const $wrapText: (tag: string, attribs?: any, body?: any) => IMou
  * @param body - optional initial body
  */
 export declare const $wrapHtml: (tag: string, attribs?: any, body?: import("@thi.ng/api").MaybeDeref<string> | undefined) => IMountWithState<import("@thi.ng/api").MaybeDeref<string>>;
+/**
+ * {@link IComponent} wrapper for an existing DOM element. When mounted, the
+ * given element will be (re)attached to the parent node provided at that time.
+ *
+ * @param el
+ */
+export declare const $wrapEl: (el: Element) => IComponent;
 //# sourceMappingURL=wrap.d.ts.map

package/wrap.js

@@ -1,4 +1,4 @@
-import { $el, $html, $remove, $text } from "./dom.js";
+import { $addChild, $el, $html, $remove, $text } from "./dom.js";
 import { SCHEDULER } from "./scheduler.js";
 const wrapper = (update) => (tag, attribs, body) => ({
     el: undefined,
@@ -33,3 +33,20 @@ export const $wrapText = wrapper($text);
  * @param body - optional initial body
  */
 export const $wrapHtml = wrapper($html);
+/**
+ * {@link IComponent} wrapper for an existing DOM element. When mounted, the
+ * given element will be (re)attached to the parent node provided at that time.
+ *
+ * @param el
+ */
+export const $wrapEl = (el) => ({
+    async mount(parent, idx) {
+        $addChild(parent, el, idx);
+        return (this.el = el);
+    },
+    async unmount() {
+        $remove(this.el);
+        this.el = undefined;
+    },
+    update() { },
+});