@jsenv/navi 0.29.89 → 0.29.91

package/docs/AI_INSTRUCTIONS.md

@@ -149,6 +149,25 @@ 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. A clear (or a value written as `undefined`) puts
+  such a pair back on its placeholder and back to answering nothing, so a row's
+  cross means what it says. `hours` bounds what the wheels offer
+  (`{ min: 7, max: 21 }`, or the list itself) — rows nobody can land on are rows
+  in the way. 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/actions.md

@@ -72,6 +72,16 @@ const userAction = getUser.bindParams({ id: userIdSignal });
 | `reset()`  | Aborts what is running and puts the action back to idle, data and all.   |
 | `abort()`  | Calls off the run in flight, keeping the data it had.                    |
 
+### Aborting saves resources, it does not undo
+
+`abort()` cancels what can still be cancelled — a `fetch` wired to the
+callback's `signal` — and nothing more. The server may have done the work
+before the cancellation reached it, or may not honor cancellations at all:
+whether the work happened is known from the run's settlement alone. For that
+reason a run's promise settles only when its callback settles, even after an
+abort, and anything sequenced behind a run — an optimistic control's queued
+request, for instance — waits for that settlement, never for the abort.
+
 ## Reading an action
 
 ```jsx

package/docs/control_object.md

@@ -146,7 +146,19 @@ are not all there yet:
   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.
+  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

package/docs/control_value.md

@@ -10,6 +10,7 @@ somewhere else in the app.
 - [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)
+- [The PROP is what controls, not its value](#the-prop-is-what-controls-not-its-value)
 - [`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)
 
@@ -160,6 +161,28 @@ own `selected` — but not expect the two to arbitrate. An item that declares
 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.
 
+## The PROP is what controls, not its value
+
+`value` (and `checked`, and a row's `selected`) makes a control controlled by
+being **there**. Its value is a separate question: `value={undefined}` says "I
+hold this one, and right now it holds nothing" — the control shows nothing, and
+nothing else can fill it. That is a real state and it is the one asked for.
+
+The trap is the shorthand for an optional prop:
+
+```jsx
+// WRONG — the key is always there, so the control is always controlled,
+// and the group above it can never fill it
+<Input checked={bound ? undefined : checked} />
+
+// RIGHT — the prop is there only when you are the one answering
+<Input {...(bound ? {} : { checked })} />
+```
+
+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.
+
 ## `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.89",
+  "version": "0.29.91",
   "type": "module",
   "description": "Library of components including navigation to create frontend applications",
   "repository": {