@thi.ng/rdom 0.10.13 → 0.10.15

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2023-03-02T18:09:03Z
+- **Last updated**: 2023-03-09T13:01:59Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.

package/README.md

@@ -13,9 +13,11 @@ This project is part of the
   - [From hdom to rdom: Reactive UIs without virtual DOMs](#from-hdom-to-rdom-reactive-uis-without-virtual-doms)
   - [Targetted, isolated updates](#targetted-isolated-updates)
   - [Async updates, scheduling & life cycle methods](#async-updates-scheduling--life-cycle-methods)
+  - [@thi.ng/atom integration](#thingatom-integration)
+- [DOM creation & mutation](#dom-creation--mutation)
+- [Control structures](#control-structures)
+  - [Event handlers for reactive streams](#event-handlers-for-reactive-streams)
 - [Status](#status)
-    - [HIC SUNT DRACONES](#hic-sunt-dracones)
-    - [@thi.ng/atom integration](#thingatom-integration)
 - [Support packages](#support-packages)
 - [Related packages](#related-packages)
 - [Installation](#installation)
@@ -72,13 +74,13 @@ only that body/subtree in the target DOM will be impacted/updated directly...
 The package provides an interface
 [`IComponent`](https://docs.thi.ng/umbrella/rdom/interfaces/IComponent.html)
 (with a super simple life cycle API), a base component class
-[`Component`](https://docs.thi.ng/umbrella/rdom/classes/Component.html) for stubbing and a
-number of fundamental control constructs & component-wrappers for composing more
-complex components and to reduce boilerplate for various situations. Whilst
-targetting a standard JS DOM by default, each component can decide for itself
-what kind of target data structure (apart from a browser DOM) it manages. _rdom_
-components themselves have **no mandatory** knowledge of a browser DOM. As an
-example, similar to
+[`Component`](https://docs.thi.ng/umbrella/rdom/classes/Component.html) for
+stubbing and a number of fundamental control constructs & component-wrappers for
+composing more complex components and to reduce boilerplate for various
+situations. Whilst targetting a standard JS DOM by default, each component can
+decide for itself what kind of target data structure (apart from a browser DOM)
+it manages. _rdom_ components themselves have **no mandatory** knowledge of a
+browser DOM. As an example, similar to
 [@thi.ng/hdom-canvas](https://github.com/thi-ng/umbrella/tree/develop/packages/hiccup-canvas),
 the
 [@thi.ng/rdom-canvas](https://github.com/thi-ng/umbrella/tree/develop/packages/rdom-canvas)
@@ -91,7 +93,13 @@ draw calls.
 Since there's no central coordination in _rdom_ (neither explicitly nor
 implicitly), each component can (and does) update whenever its state value has
 changed. Likewise, components are free to directly manipulate the DOM through
-other means, as hinted at earlier. Various _rdom_ control constructs are dispatching component updates via a central scheduler. By default this is only a dummy implementation which processes tasks immediately. However, as usual _rdom_ only relies on the [`IScheduler`](https://docs.thi.ng/umbrella/rdom/interfaces/IScheduler.html) interface and so supports other implementations, like [`RAFScheduler`](https://docs.thi.ng/umbrella/rdom/classes/RAFScheduler.html).
+other means, as hinted at earlier. Various _rdom_ control constructs are
+dispatching component updates via a central scheduler. By default this is only a
+dummy implementation which processes tasks immediately. However, as usual _rdom_
+only relies on the
+[`IScheduler`](https://docs.thi.ng/umbrella/rdom/interfaces/IScheduler.html)
+interface and so supports other implementations, like
+[`RAFScheduler`](https://docs.thi.ng/umbrella/rdom/classes/RAFScheduler.html).
 
 The [`IComponent`](https://docs.thi.ng/umbrella/rdom/interfaces/icomponent.html)
 interface is at the heart of _rdom_. It defines three lifecycle methods to:
@@ -110,24 +118,11 @@ please consult the docs for these packages to learn more about the available
 constructs and patterns. Most of _rdom_ only deals with either subscribing to
 reactive values and/or wrapping/transforming existing subscriptions, either
 explicitly using the provided control components (e.g.
-[`$sub()`](https://docs.thi.ng/umbrella/rdom/modules.html#_sub)) or using
-[`$compile()`](https://docs.thi.ng/umbrella/rdom/modules.html#_compile) to
+[`$sub()`](https://docs.thi.ng/umbrella/rdom/functions/_sub.html)) or using
+[`$compile()`](https://docs.thi.ng/umbrella/rdom/functions/_compile.html) to
 auto-wrap such values embedded in an hiccup tree.
 
-## Status
-
-**BETA** - possibly breaking changes forthcoming
-
-[Search or submit any issues for this package](https://github.com/thi-ng/umbrella/issues?q=%5Brdom%5D+in%3Atitle)
-
-#### HIC SUNT DRACONES
-
-This is still a young project. Even though most of the overall approach,
-component lifecycle and API are fairly stable by now (after ~75 commits) and
-used in production, so far there's only brief documentation and only few public
-examples. This is being worked & improved on...
-
-#### @thi.ng/atom integration
+### @thi.ng/atom integration
 
 For the sake of deduplication of functionality and to keep the number of
 dependencies to a minimum, direct
@@ -136,8 +131,118 @@ integration has been removed in favor of using relevant
 [@thi.ng/rstream](https://github.com/thi-ng/umbrella/tree/develop/packages/rstream)
 constructs, which can be used as lightweight adapters, i.e.:
 
-- [`fromAtom()`](https://docs.thi.ng/umbrella/rstream/modules.html#fromAtom)
-- [`fromView()`](https://docs.thi.ng/umbrella/rstream/modules.html#fromView)
+- [`fromAtom()`](https://docs.thi.ng/umbrella/rstream/functions/fromAtom.html)
+- [`fromObject()`](https://docs.thi.ng/umbrella/rstream/functions/fromObject.html)
+- [`fromView()`](https://docs.thi.ng/umbrella/rstream/functions/fromView.html)
+
+## DOM creation & mutation
+
+The package provides many functions to simplify the creation of individual or
+entire trees of DOM elements and to manipulate them at a later time. The single
+most important function of the package is
+[$compile](https://docs.thi.ng/umbrella/rdom/functions/_compile.html). It acts
+as a facade for many of these other functions and creates an actual DOM from a
+given hiccup component tree. It also automatically wraps any reactive values
+contained therein.
+
+**All of these functions are also usable, even if you don't intend to use any
+other package features!**
+
+- [$addChild](https://docs.thi.ng/umbrella/rdom/functions/_addChild.html)
+- [$attribs](https://docs.thi.ng/umbrella/rdom/functions/_attribs.html)
+- [$clear](https://docs.thi.ng/umbrella/rdom/functions/_clear.html)
+- [$comment](https://docs.thi.ng/umbrella/rdom/functions/_comment.html)
+- [$el](https://docs.thi.ng/umbrella/rdom/functions/_el.html)
+- [$html](https://docs.thi.ng/umbrella/rdom/functions/_html.html)
+- [$moveTo](https://docs.thi.ng/umbrella/rdom/functions/_moveTo.html)
+- [$remove](https://docs.thi.ng/umbrella/rdom/functions/_remove.html)
+- [$style](https://docs.thi.ng/umbrella/rdom/functions/_style.html)
+- [$text](https://docs.thi.ng/umbrella/rdom/functions/_text.html)
+- [$tree](https://docs.thi.ng/umbrella/rdom/functions/_tree.html)
+
+## Control structures
+
+For more advanced usage, rdom provides a range of control structures (container
+components) to simplify the handling of reactive states and reduce boilerplate
+for the implementation of common UI structures (e.g. item lists of any kind).
+
+The following links lead to the documentation of these wrappers, incl. small
+code examples:
+
+- [$klist](https://docs.thi.ng/umbrella/rdom/functions/_klist.html)
+- [$list](https://docs.thi.ng/umbrella/rdom/functions/_list.html)
+- [$object](https://docs.thi.ng/umbrella/rdom/functions/_object-1.html)
+- [$promise](https://docs.thi.ng/umbrella/rdom/functions/_promise-1.html)
+- [$refresh](https://docs.thi.ng/umbrella/rdom/functions/_refresh.html)
+- [$replace](https://docs.thi.ng/umbrella/rdom/functions/_replace.html)
+- [$sub](https://docs.thi.ng/umbrella/rdom/functions/_sub-1.html)
+- [$subObject](https://docs.thi.ng/umbrella/rdom/functions/_subObject.html)
+- [$switch](https://docs.thi.ng/umbrella/rdom/functions/_switch.html)
+- [$wrapHtml](https://docs.thi.ng/umbrella/rdom/functions/_wrapHtml.html)
+- [$wrapText](https://docs.thi.ng/umbrella/rdom/functions/_wrapText.html)
+
+### Event handlers for reactive streams
+
+Reactive rdom component are based on
+[@thi.ng/rstream](https://github.com/thi-ng/umbrella/tree/develop/packages/rstream)
+subscriptions. In order to create a feedback loop between those reactive state
+values and their subscribed UI components, input event handlers need to feed any
+user changes back to those reactive state(s). To reduce boilerplate for these
+tasks, the following higher order input event handlers are provided:
+
+- [$input](https://docs.thi.ng/umbrella/rdom/functions/_input.html)
+- [$inputCheckbox](https://docs.thi.ng/umbrella/rdom/functions/_inputCheckbox.html)
+- [$inputFile](https://docs.thi.ng/umbrella/rdom/functions/_inputFile.html)
+- [$inputFiles](https://docs.thi.ng/umbrella/rdom/functions/_inputFiles.html)
+- [$inputNum](https://docs.thi.ng/umbrella/rdom/functions/_inputNum.html)
+- [$inputTrigger](https://docs.thi.ng/umbrella/rdom/functions/_inputTrigger.html)
+
+```ts
+import { $compile, $input } from "@thi.ng/rdom";
+import { reactive, trace } from "@thi.ng/rstream";
+
+// reactive value/state w/ transformation
+const name = reactive("").map((x) => x.toUpperCase());
+
+// reactive text field for `name`
+$compile(["input", {
+    type: "text",
+    // any value changes are fed back into `name`, which in return
+    // triggers an update of this (and any other) subscription
+    oninput: $input(name),
+    value: name
+}]).mount(document.body);
+
+// addtional subscription for debug console output
+name.subscribe(trace("name:"));
+```
+
+Click counter:
+
+```ts
+import { $compile, $inputTrigger } from "@thi.ng/rdom";
+import { reactive } from "@thi.ng/rstream";
+import { count, scan } from "@thi.ng/transducers";
+
+// reactive value/stream setup
+const clicks = reactive(true);
+
+// button component with reactive label showing click count
+$compile([
+    "button",
+    // $inputTrigger merely emits `true` onto the given reactive stream
+    { onclick: $inputTrigger(clicks) },
+    "clicks: ",
+    // using transducers to transform click stream into a counter
+    clicks.transform(scan(count(-1))),
+]).mount(document.body);
+```
+
+## Status
+
+**STABLE** - used in production
+
+[Search or submit any issues for this package](https://github.com/thi-ng/umbrella/issues?q=%5Brdom%5D+in%3Atitle)
 
 ## Support packages
 
@@ -216,9 +321,9 @@ A selection:
 
 TODO
 
-Currently, documentation only exists in the form of small examples and
-various doc strings (incomplete). I'm working to alleviate this
-situation ASAP... In that respect, PRs are welcome as well!
+Currently, documentation only exists in the form of small examples and various
+doc strings (incomplete). I'm working to alleviate this situation ASAP... In
+that respect, PRs are welcome as well!
 
 ### Basic usage
 

package/dom.d.ts

@@ -31,12 +31,17 @@ export declare const $tree: (tree: any, parent: Element, idx?: NumOrElement) =>
  * Create a single DOM element and optionally attaches it to `parent`.
  *
  * @remarks
+ * If `tag` is a namespaced tagname (e.g. `prefix:tag`), the element will be
+ * created via `document.createElementNS()` and the prefix will be resolved via
+ * known aliases registered by {@link registerPrefix}. SVG element names do not
+ * need to be prefixed and are recognized automatically.
+ *
  * Supports Emmet-style tag names in this form: `tag#id.class1.class2`.
- * `attribs` is a plain object of element attributes. See
- * {@link $attribs} for further details.
+ * `attribs` is a plain object of element attributes. See {@link $attribs} for
+ * further details.
  *
- * If `parent` is given, but no `idx` arg, the new element will be
- * appended as child.
+ * If `parent` is given, but no `idx` arg, the new element will be appended as
+ * child.
  *
  * @param tag -
  * @param attribs -
@@ -157,8 +162,8 @@ export declare const $attribs: (el: Element, attribs: any) => void;
  */
 export declare const $style: (el: Element, rules: string | any) => void;
 /**
- * Registers an XML namespace prefix and its URL for later use, e.g. to
- * define namespaced elements/attributes.
+ * Registers an XML namespace prefix and its URL for later use, e.g. to define
+ * namespaced elements/attributes via {@link $el}, {@link $tree}.
  *
  * @param prefix -
  * @param url -

package/dom.js

@@ -93,12 +93,17 @@ const $treeIter = (tree, parent) => {
  * Create a single DOM element and optionally attaches it to `parent`.
  *
  * @remarks
+ * If `tag` is a namespaced tagname (e.g. `prefix:tag`), the element will be
+ * created via `document.createElementNS()` and the prefix will be resolved via
+ * known aliases registered by {@link registerPrefix}. SVG element names do not
+ * need to be prefixed and are recognized automatically.
+ *
  * Supports Emmet-style tag names in this form: `tag#id.class1.class2`.
- * `attribs` is a plain object of element attributes. See
- * {@link $attribs} for further details.
+ * `attribs` is a plain object of element attributes. See {@link $attribs} for
+ * further details.
  *
- * If `parent` is given, but no `idx` arg, the new element will be
- * appended as child.
+ * If `parent` is given, but no `idx` arg, the new element will be appended as
+ * child.
  *
  * @param tag -
  * @param attribs -
@@ -394,8 +399,8 @@ const PREFIXES = {
     xmlns: XML_XMLNS,
 };
 /**
- * Registers an XML namespace prefix and its URL for later use, e.g. to
- * define namespaced elements/attributes.
+ * Registers an XML namespace prefix and its URL for later use, e.g. to define
+ * namespaced elements/attributes via {@link $el}, {@link $tree}.
  *
  * @param prefix -
  * @param url -

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/rdom",
-  "version": "0.10.13",
+  "version": "0.10.15",
   "description": "Lightweight, reactive, VDOM-less UI/DOM components with async lifecycle and @thi.ng/hiccup compatible",
   "type": "module",
   "module": "./index.js",
@@ -38,15 +38,15 @@
     "@thi.ng/api": "^8.7.3",
     "@thi.ng/checks": "^3.3.9",
     "@thi.ng/errors": "^2.2.12",
-    "@thi.ng/hiccup": "^4.2.35",
+    "@thi.ng/hiccup": "^4.2.36",
     "@thi.ng/paths": "^5.1.32",
     "@thi.ng/prefixes": "^2.1.19",
-    "@thi.ng/rstream": "^7.2.42",
+    "@thi.ng/rstream": "^7.2.43",
     "@thi.ng/strings": "^3.4.1"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.34.2",
-    "@thi.ng/testament": "^0.3.11",
+    "@thi.ng/testament": "^0.3.12",
     "rimraf": "^4.1.2",
     "tools": "^0.0.1",
     "typedoc": "^0.23.24",
@@ -137,8 +137,7 @@
       "hiccup-svg",
       "transducers"
     ],
-    "status": "beta",
     "year": 2020
   },
-  "gitHead": "8342900eedc77bb09edb8c544804578b71f8acc6\n"
+  "gitHead": "8ab2cbfe2f59b7ef672b6e1cf2a43368f8437ddf\n"
 }