@jsenv/navi 0.29.418 → 0.29.419

package/docs/view_transitions.md

@@ -10,6 +10,7 @@ they are met once.
 - [Nested groups, and the fallback fade](#nested-groups-and-the-fallback-fade)
 - [Rendering is suspended for the whole callback](#rendering-is-suspended-for-the-whole-callback)
 - [`ready` rejects when the transition is skipped, `finished` when the update fails](#ready-rejects-when-the-transition-is-skipped-finished-when-the-update-fails)
+- [An element captured in a view transition cannot be pointed at](#an-element-captured-in-a-view-transition-cannot-be-pointed-at)
 - [The top layer is painted through the root's picture](#the-top-layer-is-painted-through-the-roots-picture)
 - [Two frames show the live document](#two-frames-show-the-live-document)
 - [What makes a transition restyle the whole document](#what-makes-a-transition-restyle-the-whole-document)
@@ -20,18 +21,28 @@ they are met once.
 A `view-transition-name` must be unique per document: a duplicate aborts the
 transition, silently. Scope any name the app adds — per item id, per screen.
 
-The other half of the same fact is a bonus that costs nothing: any element given
-its own name (a tab underline, a header, a stamp) is animated by the browser
-from where it was to where it is during **any** transition, whoever started it.
-`Nav` does this for its current-tab indicator (`currentIndicator`), which is why
-the bar follows a `RouteTravel` swipe with no wiring between the two.
+A named element is photographed on its own and animated by the browser from where
+it was to where it is, during any transition, whoever started it. Hence the trap:
+**an element named inside a page that moves does not move with it.** The name
+lifts it out of its page's picture into a picture of its own, which stands where
+it was captured, fading, while the pages slide away under it — right for a morph
+between the two pages, wrong for anything that belongs to its page. navi's own
+components drop their names for such movements: `Nav` names its current-tab bar
+only for a movement between two tabs of its own row (`currentIndicatorSlides`),
+and `List` unnames its rows for the length of any route transition or travel. A
+name the app puts inside the pages is given only for the gesture it serves, or
+dropped while they move: `view-transition-name: none` under
+`:root:is([data-navi-route-transition], [data-navi-route-travel])`. Without nested
+groups it also escapes the pages' clip, and navi warns about one inside a
+transition area.
 
 ## Nested groups, and the fallback fade
 
 List and grid transitions rely on nested groups (`view-transition-group:
-contain`, Chrome/Edge 140+). On a browser without it nothing is named, so an
-unconditional `startViewTransition` falls back to a full-page cross-fade. If
-that fade is unwanted, the app — not a component — writes:
+contain`, Chrome/Edge 140+). On a browser without them nothing is named, so an
+unconditional `startViewTransition` falls back to a full-page cross-fade. Whether
+that fade is a decent default or a glitch is the application's call, never a
+component's, and turning it off is one rule (see `itemTransition` on `List`):
 
 ```css
 @supports not (view-transition-group: contain) {
@@ -41,9 +52,6 @@ that fade is unwanted, the app — not a component — writes:
 }
 ```
 
-Only the application knows whether a page-wide fade is a decent default or a
-glitch there.
-
 ## Rendering is suspended for the whole callback
 
 The document's rendering is suspended for the whole update callback, from the
@@ -53,103 +61,99 @@ callback awaits something that cannot happen, until the browser gives up on the
 transition entirely (`Transition was aborted because of timeout in DOM update`).
 Await a microtask, a task or a render — never a frame.
 
-That suspension lasts exactly as long as the callback, and **in a sub-document
-it takes the scrollbar with it**: an iframe's scrollbar is painted by the framed
-document, so it goes and comes back, shifting the layout by its width. A
-top-level page is spared — its root scrollbar is the compositor's. So a callback
-that waits on the network flickers every demo shown in an iframe while the same
-app, opened on its own, shows nothing. Keep the callback short, and suspect the
-frame before the code when a scrollbar blinks.
+**In a sub-document the suspension takes the scrollbar with it**: an iframe's
+scrollbar is painted by the framed document, so it goes and comes back for the
+length of the callback, shifting the layout by its width — a top-level page is
+spared, its root scrollbar being the compositor's. Keep the callback short, and
+suspect the frame before the code when a scrollbar blinks.
 
 ## `ready` rejects when the transition is skipped, `finished` when the update fails
 
 There is only ever one transition per document, so another one starting SKIPS
 this one — as does the document going hidden or its snapshot containing block
-changing size mid-movement (a phone's address bar folding, its keyboard
-opening). A skip rejects `viewTransition.ready`, with a stackless DOMException
-(`AbortError` "skipped", or `InvalidStateError` "aborted because of invalid
-state"). `viewTransition.finished` still FULFILLS on a skip: the end state is
-reached, only the animation is not. `finished` (and `updateCallbackDone`)
-reject for one reason only, the update callback throwing.
-
-So ending a transition means handling both ways of `finished` — `.finally()`
-does not handle a rejection, an unhandled one is what it leaves behind, and
+changing size mid-movement (a phone's address bar folding, its keyboard opening).
+A skip rejects `viewTransition.ready`, with a stackless DOMException (`AbortError`
+"skipped", or `InvalidStateError` "aborted because of invalid state").
+`viewTransition.finished` still FULFILLS on a skip: the end state is reached, only
+the animation is not. `finished` (and `updateCallbackDone`) reject for one reason
+only, the update callback throwing.
+
+So ending a transition means handling both ways of `finished` — `.finally()` 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, () => {})`.
 
+## An element captured in a view transition cannot be pointed at
+
+A captured element is not painted where it stands, and nothing hit-tests to it: a
+press over it falls through to the nearest ancestor still being painted, whatever
+the pseudo-elements are told about `pointer-events`. Under the root's default
+name, that is the whole page for the length of the movement. It is why a
+`RouteTravel` keeps the root out of its pictures, so the page around the box stays
+live, and catches a press on the travelling box at the document, handing it to the
+box it fell inside; and why a door in a bar a route transition photographs needs
+`pressableDuringRouteTransition` to stay pressable (see
+[route_transitions.md](./route_transitions.md#pages-between-fixed-bars-the-transition-area)).
+
 ## The top layer is painted through the root's picture
 
-A modal `<dialog>`, its `::backdrop`, a popover: the browser paints the top
-layer during a transition only as part of the root's picture. With `:root {
-view-transition-name: none }`, the wall and the dialog go unpainted for the
-length of the movement, and a named element inside the dialog is photographed
-empty (Chrome 153, reproduced in a bare page; in a long page it showed only
-past a few thousand pixels of scroll, which is how it hid). A transition that
-opens or closes a top-layer surface keeps the root's default name and pays the
-frozen page — under a modal wall that costs nothing. navi's own lift
-(`popup_lift.md`) does exactly that.
-
-When the root cannot be kept — a route transition splits the bars from the
-pages, which only works with the root opted out — the top layer has to be
-**stood in for**. A dialog's box is an element, so it can be named and
-photographed on its own. Its wall cannot: `::backdrop` wears no name. What
-works is painting what the wall paints into the pictures themselves: a plain
-element appended inside each photographed box (the pages, each bar) before
-each capture, and one `position: fixed` element in the live document for what
-no picture covers, with a hole cut where each picture stands. The live one is
-not a picture, so nothing cross-fades it: it is animated on the movement's own
-clock. Where a picture stands changes over the movement — the frame the first
-picture is taken on shows the leaving state, the last frame the arriving one,
-and in between only the intersection of the two states' rectangles is under a
-picture at every moment — so the holes are cut three times. Reference:
-`paintTransitionWalls` and `paintRestWalls` in `nav/transition_furniture.js`;
-the measured story is in [route_transitions.md](./route_transitions.md#pages-between-fixed-bars-the-transition-area).
+A modal `<dialog>`, its `::backdrop`, a popover: the browser paints the top layer
+during a transition only as part of the root's picture. With
+`:root { view-transition-name: none }`, the wall and the dialog go unpainted for
+the length of the movement, and a named element inside the dialog is photographed
+empty. A transition that opens or closes a top-layer surface keeps the root's
+default name and pays the frozen page — under a modal wall that costs nothing.
+navi's own lift ([popup_lift.md](./popup_lift.md)) does exactly that.
+
+When the root cannot be kept — a route transition splits the bars from the pages,
+which only works with the root opted out — the top layer has to be **stood in
+for**. A dialog's box is an element, so it can be named and photographed on its
+own; its wall cannot, `::backdrop` wears no name. What works is painting what the
+wall paints into the pictures themselves, plus a live element in the document for
+what no picture covers — not a picture, so animated on the movement's own clock,
+and switched on by the same DOM write that switches the real wall off (see
+[Two frames show the live document](#two-frames-show-the-live-document)).
 
 ## Two frames show the live document
 
 A view transition is not pictures from the call to `finished`. **The frame the
-first picture is taken on is rendered and shown**, with the top layer painted
-as usual, and `:active-view-transition` already matches on it (it matches from
-the `startViewTransition` call). **The frame after the pictures are dropped is
-shown too**, before the `finished` callbacks run — they are a frame late.
-Whatever is switched on for the movement is therefore on screen one frame
-before the pictures and one frame after; anything it stands in for must be
-switched off for exactly the same span, or that frame shows both (measured: a
-wall twice as dark under the press, read as a flash).
+first picture is taken on is rendered and shown**, with the top layer painted as
+usual, and `:active-view-transition` already matches on it (it matches from the
+`startViewTransition` call). **The frame after the pictures are dropped is shown
+too**, before the `finished` callbacks run — they are a frame late. Whatever is
+switched on for the movement is therefore on screen one frame before the pictures
+and one frame after; anything it stands in for must be switched off for exactly
+the same span, or that frame shows both (a wall twice as dark: a flash).
 
 Two consequences for the switch itself:
 
 - **Switch both on the same DOM write**, at the same moment: an attribute set
   before the call and removed in `finished`. The late frame then shows the
-  stand-in alone, which is what the real thing looked like — one frame nobody
-  can see.
-- **`:active-view-transition` is the only same-frame signal at the end**: it
-  stops matching in the rendering step that drops the pictures, before that
-  frame is painted. It is what to use when the last frame must differ from the
-  movement (see the holes above). It is NOT what to gate a stand-in's
-  `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.
+  stand-in alone, which is what the real thing looked like — one frame nobody can
+  see.
+- **`:active-view-transition` is the only same-frame signal at the end**: it stops
+  matching in the rendering step that drops the pictures, before that frame is
+  painted. It is what to use when the last frame must differ from the movement. It
+  is NOT what to gate a stand-in's `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.
 
 ## What makes a transition restyle the whole document
 
-Starting a transition restyles what changed and nothing more: in a bare page,
-the capture of the old state restyles a handful of elements, however long the
-page is. Two things make it restyle every one of them, in the frame the old
-state is photographed — on a page of ~4,700 elements, 17–21 ms at full speed
-and 60–90 ms with the CPU throttled 4×, added to every transition before
-anything moves:
+Starting a transition restyles what changed and nothing more: in a bare page, the
+capture of the old state restyles a handful of elements, however long the page
+is. Two things make it restyle every element of the page, in the frame the old
+state is photographed — added to every transition before anything moves:
 
 - **A `::highlight()` rule every element matches.** Written for the whole
-  document, `::highlight(x) { … }` makes Chrome restyle every element when a
-  view transition starts (Chrome 153, bare page: 10,009 of 10,009 elements; 6
-  once the rule is scoped). Scope it to the elements that hold the ranges —
+  document, `::highlight(x) { … }` makes Chrome restyle every element when a view
+  transition starts. Scope it to the elements that hold the ranges —
   `.results::highlight(x), .results ::highlight(x)` (both: a browser without
   highlight inheritance only paints what the rule matches). navi's own search
   highlight is scoped to list rows.
-- **A custom property changed on `:root`.** Every element inherits it, so
-  changing one restyles the document — and a movement changes its values as it
-  starts. What the pictures read belongs on `::view-transition` instead: the
+- **A custom property changed on `:root`.** Every element inherits it, so changing
+  one restyles the document — and a movement changes its values as it starts.
+  What the pictures read belongs on `::view-transition` instead: the
   pseudo-element tree inherits from it, and no element of the document does.
 
   ```css
@@ -160,41 +164,39 @@ anything moves:
   }
   ```
 
-  A value computed in JS cannot get there through an inline style, which
-  cannot target a pseudo-element: it goes in a rule of a sheet of its own,
-  `:root::view-transition {}`, set with `rule.style.setProperty()` (navi does
-  this in `nav/transition_values.js`).
+  A value computed in JS cannot get there through an inline style, which cannot
+  target a pseudo-element: it goes in a rule of a sheet of its own,
+  `:root::view-transition {}`, set with `rule.style.setProperty()`.
 
   A value JS has to read back is the exception: what JS reads off
   `::view-transition` is not reliable outside a live transition —
-  `getComputedStyle(root, "::view-transition")` answers while none runs, but
-  in Chrome and WebKit alike it went on answering empty for rules added after
-  its first read. Such a value stays on `:root`, registered with `@property`
-  and `inherits: false` so that the document does not inherit it, and is
-  handed to the pictures explicitly: `--x: inherit` on `::view-transition` and
-  on the pseudo-elements below it.
+  `getComputedStyle(root, "::view-transition")` answers while none runs, but in
+  Chrome and WebKit alike it went on answering empty for rules added after its
+  first read. Such a value stays on `:root`, registered with `@property` and
+  `inherits: false` so that the document does not inherit it, and is handed to the
+  pictures explicitly: `--x: inherit` on `::view-transition` and on the
+  pseudo-elements below it.
 
 Whatever does depend on the root is paid once, by the frame of the capture —
-unless a style read follows a write on the root, which forces the restyle on
-the spot, in the click. Read what the transition needs (names, rectangles)
-before writing anything on the root.
+unless a style read follows a write on the root, which forces the restyle on the
+spot, in the click. Read what the transition needs (names, rectangles) before
+writing anything on the root.
 
 ## A hidden element is not photographed, even in the top layer
 
 A popover or a modal `<dialog>` whose ancestor is `display: none` still matches
-`:popover-open` or `:modal`, but it is not rendered: `checkVisibility()` is
-false, its rectangle is empty, and a transition taking its pictures then has it
-on the old side only — it leaves, as if it were gone. `isConnected` says
-nothing about it; `checkVisibility()` is what tells which of the two states an
-element is part of. navi relies on it to keep the page left by a route
-transition mounted but out of the second picture (see
+`:popover-open` or `:modal`, but it is not rendered: `checkVisibility()` is false,
+its rectangle is empty, and a transition taking its pictures then has it on the
+old side only — it leaves, as if it were gone. `isConnected` says nothing about
+it; `checkVisibility()` is what tells which of the two states an element is part
+of. navi relies on it to keep the page left by a route transition mounted but out
+of the second picture (see
 [route_transitions.md](./route_transitions.md#the-page-being-left-stays-until-its-movement-is-over)).
 
 ## 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
+- [drag_to_travel.md](./drag_to_travel.md) — a transition held under a finger
+- [drag_interactions.md](./drag_interactions.md#naming-what-travels) — naming what
+  moves when something is dropped on a place

package/docs/z_index.md

@@ -11,15 +11,8 @@ Reach for the tools in this order.
 
 Between positioned elements that all have `z-index: auto`, the last one written
 paints in front. Moving a tag is the cheapest way to reorder, and it can never
-affect anything outside its parent.
-
-```jsx
-// The stamp paints over the content because it comes after it. No z-index.
-<Box position="relative">
-  <CardContent />
-  <Stamp />
-</Box>
-```
+affect anything outside its parent (see
+[the card at the end](#a-card-that-stacks-three-layers-with-no-z-index)).
 
 If the element that must be in front cannot move in the DOM (it is a slot, it
 is written by a consumer), that is a real reason to go further — "I did not
@@ -30,11 +23,8 @@ think about the order" is not.
 `z-index: 5` does not mean "in front of my siblings". It means "in front of
 everything painted lower **in the nearest stacking context**", and when no
 ancestor opens one, that context is the document root — including `FixedBar`,
-sticky list-group labels, and popups.
-
-This is the failure that keeps happening: a small `z-index` inside a card wins
-against a bar written at the other end of the page, because both are competing
-in the same, page-wide context.
+sticky list-group labels, and popups. That is how a small `z-index` inside a
+card wins against a bar written at the other end of the page.
 
 ## 3. If a `z-index` is genuinely needed, isolate
 
@@ -51,74 +41,51 @@ takes its place among its own siblings.
 
 A `z-index` inside a reusable component without this is a bug waiting for its
 call site: the component behaves differently depending on where it is dropped.
+An app writing its own number without it is competing with navi's scale (§5).
 
 ## 4. What creates a stacking context without you asking
 
 `opacity` below 1, `transform`, `filter`, `backdrop-filter`, `will-change`,
 `contain: paint`, `mix-blend-mode`, and a positioned element with a `z-index`
-other than `auto` all open one. Two consequences:
+other than `auto` all open one: something you faded or moved suddenly paints as
+a block, and a `z-index` written deeper inside stops reaching where you
+expected. The answer is still DOM order — write the layer that must be on top
+last — not a `z-index` "to repair it": adding one on top of an unnoticed
+stacking context is how a value ends up tuned to a symptom.
 
-- something you faded or moved suddenly paints as a block, in front of or
-  behind a sibling it used to interleave with;
-- a `z-index` you wrote deeper inside stops reaching where you expected,
-  because one of these ancestors now caps it.
+## 5. The values navi plays with
 
-The answer is still DOM order — write the layer that must be on top last —
-not a `z-index` "to repair it". Adding one on top of an unnoticed stacking
-context is how a value ends up tuned to a symptom.
+They live in `src/navi_z_indexes.js`, as tokens, in bands a decade apart — one
+can grow without reaching the next, and a value seen in devtools says which
+band it came from. From the bottom:
 
-## 5. The values navi plays with
+1, 2, 3 (a `Group` member hovered, focused, holding a popup open) < 10 (sticky
+parts, while something scrolls under them) < 100 (`FixedBar`) < 1000
+(`Dialog`/`Popover` with `layer="local"` and their backdrops, plus stack order)
+< 10000 (a modal's wall painted into the page for the length of a route
+transition, standing in for the top layer) < the top layer itself
+(`Dialog`/`Popover` with `layer="top"`, callouts).
 
-They all live in `src/navi_z_indexes.js`, as tokens, in one ordered list — the
-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             |
-| A modal's wall painted into the page for the length of a route transition, standing in for the top layer                            | `--navi-z-index-top-layer`                                                                            | 10000                        |
-| `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, `<Box sticky>` | `--navi-z-index-sticky`                                                                               | 10                           |
-| A `Group` member under the pointer, then the one holding focus, then the one holding a popup open                                   | `--navi-z-index-control-hovered`, `--navi-z-index-control-focused`, `--navi-z-index-control-expanded` | 1, 2, 3                      |
-| `Table` sticky cells, drag, resize                                                                                                  | `src/control/table/z_indexes.js`                                                                      | 1–7, derived from each other |
-
-What to read from it:
-
-- **The order matters more than the numbers.** A bar is above anything the page
-  scrolls, a popup above the bar, and a control raising itself above its
-  neighbour is at the bottom — a hovered control crossing the top bar is the
-  bug the gaps exist to make impossible.
-- **A z-index that only orders a component's own parts stays a literal** next to
-  the rule that needs it. Tokens are for what is decided against another
-  component; putting "above my own sibling" in the global list would only
-  dilute it.
-- **An app writing its own number is competing with this scale.** Write
-  `isolation: isolate` on the parent instead, and the number stops meaning
-  anything outside it.
+**The order matters more than the numbers.** A bar is above anything the page
+scrolls, a popup above the bar, and a control raising itself above its
+neighbour is at the bottom — a hovered control crossing the top bar is the bug
+the gaps exist to make impossible. **A z-index that only orders a component's
+own parts stays a literal** next to the rule that needs it (`Table` orders its
+sticky cells, drag and resize on a 1–7 scale of its own).
 
 ### A sticky part is only in the band while it is stuck
 
 `--navi-z-index-sticky` says "kept stuck while something scrolls under it", and
-the second half of that sentence is a condition, not decoration. A `List` group
-label at rest is a block in the flow: nothing passes under it, and painting it
-at 10 there is what slices a focus ring, a badge or a stamp that a neighbouring
-row lets out of its box — including a `Group` member raising itself to 1, 2 or 3.
-
-CSS cannot express the condition. There is no `:stuck`, and
-`@container scroll-state(stuck: top)` styles a container's **descendants**, so
-an element can never read its own stuck state — which is the one that matters
-here. So `List` measures it and marks its three sticky parts
-(`.navi_list_item_header`, `.navi_list_item_footer`,
-`.navi_list_item_group_label`) with `navi-stuck`, against its own scroller and
-not the window, updated on scroll, on resize, and on every commit (a virtualized
-list changes which labels exist without anything scrolling).
-
-navi's own rule is the first reader: the band applies under `[navi-stuck]`,
-`auto` applies at rest. That is what puts the decision back within reach of an
-app — a card whose badge overflows into the label below it gets past it with a
-literal in the card, against its own neighbour, exactly as §1–3 above ask:
+the second half of that sentence is a condition. A `List` group label at rest
+is a block in the flow: nothing passes under it, and painting it at 10 there is
+what slices a focus ring, a badge or a stamp that a neighbouring row lets out of
+its box — including a `Group` member raising itself to 1, 2 or 3.
+
+An element cannot read its own stuck state in CSS, so `List` measures it and
+marks its header, footer and group labels `navi-stuck`: the band applies there,
+`auto` at rest. That puts the decision back within reach of an app — a card
+whose badge overflows into the label below it gets past it with a literal in
+the card, against its own neighbour, exactly as §1–3 ask:
 
 ```jsx
 // Reaches past a label at rest (auto), loses to one that is stuck (10).
@@ -127,48 +94,32 @@ literal in the card, against its own neighbour, exactly as §1–3 above ask:
 
 For what a literal cannot reach, each part has a pair of variables —
 `--list-header-z-index`, `--list-footer-z-index`, `--list-group-label-z-index`,
-each with a `-stuck` counterpart defaulting to the band — settable on `<List>`
-with no selector and no navi class name. Reach for them last, and remember a
-negative value is compared against the page like any other: without a stacking
-context between the label and the nearest opaque background, `-1` does not put
-the label behind the rows, it puts it behind that background and out of sight.
-
-See the "Sticky parts" chapter of
+each with a `-stuck` counterpart defaulting to the band — settable on `<List>`.
+Reach for them last, and remember a negative value is compared against the page
+like any other: without a stacking context between the label and the nearest
+opaque background, `-1` does not put the label behind the rows, it puts it
+behind that background and out of sight. See the "Sticky parts" chapter of
 [12_list_demo.html](../src/control/demos/12_list_demo.html).
 
-`<Box sticky>` and `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.
+`Box`'s own sticky `header`/`footer` — the shape without a `body`; beside a
+body they are plain blocks — and `<Box sticky>` take the opposite default: they
+are in the band **always**, not only while stuck. A `Box` cannot tell: it is
+the generic scrolling area, its content is whatever the app puts in it, and a
+sticky part at `auto` loses to anything that content positioned, a `transform`
+or an `opacity` below 1 included. The scrolling box is `isolation: isolate`, so
+the band stays local to it. At the one call site that knows nothing inside is
+positioned — a badge or a stamp overflowing a row is otherwise sliced by a
+header it never scrolls under — `--box-header-z-index: auto`
+(`--box-footer-z-index` likewise) writes it back.
 [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.
 
-`<Box sticky>` — the one an app writes by hand — is that same generic case, so
-it carries the band too, from the `sticky` prop itself (`position="sticky"`
-included):
-
-```jsx
-// position: sticky + z-index: var(--navi-z-index-sticky). Nothing to write.
-<Box sticky bottom>
-  <SubmitButton />
-</Box>
-```
-
-Without it the box is a positioned element at `z-index: auto`, and anything the
-page raised passes in front of it — a `Group` member holding focus is at 2, so
-it is seen crossing a submit bar the box was written to keep last. DOM order
-cannot answer that (2 beats `auto` whatever the order) and `isolation: isolate`
-neither (the common parent holds both, isolating it does not reorder them), so
-without the band the app would have no move left but a literal of its own.
-
-An explicit `zIndex` wins, `zIndex="auto"` included — the way
-`--box-header-z-index` writes the band back at a call site that knows better:
+`<Box sticky>` carries the band from the prop itself. Without it, a `Group`
+member holding focus (2) would be seen crossing a submit bar the box was written
+to keep last, and neither DOM order nor `isolation` can answer that: 2 beats
+`auto` whatever the order, and the common parent holds both. An explicit
+`zIndex` wins, `"auto"` included:
 
 ```jsx
 // Back to auto: this one is meant to slide under the card that follows it.
@@ -183,10 +134,11 @@ member that comes after it in the DOM. DOM order cannot express "whichever one
 is hovered", so this is a legitimate `z-index`.
 
 `isolation: isolate` on the group would contain those values, but it would
-also contain the popup of a `Picker` held in the group: its 1000 would become
-local, and the popup would be capped inside the group instead of covering the
-page. So the group is deliberately not isolated, and what keeps its 1, 2 and 3
-harmless is the scale above them.
+also contain the popup of a `Picker` held in the group when that popup stacks
+in the page (`popupLayer="local"`): its 1000 would become local, and the popup
+would be capped inside the group instead of covering the page. A top-layer
+popup, the default, escapes any stacking context. So the group is deliberately
+not isolated, and what keeps its 1, 2 and 3 harmless is the scale above them.
 
 ## A card that stacks three layers with no `z-index`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/navi",
-  "version": "0.29.418",
+  "version": "0.29.419",
   "type": "module",
   "description": "Library of components including navigation to create frontend applications",
   "repository": {
@@ -34,7 +34,7 @@
     "preact": "^11.0.0-rc.2"
   },
   "dependencies": {
-    "@jsenv/dom": "0.17.84",
+    "@jsenv/dom": "0.17.85",
     "@jsenv/humanize": "1.8.6",
     "@jsenv/validity": "0.4.5"
   },

package/docs/badge_list.md

@@ -1,83 +0,0 @@
-# BadgeList
-
-A row of badges that wraps. What it does at runtime depends on what it is asked
-for, and nothing is set up for a case that cannot happen:
-
-- **plain** — no `max`, no `maxLines`, no `fallback`, no `shrinkWrap`: one
-  element holding its children as-is. No registry, no effect, no measurement.
-- **`max` / `fallback`** — the badges are counted (see below), nothing is
-  measured, no DOM is watched.
-- **`shrinkWrap`** — a hidden clone of the list is laid out to find the widest
-  wrapped row, and the list is narrowed to it so the last row isn't ragged.
-  Opt-in outside a `Picker` (a picker draws a border around the list, so the
-  ragged edge shows; elsewhere the work would often go unseen). With `maxLines`
-  the rows are read first, at the full width, and the list is narrowed once the
-  surplus is gone — in place, no clone.
-- **`maxLines`** — every badge is laid out once, hidden; where the rows fell is
-  read; the list is rendered again with the badges that fit and a `+N more`
-  badge for the rest. Both renders land in the same frame. A width change of
-  the room around the list triggers another measure — not a change of the
-  list's own width, which is what it produces, not what it is given.
-
-## How badges are counted
-
-Once the list has something to decide — a `max`, a `fallback`, `maxLines` — a
-`Badge` inside it does not render itself: it hands its props to the list
-through `BadgeListContext` and renders nothing (a plain list leaves its badges
-to render themselves). Badges register in tree order, so by the time the list
-gets to its own content it holds them all
-and knows how many there are before deciding what to show — without walking
-children vnodes, and without rendering a badge it then has to take back.
-
-Two consequences:
-
-- a `Badge` must be a **direct** child of the list — its rendering is moved
-  into the list, so `<div><Badge /></div>` takes the badge out of its wrapper;
-- a badge's own `key` goes to the registering vnode and not to the badge the
-  list draws, which is keyed by position. Reordering recreates the nodes rather
-  than moving them.
-
-## `maxLines` in a Picker
-
-A picker clamps its value with `maxLines`, which is CSS line-clamp — it counts
-line boxes of inline text and never sees a wrapped flex row. So a `BadgeList`
-rendered as a picker's `ui` reads the number from `MaxLinesContext` instead
-(the picker provides it, default 1) and caps its own rows to it, and the picker
-turns its own clamp off (`.navi_picker_value:has(.navi_badge_list)`). Nothing
-to set on the list; `maxLines` on the picker is enough, and a `maxLines` on the
-list itself is a local override.
-
-`max` is a different cap: a number of badges, whatever the rows. The two
-compose — the `+N` badge takes one of the `max` slots.
-
-## The `fallback`
-
-Without a `fallback`, an empty list renders **nothing**. Inside a picker there
-is one more thing to know: a picker given a `ui` draws that and only that, its
-own `placeholder` is **not** drawn next to it. An empty `BadgeList` in a picker
-is a blank picker — so the list's `fallback` is the placeholder, and the
-placeholder text is what to pass:
-
-```jsx
-<BadgeList fallback="Select skills…">
-  {selected.map((skill) => (
-    <Badge key={skill}>{skill}</Badge>
-  ))}
-</BadgeList>
-```
-
-Plain text is the right shape for it. It reads at the picker's own size, in the
-placeholder color — the picker colors its value slot that way while it holds
-nothing — and the picker box stays the same height empty and filled: the box is
-held one line tall by the picker's own line (the right slot is `1lh`), whatever
-the slot inside holds. That slot is a fraction of a pixel taller with a line of
-text than with a row of badges (0.89px at the default font size — a line is set
-by the picker's font and line-height, a badge by its own padding and smaller
-font), which nothing shows.
-
-A transparent `Badge` as fallback matches the slot to the pixel instead, but its
-text is badge-sized — smaller than the picker's — and reads as a badge with
-nothing in it. Only worth it where the slot itself is what something else is
-sized on. Section 4 of `src/control/demos/picker/2_select_multiple_demo.html`
-measures the three cases (no fallback, plain text, transparent badge), box and
-slot side by side.