work

Author: dmail

packages/frontend/navi/dist/jsenv_navi.js

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

packages/frontend/navi/dist/jsenv_navi.js.map

@@ -41,7 +41,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
 

packages/frontend/navi/docs/control_value.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
 
@@ -609,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
@@ -625,12 +644,12 @@ URL that replaces rather than pushes ([Search params](#search-params)). Declare
 the step as one, and hand its signal to the container:
 
 ```js
-const stepSignal = stateSignal(undefined, {
+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 nothing
-  // when the route stops matching
+  // 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", {
@@ -639,16 +658,20 @@ export const ALERT_EDIT_ROUTE = route("/alerts/:alertId/edit", {
 ```
 
 ```jsx
-<SlideContainer signal={stepSignal} defaultCurrent={editing ? "recap" : "when"}>
+<SlideContainer signal={stepSignal}>
 ```
 
 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:
 
-- **the param is absent while the step is the default one** (route.js prunes it),
-  so `/alerts/W-123/edit` stays clean and `defaultCurrent` is what says where the
-  container opens. An empty signal means "wherever this would have opened
-  anyway", not "the first slide";
+- **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
@@ -664,6 +687,24 @@ 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.
+
+```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 });
+```
+
+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.
+
 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

packages/frontend/navi/docs/css_architecture.md

@@ -110,14 +110,14 @@ Binding the state does not remove the callback — it removes one job from it:
 
 ## What binds itself
 
-| the state                         | how it binds                               | where it is written up                                                                 |
-| --------------------------------- | ------------------------------------------ | -------------------------------------------------------------------------------------- |
-| a control's value                 | `signal` (every control, every group)      | [control_value.md](./control_value.md)                                                 |
-| the area a `SlideContainer` is on | `signal` (a route's, and it is in the URL) | its JSDoc, [navigation.md](./navigation.md)                                            |
-| a popup being open                | `signal`, `open`, `navState`               | [popup_open.md](./popup_open.md)                                                       |
-| where the user is                 | route + search-param signals               | [navigation.md](./navigation.md)                                                       |
-| a value proposed to a control     | `command="--navi-update"`                  | [control_value.md](./control_value.md#a-button-that-proposes-a-value-is---navi-update) |
-| the state of an async run         | an `action`, read by `useAsyncData`        | [actions.md](./actions.md)                                                             |
+| the state                         | how it binds                                                | where it is written up                                                                                               |
+| --------------------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| a control's value                 | `signal` (every control, every group)                       | [control_value.md](./control_value.md)                                                                               |
+| the area a `SlideContainer` is on | `signal` (a route's search param signal puts it in the URL) | its JSDoc, [navigation.md](./navigation.md#a-slidecontainer-in-the-url-a-position-that-is-not-a-place-one-came-from) |
+| a popup being open                | `signal`, `open`, `navState`                                | [popup_open.md](./popup_open.md)                                                                                     |
+| where the user is                 | route + search-param signals                                | [navigation.md](./navigation.md)                                                                                     |
+| a value proposed to a control     | `command="--navi-update"`                                   | [control_value.md](./control_value.md#a-button-that-proposes-a-value-is---navi-update)                               |
+| the state of an async run         | an `action`, read by `useAsyncData`                         | [actions.md](./actions.md)                                                                                           |
 
 ## When there is no binding
 

packages/frontend/navi/docs/navigation.md

@@ -455,8 +455,6 @@ const durationToMs = (duration) => {
 // "somewhere over there" (a gesture one browses with), or it said a name (a tab
 // pressed, a key, a command — a place aimed at). Nothing at all when the travel
 // came from code, which has no interaction to speak of.
-const CAUSES_WRITTEN_BY_REPLACEMENT = ["drag", "refusal", "state"];
-
 const causeOfEvent = (event) => {
   if (!event) {
     return "code";
@@ -471,6 +469,10 @@ const causeOfEvent = (event) => {
   return "command";
 };
 
+// The causes that are not places one went, whatever the state they are written
+// into says (see writeAreaAsked).
+const CAUSES_WRITTEN_BY_REPLACEMENT = ["drag", "refusal", "state"];
+
 const readArea = (slideElement) =>
   slideElement.getAttribute("data-slide-area") || slideElement.id || "";
 
@@ -525,16 +527,34 @@ const readArea = (slideElement) =>
  *   still unanswered) is where one stops — after which the signal is written
  *   with the area actually shown, so it says where one IS and never where one
  *   asked to be.
- *   Hand it a `stateSignal` declared on a route (`searchParams: { step }`) and
- *   the address is that state: `?step=<area>` on every travel, and the walk
- *   above is what a link, a bookmark or a traversal goes through. Written by
+ *   PUTTING THE AREA IN THE URL is that binding and nothing more: hand it a
+ *   `stateSignal` a route declares as a search param, and `?step=<area>` is
+ *   written on every travel, read on a load, a bookmark, a link, a traversal —
+ *   through the walk above, so an address cannot open a slide the walk may not
+ *   reach.
+ *   ```js
+ *   const stepSignal = stateSignal("when", { id: "step", weak: true });
+ *   route("/alerts/:id/edit", { searchParams: { step: stepSignal } });
+ *   ```
+ *   ```jsx
+ *   <SlideContainer signal={stepSignal}>
+ *   ```
+ *   Where it opens is the state's own default (`stateSignal`'s first argument —
+ *   a signal there, for a start that depends on where one is), and the param
+ *   stays out of the address while the area IS that default. `weak` keeps the
+ *   step from being inherited by links built to that route. Written by
  *   replacement unless the state says `history: "push"`, and even then a slide
  *   reached by DRAGGING replaces — see docs/navigation.md.
- * @param {string} [props.defaultCurrent] - which slide to open on, when the
- *   travel is left to the container. Mount-only, like every other `default*`:
+ * @param {string} [props.defaultCurrent] - which slide to open on, for a
+ *   container that owns its position. Mount-only, like every other `default*`:
  *   it says where one starts, not where one is — say `current` for that.
  *   Without it the first slide is the one shown, the way a stack of pages opens
  *   on its first page.
+ *   A container bound to a `signal` does not own its position, and where it
+ *   opens is that state's own default (`stateSignal`'s first argument) rather
+ *   than this: one place says where the area starts, and it is the place a
+ *   reset goes back to. This still answers for a signal holding nothing at
+ *   all.
  * @param {(area: string, detail: {cause: "drag"|"keyboard"|"command"|"code"|"state", event: Event}) => void|false|Promise<void|false>} [props.onCurrentChange]
  *   - the slide being shown has changed. `cause` says what asked for it, which
  *   is what tells a place browsed past from a place aimed at — a slide dragged

packages/frontend/navi/docs/state_binding.md

@@ -29,7 +29,15 @@ let isUpdatingRoutesFromUrl = false;
  *   `:name=${signal}` binds that param to a signal.
  * @param {object} [options]
  * @param {Object<string, import("@preact/signals").Signal>} [options.searchParams]
- *   Search params this route two-way syncs with, by name.
+ *   Search params this route two-way syncs with, by name. The signal and the url
+ *   are the same state: writing the signal rewrites the address, an address
+ *   arriving from outside writes the signal, and the param disappears from the
+ *   url while the signal holds its default.
+ *   Writing one AMENDS the history entry one is on — a param qualifies the
+ *   screen, it 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 where it is declared (`stateSignal(v, { history: "push" })`), and
+ *   one write can still say otherwise (`signal.set(v, { history })`).
  * @param {Object<string, RegExp | Array | ((value: string) => boolean)>} [options.params]
  *   Which values a path param accepts, by param name: a regexp tested against the
  *   decoded segment, the list of accepted values (compared as strings, so it can

packages/frontend/navi/src/layout/slide_container.jsx

@@ -410,7 +410,7 @@ <h2 id="s-text-align">Text Align</h2>
                 style={{ width: "200px" }}
               />
             </label>
-            <Box row spacing="16px" style={{ flexWrap: "wrap" }}>
+            <Box flex="y" spacing="16px">
               {["Marie D.", "Marie-Christine D."].map((name) => (
                 <Box
                   key={name}