@jsenv/navi 0.29.165 → 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,
@@ -331,9 +342,14 @@ consistency across the app, not from any single call site.
   restored on reload without a route and without an entry per step: a search
   param signal handed to a `SlideContainer`, walked to rather than jumped to,
   and `history: "push"` for the states whose values ARE places (with the write
-  that says otherwise, `signal.set(v, { history })`). Read it before writing any
-  routing code — the position of the user belongs in the URL by default, and
-  that decision is not retrofittable.
+  that says otherwise, `signal.set(v, { history })`). It also holds the rule for
+  an OVERLAY — something opened from every screen and drawn over whatever the
+  reader was on: the URL may say what is drawn over the screen, it must never
+  name a place the reader is not at, which is why `/me/settings` is wrong for it
+  and `/places?settings` is right (the layer's address contains the address of
+  what it covers, so closing is exact even from a shared link). Read it before
+  writing any routing code — the position of the user belongs in the URL by
+  default, and that decision is not retrofittable.
 - Source code and demos on GitHub:
   https://github.com/jsenv/core/tree/main/packages/frontend/navi — where to go
   when the built export's JSDoc doesn't answer the question (see "Where the

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/docs/navigation.md

@@ -19,6 +19,14 @@ linking to them, and turning them into tabs.
 - [Tabs that are not routes](#tabs-that-are-not-routes)
   - [A `SlideContainer` in the URL: a position that is not a place one came from](#a-slidecontainer-in-the-url-a-position-that-is-not-a-place-one-came-from)
   - [A state whose values ARE places: `history: "push"`](#a-state-whose-values-are-places-history-push)
+- [A layer over the screen: what its address may say](#a-layer-over-the-screen-what-its-address-may-say)
+  - [Why a layer is a routing question at all](#why-a-layer-is-a-routing-question-at-all)
+  - [`/me/settings` names a place the reader is not at](#mesettings-names-a-place-the-reader-is-not-at)
+  - [It is not "use a search param"](#it-is-not-use-a-search-param)
+  - [What the search param buys: the way back is in the address](#what-the-search-param-buys-the-way-back-is-in-the-address)
+  - [The wiring](#the-wiring)
+  - [Places inside the layer](#places-inside-the-layer)
+  - [What it costs](#what-it-costs)
 
 ## The rule that decides everything else: the position belongs in the URL
 
@@ -747,3 +755,162 @@ not one. What travels is the box, and the address is a label on where the box
 stands. A position several parts of the app must react to is still a route.
 
 Demo: [../src/layout/demos/8_slide_container_demo.html](../src/layout/demos/8_slide_container_demo.html).
+
+## A layer over the screen: what its address may say
+
+Some things are opened from everywhere and drawn OVER whatever the reader was
+looking at: the settings behind a gear in the top bar, a photo, a help sheet.
+Closing one puts the reader back exactly where they were — not on a page the app
+picked, on the one they had. And the address has to hold it, for the same reasons
+every other position does: a reload lands on it, a link opens on it, the back
+button closes it.
+
+### Why a layer is a routing question at all
+
+Layout should not decide routing. But routing decides a great deal of what is on
+screen: which page is mounted, whose data loads, which bar entry lights up, which
+movement plays between two screens. An address is not a label — it is read by
+everything — so a layer, which is a pure fact of layout, cannot be given just any
+address.
+
+The rule that falls out of it, and the whole of this section:
+
+> The URL may say what is drawn OVER the screen. It must never name a place the
+> reader is not at.
+
+### `/me/settings` names a place the reader is not at
+
+Settings opened from anywhere and drawn over anything are not inside `/me`, even
+when they conceptually belong to "me". Written `/me/settings`, the router
+believes otherwise, and everything that reads the router inherits the belief:
+
+- the bar entry for the "me" section lights up while the settings cover a game;
+- `/me` matches, so the screen the reader was on is REPLACED. The covering is a
+  fiction that lasts as long as the animation, and the page beneath is gone;
+- a route transition plays a crossing between two pages that never crossed, and
+  its back half plays on every way out — the sheet lifts to reveal a page that
+  was never underneath;
+- and it is wrong on the way out too: closing does not return to `/me`, it
+  returns to wherever the reader was, which the address never said.
+
+These do not get fixed one at a time. `currentExcept` stops one link from
+claiming "you are here"; a `"none"` relation silences one crossing; a hand-rolled
+`active` replaces one reading. Each patches a reader of the lie without removing
+it, and the next reader arrives quietly wrong.
+
+### It is not "use a search param"
+
+`/settings` at the top level does not claim to be inside `/me` — it is honest
+about not being there, and every symptom above goes with it. What it still is,
+though, is a PAGE: it names a screen, so the screen beneath is gone, and closing
+has nowhere written to return to. `whatever/settings` is the same answer in a
+longer word.
+
+So the rule is not about search params. It is about not claiming a position. A
+path can be honest; what a path cannot do is carry what is underneath.
+
+### What the search param buys: the way back is in the address
+
+`/places?settings` says two things at once — which screen the reader is on, and
+what is drawn over it. That is what makes closing exact from a cold start: a
+reload, a link someone sent, a new tab. The layer's address CONTAINS the address
+of what it covers, so "close" needs no memory at all.
+
+`/settings` has to remember instead. In practice the browser often does — after a
+reload the session's history is still there, so a back-press lands somewhere —
+but that is the BROWSER's memory of this tab, not the address. A link someone
+else opens has none of it, and neither does a bookmark. Only the address travels,
+which is what makes the param shape the right model rather than the convenient
+one.
+
+### The wiring
+
+```js
+const settingsSignal = stateSignal(false, {
+  id: "settings",
+  type: "boolean",
+  weak: true,
+  history: "push",
+});
+export const ROOT_ROUTE = route("/", {
+  searchParams: { settings: settingsSignal },
+});
+```
+
+```jsx
+<Button command="--navi-toggle" commandFor="settings_panel">⚙</Button>
+…
+<SidePanel id="settings_panel" signal={settingsSignal} side="top" expandY />
+```
+
+Every piece of it answers something:
+
+- **declared on the ROOT route**, so the layer opens over every screen. Declared
+  on one route it would only exist there, and a door in the furniture is on every
+  screen ([Search params](#search-params));
+- **`weak`**, so a link built to a page never inherits a layer that happens to be
+  open. A layer qualifies one visit; it is not part of anyone's address;
+- **`history: "push"`**, so the layer is a place one came from and the back button
+  closes it. The closing itself is never an entry of its own — see
+  [popup_open.md](./popup_open.md), which owns what a `signal` bound to a URL
+  writes on open, on close, and on cancel;
+- **the panel is rendered outside the page area**, next to the router rather than
+  inside it. It is drawn over the pages and the fixed bars alike, and it stays
+  mounted while closed so it has somewhere to animate from;
+- **`expandY`**, because a sheet is content-tall by default and a layer covers
+  the screen. It is also what any tab row inside it must NOT be given: `expand`
+  is both axes, and in the panel's own column that makes the row eat the height
+  and push everything below it off screen;
+- **no `defineRouteTransition` for it.** Nothing crosses: the page beneath does
+  not change, so there is no pair of pages and no movement between them. A layer
+  has an entrance of its own, and route transitions are for pages replacing pages
+  ([route_transitions.md](./route_transitions.md)).
+
+### Places inside the layer
+
+A layer big enough to have tabs holds them the way a wizard does — a search param
+of its own, `oneOf` its pages, replacing rather than pushing, so the back button
+closes the layer instead of stepping back one tab. Everything in
+[A `SlideContainer` in the URL](#a-slidecontainer-in-the-url-a-position-that-is-not-a-place-one-came-from)
+applies unchanged, and a layer is exactly the case that section names for
+`SlideContainer` over `RouteTravel`: a popup lives in the browser's top layer,
+where two pages cannot stand side by side.
+
+```js
+const settingsTabSignal = stateSignal("account", {
+  id: "settings_tab",
+  oneOf: ["account", "alerts", "advanced"],
+  weak: true,
+});
+```
+
+The address then grows and shrinks with what the reader does: `/me` closed,
+`/me?settings` open on the tab it opens on, `/me?settings&settings_tab=alerts`
+one tab further, and back to `/me?settings` returning to the first.
+
+Two params, because they answer two questions — is the layer there, and which of
+its pages is shown. One param whose value is "which page of the layer, or none"
+(`?settings=alerts`) is arguably the shape the address wants, and it is not
+expressible today: a popup says its open state as a boolean, so it would
+overwrite the tab on every open.
+
+### What it costs
+
+This is a compromise, and it is worth stating rather than discovering:
+
+- **the page beneath stays mounted and alive under an opaque layer.** Its actions
+  keep running, refreshing, retrying, for something nobody can see. Nothing tells
+  a route "you are covered", and nothing should be inferred from a layer being
+  open — the reader is still on that page, and will be back on it in a moment;
+- **the router knows nothing about layers.** `<Route>` renders pages; the layer is
+  drawn beside them by the application. The address is honest about it, but "over"
+  is not a routing concept, and no `<Route>` shape expresses it;
+- **the app really is on the page underneath**, which is right for `aria-current`,
+  for the bar, for a link built while the layer is open — and is exactly wrong for
+  anything wanting "the settings are what is current". If something needs to
+  answer that, it reads the layer's own state, not the router.
+
+Demo:
+[../src/nav/demos/route_transition_fixed_bars/route_transition_fixed_bars.html](../src/nav/demos/route_transition_fixed_bars/route_transition_fixed_bars.html)
+— a bar holding both doors side by side: notifications, a page that replaces the
+screen with a route transition, and settings, a layer that covers it.

package/docs/popup_open.md

@@ -533,7 +533,10 @@ is nav state by construction.
 
 The two meet when the signal IS a route's: a search-param `stateSignal` given to
 `signal` puts the open state in the address itself, where a link can point at
-it.
+it. That is also the shape a popup takes when it is a LAYER over the screen —
+settings opened from every screen and closed back onto the one the reader was on
+— and what the address may and may not claim there is a decision of its own:
+[navigation.md](./navigation.md#a-layer-over-the-screen-what-its-address-may-say).
 
 ### `open`, and what it costs
 

package/docs/route_transitions.md

@@ -65,6 +65,14 @@ happens to be everywhere. Write it for a page whose door really is furniture; a
 page reached from a screen has that screen to be paired with, and the pair says
 more.
 
+**Such a page is still a PAGE**, and that is the question to settle before
+writing the relation: it takes the screen's place, and the reader comes back to
+whatever the router puts there — not necessarily to what they were on. A door in
+the furniture whose destination must be drawn OVER the screen, and must give it
+back exactly on closing, is not a page at all: it is a layer, its address says so
+differently, and no relation is written for it. See
+[navigation.md](./navigation.md#a-layer-over-the-screen-what-its-address-may-say).
+
 ## Choosing a movement
 
 - **`slide-x`** — going INTO something: a list item opened, a card followed, a

package/package.json

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