@jsenv/navi 0.29.42 → 0.29.44

package/docs/form_changed.md

@@ -0,0 +1,129 @@
+# What a form sends, and what it measures against
+
+A form answers a question. Asked again with the same answer, it has nothing to
+say — so by default **a `<Form>` sends nothing when nothing changed**. This is
+the whole subject of this file: what "changed" is measured against, what counts
+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 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)
+- [A submit that says it is waiting](#a-submit-that-says-it-is-waiting)
+- [A control that is not a field](#a-control-that-is-not-a-field)
+
+## Sending nothing is the default
+
+Submitting a form nobody touched — one just rendered, one whose fields still
+hold their defaults, one reopened and left alone — runs **no action**. No
+request, nothing in the network tab.
+
+Everything around the action still happens: the constraints are checked, and
+what follows the send still follows it (the popup closes, the slide moves on).
+The user is done either way; there was simply nothing to send.
+
+`canSendWhileUnchanged` turns that off, for a form where sending the same thing
+twice is the point — a single button firing a notification, an action whose
+duplicates are fine.
+
+```jsx
+<Form action={notify} canSendWhileUnchanged>
+```
+
+## What the form is measured against
+
+One value, called the baseline here: **what the form held the last time it had
+nothing to say.**
+
+- taken once the fields have registered — the earliest moment the form knows
+  what it holds;
+- taken again after every **successful** send, so the next submit is measured
+  against what was just sent (a send that failed changes nothing: the same
+  value must remain sendable);
+- never taken again on its own. A form does not notice that its fields were
+  filled from the outside — see `pristineKey` below.
+
+Fields holding nothing are left out on both sides. Whether an empty field is
+absent or present-and-empty depends on when it registered, and comparing those
+would make an untouched form look changed.
+
+## What counts as already held
+
+This is the part that decides everything, and the one that surprises: a field
+can be **named, filled, and still not part of the baseline**.
+
+| what the field was given                      | held? |
+| --------------------------------------------- | ----- |
+| `value`                                       | yes   |
+| `signal` carrying something                   | yes   |
+| `signal` that is empty                        | no    |
+| `defaultValue` (and the field still shows it) | no    |
+| `defaultValue`, moved away from it            | yes   |
+| nothing                                       | no    |
+
+The rule behind the table: **a value is an answer, a default is a suggestion.**
+An age that is usually 18, a duration that is usually 1h30 — the form holds
+nothing there, and confirming the suggestion IS an answer ("yes, 18"), which
+must be sendable. A bound signal falls on whichever side its content puts it: a
+signal restored from the url or set by whoever fills the screen carries an
+answer, even when the signal also declares a default (its default only says
+where a reset goes back to).
+
+The same question is asked of a single control by `isUIStateHeld`
+(`src/control/held_ui_state.js`) — a form asks it once per field.
+
+## A screen filled after it opened: `pristineKey`
+
+The baseline is taken as soon as the fields have registered, which is right for
+a form whose values are there on the first render — and wrong for a screen that
+modifies something: the resource arrives a request later and fills the fields,
+so a form measured against what it held BEFORE that opens **already changed**.
+Its submit is live, and pressing it sends back the resource untouched.
+
+`pristineKey` takes the baseline again. Pass whatever says the filling is done:
+
+```jsx
+<Form pristineKey={game && players && places ? "loaded" : undefined}>
+```
+
+Change it **once**, when the screen is ready. Taken again after someone started
+typing, it would call what they wrote the reference.
+
+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.
+
+## A submit that says it is waiting
+
+By default a submit that sends nothing is still accepted — in a dialog or a
+slide it closes / moves on all the same. In a form that goes nowhere on its own,
+the press would visibly do nothing; `readOnlyWhileFormUnchanged` on the button
+holds it back and says what it is waiting for.
+
+```jsx
+<Button type="submit" readOnlyWhileFormUnchanged>
+  Save
+</Button>
+```
+
+## A control that is not a field
+
+A control inside a form is expected to carry a value under its name, and a
+nameless one is warned about — its state would silently stay out of what is
+sent. A control that only opens something (a picker whose popup draws a shape, a
+row whose value is carried by a hidden input beside it) says so with
+`allowNameless`:
+
+```jsx
+<Picker allowNameless ui={…}>
+```
+
+It is then neither collected nor complained about.
+
+## See also
+
+- [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/docs/scroll.md

@@ -226,16 +226,66 @@ All slides live in **the same grid cell**, so the box measures itself on the
 between slides — and it also means a short slide shows empty room below it. It
 is a trade, not a leak.
 
-`SlideContainer` is `flex: 0 1 auto`: it shrinks (the slides then scroll their
-own body) but never grows on its own. Growing is the caller's decision —
-`expandY`.
+**The slide IS the body.** This is the one thing to get right, and the shape
+everyone writes first gets it wrong: a `Dialog` with a `<Box body>` around the
+slides puts a scroller ABOVE them, and that scroller's content is the grid —
+measured on the tallest slide. Stand on a short slide and it carries the
+scrollbar of a neighbour, scrolling through emptiness.
+
+```jsx
+// WRONG — the dialog's body scrolls the tallest slide, on every slide
+<Dialog maxHeight="min(80vh, 640px)">
+  <Box header>tabs</Box>
+  <Box body>
+    <SlideContainer>
+      <Slide padding="l">…</Slide>
+    </SlideContainer>
+  </Box>
+</Dialog>
+
+// RIGHT — the cap stays a constraint, each slide scrolls its own content
+<Dialog maxHeight="min(80vh, 640px)" flex="y">
+  <Box header flexShrink="0">tabs</Box>
+  <SlideContainer>
+    <Slide overflow="auto">
+      <Box header padding="m">…</Box>  {/* the slide scrolls: padding on the parts */}
+      <Box body padding="l">…</Box>
+    </Slide>
+  </SlideContainer>
+</Dialog>
+```
+
+Why it then behaves: the cap on the height comes from above and must reach the
+slides as a **constraint**, never as a scroller. `SlideContainer` is
+`flex: 0 1 auto` — it shrinks into what is left (growing is the caller's
+decision, `expandY`) — the grid hands that height to **every** slide, and a
+slide with an `overflow` of its own scrolls only when ITS content is taller than
+that. The tall slide scrolls; the short ones are tall boxes with a short content
+in them, which is what one wants: they take the height the context imposes and
+ignore the height of their neighbour.
+
+So: nothing scrollable between the cap and the slides. A `<Box body>` around
+them is a scroller (see the table at the top of this file) — and so is a bare
+`overflow="auto"` on a wrapper. The dialog keeps a shared `header` if the tabs
+are shared, with an explicit `flexShrink="0"` since the rule that gives it for
+free lives inside `[data-scrollable]`.
+
+**Padding goes on the slide** — or on its parts, since the slide is now the
+scroller (see the top of this file) — but never on the container nor on
+anything above it.
+Overflow clips at the _padding_ edge, so a padding on the container is a band
+the clipping does not cover: the arriving slide is seen there before it has
+reached the frame. And a padding above the slides does not travel — the two
+contents cross each other flush, instead of each arriving already inset. On the
+slide, the inset travels with what it insets.
 
 Pass `travelByKeyboard={false}` when the arrow keys belong to the content (a list
 one walks through, a picker whose slides are steps): otherwise the right arrow
 changes screen mid-reading.
 
 Reference: `src/layout/dialog.jsx`, `src/layout/popover.jsx`,
-`src/layout/slide_container.jsx`.
+`src/layout/slide_container.jsx`, and the "One slide much taller than the
+others" case in `src/layout/demos/8_slide_container_demo.html`.
 
 ## Hover while scrolling
 

package/docs/z_index.md

@@ -97,6 +97,47 @@ What to read from it:
   `isolation: isolate` on the parent instead, and the number stops meaning
   anything outside it.
 
+### A sticky part is only in the band while it is stuck
+
+`--navi-z-index-sticky` says "kept stuck while something scrolls under it", and
+the second half of that sentence is a condition, not decoration. A `List` group
+label at rest is a block in the flow: nothing passes under it, and painting it
+at 10 there is what slices a focus ring, a badge or a stamp that a neighbouring
+row lets out of its box — including a `Group` member raising itself to 1 or 2.
+
+CSS cannot express the condition. There is no `:stuck`, and
+`@container scroll-state(stuck: top)` styles a container's **descendants**, so
+an element can never read its own stuck state — which is the one that matters
+here. So `List` measures it and marks its three sticky parts
+(`.navi_list_item_header`, `.navi_list_item_footer`,
+`.navi_list_item_group_label`) with `navi-stuck`, against its own scroller and
+not the window, updated on scroll, on resize, and on every commit (a virtualized
+list changes which labels exist without anything scrolling).
+
+navi's own rule is the first reader: the band applies under `[navi-stuck]`,
+`auto` applies at rest. That is what puts the decision back within reach of an
+app — a card whose badge overflows into the label below it gets past it with a
+literal in the card, against its own neighbour, exactly as §1–3 above ask:
+
+```jsx
+// Reaches past a label at rest (auto), loses to one that is stuck (10).
+<Stamp style={{ position: "absolute", bottom: "-12px", zIndex: 1 }} />
+```
+
+There was no such value before: a label sat at 10 whether or not it was stuck,
+so nothing a card could write got past it.
+
+For what a literal cannot reach, each part has a pair of variables —
+`--list-header-z-index`, `--list-footer-z-index`, `--list-group-label-z-index`,
+each with a `-stuck` counterpart defaulting to the band — settable on `<List>`
+with no selector and no navi class name. Reach for them last, and remember a
+negative value is compared against the page like any other: without a stacking
+context between the label and the nearest opaque background, `-1` does not put
+the label behind the rows, it puts it behind that background and out of sight.
+
+See the "Sticky parts" chapter of
+[12_list_demo.html](../src/control/demos/12_list_demo.html).
+
 ### Why a `Group` member is not isolated
 
 `Group` overlaps its members by one border width, so the one the user is on has

package/package.json

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