@jsenv/navi 0.29.30 → 0.29.32

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

@@ -63,6 +63,7 @@ condition: `{ swipe_right: canArchive && archive }`.
 | `swipe_left` `swipe_right` `swipe_up` `swipe_down`     | a press that travels                           |
 | `longpress`                                            | a press held still                             |
 | `move` `reorder` `toss`                                | the element carried, and what letting go means |
+| `grab`                                                 | the instant a drag takes hold of it            |
 | `"keyboard:<shortcut>"`                                | keys, e.g. `"keyboard:ctrl+backspace"`         |
 
 A name nothing knows how to detect produces a dev warning naming the detectors
@@ -109,17 +110,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 {
@@ -227,6 +229,39 @@ name what moves.
 | `data-drag-delay` `data-drag-slop` `data-drag-threshold` | when the press becomes a grab          |
 | `data-toss-distance` `data-toss-speed`                   | how far and how fast counts as a throw |
 
+### Saying the grab is acquired: `grab`
+
+The three above answer the **release**. Between the press and the release there is
+one instant that counts for the hand: the one where the object stops being pressed
+and starts being held. `grab` is that instant — the same one whichever way the drag
+was entered, a finger held still or a mouse travelled a few pixels.
+
+```jsx
+<Box
+  interactions={{
+    toss: (event) => remove(event.detail.id),
+    grab: () => navigator.vibrate?.(10),
+  }}
+/>
+```
+
+It matters most where it is least visible. On a screen the held object is under the
+thumb that hides it, so the only feedback available is the one that is felt; without
+it the hand waits, doubts the press was heard, and lets go too early — the whole
+gesture fails, not its decoration. With a mouse the grab is acquired after a few
+pixels and the object has visibly moved, so the answer is already there.
+
+Nothing here is about vibration: a sound, a class, a measure are the same moment.
+
+`grab` **reports, it does not ask**: what it returns is not waited on, and
+preventing its event does not call the gesture off. And it is not an interaction on
+its own — declared without `move`, `reorder` or `toss` there is no gesture for it to
+be the beginning of, and a dev warning says so. Its detail carries `pointerType` and
+the `gestureInfo`.
+
+A `longpress` needs none of this: it already happens at the moment the hold is
+acquired, not at the release.
+
 ### Dressing the clone
 
 What the pointer carries is a copy, and a copy of a transparent element is
@@ -399,6 +434,8 @@ container above it does not take the gesture:
   the registry.
 - `src/control/interaction/interaction_press.js` — swipes and holds, and what a
   swipe writes on the element.
+- `src/control/interaction/interaction_drag.js` — `move`, `reorder`, `toss` and
+  the `grab` moment.
 - `src/control/interaction/interaction_keyboard.js`,
   `interaction_native.js` — the other two detectors.
 - `src/control/demos/38_interactions_demo.html` — every case above, plus a

package/package.json

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