@jsenv/navi 0.29.43 → 0.29.44

package/docs/AI_INSTRUCTIONS.md

@@ -69,8 +69,10 @@ consistency across the app, not from any single call site.
   `docs/resource_with_params.md`, `docs/resource_dependencies.md`.
 - `docs/list_refresh.md` — what a write sends back to the network and what stays
   on screen meanwhile: stale data returned by `useAsyncData({ loading: true })`,
-  what updates from a response without any request, `rerunOn` and its defaults.
-  Read it before adding verbs to `rerunOn` or hiding a list on `loading`.
+  what updates from a response without any request, `rerunOn` and its defaults,
+  and how a paginated `<List.Items>` re-reads its slices without disappearing.
+  Read it before adding verbs to `rerunOn`, hiding a list on `loading`, or
+  remounting a list with a `key` to refresh it.
 - `docs/css_architecture.md` — how Navi's CSS layering works, and the
   supported ways to override component styles (props > CSS variables > direct
   rule overrides, in that preference order).
@@ -90,6 +92,11 @@ 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".
+- `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
+  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.
 - `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_group.md

@@ -130,6 +130,11 @@ The controls shipped by navi all follow this: `Button`, `Input`, `Select`,
 - Controls separated by space, each with its own frame — that is a `Box` with
   `spacing`, they were never one object.
 - A label and its control — that is `Field`.
+- Several controls making ONE value between them (an address out of three
+  fields, a day and two wheels out of one moment) — that is `ControlGroup`,
+  which is about the value and draws nothing. Same word, other subject: see
+  [control_object.md](./control_object.md). Both at once is fine — a `Group`
+  around the members of a `ControlGroup`.
 - Radio buttons or checkboxes sharing a name and a validation — that is
   `RadioGroup` / `CheckboxGroup`, which is about the value, not the frame. They
   can be put inside a `Group` if you also want them to share a frame.

package/docs/control_object.md

@@ -0,0 +1,133 @@
+# A value made of several controls
+
+One question, answered by more than one control: a day and two wheels that make
+"mardi 19h", three fields that make an address, two wheels that add up to a
+number of minutes. Navi has one mechanism for that — a group aggregates what its
+children hold into a single value, and hands it back the same way — and three
+places it shows up. This file says which one to reach for, and what a picker
+whose value is an object needs in its popup.
+
+- [`<ControlGroup>`: the shape](#controlgroup-the-shape)
+- [`<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)
+- [`Group` is not `ControlGroup`](#group-is-not-controlgroup)
+
+## `<ControlGroup>`: the shape
+
+A group with no opinion beyond the shape of its value: it aggregates its named
+children into an object, distributes an object back down to them, and carries
+its own `action`/`uiAction`/`command` if you want one.
+
+```jsx
+<ControlGroup name="address">
+  <Input name="street" />
+  <Input name="city" />
+  <Input name="zip" />
+</ControlGroup>
+// worth { street, city, zip }
+```
+
+It is also the brick composite controls are built from:
+`aggregateChildStates` / `distributeChildUIState` replace "one key per child"
+with a value of your own — two wheels that are one number of minutes, three
+fields that are one date. A group with them takes and hands back a single
+value, so it can be driven by one `value`/`signal` like any other control. It is
+what `SpinTime` is made of, and the same mechanism `InputDuration`, `SpinGroup`
+and `WheelGroup` use for their own members.
+
+## `<Form>`: the shape, plus a send
+
+A `<Form>` aggregates exactly the same way. What it adds is everything about
+**sending**: the reference it measures against, the refusal to act when nothing
+changed (see [form_changed.md](./form_changed.md)), the submit button and its
+`readOnlyWhileFormUnchanged`, what follows a successful send (`command`), and a
+`<form>` element with the browser's own submit/reset.
+
+So the choice is not about the value, it is about whether this cluster is a
+**question with a send**:
+
+- a shape inside a bigger whole → `ControlGroup`;
+- something the user sends → `Form`.
+
+A `<Form>` inside a `<Form>` is legal — the inner one becomes a group without
+the `<form>` element — but it carries all of the above with it: its own
+reference, its own "nothing changed", its own submit story. Grouping three
+fields into a sub-object should cost none of that.
+
+## Naming, and what a nameless group does
+
+A group's `name` is the key its value lands under, in the group above it. This
+is true of a `ControlGroup` and of a nested `Form` alike.
+
+Left nameless, a group is a **grouping**: it exists to hold its children
+together (shared navigation, a visual cluster) without claiming a key, and what
+it holds is merged into the object around it as if its children had been written
+there.
+
+```jsx
+<ControlGroup name="when">
+  <DaySpin name="day" />
+  <WheelGroup>
+    <Wheel name="hours" />
+    <Wheel name="minutes" />
+  </WheelGroup>
+</ControlGroup>
+// worth { day, hours, minutes } — the WheelGroup adds no key of its own
+```
+
+A nameless **leaf** is a different story: it is a control whose value has
+nowhere to go, and it is warned about. When that is deliberate — a control that
+only opens something — say so with `allowNameless` (see
+[form_changed.md](./form_changed.md#a-control-that-is-not-a-field)).
+
+## A picker whose value is an object
+
+`type="object"` is the picker whose value is what the group in its popup
+aggregates (next to `type="array"`, whose value is a selection):
+
+```jsx
+<Picker name="when" type="object" value={{ day, hours, minutes }}>
+  <ControlGroup>
+    <DaySpin name="day" signal={daySignal} />
+    <WheelGroup>
+      <Wheel name="hours" signal={hoursSignal} />
+      <Wheel name="minutes" signal={minutesSignal} />
+    </WheelGroup>
+  </ControlGroup>
+</Picker>
+```
+
+Two things to get right:
+
+- **One control in the popup, and it must be the group.** A picker syncs with a
+  single control: the first one receives the picker's whole value and is the
+  only one read back. Two controls side by side in a popup is the shape to
+  avoid — the second is neither filled nor collected, and navi says so in dev.
+  Wrap them in one `ControlGroup` (or one `Form`, when the popup has a send of
+  its own).
+- **The value travels by name.** What the picker was given goes down into the
+  group, which hands each named child its own key; a nameless grouping inside
+  receives the whole object and picks out what it names. Give a picker of this
+  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.
+
+## `Group` is not `ControlGroup`
+
+Two names, two subjects, no relation:
+
+- `<Group>` is about the **frame** — several controls reading as one object to
+  the eye, one border per seam. See [control_group.md](./control_group.md).
+- `<ControlGroup>` is about the **value** — several controls reading as one
+  object to the action.
+
+They compose: a `Group` around controls that also happen to be a
+`ControlGroup`'s children is fine, and either can exist without the other.
+
+## See also
+
+- [form_changed.md](./form_changed.md) — what a form sends, and what it measures
+  against
+- [control_value.md](./control_value.md) — who holds a single control's value
+- [control_group.md](./control_group.md) — the visual `<Group>`

package/docs/control_value.md

@@ -52,6 +52,23 @@ Both halves are worth knowing about, because each replaces a habit:
 - the follow replaces the `key` or the `value`/`uiAction` pair used to push an
   outside change into a control.
 
+The follow goes all the way up: a bound control that lives inside a group — two
+wheels in a `WheelGroup`, a field in a `ControlGroup` — makes that group
+re-aggregate when its signal is written, and the form above sees the new value.
+A shortcut that pushes the controls from the outside is an answer like any
+other: the wheels roll, and the submit lights up.
+
+```jsx
+<Button
+  onClick={() => {
+    hoursSignal.value = 2;
+    minutesSignal.value = 0;
+  }}
+>
+  2h
+</Button>
+```
+
 ## `signal` + `defaultValue`: the answer and where it starts
 
 They are not competing, they answer two different questions:
@@ -126,6 +143,8 @@ directions; it just has nothing extra to say.
 
 - [form_changed.md](./form_changed.md) — what a form makes of each of these:
   which fields it counts as already answered, and when it sends nothing
+- [control_object.md](./control_object.md) — several controls reading as one
+  object: which group aggregates them, and how the value travels down by name
 - [control_group.md](./control_group.md) — several controls reading as one
   framed object
 - [actions.md](./actions.md#action-or-uiaction) — `action` or `uiAction`: which

package/docs/form_changed.md

@@ -124,4 +124,6 @@ It is then neither collected nor complained about.
 
 - [control_value.md](./control_value.md) — who holds a control's value:
   nothing, a bound `signal`, or you
+- [control_object.md](./control_object.md) — one value made of several
+  controls: `ControlGroup`, `Form`, and a picker whose value is an object
 - [actions.md](./actions.md) — what an action does around the send itself

package/docs/list_refresh.md

@@ -67,9 +67,56 @@ way back is a re-read.
 `DELETE` is symmetric: returning the id drops the item from the store, and every
 list containing it drops it too.
 
+## A paginated list stays on screen too
+
+A `<List.Items>` reading through `GET_RANGE` holds the slices it received —
+places in a collection, not a list of ids — so nothing the store does can fix
+them: a row that changed tab, or one that was deleted, moves every row after it
+one rank up, and only the collection knows who fills the last place.
+
+It is told, and it re-reads by itself:
+
+```jsx
+<List.Items
+  count={count}
+  itemsAction={NOTIFICATION.GET_RANGE.bindParams({ scope })}
+  renderItem={(item, index, { refreshing }) => …}
+/>
+```
+
+The reader keeps no value, so there is nothing to rerun; what it has is a
+signal, bumped by the verbs `rerunOn.GET_RANGE` lists (`["POST", "DELETE"]` by
+default — `DELETE` is in there precisely because the store cannot fix places).
+A run hearing it asks again **for the window it is drawing**, and keeps drawing
+it meanwhile:
+
+| Moment                          | what the run draws   | state        |
+| ------------------------------- | -------------------- | ------------ |
+| nothing received yet            | skeletons            | loading      |
+| re-reading after a first answer | the rows from before | `refreshing` |
+| answer received                 | the new rows         | —            |
+
+The rows, the scroll position and the row being read all stay; the slices
+outside the window are forgotten only once the answer is in, and asked for
+again if the user goes back to them. A re-read that fails leaves the rows from
+before on screen. While it is in flight, the list carries `navi-refreshing` and
+`renderItem` gets `{ refreshing }` — read it as "what you see is from before",
+never as "there is nothing to see".
+
+An app that knows a row is on its way out (it is the one deleting it) says so
+itself: it is the one rendering the row, so it draws it loading, muted, or not
+at all. The run is not told about rows, only about the collection.
+
+```jsx
+// ✗ remounting the run to refresh it: every row on screen becomes a skeleton
+//   again, and the list reopens where it opens, not where it was being read
+<List.Items key={`${scope}:${moved}`} … />
+```
+
 ## `rerunOn`, verb by verb
 
-`rerunOn` says which verbs invalidate this resource's `GET` / `GET_MANY`:
+`rerunOn` says which verbs invalidate this resource's `GET` / `GET_MANY` /
+`GET_RANGE`:
 
 ```js
 const GAME_RADAR = resource("game_radar", {
@@ -78,12 +125,13 @@ const GAME_RADAR = resource("game_radar", {
 });
 ```
 
-Defaults are `{ GET: false, GET_MANY: ["POST"] }`:
+Defaults are `{ GET: false, GET_MANY: ["POST"], GET_RANGE: ["POST", "DELETE"] }`:
 
-| Default              | Why                                                                                                                                                                                                                                                                                 |
-| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `GET: false`         | `PUT`/`PATCH` already update the UI through the store; `DELETE` resets the `GET` rather than re-running it, so a deleted item shows nothing instead of a spinner then a 404. Give the deleted case its own UI (an "item not found" panel, a redirect) instead of `GET: ["DELETE"]`. |
-| `GET_MANY: ["POST"]` | Whether a new item belongs in this list depends on filters, pagination, sort — the backend knows, the client does not. `DELETE` is excluded because the store already removes the item from every list.                                                                             |
+| Default                         | Why                                                                                                                                                                                                                                                                                 |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `GET: false`                    | `PUT`/`PATCH` already update the UI through the store; `DELETE` resets the `GET` rather than re-running it, so a deleted item shows nothing instead of a spinner then a 404. Give the deleted case its own UI (an "item not found" panel, a redirect) instead of `GET: ["DELETE"]`. |
+| `GET_MANY: ["POST"]`            | Whether a new item belongs in this list depends on filters, pagination, sort — the backend knows, the client does not. `DELETE` is excluded because the store already removes the item from every list.                                                                             |
+| `GET_RANGE: ["POST", "DELETE"]` | A slice is a range of places: a row leaving the collection shifts every place after it, which the store cannot do. Add the verb that moves an item in or out of the collection — a `PATCH` that archives, one that changes an item's tab.                                           |
 
 Adding `PUT`/`PATCH` to `GET_MANY` is the usual over-correction: it costs a
 request and a `loading` pass to obtain something the response already contained.
@@ -92,12 +140,13 @@ updated item — not client-side refreshing.
 
 ## Decision table
 
-| What changed              | Re-read the list?                                    |
-| ------------------------- | ---------------------------------------------------- |
-| a field of one item       | no — the write's response is enough                  |
-| membership of the list    | yes (`POST`) — the backend decides who belongs       |
-| the ORDER of the list     | yes — the store stores, it does not sort (see below) |
-| nothing came back (`204`) | yes — there is nothing to put in the store           |
+| What changed                | Re-read the list?                                    |
+| --------------------------- | ---------------------------------------------------- |
+| a field of one item         | no — the write's response is enough                  |
+| membership of the list      | yes (`POST`) — the backend decides who belongs       |
+| the ORDER of the list       | yes — the store stores, it does not sort (see below) |
+| nothing came back (`204`)   | yes — there is nothing to put in the store           |
+| a place in a paginated list | yes — a `GET_RANGE` reads places, and places shift   |
 
 ## The store stores, it does not sort
 

package/package.json

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