@kerfjs/ui 5.0.0-beta.4 → 5.0.0-beta.41

package/docs/webawesome-theme.md

@@ -4,10 +4,10 @@
 free components and the Kerf/Hot Sheet 2 design system.
 
 ```ts
-import type {} from '@kerfjs/ui/webawesome';
-import '@kerfjs/ui/webawesome.css';
-import '@awesome.me/webawesome/dist/components/button/button.js';
-import '@awesome.me/webawesome/dist/components/input/input.js';
+import type {} from "@kerfjs/ui/webawesome";
+import "@kerfjs/ui/webawesome.css";
+import "@awesome.me/webawesome/dist/components/button/button.js";
+import "@awesome.me/webawesome/dist/components/input/input.js";
 ```
 
 The type-only package import augments `kerfjs/jsx-runtime` with the 70
@@ -54,6 +54,80 @@ 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.
 
+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 +
+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
+(`::part(form-control-label)` plus the Slider's `::part(label)`). OTP Input
+exposes `label` instead of `form-control-label`; the theme gives it the same
+uppercase 12px/650 treatment. Inline control labels (Checkbox, Switch) keep
+their natural sentence case.
+
+Known Date's field captions and bordered text-like field hints use the same 9px
+inline inset, keeping secondary text aligned with the value rather than the
+field's outer border. This covers Input, Known Date, Number Input, OTP Input,
+Select, Textarea, and Time Input hints; unbordered group hints retain their own
+natural geometry. OTP Input's label and hint both use the 9px field-text inset.
+
+Checkbox Group and Radio Group option regions receive the shared 8px inline
+outer inset through `::part(form-control-input)`. Unlike bordered fields, these
+groups have no shell of their own, so the explicit margin places their controls
+on the same content-item geometry without adding padding to each option. The
+Color Picker trigger receives the same 8px inline outer inset because it also
+has no bordered field shell. Slider's complete interactive region receives the
+shared 8px logical inline outer inset through `::part(slider)`, keeping its
+track, markers, references, and hint together without moving the label.
+
+Non-field chrome follows explicit, overridable control, surface, and container
+tiers:
+
+- `--kui-wa-control-inset` defaults to the 8px content-item padding. It applies
+  to tabs, tree-item trailing content, tags, and dropdown items. Tree selection
+  also uses Kerf's 8px inline outer margin, so its background reads as an inset
+  list item instead of an edge-to-edge stripe. Buttons already consume the same
+  `--wa-form-control-padding-inline` 8px value at every size, so no extra part
+  override is needed.
+- `--kui-wa-surface-margin` and `--kui-wa-surface-inset` default to 8px.
+  Accordion, Card, Details, Callout, and Include use the margin around their
+  complete surface and the inset within it. Accordion applies the outer margin
+  once to the group rather than separating connected items; Card's header,
+  body, and footer all receive the full inset.
+- `--kui-wa-container-inset` defaults to the 16px homogeneous-group step. Tab
+  Panel retains this roomier tier for unframed panel content. Dialog body uses
+  the 8px surface inset, while its footer uses the 16px container inset so
+  content stays compact and the action group has a clearer boundary. These two
+  parts do not inherit the dialog's shared `--spacing` value.
+
+Add `class="hide-actions"` to a `wa-dialog` when the dialog supplies its own
+dismissal affordance and should omit Web Awesome's header action region. The
+theme sets `display: none` on the directly exported `header-actions` part; it
+does not attempt to chain `::part()` through the internal `dialog` and `header`
+parts, which CSS shadow parts do not support.
+
+Badge remains intentionally compact at Web Awesome's intrinsic `0.375em` block /
+`0.625em` inline padding (4.5px / 7.5px at its default 12px text size): it is a
+short status or count, not a content item. Breadcrumb has no bordered or filled
+container, and Scroller delegates item chrome to its slotted children, so both
+retain their upstream geometry. Web Awesome 3.12's free catalog has
+`wa-dropdown-item`, but no `wa-menu-item`; the theme therefore styles the
+supported dropdown item rather than carrying a dead selector.
+
+Override a tier for a product scope after importing the theme:
+
+```css
+.roomy-editor {
+  --kui-wa-control-inset: 0.75rem;
+  --kui-wa-surface-margin: 0.75rem;
+  --kui-wa-surface-inset: 0.75rem;
+  --kui-wa-container-inset: 1.5rem;
+}
+```
+
 Accordion, Details, Breadcrumb, and Kerf Select share
 `--kui-disclosure-icon-scale` (default `.5`) so disclosure and traversal
 chevrons keep the same visual weight. The Accordion and Details components
@@ -73,12 +147,12 @@ subtree, or for one instance after the theme import:
 
 ```css
 :root {
-  --wa-tooltip-arrow-size: .375rem;
-  --kui-wa-popover-arrow-size: .375rem;
+  --wa-tooltip-arrow-size: 0.375rem;
+  --kui-wa-popover-arrow-size: 0.375rem;
 }
 
 .pointed-popover {
-  --arrow-size: .5rem;
+  --arrow-size: 0.5rem;
 }
 ```
 
@@ -179,7 +253,7 @@ smallest subtree that needs a different identity:
 :root {
   --wa-color-brand-fill-loud: #7540a8;
   --wa-color-focus: #7540a8;
-  --wa-form-control-border-radius: .5rem;
+  --wa-form-control-border-radius: 0.5rem;
 }
 
 .billing-workspace {

package/docs/workbench.md

@@ -0,0 +1,123 @@
+# Workbench
+
+`@kerfjs/ui/workbench` is the Xcode-like multi-panel workspace: a collapsible
+left rail, right rail, and bottom drawer around a central work area (any absent).
+It generalizes the instant-width / sliding-content collapse used by the catalog
+sidebar. One of the opt-in app layouts (see
+[`../../docs/23-app-layouts.md`](../../docs/23-app-layouts.md)); best on
+desktop-class devices.
+
+```ts
+import { Workbench } from "@kerfjs/ui/workbench";
+import "@kerfjs/ui/workbench.css";
+```
+
+## State lives in the app
+
+`Workbench` is declarative and the collapse is **pure CSS** — no wire. The app
+owns each panel's `collapsed` flag (usually a signal) and toggles it; the panel
+animates itself.
+
+```tsx
+const navCollapsed = signal(false);
+
+<Workbench
+  id="studio"
+  label="Studio"
+  main={<Editor />}
+  leftRail={{
+    content: <Navigator />,
+    label: "Navigator",
+    collapsed: navCollapsed.value,
+    size: 280,
+  }}
+  rightRail={{
+    content: <Inspector />,
+    label: "Inspector",
+    collapsed: inspectorCollapsed.value,
+  }}
+  bottomDrawer={{
+    content: <Console />,
+    label: "Console",
+    collapsed: consoleCollapsed.value,
+  }}
+/>;
+```
+
+Each `WorkbenchPanel` takes `content`, an optional `collapsed`, an optional
+`size` (rail width or drawer height in px, overriding the CSS default —
+`--kui-workbench-rail-width` 280px, `--kui-workbench-drawer-height` 220px), and
+an optional `label`. Common shell behavior is configured rather than restyled:
+
+- `separator: "auto" | "hidden"` controls the owned dock-edge separator;
+- `collapseMotion: "slide" | "fade-slide" | "none"` keeps the track change
+  instant while choosing composited content motion;
+- `contentOverflow: "clip" | "auto" | "visible"` lets a drawer temporarily
+  expose an open popup without a descendant override;
+- `presentation: "inline" | "overlay" | "hidden"` supports compact overlays
+  or a responsive replacement. Overlay panels clamp both their track and fixed-size
+  animated content to the configured viewport-relative maximum;
+- `restoreControl` places an application-owned restore affordance in a
+  safe-area-aware viewport corner (`restorePosition` chooses the corner).
+
+The same policy props are available on `ResizableRegion` and
+`CollapsiblePanel`, so a resizable application shell does not need to reach
+into `.kui-resizable-region__content`.
+
+## Resizable application-shell migration
+
+An application such as Hot Sheet can replace its shell descendant overrides
+with state-derived props:
+
+```tsx
+<ResizableRegion
+  id="terminal-drawer"
+  label="Terminal drawer"
+  axis="vertical"
+  edge="start"
+  size={drawerSize.value}
+  min={180}
+  max={520}
+  collapsed={!drawerVisible.value}
+  separator={magnified.value ? "hidden" : "auto"}
+  collapseMotion="fade-slide"
+  contentOverflow={createMenuOpen.value ? "visible" : "clip"}
+  presentation={mobile.value ? "overlay" : "inline"}
+  restoreControl={<button data-action="show-drawer">Show terminals</button>}
+>
+  <TerminalDrawer />
+</ResizableRegion>
+```
+
+`wireResizableRegions` marks the active region with `data-resizing` and the
+package CSS suppresses content motion during pointer resize. 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,
+and safe-area restore placement. The app still owns the signals and decides
+when each policy applies.
+
+## Public styling boundary
+
+Import `@kerfjs/ui/workbench.css` after the component subpath. Applications may
+set `--kui-workbench-rail-width` and `--kui-workbench-drawer-height` on a
+Workbench instance. The supported composition classes are `.kui-workbench`,
+`.kui-workbench__rail`, `.kui-workbench__rail--left`,
+`.kui-workbench__rail--right`, `.kui-workbench__center`,
+`.kui-workbench__main`, `.kui-workbench__drawer`, and
+`.kui-workbench__panel-content`, and `.kui-workbench__restore`; these exact hooks are cataloged for tools that
+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.
+
+## How the collapse animates
+
+Collapsing snaps the panel's flex track to zero in a single reflow (so the work
+area relayouts once, not per frame) while the panel's fixed-size content slides
+out via a composited `transform` — a rail slides horizontally, the drawer
+vertically — clipped by the shell's overflow. The drawer content is positioned
+against the shell's stable bottom edge, so opening and closing move monotonically
+through the transform rather than inheriting a changing normal-flow origin. It
+honors `prefers-reduced-motion` (the slide collapses to instant). On smaller
+device classes, present the rails' contents through a `NavStack` or overlay
+drawers rather than shrinking the three-panel shell.

package/doctor/cli.mjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+
+import console from 'node:console';
+import { execFile } from 'node:child_process';
+import { writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import process from 'node:process';
+import { promisify } from 'node:util';
+
+import { formatUiDoctorText, runUiDoctor, UI_DOCTOR_EXIT } from './index.mjs';
+
+const execFileAsync = promisify(execFile);
+const args = process.argv.slice(2);
+const take = (name, repeat = false) => {
+  const values = [];
+  while (args.includes(name)) {
+    const index = args.indexOf(name);
+    const value = args[index + 1];
+    if (!value || value.startsWith('--'))
+      throw new Error(`${name} requires a value.`);
+    args.splice(index, 2);
+    values.push(value);
+    if (!repeat) break;
+  }
+  return repeat ? values : values[0];
+};
+
+async function changedPaths(root) {
+  const { stdout: tracked } = await execFileAsync(
+    'git',
+    ['diff', '--name-only', '--diff-filter=ACMR', 'HEAD', '--'],
+    { cwd: root },
+  );
+  const { stdout: untracked } = await execFileAsync(
+    'git',
+    ['ls-files', '--others', '--exclude-standard'],
+    { cwd: root },
+  );
+  return [
+    ...new Set(`${tracked}\n${untracked}`.split(/\r?\n/).filter(Boolean)),
+  ].sort();
+}
+
+try {
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`Usage: kerf-ui-doctor [--full | --changed] [options]
+
+Options:
+  --root <path>          Workspace root (default: current directory)
+  --package <name|path>  Select one workspace package
+  --path <path>          Restrict changed mode (repeatable)
+  --config <path>        Doctor config (default: .kerf-ui-doctor.json)
+  --browser-url <url>    Explicitly enable browser evaluation
+  --browser <list>       Comma-separated chromium,firefox,webkit
+  --eslint <preset>      recommended-ui or strict-ui
+  --format <format>      text or json (default: text)
+  --output <path>        Also write the merged report
+  --no-cache             Disable the content-addressed cache
+
+Exit codes: 0 clean, 1 findings, 2 configuration/tool failure, 130 cancelled.`);
+    process.exit(0);
+  }
+  const root = resolve(take('--root') ?? process.cwd());
+  const packageSelector = take('--package');
+  const explicitPaths = take('--path', true);
+  const configPath = take('--config');
+  const url = take('--browser-url');
+  const browserList = take('--browser');
+  const eslintConfig = take('--eslint') ?? 'recommended-ui';
+  const format = take('--format') ?? 'text';
+  const output = take('--output');
+  const full = args.includes('--full');
+  const changed = args.includes('--changed');
+  const noCache = args.includes('--no-cache');
+  const known = new Set(['--full', '--changed', '--no-cache']);
+  const unknown = args.filter((item) => !known.has(item));
+  if (unknown.length)
+    throw new Error(`Unknown arguments: ${unknown.join(' ')}`);
+  if (full && changed)
+    throw new Error('--full and --changed are mutually exclusive.');
+  if (!['text', 'json'].includes(format))
+    throw new Error('--format must be text or json.');
+  if (!['recommended-ui', 'strict-ui'].includes(eslintConfig))
+    throw new Error('--eslint must be recommended-ui or strict-ui.');
+  const abort = new globalThis.AbortController();
+  process.once('SIGINT', () => abort.abort());
+  const paths =
+    changed && !explicitPaths.length ? await changedPaths(root) : explicitPaths;
+  const report = await runUiDoctor({
+    root,
+    package: packageSelector,
+    mode: changed ? 'changed' : full ? 'full' : undefined,
+    paths,
+    configPath,
+    cache: !noCache,
+    signal: abort.signal,
+    eslintConfig,
+    browser: url
+      ? { url, browsers: browserList?.split(',').map((item) => item.trim()) }
+      : undefined,
+  });
+  const rendered =
+    format === 'json'
+      ? JSON.stringify(report, null, 2)
+      : formatUiDoctorText(report);
+  if (output) await writeFile(resolve(root, output), `${rendered}\n`);
+  else console.log(rendered);
+  process.exitCode = report.exitCode;
+} catch (error) {
+  console.error(`kerf-ui-doctor: ${error.message}`);
+  process.exitCode =
+    process.exitCode === UI_DOCTOR_EXIT.cancelled
+      ? process.exitCode
+      : UI_DOCTOR_EXIT.configuration;
+}

package/doctor/config.schema.json

@@ -0,0 +1,68 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/brianwestphal/kerf/main/ui/doctor/config.schema.json",
+  "title": "Kerf UI doctor configuration",
+  "type": "object",
+  "required": ["schemaVersion"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "schemaVersion": { "const": 1 },
+    "mode": { "enum": ["full", "changed"] },
+    "package": { "type": "string", "minLength": 1 },
+    "stages": {
+      "type": "object",
+      "properties": {
+        "catalog": { "type": "boolean" },
+        "typescript": { "type": "boolean" },
+        "eslint": { "type": "boolean" },
+        "analyzer": { "type": "boolean" },
+        "browser": { "type": "boolean" }
+      },
+      "additionalProperties": false
+    },
+    "browser": {
+      "type": "object",
+      "required": ["url"],
+      "properties": {
+        "url": { "type": "string", "pattern": "^https?://" },
+        "browsers": {
+          "type": "array",
+          "items": { "enum": ["chromium", "firefox", "webkit"] },
+          "uniqueItems": true
+        },
+        "retention": { "enum": ["always", "on-failure", "never"] },
+        "outputDirectory": { "$ref": "#/$defs/path" },
+        "reportPath": { "$ref": "#/$defs/path" }
+      },
+      "additionalProperties": false
+    },
+    "cache": { "type": "boolean" },
+    "suppressions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "rules", "target", "rationale"],
+        "properties": {
+          "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+          "rules": {
+            "type": "array",
+            "items": { "type": "string", "minLength": 1 },
+            "minItems": 1,
+            "uniqueItems": true
+          },
+          "target": { "$ref": "#/$defs/path" },
+          "rationale": { "type": "string", "minLength": 12 }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "path": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^(?!/)(?!.*(^|/)\\.\\.(/|$))(?!.*[?*]).+"
+    }
+  }
+}

package/doctor/eslint-diagnostics.d.mts

@@ -0,0 +1,24 @@
+export interface EslintDiagnosticLike {
+  ruleId?: string | null;
+  message: string;
+}
+
+export function isForeignRuleDefinitionDiagnostic(
+  item: EslintDiagnosticLike,
+): boolean;
+
+export interface ConsumerEslintConfigLike {
+  rules?: Record<string, unknown>;
+  linterOptions?: Record<string, unknown>;
+}
+
+export interface ProjectedConsumerCoreConfig {
+  files: string[];
+  rules?: Record<string, unknown>;
+  linterOptions?: Record<string, unknown>;
+}
+
+export function projectConsumerCoreConfig(
+  config: ConsumerEslintConfigLike | undefined,
+  file: string,
+): ProjectedConsumerCoreConfig | undefined;

package/doctor/eslint-diagnostics.mjs

@@ -0,0 +1,24 @@
+export function isForeignRuleDefinitionDiagnostic(item) {
+  return (
+    typeof item.ruleId === 'string' &&
+    !item.ruleId.startsWith('kerfjs/') &&
+    item.message === `Definition for rule '${item.ruleId}' was not found.`
+  );
+}
+
+export function projectConsumerCoreConfig(config, file) {
+  const rules = Object.fromEntries(
+    Object.entries(config?.rules ?? {}).filter(
+      ([ruleId]) => !ruleId.includes('/'),
+    ),
+  );
+  const linterOptions = config?.linterOptions
+    ? { ...config.linterOptions }
+    : undefined;
+  if (Object.keys(rules).length === 0 && !linterOptions) return undefined;
+  return {
+    files: [file],
+    ...(Object.keys(rules).length > 0 ? { rules } : {}),
+    ...(linterOptions ? { linterOptions } : {}),
+  };
+}

package/doctor/index.d.mts

@@ -0,0 +1,116 @@
+export type UiDoctorSeverity = 'error' | 'warning' | 'review' | 'info';
+export type UiDoctorStageId =
+  | 'catalog'
+  | 'typescript'
+  | 'eslint'
+  | 'analyzer'
+  | 'browser'
+  | 'doctor'
+  | 'merged';
+export type UiDoctorStageStatus =
+  'ran' | 'cached' | 'skipped' | 'unavailable' | 'failed' | 'cancelled';
+
+export interface UiDoctorSuppression {
+  id: string;
+  rules: string[];
+  target: string;
+  rationale: string;
+}
+
+export interface UiDoctorConfig {
+  $schema?: string;
+  schemaVersion: 1;
+  mode?: 'full' | 'changed';
+  package?: string;
+  stages?: Partial<
+    Record<
+      'catalog' | 'typescript' | 'eslint' | 'analyzer' | 'browser',
+      boolean
+    >
+  >;
+  browser?: {
+    url: string;
+    browsers?: Array<'chromium' | 'firefox' | 'webkit'>;
+    retention?: 'always' | 'on-failure' | 'never';
+    outputDirectory?: string;
+    reportPath?: string;
+  };
+  cache?: boolean;
+  suppressions?: UiDoctorSuppression[];
+}
+
+export interface UiDoctorDiagnostic {
+  id: string;
+  severity: UiDoctorSeverity;
+  stage: UiDoctorStageId | string;
+  message: string;
+  location?: { file: string; line: number; column: number; path?: string };
+  dom?: { context?: string; selector: string };
+  evidence?: unknown;
+  catalogFacts?: unknown;
+  documentation?: string;
+  action?: string;
+  sources?: string[];
+}
+
+export interface UiDoctorReport {
+  schemaVersion: 1;
+  tool: { name: '@kerfjs/ui/doctor'; reportVersion: 1 };
+  mode: 'full' | 'changed';
+  root: '.';
+  package: string;
+  paths: string[];
+  stages: Array<{ id: string; status: UiDoctorStageStatus; detail?: string }>;
+  diagnostics: UiDoctorDiagnostic[];
+  suppressions: Array<
+    UiDoctorDiagnostic & { suppression: { id: string; rationale: string } }
+  >;
+  summary: {
+    errors: number;
+    warnings: number;
+    review: number;
+    suppressed: number;
+  };
+  exitCode: 0 | 1 | 2 | 130;
+  cache: { hit: boolean; key: string };
+}
+
+export const UI_DOCTOR_SCHEMA_VERSION: 1;
+export const UI_DOCTOR_EXIT: Readonly<{
+  clean: 0;
+  findings: 1;
+  configuration: 2;
+  cancelled: 130;
+}>;
+export const UI_DOCTOR_RULES: Readonly<
+  Record<string, { severity: UiDoctorSeverity; title: string }>
+>;
+export function validateUiDoctorConfig(
+  config: unknown,
+  source?: string,
+): UiDoctorDiagnostic[];
+export function readUiDoctorConfig(
+  root: string,
+  path?: string,
+): Promise<{
+  path: string;
+  config: UiDoctorConfig;
+  diagnostics: UiDoctorDiagnostic[];
+}>;
+export function resolveUiDoctorPackage(
+  root: string,
+  selector?: string,
+): Promise<string>;
+export function runUiDoctor(options?: {
+  root?: string;
+  package?: string;
+  mode?: 'full' | 'changed';
+  paths?: string[];
+  config?: UiDoctorConfig;
+  configPath?: string;
+  cache?: boolean;
+  signal?: AbortSignal;
+  browser?: UiDoctorConfig['browser'];
+  eslintConfig?: 'recommended-ui' | 'strict-ui';
+}): Promise<UiDoctorReport>;
+export function formatUiDoctorText(report: UiDoctorReport): string;