@jsenv/navi 0.29.406 → 0.29.408

package/docs/AI_INSTRUCTIONS.md

@@ -232,14 +232,15 @@ to start when unsure which export solves a problem.
   `:nth-child`, `:empty`) on a container holding navi components.
 - `safe_area.md` — the two inset families, an app narrower than the window
   (`--navi-app-max-width`), `data-navi-safe-area`, which viewport is which under
-  a virtual keyboard (overlaid on Chromium by default:
-  `--navi-keyboard-inset-bottom`). Read before hand-writing an offset to clear a `FixedBar`.
+  a virtual keyboard (overlaid on Chromium only with
+  `enableVirtualKeyboardOverlay()`: `--navi-keyboard-inset-bottom`). Read before hand-writing an offset to clear a `FixedBar`.
 - `scroll.md` — where scrolling happens: `header`/`body`/`footer`, `List`'s
   `scroller`, where a list opens and what a search does to where it is, a popup
   that scrolls, hover while scrolling; many rows: `<List.Items>` and the render
   window (`renderBudget`, its `{ initial, after }` form for a list opening in
-  a click, `virtualItemSize`). Read before writing CSS to make something
-  scroll, and before rendering a collection as `<List.Item>` children.
+  a click, `virtualItemSize`, `findText` for Cmd/Ctrl + F beyond the window).
+  Read before writing CSS to make something scroll, and before rendering a
+  collection as `<List.Item>` children.
 - `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/control_value.md

@@ -195,12 +195,13 @@ That is what the `:smooth` argument asks for:
   one whose first step would be — is not travelled to at all: the same message
   the chevron that way gives, said on the spin, and the value is left alone.
 - **A gesture on the control itself is never fought.** A wheel being dragged
-  or flung keeps reporting its own rows; the requested value is where it goes
-  once the finger's movement is over. A value a wheel merely caught up with is
-  not a choice either: arriving on it fires no settle, no `action` — those
-  belong to the user's own inputs. A spin is the other way round, and for the
-  same reason: the travel IS the answer being given, so landing tells
-  `uiAction` about it, with the press that asked for it.
+  or flung holds the rows it crosses without making them its value; the row it
+  comes to rest on is the value, and overrules one requested meanwhile. A
+  value a wheel merely caught up with is not a choice either: arriving on it
+  fires no settle, no `action` — those belong to the user's own inputs. A spin
+  is the other way round, and for the same reason: the travel IS the answer
+  being given, so landing tells `uiAction` about it, with the press that asked
+  for it.
 - **`prefers-reduced-motion` keeps the instant swap.** The option describes
   how the change is shown, and whoever asked to see less motion is answered
   first.

package/docs/safe_area.md

@@ -200,12 +200,12 @@ the keyboard moves depends on the browser.
 | `visualViewport.height`          | yes, except where the keyboard overlays (below) |
 | `--navi-vvh` (tracks the visual) | same as `visualViewport.height`                 |
 
-Wherever the browser has the VirtualKeyboard API (Chromium), navi makes the
-keyboard overlay the page rather than shrink it (`src/layout/virtual_keyboard.js`):
-no viewport shrinks, and the keyboard arrives as `--navi-keyboard-inset-bottom`
-(`env(keyboard-inset-height)`), which `--navi-app-inset-bottom` adds. Firefox,
-Safari, and an app that called `disableVirtualKeyboardOverlay()` shrink the
-visual viewport instead, and `--navi-keyboard-inset-bottom` stays 0. Either way
+By default the keyboard shrinks the visual viewport, on every browser, and
+`--navi-keyboard-inset-bottom` stays 0. Where the browser has the VirtualKeyboard
+API (Chromium), an app can call `enableVirtualKeyboardOverlay()` to make the
+keyboard overlay the page instead (`src/layout/virtual_keyboard.js`): no viewport
+shrinks, and the keyboard arrives as `--navi-keyboard-inset-bottom`
+(`env(keyboard-inset-height)`), which `--navi-app-inset-bottom` adds. Either way
 `--navi-app-height` and the popup ceilings answer the part of the screen left
 visible.
 

package/docs/scroll.md

@@ -400,6 +400,57 @@ this by hand with a `useEffect` that widens a slice: that effect is one preact
 runs early, and it fails for that reason. The runs ask their source for `after`
 rows from the start, so the smaller first window costs no second request.
 
+### Cmd/Ctrl + F: `findText`
+
+The browser's find in page searches the DOM, and a row outside the render
+window is not in it: Cmd/Ctrl + F finds the rows on screen and a few around
+them, nothing else.
+
+```jsx
+<List.Items
+  items={users}
+  renderItem={renderUser}
+  findText={(user) => user.name}
+/>
+```
+
+With `findText`, the fillers carry the text of the rows they hold the room of,
+one line per row at the row size, inside `hidden="until-found"` elements:
+nothing of it is laid out or painted, and find still reaches it. On a match the
+browser reveals the element and scrolls to the line — which is where the row
+stands — and the render window, following that scroll like any other, draws
+the row. A row inside the window has no hidden copy, so every row is found
+exactly once and the count in the find bar is right.
+
+What it costs, and where it stops:
+
+- **A cost that follows the collection again.** The text of every row outside
+  the window is rebuilt when the window slides (one `findText` call per row)
+  and sits in the DOM as text, one element per 64 rows. Give it to a list a
+  user would search with the browser, not to every run.
+- **One line per row**, and only that line is found while the row is not
+  drawn: return what a user would type, not everything the row shows.
+- **What the client holds, no more.** A row a paginated run has not loaded has
+  no text to be found by.
+- **Chrome 102, Firefox 148, Safari 26.2.** Elsewhere the attribute reads as a
+  plain `hidden`: find stops at the window, as without `findText`.
+
+Two things not to write beside it:
+
+- **A transparent copy of the list's text laid over it** (a `<textarea>` or a
+  `<div>` in `color: transparent`). Every row in the window is then found
+  twice, drawn and copied, and the copy only lines up with rows of one fixed
+  height. It is the first idea everyone has; the demo keeps it for comparison.
+- **A `beforematch` listener moving the window.** The list re-renders in the
+  microtask after the event, which removes the element before the browser has
+  scrolled to it. The browser's own scroll is what moves the window.
+
+And one trap outside the list: a CSS reset forcing `[hidden] { display: none }`
+must leave `[hidden="until-found"]` out — an element hidden with `display: none`
+is never revealed. navi's own does (`src/box/box.jsx`).
+
+Reference: `src/control/demos/19_list_find_in_page_demo.html`.
+
 ### Doing it well
 
 - **A stable `id` on every item.** The run keys its rows on `item.id` — it is
@@ -434,7 +485,7 @@ row is ever a skeleton with `items`, and it costs what the same rows would as
 children. There is no reason to hold back from it for a list that might grow.
 
 Reference: `src/control/list/list.jsx` (JSDoc on `List` — `renderBudget`,
-`virtualItemSize` — and on `List.Items`),
+`virtualItemSize` — and on `List.Items` — `findText`),
 `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 run reading a slice at a time). What a run reads back after a write is in

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/navi",
-  "version": "0.29.406",
+  "version": "0.29.408",
   "type": "module",
   "description": "Library of components including navigation to create frontend applications",
   "repository": {
@@ -34,7 +34,7 @@
     "preact": "^11.0.0-rc.2"
   },
   "dependencies": {
-    "@jsenv/dom": "0.17.78",
+    "@jsenv/dom": "0.17.80",
     "@jsenv/humanize": "1.8.6",
     "@jsenv/validity": "0.4.5"
   },