@jsenv/navi 0.29.398 → 0.29.399

package/docs/dynamic_import.md

@@ -146,8 +146,9 @@ by the code arriving.
 `prefetch={false}` opts one out. The url is matched against the routes on
 screen, a section and the page inside it alike, and what is prerun is **every
 route action that asks nothing of the address** — a page's code, a read
-without params. An action whose params come from the address is never
-prefetched: a prefetch has no address, the id may still be chosen.
+without params. An action whose params come from the address is not
+prefetched by a link: a link's prefetch has no address, the id may still be
+chosen.
 `routeAction(route, action, undefined, { prefetch: false })` keeps a
 param-less read that is not worth a hover out of it.
 

package/docs/popup_open.md

@@ -320,6 +320,12 @@ So a dialog whose content is seeded once — an uncontrolled field on a
 first render. Learning it afterwards would mean mounting on the previous subject
 and correcting it, which is a flicker at best and stale fields at worst.
 
+One opening does not follow that order: a `mount="while-opened"` popup pressed on
+its own `anchor` (a picker's trigger, an expandable's UI part) has its content
+built by the press, ahead of the click (see
+[what the popup holds while it is closed](#what-the-popup-holds-while-it-is-closed)). A popup opened ON something is
+opened by a command pressed elsewhere, and keeps the order above.
+
 The two other places one could listen are not that moment, and it is worth
 knowing why:
 
@@ -1008,7 +1014,8 @@ slots".
 Being open is where the user is, and what a popup draws belongs to the screen
 exactly the way a page's own data does. So a popup that loads something binds
 its open state (above) and asks for its data with a `routeAction` whose params
-are `false` while it is closed:
+are `false` while it is closed — and its content reads the question itself,
+without the part that says whether it is open:
 
 ```js
 const groupSheetOpenSignal = stateSignal(false, {
@@ -1016,12 +1023,17 @@ const groupSheetOpenSignal = stateSignal(false, {
   type: "boolean",
 });
 
+// asked while the sheet is open
 export const GROUP_MEMBERS = routeAction(GAME_ROUTE, USER.GET_MANY, () => {
   if (!groupSheetOpenSignal.value) {
     return false;
   }
   return { group: groupSignal.value };
 });
+// read by the sheet, open or closed
+export const GROUP_MEMBERS_SHOWN = USER.GET_MANY.bindParams({
+  group: groupSignal,
+});
 ```
 
 ```jsx
@@ -1030,15 +1042,16 @@ export const GROUP_MEMBERS = routeAction(GAME_ROUTE, USER.GET_MANY, () => {
 </Dialog>;
 
 const GroupMembers = () => {
-  const [members] = useAsyncData(GROUP_MEMBERS); // reads, never runs
+  const [members] = useAsyncData(GROUP_MEMBERS_SHOWN); // reads, never runs
   …
 };
 ```
 
 The same shape when the popup is one of many — a sheet on every card, opened
 from wherever the card is read. Its open state then says which one, and the
-route action reads the id straight from it. Declared on the root route, since a
-card is not a page:
+route action reads the id straight from it, while each card's content reads the
+question of its own card. Declared on the root route, since a card is not a
+page:
 
 ```js
 const seatSheetSignal = stateSignal(undefined, {
@@ -1048,18 +1061,39 @@ const seatSheetSignal = stateSignal(undefined, {
 });
 const ANY_PAGE = route("/", { searchParams: { seat: seatSheetSignal } });
 
+export const seatableUsersOf = (gameId) => ({ game: gameId });
 export const SEATABLE_USERS = routeAction(ANY_PAGE, USER.GET_MANY, () => {
   const gameId = seatSheetSignal.value;
-  return gameId ? { game: gameId } : false;
+  return gameId ? seatableUsersOf(gameId) : false;
 });
 ```
 
 ```jsx
 <Dialog signal={seatSheetSignal} value={game.id}>
-  <SeatableUsers />
-</Dialog>
+  <SeatableUsers gameId={game.id} />
+</Dialog>;
+
+const SeatableUsers = ({ gameId }) => {
+  const [users] = useAsyncData(
+    USER.GET_MANY.bindParams(seatableUsersOf(gameId)),
+  );
+  …
+};
 ```
 
+**The content reads its question, never the route action.** The route action's
+params are `false` while the popup is closed, and for the route action that is
+right: it says _when_ to ask. Read by the content, the same `false` says there
+is nothing to show — `useAsyncData` hands back `undefined` the moment the popup
+closes, the list empties while hidden, and the next opening builds it again from
+the top: the scroll position is lost, and every row is rendered once more for an
+answer that never left the store. When the popup is one of many, it is worse: the
+route action follows whichever popup is open, so a card's sheet kept mounted
+since an earlier opening redraws with another card's rows each time that one
+opens. Closing a popup does not change what it is about, so what it reads leaves
+the open state out. Equal params share one instance — the content reads the very
+one the route action runs, so nothing is asked twice and nothing is copied.
+
 **A popup that waits holds its own `<Loading>`**, like every other part of a
 screen that can wait — it is not built into `Dialog`/`Popover`, because only the
 code inside knows whether anything in there loads at all:
@@ -1116,7 +1150,8 @@ become a popup's private request — asked for late, and asked for alone.
 
 A closed popup builds nothing: `children` are mounted on the first open, and
 stay mounted afterwards — a reopened popup finds its scroll position and its
-half-typed form where it left them.
+half-typed form where it left them, as long as the data it draws does not leave
+with the close (see [A popup that loads data](#a-popup-that-loads-data)).
 
 "Closed" is two states, not one — never opened yet, and closed again after an
 opening — so the `mount` prop answers both at once:
@@ -1134,7 +1169,9 @@ off it, fields a surrounding form submits, a size measured from outside.
 
 Whatever the value but `"while-opened"`, intent on the anchor — a pointer
 entering it, focus landing in it — builds the content ahead of the click that
-will open it.
+will open it. A `"while-opened"` popup is warmed by a press on its anchor only,
+and a press that ends without opening it — a scroll, a drag, a release
+elsewhere — throws the content away: there is still one content at a time.
 
 `"while-opened"` is what an uncontrolled field seeded from a `defaultValue`
 needs: without it, a popup reopened after the underlying value changed still

package/package.json

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