@jsenv/navi 0.29.114 → 0.29.115

package/docs/actions.md

@@ -97,6 +97,20 @@ it — and why a run settles with its error rather than rejecting — is
 state at once — `{ idle, loading, completed, aborted, error, data, params }` —
 for a component that needs to look at it rather than render it.
 
+**Reading does not run.** `useAsyncData` waits for data someone else asked for
+— for a page, the route, through `routeAction`. A component reading an action
+that nobody ran suspends, and `<Loading>` draws nothing for an idle action (no
+spinner for a request nobody sent): the whole subtree stays blank, for good. The
+obvious fix does not work — a `useEffect` in that same component that would
+`run()` it never fires, because a suspended component has no effects, and the
+run it was about to start is exactly what the suspension waits for. So either
+the action is started **before** anything reads it — bound where the screen is
+decided: a `routeAction`, a `<Button action>`, the `action` of the `<Link>` one
+came in by — or the component owns its request and does not suspend on it: a
+folding panel, a slice a button asks for. That one reads `action.dataSignal` and
+`action.errorSignal` (or `useActionStatus`) directly, `run()`s the action from an
+effect, and draws its own skeleton until the data is there.
+
 `{ onLoad }` is what the screen does with the data **once, when it becomes
 known** — seed the fields someone is about to edit, focus something, remember
 where a list was:

package/docs/create_and_edit.md

@@ -134,7 +134,9 @@ Two things to know or the screen stays empty:
 - **Reading an action does not start it.** `useAsyncData` waits for data
   someone else asked for; what asks is the route (`routeAction`). A component
   reading an action nobody runs suspends forever, and the whole `<Loading>`
-  subtree stays blank.
+  subtree stays blank — and an effect in that component cannot rescue it, a
+  suspended component has no effects. What to do instead is under "Reading an
+  action" in [actions.md](./actions.md#reading-an-action).
 - **Handle the error where it happens**, or hand it to an `<ErrorBoundary>`:
   `useAsyncData(action, { loading: true, error: true })` returns
   `[data, loading, error]`, which is what lets a page draw its own "the server

package/package.json

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