@jsenv/navi 0.29.102 → 0.29.104

package/docs/AI_INSTRUCTIONS.md

@@ -123,11 +123,24 @@ consistency across the app, not from any single call site.
   inside a `Dialog`/`Popover`, and what a scroll does to hover
   (`hoverWhileScrolling`, `isScrolling()`). Read it before writing CSS to make
   something scroll — navi almost certainly already has the prop.
+- `docs/badge_list.md` — what a `BadgeList` does per prop (plain, `max`,
+  `shrinkWrap`, `maxLines`) and how it counts its badges (a `Badge` inside one
+  renders nothing and hands itself to the list — so badges must be direct
+  children). How `maxLines` reaches a list drawn inside a `Picker`
+  (`MaxLinesContext`, the picker's own clamp turned off), and why a list in a
+  picker needs a `fallback` — the placeholder text, as plain text: a picker
+  given a `ui` draws no placeholder of its own. Read it before putting a
+  `BadgeList` in a picker's `ui`, before wrapping its fallback in a `Badge`,
+  and before setting `maxLines` on the list rather than on the picker.
 - `docs/control_value.md` — who holds a control's value: nobody, a bound
   `signal` (two-way, in both directions), or you (`value`/`checked`). What
   `signal` + `defaultValue` says, what a signal holds for each kind of control,
-  and why `value` and `signal` cannot both be passed. Read it before wiring a
-  control's value by hand with `value` + `uiAction`.
+  and why `value` and `signal` cannot both be passed. It also holds the answer
+  to "a shortcut button beside a control" — `--navi-update`, gated like every
+  interaction, against an `onClick` writing the signal, which is not and fires
+  on a read-only control. Read it before wiring a
+  control's value by hand with `value` + `uiAction`, and before writing a button
+  that proposes a value.
 - `docs/create_and_edit.md` — the loop almost every app has: a screen that
   creates a resource, the page of what was created, a screen that edits it. The
   routes and why several match at once, one form for two modes, filling the edit
@@ -189,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,
@@ -203,9 +217,16 @@ consistency across the app, not from any single call site.
   of navi's own.
 - `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:
+  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).
   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.
+  cannot be got right from outside navi — and before stopping the propagation of
+  a pointerdown/mousedown/click to keep a popup from opening.
 - `docs/drag_to_travel.md` — a pointer pushing a whole screen aside
   (`SlideContainer`, `RouteTravel`) and a popup pushed back towards its edge:
   what the gesture is, and above all who owns a press several boxes want — a

package/docs/badge_list.md

@@ -0,0 +1,80 @@
+# BadgeList
+
+A row of badges that wraps. What it does at runtime depends on what it is asked
+for, and nothing is set up for a case that cannot happen:
+
+- **plain** — no `max`, no `maxLines`, no `fallback`, no `shrinkWrap`: one
+  element holding its children as-is. No registry, no effect, no measurement.
+- **`max` / `fallback`** — the badges are counted (see below), nothing is
+  measured, no DOM is watched.
+- **`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.
+- **`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
+  the room around the list triggers another measure — not a change of the
+  list's own width, which is what it produces, not what it is given.
+
+## How badges are counted
+
+A `Badge` inside a `BadgeList` does not render itself: it hands its props to
+the list through `BadgeListContext` and renders nothing. Badges register in
+tree order, so by the time the list gets to its own content it holds them all
+and knows how many there are before deciding what to show — without walking
+children vnodes, and without rendering a badge it then has to take back.
+
+Two consequences:
+
+- a `Badge` must be a **direct** child of the list — its rendering is moved
+  into the list, so `<div><Badge /></div>` takes the badge out of its wrapper;
+- a badge's own `key` goes to the registering vnode and not to the badge the
+  list draws, which is keyed by position. Reordering recreates the nodes rather
+  than moving them.
+
+## `maxLines` in a Picker
+
+A picker clamps its value with `maxLines`, which is CSS line-clamp — it counts
+line boxes of inline text and never sees a wrapped flex row. So a `BadgeList`
+rendered as a picker's `ui` reads the number from `MaxLinesContext` instead
+(the picker provides it, default 1) and caps its own rows to it, and the picker
+turns its own clamp off (`.navi_picker_value:has(.navi_badge_list)`). Nothing
+to set on the list; `maxLines` on the picker is enough, and a `maxLines` on the
+list itself is a local override.
+
+`max` is a different cap: a number of badges, whatever the rows. The two
+compose — the `+N` badge takes one of the `max` slots.
+
+## The `fallback`
+
+Without a `fallback`, an empty list renders **nothing**. Inside a picker there
+is one more thing to know: a picker given a `ui` draws that and only that, its
+own `placeholder` is **not** drawn next to it. An empty `BadgeList` in a picker
+is a blank picker — so the list's `fallback` is the placeholder, and the
+placeholder text is what to pass:
+
+```jsx
+<BadgeList fallback="Select skills…">
+  {selected.map((skill) => (
+    <Badge key={skill}>{skill}</Badge>
+  ))}
+</BadgeList>
+```
+
+Plain text is the right shape for it. It reads at the picker's own size, in the
+placeholder color — the picker colors its value slot that way while it holds
+nothing — and the picker box stays the same height empty and filled: the box is
+held one line tall by the picker's own line (the right slot is `1lh`), whatever
+the slot inside holds. That slot is a fraction of a pixel taller with a line of
+text than with a row of badges (0.89px at the default font size — a line is set
+by the picker's font and line-height, a badge by its own padding and smaller
+font), which nothing shows.
+
+A transparent `Badge` as fallback matches the slot to the pixel instead, but its
+text is badge-sized — smaller than the picker's — and reads as a badge with
+nothing in it. Only worth it where the slot itself is what something else is
+sized on. Section 4 of `src/control/demos/picker/2_select_multiple_demo.html`
+measures the three cases (no fallback, plain text, transparent badge), box and
+slot side by side.

package/docs/control_value.md

@@ -6,6 +6,7 @@ somewhere else in the app.
 
 - [The three answers](#the-three-answers)
 - [A bound signal works in both directions](#a-bound-signal-works-in-both-directions)
+- [A button that proposes a value is `--navi-update`](#a-button-that-proposes-a-value-is---navi-update)
 - [`signal` + `defaultValue`: the answer and where it starts](#signal--defaultvalue-the-answer-and-where-it-starts)
 - [What a signal holds, control by control](#what-a-signal-holds-control-by-control)
 - [Empty keeps the shape of the question](#empty-keeps-the-shape-of-the-question)
@@ -68,20 +69,64 @@ Both halves are worth knowing about, because each replaces a habit:
 The follow goes all the way up: a bound control that lives inside a group — two
 wheels in a `WheelGroup`, a field in a `ControlGroup` — makes that group
 re-aggregate when its signal is written, and the form above sees the new value.
-A shortcut that pushes the controls from the outside is an answer like any
-other: the wheels roll, and the submit lights up.
+A value pushed in from anywhere is an answer like any other: the wheels roll,
+and the submit lights up. Which is why a **button** offering such a value is not
+a hand-written signal write — see the next section.
+
+## A button that proposes a value is `--navi-update`
+
+A shortcut beside a control — "Tous niveaux" / "Aucun niveau" next to a list of
+levels, "1h / 1h30 / 2h" next to a pair of wheels, a suggestion under a field —
+is a value being offered to that control. It is not an action, and it is not a
+signal to write by hand:
 
 ```jsx
+<ControlGroup id="duration">
+  <TimeWheel name="duration" signal={durationSignal} />
+</ControlGroup>
+
+<Button
+  command="--navi-update"
+  commandFor="duration"
+  value={{ hours: 1, minutes: 30 }}
+>
+  1h30
+</Button>
+```
+
+- the **value** is the button's own `value`, whatever shape it has — a string, an
+  array of levels, an object of two wheels;
+- the **target** is `commandFor`, naming the control's id — left out, the nearest
+  control around the button is used, which is what a button placed inside the
+  control it proposes to wants;
+- and the press goes through the same gate as every other interaction, so a
+  read-only, disabled or busy control **refuses it and says why**.
+
+That last point is the whole reason, and the counter-example is what everybody
+writes first:
+
+```jsx
+// ✗ not gated — plain DOM. On a read-only sheet the button greys out and fires
+//   all the same, rewriting a value nobody is allowed to change.
 <Button
   onClick={() => {
-    hoursSignal.value = 2;
-    minutesSignal.value = 0;
+    durationSignal.value = { hours: 1, minutes: 30 };
   }}
 >
-  2h
+  1h30
 </Button>
 ```
 
+Writing a signal from an `onClick` is only right where nothing is being proposed
+to a control: moving something else on screen, seeding state before anything is
+drawn.
+
+The id goes **on the control**, and a group is one — `ControlGroup`, `Form`,
+`WheelGroup`, `List selectable`. Put it on a layout box around the control and
+the command finds an element that holds no value; navi says so in dev rather
+than letting the press do nothing at all. An id that matches nothing is a dev
+warning too, naming the id it looked for.
+
 ## `signal` + `defaultValue`: the answer and where it starts
 
 They are not competing, they answer two different questions:

package/docs/interactions.md

@@ -531,14 +531,62 @@ 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
-
-`data-drag-ignore` says the press there is none of the gesture's business: the
-element under it never starts a drag, and keeps both its cursor and its text
-selection. That is what a button living inside a carried piece needs — a cross
-that removes it, a menu — otherwise the piece is picked up from the button like
-from anywhere else. A click of its own usually has to stop there too, or the
-piece reads it as its own click.
+### An affordance inside somebody else's box: `ownTarget`
+
+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)}>
+  ×
+</Badge.Button>
+```
+
+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 an element 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:
+
+```jsx
+<button class="court_side" data-own-target="always" 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.
+
+#### 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/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.102",
+  "version": "0.29.104",
   "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.27",
     "@jsenv/humanize": "1.7.8",
     "@jsenv/validity": "0.4.2"
   },