@jsenv/navi 0.29.93 → 0.29.95

package/docs/AI_INSTRUCTIONS.md

@@ -146,8 +146,9 @@ consistency across the app, not from any single call site.
   `canSendWhileUnchanged` because a submit "does nothing".
 - `distributeChildStates` on a group — the way down asked once for ALL the
   children, when they cannot be placed one at a time (four seats where who sits
-  down decides who moves). The mirror of `aggregateChildStates`; see
-  control_object.md. Read it before writing a `uiAction` whose only job is to
+  down decides who moves), and asked again whenever one of them speaks, so the
+  other views of the same answer follow. The mirror of `aggregateChildStates`;
+  see control_object.md. Read it before writing a `uiAction` whose only job is to
   translate. Two neighbouring questions have answers already: a yes/no shown as
   two rows needs no translation (`List.Item value={true}` beside
   `value={false}` IS a boolean control), and a cross that means "back to the

package/docs/control_object.md

@@ -164,18 +164,60 @@ distributeChildStates: (groupValue, children) => new Map([[child, state], …])
 the mirror of `aggregateChildStates`, which already sees every child. A child
 the Map does not name is left where it is. Given both, the plural one wins.
 
-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.
+**It closes the loop, which the per-child one does not.** A group with a plural
+distribute holds ONE answer its children are views OF — a list saying who plays,
+four seats saying who sits where — rather than a value that IS what they said.
+So when one view speaks, the answer moves and **the other views are placed
+again**; the one that just acted is left where the user put it. Without that, a
+seat keeps showing somebody the list no longer holds, and nothing says so.
+
+This is the same rule as "a child arriving after the value did is placed from
+what the group holds", for a child that was there when the value moved without
+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.
+
+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.93",
+  "version": "0.29.95",
   "type": "module",
   "description": "Library of components including navigation to create frontend applications",
   "repository": {