@jsenv/navi 0.29.166 → 0.29.167

package/docs/AI_INSTRUCTIONS.md

@@ -69,6 +69,17 @@ consistency across the app, not from any single call site.
   collection (searching it is that collection's own `GET_MANY`). Companion
   files: `docs/actions.md`, `docs/resource_with_params.md`,
   `docs/resource_dependencies.md`.
+- `docs/data_states.md` — what a screen draws while its data is loading,
+  missing, stale or failed: the three questions `data`, `loading` and `error`
+  answer separately, the four combinations of the first two and what each one
+  means, and the invariant that `loading: true` never suspends — so a component
+  drawing its own states is never taken away, with the dialog, the scroll
+  position and the retry button it was holding. Also why a skeleton is TOLD
+  whether it is loading rather than deducing it from emptiness, why an error
+  arrives beside the data rather than in place of it, and what `dismissError()`
+  does and does not do. Read it before drawing a skeleton on `!data`, before
+  hiding content because `error` is set, and before adding a state flag of your
+  own next to what the hook already returns.
 - `docs/list_refresh.md` — what a write sends back to the network and what stays
   on screen meanwhile: stale data returned by `useAsyncData({ loading: true })`,
   what updates from a response without any request, `rerunOn` and its defaults,

package/docs/actions.md

@@ -130,10 +130,12 @@ const [user] = useAsyncData(userAction);
 
 `useAsyncData` suspends until the data is there and throws on failure, leaving
 both to the nearest `<Loading>` and `<ErrorBoundary>`; pass `{ loading: true }`
-or `{ error: true }` to handle either inside the component (stale data stays
-available while a rerun is in flight). Where a failure goes when no screen takes
-it — and why a run settles with its error rather than rejecting — is
-[error_handling.md](./error_handling.md). `useActionStatus(action)` gives the whole
+or `{ error: true }` to receive either as a value instead, the component staying
+mounted throughout and keeping the data it already had. What it then draws for
+each state — the four combinations of `data` and `loading`, why a skeleton is
+told whether it is loading — is [data_states.md](./data_states.md). Where a
+failure goes when no screen takes it — and why a run settles with its error
+rather than rejecting — is [error_handling.md](./error_handling.md). `useActionStatus(action)` gives the whole
 state at once — `{ idle, loading, completed, aborted, error, data, params }` —
 for a component that needs to look at it rather than render it. It reads that
 very instance: to know what moves when a control is handed the action, see

package/docs/data_states.md

@@ -0,0 +1,147 @@
+# The states of a screen's data
+
+A screen reading async data draws one of a handful of states, and there are two
+ways to get it wrong. Both are common, and both come from the same shortcut.
+
+- **A wait announced over something that is not coming.** A skeleton drawn on
+  "there is no data" alone keeps shimmering after the load failed, and after the
+  params turned out to be false. It says "hold on", and there is nothing to hold
+  on for.
+- **Content taken away because something behind it went wrong.** A list that
+  disappears because its refresh failed; a page replaced by a message while the
+  rows it had are still perfectly good, and still true a second ago.
+
+The shortcut behind both: collapsing "loading", "empty" and "failed" into one
+state — _not ready_ — and drawing one thing for it. They are three separate
+questions, and a screen that draws honestly answers them separately:
+
+- **is there something to show?** → `data`
+- **is anything on its way?** → `loading`
+- **did the last attempt fail?** → `error`
+
+navi's part is to answer all three, at every render, and to keep answering them.
+What is drawn for each is the component's, always: navi has no opinion on
+whether a missing list is a skeleton, a sentence or an illustration.
+
+## Asking for a state means receiving it as a value
+
+Without options, `useAsyncData` **delegates**: it suspends while the data is not
+there and throws when the action failed, so the states are drawn by the
+`<Loading>` and `<ErrorBoundary>` above rather than by the component.
+
+Each option turns one of those from something done _to_ the component into a
+value the component reads:
+
+| passed          | the wait                  | the failure                  |
+| --------------- | ------------------------- | ---------------------------- |
+| nothing         | suspends into `<Loading>` | throws to `<ErrorBoundary>`  |
+| `loading: true` | `loading`, a boolean      | throws                       |
+| `error: true`   | suspends                  | `error`, plus `dismissError` |
+| both            | `loading`                 | `error`                      |
+
+The invariant that makes this worth relying on: **`loading: true` never
+suspends.** Not while the action runs, not while a debounced binding is
+settling, not while it holds params nobody has started yet, not after a failure
+whose message was dismissed. Every one of those comes back as a value.
+
+That is not a detail of the wait — it is what keeps the component alive.
+Suspending does not draw a spinner over a subtree: it takes the subtree away and
+puts the boundary's fallback in its place, and everything under it is remounted
+when it comes back. A dialog open inside it closes, a scroll position is lost,
+half-typed text is gone, and the retry button the component was offering
+disappears along with the component. A component that said it draws its own
+states is never taken away from the person looking at it.
+
+`error: true` says the same thing about failure, and it has the same
+consequence: the component stays, so it is still there to offer the way out.
+
+A component that delegates nothing needs no `<Loading>` above it. One that
+delegates its wait does, since that is where the suspension lands, and navi says
+so rather than leaving the subtree blank.
+
+## `data` and `loading` are independent
+
+They answer different questions, so all four combinations happen and each one
+means something different:
+
+| `data`      | `loading` | what it is                    | what a screen draws      |
+| ----------- | --------- | ----------------------------- | ------------------------ |
+| `undefined` | `true`    | first load                    | a skeleton, animated     |
+| set         | `true`    | a refresh over a known answer | the content, marked busy |
+| set         | `false`   | settled                       | the content              |
+| `undefined` | `false`   | nothing here, nothing coming  | an empty state           |
+
+Two consequences worth stating out loud.
+
+**The emptiness test is `data === undefined`, never `loading`.** Reading
+`loading` as "there is nothing to display" blanks the screen on every refresh —
+for a checkbox ticked on one row of a list, the whole list goes.
+
+**A skeleton is told whether it is loading; it does not deduce it.** The last
+row of the table is the one that gets forgotten, and it is reachable: a first
+load that failed — its message on screen or dismissed — and a route action whose
+params getter returns false. A skeleton drawn on emptiness alone shimmers there
+forever, claiming a load nobody started.
+
+```jsx
+const [items, loading] = useAsyncData(ACTION, { loading: true });
+if (items === undefined) {
+  return <ItemsSkeleton loading={loading} />;
+}
+return <ItemList items={items} busy={loading} />;
+```
+
+navi's own placeholders take that flag rather than inventing it: `<Text loading>`
+shimmers, `<Text skeleton>` is the same bar held still, and `<Text skeleton
+loading={loading}>` is one that tells the truth either way.
+
+**Knowing the count beforehand beats guessing it.** How many skeleton rows to
+draw is a question the response answers too late; a screen that already knows —
+a count carried by the parent resource, a total returned alongside a previous
+page — says so, and `<List loading loadingSkeletonCount={0}>` draws the empty
+state right away instead of three rows that will vanish. Nothing jumps when the
+response lands.
+
+## An error is a message on the screen, not the screen
+
+`error: true` hands the failure over **beside** the data the action already had,
+not in place of it. A refresh that failed does not unmake the previous answer,
+so a screen that had something to show keeps it and says the failure over it:
+
+```jsx
+const [items, loading, error, dismissError] = useAsyncData(ACTION, {
+  loading: true,
+  error: true,
+});
+if (error && !items) {
+  return <ErrorScreen error={error} />; // nothing behind it: the message is the screen
+}
+return (
+  <>
+    {error && <ErrorStrip error={error} onClose={dismissError} />}
+    <ItemList items={items} busy={loading} />
+  </>
+);
+```
+
+`dismissError()` removes the message and nothing else — nothing is asked again,
+because nothing had to be: what closing it reveals was already there. What comes
+back is the same state minus the error, which is why the two branches above stay
+honest afterwards.
+
+Taking the whole subtree away is `<ErrorBoundary>`'s job and it is a different
+decision: reach for it when the failure means the screen genuinely cannot be
+drawn, not as a stronger version of the same thing. Which of the two, and where
+an error goes when neither takes it, is
+[error_handling.md](./error_handling.md).
+
+## Reference
+
+- [error_handling.md](./error_handling.md) — the two kinds of error, where each
+  is shown, and what happens to one nobody displays.
+- [list_refresh.md](./list_refresh.md) — the same states for a list, plus what a
+  write puts back on screen with no request at all.
+- [actions.md](./actions.md#reading-an-action) — reading an action versus
+  running one, `{ run: true }`, `{ onLoad }`.
+- `src/state/demos/use_async_data_demo.html` — one card per shape: delegated,
+  loading inline, both inline, owning its request.

package/docs/error_handling.md

@@ -140,6 +140,15 @@ const [game, loading, error, dismissError] = useAsyncData(gameAction, {
 });
 ```
 
+`game` and `error` arrive **together**: a refresh that failed does not unmake
+the answer the action already had, so the screen keeps what it has and says the
+failure on it, and `dismissError()` takes that message away without asking
+anything again. That is the whole difference between the two shapes — a boundary
+replaces the subtree by definition, this one writes on it — so reach for the
+boundary when the failure means the screen cannot be drawn at all, and for this
+when it means one thing about it is out of date. How the component draws the
+states it is handed is [data_states.md](./data_states.md).
+
 And one row rather than the whole list: `<List.Item error>` replaces the row's
 content with the message — what the row stood for did not happen, so drawing it
 as if it had would be a lie.

package/docs/list_refresh.md

@@ -27,13 +27,15 @@ The short answer:
 | never completed yet   | `undefined` | `true`    |
 | running after success | previous    | `true`    |
 | completed             | fresh       | `false`   |
+| failed after success  | previous    | `false`   |
+| failed, error closed  | `undefined` | `false`   |
 
 So the emptiness test is `data === undefined`, never `loading`:
 
 ```js
 const [items, loading] = useAsyncData(ACTION, { loading: true });
 if (items === undefined) {
-  return null; // first load: there is nothing to show yet
+  return <RadarListSkeleton loading={loading} />; // nothing to show yet
 }
 return <RadarList radars={items} busy={loading} />; // re-read: stay on screen
 ```
@@ -48,10 +50,23 @@ if (loading) {
 Read `loading` as "what you are displaying is from before", not "there is
 nothing to display".
 
+The two answer different questions — _is there anything to show_ and _is
+anything on its way_ — so a screen reads both, and a skeleton is given `loading`
+rather than deducing it from emptiness. The four combinations, and what each one
+draws, are in [data_states.md](./data_states.md).
+
 `<List loading>` is the first-load answer, not the refresh one: it replaces the
 rows with skeletons. Pass it while stale rows exist and they disappear — same
 mistake as `loading ? null :`, one level down.
 
+The `failed after success` row is the same rule at the other end: a refresh that
+failed does not unmake the rows either. With `error: true` the failure comes
+back **beside** them, so the list stays and the failure is said over it — a
+strip above the rows, a retry, `dismissError()` to close the strip without
+asking anything again. Taking the rows away is `<ErrorBoundary>`'s job, and only
+when the screen genuinely cannot be drawn — see
+[data_states.md](./data_states.md).
+
 ## What updates without a request
 
 An action's `data` is a computation over the resource store, not a snapshot of

package/package.json

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