@jsenv/navi 0.29.388 → 0.29.389

package/docs/pan_zoom.md

@@ -47,7 +47,9 @@ the release leaves behind. A pointer pans only once it has travelled a few px
 `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.
+whatever else reads it: nothing captures it, waits on it or swallows its click
+until a second finger lands, so a `click` or a `longpress` declared beside `zoom`
+answers it as it would anywhere. `pan` alone leaves the wheel to the page.
 
 ### A surface that scrolls past: `data-pan-after-hold`
 
@@ -76,6 +78,10 @@ say so. It spends the hold, though: a `longpress` declared beside a `pan` that
 waits asks one finger to answer two waits, and the surface's — the shorter one
 — is the one answered.
 
+On a surface that only zooms there is no pan to wait for: one finger is the
+page's to scroll, two are the surface's, and `"kept"` (below) has nothing to
+keep.
+
 The wait is then asked before every pan, which is right while each finger
 landing there is genuinely ambiguous. Once the user has settled into the plan it
 is not, and asking again is asking three times for one sentence:
@@ -152,11 +158,11 @@ place `data-pan-after-hold` is.
 
 ### When the surface has the hand: `grab`, `release`, `[data-grabbed]`
 
-A surface that is asked for — by a hold, or by the first few pixels of travel —
-has an instant where it becomes the hand's, and nothing on screen says it. The
-hand then moves too early and scrolls the page instead, or waits long past the
-moment out of doubt. So the surface says it, the same two words a carried element
-says (`grab`, `release`) and the same attribute:
+A surface that is asked for — by a hold, by the first few pixels of travel, or
+by a second finger — has an instant where it becomes the hand's, and nothing on
+screen says it. The hand then moves too early and scrolls the page instead, or
+waits long past the moment out of doubt. So the surface says it, the same two
+words a carried element says (`grab`, `release`) and the same attribute:
 
 ```jsx
 <Box
@@ -180,7 +186,8 @@ says (`grab`, `release`) and the same attribute:
 }
 ```
 
-`[data-grabbed]` is on the element for as long as a hand is on the surface, so
+`[data-grabbed]` is on the element for as long as a hand is on the surface (on
+one that only zooms, from the second finger landing to the last one lifting), so
 a contour, a veil or a raised shadow needs no listener — which is what this is
 usually for. (`[data-hand-kept]` is the other one, and it outlasts the finger:
 see [`data-pan-after-hold`](#a-surface-that-scrolls-past-data-pan-after-hold).) `grab` and `release` are for the rest: a vibration, a state kept

package/docs/resource.md

@@ -256,7 +256,8 @@ These are not guessable — each relationship method has its own shape.
 
 ### `.one(propertyName, childResource, { GET, PUT, DELETE })`
 
-The callback returns the **parent** object with the child nested inside:
+`GET` and `PUT` return the **parent** object with the child nested inside;
+`DELETE` returns the parent id, or `{ id }`:
 
 ```js
 const USER_SESSION = USER.one("session", SESSION, {
@@ -419,7 +420,8 @@ rules, verified by `src/state/rest/tests/resource_graph_parent_rerun.test.js`:
   rerun) by its own `DELETE`, as a root `GET` is; a scoped `GET` is not reset —
   its data simply resolves to nothing once the child is dropped. Override per
   relation with `rerunOn`/`dependencies`, which every relationship method
-  accepts.
+  accepts; what a relation leaves out is its parent resource's (`rerunOn` key
+  by key).
 
 Splitting a sub-resource out of a parent `PATCH` therefore changes the refresh
 graph: a parent field the parent's own response kept fresh is, once the relation
@@ -460,8 +462,10 @@ membership of each list is a question its own scope answers.
 `withParams()` chains, merging the params —
 `USER.withParams({ role: "admin" }).withParams({ gender: "male" })` is
 `USER.withParams({ role: "admin", gender: "male" })`. Its second argument takes
-`rerunOn` and `dependencies` for that scope; left out, the scope inherits the
-resource's. Empty params throw: a scope has to be about something.
+`rerunOn` and `dependencies` for that scope; what it leaves out is the
+resource's — a `rerunOn` key by key, so `{ rerunOn: { GET: ["PATCH"] } }` keeps
+the resource's `GET_MANY` and `GET_RANGE`. Empty params throw: a scope has to be
+about something.
 
 It is not the tool for a param the user types. A search word bound with
 `withParams()` would keep its results from refreshing after a write on the

package/docs/safe_area.md

@@ -75,13 +75,8 @@ So the app states its own screen once, and never names a component:
 
 The bands fall out of it (centered), `--navi-app-width` follows, and `FixedBar`
 pins itself to the column's edges rather than the glass. An app wanting them
-uneven writes `--navi-app-inset-left` / `-right` directly instead.
-
-In pixels: popup placement reads this value back from CSS to compute its own
-margins, and a custom property computes to a token stream rather than to a
-length, so `40rem` would arrive there as the string `"40rem"`. A non-px value
-still caps the popup's size (that part is pure CSS) but leaves its margins and
-its placement viewport-sized, and says so in the console.
+uneven writes `--navi-app-inset-left` / `-right` directly instead; everything
+below follows those the same way, popup placement included.
 
 Every popup follows: `Dialog`, `Popover`, and everything built on them
 (`Picker`, `Select`…). It is a ceiling and nothing more — on a screen narrower
@@ -116,15 +111,19 @@ price.
 
 #### Placement follows the same rectangle
 
-`--navi-app-max-width` moves where a popup is placed, not only how big it may
+The app's rectangle moves where a popup is placed, not only how big it may
 get. Placement is computed against the visual viewport narrowed to the level-1
-bands: `getAppInsets` (`src/layout/responsive.js`) is the JS reading of them,
-navi hands them to `@jsenv/dom` once (`setPlacementViewportInsets`, wired in
+bands: `getAppInsets` (`src/layout/responsive.js`) reads `--navi-app-inset-*`
+back off the computed style — the bands `--navi-app-max-width` centers and the
+ones an app writes by hand alike, in any length unit — navi hands them to
+`@jsenv/dom` once (`setPlacementViewportInsets`, wired in
 `navi_css_vars.js`), and `pickPositionRelativeTo` reads them on every
-placement. Invisible for anything centered on its cross axis — `center`,
-`bottom`, `top`, which is what a dialog does nearly always — but it is what puts
-anything anchored to an edge (a `positionArea` like `bottom-start`, a
-`SidePanel`) flush against the app column's edge rather than the window's.
+placement. With centered bands it is invisible for anything centered on its
+cross axis — `center`, `bottom`, `top`, which is what a dialog does nearly
+always — and with uneven ones it is what centers that dialog on the app column
+rather than on the window. Either way it is what puts anything anchored to an
+edge (a `positionArea` like `bottom-start`, a `SidePanel`) flush against the
+app column's edge rather than the window's.
 `FixedBar` reads the same description through CSS instead: it is pinned to
 `--navi-app-inset-*`, which says where the app's rectangle is in the window
 rather than how wide it may be.
@@ -156,20 +155,25 @@ Beware of making that container scrollable by accident — see
 `var(--navi-safe-area-inset-bottom)` in any rule. It is always declared, whether
 or not the app ever mounts a bar.
 
-From **JS**, the four `--navi-safe-area-inset-*` are registered as lengths
-(`@property`, in `safe_area.js`), so
+From **JS**, both levels are registered as lengths (`@property`, in
+`safe_area.js`), so
 `getComputedStyle(document.documentElement).getPropertyValue("--navi-safe-area-inset-bottom")`
-gives pixels. The level-1 `--navi-app-inset-*` are not registered and keep their
-`calc()` unresolved there: give a hidden box `height: var(…)` and measure it —
-see `src/layout/demos/fixed_bar/keyboard.html`.
+gives pixels, and so does `--navi-app-inset-*`.
 
 ### Putting something new into it
 
-Publish what you take on one edge, into that edge's slot. That is the whole
-contract — a native banner, an OS strip, anything an app invents joins the sum
-without a single component learning it exists. `FixedBar` is the worked example:
-it measures its own border box (notch included) and writes
-`--navi-fixed-bar-space-*` (`src/layout/fixed_bar/fixed_bar_space.js`).
+Level 2 has one slot per edge, `--navi-fixed-bar-space-*`, and it belongs to
+`FixedBar`: each bar measures its own border box (notch included), and navi
+writes the largest one on that edge inline on `<html>`
+(`src/layout/fixed_bar/fixed_bar_space.js`). The slot is combined with
+`env(safe-area-inset-*)` through `max()`, not added to it, since a bar measured
+with its notch already covers the notch.
+
+Something else taking an edge — a native banner, an OS strip — is published by
+being drawn as a `FixedBar`; every component reading the safe area then clears
+it without learning it exists. Writing the slot by hand holds only while no bar
+takes that edge: the first bar mounting there replaces the value rather than
+adding to it.
 
 ## What already reads it
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/navi",
-  "version": "0.29.388",
+  "version": "0.29.389",
   "type": "module",
   "description": "Library of components including navigation to create frontend applications",
   "repository": {
@@ -34,7 +34,7 @@
     "preact": "^11.0.0-rc.2"
   },
   "dependencies": {
-    "@jsenv/dom": "0.17.72",
+    "@jsenv/dom": "0.17.73",
     "@jsenv/humanize": "1.8.5",
     "@jsenv/validity": "0.4.5"
   },