@jsenv/navi 0.29.416 → 0.29.418

package/docs/mobile_touch.md

@@ -19,6 +19,7 @@ changes, measure again before trusting a number here.
 - [Only the start is contested](#only-the-start-is-contested)
 - [The click is the browser's call as much as ours](#the-click-is-the-browsers-call-as-much-as-ours)
 - [A tap dropped after a touch drag](#a-tap-dropped-after-a-touch-drag)
+- [A finger is captured to what it touched, inside shadow trees too](#a-finger-is-captured-to-what-it-touched-inside-shadow-trees-too)
 - [A finger never makes a wheel event](#a-finger-never-makes-a-wheel-event)
 - [Verifying without a device](#verifying-without-a-device)
 
@@ -160,6 +161,40 @@ Chromium's `gesture_provider.cc` (`ignore_single_tap_`, reset on the next down)
 and `tap_suppression_controller.cc` (the tap that stops a fling, 180ms) for the
 two mechanisms that do NOT explain it.
 
+## A finger is captured to what it touched, inside shadow trees too
+
+A touch pointer is captured the moment it lands, by the browser, to the element
+it landed on — nobody calls `setPointerCapture`. A mouse and a pen are not.
+That capture is announced like any other, with a `gotpointercapture` just
+before the first pointer event that follows, and a finger resting still sends
+one soon: its contact changes, so `pointermove`s with unchanged coordinates
+come within the first 100ms or so. Nearly every touch press therefore sees a
+`gotpointercapture` it never asked for. Code that reads it as "another gesture
+took this press" gives up on almost every finger.
+
+Recognising that capture is where Chrome misleads: **it goes to the deepest
+element under the finger, shadow trees included.** On an `<input>` or a
+`<textarea>` that is the inner editor, inside the field's own shadow tree; in a
+web component, whatever its shadow root holds there. `hasPointerCapture` on
+what the page sees — the field, the host — answers `false` at `pointerdown`,
+after `gotpointercapture`, and for the whole press. Yet the `gotpointercapture`
+reaches the page retargeted to that same element. An open shadow root shows
+both halves: the host answers `false`, the element inside it `true`.
+
+So the browser's capture is recognised by where it lands, never asked for: on
+a touch press, a capture announced on the press's own target is the browser's,
+whenever it arrives. Compare both events from the same tree: each is
+retargeted to the shadow host from outside. A gesture that takes the press onto
+that same element cannot be told apart from it, so it has to say so another way.
+
+Measured in Chromium 153 through `Input.dispatchTouchEvent`. The capture does
+not depend on the slop, so the desktop path shows it; see
+[Verifying without a device](#verifying-without-a-device). The same `false` on
+a field shows on an Android phone (Chrome 153). Not measured in Safari.
+
+Reference: `implicitCaptureHolder` and `takePress` in `@jsenv/dom`'s
+`press_held.js`.
+
 ## A finger never makes a wheel event
 
 No mobile browser turns a touch into `wheel` events: those come from a mouse

package/docs/resource.md

@@ -300,6 +300,19 @@ store are written, and re-renders when its row is — `useArray` to the whole
 store. An entry of `useAllByIds` given by a unique key rather than by id can
 only be found by reading the whole store, and that read follows it too.
 
+A row counts as written only when something in it changed:
+
+- **An answer** — what a callback returns — is compared to the row held in
+  depth. Parsed JSON makes every object nested in a row a new one; a
+  revalidation returning the same rows keeps every one of them, and their
+  readers stay still.
+- **A relation** changes its row when the row points at other children. What
+  happens to the children themselves is followed through the relation:
+  `game.place.label` read in a render re-renders it when the place is written,
+  and the game row stays the one it was.
+- **A value written with `store.upsert()`** is compared by reference: a new
+  object is a change, whatever it holds.
+
 ## Relations: pick one of the four methods
 
 A backend sub-route (`/games/:id/candidates`, `/games/:id/candidates/:userId/seen`)

package/docs/route_transitions.md

@@ -552,9 +552,11 @@ Measured on that page, first frame of the movement: 63 → 45 ms at full speed,
 What that means for a page and for the application around it:
 
 - **It is still mounted for the length of the movement.** Its effects keep
-  running, and it still reads the address: whatever re-renders when the URL
-  changes re-renders in it too, hidden (see
-  [What a transition costs](#what-a-transition-costs)).
+  running, and it still reads the address: a component reading the URL, a
+  route or a signal directly re-renders in it too, hidden (see
+  [What a transition costs](#what-a-transition-costs)). What it reads through
+  `useAsyncData` does not: navi leaves a page alone as soon as its container
+  would no longer show it.
 - **It is taken down after the page arriving is up.** A cleanup that puts back
   what it found — a document title, a class on `<body>`, a value in a shared
   store — puts a stale value back over the new page's. Such a registration is
@@ -646,10 +648,36 @@ elements):
   thirty cards: 90 re-renders gone, first frame 58 → 41 ms). A row read with
   `RESOURCE.useById` follows that row only, so the page arriving loading rows
   of its own into the same store leaves the cards of the page being left as
-  they were. What reacts is then the page's own reading of its route's action
-  — its params, its data and its state all move as the route stops matching —
-  and that re-renders the page with everything in it (on the list of thirty
-  cards: about 1,150 component renders, the largest share of the callback).
+  they were. What moves last is the page's own reading of its route's action
+  — its params, its data and its state all change as the route stops
+  matching. `useAsyncData` gives no render to a page its container no longer
+  shows: the page is about to be taken down, or hidden until the movement is
+  over (on the list of thirty cards: about 450 component renders gone from the
+  callback, first frame 10–20 ms sooner at 4× CPU, nothing measurable at full
+  speed). A component reading the action's signals itself
+  (`action.dataSignal.value`) does not get that, and re-renders in the hidden
+  page.
+- **Restyling the page arriving more than once.** Built inside the update
+  callback, it is styled as it lands; anything written afterwards that its
+  elements inherit, or that re-selects them, restyles all of them again. On the
+  list of thirty cards (~7,000 elements) three did, 16–19 ms each at full
+  speed: the height of a list group's sticky label, written on the group once
+  measured (navi keeps it from being inherited, which took the movement 17 ms
+  sooner); the room a fixed bar takes (`--navi-fixed-bar-space-*`, feeding the
+  inherited `--navi-safe-area-inset-*`), which changes on the root when a bar
+  arrives or leaves with the page; and an app's `:has()` rule on the list
+  container over its rows (`.navi_list_container:has(.card) …`), evaluated
+  again as the rows land. An attribute the app sets on the container says the
+  same thing as that `:has()`, for nothing.
+- **Building rows the first picture does not show.** A list coming back
+  where it was draws, in the update callback, the rows that were on screen
+  then — the `visibleCount` of the position it is handed back (see
+  [scroll.md](./scroll.md#where-the-list-opens-and-where-it-is)) — and the
+  rest of its window once the movement has started. The movement does not wait
+  for them: it plays on the compositor, which keeps presenting frames while the
+  main thread builds the rows. On the list of thirty cards, handed its whole
+  position back: the movement starts 70–85 ms after the click instead of
+  185–270.
 - **Re-rendering what did not change, on the press itself.** A component that
   only wants a yes or a no reads a computed flag, not the signal it is derived
   from: a list whose rows each read the count of runs in flight re-rendered

package/docs/scroll.md

@@ -157,13 +157,25 @@ picked up then. When it is still not the box you mean, say so explicitly with
 - **`scrolled`** is the controlled form of the same thing — same pair as
   `open`/`defaultOpen` elsewhere in navi. The list goes back there every time it
   changes, even after the user scrolled.
-- **`onScrolledChange`** gives `{id, index, offset}` as the user scrolls.
+- **`onScrolledChange`** gives `{id, index, offset, visibleCount}` as the user
+  scrolls. `visibleCount` is how many rows were on screen from that one on:
+  handed back whole (`defaultScrolled={position}`), the position also says what
+  to draw first — the list's first commit draws those rows (and the one above,
+  when it stood partly in view) and the rest of its window once painted. An app
+  keeping only the `id` (in its url, say) keeps the place and drops that: the
+  list then draws its whole window before its first picture.
 - A list with an `id` **comes back where it was** when its screen is left and
   come back to, the way the page does: the position is kept under the list's
   `id` and the page's url, for the session, and put back by name the way
-  `defaultScrolled={{id, offset}}` is. A fresh arrival at the page still opens
-  at `defaultScrolled`. **`scrollResetOnNavigation`** opts out: the list then
+  `defaultScrolled={{id, offset}}` is — `visibleCount` included, and kept even
+  when the list was never scrolled. A fresh arrival at the page still opens at
+  `defaultScrolled`. **`scrollResetOnNavigation`** opts out: the list then
   opens the same way every time.
+- A list scrolling the document and opening on a row **places the document
+  itself**, on the row: the offset the page kept for its url is not put back
+  over it. Those are pixels of the page as it was drawn, and the rows the
+  window holds off screen are fillers of an estimated height — the same pixels
+  now fall on other rows.
 
 ### A search moves the list, and gives it back
 
@@ -390,10 +402,16 @@ scrolls: a `maxHeight` on a list that IS the scrolling area,
 ### The first paint of a list that opens in a click
 
 A popup's content is built in the click that opens it (see `popup_open.md`),
-and rows below the fold cost the same there as rows on screen. `renderBudget`
+and rows below the fold cost the same there as rows on screen. A page coming
+back in a route transition is the same case: it is built in the transition's
+update callback, and every row drawn there delays the movement. `renderBudget`
 takes `{ initial, after }` for exactly this: `initial` rows in the commit the
 browser paints first — what a phone screen shows, plus a few — and `after` from
-the paint on. The switch waits for the paint itself, not for an effect: preact
+the paint on. They are counted from the row the list opens on: the first
+picture of a list opening on a row shows that row and what is below it, and
+the window is centered on it only from the paint on. A position handed back
+with its `visibleCount` sizes that first window itself, whatever `initial`
+guessed. The switch waits for the paint itself, not for an effect: preact
 runs a component's pending effects early when that component renders again,
 and something always re-renders before a popup has painted. Do not rebuild
 this by hand with a `useEffect` that widens a slice: that effect is one preact

package/docs/state_binding.md

@@ -32,8 +32,6 @@ was missed.
 
 ## The callback that only remembers
 
-The same mistake, in four places:
-
 ```jsx
 // ✗ the app is told where the slides went, and writes it back down
 <SlideContainer
@@ -45,18 +43,6 @@ The same mistake, in four places:
 // ✓
 <SlideContainer signal={stepSignal} />
 
-// ✗ the control is told what it now holds, and the app writes it back down
-<Picker value={side} uiAction={(value) => (sideSignal.value = value)} />
-// ✓
-<Picker signal={sideSignal} />
-
-// ✗ a button proposing a value to a control, straight into the signal
-<Button onClick={() => (durationSignal.value = ninetyMinutes)}>1h30</Button>
-// ✓
-<Button command="--navi-update" commandFor="duration" value={ninetyMinutes}>
-  1h30
-</Button>
-
 // ✗ the popup is told it opened, and the app writes it back down
 <Dialog
   open={isOpen}
@@ -69,7 +55,8 @@ The same mistake, in four places:
 
 In each pair the second line is not a tidier spelling of the first: it is the
 binding the component already implements, and the first is a partial
-re-implementation of it.
+re-implementation of it. The same pair for a control's value, and for a button
+proposing one, is in [control_value.md](./control_value.md).
 
 ## Why it is not merely shorter
 
@@ -77,22 +64,20 @@ A binding is written by **everything that moves the state**, not only by the
 gesture the caller thought of. A `SlideContainer`'s signal is written by a drag,
 by an arrow key, by a `--navi-right` command sent from a chevron outside the
 box, by the address when the signal is a route's own, by a step refusing to be
-left. A control's
-signal is written by the user typing, by a group placing its children, by a
-picker committing on close, by a `--navi-update` from a shortcut button. A
-hand-written callback catches the cases it was written for and silently misses
-the rest — and the drift only shows on the screen where a second gesture was
-added.
+left. A control's signal is written by the user typing, by a group placing its
+children, by a picker filling its popup or putting back what it held on Escape,
+by a `--navi-update` from a shortcut button. A hand-written callback catches the
+cases it was written for and silently misses the rest — and the drift only shows
+on the screen where a second gesture was added.
 
 It reads in the other direction too, which no callback gives at all: writing the
 signal MOVES the component. The wheels roll, the slides travel, the popup opens.
 That is what replaces the `key` or the `value` prop pushed down to force a
 component into a state.
 
-And it goes through navi's interaction gate. A `command` on a read-only,
-disabled or busy control is refused and says why; an `onClick` doing the same
-write is plain DOM, fires on a greyed-out button and rewrites a value nobody was
-allowed to change.
+And a `command` goes through navi's interaction gate, which an `onClick` writing
+the same state does not (see
+[control_value.md](./control_value.md#a-button-that-proposes-a-value-is---navi-update)).
 
 ## What is left for the callback
 
@@ -113,13 +98,10 @@ Binding the state does not remove the callback — it removes one job from it:
 ## The callback also fires for the state's own changes
 
 A bound container walks to whatever its signal holds, and tells the callback
-about that walk — `cause: "state"`, `event: null`. It is the only piece that
-knows the change was not a press, and saying so is its job.
-
-The trap is on the other side. A callback that writes somewhere whose answer
-flows back INTO the signal — a server whose response is upserted into the store,
-a `useSignalSync` on the row that re-renders from it — makes every answer a
-change, and every change a write:
+about that walk — `cause: "state"`, `event: null`. The trap is a callback that
+writes somewhere whose answer flows back INTO the signal — a server whose
+response is upserted into the store, a `useSignalSync` on the row that
+re-renders from it:
 
 ```jsx
 // ✗ the answer of the write feeds the signal the write came from
@@ -130,49 +112,29 @@ const styleSignal = useSignalSync(user.share_image_style);
 />;
 ```
 
-With one write at a time nothing shows: the answer carries the value the signal
-already holds, so the model does not change. It takes two writes in flight — two
-notches 200ms apart, a 300ms round trip:
-
-```
-t=0    notch → B   signal=B   PUT B ──────────────┐
-t=200  notch → A   signal=A   PUT A ────────────┐ │
-t=300  B answers, store=B, signal=B, the box     │ │
-       walks to B, onCurrentChange(B, "state"),  │ │
-       save(B) → PUT B ───────────────────────┐  │ │
-t=500  A answers … save(A) → PUT A            │  │ │
-t=600  B answers … save(B) → PUT B            │  │ │
-…
-```
-
-Nothing was reordered — it is enough that an answer lands after a newer write
-was sent. Every answer is then the answer to a request the user has already
-moved past, the container obeys the model, the callback saves what it was just
-told, and that write's answer starts the next turn.
+One write at a time shows nothing: the answer carries the value the signal
+already holds. Two in flight — two notches in quick succession — and every
+answer is to a request the user has already moved past: the container walks to
+it, the callback saves it, and that write's answer starts the next turn. The
+loop never closes.
 
 Decide what the signal IS:
 
 - **The signal is the choice, the server only confirms it.** Seed it once with
-  `useSignal(model)` and never sync it. A late answer changes the store, not the
-  picture. The cost: a write that fails is not undone on screen unless the
-  callback undoes it. Right for a setting saved on the gesture, with no "Save"
-  button.
+  `useSignal(model)` and never sync it: a late answer changes the store, not the
+  picture, and a write that fails is not undone on screen unless the callback
+  undoes it. Right for a setting saved on the gesture, with no "Save" button.
+  That is a `SlideContainer`'s shape; a control says it with
+  `defaultValue={model}` and an `action` (see
+  [control_value.md](./control_value.md#a-defaultvalue-follows-what-it-was-read-from)).
 - **The model is the truth, the control only proposes.** Keep `useSignalSync`
-  and ignore `cause: "state"` in the callback — a change the state asked for is
-  not a choice to save. The cost: a late answer still pulls the picture back for
-  one round trip. Right when another client or a background refresh may change
-  the row while the control is on screen.
+  and ignore `cause: "state"` — a change the state asked for is not a choice to
+  save. A late answer still pulls the picture back for one round trip. Right
+  when another client or a background refresh may change the row while it is on
+  screen.
 - **Never two writes in flight for one field.** Debounce the write, or cancel
-  the one before it (`createRequestCanceller`), so no answer can be older than
-  the latest intent. Right when the write is the expensive part.
-
-Measured on the same screen, the same two notches, a 300ms round trip:
-
-| what the signal is                        | writes sent     | slide changes |
-| ----------------------------------------- | --------------- | ------------- |
-| `useSignalSync` + save every change       | 39, still going | 39            |
-| `useSignal`, seeded once                  | 2               | 2             |
-| `useSignalSync` + ignore `cause: "state"` | 2               | 4             |
+  the one before it (`createRequestCanceller`), so no answer is older than the
+  latest intent. Right when the write is the expensive part.
 
 ## What binds itself
 
@@ -189,13 +151,10 @@ Measured on the same screen, the same two notches, a 300ms round trip:
 
 "Who writes the score" has three answers — a player of the game, the organizer
 alone, nobody — and only two of them are rows: "nobody" is a switch under the
-list. So the state holds a value the list cannot show, and binding the list to
-that state leaves it showing nothing whenever the switch is on.
-
-The reflex is to fall back on `value` + `uiAction` and remember the row by hand.
-The finding is elsewhere: **the list is not asking that question**. It asks
-"which of these two", the switch asks "anybody at all", and the answer the
-screen sends is made of both:
+list. Bound to the state holding all three, the list shows nothing whenever the
+switch is on. The fix is not `value` + `uiAction`: **the list is not asking that
+question**. It asks "which of these two", the switch asks "anybody at all", and
+the answer the screen sends is made of both:
 
 ```jsx
 const scorerSignal = signal("player"); // what the list asks: one of ITS rows
@@ -210,13 +169,10 @@ const whoWritesSignal = computed(() =>
 ```
 
 Each control binds the state it is about, and the value that spans them is
-computed from those — never held a second time. It also gives back for free what
-the hand-written version had to arrange: the row chosen before the switch went
-on is still chosen when it goes off, because nothing ever cleared it.
-
-The rule underneath: a control shows values, so the state it binds is the one
-whose values it can show. A state holding more than that is more than one
-question.
+computed from those — never held a second time (the row chosen before the switch
+went on is still chosen when it goes off: nothing cleared it). A control binds
+the state whose values it can show; a state holding more than that is more than
+one question.
 
 ## When there is no binding
 
@@ -235,7 +191,6 @@ the next screen copies, and by then it is the app's pattern.
 
 - [control_value.md](./control_value.md) — who holds a control's value, and what
   a bound signal holds control by control
-- [actions.md](./actions.md#action-or-uiaction) — `action` or `uiAction`
 - [popup_open.md](./popup_open.md) — who owns the fact that a popup is open
 - [interactions.md](./interactions.md) — a gesture is named, not read by hand:
   the same rule, one layer down

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/navi",
-  "version": "0.29.416",
+  "version": "0.29.418",
   "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.83",
+    "@jsenv/dom": "0.17.84",
     "@jsenv/humanize": "1.8.6",
     "@jsenv/validity": "0.4.5"
   },