@jsenv/navi 0.29.103 → 0.29.105

package/docs/AI_INSTRUCTIONS.md

@@ -202,7 +202,8 @@ consistency across the app, not from any single call site.
   `Text`, `maxLines` as the one way to truncate (and why `lineClamp={1}` is
   not it), what makes truncation actually happen in a flex row, and the two
   opposite shapes of "icon | text | icon" — the end icon kept outside the
-  truncating text, or `attachLastChild` so it never lands alone on a line.
+  truncating text, or `attachLastChild` so it never lands alone on a line —
+  and why an emoji belongs only in free text, rendered with `emojiAsIcon`.
   Read it before writing an overflowing label or a row with a trailing icon.
 - `docs/i18n.md` — where the texts an app displays live: `interpolateText` /
   `<Interpolate>` for one sentence, `createI18n` for the app's registry,
@@ -217,7 +218,11 @@ consistency across the app, not from any single call site.
 - `docs/interactions.md` — the `interactions` prop: making a component answer a
   swipe, a held press, a shortcut, and registering a gesture navi does not have.
   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.
+  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 `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

@@ -531,15 +531,11 @@ sideways), while a `move` goes wherever it is put, a `land` wherever the board h
 places and a `toss` wherever it was thrown (`xy`). `data-drag-delay`,
 `data-drag-slop`, `data-drag-threshold` tune when the press becomes a grab.
 
-### A control inside something draggable
+### An affordance inside somebody else's box: `ownTarget`
 
-`ownTarget` on the control says it: a chip's cross inside a carried piece, an
-eye on a row that travels, a diskette on a picker's façade. The press belongs to
-that control alone — no gesture starts under it, and nothing above it answers
-the mousedown or the click. It also follows the interactivity of the zone around
-it: read-only, disabled or busy, the affordance goes rather than greys (pass
-`ownTarget="refuse"` for one whose presence is information in itself), and its
-`onClick` waits for its own gate instead of firing from the DOM.
+A chip's cross inside a carried piece, an eye on a row that travels, a diskette
+on a picker's façade. It is aimed AT, not merely inside, and the press belongs
+to it alone:
 
 ```jsx
 <Badge.Button ownTarget onClick={() => remove(id)}>
@@ -547,9 +543,59 @@ it: read-only, disabled or busy, the affordance goes rather than greys (pass
 </Badge.Button>
 ```
 
-`data-drag-ignore` says the same thing to the gesture alone, for something that
-is not a control: the press there is none of the gesture's business, and the
-element keeps both its cursor and its text selection.
+No gesture starts under it, no navi control above it answers the mousedown or
+the click, and its `onClick` waits for its own interaction gate instead of
+firing from the DOM.
+
+#### Does it write to the control it sits in?
+
+That question, and nothing else, picks the mode:
+
+| what it does                                                 | mode                 | on a read-only / disabled / busy zone     |
+| ------------------------------------------------------------ | -------------------- | ----------------------------------------- |
+| writes to it (a cross that removes, a stepper)               | `ownTarget`          | it goes                                   |
+| writes to it, and its presence says there is something there | `ownTarget="refuse"` | it stays and refuses with a callout       |
+| never touches it (a diskette saving into MY address book)    | `ownTarget="always"` | nothing changes: still lit, still pressed |
+
+A greyed cross that still removes is worse than no cross — hence the default.
+`"always"` is the other extreme and the caller owns it: the zone's read-only is
+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 something you draw yourself
+
+`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
+<Box as="button" ownTarget className="court_side" onClick={explain}>
+```
+
+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
+
+What `ownTarget` stops is navi answering: the controls above it, and the
+gestures. It does **not** stop the event — the propagation is left whole, so
+that everything which is not a navi interaction still sees the press it always
+saw. A raw `onClick` on an ancestor is one of those, and still fires; stop it
+there yourself if it must not.
+
+`data-drag-ignore` says a narrower thing, to the gesture alone: the press there
+is none of the gesture's business, and the element keeps both its cursor and its
+text selection.
 
 ### What says a thing can be picked up
 

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,79 @@ 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.
+
+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/docs/typography.md

@@ -28,7 +28,7 @@ same names — `size="l"` is a font size, `padding="l"` is a gap.
 
 Live examples: `src/text/demos/*_demo.html` — one page per concern
 (`text_overflow_demo.html`, `text_spacing_demo.html`, `text_loading_demo.html`,
-`text_attach_last_child_demo.html`, `icon_demo.html`).
+`text_attach_last_child_demo.html`, `text_emoji_demo.html`, `icon_demo.html`).
 
 ## Truncating: `maxLines`, and nothing else
 
@@ -61,7 +61,9 @@ width must say it too**, or the whole chain grows instead of truncating:
 
 ```jsx
 <Box flex width="300" spacing="s">
-  <Box flex expandX minWidth="0">   {/* without minWidth the row just grows */}
+  <Box flex expandX minWidth="0">
+    {" "}
+    {/* without minWidth the row just grows */}
     <Text maxLines={1}>…</Text>
   </Box>
 </Box>
@@ -153,6 +155,45 @@ Two things opt out of that flow:
   the space characters too. This replaces them with padding-based spaces, so the
   underline stops at the text. `Link` sets it.
 
+## Emoji
+
+**An emoji is not a character the layout can absorb.** The system emoji fonts
+(Apple Color Emoji, Segoe UI Emoji, Noto Color Emoji) have a taller
+ascent/descent than any text font, so the moment an emoji sits in a line, that
+line is taller than the ones around it: a row shifts down next to its
+neighbours, a paragraph's lines are unevenly spaced, a truncated label no
+longer lines up with its siblings.
+
+So, first: **an emoji is only expected in free text a user typed** — a message,
+a comment, a description. It has no business in a name, a title, an identifier,
+a label. Validate those fields so it never gets in, rather than teaching every
+row of the app to survive it.
+
+Where it is expected, `emojiAsIcon`:
+
+```jsx
+<Text emojiAsIcon>Salut 👋 on se retrouve au parc 🌳 ?</Text>
+```
+
+Every emoji found in the string children is rendered inside an `Icon`, which
+caps it at `1em` and centers it on the line like any glyph icon — the line keeps
+the height of its text, on one line or several. This is what chat apps do (an
+emoji is a 1em box, never a glyph with its own metrics). `Button` and
+`MessageBox` have it on by default — a label is one line whose height
+everything around it relies on, a message is free text; `Badge` forwards it,
+opt-in.
+
+What it does not do, and that is accepted: under `maxLines` the `Text` clips at
+its own box — that is what truncation is — and an emoji drawn a little beyond
+its 1em box can lose a sliver at the top. The line stays aligned, which is the
+part that matters.
+
+**Do not raise `lineHeight` because of emoji.** The default line height keeps
+text compact and, with `emojiAsIcon`, holds up even when nearly every word is
+an emoji (see the dense cases in `text_emoji_demo.html`). A `lineHeight` is a
+typographic choice for the text itself — a paragraph that wants air — never a
+workaround for a glyph that grew too tall; that glyph gets `emojiAsIcon`.
+
 ## Text that must not move when its style changes
 
 A label that becomes bold when its row is selected reflows everything around it.

package/package.json

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