@jsenv/navi 0.29.94 → 0.29.95

package/docs/control_object.md

@@ -177,18 +177,47 @@ it. It matters most inside a picker's popup, where nothing else would bring the
 value back down: a picker's value IS what the control in its popup holds, so the
 façade never echoes it back.
 
-A group with an `aggregateChildStates` of its own is outside all of this: what
-it returns is taken as the truth, `undefined` included. That is the one way such
-a group says **"I have nothing to say yet"** — return `undefined` while the
-children it needs are missing, and navi leaves the value alone instead of
-publishing an empty shape upward. A group written to always return its keys
-(`{ mode: undefined, levels: [] }`) is claiming an answer nobody gave, and that
-claim overwrites the row above it the moment the popup opens.
-
-Together they are what makes the two-hop case work — the form fills the row, the
-row fills the control in its popup — whatever order the pieces turn up in. Get
-one of them wrong and the symptom is always the same: a value that was there
-before the popup opened, and empty after.
+Three things follow, and all three were paid for twice before being written
+here:
+
+- **the group's value has to be the view that carries the MOST.** Four seats say
+  who plays AND who sits where; a list of who plays says half of that. Make the
+  seating the value and the list is derived from it (`value.filter(Boolean)`);
+  make the list the value and every gesture on a seat has to be guessed at. The
+  rule to apply: between two views of one answer, the value is the one the other
+  can be computed from;
+- **the Map must name EVERY child**, the derived view included. A child the Map
+  does not name is left where it is — which reads as "the list never fills";
+- **a gesture that moves two children writes the GROUP's value, not the two
+  children.** Dragging somebody from one seat to another is one intention and
+  two writes; written one after the other, the group re-places between them, the
+  rule sees a free seat and puts the person back where they were. Written as one
+  change of the group's value there is nothing in between. (Wrapping the two
+  writes in a signal `batch()` does NOT do it: the group aggregates on each
+  child's change, not on the render that follows.)
+
+```jsx
+// the value IS the seating; the list is a view of it
+<ControlGroup
+  aggregateChildStates={(children) => {…}}   // seats, minus who the list dropped, plus who it added
+  distributeChildStates={(slots, children) =>
+    new Map([
+      ...seats.map((seat, i) => [seat, slots[i]]),
+      [list, slots.filter(Boolean)],
+    ])
+  }
+>
+```
+
+```js
+// and a drag is one write
+const moveTo = (from, to) => {
+  const slots = [...rowSignal.value];
+  slots[to] = slots[from];
+  slots[from] = undefined;
+  rowSignal.value = slots;
+};
+```
 
 ## One line, one key
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/navi",
-  "version": "0.29.94",
+  "version": "0.29.95",
   "type": "module",
   "description": "Library of components including navigation to create frontend applications",
   "repository": {