@jsenv/navi 0.29.218 → 0.29.220

package/docs/actions.md

@@ -244,6 +244,17 @@ invisible at the call site and expensive on screen: the request then leaves with
 the gesture instead of with the screen, one waterfall behind everything else the
 address needed.
 
+**A route action is a read.** The parameter says whose data it is; it does not
+say who may ask for it. An address asks again on every arrival — a reload, a
+pasted link, a step back — which is exactly what a read is for and what a write
+cannot survive: `POST /users/:id/invitations` hung on `/users/:id` mints a token
+per reload, for ever, and nothing at the call site says so. So a run that writes
+belongs to the component that decided to write, whatever its parameter, and
+`{ run: true }` is what says it. That is the shape of a request prepared for a
+gesture — a token a share button must already hold when it is pressed, since the
+OS share sheet only opens inside the gesture and never after an `await`: it runs
+at mount because the press cannot wait for it, not because the address changed.
+
 `{ onLoad }` is what the screen does with the data **once, when it becomes
 known** — seed the fields someone is about to edit, focus something, remember
 where a list was:

package/docs/navigation.md

@@ -894,9 +894,12 @@ one tab further, and back to `/me?settings` returning to the first.
 
 Two params, because they answer two questions — is the layer there, and which of
 its pages is shown. One param whose value is "which page of the layer, or none"
-(`?settings=alerts`) is arguably the shape the address wants, and it is not
-expressible today: a popup says its open state as a boolean, so it would
-overwrite the tab on every open.
+(`?settings=alerts`) is arguably the shape the address wants, and a popup cannot
+hold it: it is open on exactly one value of its signal (`value`, see
+[popup_open.md](./popup_open.md#signal--the-app-holds-it-both-ways)), so a tab
+changing under it would read as the layer closing. `value` is for the other
+question — WHICH of several popups is open, one sheet per card under a single
+`?seat=<gameId>` — not for what varies inside one.
 
 ### What it costs
 

package/docs/popup_open.md

@@ -687,6 +687,21 @@ which is what every navi control does with its value (see
 on them (`SidePanel`) all take it. A signal already `true` at mount means the
 popup was already open when the page appeared: no entrance plays.
 
+`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:
+
+```jsx
+<Dialog signal={seatSheetSignal} value={game.id} />
+```
+
+The popup is open while the signal holds its value and closed otherwise;
+opening writes the value, closing writes `undefined`, which a state signal reads
+as its default and takes out of the url. Everything above still holds — the
+same writes, the same history rules — only what "open" is worth in the signal
+changes. A popup is open on exactly one value: what varies while it is open (a
+tab inside it) is a param of its own, see
+[navigation.md](./navigation.md#places-inside-the-layer).
+
 ### `navState` — the history entry holds it
 
 ```jsx
@@ -756,6 +771,31 @@ const GroupMembers = () => {
 };
 ```
 
+The same shape when the popup is one of many — a sheet on every card, opened
+from wherever the card is read. Its open state then says which one, and the
+route action reads the id straight from it. Declared on the root route, since a
+card is not a page:
+
+```js
+const seatSheetSignal = stateSignal(undefined, {
+  id: "seat",
+  type: "string",
+  weak: true,
+});
+const ANY_PAGE = route("/", { searchParams: { seat: seatSheetSignal } });
+
+export const SEATABLE_USERS = routeAction(ANY_PAGE, USER.GET_MANY, () => {
+  const gameId = seatSheetSignal.value;
+  return gameId ? { game: gameId } : false;
+});
+```
+
+```jsx
+<Dialog signal={seatSheetSignal} value={game.id}>
+  <SeatableUsers />
+</Dialog>
+```
+
 **A popup that waits holds its own `<Loading>`**, like every other part of a
 screen that can wait — it is not built into `Dialog`/`Popover`, because only the
 code inside knows whether anything in there loads at all:

package/package.json

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