@jsenv/navi 0.29.91 → 0.29.93

package/docs/AI_INSTRUCTIONS.md

@@ -144,6 +144,15 @@ consistency across the app, not from any single call site.
   `signal` carrying something is an answer). Read it before a screen that
   modifies an existing resource (`pristineKey`), and before reaching for
   `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
+  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
+  usual answer" needs none either — clearing empties, and `placeholder` is
+  where that sentence is written (control_value.md).
 - `docs/control_object.md` — a value made of several controls: `<ControlGroup>`
   (the shape) vs `<Form>` (the shape plus a send), what a group's `name` does
   and what a nameless one merges, and what a `<Picker type="object">` needs in

package/docs/actions.md

@@ -185,12 +185,12 @@ the event that caused it, and `findEvent(event, type)` walks that chain back:
   clearable
   uiAction={(value, event) => {
     if (findEvent(event, "navi_clear_ui_state")) {
-      // the clear cross was pressed — for this row that means "back to the
-      // profile level", not "empty"
-      draft.level = profile.level;
+      // the cross was pressed — the row is empty because somebody emptied it,
+      // not because the last player left the list
+      askAgainLater();
       return;
     }
-    draft.level = value;
+    draft.players = value;
   }}
 />
 ```

package/docs/control_object.md

@@ -152,6 +152,18 @@ are not all there yet:
   group holds. Only a child controlled by a `value`/`checked` prop is left
   alone: its owner decides.
 
+`distributeChildUIState` is asked child by child, which is fine while each child
+can be placed on its own. When it cannot — four seats where who sits down
+decides who moves, a row whose first answer changes what the others may show —
+`distributeChildStates` is the same way down asked ONCE for all of them:
+
+```js
+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

package/docs/control_value.md

@@ -11,6 +11,8 @@ somewhere else in the app.
 - [Empty keeps the shape of the question](#empty-keeps-the-shape-of-the-question)
 - [Which controls take a `signal`](#which-controls-take-a-signal)
 - [The PROP is what controls, not its value](#the-prop-is-what-controls-not-its-value)
+- [A yes/no shown as two rows](#a-yesno-shown-as-two-rows)
+- [Clearing, resetting, and what is shown meanwhile](#clearing-resetting-and-what-is-shown-meanwhile)
 - [`value` and `signal` exclude each other](#value-and-signal-exclude-each-other)
 - [A `stateSignal` brings more than a value](#a-statesignal-brings-more-than-a-value)
 
@@ -183,6 +185,54 @@ Passing a prop the code knows will always be `undefined` is the same mistake
 written once instead of twice: leave it out. navi says so in dev when a group
 tries to place a child that has claimed itself this way.
 
+## A yes/no shown as two rows
+
+A checkbox is one way to ask a yes/no; two rows one can compare — "Publique, we
+propose it to players looking for this kind of game" against "Privée, it travels
+only by the link you send" — is another, and it is the same value:
+
+```jsx
+<Picker name="visibility" signal={isPublicSignal}>
+  <List selectable>
+    <List.Item value={true}>Publique …</List.Item>
+    <List.Item value={false}>Privée …</List.Item>
+  </List>
+</Picker>
+```
+
+Nothing translates: the row holds the boolean, the form carries the boolean.
+What cannot be done is give a row `undefined` to mean "no value" — `undefined`
+is what UNCHECKED means, here as in HTML, so such a row can never be ticked.
+A value the control can hold is a value one can see; "nothing chosen" is the
+absence of a row, not a row.
+
+## Clearing, resetting, and what is shown meanwhile
+
+Three things that look alike and are not:
+
+| gesture / prop            | what it does                                                                        |
+| ------------------------- | ----------------------------------------------------------------------------------- |
+| `--navi-clear`, the cross | the control holds its own empty — `""`, `[]`, `{}`, unchecked                       |
+| `--navi-reset`            | the control goes back to its `defaultValue`                                         |
+| `defaultValue`            | where it starts, and where a reset goes back to — a real value, sent like any other |
+| `placeholder`             | what is SHOWN while it holds nothing, and never a value                             |
+
+So a row whose cross means "back to the one from my profile" needs nothing of
+its own: clearing empties it, and `placeholder` is where that sentence is
+written.
+
+```jsx
+<Picker clearable placeholder="Celui de mon profil" signal={sideSignal} />
+```
+
+What the app then reads is `undefined` (or the empty of the row's type), which
+is what "nothing chosen here, use the usual answer" already means everywhere
+else — the same rule as an emptied signal falling back on its default.
+
+A control that cannot show emptiness — a pair of wheels has no blank row to land
+on — takes the same `placeholder` as a POSITION instead of a word (see
+`TimeWheel`): shown, and still not an answer.
+
 ## `value` and `signal` exclude each other
 
 `value` (or `checked`) says "you hold it", `signal` says "the signal holds it".

package/package.json

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