@jsenv/navi 0.29.491 → 0.29.493

package/docs/actions.md

@@ -456,9 +456,13 @@ on a read-only control — holds everywhere but on a control with
 button and a link hold no state to mirror: there, each press is one call). The
 user typing is one cause among several: a `value` prop coming back down after a
 render, a popup control propagating its choice up to the picker holding it, a
-group cascading a value into its children — all of them reach `uiAction`, so
-that a signal or a local variable listening to it never drifts out of sync.
-Reading it as "the user did something" is the natural mistake.
+group cascading a value into its children, a group filling a control it builds
+(a popup's fields at the opening), a new `defaultValue` taken by a field nobody
+edited — all of them reach `uiAction`, so that a signal or a local variable
+listening to it never drifts out of sync. The one value it does not hear is the
+one a control starts on by itself, its own `defaultValue` or `value`: a mirror
+reads that one at mount. Reading it as "the user did something" is the natural
+mistake.
 
 The second argument says which one it was. Every event navi dispatches carries
 the event that caused it, and `findEvent(event, type)` walks that chain back:

package/docs/control_value.md

@@ -291,7 +291,9 @@ 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.
+mounted while closed. An object — a `ControlGroup`, a `Form` — takes it key by
+key: a field holding an edit keeps it, measured against its key of the new
+default, while the fields around it follow.
 
 Where the record goes depends on who sends it. A control that saves itself —
 its own `action`, nothing around it to press — takes it as `defaultValue`

package/docs/create_and_edit.md

@@ -237,22 +237,40 @@ typed in it, and coming back re-reads the resource. There is nothing to restore.
 ### A screen that stays open after Save
 
 Everything above assumes the screen is left on saving. One edited in place —
-a settings panel, saved, then edited again — has no shape that answers all of
-it yet, and each of the three leaves one thing out:
-
-- `defaultValue={record.x}` follows the record and never undoes an edit, but is
-  not held: an untouched Save sends the record back.
-- `onLoad` + `pristineKey` is held, and stops following: a record moved while
-  the screen is open stays as `onLoad` found it.
-- `useSignalSync(record.x)` ([state_binding.md](./state_binding.md)) is held
-  and follows, but the record moving overwrites what is being typed. It
-  compares by content: a record read again as a new but equal array or object
-  is not a move.
-
-Until one shape answers all three, a block that stays on screen takes
-`useSignalSync`, one per field: what it gives up — a move landing over a field
-being typed — needs someone else saving the same record at that moment, the
-rarest of the three on a settings block.
+a settings panel, saved, then edited again — asks three things at once: the
+form holds the record (an untouched Save sends nothing), follows it when it
+moves (another admin, a run ending), and never overwrites what is being typed.
+That is `<Form record>`:
+
+```jsx
+<Form action={saveSetting} record={setting}>
+  <Input name="interval_minutes" />
+  <CheckboxGroup name="sexes" required>
+    …
+  </CheckboxGroup>
+  <Button type="submit" readOnlyWhileFormUnchanged>
+    Enregistrer
+  </Button>
+</Form>
+```
+
+Each named field starts on its key, held. A new record — compared by content,
+so the same one read again is no move — is taken key by key: a field nobody
+touched shows it, a field being typed in keeps what is typed, and the form,
+measured against the new record from then on, reads changed exactly where an
+edit differs from it. Save then sends the edit with the other keys as the
+record now has them, not as they were when the screen opened. A send that went
+through needs nothing more: its answer, landing as the next record, is what
+the form holds. The record may be `undefined` while it loads — no
+`pristineKey`, no `onLoad` copy. Nothing tells the person typing that the
+record moved under their field: their Save is the answer.
+
+A single control that saves itself has the same three with
+`defaultValue={record.x}`, which follows and never undoes an edit; held only
+matters to a form. A control bound to a signal of the screen's own takes
+`useSignalSync(record.x)` ([state_binding.md](./state_binding.md)): held and
+following, compared by content, but the record moving overwrites what is being
+typed.
 
 What not to write: `useSignal(record.x)` with `key={record.updated_at}` on the
 block. The key throws away what is being typed each time the record moves.
@@ -435,9 +453,11 @@ only its mechanisms change.
 A list's copy of a record can be minutes old, so a sheet that saves the whole
 record reads it again as it opens, and that answer lands after the popup has
 taken what it holds at open. A `Picker` given the record as its `value` (or its
-signal) counts what the outside writes before the person changes anything as
-what was there at open: a look and a close send nothing, and a cancel goes back
-to the record as it arrived, not to the list's copy.
+signal) counts what the outside writes before the person presses or types in
+the popup as what was there at open: a look and a close send nothing, and a
+cancel goes back to the record as it arrived, not to the list's copy. A record
+landing after that press — a slow re-read, a sub-sheet opened only to look — is
+an edit, and a keeping close sends it.
 
 What does not change:
 

package/docs/data_states.md

@@ -25,8 +25,9 @@ whether a missing list is a skeleton, a sentence or an illustration.
 
 ## Asking for a state means receiving it as a value
 
-Without options, `useAsyncData` **delegates**: it suspends while the data is not
-there and throws when the action failed, so the states are drawn by the
+Without options, `useAsyncData` **delegates**: it suspends while the action
+runs — a rerun over data already held included — and throws when the action
+failed, so the states are drawn by the
 `<Loading>` and `<ErrorBoundary>` above rather than by the component. Each
 option turns one of those from something done _to_ the component into a value
 the component reads:

package/docs/drag_interactions.md

@@ -557,6 +557,21 @@ sends the copy home like any refused carry. Nothing waits on a write still out:
 the next drop is answered on its own, so an answer that replays its moves over
 the state it was given keeps two drops in a row in order.
 
+One outcome may answer two kinds of drop: a player put on another seat stands
+there at once, the same player dropped on « Free the seat » is asked first, and
+the copy has to wait over the zone while the question is open. `optimistic` is
+then a function of the drop — the `event.detail` the answer reads, without the
+event —, asked as the answer is about to run:
+
+```jsx
+land: {
+  answer: (event) =>
+    event.detail.toId === releaseZoneId ? askRelease(event) : land(event),
+  verb: "PATCH",
+  optimistic: (detail) => detail.toId !== releaseZoneId,
+},
+```
+
 Only `reorder` and `land`: a `move` hands its position over when the answer is
 in, and a throw has nothing to draw at once.
 

package/docs/interactions.md

@@ -111,7 +111,8 @@ A value can also say what it is besides what it does, as
 happen, and the policy's words are said where the hand made it — before anything
 moves, for a gesture: a carried thing is not picked up, a swiped row resists like
 a wall. `optimistic` is for a `reorder` or a `land` drawn at once and written
-after ([drag_interactions.md](./drag_interactions.md#answered-at-once-optimistic)).
+after — `true`, or a function of the drop deciding it per drop
+([drag_interactions.md](./drag_interactions.md#answered-at-once-optimistic)).
 A falsy `answer` is "not this one" too.
 
 ### The interactions navi detects

package/docs/navigation.md

@@ -580,7 +580,9 @@ Five cases, and they are not a policy to configure but five different facts:
   further down than that page is tall.
 - **Replacing the entry** (`<Link replace>`, `route.redirectTo()`, a param
   settling) moves nothing: the same place said differently — except in a row of
-  tabs, below.
+  tabs, below. A link to the address the document is at replaces too, as the
+  browser answers it: stacked, it would leave an entry that Back returns to
+  without moving.
 - **A reload** lands where one was, as it would have without navi, once the
   page is there ([below](#a-page-that-is-not-whole-yet)).
 
@@ -727,10 +729,19 @@ above the element has laid out, with nothing to tell it how long to wait.
 A mark that only designates — the row a notification points at, outlined until
 the reader moves on — is `:target` too, even though it restyles the element: it
 lasts until the page next writes its URL, which is the length of "this one". A
-search param would outlive it, as state the page does not act on. The alignment
-`setUrlTargetOptions({ block })` sets holds for the whole app; a target that wants
-to land with more room before it says so on itself, with a scroll-margin
-(`scrollMarginBlock` on a `Box`), which the landing honours.
+search param would outlive it, as state the page does not act on.
+
+Where the target lands is said for the app with `setUrlTargetOptions({ block })`,
+and by a target for itself with `data-url-target-block` — on the element, or on a
+box around it, a list saying it once for its items — read first. `"auto"` is the
+word for a target the app cannot size ahead: one that fits the screen (less the
+scroll-padding its bars reserve) lands in the middle, read with what is around
+it — the row a notification points at —, one taller lands on its top, where
+reading starts — an article of the terms. It is not the default: an `id` on a
+heading is short, and a heading is read from where it starts. A target that
+wants more room before it says so with a scroll-margin (`scrollMarginBlock` on a
+`Box`), which every alignment honours — never a margin computed to push it
+towards the middle, right for one height of row only.
 
 ### A row of tabs, where a replace IS an arrival
 

package/docs/network_policy.md

@@ -102,7 +102,7 @@ was asked:
 
 - **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
+  feeding 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
@@ -131,6 +131,17 @@ anything moves: a carried thing is not picked up, a swiped row resists as a wall
 does. Undeclared, the gesture plays to the end and the write it calls fails
 after — said on the element, the way any refused answer is.
 
+What a held form holds is what feeds its write: its fields, and a press that
+sends or updates what it holds. A button or a link asking nothing of that write
+stays pressable — a travel between slides or a step back in a wizard
+(`--navi-left`, `--navi-go-to-slide:recap`, `--navi-back`), a page (a `Link`,
+`--navi-nav-to`), a `uiAction`, a function of its own without `actionVerb` (a
+"Cancel", `ButtonCopyToClipboard`) — and so is a way out (`--navi-close`,
+`--navi-cancel`). The same goes for what a held control holds: a `Link` in the
+popup of a held `Picker` still leads to its page. The form's own read-only and
+busy state hold them all the same; `whenSelfInteractionsBlocked="ignore"` is what
+takes a button out of those too.
+
 ## Holding writes while reads go out
 
 `reads: "network"` keeps the first half of the policy and drops the second: the
@@ -196,6 +207,15 @@ has nothing to decide which one says why.
   />;
   ```
 
+  A `<Picker>` whose popup is that form is held the same way with
+  `openWhileReadOnly={false}` beside `readOnly`. Read-only alone, a picker
+  still opens, so that what it holds can be read, and everything in its popup
+  is held in turn — the right answer when the sheet has something to show, a
+  step for nothing when it only fills a form. When that form is bound to a
+  write or declares its `actionVerb`, navi holds it anyway, and marking the
+  opener only decides where the refusal is said: on the opener, before
+  anything opens, or in the sheet.
+
 - **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.

package/docs/popup_lift.md

@@ -24,6 +24,7 @@ and everything below follows from that one fact.
 - [A row of cards: one popup that walks](#a-row-of-cards-one-popup-that-walks)
 - [Lifting on the way back only](#lifting-on-the-way-back-only)
 - [What it costs, and where the time goes](#what-it-costs-and-where-the-time-goes)
+- [Less motion](#less-motion)
 - [The wall, and the frame before the movement](#the-wall-and-the-frame-before-the-movement)
 - [What the browser does around it](#what-the-browser-does-around-it)
 
@@ -286,9 +287,9 @@ and dev warns.
 
 **Tell the collecting close from the others.** Escape, the back button and a
 press on the wall close the dialog too, and usually mean "not now" rather than
-"collect". A `Dialog`'s or a `Popover`'s `onClose` receives who asked
-(`e.detail.requester`, the button of a `--navi-close`), and only the close that
-collects writes the state.
+"collect". A `Dialog`'s, a `Popover`'s or a `Picker`'s `onClose` receives who
+asked (`e.detail.requester`, the button of a `--navi-close`), and only the
+close that collects writes the state.
 The others land nowhere: the fixed `liftAnchor` names nothing, so they wait out
 those 300 ms, fade out, and dev warns.
 
@@ -317,6 +318,19 @@ and one layout. So the lever is the content:
 The movement itself is the browser's: once it starts, the content's cost is
 over.
 
+## Less motion
+
+Under `prefers-reduced-motion: reduce` nothing lifts: the popup opens or closes
+where it stands. Only the movement is gone — the close is the same close,
+`onClose` and `liftAnchor` are read as before, the wall still fades in. Not a
+cross-fade in its place: that is still a view transition, and the page stays
+frozen under its pictures for as long as it plays.
+
+A popup's own opening and closing answer the setting too: `scaling` and
+`expand-*` keep their fade and lose their growth, a `slide-from-*` lands at
+once, `fading` is unchanged. So `{ open: "scaling", close: "lifting" }` closes
+with a fade.
+
 ## The wall, and the frame before the movement
 
 The frame the dialog opens on is the picture the movement starts from. On it the

package/docs/popup_open.md

@@ -382,7 +382,10 @@ What the picker measures as "changed since open" is what its mirrored group
 holds. A piece of the answer living outside the controls — a seating rearranged
 by drag, kept in component state — has to be held by a control in the group too
 (a named control bound to that state), or a close over it reads as nothing
-changed and nothing runs.
+changed and nothing runs. The app writing that state is the person's change
+once they have pressed or typed in the popup (or in a sheet opened from it);
+before that it is the outside's — the record re-read as the sheet opens
+([create_and_edit.md](./create_and_edit.md#the-same-loop-in-a-dialog)).
 
 A card in a list opens on `openOn="longpress"`, so a tap on it stays a tap. Two
 pickers on one card — the score sheet inside the edit card — are one wait: the
@@ -1104,7 +1107,9 @@ share sheet per card) pays one element per closed popup at every mount, not a
 popup: a row may carry the popups of its own actions. It is built at once when
 something needs it from the start — open at mount, a `navState`, an `anchor` (a
 hover builds the content ahead of the click), or a `mount` other than the
-default. A `Picker`'s popup is the picker's own, built with it.
+default. A `Picker`'s popup is the picker's own, built with it: it is anchored
+on the picker's trigger, whose hover builds the content, and every way the
+picker opens asks its popup directly.
 
 "Closed" is two states, not one — never opened yet, and closed again after an
 opening — so the `mount` prop answers both at once:

package/docs/resource.md

@@ -566,12 +566,19 @@ out with an example in its JSDoc:
   parent the store does not hold yet is left alone: its array comes with its
   next read.
 - **`.scopedOne(propertyName, callbacks)`** — every callback returns
-  `[ownerId, props | null]`; the property is `null` until one does.
+  `[ownerId, props | null]`; the property is `null` until one does. An owner
+  the store does not hold yet is left alone: the answer is the action's value,
+  and the owner's next read brings its child.
 - **`.scopedMany(propertyName, { idKey, … })`** — `[ownerId, props]`; `PUT` (an
   id rename) `[ownerId, oldId, props]`; `DELETE` `[ownerId, childId]`; any
   `*_MANY` `[ownerId, itemArray]`, which replaces the whole collection;
   `DELETE_MANY` `[ownerId, [childId, …]]`. `idKey` names the child's own key
-  inside its owner (`"id"` by default).
+  inside its owner (`"id"` by default). Where the collection arrives — a
+  `*_MANY` answer, an owner answer embedding the property — each child is set
+  to what it received: a field the held child has and the answer lacks becomes
+  `undefined`, since nothing else holds a part of a scoped child (a seat
+  changing hands keeps nothing of whoever sat there). A singular answer merges
+  into the child, as it may carry a part of it.
 
 `ownerId` may be `{ [uniqueKey]: value }` when the owner is known by an
 alternate key. A scoped child takes relations of its own —
@@ -637,7 +644,8 @@ Relationship mutations do **not** invalidate their parent by default. The rules:
   (`POST_MANY` included), rerun nothing on the owner: the callback result
   already carries the updated child, or the whole collection. Its own reads
   still follow its `rerunOn` (`POST` covers `POST_MANY` there).
-- `.scopedOne` mutations rerun nothing, ever — the result is the new value.
+- `.scopedOne` mutations rerun nothing, ever — the result is the new value,
+  and whoever reads the property is drawn again with it.
 - `.one` / `.many` children live in an independent store; mutating them never
   reruns the parent. A `.many()` write changes the parent's array only through
   the answers naming it (`[parentId, …]`, see
@@ -775,6 +783,31 @@ written in place is; what fails throws into that first run. A cycle is fine: a
 rerun is one hop, and it reruns reads only. `createAction`'s `dependencies` take
 the same function form.
 
+As written, that `USER` entry reruns every profile and every list of people
+read in the session at each member added or removed — five more requests for
+three profiles and two lists, growing with the session. A member written moves
+the ranks of the group's list, read by slices, and changes no profile: name
+the reads a heard write reaches with `reads`:
+
+```js
+const USER = resource("user", {
+  dependencies: () => [
+    {
+      resource: PLAYER_GROUP,
+      on: ["addMember", "removeMember"],
+      reads: ["GET_RANGE"],
+    },
+  ],
+  GET,
+  GET_MANY,
+  GET_RANGE,
+});
+```
+
+`reads` takes `GET`, `GET_MANY` and `GET_RANGE`; left out, all three. Without
+`on`, it applies to every write of the resource. `createAction`'s
+`dependencies` refuse it: an action is one question, asked again whole.
+
 ## A function calling the verb, or the instance
 
 Both forms are real, and what separates them is narrower than it looks:

package/docs/scroll.md

@@ -129,7 +129,9 @@ today's) — and it is compared by value, so it can be computed at every render.
 left and come back to, or the page reloaded, the way the page does (its `id`
 must name one list of the app, see [below](#a-list-that-comes-back-one-id-one-list));
 **`scrollResetOnNavigation`** opts out. A push to its screen is an arrival and
-forgets it, even when the address names the item one was reading: a link that is
+forgets it — so is a document loaded fresh at its address, typed or reached from
+outside the app, where only a reload or a back/forward load finds it again —
+even when the address names the item one was reading: a link that is
 a return by meaning says `asReturn`, and the list comes back where that address
 was left (see
 [navigation.md](./navigation.md#where-a-navigation-lands-the-scroll)). What it draws there before its source

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/navi",
-  "version": "0.29.491",
+  "version": "0.29.493",
   "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.98",
+    "@jsenv/dom": "0.17.99",
     "@jsenv/humanize": "1.8.11",
     "@jsenv/validity": "0.4.7"
   },