@jsenv/navi 0.29.52 → 0.29.53

package/docs/AI_INSTRUCTIONS.md

@@ -73,9 +73,28 @@ consistency across the app, not from any single call site.
   and how a paginated `<List.Items>` re-reads its slices without disappearing.
   Read it before adding verbs to `rerunOn`, hiding a list on `loading`, or
   remounting a list with a `key` to refresh it.
+- `docs/error_handling.md` — the two kinds of error and how navi keeps them
+  apart: where an error is shown depending on where it came from (a control's
+  action shows it on what was clicked, a route action replaces the page, a
+  refused value is validation and not an error at all), why a run never rejects,
+  the `__handled_by__` mark that means "this error is on screen somewhere" (and
+  what `preact/debug` throws over your app without it), what becomes of an error
+  nobody displays, and the two rules any error boundary must follow — mark only
+  what you render, reset on the document URL and not only on the rerun. Read it
+  before displaying an error by hand, before writing an error boundary of your
+  own, and before concluding that a dev overlay over a page that already shows
+  its error is a crash.
 - `docs/css_architecture.md` — how Navi's CSS layering works, and the
   supported ways to override component styles (props > CSS variables > direct
   rule overrides, in that preference order).
+- `docs/safe_area.md` — where the app is in the window and what covers it:
+  the two inset families (`--navi-app-inset-*` for what is pinned to an edge,
+  `--navi-safe-area-inset-*` for what flows inside), how an app declares itself
+  narrower than the window, `data-navi-safe-area`, how something new joins the
+  sum, and which viewport is which once a virtual keyboard is open. Read it
+  before hand-writing an offset to clear a `FixedBar`, before reaching for
+  `env(safe-area-inset-*)` directly, and before making an app simulate a phone
+  screen.
 - `docs/scroll.md` — where scrolling happens: what turns `Box`
   `header`/`body`/`footer` on, `FixedBar` space, `List`'s `scroller`, scroll
   inside a `Dialog`/`Popover`, and what a scroll does to hover
@@ -185,6 +204,25 @@ consistency across the app, not from any single call site.
     does this for its current-tab indicator automatically
     (`currentIndicator`), which is why the bar follows a `RouteTravel` swipe
     with no wiring.
+  - the document's rendering is SUSPENDED for the whole update callback, from
+    the capture of the old state to the capture of the new one. Nothing paints,
+    and `requestAnimationFrame` does not tick in there — awaiting a frame
+    inside the callback awaits something that cannot happen, until the browser
+    gives up on the transition entirely (`Transition was aborted because of
+timeout in DOM update`). Await a microtask, a task or a render; never a
+    frame.
+  - that suspension lasts exactly as long as the callback, and **in a
+    sub-document it takes the scrollbar with it**: an iframe's scrollbar is
+    painted by the framed document, so it goes and comes back, shifting the
+    layout by its width. A top-level page is spared — its root scrollbar is the
+    compositor's. So a callback that waits on the network flickers every demo
+    shown in an iframe while the same app, opened on its own, shows nothing.
+    Keep the callback short, and suspect the frame before the code when a
+    scrollbar blinks.
+  - `viewTransition.finished` REJECTS when another transition replaces this one
+    — there is only ever one per document. `.finally()` does not handle a
+    rejection, so an unhandled one is what it leaves behind; `.then(done, done)`
+    is the shape that ends a transition whichever way it went.
 
 If unsure which export solves a problem, check `README.md` first: it names what
 navi provides, area by area. From a name, the built export tells you the API and

package/docs/MOBILE_LAYOUT_PITFALLS.md

@@ -82,8 +82,8 @@ far from the wrapper:
 - **Worse than not sticking: the sticky element is offset downwards.** The rectangle a
   sticky element sticks within is the scroll container's box shrunk by its
   `scroll-padding` (CSS Position L3), and Chromium applies that for an element scroll
-  container. A wrapper carrying `data-navi-fixed-bar-space` has
-  `scroll-padding-top: var(--navi-fixed-bar-space-top)`, so labels come to rest at
+  container. A wrapper carrying `data-navi-safe-area` has
+  `scroll-padding-top: var(--navi-safe-area-inset-top)`, so labels come to rest at
   `scroll-padding-top + top` — a group label floating a hundred pixels below the bar,
   covering the content above it.
 

package/docs/actions.md

@@ -81,7 +81,9 @@ 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). `useActionStatus(action)` gives the whole
+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
 state at once — `{ idle, loading, completed, aborted, error, data, params }` —
 for a component that needs to look at it rather than render it.
 

package/docs/create_and_edit.md

@@ -138,7 +138,9 @@ Two things to know or the screen stays empty:
 - **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
-  refused" with a "try again" that calls `action.rerun()`.
+  refused" with a "try again" that calls `action.rerun()`. Which of the two, and
+  what happens to an error no screen takes:
+  [error_handling.md](./error_handling.md).
 
 ## Two screens, two states
 

package/docs/css_architecture.md

@@ -222,14 +222,16 @@ is placed. Placement is still computed against the real viewport
 (`pickPositionRelativeTo`, in `@jsenv/dom`). That is invisible for anything
 centered on its cross axis — `center`, `bottom`, `top`, which is what a dialog
 does nearly always — but shows for anything anchored to an edge: a
-`positionArea` like `bottom-start`, a `SidePanel`, a fixed bar. Those sit
-against the window's edge rather than the app column's, so they stay on the real
-viewport for now (`side_panel.jsx` restates `--dialog-maxmax-width` as the full
-viewport on purpose).
-
-Making them follow the app column too means narrowing the container rect
-placement is computed against, inside `pickPositionRelativeTo` — worth doing the
-day a side panel or a fixed bar has to live inside a simulated screen.
+`positionArea` like `bottom-start`, a `SidePanel`. Those sit against the
+window's edge rather than the app column's, so they stay on the real viewport
+for now (`side_panel.jsx` restates `--dialog-maxmax-width` as the full viewport
+on purpose).
+
+`FixedBar` is the exception, and shows the shape of the fix: it is pinned to
+`--navi-app-inset-*` (see `docs/safe_area.md`), which describes where the app's
+rectangle is in the window rather than how wide it may be. Making the rest
+follow means narrowing the container rect placement is computed against, inside
+`pickPositionRelativeTo`, to that same rectangle.
 
 Note that an app can already get all of it, placement included, by rendering
 itself in an iframe of the target width: the viewport then genuinely _is_ the

package/docs/error_handling.md

@@ -0,0 +1,174 @@
+# Error handling
+
+There are two kinds of error in an app, and everything here exists to keep them
+apart:
+
+- **what the person can see and act on** — offline, a 404, the server refusing
+  a value. That is data. It must be displayed, and displayed where it makes
+  sense for what just happened;
+- **a bug** — a `TypeError`, a contract broken. That must be as loud as
+  possible, and must never be swallowed by the machinery built for the first
+  kind.
+
+The rule the whole thing rests on: **displaying an error is claiming it.**
+Whatever puts an error on screen says so, and an error nobody claimed is
+treated as a bug. Nothing has to guess which kind it is, and nothing has to
+guess at the wrong moment — the answer is given after the fact by what actually
+rendered.
+
+## Where an error appears depends on where it came from
+
+### Someone just acted — a control's action
+
+A `<Button action>`, a `<Form>` submit: the person did something and is waiting
+for the answer, so the answer belongs where they acted. navi shows it as a
+validation message on the **requester** (the submit button, not the form):
+
+```jsx
+<Button action={GAME.POST.bindParams(values)}>Créer</Button>
+```
+
+- `errorMapping(error)` turns the raw error into what to show: a string, an
+  `Error`, an element, or `{ message, target }` to point the message at another
+  element.
+- The message is a constraint on the control (`navi_action_error`) rather than a
+  render of its own, and it **auto-resets on the next action**: hitting submit
+  again clears it and re-submits, instead of the form being stuck invalid.
+- `actionErrorEffect` changes that: `"throw"` re-throws the error from a layout
+  effect so the nearest `<ErrorBoundary>` takes it (a control cannot throw from
+  an event handler and be caught — see the comment in
+  [use_execute_action.js](../src/action/use_execute_action.js)), and anything
+  else — `"none"` — means the control displays nothing because something else
+  does. `<Details>` uses that: its `<ActionRenderer>` shows the error inside the
+  open panel.
+
+### A screen's data failed — a route action
+
+Nobody clicked; the page simply cannot be drawn. It is the page, or a piece of
+it, that is replaced — by an ancestor, never by a prop on the page. That is what
+`useAsyncData`'s default means: **delegate**. The component says what it renders
+when it has data, and what it cannot render is somebody else's job, up the tree:
+
+```jsx
+<Route>
+  <ErrorBoundary
+    fallback={({ error, resetError }) => (
+      <ErrorScreen error={error} onRetry={resetError} />
+    )}
+  >
+    <Loading fallback={<GameSkeleton />}>
+      <Route route={GAME_ROUTE} element={GamePage} />
+      <Route route={GAMES_ROUTE} element={GamesPage} />
+    </Loading>
+  </ErrorBoundary>
+</Route>
+```
+
+Two things about that shape:
+
+- The boundary goes **outside** the `<Loading>`. A page suspends first and fails
+  second; a boundary placed under the `Suspense` it suspended in is part of the
+  tree being held.
+- It is written **between** a container `<Route>` and its branches, and the
+  container reads through it — the selected branch keeps whatever was written
+  around it. So a boundary can bracket a section of the pages instead of the
+  whole router, without the router having to know it exists.
+
+Inside the component when the error is part of what the screen draws rather than
+a screen of its own:
+
+```jsx
+const [game, loading, error, dismissError] = useAsyncData(gameAction, {
+  loading: true,
+  error: true,
+});
+```
+
+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.
+
+### A value is refused — validation
+
+Not an error at all, and not to be modelled as one: a value the app or the
+browser refuses is a **status on the control**, carried by navi's constraint
+validation. Never throw to reject a value — see `src/control/rules/`.
+
+## What a failing action does
+
+It writes the error into `errorSignal`, moves to `FAILED`, and stops.
+
+**A run never rejects.** `run()`, `rerun()`, `prerun()` settle with the error as
+their value. Nothing about a failed action arrives as a rejected promise, so
+there is no floating rejection to catch and no navigation that has to await one
+to stay quiet. Code that wants the error asks for it — `useAsyncData`,
+`errorSignal`, or an `onError` passed to the run.
+
+Why it does no more than that: **at the instant an action fails, nothing can
+know whether a screen will display it.** A route action runs before its page
+renders — often before that page exists — so any decision made there about "will
+someone show this?" is a guess, and it is wrong for the most common case in the
+app. So no decision is made there.
+
+## Claiming an error: `__handled_by__`
+
+Whatever displays the error sets `error.__handled_by__` (via
+`markErrorAsDisplayedBy` in
+[action_error_report.js](../src/action/action_error_report.js)). That mark means
+one thing and only one: **this error is on screen somewhere.**
+
+It is the same mark the jsenv supervisor reads to keep its dev overlay out of
+the way. It has to exist because `preact/debug` re-throws, in a `setTimeout`,
+**every error a boundary handled** — deliberately, so that React-style dev
+overlays keep working:
+
+```js
+// when an error was handled by an ErrorBoundary we will nonetheless emit an error
+// event on the window object. This is to make up for react compatibility in dev mode
+// and thus make the Next.js dev overlay work.
+```
+
+Without the mark, an app calmly displaying "you are offline" gets a crash
+overlay thrown over it.
+
+Everything navi ships already marks: `<ErrorBoundary>` when it renders its
+fallback, `<ActionRenderer>` / `<Button action>` when they render their error
+branch, `useAsyncData({ error: true })`
+when it hands the error to the component, and a run given an `onError` — asking
+for the error is taking it.
+
+## Claimed by nobody: the report
+
+Unclaimed errors are re-thrown from a macrotask, which makes them ordinary
+unhandled errors — window `error` event, jsenv overlay in dev — pointing at the
+code that produced them.
+
+The delay is the whole mechanism: every render that could display the error
+(Preact's queue, a `Suspense` boundary settling on the failure, the boundary
+above it) happens in microtasks, so one macrotask later the answer is final. A
+screen that mounts much later than that — mounted by something slower than a
+render — gets its error reported anyway; the report is then a duplicate of what
+it shows, never a lie about it. The same error reaching the reporter twice is
+reported once.
+
+## Writing your own boundary
+
+navi's `<ErrorBoundary>` is what a boundary must be, and both of its rules are
+easy to miss when writing another one:
+
+- **Mark only what you actually render.** Marking on catch, before knowing
+  whether anything is displayed, turns a boundary into a bug swallower: a
+  `TypeError` in a component becomes a blank page AND a silent one, since the
+  mark muted the overlay that would have pointed at it. navi's boundary marks
+  just before rendering its fallback, and re-throws untouched when it has no
+  fallback — nothing to display means nothing handled.
+- **Reset on the document URL, not only on the rerun.** Re-running the failed
+  action is one way out; going somewhere else is the common one. A boundary that
+  only watches the action stays in place of every page after the failure,
+  including the ones that would render fine.
+
+The one reason to write your own: **filtering what you take.** navi's takes
+everything its subtree throws. An app that wants its own bugs to stay visible
+displays only what is data to it — an error carrying an HTTP status, its own
+`OfflineError` — and re-throws the rest **unmarked**, so the overlay still does
+its job.

package/docs/navigation.md

@@ -190,16 +190,37 @@ Two shapes for a section, and which one applies is decided by the URL:
 
 ### Loading data
 
-A branch loads with `action`, and shows its states with the usual boundaries:
+A page reads its data from a route action through `useAsyncData` and says only
+what it renders; what it cannot render is delegated to an ancestor — waiting to
+`<Loading>`, failing to `<ErrorBoundary>`. Both are written **between** the
+container and its branches, and the container reads through them, so a whole
+section of pages shares one:
 
 ```jsx
-<ErrorBoundary fallback={(error, { resetError }) => …}>
-  <Suspense fallback={<p>Loading…</p>}>
-    <Route route={GAME_ROUTE} action={loadGame} element={(game) => <GamePage game={game} />} />
-  </Suspense>
-</ErrorBoundary>
+<Route>
+  <ErrorBoundary
+    fallback={({ error, resetError }) => (
+      <ErrorScreen error={error} onRetry={resetError} />
+    )}
+  >
+    <Loading fallback={<GameSkeleton />}>
+      <Route route={GAME_ROUTE} element={GamePage} />
+      <Route route={GAMES_ROUTE} element={GamesPage} />
+    </Loading>
+  </ErrorBoundary>
+  <Route fallback element={NotFoundPage} />
+</Route>
 ```
 
+The order matters: the boundary goes **outside** the `<Loading>`. A page
+suspends first and fails second, and a boundary placed under the `Suspense` it
+suspended in is part of the tree being held.
+
+A branch selected inside a wrapper keeps it — the container renders the active
+branch alone, wrapper included, so `<Loading>`/`<ErrorBoundary>` can bracket a
+subset of the branches rather than the whole router. What happens to a failure
+no boundary takes: [error_handling.md](./error_handling.md).
+
 ## Links and tab rows
 
 `<Link route={…}>` builds its href from the route and knows on its own whether it

package/docs/safe_area.md

@@ -0,0 +1,161 @@
+# The safe area: where the app is, and what covers it
+
+An app is rarely given the whole window. A bar is pinned over it, the device
+eats a corner, the app itself pretends to be a phone inside a desktop window.
+Every component that must stay clear of all that would otherwise have to learn
+what "all that" is — and each one would learn a different subset.
+
+So navi publishes it, once, as CSS variables on `<html>`. Whoever reduces the
+visible region says so; whoever must avoid it reads the sum and never learns
+what is covering it.
+
+## The two levels
+
+There are two rectangles, and confusing them is the mistake this file exists to
+prevent.
+
+```
+┌────────────────────── window ───────────────────────┐
+│      │                                     │        │
+│ band │ ┌───────── FixedBar top ─────────┐  │  band  │  ← --navi-app-inset-*
+│      │ ├────────────────────────────────┤  │        │
+│      │ │                                │  │        │
+│      │ │       the safe area            │  │        │  ← --navi-safe-area-inset-*
+│      │ │                                │  │        │
+│      │ └──────── FixedBar bottom ───────┘  │        │
+└─────────────────────────────────────────────────────┘
+```
+
+**`--navi-app-inset-{top,right,bottom,left}`** — from the window's edges to the
+app's own rectangle. What is _pinned to an edge_ is pinned to this.
+
+**`--navi-safe-area-inset-{top,right,bottom,left}`** — from the window's edges
+to the band left free _inside_ that rectangle. What _flows, scrolls or gets
+painted_ keeps to this.
+
+Two and not one, because a fixed bar is one of the things that reduce the free
+band: placed against the band it contributes to, it would push itself off its
+own edge. What is anchored and what is anchored-inside cannot be the same
+number.
+
+Level 2 is level 1 plus everything on that edge:
+
+```css
+--navi-safe-area-inset-top: calc(
+  var(--navi-app-inset-top) +
+    max(env(safe-area-inset-top), var(--navi-fixed-bar-space-top))
+);
+```
+
+`max()` and not a sum between the notch and the bars: a bar pinned to an edge
+already reaches under the notch and counts it in its own height, so adding both
+would reserve it twice.
+
+Declared in `src/layout/safe_area.js`.
+
+## Using it
+
+### An app that is narrower than the window
+
+One line, and nothing names a component:
+
+```css
+:root {
+  --navi-app-max-width: 600px;
+}
+```
+
+The bands fall out of it (centered), `--navi-app-width` follows, and `FixedBar`
+pins itself to the column's edges rather than the glass. An app wanting them
+uneven writes `--navi-app-inset-left` / `-right` directly instead.
+
+Do **not** get this by mounting empty `FixedBar area="left"/"right"`: they would
+reserve the room, but the app's rectangle would still be the whole window, so
+dialogs and popovers would keep sizing themselves against 1500px.
+
+### Something that scrolls under the furniture
+
+Mark it, and it gets both paddings:
+
+```html
+<div id="main" data-navi-safe-area>…</div>
+```
+
+Two distinct things must be given back, and forgetting the second is the classic
+bug — `padding`, or the last screenful stays unreachable under the bar; and
+`scroll-padding`, or everything the browser scrolls _to_ (an anchor,
+`scrollIntoView()`, a field taking focus, a restored position) lands _behind_ it.
+The padding does not help there: it moves the content, not the place the browser
+brings its target to.
+
+Which element scrolls is the app's business, so navi never picks one. `:root`
+gets the `scroll-padding` unconditionally, since the document is the scrollport
+in the common case.
+
+Beware of making that container scrollable by accident — see
+`MOBILE_LAYOUT_PITFALLS.md`.
+
+### Reading it yourself
+
+`var(--navi-safe-area-inset-bottom)` in any rule. It is always declared, whether
+or not the app ever mounts a bar.
+
+Reading it from **JS** takes a probe: an unregistered custom property keeps its
+`calc()` unresolved through `getComputedStyle`. Give a hidden box
+`height: var(--navi-safe-area-inset-bottom)` and measure it — see
+`src/layout/demos/fixed_bar/keyboard.html`.
+
+### Putting something new into it
+
+Publish what you take on one edge, into that edge's slot. That is the whole
+contract — a native banner, an OS strip, anything an app invents joins the sum
+without a single component learning it exists. `FixedBar` is the worked example:
+it measures its own border box (notch included) and writes
+`--navi-fixed-bar-space-*` (`src/layout/fixed_bar/fixed_bar_space.js`).
+
+## What already reads it
+
+Pointers, not a list to keep in sync — grep `--navi-safe-area-inset` for the
+truth:
+
+- `FixedBar` pins itself to `--navi-app-inset-*`.
+- `List` offsets its sticky group labels when `scroller="document"`, so a label
+  comes to rest in front of the bar and not behind it.
+- `RouteTravel` clips the pictures of a travel to the safe area. It has to: a
+  view transition paints in the top layer, where no `overflow` of the document
+  reaches it, and the box pages travel in runs _under_ the bars by design — so
+  a page scrolled by one pixel would be watched painting over them.
+
+## The trap: which viewport
+
+Three heights are in play and they are not the same one.
+
+| what                             | shrinks when the keyboard opens |
+| -------------------------------- | ------------------------------- |
+| `window.innerHeight` / `100dvh`  | no                              |
+| `visualViewport.height`          | yes                             |
+| `--navi-vvh` (tracks the visual) | yes                             |
+
+`position: fixed` — so every `FixedBar` — is laid out against the **layout**
+viewport. A bottom bar therefore stays at the bottom of a window the keyboard is
+covering: it ends up _behind_ the keyboard, and no inset says so, because
+nothing reduced the layout viewport.
+
+The consequence for anything measuring against the insets: mix the two families
+and you get a drift that only appears with a keyboard open. `getBoundingClientRect`
+is in layout-viewport coordinates, so what is compared to it must be too
+(`100dvh`), while `--navi-app-*` derives from `--navi-vvh` because what navi
+_sizes_ must fit what is actually visible.
+
+`src/layout/demos/fixed_bar/keyboard.html` puts all of these on screen at once
+and turns the bottom bar's number red when it goes under the keyboard. On a
+phone; a desktop has no keyboard to open.
+
+## Current limitation
+
+Popup **placement** does not follow level 1 yet: `pickPositionRelativeTo` (in
+`@jsenv/dom`) still computes against the real viewport. Invisible for anything
+centered on its cross axis — which is what a dialog does nearly always — but a
+`positionArea` like `bottom-start` or a `SidePanel` sits against the window's
+edge rather than the app column's. See "Current limitations" in
+`css_architecture.md`.

package/docs/scroll.md

@@ -71,14 +71,19 @@ Reference: `src/box/box.jsx` (the `[data-scrollable]` CSS),
 
 The default case: nothing to do, the document scrolls.
 
-The case that needs wiring is **fixed bars** — a top bar, a bottom nav, the
-normal shape of a mobile app. `FixedBar` measures its own height (safe area
-included) and publishes it on `<html>`:
+The case that needs wiring is whatever covers the viewport — **fixed bars** (a
+top bar, a bottom nav, the normal shape of a mobile app), the device's own
+notch, a band an app reserves for itself. Each publishes what it takes, navi
+adds them up on `<html>`, and the content reads the sum:
 
 ```
---navi-fixed-bar-space-top / -bottom / -left / -right
+--navi-safe-area-inset-top / -right / -bottom / -left
 ```
 
+`docs/safe_area.md` holds the concept: the two levels, how an app declares
+itself narrower than the window, and how something other than a bar joins the
+sum.
+
 Two distinct things must be given back to the content, and forgetting the
 second one is the classic bug:
 
@@ -94,7 +99,7 @@ scrolls — which element that is, is the app's business, so navi does not pick:
 
 ```html
 <!-- on the container that scrolls under the bars -->
-<div id="main" data-navi-fixed-bar-space>…</div>
+<div id="main" data-navi-safe-area>…</div>
 ```
 
 **Do not make that container scrollable by accident.** An `overflow-x: auto`

package/package.json

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