@jsenv/navi 0.29.39 → 0.29.41

package/docs/AI_INSTRUCTIONS.md

@@ -75,8 +75,9 @@ consistency across the app, not from any single call site.
   supported ways to override component styles (props > CSS variables > direct
   rule overrides, in that preference order).
 - `docs/scroll.md` — where scrolling happens: what turns `Box`
-  `header`/`body`/`footer` on, `FixedBar` space, `List`'s `scroller`, and
-  scroll inside a `Dialog`/`Popover`. Read it before writing CSS to make
+  `header`/`body`/`footer` on, `FixedBar` space, `List`'s `scroller`, scroll
+  inside a `Dialog`/`Popover`, and what a scroll does to hover
+  (`hoverWhileScrolling`, `isScrolling()`). Read it before writing CSS to make
   something scroll — navi almost certainly already has the prop.
 - `docs/control_value.md` — who holds a control's value: nobody, a bound
   `signal` (two-way, in both directions), or you (`value`/`checked`). What

package/docs/actions.md

@@ -97,6 +97,43 @@ callback:
 </Button>
 ```
 
+## `action` or `uiAction`
+
+Both fire when a control's value changes, and they are not two ways of writing
+the same thing:
+
+|                   | `uiAction(value, event)`                   | `action`                                                                   |
+| ----------------- | ------------------------------------------ | -------------------------------------------------------------------------- |
+| what it is        | a plain callback                           | an action bound to the control's value                                     |
+| while it runs     | nothing                                    | the control is busy (`aria-busy`, its loading state)                       |
+| if it fails       | an unhandled rejection — nothing on screen | an error callout on the control, and the control goes back to what it held |
+| a popup around it | closes                                     | refuses to close until it is done                                          |
+
+`uiAction` is a notification: the value has changed, here it is. Use it for what
+cannot fail — logging, moving something else on screen, keeping a local
+variable.
+
+Anything that can fail or take time is an `action`, and it does not have to be
+an action instance: a plain function is wrapped into one, bound to the control's
+value, so the callback receives what the control now holds.
+
+```jsx
+// ✓ the box shows it is saving, says so if the save fails, and goes back to
+//   where it was — nothing to write for any of it
+<Input type="checkbox" action={(visibility) => saveMe({ visibility })} />
+
+// ✗ same save, and the user learns nothing: no pending state, and a failure
+//   leaves the box showing something the server never accepted
+<Input type="checkbox" uiAction={(visibility) => saveMe({ visibility })} />
+```
+
+The give-away is an `async` `uiAction`, or one that calls something that writes:
+`uiAction` never waits for what it starts, so nobody is left holding the result.
+
+To merely REMEMBER the value rather than send it, neither is the answer: bind a
+signal and drop the callback entirely — see
+[control_value.md](./control_value.md).
+
 ## Reruns
 
 Actions do not stay stale on their own: a resource's `POST` reruns the

package/docs/control_value.md

@@ -126,7 +126,7 @@ directions; it just has nothing extra to say.
 
 - [control_group.md](./control_group.md) — several controls reading as one
   framed object
-- [actions.md](./actions.md) — `action` vs `uiAction`: what carries loading and
-  error
+- [actions.md](./actions.md#action-or-uiaction) — `action` or `uiAction`: which
+  one carries loading and error, and which one carries nothing
 - [popup_open.md](./popup_open.md#escape-cancels-the-other-gestures-keep) — what
   a cancelled popup does to the value inside it

package/docs/scroll.md

@@ -7,6 +7,7 @@ scrolling area (`Box header/body/footer`, `List`, a popup) are told about it.
 - [1. The document scrolls](#1-the-document-scrolls)
 - [2. A part of the document scrolls](#2-a-part-of-the-document-scrolls)
 - [3. A popup scrolls](#3-a-popup-scrolls)
+- [Hover while scrolling](#hover-while-scrolling)
 - [The list border](#the-list-border)
 
 ## What makes header/body/footer work: the overflow
@@ -236,6 +237,58 @@ changes screen mid-reading.
 Reference: `src/layout/dialog.jsx`, `src/layout/popover.jsx`,
 `src/layout/slide_container.jsx`.
 
+## Hover while scrolling
+
+A scroll moves the content under a pointer that does not move. The browser
+reports that as hover: it fires `mouseleave` + `mouseenter` for **every element
+crossing the cursor** — a dozen per wheel tick. None of it was asked for; the
+user asked to scroll.
+
+It is free as long as hover only paints a background. It stops being free the
+moment hover triggers real work — a highlight somewhere else in the tree, a
+prefetch, a map redrawing a layer — because that work then lands on the main
+thread exactly while a scroll animation is running, and the scroll stutters.
+
+### The fact is in the DOM: `navi-scrolling`
+
+While an element scrolls it carries `navi-scrolling`, written by one capturing
+listener on the document (`scroll` does not bubble, but it does propagate in
+the capture phase) and removed once it has been quiet for a moment — scroll
+events stop before the movement does. Nothing subscribes to anything: whoever
+is concerned says so in CSS.
+
+```css
+/* my rows answer the pointer only when nothing is moving them */
+[navi-scrolling] .my_row {
+  pointer-events: none;
+}
+```
+
+`pointer-events` is what does the work, and it does the whole of it: enter,
+move and leave at once, in the browser, at no cost per element. Hand-written in
+JS the same suppression takes three handlers — once `mouseenter` has been
+swallowed the pointer is already inside the element, so only `mousemove` can
+ever bring the hover back.
+
+The page scroll carries the attribute on `document.scrollingElement`, so an
+ancestor rule covers it too. In JS the same fact reads as `isScrolling()` /
+`isScrolling(element)`, or `scrollActivitySignal` to react to it.
+
+### In a `List`: nothing to do
+
+`List` rows leave hit-testing while anything scrolling them moves — its own
+scroll box, the panel around it, the page.
+
+```jsx
+<List hoverWhileScrolling>   {/* opt back in */}
+```
+
+The default costs one thing, and it is the honest half of the same trade: right
+after a scroll, the row under the pointer lights up only once the pointer moves
+by a pixel.
+
+Reference: `src/utils/scroll_activity.js`.
+
 ## The list border
 
 Not scroll, but the same family of problem — a reasonable default nobody knows

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/navi",
-  "version": "0.29.39",
+  "version": "0.29.41",
   "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.13",
+    "@jsenv/dom": "0.17.14",
     "@jsenv/humanize": "1.7.8",
     "@jsenv/validity": "0.4.2"
   },