@kerfjs/ui 4.5.0-beta.1 → 5.0.0-beta.100

package/docs/anchored-surface.md

@@ -0,0 +1,101 @@
+# AnchoredSurface
+
+Use `openAnchoredSurface` from `@kerfjs/ui/anchored-surface` for interactive help
+or other arbitrary content beside a control. Use `openAnchoredSurfaceAt` for a
+pointer location. Import `@kerfjs/ui/styles.css` or the individual
+`@kerfjs/ui/anchored-surface.css` stylesheet. The surface draws its own raised
+background, border, inset, radius, shadow, and viewport size limit; the app
+supplies the content and decides when to open or close it.
+
+```tsx
+import { openAnchoredSurface } from '@kerfjs/ui/anchored-surface';
+
+const help = openAnchoredSurface(button, () => <HelpContent />, {
+  label: 'Pricing help',
+});
+// Close after an app action: help.close();
+```
+
+The returned `OverlayHandle` has `el`, idempotent `close()`, and `result`.
+The surface is a non-modal `role="dialog"` named by the required nonempty `label`.
+Focus moves to its first focusable descendant by default and returns to the
+focusable anchor on close (or the previously focused element for a nonfocusable
+anchor). Pass `initialFocus: false` for read-only
+help that leaves focus on its trigger. Escape and an outside press dismiss it;
+`dismiss`, `onDismiss`, and `outsideIgnore` can customize that behavior.
+`placement` (`bottom` or `top`), `align` (`start` or `end`), `gap`, and
+`viewportMargin` feed the shared `kerfjs/overlay` positioning core: it flips
+vertically when the other side fits, keeps the surface `viewportMargin` (default
+8px) inside the viewport edges, and follows scroll and resize. The surface fits
+its height to the room beside the anchor: when neither side holds it, it opens
+on the roomier side, caps its height to that room, and scrolls its content.
+The room is exposed to the content as `--kui-anchored-surface-available-height`
+and refreshed on every reposition, so a tall help surface fits beside a field on
+a phone without application media queries or `max-height` overrides.
+
+```tsx
+openAnchoredSurfaceAt(
+  { x: event.clientX, y: event.clientY, context: event.target as Element },
+  () => <ContextHelp />,
+  { label: 'Context help' },
+);
+```
+
+Pass `context` for a pointer opened inside a modal dialog. Inside a Web
+Awesome `wa-dialog` or `wa-drawer`, the surface stays interactive with no extra
+markup: `kerfjs/overlay` finds the modal `<dialog>` in the element's shadow
+root and hosts the surface in the element's light DOM, slotted inside the
+dialog. Dialogs opened by `kerfjs/overlay` get a host automatically too. For an
+app-owned native `<dialog>`, include
+`<div data-kerf-overlay-host data-morph-skip></div>` in the dialog markup so
+controls in the anchored surface stay interactive. For any other modal context,
+pass `container`: an element inside the open modal, where the surface is
+appended instead. The helper uses the browser top layer where available, and
+the shared overlay fallback elsewhere.
+
+Closing the anchor's modal dialog also closes the surface. Escape closes only
+the surface; the dialog beneath stays open. The temporary pointer anchor is
+removed when the surface closes.
+
+## Dark tone for media chrome
+
+A popup anchored to dark media chrome (a volume control in a
+`ToolbarControlGroup tone="dark"` over a video or image preview) passes
+`tone: 'dark'`:
+
+```tsx
+openAnchoredSurface(volumeButton, () => <VolumeControls />, {
+  label: 'Volume',
+  tone: 'dark',
+  placement: 'top',
+});
+```
+
+The tone is the same loud, inverse tone as a dark `ToolbarControlGroup` or
+`ToolbarText`: dark beside a light page and light beside a dark one, so the
+popup matches the group that opened it. When the surface opens it takes the
+opposite of the anchor's color scheme (an explicit `color-scheme` on the anchor
+or an ancestor wins; `light dark` follows the user's preference), and the
+surface is marked `data-tone="dark"`. Nothing else changes. Every semantic
+color token is a `light-dark()` pair, so the surface fill, border, and shadow,
+and the text, borders, and focus rings of the Kerf UI and Web Awesome
+components inside it (a `ListItem` mute row, a `wa-slider`), resolve to the
+other side by inheritance. The content needs no tone props and no overrides.
+Text and focus rings keep WCAG AA in both page schemes. A theme that replaces a
+semantic token with a single color instead of a `light-dark()` pair opts that
+token out of the flip. While the surface is open it follows a live switch: an
+OS preference change, or a theme class, attribute, or inline `color-scheme`
+changed on the anchor or one of its ancestors, flips it to the new opposite
+(the content's own color transitions run, as the page's do). A scheme changed
+only by swapping a stylesheet is not observed. `openAnchoredSurfaceAt` reads the
+scheme from its `context` (the element under the pointer), so a region with its
+own `color-scheme` is honored; without a connected `context` it reads the modal
+scope's (or the page's).
+
+## Theming
+
+Override `--kui-anchored-surface-inset` and
+`--kui-anchored-surface-radius` for a theme; content can compose any Kerf UI
+components without the surface applying action policy. Prefer `PopupMenu` for
+a typed command list and `Select` for choosing a persistent value. See
+[component selection](component-selection.md).

package/docs/app-layouts.md

@@ -9,7 +9,7 @@ changes. The layouts:
 - [`NavStack`](nav-stack.md) — push/pop navigation (a single pane is a one-entry stack).
 - [`SplitView`](split-view.md) — list-detail (two panes, collapsing to a stack).
 - [`Workbench`](workbench.md) — the Xcode-like collapsible rails + drawer.
-- [`TabScaffold`](tab-scaffold.md) — the iOS bottom tab bar (each tab a stack).
+- [`TabNavigator`](tab-navigator.md) — the iOS bottom tab bar (each tab a stack).
 - [`CollapsiblePanel` + `wireSidebar`](collapsible-panel.md) — a standalone
   collapsible rail or bottom drawer (with `CollapsiblePanelToggle`), outside a full
   shell: the standard collapse animation, icon convention, and `wireSidebar`
@@ -19,15 +19,147 @@ Derive responsiveness from `deviceClass()`: `compact` (a handset or portrait
 tablet) means "one pane at a time"; `atLeast('tablet')` / `atLeast('desktop')`
 gate the roomier presentations.
 
+Full-height shells retain `height: 100%` so they remain embeddable. Give a
+top-level shell a definite height chain by importing `@kerfjs/ui/document.css`
+and applying `.kui-app-root` to the direct mount container; see the
+[document baseline](document-baseline.md). Do not replace an embeddable shell's
+height with `100dvh`; a full-viewport app instead adds `data-viewport="locked"`
+to its `.kui-app-root`, which locks the document (not the shell) to `100dvh`.
+
+## Safe areas
+
+On a device with unsafe areas (a notch, rounded corners, a home indicator) and a
+page that opts into them with `<meta name="viewport" content="…, viewport-fit=cover">`,
+the layouts handle the insets for you. There is nothing to configure:
+
+- **Surfaces paint edge to edge.** Pane and panel backgrounds, separators, and
+  dividers run through the unsafe area. A collapsible rail or drawer grows by
+  the inset it reaches, so its content keeps its configured width or height.
+- **Content is padded on the sides it touches.** Inline insets pad the sides a
+  region actually reaches. Block insets become padding _inside_ the scroll
+  container (with matching `scroll-padding`), so content scrolls under the
+  status bar or home indicator but its first and last items can always be
+  scrolled clear.
+- **Interior edges get nothing.** A `Workbench` center next to an expanded rail,
+  a `SplitView` detail beside its list, or a `NavStack` view under its docked
+  chrome is not inset on that edge. Collapse the rail and the center picks up
+  the edge. A `NavStack` with `chromePresentation="overlay"` is the exception
+  by design: its views reach under the translucent chrome, and the measured
+  chrome height (top safe area included) becomes their block-start inset, so
+  content scrolls beneath the bar yet rests clear of it (see
+  [Navigation stack › Overlay chrome](nav-stack.md#overlay-chrome)). Its
+  `bottomToolbarPresentation="overlay"` does the same at the bottom: the
+  measured toolbar height (bottom safe area included) becomes the views'
+  block-end inset, so the last item rests just above the toolbar. A
+  `TabNavigator` with `barPresentation="overlay"` does the same for its tab
+  bar: the measured bar height (bottom safe area included) becomes the
+  scenes' block-end inset.
+- **No double inset.** Whichever region applies an inset clears it for its
+  descendants. A layout region whose only child is a `Pane` or another layout
+  lets that child own the insets. That child fills the region — a `Workbench`
+  area or panel, a `NavStack` view, a `TabNavigator` scene — so a sole `Pane`'s
+  header stays pinned while its own content scrolls. A `Pane` header or footer whose only child is
+  a `Toolbar` hands the inline insets to the toolbar, so the toolbar's dividers
+  still reach the edge.
+
+A plain `Pane` follows the same rules. It assumes it may touch every screen edge
+unless its layout says otherwise. When your own markup puts panes side by side,
+say which sides each pane reaches with `safeAreaEdges`:
+
+```tsx
+<div class="app-columns">
+  <Pane label="Library" safeAreaEdges={['block-start', 'block-end', 'inline-start']}>…</Pane>
+  <Pane label="Reader" safeAreaEdges={['block-start', 'block-end', 'inline-end']}>…</Pane>
+</div>
+```
+
+An app bar or bottom bar that sits directly at a screen edge, outside any
+`Pane` header or footer, claims its edges the same way. A `Toolbar` only pads
+the inline edges an owner hands it until you list the sides it reaches:
+
+```tsx
+<List fill>
+  <Toolbar
+    label="App bar"
+    safeAreaEdges={['block-start', 'inline-start', 'inline-end']}
+    leading={<ToolbarText text="Atlas" />}
+  />
+  <Row gap="none" flex>…panes that list block-end and their outer side…</Row>
+</List>
+```
+
+Each claimed side pads by the edge context, or the full device inset when
+nothing routes that edge, while the bar's surface and divider still reach the
+screen edge. A claimed toolbar inside a `Pane` header or footer adds nothing
+extra, because the pane already owns those edges.
+
+Pass `safeAreaEdges={[]}` for a pane that never sits at a screen edge. In an
+arrangement you own, give each `Pane` (and each edge-claiming `Toolbar`)
+`safeAreaEdges` listing only the sides its region reaches. The toolbar
+configurations layouts accept (a Workbench `mainToolbar` / `mainBottomToolbar`,
+and a Workbench panel's or `CollapsiblePanel`'s `toolbar`) forward
+`safeAreaEdges` to their `Toolbar` the same way.
+A `CollapsiblePanel` clears the edge it covers for its direct flex siblings
+automatically; a panel wrapped in your own grid cell cannot see its siblings,
+so pass the neighboring panes' `safeAreaEdges` yourself.
+
+The device insets come from `--kui-safe-area-block-start`, `-block-end`,
+`-inline-start`, and `-inline-end`, which default to `env(safe-area-inset-*)`.
+Override them on `:root` to reserve room for app-owned chrome or to simulate a
+device in tests.
+
+### Edge-to-edge content inside a Pane
+
+The Pane's scrolling slot publishes its resolved horizontal padding as
+`--kui-pane-content-inset-inline-start` and
+`--kui-pane-content-inset-inline-end`. Both inherited values include the safe
+area on the corresponding side, plus the extra 8px when `deepInset` is true.
+An app component can use them to let a row background or divider reach the
+Pane edge while its text stays on the ordinary content axis:
+
+```css
+.orders-table {
+  margin-inline-start: calc(-1 * var(--kui-pane-content-inset-inline-start));
+  margin-inline-end: calc(-1 * var(--kui-pane-content-inset-inline-end));
+}
+
+.orders-table th:first-child,
+.orders-table td:first-child {
+  padding-inline-start: calc(var(--kui-pane-content-inset-inline-start) + 17px);
+}
+
+.orders-table th:last-child,
+.orders-table td:last-child {
+  padding-inline-end: calc(var(--kui-pane-content-inset-inline-end) + 17px);
+}
+```
+
+Here 17px is the app's chosen text offset from the content slot: a default
+`ContentItem` uses 8px outer margin, 1px border, and 8px inner padding. Adjust
+that offset to match the neighboring content. Keep the table inside the Pane's
+single scrolling slot; the negative margins change only its inline reach. The
+[`Pane` UX catalog example](../ux-demo/demos/pane.tsx) shows both `deepInset`
+states with the same table component.
+
+### Scrolling beneath overlaying chrome
+
+`Pane.scrollClearance` (`"block-start"`, `"block-end"`, or `"both"`) lets the
+scrolling slot pass beneath chrome laid over the pane's edge, such as a
+`DialogSurface` floating footer over a filling Pane. The slot adds the
+inherited `--kui-scroll-clearance-block-*` context that the chrome publishes to
+its block padding and `scroll-padding`, alongside the safe-area and
+`deepInset` insets, so its first and last items still rest clear of the
+chrome. See `docs/layout.md` "Scroll clearance".
+
 ## Decision matrix
 
-| Situation                                                                    | Layout                                                                                          | Device threshold                                                                                                                   |
-| ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
-| Simple app, a few flat sections                                              | `NavStack` with one entry (single pane); add `TabScaffold` for 2–5 co-equal sections on handset | `TabScaffold` on `compact`; promote its tabs to a `Workbench` rail / sidebar `atLeast('desktop')`                                  |
-| Drill-down browsing (list → item → sub-item)                                 | `NavStack`; upgrade to `SplitView` once list + detail fit together                              | `SplitView` two-pane `atLeast('tablet')` landscape / non-`compact`; `NavStack` form on `compact`                                   |
-| Two related panes, selecting on the left updates the right                   | `SplitView`                                                                                     | two panes when not `compact`; collapses to `NavStack` (list → detail) on `compact`                                                 |
-| Complex tool / editor with peripheral panels (navigator, inspector, console) | `Workbench`                                                                                     | full three-panel `atLeast('desktop')`; on smaller classes present the rails via `NavStack` / overlay drawers, not a shrunken shell |
-| Mobile app with 2–5 top-level destinations, each its own drill-down          | `TabScaffold`, each tab a `NavStack`                                                            | bottom bar on `compact`; promote to a rail / sidebar `atLeast('desktop')`                                                          |
+| Situation                                                                    | Layout                                                                                           | Device threshold                                                                                                                   |
+| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
+| Simple app, a few flat sections                                              | `NavStack` with one entry (single pane); add `TabNavigator` for 2–5 co-equal sections on handset | `TabNavigator` on `compact`; promote its tabs to a `Workbench` rail / sidebar `atLeast('desktop')`                                 |
+| Drill-down browsing (list → item → sub-item)                                 | `NavStack`; upgrade to `SplitView` once list + detail fit together                               | `SplitView` two-pane `atLeast('tablet')` landscape / non-`compact`; `NavStack` form on `compact`                                   |
+| Two related panes, selecting on the left updates the right                   | `SplitView`                                                                                      | two panes when not `compact`; collapses to `NavStack` (list → detail) on `compact`                                                 |
+| Complex tool / editor with peripheral panels (navigator, inspector, console) | `Workbench`                                                                                      | full three-panel `atLeast('desktop')`; on smaller classes present the rails via `NavStack` / overlay drawers, not a shrunken shell |
+| Mobile app with 2–5 top-level destinations, each its own drill-down          | `TabNavigator`, each tab a `NavStack`                                                            | bottom bar on `compact`; promote to a rail / sidebar `atLeast('desktop')`                                                          |
 
 ### Worked examples
 
@@ -40,11 +172,28 @@ gate the roomier presentations.
   selection).
 - **IDE (complex tool):** `Workbench` with a left navigator rail, a right
   inspector rail, and a bottom console drawer, each `collapsed` bound to a
-  signal. Only offer this `atLeast('desktop')`.
-- **Social app (tabbed):** `TabScaffold` with Home / Search / Profile tabs, each
+  signal. Only offer this `atLeast('desktop')`. To let people size the
+  navigator or console, opt those panels in with `resizable` and call
+  `wireWorkbench` with their size signals and `deviceClass`; resizing is
+  suspended on `compact`, where the rails become overlay drawers — or give each
+  rail `responsiveOverlayAt: "narrow"` and let the Workbench's own width decide
+  when it overlays, with no device check; pass each rail's `collapsed` signal
+  to `wireWorkbench` so the overlay starts collapsed, takes focus and keeps Tab
+  inside it while open, and closes on Escape or an outside press. Inline
+  rails, fixed or resizable, leave the editor its `mainMinSize` (320px by
+  default) and shrink in proportion when the window narrows; the bottom drawer
+  leaves it `mainMinHeight` (120px by default) and shrinks when the window gets
+  shorter.
+- **Social app (tabbed):** `TabNavigator` with Home / Search / Profile tabs, each
   `content` a `NavStack`. On a tablet/desktop, render the same sections as a
   `Workbench` left rail instead of a bottom bar.
 
+Whatever the layout, call `wireScrollDividers(appRoot)` from
+`@kerfjs/ui/wire-scroll-dividers` once: every `Pane` a layout renders, every
+`NavStack`'s top chrome and bottom toolbar, and every `TabNavigator` bar then
+draw the line between the pinned chrome and the scrolling content only while
+content is scrolled beneath them, and toolbars need no divider of their own. See [Scroll dividers](layout.md#scroll-dividers).
+
 ## Dialogs
 
 Pick the dialog's inner layout by the same complexity axis, then apply the device

package/docs/apple-hig.md

@@ -7,10 +7,12 @@ Native Apple applications should use native platform controls and follow the Hum
 - Accessibility is behavior: every workflow is keyboard-operable; focus is visible; DOM and reading order agree; controls have accessible names; decorative icons are hidden.
 - Use adaptive semantic colors. Every custom role needs usable light, dark, and increased-contrast behavior. Never rely on color alone.
 - Use the system UI font stack and allow browser zoom through 200%. Avoid thin weights and hard minimums that clip enlarged text.
+- On iOS, prevent unwanted focus magnification by keeping editable text legible at touch widths. Do not force the page scale back on blur: that would also undo a person's deliberate pinch zoom.
 - Group with space and alignment before adding borders. Keep essential content in the leading reading path and secondary detail in progressive disclosure.
 - Use one icon family and one metaphor per action. Directional icons may mirror in RTL; checkmarks, logos, and real-world objects do not.
 - Motion is brief, causal, and optional. Honor reduced-motion and reduced-transparency preferences; repeating indicators stop moving under reduced motion.
 - Writing is concise, specific, and action-led. Labels describe the result, not implementation details.
+- Capitalize by element type, consistently: names of commands, controls, views, and fields use title style; descriptions, messages, tooltips, and option text use sentence style. See [Writing interface copy](./writing.md#capitalization).
 
 ## Interaction