@jsenv/navi 0.29.43 → 0.29.45

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/css_architecture.md

@@ -120,6 +120,71 @@ Note that scoping to an ancestor is not enough: `.my-sidebar { --link-color-pres
 
 When a component default deserves to be themed globally, promote it: declare a `--navi-<component>-<thing>` in [navi_css_vars.js](../src/navi_css_vars.js) and make the component default read `var(--navi-…)`.
 
+#### An app narrower than the screen
+
+An app that never spans the whole window — a phone-shaped column centered in a
+wide one, bands on the sides — has one problem with popups: a dialog lives in
+the browser's top layer, so it is calibrated on the _viewport_, and would paint
+1500px of modal over a 600px app. The top bar and the bottom nav have the same
+problem and solve it by repeating the app width by hand; popups must not need
+that, because the app would then have to know which components exist.
+
+So the app states its own screen once, and never names a component:
+
+```css
+:root {
+  --navi-app-max-width: 600px;
+  /* --navi-app-max-height too, for an app that also caps its height */
+}
+```
+
+In pixels: popup placement reads this value back from CSS to compute its own
+margins, and a custom property computes to a token stream rather than to a
+length, so `40rem` would arrive there as the string `"40rem"`. A non-px value
+still caps the popup's size (that part is pure CSS) but leaves the margins
+viewport-sized, and says so in the console.
+
+Every popup follows: `Dialog`, `Popover`, and everything built on them
+(`Picker`, `Select`…). It is a ceiling and nothing more — on a screen narrower
+than the app it never binds, and each popup still subtracts its own
+`marginWithContainer` from it, so the gap with the edges is kept either way.
+That gap is itself a share of the app's screen, not of the window (`"3appw"`,
+navi's own unit alongside `vvw`/`vvh`) — otherwise a 3% margin measured on a
+1500px window would eat 90px out of a 600px app.
+
+Do **not** try to get this by setting `--dialog-max-width` on `.navi_dialog`
+from the app. Two reasons:
+
+- it is a `--component-*` token, declared on the element (see the table above),
+  so components that write it themselves outrank an app rule of lower
+  specificity — `.navi_picker[aria-haspopup="dialog"] .navi_dialog` does exactly
+  that, and the app's cap silently disappears for every picker;
+- it is the knob a single popup uses to ask for a specific size, not a ceiling.
+  `--navi-app-max-width` feeds `--dialog-maxmax-width`, the hard ceiling _under_
+  that knob, so a popup that genuinely needs its own `maxWidth` can still say so
+  without any of them escaping the app's screen.
+
+##### Current limitations
+
+`--navi-app-max-width` caps how big a popup may get; it does not move where one
+is placed. Placement is still computed against the real viewport
+(`pickPositionRelativeTo`, in `@jsenv/dom`). That is invisible for anything
+centered on its cross axis — `center`, `bottom`, `top`, which is what a dialog
+does nearly always — but shows for anything anchored to an edge: a
+`positionArea` like `bottom-start`, a `SidePanel`, a fixed bar. Those sit
+against the window's edge rather than the app column's, so they stay on the real
+viewport for now (`side_panel.jsx` restates `--dialog-maxmax-width` as the full
+viewport on purpose).
+
+Making them follow the app column too means narrowing the container rect
+placement is computed against, inside `pickPositionRelativeTo` — worth doing the
+day a side panel or a fixed bar has to live inside a simulated screen.
+
+Note that an app can already get all of it, placement included, by rendering
+itself in an iframe of the target width: the viewport then genuinely _is_ the
+app's screen and no token is needed at all. `--navi-app-max-width` is the answer
+for an app that does not want to pay that price.
+
 ### 3. Direct rule override (avoid unless necessary)
 
 Overriding the actual CSS rules (not the variables) is intentionally hard — that is by design. If you find yourself needing to do this, it usually means a CSS variable should be exposed for that property. Open an issue or add the variable yourself and contribute it back.
@@ -133,4 +198,5 @@ Overriding the actual CSS rules (not the variables) is intentionally hard — th
 | One component instance       | Component prop or `style` attribute                                        |
 | All instances of a component | `--component-*` in unlayered app CSS, on a selector matching the component |
 | A global design token        | `--navi-*` on `:root`                                                      |
+| How wide popups may ever get | `--navi-app-max-width` on `:root`                                          |
 | A structural layout rule     | Expose a new CSS variable (contribute)                                     |

package/docs/form_changed.md

@@ -7,6 +7,7 @@ as an answer the form already holds, and what to do on a screen whose fields are
 filled a request later.
 
 - [Sending nothing is the default](#sending-nothing-is-the-default)
+- [What follows a send](#what-follows-a-send)
 - [What the form is measured against](#what-the-form-is-measured-against)
 - [What counts as already held](#what-counts-as-already-held)
 - [A screen filled after it opened: `pristineKey`](#a-screen-filled-after-it-opened-pristinekey)
@@ -31,6 +32,50 @@ duplicates are fine.
 <Form action={notify} canSendWhileUnchanged>
 ```
 
+## What follows a send
+
+The form has answered its question; `command` says what the screen does about
+it — dismiss the popup (`--navi-close`), move on the slide map
+(`--navi-left`…), go to a page (`--navi-nav-to:/games/42`), stay put
+(`--navi-void`). Left out, the surface the form sits in decides: a popup closes,
+a slide goes on, a form on a page does nothing.
+
+It runs **whether or not there was anything to send** — that is the other half
+of the rule above: the person is done either way, and a submit that ran no
+action still closes the popup, still moves on, still navigates. Which is why
+this is a prop, decided before the send: the form has to know where it goes even
+when nothing happened.
+
+Nothing runs when the send fails, or when a constraint refuses it. The form then
+stays in front of the person, showing what it is waiting for.
+
+### When only the response knows where to go
+
+A creation lands on the page the server just made, and its id comes back with
+the response — too late for a prop. Do it in the action, which is where the
+answer is:
+
+```jsx
+<Form
+  action={async (value) => {
+    const game = await createGame(value);
+    navTo(`/games/${game.id}`);
+  }}
+>
+```
+
+Nothing to declare: a creation always has something to send, so there is no
+"the press did nothing" case for `command` to cover.
+
+If you would rather it go through the command machinery all the same (to reuse
+whatever a command does on that surface), the form carries what follows the send
+as `data-after-send`, read once the send has succeeded — so an action can write
+it while it runs:
+
+```js
+formRef.current.setAttribute("data-after-send", `--navi-nav-to:/games/${id}`);
+```
+
 ## What the form is measured against
 
 One value, called the baseline here: **what the form held the last time it had
@@ -90,6 +135,11 @@ Its submit is live, and pressing it sends back the resource untouched.
 Change it **once**, when the screen is ready. Taken again after someone started
 typing, it would call what they wrote the reference.
 
+No need to delay it by a tick: the reference is taken when the fields have
+settled, and again at the end of that same tick — so a row that arrives in a
+render of its own (a value computed from signals, a memoized row) is part of it
+without the screen having to know which of its fields settle late.
+
 Do not use a `key` on the `<Form>` for this: it remounts every control and every
 popup inside it, and anything half-typed goes with them.
 
@@ -124,4 +174,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.45",
   "type": "module",
   "description": "Library of components including navigation to create frontend applications",
   "repository": {