@jsenv/navi 0.29.417 → 0.29.419

package/docs/network_policy.md

@@ -3,9 +3,9 @@
 One declaration says whether a request may leave, and the action layer reads it
 everywhere it matters. Two things follow from it:
 
-- **writes are held.** A control bound to a `POST`, `PUT`, `PATCH` or `DELETE`
-  action — or sitting in a form bound to one — is read-only and says why,
-  before the press.
+- **writes are held.** A control holding a `POST`, `PUT`, `PATCH` or `DELETE`
+  action — or sitting in a form holding one — is read-only and says why, before
+  the press.
 - **reads are answered from the store.** A resource `GET` completes with the row
   it already holds and asks nothing.
 
@@ -17,36 +17,24 @@ are the entire point — wants only the first, and says `reads: "network"`.
 ## What navi keeps without being asked
 
 What an app wants when the network is gone is one sentence: **answer from what
-you already hold, ask nothing, and refuse writes politely.** Nothing in it is
-about one app; navi does it once, and an app only has to say _when_.
-
-Leaving a page erases nothing. Four facts of the action layer add up to a
-cache the app never has to write:
-
-- **The data of a resource action is the store row.** A `GET` completes with an
-  id, and `action.data` is `store.select(id)`, live. Whatever was read once is
-  still there, updated by every later response that mentions it.
-- **A route action left behind is aborted, not reset.** Its value survives; only
-  a run in flight is called off.
-- **Running a completed action is a no-op.** Coming back to `/games/abc` from
-  the list sends nothing while the instance that read it is alive — `run()` on a
-  `COMPLETED` action already has its data. Only `rerun()` goes back to the
-  network (see [actions.md](./actions.md)). An instance nothing references any
-  more is asked again, with the store row drawn meanwhile; under the policy
-  that ask is answered from the store (below).
-- **A failed rerun keeps the previous value.** Only `errorSignal` and the
-  running state move; what was on screen stays on screen.
-
-So an app that caches responses in a `Map` beside navi is keeping a second copy
-of what the store holds — and going stale on its own.
+you already hold, ask nothing, and refuse writes politely.** navi does it once,
+and an app only has to say _when_. Leaving a page erases nothing: the data of a
+resource action is the store row, live, updated by every later response that
+mentions it; a route action left behind is aborted, not reset; coming back to
+`/games/abc` sends nothing while the instance that read it is alive, since
+`run()` on a completed action is a no-op
+([actions.md](./actions.md#running-run-rerun-prerun-reset)), and an instance
+nothing references any more asks again with the store row drawn meanwhile; a
+failed rerun keeps the previous value. So an app that caches responses in a
+`Map` beside navi is keeping a second copy of what the store holds — and going
+stale on its own.
 
 ## The one thing the app decides: the reason
 
-Which moments count as "offline" is the app's. A device without a network
+Which moments count as "offline" is the app's: a device without a network
 interface, a mode chosen in the settings, an outage the user agreed to stop
-fighting — these are not said the same way to the user, and an app may have
-none, one or all of them. Navi asks for a single value, the **reason**, and
-reads it everywhere it matters:
+fighting are not said the same way to the user. navi asks for a single value,
+the **reason**, and reads it everywhere it matters:
 
 ```js
 import { setNetworkPolicy } from "@jsenv/navi";
@@ -61,7 +49,7 @@ setNetworkPolicy(offlineReasonSignal, {
 ```
 
 The source may be a signal (followed live), a function, or a plain value. Set
-it once, at startup; there is nothing else to wire.
+it once, at startup.
 
 ## What the policy changes
 
@@ -71,28 +59,27 @@ was asked:
 
 - **A `GET` answers from the store.** If the row it designates is there, the
   action completes with it and nothing is asked. The row is the one its params
-  name — by the resource's `idKey`, or by any of its `uniqueKeys` — or, when
-  the params name none (a `GET` without params, like `/me`), the row the
-  action last completed with. Going from game A to game B, both read
-  before, is a change of params that would normally rerun `GAME.GET`; under the
-  policy it completes from the store, and a screen that does not take
-  `error: true` keeps drawing what it holds instead of falling into its error
-  boundary. A route opening a user by id **or** by slug gives navi both keys to
-  look by: `resource("user", { uniqueKeys: ["slug"], … })`.
+  name — by the resource's `idKey`, or by any of its `uniqueKeys` — or, when the
+  params name none (a `GET` without params, like `/me`), the row the action last
+  completed with. Going from game A to game B, both read before, is a change of
+  params that would normally rerun `GAME.GET`; under the policy it completes
+  from the store, and a screen that does not take `error: true` keeps drawing
+  what it holds instead of falling into its error boundary. A route opening a
+  user by id **or** by slug gives navi both keys to look by:
+  `resource("user", { uniqueKeys: ["slug"], … })`.
 - **A completed read stays completed.** `GET_MANY` (and every other read) has
   nowhere to answer from: the store holds items, not queries, and only the
   action's own value knows which ids answered `/users?scope=shareable`. So a
   rerun asked of a completed read under the policy is held — the action keeps
   its state, its value and its data, exactly as a `run()` on a completed action
-  would. This is the piece an app cannot do on its own: by the time a callback
-  runs, its action has already been reset.
+  would.
 - **A `GET_RANGE` revalidation fails quietly.** A list that comes back to the
   screen draws the composition it left and asks again for the window it draws;
   under the policy that ask fails, and a failed revalidation keeps the rows it
   had. Only a window never loaded shows the failure.
 - **Everything else settles with a `NetworkPolicyError`.** A read with nothing
-  in the store, a relationship `GET` (it has no row of its own to answer with), a
-  write that got through anyway: the action ends `FAILED` with an error whose
+  in the store, a relationship `GET` (it has no row of its own to answer with),
+  a write that got through anyway: the action ends `FAILED` with an error whose
   `reason` is the policy's value. `isNetworkPolicyError(error)` tells it apart
   from a request that left and never came back — that one is the app's `fetch`
   rejecting, and the app names it. The class says the request never left, and
@@ -101,30 +88,30 @@ was asked:
 
   It is an error only in the way it travels. Nothing treats it as a bug: navi
   never reports it as unhandled, and when one reaches `window` anyway — a run
-  called by hand whose failure nobody catches, a render throw no boundary took
-  — navi cancels the event, so neither the browser console nor the jsenv
-  overlay says anything. The person reads the screen; nobody else has to hear
-  about it.
-
-  One line is left, in dev only. A boundary displaying it — `<ErrorBoundary>`,
-  a control with `actionErrorEffect="throw"` — makes `preact/debug` log it with
-  `console.error`, as it logs every error a boundary catches, 404s and failed
-  fetches included. `preact/debug` reads no option or flag that would say the
-  error is handled, so that line stays. The jsenv overlay stays quiet, and a
+  called by hand whose failure nobody catches, a render throw no boundary took —
+  navi cancels the event, so neither the browser console nor the jsenv overlay
+  says anything. One line is left, in dev only: a boundary displaying it
+  (`<ErrorBoundary>`, a control with `actionErrorEffect="throw"`) makes
+  `preact/debug` log it with `console.error`, as it logs every error a boundary
+  catches, and `preact/debug` reads nothing that would say it is handled. A
   build does not load `preact/debug`.
 
-- **A write is refused before the press.** A control bound to a `POST`, `PUT`,
-  `PATCH` or `DELETE` action — or any control inside a `<Form>` bound to one —
-  is read-only while the policy holds, and answers the press with
-  `readOnlyMessage`. Nothing to add per button.
+- **A write is refused before the press.** A control holding a write verb's
+  instance — `GAME.DELETE`, `GAME.DELETE.bindParams({ id })` — or any control
+  inside a `<Form>` holding one, is read-only while the policy holds, and
+  answers the press with `readOnlyMessage`.
 
 Which actions the policy sees: those declaring a verb (`meta.verb`) — every
-action a `resource()` makes. A plain `createAction` may not touch the network
-at all, so it is left alone. `createAction(callback, { meta: { verb } })` opts
-it into what the action layer holds — a control bound to a write verb is
-read-only, a completed `"GET"` is not rerun — but its callback is still called
-when it runs: answering from the store and settling with a `NetworkPolicyError`
-are done by the callbacks a `resource()` wraps.
+action a `resource()` makes. A plain `createAction` may not touch the network at
+all, so it is left alone, and so is a function handed to a control's `action`:
+it is wrapped into an action with no verb, even when it calls one, so the
+control is not held and the write fails after the press with a
+`NetworkPolicyError` ([resource.md](./resource.md#a-function-calling-the-verb-or-the-instance)).
+`createAction(callback, { meta: { verb } })` opts an action into what the action
+layer holds — a control bound to a write verb is read-only, a completed `"GET"`
+is not rerun — but its callback is still called when it runs: answering from
+the store and settling with a `NetworkPolicyError` are done by the callbacks a
+`resource()` wraps.
 
 ## Holding writes while reads go out
 
@@ -149,10 +136,9 @@ own account.
 What this buys over a guard in the app's own request layer is **when** the
 refusal happens. A guard one layer below sees a request that was already built:
 the press was accepted, the sheet opened, the form submitted, and only then does
-it fail. navi knows which controls are bound to a write before any of that, so
-the button says why instead of being pressed, and the dialog it would have
-opened never opens. A button that always fails teaches people not to press
-buttons.
+it fail. navi knows which controls hold a write before any of that, so the
+button says why instead of being pressed, and the dialog it would have opened
+never opens. A button that always fails teaches people not to press buttons.
 
 ## Two reasons at once
 
@@ -174,8 +160,8 @@ setNetworkPolicy(networkPolicyReasonSignal, {
 
 `reads` is read from the reason for exactly this: one declaration, and the
 reason decides which kind of policy is holding. The `??` above is the
-precedence, and it is the app's to write — when both hold the same write, which
-one says why is something navi has nothing to decide it with.
+precedence, and it is the app's to write: when both hold the same write, navi
+has nothing to decide which one says why.
 
 ## What stays the app's
 
@@ -195,14 +181,14 @@ one says why is something navi has nothing to decide it with.
 - **What a screen says on a `NetworkPolicyError`** — "no network" is a fact
   about the device, "offline mode" a decision, "we are only looking" neither;
   `error.reason` is there so the screen says the right one.
-- **Which answer is worth keeping across a reload.** A resource declaring
+- **Which answer is worth keeping across a reload** — which resource, into
+  which signal, for which session: a resource declaring
   [`persist`](./resource.md#persist-the-last-answer-drawn-again-after-a-reload)
-  has its last `GET` answer back in the store at the first run, and under the
-  policy that row answers the `GET`: a reload offline reopens on it. Which
-  resource, into which signal, and for which session, is the app's to say.
-- **A queue of writes to replay** once the network is back. Deliberately not
-  navi's: what a replayed write means (a score entered twice? a seat taken
-  since?) is the app's business.
+  has its kept row answer the `GET` under the policy, so a reload offline
+  reopens on it.
+- **A queue of writes to replay** once the network is back — not navi's: what a
+  replayed write means (a score entered twice? a seat taken since?) is the app's
+  business.
 
 ## See also
 

package/docs/pan_zoom.md

@@ -36,20 +36,19 @@ them panning and the distance between them zooming, and a finger lifting
 re-anchors on what is left. What a pixel of pan means in your coordinates, and
 whether the zoom is continuous or stepped, is yours: the numbers are the numbers.
 
-What navi holds is what has to be settled **before** the press: `touch-action` on
-the surface, said from a stylesheet because a browser decides what a touch may do
-when it lands; the pan stepping back for what is carried across the surface (a
-`move`, a handle, a field, a popover — the same list a travelling box steps back
-for); the pinch not beginning as a pan under its first finger; the wheel and the
-pinch writing one `zoom`; the capture, the pointer the browser drops, the click
-the release leaves behind, and the next tap's click, which Chrome on Android
-drops after a touch drag whose `touchmove`s nobody refused (see
-[mobile_touch.md](./mobile_touch.md#a-tap-dropped-after-a-touch-drag)).
-A pointer pans only once it has travelled a few px (`data-drag-threshold`), so a
-tap stays a tap: a `longpress` declared beside `pan` still gets its hold, and a
-`double_click` still gets its two presses. A press that does pan is the
-surface's: a `longpress` waiting on it gives up the moment the pan begins, even
-inside its own slop.
+Everything else is settled before the press, and there is nothing to wire: the
+pan steps back for what is carried across the surface (a `move`, a handle, a
+field, a popover — the same list a travelling box steps back for), the pinch does
+not begin as a pan under its first finger, the wheel and the pinch write one
+`zoom`, the click the release leaves behind is swallowed, and the next tap's is
+kept — Chrome on Android drops it after a touch drag whose `touchmove`s nobody
+refused (see
+[mobile_touch.md](./mobile_touch.md#a-tap-dropped-after-a-touch-drag)). A pointer
+pans only once it has travelled a few px (`data-drag-threshold`), so a tap stays
+a tap: a `longpress` declared beside `pan` still gets its hold, and a
+`double_click` its two presses. A press that does pan is the surface's: a
+`longpress` waiting on it gives up the moment the pan begins, even inside its own
+slop.
 
 Declared alone, `zoom` takes two fingers and the wheel and leaves one pointer to
 whatever else reads it: nothing captures it, waits on it or swallows its click
@@ -62,9 +61,8 @@ the page.
 
 A surface takes every touch that lands on it, which is right for a map filling
 the screen — there is no page left behind it to scroll. A plan shown as a
-thumbnail on a page is the other case: a finger there means to scroll nine times
-out of ten, and a surface answering all of them makes the page unreadable past
-it.
+thumbnail on a page is the other case: a finger there usually means to scroll,
+and a surface answering every one makes the page unreadable past it.
 
 ```jsx
 <Box data-pan-after-hold interactions={{ pan, zoom }} />
@@ -74,20 +72,16 @@ The finger then says it means THIS surface the way it says it means to carry a
 drag source — by standing still. Until the hold the page keeps its scroll, and
 the pan starts where the finger already is. The pinch is not given away with it:
 two fingers on a surface that answers `zoom` are its own. A mouse travelling is
-untouched — a button held down over a surface could never have meant a scroll,
-and its wheel is settled on its own (see below) — and it is read off the element
-or any ancestor, the same place `data-drag-on-contact` is said.
+untouched — a button held down over a surface could never have meant a scroll.
+It is read off the element or any ancestor, like `data-drag-on-contact`.
 
-Opt-in, and for the same reason its opposite is (see
-[`data-drag-on-contact`](./drag_interactions.md#a-finger-that-does-not-have-to-wait-data-drag-on-contact)):
-navi cannot see whether anything behind the surface scrolls. You know;
-say so. It spends the hold, though: a `longpress` declared beside a `pan` that
-waits asks one finger to answer two waits, and the surface's — the shorter one
-— is the one answered.
-
-On a surface that only zooms there is no pan to wait for: one finger is the
-page's to scroll, two are the surface's, and `"kept"` (below) has nothing to
-keep.
+Opt-in, for the same reason its opposite
+[`data-drag-on-contact`](./drag_interactions.md#a-finger-that-does-not-have-to-wait-data-drag-on-contact)
+is: navi cannot see whether anything behind the surface scrolls. You know; say
+so. It spends the hold: a `longpress` declared beside a `pan` that waits asks one
+finger to answer two waits, and the surface's — the shorter one — is the one
+answered. On a surface that only zooms there is no pan to wait for: one finger is
+the page's, two are the surface's, and `"kept"` (below) has nothing to keep.
 
 The wait is then asked before every pan, which is right while each finger
 landing there is genuinely ambiguous. Once the user has settled into the plan it
@@ -98,14 +92,11 @@ is not, and asking again is asking three times for one sentence:
 ```
 
 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.
-It asks again only after a press has landed away from it, which is the hand
-saying it has moved on; navi watches for that press itself, so nothing on your
-side listens to the window.
-
-The paid wait is a state to draw — the map answers on contact now, and the user
-has to be told — so the surface says it: `[data-hand-kept]`, for as long as it
-holds the hand, a finger on it or not.
+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
+`"kept"` surface carries it: `[data-hand-kept]`, for as long as it holds the
+hand, a finger on it or not.
 
 ```css
 .plan[data-hand-kept] {
@@ -113,23 +104,20 @@ holds the hand, a finger on it or not.
 }
 ```
 
-Only a `"kept"` surface ever carries it: one that answers on contact was never
-given anything to keep. `[data-grabbed]` is the narrower word — a hand on it at
-this instant — and the two are drawn together or apart as you like
-(`[data-hand-kept]:not([data-grabbed])` is the surface waiting, held, for the
-next finger).
+`[data-grabbed]` is the narrower word — a hand on it at this instant — so
+`[data-hand-kept]:not([data-grabbed])` is the surface waiting, held, for the
+next finger.
 
 ### A wheel that does not steal the page's scroll
 
-A wheel over a surface in a page means to scroll that page nine times out of ten
-— it is what a wheel means everywhere else on it, and a surface that answers all
-of them makes the page unreadable past it, the same way a finger taking every
-touch does.
-
-So a bare wheel zooms only where nothing around the surface would have scrolled:
-a map filling the screen, a board in a modal. Where something would — a plan
-shown in the middle of a page — the page keeps its scroll and the zoom is one
-key away:
+A wheel over a surface in a page means to scroll that page just as often as a
+finger does, and is settled the other way for one reason: what a TOUCH may do is
+decided before it lands, from `touch-action`, so only the caller can say it; a
+WHEEL is read, and by the time the event is there, what scrolls around the
+surface can simply be looked up. So nothing is declared: a bare wheel zooms only
+where nothing around the surface would have scrolled — a map filling the screen,
+a board in a modal (the walk stops at a modal) — and where something would, the
+page keeps its scroll and the zoom is one key away:
 
 | wheel over the surface | in a page that scrolls | where nothing scrolls |
 | ---------------------- | ---------------------- | --------------------- |
@@ -137,22 +125,12 @@ key away:
 | `ctrl` / `meta` held   | zooms                  | zooms                 |
 | trackpad pinch         | zooms                  | zooms                 |
 
-Nothing is declared for this, unlike `data-pan-after-hold` right above — and the
-difference is worth knowing, because it is the same question asked twice. What a
-TOUCH may do is settled before it lands, from `touch-action`, so nothing can be
-read at that point and only the caller knows. A WHEEL is read: by the time the
-event is there, what scrolls around the surface can simply be looked up, so navi
-looks it up instead of asking. The walk stops at a modal, whose page behind is
-not what a wheel over it is for.
-
 A refused wheel is not a wheel that did nothing: navi says what it is waiting for
 (`⌘ + scroll to zoom`, `Ctrl` off a Mac) in a callout over the surface, which
-goes away with the gesture. It is navi's own text, `interaction.zoom.needs_modifier`
-— override it through `naviI18n` like any other (see `docs/i18n.md`).
-
-The trackpad pinch arrives as a wheel with `ctrl` held, which is why it goes on
-zooming everywhere: it is the desk's version of two fingers on a phone, and it
-was never the page's.
+goes away with the gesture — navi's own text, `interaction.zoom.needs_modifier`,
+overridden through `naviI18n` like any other (see [i18n.md](./i18n.md)). The
+trackpad pinch arrives as a wheel with `ctrl` held, which is why it zooms
+everywhere: it is the desk's version of two fingers on a phone.
 
 ```jsx
 <Box data-zoom-on-contact interactions={{ pan, zoom }} />
@@ -160,32 +138,16 @@ was never the page's.
 
 `data-zoom-on-contact` takes the bare wheel back, for a surface that owns it
 whatever stands around it — a map whose page happens to scroll a little, an
-editor where the wheel is a tool. Read off the element or any ancestor, the same
-place `data-pan-after-hold` is.
+editor where the wheel is a tool. Read off the element or any ancestor.
 
 ### When the surface has the hand: `grab`, `release`, `[data-grabbed]`
 
 A surface that is asked for — by a hold, by the first few pixels of travel, or
 by a second finger — has an instant where it becomes the hand's, and nothing on
-screen says it. The hand then moves too early and scrolls the page instead, or
-waits long past the moment out of doubt. So the surface says it, the same two
-words a carried element says (`grab`, `release`) and the same attribute:
-
-```jsx
-<Box
-  data-pan-after-hold
-  interactions={{
-    pan,
-    zoom,
-    grab: (event) => {
-      if (event.detail.pointerType === "touch") {
-        navigator.vibrate?.(10);
-      }
-    },
-    release: () => {},
-  }}
-/>
-```
+screen says it: the hand moves too early and scrolls the page, or waits long past
+the moment out of doubt. So the surface says it with the two words and the
+attribute a carried element uses (see
+[drag_interactions.md](./drag_interactions.md#saying-the-grab-is-acquired-grab)).
 
 ```css
 .plan[data-grabbed] {
@@ -195,20 +157,17 @@ words a carried element says (`grab`, `release`) and the same attribute:
 
 `[data-grabbed]` is on the element for as long as a hand is on the surface (on
 one that only zooms, from the second finger landing to the last one lifting), so
-a contour, a veil or a raised shadow needs no listener — which is what this is
-usually for. (`[data-hand-kept]` is the other one, and it outlasts the finger:
-see [`data-pan-after-hold`](#a-surface-that-scrolls-past-data-pan-after-hold).) `grab` and `release` are for the rest: a vibration, a state kept
-elsewhere. Their detail is `{ pointerType }`; like a drag's, they **report and do
-not ask**, and declared without `pan` or `zoom` they are a drag's words again,
-which is what the dev warning says.
-
-**Do not read the capture instead.** `setPointerCapture` is what the gesture takes
-at that same instant, and it is the wrong signal twice over: the browser does not
-announce a capture when it is taken but just before the NEXT pointer event for
-that pointer, so a finger that holds still and then keeps still is announced
-nothing at all, and a finger that moves is told at the very moment the surface is
-already moving under it. With a mouse it lands mid-travel. `grab` is told where it
-happens, before the first `pan`.
+a contour, a veil or a raised shadow needs no listener. `grab` and `release`,
+declared beside `pan`/`zoom`, are for the rest — a vibration on the touch that
+took the surface, a state kept elsewhere. Their detail is `{ pointerType }`; they
+report and do not ask, and declared without `pan` or `zoom` they are a drag's
+words again, which the dev warning says.
+
+**Do not read the pointer capture instead.** The browser announces it just
+before the NEXT pointer event, so a finger held still is announced nothing and a
+finger that moves is told when the surface is already moving under it (see
+[mobile_touch.md](./mobile_touch.md#a-finger-is-captured-to-what-it-touched-inside-shadow-trees-too)).
+`grab` is told where it happens, before the first `pan`.
 
 ## Reference
 
@@ -217,5 +176,5 @@ happens, before the first `pan`.
   page, on `installPanZoom` from `@jsenv/dom`.
 - `@jsenv/dom` — `src/interaction/drag/pan_zoom.js`: the pointers, the pinch,
   the wheel and what it is given to.
-- `src/control/demos/38_interactions_demo.html` — a surface panned and zoomed.
-- `src/control/demos/integration/5_plan_editor_demo.html` — a plan editor.
+- `src/control/demos/38_interactions_demo.html` — a surface panned and zoomed,
+  after a hold, and kept.