@jsenv/navi 0.29.355 → 0.29.357

package/docs/AI_INSTRUCTIONS.md

@@ -142,7 +142,8 @@ to start when unsure which export solves a problem.
 - `control_group.md` — `<Group>`: several controls reading as one framed
   object. Read before negative margins or `border-radius: 0` by hand.
 - `form_changed.md` — a form sends nothing when nothing changed; what "changed"
-  is measured against; `pristineKey`; `standalone`. Read before
+  is measured against; `pristineKey`; `standalone`; what follows a send, and
+  `command="--navi-void"` for a form that keeps its popup open. Read before
   `canSendWhileUnchanged`, and before a control inside a group whose value it
   has no business joining.
 - `field_validation.md` — what only a browser can answer versus "is this value

package/docs/form_changed.md

@@ -42,6 +42,33 @@ is (`--navi-reset`), stay put as it is (`--navi-void`). Left out, the surface th
 form sits in decides: a popup closes, a slide goes on, a form on a page does
 nothing.
 
+### A popup that stays open
+
+A side panel, a dialog or a popover closes once a form inside it is sent. When
+the popup is a place one keeps working in — a panel where a push is sent, two
+fields are fixed, an account is linked — the form says it stays:
+
+```jsx
+<SidePanel signal={openUserSignal} value={user.id}>
+  <Form action={sendPush} command="--navi-void">
+    …
+  </Form>
+</SidePanel>
+```
+
+The form says it, not the popup. A popup does not know which of its forms is
+its answer: the same panel can hold a form you edit in over and over and a
+"delete" whose send has to close it. A popup that stays open whatever is sent
+inside it would make every form in it that should close say so again, which
+is the same repetition in the other direction. Nor does a `SidePanel` get a
+different default from a `Dialog`: the same content in either one should
+behave the same, and on a small screen a `SidePanel` often _is_ a dialog.
+
+When the popup's open state is a url param (`signal` bound to a route's search
+param), closing it takes the param out of the url. A form that forgot
+`--navi-void` then looks like a screen that reloaded: the panel is gone, and so
+is what a reload would have brought back.
+
 `--navi-reset` is the one to reach for when the form is a place one comes back
 to — an entry created, then the next one: the fields go back to their
 `defaultValue`, ready for the next entry. (What the form is measured against

package/docs/popup_backdrop.md

@@ -9,7 +9,7 @@ It answers three questions, and they are independent:
 1. **Is there anything between the popup and the page at all?** That is
    `backdrop`.
 2. **What does a press outside do?** Close, cancel, be absorbed, pass through.
-   That is `pointerInteractionOutsideEffect`.
+   That is `pressOutside`.
 3. **How far does what is behind withdraw?** Dimmed, blurred, barely marked,
    not painted at all. That is the paint: `backdropVariant`, `backdropColor`,
    `backdropFilter`.
@@ -41,7 +41,7 @@ that gave no sign it would.
 `backdrop={false}` is how that popup says there is no wall:
 
 ```jsx
-<Popover pointerInteractionOutsideEffect="close" backdrop={false}>
+<Popover pressOutside="close" backdrop={false}>
 ```
 
 The popup then hears an outside press from the document itself, and takes
@@ -92,9 +92,9 @@ 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
+`pressOutside="capture"` and `backdrop={false}` contradict
 each other — absorbing is what a wall does — and navi warns rather than
-silently behaving like `"none"`.
+silently behaving like `"ignore"`.
 
 ## Where the outside begins
 
@@ -131,8 +131,8 @@ 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, `pointerInteractionOutsideEffect` and all: `"cancel"`
-reverts, `"capture"` absorbs it, `"none"` (a `Popover`'s default, where no
+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,
@@ -179,7 +179,7 @@ panel that closes on that press then reopens on the click that follows is a
 panel meant to stay open, blinking.
 
 ```jsx
-<SidePanel id="error_panel" signal={openCardIdSignal} closeOnClickOutside>
+<SidePanel id="error_panel" signal={openCardIdSignal} closeByPressOutside>
   …
 </SidePanel>
 
@@ -236,12 +236,12 @@ Both are forwarded by `Popup`, `SidePanel`, `Picker` and `SplitButton`, next to
 When the choice is the app's rather than one popup's, it goes on `:root`. Each
 kind of backdrop has a colour **and** a filter, and they travel together:
 
-| kind                                                         | tokens                                                                            |
-| ------------------------------------------------------------ | --------------------------------------------------------------------------------- |
-| the default (`pointerInteractionOutsideEffect` close/cancel) | `--navi-backdrop-close-background`, `--navi-backdrop-close-backdrop-filter`       |
-| `pointerInteractionOutsideEffect="capture"`                  | `--navi-backdrop-capture-background`, `--navi-backdrop-capture-backdrop-filter`   |
-| `backdropVariant="discrete"`                                 | `--navi-backdrop-discrete-background`, `--navi-backdrop-discrete-backdrop-filter` |
-| `animation="lifting"`, `backdropVariant="lift"`              | `--navi-backdrop-lift-background`, `--navi-backdrop-lift-backdrop-filter`         |
+| kind                                            | tokens                                                                            |
+| ----------------------------------------------- | --------------------------------------------------------------------------------- |
+| the default (`pressOutside` close/cancel)       | `--navi-backdrop-close-background`, `--navi-backdrop-close-backdrop-filter`       |
+| `pressOutside="capture"`                        | `--navi-backdrop-capture-background`, `--navi-backdrop-capture-backdrop-filter`   |
+| `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
 is genuinely unreachable then, so it reads as clearly secondary. Nothing else
@@ -313,10 +313,10 @@ one it is, so the same two lines hold under both renderers.
 
 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 `pointerInteractionOutsideEffect` and on `backdropVariant` — write them
+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 `pointerInteractionOutsideEffect="none"` renders no backdrop at
+A `Popover` with `pressOutside="ignore"` renders no backdrop at
 all: there is nothing to paint, and both props are ignored.

package/docs/popup_lift.md

@@ -93,6 +93,8 @@ Two traps, both about the thumbnail:
 - **A scene under `lift="box"`** keeps the thumbnail at its own size in the
   corner of a growing, empty box, then swaps. Choose the kind by what grows:
   text and controls keep their scale (`box`), a drawing does not (`scene`).
+  Dev warns when the lifted node is, box for box, an `<svg>`, `<img>`,
+  `<picture>`, `<canvas>` or `<video>` under `box`.
 - **A thumbnail that is not the scene framed.** `scene` assumes the thumbnail
   is either the whole drawing smaller, or a band cut from its middle as wide as
   it. A thumbnail letterboxed inside a box of another aspect ratio (an SVG
@@ -157,6 +159,7 @@ const currentKeySignal = useSignal(undefined);
 <Dialog
   id={ZOOM_ID}
   animation="lifting"
+  lift="scene"
   mount="while-opened"
   onOpen={(e) => {
     currentKeySignal.value = e.detail.value;

package/docs/popup_open.md

@@ -688,12 +688,12 @@ the popup without closing it, and the error callout stays where the press was.
 The gestures that close a popup do not all mean the same thing, and that is on
 purpose:
 
-| gesture                        | what it means | who decides                                         |
-| ------------------------------ | ------------- | --------------------------------------------------- |
-| Escape                         | cancel        | `escapeEffect="cancel"` (default)                   |
-| a click outside                | close, keep   | `pointerInteractionOutsideEffect="close"` (default) |
-| a close cross (`--navi-close`) | close, keep   | [the cross](#the-close-cross)                       |
-| `--navi-cancel` on a button    | cancel        | the button                                          |
+| gesture                        | what it means | who decides                       |
+| ------------------------------ | ------------- | --------------------------------- |
+| Escape                         | cancel        | `escapeEffect="cancel"` (default) |
+| a press outside                | close, keep   | `pressOutside="close"` (default)  |
+| a close cross (`--navi-close`) | close, keep   | [the cross](#the-close-cross)     |
+| `--navi-cancel` on a button    | cancel        | the button                        |
 
 Escape says "forget it". It is the one gesture that has meant that everywhere,
 for as long as there have been dialogs, and navi keeps it that way. **A popup
@@ -927,7 +927,7 @@ the renderer.
 
 ```jsx
 const Panel = ({ children }) => (
-  <SidePanel id="error_panel" signal={openCardIdSignal} closeOnClickOutside>
+  <SidePanel id="error_panel" signal={openCardIdSignal} closeByPressOutside>
     {children}
   </SidePanel>
 );

package/package.json

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