@jsenv/navi 0.30.35 → 0.30.37

package/docs/AI_INSTRUCTIONS.md

@@ -176,7 +176,7 @@ start when unsure which export solves a problem.
 - `interactions.md` — a gesture is named, not read by hand: the `interactions`
   prop, swipes, holds, counted taps, the gate, a gesture's write verb
   (`{ answer, verb }`, held by the network policy), `selfInteractions`,
-  registering a detector. Before a `pointerdown` listener of your own, and before
+  registering a detector, why a popup's own element is not swiped. Before a `pointerdown` listener of your own, and before
   stopping propagation to keep a popup shut.
 - `drag_interactions.md` — an element carried: `move`, `reorder`, `land`,
   `toss`, `leave`, `moving`, the `grab`/`release`/`refuse` moments, an
@@ -197,7 +197,8 @@ start when unsure which export solves a problem.
   component style or writing `import.meta.css`.
 - `safe_area.md` — the app's rectangle and the band left free inside it, an app
   narrower than the window (`--navi-app-max-width`), `data-navi-safe-area`, a
-  popup kept clear of the bars (`container="safe-area"`, a toast), the viewport
+  popup kept clear of the bars (`container="safe-area"`, a toast and how it is
+  pushed away), the viewport
   under a virtual keyboard, a document wider than the screen. Before
   hand-writing an offset to clear a `FixedBar`.
 - `scroll.md` — where scrolling happens: `header`/`body`/`footer`, a `List`'s

package/docs/drag_to_travel.md

@@ -6,8 +6,9 @@ are two families, and they do not work the same way:
 - **A row of screens** (`SlideContainer`, `RouteTravel`) is a real scroller with
   one snap point per screen. The browser reads the hand. See
   [The browser scrolls the row](#the-browser-scrolls-the-row).
-- **A box pushed aside** (a docked `Dialog` or a `SidePanel` pushed back to close
-  it, a row swiped with `interactions`) has nothing to scroll to, so the press is
+- **A box pushed aside** (a docked `Dialog`, a `SidePanel` or a `Popover` with
+  `closeByDrag` pushed out to close it, a row swiped with `interactions`) has
+  nothing to scroll to, so the press is
   read by one module, `drag_to_travel.js` in @jsenv/dom. See
   [A box pushed aside: the press](#a-box-pushed-aside-the-press).
 
@@ -143,7 +144,8 @@ box moves:
 And one thing narrows it from the other end: a docked `Dialog` reads the press
 only on its grip — its header, plus anything carrying `data-swipe-grip` — so a
 board, a map or a list it holds keeps its own gestures, and a sheet with neither
-is not pushed back at all. A `SidePanel` is pushed from its whole surface.
+is not pushed back at all. A `SidePanel`, and a `Popover` with `closeByDrag`,
+are pushed from their whole surface.
 
 ### Boxes inside boxes
 

package/docs/interactions.md

@@ -310,6 +310,25 @@ rejecting with nothing comes back without a word. What a success does to it is
 yours (a list that redemands its rows, a row that leaves): navi does not make it
 disappear.
 
+### Not on a popup's own element
+
+What navi moves is the element that declares the swipe, through its `translate`.
+A popup's `translate` is where it stands: its placement writes it on the
+element, inline, and an inline value wins. A swipe declared on a `Popover`, a
+`Dialog` or a `SidePanel` itself is still answered, but nothing follows the
+finger: the popup stays put, and goes at the release if the answer closes it.
+navi warns about it in dev.
+
+Pushing a popup away is not a swipe to answer, it is a way of closing it:
+`closeByDrag` on a `Popover` (on by default on a `SidePanel`; a docked `Dialog`
+sheet is pushed by its header). The popup follows the finger without its
+placement being touched, is hidden behind the edge it leaves by, and closes once
+it is out — a close that keeps, like the cross's. A toast is the usual case, see
+[safe_area.md](./safe_area.md#pushed-away-by-hand).
+
+A swipe on something the popup holds, a row of a menu, is that element's, and it
+moves like any other.
+
 ## Twice, whichever hand it is
 
 At the finger there is no `dblclick`, and not even a second `click`: two taps in

package/docs/popup_open.md

@@ -563,12 +563,13 @@ does next.
 The gestures that close a popup do not all mean the same thing, and that is on
 purpose:
 
-| gesture                        | means       | who decides                                                                      |
-| ------------------------------ | ----------- | -------------------------------------------------------------------------------- |
-| Escape                         | cancel      | always on a `Dialog`/`Popover`; a `Picker`'s `escapeEffect="cancel"` (default)   |
-| a press outside                | close, keep | `pressOutside="close"`, default of `Dialog` and `Picker` (`Popover`: `"ignore"`) |
-| a close cross (`--navi-close`) | close, keep | [the cross](#the-close-cross)                                                    |
-| `--navi-cancel` on a button    | cancel      | the button                                                                       |
+| gesture                        | means       | who decides                                                                                              |
+| ------------------------------ | ----------- | -------------------------------------------------------------------------------------------------------- |
+| Escape                         | cancel      | always on a `Dialog`/`Popover`; a `Picker`'s `escapeEffect="cancel"` (default)                           |
+| a press outside                | close, keep | `pressOutside="close"`, default of `Dialog` and `Picker` (`Popover`: `"ignore"`)                         |
+| a close cross (`--navi-close`) | close, keep | [the cross](#the-close-cross)                                                                            |
+| `--navi-cancel` on a button    | cancel      | the button                                                                                               |
+| pushed out by hand             | close, keep | `closeByDrag`: on by default on a `SidePanel`, off on a `Popover`; a docked `Dialog` sheet by its header |
 
 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

package/docs/resource.md

@@ -536,6 +536,10 @@ const ORDER = resource("order", {
 <Button action={ORDER.cancel.bindParams({ id })}>Cancel</Button>;
 ```
 
+A write's name is its own: never a verb's, in any case (`post`, `Patch`,
+`get_many`…), nor a member the resource already exposes (`store`, `one`,
+`scopedMany`, `withParams`…). Declaring the resource throws otherwise.
+
 `ORDER.cancel` is an action beside the verbs: its own loading and error on the
 button that runs it, held by the network policy as its `verb`, and answered as
 that verb is (a `PATCH` returns the item, which is upserted). Its `rerunOn` says

package/docs/safe_area.md

@@ -198,6 +198,33 @@ above the device's own band, and it follows a bar coming or going while it is
 open. A sliding entrance is cut at that edge, so it comes out from behind the
 bar.
 
+#### Pushed away by hand
+
+A toast one has read is pushed away. `closeByDrag` pushes it back down, behind
+the bar it came out of; a list of sides lets it be thrown sideways as well, and
+it leaves the way it was thrown:
+
+```jsx
+<Popover
+  signal={toastSignal}
+  positionArea="bottom"
+  container="safe-area"
+  marginWithContainer={12}
+  animation="slide-from-bottom"
+  closeByDrag={["bottom", "left", "right"]}
+>
+```
+
+It follows the finger, and on release it finishes leaving or comes back. The way
+out covers the 12px too, so nothing of it is left showing at the edge. A button
+in it keeps its tap, and a push that starts on the button does not press it.
+
+The push closes the popover, which writes the signal like any other close. A
+toast that hides itself after a delay is then simply hidden sooner, and that
+delay was set for one toast: when it runs out, it closes the toast only if the
+signal still holds that one. Otherwise the next toast, shown in the meantime, is
+the one it closes.
+
 Not a fixed box carrying the insets with a `layer="local"` popover in it: that
 box is a second copy of the rectangle, and its popover is under the top layer,
 so a sheet open at the time hides it.

package/package.json

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