@kerfjs/ui 5.0.0-beta.68 → 5.0.0-beta.69

package/docs/component-contract.md

@@ -92,6 +92,16 @@ the `data-*` attributes it actually writes. First-party entries always carry
 the list, empty when their helpers write none; it is optional in extension
 catalogs.
 
+An extension catalog may add `wiring.sources` entries with `export` and
+`source` for each application-owned helper. The source path is relative to its
+package root; `ui-wiring` resolves helper imports through this file, including
+relative re-export barrels. Every named export must also appear in
+`wiring.helpers`.
+
+The selection catalog's `wiringProviders` lists public helpers that install
+other wiring helpers. The `ui-wiring` rule accepts a provider call for each
+helper it declares; `wireCatalog` provides `wireScrollDividers`.
+
 The generator starts with permissive defaults. An `any` mode records that the
 catalog has no defensible prohibition; it does not claim every composition is
 recommended. Objective rules live in
@@ -252,6 +262,8 @@ claim Kerf delivery paths for them.
 Extension entries may add `uses` for direct composition dependencies and
 repository-relative `source` and `demoSource` files. Resolve each dependency
 against the combined Kerf and consumer catalogs; do not duplicate a Kerf id.
+For Doctor's opt-in component ownership mode, add `styleSources` with the CSS
+paths each entry owns, relative to the consumer package root.
 
 - Components own semantic markup, stable anatomy, documented variants, ARIA projection, and package CSS hooks.
 - Applications own signals/stores, product copy, domain-state mapping, persistence, routing, permissions, and transport.
@@ -506,20 +518,49 @@ a plain `<button>` — the group styles `> button` fully, and it keeps the group
 free of a Web Awesome dependency and shadow DOM. Use `ToolbarActionLink` when
 the action must retain native anchor navigation; the group owns its geometry,
 hover, and focus treatment. Set `overflow="scroll"` when a row of controls must
-stay inside the available toolbar width. Set `visibility="compact-only"` for a
+stay inside the available toolbar width. A disabled native button keeps the
+group's geometry, dims to half opacity, uses the `not-allowed` cursor, and
+paints neither its own nor a lone group's hover surface.
+Set `visibility="compact-only"` for a
 group that replaces wider toolbar controls below the Toolbar's compact container
-breakpoint; do not hide the group with an application class. Reach for
-`wa-button` only when you need
-a Web Awesome feature; a popup menu is a `PopupMenu`, which renders its own
-trigger. Nothing wraps inside a group: an icon sits beside its label on one
-row, and a group's controls never break onto a second line — the group sizes
-to its content and the enclosing `Toolbar`'s responsive policy relocates whole
-groups. For a compact mixed-content group, set `nestedDropdown`; a
+breakpoint; do not hide the group with an application class.
+Use `sizing="grow"` on an expanded search group in a wrapping zone: it grows from
+`growBasis` (19rem by default) into available row space, then takes a whole
+row at 480px container width or less. The collapsed search stays icon-sized.
+Use `sizing="fill"` for a group, including a non-search segmented control,
+that spans its wrapping row. Set `visibility="hide-collapsed-tiny"` on a
+collapsible group to omit its closed icon at 224px or less; expanded content
+remains visible. These sizes use the enclosing Toolbar's container width.
+In a stacked Toolbar, set `placement="end"` on a collapsed group that should
+sit at the trailing edge of its flex row. An expanded search with
+`sizing="fill"` takes a whole row and enters from the row above; reduced-motion
+preferences remove that entrance animation.
+Use `visibility="yield-to-expanded-sibling"` on trailing groups that should
+leave a 480px-or-narrower toolbar while a sibling trailing group is expanded.
+They return when it collapses or the toolbar widens; leading and center zones
+remain visible.
+Reach for `wa-button` only when you need a Web Awesome feature; a popup menu is a `PopupMenu`, which renders its own
+trigger. By default a group stays on one row: each icon sits beside its label,
+and the enclosing `Toolbar`'s responsive policy relocates whole groups. Set
+`overflow="wrap"` only for independent links that should move as whole actions
+to another row within the group; use `overflow="scroll"` for a bounded one-row
+action strip. A wrapping group centers in the toolbar band on one row and
+starts at its top when it grows to multiple rows. For a compact mixed-content
+group, set `nestedDropdown`; a
 text-and-caret trigger grows to its intrinsic width while an icon-only trigger
 can remain square. A compact icon `<button>` is a 32px circle, so a selected
 compact segment never becomes an oval. An icon-only `Select` joins a group as
 one more segment with its siblings' inset, radius, hover, and focus ring; only a
-lone Select grows the group to its icon-and-caret pill. Set `menuInset` to configure the dropdown menu surface
+lone Select grows the group to its icon-and-caret pill.
+
+For a rail view heading, use `Select presentation="title"`: its intrinsic
+36px borderless trigger has a bold large label flush with its leading edge and
+a caret beside that label. Set `focusRingInset` when a NavStack or panel clips
+outside painting; the Select keeps its focus outline 3px inside the trigger
+and drops it while the listbox is open. Both settings belong to Select, not an
+application `::part()` override.
+
+Set `menuInset` to configure the dropdown menu surface
 without application `::part(menu)` CSS; the default `standard` keeps each menu's
 own inset (8px for a raw `wa-dropdown`, the Select listbox's 4px for a
 `PopupMenu`), while `compact` and `list-zero` apply to every nested menu. A
@@ -655,6 +696,8 @@ the only shrinking, horizontally scrolling region; `leading`, `trailing`, and
 trailing action belongs immediately after the final tab and use `end` for a
 separate action pinned to the far edge. Applications own the action content,
 but must not restyle TabBar descendants to recreate that allocation.
+When a leading AppTab is pinned, the leading scroll divider appears at that
+tab's trailing edge while peer tabs scroll beneath it, including in RTL.
 
 CSS, the generated wrappers that make it
 reachable, and the registration module are the package's only declared side
@@ -676,6 +719,12 @@ line of its own and centers in its slot. It is a
 placeholder, not progress: use `LoadingSpinner` for known busy activity, and never
 animate the skeleton.
 
+`LoadingSpinner` accepts the same `size` steps as `LucideIcon`: `xs`, `s`, `m`,
+`l`, `xl` (12/16/20/24/32px at a 16px root) or a positive finite pixel
+number converted to rem. Omit `size` to keep its inherited 1em box. A supplied
+size is exposed as `data-size`; callers configure the spinner through this prop
+instead of sizing its SVG from outside.
+
 A placeholder is loading, not unavailable, so it keeps the `disabled` attribute (its
 controls stay inert and out of the keyboard order) but never shows disabled chrome.
 `skeleton.css`, which every component that renders a skeleton loads, neutralizes generic

package/docs/component-selection.md

@@ -171,7 +171,7 @@ beside a `ContentItem` value, and connect its id to the preview group's
 | Panel, dialog, or page heading — `Toolbar` + `ToolbarText`                                                              | A panel, dialog, or page needs an extra-large title, optional icon, grouped trailing actions, and optional supporting copy.                                                                                                                                                                                                                              | Do not add a private heading wrapper or bespoke layout. The toolbar supplies structure, not modal behavior; use an application overlay or Web Awesome `wa-dialog` for that behavior. In a narrow peripheral rail or drawer, where xlarge would truncate at the panel's minimum size, use the default `ToolbarText` size as pane identity.  | Connect title/supporting-copy ids to the host, group controls, and delegate actions. **For a page or view title set `headingLevel` (usually `1`)** on `ToolbarText`; omit it for a dialog title referenced by `aria-labelledby`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Open state, focus lifecycle, dismissal, controls, ids, copy, and heading level.                                                                          | `@kerfjs/ui/toolbar` + `@kerfjs/ui/toolbar-text`                                          | [Toolbar headings](./accessibility.md#toolbar-headings)                             |
 | Dialog or popup geometry — `DialogSurface`, `PopupSurface`                                                              | Recurring Web Awesome dialogs need standard sizes/presentations/body/footer insets, or dropdown menus need list-compatible inset ownership.                                                                                                                                                                                                              | Do not use these wrappers as generic layout or to replace native dialog/dropdown behavior. Avoid consumer `::part()` overrides and do not stack a dialog body inset around list-owned child geometry.                                                                                                                                      | Wrap one `wa-dialog` or `wa-dropdown`; choose the typed geometry while retaining native labeling, open state, focus, dismissal, and menu semantics. Compose a dialog body as a `List` by default, use `bodyInset="none"` when its children own list geometry, and wrap bare prose in `ListInsetText`.                                                                                                                                                                                                                                                                                                                                                                                                                  | State, focus lifecycle, dismissal, labels, content, and outer placement.                                                                                 | `@kerfjs/ui/surface-scaffold`                                                             | [Surface scaffolds](./surface-scaffold.md)                                          |
 | Key/value facts — `ValueTable`, `ValueTableRow`                                                                         | Read-only labels and values form a semantic definition list, optionally with a leading icon.                                                                                                                                                                                                                                                             | Do not use it for editable form fields or a row/column data grid; use native form or table semantics.                                                                                                                                                                                                                                      | Compose typed `ValueTableRow` entries; pass `icon` when a 24px leading icon adds useful context.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Values, formatting, icon meaning, and empty/loading policy.                                                                                              | `@kerfjs/ui/value-table`                                                                  | [Component ownership](./component-contract.md#ownership-boundaries)                 |
-| Indeterminate activity — `LoadingSpinner`                                                                               | A Kerf surface needs compact, labeled or decorative indeterminate progress.                                                                                                                                                                                                                                                                              | Do not use it for known progress; use Web Awesome `wa-progress-bar` or `wa-progress-ring`. Direct Web Awesome UI may use `wa-spinner`; do not mix spinner systems within one surface.                                                                                                                                                      | None; pass a label when the spinner conveys status.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Loading lifecycle and adjacent status copy.                                                                                                              | `@kerfjs/ui/loading-spinner`                                                              | [Accessibility](./accessibility.md#shared-rules)                                    |
+| Indeterminate activity — `LoadingSpinner`                                                                               | A Kerf surface needs compact, labeled or decorative indeterminate progress.                                                                                                                                                                                                                                                                              | Do not use it for known progress; use Web Awesome `wa-progress-bar` or `wa-progress-ring`. Direct Web Awesome UI may use `wa-spinner`; do not mix spinner systems within one surface.                                                                                                                                                      | Pass a label when the spinner conveys status; use size for a named icon step or positive pixel size.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Loading lifecycle and adjacent status copy.                                                                                                              | `@kerfjs/ui/loading-spinner`                                                              | [Accessibility](./accessibility.md#shared-rules)                                    |
 | Loading placeholder — `Skeleton` + a component's `placeholder` prop                                                     | A value or a whole component is still loading and should hold its space as a subtle, unanimated block, keeping the layout stable — an inspector or detail view rendering its real chrome with per-record values absent.                                                                                                                                  | Do not use it for known progress (use `LoadingSpinner`), do not animate it, and do not hand-rebuild a component's empty state — set `placeholder` on the component instead. Prefer it over `wa-skeleton`, which the pure-Kerf primitives avoid to stay Web-Awesome-free.                                                                   | Set `placeholder` on a value-bearing component (`Select`, `ListHeader`, `ListItem`, `ValueTableRow`, `SegmentedControl`, `StateBanner`, `AppTab`, `ToolbarText`, `ListActionRow`) to render skeletons in its value slots with interactivity disabled; use the standalone `Skeleton` for a custom slot.                                                                                                                                                                                                                                                                                                                                                                                                                 | Loading lifecycle, which slots are unknown, and announcing the loading region.                                                                           | `@kerfjs/ui/skeleton`                                                                     | [Accessibility](./accessibility.md#shared-rules)                                    |
 | Command menu — `PopupMenu`                                                                                              | A short list of commands sits behind one trigger, such as a toolbar sort or More menu, optionally grouped under headings and dividers with item icons.                                                                                                                                                                                                   | Do not use it to choose a persistent value; use `Select`. Do not hand-write `wa-dropdown`/`wa-dropdown-item` markup for an action menu.                                                                                                                                                                                                    | Import `@kerfjs/ui/popup-menu/register` once. Place it in a `single` `ToolbarControlGroup` with `nestedDropdown` and a `menuInset`, or wrap it in `PopupSurface` outside a toolbar. Handle item `action`s by delegation.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Commands, enabled state, and reactions to opening or closing.                                                                                            | `@kerfjs/ui/popup-menu`                                                                   | [Toolbar composition](#toolbar-composition)                                         |
 | Value selection — `Select`                                                                                              | A controlled form, toolbar, or compact navigation value comes from a moderate or long choice list, possibly grouped, icon-bearing, icon-only when closed, or truncating. Set `multiple` with an array `value` when the person may choose any number of them; add `selectedPresentation="icon-only"` and a fixed `triggerIcon` for a toolbar filter menu. | Do not use it for commands; use `PopupMenu`. Do not use it for a small visible choice set; use `SegmentedControl`. Prefer it over direct `wa-select`, `wa-option`, or value-like `wa-dropdown`/`wa-dropdown-item` composition.                                                                                                             | Import `@kerfjs/ui/select/register` once for registration and current-request animation ownership; listen for standard input/change events. Do not add consumer popup timing or positioning repairs. Use typed presentation props rather than consumer `::part()` overrides; let the parent own placement.                                                                                                                                                                                                                                                                                                                                                                                                             | Controlled value, validation, choices, domain mapping, and outer placement.                                                                              | `@kerfjs/ui/select`                                                                       | [Web Awesome integration](../README.md#web-awesome-theme)                           |
@@ -268,11 +268,16 @@ instead of the default ellipsis. A `TabBar` owns its
 scrolling strip; its public `--kui-tab-bar-strip-*` tokens configure strip
 height, spacing, border, radius, background, and scroll inset without styling
 its internal classes. `--kui-tab-bar-trailing-flex` controls the trailing zone.
+For a distinct application action, use `end` to pin it at the far edge; use
+`trailingPlacement="adjacent"` to keep a tab-local `trailing` action beside the
+strip. Each zone accepts one `ToolbarControlGroup` or one standalone
+`wa-button` for a primary action with its own chrome. Avoid wrappers and
+application flex overrides.
 Set `pinned` on the first `AppTab` when that tab must remain visible as peers
 scroll. It stays inside the tablist and keyboard order. Set the public
 `--kui-app-tab-pinned-background` token if the surrounding surface differs from
 the default; the pinned tab must cover peers as they scroll beneath it. Its
-background also covers the strip's inline padding so scrolled labels cannot
+background also covers the strip's inline padding and border so scrolled labels cannot
 paint beside the pinned edge, including in right-to-left strips. Call
 `wireTabBars` for keyboard selection and reorder behavior and its WebKit RTL
 scroll correction.
@@ -345,6 +350,11 @@ search content before saving.
 The form-field corners and required marker use the same Web Awesome
 form-control radius, marker color, and offset tokens as a neighboring
 `wa-input`.
+The four public color tokens (`--kui-token-search-background`,
+`--kui-token-search-border`, `--kui-token-search-token-background`, and
+`--kui-token-search-token-foreground`) inherit from an app ancestor or the
+field's root. `className` marks that root, including the outer wrapper in
+`form-field` presentation, so one app class can configure either form.
 `TokenSearchRule.suggest(input, state)` receives the unfinished value and current committed tokens, so a rule can omit values already selected. Existing one-argument suggestion callbacks continue to work.
 For a sibling date picker or other app helper, call `model.commit(value)` while a `name:` prefix is active. It parses and commits that value for the active rule even when it is absent from suggestions, replacing the unfinished prefix text. Invalid values and calls without an active prefix leave the query unchanged; `choose(value)` remains restricted to suggested tokens.
 To apply a saved search or restore a query programmatically, call `model.replace({ query, tokens })`. It publishes parsed state and rebuilds the DOM-owned editor text even when no chip changed. For a field without a model, change the field's `revision` prop when setting `query` yourself.
@@ -356,6 +366,9 @@ passive content such as a shortcut hint.
 Set `fill` on a collapsible `TokenSearchField` in a stretched Toolbar center to
 use the available width when expanded; the field and its search group retain
 their compact widths when collapsed.
+When the expanded toolbar field has focus, its inset surface uses
+`--kui-token-search-background` or the default surface color if that token is
+unset.
 
 ## Toolbar composition
 
@@ -377,10 +390,13 @@ copy below as app-owned content. Size the title to its track: a narrow
 peripheral rail or drawer (a navigator, inspector, or console beside a work
 area that carries the extra-large title, often with its own close control in
 the header) labels itself with the default size, because extra-large truncates
-there — "Inspector" becomes "Ins…" in a 160px rail. Nothing wraps inside a
-`ToolbarControlGroup`: an icon sits beside its label on one row and the group
-sizes to its content, so a row that does not fit relocates whole groups
-through the toolbar's `responsive` policy rather than breaking a group. A
+there — "Inspector" becomes "Ins…" in a 160px rail. By default, nothing wraps
+inside a `ToolbarControlGroup`: an icon sits beside its label on one row and the
+group sizes to its content, so a row that does not fit relocates whole groups
+through the toolbar's `responsive` policy. For independent action links that
+must all remain visible, set `overflow="wrap"`: whole links move to another
+row inside the group without breaking an icon from its label. Use
+`overflow="scroll"` when a single-row action strip is intentional. A
 toolbar draws no divider by default: pinned over or under scrolling content,
 it gets one from the scroll state instead — the `Pane` it heads draws the line
 only while content is scrolled beneath it, once `wireScrollDividers` is wired

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

@@ -19,6 +19,7 @@
       "publicTokens": ["--acme-filter-chip-accent"],
       "uses": ["chip"],
       "source": "src/filter-chip.tsx",
+      "styleSources": ["src/filter-chip.css"],
       "demoSource": "ux-demo/demos/filter-chip.tsx",
       "geometry": {
         "margin": "none",

package/docs/layout.md

@@ -111,6 +111,12 @@ scrolls under its pinned header; with a header it draws the line under that
 header itself, so the stack's chrome never doubles it. It follows re-renders: panes that appear later are paired, and an
 attribute a morph drops returns before paint.
 
+Multiple calls in one document share one attribute writer, including calls on
+overlapping roots. Each call contributes its own root and optional named
+targets; its disposer removes only that registration. When the last disposer
+runs, the writer removes the attributes it owns. An app that calls `wireCatalog`
+for a root already has scroll dividers there and does not need another call.
+
 The wiring only reports state; every component draws its own line. It writes
 `data-scroll-overflow` (the edges with content hidden beyond them, in canonical
 `t`/`r`/`b`/`l` order) on each scroller and `data-scroll-divider` (the sides to

package/docs/ui-analyzer.md

@@ -144,6 +144,10 @@ which element a selector styles.
   imported component's JSX (`<Toolbar className="header" />`) is the subject
   of a rule in a stylesheet that file imports, so the application restyles the
   component through it. The evidence names the stylesheet, line, and selector.
+  For cataloged application components, the import may be direct and relative
+  or use an exact or wildcard TypeScript `paths` alias from the nearest
+  `tsconfig.json` inside the analyzed root (including inherited options).
+  Unresolved aliases remain unclassified; the analyzer does not execute code.
 
 Every message names the configuration to use (the component's typed props,
 public tokens, and variants from its catalog entry) and ends with the same
@@ -188,6 +192,14 @@ findings. `eslint-plugin-kerfjs`'s `ui-component-ownership` rule reports
 `KUI-L020` and `KUI-L021` in JavaScript and TypeScript (style strings, style
 objects, and `style.setProperty()`), where this analyzer reads only CSS.
 
+Pass `ownership: 'component'` to `analyzeUiProject` to enforce the boundary
+between components in one package. In that mode each catalog entry owns only
+its declared `styleSources` for CSS and its selection catalog `source` module
+for JSX; sibling files are foreign. Paths are relative to that entry's package
+root. Declare `styleSources` on the selection catalog extension entry or
+composition entry. Entries without those paths own no files in component mode,
+so add them before adopting it.
+
 ### Retired: `KUI-L005` (forced component dimension)
 
 `KUI-L005` used to report, as a review finding, any `width`/`height`/`min-*`/

package/docs/ui-doctor.md

@@ -7,6 +7,7 @@ npx kerf-ui-doctor --full
 npx kerf-ui-doctor --changed
 npx kerf-ui-doctor --package @acme/admin --changed
 npx kerf-ui-doctor --full --browser-url http://127.0.0.1:4173
+npx kerf-ui-doctor --full --fail-on warning
 ```
 
 The default terminal output is short and repair-oriented. `--format json` emits the schema-version-1 report; `--output report.json` writes the same representation. The package exports its contract from `@kerfjs/ui/doctor`, its configuration schema from `@kerfjs/ui/doctor/config.schema.json`, and its report schema from `@kerfjs/ui/doctor/report.schema.json`.
@@ -39,6 +40,15 @@ root (`KUI-L022`); the ESLint stage's `ui-component-ownership` rule reports
 component's configuration, and its message routes a need with no prop to a
 component-gap report instead of an override (see
 [the analyzer rule](./ui-analyzer.md#component-ownership-kui-l019kui-l022)).
+The analyzer resolves a cataloged application component imported through an
+exact or wildcard TypeScript `paths` alias from the nearest consumer tsconfig,
+so the same root hook-class check applies in those files.
+Set `"ownership": "component"` in `.kerf-ui-doctor.json` to enforce the same
+boundary between a consumer package's own cataloged components. The default is
+`"package"`. Each local catalog entry then owns only its declared
+`styleSources` (relative to its package root) and its selection catalog
+`source` module. The component mode reports sibling CSS and hook-class
+restyles while still allowing a component's own stylesheet and module.
 
 The browser evaluator is different: it runs the application and is disabled by default. It only runs when configuration supplies `browser.url` or the command receives `--browser-url`. Start and authorize the target application separately.
 
@@ -66,8 +76,10 @@ Place `.kerf-ui-doctor.json` at the workspace root:
   "$schema": "./node_modules/@kerfjs/ui/doctor/config.schema.json",
   "schemaVersion": 1,
   "mode": "full",
+  "ownership": "component",
   "stages": { "browser": false },
   "cache": true,
+  "failOn": "warning",
   "suppressions": [
     {
       "id": "legacy-toolbar",
@@ -91,14 +103,14 @@ Reports replace the workspace's absolute path with `<repo-root>` and express in-
 
 Every diagnostic has a stable `id`, `severity`, `stage`, message, and—when applicable—an exact source location with JSON path or DOM context/selector. Analyzer evidence, catalog facts, documentation links, and safe next actions are preserved when the source tool provides them. Identical findings merge with their source stages; same identifiers with conflicting severities remain separate and add `KUI-D003`.
 
-Exit codes are deterministic:
+Exit codes are deterministic. `failOn` defaults to `error`; `--fail-on error|review|warning` overrides the config for a run. `review` fails on errors or review findings; `warning` also fails on warnings. Suppressed diagnostics never count. The effective threshold is part of the cache key.
 
-- `0`: no active error diagnostics;
+- `0`: no active diagnostics at or above the selected threshold;
 - `1`: repairable application findings;
 - `2`: malformed configuration, unavailable required tooling, or a failed stage;
 - `130`: cancellation.
 
-Warnings and review findings remain visible but do not fail unless their originating preset promotes them to errors. A cached report keeps its original exit code and labels previously run stages `cached`.
+Warnings and review findings remain visible at every threshold. A cached report keeps its original exit code and labels previously run stages `cached`.
 
 ## Monorepos and repair loops
 

package/doctor/cli.mjs

@@ -54,6 +54,7 @@ Options:
   --browser <list>       Comma-separated chromium,firefox,webkit
   --eslint <preset>      recommended-ui or strict-ui
   --format <format>      text or json (default: text)
+  --fail-on <severity>   error, review, or warning (default: error)
   --output <path>        Also write the merged report
   --no-cache             Disable the content-addressed cache
 
@@ -68,6 +69,7 @@ Exit codes: 0 clean, 1 findings, 2 configuration/tool failure, 130 cancelled.`);
   const browserList = take('--browser');
   const eslintConfig = take('--eslint') ?? 'recommended-ui';
   const format = take('--format') ?? 'text';
+  const failOn = take('--fail-on');
   const output = take('--output');
   const full = args.includes('--full');
   const changed = args.includes('--changed');
@@ -80,6 +82,8 @@ Exit codes: 0 clean, 1 findings, 2 configuration/tool failure, 130 cancelled.`);
     throw new Error('--full and --changed are mutually exclusive.');
   if (!['text', 'json'].includes(format))
     throw new Error('--format must be text or json.');
+  if (failOn && !['error', 'review', 'warning'].includes(failOn))
+    throw new Error('--fail-on must be error, review, or warning.');
   if (!['recommended-ui', 'strict-ui'].includes(eslintConfig))
     throw new Error('--eslint must be recommended-ui or strict-ui.');
   const abort = new globalThis.AbortController();
@@ -95,6 +99,7 @@ Exit codes: 0 clean, 1 findings, 2 configuration/tool failure, 130 cancelled.`);
     cache: !noCache,
     signal: abort.signal,
     eslintConfig,
+    failOn,
     browser: url
       ? { url, browsers: browserList?.split(',').map((item) => item.trim()) }
       : undefined,

package/doctor/config.schema.json

@@ -9,6 +9,7 @@
     "schemaVersion": { "const": 1 },
     "mode": { "enum": ["full", "changed"] },
     "package": { "type": "string", "minLength": 1 },
+    "ownership": { "enum": ["package", "component"] },
     "stages": {
       "type": "object",
       "properties": {
@@ -37,6 +38,7 @@
       "additionalProperties": false
     },
     "cache": { "type": "boolean" },
+    "failOn": { "enum": ["error", "review", "warning"] },
     "suppressions": {
       "type": "array",
       "items": {

package/doctor/index.d.mts

@@ -22,6 +22,7 @@ export interface UiDoctorConfig {
   schemaVersion: 1;
   mode?: 'full' | 'changed';
   package?: string;
+  ownership?: 'package' | 'component';
   stages?: Partial<
     Record<
       'catalog' | 'typescript' | 'eslint' | 'analyzer' | 'browser',
@@ -36,6 +37,7 @@ export interface UiDoctorConfig {
     reportPath?: string;
   };
   cache?: boolean;
+  failOn?: 'error' | 'review' | 'warning';
   suppressions?: UiDoctorSuppression[];
 }
 
@@ -109,6 +111,7 @@ export function runUiDoctor(options?: {
   config?: UiDoctorConfig;
   configPath?: string;
   cache?: boolean;
+  failOn?: 'error' | 'review' | 'warning';
   signal?: AbortSignal;
   browser?: UiDoctorConfig['browser'];
   eslintConfig?: 'recommended-ui' | 'strict-ui';

package/doctor/index.mjs

@@ -131,9 +131,11 @@ export function validateUiDoctorConfig(
     'schemaVersion',
     'mode',
     'package',
+    'ownership',
     'stages',
     'browser',
     'cache',
+    'failOn',
     'suppressions',
   ]);
   for (const key of Object.keys(config))
@@ -152,6 +154,11 @@ export function validateUiDoctorConfig(
       '$.package',
       'package must be a non-empty workspace package name or path.',
     );
+  if (
+    config.ownership !== undefined &&
+    !['package', 'component'].includes(config.ownership)
+  )
+    add('$.ownership', 'ownership must be package or component.');
   if (config.stages !== undefined) {
     if (
       !config.stages ||
@@ -224,6 +231,11 @@ export function validateUiDoctorConfig(
   }
   if (config.cache !== undefined && typeof config.cache !== 'boolean')
     add('$.cache', 'cache must be boolean.');
+  if (
+    config.failOn !== undefined &&
+    !['error', 'review', 'warning'].includes(config.failOn)
+  )
+    add('$.failOn', 'failOn must be error, review, or warning.');
   if (config.suppressions !== undefined) {
     if (!Array.isArray(config.suppressions))
       add('$.suppressions', 'suppressions must be an array.');
@@ -975,6 +987,7 @@ export async function runUiDoctor({
   config: suppliedConfig,
   configPath,
   cache,
+  failOn,
   signal,
   browser,
   runners = {},
@@ -1008,6 +1021,14 @@ export async function runUiDoctor({
     );
   }
   const selectedMode = mode ?? config.mode ?? 'full';
+  const selectedFailOn = failOn ?? config.failOn ?? 'error';
+  if (failOn !== undefined && !['error', 'review', 'warning'].includes(failOn))
+    initialDiagnostics.push(
+      configDiagnostic('failOn must be error, review, or warning.', {
+        file: '<options>',
+        path: '$.failOn',
+      }),
+    );
   const stages = { ...defaultStages, ...config.stages };
   if (browser?.url || config.browser?.url) stages.browser = true;
   const selectedPaths =
@@ -1035,6 +1056,7 @@ export async function runUiDoctor({
   const cachePath = resolve(root, '.kerf-cache/ui-doctor-v1.json');
   const key = await cacheKey(root, packageRoot, selectedMode, selectedPaths, {
     ...config,
+    failOn: selectedFailOn,
     browser: config.browser
       ? { ...config.browser, url: '<redacted-url>' }
       : undefined,
@@ -1123,6 +1145,7 @@ export async function runUiDoctor({
                 root,
                 packageRoot,
                 paths: selectedPaths,
+                ownership: config.ownership ?? 'package',
                 signal,
               })
             : (async () => ({
@@ -1130,6 +1153,7 @@ export async function runUiDoctor({
                   await analyzeUiProject({
                     root: packageRoot,
                     paths: selectedPaths,
+                    ownership: config.ownership ?? 'package',
                     knownRules: [...registeredRuleIds, ...eslintRuleIds],
                   }),
                 ),
@@ -1228,7 +1252,9 @@ export async function runUiDoctor({
     ? UI_DOCTOR_EXIT.cancelled
     : infrastructureFailure
       ? UI_DOCTOR_EXIT.configuration
-      : summary.errors
+      : summary.errors ||
+          (selectedFailOn !== 'error' && summary.review) ||
+          (selectedFailOn === 'warning' && summary.warnings)
         ? UI_DOCTOR_EXIT.findings
         : UI_DOCTOR_EXIT.clean;
   const report = redact(root, {

package/llms.txt

@@ -109,7 +109,7 @@ not a reason to override — and your own components follow the same rule.
    pair measures below 4.5:1, is review finding `KUI-L018` (set both); CSS that restyles a component
    (`KUI-L019`), touches its private `--_*` variables (`KUI-L020`), overrides a token a typed prop sets
    (`KUI-L021`), or styles it through a hook class on its root (`KUI-L022`) is an error: configure the
-   component instead, and report a component gap when no prop exists; repair source-located errors until exit 0. Use full mode for release gates;
+   component instead, and report a component gap when no prop exists; application-component imports may use TypeScript `paths` aliases; use `"ownership": "component"` with catalog `styleSources` to apply this boundary between an app's own components; repair source-located errors until exit 0. Use full mode for release gates;
    generated `dist`/`coverage`, dependency, cache, evidence, and nested-worktree
    directories are excluded consistently from every static stage.
    [`kerf-ui-analyze`](./docs/ui-analyzer.md) remains available when only static
@@ -165,6 +165,9 @@ headingLevel`, `TokenSearchField clearIcon`, `ContentItem frame="framed"` for a
   expanded trailing control to a full second row at `responsiveAt`; the leading
   title remains above it. Public leading-min-width, trailing-gap/justify, and
   per-zone inline-padding tokens cover app-specific toolbar geometry.
+  In a stacked Toolbar, `ToolbarControlGroup placement="end"` places a collapsed
+  search at its row's trailing edge; `sizing="fill"` gives its expanded state a
+  full row and a reduced-motion-aware downward entrance.
   `--kui-toolbar-inset: 0px` removes an embedded Toolbar's outer padding and
   corresponding minimum-height allowance while preserving its zone gap and
   safe-area compensation.
@@ -286,7 +289,9 @@ headingLevel`, `TokenSearchField clearIcon`, `ContentItem frame="framed"` for a
   (`@kerfjs/ui/popup-menu`, registered once via `@kerfjs/ui/popup-menu/register`)
   in a `single` `ToolbarControlGroup` with `nestedDropdown`; never hand-write
   `wa-dropdown` markup for a menu. Let the group size the trigger from its icon,
-  localized text, and caret. `PopupMenu` items also support nested `submenu`
+  localized text, and caret. Set `overflow="wrap"` for independent action links
+  that must remain fully visible at narrow widths; whole links move to a second
+  row, as in the catalog resource footer. `PopupMenu` items also support nested `submenu`
   actions, headings, dividers, checked or trailing choice marks, danger tone,
   and disabled reasons; nested headings/dividers stay out of keyboard choices;
   use `context` with `openPopupMenuAt`/`closePopupMenu` for pointer-anchored row
@@ -379,7 +384,9 @@ headingLevel`, `TokenSearchField clearIcon`, `ContentItem frame="framed"` for a
   callbacks. For a tab-local action plus a separate far-edge action, set
   `TabBar trailingPlacement="adjacent"`, put the local action in `trailing`, and
   the workspace action in `end`; the component keeps both visible while its tab
-  list shrinks and scrolls, without application descendant CSS. Managed
+  list shrinks and scrolls, without application descendant CSS. Each action
+  zone accepts one ToolbarControlGroup or a standalone `wa-button` for its own
+  Web Awesome chrome. Managed
   TokenSearchField clear also preserves open state and replacement
   editor focus before the next input task, so shortcut-letter typing stays in search.
   Select All deletion does the same; deletion
@@ -416,7 +423,8 @@ headingLevel`, `TokenSearchField clearIcon`, `ContentItem frame="framed"` for a
   `busy` spinner while its `status` (and a `ListItem`'s `trailing`) content
   become skeletons. Use the standalone `Skeleton` for a custom slot. Prefer it over `wa-skeleton`
   (the pure-Kerf primitives avoid Web Awesome), and never animate it — use
-  `LoadingSpinner` for known busy activity instead.
+  `LoadingSpinner` for known busy activity instead. Set its `size` prop to a
+  named icon step or positive pixel number when the inherited 1em is unsuitable.
 - **Keep ListItem content inside the row.** The rounded `ListItem` root clips
   overflowing label, status, and dormant trailing content. Set `multiline` when
   the primary label should wrap; use `ListActionRow` instead when trailing content
@@ -435,7 +443,9 @@ headingLevel`, `TokenSearchField clearIcon`, `ContentItem frame="framed"` for a
 - **Size a Select through its API.** `triggerWidth` chooses `fit-content`,
   `max-content`, or `fill`; `--kui-select-trigger-max-width` caps it. For custom
   selected text, use the public color, font-size, and font-weight tokens; the
-  closed value ellipsizes when space runs out.
+  closed value ellipsizes when space runs out. `presentation="title"` gives a
+  rail view heading a 36px bold, flush-start trigger and adjacent caret;
+  `focusRingInset` keeps its ring inside clipping ancestors.
 - **Configure application tabs at their owners.** AppTab's `icon-only`
   presentation keeps `name` accessible, `labelMaxWidth` ellipsizes a long name,
   `nameOverflow="visible"` shows the full name during inline loading, and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kerfjs/ui",
-  "version": "5.0.0-beta.68",
+  "version": "5.0.0-beta.69",
   "description": "Accessible, composable UI primitives for kerf applications.",
   "type": "module",
   "license": "MIT",

package/dist/chunk-5SYE4CCT.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/token-search-field.tsx"],"names":[],"mappings":"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","file":"chunk-5SYE4CCT.js","sourcesContent":["import type { SafeHtml } from 'kerfjs';\nimport { Search, X } from 'lucide';\n\nimport { LucideIcon } from './lucide-icon.js';\nimport type { KerfUiContent } from './semantic-content.js';\nimport type { TokenSearchModel } from './token-search-model.js';\n\nexport interface TokenSearchToken {\n  value: string;\n  label: string;\n  offset?: number;\n  accessibleLabel?: string;\n}\n\nexport interface TokenSearchTrailingAction {\n  icon: SafeHtml;\n  label: string;\n  action: string;\n  id?: string;\n}\n\nexport type TokenSearchEditorAttributes = Readonly<\n  Record<`data-${string}`, string | undefined> & {\n    'data-component'?: never;\n    'data-key'?: never;\n    'data-morph-skip'?: never;\n    'data-token-search-editor'?: never;\n    'data-token-count'?: never;\n    'data-placeholder'?: never;\n  }\n>;\n\ninterface TokenSearchFieldBaseProps {\n  id: string;\n  label: string;\n  query?: string;\n  tokens?: readonly TokenSearchToken[];\n  /** Opt-in grammar, suggestion, and evaluation state. Overrides `query` and `tokens`. */\n  model?: TokenSearchModel;\n  /**\n   * Editor identity for a programmatic text replacement. The editor's text is\n   * DOM-owned between token changes, so a new `query` with the same tokens\n   * does not re-render it (that would reset the caret on every keystroke).\n   * Change `revision` when the app replaces the text itself — reseeding a\n   * persistent dialog's field on reopen, applying a saved search — and the\n   * editor is rebuilt from `query` and `tokens`.\n   */\n  revision?: string | number;\n  placeholder?: string;\n  tokenPlaceholder?: string;\n  disabled?: boolean;\n  autofocus?: boolean;\n  /** Let an expanded collapsible field consume the available inline width. */\n  fill?: boolean;\n  leading?: KerfUiContent;\n  editAction?: string;\n  removeAction?: string;\n  clearAction?: string;\n  clearLabel?: string;\n  /** Icon for the clear button. Default: the Lucide `x` glyph token chips also use. */\n  clearIcon?: SafeHtml;\n  className?: string;\n  editorAttributes?: TokenSearchEditorAttributes;\n  /** Native named-slot assignment when composed inside a web component. */\n  slot?: string;\n}\n\ntype TokenSearchTrailingProps =\n  | { trailing?: KerfUiContent; trailingAction?: never }\n  | { trailing?: never; trailingAction: TokenSearchTrailingAction };\n\ntype TokenSearchPresentationProps =\n  | {\n      /** Standalone field chrome or the inset visual layer of a configured toolbar group. */\n      presentation?: 'standalone' | 'toolbar-group';\n      hint?: never;\n      required?: never;\n    }\n  | {\n      /** Visible form label and optional hint around the full-width standalone control. */\n      presentation: 'form-field';\n      hint?: string;\n      /** Marks the editor required; the app validates its value. */\n      required?: boolean;\n    };\n\ntype TokenSearchCollapsibleProps =\n  | {\n      /** Allow an empty field to render as one iconic action. */\n      collapsible: true;\n      /** Keep an empty collapsible field open while the application owns focus. */\n      expanded?: boolean;\n      expandAction?: string;\n      expandLabel?: string;\n    }\n  | {\n      collapsible?: false;\n      expanded?: never;\n      expandAction?: never;\n      expandLabel?: never;\n    };\n\nexport type TokenSearchFieldProps = TokenSearchFieldBaseProps &\n  TokenSearchCollapsibleProps &\n  TokenSearchTrailingProps &\n  TokenSearchPresentationProps;\n\nexport interface TokenSearchFieldValue {\n  query: string;\n  tokens: TokenSearchToken[];\n}\n\ntype TokenSearchPart =\n  { kind: 'text'; value: string } | { kind: 'token'; token: TokenSearchToken };\n\nfunction orderedParts(\n  query: string,\n  tokens: readonly TokenSearchToken[],\n): TokenSearchPart[] {\n  const ordered = tokens\n    .map((token, index) => ({\n      token,\n      index,\n      offset: Math.max(0, Math.min(query.length, token.offset ?? query.length)),\n    }))\n    .sort(\n      (left, right) => left.offset - right.offset || left.index - right.index,\n    );\n  const parts: TokenSearchPart[] = [];\n  let cursor = 0;\n  for (const { token, offset } of ordered) {\n    parts.push({ kind: 'text', value: query.slice(cursor, offset) });\n    parts.push({ kind: 'token', token: { ...token, offset } });\n    cursor = offset;\n  }\n  parts.push({ kind: 'text', value: query.slice(cursor) });\n  return parts;\n}\n\nfunction CloseIcon() {\n  return <LucideIcon icon={X} name=\"x\" />;\n}\n\nexport function TokenSearchField({\n  id,\n  label,\n  query = '',\n  tokens = [],\n  model,\n  revision,\n  placeholder = 'Search',\n  tokenPlaceholder = 'Add search…',\n  disabled = false,\n  autofocus = false,\n  fill = false,\n  collapsible = false,\n  expanded = false,\n  expandAction = 'expand-token-search',\n  expandLabel,\n  leading,\n  trailing,\n  trailingAction,\n  presentation = 'standalone',\n  hint,\n  required = false,\n  editAction = 'edit-search-token',\n  removeAction = 'remove-search-token',\n  clearAction = 'clear-token-search',\n  clearLabel = 'Clear search',\n  clearIcon,\n  className = '',\n  editorAttributes = {},\n  slot,\n}: TokenSearchFieldProps) {\n  if (model) {\n    query = model.state.value.query;\n    tokens = model.state.value.tokens;\n  }\n  const suggestions = model?.suggestions.value ?? [];\n  const parts = orderedParts(query, tokens);\n  const tokenKey = tokens.map((token) => token.value).join('|');\n  const key = model\n    ? `${id}@${String(revision ?? '')}:${model.editorRevision.value}:${tokenKey}`\n    : revision === undefined\n      ? `${id}:${tokenKey}`\n      : `${id}@${String(revision)}:${tokenKey}`;\n  const resolvedExpanded =\n    !collapsible || expanded || query.length > 0 || tokens.length > 0;\n  const control = (\n    <div\n      class={`kui-token-search ${className}`.trim()}\n      data-component=\"token-search-field\"\n      data-token-search-id={id}\n      data-disabled={String(disabled)}\n      data-collapsible={String(collapsible)}\n      data-expanded={String(resolvedExpanded)}\n      data-fill={String(fill)}\n      data-has-trailing={String(Boolean(trailing || trailingAction))}\n      data-presentation={presentation}\n      slot={slot}\n    >\n      {!resolvedExpanded ? (\n        <button\n          type=\"button\"\n          class=\"kui-token-search__expand\"\n          data-action={expandAction}\n          aria-label={expandLabel ?? label}\n          title={expandLabel ?? label}\n          disabled={disabled}\n        >\n          <LucideIcon icon={Search} name=\"search\" />\n        </button>\n      ) : (\n        <>\n          <span class=\"kui-token-search__leading\" aria-hidden=\"true\">\n            {leading ?? <LucideIcon icon={Search} name=\"search\" />}\n          </span>\n          <div\n            {...editorAttributes}\n            class=\"kui-token-search__editor\"\n            data-key={key}\n            data-morph-skip\n            data-token-search-editor={id}\n            data-token-count={tokens.length}\n            data-placeholder={tokens.length ? tokenPlaceholder : placeholder}\n            role=\"searchbox\"\n            aria-label={presentation === 'form-field' ? undefined : label}\n            aria-labelledby={\n              presentation === 'form-field' ? `${id}-label` : undefined\n            }\n            aria-describedby={\n              presentation === 'form-field' && hint ? `${id}-hint` : undefined\n            }\n            aria-required={required ? 'true' : undefined}\n            aria-disabled={disabled ? 'true' : undefined}\n            contenteditable={disabled ? 'false' : 'true'}\n            spellcheck=\"false\"\n            autofocus={autofocus}\n          >\n            {parts.map((part) =>\n              part.kind === 'text' ? (\n                <span\n                  data-token-search-text\n                  data-empty={String(part.value.length === 0)}\n                >\n                  {part.value || (tokens.length ? '\\u200b' : '')}\n                </span>\n              ) : (\n                <span\n                  class=\"kui-token-search__token\"\n                  contenteditable=\"false\"\n                  data-component=\"token-search-token\"\n                  data-token-value={part.token.value}\n                >\n                  <button\n                    type=\"button\"\n                    class=\"kui-token-search__token-edit\"\n                    data-action={editAction}\n                    data-token-value={part.token.value}\n                    aria-label={`Edit ${part.token.accessibleLabel ?? part.token.label}`}\n                    disabled={disabled}\n                  >\n                    {part.token.label}\n                  </button>\n                  <button\n                    type=\"button\"\n                    class=\"kui-token-search__token-remove\"\n                    data-action={removeAction}\n                    data-token-value={part.token.value}\n                    aria-label={`Remove ${part.token.accessibleLabel ?? part.token.label}`}\n                    disabled={disabled}\n                  >\n                    <CloseIcon />\n                  </button>\n                </span>\n              ),\n            )}\n          </div>\n          {(query || tokens.length > 0) && (\n            <button\n              type=\"button\"\n              class=\"kui-token-search__clear\"\n              data-action={clearAction}\n              aria-label={clearLabel}\n              title={clearLabel}\n              disabled={disabled}\n            >\n              {clearIcon ?? <CloseIcon />}\n            </button>\n          )}\n          {trailingAction ? (\n            <button\n              type=\"button\"\n              class=\"kui-token-search__trailing-action\"\n              id={trailingAction.id}\n              data-action={trailingAction.action}\n              aria-label={trailingAction.label}\n              title={trailingAction.label}\n              disabled={disabled}\n            >\n              {trailingAction.icon}\n            </button>\n          ) : trailing ? (\n            <span class=\"kui-token-search__trailing\">{trailing}</span>\n          ) : null}\n          {!disabled && suggestions.length > 0 && (\n            <div\n              class=\"kui-token-search__suggestions\"\n              data-token-search-keep-open\n            >\n              {suggestions.map((suggestion) => (\n                <button\n                  type=\"button\"\n                  class=\"kui-token-search__suggestion\"\n                  data-token-search-suggestion={suggestion.value}\n                >\n                  {suggestion.label}\n                </button>\n              ))}\n            </div>\n          )}\n        </>\n      )}\n    </div>\n  );\n  if (presentation !== 'form-field') return control;\n  return (\n    <div class=\"kui-token-search__field\" data-token-search-form-field={id}>\n      <div\n        class=\"kui-token-search__field-label\"\n        id={`${id}-label`}\n        data-token-search-form-label={id}\n      >\n        {label}\n        {required && (\n          <span class=\"kui-token-search__field-required\" aria-hidden=\"true\">\n            *\n          </span>\n        )}\n      </div>\n      {control}\n      {hint && (\n        <div class=\"kui-token-search__field-hint\" id={`${id}-hint`}>\n          {hint}\n        </div>\n      )}\n    </div>\n  );\n}\n\n/** Read editable text and ordered token offsets from a rendered TokenSearchField editor. */\nexport function readTokenSearchField(\n  editor: HTMLElement,\n  knownTokens: readonly TokenSearchToken[] = [],\n): TokenSearchFieldValue {\n  let query = '';\n  const tokens: TokenSearchToken[] = [];\n  const visit = (node: Node): void => {\n    if (node.nodeType === Node.TEXT_NODE) {\n      query += (node.textContent ?? '')\n        .replaceAll('\\u00a0', ' ')\n        .replaceAll('\\u200b', '');\n      return;\n    }\n    if (!(node instanceof HTMLElement)) return;\n    if (node.matches('[data-component=\"token-search-token\"]')) {\n      const value = node.dataset.tokenValue;\n      const known = knownTokens.find((token) => token.value === value);\n      if (known) tokens.push({ ...known, offset: query.length });\n      else if (value)\n        tokens.push({ value, label: value, offset: query.length });\n      return;\n    }\n    if (node.tagName === 'BR') {\n      query += ' ';\n      return;\n    }\n    for (const child of node.childNodes) visit(child);\n  };\n  for (const child of editor.childNodes) visit(child);\n  return { query, tokens };\n}\n\n/** Focus an editor and place its caret at a text offset, skipping atomic token chips. */\nexport function placeTokenSearchCaret(\n  editor: HTMLElement,\n  offset?: number,\n): void {\n  editor.focus({ preventScroll: true });\n  const selection = globalThis.getSelection();\n  if (!selection) return;\n  const range = document.createRange();\n  if (offset === undefined) {\n    range.selectNodeContents(editor);\n    range.collapse(false);\n  } else {\n    let remaining = Math.max(0, offset);\n    let found = false;\n    const walker = document.createTreeWalker(editor, NodeFilter.SHOW_TEXT, {\n      acceptNode: (node) =>\n        node.parentElement?.closest('[data-component=\"token-search-token\"]')\n          ? NodeFilter.FILTER_REJECT\n          : NodeFilter.FILTER_ACCEPT,\n    });\n    for (let node = walker.nextNode(); node; node = walker.nextNode()) {\n      const source = node.textContent ?? '';\n      const length = source.replaceAll('\\u200b', '').length;\n      if (remaining <= length) {\n        range.setStart(\n          node,\n          source === '\\u200b' ? 0 : Math.min(remaining, source.length),\n        );\n        range.collapse(true);\n        found = true;\n        break;\n      }\n      remaining -= length;\n    }\n    if (!found) {\n      range.selectNodeContents(editor);\n      range.collapse(false);\n    }\n  }\n  selection.removeAllRanges();\n  selection.addRange(range);\n}\n"]}