@kerfjs/ui 5.0.0-beta.50 → 5.0.0-beta.52

package/docs/webawesome-theme.md

@@ -54,12 +54,30 @@ pointer targets. Override `--kui-wa-carousel-icon-size`,
 `--kui-wa-carousel-dot-hit-size` on a carousel or containing scope when a
 product needs different geometry.
 
+Code text uses Kerf's named monospace stack, `--kui-font-mono`
+(`ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono",
+monospace`), and the theme points `--wa-font-family-code` at it. Web Awesome's
+own `ui-monospace, monospace` renders the generic face (Courier on macOS) in
+Chromium, which does not recognize `ui-monospace`; because the generic
+`monospace` ends any stack, Kerf's token owns the stack rather than appending
+fallbacks after Web Awesome's. Override `--kui-font-mono` to change code text in
+both Kerf and Web Awesome components.
+
 Form fields carry the same content-item inset as the Kerf primitives: a 1px
 border with 8px inside it (`--wa-form-control-border-width`,
 `--wa-form-control-padding-block`, and `--wa-form-control-padding-inline` are set
 to the `--kui-layout-item-border-width` / `--kui-layout-item-padding` values), so
-a single-line control lands at the standard ~40px height and the value sits 9px
-in from the field edge. Each field's top label is inset by that same border +
+the value sits 9px in from the field edge. Default-size single-line controls
+share Kerf's 44px control height — the height of a Kerf `Select`, a toolbar
+group, and a list row — so a `wa-input` or `wa-button` sits flush beside a Kerf
+`Select`. The theme sets `--wa-form-control-height` to `2.75em` (44px at the
+16px default) on Button, Color Picker, Input, Known Date, Number Input, Radio
+Group, Select, Textarea (its minimum height), and Time Input, so `size="large"`
+scales proportionally while `size="small"` keeps Web Awesome's compact secondary
+height. The token is scoped to those controls rather than the root because Web
+Awesome also derives tag, copy-button, and toast geometry from it. Buttons
+inside a `ToolbarControlGroup` keep the group's 40px (32px compact) control
+height. Each field's top label is inset by that same border +
 padding (9px) so it lines up with the value inside the field, and is styled
 exactly like a `ListHeader` label — uppercase, `--kui-font-xs`, weight 650, quiet
 foreground. This applies to every free field that exposes a top label

package/docs/workbench.md

@@ -12,6 +12,12 @@ import { Workbench } from "@kerfjs/ui/workbench";
 import "@kerfjs/ui/workbench.css";
 ```
 
+A top-level `Workbench` needs a definite containing height. Import the opt-in
+`@kerfjs/ui/document.css` baseline and add `.kui-app-root` to the direct mount
+container, or provide an equivalent definite height in application-owned
+layout. The component intentionally uses `height: 100%` rather than `100dvh` so
+it can also be embedded. See [Document baseline](document-baseline.md).
+
 ## State lives in the app
 
 `Workbench` is declarative and the collapse is **pure CSS** — no wire. The app
@@ -90,7 +96,10 @@ with state-derived props:
 ```
 
 `wireResizableRegions` marks the active region with `data-resizing` and the
-package CSS suppresses content motion during pointer resize. A collapsed,
+package CSS suppresses content motion during pointer resize. It applies the
+live size to both the track and the slide-motion content, so content fills the
+region throughout a drag, including any safe-area edge extent, and a later
+collapse slides it out at the resized width. A collapsed,
 overlay, or hidden region is not resizeable. Together these policies replace
 app CSS for separator suppression, instant-track/composited-content collapse,
 popup overflow, mobile overlay/hidden replacement, resize-transition guards,
@@ -110,6 +119,16 @@ must classify public application selectors. Prefer the component props and two
 size tokens before selecting internal anatomy, and do not target its data
 attributes or descendant tags as styling contracts.
 
+## Safe areas
+
+Each rail and the drawer grows by the unsafe inset of the screen edge it docks
+to, so its surface and separator paint through while its content keeps the
+configured size and is padded for the edges it touches. The main area pads for
+the edges it reaches, inside its scroller: an expanded inline rail or drawer
+takes that edge away, and collapsing it (or presenting it as an overlay) hands
+the edge back. A region whose only child is a `Pane` or layout lets that child
+own the insets. See [Choosing an app layout › Safe areas](app-layouts.md#safe-areas).
+
 ## How the collapse animates
 
 Collapsing snaps the panel's flex track to zero in a single reflow (so the work

package/evaluator/index.mjs

@@ -336,6 +336,50 @@ async function inspectPage(page, geometryContracts) {
       return null;
     };
 
+    const hitExtent = (element, rect) => {
+      const root = element.getRootNode();
+      const probe = root.elementFromPoint ? root : document;
+      const inViewport = (x, y) =>
+        x >= 0 && y >= 0 && x < innerWidth && y < innerHeight;
+      const owns = (x, y) => {
+        const hit = probe.elementFromPoint(x, y);
+        return !!hit && (hit === element || element.contains(hit));
+      };
+      const x = rect.left + rect.width / 2;
+      const y = rect.top + rect.height / 2;
+      if (!inViewport(x, y) || !owns(x, y)) return null;
+      // Walk out in 1px steps (no further than the 44px goal needs), then
+      // refine the last step in quarter pixels; the reach is the last owned
+      // sample, so it never overstates the target. A walk stopped by
+      // the viewport edge cannot see the rest of the layer, so it is marked
+      // and mirrored from the opposite side (hit layers are symmetric insets).
+      const reach = (dx, dy) => {
+        const at = (distance) => [x + dx * distance, y + dy * distance];
+        let owned = 0;
+        while (owned < 24) {
+          const point = at(owned + 1);
+          if (!inViewport(...point)) return { distance: owned, clipped: true };
+          if (!owns(...point)) break;
+          owned += 1;
+        }
+        if (owned >= 24) return { distance: owned, clipped: false };
+        while (owns(...at(owned + 0.25))) owned += 0.25;
+        return { distance: owned, clipped: false };
+      };
+      const span = (first, second) =>
+        first.clipped && second.clipped
+          ? first.distance + second.distance
+          : first.clipped
+            ? 2 * second.distance
+            : second.clipped
+              ? 2 * first.distance
+              : first.distance + second.distance;
+      return {
+        width: span(reach(-1, 0), reach(1, 0)),
+        height: span(reach(0, -1), reach(0, 1)),
+      };
+    };
+
     for (const element of interactives) {
       const target = selector(element);
       const rect = element.getBoundingClientRect();
@@ -495,14 +539,35 @@ async function inspectPage(page, geometryContracts) {
           'button,input:not([type="hidden"]),select,textarea,[role]',
         ) &&
         (rect.width < 43.5 || rect.height < 43.5)
-      )
-        diagnostics.push({
-          code: 'KUI-B050',
-          selector: target,
-          message: `Hit target is ${rect.width.toFixed(1)}×${rect.height.toFixed(1)}px; expected at least 44×44px.`,
-          repair: repair.target,
-          evidence: { width: rect.width, height: rect.height },
-        });
+      ) {
+        // The border box understates a control whose pointer target is
+        // extended by a transparent hit layer (a positioned ::before/::after
+        // that receives pointer events). Hit-test outward from the center to
+        // measure the area the pointer can actually reach; a probe that finds
+        // no hit (off-screen, covered center) keeps the border box.
+        const hit = hitExtent(element, rect);
+        const width = Math.max(rect.width, hit?.width ?? 0);
+        const height = Math.max(rect.height, hit?.height ?? 0);
+        // Compact density is a deliberate trade-off: its rows are 36px tall,
+        // and a taller hit layer would reach into the neighboring row. Inside
+        // `[data-density="compact"]` a target still needs the full 44px width
+        // but only the 36px compact row height.
+        const compact = element.closest('[data-density="compact"]') !== null;
+        const requiredHeight = compact ? 36 : 44;
+        if (width < 43.5 || height < requiredHeight - 0.5)
+          diagnostics.push({
+            code: 'KUI-B050',
+            selector: target,
+            message: `Hit target is ${width.toFixed(1)}×${height.toFixed(1)}px; expected at least 44×${requiredHeight}px${compact ? ' (compact density)' : ''}.`,
+            repair: repair.target,
+            evidence: {
+              width,
+              height,
+              box: { width: rect.width, height: rect.height },
+              required: { width: 44, height: requiredHeight },
+            },
+          });
+      }
     }
 
     const parse = (value) => {

package/llms.txt

@@ -34,7 +34,9 @@ the folder modules, and CSS only imports their owner stylesheets.
    when app-owned components must participate in selection or alignment.
    Load the [Composition catalog v2](./ai/component-catalog-v2.json) to
    mechanically evaluate parents, contexts, zones/cardinality, children, state,
-   wiring, responsive/layout/accessibility rules, and public boundaries. V1
+   wiring (including the wiring-owned `stateAttributes` an app must never
+   render or remove), responsive/layout/accessibility rules, and public
+   boundaries. V1
    remains compatible; v2 joins catalogs by `package:id`. Consumer v2 catalogs
    use [the v2 extension schema](./ai/component-catalog-extension-v2.schema.json).
    Load [compile-time contracts](./ai/compile-time-contracts-v1.json) for stable
@@ -70,7 +72,9 @@ the folder modules, and CSS only imports their owner stylesheets.
    [catalog-authoring.json](./ai/catalog-authoring.json), then follow its
    authoritative [Catalog demo authoring contract](./docs/catalog.md#catalog-demo-authoring-contract).
    Use its component/composition/recipe taxonomy and functional-group,
-   importance, alphabetical-tie, and recipes-last ordering policy.
+   importance, alphabetical-tie, and recipes-last ordering policy. Focused
+   demos and recipes use public components plus `CatalogExample.viewport`,
+   never local stylesheets, inline styles, or styling-only classes.
 5. **Apply the rules below and in** [skill.md](./ai/skill.md).
 6. **Before calling an integration complete**, run
    [`kerf-ui-doctor`](./docs/ui-doctor.md). Its portable JSON report merges
@@ -103,6 +107,11 @@ the folder modules, and CSS only imports their owner stylesheets.
   own the geometry (8px inline margin + 1px border + 8px padding). Do not add a
   container padding on top of a content-item's own margin — pick one owner. Use
   `.kui-content` for 24px major vertical rhythm.
+- **Opt into document globals explicitly.** Import `@kerfjs/ui/document.css`
+  once for border-box sizing, token-backed body/link presentation, and zero body
+  margin. Put `.kui-app-root` on the one direct mount container only when a
+  percentage-height shell needs the provided `html` → `body` → app-root height
+  chain. The baseline is not part of `styles.css` or component browser imports.
 - **Use `Row` for horizontal and `List` for vertical layout.** Both expose
   physical `hAlign`/`vAlign` props and typed gaps. Row defaults to left/full,
   an `xs` gap, and no wrapping; List retains full/top and zero-gap defaults.
@@ -117,13 +126,19 @@ the folder modules, and CSS only imports their owner stylesheets.
   shorthand (`gap="xs"`, `gap="m"`) or a complete `CssLength` from the CSS-free
   `@kerfjs/ui/css-values` builders; raw CSS strings are rejected. Use `flex()`
   for List flex, typed lengths for Skeleton geometry, and
-  `uiColor()`/`colorVar()` for choice-icon colors. These brands are intentionally
+  foreground colors for choice icons: `uiColor()` with an `*-on-*`/text token
+  or `foregroundColorVar()`; fill aliases such as `uiColor('success')` do not
+  type-check. These brands are intentionally
   not interchangeable; rows use classes/tokens/props rather than raw `style`.
 - **Use `Grid` for a fixed positive count of equal-width columns.** It uses
   zero-minimum fractional tracks, so intrinsic content cannot make one column
   wider than its peers. The app owns responsive count changes; use custom CSS
   grid for asymmetric/intrinsic tracks and `ResizableRegion` for adjustable
   boundaries. `Grid.gap` and `Grid.flex` use the same typed grammars as Row.
+- **Give a layout root `fill`, not a frame `Pane`.** A Row, List, or Grid that
+  is the sole layout root of a definite-height parent takes its full height
+  with `fill` and carries safe `data-*` markers through `rootAttributes`.
+  Inside a flex layout use `flex` instead.
 - **Keep Web Awesome on the shared inset tiers.** `webawesome.css` uses
   `--kui-wa-control-inset` (8px controls/items) and
   `--kui-wa-surface-margin` / `--kui-wa-surface-inset` (8px around/inside
@@ -173,22 +188,25 @@ the folder modules, and CSS only imports their owner stylesheets.
   need a Web Awesome feature, chiefly the `slot="trigger"` button of a `wa-dropdown`
   popup menu. A toolbar popup menu is a `single` `ToolbarControlGroup` around a
   `wa-dropdown` (its `slot="trigger"` `wa-button` is the toolbar button, kept under
-  `data-morph-skip-children`). Compact mixed groups keep standard item padding
-  and raised selected chrome without an internal separator; the selected item
-  paints over the outer border. For an avatar control, set `content="avatar"` and
-  `avatarImage` on the group instead of inserting an `img`; a lone control paints
-  the group and a multi-button group paints only its pressed highlight.
+  `data-morph-skip-children`). Let the group size the trigger from its icon,
+  localized text, and caret; do not force a dropdown or button width. Compact
+  mixed groups keep standard item padding and raised selected chrome without an
+  internal separator; the selected item paints over the outer border. For an
+  avatar control, set `content="avatar"` and `avatarImage` on the group instead of
+  inserting an `img`; a lone control paints the group and a multi-button group
+  paints only its pressed highlight.
 - **Use one direct toolbar composition for panel/dialog/page headings.** Put an
   optional icon in a `ToolbarControlGroup`, an extra-large `ToolbarText` directly
   in the leading zone, and actions in a trailing group. Supporting copy is
   app-owned content below. Do not create a private heading wrapper or restyle the
   toolbar.
-- **Use `Text` for ordinary semantic headings and paragraphs outside toolbar
-  title zones.** Omit `variant` for the default `p`, or pass `h1`–`h6` based on
-  the document outline. Independently compose `tone="quiet|danger"`,
+- **Use `Text` for ordinary semantic headings, paragraphs, and inline secondary
+  text outside toolbar title zones.** Omit `variant` for the default `p`, pass
+  `h1`–`h6` based on the document outline, or use `variant="span"` inside a row,
+  label, or table cell without adding box geometry. Independently compose `tone="quiet|danger"`,
   `size="compact"`, and `font="monospace"` for supporting, error, compact, and
   code roles instead of global utility classes. It passes native attributes
-  through and owns the standard transparent border plus item padding; keep
+  through; block variants own the standard transparent border plus item padding, while `span` owns none. Keep
   toolbar titles on `ToolbarText` and list-aligned bare prose on `ListInsetText`.
 - **Space by the five-step scale, by relationship not by eye.** `0`
   `--kui-space-none`, `4px` `--kui-space-2xs`, `8px` `--kui-space-xs` (inside a
@@ -279,7 +297,7 @@ tree-shakeable, declarative with `wire…` helpers, each with a companion CSS im
 `@kerfjs/ui/device-class`. For a standalone collapsible rail/drawer outside a full
 shell, `@kerfjs/ui/collapsible-panel` (`CollapsiblePanel`, `CollapsiblePanelToggle`)
 
-- `@kerfjs/ui/wire-sidebar` (`wireSidebar`: toggle, focus, compact overlay, persistence).
+- `@kerfjs/ui/wire-sidebar` (`wireSidebar`: toggle, focus, compact overlay, persistence; a compact overlay starts closed and opens only on a user action, and `inlineCollapsed` declares a panel's inline default).
   `@kerfjs/ui/catalog` is another opt-in shell — a
   `Catalog` component + `wireCatalog` helper for building a component-gallery catalog
   (collapsible category sidebar + preview stage + resources footer, with an opt-in
@@ -300,7 +318,7 @@ shell, `@kerfjs/ui/collapsible-panel` (`CollapsiblePanel`, `CollapsiblePanelTogg
 - [component-contract.md](./docs/component-contract.md): what a component owns vs. what the app owns.
 - [accessibility.md](./docs/accessibility.md): keyboard and ARIA contracts per component.
 - [recipes.md](./docs/recipes.md): production compositions (app shell, list-detail dialog, composer form, …) as copyable references.
-- [app-layouts.md](./docs/app-layouts.md): choosing `NavStack`/`SplitView`/`Workbench`/`TabScaffold` by data + interaction + device, and dialog presentation.
+- [app-layouts.md](./docs/app-layouts.md): choosing `NavStack`/`SplitView`/`Workbench`/`TabScaffold` by data + interaction + device, and dialog presentation, plus the safe-area model (surfaces paint through unsafe areas; content pads only the edges it reaches; `Pane.safeAreaEdges` for app-owned arrangements, `Toolbar.safeAreaEdges` for an app bar or bottom bar at a screen edge).
 - [webawesome-theme.md](./docs/webawesome-theme.md): the optional Web Awesome theme; catalog coverage means themed-and-supported, not preferred (prefer the Kerf primitive when one exists). The UX sidebar visibly tags superseded and exceptional Web Awesome choices as `Discouraged`; Popup remains an available conditional positioning primitive.
 - [component-catalog.json](./ai/component-catalog.json) + [component-catalog-extension.schema.json](./ai/component-catalog-extension.schema.json) + [catalog-authoring.json](./ai/catalog-authoring.json) + [public-api-signatures-v1.md](./ai/public-api-signatures-v1.md) + [webawesome-jsx-signatures-v1.md](./ai/webawesome-jsx-signatures-v1.md): machine-readable selection facts, a reusable app-component extension contract, Catalog authoring discovery, and exact signatures.
 - [compile-time-contracts-v1.json](./ai/compile-time-contracts-v1.json) + [type-contracts.md](./docs/type-contracts.md): stable compile diagnostics, packed-declaration proof, migrations, and explicit non-goals.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kerfjs/ui",
-  "version": "5.0.0-beta.50",
+  "version": "5.0.0-beta.52",
   "description": "Accessible, composable UI primitives for kerf applications.",
   "type": "module",
   "license": "MIT",
@@ -292,6 +292,7 @@
       "import": "./dist/index.js"
     },
     "./foundation.css": "./dist/styles/foundation.css",
+    "./document.css": "./dist/styles/document.css",
     "./layout.css": "./dist/styles/layout.css",
     "./webawesome.css": "./dist/styles/webawesome.css",
     "./styles.css": "./dist/styles/styles.css",
@@ -351,7 +352,8 @@
   "scripts": {
     "build": "tsup && node ../scripts/clean-dist-output.mjs dist && node scripts/build-css.mjs && node scripts/build-browser-entries.mjs",
     "dev": "npm run build && vite --config ux-demo/vite.config.ts",
-    "demo:build": "npm run build && vite build --config ux-demo/vite.config.ts && node scripts/check-demo-bundle.mjs",
+    "demo:bundle": "npm run build && vite build --config ux-demo/vite.config.ts",
+    "demo:build": "npm run demo:bundle && node scripts/check-demo-bundle.mjs",
     "demo:serve": "vite preview --config ux-demo/vite.config.ts",
     "test:e2e:serve": "npm run check:catalog && npm run check:demo-conformance && npm run demo:build && npm run demo:serve",
     "format": "prettier --write . --ignore-unknown",