@jsenv/navi 0.29.85 → 0.29.87

package/docs/autofocus.md

@@ -82,17 +82,24 @@ itself.
 
 ## On a touch device: the surface is what one arrives on
 
-Where the keyboard is a virtual one — anything answering `pointer: coarse` — a
-popup opening drops step 3 of the ladder entirely: the focus goes where
-something ASKED for it, and otherwise to the surface itself.
-
-The condition is the device, not the popup's shape and not the gesture that
-opened it. A virtual keyboard is a fact about the screen: it costs a third of
-the height whichever popup raised it, and a popup opened by the page loading —
-no pointer in it at all — is exactly the one that must not be answered "no
-keyboard here". Docking only makes the cost more visible (a bottom sheet is
-short, so there is less room to lose before the title goes), it is not what
-creates it.
+Where the keyboard is a virtual one — anything answering `pointer: coarse` — an
+arrival drops step 3 of the ladder entirely: the focus goes where something
+ASKED for it, and otherwise to the surface itself.
+
+Every arrival, not just a popup opening. A slide travelling in (so a
+`RouteTravel` screen too) hands out the focus the same way and loses the same
+thing by landing on the first focusable — more of it, even, a screen having more
+above the fold than a popup. Its surface is the `SlideContainer` box, which is
+what takes the keyboard when the slide holds nothing that can, so the arrows
+keep working from there.
+
+The condition is the device, not the shape of what arrives and not the gesture
+that brought it. A virtual keyboard is a fact about the screen: it costs a third
+of the height whatever raised it, and an arrival with no pointer in it at all —
+a popup opened by the page loading, a travel asked for by code — is exactly the
+one that must not be answered "no keyboard here". Docking only makes the cost
+more visible (a bottom sheet is short, so there is less room to lose before the
+title goes), it is not what creates it.
 
 Withdrawing only the FIELDS would not be enough either. The first focusable is
 wherever the content happens to put it — and in a popup that explains before it
@@ -105,7 +112,8 @@ Nothing to pass, and nothing to remember per call site.
 
 ### Opting a field back in
 
-Some popups really are opened to type in: one comment box, one rename field.
+Some popups — and some screens — really are opened to type in: one comment box,
+one rename field.
 There, the field says so itself, and that beats the device — step 2 of the
 ladder comes before step 3 was ever skipped.
 

package/docs/control_object.md

@@ -11,6 +11,7 @@ whose value is an object needs in its popup.
 - [`<Form>`: the shape, plus a send](#form-the-shape-plus-a-send)
 - [Naming, and what a nameless group does](#naming-and-what-a-nameless-group-does)
 - [A picker whose value is an object](#a-picker-whose-value-is-an-object)
+- [One line, one key](#one-line-one-key)
 - [A settings sheet](#a-settings-sheet)
 - [`Group` is not `ControlGroup`](#group-is-not-controlgroup)
 
@@ -113,6 +114,39 @@ Two things to get right:
   kind a scalar type and there is no group to distribute anything — the whole
   object lands on one control, which is how `"[object Object]"` ends up in a
   url.
+- **A control that helps FIND the answer is not the answer.** A search box above
+  a long list, a "select all" beside it: they are tools, and a tool says so with
+  `allowNameless`. The picker then walks past it and talks to the list, which is
+  what a popup made of one choice and the means to reach it needs.
+
+```jsx
+<Picker name="place_ids" type="array">
+  <Input allowNameless placeholder="chercher" navi-list="places" />
+  <List id="places" selectable multiple>
+    …
+  </List>
+</Picker>
+```
+
+## One line, one key
+
+A row that opens a popup is one control, so what it answers arrives under its
+one name. A row answering two questions at once — where the level comes from
+AND which levels, when it starts AND when it ends — hands back a sub-object:
+
+```jsx
+<Picker name="level" type="object">   // { level: { level_mode, levels } }
+<Picker name="hours" type="object">   // { hours: { from_minute, to_minute } }
+```
+
+Flattening those into the sent object is the caller's business
+(`{ ...value.level, ...value.hours }`), and it is the only reasonable place for
+it: a picker with no name of its own could not be collected, and one merging its
+keys into the object around it would take the row's own identity away — nothing
+would say which row a key came from, nor which row to put an incoming value
+back on. A `<ControlGroup>` with no name IS that merge, and it exists for the
+case where there is no row: several controls in one screen, no door between
+them.
 
 ## A settings sheet
 

package/docs/control_value.md

@@ -8,6 +8,7 @@ somewhere else in the app.
 - [A bound signal works in both directions](#a-bound-signal-works-in-both-directions)
 - [`signal` + `defaultValue`: the answer and where it starts](#signal--defaultvalue-the-answer-and-where-it-starts)
 - [What a signal holds, control by control](#what-a-signal-holds-control-by-control)
+- [Empty keeps the shape of the question](#empty-keeps-the-shape-of-the-question)
 - [Which controls take a `signal`](#which-controls-take-a-signal)
 - [`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)
@@ -117,6 +118,31 @@ writes it, and what they change is written back into it. One signal for a screen
 whose values arrive together — see
 [create_and_edit.md](./create_and_edit.md#two-screens-two-states).
 
+## Empty keeps the shape of the question
+
+What a control is worth when it holds nothing has the type of what it holds when
+it holds something. A list of days nobody picked is `[]`, not `""`:
+
+| control                                           | empty is |
+| ------------------------------------------------- | -------- |
+| `Picker type="array"`, `List selectable multiple` | `[]`     |
+| `Picker type="object"`                            | `{}`     |
+| text/number/date `Input`, `Select`                | `""`     |
+| `Input type="checkbox" value={true}`              | `false`  |
+| radio, checkbox holding a value of its own        | absent   |
+
+This is what a clear (`--navi-clear`, a row's cross) leaves behind and what the
+object around it carries, so the conversion nobody writes — `value.days || []` —
+is not needed, and not needed only after having watched the wrong shape reach
+the server.
+
+A checkbox is a member of a set, the way HTML has it: checked it carries its
+`value` (`"on"` when it was given none), unchecked it carries nothing at all —
+which is what lets several checkboxes sharing a name aggregate into an array. A
+checkbox that is a yes/no rather than a member says so with `value={true}`, and
+is then `true` or `false`. Its bound `signal` holds the boolean either way (see
+the table above): what a signal on a checkbox is about is whether it is checked.
+
 ## Which controls take a `signal`
 
 All of them: `Input` (every type), `Picker`, `Select`, `Wheel`, `Spin`,
@@ -131,7 +157,8 @@ something else read where the slides are — or move them by writing it.
 Inside a `List selectable` you can bind the list, or give each `List.Item` its
 own `selected` — but not expect the two to arbitrate. An item that declares
 `selected` is answering for itself, and the list's signal does not reposition
-it.
+it. On screen that reads as a list where clicking does nothing, so navi says it
+in dev the moment the two claims meet: bind one end or the other, not both.
 
 ## `value` and `signal` exclude each other
 

package/docs/form_changed.md

@@ -168,7 +168,10 @@ row whose value is carried by a hidden input beside it) says so with
 <Picker allowNameless ui={…}>
 ```
 
-It is then neither collected nor complained about.
+It is then neither collected nor complained about — and inside a picker's popup
+it is not the control the picker talks to either, which is what lets a search
+box sit above the list that IS the answer (see
+[control_object.md](./control_object.md#a-picker-whose-value-is-an-object)).
 
 ## See also
 

package/package.json

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