@thi.ng/rdom 0.10.6 → 0.10.9

package/CHANGELOG.md

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

package/README.md

@@ -22,6 +22,8 @@ This project is part of the
 - [Dependencies](#dependencies)
 - [Usage examples](#usage-examples)
 - [API](#api)
+  - [Basic usage](#basic-usage)
+  - [Lists](#lists)
 - [Authors](#authors)
 - [License](#license)
 
@@ -218,6 +220,8 @@ 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
+
 ```ts
 import { $compile } from "@thi.ng/rdom";
 import { reactive } from "@thi.ng/rstream";
@@ -242,7 +246,7 @@ $compile([
     "div",
     {},
     // transformed color as title (aka derived view)
-    ["h1", {}, bg.transform(map((col) => `Hello, ${col}!`))],
+    ["h1", {}, bg.map((col) => `Hello, ${col}!`)],
     [
         // tag with Emmet-style ID & classes
         "button#foo.w4.pa3.bn",
@@ -257,6 +261,51 @@ $compile([
 ]).mount(document.body);
 ```
 
+### Lists
+
+See [`$list`](https://docs.thi.ng/umbrella/rdom/functions/_list.html) and
+[`$klist`](https://docs.thi.ng/umbrella/rdom/functions/_klist.html) docs for
+further information...
+
+```ts
+import { $klist } from "@thi.ng/rdom";
+import { reactive } from "@thi.ng/rstream";
+
+const items = reactive([
+    { id: "a", val: 1 },
+    { id: "b", val: 2 },
+    { id: "c", val: 3 },
+]);
+
+$klist(
+    // reactive data source (any rstream subscribable)
+    items,
+    // outer list element & attribs
+    "ul",
+    { class: "list red" },
+    // list item component constructor
+    (x) => ["li", {}, x.id, ` (${x.val})`],
+    // key function (includes)
+    (x) => `${x.id}-${x.val}`
+).mount(document.body);
+
+// update list:
+// - item a will be removed
+// - item b is unchanged
+// - item d will be newly inserted
+// - item c will be updated (due to new value)
+setTimeout(
+    () => {
+        items.next([
+            { id: "b", val: 2 },
+            { id: "d", val: 4 },
+            { id: "c", val: 30 },
+        ]);
+    },
+    1000
+);
+```
+
 ## Authors
 
 - [Karsten Schmidt](https://thi.ng)

package/klist.d.ts

@@ -8,32 +8,48 @@ interface KListItem {
 }
 /**
  * Similar to {@link $list}, however additionally uses keying to establish list
- * item identities and uses them in a more complex diffing algorithm to avoid
- * re-initialization of list items if they've been re-ordered or changed
- * positions due to removal/insertion of other items in the list.
+ * item identities and uses these keys (and *only* these!) in a more complex
+ * diffing algorithm to avoid re-initialization of list items if they've been
+ * re-ordered or changed positions due to removal/insertion of other items in
+ * the list.
  *
  * @remarks
  * The given `keyFn` is used to obtain a *unique* key value for each list item
- * obtained from the reactive arrays obtained from `src`.
+ * obtained from the reactive arrays obtained from `src`. Like a hash, the key
+ * value MUST represent an item's *current* value such that if the value
+ * changes, so does the key.
  *
  * @example
  * ```ts
- * const items = reactive([{id: "a"}, {id: "b"}, {id: "c"}]);
+ * const items = reactive([{id: "a", val: 1}, {id: "b", val: 2}, {id: "c", val: 3}]);
  *
  * $klist(
- *   // data source (rstream subsribable)
+ *   // data source (any rstream subscribable)
  *   items,
  *   // outer list element & attribs
  *   "ul",
  *   { class: "list red" },
  *   // list item component constructor
- *   (x) => ["li", {}, x.id],
+ *   (x) => ["li", {}, x.id, ` (${x.val})`],
  *   // key function
- *   (x) => x.id
+ *   (x) => `${x.id}-${x.val}`
  * ).mount(document.body);
  *
- * // update list
- * items.next([{id: "b"}, {id: "d"}, {id: "c"}]);
+ * // update list:
+ * // - item a will be removed
+ * // - item b is unchanged
+ * // - item d will be newly inserted
+ * // - item c will be updated (due to new value)
+ * setTimeout(
+ *   () => {
+ *     items.next([
+ *       { id: "b", val: 2 },
+ *       { id: "d", val: 4 },
+ *       { id: "c", val: 30 },
+ *     ]);
+ *   },
+ *   1000
+ * );
  * ```
  *
  * @param src -

package/klist.js

@@ -4,32 +4,48 @@ import { $moveTo } from "./dom.js";
 import { $sub } from "./sub.js";
 /**
  * Similar to {@link $list}, however additionally uses keying to establish list
- * item identities and uses them in a more complex diffing algorithm to avoid
- * re-initialization of list items if they've been re-ordered or changed
- * positions due to removal/insertion of other items in the list.
+ * item identities and uses these keys (and *only* these!) in a more complex
+ * diffing algorithm to avoid re-initialization of list items if they've been
+ * re-ordered or changed positions due to removal/insertion of other items in
+ * the list.
  *
  * @remarks
  * The given `keyFn` is used to obtain a *unique* key value for each list item
- * obtained from the reactive arrays obtained from `src`.
+ * obtained from the reactive arrays obtained from `src`. Like a hash, the key
+ * value MUST represent an item's *current* value such that if the value
+ * changes, so does the key.
  *
  * @example
  * ```ts
- * const items = reactive([{id: "a"}, {id: "b"}, {id: "c"}]);
+ * const items = reactive([{id: "a", val: 1}, {id: "b", val: 2}, {id: "c", val: 3}]);
  *
  * $klist(
- *   // data source (rstream subsribable)
+ *   // data source (any rstream subscribable)
  *   items,
  *   // outer list element & attribs
  *   "ul",
  *   { class: "list red" },
  *   // list item component constructor
- *   (x) => ["li", {}, x.id],
+ *   (x) => ["li", {}, x.id, ` (${x.val})`],
  *   // key function
- *   (x) => x.id
+ *   (x) => `${x.id}-${x.val}`
  * ).mount(document.body);
  *
- * // update list
- * items.next([{id: "b"}, {id: "d"}, {id: "c"}]);
+ * // update list:
+ * // - item a will be removed
+ * // - item b is unchanged
+ * // - item d will be newly inserted
+ * // - item c will be updated (due to new value)
+ * setTimeout(
+ *   () => {
+ *     items.next([
+ *       { id: "b", val: 2 },
+ *       { id: "d", val: 4 },
+ *       { id: "c", val: 30 },
+ *     ]);
+ *   },
+ *   1000
+ * );
  * ```
  *
  * @param src -

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/rdom",
-  "version": "0.10.6",
+  "version": "0.10.9",
   "description": "Lightweight, reactive, VDOM-less UI/DOM components with async lifecycle and @thi.ng/hiccup compatible",
   "type": "module",
   "module": "./index.js",
@@ -35,22 +35,22 @@
     "test": "testament test"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.6.3",
-    "@thi.ng/checks": "^3.3.7",
-    "@thi.ng/errors": "^2.2.8",
-    "@thi.ng/hiccup": "^4.2.29",
-    "@thi.ng/paths": "^5.1.28",
-    "@thi.ng/prefixes": "^2.1.17",
-    "@thi.ng/rstream": "^7.2.35",
-    "@thi.ng/strings": "^3.3.23"
+    "@thi.ng/api": "^8.7.2",
+    "@thi.ng/checks": "^3.3.9",
+    "@thi.ng/errors": "^2.2.11",
+    "@thi.ng/hiccup": "^4.2.32",
+    "@thi.ng/paths": "^5.1.31",
+    "@thi.ng/prefixes": "^2.1.19",
+    "@thi.ng/rstream": "^7.2.38",
+    "@thi.ng/strings": "^3.3.26"
   },
   "devDependencies": {
-    "@microsoft/api-extractor": "^7.33.7",
-    "@thi.ng/testament": "^0.3.9",
-    "rimraf": "^3.0.2",
+    "@microsoft/api-extractor": "^7.34.2",
+    "@thi.ng/testament": "^0.3.11",
+    "rimraf": "^4.1.2",
     "tools": "^0.0.1",
-    "typedoc": "^0.23.22",
-    "typescript": "^4.9.4"
+    "typedoc": "^0.23.24",
+    "typescript": "^4.9.5"
   },
   "keywords": [
     "async",
@@ -140,5 +140,5 @@
     "status": "beta",
     "year": 2020
   },
-  "gitHead": "3f0b3e2a7c82aefc7e46fb4338369836b5e1b8cf\n"
+  "gitHead": "cafa4ecea90fb681949dc3885a5bd6ddefa38b51\n"
 }