@jsenv/navi 0.29.299 → 0.29.301

package/docs/AI_INSTRUCTIONS.md

@@ -157,7 +157,8 @@ to start when unsure which export solves a problem.
 
 - `popup_open.md` — a popup owns its open state; `command` + `commandfor`;
   `triggerNaviCommand` as the last resort, with the event forwarded and never
-  invented; opening ON something; a press that opens and acts is a `Picker`;
+  invented; opening ON something; a press that opens and acts is a `Picker`,
+  and its trigger wears the wait and the error (a card that lifts, `openOn`);
   Escape cancels; the close cross; a popup that loads data. Read before passing
   `open`, calling `triggerNaviCommand`, or writing a close button.
 - `popup_backdrop.md` — three independent questions: a wall or not

package/docs/interactions.md

@@ -98,6 +98,12 @@ which the carrying interactions answer with).
 | `pan` `zoom`                                           | a surface under the hand, or under a wheel                  |
 | `"keyboard:<shortcut>"`                                | keys, e.g. `"keyboard:ctrl+backspace"`                      |
 
+Two holds on one press — a `longpress` declared on something inside an
+element that declares one too — are answered by the nearer one, the way a
+click is the innermost target's: the inner hold fires, the outer wait is given
+up. Delays being equal; an outer hold made shorter than the inner one fires
+first.
+
 A name nothing knows how to detect produces a dev warning naming the detectors
 that exist. The carrying family and the two surface streams each have a file of
 their own — [drag_interactions.md](./drag_interactions.md) and

package/docs/popup_open.md

@@ -403,6 +403,102 @@ dialog hides: a popup written once, far from every press that opens it, has to
 be told what it is about and has to answer somebody — and neither question
 exists once the popup is written where it is used.
 
+### The trigger wears the wait
+
+The picker's `action` runs on the trigger, not in the popup: it is dispatched
+on the close that keeps, and the popup goes while it runs. So what is still on
+screen answers for the write — `aria-busy` and the loading outline on the
+trigger while the request is out, the error callout on it if the server
+refuses, and the value rolled back to the last accepted one — on by default
+for a picker, and what one wants: nobody is left mid-edit behind a closed
+popup, and the card goes on saying what the server knows. A
+card that IS the trigger (`variant="bare"`, the card as `ui`) therefore waits
+as a card and is refused as a card, wherever in the tree the sheet was written.
+
+```jsx
+<Picker
+  variant="bare"
+  type="object"
+  mode="dialog"
+  ui={<MatchCard match={match} />}
+  value={match}
+  action={(next) => MATCH.PATCH({ id: match.id, ...next })}
+>
+  <ControlGroup>
+    <MatchCard match={match} editable />
+    <Button command="--navi-cancel">Cancel</Button>
+    <Button command="--navi-send">Save</Button>
+  </ControlGroup>
+</Picker>
+```
+
+The card shows the answer the moment the sheet leaves when its `ui` is drawn
+from what the picker holds rather than from what the caller knows — the same
+state navi's own default `ui` reads, rolled back by `resetOnError`, so nothing
+about the pending value is the caller's to keep or to put back. Two ways to
+read it: `ui={MatchCard}` hands the component `value`, `loading` and
+`interactive` as props; `ui={<MatchCard match={match} />}` keeps the caller's
+own props and reads the same three with `usePickerState()` inside. The
+`loading` is the wait: navi's loading outline is a two-pixel run around the
+box, which a card-sized trigger draws its own waiting state for.
+
+What the picker measures as "changed since open" is what its mirrored group
+holds. A piece of the answer living outside the controls — a seating
+rearranged by drag, kept in component state — has to be held by a control in
+the group too (a named control bound to that state), or a close over it reads
+as nothing changed and nothing runs.
+
+Two props finish the construct. `openOn="longpress"` (or
+`["longpress", "contextmenu"]`) makes the hold what opens it, so a tap on the
+card stays a tap — what a card in a list needs: the drawing gets its pointer
+back, a link in it navigates, a button in it presses, a picker in it opens on
+its own click, with nothing to declare. Two pickers on one card is the score
+sheet inside the edit card (`12_picker_card_demo.html`): the inner one names
+the card as its `anchor` so it lifts the whole card, and says `standalone` so
+its value stays its own. One card, one wait: each picker wears the other's
+run through `loading` (from its `onActionStart`/`onActionEnd`), so while
+either write is out the hold and the click are both refused, with the busy
+reason where the finger is — the click only once the score picker says
+`openWhileReadOnly={false}`: a busy picker otherwise still opens, to be read,
+and a sheet of fields to fill in is not that. A hold declared inside the card answers before the
+card's own: the nearer hold takes the press. `animation="growing"` with
+`dialogSizeFromAnchor` (as wide as the card, floor and ceiling),
+`popupBackgroundColor="transparent"` and `popupBoxShadow="none"` lifts the
+card out of its place and puts it back (`data-grow` on the card inside the
+sheet; see Dialog's own `animation`). `12_picker_card_demo.html` shows all of
+it, against a backend that answers when told to.
+
+This is not `optimistic`. `optimistic` on a control is "draw no wait at all";
+here the wait is drawn, on the trigger, and the popup was never what held it.
+An optimistic picker is for a write not worth showing — the card then reads
+the store and says nothing until the answer lands.
+
+The same shape with nothing to write is a **door**: a drawing that grows to be
+looked at — a weather scene, a plan — and comes back. `picksNothing`, no
+`action`, no `dialogSizeFromAnchor` (it opens precisely to get bigger):
+
+```jsx
+<Picker
+  picksNothing
+  variant="bare"
+  mode="dialog"
+  ui={scene}
+  aria-label="Zoom"
+  animation="growing"
+  popupBackgroundColor="transparent"
+  popupBoxShadow="none"
+>
+  <Box data-grow>{scene}</Box>
+</Picker>
+```
+
+A `Button` opening a `Dialog` with an `anchor` does the same and is not wrong;
+what the picker removes is the id plumbing (the trigger is the anchor, the
+popup is its own), and what it keeps is the day the drawing becomes editable —
+it is already the thing that wears the wait. The button + shared dialog stays
+the answer for [the two cases where a popup must be
+shared](#when-a-shared-popup-is-still-the-right-answer).
+
 ### A trigger that is only an icon
 
 `variant="icon"` draws no value, and therefore no slot beside one either: the
@@ -536,8 +632,12 @@ to be hand-written to work around it: `command` next to `action` is that
 workaround, done at the one moment where the action has settled and the button
 is no longer busy.
 
-To close on the press instead — the answer taken as soon as it is given, the
-save running on its own behind a closed popup — say so on the control:
+When what opened the popup is still on screen and should answer for the write
+— its wait, its refusal — the popup was a picker's all along: see [the trigger
+wears the wait](#the-trigger-wears-the-wait). What follows is for the other
+case, a popup nobody stands in for. To close on the press — the answer taken as
+soon as it is given, the save running on its own behind a closed popup — say so
+on the control:
 
 ```jsx
 <Form command="--navi-close" action={saveScore} optimistic resetOnError>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/navi",
-  "version": "0.29.299",
+  "version": "0.29.301",
   "type": "module",
   "description": "Library of components including navigation to create frontend applications",
   "repository": {