@jsenv/navi 0.29.442 → 0.29.444

package/docs/AI_INSTRUCTIONS.md

@@ -114,8 +114,8 @@ start when unsure which export solves a problem.
   Before any handler whose body only assigns state.
 - `control_value.md` — who holds a control's value; `--navi-update` for a button
   proposing one; a `defaultValue` follows the record it was read from; empty
-  keeps the shape of the question. Before wiring a value with `value` +
-  `uiAction`.
+  keeps the shape of the question; what a checkbox is worth (`boolean` for a
+  yes/no). Before wiring a value with `value` + `uiAction`.
 - `control_object.md` — one value made of several controls: `ControlGroup` versus
   `Form`, naming, `<Picker type="object">`, a settings sheet, controls that are
   not there (lazy slides, popups, deferred boxes, items outside the render
@@ -186,10 +186,11 @@ start when unsure which export solves a problem.
   `scroller`, where a list opens (a position handed back whole, `visibleCount`
   included), a list that comes back (its `id` names one list of the app), a
   popup that scrolls, many rows (`<List.Items>`, the render window and its first
-  picture, `findText`), many sections (`<Box mount="after-paint">` and what it
-  leaves out of reach), hover while scrolling. Before writing CSS to
-  make something scroll, before rendering a collection as `<List.Item>`
-  children, and before deferring part of a page.
+  picture, skeletons at the size of their item, `itemSize`, `findText`), many
+  sections (`<Box mount="after-paint">` and what it leaves out of reach), hover
+  while scrolling. Before writing CSS to make something scroll, before
+  rendering a collection as `<List.Item>` children, before writing a
+  `renderSkeleton`, and before deferring part of a page.
 - `z_index.md` — DOM order first; a `z-index` without `isolation: isolate`
   competes with the page; navi's bands. Before writing a `z-index`.
 - `typography.md` — text is a component; `maxLines` is the one truncation; one
@@ -225,8 +226,10 @@ start when unsure which export solves a problem.
   `<Input type="checkbox">`/`<Input type="radio">`; there is no `Checkbox`),
   `Select`, `Picker` and the others work with nothing wired: inside a `Form`, the
   form reads them when it sends. When the app needs the value, bind it with
-  `signal`. `action` reacts to a change that can fail or take time; it is not how
-  a control is wired. Never `onChange` + manual state.
+  `signal`. A checkbox is HTML's (`"on"` or its `value`, `undefined` unchecked);
+  a yes/no is `<Input type="checkbox" boolean>`, `true` or `false`. `action`
+  reacts to a change that can fail or take time; it is not how a control is
+  wired. Never `onChange` + manual state.
 - **A gesture is named, not read by hand**: `interactions={{ swipe_right: … }}`
   on any `Box`, so on any component — never a `pointerdown` listener of your own.
 - **Texts**: a user-visible sentence containing a value is one template with

package/docs/actions.md

@@ -313,13 +313,17 @@ the control's value, so the callback receives what the control now holds.
 ```jsx
 // ✓ the box shows it is saving, says so if the save fails, and goes back to
 //   where it was — nothing to write for any of it
-<Input type="checkbox" action={(visibility) => saveMe({ visibility })} />
+<Input type="checkbox" boolean action={(visibility) => saveMe({ visibility })} />
 
 // ✗ same save, and the user learns nothing: no pending state, and a failure
 //   leaves the box showing something the server never accepted
-<Input type="checkbox" uiAction={(visibility) => saveMe({ visibility })} />
+<Input type="checkbox" boolean uiAction={(visibility) => saveMe({ visibility })} />
 ```
 
+`boolean` makes the box a yes/no, `true` or `false`; without it, unchecked is
+`undefined` and the save sends nothing (see
+[control_value.md](./control_value.md#what-a-checkbox-is-worth)).
+
 The give-away is an `async` `uiAction`, or one that calls something that writes:
 `uiAction` never waits for what it starts, so nobody is left holding the result.
 To merely REMEMBER the value rather than send it, neither is the answer: bind a

package/docs/control_value.md

@@ -14,6 +14,7 @@ somewhere else in the app.
 - [Drawing what a control holds](#drawing-what-a-control-holds)
 - [What a signal holds, control by control](#what-a-signal-holds-control-by-control)
 - [Empty keeps the shape of the question](#empty-keeps-the-shape-of-the-question)
+- [What a checkbox is worth](#what-a-checkbox-is-worth)
 - [Which controls take a `signal`](#which-controls-take-a-signal)
 - [The PROP is what controls, not its value](#the-prop-is-what-controls-not-its-value)
 - [A yes/no shown as two rows](#a-yesno-shown-as-two-rows)
@@ -281,18 +282,37 @@ it holds something. A list of days nobody picked is `[]`, not `""`:
 | `Picker type="array"`, `List selectable multiple` | `[]`     |
 | `Picker type="object"`                            | `{}`     |
 | text/number/date `Input`, `Select`                | `""`     |
-| `Input type="checkbox" value={true}`              | `false`  |
-| radio, checkbox holding a value of its own        | absent   |
+| `Input type="checkbox" boolean`                   | `false`  |
+| radio, any other checkbox                         | absent   |
 
 This is what a clear (`--navi-clear`, a row's cross) leaves behind and what the
 object around it carries, so `value.days || []` is not needed.
 
-A checkbox is a member of a set, the way HTML has it: checked it carries its
-`value` (`"on"` when it was given none), unchecked it carries nothing at all —
-which is what lets several checkboxes sharing a name aggregate into an array. A
-checkbox that is a yes/no says so with `value={true}`, and is then `true` or
-`false`. Its bound `signal` holds the boolean either way: what a signal on a
-checkbox is about is whether it is checked.
+## What a checkbox is worth
+
+A checkbox answers the way HTML's does: checked it carries its `value`,
+unchecked it carries nothing. `boolean` makes it a yes/no instead:
+
+| checkbox       | checked  | unchecked   |
+| -------------- | -------- | ----------- |
+| no `value`     | `"on"`   | `undefined` |
+| `value="toto"` | `"toto"` | `undefined` |
+| `value={true}` | `true`   | `undefined` |
+| `boolean`      | `true`   | `false`     |
+
+That is what it hands everywhere: to its own `action` and `uiAction`, and to
+the form or group around it. Only a bound `signal` differs: it holds whether the
+box is checked, a boolean in every row above.
+
+Choose by what the box asks:
+
+- **A yes/no** (a setting, a consent, a favourite) is `boolean`. Unchecked has
+  to say "no", and `undefined` says nothing: `{ favourite: undefined }` is sent
+  as `{}`, the server changes nothing, and the box shows a "no" nobody
+  accepted.
+- **A member of a set** (several checkboxes sharing a `name`, each adding its
+  value) takes its own `value`, or none for `"on"`. Unchecked carries nothing,
+  so the group gathers only the checked ones into an array.
 
 ## Which controls take a `signal`
 

package/docs/mobile_touch.md

@@ -207,8 +207,9 @@ below, though: the obvious ones hide the race.
 **Chrome**: drive DevTools' touch emulator, which goes through Chrome's
 gesture detector with the **mobile** configuration (8px slop):
 
-- a headed Chromium (`chromium.launch({ headless: false })`) — headless
-  delivers nothing through this path;
+- a full browser: Chrome (`chromium.launch({ channel: "chrome" })`), headless
+  or not, or a headed Chromium (`headless: false`) — Playwright's default
+  headless shell delivers nothing through this path;
 - on a CDP session, `Emulation.setEmitTouchEventsForMouse({ enabled: true,
 configuration: "mobile" })`, then `Input.dispatchMouseEvent` with
   `mousePressed` / `mouseMoved` / `mouseReleased` (`buttons: 1` while down). The
@@ -237,6 +238,18 @@ them exactly as on a phone:
   and a restarted `safaridriver`. The page's `localStorage` does not survive
   that, so whatever must be read is read before the swipe.
 
+A fling — the momentum a lifted finger leaves — is out of `safaridriver`'s
+reach for the same reason. The Simulator turns the Mac's mouse into a finger:
+system mouse events (`CGEvent`, a press, moves a frame apart, a release while
+still moving fast) on the Simulator window fling Safari exactly like a thumb,
+its momentum included (over 3 s: flings closer than that add up). The window
+has to be on screen in the current Space: when it is not, activating the
+Simulator does not bring it, and the events land in whatever window is under
+the pointer — check which window is topmost at the points of the drag before
+sending any, and wait for the Space to switch after activating. What the page
+records is read back through a request it sends itself (the page runs on a
+local server), since nothing can query it.
+
 What to synthesize is the hand's imperfection — a gesture simulated as clean,
 evenly spaced points passes forever and proves nothing: a slow start landing a
 report between 6 and 9px, steep first pixels, a report that jumps. What to read:
@@ -244,10 +257,10 @@ the `touchmove`s with `cancelable` and `defaultPrevented`, the `pointercancel`,
 `scrollY`, and what the gesture itself says (for a travel,
 `data-drag-travel-walking` on `:root` and the slide that ends up current).
 
-What neither path shows: the lift of a real finger (the last reports before
-`pointerup`), a real device's event timing (the order in which the browser's
-cancel and the next report reach the page), a momentum tail killed by a landing
-finger. Those remain device questions.
+What these paths do not show: the lift of a real finger (the last reports
+before `pointerup`), a real device's event timing (the order in which the
+browser's cancel and the next report reach the page), a momentum tail killed by
+a landing finger. Those remain device questions.
 
 Reference: `src/layout/demos/lab/slide_container_touch_race.html` — a row of
 slides that do not scroll and a row that do, for the two cases above.

package/docs/scroll.md

@@ -196,8 +196,10 @@ takes the list back to where it was, which may be nowhere near that row.
 `loading` (with `loadingFallback`, `loadingSkeletonCount`, `renderSkeleton`)
 says "I have nothing at all to show yet": placeholder rows stand in for the
 whole list. `<List.Items count>` says "I know how many rows are coming": the
-rows not held yet are skeletons in their own place, asked for as they enter the
-render window — a list that knows its count has no use for the first one.
+rows not held yet are skeletons in their own place, at their own size (see
+[What the list knows, and what it guesses](#what-the-list-knows-and-what-it-guesses)),
+asked for as they enter the render window — a list that knows its count has no
+use for the first one.
 
 Reference: `src/control/list/list.jsx` (JSDoc on `List` and `List.Items`).
 
@@ -362,9 +364,9 @@ room it took — the window sliding changes nothing above the screen. What was
 never drawn it cannot measure, so it guesses:
 
 - the fillers hold every item never drawn at one size — `virtualItemSize` when
-  given, the average of the items measured so far otherwise. A scroll position
-  inside a filler is read with it too, and an item on its way takes at least
-  that room;
+  given, the average of the items measured so far otherwise — unless its run
+  says the room it takes (see below). A scroll position inside a filler is
+  read with it too, and an item on its way takes at least that room;
 - when the window reaches past what it has drawn, it weighs the next items like
   the drawn ones next to them, and measures them once they are drawn.
 
@@ -375,10 +377,35 @@ item guessed **bigger** makes it count too few, and a blank shows until they
 are measured. So a size you give is the **worst case**: in a list whose items
 differ in height, `virtualItemSize` is the smallest an item can be — the
 one-line item, in a thread of one-line items and cards. The scrollbar then
-under-states a list made mostly of big items; the screen stays covered. One
-number for the whole list is the point: a size per kind of item, or per state
-of one, is a model to keep in step with the markup, for a scrollbar a little
-more exact.
+under-states a list made mostly of big items; the screen stays covered.
+
+A guess costs something else when its item is drawn above the screen: the item
+takes its real room, and what is on screen moves by the difference. The list
+puts the screen back by writing the scroll, except where a write would cost the
+user the scroll in progress — and on iOS a fling stops at any write, so during
+a fling every card drawn above the screen pushes it down. A list that knows
+the room of each item before the item arrives says it with `<List.Items
+itemSize>`, and guesses nothing: the fillers hold every item at its own room.
+That is a model to keep in step with the markup (in development, a drawn item
+whose room differs from it is reported), worth it where the items above the
+screen come in a few sizes the data tells apart before it arrives — the
+one-line games and the compact cards of a thread, when the server says which
+past games have a score.
+
+The items on their way are held the same way: a skeleton stands where its item
+will be, at the room it is drawn at, and when the page lands each item takes
+its own room — what is below a skeleton of the wrong size moves by the
+difference. The list puts the screen back while a real item is on it, but a
+fling into a part of the collection not loaded yet leaves a screen of skeletons
+alone, with no item to hold: the screen moves with every skeleton that was
+wrong (hundreds of pixels, in a thread drawing one-line skeletons where compact
+cards land). So `renderSkeleton` draws each index at the room its item will
+take, from what is known before the data — the same knowledge `itemSize` gives
+the fillers. Items that cannot be told apart before they arrive are better
+drawn at one height than announced by skeletons that guess. And anything drawn
+above the screen that changes size afterwards — an image without its
+dimensions, a block that expands — moves the screen the same way, which nothing
+puts back during a fling on iOS: reserve its room.
 
 The window's own guess past what it has drawn is the one that is not the worst
 case, on purpose. Guessing the smallest there walks into cards at the one-line
@@ -457,6 +484,9 @@ Reference: `src/control/demos/19_list_find_in_page_demo.html`.
 
 ### Doing it well
 
+- **Skeletons at the size of their item**, and `itemSize` when the items above
+  the screen come in sizes the data tells apart before it arrives (see
+  [What the list knows, and what it guesses](#what-the-list-knows-and-what-it-guesses)).
 - **A stable `id` on every item.** The run keys its rows on `item.id` — it is
   what addresses a row from outside (`--navi-select`, `scrolled={{ id }}`), and
   what tells a row that moved from a row that changed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/navi",
-  "version": "0.29.442",
+  "version": "0.29.444",
   "type": "module",
   "description": "Library of components including navigation to create frontend applications",
   "repository": {