@jsenv/navi 0.29.377 → 0.29.379

package/docs/AI_INSTRUCTIONS.md

@@ -227,7 +227,9 @@ to start when unsure which export solves a problem.
   viewport on Chrome Android and miscenters every dialog; `overflow-x: clip`.
 - `z_index.md` — DOM order first; a `z-index` without `isolation: isolate`
   competes with the page; navi's bands. Read before writing a `z-index`.
-- `typography.md` — text is a component; `maxLines` is the one truncation;
+- `typography.md` — text is a component; `maxLines` is the one truncation
+  (never `lineClamp`/`overflowEllipsis`/`text-overflow` by hand), on `Text`
+  and its family, a `Picker`'s value, a `Binder`'s tabs, a `BadgeList`'s rows;
   `attachLastChild`; one line height for everything (`--navi-line-height`,
   1.25). Read before an overflowing label, and before touching a
   `line-height`.

package/docs/popup_lift.md

@@ -116,7 +116,11 @@ paints nothing, off the first descendant that has its box and paints.
 So a transparent wrapper around the card is fine, and a card whose colour
 lives on a nested element of a different size is not: publish the colour on
 the box that is the card. A gradient or an image travels as well
-(`background-image`), a shadow does not.
+(`background-image`). A shadow or a halo (`box-shadow`, `filter:
+drop-shadow()`) is in the picture but cut at the box's edge, with the content
+the box uncovers — except when the two boxes are the same size (`box`) or the
+same aspect ratio (`scene`): both pictures then fit the box the whole way,
+nothing needs uncovering, and the ink travels with the box.
 
 Corners are not paint: they are written per box, on purpose — the same card at
 two sizes does not want the same round, a 6px corner stops showing on a big

package/docs/typography.md

@@ -66,9 +66,34 @@ Do **not** write `lineClamp={1}`. `lineClamp` and `overflowEllipsis` are raw
 is not a `Text` (or deliberately opts out of it) and still needs that CSS. They
 know nothing about each other, so `lineClamp={1}` gives a single-line webkit box
 without the single-line handling `maxLines={1}` brings — `maxLines` switches the
-element to a block, sets `min-width: 0` on itself, and keeps `white-space`
-sensible for the tag it renders (a `<p>` keeps its line breaks). On a `Text`,
-`maxLines` is always the right answer.
+element to a block, sets `min-width: 0` on itself, and states the `white-space`
+its line count needs: one line does not wrap, n lines may (a `<p>` keeps its
+line breaks in both cases). That last part is what makes it hold anywhere:
+`white-space` is inherited, and a raw clamp put under a single-line ancestor — a
+`Picker`'s value, a `Time` — inherits `nowrap`, gets one line to cut, and lets
+the text run past its box instead. On a `Text`, `maxLines` is always the right
+answer, and an explicit `noWrap`/`pre`/`preLine` beside it still wins.
+
+### Who takes `maxLines`
+
+The prop is the same everywhere: a number of lines, cut with an ellipsis.
+
+- **`Text`** and everything built on it — `Title`, `Paragraph`, `Caption`,
+  `Link`, `Time`, `Quantity`… — the prop flows through. `Badge` is `maxLines={1}`
+  by construction.
+- **`Picker`** — its value, `maxLines={1}` by default; `variant="text"` and
+  `variant="bare"` draw the caller's own thing and are not clamped, a `Text` in
+  their `ui` cuts itself with its own `maxLines`.
+- **`PickerSpin`** (`DaySpin`, `TimeSpin`…) — its value; left out, a long value
+  wraps and the box grows.
+- **`Binder`** — its tab labels, `maxLines={1}` by default, `false` lets them
+  wrap; overridable per item.
+- **`BadgeList`** — its rows, measured (a wrapped flex row is not a line box):
+  the badges that fit and a "+N" badge for the rest. Inside a `Picker` it
+  inherits the picker's count, see [badge_list.md](./badge_list.md).
+
+On a plain `Box`, `maxLines` is the raw CSS mapping described above: it clamps
+whatever the box holds, and states nothing else.
 
 ### Truncation only happens if something says "you may shrink"
 

package/package.json

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