@jsenv/navi 0.29.224 → 0.29.226

package/docs/AI_INSTRUCTIONS.md

@@ -114,11 +114,14 @@ 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` read with `loading: true` (a branch, not a
+  `<Loading>`), a component reads its own with `useAsyncData(() => import(…))`;
+  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/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,99 +7,139 @@ 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";
-
-const GamePage = lazy(() => import("./game_page.jsx"));
+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. 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:
 
-<Route>
-  <ErrorBoundary fallback={PageError}>
-    <Loading fallback={<PageSkeleton />}>
-      <Route route={GAME_ROUTE} element={GamePage} />
-    </Loading>
-  </ErrorBoundary>
-</Route>;
+```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, loading, error] = useAsyncData(GAME_PAGE_CODE, {
+    loading: true,
+    error: true,
+  });
+  if (loading) {
+    return <GameScreenPending />;
+  }
+  if (error) {
+    return <GameScreenUnavailable />;
+  }
+  return <Page />;
+};
+
+<Route route={GAME_ROUTE} element={GamePage} />;
 ```
 
-Everything the data layer already 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 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));
+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 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>
+  );
+};
 ```
 
-## Where the boundary goes
+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.
 
-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:
-
-- **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.
-
-The same fetch, from code: `route.preload()` for a route something is about to
+**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.
+
+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
-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
 
-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.
@@ -124,13 +164,38 @@ 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
-
-`preact/compat` has a `lazy()` too. It suspends without saying anything to
+## 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.
+
+**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
+
+`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 +205,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.226",
   "type": "module",
   "description": "Library of components including navigation to create frontend applications",
   "repository": {