@jsenv/navi 0.29.414 → 0.29.416

package/docs/autofocus.md

@@ -15,6 +15,7 @@ at the end of this page.
 - [What a field says about itself](#what-a-field-says-about-itself)
 - [When the opening places nothing](#when-the-opening-places-nothing)
 - [The ring is decided too](#the-ring-is-decided-too)
+- [When a popup closes](#when-a-popup-closes)
 - [Moving the focus yourself](#moving-the-focus-yourself)
 
 ## What we want
@@ -202,6 +203,24 @@ focused while the input is). Style the standard name and you get that for free.
 }
 ```
 
+## When a popup closes
+
+The focus goes back to what held it when the popup opened — the trigger, most
+of the time — so the user carries on where they were.
+
+A popup that closes because it **leaves the tree** — its component unmounted,
+the page holding it left — gives the focus back once that change is over, and
+only to an element still in the document: the trigger often leaves in the same
+render, and focusing it just before it goes would be focusing nothing (and
+making its removal cost more). It gives the focus back only into a void, too:
+when something else took the focus meanwhile — the page arriving, focusing a
+field of its own — that one keeps it.
+
+So `{editing && <Dialog open>…</Dialog>}` unmounted from a button inside it
+lands the focus back on the button that opened it, and a dialog left along
+with the page around it lands it nowhere (`<body>`), exactly as if the page
+had simply been removed.
+
 ## Moving the focus yourself
 
 Prefer saying where the focus belongs over moving it: `autoFocus` on the field

package/docs/resource.md

@@ -292,9 +292,13 @@ Keep their **ids**, not the objects: an object is a snapshot, and it stops
 following its row the moment anything writes to it. `RESOURCE.useAllByIds(ids)`
 reads those rows as they are now — a kept id turned back into something that
 stays fresh, and the ids the store no longer holds simply drop out.
-`RESOURCE.useById(id)` is the singular, `RESOURCE.useArray()` the whole store;
-all three subscribe the render that calls them, and none is a hook (a `.map()`
-over them is fine).
+`RESOURCE.useById(id)` is the singular, `RESOURCE.useArray()` the whole store.
+None is a hook (a `.map()` over them is fine), and each subscribes the render
+that calls it to what it returns: `useById` and `useAllByIds` to the rows they
+hand back — a card reading its own row stays still while other rows of the
+store are written, and re-renders when its row is — `useArray` to the whole
+store. An entry of `useAllByIds` given by a unique key rather than by id can
+only be found by reading the whole store, and that read follows it too.
 
 ## Relations: pick one of the four methods
 

package/docs/route_transitions.md

@@ -567,6 +567,13 @@ What that means for a page and for the application around it:
   is photographed on the old side only, leaves with its page, and is closed
   when the page is taken down (see
   [view_transitions.md](./view_transitions.md#a-hidden-element-is-not-photographed-even-in-the-top-layer)).
+- **The focus it holds goes where its removal would have sent it** — to no
+  element — when it is hidden: a hidden element keeps the focus otherwise,
+  and would receive the keys pressed during the movement.
+- **Never while a modal dialog is open.** An open modal keeps everything but
+  itself out of reach — the page arriving could not even take the focus — and
+  one in a page kept while leaving would stay open for the whole movement. The
+  page is then taken down at once, as without a movement.
 - **Only where the page would have been taken down anyway.** A page rendered by
   the same element on both sides — two routes, one component — is the same
   instance carried over, as without a movement.
@@ -630,12 +637,19 @@ elements):
   navi's movements declare nothing inheritable on the root; a custom type
   publishing values of its own writes them on `::view-transition` (see
   [Custom movements](#custom-movements)).
-- **The page being left reacting to the address it no longer matches.** Every
-  component in it that re-renders on a URL change does so inside the update
-  callback, next to the page arriving being built — measured: about 2,500
-  component renders for the list of thirty cards, its links and its list
-  first. Taking the page down there instead would drop them, and still costs
-  more; what re-renders on the address is worth keeping to what has to.
+- **The page being left reacting to what the navigation changed.** Every
+  component in it that re-renders on the change does so inside the update
+  callback, next to the page arriving being built. A link or a button pointing
+  at a route (`<Link route>`, `<Button route>`) reads one flag — whether it is
+  current — and stays still unless that flips: a profile opening leaves the
+  links to a hundred other profiles exactly as they were (on the list of
+  thirty cards: 90 re-renders gone, first frame 58 → 41 ms). A row read with
+  `RESOURCE.useById` follows that row only, so the page arriving loading rows
+  of its own into the same store leaves the cards of the page being left as
+  they were. What reacts is then the page's own reading of its route's action
+  — its params, its data and its state all move as the route stops matching —
+  and that re-renders the page with everything in it (on the list of thirty
+  cards: about 1,150 component renders, the largest share of the callback).
 - **Re-rendering what did not change, on the press itself.** A component that
   only wants a yes or a no reads a computed flag, not the signal it is derived
   from: a list whose rows each read the count of runs in flight re-rendered

package/package.json

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