@jsenv/navi 0.29.134 → 0.29.135

package/docs/control_group.md

@@ -39,14 +39,24 @@ Live examples: `src/control/demos/15_group_demo.html`.
 
 ## What Group does to its members
 
-- **Seams**: each member after the first is pulled back by one border width, so
-  the two borders along a seam become one line. The width comes from the
-  member's own `--border-width` when it declares one, else from the group's
+- **Seams**: a member with a member before it is pulled back by one border
+  width, so the two borders along a seam become one line. The width comes from
+  the member's own `--border-width` when it declares one, else from the group's
   `--group-border-width` (default: `--navi-control-border-width`).
-- **Corners**: the first member loses the radius on the side that joins, the
-  last one loses it on the other side, and any member in between loses all
-  four. A single member keeps its own radius — a group of one looks like the
-  control alone. The ask is made twice, in two forms — see below.
+- **Corners**: a member loses the radius on each side where it faces another
+  member — the first one on the side that joins, the last one on the other
+  side, one in between on all four. A single member keeps its own radius — a
+  group of one looks like the control alone. The ask is made twice, in two
+  forms — see below.
+- **Members only**: a child out of the group's flow is none of the group's
+  business, and there are more of those than it looks. A popup renders inside
+  its opener's own subtree, so a `Dialog` or `Popover` written next to the
+  button that opens it is a child of the group itself, and brings its backdrop
+  along; a callout anchored on a `<button>` is mounted in that button's parent.
+  They mark themselves `navi-out-of-flow`, and the group reads that: none of
+  them takes a corner of its own, none moves anyone else's (a row of one button
+  and the dialog it opens is still a group of one), none is pulled back by a
+  border width it does not share.
 - **Overlap order**: the member under the pointer, the member showing a focus
   ring, and the member holding something open (`aria-expanded="true"`) paint
   above their neighbours (`position: relative` plus

package/docs/css_architecture.md

@@ -4,7 +4,7 @@
 
 Navi components are styled through a combination of CSS custom properties (variables) and scoped CSS rules. The architecture is designed so that:
 
-1. **Navi wins by default** — component rules are not placed inside `@layer`, so they beat any layered global styles.
+1. **Navi wins by default** — the rules that paint and lay a component out are not placed inside `@layer`, so they beat any layered global style. The exception is deliberate and always says so in a comment: a rule navi is happy to hand back sits in `@layer navi` next to the defaults — see [The exception](#the-exception-a-rule-navi-offers-back).
 2. **Defaults are easy to override** — default values for CSS variables are declared inside `@layer navi`, which has the lowest possible specificity, making them trivially overridable from outside.
 3. **The preferred override surface is component props** — props translate to inline styles or data attributes, not class names.
 
@@ -14,14 +14,14 @@ Navi components are styled through a combination of CSS custom properties (varia
 
 ```
 @layer navi {
-  /* CSS variable defaults only */
+  /* CSS variable defaults — and, when navi says so, a rule it offers back */
   .navi_button {
     --button-height: 32px;
     --button-padding-x: 12px;
   }
 }
 
-/* Actual rules — outside any layer */
+/* The rules that paint and lay out — outside any layer */
 .navi_button {
   height: var(--button-height);
   padding-inline: var(--button-padding-x);
@@ -49,6 +49,37 @@ Navi components often need to enforce specific values that global resets or util
 
 By keeping rules outside any layer, Navi wins by default without resorting to `!important`. An app that genuinely needs to change a structural rule should do so through the CSS variable surface, not by overriding the rule directly.
 
+### The exception: a rule navi offers back
+
+Some rules are not structure — they are what navi puts there in the absence of
+anything else, and an app (or another navi component) is meant to win over them
+plainly. Those go **inside** `@layer navi`, rules and all, and each one carries a
+comment naming who is supposed to win:
+
+- `[navi-aspect-ratio]`'s `min-width/min-height` and `.navi_icon`'s `display`
+  (`box.jsx`, `text.jsx`), so box.jsx's own unlayered `[navi-box-flow]`
+  attributes can still change the display;
+- the text properties a surface takes back from its opener
+  (`surface_text_css.js`), so an app that wants one of them back says so;
+- the `[data-url-target]` mark, the document's `line-height`, a Field's spacing
+  and a Label's dimmed color — appearance with no structural role;
+- `[data-navi-safe-area]`'s padding (`safe_area.js`), which is a suggestion for
+  an element the **app** owns.
+
+So the layer is readable from the outside as a statement rather than an
+accident:
+
+| In `@layer navi`                                 | Unlayered                        |
+| ------------------------------------------------ | -------------------------------- |
+| every CSS variable default                       | the rules that paint and lay out |
+| a rule navi offers back (commented, on the rule) | navi's own structure             |
+
+Either way an app never has to inflate a selector: a layered rule loses to any
+unlayered rule of the app's, and an unlayered one is reached through the
+variable that feeds it — `--picker-border-radius` for the picker's corners,
+`--navi-control-border-radius` for every control's, both declared in the layer
+and both overridable from a single-class rule.
+
 ---
 
 ## Override surfaces

package/docs/route_transitions.md

@@ -188,12 +188,28 @@ taken. Without that wait the picture keeps only the band the browser had
 already painted at the new offset, and the movement carries a fragment of the
 page instead of the page.
 
-With an area marked, the page around it is left LIVE rather than photographed:
-the bars keep answering the pointer for the whole movement, which a captured
-element cannot do. The flip side is that anything around the area which must
-_animate_ rather than stand still — a title that changes with the route — needs
-a `view-transition-name` of its own; named, the browser moves it on the same
-clock as the pages.
+With an area marked, each **fixed bar around it is photographed on its own** for
+the length of the movement, and whether it is the frame or part of what changes
+is derived rather than declared — it is a fact about the pair of states, not
+about the bar:
+
+- a bar **both states have** is one element, so its two pictures pair into one
+  group and it holds where it stands. The pages move behind it, and a bar whose
+  content changes with the route cross-fades without being named by hand.
+- a bar **one state has** meets no counterpart. It holds where it was
+  photographed while the pages move over it — covered as a page comes over it,
+  uncovered as one leaves — instead of appearing or vanishing in a frame. A page
+  that takes the whole screen (a full-screen wizard whose banner is its own
+  header) is this case, on the way in and on the way back.
+
+The pages are ordered above the bars for that reason. The price of being
+photographed is that a bar cannot answer the pointer for those few hundred
+milliseconds, which is what a route transition wants anyway: both pages are
+pictures too, and a press landing on either would be an accident. `RouteTravel`
+is the opposite case — a finger is on the box — and leaves the bars live.
+
+A bar the application names itself keeps its name and its own movement: navi
+names only what is unnamed.
 
 It is a `Box`, so the layout the pages need is written on it directly (`flex`,
 `className`, `style`, …). An app that already has an element holding its pages
@@ -237,6 +253,41 @@ half-transparent pictures to add up rather than cover each other
 (`mix-blend-mode: plus-lighter`, as the shipped `zoom` and the demo's `spin`
 both do). A movement where both pages move wants what navi poses.
 
+## Two routes matching one url
+
+A relation is written between two pages, and it is resolved through **which page
+is current** — not through the url, and not through the branch the router
+renders. So a url claimed by two of the routes named in relations makes the
+movement depend on the order the relations were declared in:
+
+```js
+const ALERTS_ROUTE = route("/me/alerts");
+const ALERT_CREATE_ROUTE = route("/me/alerts/create");
+const ALERT_DETAIL_ROUTE = route("/me/alerts/:alertId"); // "create" is an alertId
+
+defineRouteTransition(ALERTS_ROUTE, ALERT_DETAIL_ROUTE, "slide-x");
+defineRouteTransition(ALERTS_ROUTE, ALERT_CREATE_ROUTE, "cover-y");
+```
+
+On `/me/alerts/create` both detail and create are current; the page mentioned
+first wins, and the composer slides in from the right instead of covering. It is
+the one place where declaration order is load-bearing, and nothing on screen says
+so — a wrong movement is still a movement, and reads as a deliberate choice.
+
+The fix is on the route, not on the relation: make one of them decline the url
+(see [navigation.md](./navigation.md#which-values-a-param-accepts)).
+
+```js
+const ALERT_DETAIL_ROUTE = route("/me/alerts/:alertId", {
+  params: { alertId: (alertId) => alertId !== "create" },
+});
+```
+
+Which is worth doing whether or not a transition is involved: two routes matching
+one url is also two route actions running, and two branches competing for the
+`<Route>` the router renders. Left in place, navi says it once in the console,
+naming both routes.
+
 ## Route transitions and `RouteTravel` — one pair, one system
 
 `RouteTravel` and `defineRouteTransition` answer different questions:

package/package.json

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