@jsenv/navi 0.29.388 → 0.29.390

package/docs/pan_zoom.md

@@ -42,12 +42,21 @@ when it lands; the pan stepping back for what is carried across the surface (a
 `move`, a handle, a field, a popover — the same list a travelling box steps back
 for); the pinch not beginning as a pan under its first finger; the wheel and the
 pinch writing one `zoom`; the capture, the pointer the browser drops, the click
-the release leaves behind. A pointer pans only once it has travelled a few px
-(`data-drag-threshold`), so a tap stays a tap: a `longpress` declared beside
-`pan` still gets its hold, and a `double_click` still gets its two presses.
+the release leaves behind, and the next tap's click, which Chrome on Android
+drops after a touch drag whose `touchmove`s nobody refused (see
+[mobile_tap_suppression_after_drag.md](./mobile_tap_suppression_after_drag.md)).
+A pointer pans only once it has travelled a few px (`data-drag-threshold`), so a
+tap stays a tap: a `longpress` declared beside `pan` still gets its hold, and a
+`double_click` still gets its two presses. A press that does pan is the
+surface's: a `longpress` waiting on it gives up the moment the pan begins, even
+inside its own slop.
 
 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. From the second finger on, both are the pinch's,
+and a `longpress` waiting on the first gives up. `pan` alone leaves the wheel to
+the page.
 
 ### A surface that scrolls past: `data-pan-after-hold`
 
@@ -76,6 +85,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 +165,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 +193,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

@@ -42,6 +42,7 @@ looks like ([data_states.md](./data_states.md#data-and-loading-are-independent))
   - [`.many(propertyName, childResource, restCallbacks)`](#manypropertyname-childresource-restcallbacks)
   - [`.scopedOne(propertyName, { idKey, GET, POST, PUT, PATCH, DELETE })`](#scopedonepropertyname--idkey-get-post-put-patch-delete-)
   - [`.scopedMany(propertyName, { idKey, GET, GET_MANY, POST, PUT, PATCH, DELETE, … })`](#scopedmanypropertyname--idkey-get-get_many-post-put-patch-delete--)
+  - [A relation declared on a scoped child](#a-relation-declared-on-a-scoped-child)
 - [When the backend answers a sub-route with the whole parent](#when-the-backend-answers-a-sub-route-with-the-whole-parent)
 - [Relations and autorerun](#relations-and-autorerun)
 - [`withParams()`: a scope with reruns of its own](#withparams-a-scope-with-reruns-of-its-own)
@@ -256,7 +257,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, {
@@ -358,6 +360,43 @@ const GAME_CANDIDATES = GAME.scopedMany("candidates", {
 `idKey` names the child's own key inside its owner (`user_id` above); it defaults
 to `"id"`.
 
+### A relation declared on a scoped child
+
+A scoped child takes relations of its own — a column pointing at a shared data
+type:
+
+```js
+const TABLE_COLUMNS = TABLE.scopedMany("columns", {
+  idKey: "name",
+  GET_MANY: async ({ id }) => [id, await fetchJson(`/tables/${id}/columns`)],
+  // [id, [{ name: "email", dataType: { id: 2, name: "varchar" } }, …]]
+  PATCH: async ({ id, name, ...props }) => [
+    id,
+    await fetchJson(`/tables/${id}/columns/${name}`, {
+      method: "PATCH",
+      body: props,
+    }),
+  ],
+});
+TABLE_COLUMNS.one("dataType", DATA_TYPE);
+```
+
+Every column gets a reactive `dataType` read from the `DATA_TYPE` store, fed by
+what the scoped child's callbacks embed. The relation itself takes none of the
+callbacks whose result names the column — `.one()`'s `GET`/`PUT`/`DELETE`,
+`.many()`'s `GET_MANY`/`DELETE`/`DELETE_MANY`, and every callback of a
+`.scopedOne()`/`.scopedMany()`, whose `ownerId` would be the column: they name
+it by its `name` alone, and a column exists only inside its table — two tables
+can each have an `email`. Declaring one throws. A column's data type is read and
+changed through `TABLE_COLUMNS`, whose results say which table
+(`[id, { name, dataType }]`); the fields of a data type itself, through
+`DATA_TYPE`.
+
+A `.scopedOne()`/`.scopedMany()` chained on a scoped child works the same way,
+and keeps one value per column: `TABLE_COLUMNS.scopedMany("constraints")` gives
+`users.email` and `admins.email` a collection each, fed by the `constraints`
+embedded in each table's columns.
+
 ## When the backend answers a sub-route with the whole parent
 
 This is the common REST shape, and it is the reason `op` dispatch feels
@@ -404,7 +443,8 @@ parent's own fields change too, either let the parent GET rerun (see below) or
 Relationship mutations do **not** invalidate their parent by default. The exact
 rules, verified by `src/state/rest/tests/resource_graph_parent_rerun.test.js`:
 
-- `.scopedMany` child **POST** reruns the owner's singular `GET` — but only when
+- `.scopedMany` child **POST** reruns the owner's singular `GET`, whether it
+  goes through the child or through a `withParams()` scope of it — but only when
   the last GET response actually embedded that property. GET_MANY on the parent
   is never rerun by a child POST (a list of parents is not stale because one of
   them gained a child).
@@ -419,7 +459,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
@@ -457,11 +498,18 @@ share is the **store**: an item updated through one is the same object in the
 others, so the fields of a row change everywhere without a request — only the
 membership of each list is a question its own scope answers.
 
+It scopes a relation as well as a resource, and the scope's actions are the
+relation's: `TABLE_COLUMNS.withParams({ withTypes: true }).GET_MANY` keeps the
+`[ownerId, items]` contract of `.scopedMany()` and replaces that table's
+columns.
+
 `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.390",
   "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.74",
     "@jsenv/humanize": "1.8.5",
     "@jsenv/validity": "0.4.5"
   },