@jsenv/navi 0.29.430 → 0.29.432

package/docs/AI_INSTRUCTIONS.md

@@ -143,7 +143,9 @@ start when unsure which export solves a problem.
   own actions). Before passing `open`, calling `triggerNaviCommand`, or
   writing a close button.
 - `popup_backdrop.md` — three independent questions: a wall or not, what an
-  outside press does, how far the page withdraws. Before CSS for a backdrop.
+  outside press does, how far the page withdraws; and the browser's
+  `theme-color` that a popup paints over. Before CSS for a backdrop, or a
+  `theme-color` meta.
 - `popup_lift.md` — `animation="lifting"`: the pressed card brought to the front.
   Before giving a `Dialog` or a `Picker` `animation="lifting"`.
 - `dialog_shape.md` — bounds rather than a width, the container ceiling, the

package/docs/navigation.md

@@ -26,6 +26,7 @@ linking to them, and turning them into tabs.
   - [What the search param buys: the way back is in the address](#what-the-search-param-buys-the-way-back-is-in-the-address)
   - [The wiring](#the-wiring)
   - [Places inside the layer](#places-inside-the-layer)
+  - [A link inside the layer leads to a page](#a-link-inside-the-layer-leads-to-a-page)
   - [What it costs](#what-it-costs)
 
 ## The rule that decides everything else: the position belongs in the URL
@@ -783,7 +784,9 @@ Every piece of it answers something:
   off screen;
 - **no `defineRouteTransition` for it.** The page beneath does not change, so
   there is no pair of pages to move between — route transitions are for pages
-  replacing pages ([route_transitions.md](./route_transitions.md)).
+  replacing pages ([route_transitions.md](./route_transitions.md)). When a link
+  inside the layer does change it, see
+  [below](#a-link-inside-the-layer-leads-to-a-page).
 
 ### Places inside the layer
 
@@ -811,6 +814,30 @@ is shown. A popup's `value` answers another one, WHICH of several popups is open
 (one sheet per card under a single `?seat=<gameId>`), not what varies inside one
 (see [popup_open.md](./popup_open.md#signal--the-app-holds-it-both-ways)).
 
+### A link inside the layer leads to a page
+
+The terms of use behind an About dialog, a profile behind a name in the
+notifications: a link inside the layer leads to another page, and the layer does
+not follow — its params are `weak`, the link drops them, and the layer closes in
+the navigation that brings the page. The back button brings both back: the page,
+and the layer over it as it was, on the tab it was on.
+
+Neither is a movement of the layer's. **The page changing is its movement**: a
+layer opened or closed by the navigation that puts another page on screen plays
+no entrance and no exit, and its slides land where the address puts them rather
+than travelling there — a tab row's indicator with them. A route transition
+towards that page already carries the layer: photographed with the page it
+covers, it leaves with that page and comes back with it
+([route_transitions.md](./route_transitions.md#pages-between-fixed-bars-the-transition-area)).
+Without one, the page cuts, and the layer cuts with it. Played on its own as
+well, the layer would move twice — dropping in over a page that is sliding.
+
+The line is the page, not how the navigation was made: the back button closing
+the layer itself (`/me?settings` → `/me`) is the layer's own movement, and plays
+its exit. A page is what navi moves between — a new path, or a param that a
+relation or a `RouteTravel` row names as a page. A search param the page merely
+reads keeps the page, and a layer that changes with it moves on its own.
+
 ### What it costs
 
 This is a compromise, and it is worth stating rather than discovering:

package/docs/popup_backdrop.md

@@ -254,6 +254,59 @@ eye is on — a picture opened full, a plan, a card painting its own surface.
 `"invisible"` is the one kind with no filter token: it paints nothing, and a
 filter would still be seen.
 
+## Above the screen: the browser's colour
+
+On a phone the browser paints a band above the page — Chrome's address bar, the
+status bar of an installed app — in the colour of `<meta name="theme-color">`.
+It touches the page's top edge, so it reads as part of whatever is drawn there.
+A backdrop that stops at the top of the viewport, under a band still at full
+brightness, reads as two layers that do not belong together. So navi works that
+colour out from what is on screen:
+
+- **The page says it with `<Head>`**, the way it says its title:
+
+  ```jsx
+  <Head>
+    <meta name="theme-color" content="#2563a8" />
+  </Head>
+  ```
+
+  The last `<Head>` to arrive wins, whatever order they leave in (a route
+  transition puts the arriving page up before it takes the leaving one down). A
+  `theme-color` meta written in the HTML shows when no `<Head>` gives one.
+
+- **Each open popup in the top layer paints over it**, in the order they
+  opened: its backdrop colour over the colour under it, then its own background
+  over that when it is flush with the top edge — `marginWithContainer={0}` with
+  `expand`/`expandY` or a top `positionArea`, which is what a full-screen
+  dialog or a `SidePanel side="top"` is. A wash of `rgba(12, 23, 44, 0.45)` over
+  a `#2563a8` bar gives `#1a4170`. A navy full-screen dialog gives its navy.
+
+The colour changes when the opening starts, and changes back when the closing
+starts. If the page under an open popup changes its colour, the popup paints
+over the new one. Each `media` a page gives (one colour per
+`prefers-color-scheme`) is painted over on its own.
+
+Nothing is written at the call site. The `themeColor` prop is for what navi
+cannot read:
+
+- the `backdropFilter` is left out: a flat colour has nothing to blur;
+- a surface painted with an image or a gradient has no colour to read, and
+  `themeColor="#0c172c"` gives it one;
+- `themeColor={false}` leaves the colour under the popup as it is.
+
+A popup that lays nothing over the edge changes nothing: `backdropVariant="invisible"`,
+`backdrop={false}`, a `Popover` without a backdrop, any `layer="local"` popup.
+A `Popover` paints its backdrop only, never its surface: it has no notion of
+being flush with an edge.
+
+**A `<Head>` inside a popup does not give the popup's colour.** It counts as a
+page's `<Head>`, under every popup, including the one holding it. It also stays
+after the closing. A popup's content stays mounted once built (`mount`, see
+[`popup_open.md`](./popup_open.md)), and its `<Head>` stays with it, so its colour
+remains after the popup has gone. `themeColor` lasts exactly as long as the
+popup is open.
+
 ## Why props, and not a rule in the app's stylesheet
 
 **The backdrop is not inside the popup**, and which element it is depends on the

package/docs/popup_open.md

@@ -636,7 +636,10 @@ opens or closes on its own — Escape, the backdrop, a `--navi-close` — and af
 a close a busy control denied, when the signal says "open" again, because that
 is what is true (see [state_binding.md](./state_binding.md)). A signal already
 `true` at mount means the popup was already open when the page appeared: no
-entrance plays.
+entrance plays. Nor does an opening — or an exit — the signal asks for in the
+navigation that puts another page on screen: that page is the popup's movement
+([navigation.md](./navigation.md#a-link-inside-the-layer-leads-to-a-page)), and
+the same holds for `open` and `navState`.
 
 `value` makes the signal say WHICH popup is open, for several sharing it — one
 sheet per card in a feed, with a single `?seat=<gameId>` for all of them:

package/docs/route_transitions.md

@@ -267,7 +267,11 @@ travelling with the pages has a rectangle where it will be, not where it is seen
 finger is on the box — and leaves the bars live.
 
 A **modal `Dialog` open on a page** is furniture of the same kind: it travels with
-its page, or holds if both states have it. Its wall cannot be photographed (see
+its page, or holds if both states have it. One the navigation itself opens or
+closes — a layer whose `weak` param the link drops, or the back brings back —
+moves that way only, with no entrance or exit of its own on top
+([navigation.md](./navigation.md#a-link-inside-the-layer-leads-to-a-page)). The
+dialog's wall cannot be photographed (see
 [view_transitions.md](./view_transitions.md#the-top-layer-is-painted-through-the-roots-picture)),
 and dropping it for the movement makes the window blink under the press, so navi
 paints it into the pictures: a page leaving from under a wall leaves dimmed, one
@@ -450,8 +454,9 @@ What that means for a page and for the application around it:
 - **It is taken down after the page arriving is up.** A cleanup that puts back
   what it found — a document title, a class on `<body>`, a value in a shared store
   — puts a stale value back over the new page's. Such a registration is written as
-  "the last to arrive wins": navi's `<Head>` keeps its titles as a stack, and a
-  slot shows the last `SlotFill` to arrive.
+  "the last to arrive wins": navi's `<Head>` keeps its titles and its
+  `theme-color` metas as a stack, and a slot shows the last `SlotFill` to
+  arrive.
 - **What it fills outside its own nodes leaves at once.** A `SlotFill` in a page
   kept while leaving steps out of its slot, so a bar each page fills shows the
   page arriving — or nothing, when that page fills none.

package/package.json

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