@jsenv/navi 0.29.142 → 0.29.144

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/docs/state_binding.md

@@ -0,0 +1,142 @@
+# Bound, not wired
+
+Every piece of state navi shows already has a way in and a way out: the value in
+a control, the area a `SlideContainer` stands on, whether a popup is open, where
+the user is in the application. A callback whose whole body copies that state
+into a variable of your own is a second road beside one that exists — and from
+then on there are two owners for one truth.
+
+- [The three shapes](#the-three-shapes)
+- [The callback that only remembers](#the-callback-that-only-remembers)
+- [Why it is not merely shorter](#why-it-is-not-merely-shorter)
+- [What is left for the callback](#what-is-left-for-the-callback)
+- [What binds itself](#what-binds-itself)
+- [When there is no binding](#when-there-is-no-binding)
+
+## The three shapes
+
+Almost everything an application has to say about a component is one of three
+things, and each has its own prop:
+
+| what the code has to say                      | how it is said                             |
+| --------------------------------------------- | ------------------------------------------ |
+| this state is the app's, both ways            | `signal`                                   |
+| something HAPPENS when it changes             | `action` (`uiAction` for what cannot fail) |
+| a press asks something of a component near it | `command` + `commandFor`                   |
+
+Reaching for a handler that is none of the three — an `onClick`, an
+`onCurrentChange`, a `uiAction` writing a signal — is the sign that one of them
+was missed.
+
+## The callback that only remembers
+
+The same mistake, in four places:
+
+```jsx
+// ✗ the app is told where the slides went, and writes it back down
+<SlideContainer
+  current={step}
+  onCurrentChange={(area) => {
+    stepSignal.value = area;
+  }}
+/>
+// ✓
+<SlideContainer signal={stepSignal} />
+
+// ✗ the control is told what it now holds, and the app writes it back down
+<Picker value={side} uiAction={(value) => (sideSignal.value = value)} />
+// ✓
+<Picker signal={sideSignal} />
+
+// ✗ a button proposing a value to a control, straight into the signal
+<Button onClick={() => (durationSignal.value = ninetyMinutes)}>1h30</Button>
+// ✓
+<Button command="--navi-update" commandFor="duration" value={ninetyMinutes}>
+  1h30
+</Button>
+
+// ✗ the popup is told it opened, and the app writes it back down
+<Dialog
+  open={isOpen}
+  onOpen={() => (openSignal.value = true)}
+  onClose={() => (openSignal.value = false)}
+/>
+// ✓
+<Dialog signal={openSignal} />
+```
+
+In each pair the second line is not a tidier spelling of the first: it is the
+binding the component already implements, and the first is a partial
+re-implementation of it.
+
+## Why it is not merely shorter
+
+A binding is written by **everything that moves the state**, not only by the
+gesture the caller thought of. A `SlideContainer`'s signal is written by a drag,
+by an arrow key, by a `--navi-right` command sent from a chevron outside the
+box, by the address when the signal is a route's own, by a step refusing to be
+left. A control's
+signal is written by the user typing, by a group placing its children, by a
+picker committing on close, by a `--navi-update` from a shortcut button. A
+hand-written callback catches the cases it was written for and silently misses
+the rest — and the drift only shows on the screen where a second gesture was
+added.
+
+It reads in the other direction too, which no callback gives at all: writing the
+signal MOVES the component. The wheels roll, the slides travel, the popup opens.
+That is what replaces the `key` or the `value` prop pushed down to force a
+component into a state.
+
+And it goes through navi's interaction gate. A `command` on a read-only,
+disabled or busy control is refused and says why; an `onClick` doing the same
+write is plain DOM, fires on a greyed-out button and rewrites a value nobody was
+allowed to change.
+
+## What is left for the callback
+
+Binding the state does not remove the callback — it removes one job from it:
+
+- **`onCurrentChange` with a `signal` bound still fires**, and is still worth
+  writing: `cause` says whether the slide was pressed, dragged, or asked for by
+  the address — which is what tells a history push from a replace — and
+  returning `false` REFUSES the travel. Neither of those is state.
+- **`uiAction`** is for what moves with the value without being it: logging,
+  something else on screen following along. Not "remember it".
+- **`action`** is for what can fail or take time — it carries the busy state and
+  the error, which a `uiAction` does not (see
+  [actions.md](./actions.md#action-or-uiaction)).
+- **`onClick`** is for imperative work with nothing to send, nothing to open and
+  nothing to propose.
+
+## 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 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
+
+Sometimes the state being wired by hand has no prop for it. That is not a
+licence to wire it — it is a finding, and it is one of two:
+
+- the state is already held somewhere and the app is keeping a parallel copy of
+  it (the URL, the control itself, an action's own state) — the fix is to read
+  it where it lives;
+- or navi is genuinely missing a binding, and should gain one.
+
+Say which, rather than leaving a hand-wired callback behind: it is the version
+the next screen copies, and by then it is the app's pattern.
+
+## See also
+
+- [control_value.md](./control_value.md) — who holds a control's value, and what
+  a bound signal holds control by control
+- [actions.md](./actions.md#action-or-uiaction) — `action` or `uiAction`
+- [popup_open.md](./popup_open.md) — who owns the fact that a popup is open
+- [interactions.md](./interactions.md) — a gesture is named, not read by hand:
+  the same rule, one layer down

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/navi",
-  "version": "0.29.142",
+  "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"
   },