@jsenv/navi 0.29.103 → 0.29.104

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 `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 — and before stopping the propagation 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,50 @@ 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 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.103",
+  "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"
   },