docs(rdom): update $compile, $wrapEl, $wrapHtml docs (#456)

Author: postspectacular

packages/rdom/src/compile.ts

@@ -29,6 +29,15 @@ import { $wrapEl, $wrapText } from "./wrap.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 const $compile = (tree: any): IComponent =>

packages/rdom/src/wrap.ts

@@ -37,6 +37,25 @@ export const $wrapText = wrapper($text);
  * 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
@@ -47,6 +66,17 @@ 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.
  *
+ * @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 const $wrapEl = (el: Element): IComponent => ({