@jsenv/navi 0.29.387 → 0.29.389

package/docs/popup_open.md

@@ -91,7 +91,7 @@ where that state lives:
 
 | what opens it                      | how                                                    |
 | ---------------------------------- | ------------------------------------------------------ |
-| a button                           | `command` / `commandfor` attributes, no `open`         |
+| a button                           | `command` / `commandFor` props, no `open`              |
 | a gesture, an event, a JS decision | `triggerNaviCommand(...)`, still no `open`             |
 | a state the app holds              | `signal` — [below](#when-the-app-holds-the-open-state) |
 | where the user is                  | `navState`, or a route `stateSignal` given to `signal` |
@@ -99,7 +99,7 @@ where that state lives:
 ## A button opens it: the attributes
 
 ```jsx
-<Button command="--navi-open" commandfor="note-dialog">
+<Button command="--navi-open" commandFor="note-dialog">
   Read the note
 </Button>
 <Dialog id="note-dialog">…</Dialog>
@@ -123,7 +123,7 @@ press:
 ## Something else opens it: `triggerNaviCommand`
 
 The attributes fire on every click of the element that carries them, and they
-cover more than "this button opens that dialog": `commandfor` says to whom,
+cover more than "this button opens that dialog": `commandFor` says to whom,
 `value` says what it is about, `--navi-x:argument` says how. Before writing any
 JS here, check none of those is the answer — `triggerNaviCommand` is the last
 resort, not the general way to run a command.
@@ -209,7 +209,7 @@ closes the popup as usual.
 
 ```jsx
 <Row
-  commandfor="row_menu"
+  commandFor="row_menu"
   interactions={{
     longpress: (event) =>
       triggerNaviCommand(event.target, "--navi-open", event),
@@ -225,7 +225,8 @@ own opening press from somebody else's comes from that gesture.
 The first argument is the command's **source** — the element it is triggered
 _from_. The target is resolved from it, in this order:
 
-1. `commandfor="someId"` on the source,
+1. `commandFor="someId"` on the source (written to the DOM as the HTML
+   `commandfor` attribute, which is what is read),
 2. `navi-command-target="parent-control" | "child-control"`,
 3. the command's own fallback — for the popup commands, `closest("[aria-expanded]")`.
 
@@ -234,7 +235,7 @@ element itself as the source resolves to that popup: `closest()` starts at the
 element itself. That is the short form used above, and it is enough whenever the
 JS that decides already holds the popup's ref.
 
-To trigger from another element instead, give that element a `commandfor`
+To trigger from another element instead, give that element a `commandFor`
 pointing at the popup's `id` — attribute-driven target resolution, JS-driven
 timing.
 
@@ -250,10 +251,11 @@ names none, and on whoever asked when nothing else says. In that order:
 3. **`detail.source`** — who asked. A button therefore opens the popup on
    itself, and a popup passed as its own source is its own anchor.
 
-For `Dialog` the anchor does nothing at all unless `sizeFromAnchor` is passed
-(then, and only then, it feeds the `--anchor-width`/`--anchor-height` CSS vars);
-for `Popover`, which really is positioned relative to its anchor, say what the
-anchor is:
+For `Dialog` the anchor does nothing at all unless `sizeFromAnchor` asks for
+it (it then feeds the `--anchor-width`/`--anchor-height` CSS vars) or
+`animation="lifting"` does (the box the dialog comes out of, see
+[popup_lift.md](./popup_lift.md)); for `Popover`, which really is positioned
+relative to its anchor, say what the anchor is:
 
 ```jsx
 <Popover ref={popoverRef} anchor={rowRef}>
@@ -261,8 +263,9 @@ anchor is:
 
 `anchorCustomEventDetail="ignore"` drops the open's side of that order
 entirely, leaving the `anchor` prop alone — for a popover that must never be
-anchored to whatever opened it (`SidePanel` does this), and for a
-`sizeFromAnchor` dialog that must never be sized from it.
+anchored to whatever opened it (`SidePanel` does this), and for a dialog that
+must never be sized from it (`sizeFromAnchor`) or lifted out of it
+(`animation="lifting"`).
 
 ## Opening it ON something
 
@@ -272,8 +275,8 @@ row is one dialog with two modes, and the press is the only thing that knows
 which one — so the press says it, with its own value:
 
 ```jsx
-<Button command="--navi-open" commandfor="radar-dialog">Nouveau radar</Button>
-<Button value={radar.id} command="--navi-open" commandfor="radar-dialog" />
+<Button command="--navi-open" commandFor="radar-dialog">Nouveau radar</Button>
+<Button value={radar.id} command="--navi-open" commandFor="radar-dialog" />
 
 <Dialog
   id="radar-dialog"
@@ -629,7 +632,7 @@ command once it succeeded.
 ```jsx
 // Stays open while save() runs, closes when it resolves, stays open if it
 // throws — with what was typed still there and the error on the button.
-<Button command="--navi-close" commandfor="note-dialog" action={save}>
+<Button command="--navi-close" commandFor="note-dialog" action={save}>
   Save
 </Button>
 ```
@@ -689,12 +692,12 @@ the popup without closing it, and the error callout stays where the press was.
 The gestures that close a popup do not all mean the same thing, and that is on
 purpose:
 
-| gesture                        | what it means | who decides                       |
-| ------------------------------ | ------------- | --------------------------------- |
-| Escape                         | cancel        | `escapeEffect="cancel"` (default) |
-| a press outside                | close, keep   | `pressOutside="close"` (default)  |
-| a close cross (`--navi-close`) | close, keep   | [the cross](#the-close-cross)     |
-| `--navi-cancel` on a button    | cancel        | the button                        |
+| gesture                        | what it means | who decides                                                                                            |
+| ------------------------------ | ------------- | ------------------------------------------------------------------------------------------------------ |
+| Escape                         | cancel        | always, for a `Dialog`/`Popover`; `escapeEffect="cancel"` (the default) for a `Picker`                 |
+| a press outside                | close, keep   | `pressOutside="close"` — the default of a `Dialog` and of a `Picker`; a bare `Popover` says `"ignore"` |
+| a close cross (`--navi-close`) | close, keep   | [the cross](#the-close-cross)                                                                          |
+| `--navi-cancel` on a button    | cancel        | the button                                                                                             |
 
 Escape says "forget it". It is the one gesture that has meant that everywhere,
 for as long as there have been dialogs, and navi keeps it that way. **A popup
@@ -757,7 +760,8 @@ empty.
 
 ### `escapeEffect="close"`, and why it is a last resort
 
-`escapeEffect="close"` makes Escape say what a click outside says. It exists,
+`escapeEffect="close"` — a `Picker` prop; a `Dialog`/`Popover` has no such
+switch — makes Escape say what a click outside says. It exists,
 and it is almost never what you want: it takes away the only key that undoes,
 and a popup with no way back is one people stop opening. Reach for a close
 cross first.
@@ -996,7 +1000,8 @@ one fill above.
 
 A press on another card is not an outside press once the card names the panel
 with `data-navi-popup-inside` (see [popup_backdrop.md](./popup_backdrop.md)).
-The full example is `src/layout/demos/7_slot_demo.html`, "two side panels".
+The full example is `src/layout/demos/7_slot_demo.html`, "Two side-panel
+slots".
 
 ## A popup that loads data
 
@@ -1116,14 +1121,20 @@ half-typed form where it left them.
 "Closed" is two states, not one — never opened yet, and closed again after an
 opening — so the `mount` prop answers both at once:
 
-| `mount`                       | before the first open | after a close |
-| ----------------------------- | --------------------- | ------------- |
-| `"always"`                    | mounted               | mounted       |
-| `"from-first-open"` (default) | not mounted           | mounted       |
-| `"while-opened"`              | not mounted           | not mounted   |
+| `mount`                       | before the first open       | after a close |
+| ----------------------------- | --------------------------- | ------------- |
+| `"always"`                    | mounted                     | mounted       |
+| `"idle"`                      | mounted once the page idles | mounted       |
+| `"from-first-open"` (default) | not mounted                 | mounted       |
+| `"while-opened"`              | not mounted                 | not mounted   |
 
 `"always"` is for content something depends on before any opening: a value read
 off it, fields a surrounding form submits, a size measured from outside.
+`"idle"` is `"always"` minus the cost on the render that draws the page.
+
+Whatever the value but `"while-opened"`, intent on the anchor — a pointer
+entering it, focus landing in it — builds the content ahead of the click that
+will open it.
 
 `"while-opened"` is what an uncontrolled field seeded from a `defaultValue`
 needs: without it, a popup reopened after the underlying value changed still

package/docs/resource.md

@@ -93,14 +93,15 @@ const GAME = resource("game", {
 ```
 
 The callback receives the bound params merged with the range the list asks for
-(`start`, `end`, `limit`, `before`, `after`, `around`, `count`), and a `signal`
-as second argument — aborted when the list stops wanting those rows. It returns
-a range the way a `Content-Range` does: **`{ items, start, count }`** — these
-rows, at this place, out of that many. `start` may be omitted when the list
-asked for a positive one; `count` defaults to `start + items.length` (a source
-that does not know its total). The items are upserted on their way in, so the
-list draws store items — never copies of the JSON — and a request sent from a
-row is read back on that row.
+(`start`, `end`, `limit`, `before`, `after`, `around`, `count`), and `{ signal }`
+as second argument — a signal aborted when the list stops wanting those rows.
+It returns a range the way a `Content-Range` does: **`{ items, start, count }`**
+— these rows, at this place, out of that many. `start` may be omitted when the
+list asked for one at or after `0` (a negative `start` counts back from the end,
+and the source must then say where the slice landed); `count` defaults to
+`start + items.length` (a source that does not know its total). The items are
+upserted on their way in, so the list draws store items — never copies of the
+JSON — and a request sent from a row is read back on that row.
 
 A row that must follow its **own fields** through a write reads them from the
 store rather than from the object it was handed:
@@ -131,9 +132,12 @@ this collection again after its screen went away finds it drawn and revalidates
 it rather than starting over
 ([list_refresh.md](./list_refresh.md#leaving-the-screen-and-coming-back)).
 
-What it does not give is membership: an item that leaves the collection stays on
-screen until the rows are asked for again. Give the screen its own way to ask
-(a refresh gesture, a `key` on the run).
+Membership is what a re-read answers: a verb listed in `rerunOn.GET_RANGE`
+(`["POST", "DELETE"]` by default) tells the run the collection moved, and it
+asks again for the window it draws, rows staying on screen meanwhile. A write
+that moves an item in or out through another verb — a `PATCH` that archives —
+is added there, or `reader.invalidate()` is called; a `key` on the run is not the
+way ([list_refresh.md](./list_refresh.md#a-paginated-list-stays-on-screen-too)).
 
 It reads a collection, so it lives on the resource itself (or on a
 `withParams()` of it), not on a relation.
@@ -252,7 +256,8 @@ These are not guessable — each relationship method has its own shape.
 
 ### `.one(propertyName, childResource, { GET, PUT, DELETE })`
 
-The callback returns the **parent** object with the child nested inside:
+`GET` and `PUT` return the **parent** object with the child nested inside;
+`DELETE` returns the parent id, or `{ id }`:
 
 ```js
 const USER_SESSION = USER.one("session", SESSION, {
@@ -411,14 +416,18 @@ rules, verified by `src/state/rest/tests/resource_graph_parent_rerun.test.js`:
   reruns the parent. Declare it explicitly with `dependencies` if you need it
   (see [`dependencies`](#dependencies-rerun-after-another-resource-writes)).
 - Within a relationship resource, the usual defaults still apply: its own
-  `GET_MANY` reruns after its own `POST`; its `GET` is reset (not rerun) by its
-  `DELETE`. Override per relation with `rerunOn`/`dependencies`, which every
-  relationship method accepts.
+  `GET_MANY` reruns after its own `POST`. A `.one`/`.many` `GET` is reset (not
+  rerun) by its own `DELETE`, as a root `GET` is; a scoped `GET` is not reset —
+  its data simply resolves to nothing once the child is dropped. Override per
+  relation with `rerunOn`/`dependencies`, which every relationship method
+  accepts; what a relation leaves out is its parent resource's (`rerunOn` key
+  by key).
 
 Splitting a sub-resource out of a parent `PATCH` therefore changes the refresh
-graph: what used to be refreshed by the parent's own response is now refreshed
-only by these rules. When a parent field genuinely depends on a child mutation,
-say so with `dependencies` rather than relying on a rerun that will not happen.
+graph: a parent field the parent's own response kept fresh is, once the relation
+is a resource of its own, refreshed only by these rules. When a parent field
+genuinely depends on a child mutation, say so with `dependencies` rather than
+relying on a rerun that will not happen.
 
 ## `withParams()`: a scope with reruns of its own
 
@@ -453,8 +462,10 @@ membership of each list is a question its own scope answers.
 `withParams()` chains, merging the params —
 `USER.withParams({ role: "admin" }).withParams({ gender: "male" })` is
 `USER.withParams({ role: "admin", gender: "male" })`. Its second argument takes
-`rerunOn` and `dependencies` for that scope; left out, the scope inherits the
-resource's. Empty params throw: a scope has to be about something.
+`rerunOn` and `dependencies` for that scope; what it leaves out is the
+resource's — a `rerunOn` key by key, so `{ rerunOn: { GET: ["PATCH"] } }` keeps
+the resource's `GET_MANY` and `GET_RANGE`. Empty params throw: a scope has to be
+about something.
 
 It is not the tool for a param the user types. A search word bound with
 `withParams()` would keep its results from refreshing after a write on the

package/docs/route_transitions.md

@@ -132,8 +132,9 @@ relation was written for. Two situations, two answers:
   deserves a direction. This is the case the export exists for.
 
 A default has no direction (nothing says which of two arbitrary pages is
-"before" the other), so only directionless movements make sense there. Written
-relations, and `"none"`, always win over it.
+"before" the other), so only directionless movements make sense there: navi's
+`slide-*` and `cover-*` are written on the direction, and as the default they
+play nothing. Written relations, and `"none"`, always win over it.
 
 ## When one navigation knows better
 
@@ -179,7 +180,8 @@ the same forms `defineRouteTransition` takes, plus `direction`. It overrides
 answers for. So:
 
 - `{ direction: "back" }` keeps the pair's movement and only turns it round;
-- `"zoom"` swaps the movement, keeping nothing else;
+- `"zoom"` swaps the movement; the way round and the pace are still the
+  pair's;
 - `"none"` cuts, where the pair — or the default — would have played;
 - `{ duration: 500 }` re-times what was already going to play.
 
@@ -525,12 +527,13 @@ await page.goBack();
 The window is **one frame**: the hold is given back inside the view
 transition's callback, which the browser runs at its next rendering
 opportunity. `tests/route_transition_list_revisit/` walks it the wrong way on
-purpose in its last case — under a movement the list that comes back is the same
-DOM element ten times out of ten and asks for nothing, while the same walk
-without a movement is a real one — and the window measured there is a back at 0
-or 8ms losing every round trip, at 16ms losing only the first, and past 64ms
-losing none. No thumb moves in one frame; an automated click continues in the
-same millisecond. This is a testing trap, not a user-facing behaviour.
+purpose in its last case — a back pressed the instant the URL changes — and
+which side of that frame a cycle lands on belongs to the machine's load: under
+a movement the list that comes back is either the element that never left,
+asking for nothing, or one truly remounted, asking once, while the same walk
+without a movement is a real one every time. No thumb moves in one frame; an
+automated click continues in the same millisecond. This is a testing trap, not
+a user-facing behaviour.
 
 ## The rest, briefly
 
@@ -538,6 +541,6 @@ same millisecond. This is a testing trap, not a user-facing behaviour.
   a per-relation `{ type, duration }` for one relation.
 - The URL leads: transitions play on navigations somebody else started (a
   `<Link>`, the back button, `history.back()`). Nothing here navigates.
-- A browser without view transitions (Firefox) navigates with a cut. The app
+- A browser without view transitions navigates with a cut. The app
   must remain fully usable that way — which it is, if the transitions state
   relations rather than carry information.

package/docs/safe_area.md

@@ -75,13 +75,8 @@ So the app states its own screen once, and never names a component:
 
 The bands fall out of it (centered), `--navi-app-width` follows, and `FixedBar`
 pins itself to the column's edges rather than the glass. An app wanting them
-uneven writes `--navi-app-inset-left` / `-right` directly instead.
-
-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.
+uneven writes `--navi-app-inset-left` / `-right` directly instead; everything
+below follows those the same way, popup placement included.
 
 Every popup follows: `Dialog`, `Popover`, and everything built on them
 (`Picker`, `Select`…). It is a ceiling and nothing more — on a screen narrower
@@ -98,11 +93,13 @@ Two ways NOT to get this:
   popovers would keep sizing themselves against 1500px;
 - setting `--dialog-max-width` on `.navi_dialog` from the app. It is a
   `--component-*` token, declared on the element (see
-  [css_architecture.md](./css_architecture.md#--navi--vs---component--where-the-override-has-to-go)),
-  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 also the
-  knob a single popup uses to ask for a specific size, not a ceiling:
+  [css_architecture.md](./css_architecture.md#--navi--vs---component--where-the-override-has-to-go)):
+  every dialog resets it on itself in an unlayered rule, so that a nested
+  dialog does not inherit its parent's size, and a `maxWidth` prop writes it
+  inline (a `Picker` under `dialogSizeFromAnchor` does) — an app rule of the
+  same specificity does not reliably win, and the cap silently disappears. It
+  is also 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 escaping the app's screen.
@@ -114,15 +111,19 @@ price.
 
 #### Placement follows the same rectangle
 
-`--navi-app-max-width` moves where a popup is placed, not only how big it may
+The app's rectangle moves where a popup is placed, not only how big it may
 get. Placement is computed against the visual viewport narrowed to the level-1
-bands: `getAppInsets` (`src/layout/responsive.js`) is the JS reading of them,
-navi hands them to `@jsenv/dom` once (`setPlacementViewportInsets`, wired in
+bands: `getAppInsets` (`src/layout/responsive.js`) reads `--navi-app-inset-*`
+back off the computed style — the bands `--navi-app-max-width` centers and the
+ones an app writes by hand alike, in any length unit — navi hands them to
+`@jsenv/dom` once (`setPlacementViewportInsets`, wired in
 `navi_css_vars.js`), and `pickPositionRelativeTo` reads them on every
-placement. Invisible for anything centered on its cross axis — `center`,
-`bottom`, `top`, which is what a dialog does nearly always — but it is what puts
-anything anchored to an edge (a `positionArea` like `bottom-start`, a
-`SidePanel`) flush against the app column's edge rather than the window's.
+placement. With centered bands it is invisible for anything centered on its
+cross axis — `center`, `bottom`, `top`, which is what a dialog does nearly
+always — and with uneven ones it is what centers that dialog on the app column
+rather than on the window. Either way it is what puts anything anchored to an
+edge (a `positionArea` like `bottom-start`, a `SidePanel`) flush against the
+app column's edge rather than the window's.
 `FixedBar` reads the same description through CSS instead: it is pinned to
 `--navi-app-inset-*`, which says where the app's rectangle is in the window
 rather than how wide it may be.
@@ -154,18 +155,25 @@ Beware of making that container scrollable by accident — see
 `var(--navi-safe-area-inset-bottom)` in any rule. It is always declared, whether
 or not the app ever mounts a bar.
 
-Reading it from **JS** takes a probe: an unregistered custom property keeps its
-`calc()` unresolved through `getComputedStyle`. Give a hidden box
-`height: var(--navi-safe-area-inset-bottom)` and measure it — see
-`src/layout/demos/fixed_bar/keyboard.html`.
+From **JS**, both levels are registered as lengths (`@property`, in
+`safe_area.js`), so
+`getComputedStyle(document.documentElement).getPropertyValue("--navi-safe-area-inset-bottom")`
+gives pixels, and so does `--navi-app-inset-*`.
 
 ### Putting something new into it
 
-Publish what you take on one edge, into that edge's slot. That is the whole
-contract — a native banner, an OS strip, anything an app invents joins the sum
-without a single component learning it exists. `FixedBar` is the worked example:
-it measures its own border box (notch included) and writes
-`--navi-fixed-bar-space-*` (`src/layout/fixed_bar/fixed_bar_space.js`).
+Level 2 has one slot per edge, `--navi-fixed-bar-space-*`, and it belongs to
+`FixedBar`: each bar measures its own border box (notch included), and navi
+writes the largest one on that edge inline on `<html>`
+(`src/layout/fixed_bar/fixed_bar_space.js`). The slot is combined with
+`env(safe-area-inset-*)` through `max()`, not added to it, since a bar measured
+with its notch already covers the notch.
+
+Something else taking an edge — a native banner, an OS strip — is published by
+being drawn as a `FixedBar`; every component reading the safe area then clears
+it without learning it exists. Writing the slot by hand holds only while no bar
+takes that edge: the first bar mounting there replaces the value rather than
+adding to it.
 
 ## What already reads it
 
@@ -182,24 +190,36 @@ truth:
 
 ## The trap: which viewport
 
-Three heights are in play and they are not the same one.
+Three heights are in play and they are not the same one — and which of them
+the keyboard moves depends on the browser.
+
+| what                             | shrinks when the keyboard opens                 |
+| -------------------------------- | ----------------------------------------------- |
+| `window.innerHeight` / `100dvh`  | no                                              |
+| `visualViewport.height`          | yes, except where the keyboard overlays (below) |
+| `--navi-vvh` (tracks the visual) | same as `visualViewport.height`                 |
 
-| what                             | shrinks when the keyboard opens |
-| -------------------------------- | ------------------------------- |
-| `window.innerHeight` / `100dvh`  | no                              |
-| `visualViewport.height`          | yes                             |
-| `--navi-vvh` (tracks the visual) | yes                             |
+Wherever the browser has the VirtualKeyboard API (Chromium), navi makes the
+keyboard overlay the page rather than shrink it (`src/layout/virtual_keyboard.js`):
+no viewport shrinks, and the keyboard arrives as `--navi-keyboard-inset-bottom`
+(`env(keyboard-inset-height)`), which `--navi-app-inset-bottom` adds. Firefox,
+Safari, and an app that called `disableVirtualKeyboardOverlay()` shrink the
+visual viewport instead, and `--navi-keyboard-inset-bottom` stays 0. Either way
+`--navi-app-height` and the popup ceilings answer the part of the screen left
+visible.
 
 `position: fixed` — so every `FixedBar` — is laid out against the **layout**
-viewport. A bottom bar therefore stays at the bottom of a window the keyboard is
-covering: it ends up _behind_ the keyboard, and no inset says so, because
-nothing reduced the layout viewport.
+viewport. Where the visual viewport is what shrinks, a bottom bar therefore
+stays at the bottom of a window the keyboard is covering: it ends up _behind_
+the keyboard, and no inset says so, because nothing reduced the layout viewport.
+Where the keyboard overlays, the bar is pinned to `--navi-app-inset-bottom`,
+which counts it, and sits above it.
 
 The consequence for anything measuring against the insets: mix the two families
 and you get a drift that only appears with a keyboard open. `getBoundingClientRect`
 is in layout-viewport coordinates, so what is compared to it must be too
-(`100dvh`), while `--navi-app-*` derives from `--navi-vvh` because what navi
-_sizes_ must fit what is actually visible.
+(`100dvh`), while `--navi-app-*` derives from `--navi-vvh` (plus the keyboard
+inset) because what navi _sizes_ must fit what is actually visible.
 
 `src/layout/demos/fixed_bar/keyboard.html` puts all of these on screen at once
 and turns the bottom bar's number red when it goes under the keyboard. On a

package/docs/scroll.md

@@ -47,7 +47,7 @@ Two shapes, and they do not behave the same:
 | `header` / `footer` alone | the container itself scrolls, and they are `position: sticky` at its edges — the content scrolls under them                                                                                       |
 | a `body` as well          | the container becomes a flex column, its own overflow turns to `hidden`, and the **body is the only thing that scrolls**; header and footer sit outside it (`position: static`, `flex-shrink: 0`) |
 
-Two consequences worth knowing before fighting them:
+Three 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
@@ -61,7 +61,8 @@ Two consequences worth knowing before fighting them:
   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.
+  scrolls under. The box is `isolation: isolate` already, so either value stays
+  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
@@ -237,10 +238,11 @@ A dialog is already bounded by the room its container leaves it
 (`--dialog-maxmax-height`), so a `maxHeight` is only for making it smaller than
 that.
 
-`dialog.jsx` deliberately declares no `overflow` of its own: a modal dialog
-would inherit `auto` from the UA stylesheet and a `layer="local"` one gets
-nothing, so without a scrolling rule its `max-height` would only decide how big
-the box looks while the content kept painting straight through it.
+`dialog.jsx` deliberately declares no `overflow` of its own: the
+`[data-scrollable]` the dialog carries is its scrolling rule. A modal dialog
+would get `auto` from the UA stylesheet anyway, but a `layer="local"` one gets
+nothing, and without that rule its `max-height` would only decide how big the
+box looks while the content kept painting straight through it.
 
 ### `scrollCapture`
 
@@ -309,7 +311,7 @@ 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]`.
+free applies only next to a `body`.
 
 **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
@@ -393,8 +395,8 @@ browser paints first — what a phone screen shows, plus a few — and `after` f
 the paint on. The switch waits for the paint itself, not for an effect: preact
 runs a component's pending effects early when that component renders again,
 and something always re-renders before a popup has painted. Do not rebuild
-this by hand with a `useEffect` that widens a slice — that is the thing it
-replaces, and it fails for that reason. The runs ask their source for `after`
+this by hand with a `useEffect` that widens a slice: that effect is one preact
+runs early, and it fails for that reason. The runs ask their source for `after`
 rows from the start, so the smaller first window costs no second request.
 
 ### Doing it well

package/docs/testid.md

@@ -85,7 +85,9 @@ found by nothing, while the host is what the user focuses and what
 `getByRole(role, { name })` and `getByLabel()` read.
 
 ```jsx
-<Picker variant="icon" aria-label="Aide" ui={<Icon>…</Icon>} />
+<Picker variant="icon" aria-label="Aide" ui={<Icon>…</Icon>}>
+  …
+</Picker>
 ```
 
 ```html
@@ -122,6 +124,13 @@ error message, a section, a row — put the testid on the surrounding component
 (`<Field data-testid="email-field">`, `<Box data-testid="cart-row">`); anything
 built on `Box` forwards it to its own element.
 
+A selectable `List.Item` is a control too, and the rule holds there with a
+consequence worth knowing: its host is the real checkbox or radio the row
+selects with, an input navi draws invisible (`navi-visually-hidden`) and lays
+under the row's content. A `data-testid` on the item names that input — what
+`toBeChecked()` reads, not what the eye sees. A test that presses the row, or
+waits for it to show, targets what the row draws: a testid on its content.
+
 A picker's popup is the one element the application does not render itself:
 `<Picker>` builds it, so a `data-testid` on the picker names the trigger and
 nothing names the popup. `popupTestId` does:

package/docs/typography.md

@@ -84,7 +84,7 @@ The prop is the same everywhere: a number of lines, cut with an ellipsis.
 - **`Picker`** — its value, `maxLines={1}` by default; `variant="text"` and
   `variant="bare"` draw the caller's own thing and are not clamped, a `Text` in
   their `ui` cuts itself with its own `maxLines`.
-- **`PickerSpin`** (`DaySpin`, `TimeSpin`…) — its value; left out, a long value
+- **`Spin`** (`DaySpin`, `NumberSpin`…) — its value; left out, a long value
   wraps and the box grows.
 - **`Binder`** — its tab labels, `maxLines={1}` by default, `false` lets them
   wrap; overridable per item.
@@ -104,9 +104,8 @@ width must say it too**, or the whole chain grows instead of truncating:
 
 ```jsx
 <Box flex width="300" spacing="s">
+  {/* without minWidth the row just grows */}
   <Box flex expandX minWidth="0">
-    {" "}
-    {/* without minWidth the row just grows */}
     <Text maxLines={1}>…</Text>
   </Box>
 </Box>

package/docs/view_transitions.md

@@ -75,15 +75,6 @@ does not handle a rejection, an unhandled one is what it leaves behind, and
 `.then(done, done)` is the shape that ends it whichever way it went — while a
 `ready` waiter must expect the skip: `ready.then(onPictures, () => {})`.
 
-## See also
-
-- [route_transitions.md](./route_transitions.md) — pages moving against each
-  other on navigation
-- [drag_to_travel.md](./drag_to_travel.md) — a transition held under a finger,
-  and what the main thread cannot read of it
-- [drag_interactions.md](./drag_interactions.md#naming-what-travels) — naming
-  what moves when something is dropped on a place
-
 ## The top layer is painted through the root's picture
 
 A modal `<dialog>`, its `::backdrop`, a popover: the browser paints the top
@@ -137,3 +128,12 @@ Two consequences for the switch itself:
   `display` on: hidden before the call, a stand-in measures as a zero rect and
   lands in the wrong place; and on the capture frame it is displayed while the
   real thing is still there.
+
+## See also
+
+- [route_transitions.md](./route_transitions.md) — pages moving against each
+  other on navigation
+- [drag_to_travel.md](./drag_to_travel.md) — a transition held under a finger,
+  and what the main thread cannot read of it
+- [drag_interactions.md](./drag_interactions.md#naming-what-travels) — naming
+  what moves when something is dropped on a place