@jsenv/navi 0.29.95 → 0.29.97

package/docs/control_object.md

@@ -177,7 +177,7 @@ 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
+Five things follow, and each of them was paid for twice before being written
 here:
 
 - **the group's value has to be the view that carries the MOST.** Four seats say
@@ -188,15 +188,54 @@ here:
   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.)
+- **name the children you WANT, never exclude the one you don't.** A group holds
+  more than the views: a search box, a filter, whatever the popup needs. Reading
+  the seats as "every child except the list" collects those too, and the value
+  ends up with five slots for four seats. Finding them by name says what it
+  means;
+- **a gesture that moves two children must never leave the value in an
+  in-between.** Dragging somebody from one seat to another is one intention and
+  two writes, and the group aggregates between them: for one instant the person
+  is in the list and in no seat, which a value that IS the seating has no room
+  for. Measured, that instant costs the person — the aggregate drops them and
+  the distribute unticks them before the second write lands. Two ways out, and
+  the first is the one to prefer:
+
+  1. **write the group's value once.** `rowSignal.value = slots` with both seats
+     already moved: there is no in-between at all. Available when the row is
+     where the placement lives;
+  2. **write the destination first**, when the seats are the truth and must stay
+     separate signals. The person is somewhere at every observable moment (in
+     two seats for an instant, which the rule then resolves), instead of nowhere.
+     Source-first loses them — measured, and silently.
+
+  Wrapping the two writes in a signal `batch()` does NOT help: the group
+  aggregates on each child's change, not on the render that follows.
+
+- **and when the in-between cannot be avoided, the aggregate says so.** Two
+  people swapping seats means one leaves before the other arrives, whichever
+  order the writes take. What is avoidable is PUBLISHING that half-state: an
+  aggregate that returns **what the group already holds** says "not yet, ask me
+  again" — nothing is placed, nothing is handed to the row above, and the next
+  assembly publishes the whole answer. Returning `undefined` says the opposite
+  ("there is no answer"), and wipes the row.
+
+```js
+// "not yet": the moving person is picked and seated nowhere, and it is not
+// somebody who was just ticked — so this is a gesture in flight
+const midMove = picked.some(
+  (id) => !seatedNow.includes(id) && lastAnswer.includes(id),
+);
+if (midMove) {
+  return lastAnswer; // what the group already holds
+}
+```
 
 ```jsx
+// the seats are found by name, never as "everything that is not the list"
+const seatChildren = (children) =>
+  SEAT_NAMES.map((name) => children.find((child) => child.name === name));
+
 // 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

package/package.json

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