@kerfjs/ui 5.0.0-beta.9 → 5.0.0-beta.90

package/docs/anchored-surface.md

@@ -0,0 +1,51 @@
+# 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`), and `gap` feed the
+shared `kerfjs/overlay` positioning core: it flips vertically when the other
+side fits, clamps horizontally, and follows scroll and resize. Content taller
+than the viewport scrolls inside the surface.
+
+```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>`. For app-owned
+dialogs, include `<div data-kerf-overlay-host data-morph-skip></div>` in the
+dialog markup so controls in the anchored surface stay interactive. Dialogs
+opened by `kerfjs/overlay` get that host automatically. The helper uses the
+browser top layer where available, and the shared overlay fallback elsewhere.
+Closing an anchor's modal dialog also closes the surface. The temporary pointer
+anchor is removed when the surface closes.
+
+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,21 +9,135 @@ 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`
+  semantics (focus, compact overlay, persistence).
 
 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`.
+
+## 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 chrome is
+  not inset on that edge. Collapse the rail and the center picks up the edge.
+- **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.
+
 ## 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
 
@@ -36,11 +150,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,6 +7,7 @@ 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.