@jsenv/navi 0.29.300 → 0.29.302

package/docs/dialog_shape.md

@@ -77,6 +77,14 @@ adjusted without giving up the rest:
 | `expandX`             | `true`     | container-wide, same reason                           |
 | `scrollCapture`       | `true`     | a drag past the sheet's edge must not reach the page  |
 
+A `layer="top"` dialog flush with an edge of the screen — a docked sheet on the
+bottom, anything with `marginWithContainer={0}` — keeps the band the device
+reserves there (`env(safe-area-inset-*)`: the notch, the home indicator,
+Safari's floating bar). The surface still reaches the edge; what it holds stops
+at the band. Only the device's own inset: the dialog is in front of the app's
+fixed bars, so `--navi-safe-area-inset-*`, which counts them too (see
+[`safe_area.md`](./safe_area.md)), is not what it reads.
+
 Plus a swipe-down-to-close, held by the sheet's `header` (a `Box` with the
 `header` prop) and by anything carrying `data-swipe-grip` — never by the whole
 sheet, so a board something is dragged across keeps its own gestures. See
@@ -181,10 +189,17 @@ Two things make it safe to reach for:
 
 ## A `layer="local"` dialog answers to its container
 
-`layer="top"` (the default) is a real `<dialog>` in the browser's top layer:
-native focus trap, `Escape`, hardware back-button dismissal, the rest of the
-document made inert. `layer="local"` stays in normal document flow, confined to
-and clipped by its own positioned ancestor.
+`layer="top"` (the default) is a real `<dialog>` in the browser's top layer,
+placed against the screen and clipped by nothing — modal, with everything
+behind made inert, unless `backdrop={false}` says otherwise (see
+[`popup_backdrop.md`](./popup_backdrop.md)). `layer="local"` stays in normal
+document flow, confined to and clipped by its own positioned ancestor.
+
+For a **docked** dialog that is the choice of which edge the sheet rests on:
+`layer` names the container, and docking makes the sheet flush and full width
+against it. A sheet meant for the bottom of the screen is `layer="top"`, even
+when the page behind it must stay live — that is `backdrop={false}`, not
+`layer="local"`.
 
 For the shape, that swaps what every bound is measured against: the container
 becomes that ancestor's box, read through
@@ -194,10 +209,10 @@ is open — its backdrop covers the scrollport, not the scrolled content, so
 scrolling would slide the dialog away and reveal what the backdrop does not
 cover. `scrollCapture` is what extends that lock to the whole page.
 
-One accepted limitation, not an oversight: a local dialog **cannot** be
-dismissed by the hardware/gesture back button. No web API hooks into that
-outside the browser's own modal-dismissal stack, which only a genuine
-`showModal()` element joins.
+One accepted limitation, not an oversight: a dialog that is not modal —
+`layer="local"`, or `backdrop={false}` — **cannot** be dismissed by the
+hardware/gesture back button. No web API hooks into that outside the browser's
+own modal-dismissal stack, which only a genuine `showModal()` element joins.
 
 ## Reaching all of this through a `Picker` or a `SplitButton`
 

package/docs/interactions.md

@@ -7,6 +7,8 @@
 - [Which interaction asked](#which-interaction-asked)
 - [Reaching the control](#reaching-the-control)
 - [What a swipe draws, and what it leaves to you](#what-a-swipe-draws-and-what-it-leaves-to-you)
+- [Twice, whichever hand it is](#twice-whichever-hand-it-is)
+  - [The click on the way there](#the-click-on-the-way-there)
 - [Carrying something, or a surface under the hand](#carrying-something-or-a-surface-under-the-hand)
 - [An affordance inside somebody else's box: `selfInteractions`](#an-affordance-inside-somebody-elses-box-selfinteractions)
   - [Why it is a list, and why it is required](#why-it-is-a-list-and-why-it-is-required)
@@ -87,16 +89,32 @@ which the carrying interactions answer with).
 
 ### The interactions navi detects
 
-| Key                                                    | Read from                                                   |
-| ------------------------------------------------------ | ----------------------------------------------------------- |
-| `mousedown` `mouseup` `click` `dblclick` `contextmenu` | the browser's own events                                    |
-| `swipe_left` `swipe_right` `swipe_up` `swipe_down`     | a press that travels                                        |
-| `longpress`                                            | a press held still                                          |
-| `move` `reorder` `land` `toss` `leave`                 | the element carried, and what letting go means              |
-| `moving`                                               | the same carry, told on every frame                         |
-| `grab` `release` `refuse`                              | the instants a drag takes hold, lets go, or does not happen |
-| `pan` `zoom`                                           | a surface under the hand, or under a wheel                  |
-| `"keyboard:<shortcut>"`                                | keys, e.g. `"keyboard:ctrl+backspace"`                      |
+| Key                                                | Read from                                                   |
+| -------------------------------------------------- | ----------------------------------------------------------- |
+| `mousedown` `mouseup` `click` `contextmenu`        | the browser's own events                                    |
+| `swipe_left` `swipe_right` `swipe_up` `swipe_down` | a press that travels                                        |
+| `longpress`                                        | a press held still                                          |
+| `double_click` `single_click`                      | two presses in a row, or one that stayed alone              |
+| `move` `reorder` `land` `toss` `leave`             | the element carried, and what letting go means              |
+| `moving`                                           | the same carry, told on every frame                         |
+| `grab` `release` `refuse`                          | the instants a drag takes hold, lets go, or does not happen |
+| `pan` `zoom`                                       | a surface under the hand, or under a wheel                  |
+| `"keyboard:<shortcut>"`                            | keys, e.g. `"keyboard:ctrl+backspace"`                      |
+
+Two holds on one press — a `longpress` declared on something inside an
+element that declares one too — are answered by the nearer one, the way a
+click is the innermost target's: the inner hold fires, the outer wait is given
+up. Delays being equal; an outer hold made shorter than the inner one fires
+first.
+
+There is no `dblclick` in that table, on purpose: the browser fires it for a
+mouse and never for a finger, so an element declaring it would answer half the
+hands that reach it. `double_click` is the same gesture counted from the
+pointer — see [Twice, whichever hand it is](#twice-whichever-hand-it-is). navi says so in dev, once per element, the first time it happens: the
+outer hold is a declaration that can never fire, and a picker opened by
+`openOn="longpress"` around a card that already holds one is exactly where it
+happens. One hold has one meaning — two things on one card want two gestures
+(a hold and a click), not two holds.
 
 A name nothing knows how to detect produces a dev warning naming the detectors
 that exist. The carrying family and the two surface streams each have a file of
@@ -190,6 +208,67 @@ comes back once it settles — a failure leaves the row in place so it can be tr
 again. What a success does to the element is yours (a list that redemands its
 rows, a row that leaves): navi does not make it disappear.
 
+## Twice, whichever hand it is
+
+At the finger there is no `dblclick`. There is not even a second `click`: two
+taps in the same place are a gesture the browser keeps for itself (its own
+zoom), so it withholds them — measured on a phone, two taps 120 ms apart give
+two `pointerup`, ONE `click` and no `dblclick` at all. Anything that wants to
+mean "twice" therefore has to count presses, which is what `double_click` is:
+
+```jsx
+<Box interactions={{ pan, zoom, double_click: (event) => open(event) }} />
+```
+
+One name for the mouse and for the finger — a tap is a click, and the same
+gesture opens the plan at a desk and on a phone.
+
+The rhythm is one window, opened by the FIRST press: the second has to land
+inside it, and near enough to it.
+
+| Attribute                 | Default | Meaning                                     |
+| ------------------------- | ------- | ------------------------------------------- |
+| `data-double-click-delay` | `400`   | ms the window stays open                    |
+| `data-double-click-slop`  | `30`    | px the second press may land from the first |
+
+The two numbers are read against the rest of the family rather than picked. 400
+sits under the hold's 450: a pause longer than the wait navi calls "held" is
+longer than one gesture — which also means a press slow enough to be a hold
+cannot start a double click, and a hold answered on the second press takes that
+press back. 30 px is a fingertip and not a pixel, because between the two the
+finger leaves the glass and lands again where it means to; the 8 px of
+`data-longpress-slop` answer a different question (has this finger stood
+still?).
+
+### The click on the way there
+
+By default both happen, the way they do in a browser: the first press is a
+`click`, and the second is answered by the `double_click` alone — the click it
+would have left behind is swallowed, the way every gesture swallows the one it
+leaves.
+
+`single_click` is for the case where even the first one is too much: two
+answers that exclude each other — a plan that opens on the double must not do
+whatever a lone tap does on the way there. It is the same window read the other
+way, the tap that STAYED alone, said once the window has closed on it:
+
+```jsx
+<Box
+  interactions={{
+    single_click: (event) => select(event),
+    double_click: (event) => open(event),
+  }}
+/>
+```
+
+It costs that wait, which is why it is a name a caller picks rather than
+something a declared `double_click` imposes on `click`. And it hands the
+element's click over: the click each tap leaves behind is swallowed, so a
+control that wants its action on a lone click asks for it there —
+`single_click: "request_action"`, not `action` reached by a click that no longer
+arrives. A keyboard activation is not held: nothing can double it, so it is said
+at once.
+
 ## Carrying something, or a surface under the hand
 
 Two families of interaction have a file of their own, because each is a subject:
@@ -408,6 +487,10 @@ tuned in one place and a stylesheet can read the same value.
 | `data-longpress-delay` | `450`   | ms the press must be held                 |
 | `data-longpress-slop`  | `8`     | px the pointer may drift during the wait  |
 
+Plus the two the double click is counted with, `data-double-click-delay` and
+`data-double-click-slop` (see [Twice, whichever hand it
+is](#twice-whichever-hand-it-is)).
+
 A threshold is a **fraction and never a distance**: the same gesture must mean
 the same thing on a phone and on a wide screen. Speed answers on its own on top
 of it — a brief flick counts whatever the distance covered.
@@ -516,17 +599,18 @@ container above it does not take the gesture:
   finger, which is the native gesture. To place it at the press point rather than
   on the element:
   `triggerNaviCommand(target, "--navi-open", interactionEvent, { anchor })`.
-- **A swipe has no keyboard equivalent.** There is nothing to press that means
-  "swipe right", so a swipe is only reachable if something else on the element
-  offers the same thing — a `"keyboard:<shortcut>"`, a `contextmenu`, or the
-  control's own action.
+- **A swipe has no keyboard equivalent, and neither has a double click.** There
+  is nothing to press that means "swipe right", and no key that means "twice",
+  so either is only reachable if something else on the element offers the same
+  thing — a `"keyboard:<shortcut>"`, a `contextmenu`, or the control's own
+  action.
 
 ## Reference
 
 - `src/control/interaction/interaction_registry.js` — the prop, the four values,
   the registry.
-- `src/control/interaction/interaction_press.js` — swipes and holds, and what a
-  swipe writes on the element.
+- `src/control/interaction/interaction_press.js` — swipes, holds and the two
+  taps, and what a swipe writes on the element.
 - `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/docs/pan_zoom.md

@@ -43,8 +43,8 @@ when it lands; the pan stepping back for what is carried across the surface (a
 for); the pinch not beginning as a pan under its first finger; the wheel and the
 pinch writing one `zoom`; the capture, the pointer the browser drops, the click
 the release leaves behind. A pointer pans only once it has travelled a few px
-(`data-drag-threshold`), so a tap stays a tap and a `longpress` declared beside
-`pan` still gets its hold.
+(`data-drag-threshold`), so a tap stays a tap: a `longpress` declared beside
+`pan` still gets its hold, and a `double_click` still gets its two presses.
 
 Declared alone, `zoom` takes two fingers and the wheel and leaves one pointer to
 whatever else reads it; `pan` alone leaves the wheel to the page.

package/docs/popup_backdrop.md

@@ -61,13 +61,34 @@ questions. `"invisible"` is for a popup that must absorb — a menu whose
 dismissing click must not also press what is under it — without dimming the
 page for it. `backdrop={false}` is for a popup that must not absorb at all.
 
-**Only a non-modal popup can honour it.** `Popover` always can, either layer. A
-`Dialog` can only in `layer="local"`: the default `layer="top"` is shown with
-`showModal()`, which makes everything behind genuinely inert before any of
-navi's code runs — there is no press left to let through, and asking for one
-warns. `Popup` follows from that: it forwards `backdrop` to its popover and
-drops it for a top-layer dialog, so the same usage that gives one press on a
-desktop costs two once the small-screen resolution picks dialog mode.
+**It is what decides whether a popup is modal.** `Popover` is never modal,
+either layer. A `Dialog` is modal exactly when it has a wall: with one, a
+top-layer dialog is `showModal()`'d and the browser makes everything behind
+genuinely inert; without one it goes to the same top layer through the Popover
+API (`popover="manual"`), placed against the screen just the same, over a page
+that stays live. `Popup` forwards `backdrop` in both modes, so which of popover
+or dialog the small-screen resolution picks says nothing about whether one
+press or two are needed.
+
+That is what a bottom sheet on a phone is made of. `dockedOnSmallTouchScreen`
+docks the dialog against its container, and `layer` is what that container is —
+`"top"` for the screen, `"local"` for the box the popup was declared in. A
+sheet flush with the bottom of the screen over a map still being read object by
+object is `layer="top"` for the shape and `backdrop={false}` for the map:
+
+```jsx
+<Popup dockedOnSmallTouchScreen layer="top" backdrop={false}>
+```
+
+Going `layer="local"` to keep the map live instead confines the sheet to the
+box it was declared in — full width and flush against _that_, which on a
+partial container reads as a sheet that failed rather than as a sheet.
+
+What a wall-less dialog gives up is the one thing only a modal gets natively:
+the hardware/gesture back button no longer dismisses it (same accepted
+limitation as `layer="local"`, see [`dialog_shape.md`](./dialog_shape.md)).
+Focus is not trapped either, deliberately — a page meant to be reachable is
+meant to be reachable with the keyboard too.
 
 `pointerInteractionOutsideEffect="capture"` and `backdrop={false}` contradict
 each other — absorbing is what a wall does — and navi warns rather than

package/docs/popup_open.md

@@ -409,8 +409,9 @@ The picker's `action` runs on the trigger, not in the popup: it is dispatched
 on the close that keeps, and the popup goes while it runs. So what is still on
 screen answers for the write — `aria-busy` and the loading outline on the
 trigger while the request is out, the error callout on it if the server
-refuses, and the value rolled back to the last accepted one (`resetOnError`,
-on by default for a picker: nobody is left mid-edit behind a closed popup). A
+refuses, and the value rolled back to the last accepted one — on by default
+for a picker, and what one wants: nobody is left mid-edit behind a closed
+popup, and the card goes on saying what the server knows. A
 card that IS the trigger (`variant="bare"`, the card as `ui`) therefore waits
 as a card and is refused as a card, wherever in the tree the sheet was written.
 
@@ -422,9 +423,6 @@ as a card and is refused as a card, wherever in the tree the sheet was written.
   ui={<MatchCard match={match} />}
   value={match}
   action={(next) => MATCH.PATCH({ id: match.id, ...next })}
-  // the draft is what the person typed, and the sheet is the only place it
-  // can be found again: keep it when the server says no
-  resetOnError={false}
 >
   <ControlGroup>
     <MatchCard match={match} editable />
@@ -434,6 +432,16 @@ as a card and is refused as a card, wherever in the tree the sheet was written.
 </Picker>
 ```
 
+The card shows the answer the moment the sheet leaves when its `ui` is drawn
+from what the picker holds rather than from what the caller knows — the same
+state navi's own default `ui` reads, rolled back by `resetOnError`, so nothing
+about the pending value is the caller's to keep or to put back. Two ways to
+read it: `ui={MatchCard}` hands the component `value`, `loading` and
+`interactive` as props; `ui={<MatchCard match={match} />}` keeps the caller's
+own props and reads the same three with `usePickerState()` inside. The
+`loading` is the wait: navi's loading outline is a two-pixel run around the
+box, which a card-sized trigger draws its own waiting state for.
+
 What the picker measures as "changed since open" is what its mirrored group
 holds. A piece of the answer living outside the controls — a seating
 rearranged by drag, kept in component state — has to be held by a control in
@@ -442,13 +450,41 @@ as nothing changed and nothing runs.
 
 Two props finish the construct. `openOn="longpress"` (or
 `["longpress", "contextmenu"]`) makes the hold what opens it, so a tap on the
-card stays a tap — what a card in a list needs. `animation="growing"` with
-`dialogSizeFromAnchor`, `dialogMaxWidth="var(--anchor-width)"`,
+card stays a tap — what a card in a list needs: the drawing gets its pointer
+back, a link in it navigates, a button in it presses, a picker in it opens on
+its own click, with nothing to declare. Two pickers on one card is the score
+sheet inside the edit card (`12_picker_card_demo.html`): the inner one names
+the card as its `anchor` so it lifts the whole card, and says `standalone` so
+its value stays its own. One card, one wait: each picker wears the other's
+run through `loading` (from its `onActionStart`/`onActionEnd`), so while
+either write is out the hold and the click are both refused, with the busy
+reason where the finger is — the click only once the score picker says
+`openWhileReadOnly={false}`: a busy picker otherwise still opens, to be read,
+and a sheet of fields to fill in is not that. A hold declared inside the card answers before the
+card's own: the nearer hold takes the press. `animation="growing"` with
+`dialogSizeFromAnchor` (as wide as the card, floor and ceiling),
 `popupBackgroundColor="transparent"` and `popupBoxShadow="none"` lifts the
 card out of its place and puts it back (`data-grow` on the card inside the
 sheet; see Dialog's own `animation`). `12_picker_card_demo.html` shows all of
 it, against a backend that answers when told to.
 
+A gesture inside the sheet that is not a field — cancel the game, delete it —
+is still an answer the sheet gives. A named button says which:
+
+```jsx
+<Button name="op" value="cancel" command="--navi-send">
+  Cancel the game
+</Button>
+```
+
+Its name and value travel with the fields (the group takes the sender's
+value, see `wantRequesterButtonState`), the sheet leaves on the send, and the
+picker's `action` receives `{ …fields, op: "cancel" }` — so this write is
+worn by the trigger exactly like the others, callout included, and a drawing
+reading `usePickerState()` can already show the "cancelled" stamp while the
+request is out. No button inside the popup needs an action of its own: a run
+started in there would belong to a control the close takes away.
+
 This is not `optimistic`. `optimistic` on a control is "draw no wait at all";
 here the wait is drawn, on the trigger, and the popup was never what held it.
 An optimistic picker is for a write not worth showing — the card then reads

package/package.json

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