@jsenv/navi 0.29.30 → 0.29.31

package/docs/control_group.md

@@ -46,12 +46,15 @@ Live examples: `src/control/demos/15_group_demo.html`.
 - **Corners**: the first member loses the radius on the side that joins, the
   last one loses it on the other side, and any member in between loses all
   four. A single member keeps its own radius — a group of one looks like the
-  control alone.
-- **Overlap order**: the member under the pointer, and the member holding
-  focus, paints above its neighbours (`position: relative; z-index: 1`).
-  Without it the border color change and the focus ring of the active member
-  would be sliced by whichever neighbour is painted after it. The value is `1`
-  and there is deliberately no `isolation: isolate` — see
+  control alone. The ask is made twice, in two forms — see below.
+- **Overlap order**: the member under the pointer, and the member showing a
+  focus ring, paint above their neighbours (`position: relative` plus
+  `--navi-z-index-control-hovered` / `-focused`). Without it the border color
+  change and the focus ring of the active member would be sliced by whichever
+  neighbour is painted after it. The focused member is matched whether it wears
+  `data-focus-visible` itself or merely contains it — a control that wraps a
+  real input (`Picker`, `Spin`) draws the ring on its own frame while the
+  keyboard is held inside. There is deliberately no `isolation: isolate` — see
   [z_index.md](./z_index.md).
 
 Nothing else: a group does not restyle its members, does not impose a size,
@@ -59,14 +62,21 @@ and takes any `Box` prop for its own layout.
 
 ## Writing a control that belongs in a group
 
-A group squares the corners of its **direct children** — it addresses the
-control root, never the elements inside it. So a control declares the radius
-of its frame on its own root element, and whatever inner element actually
-paints the frame takes `border-radius: inherit`:
+A group never writes a selector that reaches inside a member — a member's
+subtree holds more than the member (a `Picker` renders its popup inside
+itself, not in a portal; a control carries buttons of its own, like the clear
+cross in a slot), and a rule matching "some descendant" finds all of them. It
+asks for a square corner in two forms instead, and a control answers with
+whichever fits.
+
+**The property, on the member itself.** A control declares the radius of its
+frame on its own root, and whatever inner element paints that frame takes
+`border-radius: inherit`. The group sets the property on the root; the frame
+follows.
 
 ```css
 .navi_thing {
-  /* The radius is declared here even though the frame below draws it */
+  /* Declared here even though the box below is what draws it */
   border-radius: var(--thing-border-radius);
 
   .navi_thing_box {
@@ -76,6 +86,36 @@ paints the frame takes `border-radius: inherit`:
 }
 ```
 
+**The custom property, which travels.** A member is not always the control
+that carries the frame: a button can arrive wrapped in a tooltip or a link, at
+any depth. So the group also sets `--x-corner-top-left-radius` and its three
+siblings on the member, and a control that can arrive wrapped reads them as an
+override of its own radius. The `--x-` prefix says what they are: navi's
+internal wiring between a group and its members, not a surface an app writes
+to (an app changes a radius with the `borderRadius` prop, which lands in the
+fallback below and is what the corner keeps everywhere the group has no claim):
+
+```css
+.navi_thing {
+  border-top-left-radius: var(
+    --x-corner-top-left-radius,
+    var(--thing-border-radius)
+  );
+  /* …and the three others */
+}
+```
+
+**Whoever answers the ask also stops it.** Custom properties inherit all the
+way down, so the control that consumed a corner sets the four back to
+`initial` on the first element inside it — otherwise a button in a slot, or the
+Save button of a form in an open popup, reads a corner meant for the row that
+opened it. `Popover` and `Dialog` stop it too, at their own root: nothing a
+popup holds is at a seam.
+
+Reference: `.navi_button_content` in `button_ui.jsx` (a button reads then
+stops), `.navi_picker_right_slot`, `.navi_input_slot`, `.navi_popover`,
+`.navi_dialog`.
+
 A control that declares its radius on an inner element instead is invisible to
 `Group`: it keeps round corners in the middle of the row, and no rule written
 in `group.jsx` can reach it without naming that private class — which is how a

package/docs/interactions.md

@@ -109,17 +109,18 @@ in dev.
 navi makes the element follow the finger — there is nothing to decide about
 that — and says where the gesture is up to:
 
-| Written on the element                   | Meaning                                   |
-| ---------------------------------------- | ----------------------------------------- |
-| `--swipe-pulled`                         | how far it has come, signed, in px        |
-| `--swipe-progress`                       | the same as a fraction, signed, inherited |
-| `[data-swiping="left\|right\|up\|down"]` | which way, while a finger holds it        |
-| `[data-swipe-past-threshold]`            | letting go now would go through with it   |
+| Written on the element                   | Meaning                                 |
+| ---------------------------------------- | --------------------------------------- |
+| `--swipe-pulled`                         | how far it has come, signed, in px      |
+| `--swipe-progress`                       | the same as a fraction, signed          |
+| `[data-swiping="left\|right\|up\|down"]` | which way, while a finger holds it      |
+| `[data-swipe-past-threshold]`            | letting go now would go through with it |
 
 WHAT is revealed behind is yours: navi does not know what putting a row away
 looks like. A trail is usually a child of the swiped element sized off
-`--swipe-pulled` — which is what makes those values reachable from CSS at all, a
-sibling could not read them.
+`--swipe-pulled`. Both values inherit, so a child reads them; a sibling cannot,
+which is why the trail goes inside — and it travels with the row, since what
+navi translates is the element that declares the gesture.
 
 ```css
 .trail {

package/package.json

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