@jsenv/navi 0.29.226 → 0.29.227

package/docs/AI_INSTRUCTIONS.md

@@ -116,7 +116,8 @@ to start when unsure which export solves a problem.
   writes politely. Read before caching responses in the app.
 - `dynamic_import.md` — a screen's code arrives like its data: a page's
   import is a `routeAction` read with `loading: true` (a branch, not a
-  `<Loading>`), a component reads its own with `useAsyncData(() => import(…))`;
+  `<Loading>`), a component's is started by what asks — `actionRunEffect` on a
+  state, `useAsyncData(() => import(…))` only as the fallback;
   links prerun on intent what asks nothing of the address; a transition
   photographs the pending screen; a chunk's `import.meta.css`; a chunk that
   does not come is never a bug and never comes twice in one document — offer

package/docs/dynamic_import.md

@@ -7,8 +7,10 @@ the network is gone or a deploy happened in between — and nothing on screen
 should have to know whether what it waits for is bytes of data or bytes of
 code.
 
-So navi has nothing lazy-shaped: **the import is an action**, read by the hook
-a screen already reads its data with. Two shapes, decided by who asks.
+So navi has nothing lazy-shaped: **the import is an action**, started by what
+asks for it — the address through `routeAction`, a state through
+`actionRunEffect` — and read by the hook a screen already reads its data
+with. Running it from the hook itself is the fallback, as for data.
 
 ## A page: its code is a route action
 
@@ -72,43 +74,66 @@ The page module itself is ordinary — it reads its data with
 `useAsyncData(GAME_PAGE_ACTION)` like any page — and imports the routes module
 back for it; a dynamic import is not a load-order cycle.
 
-## A component inside a page that stays: it reads its own code
+## A component inside a page that stays: who asks for its code
 
 A plan drawn on demand inside a page that stays knows where it is drawn and
-what stands there — a frame, a line, a button. `useAsyncData` takes a
-function: the request this component owns, made into an action once on the
-first render and kept for the life of the instance, its answer as the data.
-The wait and the failure are then drawn where the frame is, and no boundary is
-involved:
-
-```jsx
-const PlanSection = () => {
-  const [Plan, loading, error] = useAsyncData(
-    () => import("./plan.jsx").then((m) => m.Plan),
-    { loading: true, error: true },
-  );
-  return (
-    <PlanFrame>
-      {loading ? <Text>…</Text> : null}
-      {error ? <Button action={() => reload()}>Recharger</Button> : null}
-      {Plan ? <Plan /> : null}
-    </PlanFrame>
-  );
-};
-```
-
-The same reasons as for a page hold: nothing stands there yet, so a
-suspension would only swap and remount for nothing. Delegating instead
-(`useAsyncData(fn)` alone, under a `<Loading>` around the frame) follows the
-rule for data: **the `<Loading>` goes where the fallback should land.** A
-boundary around the whole router takes the router away while a page loads —
-top bar, tabs and all.
-
-This shape starts at the render and is per instance: a component fetched this
-way in three places asks three times (the browser fetches the module once),
-and coming back to it suspends for the microtask the import takes to answer
-from the module map. A page wants the route action shape; a section inside a
-page rarely notices.
+what stands there — a frame, a line, a button. The wait and the failure are
+drawn where the frame is, with `loading: true` and `error: true`, the same way
+as for a page. What differs is **who starts the import**, and the order of
+preference is the one `useAsyncData` states for data: **the run belongs to
+what asks, not to the render.**
+
+1. **The address asks** → `routeAction`, above. A section of a page that has
+   an address (`/places/:id/plan`) is a page.
+2. **A state asks** → `actionRunEffect`. A plan drawn once a mode is entered,
+   a tab chosen, a popup opened: the signal that says so is what starts the
+   import, declared once at module scope — one action for every instance,
+   started by the state change rather than by the render that follows it,
+   and holding its answer across mounts:
+
+   ```jsx
+   const PLAN_CODE = actionRunEffect(
+     () => import("./plan.jsx").then((m) => m.Plan),
+     () => planShownSignal.value,
+   );
+
+   const PlanSection = () => {
+     const [Plan, loading, error] = useAsyncData(PLAN_CODE, {
+       loading: true,
+       error: true,
+     });
+     return (
+       <PlanFrame>
+         {loading ? <Text>…</Text> : null}
+         {error ? <Button action={() => reload()}>Recharger</Button> : null}
+         {Plan ? <Plan /> : null}
+       </PlanFrame>
+     );
+   };
+   ```
+
+3. **Nothing above the component asks** → `useAsyncData` with a function, the
+   fallback: the component's own existence is the only thing that asks, so the
+   request is its own, made into an action once on the first render and kept
+   for the life of the instance.
+
+   ```jsx
+   const [Plan, loading, error] = useAsyncData(
+     () => import("./plan.jsx").then((m) => m.Plan),
+     { loading: true, error: true },
+   );
+   ```
+
+   It starts one render late, and per instance: a component fetched this way
+   in three places asks three times (the browser fetches the module once), and
+   coming back to it suspends for the microtask the import takes to answer
+   from the module map. Reach for it when there is genuinely no state to read
+   the request off — not to save declaring one.
+
+Delegating instead (the hook without `loading: true`, under a `<Loading>`
+around the frame) follows the rule for data: **the `<Loading>` goes where the
+fallback should land.** A boundary around the whole router takes the router
+away while a page loads — top bar, tabs and all.
 
 Nothing has to be kept out of a subtree loaded this way: the suspension
 happens before the module's components exist, so nothing inside it is parked

package/docs/interactions.md

@@ -325,6 +325,13 @@ being sent: everything — the popup is the only place its failure can be read,
 and `actionStandalone` there is how a save fails behind a closed popup. Something
 the app watches from somewhere else: nothing — it was never being watched here.
 
+And when the answer being sent may never arrive at all — a request over a
+network that stopped answering — the hold outlives what it was protecting:
+nothing can close the popup, ever. `actionAbortable` keeps the hold and gives it
+a release, so closing calls the run off rather than being refused. What that
+costs, and where it may be said, is
+[popup_open.md](./popup_open.md#the-popup-owns-its-open-state).
+
 ### On something you draw yourself
 
 `selfInteractions` is a `Box` prop too, so an affordance does not have to become

package/docs/popup_open.md

@@ -29,10 +29,10 @@ something a `useState` in the parent cannot give back: **a popup refuses to
 close while a control inside it is mid-action**.
 
 ```js
-// what both do on every close request
-const busyElement = findBusyElementInside(popupEl);
-if (busyElement) {
-  dispatchRequestInteraction(busyElement, { ... });
+// what both do on every close request (popup_busy.js)
+const controlsHolding = findControlsHoldingPopup(popupEl);
+if (controlsHolding.length) {
+  dispatchRequestInteraction(controlsHolding[0].element, { ... });
   requestCloseEvent.preventDefault();
 }
 ```
@@ -58,6 +58,33 @@ It is still busy for itself — the spinner, the second press refused, the error
 callout — which is the whole point of keeping `action` (see
 [interactions.md](./interactions.md#the-fourth-question-whose-wait-is-it)).
 
+Between the two sits a run that IS being waited on and may never end. A request
+over a network that stopped answering settles neither way, and the hold then
+lasts exactly as long as the run: the popup closes for nothing and nobody, and
+the page has to be reloaded. `actionAbortable` gives that hold a release — the
+person waiting decides the answer is not coming, and closing is how they say
+it:
+
+```jsx
+<Form action={saveScore} actionAbortable>
+```
+
+Every close request then goes through and calls the run off on the way out:
+Escape, the backdrop, the cross, the phone's back gesture. No gesture is singled
+out, because the cancel/keep distinction below is about the VALUE a popup holds,
+and there is nothing left to keep or put back once the answer is already on the
+wire — each of those gestures means "I want out of here", which is the only
+thing being answered.
+
+What it costs is written down: aborting frees the client and nothing more, so
+the write may have landed anyway (see
+[actions.md](./actions.md#aborting-saves-resources-it-does-not-undo)). Say it
+where the screen can be re-opened on what is actually there, never where the
+popup is the only place the outcome could be read. Everything inside the form
+inherits it along with the wait itself; a popup holding one run that may be
+given up on and one that may not still refuses, since calling off half of them
+would cost an answer and change nothing on screen.
+
 So the question is never "should this popup be controlled?" but "what triggers
 the opening?" — and, when the answer is the application rather than a gesture,
 where that state lives:

package/package.json

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