@jsenv/navi 0.29.224 → 0.29.225

package/docs/AI_INSTRUCTIONS.md

@@ -114,11 +114,13 @@ to start when unsure which export solves a problem.
   a boundary. Read before displaying an error by hand or writing a boundary.
 - `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: `lazy()` makes
-  the import an action, so `<Loading>`, `<ErrorBoundary>` and `rerun` cover it;
-  links fetch code on intent, never data; a transition photographs the
-  fallback; a chunk's `import.meta.css`; why not preact's `lazy`. Read before
-  an `import()` in a component or a page, and before `prefetch={false}`.
+- `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}`.
 
 ### Controls and forms
 

package/docs/css_architecture.md

@@ -139,8 +139,8 @@ why they are still concatenated.
 
 A module reached by `import()` carries its stylesheet in its chunk, adopted
 when the chunk runs: a fallback rendered before it cannot use its classes, and
-between unlayered sheets the last adopted wins. What follows for a lazily
-loaded component is in [dynamic_import.md](./dynamic_import.md).
+between unlayered sheets the last adopted wins. What follows for code loaded
+on demand is in [dynamic_import.md](./dynamic_import.md).
 
 ### Browser support: navi's css and your target
 

package/docs/dynamic_import.md

@@ -7,14 +7,27 @@ 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.
 
-## The import is an action
+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.
 
-`lazy()` turns a loader into a component whose code is an action:
+## A page: its code is a route action
 
-```jsx
-import { lazy } from "@jsenv/navi";
+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:
 
-const GamePage = lazy(() => import("./game_page.jsx"));
+```jsx
+const GAME_PAGE_ACTION = routeAction(GAME_ROUTE, GAME.GET, () => ({
+  gameId: GAME_ROUTE.paramsSignal.value.gameId,
+}));
+const GAME_PAGE_CODE = routeAction(GAME_ROUTE, () =>
+  import("./game_page.jsx").then((m) => m.GamePage),
+);
+
+const GamePage = () => {
+  const [Page] = useAsyncData(GAME_PAGE_CODE);
+  return <Page />;
+};
 
 <Route>
   <ErrorBoundary fallback={PageError}>
@@ -25,75 +38,85 @@ const GamePage = lazy(() => import("./game_page.jsx"));
 </Route>;
 ```
 
-Everything the data layer already decides then holds for the code, with
-nothing more to write:
+Everything the data layer decides then holds for the code, with nothing more
+to write:
 
-- **It starts with the data.** The route action runs on the url change; the
-  import starts from the render the match triggers, a microtask later — or
-  earlier, on intent (below). The two are in flight together, and the page
-  suspends on whichever arrives last.
-- **One wait.** The import suspends into the nearest `<Loading>` like a
-  `useAsyncData` does — the boundary is told it is loading, and draws its
-  fallback. It counts in the document's busy state like a route action.
+- **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, and going
-  somewhere else leaves it behind. A module missing after a deploy is an error
-  the screen already knows how to show.
-- **Fetched once.** A completed run is not run again: coming back to the page
-  renders synchronously, only the data is asked for per params.
-
-The loader resolves to the component itself or to the module: its `default`
-export, or its only exported function. A module exporting several says which
-by returning it from the loader — and two `lazy()` on the same module cost one
-fetch, the browser holds a module once:
-
-```js
-const PlanThumbnail = lazy(() => import("./plan.jsx").then((m) => m.PlanThumbnail));
-const PlanDialog = lazy(() => import("./plan.jsx").then((m) => m.PlanDialog));
+  `<ErrorBoundary>` shows it, `error.action.rerun()` is the way back, going
+  somewhere else leaves it behind.
+- **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).
+
+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 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>
+  );
+};
 ```
 
-## Where the boundary goes
+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.
 
-The rule of the data layer applies unchanged: **the `<Loading>` goes where the
-fallback should land**, and a `lazy()` element needs one above it exactly as a
-page reading its data does. A boundary around the whole router takes the
-router away while a page loads — top bar, tabs and all — and puts the fallback
-in its place. Written between the container and its branches, it holds the
-page's box and nothing else (see [navigation.md](./navigation.md), "Loading
-data"). A component fetched on demand inside a page that stays gets its own
-`<Loading>` around it, with the frame of what it stands in for as the
-fallback.
+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.
 
 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
-by the code arriving. A subtree parked later is parked by a data suspension,
-which is the same story with or without a split.
+by the code arriving.
 
 ## Ahead of the render: intent
 
-**A link fetches the code of where it leads when the pointer or the focus
-reaches it.** `<Link>` and `<Button>` with an `href` or a `route` do it by
-default; `prefetch={false}` opts one out — a destination not worth fetching on
-a hover. The url is matched against the routes on screen, a section and the
-page inside it alike, and each fetches what its router registered for it.
-
-Two things are deliberately NOT part of it:
+**A link preloads where it leads when the pointer or the focus reaches it.**
+`<Link>` and `<Button>` with an `href` or a `route` do it by default;
+`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.
+`routeAction(route, action, undefined, { prefetch: false })` keeps a
+param-less read that is not worth a hover out of it.
 
-- **Only code is fetched, never data.** The data is the route action's, asked
-  for on arrival with the params the address holds. A prefetch has no such
-  address yet — the id may still be chosen — and a read ahead of need is a
-  decision the app takes itself, with `prerun()` on the binding it wants warm.
-- **A prefetch that fails is forgotten**, not reported: nothing on screen asked
-  for it. The visit that needs the code asks again and shows its own failure.
+A prefetch that fails is forgotten, not reported: nothing on screen asked for
+it. The arrival asks again and shows its own failure.
 
-The same fetch, from code: `route.preload()` for a route something is about to
+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
-destination has nothing to preload — the navigation itself fetches the code.
-
-Which routers know: a route's lazy elements register when the router holding
-them renders. A section whose sub-router is inside its own chunk registers its
-pages once the section is on screen; before that, intent on a link to a
-sub-page fetches the section.
+destination has nothing to preload — the navigation itself asks.
 
 ## What a transition photographs
 
@@ -124,13 +147,31 @@ consequences:
   in the build fixes. A rule that depends on it is a rule to make more
   specific.
 
-## Preact's `lazy()` is not this one
+## When the code does not come
+
+Someone has the app open, a deploy moves the chunks, and the next `import()`
+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.
+
+## Preact's `lazy()` is not this
 
-`preact/compat` has a `lazy()` too. It suspends without saying anything to
+`preact/compat` has a `lazy()`. It suspends without saying anything to
 `<Loading>`: the boundary keeps the last reason it knows — "idle" by default —
 and draws nothing while the module loads; a failure is not an action's, so no
 `rerun` brings the page back. Navi warns in dev when a `<Loading>` catches a
-suspension it cannot attribute to an action. Import `lazy` from navi.
+suspension it cannot attribute to an action. Read the import through an
+action.
 
 ## The build
 
@@ -140,7 +181,9 @@ configure.
 
 ## Reference
 
-- `src/nav/demos/code_splitting/code_splitting_demo.html` — two pages fetched
-  on demand next to a route action, one prefetched on hover and one opted out,
-  with the import drawn on the backend's frontier so both waits can be watched.
-- `src/state/async/lazy.jsx`, `src/nav/use_preload_on_intent.js`
+- `src/nav/demos/code_splitting/code_splitting_demo.html` — two pages whose
+  code is a route action, one prefetched on hover and one opted out, and a
+  component inside a page that stays, drawing its own wait and failure; every
+  import is drawn on the backend's frontier so a wait or a failure can be
+  played by hand.
+- `src/nav/route_action.js`, `src/nav/use_preload_on_intent.js`

package/package.json

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