@jsenv/navi 0.29.398 → 0.29.400

package/docs/AI_INSTRUCTIONS.md

@@ -71,9 +71,10 @@ to start when unsure which export solves a problem.
 
 - `navigation.md` — the position of the user belongs in the URL by default,
   and that decision is not retrofittable: routes, params, search params,
-  `<Route>`, tab rows, `navBack`, `RouteTravel`, where a navigation lands, a
-  `SlideContainer` read from the URL, and what a layer drawn over the screen may
-  say in its address. Read before writing any routing code.
+  `<Route>`, tab rows, `navBack`, `RouteTravel`, where a navigation lands (a
+  `#id` landing on the element it names), a `SlideContainer` read from the URL,
+  and what a layer drawn over the screen may say in its address. Read before
+  writing any routing code, and before scrolling to an element on arrival.
 - `route_transitions.md` — a transition states a relation the user reads as a
   map; a pair of routes is animated by `RouteTravel` or by a transition, never
   both; a test waits for the page arriving, never for its address. Read before
@@ -137,7 +138,9 @@ to start when unsure which export solves a problem.
   `action`, `command` + `commandFor`). Read before writing any handler whose
   body only assigns state.
 - `control_value.md` — who holds a control's value; `--navi-update` for a
-  button proposing a value; empty keeps the shape of the question; what a
+  button proposing a value; a `defaultValue` follows the record it was read
+  from (no `key` to remount); drawing what a picker holds (`ui={Component}`,
+  not a signal of your own); empty keeps the shape of the question; what a
   `stateSignal` brings; a time of day typed (`TimeSpin`) or turned
   (`TimeWheel`). Read before wiring a value with `value` + `uiAction`.
 - `control_object.md` — one value made of several controls: `ControlGroup`
@@ -259,6 +262,9 @@ to start when unsure which export solves a problem.
 - **Routing is signal-based**: URL state (including search params) two-way
   syncs with signals. Don't build parallel state for what a route/query
   signal already tracks.
+- **A link lands on an element by its fragment**: give the element an `id` and
+  link to `#id`. Never a search param plus `scrollIntoView` in an effect (see
+  `navigation.md`).
 - **Actions** model async operations with a lifecycle (idle, running,
   completed, failed, aborted). Components read an action's state via
   `useAsyncData`, not by manually tracking loading/error booleans. Reading does

package/docs/control_value.md

@@ -10,6 +10,8 @@ somewhere else in the app.
 - [A button that proposes a value is `--navi-update`](#a-button-that-proposes-a-value-is---navi-update)
   - [`--navi-update:smooth`: the control is seen answering](#--navi-updatesmooth-the-control-is-seen-answering)
 - [`signal` + `defaultValue`: the answer and where it starts](#signal--defaultvalue-the-answer-and-where-it-starts)
+- [A `defaultValue` follows what it was read from](#a-defaultvalue-follows-what-it-was-read-from)
+- [Drawing what a control holds](#drawing-what-a-control-holds)
 - [What a signal holds, control by control](#what-a-signal-holds-control-by-control)
 - [Empty keeps the shape of the question](#empty-keeps-the-shape-of-the-question)
 - [Which controls take a `signal`](#which-controls-take-a-signal)
@@ -22,12 +24,12 @@ somewhere else in the app.
 
 ## The three answers
 
-| what you pass          | who holds the value | when the user acts                          |
-| ---------------------- | ------------------- | ------------------------------------------- |
-| nothing                | the control         | it keeps it; `uiAction` tells you           |
-| `defaultValue`         | the control         | same — the default is only where it starts  |
-| `signal`               | the signal          | the control writes it back, both ways       |
-| `value` (or `checked`) | you                 | nothing moves until you hand a new one down |
+| what you pass          | who holds the value | when the user acts                                                                    |
+| ---------------------- | ------------------- | ------------------------------------------------------------------------------------- |
+| nothing                | the control         | it keeps it; `uiAction` tells you                                                     |
+| `defaultValue`         | the control         | same — the default is where it starts, and a new one is taken while nothing is edited |
+| `signal`               | the signal          | the control writes it back, both ways                                                 |
+| `value` (or `checked`) | you                 | nothing moves until you hand a new one down                                           |
 
 A control given `value` and nothing to listen to it (`uiAction`, `action`, a
 `signal`, a surrounding form) is read-only, and says so in dev: it is showing
@@ -228,6 +230,50 @@ default rather than leaving it blank — which is what makes "nothing decided
 here, use the usual answer" expressible at all. Without a `defaultValue`, an
 emptied signal empties the control.
 
+## A `defaultValue` follows what it was read from
+
+A field editing a record starts on that record, `defaultValue={user.first_name}`,
+and the record moves after mount: the save comes back normalized (a trailing
+space trimmed), another screen or device changed it, a refresh arrived. The
+control takes the new default **while it holds no edit** — nothing typed, picked
+or toggled since the value the outside last accepted. An edit is never undone:
+the default waits, and lands once that edit is accepted (the action succeeded)
+or taken back (the action failed, the popup was cancelled).
+
+This holds for a control, for a group given a `defaultValue` (a selectable list,
+a `ControlGroup`), and for everything inside a picker's popup, which stays
+mounted while closed. So the record goes in as `defaultValue` and nothing
+else: no `key` to remount the popup when it changes. A key is worse than
+unnecessary here, since it also destroys whatever is being typed when the
+answer to ANOTHER field arrives.
+
+A picker's cancel follows the same line. It puts back what the picker held at
+open, which undoes the person's edits, but what the outside moved during the
+opening stays moved.
+
+## Drawing what a control holds
+
+A picker's trigger usually shows the choice (a label for a code, a summary of
+an object). Read it from the picker rather than keeping a copy:
+
+```jsx
+const VisibilityLabel = ({ value }) => <Text>{labelOf(value)}</Text>;
+
+<Picker name="visibility" defaultValue={user.visibility} ui={VisibilityLabel}>
+  …
+</Picker>;
+```
+
+`ui={Component}` is handed `value`, `loading` and `interactive`. A `ui` given as
+an element reads the same three with `usePickerState()`.
+
+What not to write: `const s = useSignal(defaultValue)` bound as `signal={s}`,
+just to have something to read. `useSignal` reads its argument once, so the
+signal never hears the record move, and a bound signal takes precedence over the
+control's own `defaultValue`. The field is stuck on its first value. A signal is
+for a value the app owns and writes itself (a url param, state shared between
+screens), not a mirror kept for drawing.
+
 ## What a signal holds, control by control
 
 The signal holds what the control is ABOUT, which is not always its `value`

package/docs/drag_to_travel.md

@@ -59,6 +59,10 @@ and are referenced from here rather than restated.
   because the picture alone decided. Only a release at rest, or a slow retreat,
   is judged by the picture — about a third of a box — because there the
   position is the only witness left.
+- **A travel caught in flight and thrown on the way it was going asks for the
+  one after.** Two swipes the same way are two screens, however close
+  together: the second one is not a vote for the screen already arriving. See
+  [below](#a-hand-reaching-for-something-still-moving-is-reaching-for-that-thing).
 - **The bars those verdicts compare against sit well below the speed the
   fingertip actually has, and they must.** Velocity is averaged over a trailing
   window (pointer events arrive irregularly, and the last one before a release
@@ -449,6 +453,26 @@ Taking over means the pictures stop where they are and answer the finger again,
 from where they stand (`slack`) rather than from zero. Only one box is in hand,
 and walking out of either of its ends is a travel of its own — see below.
 
+What letting go of it again means is read from the hand, three ways:
+
+- **merely touched** — a press that moved less than a gesture's worth: nobody
+  asked the travel to stop, it was asked to wait, and it carries on to where it
+  was going;
+- **thrown back** — against the way it was going, fast: everything goes back;
+- **thrown on** — the way it was already going, fast, having moved by more than
+  a tremor: that is a second push, and it asks for the screen AFTER the one
+  arriving (`thrownOn`). Read as a verdict on the box in hand, it only confirms
+  what was already arriving — the travel stops at the press and goes on to the
+  same place, and the hand feels its second swipe swallowed. So the gesture
+  asks for the next box at the release (`onEdge` with `thrown`), with the
+  picture still short of the end of the one in hand, and nothing on screen
+  moves for it: the travel goes on from where the hand left it, to one screen
+  further. It is the wheel's rule (a second push over the tail is a screen, not
+  credit towards one) said for a hand.
+
+A slow hand going the same way and stopping before it lets go is not thrown:
+there the picture decides, and the screen arriving arrives.
+
 ### A hand that does not stop at the end of a page is asking for the next one
 
 One travel brings in one neighbour, but a gesture is not over because a travel
@@ -470,6 +494,14 @@ The two ends cost differently, and it is worth knowing which one is being felt:
   one instead. The travel turns around where it stands, on the same transition,
   and there is no gap at all.
 
+That cost is a `RouteTravel` one: a `SlideContainer` has every slide mounted,
+so handing over is only re-staging — the slide reached becomes the one dragged,
+the one left stays beside it, the slide past it is put on the other side, and
+nothing on screen moves. Which is also why only a `SlideContainer` answers a
+throw (`thrown`, above): a `RouteTravel` would have to jump its pictures the
+rest of the way before handing over, a page seen leaping, so it declines and
+the page caught simply arrives.
+
 What the browser will not turn around with it is everything ELSE the
 transition carries — see [One gesture that bar cannot
 follow](#one-gesture-that-bar-cannot-follow).

package/docs/dynamic_import.md

@@ -146,8 +146,9 @@ by the code arriving.
 `prefetch={false}` opts one out. The url is matched against the routes on
 screen, a section and the page inside it alike, and what is prerun is **every
 route action that asks nothing of the address** — a page's code, a read
-without params. An action whose params come from the address is never
-prefetched: a prefetch has no address, the id may still be chosen.
+without params. An action whose params come from the address is not
+prefetched by a link: a link's prefetch has no address, the id may still be
+chosen.
 `routeAction(route, action, undefined, { prefetch: false })` keeps a
 param-less read that is not worth a hover out of it.
 

package/docs/navigation.md

@@ -16,6 +16,7 @@ linking to them, and turning them into tabs.
 - [The back arrow: `navBack`](#the-back-arrow-navback)
 - [Tabs that travel: `RouteTravel`](#tabs-that-travel-routetravel)
 - [Where a navigation lands: the scroll](#where-a-navigation-lands-the-scroll)
+  - [Landing on an element: the fragment](#landing-on-an-element-the-fragment)
 - [Creating something, then editing it](#creating-something-then-editing-it)
 - [Tabs that are not routes](#tabs-that-are-not-routes)
   - [A `SlideContainer` in the URL: a position that is not a place one came from](#a-slidecontainer-in-the-url-a-position-that-is-not-a-place-one-came-from)
@@ -694,7 +695,7 @@ the two, never both: see [route_transitions.md](./route_transitions.md).
 
 ## Where a navigation lands: the scroll
 
-Four cases, and they are not a policy to configure but four different facts:
+Five cases, and they are not a policy to configure but five different facts:
 
 - **Going somewhere new** (a `<Link>`, anything that pushes to another path)
   lands at the top. It is an arrival: the offset one had elsewhere means nothing
@@ -704,6 +705,10 @@ Four cases, and they are not a policy to configure but four different facts:
   reader is scrolled in — a [layer](#a-layer-over-the-screen-what-its-address-may-say)
   opening, a [state whose values are places](#a-state-whose-values-are-places-history-push)
   written — and moves nothing, like a replace.
+- **Going somewhere new, to an element** (`/places/le-set#tournaments`) lands
+  on the element whose `id` is the fragment, once it is rendered — even when it
+  arrives with the data a second later. See
+  [Landing on an element](#landing-on-an-element-the-fragment).
 - **Going back or forward** (the browser's buttons, `navBack()`,
   `history.back()`) lands where that page was left. navi keeps the position and
   puts it back once the page is really rendered, which is what the browser
@@ -732,6 +737,81 @@ in a browser with no Navigation API — is `navBack()`. Where there may be
 nothing to go back to (a shared link opened cold), decide what the arrow does
 from the history, not from the link.
 
+### Landing on an element: the fragment
+
+A link meant to bring one element under the reader's eyes — a notification
+pointing at a section several screens down, a shared link to a comment, a row
+in a list — is an `id` on the element and a `#id` in the link. Nothing else:
+
+```jsx
+<Box id="tournaments">…</Box>
+
+// anywhere else
+<Link href={`${PLACE_ROUTE.buildUrl({ slug })}#tournaments`}>…</Link>
+```
+
+`<Link route>` builds no fragment, so the link spells its `href`.
+
+The browser alone is not enough in an app. It answers a fragment when the
+document finishes loading and on a fragment navigation within the page — both
+before the data has drawn the element — and a navigation navi routes is not a
+fragment navigation at all. So navi answers every URL carrying a hash itself:
+
+- **It waits for the element, and for the page.** The element is reached when
+  it exists and shows something (`checkVisibility`): one still loading, or
+  rendered inside a closed tab or a folded `<details>`, has not arrived yet.
+  navi opens nothing to reach it, and reaches it as soon as it shows — the
+  reader opening the `<details>`, switching to the tab — while the wait lasts.
+  And it is reached once no route or action is loading: until then, what sits
+  above it may still be drawn and push it down — and a page reusing the node of
+  the page being left (`/places/a#tournaments` → `/places/b#tournaments`) holds
+  it before its own data has come.
+- **It gives up.** Once the document has had no route or action loading for
+  `graceAfterIdle` (1 s). A link to an element that is gone lands where a link
+  without a fragment would — at the top of a page one arrives at — with no
+  mark. A document that never stops working is answered after `maxWait`
+  (10 s), with the element as it stands.
+- **A return is not an arrival.** Back, forward and a reload land where the
+  page was left, as they do without a fragment; the fragment then only puts
+  `:target` on its element — no scroll, no ring, no focus.
+- **It answers once per arrival.** What is watched is the path and the hash: a
+  search param written while the reader is there (a filter, a page) does not
+  throw them back to the element. Pressing the very link one is on answers
+  again.
+- **What the reader gets**: the element against the top edge, instantly (what
+  the browser does with a fragment); the keyboard focus on it when it is itself
+  focusable — an `id` on the link or the button, not on a box around one; and a
+  fading ring, the element carrying `data-url-target` for `markDuration` (2 s).
+  The ring is coloured by `--navi-url-target-color` and lives in `@layer navi`:
+  an unlayered `[data-url-target] { … }` replaces it, `animation: none` removes
+  it. Its length is `markDuration`, which also publishes
+  `--navi-url-target-duration` to CSS — setting only the variable makes the ring
+  and the attribute disagree.
+- **Adjusting it**: `setUrlTargetOptions()`, once, at the app's start — the
+  alignment (`block`), `behavior`, `markDuration`, `graceAfterIdle`, `maxWait`.
+
+**`:target` is the lasting "this one"**, and `data-url-target` the moment it
+arrived. navi sets `:target` on the element as it lands on it — the browser
+alone never would after a navigation navi routes, nor for an element that
+arrived after the load — and takes it off once the URL stops naming the
+element, which the browser alone would not either: a search param written on
+the page rebuilds the address without its fragment, a back returns to the page
+without one. It stays on the element navi landed on; a node rendered in its
+place later is another one. In JS, `useUrlTargetId()` is the id the hash
+designates, `""` when there is none, re-rendering when it changes.
+
+#### A fragment, or a search param
+
+A fragment says where to look; a search param says what to show. When the page
+draws something differently for the value — a filter, a selected row, an open
+panel — it is a [search param](#search-params). When the page is the same and
+only the reader's eyes should go somewhere, it is a fragment, down to a single
+row (`#tournament_42`).
+
+A search param plus a `scrollIntoView` in an effect rebuilds this, less well:
+the effect fires at mount, before what sits above the element has laid out,
+and nothing ever tells it to stop waiting.
+
 ### A row of tabs, where a replace IS an arrival
 
 The tabs of a `<RouteTravel>` navigate by replacing, and yet each one is another

package/docs/popup_open.md

@@ -1008,7 +1008,8 @@ slots".
 Being open is where the user is, and what a popup draws belongs to the screen
 exactly the way a page's own data does. So a popup that loads something binds
 its open state (above) and asks for its data with a `routeAction` whose params
-are `false` while it is closed:
+are `false` while it is closed — and its content reads the question itself,
+without the part that says whether it is open:
 
 ```js
 const groupSheetOpenSignal = stateSignal(false, {
@@ -1016,12 +1017,17 @@ const groupSheetOpenSignal = stateSignal(false, {
   type: "boolean",
 });
 
+// asked while the sheet is open
 export const GROUP_MEMBERS = routeAction(GAME_ROUTE, USER.GET_MANY, () => {
   if (!groupSheetOpenSignal.value) {
     return false;
   }
   return { group: groupSignal.value };
 });
+// read by the sheet, open or closed
+export const GROUP_MEMBERS_SHOWN = USER.GET_MANY.bindParams({
+  group: groupSignal,
+});
 ```
 
 ```jsx
@@ -1030,15 +1036,16 @@ export const GROUP_MEMBERS = routeAction(GAME_ROUTE, USER.GET_MANY, () => {
 </Dialog>;
 
 const GroupMembers = () => {
-  const [members] = useAsyncData(GROUP_MEMBERS); // reads, never runs
+  const [members] = useAsyncData(GROUP_MEMBERS_SHOWN); // reads, never runs
   …
 };
 ```
 
 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:
+route action reads the id straight from it, while each card's content reads the
+question of its own card. Declared on the root route, since a card is not a
+page:
 
 ```js
 const seatSheetSignal = stateSignal(undefined, {
@@ -1048,18 +1055,39 @@ const seatSheetSignal = stateSignal(undefined, {
 });
 const ANY_PAGE = route("/", { searchParams: { seat: seatSheetSignal } });
 
+export const seatableUsersOf = (gameId) => ({ game: gameId });
 export const SEATABLE_USERS = routeAction(ANY_PAGE, USER.GET_MANY, () => {
   const gameId = seatSheetSignal.value;
-  return gameId ? { game: gameId } : false;
+  return gameId ? seatableUsersOf(gameId) : false;
 });
 ```
 
 ```jsx
 <Dialog signal={seatSheetSignal} value={game.id}>
-  <SeatableUsers />
-</Dialog>
+  <SeatableUsers gameId={game.id} />
+</Dialog>;
+
+const SeatableUsers = ({ gameId }) => {
+  const [users] = useAsyncData(
+    USER.GET_MANY.bindParams(seatableUsersOf(gameId)),
+  );
+  …
+};
 ```
 
+**The content reads its question, never the route action.** The route action's
+params are `false` while the popup is closed, and for the route action that is
+right: it says _when_ to ask. Read by the content, the same `false` says there
+is nothing to show — `useAsyncData` hands back `undefined` the moment the popup
+closes, the list empties while hidden, and the next opening builds it again from
+the top: the scroll position is lost, and every row is rendered once more for an
+answer that never left the store. When the popup is one of many, it is worse: the
+route action follows whichever popup is open, so a card's sheet kept mounted
+since an earlier opening redraws with another card's rows each time that one
+opens. Closing a popup does not change what it is about, so what it reads leaves
+the open state out. Equal params share one instance — the content reads the very
+one the route action runs, so nothing is asked twice and nothing is copied.
+
 **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:
@@ -1116,7 +1144,8 @@ become a popup's private request — asked for late, and asked for alone.
 
 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.
+half-typed form where it left them, as long as the data it draws does not leave
+with the close (see [A popup that loads data](#a-popup-that-loads-data)).
 
 "Closed" is two states, not one — never opened yet, and closed again after an
 opening — so the `mount` prop answers both at once:
@@ -1134,7 +1163,13 @@ off it, fields a surrounding form submits, a size measured from outside.
 
 Whatever the value but `"while-opened"`, intent on the anchor — a pointer
 entering it, focus landing in it — builds the content ahead of the click that
-will open it.
+will open it. A `"while-opened"` popup is warmed only by a press on what opens
+it — a `--navi-open` button, a picker's trigger when a press opens it, an
+expandable's UI part — and a press that ends without opening it (a scroll, a
+drag, a release elsewhere) throws the content away: there is still one content
+at a time. A popup with an `onOpen` is never warmed, so the content is always
+built after it (see
+[`onOpen` runs before the popup has built anything](#onopen-runs-before-the-popup-has-built-anything)).
 
 `"while-opened"` is what an uncontrolled field seeded from a `defaultValue`
 needs: without it, a popup reopened after the underlying value changed still

package/docs/scroll.md

@@ -3,9 +3,9 @@
 Where scrolling happens in a navi app, and how the pieces that live inside a
 scrolling area (`Box header/body/footer`, `List`, a popup) are told about it.
 
-Where a navigation LANDS is another subject — a push at the top, a back or
-forward where the page was left, a row of tabs giving each tab back the offset
-it was read at: see
+Where a navigation LANDS is another subject — a push at the top, a push with a
+`#id` on the element it names, a back or forward where the page was left, a row
+of tabs giving each tab back the offset it was read at: see
 [navigation.md](./navigation.md#where-a-navigation-lands-the-scroll).
 
 - [What makes header/body/footer work: the overflow](#what-makes-headerbodyfooter-work-the-overflow)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/navi",
-  "version": "0.29.398",
+  "version": "0.29.400",
   "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.75",
+    "@jsenv/dom": "0.17.76",
     "@jsenv/humanize": "1.8.5",
     "@jsenv/validity": "0.4.5"
   },