Skip to content

Commit

Permalink
docs(rdom): update $compile, $wrapEl, $wrapHtml docs (#456)
Browse files Browse the repository at this point in the history
  • Loading branch information
postspectacular committed Mar 5, 2024
1 parent 6994a63 commit 1d70c04
Show file tree
Hide file tree
Showing 2 changed files with 39 additions and 0 deletions.
9 changes: 9 additions & 0 deletions packages/rdom/src/compile.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 =>
Expand Down
30 changes: 30 additions & 0 deletions packages/rdom/src/wrap.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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 => ({
Expand Down

0 comments on commit 1d70c04

Please sign in to comment.