@thi.ng/rdom 0.10.7 → 0.10.9

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2023-02-05T14:42:21Z
+- **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/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.7",
+  "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,18 +35,18 @@
     "test": "testament test"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.7.0",
-    "@thi.ng/checks": "^3.3.8",
-    "@thi.ng/errors": "^2.2.9",
-    "@thi.ng/hiccup": "^4.2.30",
-    "@thi.ng/paths": "^5.1.29",
-    "@thi.ng/prefixes": "^2.1.18",
-    "@thi.ng/rstream": "^7.2.36",
-    "@thi.ng/strings": "^3.3.24"
+    "@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.34.2",
-    "@thi.ng/testament": "^0.3.10",
+    "@thi.ng/testament": "^0.3.11",
     "rimraf": "^4.1.2",
     "tools": "^0.0.1",
     "typedoc": "^0.23.24",
@@ -140,5 +140,5 @@
     "status": "beta",
     "year": 2020
   },
-  "gitHead": "50ba9c87676fac60c46d2bc0e4d2c7711a374a68\n"
+  "gitHead": "cafa4ecea90fb681949dc3885a5bd6ddefa38b51\n"
 }