@jsenv/navi 0.29.478 → 0.29.480

package/docs/AI_INSTRUCTIONS.md

@@ -26,7 +26,9 @@ source of knowledge has one job:
 - **The built code, `dist/jsenv_navi.js`** — the exhaustive truth about the API,
   JSDoc included, always under `node_modules/@jsenv/navi/`. When a signature, a
   default or an accepted value is what you need, read it there rather than
-  guessing.
+  guessing. The formatters navi re-exports from `@jsenv/humanize` (`format*`,
+  `createI18n`, `interpolateText`) are a re-export there: their JSDoc is in
+  `node_modules/@jsenv/humanize/dist/browser/jsenv_humanize_browser.js`.
 - **Sources, demos and tests** — how an export is really used:
   `src/**/demos/*_demo.html` exercise one component per page, prop by prop. They
   are not published to npm, so they live only in the repo
@@ -57,7 +59,8 @@ start when unsure which export solves a problem.
 ### Routing and movement
 
 - `navigation.md` — the position of the user belongs in the URL by default:
-  routes and which branch renders, search params, redirections, the back arrow
+  routes and which branch renders, a page (`/x`) or a frame (`/x/`), search
+  params, redirections, the back arrow
   (`navBack`), where a navigation lands (a `#id` for an element; a page not
   whole yet holds its position with `useHoldScrollRestoration`), a
   `SlideContainer` read from the URL, what a layer drawn over the screen may say

package/docs/actions.md

@@ -22,6 +22,7 @@ them by hand — see [resource.md](./resource.md).
 
 - [Params: `bindParams`, and calling the action](#params-bindparams-and-calling-the-action)
   - [The answer is kept on the instance that ran](#the-answer-is-kept-on-the-instance-that-ran)
+  - [Nothing to ask, and coming back](#nothing-to-ask-and-coming-back)
   - [The in-between states of a gesture are real params](#the-in-between-states-of-a-gesture-are-real-params)
 - [Running: `run`, `rerun`, `prerun`, `reset`](#running-run-rerun-prerun-reset)
   - [Aborting saves resources, it does not undo](#aborting-saves-resources-it-does-not-undo)
@@ -124,6 +125,28 @@ verb — `computed(() => ME.GET.dataSignal.value)` — only works for a verb
 something runs **directly**, with no params; anything else derives from the
 instance: `computed(() => COUNTS.dataSignal.value)`.
 
+### Nothing to ask, and coming back
+
+A binding has nothing to ask while its params as a whole are `undefined` or
+`null` — a question computed from a form still missing a field.
+`{ id: undefined }` is not that: it is a question, and it is asked. With nothing
+to ask, the binding reads an instance holding nothing, idle: no data, no wait.
+The previous answer stands in only while a newer one is coming, and none is.
+
+What the previous params got stays on the instance that ran. A run still out
+for them is called off by `actionRunEffect` (so by a route action) and carries
+on under a plain binding; either way nothing is reset — an action does not
+start over because its params went away.
+
+Whether coming back to those params finds that answer depends on the instance
+still being there. Without `keep` it lives as long as something references it,
+and once nothing does it goes at a moment nothing in the code decides: coming
+back may find it or ask again, and neither is something to build on.
+`createAction(callback, { keep: { ms } })` is what decides. The answer stays
+good for `ms` from the moment it landed, and the first screen asking for those
+params after that asks again: a read worth asking at each visit — a
+measurement, a quota — declares a short one.
+
 ### The in-between states of a gesture are real params
 
 The delay decides _when_ a question goes out, never _which_ one is coherent: it

package/docs/drag_to_travel.md

@@ -79,9 +79,15 @@ are read at the press, before the box moves:
    [interactions.md](./interactions.md#an-affordance-inside-somebody-elses-box-selfinteractions));
    and a popover or a `<dialog>` inside the box, which is a layer over it. A
    button, a link or a checkbox is not among them on purpose: a drag from one
-   travels, and the click it would have made is swallowed. A field that only
-   reads the press — a picker's façade is an `<input>` that opens a popup — says
-   so with `data-press-only`, and a travel starts there like anywhere else.
+   travels, and the click it would have made is swallowed before any listener
+   hears it, the ancestors' included: an `onClick` on something that travels
+   needs no distance check of its own. For the same reason
+   navi refuses the browser's own drag of a link or an image for that press: it
+   starts a few pixels in and would take the pointer before the travel forms.
+   An app that wants an image dragged out of the page marks it
+   `data-no-drag-travel`. A field that only reads the press — a picker's façade
+   is an `<input>` that opens a popup — says so with `data-press-only`, and a
+   travel starts there like anywhere else.
 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. A row swiped with

package/docs/form_changed.md

@@ -53,9 +53,10 @@ for.
 
 ### A popup that stays open
 
-A popup closes once a form inside it is sent. When it is a place one keeps
-working in — a panel where a push is sent, two fields are fixed, an account is
-linked — the form says it stays:
+A popup closes once a form inside it is sent, even when the send took the form
+out of the page. When it is a place one keeps working in — a panel where a push
+is sent, two fields are fixed, an account is linked, an answer drawn where the
+form was ("link sent, check your inbox") — the form says it stays:
 
 ```jsx
 <SidePanel signal={openUserSignal} value={user.id}>

package/docs/interactions.md

@@ -478,10 +478,14 @@ teardown, so a travelling container above it does not take the gesture (see
   selection refused only for the length of its gesture — in time for a mouse,
   too late for a finger held still — so it says `user-select: none` itself (see
   [drag_interactions.md](./drag_interactions.md#the-text-inside-user-select-none)).
-- **A swipe cannot also be dragged out of the page.** An element declaring a
-  swipe gets `draggable={false}` and its `dragstart` refused — a native drag _is_
-  press-and-move, and a link or an image is draggable without anyone asking. One
-  gesture cannot mean both.
+- **What a press moves cannot also be dragged out of the page.** A swipe, a
+  travel (a `SlideContainer`, a `RouteTravel`, a sheet pushed back) and a `pan`
+  surface refuse the browser's own drag of the link or image a press lands on —
+  a native drag _is_ press-and-move, a link or an image is draggable without
+  anyone asking, and the browser starts it a few pixels in, before any of them
+  has decided. One gesture cannot mean both. What they leave alone keeps its
+  drag: an element inside marked `data-no-drag-travel` reads the pointer itself.
+  An element declaring a swipe also gets `draggable={false}`.
 - **A popup can open while the finger is still down** — a menu under a waiting
   finger is the native gesture (see
   [popup_open.md](./popup_open.md#opening-while-the-finger-is-still-down), and

package/docs/navigation.md

@@ -5,6 +5,7 @@ linking to them, and turning them into tabs.
 
 - [The rule that decides everything else: the position belongs in the URL](#the-rule-that-decides-everything-else-the-position-belongs-in-the-url)
 - [Declaring routes](#declaring-routes)
+  - [A page or a frame: the trailing slash](#a-page-or-a-frame-the-trailing-slash)
   - [A document that is not at the root: `setBaseUrl`](#a-document-that-is-not-at-the-root-setbaseurl)
   - [A section is allowed to be a route of its own](#a-section-is-allowed-to-be-a-route-of-its-own)
   - [Which values a param accepts](#which-values-a-param-accepts)
@@ -68,6 +69,32 @@ application, and an import line says which places a component deals with. Routes
 are plain objects usable outside any component (`buildUrl()`, `navTo()`,
 `redirectTo()`, `matching`), which is why they are declared apart from the JSX.
 
+### A page or a frame: the trailing slash
+
+The last character of a pattern is part of what the route stands for:
+
+- `route("/map")` is a **page**: it matches `/map` and nothing below it.
+- `route("/map/")` is a **frame**: it matches `/map` and every address below it,
+  `/map/flow` and `/map/isochrone/compare` included. The root `/` is always one.
+
+A frame is what stays on screen while one moves below it: the map under its
+panels, an admin shell around its sections. A page is one screen among others,
+even when its address starts theirs: the profile at `/me`, beside the address
+book at `/me/players`. To choose, ask whether the route is still on screen at
+the addresses below it. The answer decides more than what renders:
+
+|                                                                    | page `route("/map")`                                           | frame `route("/map/")`                                              |
+| ------------------------------------------------------------------ | -------------------------------------------------------------- | ------------------------------------------------------------------- |
+| matches `/map/flow`                                                | no                                                             | yes                                                                 |
+| its search params, on `/map/flow`                                  | absent: they belong to `/map` alone                            | held: the url keeps them, the signal follows them                   |
+| `/map/:panel` defaulting to `"isochrone"`, beside `/map/isochrone` | `/map` is this page alone, the panel lives at `/map/isochrone` | `/map` opens on the isochrone panel, and a link to it builds `/map` |
+
+So a frame written without its slash shows itself in two ways: its search params
+are left out of the addresses below it (not written there, not read from there),
+and its address does not open on the default section. Details in
+[Search params](#search-params) and in
+[Declaring the sections](#declaring-the-sections-is-what-makes-them-places).
+
 ### A document that is not at the root: `setBaseUrl`
 
 A second document in the same site — an admin panel at `/admin/admin.html`
@@ -125,6 +152,25 @@ already open — a tab pointing at the current page cannot be clicked. The defau
 section has no segment, so its literal route is the **parent** of the
 parameterized one, and still does not inherit the param.
 
+The default section can also have an address of its own, when the bare address
+is another page:
+
+```js
+export const PROFILE_ROUTE = route("/me"); // a page, not a frame
+export const ADDRESS_BOOK_ROUTE = route(`/me/:section=${bookSectionSignal}`); // default "players"
+export const PLAYERS_ROUTE = route("/me/players");
+export const GROUPS_ROUTE = route("/me/groups");
+```
+
+A page at the bare address (see
+[A page or a frame](#a-page-or-a-frame-the-trailing-slash)) and a literal for the
+default are what say so: the param is then required, `/me` is the profile alone,
+and `ADDRESS_BOOK_ROUTE.buildUrl()` gives `/me/players` or `/me/groups`, never
+`/me`. A visit to the profile leaves the section where it was. The bare address
+is the default section in the two other cases: when nothing is declared there
+but a frame (`/map/` around its panels opens on the default one), and when no
+literal is declared for the default (`/games/me` above).
+
 That the literals exist is what tells navi these values name pages. Where none is
 declared, the value stays a qualifier, carried by an ancestor url:
 
@@ -157,8 +203,10 @@ export const GAME_ROUTE = route(`/:gameId=${gameIdSignal}`, {
 This is what lets a param sit at the root without swallowing every single-segment
 address: `/cgu` stays another route's url, `<Route fallback>` is reachable, and
 no signal is written for a url this route has nothing to do with. A constrained
-param is also **required**: `/:gameId` does not match `/`. The accepted forms are
-in `route()`'s JSDoc.
+param is also **required**: `/:gameId` does not match `/` — unless its default
+stands for the bare address, as `/games/me` does for `/games/me/:section` (see
+[Declaring the sections](#declaring-the-sections-is-what-makes-them-places)).
+The accepted forms are in `route()`'s JSDoc.
 
 #### Constrain the shape, never the existence
 
@@ -257,7 +305,13 @@ export const HOME_ROUTE = route("/", { searchParams: { vue: vueSignal } });
 
 The signal and the URL are the same state: never keep a `useState` beside a route
 param for the same fact. Declared on the **root route**, a search param holds
-wherever one is in the application; declared on one route, it exists only there.
+wherever one is in the application; declared on one route, it exists only there:
+on its own address for a page, on its own address and every address below it for
+a frame (see [A page or a frame](#a-page-or-a-frame-the-trailing-slash)). Two
+pages may each have a `?q=` of their own: the list at `/places` and the clubs at
+`/places/clubs` keep two searches, even with a `/places/:section` matching both.
+A param several pages need, and no frame holds, is declared on each of them,
+with the same signal.
 
 Writing it AMENDS the history entry one is on rather than stacking a new one: a
 param that qualifies a screen is not a place, and one entry per write turns a
@@ -300,7 +354,8 @@ the branch taken when no sibling matches.
 A route matches its own address and nothing below it — `/games/:gameId` does not
 match `/games/2/edit` — except `/` and a pattern ending in `/`, which match
 everything below them too (`route("/games/")` matches `/games/2/edit`): that is
-what keeps a section's container on screen while one is inside it. Two patterns
+what keeps a section's container on screen while one is inside it (see
+[A page or a frame](#a-page-or-a-frame-the-trailing-slash)). Two patterns
 can still match one url — `/games/my_games` is also a `/games/:gameId` — and a
 container renders the **first** branch that matches, in the order written, not
 the most specific. So the branches go from the most precise to the widest, and
@@ -398,6 +453,14 @@ section it does NOT stand for. Both amend what a link claims about itself and
 nothing else — neither is an answer to a route that lies about where the reader
 is (see [what its address may say](#a-layer-over-the-screen-what-its-address-may-say)).
 
+The routing takes a plain click that moves this tab, and nothing else. A link
+with `target="_blank"` (or any `target` other than `_self`) opens the app in that
+tab or window, which loads it and routes there; a link with `download` saves its
+address; a click with a modifier key (a new tab, a new window, a download) is the
+browser's. None of them costs the page the reader is on — a half-filled form
+beside a link to the terms stays filled. Nothing is fetched ahead for such a
+link either: the other tab loads its own code.
+
 ## The back arrow: `navBack`
 
 An arrow drawn inside the app promises the screen the reader came from — never

package/docs/pan_zoom.md

@@ -91,10 +91,12 @@ is not, and asking again is asking three times for one sentence:
 <Box data-pan-after-hold="kept" interactions={{ pan, zoom }} />
 ```
 
-From the moment the surface is given the hand — the hold, a pinch, a mouse
-travelling — it pans on contact, the way the same plan does opened full screen,
-until a press lands away from it; navi watches for that press itself, so nothing
-on your side listens to the window. The paid wait is a state to draw, and only a
+From the moment a finger gives the surface the hand — the hold, or a pinch — it
+pans on contact, the way the same plan does opened full screen, until a press
+lands away from it; navi watches for that press itself, so nothing on your side
+listens to the window. A mouse never owed the wait, so it neither spends it nor
+marks it: after a mouse pan the next finger still waits, and the attribute is
+safe to write for every device. The paid wait is a state to draw, and only a
 `"kept"` surface carries it: `[data-hand-kept]`, for as long as it holds the
 hand, a finger on it or not.
 

package/docs/popup_backdrop.md

@@ -138,6 +138,11 @@ wheel above is painted, so a press on it is a press on the popup — which is wh
 lets one marker cover a whole row without swallowing the controls it holds. A
 nested box that is see-through too needs its own marker.
 
+**Inside a box that travels by drag, the marker answers the click.** A press on
+a row of slides, or on a sheet that swipes closed, may be the start of that
+travel; the popup closes on the click that ends the press, which a travel
+swallows, rather than at the press itself.
+
 **Space beside something, not space between two things.** What the wheel does
 not cover is plainly nothing, and a press there reads as a press on the page.
 The gap between two rows of a column does not read that way — it is a seam of

package/docs/popup_lift.md

@@ -218,9 +218,10 @@ closing, and a name built from it at that render names no tile: build it from
 the last key the walk held — a ref written while the signal holds one.
 
 **A press on the surface that dismisses is `data-navi-popup-outside`** (see
-[popup_backdrop.md](./popup_backdrop.md#where-the-outside-begins)), read on the
-press itself. A close written by hand on a click has to tell a click from the
-end of a swipe — and that guard is the sign the marker was missed.
+[popup_backdrop.md](./popup_backdrop.md#where-the-outside-begins)). The row
+travels, so the marker answers the press's click rather than its mousedown: a
+swipe that starts on the free space walks, and only a press that stayed one
+closes.
 
 ## Lifting on the way back only
 

package/docs/route_transitions.md

@@ -287,9 +287,10 @@ Four misconfigurations are silent enough to be worth a console warning, each sai
 once: an area that was not captured (the case above); several elements marked at
 once — they share one `view-transition-name`, and the browser refuses every route
 transition while they do; pages travelling on the document while something else
-is captured on its own — the blank band; and, on a browser without nested groups,
-a `view-transition-name` written inside the area, whose element escapes the pages'
-picture (see
+is captured on its own — the blank band; and a `view-transition-name` written
+inside the area that only one of the two pages has: with nothing to morph into,
+its element stands still and fades while the pages move, in every browser, and
+without nested groups it is not even clipped (see
 [view_transitions.md](./view_transitions.md#a-name-is-unique-per-document)). A
 warning here is a bug to fix, not a mechanism to lean on.
 
@@ -474,6 +475,9 @@ What that means for a page and for the application around it:
   it was (`<List id>`) under the same `id` as a list of the page arriving is the
   same list to navi, and the two overwrite each other's position (see
   [scroll.md](./scroll.md#a-list-that-comes-back-one-id-one-list)).
+  They let go of the document once hidden: a list scrolling the page stops
+  placing it on the item it opened on, and stops answering its scrolls and
+  resizes, so the page arriving lands where it was left, or at its top.
 - **Never while a modal dialog is open.** An open modal keeps everything but
   itself out of reach — the page arriving could not even take the focus — and one
   in a page kept while leaving would stay open for the whole movement. The page is

package/docs/scroll.md

@@ -117,8 +117,8 @@ say so with `"document"` or the element itself.
 ### Where the list opens, and where it is
 
 `defaultScrolled` (or `scrolled`, held) takes `{id, offset}` — what
-`onScrolledChange` hands out — and asks for the row BY NAME, then puts it back
-by MEASURING it: it lands where it was even if rows were inserted before it,
+`onScrolledChange` hands out — and asks for the item BY NAME, then puts it back
+by MEASURING it: it lands where it was even if items were inserted before it,
 whatever the screen it was saved on. "Reopen a thread where I left it" is
 already provided; keep the position whole, its `visibleCount` sizes the first
 paint. A `defaultScrolled` that changes before anyone has moved the list is
@@ -129,9 +129,9 @@ must name one list of the app, see [below](#a-list-that-comes-back-one-id-one-li
 **`scrollResetOnNavigation`** opts out. What it draws there before its source
 answers is another matter
 ([What a run knows when it opens](#what-a-run-knows-when-it-opens)). A list scrolling the document that
-opens on a row places the document itself: the offset the page kept for its url
-is not put back over it — the rows held off screen are fillers of an estimated
-height, and the same pixels now fall on other rows.
+opens on an item places the document itself: the offset the page kept for its url
+is not put back over it — the items held off screen are fillers of an estimated
+height, and the same pixels now fall on other items.
 
 ### A list that comes back: one `id`, one list
 

package/docs/testid.md

@@ -76,11 +76,14 @@ Navi hands the host the props it knows belong there (`id`, `name`, `type`,
 root box instead — so a `data-test-id` or a `data-qa` of your own would name
 the wrapper, which is the second reason to keep the standard spelling.
 
-`aria-label` and `aria-labelledby` take the same road, and for the reason the
-section above gives: the name has to be where the role is. The root box has no
-role — it is a wrapper — so a name left on it would be announced by nothing and
-found by nothing, while the host is what the user focuses and what
-`getByRole(role, { name })` and `getByLabel()` read.
+`aria-label` and `aria-labelledby` follow the role, for the reason the section
+above gives: the name has to be where the role is. For most controls that is the
+host. The root box has no role — it is a wrapper — so a name left on it would be
+announced by nothing and found by nothing, while the host is what the user
+focuses and what `getByRole(role, { name })` and `getByLabel()` read. A `Wheel`
+is the other way round: its root is the `spinbutton` the user focuses, and its
+host is an `aria-hidden` input carrying the value, so the name lands on the
+root.
 
 ```jsx
 <Picker variant="icon" aria-label="Aide" ui={<Icon>…</Icon>}>

package/docs/view_transitions.md

@@ -33,8 +33,9 @@ and `List` unnames its rows for the length of any route transition or travel. A
 name the app puts inside the pages is given only for the gesture it serves, or
 dropped while they move: `view-transition-name: none` under
 `:root:is([data-navi-route-transition], [data-navi-route-travel])`. Without nested
-groups it also escapes the pages' clip, and navi warns about one inside a
-transition area.
+groups it also escapes the pages' clip. navi warns about a name inside a
+transition area that only one of the two pages has: with nothing to morph into,
+it can only be this trap.
 
 ## Nested groups, and the fallback fade
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/navi",
-  "version": "0.29.478",
+  "version": "0.29.480",
   "type": "module",
   "description": "Library of components including navigation to create frontend applications",
   "repository": {
@@ -35,8 +35,8 @@
   },
   "dependencies": {
     "@jsenv/dom": "0.17.94",
-    "@jsenv/humanize": "1.8.7",
-    "@jsenv/validity": "0.4.5"
+    "@jsenv/humanize": "1.8.8",
+    "@jsenv/validity": "0.4.6"
   },
   "devDependencies": {
     "@jsenv/assert": "4.5.7",