@jsenv/navi 0.29.27 → 0.29.29

package/docs/AI_INSTRUCTIONS.md

@@ -47,6 +47,15 @@ consistency across the app, not from any single call site.
 - `docs/z_index.md` — stacking: why DOM order is the first tool, what a
   `z-index` without `isolation: isolate` actually competes against, and the
   values navi's own popups/bars/tables use. Read it before writing a `z-index`.
+- `docs/i18n.md` — where the texts an app displays live: `interpolateText` /
+  `<Interpolate>` for one sentence, `createI18n` for the app's registry,
+  `naviI18n` for navi's own texts. Read it before writing a user-visible
+  sentence, and before overriding a navi message.
+- `docs/interactions.md` — the `interactions` prop: making a component answer a
+  swipe, a held press, a shortcut, and registering a gesture navi does not have.
+  Read it before reading the pointer by hand — who owns a press between nested
+  boxes, and what a touch may do, are decided before the first pixel moves and
+  cannot be got right from outside navi.
 - `docs/MOBILE_LAYOUT_PITFALLS.md` — mobile-specific layout gotchas (viewport
   units, virtual keyboard, safe areas).
 - `docs/navigation.md` — how to build navigation: declaring routes
@@ -80,6 +89,15 @@ consistency across the app, not from any single call site.
 - **Field components** (`Input`, `Select`, `Checkbox`, etc.) take an `action`
   prop to respond to interaction — this is the standard wiring, not
   `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
+  — see `docs/interactions.md`.
+- **Texts**: a user-visible sentence containing a value is written as one
+  template with `[placeholder]`s (`interpolateText` / `<Interpolate>`), not cut
+  into JSX fragments or concatenations. Beyond a handful of texts, an app
+  declares them in its own `createI18n()` instance — using the English text
+  itself as the key, whereas navi's `naviI18n` uses opaque keys. Application
+  texts never go into `naviI18n`. See `docs/i18n.md`.
 - **View transitions**: navi components animate their own changes
   (`itemTransition` on `List`, `RouteTravel` for routes) and never decide for
   the whole document. Two things are the application's call, not navi's:

package/docs/i18n.md

@@ -0,0 +1,183 @@
+# Texts and i18n
+
+Every text an app displays is a value it owns, like any other. The goal here is
+that those values live somewhere findable and are written as whole sentences —
+not cut into JSX fragments, not concatenated at the call site, not scattered so
+widely that changing the tone of the app means grepping for punctuation.
+
+Translation is a consequence of doing that, not the reason to do it. An app with
+one language still benefits from one place holding its wording; and once it does,
+adding a second language becomes a data change instead of a refactor.
+
+Three tools, from smallest commitment to largest:
+
+| Tool                    | Gives you                                |
+| ----------------------- | ---------------------------------------- |
+| `interpolateText(t, v)` | one readable sentence with values in it  |
+| `<Interpolate>`         | the same, with JSX allowed in the values |
+| `createI18n()`          | a registry of the app's texts            |
+| `naviI18n`              | navi's own texts, to override            |
+
+## Writing a sentence: `interpolateText` / `<Interpolate>`
+
+Use these the moment a sentence contains a value. They need no i18n instance and
+no setup, so there is no reason to avoid them in a single-language app.
+
+```js
+import { interpolateText } from "@jsenv/navi";
+
+interpolateText("Deleting [name]…", { name: file.name });
+```
+
+In JSX, `<Interpolate>` keeps the sentence readable when part of it is styled:
+
+```jsx
+<Interpolate radiusKm={<Text bold>{radius} km</Text>} zoneName={zone}>
+  Data limited to [radiusKm] around [zoneName].
+</Interpolate>
+```
+
+The point is that the full sentence is visible in one place. The alternative —
+`Data limited to <Text bold>{radius} km</Text> around {zone}.` — reads as
+fragments, and cannot later become a translation key, because there is no
+single string to be the key.
+
+Placeholders are `[name]`. The delimiter is `[]` rather than `{}`/`{{}}` because
+it collides with neither JSX nor template literals nor ordinary punctuation.
+Details worth knowing (all in `interpolateText`'s JSDoc): a value can be a
+dot-path (`[item.label]`), a function (called only if the placeholder is
+present), and a placeholder with no value is left visible as `[name]` rather
+than disappearing.
+
+## Centralizing texts: `createI18n`
+
+Once several components display text, give the app a registry. One instance for
+the whole app, exported from one module:
+
+```js
+// src/app_i18n.js
+import { createI18n } from "@jsenv/navi";
+
+export const i18n = createI18n({ keyLang: "en" });
+```
+
+Then call it wherever a text is needed. It is callable directly:
+
+```js
+import { i18n } from "@/app_i18n.js";
+
+i18n("Deleting [name]…", { name: file.name });
+```
+
+### In an app, the text is the key
+
+`keyLang: "en"` means "keys are already written in English". The key doubles as
+its own English template, so a single-language app registers nothing at all and
+still gets readable output, and adding French later touches only the registry:
+
+```js
+i18n.add("Deleting [name]…", { fr: "Suppression de [name]…" });
+```
+
+This is the recommended style for applications, because it keeps the call site
+readable. `i18n("Deleting [name]…")` says what appears on screen;
+`i18n("file.delete.progress")` requires a lookup to know. The cost — changing
+the English wording changes the key, so its translations must be updated
+alongside — is the smaller problem in practice, and it is a mechanical one.
+
+### In navi, the key is opaque
+
+`naviI18n` uses opaque keys (`"list.empty"`, `"constraint.required.email"`)
+because a library's texts are addressed from the outside: an app overriding a
+message needs a stable name that does not move when navi rewords its default
+English. Same reasoning applies to any shared component library — the trade-off
+flips with who owns the text.
+
+Without `keyLang`, every language is explicit, English included:
+
+```js
+const i18n = createI18n();
+i18n.add("greeting", { en: "Hello [name]!", fr: "Bonjour [name] !" });
+```
+
+### Registering
+
+Three ways in, all accumulative — re-registering a key replaces that one key and
+leaves the rest alone:
+
+```js
+i18n.add("Save", { fr: "Enregistrer" }); // one key, many languages
+i18n.addAll({ Save: { fr: "Enregistrer" }, Cancel: { fr: "Annuler" } });
+i18n.addLangKeys("fr", frenchPack); // a whole language, e.g. a fetched JSON file
+```
+
+A regional variant inherits from its parent for every key it does not override,
+resolved at registration time — so register `"fr"` before `"fr-CA"`.
+
+### What comes out
+
+`i18n(key, values, { lang })` returns the translation with placeholders
+replaced. When nothing matches it returns the key itself, so a missing
+translation degrades to readable text rather than blank space or a crash. Pass
+`fallbackLang` at creation to fall through to another language first, per key —
+a half-translated language stays usable.
+
+`i18n.has(key)` is the way to tell "no translation" apart from "translation that
+happens to equal the key".
+
+## Which language
+
+Nothing needs configuring for navi and app texts to agree on a language: both
+default to `languagesSignal`, which is read live on every lookup — the browser's
+`navigator.languages`, plus two app-level overrides.
+
+```js
+import { setSupportedLanguages, setPreferredLanguage } from "@jsenv/navi";
+
+setSupportedLanguages(["en", "fr"]); // what the app offers, at startup
+setPreferredLanguage("fr"); // what this user picked, from a language picker
+```
+
+`setSupportedLanguages` matters more than it looks: without it, a browser
+preferring German resolves to German, and every key missing in German falls back
+to its key. With it, that browser lands on the app's best available language
+instead.
+
+Because the language is read at lookup time, a component that reads `i18n(...)`
+during render re-renders with the new wording when the language changes — as
+long as the call happens in render, not in a value captured once outside it.
+
+## Changing what navi says
+
+`naviI18n` holds navi's own texts. Register on it to override a default or to
+add a language navi does not ship:
+
+```js
+import { naviI18n } from "@jsenv/navi";
+
+naviI18n.add("list.empty", {
+  en: "Nothing here yet.",
+  fr: "Rien pour l'instant.",
+});
+naviI18n.addLangKeys("ja", { "button.close": "閉じる" });
+```
+
+Its JSDoc lists the key namespaces; the exhaustive list of keys and defaults is
+the registration block in `src/text/navi_i18n.js`, which is meant to be read.
+
+Do not put application texts in `naviI18n`. Key collisions aside, the two have
+different lifecycles: navi's keys come with the package version, the app's come
+with the app.
+
+One convention to know, since it is what `<Quantity>`/`<Unit>` look up: a unit
+name may have `<unit>__plural` and `<unit>__short` variants, both optional
+(missing ones fall back to the singular). An unregistered unit goes to
+`Intl.NumberFormat`, so only units Intl gets wrong or does not know need
+registering at all.
+
+## Choosing, in one line
+
+Reach for `interpolateText`/`<Interpolate>` as soon as a sentence has a value in
+it. Reach for `createI18n` as soon as more than a handful of texts exist — the
+migration from the first to the second is wrapping the string in a call, which
+is why starting with plain interpolation costs nothing.

package/docs/interactions.md

@@ -0,0 +1,375 @@
+# `interactions` — a component that answers more than a click
+
+## What we want
+
+An element should be able to answer a gesture — a row swiped aside to archive it,
+a card held down to open a menu, a shortcut that sends a form — and the person
+writing that element should only have to **name** the gesture and say what it
+does.
+
+Everything hard about a gesture is not the detection. It is the four things
+around it:
+
+- **who owns the press** when boxes are nested (a row swiped sideways inside a
+  container that travels sideways);
+- **which of several gestures a single press turns out to be** (a swipe, a hold, a
+  click — one press, one arbiter);
+- **the click the browser fires afterwards**, which would follow the link the
+  gesture started from;
+- **whether the element is allowed to be interacted with at all** (disabled,
+  read-only, waiting on something).
+
+navi owns those four. An application that reads the pointer itself gets two of
+them wrong by construction, because two of them can only be decided from inside
+navi and before the first pixel moves.
+
+## The prop
+
+`interactions` is a prop of `Box`, so it is available on anything built from
+one — `Box`, `List.Item`, `Button`, `Link`, the field components. Its keys are
+**event types**, its values say what that interaction does.
+
+```jsx
+<Box
+  interactions={{
+    "swipe_right": "request_action",
+    "swipe_left": (event) => markUnread(event),
+    "longpress": (event) => openMenu(event),
+    "keyboard:ctrl+backspace": "request_action",
+  }}
+/>
+```
+
+`action` is untouched by this and keeps its own wiring — a click on a button, a
+change on a field. `interactions` is the other half: everything that is not that
+natural one.
+
+### The three values
+
+| Value                 | Meaning                                              |
+| --------------------- | ---------------------------------------------------- |
+| `"request_action"`    | ask the nearest control for its `action` prop        |
+| `"request_ui_action"` | ask it for a ui action (what says "the user acted")  |
+| a function            | do this, with the interaction event as only argument |
+
+A falsy value means "not this one", so an interaction can be declared under a
+condition: `{ swipe_right: canArchive && archive }`.
+
+### The interactions navi detects
+
+| Key                                                    | Read from                                      |
+| ------------------------------------------------------ | ---------------------------------------------- |
+| `mousedown` `mouseup` `click` `dblclick` `contextmenu` | the browser's own events                       |
+| `swipe_left` `swipe_right` `swipe_up` `swipe_down`     | a press that travels                           |
+| `longpress`                                            | a press held still                             |
+| `move` `reorder` `toss`                                | the element carried, and what letting go means |
+| `"keyboard:<shortcut>"`                                | keys, e.g. `"keyboard:ctrl+backspace"`         |
+
+A name nothing knows how to detect produces a dev warning naming the detectors
+that exist.
+
+## Which interaction asked
+
+An interaction navi makes is **dispatched as an event of its own name** —
+bubbling, cancelable, chained onto the event it was read from. So an action does
+not need to be told which interaction asked for it: it reads the event it already
+receives.
+
+```jsx
+<Button
+  action={(value, { event }) => {
+    const swipe = findEvent(event, "swipe_right");
+    if (swipe) {
+      const { axis, sign, pulled, size, progress } = swipe.detail;
+    }
+  }}
+  interactions={{ swipe_right: "request_action" }}
+/>
+```
+
+`findEvent` is exported from `@jsenv/navi`. Because these are real events, an
+ancestor can also listen for one, and `preventDefault()` on it means "not this
+time".
+
+The lower-level event the interaction was read from is reachable too:
+`interactionEvent.detail.event` is the `pointerdown` a swipe or a hold was made
+of — which is how a menu is opened at the point the press happened.
+
+## Reaching the control
+
+Everything goes through the interaction gate of the **nearest control** — itself,
+an ancestor, or a descendant, in that order. So a disabled, read-only or busy
+control answers a swipe the way it answers a click: it says why, where the
+interaction happened, and nothing runs. A `Box` with no control anywhere near it
+still answers a callback; only `"request_action"` has nothing to ask, and says so
+in dev.
+
+## What a swipe draws, and what it leaves to you
+
+navi makes the element follow the finger — there is nothing to decide about
+that — and says where the gesture is up to:
+
+| Written on the element                   | Meaning                                   |
+| ---------------------------------------- | ----------------------------------------- |
+| `--swipe-pulled`                         | how far it has come, signed, in px        |
+| `--swipe-progress`                       | the same as a fraction, signed, inherited |
+| `[data-swiping="left\|right\|up\|down"]` | which way, while a finger holds it        |
+| `[data-swipe-past-threshold]`            | letting go now would go through with it   |
+
+WHAT is revealed behind is yours: navi does not know what putting a row away
+looks like. A trail is usually a child of the swiped element sized off
+`--swipe-pulled` — which is what makes those values reachable from CSS at all, a
+sibling could not read them.
+
+```css
+.trail {
+  position: absolute;
+  top: 0;
+  right: 100%; /* the strip the row just left */
+  bottom: 0;
+  width: var(--swipe-pulled);
+  opacity: calc(var(--swipe-progress) * 3);
+}
+[data-swipe-past-threshold] .trail {
+  background: var(--ok-color);
+}
+```
+
+While the answer takes time, the element **stays where the gesture left it**, and
+comes back once it settles — a failure leaves the row in place so it can be tried
+again. What a success does to the element is yours (a list that redemands its
+rows, a row that leaves): navi does not make it disappear.
+
+## Carrying something: `move`, `reorder`, `toss`
+
+All three are the same gesture — the element is picked up and carried — and what
+differs is the release. One detector reads them all, because it is one press.
+
+`reorder` and `toss` **combine**: dropped on another item the element changes
+places, thrown far and fast it is gotten rid of. `move` does **not** combine with
+`reorder` — an element either goes where it is put or takes a place in a list,
+and one release cannot mean both (a dev warning says so).
+
+`move` carries the element ITSELF and leaves it where it was put; the other two
+carry a copy and put the original back. That is the same difference said in layout
+terms: something moved has a new place of its own, something reordered had its
+place taken by the list.
+
+```jsx
+<Box
+  id={token.id}
+  interactions={{
+    move: (event) => remember(event.detail.x, event.detail.y),
+  }}
+/>
+```
+
+`data-drag-free` on the element or a container lets it leave; by default a `move`
+stays inside what one can SEE of its container — which requires that container to
+be a scroll container at all (`overflow` anything but `visible`), since there is
+nothing else for "inside" to mean. A `move` whose answer rejects travels back, because a
+place the application would not accept must not stay on screen as if it had.
+
+**Declaring `toss` frees the area by itself.** What is dragged is otherwise kept
+inside its scroll area — right for a reorder, since a row belongs to its list, and
+fatal for a throw: the copy hits the edge of the list, no distance is ever covered,
+so no throw can happen and no sideways movement is even visible. So the two
+together let it leave.
+
+```jsx
+<List.Item
+  id={task.id}
+  data-view-transition-name={`task_${task.id}`}
+  interactions={{
+    reorder: (event) => {
+      const { fromId, toId, syncCloneWithDropTarget } = event.detail;
+      return document.startViewTransition(() => {
+        syncCloneWithDropTarget();
+        setOrder(moveBefore(order, fromId, toId));
+      }).finished;
+    },
+    toss: (event) => remove(event.detail.id),
+  }}
+/>
+```
+
+The gesture is `startDragTo`'s, whole: `move` carries the element itself, the
+other two carry a copy above the page while the original keeps its place, with a
+drop hint, drop targets found by intersection, no-op drops filtered out, and the
+flight of a thrown copy plus its return when the answer refuses. Only what the
+declared outcomes need runs — no copy for a move, no hint for something
+that can only be thrown away.
+
+Every element declaring `reorder` marks itself, so the set of items IS the set of
+elements that declared it — no selector to pass, and an item that must not move
+simply does not declare it. An element declaring only `toss` marks nothing: it is
+not a place anything lands. Items are named by their `id`.
+
+`toId` is null for a drop at the end. `syncCloneWithDropTarget` must be called
+synchronously inside the transition callback, next to the state change, so the copy
+is captured where it lands rather than where it was let go of.
+
+**The promise matters in both cases**: the gesture holds its copy until the answer
+settles. Returning the transition is what makes a landing continuous; a `toss` that
+rejects brings the copy back, because the thing still exists and the screen has to
+say so.
+
+A throw is asked about before a landing: a hand that sent something across the
+screen has not asked for it to swap places with whatever it flew over.
+
+Starting a document transition is the application's call, not navi's: a
+`view-transition-name` must be unique per document, so only the application can
+name what moves.
+
+| Attribute                                                | Meaning                                |
+| -------------------------------------------------------- | -------------------------------------- |
+| `data-drag-axis="x"\|"y"\|"xy"`                          | which axes the drag walks              |
+| `data-drag-delay` `data-drag-slop` `data-drag-threshold` | when the press becomes a grab          |
+| `data-toss-distance` `data-toss-speed`                   | how far and how fast counts as a throw |
+
+### Dressing the clone
+
+What the pointer carries is a copy, and a copy of a transparent element is
+invisible — an element has no background unless something gave it one, and a row
+usually gets its own from the list around it, which the copy has left. So the
+clone's look is the page's to declare, through the attributes the gesture puts on
+it:
+
+| Attribute                 | On                                                     |
+| ------------------------- | ------------------------------------------------------ |
+| `navi-drag-clone`         | the copy being carried                                 |
+| `navi-drag-clone-wrapper` | what positions it (already shadowed, in the top layer) |
+| `navi-drag-clone-source`  | the original, still in place (already hidden)          |
+
+```css
+.task[navi-drag-clone] {
+  background: white;
+  border-radius: 6px;
+}
+```
+
+Reusing the item's own class is the point: the copy is that item, so it is styled
+as that item plus whatever being carried changes.
+
+`data-drag-axis` says which axes the drag walks, and its default is not the same
+for every outcome: `reorder` alone walks the list (`y`, or `x` for a list that runs
+sideways), while a `move` goes wherever it is put and a `toss` wherever it was
+thrown (`xy`). `data-drag-delay`, `data-drag-slop`, `data-drag-threshold` tune when
+the press becomes a grab.
+
+## Tuning
+
+Read off the element or any ancestor carrying the attribute, so a whole list is
+tuned in one place and a stylesheet can read the same value.
+
+| Attribute              | Default | Meaning                                   |
+| ---------------------- | ------- | ----------------------------------------- |
+| `data-swipe-threshold` | `0.33`  | fraction of the element to pull to commit |
+| `data-longpress-delay` | `450`   | ms the press must be held                 |
+| `data-longpress-slop`  | `8`     | px the pointer may drift during the wait  |
+
+A threshold is a **fraction and never a distance**: the same gesture must mean
+the same thing on a phone and on a wide screen. Speed answers on its own on top
+of it — a brief flick counts whatever the distance covered.
+
+## Registering an interaction navi does not have
+
+The registry holds no detector of its own: navi's swipes, holds and shortcuts go
+through the same door an application uses.
+
+```js
+import { defineInteractionDetector } from "@jsenv/navi";
+
+defineInteractionDetector({
+  name: "triple_click",
+  claims: (type) => type === "triple_click",
+  setup: (element, trigger) => {
+    let count = 0;
+    let timeout = null;
+    const onClick = (clickEvent) => {
+      count++;
+      clearTimeout(timeout);
+      timeout = setTimeout(() => {
+        count = 0;
+      }, 1000);
+      if (count < 3) {
+        return;
+      }
+      count = 0;
+      trigger(clickEvent);
+    };
+    element.addEventListener("click", onClick);
+    return () => {
+      clearTimeout(timeout);
+      element.removeEventListener("click", onClick);
+    };
+  },
+});
+```
+
+`setup(element, trigger, { types, readConfig })` runs **once per element** and
+returns how to undo whatever it did. Listeners, attributes, anything: it is a
+plain setup and teardown, so a detector counts what it needs in its own closure
+and nothing has to hold state on its behalf.
+
+`claims` takes a **set** of names rather than one, because interactions sharing an
+input have to be arbitrated together — a swipe, a hold and a click dispute the
+same press, and read apart they walk over each other. `types` (third argument) is
+which of them were actually declared here.
+
+`trigger(type, originalEvent, detail)` says the interaction happened. Called with
+a single event — `trigger(event)` — the type is the detector's own, which only
+works when exactly one of its names is declared. When `originalEvent.type` is
+already the interaction's name (a native one), that event IS the interaction and
+no second one is dispatched.
+
+It returns **`null` when nothing ran** (the gate refused, no control to ask, the
+interaction event was prevented) and otherwise a **promise**: resolved once the
+effect worked, rejected when it did not. Those two answers are not the same and a
+detector usually treats them differently — a row pulled out comes back either
+way, something thrown off the screen only comes back if the throw failed.
+
+`readConfig(attribute, defaultValue)` reads a number off the element or any
+ancestor carrying that attribute, so a whole list is tuned in one place.
+
+A detector that reads the pointer must mark itself in the DOM so a travelling
+container above it does not take the gesture:
+`element.setAttribute("data-no-drag-travel", "")`, undone in the teardown (see
+`docs/drag_to_travel.md`). navi's own swipes do the equivalent with
+`data-travel-by-drag`.
+
+## Things worth knowing before guessing
+
+- **A hold does not take the context menu.** Declaring `longpress` says what a
+  held finger does; a right click comes from the other button and keeps opening
+  the browser's menu. Declare `contextmenu` beside it to make the right click do
+  the same thing. (A held _finger_ is the system's own context-menu gesture, and
+  that one is refused while the wait runs.)
+- **A swipe cannot also be dragged out of the page.** An element declaring a
+  swipe gets `draggable={false}` and its `dragstart` refused — a native drag _is_
+  press-and-move, and a link or an image is draggable without anyone asking. One
+  gesture cannot mean both.
+- **`interactions` adds, it does not replace.** A control's own wiring stays:
+  `actionEvent` / `actionOnMouseDown` are still how you change what triggers
+  `action` by default.
+- **A popup can open while the finger is still down.** navi's `Popover` is
+  `popover="manual"` and owns its dismissal, so the `pointerup` ending a hold is
+  not read as an interaction outside it — a menu can appear under a waiting
+  finger, which is the native gesture. To place it at the press point rather than
+  on the element:
+  `triggerNaviCommand(target, "--navi-open", interactionEvent, { anchor })`.
+- **A swipe has no keyboard equivalent.** There is nothing to press that means
+  "swipe right", so a swipe is only reachable if something else on the element
+  offers the same thing — a `"keyboard:<shortcut>"`, a `contextmenu`, or the
+  control's own action.
+
+## Reference
+
+- `src/control/interaction/interaction_registry.js` — the prop, the three values,
+  the registry.
+- `src/control/interaction/interaction_press.js` — swipes and holds, and what a
+  swipe writes on the element.
+- `src/control/interaction/interaction_keyboard.js`,
+  `interaction_native.js` — the other two detectors.
+- `src/control/demos/38_interactions_demo.html` — every case above, plus a
+  mailbox and a custom `swipe_out` gesture registered from the page.

package/docs/resource.md

@@ -25,7 +25,7 @@ Each callback returns the data to upsert into the store:
 | GET / POST / PUT / PATCH | the full item object, `{ id, … }` |
 | DELETE                   | the id, or `{ id }`               |
 | GET_MANY / POST_MANY / … | an array of item objects          |
-| GET_PAGE                 | `{ items, start, count }` (below) |
+| GET_RANGE                | `{ items, start, count }` (below) |
 
 Actions are read in components through the action system (`useAsyncData`,
 `<Button action>`, …) — see [actions.md](./actions.md).
@@ -48,18 +48,18 @@ it yourself is the point:
   else to land (see [When the backend answers a sub-route with the whole
   parent](#when-the-backend-answers-a-sub-route-with-the-whole-parent)).
 
-A list that loads its rows page by page is **not** one of those cases — that is
-`GET_PAGE`, right below.
+A list that loads its rows a slice at a time is **not** one of those cases — that is
+`GET_RANGE`, right below.
 
-## `GET_PAGE`: feeding a list that loads as it scrolls
+## `GET_RANGE`: feeding a list that loads as it scrolls
 
 A `<List.Items>` asks for the rows it is about to draw and keeps what it gets.
-`GET_PAGE` is the resource's answer to that question — one slice at a time:
+`GET_RANGE` is the resource's answer to that question — one slice at a time:
 
 ```js
 const GAME = resource("game", {
   GET: ({ id }) => fetchJson(`/games/${id}`),
-  GET_PAGE: ({ radar, start, limit }) =>
+  GET_RANGE: ({ radar, start, limit }) =>
     fetchJson(`/radars/${radar.id}/games?start=${start}&limit=${limit}`),
   // { items: [{ id, … }, …], start: 20, count: 137 }
 });
@@ -68,7 +68,7 @@ const GAME = resource("game", {
 ```jsx
 <List.Items
   count={radar.match_count}
-  itemsAction={GAME.GET_PAGE.bindParams({ radar })}
+  itemsAction={GAME.GET_RANGE.bindParams({ radar })}
   renderItem={(game) => <GameCard game={game} />}
 />
 ```
@@ -76,7 +76,7 @@ const GAME = resource("game", {
 The callback receives the bound params merged with the range the list asks for
 (`start`, `end`, `limit`, `before`, `after`, `around`, `count`), and a `signal`
 as second argument — aborted when the list stops wanting those rows. It returns
-a page the way a `Content-Range` does: **`{ items, start, count }`** — these
+a range the way a `Content-Range` does: **`{ items, start, count }`** — these
 rows, at this place, out of that many. `start` may be omitted when the list
 asked for a positive one; `count` defaults to `start + items.length` (a source
 that does not know its total). The items are upserted on their way in, so the
@@ -98,12 +98,12 @@ makes a change detectable), so the one the list is holding is the one it was
 given. Relations are not concerned: they are keyed by owner, and a row reading
 `game.candidates` reads the shared collection whatever object carries it.
 
-`GET_PAGE` is a **reader, not an action**. It keeps no value and takes no place
+`GET_RANGE` is a **reader, not an action**. It keeps no value and takes no place
 in the rerun graph, which is what makes it usable per slice:
 
-- the list already holds the pages it received and glues them back together —
+- the list already holds the slices it received and glues them back together —
   a second memory holding one of them would fight it;
-- a `POST` invalidating "the collection" would otherwise send every page ever
+- a `POST` invalidating "the collection" would otherwise send every slice ever
   loaded back to the network at once.
 
 What it does not give is membership: an item that leaves the collection stays on

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/navi",
-  "version": "0.29.27",
+  "version": "0.29.29",
   "type": "module",
   "description": "Library of components including navigation to create frontend applications",
   "repository": {
@@ -29,7 +29,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@jsenv/dom": "0.17.9",
+    "@jsenv/dom": "0.17.10",
     "@jsenv/humanize": "1.7.8",
     "@jsenv/validity": "0.4.2"
   },
@@ -41,8 +41,8 @@
     "@jsenv/snapshot": "../../tooling/snapshot",
     "@jsenv/terminal-table": "../../tooling/terminal-table",
     "@jsenv/urls": "../../tooling/urls",
-    "@preact/signals": "2.9.4",
-    "playwright": "1.61.1",
+    "@preact/signals": "2.11.1",
+    "playwright": "1.62.1",
     "preact": "11.0.0-beta.2"
   },
   "publishConfig": {