work

Author: dmail

packages/frontend/navi/dist/dev/jsenv_navi.js

@@ -189,8 +189,10 @@ consistency across the app, not from any single call site.
   a popup, before writing a close button by hand, and before an
   `onOpen`/`onClose` writing a signal.
 - `docs/popup_backdrop.md` — what a popup lays between itself and the page
-  behind: the two independent questions it answers (what an outside press does,
-  how far what is behind withdraws), where the outside begins for a popup
+  behind: the three independent questions it answers (whether there is a wall
+  at all — `backdrop={false}` lets one press both dismiss the popup and reach
+  what it landed on, which `backdropVariant="invisible"` does NOT do — what an
+  outside press does, how far what is behind withdraws), where the outside begins for a popup
   painting no surface of its own (`data-navi-popup-outside`), the
   `backdropColor`/`backdropFilter` props
   for one popup and the `--navi-backdrop-*` colour+filter token pairs for the

packages/frontend/navi/dist/dev/jsenv_navi.js.map

@@ -4,8 +4,10 @@ What a `Dialog`, a `Popover` — and everything built on them: `Popup`,
 `SidePanel`, a `Picker`'s popup — lays between itself and the page it opened
 over.
 
-It answers two questions, and they are independent:
+It answers three questions, and they are independent:
 
+0. **Is there anything between the popup and the page at all?** That is
+   `backdrop`.
 1. **What does a press outside do?** Close, cancel, be absorbed, pass through.
    That is `pointerInteractionOutsideEffect`.
 2. **How far does what is behind withdraw?** Dimmed, blurred, barely marked,
@@ -15,7 +17,54 @@ It answers two questions, and they are independent:
 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.
+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.
+
+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.
+
+`backdrop={false}` is how that popup says there is no wall:
+
+```jsx
+<Popover pointerInteractionOutsideEffect="close" backdrop={false}>
+```
+
+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.
+
+**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.
+
+**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.
+
+`pointerInteractionOutsideEffect="capture"` and `backdrop={false}` contradict
+each other — absorbing is what a wall does — and navi warns rather than
+silently behaving like `"none"`.
 
 ## Where the outside begins
 
@@ -115,7 +164,8 @@ closes on an outside click blurs too.
 
 `backdropVariant` is the shorthand for the other direction: `"discrete"` for a
 barely-there dim, `"invisible"` for no paint at all. It never changes what the
-outside click does — the backdrop is still there and still catches it.
+outside click does — the wall is still there and still catches it. Whether
+there is a wall to paint is `backdrop`, above.
 
 `"invisible"` is the one kind with no filter token: it paints nothing, and a
 filter would still be seen.

packages/frontend/navi/dist/jsenv_navi.js

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

packages/frontend/navi/dist/jsenv_navi.js.map

@@ -91,6 +91,7 @@ const css = /* css */ `
  *   dialogExpandY?: boolean,
  *   dockedOnSmallTouchScreen?: boolean,
  *   marginWithContainer?: number | string,
+ *   backdrop?: boolean,
  *   backdropVariant?: "auto" | "discrete" | "invisible",
  *   backdropColor?: string,
  *   backdropFilter?: string,
@@ -139,8 +140,8 @@ const css = /* css */ `
  * `dockedOnSmallTouchScreen`, `dialogExpand*`, `dialogMinWidth`/`Height`,
  * `dialogMaxWidth`/`Height`,
  * `marginWithContainer`, `popoverMode`, `popoverSpacing`, `popupLayer`,
- * `popupTestId`, `popupWidthFitContent`, `popoverMaxHeight`, `backdropVariant`,
- * `backdropColor`, `backdropFilter`,
+ * `popupTestId`, `popupWidthFitContent`, `popoverMaxHeight`, `backdrop`,
+ * `backdropVariant`, `backdropColor`, `backdropFilter`,
  * `pointerInteractionOutsideEffect`, `escapeEffect`, `closeOnFocusOut`,
  * `scrollCapture`, `focusCapture`, `popupBackgroundColor`,
  * `popupBorderRadius`, `animation`. See picker.jsx for what each one says.
@@ -395,6 +396,7 @@ const POPUP_PROP_SET = new Set([
   "dialogExpandY",
   "dockedOnSmallTouchScreen",
   "marginWithContainer",
+  "backdrop",
   "backdropVariant",
   "backdropColor",
   "backdropFilter",

packages/frontend/navi/docs/AI_INSTRUCTIONS.md

@@ -1586,6 +1586,7 @@ const PickerFirstResolver = (props) => {
  *   anchor?: import("preact").RefObject<HTMLElement> | HTMLElement,
  *   escapeEffect?: "cancel" | "close",
  *   pointerInteractionOutsideEffect?: "close" | "cancel" | "capture",
+ *   backdrop?: boolean,
  *   backdropVariant?: "auto" | "discrete" | "invisible",
  *   backdropColor?: string,
  *   backdropFilter?: string,
@@ -1839,11 +1840,18 @@ const PickerFirstResolver = (props) => {
  *   put back the value at open ("cancel"), or nothing at all ("capture"). The
  *   default is what gives a popup with no confirm button its way out that
  *   keeps — see the same section.
+ * @param {boolean} [backdrop=true] Whether anything is laid between the popup
+ *   and the page at all. `false` lets a press outside both close the popup and
+ *   reach whatever it landed on, in one gesture — for a picker opened over a
+ *   page that stays as pressable as it looks (a plan, a map, a canvas), where a
+ *   wall would spend the first press on dismissing. Only the popover mode can
+ *   honour it: a dialog is modal and the page behind it is inert.
  * @param {"auto"|"discrete"|"invisible"} [backdropVariant="auto"] How visible the
  *   popup's backdrop is, independently of what a click outside does: `"auto"`
  *   is the paint `pointerInteractionOutsideEffect` implies, `"discrete"` a
- *   barely-there dim, `"invisible"` fully transparent. For a picker that closes on
- *   an outside click without wanting to dim the page for it.
+ *   barely-there dim, `"invisible"` fully transparent — a wall that is not seen
+ *   is still a wall, which is what `backdrop` above answers. For a picker that
+ *   closes on an outside click without wanting to dim the page for it.
  * @param {string} [backdropColor] The wash the popup paints over what is
  *   behind, for this picker alone. See Dialog's own doc.
  * @param {string} [backdropFilter] What that wash does to the picture

packages/frontend/navi/docs/popup_backdrop.md

@@ -916,7 +916,8 @@ const PickerContentInsidePopup = (props) => {
     // clicking outside revert instead, or "capture" to keep it open.
     pointerInteractionOutsideEffect = "close",
     // Named/forwarded rather than left in ...rest: rest goes to the picker
-    // element itself, not the popup, and this belongs to the popup.
+    // element itself, not the popup, and these belong to the popup.
+    backdrop,
     backdropVariant,
     backdropColor,
     backdropFilter,
@@ -1011,6 +1012,7 @@ const PickerContentInsidePopup = (props) => {
           pointerInteractionOutsideEffect={
             pointerLock ? "capture" : pointerInteractionOutsideEffect
           }
+          backdrop={backdrop}
           backdropVariant={backdropVariant}
           backdropColor={backdropColor}
           backdropFilter={backdropFilter}