@jsenv/navi 0.29.100 → 0.29.102

package/docs/control_group.md

@@ -47,14 +47,19 @@ Live examples: `src/control/demos/15_group_demo.html`.
   last one loses it on the other side, and any member in between loses all
   four. A single member keeps its own radius — a group of one looks like the
   control alone. The ask is made twice, in two forms — see below.
-- **Overlap order**: the member under the pointer, and the member showing a
-  focus ring, paint above their neighbours (`position: relative` plus
-  `--navi-z-index-control-hovered` / `-focused`). Without it the border color
-  change and the focus ring of the active member would be sliced by whichever
-  neighbour is painted after it. The focused member is matched whether it wears
-  `data-focus-visible` itself or merely contains it — a control that wraps a
-  real input (`Picker`, `Spin`) draws the ring on its own frame while the
-  keyboard is held inside. There is deliberately no `isolation: isolate` — see
+- **Overlap order**: the member under the pointer, the member showing a focus
+  ring, and the member holding something open (`aria-expanded="true"`) paint
+  above their neighbours (`position: relative` plus
+  `--navi-z-index-control-hovered` / `-focused` / `-expanded`). Without it the
+  border color change and the focus ring of the active member would be sliced
+  by whichever neighbour is painted after it. The focused member is matched
+  whether it wears `data-focus-visible` itself or merely contains it — a
+  control that wraps a real input (`Picker`, `Spin`) draws the ring on its own
+  frame while the keyboard is held inside; the expanded member is matched the
+  same way, since it can be wrapped in an enrobage. Expanded ranks highest: a
+  `Picker` opened by a click shows no focus ring, hands the focus to its popup
+  and lets the pointer travel to a neighbour, yet its border keeps saying it is
+  the one open. There is deliberately no `isolation: isolate` — see
   [z_index.md](./z_index.md).
 
 Nothing else: a group does not restyle its members, does not impose a size,
@@ -113,7 +118,7 @@ opened it. `Popover` and `Dialog` stop it too, at their own root: nothing a
 popup holds is at a seam.
 
 Reference: `.navi_button_content` in `button_ui.jsx` (a button reads then
-stops), `.navi_picker_right_slot`, `.navi_input_slot`, `.navi_popover`,
+stops), `.navi_picker_box`, `.navi_input_slot`, `.navi_popover`,
 `.navi_dialog`.
 
 A control that declares its radius on an inner element instead is invisible to

package/docs/interactions.md

@@ -105,6 +105,20 @@ interaction happened, and nothing runs. A `Box` with no control anywhere near it
 still answers a callback; only `"request_action"` has nothing to ask, and says so
 in dev.
 
+The one thing the gate weighs besides the control's state is what the
+interaction would do to it. Everything writes unless it says otherwise; an
+interaction that only shows what is already there declares `intent: "read"`, and
+a control held read-only lets that one through. That is how a read-only
+`<Picker>` still opens: the popup is where its answer is really drawn, so it
+opens and everything inside it is held read-only in turn. Disabled and busy go
+on refusing either way — one is out of service, the other is mid-operation, and
+neither has anything to show.
+
+Which controls let a read through is theirs to say, not the caller's: a picker
+with no popup of its own opens the browser's, which cannot be held read-only, so
+that one refuses. `openWhileReadOnly={false}` is how a caller says the popup is
+a form with nothing to read.
+
 ## What a swipe draws, and what it leaves to you
 
 navi makes the element follow the finger — there is nothing to decide about

package/docs/navigation.md

@@ -139,6 +139,133 @@ export const ADMIN_SETTINGS_ROUTE = route(`/admin/settings/:tab=${tabSignal}`);
 So the rule is the one you would want: name a section and it becomes a place;
 leave it unnamed and it stays a setting carried along.
 
+### Which values a param accepts
+
+A param says which segments it accepts, and a segment it declines is not a
+half-match to be sorted out later — the route simply does not match:
+
+```js
+export const GAME_ROUTE = route(`/:gameId=${gameIdSignal}`, {
+  params: { gameId: /^W-[A-Z0-9]{8}$/i },
+});
+```
+
+A constraint is a regexp, the list of accepted values, or a `(value) => boolean`
+— the list is compared as strings, so it can be the very `oneOf` given to the
+signal bound to that param:
+
+```js
+const SECTIONS = ["candidate", "to_come", "done"];
+const sectionSignal = stateSignal("to_come", {
+  id: "section",
+  oneOf: SECTIONS,
+});
+export const GAMES_SECTION_ROUTE = route(`/games/:section=${sectionSignal}`, {
+  params: { section: SECTIONS },
+});
+```
+
+This is what makes a param usable at the root, where it would otherwise swallow
+every single-segment address: `/cgu` and `/me` stay other routes' urls,
+`<Route fallback>` is reachable for `/whatever`, and no signal is written for a
+url this route has nothing to do with.
+
+A constrained param is also **required** — no segment is not one of the values
+it accepts — so `/:gameId` does not match `/`. The address with no segment is a
+route of its own, which is the shape you want anyway.
+
+#### Constrain the shape, never the existence
+
+A constraint answers one question: **is this segment addressed to this route?**
+It is decided on the url alone, before anything is written, so it can only be
+about shape — that a segment looks like a game code, not that the game exists.
+
+Whether the value is any good is a different question, asked later and answered
+by different things: the signal's own validation (`oneOf`, `autoFix`) and the
+route action's data. That question belongs to a route that **did** match, with a
+page free to repair itself, show a not-found screen, offer a way out:
+
+```js
+// ✅ /W-ZZZZZZZZ matches, the action 404s, the page says so
+// ❌ constraining gameId to the codes that exist — matching cannot ask a server,
+//    and "no route matched" is a worse answer than "this game is gone"
+```
+
+So the signal never takes part in matching. It knows what to make of a value;
+the route decides whether the url is its own.
+
+#### Why order stops being load-bearing
+
+When several routes match one url and bind the **same signal** on a param of the
+same name, they all write it, in declaration order — the last one wins:
+
+```js
+route(`/games/:gameId=${gameIdSignal}`); // declared first
+route(`/:gameId=${gameIdSignal}/:state`); // declared later
+// on /games/W-ABC234PQ the second one matches too and writes "games"
+```
+
+Constraining `gameId` removes that second match entirely, which is the fix.
+Where a param genuinely cannot be constrained, the routes must not share a
+signal.
+
+### An address that only sends elsewhere
+
+Some addresses are not pages: the root of an app whose home screen is « my
+games », the old address of a section that moved, the share link of a game
+carrying a segment only WhatsApp cares about. They exist to be resolved, and a
+route says so itself:
+
+```js
+export const HOME_ROUTE = route("/", { redirectRoute: MY_GAMES_ROUTE });
+export const GAME_SHARED_ROUTE = route("/:gameId/:shareState", {
+  redirectRoute: GAME_ROUTE,
+});
+```
+
+The params found in the url carry over to the ones the target route declares
+under the same name — `gameId` above needs no help — and what it cannot place
+is left behind, `shareState` included. `redirectRouteParams` says the rest:
+
+```js
+// renaming, when the two routes do not call it the same thing
+route("/partie/:id", {
+  redirectRoute: GAME_ROUTE,
+  redirectRouteParams: ({ id }) => ({ gameId: id }),
+});
+// dropping one, keeping the others
+route("/:gameId/invite", {
+  redirectRoute: MY_GAMES_ROUTE,
+  redirectRouteParams: { gameId: undefined },
+});
+// carrying nothing over
+route("/tri", { redirectRoute: MY_GAMES_ROUTE, redirectRouteParams: null });
+```
+
+#### Why it is not a page rendering `null`
+
+The redirection is resolved at the door of the navigation, before the url is
+written anywhere. Nothing about that address ever happens: no history entry, no
+route matching, no route action loading data for a screen nobody will see, no
+element mounted, nothing painted — and going back lands on the page before it
+rather than replaying the redirection forever.
+
+A page doing it in an effect gets none of that. It has to be routed to first,
+which means the address exists, its action runs, and the app is on a screen
+nobody should see for one paint — one a route transition can even animate _to_.
+Anything reached by rendering is already too late, so a redirection is declared
+with the address and never appears in the `<Route>` tree at all.
+
+It fires on the route's own address only. `/` catches everything below it when
+it renders a container, and would carry `/cgu` away with it if redirecting
+followed the same reading — so redirecting asks the stricter question: is this
+url exactly that route's address?
+
+Where several redirecting routes answer for one url, the more specific wins —
+`/:gameId/invite` over `/:gameId/:shareState`, the same reading the rest of the
+router uses. Chains collapse into one navigation, and a cycle throws naming the
+addresses it goes through.
+
 ### Search params
 
 A param that qualifies a page rather than naming it — a zoom level, a sort, a

package/docs/z_index.md

@@ -74,14 +74,14 @@ 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             |
-| `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                                                                      | `--navi-z-index-control-hovered`, `--navi-z-index-control-focused` | 1, 2                         |
-| `Table` sticky cells, drag, resize                                                                                                  | `src/control/table/z_indexes.js`                                   | 1–7, derived from each other |
+| Band                                                                                                                                | Token                                                                                                 | Value                        |
+| ----------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ---------------------------- |
+| Top layer (`Dialog`/`Popover` with `layer="top"`)                                                                                   | —                                                                                                     | above everything             |
+| `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:
 

package/package.json

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