@jsenv/navi 0.29.228 → 0.29.230

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/scroll.md

@@ -150,6 +150,37 @@ 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. Two things
+are needed for that, and the list warns in dev when the second is missing:
+
+- **a stable `key` on every row**, which is what says a row moved rather than a
+  row changed;
+- **the rows as the list's own children**. The places are read off the children
+  the list is given, so a component of yours rendering the rows is one child
+  however many rows come out of it — they all take the same place and keep the
+  order they first mounted in. Hand the list the rows, or a `<List.Items>`.
+
+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.228",
+  "version": "0.29.230",
   "type": "module",
   "description": "Library of components including navigation to create frontend applications",
   "repository": {