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

package/ai/components/tab-bar.md

@@ -0,0 +1,113 @@
+# TabBar
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:tab-bar` · Kerf UI · component · Navigation
+
+Controlled tab strips with typed presentation and allocation, a scroll-owning tab region, an optional adjacent trailing action, and a separately pinned far-edge end action.
+
+## When to use
+
+Controlled tab strips whose tabs shrink and scroll while fixed leading, trailing, and far-edge end actions remain visible.
+
+- Switch application tabpanels with optional overflow, closing, and reordering.
+
+**Not when:**
+
+- Do not use for a compact local toggle or a long value list.
+
+**Alternatives:**
+
+- [SegmentedControl](./segmented-control.md) (nearest)
+- [Select](./select.md) (nearest)
+- [Tab Group](./wa-tab-group.md) (prefer-over)
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/tab-bar` — exports `TabBar`, `wireTabBars`, `reorderTabs`.
+- CSS: the browser build of `@kerfjs/ui/tab-bar` pulls its CSS automatically; import `@kerfjs/ui/tab-bar.css` manually only without the `browser` export condition.
+- Wiring: `wireTabBars` from `@kerfjs/ui/wire-tab-bars` (required).
+- Wiring: `reorderTabs` from `@kerfjs/ui/wire-tab-bars` (optional).
+- Wiring: `wireScrollDividers` from `@kerfjs/ui/wire-scroll-dividers` (optional).
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/tab-bar`](../public-api-signatures-v1.md#kerfjsuitab-bar), [`@kerfjs/ui/wire-tab-bars`](../public-api-signatures-v1.md#kerfjsuiwire-tab-bars), [`@kerfjs/ui/wire-scroll-dividers`](../public-api-signatures-v1.md#kerfjsuiwire-scroll-dividers) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- leading
+- trailing
+- overflow
+- reorderable
+- rail, segmented, and inspector presentation
+- intrinsic or fill allocation
+- separate or adjacent trailing action
+- far-edge end action
+- standalone Web Awesome action in trailing or end
+- overflow dividers on each side with tabs scrolled out of view (wired by wireScrollDividers)
+
+## Composition
+
+- Parents: any.
+- Contexts: `tabpanel-navigation`.
+- Children: only `app-tab` (required: `app-tab`).
+- Built from: [AppTab](./tabs.md), [ToolbarControlGroup](./toolbar-control-group.md), [Button](./wa-button.md).
+
+Zones (a zone is bound to JSX only through its listed prop; never assume the zone id is a prop):
+
+- `tabs` — JSX prop `children`; accepts [AppTab](./tabs.md); at least 1.
+- `leading` — JSX prop `leading`; accepts [ToolbarControlGroup](./toolbar-control-group.md); 0–1.
+- `trailing` — JSX prop `trailing`; accepts [ToolbarControlGroup](./toolbar-control-group.md), [Button](./wa-button.md); 0–1.
+- `end` — JSX prop `end`; accepts [ToolbarControlGroup](./toolbar-control-group.md), [Button](./wa-button.md); 0–1.
+
+## State and wiring
+
+- selected-tab — controlled (required)
+
+**Wiring:** `wireTabBars`, `wireScrollDividers` is required.
+
+- Retain and invoke the disposer.
+- Apply onReorder to application-owned order.
+
+**Wiring-owned state attributes** — never render, remove, or branch on these as app state:
+
+- `data-tab-dragging` on `AppTab (data-component="app-tab")` (`wireTabBars`): "true" on the tab being dragged.
+- `data-tab-drop-position` on `AppTab (data-component="app-tab")` (`wireTabBars`): "before" or "after" on the tab under the pointer: where the dragged tab would land.
+- `data-tab-autoscroll` on `kui-tab-bar__tabs` (`wireTabBars`): "start" or "end" while a drag near that edge auto-scrolls the strip.
+- `data-scroll-overflow` on `kui-tab-bar__tabs` (`wireScrollDividers`): The physical edges, in canonical t/r/b/l order, beyond which content is scrolled out of view; absent when nothing is hidden (content that fits never reports its far edges). Re-applied if a re-render drops it.
+- `data-scroll-divider` on `chrome named in wireScrollDividers targets (a TabBar strip has none)` (`wireScrollDividers`): The sides, in t/r/b/l order, on which that chrome currently draws its scroll divider. Re-applied if a re-render drops it.
+
+## Geometry
+
+Margin: none · border: self · padding: self (layout role: navigation). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+- TabBar owns inline flex allocation: tabs shrink and scroll, an adjacent trailing action follows the tab strip, and the end action stays pinned at the far edge; leading, trailing, and end actions do not shrink.
+
+## Accessibility
+
+- Each tab controls a matching tabpanel.
+- Selection and focus behavior follow the configured activation mode.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Public class hooks (select for layout placement only, never to change the component's look): `kui-tab-bar`, `kui-tab-bar__leading`, `kui-tab-bar__tabs`, `kui-tab-bar__trailing`, `kui-tab-bar__end`.
+
+Never put `kui-tab-bar`, `kui-tab-bar__leading`, `kui-tab-bar__tabs`, `kui-tab-bar__trailing`, `kui-tab-bar__end` on an element you write; render `TabBar` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-tab-bar-background`, `--kui-tab-bar-border`, `--kui-tab-bar-divider-color`, `--kui-tab-bar-strip-background`, `--kui-tab-bar-strip-border-width`, `--kui-tab-bar-strip-flex`, `--kui-tab-bar-strip-gap`, `--kui-tab-bar-strip-margin-block`, `--kui-tab-bar-strip-min-height`, `--kui-tab-bar-strip-overflow-block`, `--kui-tab-bar-strip-padding`, `--kui-tab-bar-strip-radius`, `--kui-tab-bar-strip-scroll-padding-inline`, `--kui-tab-bar-trailing-flex`. Set a token only where its public contract allows; prefer a prop.
+
+Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
+
+## Diagnostics
+
+- `KUI-C104` (error) when wireTabBars is absent: TabBar requires wireTabBars for keyboard and reorder behavior.
+
+## Related
+
+- Components: [AppTab](./tabs.md), [ToolbarControlGroup](./toolbar-control-group.md), [Button](./wa-button.md), [SegmentedControl](./segmented-control.md), [Select](./select.md), [Tab Group](./wa-tab-group.md).
+- Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/accessibility.md#tabs`](../../docs/accessibility.md#tabs).
+- UX catalog route: `?component=tab-bar`.

package/ai/components/tab-navigator.md

@@ -0,0 +1,96 @@
+# TabNavigator
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:tab-navigator` · Kerf UI · component · Structure
+
+A controlled compact-device bottom tab navigator that keeps every destination scene mounted so its navigation and scroll state survive selection changes.
+
+## When to use
+
+Switch among two to five co-equal top-level destinations on compact devices while preserving each destination's independent content state.
+
+- A handset or portrait-tablet app has two to five co-equal top-level destinations.
+- Each destination must stay mounted so its NavStack and scroll position survive tab switches.
+
+**Not when:**
+
+- Do not use TabNavigator for document tabs or reorderable work items; use TabBar.
+- Do not retain the bottom bar on desktop when the same destinations should be promoted to a Workbench rail or sidebar.
+
+**Alternatives:**
+
+- [AppTab](./tabs.md) (semantic-alternative) — Use TabBar and AppTab for document-style tabpanels, overflow, closing, or reordering.
+- [Workbench](./workbench.md) (roomy-alternative) — Promote top-level destinations to a rail or sidebar on desktop-class layouts.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/tab-navigator` — exports `TabNavigatorTab`, `TabNavigatorProps`, `TabNavigator`.
+- CSS: the browser build of `@kerfjs/ui/tab-navigator` pulls its CSS automatically; import `@kerfjs/ui/tab-navigator.css` manually only without the `browser` export condition.
+- Wiring: `wireTabNavigator` from `@kerfjs/ui/wire-tab-navigator` (required).
+- Wiring: `wireScrollDividers` from `@kerfjs/ui/wire-scroll-dividers` (optional).
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/tab-navigator`](../public-api-signatures-v1.md#kerfjsuitab-navigator), [`@kerfjs/ui/wire-tab-navigator`](../public-api-signatures-v1.md#kerfjsuiwire-tab-navigator), [`@kerfjs/ui/wire-scroll-dividers`](../public-api-signatures-v1.md#kerfjsuiwire-scroll-dividers) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- text-only tabs
+- icon and text tabs
+- badged tabs (count or text-free dot)
+- one NavStack per tab
+- bar divider only while the active scene continues below it (wired by wireScrollDividers)
+- permanent or no bar divider (chromeDividers always or none)
+- sunken active-scene separator (separator auto or hidden)
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+- Built from: [Badge](./badge.md).
+
+## State and wiring
+
+**The app owns:** controlled active tab id; tab labels, icons, and content; tab badge counts or dots and their localized badgeLabel phrases; routing and persistence; responsive replacement on larger device classes; whether the bar divider follows the scroll, always shows, or never shows (chromeDividers); whether the bar's top separator follows a sunken active surface or stays hidden (separator); optional active-scene focus (tabIndex) and persistent outline (outlined).
+
+**Wiring:** `wireTabNavigator`, `wireScrollDividers` is required.
+
+- Use wireTabNavigator as documented.
+
+**Wiring-owned state attributes** — never render, remove, or branch on these as app state:
+
+- `data-scroll-overflow` on `the active kui-tab-scaffold__scene, or what scrolls inside it (a sole NavStack's active view or a sole Pane's content)` (`wireScrollDividers`): The physical edges, in canonical t/r/b/l order, beyond which content is scrolled out of view; absent when nothing is hidden (content that fits never reports its far edges). Re-applied if a re-render drops it.
+- `data-scroll-divider` on `kui-tab-scaffold__bar` (`wireScrollDividers`): The sides, in t/r/b/l order, on which this chrome currently draws its scroll divider: the side facing the scroller while content is hidden beyond it. Re-applied if a re-render drops it.
+
+## Geometry
+
+Margin: none · border: conditional · padding: self (layout role: structure). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+- The navigator owns the full-height scene region and safe-area-aware bottom bar; scene content owns its internal geometry.
+- The bar's reserved 1px top edge separates a sunken active scene or nested Pane by default; on flat surfaces it follows scroll state (wireScrollDividers). separator=hidden suppresses it.
+
+## Accessibility
+
+- Give the tablist an accessible label and keep exactly the active tab in the sequential focus order.
+- Wire selection through the controlled active id while leaving inactive scenes mounted and hidden.
+- A focusable scene is a tabpanel named by its tab label; optional scene tabIndex applies only while active.
+- A tab badge is aria-hidden; supply badgeLabel so the tab's accessible name becomes "\<label>, \<badgeLabel>" (it defaults to the badge text). The dot form, badge: true, has no text, so its badgeLabel is required.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Public class hooks (select for layout placement only, never to change the component's look): `kui-tab-scaffold`, `kui-tab-scaffold__scenes`, `kui-tab-scaffold__scene`, `kui-tab-scaffold__bar`, `kui-tab-scaffold__tab`, `kui-tab-scaffold__tab-icon`, `kui-tab-scaffold__tab-badge`, `kui-tab-scaffold__tab-label`.
+
+Never put `kui-tab-scaffold`, `kui-tab-scaffold__scenes`, `kui-tab-scaffold__scene`, `kui-tab-scaffold__bar`, `kui-tab-scaffold__tab`, `kui-tab-scaffold__tab-icon`, `kui-tab-scaffold__tab-badge`, `kui-tab-scaffold__tab-label` on an element you write; render `TabNavigator` instead (`KUI-L103`).
+
+Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
+
+## Related
+
+- Components: [Badge](./badge.md), [AppTab](./tabs.md), [Workbench](./workbench.md).
+- Docs: [`docs/tab-navigator.md`](../../docs/tab-navigator.md), [`docs/app-layouts.md#decision-matrix`](../../docs/app-layouts.md#decision-matrix).
+- UX catalog route: `?component=tab-navigator`.

package/ai/components/tabs.md

@@ -0,0 +1,95 @@
+# AppTab
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:tabs` · Kerf UI · component · Navigation
+
+Roving-tabindex-ready tabs with typed compact, segmented, icon-only, drop-target, pinned, and name-overflow presentations.
+
+## When to use
+
+Render a controlled application tab with compact or icon-only presentation, a visible drop target, optional full-name display, and an optional pinned leading position.
+
+- Render one controlled application tab inside TabBar.
+
+**Not when:**
+
+- Do not render alone or use for a compact settings choice.
+
+**Alternatives:**
+
+- [SegmentedControl](./segmented-control.md) (nearest)
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/app-tab` — exports `AppTab`.
+- CSS: the browser build of `@kerfjs/ui/app-tab` pulls its CSS automatically; import `@kerfjs/ui/app-tab.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/app-tab`](../public-api-signatures-v1.md#kerfjsuiapp-tab) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- selected
+- closable
+- draggable
+- leading
+- trailing
+- custom close icon
+- root metadata
+- compact size
+- segmented presentation
+- icon-only accessible presentation
+- label maximum width and ellipsis or visible name overflow
+- drop-target highlight
+- pinned leading position within a scrolling tablist
+- attention name color
+
+## Composition
+
+- Parents: only inside [TabBar](./tab-bar.md).
+- Contexts: `tabpanel-navigation`.
+- Children: unrestricted.
+- Built from: [LucideIcon](./lucide-icon.md).
+
+Zones (a zone is bound to JSX only through its listed prop; never assume the zone id is a prop):
+
+- `leading-decoration` — JSX prop `leading`; accepts `dormant-decoration`; 0–1.
+- `trailing-decoration` — JSX prop `trailing`; accepts `dormant-decoration`; 0–1.
+- `close-icon` — JSX prop `closeIcon`; accepts `dormant-decoration`; 0–1.
+
+## State and wiring
+
+**The app owns:** tab identity; selection; drop-target state; close policy; content; application data attribute values; outer placement.
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: self · padding: self (layout role: navigation). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- Compose in a tablist and pair with an application-owned tabpanel.
+- Keep closeIcon decorative and free of interactive descendants; the owning close button supplies its accessible name and interaction.
+- Use rootAttributes only for application data-\* metadata; component-owned identity, state, action, and role semantics are protected at runtime.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Public class hooks (select for layout placement only, never to change the component's look): `kui-app-tab`, `kui-app-tab__close`, `kui-app-tab__close-icon`, `kui-app-tab__name`, `kui-app-tab__select`, `kui-app-tab__trailing`.
+
+Never put `kui-app-tab`, `kui-app-tab__close`, `kui-app-tab__close-icon`, `kui-app-tab__name`, `kui-app-tab__select`, `kui-app-tab__trailing` on an element you write; render `AppTab` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-app-tab-attention-color`, `--kui-app-tab-color`, `--kui-app-tab-drop-indicator`, `--kui-app-tab-drop-target-background`, `--kui-app-tab-drop-target-color`, `--kui-app-tab-drop-target-ring`, `--kui-app-tab-hover-background`, `--kui-app-tab-pinned-background`, `--kui-app-tab-pinned-hover-background`, `--kui-app-tab-selected-background`, `--kui-app-tab-selected-border`, `--kui-app-tab-selected-color`, `--kui-color-brand-border-normal`, `--kui-color-brand-on-quiet`, `--kui-color-neutral-border-normal`, `--kui-color-neutral-on-quiet`, `--kui-color-surface`, `--kui-color-text`, `--kui-focus-ring`, `--kui-font-xs`, `--kui-radius-pill`, `--kui-shadow-s`, `--kui-space-2xs`, `--kui-space-xs`. Set a token only where its public contract allows; prefer a prop.
+
+Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
+
+## Related
+
+- Components: [LucideIcon](./lucide-icon.md), [SegmentedControl](./segmented-control.md).
+- Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/accessibility.md#tabs`](../../docs/accessibility.md#tabs).
+- UX catalog route: `?component=tabs`.

package/ai/components/text.md

@@ -0,0 +1,87 @@
+# Text
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:text` · Kerf UI · component · Structure
+
+Semantic native text plus a FieldLabel heading for read-only field previews that matches themed Web Awesome form labels.
+
+## When to use
+
+Render paragraph semantics by default, h1 through h6 when selected, or geometry-free inline secondary text as a span while independently configuring quiet or danger tone, compact through extra-large size, or monospace font.
+
+- Render ordinary application headings or paragraphs with native document semantics, or inline secondary text inside rows, labels, and table cells.
+- Render FieldLabel over a read-only or click-to-edit preview that replaces a Web Awesome form control.
+
+**Not when:**
+
+- Do not use Text for toolbar identity or title content; use ToolbarText inside a Toolbar zone.
+- Do not choose a heading variant for visual size alone; preserve the document heading hierarchy.
+
+**Alternatives:**
+
+- [ToolbarText](./toolbar-text.md) (toolbar-specific)
+- [ListInsetText](./list-inset-text.md) (list-geometry-specific)
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/text` — exports `Text`, `FieldLabel`.
+- CSS: the browser build of `@kerfjs/ui/text` pulls its CSS automatically; import `@kerfjs/ui/text.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/text`](../public-api-signatures-v1.md#kerfjsuitext) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- p, h1 through h6, or inline span semantic variant
+- default, quiet, or danger tone
+- compact, default, large, or xlarge size
+- default or monospace font
+- flush item geometry and tight line height
+- controlMargins selects exterior 8px gutters with canonical physical Sides
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** semantic variant; tone; size; font; copy; document heading hierarchy; FieldLabel copy, preview/edit state, and aria-labelledby association.
+
+No wiring helper.
+
+## Geometry
+
+Margin: self · border: self · padding: self (layout role: structure). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+- Block Text variants reset native margins and add a 1px transparent border plus the standard 8px item padding; flush removes the border and padding. Tight line height is available for compact copy. Span has no margin by default, border, or padding. FieldLabel mirrors the themed Web Awesome label typography, 9px inline inset, and bottom gap.
+- controlMargins adds the shared control gutter outside selected physical edges without changing border or padding; avoid duplicating a parent inset. Spans retain inline display and native inline margin behavior.
+
+## Accessibility
+
+- Text renders a native paragraph by default; choose an h1 through h6 variant by document outline rather than appearance, or span for inline secondary text.
+- Ordinary global, data, and ARIA attributes pass through to the native element.
+- Choose tone, size, and font independently of the heading level so appearance does not distort the document outline.
+- FieldLabel is plain text, not a native label; give it an id and associate the preview group with aria-labelledby.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Public class hooks (select for layout placement only, never to change the component's look): `kui-text`, `kui-text__field-label`.
+
+Never put `kui-text`, `kui-text__field-label` on an element you write; render `Text` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-color-danger-on-quiet`, `--kui-color-text-quiet`, `--kui-font-2xl`, `--kui-font-l`, `--kui-font-mono`, `--kui-font-xs`, `--kui-layout-item-padding`. Set a token only where its public contract allows; prefer a prop.
+
+Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
+
+## Related
+
+- Components: [ToolbarText](./toolbar-text.md), [ListInsetText](./list-inset-text.md).
+- Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/component-selection.md#problem-to-component-matrix`](../../docs/component-selection.md#problem-to-component-matrix).
+- UX catalog route: `?component=text`.

package/ai/components/token-search-field.md

@@ -0,0 +1,107 @@
+# TokenSearchField
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:token-search-field` · Kerf UI · component · Controls
+
+## When to use
+
+Token-controlled, optionally collapsible search editor with ordered, editable, removable filter chips.
+
+- Combine DOM-owned free text with ordered editable/removable filter tokens in one searchbox.
+- Enable collapsible mode when an empty, unfocused search should reduce to one iconic action, standalone or inside a toolbar group.
+- Use presentation="form-field" for a structured search query beside Web Awesome form controls, with a visible label, optional hint, and required marker.
+
+**Not when:**
+
+- Do not use for ordinary text input or separately labeled filter controls.
+
+**Alternatives:**
+
+- [Input](./wa-input.md) (prefer-over)
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/token-search-field` — exports `TokenSearchField`, `readTokenSearchField`, `placeTokenSearchCaret`.
+- JavaScript: `@kerfjs/ui/wire-token-search-fields` — exports `wireTokenSearchFields`.
+- JavaScript: `@kerfjs/ui/token-search-model` — exports `createTokenSearchModel`.
+- CSS: the browser build of `@kerfjs/ui/token-search-field` pulls its CSS automatically; import `@kerfjs/ui/token-search-field.css` manually only without the `browser` export condition.
+- Wiring: `readTokenSearchField` from `@kerfjs/ui/token-search-field` (required).
+- Wiring: `placeTokenSearchCaret` from `@kerfjs/ui/token-search-field` (optional).
+- Wiring: `wireTokenSearchFields` from `@kerfjs/ui/wire-token-search-fields` (required).
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/token-search-field`](../public-api-signatures-v1.md#kerfjsuitoken-search-field), [`@kerfjs/ui/wire-token-search-fields`](../public-api-signatures-v1.md#kerfjsuiwire-token-search-fields), [`@kerfjs/ui/token-search-model`](../public-api-signatures-v1.md#kerfjsuitoken-search-model) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- tokens
+- free text
+- disabled
+- collapsible standalone or toolbar composition
+- visible form-field label, hint, and required marker
+
+## Composition
+
+- Parents: any.
+- Contexts: `structured-search-editor`.
+- Children: unrestricted.
+- Built from: [LucideIcon](./lucide-icon.md).
+
+Zones (a zone is bound to JSX only through its listed prop; never assume the zone id is a prop):
+
+- `leading-decoration` — JSX prop `leading`; accepts `dormant-decoration`; 0–1.
+- `trailing-control` — JSX prop `trailing`; accepts `control`; 0–1.
+
+## State and wiring
+
+- tokens — controlled (required)
+- text — component (required)
+- expanded — controlled
+
+**Wiring:** `wireTokenSearchFields` is required.
+
+- Retain and invoke the disposer.
+- Use readTokenSearchField for DOM-owned text.
+
+**Wiring-owned state attributes** — never render, remove, or branch on these as app state:
+
+- `data-token-search-text` on `the text span inside kui-token-search__editor` (`wireTokenSearchFields`): Marks the plain-text span the helper inserts when the editor is emptied.
+- `data-empty` on `the text span inside kui-token-search__editor` (`wireTokenSearchFields`): "true" on that span while it holds no text.
+- `data-placeholder-visible` on `the kui-token-search root` (`wireTokenSearchFields`): Tracks whether the DOM-owned editor is empty so its placeholder stays outside the editable area.
+
+## Geometry
+
+Margin: none · border: self · padding: self (layout role: controls). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- Announce result changes when useful and keep tokens atomic during editing.
+- Keep leading and trailing controls aligned to the first text line while content wraps. Managed Clear restores replacement focus before the next input task, preserving immediate typing and later focus handoffs without a frame delay.
+- Wire Enter to submit without inserting a contenteditable line break and preserve focus plus the text-relative caret across controlled keyboard chip deletion before the next keystroke. Select All deletion preserves managed open state and replacement focus; persist both edited query and tokens. Visual wrapping remains available.
+- In collapsible mode, wireTokenSearchFields manages this by default: activating the trigger reveals the searchbox and moves focus into it, Escape on an empty field collapses and returns focus to the trigger, and focus leaving an empty field collapses it; each behavior is individually opt-out.
+- The form-field presentation associates its visible label and optional hint with the searchbox, exposes aria-required when required, and lets wireTokenSearchFields focus the editor from a label click. The app validates required input.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Public class hooks (select for layout placement only, never to change the component's look): `kui-token-search`, `kui-token-search__clear`, `kui-token-search__editor`, `kui-token-search__expand`, `kui-token-search__leading`, `kui-token-search__token`, `kui-token-search__token-edit`, `kui-token-search__token-remove`, `kui-token-search__suggestions`, `kui-token-search__suggestion`, `kui-token-search__trailing`.
+
+Never put `kui-token-search`, `kui-token-search__clear`, `kui-token-search__editor`, `kui-token-search__expand`, `kui-token-search__leading`, `kui-token-search__token`, `kui-token-search__token-edit`, `kui-token-search__token-remove`, `kui-token-search__suggestions`, `kui-token-search__suggestion`, `kui-token-search__trailing` on an element you write; render `TokenSearchField` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-color-brand-fill-normal`, `--kui-color-brand-on-quiet`, `--kui-color-neutral-border-normal`, `--kui-color-text-link`, `--kui-color-surface`, `--kui-color-text`, `--kui-color-text-quiet`, `--kui-focus-ring`, `--kui-font-s`, `--kui-font-xs`, `--kui-radius-pill`, `--kui-token-search-background`, `--kui-token-search-border`, `--kui-token-search-editor-min-width`, `--kui-token-search-line-size`, `--kui-token-search-token-background`, `--kui-token-search-token-foreground`, `--kui-token-search-expanded-width`. Set a token only where its public contract allows; prefer a prop.
+
+Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
+
+## Diagnostics
+
+- `KUI-C105` (error) when wireTokenSearchFields is absent: TokenSearchField requires its public wiring helper for keyboard and collapsible behavior.
+
+## Related
+
+- Components: [LucideIcon](./lucide-icon.md), [Input](./wa-input.md).
+- Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/accessibility.md#tokensearchfield`](../../docs/accessibility.md#tokensearchfield).
+- UX catalog route: `?component=token-search-field`.

package/ai/components/toolbar-control-group.md

@@ -0,0 +1,121 @@
+# ToolbarControlGroup
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:toolbar-control-group` · Kerf UI · component · Structure
+
+Typed toolbar groups for buttons, semantic action links, compact mixed controls, selected states, dropdown surfaces, and avatar controls.
+
+## When to use
+
+Provide complete toolbar action geometry through configuration, including semantic anchors, overflow containment, and dropdown menu insets without application CSS.
+
+- Group related controls inside a toolbar with a supported visual treatment.
+- Use ToolbarActionLink for navigation or external resources that must retain native anchor semantics inside a group.
+- Fill it with plain \<button> controls (the group styles > button fully); use wa-button only for a Web Awesome feature. A popup menu is a PopupMenu in a single group with nestedDropdown; it renders its own trigger, so never hand-write wa-dropdown markup. Each control stays whole: an icon sits beside its label on one row and no trigger gets a fixed width. Use overflow=wrap for independent links that should move as whole actions to another row on narrow surfaces.
+- For an avatar control, set content=avatar and avatarImage instead of inserting an img; one button paints the group and multiple buttons paint only the pressed highlight.
+- In a Workbench or CollapsiblePanel toolbar, mark a group relocateOnCollapse to keep it available in the work-area toolbar when the panel closes; place it directly or in an array in any toolbar zone.
+- Use tileTone for a contained single group containing only a direct decorative SVG icon; interactive or mixed groups retain their existing control chrome.
+- Set expandedOverflow=visible on an expanded search to anchor application suggestions, date pickers, or help below the group without overriding its geometry.
+- Use typed hideBelow/showBelow lengths with wireToolbarVisibility(root) for per-item toolbar priority; keep primary actions available and provide a showBelow overflow alternative.
+
+**Not when:**
+
+- Do not use merely to align unrelated buttons or to imitate an exclusive choice.
+- Do not reach for wa-button for an ordinary control inside the group — a plain \<button> is the default and avoids the Web Awesome dependency.
+
+**Alternatives:**
+
+- [SegmentedControl](./segmented-control.md) (nearest)
+- [Button Group](./wa-button-group.md) (prefer-over)
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/toolbar-control-group` — exports `ToolbarActionLink`, `ToolbarControlGroup`.
+- CSS: the browser build of `@kerfjs/ui/toolbar-control-group` pulls its CSS automatically; import `@kerfjs/ui/toolbar-control-group.css` manually only without the `browser` export condition.
+- Wiring: `wireToolbarVisibility` from `@kerfjs/ui/wire-toolbar-visibility` (optional).
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/toolbar-control-group`](../public-api-signatures-v1.md#kerfjsuitoolbar-control-group), [`@kerfjs/ui/wire-toolbar-visibility`](../public-api-signatures-v1.md#kerfjsuiwire-toolbar-visibility) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- contained
+- borderless
+- pressed
+- single
+- default or compact size
+- comfortable or tight density
+- icon, text, mixed, or avatar content
+- raised, filled, or outline selected chrome
+- brand, neutral, or pop selected tone
+- nested dropdown trigger
+- standard, compact, or list-zero dropdown menu inset
+- visible, horizontally scrollable, or whole-action wrapping overflow
+- always visible or compact-only responsive visibility
+- relocate on panel collapse
+- avatar scrim
+- contained avatar background on a single group or selected multi-button highlight
+- neutral, brand, success, warning, or danger quiet icon tile tone
+- clip or visible app-owned overflow while a search is expanded
+- typed hideBelow/showBelow thresholds at the nearest Toolbar content width
+
+**CSS-value props** (typed builders from `@kerfjs/ui/css-values`; raw CSS strings are rejected):
+
+- `hideBelow`: length grammar; raw values: forbid; helpers `px`, `rem`, `em`, `pct`, `space`, `lengthVar`, `calc` — e.g. `hideBelow={px(416)}`
+- `showBelow`: length grammar; raw values: forbid; helpers `px`, `rem`, `em`, `pct`, `space`, `lengthVar`, `calc` — e.g. `showBelow={px(416)}`
+
+## Composition
+
+- Parents: only inside [Toolbar](./toolbar.md) or [FloatingToolbar](./floating-toolbar.md) or [TabBar](./tab-bar.md).
+- Contexts: `toolbar-zone`.
+- Children: only `control` (required: `control`).
+- Built from: [LucideIcon](./lucide-icon.md), [SegmentedControl](./segmented-control.md).
+
+Zones (a zone is bound to JSX only through its listed prop; never assume the zone id is a prop):
+
+- `controls` — no declared JSX prop; accepts `control`; at least 1.
+
+## State and wiring
+
+**The app owns:** actions; link destination and copy; pressed state; expanded state; avatar image URL.
+
+**Wiring:** `wireToolbarVisibility` is optional.
+
+**Wiring-owned state attributes** — never render, remove, or branch on these as app state:
+
+- `data-toolbar-width-hidden` on `ToolbarText, ToolbarControlGroup and its paired busy status` (`wireToolbarVisibility`): True when typed hideBelow/showBelow thresholds hide this item at the nearest Toolbar content width. Re-applied after rendering; disposal restores prior markers.
+- `data-toolbar-visibility-probe` on `private aria-hidden measurement boxes under Toolbar` (`wireToolbarVisibility`): Internal out-of-flow CSS length resolver; created and removed by wireToolbarVisibility.
+- `data-morph-preserve` on `private aria-hidden measurement boxes and visibility state children` (`wireToolbarVisibility`): Keeps helper-owned geometry and state across Kerf renders; replacement and explicit removal are repaired, and disposal removes them.
+- `data-toolbar-visibility-state` on `private hidden children of width-managed items and paired busy statuses` (`wireToolbarVisibility`): Preserves actual CSS visibility while rendering removes a transient parent marker, preventing geometry-driven render feedback.
+
+## Geometry
+
+Margin: none · border: self · padding: self (layout role: structure). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- Name the group when its relationship is not evident from context.
+- Name an icon-only button or link with aria-label, not title. Once any help-tag installer is imported (select/register, popup-menu/register, or help-tags/register), it shows an aria-hidden Web Awesome help tag repeating that name after a 500ms hover and at once on keyboard focus, hidden on a press and on Escape, and never joins aria-labelledby. A native title keeps the browser tooltip and gets no second tag.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Public class hooks (select for layout placement only, never to change the component's look): `kui-toolbar-action-link`, `kui-toolbar-control-group`.
+
+Never put `kui-toolbar-action-link` on an element you write; render `ToolbarActionLink` instead (`KUI-L103`).
+
+Never put `kui-toolbar-control-group` on an element you write; render `ToolbarControlGroup` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-color-brand-on-quiet`, `--kui-color-pop-border-normal`, `--kui-color-pop-fill-normal`, `--kui-color-pop-on-normal`, `--kui-color-pop-on-quiet`, `--kui-color-neutral-border-loud`, `--kui-color-neutral-border-normal`, `--kui-color-neutral-fill-loud`, `--kui-color-neutral-fill-normal`, `--kui-color-neutral-on-loud`, `--kui-color-neutral-on-quiet`, `--kui-color-surface`, `--kui-focus-ring`, `--kui-shadow-s`, `--kui-toolbar-control-background`, `--kui-toolbar-control-border`, `--kui-toolbar-control-color`, `--kui-toolbar-control-dark-border`, `--kui-toolbar-control-hover-background`, `--kui-toolbar-control-pressed-background`, `--kui-toolbar-control-pressed-border`, `--kui-toolbar-control-pressed-color`, `--kui-toolbar-control-selected-background`, `--kui-toolbar-control-selected-color`, `--kui-toolbar-control-selected-shadow`, `--kui-color-neutral-fill-quiet`, `--kui-color-neutral-border-quiet`, `--kui-color-brand-fill-quiet`, `--kui-color-brand-border-quiet`, `--kui-color-success-fill-quiet`, `--kui-color-success-border-quiet`, `--kui-color-success-on-quiet`, `--kui-color-warning-fill-quiet`, `--kui-color-warning-border-quiet`, `--kui-color-warning-on-quiet`, `--kui-color-danger-fill-quiet`, `--kui-color-danger-border-quiet`, `--kui-color-danger-on-quiet`. Set a token only where its public contract allows; prefer a prop.
+
+Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
+
+## Related
+
+- Components: [LucideIcon](./lucide-icon.md), [SegmentedControl](./segmented-control.md), [Button Group](./wa-button-group.md).
+- Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/component-selection.md#problem-to-component-matrix`](../../docs/component-selection.md#problem-to-component-matrix).
+- UX catalog route: `?component=toolbar-control-group`.