@jsenv/navi 0.29.88 → 0.29.90

package/docs/AI_INSTRUCTIONS.md

@@ -149,6 +149,21 @@ consistency across the app, not from any single call site.
   and what a nameless one merges, and what a `<Picker type="object">` needs in
   its popup (one group, not two controls). Read it before making one value out
   of several controls, and before putting anything in a picker popup.
+- A time of day, and a span between two of them, come as a pair of components
+  and the choice between them is about the GESTURE:
+  `TimeSpin`/`TimeRangeSpin` (`src/control/picker/preset/spin_time.jsx`) are
+  fields one types in, and `TimeWheel`/`TimeRangeWheel`
+  (`src/control/wheel/wheel_time.jsx`) are wheels one turns. Both carry a single
+  `"HH:MM"` (or `{ start, end }` for a span), so a form holds one field either
+  way. Prefer the wheels whenever a half-written value would be nonsense — a
+  time typed digit by digit goes through states that are not times ("1" on its
+  way to "18"), each of them bounded and corrected under the fingers, while a
+  wheel only ever shows values that exist. Two things only the wheels have:
+  the bounds of a span PUSH each other while they turn (`minDuration`) instead
+  of being refused at send, and `placeholder` is a position shown without being
+  an answer — for a span that is optional ("any time of day") on wheels that
+  have no blank row to land on. Read this before writing a time input, and
+  before making a pair of wheels say "nothing set" by hand.
 - `docs/control_group.md` — `<Group>`: several controls reading as one framed
   object (one border per seam, radius on the outer corners only). Read it
   before placing bordered controls against each other, and before writing

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)
+- [A group holds what it was given](#a-group-holds-what-it-was-given)
 - [One line, one key](#one-line-one-key)
 - [A settings sheet](#a-settings-sheet)
 - [`Group` is not `ControlGroup`](#group-is-not-controlgroup)
@@ -117,7 +118,9 @@ Two things to get right:
 - **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.
+  what a popup made of one choice and the means to reach it needs. Never put it
+  on the control that IS the value — the picker would have nobody left to fill,
+  and the popup would open blank on a value it holds (navi says so in dev).
 
 ```jsx
 <Picker name="place_ids" type="array">
@@ -128,6 +131,40 @@ Two things to get right:
 </Picker>
 ```
 
+## A group holds what it was given
+
+A group's value looks like it is made of its children, and mostly it is — but
+the two are not the same thing, and the difference shows the moment the children
+are not all there yet:
+
+- a group **told** a value holds it whole, before any child has registered to
+  show it. A list whose items are still loading, a popup built at open, a row
+  scrolled out of a virtualized list — none of them make the value smaller;
+- **a child mounting or unmounting is not somebody answering.** While children
+  are arriving, their aggregate is a partial reading; a group takes it for its
+  own value only once it has derived that value itself (nobody handed it one),
+  or once a child really acts;
+- a child arriving **after** the value did is placed from what the group holds,
+  so it shows its part of it. A child arriving with something of its own to show
+  is answering, and keeps it. A child bound to a `signal` is placed like any
+  other — bound is not frozen — and the placement writes the signal, so an
+  `<Input type="hidden" signal>` carrying a piece of the answer shows what the
+  group holds. Only a child controlled by a `value`/`checked` prop is left
+  alone: its owner decides.
+
+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.
+
 ## One line, one key
 
 A row that opens a popup is one control, so what it answers arrives under its

package/package.json

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