@thi.ng/rdom 1.1.10 → 1.1.11

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2024-03-01T15:22:50Z
+- **Last updated**: 2024-03-06T08:50:42Z
 - **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.11",
   "description": "Lightweight, reactive, VDOM-less UI/DOM components with async lifecycle and @thi.ng/hiccup compatible",
   "type": "module",
   "module": "./index.js",
@@ -142,5 +142,5 @@
     ],
     "year": 2020
   },
-  "gitHead": "df9e312af741d87e6b450afcfea6a6e381662b1e\n"
+  "gitHead": "f6bb0e172c5dcb574b961f5155a50040d5569685\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;