@jsenv/navi 0.29.447 → 0.29.449

package/docs/AI_INSTRUCTIONS.md

@@ -83,7 +83,8 @@ start when unsure which export solves a problem.
   running (`{ run: true }` is the fallback), `action` versus `uiAction`, an
   action and a command on one press. Before running an action from a component.
 - `resource.md` — `resource()` and its relations (never an `op` discriminator),
-  `GET_RANGE`, a search as the same `GET_MANY`, `withParams()` scopes and
+  `GET_RANGE` (its inclusive `end`, the count for the screen around the list, a
+  question following a search field), a search as the same `GET_MANY`, `withParams()` scopes and
   `dependencies`, `persist` (and `keepPageOnScreen` for the page on screen), a
   function versus the verb's instance. Before writing a resource, and before
   caching a response yourself.

package/docs/resource.md

@@ -269,13 +269,20 @@ const GAME = resource("game", {
 
 The callback receives the bound params merged with the range the list asks for
 (`start`, `end`, `limit`, `before`, `after`, `around`), and `{ signal }`,
-aborted when the list stops wanting those rows. It returns 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 one at or after
-`0` (a negative `start` counts back from the end, and the source must then say
-where the slice landed); `count` defaults to `start + items.length`. The items
-are upserted on their way in, so the list draws store items, never copies of the
-JSON.
+aborted when the list stops wanting those rows. `end` is the last place asked
+for, included, as in `Range: items=0-99`: `limit` is `end - start + 1`, and an
+API whose end is excluded is called with `start + limit`. It returns 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 one at
+or after `0` (a negative `start` counts back from the end, and the source must
+then say where the slice landed); `count` defaults to `start + items.length`.
+The items are upserted on their way in, so the list draws store items, never
+copies of the JSON.
+
+The count is also what the screen around the list says — "5 of 83 books". The
+run hands it out with `onCountChange`: `undefined` until a slice has answered,
+then each count a slice brings, and again for each collection the run draws, so
+the number always belongs to the rows on screen.
 
 But the list keeps the object it was handed, and an update replaces the item
 object (the store holds values, which is what makes a change detectable). So a
@@ -304,6 +311,30 @@ rows staying on screen
 reads a collection, so it lives on the resource (or on a `withParams()` of it),
 not on a relation.
 
+### A question that follows a search field
+
+A reader bound to other params is another collection, and the run draws it
+from its first item — it needs no `key` for that. A param following what is
+typed then makes one collection per key, and one request each, the server
+receiving every one even when the list calls it off. `debounce` on the run
+waits for the reader to hold still, and keeps the collection from before drawn
+meanwhile, `refreshing`:
+
+```jsx
+<List.Items
+  itemsAction={BOOK.GET_RANGE.bindParams({ q: searchSignal.value })}
+  debounce={300}
+  onCountChange={(count) => {
+    bookCountSignal.value = count;
+  }}
+  renderItem={renderBook}
+/>
+```
+
+A `key` that follows the field defeats it: the run remounts at each key, and
+its wait with it. Demo: `src/control/demos/integration/1_list_loaded_by_scroll_demo.html`
+("Une recherche qui suit la frappe").
+
 ## Searching the same collection
 
 A screen showing a collection soon asks a second question about it: the list

package/docs/scroll.md

@@ -536,10 +536,14 @@ whatever `loading` says afterwards.
   item and the index it is given rather than closing over state.
 
 The rest — `virtualItemSize`, the room an item not drawn is held at (uniform
-items, or the smallest one of a mixed list — the worst case, see above), a `key`
-on the run when the collection changes as a whole (never to refresh it, see
+items, or the smallest one of a mixed list — the worst case, see above), a
+collection that changes as a whole (another array, another reader — drawn from
+its first item; never a `key` to refresh it, see
 [list_refresh.md](./list_refresh.md#a-paginated-list-stays-on-screen-too)),
-`groupBy` for sections — is in the JSDoc of `List` and `List.Items`
+`debounce` for a question following a search field
+([resource.md](./resource.md#a-question-that-follows-a-search-field)),
+`onCountChange` for the screen around the list to say how many items there
+are, `groupBy` for sections — is in the JSDoc of `List` and `List.Items`
 (`src/control/list/list.jsx`). Demos:
 `src/control/demos/17_virtual_scroll_and_filter_demo.html` (a run in memory,
 searched), `src/control/demos/integration/1_list_loaded_by_scroll_demo.html` (a

package/package.json

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