@jsenv/navi 0.29.482 → 0.29.484

package/docs/interactions.md

@@ -172,11 +172,27 @@ receives.
 ancestor can also listen for one, and `preventDefault()` on it means "not this
 time".
 
-The lower-level event is reachable too: `interactionEvent.detail.event` is the
-`pointerdown` a hold was made of, and the `pointerup` that ended a swipe or a
-tap — which is how a menu is opened at the point the press happened. A drag's
-is its `pointerdown`, release included, with one exception (see
-[drag_interactions.md](./drag_interactions.md)).
+What the callback receives depends on who made the interaction.
+`click`, `mousedown`, `mouseup` and `contextmenu` **are** the browser's event:
+its `target` is what was pressed, its `detail` the click count, and there is no
+`detail.event`. Every other interaction is an event navi dispatches **on the
+element that declares it** — its `target` is that element, whatever was pressed
+inside — and the event it was read from is `detail.event`:
+
+| Interaction                                | `detail.event`                                                                                                            |
+| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
+| `longpress`                                | the `pointerdown` held                                                                                                    |
+| a swipe                                    | the release that ended it                                                                                                 |
+| `double_click`, `single_click`             | the `pointerup` of the tap that settled it; a `single_click` no press made (the keyboard, `element.click()`): the `click` |
+| the carrying family (`move`, `reorder`, …) | the `pointerdown`, release included, with one exception (see [drag_interactions.md](./drag_interactions.md))              |
+| `"keyboard:<shortcut>"`                    | the `keydown`                                                                                                             |
+| `pan`                                      | the `pointermove`                                                                                                         |
+| `zoom`                                     | the `pointermove` of a pinch, or the `wheel`                                                                              |
+
+So `event.target` tells inner controls apart for the four native ones only.
+Whatever the interaction, the press itself — where a menu opens at the point the
+finger was — is `findEvent(event, ["pointerdown", "pointerup", "click",
+"contextmenu"]) || event`.
 
 ## Reaching the control
 
@@ -190,7 +206,32 @@ still answers a callback; only the two requests (`"request_action"`,
 A `Box` that lays out **several** controls — a row of badges, a toolbar — belongs
 to none of them: its interactions are its own, answered with no gate. A click on
 one of the controls reaches the box too, the way any click bubbles; the callback
-reads `event.target` when it has to tell them apart.
+reads `event.target` when it has to tell them apart — on a `click`; any other
+interaction's target is the box itself, and what was pressed is in its
+`detail.event` (see [Which interaction asked](#which-interaction-asked)).
+
+A box answering a press on its **blank space** only — a row that folds, a card
+that opens on any press but its buttons', a viewer that closes on its
+background — asks `isPressOnControl(event, box)`: true when the press was aimed
+at a control strictly inside the box (a field, a button, a link, a navi
+control, an element claiming its own interactions). Bounded by the box, so the
+list or the dialog around it is never taken for what was pressed:
+
+```jsx
+<Box
+  interactions={{
+    click: (event) => {
+      if (isPressOnControl(event, event.currentTarget)) {
+        return;
+      }
+      toggleFolded();
+    },
+  }}
+/>
+```
+
+For an interaction navi dispatches, the press is its `detail.event` and the box
+is the event's `target`: `isPressOnControl(event.detail.event, event.target)`.
 
 **The gate takes every declared interaction for a write.** Letting a read through
 a read-only or busy control is navi's to grant inside its own controls, and
@@ -441,7 +482,9 @@ The registry holds no detector of its own: navi's swipes, holds and shortcuts go
 through the same door an application uses, `defineInteractionDetector`. Its
 JSDoc is the contract — `setup` once per element and its teardown, what
 `trigger` returns (`null` when nothing ran, else a promise that rejects when
-the effect failed), `implies`, `refusable`, `disputesPress` — and
+the effect failed — what a callback rejects with is reported unless the
+detector says it itself, `claimsRefusals`), `implies`, `refusable`,
+`disputesPress` — and
 `38_interactions_demo.html` registers a `triple_click` from the page. A detector
 claims a **set** of names rather than one, because interactions sharing an input
 have to be arbitrated together: a swipe, a hold and a click dispute the same

package/docs/navigation.md

@@ -345,6 +345,10 @@ The routes, the document url and the renders still follow every write; only
 `window.location` waits for the state to stay still that long, and a back pressed
 before the write keeps the last address written. A push is never debounced.
 
+A `stateSignal` bound to a `Wheel` is such a value: the wheel writes every row a
+drag, a fling or a mouse wheel passes through, not only the one it settles on, so
+the state declares `debounceUrl`.
+
 ## Rendering routes
 
 `<Route>` is the only primitive. With `children` it is a container that renders
@@ -370,6 +374,12 @@ the pages of a `RouteTravel` row alike:
 </Route>
 ```
 
+`fallback` also takes a `routeFallback()`, which names the page it shows
+(`<Route fallback={NOT_FOUND_PAGE} element={NotFoundPage} />`): a movement can then
+be written about it (see
+[route_transitions.md](./route_transitions.md#a-page-opened-from-anywhere)), and
+its `matchingSignal` read outside the tree.
+
 A section with a shared prefix owns its own sub-router: one leaf on
 `/dashboard/` whose element renders its own `<Route>` tree and chrome, handing its
 local state down through `elementProps`. Pages sharing a layout but no prefix
@@ -388,7 +398,12 @@ section of pages shares one:
 <Route>
   <ErrorBoundary
     fallback={({ error, resetError }) => (
-      <ErrorScreen error={error} onRetry={resetError} />
+      <ErrorScreen
+        error={error}
+        // the rerun lifts the boundary; resetError only dismisses, and a
+        // page that never loaded has nothing to show once dismissed
+        onRetry={error.action ? () => error.action.rerun() : resetError}
+      />
     )}
   >
     <Loading fallback={<GameSkeleton />}>
@@ -452,6 +467,9 @@ with `currentAlso={[PLACE_ROUTE]}`, and `currentExcept` names a place under the
 section it does NOT stand for. Both amend what a link claims about itself and
 nothing else — neither is an answer to a route that lies about where the reader
 is (see [what its address may say](#a-layer-over-the-screen-what-its-address-may-say)).
+A bar entry drawn as a button for its press feedback says the same with
+`<Button route currentAlso currentExcept>`: it is drawn as a link and wears
+`aria-current="page"` from the same reading.
 
 The routing takes a plain click that moves this tab, and nothing else. A link
 with `target="_blank"` (or any `target` other than `_self`) opens the app in that
@@ -678,6 +696,14 @@ should go somewhere, a fragment, down to a single row (`#tournament_42`) — nev
 a search param plus a `scrollIntoView` in an effect, which fires before what sits
 above the element has laid out, with nothing to tell it how long to wait.
 
+A mark that only designates — the row a notification points at, outlined until
+the reader moves on — is `:target` too, even though it restyles the element: it
+lasts until the page next writes its URL, which is the length of "this one". A
+search param would outlive it, as state the page does not act on. The alignment
+`setUrlTargetOptions({ block })` sets holds for the whole app; a target that wants
+to land with more room before it says so on itself, with a scroll-margin
+(`scrollMarginBlock` on a `Box`), which the landing honours.
+
 ### A row of tabs, where a replace IS an arrival
 
 The tabs of a `<RouteTravel>` navigate by replacing, and yet each one is another

package/docs/network_policy.md

@@ -111,8 +111,11 @@ all, so it is left alone, and so is a function handed to a control's `action`:
 it is wrapped into an action with no verb, even when it calls one, so the
 control is not held and the write fails after the press with a
 `NetworkPolicyError` ([resource.md](./resource.md#a-function-calling-the-verb-or-the-instance)).
-`createAction(callback, { meta: { verb } })` opts an action into what the action
-layer holds — a control bound to a write verb is read-only, a completed `"GET"`
+Such a control says what its function does to the server with `actionVerb` —
+`<Input type="checkbox" boolean action={(on) => saveSetting("weather", on)}
+actionVerb="PATCH" />` — and is then held up front, with the policy's message.
+`createAction(callback, { meta: { verb } })` says the same of an action declared
+once, and opts it into what the action layer holds — a control bound to a write verb is read-only, a completed `"GET"`
 is not rerun — but its callback is still called when it runs: answering from
 the store and settling with a `NetworkPolicyError` are done by the callbacks a
 `resource()` wraps.

package/docs/pan_zoom.md

@@ -35,6 +35,9 @@ the fingers, or under the wheel. Two fingers are one gesture, the point between
 them panning and the distance between them zooming, and a finger lifting
 re-anchors on what is left. What a pixel of pan means in your coordinates, and
 whether the zoom is continuous or stepped, is yours: the numbers are the numbers.
+Where the hand is, rather than how far it moved, is on the event the report was
+read from, `detail.event`: the `pointermove` (its `clientX`/`clientY`), or the
+`wheel` for a zoom.
 
 Everything else is settled before the press, and there is nothing to wire: the
 pan steps back for what is carried across the surface (a `move`, a handle, a

package/docs/popup_open.md

@@ -93,6 +93,14 @@ one press:
 </Link>
 ```
 
+`command` and `commandFor` are props of navi's controls (`Button`, `Link`…),
+read when the control is pressed. Written on a plain element they are HTML's own
+invoker commands, and no navi popup listens to the `command` event the browser
+fires for them. `popovertarget`, `showPopover()` and `showModal()` do not go
+through the popup's open state either: they toggle the element behind it (a
+top-layer `Popover` is `popover="manual"` from its first render). From anything
+that is not a navi control, the way in is `triggerNaviCommand`.
+
 ## Something else opens it: `triggerNaviCommand`
 
 The attributes cover more than "this button opens that dialog": `commandFor`
@@ -455,7 +463,10 @@ None of them is "one popup per row of a list", which is what a picker is for.
 
 `onOpen` is called on every open (for when, see
 [above](#onopen-runs-before-the-popup-has-built-anything)), and `onClose` on
-every real close, with `detail.isCancel` when the close meant "revert". Neither
+every real close, with `detail.isCancel` when the close meant "revert" and
+`detail.isConfirm` when it was a `--navi-confirm` saying yes — so a shared Dialog
+asking a yes/no question after a gesture already over answers it there
+(`onClose={(e) => e.detail.isConfirm && release()}`). Neither
 can veto: `onClose` is the close happening, not a request to close. The refusals
 are navi's: a close over a control mid-action, and a `Picker`'s close over a
 value that does not validate.
@@ -592,13 +603,16 @@ a thumb can hit:
 ```jsx
 <Dialog id="duration">
   <Box header flex="x" alignY="center" padding="s">
-    <Box expandX>Durée de la partie</Box>
+    <Dialog.Title expandX>Durée de la partie</Dialog.Title>
     <Dialog.Close />
   </Box>
   …
 </Dialog>
 ```
 
+The text of the row is the popup's title, and so its name (see
+[below](#its-name)).
+
 ### It is the way out, so the state around it does not reach it
 
 **A close button written by hand refuses the press inside a read-only control.**
@@ -658,6 +672,12 @@ nothing else. The first of these names it:
 </Picker>
 ```
 
+In a header row, beside the cross, the title is both the row's text and the
+popup's name — written as plain text there instead, it names nothing. It is a
+heading drawn as that text: bold, at the size of the row, with no heading
+margins, unless `size` or `margin` say otherwise (see
+[the close cross](#the-close-cross)).
+
 A `Popover` has no role of its own, and a name on an element without one is
 read by nobody: a named popover is a `dialog`, unless given another `role`. A
 picker's popover always is, which is what its trigger announces
@@ -716,6 +736,21 @@ route's search-param `stateSignal` as the signal, that is how
 [a row of cards](./popup_lift.md#a-row-of-cards-one-popup-that-walks) survives
 leaving the page: the address names the card, and the sheet reopens on it.
 
+A `Picker` says the same with `openSignal` and `openValue`, its own `signal`
+and `value` being its answer:
+
+```jsx
+<Picker openSignal={editedIdSignal} openValue={item.id} action={save}>
+  …
+</Picker>
+```
+
+An item edited in place under `?edit=<id>` then reopens from a reload or a
+pasted link, Back closes it when the signal's history pushes, and the route
+actions reading `editedIdSignal` load the fresh record and what the sheet lists
+while it is open ([below](#a-popup-that-loads-data)). The picker's `onOpen` and
+`onClose` are left to what they are for: nothing in them writes the address.
+
 ### `navState` — the history entry holds it
 
 ```jsx
@@ -728,7 +763,7 @@ opening an entry of its own: the back button closes the popup rather than
 leaving the screen, and a cancel goes back with the entry
 ([above](#escapeeffectclose-and-why-it-is-a-last-resort)). A `Picker` needs none
 of this, only an `id`: its open state is nav state under that id, pushed in
-dialog mode. Without an `id` the key names one mount — the page left with the
+dialog mode (unless an `openSignal` holds it, see above). Without an `id` the key names one mount — the page left with the
 picker open and come back to is a new mount, and the state stays in the entry
 with nothing to read it (navi warns). A picker whose popup leads somewhere, a
 link inside it, has an `id`.
@@ -923,6 +958,11 @@ option is the component drawing its own wait
 (`useAsyncData(action, { loading: true })`); what is not an option is neither.
 Both are on `src/layout/demos/13_popup_loading_demo.html`.
 
+The failure has no boundary of its own either: delegated, it lands on the
+nearest `<ErrorBoundary>` above the popup — the one holding the page, whose
+fallback replaces the page under it. A read inside a popup takes `error: true`
+and says the failure where it stands.
+
 What the popup gains is everything a page has: the request leaves **with the
 screen**, in parallel with the rest of what the address needs, instead of behind
 the gesture that opens the popup; `useAsyncData` reads it (see

package/docs/resource.md

@@ -38,6 +38,7 @@ Actions are read in components through the action system (`useAsyncData`,
 - [`GET_RANGE`: feeding a list that loads as it scrolls](#get_range-feeding-a-list-that-loads-as-it-scrolls)
 - [Searching the same collection](#searching-the-same-collection)
 - [Relations: pick one of the four methods](#relations-pick-one-of-the-four-methods)
+  - [Several writes on one item: `writes`](#several-writes-on-one-item-writes)
 - [Callback return contracts](#callback-return-contracts)
 - [When the backend answers a sub-route with the whole parent](#when-the-backend-answers-a-sub-route-with-the-whole-parent)
 - [Relations and autorerun](#relations-and-autorerun)
@@ -80,7 +81,8 @@ that keeps the copy, a `stateSignal` that persists:
 
 ```js
 const mePersistedSignal = stateSignal(undefined, {
-  id: `me@${APP_VERSION}`,
+  id: "me",
+  version: APP_VERSION,
   persists: true,
   type: "object",
 });
@@ -106,8 +108,10 @@ test wants.
 What stays the app's, because only the app knows:
 
 - **the key.** A deploy that changes the shape of the answer must not draw the
-  old one: put in the signal's `id` whatever makes a copy unusable — the
-  deployed version — and a new id starts clean.
+  old one: the signal's `version` says what makes a copy unusable — the
+  deployed version. It is stored under `me@<version>`, and creating the signal
+  removes the copies every other version left (and one stored under the bare
+  id), so a device does not keep one per deploy it ever opened.
 - **`when`: is the copy about this session?** A tab viewing as someone else, an
   account being switched — the row is somebody's, and must not be kept for the
   next person. `when` is read whenever the copy is about to be read or written:
@@ -149,7 +153,8 @@ slot, replaced when the user moves:
 
 ```js
 const pageKeptSignal = stateSignal(undefined, {
-  id: `page@${APP_VERSION}`,
+  id: "page",
+  version: APP_VERSION,
   persists: true,
   type: "object",
 });
@@ -429,6 +434,7 @@ people — is two relations spelled as one, and the one the gesture is about
 | The relation itself carries fields (`candidate_since`, `seen_at`, `slot`)                                     | `.scopedMany()` — those fields belong to the pair; putting them in a shared child store corrupts that entity for every other reader |
 | The backend answers every sub-route with the whole refreshed parent                                           | still model the relation; absorb the response with a plural callback (see below)                                                    |
 | A genuine partial update of the parent itself (cancel a game)                                                 | plain `PATCH` on the parent                                                                                                         |
+| Several writes on the item itself, none of them a sub-object (cancel, archive, mark as seen)                  | one named in [`writes`](#several-writes-on-one-item-writes) each                                                                    |
 
 Singular vs plural is about the relation, not the verb: `.one`/`.scopedOne` for a
 single sub-object, `.many`/`.scopedMany` for a collection.
@@ -442,6 +448,39 @@ give that relation its own relationship method and a callback returning what was
 written, even when the backend must grow a field for it — never a flag next to
 the button.
 
+### Several writes on one item: `writes`
+
+An item takes writes that are no sub-object of it: cancel, archive, mark as
+seen, star. The first can be its `PATCH`; the others are named, each one a
+write of its own:
+
+```js
+const ORDER = resource("order", {
+  GET,
+  PATCH,
+  writes: {
+    cancel: {
+      verb: "PATCH",
+      callback: ({ id }) => post(`/orders/${id}/cancel`),
+    },
+    archive: {
+      verb: "PATCH",
+      callback: archiveOrder,
+      rerunOn: { GET_RANGE: true },
+    },
+  },
+});
+<Button action={ORDER.cancel.bindParams({ id })}>Cancel</Button>;
+```
+
+`ORDER.cancel` is an action beside the verbs: its own loading and error on the
+button that runs it, held by the network policy as its `verb`, and answered as
+that verb is (a `PATCH` returns the item, which is upserted). Its `rerunOn` says
+which reads of this resource it reruns; a read it leaves out follows `rerunOn`
+for its verb. A dependent names it like a callback —
+`{ resource: ORDER, on: ["cancel"] }` reruns after a cancel, not after an
+archive — and a resource listed bare counts it with every other write.
+
 ## Callback return contracts
 
 These are not guessable — each relationship method has its own shape, written
@@ -629,7 +668,8 @@ const SUMMARY = resource("summary", {
 ```
 
 `on` names callbacks, not verbs: `PATCH` does not cover `PATCH_MANY` the way it
-does in `rerunOn`, so each write keeps its own answer. A name that is not a
+does in `rerunOn`, nor a write [named in `writes`](#several-writes-on-one-item-writes)
+whose verb is `PATCH`, so each write keeps its own answer. A name that is not a
 write, or that the resource does not define, throws at declaration — a
 dependency that never fires leaves a count on its old value with nothing to say
 so.

package/docs/route_transitions.md

@@ -65,6 +65,19 @@ is not `defineRouteDefaultTransition`, which is about every navigation nothing
 was said about. Write it only for a door that really is furniture: a page reached from a
 screen has that screen to be paired with, and the pair says more.
 
+A page with no door at all is from anywhere too: reached by its address from
+whatever screen one was on, as the not-found page is.
+
+```js
+const NOT_FOUND_PAGE = routeFallback();
+// <Route fallback={NOT_FOUND_PAGE} element={NotFoundPage} />
+defineRouteTransition(null, NOT_FOUND_PAGE, "slide-x");
+```
+
+So is an item's own page reached from every card it appears on: pair it only
+where one screen means something different, and let the traversal retrace the way
+back (see [below](#a-traversal-retraces-its-crossing)).
+
 **Such a page is still a PAGE**: it takes the screen's place, and the reader comes
 back to whatever the router puts there. A destination that must be drawn OVER the
 screen and give it back exactly on closing is a layer, not a page — its address
@@ -360,6 +373,13 @@ a custom movement's pictures read goes on `::view-transition`, never on the root
 }
 ```
 
+The values navi hands a movement's pictures live there too, which is the only
+place they can be read from: `--navi-transition-window-width` and `-height`, the
+window the pages move in, and `--navi-route-transition-travel-x` and `-y`, the
+distance a page travels — the window less what the bars cut off it. A depth or a
+distance a movement derives from them is derived on `::view-transition`, as above;
+written on `:root`, the `var()` finds nothing and takes its fallback.
+
 ## Two routes matching one url
 
 A relation is resolved through **which page is current** — not through the url,

package/docs/safe_area.md

@@ -121,6 +121,51 @@ end (see below).
 Beware of making that container a scroller by accident — see
 [A document wider than the screen](#a-document-wider-than-the-screen).
 
+### A page that fits the free band
+
+An app whose document scrolls still has screens that must fit the screen: a
+head that stays put over a part that scrolls, a wizard whose step fills what is
+left. The height of the free band is the visual viewport less both insets:
+
+```css
+.wizard {
+  height: calc(
+    var(--navi-vvh) - var(--navi-safe-area-inset-top) -
+      var(--navi-safe-area-inset-bottom)
+  );
+}
+```
+
+`--navi-vvh` and not `100dvh`: it follows the visual viewport, so the page
+shrinks with a keyboard that shrinks it, and the insets add the bars, the notch,
+the app's own bands and an overlaying keyboard (see
+[the trap](#the-trap-which-viewport)). Never `--navi-fixed-bar-space-*`: that
+slot is how a `FixedBar` writes what it takes, and reading it for layout misses
+the notch on an edge with no bar, the band of a capped app, and the keyboard.
+
+### A strip under a bar
+
+A strip that stays under the top bar — a status banner, an "offline" line — is
+not a second `FixedBar` (one bar per edge: a second one sits on the first). It
+belongs to the flow, sticking where the band starts:
+
+```jsx
+const bannerRef = useRef();
+useTransitionCover(bannerRef);
+
+<Box
+  ref={bannerRef}
+  style={{ position: "sticky", top: "var(--navi-safe-area-inset-top)" }}
+>
+  Hors ligne
+</Box>;
+```
+
+`useTransitionCover` publishes the strip's height, so the pictures of a route
+movement are cut under it rather than sliding over it. An anchor's
+`scroll-margin` adds only what `:root`'s `scroll-padding` does not hold already
+— the strip's own height, a few pixels of air — never the bar or the band.
+
 ### Reading it yourself
 
 `var(--navi-safe-area-inset-bottom)` in any rule. It is always declared, whether
@@ -241,10 +286,16 @@ data — is still a layout bug. In dev, ask who overflows:
 import { detectHorizontalOverflow } from "@jsenv/navi";
 
 if (import.meta.dev) {
-  detectHorizontalOverflow({ root: document.querySelector("#main") });
+  detectHorizontalOverflow();
 }
 ```
 
+Measured from `<body>`, the wrapper would hold its own overflow and hide every
+culprit inside it, so the wrapper is what the content is measured against: found
+down the boxes that are the only thing their parent draws (`<body>`, the mount
+point, the shell). A wrapper beside other boxes is not found; pass it as
+`root`.
+
 It outlines the culprits in red and names them in the console, at load and
 whenever the layout changes. It reports the **outermost** box that sticks out
 (its children stick out because it does), and stays quiet about what cannot

package/docs/scroll.md

@@ -51,7 +51,9 @@ 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.
+  does not fill. Adding `expandY` to "fix" that is undoing a deliberate default
+  — the one body that grows holds a list scrolling in its own frame (see
+  [A field above the list](#a-field-above-the-list)).
 - the separating line is a `border-bottom` on the header (`border-top` on the
   footer), not a `box-shadow`: a shadow is drawn outside the box and lost to
   whatever is painted after it, so the body would cover the very line meant to
@@ -133,6 +135,28 @@ opens on an item places the document itself: the offset the page kept for its ur
 is not put back over it — the items held off screen are fillers of an estimated
 height, and the same pixels now fall on other items.
 
+### Moving the list on a press
+
+A table of contents beside a long list, a "back to today" button: the press
+sends the list to a place with `--navi-scroll`, and the list goes there the way
+`scrolled` takes it — asked for by name when it is not fetched yet, measured,
+and held until the user reaches for the list:
+
+```jsx
+<Button command="--navi-scroll:smooth" commandFor="feed" value={{ id: dayId }}>
+  Today
+</Button>
+<List id="feed">…</List>
+```
+
+The value is anything `scrolled` takes (`"start"`, `"end"`, an index,
+`{ id, offset, align }`) or an item's id, and the same place can be asked for
+again once the list was moved away from it — no `scrolled` released and set
+again a frame later. `:smooth` glides, and is instant under
+`prefers-reduced-motion`. Without it a placement follows the scroller's own
+`scroll-behavior`: a `scroll-behavior: smooth` on the box glides every
+placement of the list, the one it opens on included.
+
 ### A list that comes back: one `id`, one list
 
 The position a list comes back to is kept under its `id` and the page's url, so
@@ -216,7 +240,10 @@ So the parts are direct children of the `Dialog`:
 
 ```jsx
 <Dialog id="…" dockedOnSmallTouchScreen>
-  <Box header>title + close</Box>
+  <Box header flex="x" alignY="center">
+    <Dialog.Title expandX>…</Dialog.Title>
+    <Dialog.Close />
+  </Box>
   <Box body>
     <List scroller="parent" /> {/* NOT "self" */}
   </Box>
@@ -224,10 +251,36 @@ So the parts are direct children of the `Dialog`:
 </Dialog>
 ```
 
+The title is the popup's name ([popup_open.md](./popup_open.md#its-name)),
+drawn as the row's text.
+
 A dialog is already bounded by the room its container leaves it, so a
 `maxHeight` is only for making it smaller than that (see
 [dialog_shape.md](./dialog_shape.md#the-ceiling-nobody-sets)).
 
+### A field above the list
+
+A sheet of fixed height that keeps a field in view above a list scrolling in
+its own frame — a search box over the entries to pick from — gives the body
+the height and the list the scrolling:
+
+```jsx
+<Dialog id="…" expandY>
+  <Box header>…</Box>
+  <Box body flex="y" expandY>
+    <Input type="search" />
+    <List expandY />
+  </Box>
+</Dialog>
+```
+
+The body grows here, which it never does on its own: not to push a footer
+down, but to bound a list that is itself the scrolling area. It still scrolls
+when what stays put outgrows it (the keyboard up). `scroller="parent"` is the
+shape when there is no frame to keep and the field may scroll away with the
+rows. The field goes in the body, never in the header of a docked sheet: that
+header is its swipe grip.
+
 ### `scrollCapture`
 
 ```jsx
@@ -458,9 +511,10 @@ paint on. `initial: "100%"` is the screen and nothing more, whatever the items
 weigh: a few are drawn to be measured, and the window is sized on them before
 the browser paints — a count (`initial: 6`) is a guess that holds for one kind
 of item only. A position handed back with its `visibleCount` sizes that first
-window itself, whatever `initial` says. The runs ask their source for a page of
-items (`<List.Items pageSize>`, 100 by default) whatever either says, so the
-smaller first window costs no second request.
+window itself, whatever `initial` says. A first window smaller than a page
+still asks the source for a whole page (`<List.Items pageSize>`, 100 by
+default), so the smaller window costs no second request; a window wider than a
+page — a count budget without `initial` — is asked for whole.
 
 The switch waits for the paint itself. Do not rebuild it with a `useEffect`
 that widens a slice: preact runs a component's pending effects early when that

package/docs/state_binding.md

@@ -51,6 +51,15 @@ was missed.
 />
 // ✓
 <Dialog signal={openSignal} />
+
+// ✗ a button told it was pressed, and the app writes the state back down
+<Button aria-pressed={editing} uiAction={() => (editingSignal.value = !editing)}>
+  Edit
+</Button>
+// ✓ a button that stays pressed is a checkbox
+<Input type="checkbox" variant="button" boolean signal={editingSignal}>
+  Edit
+</Input>
 ```
 
 In each pair the second line is not a tidier spelling of the first: it is the

package/docs/testid.md

@@ -44,10 +44,23 @@ that contract is absent or not usable:
 
 - there is no accessible name, or it is an icon, or it is dynamic;
 - the app is translated, and the test must pass in every language;
+- the name is copy still being reworded;
 - several elements legitimately share role and name (rows of a list, cells of a
   table) and only their position tells them apart — a per-item
   `data-testid={`row-${id}`}` names them by identity instead of by index.
 
+A name is stable when it is not copy: an icon's `aria-label`, a landmark, the
+names navi gives its own parts. When the testid is what addresses the element,
+the contract stays checked as an assertion of its own — a rewording then breaks
+nothing, and a missing name still fails:
+
+```js
+const save = page.getByTestId("save-game");
+await expect(save).toHaveRole("button");
+await expect(save).toHaveAccessibleName(/\S/);
+await save.click();
+```
+
 ## Where it lands in navi
 
 Navi renders more than one element per component: a control is a little tree —
@@ -149,7 +162,9 @@ or waits for it to show, targets what the row draws: a testid on its content.
 What navi builds itself is named through props. A `data-testid` on a `<Picker>`
 names the trigger; `popupTestId` names the popup it builds (the callout, under
 `mode="callout"`), and `confirmTestId` / `cancelTestId` the yes and no buttons
-of a `type="confirm"` picker's default body:
+of a `type="confirm"` picker's default body. Likewise `menuTestId` names a
+`SplitButton`'s chevron half, and `previousTestId` / `nextTestId` a `Spin`'s
+two ways out (a `DaySpin`'s, a `NumberSpin`'s):
 
 ```jsx
 <Picker data-testid="tie-break" popupTestId="tie-break-sheet">
@@ -197,7 +212,12 @@ Navi's own attributes are implementation, not a contract: `data-header`,
 `navi-control*`, `.navi_*` class names, the ids navi generates when none is
 given (`useId`), and the ids it derives from yours (a picker's popup id is built
 from the picker's, so the suffix is navi's even when the base is not). They
-change without notice and without a migration note.
+change without notice and without a migration note. The exception is the state
+a guideline doc tells an app to read — `navi-refreshing`
+([list_refresh.md](./list_refresh.md)), `navi-stuck`
+([z_index.md](./z_index.md)), `data-navi-route-transition*`
+([route_transitions.md](./route_transitions.md)): a test may assert it like any
+other contract.
 Likewise a `view-transition-name` or a CSS variable: those exist to draw, not
 to be found.