@jsenv/navi 0.29.24 → 0.29.26

package/docs/AI_INSTRUCTIONS.md

@@ -49,9 +49,13 @@ consistency across the app, not from any single call site.
   values navi's own popups/bars/tables use. Read it before writing a `z-index`.
 - `docs/MOBILE_LAYOUT_PITFALLS.md` — mobile-specific layout gotchas (viewport
   units, virtual keyboard, safe areas).
-- `src/nav/route_ui.md` — routes as UI: layout/section patterns, and
-  `RouteTravel` (swiping between pages that are URLs — the tabs of a page,
-  driven by thumb, wheel, or a link).
+- `docs/navigation.md` — how to build navigation: declaring routes
+  (`route()` / `setupRoutes()`), when a section is a route of its own rather
+  than a param, search params bound to signals, rendering with `<Route>`,
+  tab rows (`Nav` / `Link` / `RouteTravel`), and the few cases where tabs are
+  legitimately not URLs. Read it before writing any routing code — the
+  position of the user belongs in the URL by default, and that decision is
+  not retrofittable.
 - Source code on GitHub: https://github.com/jsenv/core/tree/main/packages/frontend/navi/src
   — worth checking if the JSDoc on an export genuinely doesn't answer your
   question.

package/docs/drag_to_travel.md

@@ -84,14 +84,36 @@ scrolling while a screen slides. Same word, other gesture.
 
 ## Who owns a gesture
 
-Two things can claim a pointer that landed on a travelling box, and both are
-read before the box moves:
+Three things can claim a pointer that landed on a travelling box, and all three
+are read before the box moves:
 
 1. **What says so itself.** A field, a `contenteditable`, or anything carrying
    `data-no-drag-travel`.
 2. **A scroller in between with room left that way.** It keeps the gesture until
    it has no room left, and only then hands the travel over — so a row that
    scrolls sideways inside a page still scrolls sideways.
+3. **Another travelling box in between.** The innermost one takes the axes it
+   walks, and leaves the ones it does not to whoever is above it.
+
+### Boxes inside boxes
+
+A row of slides inside a page that walks between pages, a carousel inside a
+carousel, a `SlideContainer` inside a `RouteTravel`: they all get the same
+press, and the innermost is the one the hand is pointing at. So it takes the
+gesture on the axis it walks, and the boxes above it are left with whatever axis
+it does not — a row swiped sideways inside a column of screens keeps the
+sideways gesture, and the column still answers a finger going down. Nothing has
+to be declared for this: each box says which axes it travels in the DOM
+(`data-travel-by-drag`, `data-travel-by-wheel`), and that is what the boxes above
+read.
+
+Decided at the press, once and for all: from the first pixel the gesture belongs
+to whoever asked the browser for the pointer last, which is the outermost box —
+so the arbitration has to happen before anyone asks, and the box that does not
+own the gesture never does. The consequence is that an inner box sitting on its
+last slide does not hand the gesture over mid-drag: it leans on its wall, the way
+it does when it is alone. Travelling the box around it means starting the gesture
+outside it.
 
 ### The browser also wants to answer the gesture
 

package/docs/navigation.md

@@ -0,0 +1,253 @@
+# Navigation
+
+How to build navigation with `@jsenv/navi`: declaring routes, rendering them,
+linking to them, and turning them into tabs.
+
+## The rule that decides everything else: the position belongs in the URL
+
+Where the user is — which section, which tab, which sub-page — is state. Put it
+in the URL unless there is a reason not to. What that buys, none of which can be
+retrofitted later:
+
+- the browser's back and forward buttons work, because each place is a history
+  entry;
+- the place is shareable and bookmarkable — someone can send a link to exactly
+  what they are looking at;
+- the place is **targetable**: anything, anywhere in the app, can send the user
+  there with a `<Link route={…}>`, without knowing anything about the component
+  that displays it;
+- a reload lands where the user was.
+
+So the default shape of a tab row is routes: `<Nav>` + `<Link route>` +
+`<RouteTravel>`. `SlideContainer` is the exception, not the starting point — see
+[Tabs with no URL](#tabs-with-no-url) for the cases that genuinely are one.
+
+## Declaring routes
+
+Every route is created with `route()` and they are all declared to `setupRoutes()`
+in one call — the routing system resolves specificity and signal ownership across
+the whole set, so it has to see the whole set.
+
+```js
+// routes.js
+import { route, setupRoutes } from "@jsenv/navi";
+
+export const HOME_ROUTE = route("/");
+export const GAMES_ROUTE = route("/games");
+export const GAME_ROUTE = route("/games/:gameId");
+
+setupRoutes([HOME_ROUTE, GAMES_ROUTE, GAME_ROUTE]);
+```
+
+Named exports from one module, on purpose: the file is the map of the
+application, and an import line says which places a component deals with.
+Routes are plain objects usable outside of any component — `route.buildUrl()`,
+`route.navTo()`, `route.redirectTo()`, `route.matching` — which is why they are
+declared apart from the JSX that renders them.
+
+### A section is allowed to be a route of its own
+
+This is the most commonly missed point.
+
+When a segment can take a **finite, known set of values**, declare one literal
+route per value rather than one parameterized route you pass params to:
+
+```js
+// ✅ each section is a route object of its own
+export const MY_GAMES_ROUTE = route("/games/my_games");
+export const CANDIDATE_GAMES_ROUTE = route("/games/candidates");
+export const FINISHED_GAMES_ROUTE = route("/games/finished");
+```
+
+A literal route may sit alongside a parameterized one on the same segment
+(`/games/:section` and `/games/my_games`). Both match, and the literal one is
+taken as the more specific — so declaring the sections costs nothing and takes
+nothing away.
+
+Why prefer it:
+
+- **The routes are listable.** `routes.js` shows the places the application has.
+  A single `/games/:section` shows one place and hides three.
+- **No `routeParams` at the call sites.** `<Link route={MY_GAMES_ROUTE}>` instead
+  of `<Link route={GAMES_ROUTE} routeParams={{ section: "my_games" }}>`, and the
+  same for `<Route>`. A wrong section is then a missing import rather than a
+  string nobody checks.
+- **Each section can carry its own search params.** `/games/finished` may have a
+  `sort` the other sections have no business knowing about.
+
+Params stay for what is genuinely dynamic — a value the code cannot enumerate:
+
+```js
+export const GAME_ROUTE = route("/games/:gameId"); // ✅ an id
+export const DAY_ROUTE = route("/planning/:day"); // ✅ any date
+```
+
+A parameterized route also remains right for a finite set that must be handled
+**uniformly** — a row built by `.map()` over a list of sections, where writing
+one branch per section would be writing the same branch N times. Bind the param
+to a signal to get validation and a default:
+
+```js
+import { stateSignal } from "@jsenv/navi";
+
+const sectionSignal = stateSignal("to_come", {
+  id: "games_section",
+  oneOf: ["candidate", "to_come", "done"],
+  autoFix: true,
+});
+export const GAMES_SECTION_ROUTE = route(`/games/:section=${sectionSignal}`);
+```
+
+### Search params
+
+A param that qualifies a page rather than naming it — a zoom level, a sort, a
+view mode — is a search param, declared with the signal it two-way syncs with:
+
+```js
+const vueSignal = stateSignal("liste", {
+  id: "vue",
+  oneOf: ["liste", "carte"],
+});
+export const HOME_ROUTE = route("/", { searchParams: { vue: vueSignal } });
+```
+
+The signal and the URL are the same state: writing the signal rewrites the URL,
+and a URL arriving from outside writes the signal. Never keep a `useState`
+beside a route param for the same fact.
+
+Declared on the **root route**, a search param is a position that holds wherever
+one is in the application — a view mode that survives moving from page to page.
+Declared on one route, it exists only there.
+
+## Rendering routes
+
+`<Route>` is the only primitive. With `children` it is a container that renders
+the branch matching the URL; with a `route` it is a branch; with `fallback` it is
+the branch taken when no sibling matches.
+
+```jsx
+<Route>
+  <Route route={MY_GAMES_ROUTE} element={MyGamesPage} />
+  <Route route={CANDIDATE_GAMES_ROUTE} element={CandidateGamesPage} />
+  <Route route={GAME_ROUTE} element={GamePage} />
+  <Route fallback element={NotFoundPage} />
+</Route>
+```
+
+`elementProps` passes props to the element, which is how a section hands its own
+local state down to its sub-pages.
+
+Two shapes for a section, and which one applies is decided by the URL:
+
+- **A section with a shared prefix owns its own sub-router.** One leaf
+  `<Route route={DASHBOARD_SECTION_ROUTE} element={DashboardSection} />` at the
+  top, and `DashboardSection` renders its own `<Route>` tree plus whatever chrome
+  it has. Everything about the section is in one file.
+- **Pages sharing a layout but no prefix** (`/profile` and `/settings` inside an
+  authenticated shell) use a container `<Route element={AuthLayout}>`: the active
+  child is injected into the layout as its children.
+
+### Loading data
+
+A branch loads with `action`, and shows its states with the usual boundaries:
+
+```jsx
+<ErrorBoundary fallback={(error, { resetError }) => …}>
+  <Suspense fallback={<p>Loading…</p>}>
+    <Route route={GAME_ROUTE} action={loadGame} element={(game) => <GamePage game={game} />} />
+  </Suspense>
+</ErrorBoundary>
+```
+
+## Links and tab rows
+
+`<Link route={…}>` builds its href from the route and knows on its own whether it
+is the current one — that is what draws the current-tab state. `<Nav>` says once,
+for the whole row, where the bar that marks the current tab goes:
+
+```jsx
+<Nav currentIndicator>
+  <Link route={MY_GAMES_ROUTE} variant="tab">
+    Mes parties
+  </Link>
+  <Link route={CANDIDATE_GAMES_ROUTE} variant="tab">
+    Candidatures
+  </Link>
+</Nav>
+```
+
+The bar travels from one tab to the next rather than blinking, because `<Nav>`
+gives it a `view-transition-name` of its own: the browser then moves it on the
+same clock as any transition playing — including a `RouteTravel` swipe, with no
+wiring between the two.
+
+## Tabs that travel: `RouteTravel`
+
+`<RouteTravel>` wraps the `<Route>` tree of a row of tabs and makes every change
+between them a movement — a tab pressed, a key, the back button, and a thumb
+dragging the pages.
+
+```jsx
+<SectionNav />
+<RouteTravel>
+  <Route>
+    <Route route={MY_GAMES_ROUTE} element={MyGamesPage} />
+    <Route route={CANDIDATE_GAMES_ROUTE} element={CandidateGamesPage} />
+    <Route route={FINISHED_GAMES_ROUTE} element={FinishedGamesPage} />
+  </Route>
+</RouteTravel>
+```
+
+The router still mounts only the branch that matches; the page being left is
+shown from the picture the browser keeps of it. The page arriving mounts during
+the gesture and fills in under the finger, as its own loading state.
+
+The order of the tabs — what "one step that way" means, which no URL says — is
+read from the children in the order they are written. Pass `routes` only to say
+another order, or when the pages are not children of the box. An entry is a route,
+or `{ route, params }` when the tabs are params of one route.
+
+A swipe **replaces** the current history entry (a gesture browses; a tab pressed
+aims at a place and pushes, which its `<Link>` already does). `onTravel` decides
+otherwise.
+
+Several `RouteTravel` boxes may live on one page — a section of the path and a
+search param of the root route are two rows of tabs, both live — and only the one
+actually travelling is captured.
+
+Demo: [../src/nav/demos/route_travel/route_travel.html](../src/nav/demos/route_travel/route_travel.html)
+and [../src/nav/demos/tabs/tabs.html](../src/nav/demos/tabs/tabs.html). The full
+spec of the gesture is [drag_to_travel.md](./drag_to_travel.md).
+
+## Tabs with no URL
+
+`SlideContainer` holds slides that replace one another in one box, with the same
+gestures and the same travelling bar, and nothing written to the URL. Use it when
+the position genuinely is not a place one should be able to link to:
+
+- the steps of a wizard, or the screens of a picker, inside a dialog or a popover
+  — a popup is promoted to the browser's top layer, so no container can hold two
+  of them side by side and `RouteTravel` has nothing to work with there;
+- a carousel, or any window over something endless (days, months);
+- a panel switch local to one widget, which nobody would ever send a link to.
+
+If the answer to "should a link be able to open the app on this?" is yes, it is a
+route.
+
+```jsx
+<Nav slideContainer="messagerie" currentIndicator>
+  <Link slide="unread" variant="tab">Non lus</Link>
+  <Link slide="read" variant="tab">Lus</Link>
+</Nav>
+<SlideContainer id="messagerie">
+  <Slide area="unread">…</Slide>
+  <Slide area="read">…</Slide>
+</SlideContainer>
+```
+
+`<Nav slideContainer>` names the container by id — the row can sit anywhere on the
+page. It reads which slide is on screen from the container itself, and its bar
+follows the slides, a finger dragging them included. `<Link slide>` has no href
+and behaves like a button: this is not a link to anywhere.
+
+Demo: [../src/layout/demos/8_slide_container_demo.html](../src/layout/demos/8_slide_container_demo.html).

package/docs/popup_open.md

@@ -0,0 +1,185 @@
+# Opening a popup
+
+What opens a `Dialog` or a `Popover`, and who owns the fact that it is open.
+
+- [The popup owns its open state](#the-popup-owns-its-open-state)
+- [A button opens it: the attributes](#a-button-opens-it-the-attributes)
+- [Something else opens it: `triggerNaviCommand`](#something-else-opens-it-triggernavicommand)
+- [Which element receives the command](#which-element-receives-the-command)
+- [The anchor](#the-anchor)
+- [Reacting to open and close](#reacting-to-open-and-close)
+- [When `open` is the right answer, and what it costs](#when-open-is-the-right-answer-and-what-it-costs)
+- [What the popup holds while it is closed](#what-the-popup-holds-while-it-is-closed)
+
+## The popup owns its open state
+
+A `Dialog`/`Popover` with no `open` prop keeps its own open state and listens
+for requests to change it. That is the default way to use one, and it buys
+something a `useState` in the parent cannot give back: **a popup refuses to
+close while a control inside it is mid-action**.
+
+```js
+// what both do on every close request
+const busyElement = findBusyElementInside(popupEl);
+if (busyElement) {
+  dispatchRequestInteraction(busyElement, { ... });
+  requestCloseEvent.preventDefault();
+}
+```
+
+A form that is sending holds an answer that is neither committed nor given up.
+Escape, the backdrop, a close button — all of them ask, and the busy control
+answers, the same way it would answer anyone else.
+
+So the question is never "should this popup be controlled?" but "what triggers
+the opening?":
+
+| what opens it                      | how                                            |
+| ---------------------------------- | ---------------------------------------------- |
+| a button                           | `command` / `commandfor` attributes, no `open` |
+| a gesture, an event, a JS decision | `triggerNaviCommand(...)`, still no `open`     |
+| it is a piece of application state | `open` — see the cost below                    |
+
+## A button opens it: the attributes
+
+```jsx
+<Button command="--navi-open" commandfor="note-dialog">
+  Read the note
+</Button>
+<Dialog id="note-dialog">…</Dialog>
+```
+
+The available commands: `--navi-open`, `--navi-close`, `--navi-toggle`,
+`--navi-cancel` (closes, telling the popup the close means "revert"),
+`--navi-confirm` (says yes, then closes).
+
+## Something else opens it: `triggerNaviCommand`
+
+The attributes fire on every click of the element that carries them. As soon as
+the opening is a decision rather than a click — a long press, the end of a drag,
+a double-click, a keyboard shortcut, a server answer, an `IntersectionObserver` —
+the decision has to be made in JS, and the command triggered from there:
+
+```jsx
+import { triggerNaviCommand } from "@jsenv/navi";
+
+const dialogRef = useRef(null);
+const open = (event) => {
+  if (draggedRef.current) {
+    // the click that ends a throw is not a request to open
+    return;
+  }
+  triggerNaviCommand(dialogRef.current, "--navi-open", event);
+};
+
+<Box role="button" onClick={open}>…</Box>
+<Dialog ref={dialogRef}>…</Dialog>
+```
+
+This is the same entry point the attributes go through: same target resolution,
+same command proxies, same events. The popup stays uncontrolled, and keeps its
+say over closing.
+
+`event` is the DOM event the decision came from. Pass it whenever there is one:
+it is chained into the request event, and that chain is what lets the popup
+handle focus correctly (which element to give focus back to, whether a
+mousedown's click must be swallowed). Omit it only when nothing user-initiated
+triggered the command.
+
+## Which element receives the command
+
+The first argument is the command's **source** — the element it is triggered
+_from_. The target is resolved from it, in this order:
+
+1. `commandfor="someId"` on the source,
+2. `navi-command-target="parent-control" | "child-control"`,
+3. the command's own fallback — for the popup commands, `closest("[aria-expanded]")`.
+
+A popup carries `aria-expanded` from its very first render, so passing the popup
+element itself as the source resolves to that popup: `closest()` starts at the
+element itself. That is the short form used above, and it is enough whenever the
+JS that decides already holds the popup's ref.
+
+To trigger from another element instead, give that element a `commandfor`
+pointing at the popup's `id` — attribute-driven target resolution, JS-driven
+timing.
+
+## The anchor
+
+A popup with no `anchor` prop uses the command's source as its anchor
+(`detail.anchor ?? detail.source`). Passing the popup itself as the source
+therefore makes it its own anchor. For `Dialog` this only affects the
+`--anchor-width`/`--anchor-height` CSS vars; for `Popover`, which really is
+positioned relative to its anchor, say what the anchor is:
+
+```jsx
+<Popover ref={popoverRef} anchor={rowRef}>
+```
+
+The `anchor` prop always wins over whatever the command carried.
+`anchorCustomEventDetail="ignore"` (Popover only) goes further and drops the
+event's anchor entirely, for a popover that must never be anchored to whatever
+opened it.
+
+## Reacting to open and close
+
+`onClose` is called on every real close. There is no `onOpen`: an uncontrolled
+popup rewrites its own open handler, so a passed one would never run. Listen on
+the ref instead — or, when the JS that opens is yours, do the work right where
+you trigger the command.
+
+```js
+useLayoutEffect(() => {
+  const dialog = dialogRef.current;
+  const onOpen = () => {
+    /* … */
+  };
+  dialog.addEventListener("navi_request_open", onOpen);
+  return () => dialog.removeEventListener("navi_request_open", onOpen);
+}, []);
+```
+
+## When `open` is the right answer, and what it costs
+
+`open` is for a popup whose being-open is a fact about the application, not
+about the user's last gesture: a route that _is_ a dialog, an error the app
+decides to show. Use it there, and know what it changes.
+
+The busy arbitration still runs — `open={false}` goes through the same
+`requestClose` — but nobody hears the refusal. The parent's state says closed,
+the popup stayed open, and the two disagree from then on: the effect only reacts
+to `open` _changing_, so setting it back to `true` matches the popup's real
+state and does nothing, and the popup can no longer be closed by the prop at
+all until it closes on its own.
+
+`defaultOpen` is the middle ground: mount-only, and the popup owns everything
+afterwards. `defaultOpen="interaction"` means the mount _is_ the opening (the
+entrance animation plays); any other truthy value means it was already open when
+the page appeared (no entrance).
+
+## What the popup holds while it is closed
+
+A closed popup builds nothing: `children` are mounted on the first open, and
+stay mounted afterwards — a reopened popup finds its scroll position and its
+half-typed form where it left them.
+
+Two props move that line:
+
+| prop                | effect                                                                                                                                                                   |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `mountWhenClosed`   | build `children` right away — for content something depends on before any opening (a value read off it, fields a surrounding form submits, a size measured from outside) |
+| `unmountWhenClosed` | throw `children` away once the popup has finished closing — for content whose fresh state is its initial state                                                           |
+
+`unmountWhenClosed` is what an uncontrolled field seeded from a `defaultValue`
+needs: without it, a popup reopened after the underlying value changed still
+shows what it showed at closing time.
+
+```jsx
+<Dialog ref={dialogRef} unmountWhenClosed>
+  <Textarea defaultValue={note.text} />
+</Dialog>
+```
+
+The content is dropped only once the exit transition is over, so the popup never
+plays it on a blank surface; a popup reopened while it was leaving keeps the
+content that opening just asked for. `mountWhenClosed` wins if both are set.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/navi",
-  "version": "0.29.24",
+  "version": "0.29.26",
   "type": "module",
   "description": "Library of components including navigation to create frontend applications",
   "repository": {
@@ -29,7 +29,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@jsenv/dom": "0.17.7",
+    "@jsenv/dom": "0.17.8",
     "@jsenv/humanize": "1.7.8",
     "@jsenv/validity": "0.4.2"
   },