@jsenv/navi 0.29.227 → 0.29.229

package/docs/AI_INSTRUCTIONS.md

@@ -198,8 +198,9 @@ to start when unsure which export solves a problem.
   (`--navi-app-max-width`), `data-navi-safe-area`, which viewport is which under
   a virtual keyboard. Read before hand-writing an offset to clear a `FixedBar`.
 - `scroll.md` — where scrolling happens: `header`/`body`/`footer`, `List`'s
-  `scroller`, a popup that scrolls, hover while scrolling. Read before writing
-  CSS to make something scroll.
+  `scroller`, where a list opens and what a search does to where it is, a popup
+  that scrolls, hover while scrolling. Read before writing CSS to make something
+  scroll.
 - `mobile_layout_pitfalls.md` — a horizontal overflow inflates the layout
   viewport on Chrome Android and miscenters every dialog; `overflow-x: clip`.
 - `z_index.md` — DOM order first; a `z-index` without `isolation: isolate`

package/docs/data_states.md

@@ -73,6 +73,13 @@ means something different:
 
 Two consequences worth stating out loud.
 
+**A first load is only a first load when nothing is known.** A resource `GET`
+whose params name a row the store already holds — read earlier by a `GET_MANY`,
+a relation, a list — starts on the second line, not the first: the row is drawn
+and the request goes out behind it. The response replaces it, and a failure
+lands beside it like any refresh failure. A `GET` of a row the store lacks
+still starts on the first line, so what is drawn is never a different row.
+
 **The emptiness test is `data === undefined`, never `loading`.** Reading
 `loading` as "there is nothing to display" blanks the screen on every refresh —
 for a checkbox ticked on one row of a list, the whole list goes.

package/docs/scroll.md

@@ -150,6 +150,31 @@ picked up then. When it is still not the box you mean, say so explicitly with
   changes, even after the user scrolled.
 - **`onScrolledChange`** gives `{id, index, offset}` as the user scrolls.
 
+### A search moves the list, and gives it back
+
+A list that is being searched has to move: the rows the user is after have just
+been promoted to the top, and a view left where it was shows none of them. What
+makes that possible is `searchText` on the `List` — without it the list sees new
+children and nothing else.
+
+- **While the search is on**, the list scrolls back to its first row every time
+  the best matches change. "Best matches" is the top `renderBudget` rows, taken
+  by id and by `matchInfo.matchScore`, so a letter that promotes nobody new
+  leaves the list where the user put it.
+- **When the search is emptied**, the list returns to the offset it was at when
+  the search started, render window included. It goes back by offset, not by
+  row: the collection is the one from before again, in the order it was in.
+
+Both rest on each row knowing where it stands, which for rows declared one by
+one is the order they are written in — `useSearchText` hands the collection back
+reordered, the caller renders it in that order, and the places follow. Give every
+row a stable `key`: the places are read off the children as they are declared,
+and the key is what says a row moved rather than a row changed.
+
+One case is knowingly left out: a row selected during the search does not hold
+the view. Emptying the search takes the list back to where it was, which may be
+nowhere near the row just chosen.
+
 ### Sticky rows inside the list
 
 `<List.Item header>` / `<List.Item footer>` are sticky rows inside the list.

package/package.json

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