@jsenv/navi 0.29.225 → 0.29.227

package/docs/AI_INSTRUCTIONS.md

@@ -115,12 +115,14 @@ to start when unsure which export solves a problem.
 - `offline.md` — `setNetworkPolicy`: answer from the store, ask nothing, refuse
   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`, a component reads its own with
-  `useAsyncData(() => import(…))`, so `<Loading>`, `<ErrorBoundary>` and
-  `rerun` cover it; links prerun on intent what asks nothing of the address; a
-  transition photographs the fallback; a chunk's `import.meta.css`; a chunk
-  that does not come is never a bug; why not preact's `lazy`. Read before an
-  `import()` in a component or a page, and before `prefetch={false}`.
+  import is a `routeAction` read with `loading: true` (a branch, not a
+  `<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
+  `reload()`; why not preact's `lazy`. Read before an `import()` in a component
+  or a page, and before `prefetch={false}`.
 
 ### Controls and forms
 

package/docs/dynamic_import.md

@@ -7,14 +7,18 @@ 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
 
 The address asks for the page's data through a route action; it asks for the
 page's code the same way, and the two are in flight together from the url
-change:
+change. The page component in the entry reads the code like data — with
+`loading: true` and `error: true`, drawing the page's own pending screen and
+its own unavailable screen where the page will stand:
 
 ```jsx
 const GAME_PAGE_ACTION = routeAction(GAME_ROUTE, GAME.GET, () => ({
@@ -25,75 +29,111 @@ const GAME_PAGE_CODE = routeAction(GAME_ROUTE, () =>
 );
 
 const GamePage = () => {
-  const [Page] = useAsyncData(GAME_PAGE_CODE);
+  const [Page, loading, error] = useAsyncData(GAME_PAGE_CODE, {
+    loading: true,
+    error: true,
+  });
+  if (loading) {
+    return <GameScreenPending />;
+  }
+  if (error) {
+    return <GameScreenUnavailable />;
+  }
   return <Page />;
 };
 
-<Route>
-  <ErrorBoundary fallback={PageError}>
-    <Loading fallback={<PageSkeleton />}>
-      <Route route={GAME_ROUTE} element={GamePage} />
-    </Loading>
-  </ErrorBoundary>
-</Route>;
+<Route route={GAME_ROUTE} element={GamePage} />;
 ```
 
-Everything the data layer decides then holds for the code, with nothing more
-to write:
-
-- **One wait.** The page suspends into the nearest `<Loading>` on whichever of
-  the two arrives last; the boundary is told it is loading and draws its
-  fallback; the routing is busy until both are there.
-- **One failure.** A rejected import fails the run: the nearest
-  `<ErrorBoundary>` shows it, `error.action.rerun()` is the way back, going
-  somewhere else leaves it behind.
+Why a branch rather than a `<Loading>` around it: suspending takes the
+subtree away and puts the boundary's fallback in its place, then mounts the
+page again — a cost worth paying when a page already on screen re-reads its
+data (see [data_states.md](./data_states.md)), and worth nothing here, where
+the page is not there yet and has nothing to keep. `loading: true` never
+suspends: one component, no wrapper, the pending screen is the page's own
+shape, and the failure sits beside it (what it offers: below, "When the code
+does not come"). What is delegated stays delegated — the page's data, read inside
+`game_page.jsx` with `useAsyncData(GAME_PAGE_ACTION)`, still waits in the
+`<Loading>` written between the routes, as [navigation.md](./navigation.md)
+says.
+
+Everything the data layer decides then holds for the code:
+
+- **One failure.** A rejected import fails the run like a failed read; drawn
+  by the branch above, or by the nearest `<ErrorBoundary>` when the page reads
+  its code without `error: true`.
 - **Fetched once.** A route action left behind is aborted, not reset, and a
   completed one is not run again: coming back to the page renders
   synchronously, only the data is asked for per params.
 - **Fetched ahead.** A route action that asks nothing of the address is prerun
   on intent (below).
+- **Counted.** The routing is busy until the code is there, like for the
+  data.
 
 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={() => error.action.rerun()}>Réessayer</Button>
-      ) : null}
-      {Plan ? <Plan /> : null}
-    </PlanFrame>
-  );
-};
-```
-
-Delegating instead (`useAsyncData(fn)` alone, under a `<Loading>` around the
-frame) is the same hook with the same rule as 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
@@ -111,8 +151,9 @@ prefetched: a 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.
 
-A prefetch that fails is forgotten, not reported: nothing on screen asked for
-it. The arrival asks again and shows its own failure.
+A prefetch that fails is not reported: nothing on screen asked for it. The
+failure stays on the action, where the arrival asks again — a failed action is
+run, only a running or completed one is left alone — and shows its own.
 
 The same from code: `route.preload()` for a route something is about to
 navigate to, `preloadUrl(url)` for an address. A press that computes its
@@ -120,9 +161,10 @@ destination has nothing to preload — the navigation itself asks.
 
 ## What a transition photographs
 
-A route element still waiting is announced as rendered by its boundary, so a
-route transition or a `RouteTravel` takes its picture of the **fallback**, code
-and data alike. Navi does not hold a navigation for a chunk: the honest answer
+A route element still waiting is what the container rendered — its pending
+screen, or the fallback of the boundary it suspended into — so a route
+transition or a `RouteTravel` takes its picture of **that**, code and data
+alike. Navi does not hold a navigation for a chunk: the honest answer
 to "a chunk is a hundred milliseconds" is the prefetch above — the code is
 there before the press — and a skeleton that is the page's own shape is what
 gets photographed when it is not.
@@ -154,15 +196,22 @@ is a 404; or the network is gone. The browser says both the same way — a
 `TypeError` with no status — and neither is a bug of the page: there is
 nothing in the app's code to point at.
 
-The component reading its own code says it where it stands, as above. For a
-page, the failure reaches the boundary like a failed read does; a boundary
-that shows only what came from the network and rethrows the rest as a bug
-recognises an import by its action — `error.action` is the route action the
-app declared for the code — rather than by the browser's message. Either way
-`error.action.rerun()` retries; a retry failing the same way says the document
-is stale, and **reloading it** is what brings the new code. Navi does not do
-it on its own — a document reloading itself is a loop waiting to happen — the
-screen says it.
+**Asking again never fetches.** The document remembers a module whose fetch
+failed as failed: a second `import()` of the same address is refused without a
+request, for the life of the document. So a retry on an import has nothing to
+do — `error.action.rerun()` fails again at once, on the same failure — and
+the one way out is a fresh document: **`reload()`**, which the screen offers
+in words the reader understands. Navi does not reload on its own: a document
+reloading itself is a loop waiting to happen. It is also why a prefetch that
+failed is not asked again on the arrival in any useful sense: the run is made,
+refused at once, and the screen says it.
+
+The page or the component reading its code says it where it stands, as
+above. A failure left to a boundary — a page reading its code without
+`error: true` — reaches it like a failed read does; a boundary that shows only
+what came from the network and rethrows the rest as a bug recognises an import
+by its action — `error.action` is the route action the app declared for the
+code — rather than by the browser's message.
 
 ## Preact's `lazy()` is not this
 

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.225",
+  "version": "0.29.227",
   "type": "module",
   "description": "Library of components including navigation to create frontend applications",
   "repository": {