@jsenv/navi 0.29.143 → 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

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

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
 
 ```

package/docs/navigation.md

@@ -687,23 +687,28 @@ A container remembers nothing across a reload, so a step whose `required` the ap
 knows is already satisfied says so itself (`required={!alreadyFilled}`); the same
 holds for a hold that a finished job lifts (`preventNavNext={!published}`).
 
-**A start that depends on where one is** — a wizard creating something opens on
-its first question, the same wizard editing something opens on its summary — is
-not a prop on the container either: a `stateSignal` takes a SIGNAL as its default
-and follows it as long as nobody has answered otherwise.
+**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:
 
 ```js
-const stepDefaultSignal = computed(() =>
-  // `matchingSignal`, not `matching`: the plain property is a mirror, the
-  // signal is what a computed can follow
-  ALERT_EDIT_ROUTE.matchingSignal.value ? "recap" : "when",
-);
-const stepSignal = stateSignal(stepDefaultSignal, { id: "step", weak: true });
+const stepSignal = stateSignal("when", { id: "step", weak: true });
+route("/alerts/create", { searchParams: { step: stepSignal } });
+route("/alerts/:alertId/edit", {
+  searchParams: { step: { signal: stepSignal, default: "recap" } },
+});
 ```
 
-The pruning follows it too, so both addresses stay clean on the step they open
-on — `/alerts/create` on "when", `/alerts/W-123/edit` on "recap" — and a step
-someone actually chose survives the default moving under it.
+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.
+
+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

package/docs/popup_open.md

@@ -11,7 +11,8 @@ What opens a `Dialog` or a `Popover`, and who owns the fact that it is open.
 - [A press that opens a popup and acts on it](#a-press-that-opens-a-popup-and-acts-on-it)
 - [Reacting to open and close](#reacting-to-open-and-close)
 - [Escape cancels, the other gestures keep](#escape-cancels-the-other-gestures-keep)
-- [When `open` is the right answer, and what it costs](#when-open-is-the-right-answer-and-what-it-costs)
+- [When the app holds the open state](#when-the-app-holds-the-open-state)
+- [A popup that loads data](#a-popup-that-loads-data)
 - [What the popup holds while it is closed](#what-the-popup-holds-while-it-is-closed)
 
 Where the focus goes once it is open is its own subject — see
@@ -38,13 +39,15 @@ Escape, the backdrop, a close button — all of them ask, and the busy control
 answers, the same way it would answer anyone else.
 
 So the question is never "should this popup be controlled?" but "what triggers
-the opening?":
+the opening?" — and, when the answer is the application rather than a gesture,
+where that state lives:
 
-| what opens it                      | how                                            |
-| ---------------------------------- | ---------------------------------------------- |
-| a button                           | `command` / `commandfor` attributes, no `open` |
-| a gesture, an event, a JS decision | `triggerNaviCommand(...)`, still no `open`     |
-| it is a piece of application state | `open` — see the cost below                    |
+| what opens it                      | how                                                    |
+| ---------------------------------- | ------------------------------------------------------ |
+| a button                           | `command` / `commandfor` attributes, no `open`         |
+| a gesture, an event, a JS decision | `triggerNaviCommand(...)`, still no `open`             |
+| a state the app holds              | `signal` — [below](#when-the-app-holds-the-open-state) |
+| where the user is                  | `navState`, or a route `stateSignal` given to `signal` |
 
 ## A button opens it: the attributes
 
@@ -459,24 +462,121 @@ A dialog picker's cancel also goes back in history, so anything written to the
 url while it was open (a route `stateSignal`, a search param) goes back with it
 — one more reason Escape and the click outside are not interchangeable.
 
-## When `open` is the right answer, and what it costs
+## When the app holds the open state
 
-`open` is for a popup whose being-open is a fact about the application, not
-about the user's last gesture: a route that _is_ a dialog, an error the app
-decides to show. Use it there, and know what it changes.
+A popup whose being-open is a fact about the application rather than about the
+user's last gesture — a sheet an address can be reloaded into, an error the app
+decides to show — needs somewhere to keep that fact. Three props say it, and
+what separates them is where the state lives, not how hard the popup is driven:
+all three go through the same `requestClose`, so a busy control inside still
+refuses to be left mid-action. What changes is whether anyone hears the refusal.
 
-The busy arbitration still runs — `open={false}` goes through the same
-`requestClose` — but nobody hears the refusal. The parent's state says closed,
-the popup stayed open, and the two disagree from then on: the effect only reacts
-to `open` _changing_, so setting it back to `true` matches the popup's real
-state and does nothing, and the popup can no longer be closed by the prop at
-all until it closes on its own.
+### `signal` — the app holds it, both ways
+
+```jsx
+<Dialog signal={groupSheetOpenSignal} />
+```
+
+The popup opens and closes to match the signal, and writes into it whenever it
+opens or closes on its own: Escape, the backdrop, a `--navi-close` command — and
+the close a busy control denied, after which the signal says "open", because
+that is what is true. One binding both drives the popup and knows where it is,
+which is what every navi control does with its value (see
+[state_binding.md](./state_binding.md)); `Dialog`, `Popover` and what is built
+on them (`SidePanel`) all take it. A signal already `true` at mount means the
+popup was already open when the page appeared: no entrance plays.
+
+### `navState` — the history entry holds it
+
+```jsx
+<Dialog id="group-sheet" navState={{ type: "push" }} />
+```
+
+The open state goes into the history entry, so a screen left and come back to
+finds the popup as it was, and so does a reload. `true` stores it under the
+popup's own `id`; a string names the key instead. `{ type: "push" }` makes the
+opening an entry of its own — the back button then closes the popup rather than
+leaving the screen, and the cancel takes back with it whatever was written to
+the url while it was open. A `Picker` needs none of this: its popup's open state
+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.
+
+### `open`, and what it costs
+
+`open` is the one-way half of `signal` — the parent re-renders with a boolean
+and the popup follows — and the refusal is what it costs. `open={false}` goes
+through the same `requestClose`, and when a busy control denies it, the parent's
+state says closed while the popup stayed open. The two disagree from then on:
+the effect only reacts to `open` _changing_, so setting it back to `true`
+matches the popup's real state and does nothing, and the popup can no longer be
+closed by the prop at all until it closes on its own. A `signal` has no such
+gap, since the popup writes back what really happened.
 
 `defaultOpen` is the middle ground: mount-only, and the popup owns everything
 afterwards. `defaultOpen="interaction"` means the mount _is_ the opening (the
 entrance animation plays); any other truthy value means it was already open when
 the page appeared (no entrance).
 
+## A popup that loads data
+
+Being open is where the user is, and what a popup draws belongs to the screen
+exactly the way a page's own data does. So a popup that loads something binds
+its open state (above) and asks for its data with a `routeAction` whose params
+are `false` while it is closed:
+
+```js
+const groupSheetOpenSignal = stateSignal(false, {
+  id: "group_sheet",
+  type: "boolean",
+});
+
+export const GROUP_MEMBERS = routeAction(GAME_ROUTE, USER.GET_MANY, () => {
+  if (!groupSheetOpenSignal.value) {
+    return false;
+  }
+  return { group: groupSignal.value };
+});
+```
+
+```jsx
+<Dialog signal={groupSheetOpenSignal}>
+  <GroupMembers />
+</Dialog>;
+
+const GroupMembers = () => {
+  const [members] = useAsyncData(GROUP_MEMBERS); // reads, never runs
+  …
+};
+```
+
+What the popup gains is everything a page has:
+
+- the request leaves **with the screen**, in parallel with the rest of what the
+  address needs, instead of behind the gesture that opens the popup;
+- `useAsyncData` reads it — the wait delegated to `<Loading>`, the failure to
+  `<ErrorBoundary>`, `onLoad` for what is seeded once (see
+  [actions.md](./actions.md#reading-an-action));
+- the action layer's rerun rules, its dependencies
+  ([resource_dependencies.md](./resource_dependencies.md)) and the
+  aborted-not-reset treatment a route action gets when the screen is left
+  ([offline.md](./offline.md));
+- a reload keeps the open state, so it keeps the request too;
+- and the routes keep saying what an address needs, which is why they declare
+  it.
+
+The fallback — the popup owning its request, `useAsyncData(action, { run: true })`
+— is for the parameter chosen inside the popup and dying with it: a filter the
+sheet itself holds and nothing else remembers. It cannot do better than the
+gesture that opened the popup, since it starts with the component that draws it;
+a route action left with the screen. Hand-written (`bindParams` in the component,
+`run()` from a `useEffect`, `data === undefined` as the loading flag) it looks
+harmless, and that is the problem: nothing at the call site says which of the two
+it is, so the day the parameter comes from the address, screen data has quietly
+become a popup's private request — asked for late, and asked for alone.
+
 ## What the popup holds while it is closed
 
 A closed popup builds nothing: `children` are mounted on the first open, and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/navi",
-  "version": "0.29.143",
+  "version": "0.29.144",
   "type": "module",
   "description": "Library of components including navigation to create frontend applications",
   "repository": {
@@ -29,7 +29,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@jsenv/dom": "0.17.34",
+    "@jsenv/dom": "0.17.35",
     "@jsenv/humanize": "1.7.8",
     "@jsenv/validity": "0.4.3"
   },