@jsenv/navi 0.29.104 → 0.29.106

package/docs/AI_INSTRUCTIONS.md

@@ -220,9 +220,9 @@ consistency across the app, not from any single call site.
   It also holds `ownTarget`, for an affordance an application draws inside a
   zone that belongs to another control — a chip's cross, an eye, a diskette:
   the three modes and the question that picks one (does it write to the control
-  it sits in?), the `data-own-target` attribute for an element you draw
-  yourself, and what `ownTarget` does NOT stop (a plain `onClick` on an
-  ancestor).
+  it sits in?), the `Box` form that claims the press and nothing more (so an
+  affordance keeps its own drawing instead of becoming a control), and what
+  `ownTarget` does NOT stop (a plain `onClick` on an ancestor).
   Read it before reading the pointer by hand — who owns a press between nested
   boxes, and what a touch may do, are decided before the first pixel moves and
   cannot be got right from outside navi — and before stopping the propagation of

package/docs/actions.md

@@ -168,6 +168,39 @@ To merely REMEMBER the value rather than send it, neither is the answer: bind a
 signal and drop the callback entirely — see
 [control_value.md](./control_value.md).
 
+## A press that opens something and waits for the answer
+
+A press that runs work is an `action`; one that reports a value is a `uiAction`;
+one that asks something of a control near it is a `command` (a value proposed is
+`--navi-update`, see
+[control_value.md](./control_value.md#a-button-that-proposes-a-value-is---navi-update)).
+Reaching for a plain `onClick` usually means one of those was missed.
+
+The press that looks like a fourth case is the one that opens something and then
+does something with what came of it — "save this guest", pressed on a row,
+replacing the guest once the profile exists. It is not a fourth case and it is
+not a dialog plus a way home: it is a `Picker`, whose whole shape is a trigger,
+a popup, and an `action` that runs on what the popup settled.
+
+```jsx
+<Picker variant="icon" rightSlotIcon={<DisketteSvg />} action={onCreated}>
+  <GuestSavePrompt kind="player" name={guest.name} />
+</Picker>
+```
+
+Written this way, what the popup needs to know travels as props rather than
+through the press, and the popup is built the first time it opens rather than
+once per row. See
+[popup_open.md](./popup_open.md#a-press-that-opens-a-popup-and-acts-on-it).
+
+What is left for an `onClick` is what no value can express — imperative work
+with nothing to open and nothing to send. And one nuance worth knowing: on an
+`ownTarget`, a caller's `onClick` runs inside that control's own interaction
+gate rather than firing from the DOM (see
+[interactions.md](./interactions.md#an-affordance-inside-somebody-elses-box-owntarget)),
+so the usual objection — an `onClick` fires on a read-only control — does not
+apply there. Everywhere else it does.
+
 ## `uiAction` mirrors the state, it does not report a gesture
 
 `uiAction` fires whenever the control's state changes, whoever changed it. The

package/docs/badge_list.md

@@ -10,8 +10,9 @@ for, and nothing is set up for a case that cannot happen:
 - **`shrinkWrap`** — a hidden clone of the list is laid out to find the widest
   wrapped row, and the list is narrowed to it so the last row isn't ragged.
   Opt-in outside a `Picker` (a picker draws a border around the list, so the
-  ragged edge shows; elsewhere the work would often go unseen), and skipped
-  whenever `maxLines` is in play.
+  ragged edge shows; elsewhere the work would often go unseen). With `maxLines`
+  the rows are read first, at the full width, and the list is narrowed once the
+  surplus is gone — in place, no clone.
 - **`maxLines`** — every badge is laid out once, hidden; where the rows fell is
   read; the list is rendered again with the badges that fit and a `+N more`
   badge for the rest. Both renders land in the same frame. A width change of

package/docs/interactions.md

@@ -563,18 +563,27 @@ about a value the affordance does not write, so answering "read-only" to a
 gesture that was never going to write anything says nothing true. Use it only
 when that is really the case.
 
-#### On an element you draw yourself
+#### On something you draw yourself
 
-The claim is one attribute, and nothing is asked of the element carrying it —
-`ownTarget` is only the prop that writes it on a navi control:
+`ownTarget` is a `Box` prop too, so an affordance does not have to become a
+control to claim its press — a pastille positioned in a card's corner by its own
+class stays exactly what it was drawn as:
 
 ```jsx
-<button class="court_side" data-own-target="always" onClick={explain}>
+<Box as="button" ownTarget className="court_side" onClick={explain}>
 ```
 
-That is what the controls above read, and what the gesture readers read
-(`data-drag-handle`, `data-drag-ignore` and friends are the same vocabulary). An
-application keeps its own drawing and gets the press ownership all the same.
+On a box the prop does exactly one thing: it writes `data-own-target`. That
+attribute is the claim — it is what the controls above read, and what the
+gesture readers read (`data-drag-handle`, `data-drag-ignore` and friends are the
+same vocabulary). Writing it by hand on an element navi does not render works
+and is the last resort: a typo there is silent, whereas the prop is spelled
+once.
+
+The modes above are the other half, and they belong to controls: they are about
+a gate, a callout and a control's own read-only, none of which a box has. A box
+claims the press and nothing more; put the affordance on a control when what it
+does about a held zone matters.
 
 #### navi steps back; a plain `onClick` does not
 

package/docs/popup_open.md

@@ -8,6 +8,7 @@ What opens a `Dialog` or a `Popover`, and who owns the fact that it is open.
 - [Which element receives the command](#which-element-receives-the-command)
 - [The anchor](#the-anchor)
 - [Opening it ON something](#opening-it-on-something)
+- [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)
@@ -202,6 +203,107 @@ of the popup acting on it — but it is ordered against the popup's own handler
 registration, and it has to be attached in an effect on a ref. `onOpen` is that
 moment, said as a prop.
 
+## A press that opens a popup and acts on it
+
+A press that opens something and then does something with what came of it — a
+"save this guest" prompt on a row, which replaces the guest once the profile
+exists — is not a dialog plus a way home. It is a `Picker`: a trigger, a popup,
+and an `action` that runs on what the popup settled.
+
+```jsx
+// one per row: the trigger IS the thing that receives the answer
+<Picker
+  variant="icon"
+  rightSlotIcon={<DisketteSvg />}
+  action={async (created) => {
+    await USERS.GET_MANY.rerun();
+    replaceGuest(guest, created);
+  }}
+>
+  <GuestSavePrompt kind="player" name={guest.name} />
+</Picker>
+```
+
+Two things fall out of writing it this way, and both are the reason to prefer it
+over a shared dialog opened by `--navi-open`:
+
+- **what the popup needs to know travels as props**, because the popup is
+  written where the press is. No value to carry through the command, nothing to
+  read back out of an event;
+- **the popup is built the first time it opens**, not once per row on the render
+  that draws the list (see [what a popup holds while it is
+  closed](#what-the-popup-holds-while-it-is-closed)). A hundred rows is a
+  hundred triggers, not a hundred dialogs.
+
+The same component can of course be written once and used in every picker —
+`<GuestSavePrompt>` above is one — so "the prompt exists once" is a question
+about components, not about the DOM.
+
+### Composing a value, or doing work
+
+A picker mirrors **one** control in its popup — the first one that is not a
+button, a link or a control saying it is not the answer (`allowNameless`). That
+mirror is what makes `<Picker><List selectable/></Picker>` work with nothing
+wired: the picker's value IS the list's, both ways, and the picker's `action`
+runs on it when the popup closes.
+
+That is the shape for a popup that **composes a value**. A popup that **does
+work** — creates a profile, uploads a file — is the other shape, and it does not
+need the picker's `action` at all: the work is written where the press is, so
+its callback already has everything around it.
+
+```jsx
+<Picker variant="icon" rightSlotIcon={<DisketteSvg />}>
+  <Form
+    action={async (fields) => {
+      const created = await USERS.POST(fields);
+      replaceGuest(guest, created); // the row is right here
+    }}
+  >
+    …
+  </Form>
+</Picker>
+```
+
+Nothing travels back, because nothing left. This is the difference a shared
+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.
+
+### A trigger that is only an icon
+
+`variant="icon"` draws no value, and therefore no slot beside one either: the
+whole trigger is its `ui`.
+
+```jsx
+<Picker variant="icon" ui={<DisketteSvg />} />
+```
+
+Left out, that `ui` is the icon the slot would have shown — the chevron, or the
+one the picker's type carries (a pencil for `type="text"`, a calendar for
+`type="date"`), so `<Picker type="date" variant="icon" />` is a calendar and
+nothing else. `rightSlotIcon`/`rightSlot` belong to the shapes that DO draw a
+value and want something beside it; under `variant="icon"` the first is only the
+default for `ui`, and the second has nowhere to go — the clear cross included.
+
+### When a shared popup is still the right answer
+
+Two cases, and only two:
+
+- **the press can come from anywhere** — a keyboard shortcut, a menu, a button,
+  all opening the same thing. Written per press it would exist several times
+  over, each with its own open state;
+- **the popup has to outlive its trigger** — a row that leaves while its dialog
+  is open (a list refreshing under it) takes a popup written inside it with it.
+
+Neither is "one popup per row of a list", which is what a picker is for.
+
+Do not mix the two. A `<Form>` at the root of a picker's popup IS the mirrored
+control, so its value is the picker's value: handing the picker something else
+(a created profile, say) pushes it back down into the form's named fields and
+comes back as the form's aggregate. When the popup does work, let the work keep
+its result.
+
 ## Reacting to open and close
 
 `onOpen` is called on every open, before the popup builds anything (see

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/navi",
-  "version": "0.29.104",
+  "version": "0.29.106",
   "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.27",
+    "@jsenv/dom": "0.17.28",
     "@jsenv/humanize": "1.7.8",
     "@jsenv/validity": "0.4.2"
   },