@kerfjs/ui 5.0.0-beta.11 → 5.0.0-beta.110

package/ai/components/tag-field.md

@@ -0,0 +1,86 @@
+# TagField
+
+<!-- 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:tag-field` · Kerf UI · component · Controls
+
+A form field that collects short values as removable tags: SearchField's token editor in its form-field presentation, with a label, hint or error, a leading tag glyph, chips that edit or remove, a clear button, an optional max, and a hidden input per tag submitted under its name.
+
+## When to use
+
+Collect a list of short values (labels, recipients, keywords) as removable tags, each submitted as its own form value.
+
+- A form collects several short values of one kind (labels, recipients, keywords): render TagField with tags and name, wire wireTagFields with onChange, and re-render with the list it reports.
+- Values must be checked (an email shape, a known label) or capped: pass normalize and max, and show onReject's reason as the field's error.
+
+**Not when:**
+
+- Do not use it for search filters; SearchField combines free text with ordered, editable filter tokens.
+- Do not use it to pick from a short fixed set; use ChoiceChips or a multiple Select.
+- Do not use wa-tag-input.
+
+**Alternatives:**
+
+- [SearchField](./search-field.md) (nearest) — Use SearchField when the tokens are search filters rather than submitted form values.
+- [ChoiceChips](./choice-chips.md) (nearest) — Use ChoiceChips to pick several from a short known set.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/tag-field` — exports `TagField`, `TagFieldProps`.
+- CSS: the browser build of `@kerfjs/ui/tag-field` pulls its CSS automatically; import `@kerfjs/ui/tag-field.css` manually only without the `browser` export condition.
+- Wiring: `wireTagFields` from `@kerfjs/ui/wire-tag-fields` (required).
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/tag-field`](../public-api-signatures-v1.md#kerfjsuitag-field) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- labels with a hint
+- validated with max and an error
+- required
+- disabled
+- custom delimiters and duplicate policy (wireTagFields options)
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+- Built from: [SearchField](./search-field.md), [LucideIcon](./lucide-icon.md).
+
+## State and wiring
+
+**The app owns:** the tag list (update it from onChange and re-render); validation and normalization (normalize) and showing refusals (onReject, error); the field name and form association.
+
+**Wiring:** `wireTagFields` is required.
+
+- Use wireTagFields as documented.
+
+## Geometry
+
+Margin: child · border: child · padding: child (layout role: controls). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+- The SearchField form-field presentation draws the label, frame, chips, and hint; TagField adds no geometry of its own.
+
+## Accessibility
+
+- The editor is named by the visible label and described by the hint or error; each chip has an edit button (its label) and a remove button named for the tag.
+- Enter or a delimiter adds the typed text, Backspace at the start removes the last tag, ArrowLeft and ArrowRight move between chips and the editor, and Backspace or Delete on a focused chip removes it.
+
+## 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-tag-field`.
+
+Never put `kui-tag-field` on an element you write; render `TagField` 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: [SearchField](./search-field.md), [LucideIcon](./lucide-icon.md), [ChoiceChips](./choice-chips.md).
+- Docs: [`docs/tag-field.md`](../../docs/tag-field.md), [`docs/component-selection.md#problem-to-component-matrix`](../../docs/component-selection.md#problem-to-component-matrix).
+- UX catalog route: `?component=tag-field`.

package/ai/components/text-field.md

@@ -0,0 +1,102 @@
+# TextField
+
+<!-- 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-field` · Kerf UI · component · Controls
+
+A labeled single-line input (including native date and number types) or multi-line textarea with hint and error text, an optional leading icon, clear button, character count, and native numeric constraints, at the 44px control height or compact.
+
+## When to use
+
+Collect free text (names, addresses, notes, comments) with Kerf's field chrome, a visible or accessible label, supporting and validation text, and native input semantics.
+
+- A form or dialog collects a line of free text: label names it (or ariaLabel when nearby content already does), hint explains it, and error reports a validation problem.
+- People write a longer note or message: multiline with rows, or rows plus maxRows to grow with the content; maxLength with showCount shows the remaining budget.
+- A filter or search field needs a leading icon and a clear button: icon and clearable.
+- An exact number needs native range or decimal-step validation: type=number with min, max, and step (including step=any).
+- A form needs a calendar date with the browser's native date picker: type=date.
+
+**Not when:**
+
+- Do not use when only existing values are allowed; use Select.
+- Do not use when people pick among suggestions or create tags; use Combobox.
+- Do not use for search text with removable filter tokens; use SearchField.
+- Do not use for a chat-style message with a send action; use MessageComposer.
+
+**Alternatives:**
+
+- [Input](./wa-input.md) (prefer-over)
+- [Textarea](./wa-textarea.md) (prefer-over)
+- [Combobox](./combobox.md) (nearest) — Use Combobox when people pick among suggestions or create a value.
+- [MessageComposer](./message-composer.md) (nearest) — Use MessageComposer for a message with a send action.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/text-field` — exports `TextField`, `wireTextFields`.
+- CSS: the browser build of `@kerfjs/ui/text-field` pulls its CSS automatically; import `@kerfjs/ui/text-field.css` manually only without the `browser` export condition.
+- Wiring: `wireTextFields` from `@kerfjs/ui/wire-text-fields` (optional).
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/text-field`](../public-api-signatures-v1.md#kerfjsuitext-field) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- visible label or ariaLabel
+- hint
+- error
+- default or compact size
+- leading icon
+- clearable
+- multiline (fixed rows or growing to maxRows)
+- maxLength with a live count
+- disabled
+- read-only
+- required
+- native autofocus (input or textarea)
+- email, password, search, url, tel, number, or date type
+- number type with native min, max, and step constraints
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+- Built from: [LucideIcon](./lucide-icon.md).
+
+## State and wiring
+
+**The app owns:** value; validation and error copy; hint copy; what a cleared field means.
+
+**Wiring:** `wireTextFields` is optional.
+
+## 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.
+
+- Label, hint, and error sit on the value's text column (1px border + 8px padding); the 44px box matches Button and Select, and compact matches their compact 33px.
+
+## Accessibility
+
+- The whole field is a \<label> around a native \<input> or \<textarea>, so clicking anywhere on it focuses the field; the input is named by label (aria-label, with the visible label text hidden from assistive technology so the clear button and count stay out of the name) or by ariaLabel. Focus shows the standard focus ring around the box.
+- The hint and error are visible below the field and form the input's aria-description; an error also sets aria-invalid="true". The clear button is a native button named by clearLabel (default Clear), hidden while the field is empty, and returns focus to the field.
+- Compact text grows to 16px on coarse-pointer touch screens so iOS does not zoom on focus.
+
+## 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-field`, `kui-text-field__label`, `kui-text-field__required`, `kui-text-field__box`, `kui-text-field__icon`, `kui-text-field__input`, `kui-text-field__clear`, `kui-text-field__hint`, `kui-text-field__error`, `kui-text-field__footer`, `kui-text-field__count`.
+
+Never put `kui-text-field`, `kui-text-field__label`, `kui-text-field__required`, `kui-text-field__box`, `kui-text-field__icon`, `kui-text-field__input`, `kui-text-field__clear`, `kui-text-field__hint`, `kui-text-field__error`, `kui-text-field__footer`, `kui-text-field__count` on an element you write; render `TextField` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-color-neutral-on-quiet`, `--kui-color-neutral-border-normal`, `--kui-color-danger-border-loud`, `--kui-color-danger-on-quiet`, `--kui-color-text`, `--kui-color-text-quiet`, `--kui-color-surface`, `--kui-focus-ring`, `--kui-font-m`, `--kui-font-s`, `--kui-font-xs`, `--kui-layout-item-padding`, `--kui-layout-rounded-radius`, `--kui-radius-circle`. 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), [Input](./wa-input.md), [Textarea](./wa-textarea.md), [Combobox](./combobox.md), [MessageComposer](./message-composer.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-field`.

package/ai/components/text.md

@@ -0,0 +1,93 @@
+# 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
+- align start (default), center, or end for centered status copy or trailing values
+- controlMargins selects exterior 8px gutters with canonical physical Sides
+- wrap normal, anywhere, nowrap, or truncate; truncate places its ellipsis at the end, the start (keeping the tail), or the middle (keeping the last path segment or a character suffix)
+- size="medium" for a 16px heading, such as an in-list group title that wraps a long name
+
+## 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.
+
+Inset-free (no margin, border, or padding) when `flush` or `variant="span"`: the form to use inside a parent that expects inset-free content (`KUI-L204`).
+
+## 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.
+- Start and middle truncation clip visually only: the whole value stays in the DOM in reading order, and Text shows it as the element's title unless the app supplies one.
+
+## 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/toast.md

@@ -0,0 +1,85 @@
+# Toast
+
+<!-- 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:toast` · Kerf UI · CSS composition · Feedback
+
+Styling for kerfjs/overlay's toast(): a bottom-edge region of stacked, auto-dismissing notifications on the raised surface, with info, success, and warning tones, StateBanner content, and enter and exit motion.
+
+## When to use
+
+Show a brief, non-blocking confirmation or status message that dismisses itself, without hand-written toast CSS.
+
+- A completed action needs brief, non-blocking confirmation (saved, copied, published): import @kerfjs/ui/overlay-toast.css once and call toast() from kerfjs/overlay with exitClass 'kui-toast-exit' and exitDuration 200.
+- A status message needs a tone or an icon and detail: pass variant ('info', 'success', 'warning') for a plain message, or render a StateBanner as the toast's only content.
+- A rapid sequence (repeated copy actions) should collapse to the latest message: mode 'replace'.
+
+**Not when:**
+
+- Do not use a toast for an error the person must act on or a decision; use a StateBanner in the affected surface, or a DialogSurface.
+- Do not put controls that must stay reachable in a toast that dismisses itself; set duration 0 and dismiss it from your own action, or use a StateBanner.
+- Do not hand-write toast placement, stacking, or motion CSS, and do not use wa-toast.
+
+**Alternatives:**
+
+- [StateBanner](./state-banner.md) (nearest) — Use a StateBanner in place for a persistent status or an error tied to one surface.
+
+## Imports
+
+- CSS: import `@kerfjs/ui/overlay-toast.css` once.
+- Declared side effects: css.
+
+## Props
+
+No props: this entry has no JavaScript API.
+
+**Variants (configure, do not restyle):**
+
+- plain message on the raised surface
+- info, success, or warning tone (variant)
+- StateBanner as the toast's only content, taking the banner's tone and chrome
+- replace mode collapsing a rapid sequence to the latest
+- bottom-edge region by default, or top-edge stacking on an app-owned container with data-placement="top"
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+- Built from: [StateBanner](./state-banner.md).
+
+## State and wiring
+
+**The app owns:** when to show a toast and its message; duration, variant, and replace mode; an app-owned container with data-placement="top" for top-edge stacking; dismissing a persistent (duration 0) toast.
+
+No wiring helper.
+
+## Geometry
+
+Margin: self · border: self · padding: self (layout role: feedback). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+- The region insets 16px from the viewport edge plus the safe area and caps its width at 480px; toasts stack with an 8px gap.
+
+## Accessibility
+
+- The core region is an aria-live polite region and each toast is role status, so assistive technology announces it without moving focus.
+- Toasts dismiss themselves after four seconds by default; give longer messages a longer duration, and never rely on a toast for the only path to an action.
+- The entrance and exit only fade under prefers-reduced-motion or the static-effects switch, and forced colors draw a CanvasText border on Canvas.
+
+## 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): `kerf-toasts`, `kerf-toast`, `kui-toast-exit`.
+
+Classes an application may place on its own elements: `kerf-toasts`, `kerf-toast`, `kui-toast-exit`.
+
+Public tokens it reads: `--kui-overlay-toast-z-index`. 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: [StateBanner](./state-banner.md).
+- Docs: [`docs/overlay-toast.md`](../../docs/overlay-toast.md), [`docs/component-selection.md#web-awesome-integration`](../../docs/component-selection.md#web-awesome-integration).
+- UX catalog route: `?component=toast`.

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

@@ -0,0 +1,127 @@
+# 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 material=glass on a group floating over imagery or a clear (transparent) toolbar: it paints the translucent, blurred chrome material with a specular edge, controls keep AA in the normal text color, and the fill turns opaque under reduced transparency, increased contrast, or static effects. Keep the solid default on an opaque toolbar.
+- 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)
+- [Button](./button.md) (nearest) — Outside a Toolbar, a standalone icon-only toggle is an icon-only Button with pressed.
+
+## 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, outline, or no selected chrome (group-wide or one control via data-selected-chrome="none")
+- 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
+- yield to an expanded trailing sibling at 480px, or exactly while a trailing-priority Toolbar row is active (yield-to-priority-row)
+- 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.
+- A disabled native button (disabled, or aria-disabled="true" when it must stay focusable) dims to half opacity with the not-allowed cursor and no hover surface; a disabled raw wa-button paints no hover surface either. Do not add disabled styling yourself.
+- 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 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.
+- In an overlay Pane header (headerPresentation="overlay"), overlay NavStack chrome (chromePresentation="overlay") or bottom toolbar (bottomToolbarPresentation="overlay"), or a DialogSurface floating header's header-actions (headerPresentation="floating"), a default-tone group (not dark-toned, not an avatar scrim) takes --kui-color-text for its controls, so they keep WCAG AA over content passing beneath the translucent chrome material.
+- A dark-toned group's hover paints a 14% surface wash over its loud fill, on one control of a group or across a lone control's whole group, so the on-loud icon keeps at least 3:1 over a light page and well above it in dark.
+
+## 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), [Button](./button.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`.

package/ai/components/toolbar-text.md

@@ -0,0 +1,100 @@
+# ToolbarText
+
+<!-- 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-text` · Kerf UI · component · Structure
+
+## When to use
+
+Extra-large through extra-small toolbar identity text.
+
+- Render toolbar identity or heading text at a supported hierarchy size; pass headingLevel for heading semantics.
+- Use action for an editable toolbar title: it renders a native button that shrinks and ellipsizes beside sibling status chips.
+- Use tone=dark for title or filename text on a loud toolbar surface, matching dark ToolbarControlGroups.
+- 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 omit headingLevel when the text is the page or section heading.
+- Large, default, and small are intentionally quiet toolbar identity text in default tone. Use xlarge-fixed for a normal-color toolbar heading at the fixed font-l step; use Text with an h2-h6 variant for a content subsection title, or ListHeader for a list or menu section.
+
+**Alternatives:**
+
+- [Text](./text.md) (semantic-alternative) — Use Text variant h2-h6 for a normal-color subsection title in content rather than toolbar identity.
+- [ListHeader](./list-header.md) (semantic-alternative) — Use ListHeader for a list or menu section label with a count, badge, action, or disclosure.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/toolbar-text` — exports `ToolbarText`.
+- CSS: the browser build of `@kerfjs/ui/toolbar-text` pulls its CSS automatically; import `@kerfjs/ui/toolbar-text.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-text`](../public-api-signatures-v1.md#kerfjsuitoolbar-text), [`@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):**
+
+- xlarge
+- xlarge-fixed (fixed font-l heading)
+- large
+- default
+- small
+- xsmall
+- placeholder (loading)
+- description: quiet single-line supporting copy under a read-only title, aligned with its text, with descriptionId for aria-describedby
+- dark (loud-surface foreground)
+- 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: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** text; responsive priority; the delegated action handler and display-to-input editing swap.
+
+**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: none · padding: none (layout role: structure). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- Plain text is not a heading; pass headingLevel to expose role=heading + aria-level for a page/section title.
+- Actionable text is a native button with its full text as its accessible name; action cannot be combined with headingLevel, placeholder, or wrap.
+- In a Pane header with headerPresentation="overlay" or NavStack chrome with chromePresentation="overlay" (or its bottom toolbar with bottomToolbarPresentation="overlay"), or slotted as the label (or into header-actions) of a DialogSurface header with headerPresentation="floating", untoned text keeps WCAG AA over the translucent chrome material: the title takes --kui-color-text at every size and the description mixes --kui-color-text-quiet halfway toward it.
+
+## 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-text`.
+
+Never put `kui-toolbar-text` on an element you write; render `ToolbarText` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-color-neutral-on-quiet`, `--kui-color-text`, `--kui-font-2xs`, `--kui-font-2xl`, `--kui-font-l`, `--kui-font-m`, `--kui-font-s`, `--kui-font-xs`, `--kui-color-neutral-on-loud`. 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: [Text](./text.md), [ListHeader](./list-header.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-text`.