@kerfjs/ui 4.4.1 → 4.5.0-beta.1

package/docs/design/templates.md

@@ -0,0 +1,130 @@
+# Design templates — components as self-contained SVGs
+
+`docs/design/templates/` holds **SVG design templates** for `@kerfjs/ui`
+components: a faithful, self-contained picture of each component in its common
+presentation combinations, captured from the real rendered HTML/CSS (production
+tokens and styles, representative sample data). They're for design review,
+documentation, figma/paste hand-off, and any surface that wants an accurate
+component picture without running the app.
+
+## Coverage
+
+Templated components (each with light + dark variants): `PanelHeader`,
+`ToolbarControlGroup`, `Toolbar`, `ToolbarText`, `List`, `ListItem`, `ListHeader`,
+`ListActionRow`, `ValueTable`, `StateBanner`, `EmptyState`, `Skeleton`,
+`SegmentedControl`, `TabBar`/`AppTab`, and `TokenSearchField`.
+
+Deliberately **not** templated (they don't read as a single static component
+picture): `Select` renders a Web Awesome custom element that needs its runtime
+registered, so it has no faithful static capture; `LucideIcon` and
+`DisclosureArrow` are decorative primitives best seen inside the components that
+use them; `ResizableRegion` and the whole-screen layouts (`NavStack`,
+`SplitView`, `Workbench`, `TabScaffold`) and the `Catalog` shell are
+interaction-/viewport-driven screens rather than component cards — the live UX
+catalog and the app-layouts docs cover those.
+
+## Layout
+
+```
+docs/design/templates/
+  panel-header.svg              ← library: every variant, composed (light)
+  panel-header-dark.svg         ← library: dark theme
+  panel-header/
+    icon-summary-actions.svg    ← one self-contained variant (light)
+    icon-summary-actions-dark.svg ← the same variant, dark theme
+    icon-actions.svg
+    icon-actions-dark.svg
+    …
+  toolbar-control-group.svg
+  toolbar-control-group-dark.svg
+  toolbar-control-group/
+    …
+```
+
+- Each **variant** is captured in both themes — `<variant>.svg` (light) and
+  `<variant>-dark.svg` (dark) — a standalone SVG that scales crisply and drops
+  into an `<img>` anywhere. Dark is driven by domotion's `--color-scheme`, which
+  foundation.css's `light-dark()` tokens respond to. Captured with
+  `--text-mode system-font`, so text is emitted as authored `<text>` painted by the
+  viewer's system fonts: real, selectable, and small (no embedded font data). The
+  kerf UI design font stack is system-based, so the picture matches; a viewer
+  without those fonts falls back to its own.
+- The **library** files (`<component>.svg` light, `<component>-dark.svg` dark) lay
+  the variants out with captions. The generator writes a temporary HTML page whose
+  `<img>` elements reference the individual variant SVGs, then captures that page
+  with domotion and `--flatten-nested-svg`. The final library is self-contained,
+  contains positioned groups rather than nested `<svg>` elements, and remains
+  reliable in design tools such as Sketch. The individual variant files stay
+  independently reusable.
+
+## Building
+
+```sh
+npm run design-templates:build
+```
+
+This renders each component's real `SafeHtml` (with its CSS subpaths + `foundation.css`
+tokens and representative sample data) into a standalone page and captures it with
+[`domotion-svg`](https://github.com/brianwestphal/domotion)'s `domotion capture`.
+The capture command uses `--flatten-nested-svg`, which converts safely flattenable
+inline SVGs (including component icons) to groups so design tools such as Sketch do
+not have to interpret nested `<svg>` elements.
+`domotion` must be reachable: it resolves `DOMOTION_BIN`, then a local
+`node_modules/.bin/domotion`, then a sibling `../domotion` checkout.
+
+**Keep the templates current as components change.** The variants live in the
+`COMPONENTS` manifest in `scripts/build-design-templates.mjs` — when a component
+gains or changes a presentation combination (e.g. a new `PanelHeader` slot), add
+or adjust its variant there and re-run the build. Cover the common cases: if a
+component can render with or without an icon, include both.
+
+`npm run check:design-templates` (part of `npm run check`) is an offline gate
+that verifies every component + variant in the manifest has its committed output —
+a light and dark SVG per variant plus the two per-component library files — and
+that no stray template files linger for a removed component. It also rejects any
+variant or library capture that still contains nested `<svg>` elements, guarding
+the Sketch compatibility contract. It does **not**
+re-render (that needs domotion + a browser), so it catches a manifest entry whose
+templates were never generated or a half-regenerated set.
+
+Deeper **visual drift** — a component changed but its template was not regenerated —
+is caught by `npm run check:design-templates:drift`, a CI-only gate (it runs in a
+dedicated macOS browser job, **not** in the offline `npm run check`). The committed
+templates use system-font text, whose layout metrics differ by operating system, so
+macOS is the canonical exact-render environment for both generation and comparison.
+The capture fixture also pins its monospace token to `Courier New`; otherwise
+`ui-monospace` resolves to different fonts on developer and hosted macOS machines.
+The gate regenerates every template into a throwaway directory and fails if any
+regenerated SVG differs from the committed one, after normalizing the bits that
+legitimately vary between runs (XML comments and the auto-minted element ids / font
+names). If it fails, run `npm run design-templates:build` on macOS and commit the
+updated SVGs.
+
+## Templating your own components
+
+Apps that build on `@kerfjs/ui` can produce the same design templates for their
+own application-level components. Copy `scripts/build-design-templates.mjs` as a
+starting point and:
+
+1. Import your component and render it to a `SafeHtml` string with realistic
+   sample data (pass icon/action slots as `SafeHtml`, e.g. `LucideIcon({ … })` or
+   `raw('<button …>')` — never plain strings, which kerf escapes).
+2. List the component's CSS (its `@kerfjs/ui` subpaths plus `foundation.css` for
+   tokens and `layout.css`), and any of your own component CSS.
+3. Enumerate the presentation combinations in the per-component manifest.
+4. Capture each variant with `domotion capture <page.html> --selector <css>
+--text-mode system-font --flatten-nested-svg -o <variant>.svg`, once per theme with
+   `--color-scheme light` / `--color-scheme dark` (if your components theme with
+   `light-dark()`).
+5. Build a light and dark HTML library page that references the generated variants
+   with `<img src="./component/variant.svg">`, and capture each page with the same
+   domotion options, including `--flatten-nested-svg`. Let domotion own embedding,
+   id isolation, and flattening instead of hand-assembling SVG markup.
+
+Maintaining these next to the components — and reviewing the captured SVGs on
+every component change — keeps the design source of truth honest.
+
+ListItem templates retain the shared 18px leading icon and 44px row target;
+regenerate both themes and library sheets when that geometry changes. The browser
+pane/sidebar geometry checks cover the resulting 43px icon-label offset from the
+section edge (17px content inset + 18px icon + 8px gap).

package/docs/design-philosophy.md

@@ -18,12 +18,63 @@ A reference image defines hierarchy, relationships, and intended feel. It does n
 
 ### Continuity is correctness
 
-Unrelated updates must not close controls, move focus, reset a draft, replace a selection, or jump scroll. Give every durable and transient state an explicit owner. Preserve DOM identity when meaning has not changed. Distinguish blocking foreground work from background synchronization.
+Unrelated updates must not close controls, move focus, reset a draft, replace a selection, or jump scroll. Give every durable and transient state an explicit owner. The default owner is the application: domain data and persisted layout preferences — a navigation stack, a selection, a tab order, a pane size, a `collapsed`/`expanded` disclosure flag — are the app's signals, which it reads to render. A `wire…` helper owns only the _ephemeral mechanics_ around that state (a push/pop animation, overflow autoscroll, a live resize preview) and reports committed changes through callbacks. A helper takes over a piece of transient state itself only when hand-rolling that behavior is substantial and error-prone enough to cause real, inconsistent variation across apps — `wireTokenSearchFields`'s collapsible reveal/focus/Escape/blur-collapse is the bar; a one-line boolean toggle is not. Preserve DOM identity when meaning has not changed. Distinguish blocking foreground work from background synchronization.
 
 ### Hierarchy precedes decoration
 
 Establish one reading order and one dominant action per decision point. Group first with alignment, spacing, typography, and shared surfaces. A border, fill, badge, or nested card must communicate a real distinction.
 
+### Reach for the primitive, not for CSS
+
+The package is designed to look right _unstyled_. A screen built from the
+primitives, their props, and the semantic tokens should already read well, so
+custom CSS is the exception. Before adding any `padding`, `margin`, `width`,
+`height`, `border`, `background`, wrapper card, or decoration, check whether the
+component, the pane, or the content-item already owns it — it almost always does,
+and adding more usually **double-insets** or fights the component (the most common
+mistake). Trust component defaults: render a control at its natural size and color
+and fix the surrounding layout rather than overriding the control. Legitimate
+custom CSS is limited to genuinely new structure, and even then may only join a
+component's documented `publicClasses` or override documented `--kui-*` tokens at a
+real composition boundary — never size, space, or re-skin a primitive by hand, and
+never build a heading, toolbar, card, or pane geometry that a primitive provides.
+
+### Panes share one child-owned geometry
+
+Sidebars, main areas, inspectors, and dialogs use the same unpadded pane. Their
+children own margin, border, background, padding, and radius, so a transparent
+surface occupies exactly the same geometry as a visible one. Major content
+groups use 24px vertical separation; the inside of an item and the gap between
+toolbar groups use 8px. Rows and actions keep 44px targets.
+
+Use the package composition so the geometry has one owner:
+
+```tsx
+<Pane element="aside" contentElement="nav" label="Workspace" contentLabel="Workspace pages">
+    <section>
+      <ListHeader label="Workspace" />
+      <ListItem action="open" label="Inbox" icon={inboxIcon} />
+      <ListItem action="open" label="Drafts" />
+    </section>
+    <div class="kui-content-item">Panel contents</div>
+</Pane>
+```
+
+Do not pad the pane and then pad every wrapper. That duplicates the geometry
+and makes transparent borders behave differently from visible ones:
+
+```tsx
+<aside class="pane padded">
+  <section class="padded">
+    <ListHeader label="Workspace" />
+    <div class="panel padded-again">Panel contents</div>
+  </section>
+</aside>
+```
+
+Change the shared item tokens at a real composition boundary when a product
+needs different geometry; do not compensate with one-off negative margins.
+
 ### Prefer directness
 
 Use the shortest understandable, recoverable interaction. Avoid modes, dialogs, confirmations, and explicit saves when direct manipulation can safely express the same result. Low ceremony still requires a discoverable affordance, visible focus, and honest feedback.
@@ -42,6 +93,13 @@ foregrounds compatible with Hot Sheet 2 and Web Awesome. Consumers may replace
 the global palette, one semantic role, or one component instance through
 documented custom properties without rewriting component CSS.
 
+Spacing is likewise a finite, semantic scale, not a free measurement. Five
+canonical steps — 0, 4, 8, 16, and 24px, each a `--kui-space-*` token — map to a
+single relationship apiece, chosen by how connected two elements are: no
+separation, very minor air, standard within a group, between homogeneous groups,
+and major between heterogeneous groups. Off-scale values (12px, 32px) are
+deliberate exceptions. See [`layout.md`](layout.md) "Spacing scale".
+
 ### Responsive design reprioritizes
 
 Protect primary content, readable type, recognizable icons, and usable targets. Relocate secondary information before compressing it below a usable scale. Keep one clear scroll owner per region and test narrow, wide, zoomed, and intermediate layouts.

package/docs/device-class.md

@@ -0,0 +1,54 @@
+# Device class
+
+`@kerfjs/ui/device-class` reports the current viewport as a reactive **device
+class** — a size bucket × orientation × viewport-segment count — so a layout can
+pick its presentation from one signal instead of hand-wiring `matchMedia`. It is
+the foundation the app/dialog layouts build on (see
+[`../../docs/23-app-layouts.md`](../../docs/23-app-layouts.md)).
+
+```ts
+import { deviceClass } from "@kerfjs/ui/device-class";
+
+const device = deviceClass(); // ReadonlySignal<DeviceClass>
+
+effect(() => {
+  if (device.value.compact) showStack();
+  else showSplit();
+});
+```
+
+## `DeviceClass`
+
+| Field                           | Meaning                                                                    |
+| ------------------------------- | -------------------------------------------------------------------------- |
+| `size`                          | `xs-mobile` \| `mobile` \| `tablet` \| `desktop` \| `xl-desktop`           |
+| `orientation`                   | `portrait` \| `landscape`                                                  |
+| `segments` / `verticalSegments` | viewport segment counts (foldables / dual-screen); `1` on ordinary devices |
+| `handset`                       | `xs-mobile` or `mobile`                                                    |
+| `compact`                       | "one pane at a time" — a handset or a portrait tablet                      |
+| `atLeast(size)`                 | true when the current size is `size` or larger                             |
+
+Reading `device.value` inside an `effect`/`computed` re-runs when the viewport
+crosses a breakpoint, rotates, or changes its segment count. One shared viewport
+source backs every reader.
+
+## Breakpoints
+
+Default minimum widths (px): `mobile` 360, `tablet` 720, `desktop` 1024,
+`xl-desktop` 1440. Override per reader:
+
+```ts
+const device = deviceClass({ breakpoints: { tablet: 900 } });
+```
+
+The same numbers are mirrored as CSS custom properties in the foundation
+(`--kui-bp-mobile`, `--kui-bp-tablet`, `--kui-bp-desktop`, `--kui-bp-xl-desktop`)
+so CSS media queries and the JS signal read one source. `classifyViewport(width,
+orientation, segments?, verticalSegments?, breakpoints?)` is exported as the
+pure, DOM-free bucketing core.
+
+## Server rendering
+
+Without a DOM, `deviceClass()` resolves to an SSR default (1024×768, landscape,
+one segment) and hydrates to the real class on the client. Override the assumed
+viewport with `deviceClass({ ssr: { width, height } })`.

package/docs/examples/application-ui-profile.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "../../ai/application-ui-profile.schema.json",
+  "schemaVersion": 1,
+  "scope": "workspace",
+  "catalogs": [
+    {
+      "package": "@kerfjs/ui",
+      "selection": {
+        "path": "../../ai/component-catalog.json",
+        "schemaVersion": 1
+      },
+      "composition": {
+        "path": "../../ai/component-catalog-v2.json",
+        "schemaVersion": 2
+      }
+    },
+    {
+      "package": "@acme/ui",
+      "composition": {
+        "path": "./component-catalog-extension-v2.json",
+        "schemaVersion": 2
+      }
+    }
+  ],
+  "preferences": {
+    "application-shell": {
+      "preferred": "@kerfjs/ui:recipe-app-shell",
+      "rationale": "The workspace uses the standard resizable three-region shell."
+    },
+    "record-inspector": {
+      "preferred": "@acme/ui:inspector",
+      "rationale": "The application-owned inspector maps record policy onto Kerf panel primitives."
+    }
+  },
+  "theme": {
+    "colorScheme": "light",
+    "allowedColorSchemes": ["light", "dark"],
+    "density": "standard",
+    "allowedDensities": ["standard"]
+  },
+  "tokens": {
+    "--kui-color-brand-fill-normal": "oklch(0.62 0.16 255)"
+  },
+  "layout": {
+    "shell": "@kerfjs/ui:recipe-app-shell",
+    "pane": "@kerfjs/ui:pane",
+    "responsiveStrategy": "device-class",
+    "compactNavigation": "nav-stack",
+    "scrollOwnership": "one-per-pane",
+    "spacingScale": "kerf-five-step"
+  },
+  "exceptions": [
+    {
+      "id": "legacy-report-grid",
+      "rules": ["KUI-C101"],
+      "target": "src/features/legacy-report/report-grid.tsx",
+      "rationale": "The embedded report engine owns this isolated toolbar-compatible control row."
+    }
+  ]
+}

package/docs/examples/command-palette-adapter.tsx

@@ -0,0 +1,120 @@
+import '@kerfjs/ui/layout.css';
+
+import { delegate, mount, signal } from 'kerfjs';
+import { delegateActions } from 'kerfjs/actions';
+
+export interface AppCommand {
+  id: string;
+  label: string;
+  keywords?: string[];
+}
+
+export interface CommandPaletteCallbacks {
+  onClose(): void;
+  onRun(command: AppCommand): void;
+}
+
+/**
+ * Application-local example, not an @kerfjs/ui export. The application owns
+ * ranking, history, shortcuts, focus policy, command availability, and copy.
+ */
+export function mountCommandPaletteAdapter(
+  root: HTMLElement,
+  commands: AppCommand[],
+  { onClose, onRun }: CommandPaletteCallbacks,
+): () => void {
+  const query = signal('');
+  const render = () => {
+    const needle = query.value.trim().toLocaleLowerCase();
+    const matches = commands.filter(
+      (command) =>
+        !needle ||
+        [command.label, ...(command.keywords ?? [])].some((value) =>
+          value.toLocaleLowerCase().includes(needle),
+        ),
+    );
+    return (
+      <section
+        class="app-command-palette kui-content"
+        aria-label="Command palette"
+      >
+        <div class="kui-content-item">
+          <label for="app-command-query">Search commands</label>
+          <input
+            id="app-command-query"
+            type="search"
+            value={query.value}
+            autocomplete="off"
+            data-command-query
+          />
+        </div>
+        <p class="kui-content-item" aria-live="polite">
+          {matches.length} matching commands
+        </p>
+        <ul class="kui-content-item" aria-label="Matching commands">
+          {matches.map((command) => (
+            <li>
+              <button
+                type="button"
+                data-action="run-command"
+                data-command-id={command.id}
+              >
+                {command.label}
+              </button>
+            </li>
+          ))}
+        </ul>
+        <footer
+          class="kui-control-cluster kui-content-item"
+          aria-label="Command palette actions"
+        >
+          <button type="button" data-action="clear-query">
+            Clear search
+          </button>
+          <button type="button" data-action="close-palette">
+            Close
+          </button>
+        </footer>
+      </section>
+    );
+  };
+
+  const stopMount = mount(root, render);
+  const stopActions = delegateActions(root, 'click', {
+    'run-command': (_event, element) => {
+      const id = (element as HTMLElement).dataset.commandId;
+      const command = commands.find((candidate) => candidate.id === id);
+      if (command) onRun(command);
+    },
+    'clear-query': () => {
+      query.value = '';
+      root.querySelector<HTMLInputElement>('[data-command-query]')?.focus();
+    },
+    'close-palette': onClose,
+  });
+  const stopInput = delegate<HTMLInputElement>(
+    root,
+    'input',
+    '[data-command-query]',
+    (_event, input) => {
+      query.value = input.value;
+    },
+  );
+  const stopEscape = delegate(
+    root,
+    'keydown',
+    '[data-command-query]',
+    (event) => {
+      if ((event as KeyboardEvent).key === 'Escape') onClose();
+    },
+  );
+  let disposed = false;
+  return () => {
+    if (disposed) return;
+    disposed = true;
+    stopEscape();
+    stopInput();
+    stopActions();
+    stopMount();
+  };
+}

package/docs/examples/component-catalog-extension-v2.json

@@ -0,0 +1,81 @@
+{
+  "$schema": "../../ai/component-catalog-extension-v2.schema.json",
+  "schemaVersion": 2,
+  "package": "@acme/ui",
+  "compatibility": {
+    "v1Catalog": "./component-catalog-extension.json",
+    "identity": "package:id"
+  },
+  "entries": [
+    {
+      "key": "@acme/ui:inspector",
+      "package": "@acme/ui",
+      "id": "inspector",
+      "name": "Inspector",
+      "kind": "composition",
+      "source": "application",
+      "parents": { "mode": "listed", "entries": ["@kerfjs/ui:layout"] },
+      "contexts": ["record-detail"],
+      "zones": [
+        {
+          "id": "header",
+          "accepts": ["@kerfjs/ui:panel-header"],
+          "cardinality": { "min": 1, "max": 1 },
+          "exclusiveWith": []
+        },
+        {
+          "id": "facts",
+          "accepts": ["@kerfjs/ui:value-table"],
+          "cardinality": { "min": 1, "max": 1 },
+          "exclusiveWith": []
+        }
+      ],
+      "children": {
+        "mode": "listed",
+        "concepts": ["@kerfjs/ui:panel-header", "@kerfjs/ui:value-table"],
+        "requiredConcepts": [
+          "@kerfjs/ui:panel-header",
+          "@kerfjs/ui:value-table"
+        ]
+      },
+      "state": [
+        { "id": "selected-record", "owner": "application", "required": true }
+      ],
+      "wiring": { "required": false, "helpers": [], "obligations": [] },
+      "responsive": {
+        "owner": "application",
+        "behaviors": [
+          "May move between inline-end pane and dialog at the application breakpoint."
+        ]
+      },
+      "layout": {
+        "roles": ["inspector"],
+        "geometry": {
+          "margin": "parent",
+          "border": "child",
+          "padding": "child"
+        }
+      },
+      "accessibility": {
+        "obligations": ["The header names the inspector region."]
+      },
+      "boundaries": {
+        "rootClass": "acme-inspector",
+        "publicClasses": ["acme-inspector"],
+        "publicTokens": []
+      },
+      "diagnostics": [
+        {
+          "id": "KUI-C901",
+          "severity": "error",
+          "when": "the header or facts zone is absent",
+          "message": "Inspector requires exactly one header and one facts region."
+        }
+      ],
+      "provenance": {
+        "selection": "docs/inspector.md",
+        "composition": "docs/inspector.md#composition-contract"
+      }
+    }
+  ]
+}

package/docs/examples/component-catalog-extension.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "../../ai/component-catalog-extension.schema.json",
+  "schemaVersion": 1,
+  "package": "@acme/ui",
+  "description": "Application-owned components composed with Kerf UI.",
+  "entries": [
+    {
+      "id": "acme-filter-chip",
+      "name": "FilterChip",
+      "kind": "component",
+      "purpose": "A removable application filter displayed inside a token-search workflow.",
+      "useWhen": [
+        "A saved application filter needs a compact visible label and remove action."
+      ],
+      "avoidWhen": [
+        "The value belongs to TokenSearchField's own controlled token collection."
+      ],
+      "publicClasses": ["acme-filter-chip"],
+      "publicTokens": ["--acme-filter-chip-accent"],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "self"
+      },
+      "documentation": "docs/filter-chip.md"
+    },
+    {
+      "id": "acme-inspector",
+      "name": "Inspector",
+      "kind": "composition",
+      "purpose": "An application inspector composed from Kerf panel, content, and value primitives.",
+      "useWhen": ["A selected record needs a titled fact-and-action region."],
+      "avoidWhen": ["A ValueTable alone expresses the complete interaction."],
+      "geometry": {
+        "margin": "parent",
+        "border": "child",
+        "padding": "child",
+        "notes": [
+          "The embedding pane positions the inspector; PanelHeader, ValueTable, and action groups retain their own geometry."
+        ]
+      },
+      "documentation": "docs/inspector.md"
+    }
+  ]
+}