@jsenv/navi 0.29.417 → 0.29.419

package/docs/popup_backdrop.md

@@ -14,29 +14,24 @@ It answers three questions, and they are independent:
    not painted at all. That is the paint: `backdropVariant`, `backdropColor`,
    `backdropFilter`.
 
-Keeping them apart is the whole point of this page. A popup that must close on
-an outside click — because that click is the way out of the screen — may also
-need the page behind to stop competing for the eye. How much it withdraws says
-nothing about what the click does, and neither says whether the page behind is
-still reachable.
+Keeping them apart is the whole point of this page: how much the page withdraws
+says nothing about what the click does, and neither says whether the page behind
+is still reachable.
 
 ## Is there a backdrop at all
 
-A backdrop is a wall: a full-screen element in front of the page, which wins
-hit-testing. That is how it absorbs a press — not by handling the event and
-stopping it, but by being what the pointer hits. Nothing behind it hears
-anything.
+A backdrop is a wall: an element in front of the page — the screen, or the box
+a `layer="local"` popup is confined to — which wins hit-testing. That is how it
+absorbs a press: not by handling the event and stopping it, but by being what
+the pointer hits. Nothing behind it hears anything.
 
 So a popup that closes on an outside press spends that press: the first press
-dismisses, and a second one is needed to do the thing the user was already
-pointing at. That is right when the page has withdrawn — the dim says the page
-is off, and a press on it means "come back", nothing more.
-
-It is wrong when nothing withdrew. A bubble opened over a map, a plan, a canvas
-— a page that looks exactly as pressable as it did a second ago — makes the
-next press a natural continuation of the gesture, not a dismissal. Taking it to
-close the bubble spends it on something the user never asked for, and on a page
-that gave no sign it would.
+dismisses, and a second one is needed to do what the user was already pointing
+at. That is right when the page has withdrawn — the dim says the page is off,
+and a press on it means "come back". It is wrong when nothing withdrew: over a
+map, a plan, a canvas that looks exactly as pressable as a second ago, the next
+press continues the gesture, and taking it to close the bubble spends it on
+something the user never asked for.
 
 `backdrop={false}` is how that popup says there is no wall:
 
@@ -46,66 +41,63 @@ that gave no sign it would.
 
 The popup then hears an outside press from the document itself, and takes
 nothing from it: no `preventDefault`, no `stopPropagation`. It closes, and the
-same press is answered by whatever it landed on — one gesture, one press.
-
-What it listens to is `pointerdown`, the press itself rather than what the
-browser makes of it afterwards. A page that is still live is a page whose own
-elements arbitrate their presses, and a cancelled `pointerdown` — what a drag
-source and a control keeping the focus both do — suppresses every mouse event
-that would have followed. So the popup dismisses on the press, on a finger as
-on a mouse, whatever the element under it decides to do with that press.
-
-**It is not `backdropVariant="invisible"`.** A wall that is not painted is
-still a wall, and it still eats the press; the two props answer different
-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.
+same press is answered by whatever it landed on — one gesture, one press. It
+listens to `pointerdown`, the press itself, since a cancelled `pointerdown` (a
+drag source, a control keeping the focus) suppresses every mouse event after
+it: the popup dismisses on the press, whatever the element under it does with
+it.
+
+**It is not `backdropVariant="invisible"`.** A wall that is not painted is still
+a wall, and it still eats the press. `"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.
 
 **It is what decides whether a popup is modal.** `Popover` is never modal,
 either layer, and neither is a `layer="local"` dialog. A top-layer `Dialog` is
-modal exactly when it has a wall: with one it 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 sheet on a phone is made of. `dockedOnSmallTouchScreen` docks
-the dialog against an edge of its container (the top one, or `"bottom"` for a
-sheet one only reads and taps — see [`dialog_shape.md`](./dialog_shape.md)),
-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:
+modal exactly when it has a wall: with one it is `showModal()`'d and the browser
+makes everything behind genuinely inert; without one it goes to the same top
+layer through the Popover API, 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 sheet on a phone is made of. `dockedOnSmallTouchScreen` docks the
+dialog against an edge of its container (see
+[`dialog_shape.md`](./dialog_shape.md)), 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="bottom" 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.
+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.
+What a dialog that is not modal — wall-less, or `layer="local"` — gives up is
+the one thing only a modal gets natively: the hardware/gesture back button no
+longer dismisses it. No web API hooks into that outside the browser's own
+modal-dismissal stack, which only a genuine `showModal()` element joins: an
+accepted limitation, not an oversight. A wall-less `Dialog` does not trap the
+focus either, deliberately — a page meant to be reachable is meant to be
+reachable with the keyboard too. (A `SidePanel` that closes on an outside press
+does trap Tab in popover mode: it sets `focusCapture`.)
 
-`pressOutside="capture"` and `backdrop={false}` contradict
-each other — absorbing is what a wall does — and navi warns rather than
-silently behaving like `"ignore"`.
+`pressOutside="capture"` and `backdrop={false}` contradict each other —
+absorbing is what a wall does — and navi warns rather than silently behaving
+like `"ignore"`.
 
 ## Where the outside begins
 
 A popup reads "outside" from its own border box. What the press landed on
 settles nothing by itself — a press on a real backdrop and a press on the
-popup's own padding both report the popup element as their target, there being
-no `::backdrop` node to be one — so the rectangle is what tells them apart.
-
-That works as long as the box and what the popup paints are the same thing. A
-popup with no surface of its own is the case where they are not:
+popup's own padding both report the popup element as their target — so the
+rectangle is what tells them apart. That works as long as the box and what the
+popup paints are the same thing. A popup with no surface of its own is the case
+where they are not:
 
 ```jsx
 <Dialog
@@ -119,7 +111,7 @@ popup with no surface of its own is the case where they are not:
 Here the sheet is whatever the children paint, and everything between them is
 backdrop to the eye and inside the box to the code. A press just above the box
 dismisses the popup; the same press two pixels lower, on the empty half of a
-row, is ignored — the rectangle says it landed on the popup.
+row, is ignored.
 
 `data-navi-popup-outside` is how the caller says which of its own boxes are not
 the surface:
@@ -132,30 +124,25 @@ the surface:
 
 A press on that row — left of the wheel, right of it, or anywhere in the height
 it reserves while the wheel is hidden — does exactly what the same press on the
-backdrop does, `pressOutside` and all: `"cancel"`
-reverts, `"capture"` absorbs it, `"ignore"` (a `Popover`'s default, where no
-backdrop is rendered at all) leaves it without an answer.
-
-It is opt-in because navi cannot infer it: a background can come from anywhere,
-and the caller who chose the transparency is the one who knows which box is
-decoration and which is paper.
+backdrop does, `pressOutside` and all. It is opt-in because navi cannot infer
+it: only the caller who chose the transparency knows which box is decoration and
+which is paper.
 
 **The marker answers for the element it is on, never for its descendants.** The
-wheel above is painted, so a press on it is a press on the popup — which is
-what lets one marker cover a whole row without swallowing the controls it
-holds. Mark the box whose own background is the see-through part; a nested box
-that is see-through too needs its own marker.
-
-**Space beside something, not space between two things.** The row above is the
-whole of what it marks: what the wheel does not cover is plainly nothing, and a
-press there reads as a press on the page. The gap between two rows of a column
-does not read that way — it is a seam of one thing the eye holds together,
-nobody dismisses a sheet by aiming between two of its lines, and on a phone
-that gap is where a thumb lands on its way to the control below. So the marker
-goes on a box that IS free space — the height a slot reserves while its control
-is hidden, the margin beside a centred control — and never on the column that
-stacks the sheet's parts: a layout box is mostly its gaps, and marking one
-turns every gap into a dismissal.
+wheel above is painted, so a press on it is a press on the popup — which is what
+lets one marker cover a whole row without swallowing the controls it holds. A
+nested box that is see-through too needs its own marker.
+
+**Space beside something, not space between two things.** What the wheel does
+not cover is plainly nothing, and a press there reads as a press on the page.
+The gap between two rows of a column does not read that way — it is a seam of
+one thing the eye holds together, and on a phone it is where a thumb lands on
+its way to the control below. So the marker goes on a box that IS free space —
+the height a slot reserves while its control is hidden, the margin beside a
+centred control — and never on the column that stacks the sheet's parts: a
+layout box is mostly its gaps, and marking one turns every gap into a dismissal.
+Navi does not warn about a marked container: from the outside the two are the
+same box, and only the caller knows which one it wrote.
 
 A box that only reserves space while something is away gives the marker back
 when that something returns:
@@ -166,10 +153,6 @@ when that something returns:
 </Box>
 ```
 
-Navi does not warn about a marked container: the column whose gaps must not
-dismiss and the row whose sides must are the same box from the outside, and
-only the caller knows which one it wrote.
-
 ### A box of the page that is not outside
 
 `data-navi-popup-inside` is the other direction: a box of the page the caller
@@ -194,48 +177,35 @@ panel meant to stay open, blinking.
 </Box>
 ```
 
-The value names the popup by `id`, the way `commandfor` does, and the exemption
-is that popup's alone: a menu open beside the board still closes when a card is
-pressed. Several popups are named with a space between the ids.
-
-Unlike the outside marker, this one answers for its whole subtree: the outside
-marker carves free space out of a surface whose controls stay surface, this one
-adds a whole thing to the popup's ground — the card, its count, its buttons —
-and nothing in it is a dismissal.
-
-It reads a press the page hears, so it belongs with a popup that has no wall
+The value names the popup by `id`, the way `commandfor` does — several ids with
+a space between them — and the exemption is that popup's alone: a menu open
+beside the board still closes when a card is pressed. Unlike the outside marker,
+this one answers for its whole subtree: it adds a whole thing to the popup's
+ground — the card, its count, its buttons — and nothing in it is a dismissal. It
+reads a press the page hears, so it belongs with a popup that has no wall
 (`backdrop={false}`): behind a wall, no card is pressable.
 
 ### `pointer-events: none` and `inert` are not this
 
 Neither says "this is backdrop", and reaching for them here is the natural
-mistake:
-
-- `pointer-events: none` takes the box out of hit-testing, so the press is
-  answered by the nearest ancestor that is still in it — still a descendant of
-  the popup, still inside. Putting it on the marked box makes the marker
-  unreachable; navi warns about that in dev. Putting it on a decoration
-  _inside_ a marked box is the one useful case: the press falls to the marked
-  box, which is the answer wanted.
-- `inert` speaks to the keyboard and to assistive technology. It does nothing
-  at all for a press.
+mistake. Both take the box out of hit-testing — `inert` as well as speaking to
+the keyboard and to assistive technology — so the press is answered by the
+nearest ancestor still in it: still a descendant of the popup, still inside. On
+the marked box, either makes the marker unreachable (navi warns about
+`pointer-events: none` in dev). On a decoration _inside_ a marked box,
+`pointer-events: none` is the one useful case: the press falls to the marked
+box, which is the answer wanted.
 
 ## Painting one popup: two props
 
 ```jsx
-<Dialog
-  backdropColor="rgb(6 10 20 / 88%)"
-  backdropFilter="blur(4px)"
->
+<Dialog backdropColor="rgb(6 10 20 / 88%)" backdropFilter="blur(4px)">
 ```
 
-`backdropColor` is the wash (any CSS color), `backdropFilter` what that wash
-does to the picture underneath (any `backdrop-filter` value — `blur()`,
-`saturate()`, `grayscale()`). Either alone is fine: a blur over navi's default
-dim keeps the page recognisable without darkening it further.
-
-Both are forwarded by `Popup`, `SidePanel`, `Picker` and `SplitButton`, next to
-`backdropVariant`.
+`backdropColor` is the wash, `backdropFilter` what it does to the picture
+underneath; either alone is fine — a blur over navi's default dim keeps the page
+recognisable without darkening it further. `Popup`, `SidePanel`, `Picker` and
+`SplitButton` forward both, next to `backdropVariant`.
 
 ## Painting every popup: the theme tokens
 
@@ -249,7 +219,12 @@ kind of backdrop has a colour **and** a filter, and they travel together:
 | `backdropVariant="discrete"`                    | `--navi-backdrop-discrete-background`, `--navi-backdrop-discrete-backdrop-filter` |
 | `animation="lifting"`, `backdropVariant="lift"` | `--navi-backdrop-lift-background`, `--navi-backdrop-lift-backdrop-filter`         |
 
-Only `capture` blurs out of the box among the three above: the rest of the page
+The `close` pair is also a top-layer `Dialog`'s base paint, so `"ignore"` still
+dims there. A `layer="local"` dialog paints nothing under `"ignore"` — its wall
+is still there — and a `Popover` renders no backdrop at all. `"ignore"` is
+`SidePanel`'s default.
+
+Only `capture` blurs out of the box among the first three: the rest of the page
 is genuinely unreachable then, so it reads as clearly secondary. Nothing else
 about `capture` makes the blur its own — set the `close` filter token and every
 popup that closes on an outside click blurs too.
@@ -257,37 +232,24 @@ popup that closes on an outside click blurs too.
 ## The one animation that decides its own backdrop
 
 Every kind above is keyed on what the popup _does_. `animation="lifting"` is
-keyed on what the popup _is_: not a surface shown over the page, but the box
-the anchor became. That changes the answer to "how far does what is behind
+keyed on what the popup _is_: not a surface shown over the page, but the box the
+anchor became. That changes the answer to "how far does what is behind
 withdraw?", so it brings its own pair — opaque, blurred — rather than the 8%
 wash a popup shown over a page still being read wants.
 
-Three things follow from the morph and all three point the same way. What is
-lifted is looked at — a card, a plan, a picture is brought forward because it
-could not be read where it was, and anything still legible behind competes
-with it. Such a popup often paints no surface of its own (the thing that was
-lifted already has its frame, so
-`backgroundColor="transparent"`), which makes the backdrop the background of
-the popup's own content rather than something merely behind it. And the
-movement itself is the browser interpolating a picture of the document: a crisp
-page behind a box that is still travelling reads as two things moving at once.
-
-It is a default, not a rule. `backdropColor`/`backdropFilter` win over it as
-they win over everything, `backdropVariant` overrides it, and
-`backdropVariant="discrete"` is how a lifting popup asks for the light wash
-back.
-
-`backdropVariant="lift"` is the same thing said the other way round: that wall,
-on a popup that does not morph. What made it the right answer above is the
-lifted thing being what the eye is on, and a popup can be that without having
-travelled — a picture opened full, a plan, a card that paints its own surface
-(`backgroundColor="transparent"`) so the wall is its background. The movement
-is one reason to want it, not the only one.
-
-`backdropVariant` covers the other direction too: `"discrete"` for a
-barely-there dim, `"invisible"` for no paint at all. None of them changes what
-the outside click does — the wall is still there and still catches it. Whether
-there is a wall to paint is `backdrop`, above.
+Three things follow from the morph, and all three point the same way. What is
+lifted is looked at — brought forward because it could not be read where it was
+— and anything still legible behind competes with it. Such a popup often paints
+no surface of its own (`backgroundColor="transparent"`), which makes the
+backdrop the background of its content. And the movement is the browser
+interpolating a picture of the document: a crisp page behind a box still
+travelling reads as two things moving at once.
+
+It is a default, not a rule: the paint props win over it as they win over
+everything, and `backdropVariant="discrete"` is how a lifting popup asks for the
+light wash back. `backdropVariant="lift"` is the same thing said the other way
+round: that wall, on a popup that does not morph but whose content is what the
+eye is on — a picture opened full, a plan, a card painting its own surface.
 
 `"invisible"` is the one kind with no filter token: it paints nothing, and a
 filter would still be seen.
@@ -297,11 +259,11 @@ filter would still be seen.
 **The backdrop is not inside the popup**, and which element it is depends on the
 renderer:
 
-| popup                  | its backdrop                                                                                         |
-| ---------------------- | ---------------------------------------------------------------------------------------------------- |
-| `Dialog layer="top"`   | the native `::backdrop` pseudo-element of the `<dialog>`                                             |
-| `Dialog layer="local"` | a sibling `div.navi_dialog_backdrop`, before the dialog                                              |
-| `Popover`              | a sibling `.navi_popover_backdrop` (see popover.jsx's top comment for why it cannot be a descendant) |
+| popup                  | its backdrop                                                      |
+| ---------------------- | ----------------------------------------------------------------- |
+| `Dialog layer="top"`   | the native `::backdrop` pseudo-element of the `<dialog>`          |
+| `Dialog layer="local"` | a sibling `div.navi_dialog_backdrop`, before the dialog's wrapper |
+| `Popover`              | a sibling `.navi_popover_backdrop`                                |
 
 The pseudo-element inherits custom properties from the dialog — which is what
 makes the tokens above reach it at all. The sibling elements do not: they
@@ -310,19 +272,17 @@ itself lands on the paint under one renderer and silently does nothing under the
 other, and a stylesheet rule hanging off the popup's own class cannot reach the
 sibling at all except through a `:has()` that writes navi's DOM shape into the
 app's stylesheet — the kind of selector that stops matching the day navi moves a
-box.
-
-The props exist for that: navi sets them on the element that paints, whichever
-one it is, so the same two lines hold under both renderers.
+box. The props exist for that: navi sets them on the element that paints,
+whichever one it is.
 
 ## What wins over what
 
-Painting is resolved through two variables the popup and its backdrop carry,
-`--backdrop-background` and `--backdrop-filter`. Navi's own rules — the ones
-keyed on `pressOutside` and on `backdropVariant` — write them
-as defaults; the props write them inline on the same element, which beats every
-rule. So `backdropColor` wins over `backdropVariant="invisible"`, and a variant
-is only ever what the caller did not say.
-
-A `Popover` with `pressOutside="ignore"` renders no backdrop at
-all: there is nothing to paint, and both props are ignored.
+Painting is resolved through two variables, `--backdrop-background` and
+`--backdrop-filter`, on the element that paints — the `<dialog>` of a top-layer
+one, whose `::backdrop` inherits them, the sibling element otherwise. Navi's own
+rules — keyed on `pressOutside`, `animation="lifting"` and `backdropVariant` —
+write them as defaults; the props write them inline on the same element, which
+beats every rule. So `backdropColor` wins over `backdropVariant="invisible"`,
+and a variant is only ever what the caller did not say. A `Popover` with
+`pressOutside="ignore"` has no backdrop, so there is nothing for either prop to
+paint.