@jsenv/navi 0.29.463 → 0.29.465

package/docs/AI_INSTRUCTIONS.md

@@ -147,9 +147,11 @@ 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; and the browser's
-  `theme-color` that a popup paints over. Before CSS for a backdrop, or a
-  `theme-color` meta.
+  outside press does, how far the page withdraws; popups that hand over to
+  each other in one press (`PopupGroup`: the wall around a box of the page);
+  and the browser's `theme-color` that a popup paints over. Before CSS for a
+  backdrop, a `theme-color` meta, or making a popup's neighbours pressable
+  above its wall.
 - `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

@@ -511,15 +511,30 @@ on, and the position stays for the visit that brings it back. What it costs: a
 slow read that every page asks for delays the position of every page, since
 nothing tells navi which reads set the height.
 
-A route action that starts asking later is waited for too: one gated on app
-state the page did not have yet (`when`, or params that read an app-wide read
-such as the signed-in user), or one whose params are another's answer. Before it
-asks, nothing tells "not yet" from "never", so the position is written into what
-the page shows — and stays pending while a route action of the page has not
-asked: the next one that starts without an answer is waited for the same way,
-and the position is put back again once it is drawn. It ends once every route
-action of the page has asked; an action that never asks on this page (a search
-with no query) keeps it pending until the reader takes over.
+A route action that starts asking later is waited for when it says what it
+waits for: its `when`, a condition on app state the page did not have yet (the
+signed-in user, an age gate). The position is written into what the page shows
+and stays pending while a `when` of the page says no; the action that starts
+once it holds is waited for the same way, and the position is put back again
+once it is drawn. Params that say no are not waited for: they read the address,
+and this one asks nothing of the action — when it asks later (a search typed),
+the page has changed under the reader, and writing the old position would undo
+whatever they or the app did meanwhile. So a gate on app state goes in `when`,
+and the params keep what depends on the page:
+
+```js
+const BOOK_ACTION = routeAction(
+  BOOK_ROUTE,
+  BOOK.GET,
+  () => ({ slug: bookSlugSignal.value }),
+  { when: () => catalogOpenSignal.value },
+);
+```
+
+A `when` that never holds on this page (a reader who is not an admin) keeps the
+position pending until the reader takes over. An action whose params are
+another's answer needs nothing: the position is read again once that answer is
+drawn, and the action asking by then is waited for.
 
 **What navi cannot see, the page says**: a read it starts itself
 (`useAsyncData(…, { run: true })`), content whose height arrives late. While

package/docs/popup_backdrop.md

@@ -55,10 +55,12 @@ absorb at all.
 
 **It is what decides whether a popup is modal.** `Popover` is never modal,
 either layer, and neither is a `layer="local"` dialog. A top-layer `Dialog` is
-modal exactly when it has a wall: with one it is `showModal()`'d and the browser
-makes everything behind genuinely inert; without one it goes to the same top
-layer through the Popover API, placed against the screen just the same, over a
-page that stays live. `Popup` forwards `backdrop` in both modes, so which of
+modal exactly when it has a wall of its own: with one it is `showModal()`'d and
+the browser makes everything behind genuinely inert; without one it goes to the
+same top layer through the Popover API, placed against the screen just the
+same, over a page that stays live — or, in a `PopupGroup`, over a page the
+group's wall covers (see
+[Popups that hand over to each other](#popups-that-hand-over-to-each-other-popupgroup)). `Popup` forwards `backdrop` in both modes, so which of
 popover or dialog the small-screen resolution picks says nothing about whether
 one press or two are needed.
 
@@ -77,14 +79,17 @@ Going `layer="local"` to keep the map live instead confines the sheet to the box
 it was declared in — full width and flush against _that_, which on a partial
 container reads as a sheet that failed rather than as a sheet.
 
-What a dialog that is not modal — wall-less, or `layer="local"` — gives up is
-the one thing only a modal gets natively: the hardware/gesture back button no
-longer dismisses it. No web API hooks into that outside the browser's own
+Outside a `PopupGroup`, what a dialog that is not modal — wall-less, or
+`layer="local"` — gives up is the one thing only a modal gets natively: the
+hardware/gesture back button no longer dismisses it. No web API hooks into that outside the browser's own
 modal-dismissal stack, which only a genuine `showModal()` element joins: an
 accepted limitation, not an oversight. A wall-less `Dialog` does not trap the
 focus either, deliberately — a page meant to be reachable is meant to be
 reachable with the keyboard too. (A `SidePanel` that closes on an outside press
-does trap Tab in popover mode: it sets `focusCapture`.)
+does trap Tab in popover mode: it sets `focusCapture`.) In a group the group is
+the modal: the back gesture closes the open popup as a cancel, and the keyboard
+stays in the group (see
+[Popups that hand over to each other](#popups-that-hand-over-to-each-other-popupgroup)).
 
 `pressOutside="capture"` and `backdrop={false}` contradict each other —
 absorbing is what a wall does — and navi warns rather than silently behaving
@@ -183,7 +188,8 @@ beside the board still closes when a card is pressed. Unlike the outside marker,
 this one answers for its whole subtree: it adds a whole thing to the popup's
 ground — the card, its count, its buttons — and nothing in it is a dismissal. It
 reads a press the page hears, so it belongs with a popup that has no wall
-(`backdrop={false}`): behind a wall, no card is pressable.
+(`backdrop={false}`), or with a popup of a `PopupGroup` and a box of that group:
+behind a wall, no card is pressable.
 
 ### `pointer-events: none` and `inert` are not this
 
@@ -196,6 +202,116 @@ the marked box, either makes the marker unreachable (navi warns about
 `pointer-events: none` is the one useful case: the press falls to the marked
 box, which is the answer wanted.
 
+## Popups that hand over to each other: `PopupGroup`
+
+A wall spends the first press, and between popups that follow one another that
+is the wrong press to spend. On a row of score cells, each a picker, going from
+one cell to the next costs a press to dismiss and a second one to open, though
+the user pointed at the next cell straight away. `backdrop={false}` gives the
+press back, but leaves the whole page live; `"invisible"` hides the dim and
+gives nothing back.
+
+`PopupGroup` keeps the wall and moves it: around a box of the page, with that
+box in front.
+
+```jsx
+<PopupGroup backdropColor="rgb(6 10 20 / 60%)">
+  <Picker mode="popover">…</Picker>
+  <Picker mode="popover">…</Picker>
+  <Button action={addSet}>+</Button>
+</PopupGroup>
+```
+
+While one of its popups is open, what the group holds stays lit and answers for
+real — hover, the pressed state, a gesture, the focus — and the rest of the
+screen is behind the wall, which can now be dimmed: the screen says what
+answers. A row of score cells, a menu bar, a toolbar, the players of a court
+each opening a bubble.
+
+### Inside is the DOM
+
+A popup is a member by being rendered inside the group: no name, no id.
+`Popover`, `Dialog` and what is built on them count — `Popup`, `SidePanel`,
+`SplitButton`, a `Picker`'s popover, dialog or callout. Every other control the
+group holds is pressable too: a "+" or a delete button needs nothing.
+
+**What is not a descendant of the group is behind the wall, wherever it is
+painted.** While a popup of the group is open, the group is the modal, and the
+browser makes everything else inert: a neighbour lifted above the wall with a
+`z-index`, or rendered elsewhere through a portal, is painted and dead.
+
+A popup opened from inside a member is in front of it, not a peer of it: the
+group stops at each popup. What is lit is the group's whole box, its background
+and border with it, so the group is the smallest box that holds the peers — on a
+court that also draws its links and its empty seats, a layer that holds only
+the players.
+
+### What a press does while one is open
+
+- On another popup's trigger: the open popup closes — a `Picker` notes its
+  value — and that one opens, in the same press.
+- On anything else in the group: the open popup closes, and the press does what
+  it does there.
+- On the wall: the open popup closes, and nothing else hears the press.
+- Inside the open popup, or on a box marked `data-navi-popup-inside` for it:
+  nothing closes.
+
+One popup of the group is open at a time: a press on another trigger, or a
+popup opened from the keyboard or from code, asks the open one to close first.
+A popup that refuses to close (a value it cannot note) stays open: it keeps the
+press, and nothing else opens; one opened from the keyboard or from code opens
+beside it.
+
+**`pressOutside` stays the popup's, read against a wall that is always there.**
+`"close"` and `"cancel"` work as everywhere, `"capture"` spends the press and
+stays open, and `"ignore"` closes like `"close"`: there is no page under it to
+reach. `backdrop={false}` on a member changes nothing.
+
+### The group is the modal, its popups are not
+
+A `Dialog` in a group is never `showModal()`'d: it goes to the top layer
+through the Popover API, above the group. It keeps what a modal gives all the
+same, since the group is one: everything outside is inert, the keyboard reaches
+only what the group holds, and Escape and the back gesture close the open popup
+as a cancel, wherever the focus is in the group. A group works inside a sheet,
+and closes with it.
+
+**The wall is the group's.** `backdropVariant`, `backdropColor` and
+`backdropFilter` go on `<PopupGroup>`, whose default paint is the `close` pair,
+like a top-layer `Dialog`'s. A member's own are not read, and navi warns in
+dev; neither is what its `"capture"` or its `animation="lifting"` would paint —
+`backdropVariant="lift"` on the group is that wall. Above the screen, the
+browser's colour is the group's wall over the page's colour, and the group's
+`themeColor` answers for it; a member flush with the top edge still lays its
+surface over that, and a member's own `themeColor`, when it names a colour,
+gives the colour while it is open.
+
+**The page behind stays still while a `Popover` or a `Dialog` of the group is
+open**, the wheel or the finger on the wall or over a part of the group with
+nothing to scroll. A callout of the group lets the page scroll, as a callout
+does anywhere, and goes away on that scroll when told to
+(`calloutCloseByScroll`) — where the group stands in the page's own scroll. In
+a sheet, a list that scrolls on its own or a fixed bar, a gesture on the wall
+could only scroll the document behind, never the box the group stands in: the
+page stays still there too, and a wheel over the bubble still scrolls that
+box.
+
+### While one is open, the group leaves the page
+
+To stand in front, the group is shown in the top layer where it stands. An
+invisible placeholder keeps its place in the page — the element just before it,
+marked `navi-out-of-flow` (see
+[`css_architecture.md`](./css_architecture.md#counting-children-what-navi-puts-in-your-tree))
+— and the group stays pinned to that place: it follows a scroll, a resize, a
+sheet that moves, and is clipped as its ancestors clip it. At rest it is a
+`<dialog>` the app styles as it would a `<div>`.
+
+Two things follow from the group being the modal. A `Dialog` rendered among
+the group's peers is a member, never modal; one opened from inside a member is
+in front of it, and modal as anywhere. And a drag that starts in the group
+while one of its popups is open cannot land outside it until that press is
+over.
+
 ## Painting one popup: two props
 
 ```jsx
@@ -333,6 +449,7 @@ renderer:
 | `Dialog layer="top"`   | the native `::backdrop` pseudo-element of the `<dialog>`          |
 | `Dialog layer="local"` | a sibling `div.navi_dialog_backdrop`, before the dialog's wrapper |
 | `Popover`              | a sibling `.navi_popover_backdrop`                                |
+| a popup of a group     | the native `::backdrop` of the `PopupGroup`'s `<dialog>`          |
 
 The pseudo-element inherits custom properties from the dialog — which is what
 makes the tokens above reach it at all. The sibling elements do not: they

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/navi",
-  "version": "0.29.463",
+  "version": "0.29.465",
   "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.90",
+    "@jsenv/dom": "0.17.91",
     "@jsenv/humanize": "1.8.7",
     "@jsenv/validity": "0.4.5"
   },