@jsenv/navi 0.29.45 → 0.29.47

package/docs/create_and_edit.md

@@ -0,0 +1,468 @@
+# Creating a resource, then editing it
+
+The loop almost every application has: a screen that creates something, the page
+of the thing just created, and a screen that edits it. It is worth a page of its
+own because what makes it hard is not the form — it is that **the two screens
+look like the same form and are not the same thing at all**: one holds a draft
+the person is writing, the other holds a resource the server owns.
+
+Working example:
+[../src/control/demos/integration/create_then_edit/create_then_edit.html](../src/control/demos/integration/create_then_edit/create_then_edit.html)
+— the whole loop, with a backend on the page answering by hand so the loading
+and the failures can be looked at.
+
+- [What the loop owes the person](#what-the-loop-owes-the-person)
+- [The routes](#the-routes)
+- [The resource](#the-resource)
+- [Two screens, two states](#two-screens-two-states)
+- [The edit screen opens before its values](#the-edit-screen-opens-before-its-values)
+- [A field that picks from a list too big to load](#a-field-that-picks-from-a-list-too-big-to-load)
+- [Where each screen goes next](#where-each-screen-goes-next)
+- [After a write: what goes back to the network](#after-a-write-what-goes-back-to-the-network)
+- [Movement between them](#movement-between-them)
+
+## What the loop owes the person
+
+The rules below are what the rest of this page is for. Each one is a decision
+about what the person is owed, not about navi.
+
+- **Creating lands on what was created.** Going back to the list after a
+  creation asks the person to find their own thing to be sure it exists; the
+  thing itself is the proof, and it is also where they were heading.
+- **A draft is theirs until it is sent, and not a minute longer.** Half a form
+  filled must survive a reload (it is in the url), and must be gone the next
+  time "create" is opened — a create screen showing the last thing created is a
+  screen nobody trusts.
+- **Saving goes back to the thing, and so does a press that had nothing to
+  send.** The person is done either way; refusing to move because "nothing
+  changed" makes them press again to find out why.
+- **Cancelling puts back what the server says**, not what was typed and
+  abandoned. What leaving with unsaved changes does is a decision each screen
+  takes: dropping them is right when they are a few fields the person chose to
+  leave (that is what the shape below does, for free — the screen is thrown
+  away), and worth a confirmation when they are half an hour of work.
+- **What was written shows up everywhere at once.** A name changed on one screen
+  and stale on the list two seconds later reads as data loss. Some of that is
+  free (the store), some of it is a request the backend has to answer (a list
+  after a creation) — see [after a write](#after-a-write-what-goes-back-to-the-network).
+- **A failure is shown where the thing was asked for**, with what was typed
+  still there: an error on a form that emptied itself is worse than the failure.
+- **Every screen is a url.** Reload, back, a link sent to someone — the screens
+  of this loop are places, and the movement between them says how they are
+  related.
+
+Each of them has a mechanism below, and each mechanism is a line of code, not a
+framework.
+
+## The routes
+
+Four places, and each of them is a url someone can open, reload or share:
+
+```js
+const HOME_ROUTE = route("/");
+const NEW_GAME_ROUTE = route("/games/new", {
+  searchParams: {
+    name: nameSignal,
+    level: levelSignal,
+    players: playersSignal,
+  },
+});
+const GAME_ROUTE = route("/games/:gameId");
+const EDIT_GAME_ROUTE = route("/games/:gameId/edit");
+setupRoutes([HOME_ROUTE, NEW_GAME_ROUTE, GAME_ROUTE, EDIT_GAME_ROUTE]);
+```
+
+The create screen declares its fields as **search params**: a draft that
+survives a reload and travels in a link. The edit screen declares none — its
+values belong to the resource, not to the position.
+
+Two facts about matching decide the rest, and both surprise:
+
+- **Several routes match at once.** A route matches by prefix, so `/` is still
+  matching on `/games/2/edit`, and `/games/new` is also a `/games/:gameId`.
+  That is what keeps a section active while one is inside it.
+- **The first that matches wins**, in the order it is written — the `<Route>`
+  children, and the pages of a travel row alike. So they go from the most
+  precise to the widest:
+
+```jsx
+<Route>
+  <Route route={EDIT_GAME_ROUTE} element={EditGamePage} />
+  <Route route={NEW_GAME_ROUTE} element={NewGamePage} />
+  <Route route={GAME_ROUTE} element={GamePage} />
+  <Route route={HOME_ROUTE} element={HomePage} />
+</Route>
+```
+
+Same thing for what a route LOADS: the loader of `/games/:gameId` must step
+aside on `/games/new`, which is a page and not a game.
+
+```js
+const GAME_OF_ROUTE = routeAction(
+  [GAME_ROUTE, EDIT_GAME_ROUTE],
+  GAME.GET,
+  () => {
+    if (NEW_GAME_ROUTE.matchingSignal.value) {
+      return null; // "new" is not an id
+    }
+    const gameId =
+      GAME_ROUTE.paramsSignal.value.gameId ||
+      EDIT_GAME_ROUTE.paramsSignal.value.gameId;
+    return gameId ? { id: gameId } : null;
+  },
+);
+```
+
+## The resource
+
+Declare the REST callbacks once ([resource.md](./resource.md)) and the store
+does the rest — this is what makes the detail page show the new name **the
+moment the PUT answers**, with nobody reloading anything:
+
+```js
+const GAME = resource("game", {
+  GET: ({ id }) => api.readGame(id),
+  GET_MANY: () => api.readGames(),
+  POST: (values) => api.createGame(values),
+  PUT: ({ id, ...values }) => api.updateGame(id, values),
+});
+```
+
+Two things to know or the screen stays empty:
+
+- **Reading an action does not start it.** `useAsyncData` waits for data
+  someone else asked for; what asks is the route (`routeAction`). A component
+  reading an action nobody runs suspends forever, and the whole `<Loading>`
+  subtree stays blank.
+- **Handle the error where it happens**, or hand it to an `<ErrorBoundary>`:
+  `useAsyncData(action, { loading: true, error: true })` returns
+  `[data, loading, error]`, which is what lets a page draw its own "the server
+  refused" with a "try again" that calls `action.rerun()`.
+
+## Two screens, two states
+
+The same three fields, and two different things behind them:
+
+- the **create** screen holds a **draft** — nobody else's, not saved anywhere,
+  worth keeping while it is being written. It belongs in the url
+  (`searchParams`), which is what makes it survive a reload and travel in a
+  link;
+- the **edit** screen holds **what the server has**, loaded, and proposes
+  changes to it. It is the screen's own state, alive as long as the screen is.
+
+So the fields are written once, and know nothing about which screen they are in:
+
+```jsx
+const GameFormFields = ({
+  nameSignal,
+  levelSignal,
+  playersSignal,
+  loading,
+}) => (
+  <>
+    <Input name="name" signal={nameSignal} loading={loading} required />
+    <Select name="level" signal={levelSignal} loading={loading}>
+      …
+    </Select>
+  </>
+);
+```
+
+Each screen hands it its own:
+
+```jsx
+// créer: le brouillon, qui vit dans l'url
+<GameFormFields
+  nameSignal={draftNameSignal}
+  levelSignal={draftLevelSignal}
+  playersSignal={draftPlayersSignal}
+/>;
+
+// modifier: ceux de cet écran-ci, remplis quand la partie arrive
+const nameSignal = useSignal(undefined);
+```
+
+**Do not let the two share one set of signals.** It is the mistake this shape
+exists to prevent, and it does not look like one: bind both screens to the same
+`nameSignal`, edit a game, then press "create" — the game you just edited is
+sitting in the create form, and in the url. A draft and a resource are not the
+same state; one is on the screen, the other is at the backend.
+
+The draft's other half is the end of its life:
+
+```jsx
+action={async (values) => {
+  const game = await GAME.POST.bindParams(values).rerun();
+  GAME_ROUTE.navTo({ gameId: game.id });
+  draftNameSignal.value = undefined; // il a servi
+  draftLevelSignal.value = undefined;
+}}
+```
+
+`undefined`, not `""`: a state signal put back to undefined returns to its
+default and leaves the url — see [control_value.md](./control_value.md).
+
+**Clear after navigating, not before.** Those signals are read by things on the
+screen being left — the list of places is asked for with the place the draft
+holds — so emptying them while that screen is still up asks for the list again,
+for a screen nobody is looking at any more. Navigate first and the clearing is
+what it should be: tidying up behind oneself.
+
+> One signal for the whole form works too: `<Form signal={gameSignal}>` fills
+> its named children from the object, follows it when something else writes it,
+> and writes back the whole object as the fields change. Reach for it when the
+> values arrive as one object and no field needs a url of its own — the fields
+> then take nothing but their `name`.
+
+## The edit screen opens before its values
+
+The resource arrives a request after the screen. Two shapes, and both are
+right — the question is what the person should be looking at meanwhile:
+
+**The screen waits, showing the form.** The fields are there, empty and busy
+(`loading` on a control marks it `aria-busy` and shows it), and they fill in
+when the resource lands. Nothing blinks in and out, and a long screen does not
+collapse to a spinner. What it costs is one thing to say — **when the filling is
+done**:
+
+```jsx
+const [game, loading, error] = useAsyncData(GAME_OF_ROUTE, {
+  loading: true,
+  error: true,
+  onLoad: (game) => {
+    nameSignal.value = game.name;
+    levelSignal.value = game.level;
+  },
+});
+
+<Form pristineKey={game?.id}>;
+```
+
+`onLoad` is what the screen does with the data **once, when it becomes known**,
+and the two hard parts are already answered by it:
+
+- **How often.** Not every time the data arrives — a successful PUT, a list
+  reloading, a poll all hand the same game back, and copying it again would
+  overwrite what the person is in the middle of writing. It fires once per set
+  of params, which is the action's own answer to "is this another thing, or the
+  same one again". Written by hand this is a `useEffect` keyed on `game?.id`,
+  and `[game]` is the natural, wrong, thing to write.
+- **When.** From a layout effect, so what it writes belongs to the same tick as
+  the render that got the data. That is what lets `pristineKey` be the id
+  itself: the form takes its reference again at the end of that tick, and by
+  then the fields are filled. A copy written in a passive effect (after the
+  paint) would be too late — the screen would open **already changed**, and Save
+  would send the resource back to the server untouched.
+
+The rest of `pristineKey` is in [form_changed.md](./form_changed.md).
+
+**Or the screen waits, showing nothing of the form**: render a skeleton until
+the resource is there, then the form with its values already in the fields.
+Nothing to announce then — the form holds them from its first render — but the
+screen has to be one that can be blanked without the person losing their place.
+
+Either way, cancelling is a link away: the screen is thrown away with what was
+typed in it, and coming back re-reads the resource. There is nothing to restore.
+
+## A field that picks from a list too big to load
+
+A place, a player, a category: the field is a picker, and its popup holds a list
+the backend answers with. The list is **one page** — the nearest, the most
+recent, whatever a `LIMIT` returned. And the screen is pre-filled from the url:
+
+```
+/games/new?place=halle-des-sports
+```
+
+That is what pre-filling is: a link from a place's page, a back button, a
+reload, a shared invitation. The signal is the selection, and the url is its
+memory. But the url carries an **identifier and nothing else** — no name — so
+the screen looks for it in the list it has:
+
+```js
+const selected = places.find((place) => place.id === placeId);
+```
+
+Nothing guarantees that `find`. The place may be far down the ranking, created
+by someone else a minute ago, or named in a link built elsewhere. Nothing is
+broken — the screen falls back on the identifier — but it then shows
+`halle-des-sports` where it promised "Halle des sports", which is the opposite
+of what pre-filling was for. Rare, never seen in development, and always at
+someone else's.
+
+Two ways out, and only one of them keeps the feature:
+
+- **Clear the signals when the screen opens.** No selection, no selection to
+  display. This throws away pre-filling, which is the reason those params exist:
+  removing a feature is not fixing its edge case.
+- **Ask for the list SAYING what you already hold.** What the screen holds
+  travels with the request, and the backend guarantees that item is in the
+  answer — on top of its page, whatever its rank.
+
+```js
+const PLACES_OF_SCREEN = routeAction(
+  [NEW_GAME_ROUTE, EDIT_GAME_ROUTE],
+  PLACE.GET_MANY,
+  // pas `() => true`: ce que l'écran tient déjà doit voyager avec la demande
+  () => {
+    // en création: l'url, connue tout de suite
+    if (NEW_GAME_ROUTE.matchingSignal.value) {
+      return { include: draftPlaceSignal.value };
+    }
+    // en modification: elle arrive avec la ressource
+    const game = GAME_OF_ROUTE.dataSignal.value;
+    return game ? { include: game.placeId } : null;
+  },
+);
+```
+
+Reading the selection in the params is also what makes the list **reload when
+the selection changes** — the action reruns on its own. Which is why the edit
+screen returns `null` until the resource is there: asking for the list before
+knowing what it must contain is asking for it twice, and the first answer is the
+one that cannot show the name.
+
+What `include` is, on the backend side, is the whole subject:
+
+- **an addition, not a filter.** The page stays the page; the asked-for item is
+  in it as well if it was not already, and once if it was;
+- **it takes what a url can hold** — a slug as much as an id;
+- **an `include` that designates nothing is not an error.** The answer is simply
+  the page, and the screen falls back on its "not found" case — which then says
+  something true (that place is gone) instead of being an artefact of
+  pagination;
+- it takes **several** values when several fields are pre-filled:
+  `GET /users?include=42,57`.
+
+> If a url signal designates an item of a paginated list, the identifier it
+> carries must travel with the list request, and the backend must guarantee its
+> presence in the answer. A paginated list is not "the first N", it is "the first
+> N **plus what the caller already holds**".
+
+The other half of the same problem is answered by the resource rather than by
+the list: **what comes back with a resource carries its own label**. The game's
+own page shows "Lieu: Halle des sports" with no list at all, because the GET
+answers with the name next to the id. Only the url is reduced to an identifier,
+and that is exactly where `include` earns its place.
+
+## Where each screen goes next
+
+The two screens navigate for opposite reasons, and that is why they say it in
+two different places:
+
+- **Create**: the page to land on is the one the server just made, and its id
+  comes back with the response. Nothing can be declared before the send, so the
+  action navigates:
+
+  ```jsx
+  <Form
+    action={async (values) => {
+      const game = await GAME.POST.bindParams(values).rerun();
+      GAME_ROUTE.navTo({ gameId: game.id });
+    }}
+  >
+  ```
+
+- **Edit**: the destination is known before the send — and it has to be, because
+  a press with **nothing to send** must leave too. That is `command`, which runs
+  whether or not there was an action to run:
+
+  ```jsx
+  <Form
+    command={`--navi-nav-to:${GAME_ROUTE.buildUrl({ gameId: game.id })}`}
+    action={(values) => GAME.PUT.bindParams({ id: game.id, ...values }).rerun()}
+  >
+  ```
+
+  Do not hold that submit back with `readOnlyWhileFormUnchanged`: the press
+  still does something — it leaves. Holding it back is for a form that goes
+  nowhere, where the press would visibly do nothing at all.
+
+## After a write: what goes back to the network
+
+Creating one game, measured on the demo:
+
+```
+POST /games     la création
+GET  /games     la liste se relit
+GET  /games/2   la page de ce qui vient d'être créé
+```
+
+Each of the two GETs is a decision, and neither is an accident:
+
+- **The list re-reads itself** because whether a new item belongs to a list
+  depends on filters, pagination and sort — the backend knows, the client does
+  not (`rerunOn.GET_MANY: ["POST"]`, and the whole table of defaults is in
+  [list_refresh.md](./list_refresh.md)). A `PUT` does **not** re-read it: the
+  store carries the new values into every list already holding that item, which
+  is why the name changed on the game's page shows up on the list without a
+  request.
+- **The detail GET is not saved by the store.** The action for that id had never
+  run, and the store holding the item is not the same thing as an action having
+  its data. It is also often not redundant: a detail representation is richer
+  than what a write answers — here the GET adds the place's name, the POST does
+  not, and a screen trusting the POST would show "Lieu: —". Skipping it could
+  only ever be a per-resource decision ("my POST answers the same shape as my
+  GET").
+
+Coming back to that page later in the same session costs **nothing**: an action
+that has completed is not run again for the same params. That, and not any
+cache, is what makes a screen already visited open instantly — and what a
+`rerun()` is for when something must genuinely be read again.
+
+## Movement between them
+
+The screens are places, so the movement between them is `RouteTravel` — not
+`SlideContainer`, which is for positions with no url (see
+[navigation.md](./navigation.md#tabs-with-no-url)).
+
+A row says two things at once, and they are said apart. Its `<Route>` children
+are ordered by matching precision (above); `routes` is the order of the
+**journey** — what "one step that way" means:
+
+```jsx
+<RouteTravel routes={[NEW_GAME_ROUTE, GAME_ROUTE]}>
+```
+
+Creating sits to the left of the game, so arriving on what was just created goes
+right ("here is what I just made"). **A page left out of `routes` does not
+travel at all**: the list is not a step along this row — one opens the create
+screen from it, one does not slide there — so it is absent, and that move has no
+animation. Leaving a page out is how a movement is refused; there is no "no
+transition" to ask for.
+
+A pair with a movement of its own gets a row of its own, on its own axis. The
+game and its edit screen are the same thing seen two ways, so they travel
+vertically inside the position the outer row holds for them:
+
+```jsx
+const GameArea = () => (
+  <RouteTravel axis="y" routes={[EDIT_GAME_ROUTE, GAME_ROUTE]}>
+    <Route>
+      <Route route={EDIT_GAME_ROUTE} element={EditGamePage} />
+      <Route route={GAME_ROUTE} element={GamePage} />
+    </Route>
+  </RouteTravel>
+);
+```
+
+Editing sits above the game on that column, so it comes down over it and saving
+sends it back up. The outer row does not move for it: both urls are the same position
+there, which is what makes the two rows independent —
+
+```jsx
+<Route route={EDIT_GAME_ROUTE} element={GameArea} />
+<Route route={GAME_ROUTE} element={GameArea} />
+```
+
+— the same element on both branches, so the inner row stays mounted across the
+two and has something to travel between.
+
+The gesture, the back button and a link pressed all move the same way.
+
+## See also
+
+- [form_changed.md](./form_changed.md) — what a form sends, what follows a send
+- [navigation.md](./navigation.md) — routes, links, travelling
+- [resource.md](./resource.md) — the store behind GET/POST/PUT
+- [control_value.md](./control_value.md) — binding fields to signals

package/docs/css_architecture.md

@@ -65,6 +65,57 @@ Props are the primary way to customize appearance. They translate to inline `sty
 <Button style={{ "--button-height": "48px" }} />
 ```
 
+#### Variants set defaults, never resolved values
+
+A control resolves each styled property in two steps: the public variable
+holds what was asked for (`--picker-background-color`), and an internal
+`--x-` variable holds what is finally painted, per state:
+
+```css
+.navi_picker {
+  --x-picker-background-color: var(--picker-background-color);
+
+  &[data-hover] {
+    --x-picker-background-color: var(--picker-background-color-hover);
+  }
+}
+```
+
+A variant (`icon`, `discrete`, `bare`, `border`, `headless`…) describes what
+the caller did **not** say, so it writes the public variable — the default —
+and never the `--x-` one:
+
+```css
+&[data-variant="icon"] {
+  /* ✅ a default: a backgroundColor prop, being inline on this same element, wins */
+  --picker-background-color: transparent;
+  /* ❌ a verdict: the prop is read, translated, and then thrown away */
+  --x-picker-background-color: transparent;
+}
+```
+
+Writing `--x-` from a variant is the one failure mode that costs real time to
+diagnose: the prop is accepted, it reaches its variable with the right value,
+and nothing happens. A prop silently without effect is worse than a prop
+refused.
+
+Two things come with moving the default:
+
+- the **per-state** variables are derived from the base one by formula
+  (`hover` = 5% black over the background, `disabled` = 5% grey), so a variant
+  that clears the background must re-point them at the base
+  (`--picker-background-color-hover: var(--picker-background-color)`), or a box
+  reappears on hover under a control that is supposed to have none. When the
+  variant does have a resting movement, express it as a mix **into** the
+  background (`color-mix(in srgb, currentColor 8%, var(--picker-background-color))`)
+  rather than a replacement, so it still composes with a color the caller gave.
+- a variable fed by another prop keeps that chain in its fallback:
+  `--button-background-color: var(--button-background, transparent)` leaves both
+  `background` and `backgroundColor` working.
+
+The same holds for sizing: a variant lowers `--picker-padding-x-default`, not
+`--x-picker-padding-left`.
+
 ### 2. CSS variables (for global or theme-level changes)
 
 When the same change applies to many components (e.g. a design token update), set the variable at a higher scope:
@@ -200,3 +251,4 @@ Overriding the actual CSS rules (not the variables) is intentionally hard — th
 | 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)                                     |
+| What a variant decided       | A prop — a variant only ever moves defaults, so props keep winning         |

package/docs/form_changed.md

@@ -176,4 +176,6 @@ It is then neither collected nor complained about.
   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
+- [create_and_edit.md](./create_and_edit.md) — the create/edit loop this is
+  half of: routes, the resource, and where each screen goes next
 - [actions.md](./actions.md) — what an action does around the send itself

package/docs/navigation.md

@@ -248,6 +248,13 @@ read from the children in the order they are written. Pass `routes` only to say
 another order, or when the pages are not children of the box. An entry is a route,
 or `{ route, params }` when the tabs are params of one route.
 
+The row is on the **first** of its pages that matches, the way a `<Route>` shows
+its first matching branch — several routes match at once when one is a case of
+another. A page left out of the row does not travel: reaching it is a change of
+place, not a step along the row, and it plays no movement. `axis="y"` lays the
+pages out as a column instead: forward is then the page rising and the next one
+coming up from below.
+
 A swipe **replaces** the current history entry (a gesture browses; a tab pressed
 aims at a place and pushes, which its `<Link>` already does). `onTravel` decides
 otherwise.
@@ -260,6 +267,14 @@ Demo: [../src/nav/demos/route_travel/route_travel.html](../src/nav/demos/route_t
 and [../src/nav/demos/tabs/tabs.html](../src/nav/demos/tabs/tabs.html). The full
 spec of the gesture is [drag_to_travel.md](./drag_to_travel.md).
 
+## Creating something, then editing it
+
+The create screen, the page of what was created, the edit screen — three routes,
+one form, and a movement between them. It is assembled in
+[create_and_edit.md](./create_and_edit.md), which is also where the two matching
+rules that decide the shape of the `<Route>` tree are spelled out (several routes
+match at once; the first matching branch wins).
+
 ## Tabs with no URL
 
 `SlideContainer` holds slides that replace one another in one box, with the same

package/docs/scroll.md

@@ -46,9 +46,17 @@ Two consequences worth knowing before fighting them:
 - the body is `flex: 0 1 auto` — **it shrinks, it never grows**. A short body
   leaves the footer right under it rather than pushed to the bottom of a box it
   does not fill. Adding `expandY` to "fix" that is undoing a deliberate default.
-- the separating line is a `box-shadow`, not a `border`: it draws without taking
-  part in layout, so nothing shifts by a pixel when it appears. Don't add a
-  border of your own — you get two lines.
+- the separating line is a `border-bottom` on the header (`border-top` on the
+  footer). Don't add a border of your own — you get two lines. It used to be a
+  `box-shadow`, which is drawn outside the box and so lost to whatever was
+  painted after it: the body covered the very line meant to separate them.
+- header and footer sit in the sticky band
+  (`var(--navi-z-index-sticky)`), so everything the box contains passes under
+  them — positioned or not. Write `style={{ "--box-header-z-index": "auto" }}`
+  (`--box-footer-z-index` likewise) at the call site that needs the opposite: a
+  badge or a stamp overflowing a row is otherwise sliced by a header it never
+  scrolls under. `isolation: isolate` on the box keeps either value local to it.
+  See `docs/z_index.md` and `src/box/demos/9_scrollable_z_index_demo.html`.
 
 Padding belongs on the parts, not on the scrolling box: padding on a scroller
 sits inside the scrollbars, and a control flush against the edge of a scrolling
@@ -56,7 +64,8 @@ area raises a scrollbar of its own (a focus outline is drawn outside the control
 it belongs to).
 
 Reference: `src/box/box.jsx` (the `[data-scrollable]` CSS),
-`src/box/demos/8_scrollable_demo.html`.
+`src/box/demos/8_scrollable_demo.html`,
+`src/box/demos/9_scrollable_z_index_demo.html` (sticky parts and stacking).
 
 ## 1. The document scrolls
 
@@ -183,7 +192,7 @@ everyone else does, by asking for the overflow — and it already asks, on itsel
 So the parts are direct children of the `Dialog`:
 
 ```jsx
-<Dialog id="…" dockedOnTouch scrollCapture>
+<Dialog id="…" dockedOnSmallTouchScreen scrollCapture>
   <Box header>title + close</Box>
   <Box body>
     <List scroller="parent" /> {/* NOT "self" */}

package/docs/z_index.md

@@ -74,14 +74,14 @@ file is the overview, this table is its summary. Bands are a decade apart so
 one can grow without reaching the next, and so a value seen in devtools says
 which band it came from.
 
-| Band                                                                                           | Token                                                              | Value                        |
-| ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | ---------------------------- |
-| Top layer (`Dialog`/`Popover` with `layer="top"`)                                              | —                                                                  | above everything             |
-| `Dialog`/`Popover` with `layer="local"`, their backdrop, callouts                              | `--navi-z-index-popup`, `--navi-z-index-callout`                   | 1000 `+ stack order`         |
-| `FixedBar`                                                                                     | `--navi-z-index-bar`                                               | 100                          |
-| Sticky while something scrolls under: `List` header/footer/group labels, `SidePanel` head/foot | `--navi-z-index-sticky`                                            | 10                           |
-| A `Group` member under the pointer, then the one holding focus                                 | `--navi-z-index-control-hovered`, `--navi-z-index-control-focused` | 1, 2                         |
-| `Table` sticky cells, drag, resize                                                             | `src/control/table/z_indexes.js`                                   | 1–7, derived from each other |
+| Band                                                                                                                | Token                                                              | Value                        |
+| ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | ---------------------------- |
+| Top layer (`Dialog`/`Popover` with `layer="top"`)                                                                   | —                                                                  | above everything             |
+| `Dialog`/`Popover` with `layer="local"`, their backdrop, callouts                                                   | `--navi-z-index-popup`, `--navi-z-index-callout`                   | 1000 `+ stack order`         |
+| `FixedBar`                                                                                                          | `--navi-z-index-bar`                                               | 100                          |
+| Sticky while something scrolls under: `List` header/footer/group labels, `SidePanel` head/foot, `Box` header/footer | `--navi-z-index-sticky`                                            | 10                           |
+| A `Group` member under the pointer, then the one holding focus                                                      | `--navi-z-index-control-hovered`, `--navi-z-index-control-focused` | 1, 2                         |
+| `Table` sticky cells, drag, resize                                                                                  | `src/control/table/z_indexes.js`                                   | 1–7, derived from each other |
 
 What to read from it:
 
@@ -138,6 +138,19 @@ 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).
 
+`Box`'s own `header`/`footer` take the opposite default, and for a reason worth
+knowing: they are in the band **always**, not only while stuck. `List` can tell
+— it measures its parts against its own scroller. A `Box` cannot: it is the
+generic scrolling area, its content is whatever the app puts in it, and a
+sticky part that drops to `auto` loses to anything that content positioned, a
+`transform` or an `opacity` below 1 included. So the band is the default,
+`isolation: isolate` on the scrolling box keeps it local, and
+`--box-header-z-index` / `--box-footer-z-index` write it back to `auto` at the
+one call site that knows nothing inside is positioned.
+[9_scrollable_z_index_demo.html](../src/box/demos/9_scrollable_z_index_demo.html)
+shows the band, what `auto` would look like, and what the band costs, side by
+side.
+
 ### 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.45",
+  "version": "0.29.47",
   "type": "module",
   "description": "Library of components including navigation to create frontend applications",
   "repository": {