@jsenv/navi 0.29.492 → 0.29.494

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.

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

@@ -1107,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,20 @@ 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 `undefined` until the owner's row
+  or a callback speaks for it, `null` when that answer holds none. 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 +645,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 +784,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/docs/testid.md

@@ -213,7 +213,7 @@ side holds is a vnode of yours that takes its own.
 Navi's own attributes are implementation, not a contract: `data-header`,
 `data-body`, `data-scrollable`, `data-variant`, `data-callout-*`,
 `navi-control*`, `.navi_*` class names, the ids navi generates when none is
-given (`useId`), and the ids it derives from yours (a picker's popup id is built
+given (`navi_<n>`), and the ids it derives from yours (a picker's popup id is built
 from the picker's, so the suffix is navi's even when the base is not). They
 change without notice and without a migration note. The exception is the state
 a guideline doc tells an app to read — `navi-refreshing`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/navi",
-  "version": "0.29.492",
+  "version": "0.29.494",
   "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"
   },