@jsenv/navi 0.29.142 → 0.29.144

package/docs/AI_INSTRUCTIONS.md

@@ -112,6 +112,9 @@ consistency across the app, not from any single call site.
   overrides, in that preference order), and what a popup inherits from the
   element that opened it: which tokens a surface takes back, the color
   keywords and their `-mix` ratios, and why a ratio is a `:root` knob only.
+  Read its first section before writing any `import.meta.css`: the build parses
+  that css, and a `${}` the build cannot read costs the whole stylesheet its
+  comments, its transpilation, its `url()` assets and its minification.
 - `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
@@ -153,6 +156,16 @@ consistency across the app, not from any single call site.
   given a `ui` draws no placeholder of its own. Read it before putting a
   `BadgeList` in a picker's `ui`, before wrapping its fallback in a `Badge`,
   and before setting `maxLines` on the list rather than on the picker.
+- `docs/state_binding.md` — the rule the whole API rests on: state navi shows is
+  BOUND (`signal`), not copied back by a callback. The three shapes an
+  application ever has to say (`signal` / `action` / `command` + `commandFor`),
+  the four ways the same mistake is written (`onCurrentChange`, `uiAction`,
+  `onClick` and `onOpen`/`onClose` all writing a signal), why a binding is not
+  merely shorter (it is written by every gesture, it moves the component when
+  written, and it goes through the interaction gate), what is left for the
+  callback, and what to conclude when the state being wired has no prop for it —
+  a parallel copy, or a binding navi is missing. Read it before writing any
+  handler whose body only assigns state.
 - `docs/control_value.md` — who holds a control's value: nobody, a bound
   `signal` (two-way, in both directions), or you (`value`/`checked`). What
   `signal` + `defaultValue` says, what a signal holds for each kind of control,
@@ -282,9 +295,13 @@ consistency across the app, not from any single call site.
   is given back the offset it was read at, and only when the row owns the
   document scroll), a back arrow that stays inside the app (`useCanNavBack()` /
   `navBack({ fallback })`), and the few cases where tabs are legitimately not
-  URLs. Read it before writing any routing code — the
-  position of the user belongs in the URL by default, and that decision is
-  not retrofittable.
+  URLs. It also holds the middle answer — a position READ from the URL and
+  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.
 - 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

@@ -107,10 +107,47 @@ obvious fix does not work — a `useEffect` in that same component that would
 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.
+came in by — or the component owns its request: a folding panel, a slice a
+button asks for. That second one is `{ run: true }`, said in the same line that
+reads the data:
+
+```jsx
+// asks for it if nobody did, from the render that reads it
+const [members] = useAsyncData(membersAction, { run: true });
+```
+
+It starts the action from the render rather than from an effect, which is what
+makes it work at all: a suspended component has no effects, so a `run()` written
+in one would be waiting for itself. Everything else is unchanged — `loading` and
+`error` mean what they mean everywhere, delegated by default, handled inline
+when asked for — and running an action twice costs nothing, so nothing has to
+be guarded.
+
+**`{ run: true }` is the fallback, not the shape to reach for.** A route action
+is asked for when the ADDRESS changes, with everything else that address needs;
+this one cannot start before the component that draws it exists, which is a
+render late at best and a gesture late in a popup. So it is for data nothing
+else can ask for — a parameter chosen inside the component and dying with it —
+and it says so at the call site, where a hand-written `useEffect` + `run()` said
+nothing at all.
+
+Outside a component — a request the app owns rather than a component —
+`actionRunEffect(action, () => …)` is that same run declared once: it runs on
+the first truthy params, reruns when they change, aborts when they go false. It
+is the very machinery `routeAction` is built on.
+
+**Which of the two it is, is decided by the parameter, not by what draws it.**
+If the parameter is in the address — a path param, a search param bound to a
+`stateSignal` — the data belongs to the screen, and it is a `routeAction`, even
+when a popup is the only thing that draws it. The component owns its request
+only when the parameter is chosen inside it and dies with it. A popup is never
+by itself a reason to own one: being open can be bound too — to a signal, to the
+history entry, to the address — and the data of a popup that binds it is a route
+action like any other (see
+[popup_open.md](./popup_open.md#a-popup-that-loads-data)). Getting this wrong is
+invisible at the call site and expensive on screen: the request then leaves with
+the gesture instead of with the screen, one waterfall behind everything else the
+address needed.
 
 `{ 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
@@ -268,6 +305,9 @@ changes do exactly that).
 
 ## See also
 
+- [state_binding.md](./state_binding.md) — `signal`, `action` or
+  `command` + `commandFor`: the three shapes, and the callback that only
+  remembers
 - [resource.md](./resource.md) — actions created from REST callbacks, and the
   store behind them
 - [resource_with_params.md](./resource_with_params.md) — `withParams()` and

package/docs/control_value.md

@@ -243,7 +243,10 @@ that is a navi control goes through the same state controller, and the same
 
 `SlideContainer` takes one too, though it is layout rather than a control: the
 area it shows is a piece of state like any other, and binding it is what lets
-something else read where the slides are — or move them by writing it.
+something else read where the slides are — or move them by writing it. Bind it
+to a `stateSignal` a route declares as a search param and the area is in the
+address, with no route per slide — see
+[navigation.md](./navigation.md#a-slidecontainer-in-the-url-a-position-that-is-not-a-place-one-came-from).
 
 Inside a `List selectable` you can bind the list, or give each `List.Item` its
 own `selected` — but not expect the two to arbitrate. An item that declares
@@ -348,6 +351,9 @@ directions; it just has nothing extra to say.
 
 ## See also
 
+- [state_binding.md](./state_binding.md) — the same rule beyond controls:
+  a `SlideContainer`'s area, a popup being open, the position in the app — all
+  bound rather than copied back by a callback
 - [form_changed.md](./form_changed.md) — what a form makes of each of these:
   which fields it counts as already answered, and when it sends nothing
 - [control_object.md](./control_object.md) — several controls reading as one

package/docs/css_architecture.md

@@ -10,6 +10,224 @@ Navi components are styled through a combination of CSS custom properties (varia
 
 ---
 
+## Where CSS lives: `import.meta.css`
+
+A navi component declares its stylesheet with `import.meta.css`, and the build
+**parses that css**. Everything below depends on it staying parseable.
+
+```js
+const css = /* css */ `
+  .navi_button {
+    height: var(--button-height);
+  }
+`;
+import.meta.css = css;
+```
+
+The `css` constant may be declared next to the assignment or anywhere in the same
+module — the build follows the name to where it is declared. What it cannot
+follow is a name coming from **another** module: `import.meta.css = importedCss`
+is read only when the constant belongs to the module doing the assignment.
+
+**Keep the assignment in a render, not at module scope.** A component's
+stylesheet is adopted when the component first renders, so a page that never
+renders it never carries it, and a bundler that sees no caller drops the css
+along with the code. `import.meta.css = css` at the top level of a module makes
+the sheet a module side effect: it lands on every page importing the module, for
+a component that may never appear, and nothing can shake it out.
+
+That is also how a stylesheet shared between components is written — a module of
+its own, exposing an install function its callers run from their render:
+
+```js
+// input_css.js
+const inputCss = /* css */ `
+  @layer navi {
+    .navi_input {
+      /* ... */
+    }
+  }
+`;
+// Keyed on this module, so the controls drawn as a .navi_input box share one
+// stylesheet instead of each carrying a copy.
+export const installInputCss = () => {
+  import.meta.css = inputCss;
+};
+```
+
+```js
+// textarea.jsx
+import { installInputCss } from "./input_css.js";
+
+export const Textarea = (props) => {
+  installInputCss();
+  import.meta.css = css; // this component's own css, and nothing else
+  // ...
+};
+```
+
+Note the setter is keyed by module: **two assignments in one module do not add
+up**, the second replaces the first. One `import.meta.css` per module — which is
+why the shared sheet has to live in a module of its own rather than be
+concatenated into the component's.
+
+The exception is a module that is a side effect by design — `navi_css_vars.js`
+and the sheets it pulls in are the app's tokens, always needed, and assign at
+module scope on purpose.
+
+### `${}` blinds the whole stylesheet
+
+A substitution the build cannot read makes the **entire** template opaque — not
+just the line it sits on — and everything below is lost for all of it:
+
+- **comments ship to production**, with every space and newline
+- **nothing is transpiled**: no nesting lowering, no prefixing, no fallback for
+  the browsers the app targets
+- **`url("./icon.svg")` is never seen**: the file is not part of the build, not
+  copied, not hashed, and the url resolves against the document instead of the
+  module — it 404s in production
+- **nothing is checked**: an unclosed brace or an invalid value reaches the
+  browser instead of failing the build
+- **nothing is minified**
+
+So a `${}` is not a small convenience: it opts a component's whole stylesheet
+out of the build. The one shape that survives is a substitution standing exactly
+**where a css value stands** — inside a rule block, after the `:` of a
+declaration, not in a string, not in `url()`, not in a selector, a property name
+or an at-rule prelude:
+
+```js
+// read, transformed, and the expression put back
+import.meta.css = /* css */ `
+  .panel {
+    transition: translate ${SETTLE_DURATION_MS}ms ease-out;
+  }
+`;
+```
+
+Anything else ships verbatim, silently. Do not rely on the distinction: write css
+without substitutions.
+
+### Writing css without `${}`
+
+**A value the JS knows → a custom property.** The css stays static, and the value
+changes without building a new stylesheet:
+
+```js
+// avoid
+const setPanelWidth = (width) => {
+  import.meta.css = `.panel { width: ${width}; }`;
+};
+
+// prefer
+import.meta.css = /* css */ `
+  .panel {
+    width: var(--panel-width, 300px);
+  }
+`;
+const setPanelWidth = (element, width) => {
+  element.style.setProperty("--panel-width", width);
+};
+```
+
+**An attribute or class name held in a JS constant → write it out in the css.**
+This is the most common way navi's own stylesheets used to go blind: a constant
+exists because JS sets the attribute, and the css then reads it through a
+substitution. Keep the constant for the JS side and write the selector literally
+— it is one string, and it buys back the whole stylesheet:
+
+```js
+const SWIPE_AXES_ATTRIBUTE = "data-swipe";
+
+// avoid
+import.meta.css = `[${SWIPE_AXES_ATTRIBUTE}="x"] { touch-action: pan-y; }`;
+
+// prefer
+import.meta.css = /* css */ `
+  [data-swipe="x"] {
+    touch-action: pan-y;
+  }
+`;
+element.setAttribute(SWIPE_AXES_ATTRIBUTE, "x");
+```
+
+**A selector you did not want to repeat → nesting.** Reaching into JS for a name
+to avoid typing a selector twice trades a whole stylesheet for a little
+repetition; `&` removes the repetition without leaving css:
+
+```js
+// prefer
+import.meta.css = /* css */ `
+  .navi_button {
+    color: black;
+    &[data-loading] {
+      opacity: 0.5;
+    }
+  }
+`;
+```
+
+**A variant → a data attribute, both branches written out.** A condition in JS
+picking a declaration hides the css; a condition picking an attribute does not:
+
+```js
+// avoid
+import.meta.css = `.badge { color: ${tone === "danger" ? "red" : "blue"}; }`;
+
+// prefer
+import.meta.css = /* css */ `
+  .badge {
+    color: blue;
+    &[data-tone="danger"] {
+      color: red;
+    }
+  }
+`;
+```
+
+**A block of declarations repeated in several rules → a selector list.** A css
+fragment held in a JS constant and interpolated into three rules is three blind
+stylesheets; the same declarations under one selector list are css:
+
+```js
+// prefer
+import.meta.css = /* css */ `
+  :root,
+  .navi_popover,
+  .navi_dialog {
+    --navi-color-hint: color-mix(
+      in srgb,
+      currentColor var(--navi-color-hint-mix),
+      transparent
+    );
+  }
+`;
+```
+
+**A whole stylesheet shared between modules → a module exposing an install
+function**, as shown at the top of this section.
+
+### Beware when moving a shared sheet out
+
+Splitting a chunk out of a template changes **cascade order**: the extracted
+sheet is adopted by the install call, which runs before the component's own
+assignment, so it now comes _before_ that sheet instead of after it. That matters only when the two carry
+the same selector at the same specificity and in the same layer — check for that
+before splitting. In navi, `popup_css.js` and `surface_text_css.js` overlap
+`.navi_dialog` and `.navi_popover` with dialog's and popover's own css, which is
+why they are still concatenated.
+
+### The build target has to match the css
+
+The css is transpiled for the runtimes the build targets, so a target older than
+what the css uses is silently lowered. `light-dark()` under a target below Chrome
+123 becomes `var(--lightningcss-light, …) var(--lightningcss-dark, …)`, an
+invalid declaration — the color is simply not applied. navi's own build targets
+Chrome 123 because navi's css uses `light-dark()`; an app targeting older
+browsers must not use css newer than its target.
+
+---
+
 ## Layer structure
 
 ```
@@ -41,7 +259,7 @@ This means an app can override a Navi default from its own unlayered CSS, withou
 }
 ```
 
-Targeting the same element is not a detail — see [`--navi-*` vs `--component-*`](#--navi-vs---component-where-the-override-has-to-go) below.
+Targeting the same element is not a detail — see [`--navi-*` vs `--component-*`](#--navi--vs---component--where-the-override-has-to-go) below.
 
 ### Why actual rules stay outside any layer
 

package/docs/navigation.md

@@ -3,6 +3,23 @@
 How to build navigation with `@jsenv/navi`: declaring routes, rendering them,
 linking to them, and turning them into tabs.
 
+- [The rule that decides everything else: the position belongs in the URL](#the-rule-that-decides-everything-else-the-position-belongs-in-the-url)
+- [Declaring routes](#declaring-routes)
+  - [A section is allowed to be a route of its own](#a-section-is-allowed-to-be-a-route-of-its-own)
+  - [Which values a param accepts](#which-values-a-param-accepts)
+  - [An address that only sends elsewhere](#an-address-that-only-sends-elsewhere)
+  - [Search params](#search-params)
+- [Rendering routes](#rendering-routes)
+  - [Loading data](#loading-data)
+- [Links and tab rows](#links-and-tab-rows)
+- [The back arrow: `navBack`](#the-back-arrow-navback)
+- [Tabs that travel: `RouteTravel`](#tabs-that-travel-routetravel)
+- [Where a navigation lands: the scroll](#where-a-navigation-lands-the-scroll)
+- [Creating something, then editing it](#creating-something-then-editing-it)
+- [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)
+
 ## The rule that decides everything else: the position belongs in the URL
 
 Where the user is — which section, which tab, which sub-page — is state. Put it
@@ -21,8 +38,10 @@ retrofitted later:
 So the default shape of a tab row is routes: `<Nav>` + `<Link route>` +
 `<RouteTravel>`. `SlideContainer` is the exception, not the starting point — see
 [Tabs that are not routes](#tabs-that-are-not-routes) for the cases that
-genuinely are one, and for the middle answer: a position READ from the URL and
-restored on reload, without a route and without a history entry per step.
+genuinely are one, and
+[A `SlideContainer` in the URL](#a-slidecontainer-in-the-url-a-position-that-is-not-a-place-one-came-from)
+for the middle answer: a position READ from the URL and restored on reload,
+without a route and without a history entry per step.
 
 ## Declaring routes
 
@@ -289,6 +308,11 @@ Declared on the **root route**, a search param is a position that holds wherever
 one is in the application — a view mode that survives moving from page to page.
 Declared on one route, it exists only there.
 
+Writing it AMENDS the history entry one is on rather than stacking a new one: a
+param that qualifies a screen is not a place, and one entry per write turns a
+single back-press into as many as the user moved. A state whose values ARE
+places says so — see [`history: "push"`](#a-state-whose-values-are-places-history-push).
+
 ## Rendering routes
 
 `<Route>` is the only primitive. With `children` it is a container that renders
@@ -575,9 +599,9 @@ match at once; the first matching branch wins).
 ## Tabs that are not routes
 
 `SlideContainer` holds slides that replace one another in one box, with the same
-gestures and the same travelling bar, and — unless it is given a `urlParam`, see
-below — nothing written to the URL. Use it when the position genuinely is not a
-place one should be able to link to:
+gestures and the same travelling bar, and — unless the signal it is bound to is
+one the URL holds, see below — nothing written to the URL. Use it when the
+position genuinely is not a place one should be able to link to:
 
 - the steps of a wizard, or the screens of a picker, inside a dialog or a popover
   — a popup is promoted to the browser's top layer, so no container can hold two
@@ -604,7 +628,7 @@ page. It reads which slide is on screen from the container itself, and its bar
 follows the slides, a finger dragging them included. `<Link slide>` has no href
 and behaves like a button: this is not a link to anywhere.
 
-### The middle answer: a position in the URL that is not a place one came from
+### A `SlideContainer` in the URL: a position that is not a place one came from
 
 "Should a link be able to open the app on this?" has a third answer, and a wizard
 is exactly it: **yes for reading and for reloading, no for history.** The step one
@@ -615,48 +639,111 @@ and it should NOT stack an entry per step, because the back arrow of a form mean
 back-press into four, and walk the reader backwards through a form they thought
 they had left.
 
-Neither pure answer fits: routes would want one route per step, a real navigation
-per move (so a push per move), and the walk's own rules — a step held until it is
-answered, a confirmation reachable only by publishing — re-expressed as route
-guards. A plain `SlideContainer` writes nothing at all.
+There is nothing to invent for it: a search param already IS a position in the
+URL that replaces rather than pushes ([Search params](#search-params)). Declare
+the step as one, and hand its signal to the container:
 
-`urlParam` is that middle answer: the container owns one search param, writes
-where it stands into it **by replacement**, and opens on what it names.
+```js
+const stepSignal = stateSignal("when", {
+  id: "step",
+  oneOf: ["when", "where", "who", "recap", "done"],
+  // the step qualifies THIS visit, not the screen: a link built to the editor
+  // does not inherit the step one happens to be on, and it goes back to the
+  // default when the route stops matching
+  weak: true,
+});
+export const ALERT_EDIT_ROUTE = route("/alerts/:alertId/edit", {
+  searchParams: { step: stepSignal },
+});
+```
 
 ```jsx
-<SlideContainer id="alert_editor" signal={stepSignal} urlParam="step">
+<SlideContainer signal={stepSignal}>
 ```
 
-Two things it does that a `useEffect` calling `history.replaceState` beside the
-container cannot, and they are the reason it lives inside:
-
-- it writes the travels that HAPPENED. A travel a lock refused, or one the caller
-  refused late, never reaches the address — or is written back when it does;
-- it READS the param through the walk rather than jumping to it. The address
-  comes from outside the box (typed, shared, kept from a session that has moved
-  on), so every slide between here and there is asked to let go the way a key
-  going that way would ask it, and the first one that holds is where one stops.
-  `?step=done` cannot open a confirmation screen for something nobody sent — and
-  the address is then rewritten with the area actually shown, so it never says
-  one is somewhere one is not.
+That is the whole wiring, and every half of it is the piece that already
+existed. Worth naming, because each answers a question a wizard actually has:
+
+- **where it opens is the state's own default** — the first argument of
+  `stateSignal`. The container has a `defaultCurrent` for when it owns its
+  position, but a bound container does not own it: one place says where the step
+  starts, and it is the same place a reset goes back to;
+- **the param is absent while the step IS that default** (route.js prunes it), so
+  `/alerts/W-123/edit` is clean on the first step, gains `?step=where` on the
+  second, and loses it again coming back. The address carries what differs from
+  the usual answer and nothing else;
+- **the container walks to the step rather than jumping to it.** The address comes
+  from outside the box (typed, shared, kept from a session that has moved on), so
+  every slide between here and there is asked to let go the way a key going that
+  way would ask it, and the first one that holds is where one stops. `?step=done`
+  cannot open a confirmation screen for something nobody sent. The signal is then
+  written with the area actually shown, so the address never says one is
+  somewhere one is not;
+- **only the travels that HAPPENED are written.** A travel a lock refused, or one
+  `onCurrentChange` refused late, never reaches the signal — or is written back
+  when it does.
 
 A container remembers nothing across a reload, so a step whose `required` the app
 knows is already satisfied says so itself (`required={!alreadyFilled}`); the same
 holds for a hold that a finished job lifts (`preventNavNext={!published}`).
 
-`history: "push"` is the other half, for slides that ARE places one came from — a
-gallery one browses:
+**A start that depends on the page one is on** — a wizard creating something
+opens on its first question, the same wizard editing something opens on its
+summary — is said by the ROUTE, not by the state and not by the container:
 
-```jsx
-<SlideContainer urlParam={{ name: "photo", history: "push" }}>
+```js
+const stepSignal = stateSignal("when", { id: "step", weak: true });
+route("/alerts/create", { searchParams: { step: stepSignal } });
+route("/alerts/:alertId/edit", {
+  searchParams: { step: { signal: stepSignal, default: "recap" } },
+});
 ```
 
-Even there, a slide reached by DRAGGING replaces rather than pushes: swiping back
-and forth with a thumb is browsing, not a trail one wants to walk home along.
+Everything that asks "is this the default" then asks the route one is on: both
+addresses stay clean on the step they open on — `/alerts/create` on "when",
+`/alerts/W-123/edit` on "recap" — an address naming no step puts the state back
+on that page's own, and going from one to the other moves the step with it.
 
-What `urlParam` is not: a route. Nothing is declared, nothing matches, no page
-transition plays — 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.
+Not a `computed` over the route's `matchingSignal`: a state and the route that
+declares it cannot name each other — whichever is written first, the other is
+not initialised yet, and a dynamic default is read while `stateSignal` is being
+built. The route is the right place regardless; it is the thing that knows which
+page one is on.
+
+Two containers on one screen are two signals, and that is the whole answer to
+"which one owns the param": the one holding the route's signal. A gallery of
+seven wizards side by side hands each of them a `useSignal` of its own, and
+nothing goes into the address.
+
+### A state whose values ARE places: `history: "push"`
+
+Replacement is the default because most URL-held state qualifies the screen one
+is on. A state whose values are places one came from — the photo being looked at
+in a gallery — says so where the state is declared:
+
+```js
+const photoSignal = stateSignal(undefined, { id: "photo", history: "push" });
+```
+
+Every write of it then stacks an entry, wherever the write comes from. Except
+where the writer knows this particular move is not one: a slide reached by
+DRAGGING replaces even in a container that pushes, because swiping back and forth
+with a thumb is browsing, not a trail one wants to walk home along. That is said
+at the write rather than declared:
+
+```js
+photoSignal.set(nextPhoto, { history: "replace" });
+```
+
+`SlideContainer` already does exactly that for its own drags, so a gallery gets
+it by declaring the state and nothing else.
+
+### What this is not
+
+It is not a route. Nothing is declared for the steps themselves, nothing matches
+on them, and no page transition plays — a transition needs the page to change
+([route_transitions.md](./route_transitions.md)), and a search param moving is
+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).