@jsenv/navi 0.29.521 → 0.29.523

package/docs/AI_INSTRUCTIONS.md

@@ -83,12 +83,14 @@ start when unsure which export solves a problem.
 
 ### Data
 
-- `actions.md` — calling versus binding, a failing run rejects, reading is not
-  running (`{ run: true }` is the fallback), `action` versus `uiAction`, an
-  action and a command on one press. Before running an action from a component.
+- `actions.md` — calling versus binding, what a binding holds while its params
+  move (`inheritData`), a failing run rejects, reading is not running
+  (`{ run: true }` is the fallback), `action` versus `uiAction`, an action and a
+  command on one press. Before running an action from a component.
 - `resource.md` — `resource()` and its relations (never an `op` discriminator),
-  `GET_RANGE` (its inclusive `end`, the count for the screen around the list, a
-  question following a search field), a search as the same `GET_MANY`, `withParams()` scopes and
+  what each read shows while its params move, `GET_RANGE` (its inclusive `end`,
+  the count for the screen around the list, a question following a search
+  field), a search as the same `GET_MANY`, `withParams()` scopes and
   `dependencies`, `persist` (and `keepPageOnScreen` for the page on screen), a
   function versus the verb's instance. Before writing a resource, and before
   caching a response yourself.

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)
+  - [While the next answer comes](#while-the-next-answer-comes)
   - [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)
@@ -112,9 +113,11 @@ A request that follows typing — the suggestions under an address field — is
 this binding, never the field's `action`: a field whose action runs is busy,
 and a busy field is read-only, so the person could not go on typing.
 `actionDebounce` delays an action that saves what was typed. Such a request,
-written with a plain `createAction`, has no verb for the network policy to see
-([network_policy.md](./network_policy.md)): offline, its params say there is
-nothing to ask (`undefined`, [below](#nothing-to-ask-and-coming-back)).
+written with a plain `createAction`, declares that its previous suggestions
+stand in ([below](#while-the-next-answer-comes)), and has no verb for the
+network policy to see ([network_policy.md](./network_policy.md)): offline, its
+params say there is nothing to ask (`undefined`,
+[below](#nothing-to-ask-and-coming-back)).
 `src/control/demos/integration/0_address_autocomplete_demo.html` is this shape.
 
 ### The answer is kept on the instance that ran
@@ -138,13 +141,48 @@ 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)`.
 
+### While the next answer comes
+
+A binding moving to new params lands on an instance with no answer yet: `data`
+is `undefined` until its own arrives, and the screen draws its wait. The previous
+answer would be about something else — a club's podium under the name of the
+department just pressed, one person's partners on another's profile — and nothing
+would give it away: it reads as data, it only shows on a slow network, and it
+fixes itself when the answer lands.
+
+Another answer to **the same question** is different: results refined by a
+keystroke, a window recentred along a list, a thread read again because it grew.
+A blank between two of those is the only thing wrong on the screen, and the
+action says so:
+
+```js
+const searchAddresses = createAction(search, { inheritData: true });
+```
+
+The new instance then starts on what the previous one held, its failure included,
+and `loading` says a newer answer is coming. A resource declares this for each of
+its reads: one item starts on nothing, a list hands over
+([resource.md](./resource.md#what-a-read-shows-while-its-params-move)). When one
+action serves both kinds of screen, a binding says it for itself, in either
+direction:
+
+```js
+routeAction(AUTHOR_PAGE, VIDEOS, () => ({ author: authorSignal.value }), {
+  inheritData: false,
+});
+```
+
+Only a binding following a signal moves. Plain params make an instance that stays
+what it is, and hand nothing over.
+
 ### 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.
+An answer declared to stand in does so 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

package/docs/data_states.md

@@ -90,6 +90,14 @@ puts a reload on the second line as well, and so does
 [`keepPageOnScreen`](./resource.md#keeppageonscreen-the-page-on-screen-drawn-again-by-the-next-document) for
 what the page on screen reads — a `GET_MANY` and a `GET_RANGE` included.
 
+**Params moving ask another question, and its first answer is a first load.** A
+binding following a signal lands on an instance with no answer, on the first
+line: an action made with `createAction`, or the `GET` of a relation, which does
+not look in the store. What declares that the previous answer stands in starts on
+the second line: a `GET_MANY`, or `createAction(callback, { inheritData: true })`
+([actions.md](./actions.md#while-the-next-answer-comes),
+[resource.md](./resource.md#what-a-read-shows-while-its-params-move)).
+
 **The emptiness test is `data === undefined`, never `loading`.** Reading
 `loading` as "there is nothing to display" blanks the screen on every refresh —
 for a checkbox ticked on one row of a list, the whole list goes. A list is no

package/docs/drag_to_travel.md

@@ -38,12 +38,21 @@ the pointer inside a box that travels.
   pointer it has already cancelled (see
   [mobile_touch.md](./mobile_touch.md#the-browser-decides-about-8px-in-and-does-not-wait)).
   Its price is the click of a tap that shook more than 6px.
-- **A hand still moving when it lets go says where this goes, and it says it
-  both ways.** Towards what it was bringing in, the travel carries on, however
-  slowly, once it has pulled a few pixels. Away from it, fast, everything goes
-  back whatever the distance already covered — otherwise a screen caught in
-  flight and thrown back still arrives. Only a release at rest is judged by the
-  picture: about a third of the box.
+- **A page change is asked for a little later than the press is taken.** A
+  `RouteTravel` holds the press at the same 6px, but nothing is asked of the
+  router until the hand has pulled 10px further, 16px in all with a finger: a
+  navigation, a render and the requests of the page arriving are not worth a
+  hand that only shook. Turned around before that, it simply picks the other
+  neighbour. The picture sets off from where it stands rather than jumping those
+  pixels, and let go of before that, nothing has moved.
+- **Letting go asks where the hand is about to put things.** Where the picture
+  stands, plus half a second at the speed the fingertip has as it lifts, against
+  half the box. A flick lands far and goes. A hand thrown back lands short and
+  everything goes back, otherwise a screen caught in flight and thrown back
+  still arrives. A hand that slowed to a stop has no speed left, and the picture
+  answers alone. Speed counts from 25px of finger, a tap that slipped not being
+  a flick, and past 0.4 px/ms it answers on its own, or half a wide box would be
+  out of reach of any flick.
 - Pulling towards nothing follows the finger at a fraction of its distance and
   comes back: a wall one can lean on, never walk through.
 - **A direction that will be refused is one of those walls, and it must be a
@@ -210,6 +219,7 @@ carry screens.
 | what the screens are    | `<Slide>`s in one box, all mounted | routes — one mounted, ever         |
 | what says which is here | a `signal`, `current` / a command  | the URL                            |
 | what the finger moves   | a translated track                 | the pictures of a view transition  |
+| when the picture moves  | from the press becoming a gesture  | from 10px after that               |
 | letting go too early    | the track comes back               | the transition is played backwards |
 | what says the order     | the layout map                     | the `<Route>` children, in order   |
 | what one wheel push is  | `move(±1)`, as an arrow key        | one travel, as a tab pressed       |

package/docs/navigation.md

@@ -554,6 +554,23 @@ replace moves the scroll
 ([below](#a-row-of-tabs-where-a-replace-is-an-arrival)). Several `RouteTravel`
 boxes may live on one page, and only the one travelling is captured.
 
+**The URL says where the hand is heading, not where the reader is.** It changes
+once the hand has really pulled, and comes back if the page is let go of. So a
+counter, a title or a breadcrumb around the box reads
+`routeTravelSettledPageSignal` first, or it moves for a pull that goes nowhere:
+
+```jsx
+const settledPage = routeTravelSettledPageSignal.value;
+const shownId = settledPage ? settledPage.params.gameId : currentId;
+```
+
+It holds the `{ route, params }` the travel set off from for as long as the
+pictures move, and is `null` when they stop, the URL being the truth again. A
+page walked whole under the hand has arrived. A tab pressed or a wheel pushed
+holds nothing, and `null` is all they ever read. One signal for the document, as
+there is one transition at a time: on a page with several boxes, `route` says
+which row is travelling.
+
 `RouteTravel` is for pages that form a ROW the finger can push; pages related
 pair by pair are animated with `defineRouteTransition`, and a given pair by one
 of the two, never both (see

package/docs/resource.md

@@ -42,6 +42,7 @@ Actions are read in components through the action system (`useAsyncData`,
 - [Callback return contracts](#callback-return-contracts)
 - [When the backend answers a sub-route with the whole parent](#when-the-backend-answers-a-sub-route-with-the-whole-parent)
 - [Relations and autorerun](#relations-and-autorerun)
+- [What a read shows while its params move](#what-a-read-shows-while-its-params-move)
 - [`withParams()`: a scope with reruns of its own](#withparams-a-scope-with-reruns-of-its-own)
   - [`dependencies`: rerun after another resource writes](#dependencies-rerun-after-another-resource-writes)
 - [A function calling the verb, or the instance](#a-function-calling-the-verb-or-the-instance)
@@ -666,6 +667,43 @@ is a resource of its own, refreshed only by these rules. When a parent field
 depends on a child mutation, say so with `dependencies` rather than relying on a
 rerun that will not happen.
 
+## What a read shows while its params move
+
+A binding following a signal — a route action, `bindParams(signal)` — moves to
+another instance when its params change, and that instance has no answer yet.
+What it holds until its answer lands depends on the action
+([actions.md](./actions.md#while-the-next-answer-comes)):
+
+| Action                                                                                       | Until its answer lands                               |
+| -------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
+| `GET`                                                                                        | the row the store holds for these params, or nothing |
+| the `GET` of a relation (`.one()`, `.scopedOne()`, one item of `.many()` or `.scopedMany()`) | nothing, whatever the store holds                    |
+| `GET_MANY`, and the `GET_MANY` of `.many()` or `.scopedMany()`                               | the previous list                                    |
+| a write (`POST`, `PUT`, `PATCH`, `DELETE`, plural or not)                                    | what the previous instance held                      |
+
+A read of one item never starts on the previous answer: it would be another row,
+or another owner's, drawn under the new params, and nothing would give it away.
+
+A list hands over because one standing in for the next beats a skeleton. That is
+right for a search, the same collection asked again, and for a list nobody reads
+as a claim about its owner: a sheet of courts that catches up with the club a
+round trip later. It is false where the list says something about who it belongs
+to: one person's partners, on another's profile. The read cannot tell the two
+apart and the screen can, so the screen says it on its binding:
+
+```js
+const PARTNERS_ACTION = routeAction(
+  PROFILE_ROUTE,
+  USER_PARTNERS.GET_MANY,
+  () => ({ id: profileIdSignal.value }),
+  { inheritData: false },
+);
+```
+
+A `GET_RANGE` reader has no such choice to make: bound to other params it is
+another collection, drawn from its first item
+([above](#a-question-that-follows-a-search-field)).
+
 ## `withParams()`: a scope with reruns of its own
 
 A resource reruns its own reads after its own writes (`rerunOn`, see

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/navi",
-  "version": "0.29.521",
+  "version": "0.29.523",
   "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.101",
+    "@jsenv/dom": "0.17.102",
     "@jsenv/humanize": "1.8.11",
     "@jsenv/validity": "0.4.7"
   },