@jsenv/navi 0.29.417 → 0.29.419

package/docs/control_group.md

@@ -1,168 +0,0 @@
-# Grouping controls (`<Group>`)
-
-What we want: **several controls reading as one object.** A search input and
-its button, a row of segmented buttons, a column of setting rows — when they
-belong together, the eye should see one frame with divisions inside it, not
-three boxes that happen to touch. Concretely that means: one border along each
-seam instead of two side by side, and a radius only on the four outer corners.
-
-`<Group>` is what produces that. Reach for it whenever you place controls
-against each other and any of them has a border or a radius — never hand-write
-negative margins, `border-radius: 0` overrides, or a `borderRadius` prop set to
-`0` on the middle members. Those spellings look right on the case you are
-looking at and break on the next one: a member added at the end, a member
-hidden by a condition (the "first" is then the second child), a switch from row
-to column.
-
-```jsx
-<Group>
-  <Input name="search" placeholder="Search…" />
-  <Button>Go</Button>
-</Group>
-```
-
-Stacked, one setting per row:
-
-```jsx
-<Group row>
-  <Picker name="side" ui={…} expandX />
-  <Picker name="level" ui={…} expandX />
-  <Picker name="city" ui={…} expandX />
-</Group>
-```
-
-`row` (or `vertical`, the same prop — each member is a row, so they stack
-vertically and meet along horizontal seams) is the only prop that changes the
-arrangement; everything else is read off the members themselves. Say it rather
-than `flex="y"`: the seams follow `row`, not the layout.
-
-Live examples: `src/control/demos/15_group_demo.html`.
-
-## What Group does to its members
-
-- **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**: 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
-  `--navi-z-index-control-hovered` / `-focused` / `-expanded`). Without it the
-  border color change and the focus ring of the active member would be sliced
-  by whichever neighbour is painted after it. The focused member is matched
-  whether it wears `data-focus-visible` itself or merely contains it — a
-  control that wraps a real input (`Picker`, `Spin`) draws the ring on its own
-  frame while the keyboard is held inside; the expanded member is matched the
-  same way, since it can be wrapped in an enrobage. Expanded ranks highest: a
-  `Picker` opened by a click shows no focus ring, hands the focus to its popup
-  and lets the pointer travel to a neighbour, yet its border keeps saying it is
-  the one open. There is deliberately no `isolation: isolate` — see
-  [z_index.md](./z_index.md).
-
-Nothing else: a group does not restyle its members, does not impose a size,
-and takes any `Box` prop for its own layout.
-
-## Writing a control that belongs in a group
-
-A group never writes a selector that reaches inside a member — a member's
-subtree holds more than the member (a `Picker` renders its popup inside
-itself, not in a portal; a control carries buttons of its own, like the clear
-cross in a slot), and a rule matching "some descendant" finds all of them. It
-asks for a square corner in two forms instead, and a control answers with
-whichever fits.
-
-**The property, on the member itself.** A control declares the radius of its
-frame on its own root, and whatever inner element paints that frame takes
-`border-radius: inherit`. The group sets the property on the root; the frame
-follows.
-
-```css
-.navi_thing {
-  /* Declared here even though the box below is what draws it */
-  border-radius: var(--thing-border-radius);
-
-  .navi_thing_box {
-    border: ...;
-    border-radius: inherit;
-  }
-}
-```
-
-**The custom property, which travels.** A member is not always the control
-that carries the frame: a button can arrive wrapped in a tooltip or a link, at
-any depth. So the group also sets `--x-corner-top-left-radius` and its three
-siblings on the member, and a control that can arrive wrapped reads them as an
-override of its own radius. The `--x-` prefix says what they are: navi's
-internal wiring between a group and its members, not a surface an app writes
-to (an app changes a radius with the `borderRadius` prop, which lands in the
-fallback below and is what the corner keeps everywhere the group has no claim):
-
-```css
-.navi_thing {
-  border-top-left-radius: var(
-    --x-corner-top-left-radius,
-    var(--thing-border-radius)
-  );
-  /* …and the three others */
-}
-```
-
-**Whoever answers the ask also stops it.** Custom properties inherit all the
-way down, so the control that consumed a corner sets the four back to
-`initial` on the first element inside it — otherwise a button in a slot, or the
-Save button of a form in an open popup, reads a corner meant for the row that
-opened it. `Popover` and `Dialog` stop it too, at their own root: nothing a
-popup holds is at a seam.
-
-Reference: `.navi_button_content` in `button_ui.jsx` (a button reads then
-stops), `.navi_picker_box`, `.navi_input_slot`, `.navi_popover`,
-`.navi_dialog`.
-
-**A member drawing the frame itself stops it too**, without being a control. A
-row of settings — a `Field`, a `Label`, a `Box` — that paints a background or a
-border, or that insets what it holds with padding, is what the outer corner
-belongs to; the switch at the right end of that row is not on it. `Box` marks
-itself with `navi-box-frame` for exactly those props and stops the claims for
-everything inside. A wrapper adding neither is only an enrobage — a tooltip, a
-link, a bare `<Box>` — and lets them through to the control that really carries
-the frame.
-
-A control that declares its radius on an inner element instead is invisible to
-`Group`: it keeps round corners in the middle of the row, and no rule written
-in `group.jsx` can reach it without naming that private class — which is how a
-layout component ends up knowing the internals of every control. When you meet
-that symptom, fix the control, not the group.
-
-The controls shipped by navi all follow this: `Button`, `Input`, `Select`,
-`Picker`, `Spin`, checkbox, range.
-
-## When it is not a Group
-
-- Controls separated by space, each with its own frame — that is a `Box` with
-  `spacing`, they were never one object.
-- A label and its control — that is `Field`.
-- Several controls making ONE value between them (an address out of three
-  fields, a day and two wheels out of one moment) — that is `ControlGroup`,
-  which is about the value and draws nothing. Same word, other subject: see
-  [control_object.md](./control_object.md). Both at once is fine — a `Group`
-  around the members of a `ControlGroup`.
-- Radio buttons or checkboxes sharing a name and a validation — that is
-  `RadioGroup` / `CheckboxGroup`, which is about the value, not the frame. They
-  can be put inside a `Group` if you also want them to share a frame.
-- Controls that are ONE value between them, with a word written inside the frame
-  (the hours and the minutes of "07h30") — that is `SpinGroup`, which drops the
-  members' frames rather than joining them.

package/docs/mobile_layout_pitfalls.md

@@ -1,145 +0,0 @@
-# Mobile layout pitfalls
-
-## Horizontal overflow on mobile breaks `<dialog>` positioning
-
-### What happens
-
-On Chrome Android, if **any element causes the document to overflow horizontally**,
-the browser inflates the layout viewport (`window.innerWidth/innerHeight`) to match
-the full content dimensions instead of the visible screen dimensions.
-
-Example on a 412×915px phone with a 2000px-wide grid:
-
-- `window.innerWidth` → `1648` (inflated, ~4× the real width)
-- `window.innerHeight` → `3660` (inflated, ~4× the real height)
-- `window.visualViewport.width` → `412` (the actual screen)
-
-**This creates a large invisible empty area below the real content** — the browser
-has "expanded" the document to a size that doesn't correspond to anything visible.
-
-### Why `<dialog>` breaks
-
-`position: fixed; margin: auto` is supposed to center an element in the viewport.
-But for obscure reasons, Chrome Android centers it relative to the inflated **layout
-viewport** instead of the visual viewport.
-
-With `innerHeight: 3660`, `margin: auto` places the dialog at ~1830px from the top —
-the user scrolls down and finds the dialog sitting far below the visible area, miscentered
-or completely invisible.
-
-**To make things worse**, `showModal()` internally calls `.focus()` on the dialog element,
-which triggers the browser's native `scrollIntoView`. So after opening, the page automatically
-scrolls to bring the dialog into view — scrolling the user away from where they were.
-
-### The fix: clip the horizontal overflow in a wrapper
-
-The root cause is the document overflowing horizontally. The fix is to **never let the
-document itself overflow in X** — instead, contain the overflow inside a child wrapper.
-
-```html
-<body>
-  <!-- This wrapper absorbs the horizontal overflow of the whole app -->
-  <div style="overflow-x: clip;">
-    <!-- all app content goes here -->
-  </div>
-
-  <!-- Dialog is outside the wrapper, directly in body, placed first -->
-  <dialog>...</dialog>
-</body>
-```
-
-With this structure:
-
-- The document never overflows horizontally → layout viewport = visual viewport
-- `position: fixed; margin: auto` centers the dialog correctly
-- No ghost empty space at the bottom
-
-As a safety net, add `overflow-x: clip` on `html` and `body` to prevent any content
-that forgets to use a wrapper from inflating the layout viewport:
-
-```css
-html,
-body {
-  overflow-x: clip;
-}
-```
-
-What it costs: content wider than the screen is cut off instead of reachable by dragging.
-When some element genuinely needs to be scrolled horizontally (a wide table, a carousel),
-give **that element** its own `overflow-x: auto` — the wrapper stays `clip`.
-
-### Why `clip` and not `auto` or `hidden`
-
-`clip` is the only value that clips without turning the box into a **scroll container**.
-`auto`, `scroll` and `hidden` all create one, and that has two consequences that show up
-far from the wrapper:
-
-- **Every `position: sticky` in the app sticks to that wrapper**, because sticky resolves
-  against the nearest scroll container in the DOM — not against the box the app considers
-  its scroller. The wrapper grows with its content and never scrolls, so nothing sticks
-  anymore: sticky headers and `<List groupBy>` group labels just scroll away with the
-  content.
-- **Worse than not sticking: the sticky element is offset downwards.** The rectangle a
-  sticky element sticks within is the scroll container's box shrunk by its
-  `scroll-padding` (CSS Position L3), and Chromium applies that for an element scroll
-  container. A wrapper carrying `data-navi-safe-area` has
-  `scroll-padding-top: var(--navi-safe-area-inset-top)`, so labels come to rest at
-  `scroll-padding-top + top` — a group label floating a hundred pixels below the bar,
-  covering the content above it.
-
-`overflow-x: clip` also lets `overflow-y` stay `visible`, where `hidden`/`auto` force the
-other axis to `auto`.
-
-Note: `overflow: hidden` on `<html>` would additionally create a new containing block,
-which could break `position: fixed` in edge cases. A dialog in the top layer is out of
-reach of that: the top layer takes it out of every ancestor's containing block, which is
-why navi's `Dialog` stays where it is written, in its opener's subtree.
-
-### The wrapper is a net, not a fix: find what overflows
-
-Clipping makes the symptom disappear, and with it the signal. Something wider than
-the screen is a layout bug wherever it happens — a width in px, a `min-width`, a grid
-of fixed columns, an unbreakable string coming from the data. The wrapper only keeps
-that bug from taking the whole mobile viewport down with it.
-
-So in dev, ask who overflows:
-
-```js
-import { detectHorizontalOverflow } from "@jsenv/navi";
-
-if (import.meta.dev) {
-  detectHorizontalOverflow({ root: document.querySelector("#main") });
-}
-```
-
-It outlines the culprits in red and names them in the console, at load and whenever
-the layout changes. It reports the **outermost** box that sticks out (its children
-stick out because it does), and stays quiet about what cannot reach the document:
-anything inside a box that scrolls or clips on its own — a wide table in its own
-`overflow-x: auto` container is doing the right thing — and anything `position: fixed`
-or in the top layer.
-
-Measuring against the wrapper matters here: once it is in `clip` there is no scrollable
-overflow left to read, so `scrollWidth > clientWidth` reports nothing. The rectangles of
-the descendants are what tells.
-
-### Also: place `<dialog>` before content in the DOM
-
-Even with the viewport fix, `showModal()` triggers `scrollIntoView` on the dialog element.
-If the `<dialog>` is placed at the end of the DOM (after all the app content), the page
-scrolls down to it when it opens.
-
-Fix: **place `<dialog>` as the first child of `<body>`**, before any scrollable content.
-`scrollIntoView` on an element already at the top of the document has no effect.
-
-This is advice for a `<dialog>` written by hand. navi's `Dialog` is not moved: it
-renders in its opener's subtree (see
-[css_architecture.md](./css_architecture.md#counting-children-what-navi-puts-in-your-tree)).
-
-### Summary
-
-| Cause                           | Symptom                                                                                                             | Fix                                                           |
-| ------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
-| Document overflows horizontally | Layout viewport inflated → ghost space below → dialog miscentered                                                   | Wrap app content in `overflow-x: clip` container              |
-| `<dialog>` at end of DOM        | Page scrolls to dialog on `showModal()`                                                                             | Place `<dialog>` first in `<body>`                            |
-| Wrapper uses `auto`/`hidden`    | It becomes a scroll container: sticky headers and group labels stick to it (and get offset by its `scroll-padding`) | Use `clip`; put `overflow-x: auto` on the wide element itself |