@jsenv/navi 0.29.417 → 0.29.419

package/docs/data_states.md

@@ -27,10 +27,9 @@ whether a missing list is a skeleton, a sentence or an illustration.
 
 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:
+`<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                  |
 | --------------- | ------------------------- | ---------------------------- |
@@ -44,24 +43,19 @@ 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 leaves with it and is reopened when it returns, 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.
+That 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 leaves and is reopened, a scroll position is lost, half-typed text is
+gone, and the retry button the component was offering disappears with it.
+`error: true` says the same thing about failure: 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. Inside a popup that boundary is the
-popup's own — `{ loading: true }`, or a `<Loading>` inside the popup — never
-the one above the page: a suspension landing there takes the popup away with
-the page it copies, and the popup does not open at all (see
-[popup_open.md](./popup_open.md#a-popup-that-loads-data)).
+popup's own, never the one above the page
+([popup_open.md](./popup_open.md#a-popup-that-loads-data)).
 
 ## `data` and `loading` are independent
 
@@ -75,28 +69,28 @@ means something different:
 | set         | `false`   | settled                       | the content              |
 | `undefined` | `false`   | nothing here, nothing coming  | an empty state           |
 
-Two consequences worth stating out loud.
-
 **A first load is only a first load when nothing is known.** A resource `GET`
 whose params name a row the store already holds — read earlier by a `GET_MANY`,
-a relation, a list — starts on the second line, not the first: the row is drawn
-and the request goes out behind it. The response replaces it, and a failure
-lands beside it like any refresh failure. A `GET` of a row the store lacks
-still starts on the first line, so what is drawn is never a different row. A
-row known from the previous page load counts too, when the resource asks for
-it: [`persist`](./resource.md#persist-the-last-answer-drawn-again-after-a-reload)
-puts a reload on the second line as well.
+a relation, a list — starts on the second line, not the first: the row is
+drawn, the request goes out behind it, and a failure lands beside it like any
+refresh failure. A row known from the previous page load counts too, when the
+resource asks for it:
+[`persist`](./resource.md#persist-the-last-answer-drawn-again-after-a-reload)
+puts a reload on the second line as well. A `GET` bound through a signal — a
+route action, a `bindParams` holding one — is on the second line when the signal
+moves to params it has not answered yet, with the previous params' row: its
+`data` stays that row until the new answer lands, whether or not the store holds
+the new one.
 
 **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 list is no exception. A plural action — `GET_MANY`, a `.many()` or
-`.scopedMany()` read — has no data until its first answer: `undefined`, not
-`[]`. An empty array is an answer ("the collection is empty"), and the two are
-different facts drawn differently: a skeleton for the first, an empty state for
-the second. So a component reading a plural action must accept `undefined`
-before dereferencing (`items?.map`, `items ?? []`, or the branch above).
+for a checkbox ticked on one row of a list, the whole list goes. A list is no
+exception: a plural action — `GET_MANY`, a `.many()` or `.scopedMany()` read —
+has no data until its first answer, `undefined`, not `[]`. An empty array is an
+answer ("the collection is empty"), and the two are drawn differently: a
+skeleton for the first, an empty state for the second. So a component reading a
+plural action accepts `undefined` before dereferencing (`items?.map`,
+`items ?? []`, or the branch below).
 
 **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
@@ -112,16 +106,19 @@ if (items === undefined) {
 return <ItemList items={items} busy={loading} />;
 ```
 
+`loading` is not proof that a request is out, either: an action holding params
+that nothing started — idle, or aborted — reads `loading: true`, so a skeleton
+told it shimmers until something runs that action.
+
 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.
+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.
+**Knowing the count beforehand beats guessing it.** A screen that already knows
+how many rows are coming — 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.
 
 ## An error is a message on the screen, not the screen
 
@@ -156,7 +153,7 @@ 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
+## See also
 
 - [error_handling.md](./error_handling.md) — the two kinds of error, where each
   is shown, and what happens to one nobody displays.

package/docs/dialog_shape.md

@@ -16,11 +16,10 @@ Where a `Dialog` sits and how big it gets. What happens _inside_ it (scrolling,
 
 ## A dialog is sized by its content, never by a `width`
 
-`Dialog` has no `width` prop of its own (one handed to it is `Box`'s, still
-under the ceiling below), and that is the whole design: a dialog is a surface
-laid over the app, and what it holds is what knows how wide it should be. What
-a caller states are **bounds** — a floor under a dialog too narrow for its
-content, a ceiling over one that would sprawl:
+`Dialog` has no `width` prop of its own, and that is the whole design: a dialog
+is a surface laid over the app, and what it holds is what knows how wide it
+should be. What a caller states are **bounds** — a floor under a dialog too
+narrow for its content, a ceiling over one that would sprawl:
 
 | what you want to say                    | how                       |
 | --------------------------------------- | ------------------------- |
@@ -29,32 +28,26 @@ content, a ceiling over one that would sprawl:
 | "as wide as the container allows"       | `expandX` / `expandY`     |
 | "as wide as the control that opened it" | `sizeFromAnchor` (opt-in) |
 
-`sizeFromAnchor` is off by default and that is deliberate: unlike a `Popover`,
-a dialog is not attached to what opened it, so following that element's box is
-a choice, not the norm. It only ever sets a **floor**
+`sizeFromAnchor` is off by default and that is deliberate: unlike a `Popover`, a
+dialog is not attached to what opened it, so following that element's box is a
+choice, not the norm. It only ever sets a **floor**
 (`--anchor-width`/`--anchor-height`), never a width.
 
 ## The ceiling nobody sets
 
 Above every bound a caller passes there is one navi always applies: the
-container, minus `marginWithContainer` on both sides
-(`--dialog-maxmax-width` / `--dialog-maxmax-height`). It is not a default that
-a larger `maxWidth` overrides — it wins, always. A `minWidth` too large for the
-screen is clamped by it too, so **no combination of props can produce a dialog
-that overflows its container.** Stop trying to defend against that case.
-
-Two consequences worth knowing before writing CSS of your own:
-
-- the caps are applied to the dialog's **size**, not merely to its position.
-  That is what makes a centered dialog follow the mobile virtual keyboard for
-  free: the ceiling is expressed against the app's live screen
-  (`--navi-app-width`/`--navi-app-height`, which track the visual viewport), so
-  the browser reflows the dialog as the keyboard opens. Nothing to wire.
-- "the container" is the **app's own screen** for `layer="top"` — the visual
-  viewport minus the app's bands, whether `--navi-app-max-width` centers them
-  or the app writes `--navi-app-inset-*` itself (see
-  [`safe_area.md`](./safe_area.md)) — and the positioned ancestor for
-  `layer="local"`.
+container, minus `marginWithContainer` on both sides. It is not a default that a
+larger `maxWidth` overrides — it wins, always, and a `minWidth` too large for
+the screen is clamped by it too, so **no combination of props can produce a
+dialog that overflows its container.** Stop trying to defend against that case.
+
+The caps are applied to the dialog's **size**, not merely to its position, and
+expressed against the app's live screen (`--navi-app-width`/`--navi-app-height`,
+which track the visual viewport): the browser reflows a centered dialog as the
+mobile keyboard opens, with nothing to wire. "The container" is the **app's own
+screen** for `layer="top"` — the visual viewport minus the app's bands (see
+[`safe_area.md`](./safe_area.md)) — and the positioned ancestor for
+`layer="local"`.
 
 ## One dialog, two shapes
 
@@ -69,9 +62,9 @@ below it, and the question and the field stay where the finger found them.
 reads and taps (a list, a couple of buttons, a confirmation) and that holds
 nothing raising a keyboard. A bottom sheet one types into is reflowed into the
 strip left above the keyboard at every keystroke, and the mistake is silent on
-the desktop the author tests on — which is why the safe edge is the default
-and the thumb-first one is the opt-in, and why a `"bottom"` sheet found holding
-a field is warned about in dev, on any screen.
+the desktop the author tests on — which is why the safe edge is the default, and
+why a `"bottom"` sheet found holding a field is warned about in dev, on any
+screen.
 
 ```jsx
 <Dialog dockedOnSmallTouchScreen />          // top: the keyboard cannot reach it
@@ -82,36 +75,32 @@ The edge is the prop's own value rather than `positionArea` because
 `positionArea` places _both_ shapes: `positionArea="bottom"` also pins the
 centered box to the bottom of a desktop window.
 
-Both halves of the name matter. Touch alone would dock a tablet or a kiosk
-panel — a whole screen away from where the finger just tapped. Size alone would
-dock a narrow desktop window, which is still a mouse. `smallTouchScreenSignal`
-answers both, by shape rather than by a box of maximum dimensions (a phone is a
-narrow slab, in either orientation), and it is **live**: turning the phone
-re-resolves the dialog.
-
-What docking supplies — defaults only, so any single axis of the sheet can be
-adjusted without giving up the rest:
-
-| supplied              | value    | why                                                  |
-| --------------------- | -------- | ---------------------------------------------------- |
-| `positionArea`        | the edge | `"top"` unless the prop says `"bottom"`, see above   |
-| `marginWithContainer` | `0`      | a sheet is flush, or it is not a sheet               |
-| `expandX`             | `true`   | container-wide, same reason                          |
-| `scrollCapture`       | `true`   | a drag past the sheet's edge must not reach the page |
-
-A `layer="top"` dialog flush with an edge of the screen — a docked sheet,
-anything with `marginWithContainer={0}` — keeps the band the device
-reserves there (`env(safe-area-inset-*)`: the notch, the home indicator,
-Safari's floating bar). The surface still reaches the edge; what it holds stops
-at the band. Only the device's own inset: the dialog is in front of the app's
-fixed bars, so `--navi-safe-area-inset-*`, which counts them too (see
-[`safe_area.md`](./safe_area.md)), is not what it reads.
-
-Plus a swipe-to-close through the edge the sheet rests on (down for a bottom
-sheet, up for a top one), held by the sheet's `header` (a `Box` with the
-`header` prop) and by anything carrying `data-swipe-grip` — never by the whole
-sheet, so a board something is dragged across keeps its own gestures. See
-[`drag_to_travel.md`](./drag_to_travel.md).
+Both halves of the name matter: touch alone would dock a tablet or a kiosk panel,
+size alone a narrow desktop window, which is still a mouse.
+`smallTouchScreenSignal` answers both, by shape rather than by a box of maximum
+dimensions (a phone is a narrow slab, in either orientation). A `Dialog` follows
+it live: turning the phone re-resolves it. A `Picker` decides popover or dialog
+again at each opening, but a `Popup` decides once, for its lifetime — one
+mounted as a popover never docks.
+
+What docking supplies are defaults — `positionArea` (the edge),
+`marginWithContainer={0}` (a sheet is flush, or it is not a sheet), `expandX`
+and `scrollCapture` — so any single axis of the sheet can be adjusted without
+giving up the rest.
+
+A `layer="top"` dialog flush with an edge of the screen — `marginWithContainer`
+at `0` with a `positionArea` on that edge or an `expand` across it, as a docked
+sheet is — keeps the band the device reserves there (`env(safe-area-inset-*)`:
+the notch, the home indicator, Safari's floating bar): the surface reaches the
+edge, what it holds stops at the band. A centered dialog with a `0` margin
+touches no edge, and gets no band. Only the device's own inset: the dialog is in
+front of the app's fixed bars, so `--navi-safe-area-inset-*`, which counts them
+too (see [`safe_area.md`](./safe_area.md)), is not what it reads.
+
+A docked sheet closes by a swipe through the edge it rests on, held by its
+`header` and by anything carrying `data-swipe-grip` — never by the whole sheet,
+so a board something is dragged across keeps its own gestures (see
+[`drag_to_travel.md`](./drag_to_travel.md)).
 
 **`expandY` (or `expand`) cancels docking outright.** A dialog already filling
 the height touches both edges; all docking could still do is take away the
@@ -131,17 +120,12 @@ Both halves are written together, and each applies where it means something:
 <Dialog dockedOnSmallTouchScreen minWidth="12rem" maxWidth="16rem">
 ```
 
-| prop        | centered box | docked sheet                                          |
-| ----------- | ------------ | ----------------------------------------------------- |
-| `maxWidth`  | applies      | **withdrawn** — the sheet is container-wide           |
-| `minWidth`  | applies      | stops mattering (the floor is below full width)       |
-| `maxHeight` | applies      | applies — a sheet is content-tall, not container-tall |
-| `minHeight` | applies      | applies                                               |
-
 `maxWidth` is an answer about the _centered_ shape: "do not sprawl on a wide
-window". A sheet spanning its container's full width, flush against the two
-side edges, **is** the docked mode — so docking withdraws that ceiling rather
-than capping the sheet with it. The container ceiling still holds, as always.
+window". A sheet spanning its container's full width **is** the docked mode, so
+docking withdraws that ceiling rather than capping the sheet with it; the
+container ceiling still holds. `minWidth` stops mattering there (the floor is
+below full width), and `maxHeight`/`minHeight` keep applying — a sheet is
+content-tall, not container-tall.
 
 > **Trap: do not re-derive the docking condition in the app.** This looks like
 > the way to say it and is subtly wrong:
@@ -156,18 +140,15 @@ than capping the sheet with it. The container ceiling still holds, as always.
 > dialog that also sets `expandY` never docks, so the cap must never be
 > withdrawn there, and the line above withdraws it anyway. Beyond being wrong,
 > it duplicates a condition navi owns at every call site (it drifts the day
-> "docked" gains a rule), and it reads as a bug: it says nothing about docked
-> sheets to the next person. State both bounds plainly and let the dialog
-> resolve its own shape.
+> "docked" gains a rule), and it says nothing about docked sheets to the next
+> person. State both bounds plainly and let the dialog resolve its own shape.
 
 ## `expand` is not "docked", and `expandX={false}` is not "do not sprawl"
 
 `expandX`/`expandY` mean "grow to the ceiling" — the container ceiling above,
 capped in turn by `maxWidth`/`maxHeight` when they apply. `expand` is the
-shorthand for both.
-
-Since docking _supplies_ `expandX`, passing it explicitly takes the caller out
-of that default:
+shorthand for both. Since docking _supplies_ `expandX`, passing it explicitly
+takes the caller out of that default:
 
 ```jsx
 // The sheet stops being flush: a floating box against its edge of the screen.
@@ -177,8 +158,7 @@ of that default:
 That is consistent — an explicitly passed prop wins over a docked default — and
 it is still the trap, because the two props read as answering different
 questions (one about the centered shape, one about the phone) when they answer
-the same one. If what you meant was "cap the centered box", that is `maxWidth`,
-and docking withdraws it on its own.
+the same one. "Cap the centered box" is `maxWidth`.
 
 ## `marginWithContainer` decides the gap AND the ceiling
 
@@ -190,74 +170,51 @@ It defaults to a share of whatever holds the dialog (`3appw` for `layer="top"`,
 `3cqw` for `layer="local"`) and accepts a number of pixels, a viewport length —
 `appw`/`apph` being the app's own screen, `vvw`/`vvh` the visual viewport, which
 shrinks when the keyboard opens — or a container length (`cqw`/`cqh`). A
-spacing token (`"s"`, `"m"`…) cannot be resolved to pixels here: navi warns
-and places the dialog flush.
-Pass `0` for something meant to sit flush (a side panel), and note that docking
-already passes `0` for you.
+spacing token (`"s"`, `"m"`…) cannot be resolved to pixels here: navi warns and
+places the dialog flush. Pass `0` for something meant to sit flush (a side
+panel); docking already passes it.
 
 ## Holding a size while the dialog is open
 
-`sizing="frozen"` measures the dialog once and holds it until it closes; what
-no longer fits — or no longer fills it — becomes the scroll's business. It is
-for a surface acted upon while it is open: marking a notification read,
-emptying a queue, swapping between two slides of different heights. The row
-being aimed at must not move under the finger.
-
-Two things make it safe to reach for:
-
-- the freeze writes a `width`/`height`, never a `min-*` — the caps above keep
-  winning, so a frozen dialog still fits when the phone is turned;
-- the measure is taken at the first render where the prop says `"frozen"`, so a
-  dialog opening on skeletons says `sizing={loading ? "auto" : "frozen"}` and
-  is measured once the real content has arrived. Closing releases it.
+`sizing="frozen"` measures the dialog once and holds it until it closes — for a
+surface acted upon while it is open (emptying a queue, swapping between two
+slides of different heights), where the row being aimed at must not move under
+the finger. The caps above keep winning; a dialog opening on skeletons says
+`sizing={loading ? "auto" : "frozen"}`, to be measured once the real content has
+arrived.
 
 ## A `layer="local"` dialog answers to its container
 
-`layer="top"` (the default) is a real `<dialog>` in the browser's top layer,
-placed against the screen and clipped by nothing — modal, with everything
-behind made inert, unless `backdrop={false}` says otherwise (see
-[`popup_backdrop.md`](./popup_backdrop.md)). `layer="local"` stays in normal
-document flow, confined to and clipped by its own positioned ancestor.
+`layer="top"` (the default) is placed against the screen and clipped by nothing;
+`layer="local"` stays in normal document flow, confined to and clipped by its
+own positioned ancestor, which every bound is then measured against (the
+default margin in container units). Its container's scroll is locked while it
+is open — its backdrop covers the scrollport, not the scrolled content — and
+`scrollCapture` extends that lock to the whole page.
 
-For a **docked** dialog that is the choice of which edge the sheet rests on:
-`layer` names the container, and docking makes the sheet flush and full width
-against it. A sheet meant for the bottom of the screen is `layer="top"`, even
-when the page behind it must stay live — that is `backdrop={false}`, not
-`layer="local"`.
-
-For the shape, that swaps what every bound is measured against: the container
-becomes that ancestor's box, read through
-`--container-position-remaining-width`/`-height`, and the default margin is
-read in container units. Its own container's scroll is always locked while it
-is open — its backdrop covers the scrollport, not the scrolled content, so
-scrolling would slide the dialog away and reveal what the backdrop does not
-cover. `scrollCapture` is what extends that lock to the whole page.
-
-One accepted limitation, not an oversight: a dialog that is not modal —
-`layer="local"`, or `backdrop={false}` — **cannot** be dismissed by the
-hardware/gesture back button. No web API hooks into that outside the browser's
-own modal-dismissal stack, which only a genuine `showModal()` element joins.
+For a **docked** dialog, `layer` is the choice of what the sheet rests against.
+A sheet meant for the bottom of the screen is `layer="top"`, even when the page
+behind it must stay live — that is `backdrop={false}`, not `layer="local"`.
+Whether a dialog is modal, and what one that is not gives up (the back button),
+is [`popup_backdrop.md`](./popup_backdrop.md#is-there-a-backdrop-at-all)'s.
 
 ## Reaching all of this through a `Picker` or a `SplitButton`
 
-A picker's popup is a popover or a dialog depending on the screen, so it
-exposes both sets of bounds under prefixed names, and they mean exactly what
-they mean on `Dialog` itself:
-
-`dialogMinWidth`, `dialogMinHeight`, `dialogMaxWidth`, `dialogMaxHeight`,
-`dialogExpand`, `dialogExpandX`, `dialogExpandY`, `dialogSizeFromAnchor`,
-`dockedOnSmallTouchScreen`, `marginWithContainer` — plus `popoverMaxHeight` and
-`popupWidthFitContent` for the other shape.
+A picker's popup is a popover or a dialog depending on the screen, so it exposes
+the dialog's bounds under prefixed names (`dialogMinWidth`, `dialogMaxWidth`,
+`dialogExpandX`…), next to `dockedOnSmallTouchScreen` and `marginWithContainer`.
+They mean what they mean on `Dialog`, with one exception: `dialogSizeFromAnchor`
+makes the trigger's width the dialog's ceiling as well as its floor (see
+[popup_lift.md](./popup_lift.md#same-width-or-a-wider-box)).
 
-`SplitButton` forwards the same set (minus `dialogSizeFromAnchor`) to the picker
-it wraps. Anything not in
-that set lands on the split button's own box instead — so a prop that seems to
-do nothing to the menu is worth checking against that list first (see
-`POPUP_PROP_SET` in `src/control/input/split_button.jsx`).
+`SplitButton` forwards its popup props to the picker it wraps, and its menu is a
+popover unless it says `mode="dialog"` — its `dialog*` props do nothing until
+then. Anything not in its `POPUP_PROP_SET` (`src/control/input/split_button.jsx`)
+lands on the split button's own box instead, so a prop that seems to do nothing
+to the menu is worth checking against that list first.
 
 ---
 
 Reference: `src/layout/dialog.jsx` (the stylesheet at the top of the file holds
-the cap arithmetic), `src/layout/responsive.js` (`smallTouchScreenSignal`),
-`src/control/picker/picker_custom.jsx` (how the picker hands `dialogMin*`/
-`dialogMax*` to the dialog element), and `src/layout/demos/1_dialog_demo.html`.
+the cap arithmetic), `src/layout/responsive.js` (`smallTouchScreenSignal`), and
+`src/layout/demos/1_dialog_demo.html`.