@thi.ng/rdom 1.1.10 → 1.1.12

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2024-03-01T15:22:50Z
+- **Last updated**: 2024-03-07T20:40:47Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.

package/compile.d.ts

@@ -20,6 +20,15 @@ import type { IComponent } from "./api.js";
  * target attribute. If used as element body, the reactive value will be wrapped
  * using a {@link $sub} `<span>` with the value as its reactive body.
  *
+ * **Important:** Use {@link $replace}, {@link $refresh} or {@link $switch} to
+ * wrap any reactive values/subscriptions which produce actual HTML
+ * elements/components/subtrees (in hiccup format). See docs for these functions
+ * for details & examples. Not using any of these wrappers will result in
+ * unexpected outcomes.
+ *
+ * Also see {@link $wrapText}, {@link $wrapHtml} or {@link $wrapEl} for DOM
+ * element related component wrappers.
+ *
  * @param tree -
  */
 export declare const $compile: (tree: any) => IComponent;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/rdom",
-  "version": "1.1.10",
+  "version": "1.1.12",
   "description": "Lightweight, reactive, VDOM-less UI/DOM components with async lifecycle and @thi.ng/hiccup compatible",
   "type": "module",
   "module": "./index.js",
@@ -33,17 +33,18 @@
     "doc:readme": "bun ../../tools/src/module-stats.ts && bun ../../tools/src/readme.ts",
     "pub": "yarn npm publish --access public",
     "pub:wip": "yarn npm publish --access public --no-git-tag-version",
-    "test": "bun test"
+    "test": "bun test",
+    "tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.9.27",
-    "@thi.ng/checks": "^3.5.1",
-    "@thi.ng/errors": "^2.4.19",
-    "@thi.ng/hiccup": "^5.1.18",
-    "@thi.ng/paths": "^5.1.70",
-    "@thi.ng/prefixes": "^2.3.11",
-    "@thi.ng/rstream": "^8.3.10",
-    "@thi.ng/strings": "^3.7.20"
+    "@thi.ng/api": "^8.9.28",
+    "@thi.ng/checks": "^3.5.2",
+    "@thi.ng/errors": "^2.4.20",
+    "@thi.ng/hiccup": "^5.1.19",
+    "@thi.ng/paths": "^5.1.71",
+    "@thi.ng/prefixes": "^2.3.12",
+    "@thi.ng/rstream": "^8.3.11",
+    "@thi.ng/strings": "^3.7.21"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.40.1",
@@ -142,5 +143,5 @@
     ],
     "year": 2020
   },
-  "gitHead": "df9e312af741d87e6b450afcfea6a6e381662b1e\n"
+  "gitHead": "a421058a65ba76608d94129ac29451bfedaf201c\n"
 }

package/wrap.d.ts

@@ -12,6 +12,25 @@ export declare const $wrapText: (tag: string, attribs?: any, body?: any) => IMou
  * Returns a component wrapper for a single DOM element whose HTML body can be
  * later updated/replaced via `.update()`, similarly to setting `.innerHTML`.
  *
+ * @remarks
+ * Setting `.innerHtml` considered dangerous — please use with caution or use
+ * {@link $wrapText} if the source of the HTML body given to `.update()` cannot
+ * be trusted!
+ *
+ * @example
+ * ```ts
+ * import { $compile, $wrapHtml } from "@thi.ng/rdom";
+ *
+ * // create pre-configured updatable element
+ * const title = $wrapHtml("h1", { style: { color: "red" } });
+ *
+ * // embed inside rdom tree
+ * $compile(["div", {}, title, "world..."]).mount(document.body);
+ *
+ * // update element body (only after element has been mounted!)
+ * title.update("<em>hello</em>");
+ * ```
+ *
  * @param tag - element name
  * @param attribs - element attribs
  * @param body - optional initial body
@@ -21,6 +40,17 @@ export declare const $wrapHtml: (tag: string, attribs?: any, body?: import("@thi
  * {@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.
  *
+ * @example
+ * ```ts
+ * import { $compile, $wrapEl } from "@thi.ng/rdom";
+ *
+ * const title = document.createElement("h1");
+ * title.innerText = "hello";
+ *
+ * // embed existing DOM element inside an rdom tree
+ * $compile(["div", {}, $wrapEl(title), "world..."]).mount(document.body);
+ * ```
+ *
  * @param el
  */
 export declare const $wrapEl: (el: Element) => IComponent;