@kerfjs/ui 5.0.0-beta.103 → 5.0.0-beta.105

package/README.md

@@ -142,7 +142,7 @@ because neither has one unambiguous returned root; `CollapsiblePanelToggle`
 supports it as a normal single-root control.
 
 `ListItem.rootAttributes`, `ListHeader.rootAttributes`,
-`ListActionRow.rootAttributes`, `AppTab.rootAttributes`,
+`ListActionRow.rootAttributes`, `TabBarItem.rootAttributes`,
 `Catalog.stageRootAttributes`, `CatalogExample.rootAttributes`, and `CatalogExampleStack.rootAttributes` carry typed
 application `data-*` metadata without
 teaching the package domain fields. `ListHeader.triggerAttributes` and
@@ -207,81 +207,103 @@ interchangeable. `ListItem` and `ListActionRow` deliberately expose no raw
 
 ## Component subpaths
 
-| Component                                                           | Browser import (includes reachable CSS) | Manual CSS export                        |
-| ------------------------------------------------------------------- | --------------------------------------- | ---------------------------------------- |
-| `LucideIcon`                                                        | `@kerfjs/ui/lucide-icon`                | `@kerfjs/ui/lucide-icon.css`             |
-| `Badge`                                                             | `@kerfjs/ui/badge`                      | `@kerfjs/ui/badge.css`                   |
-| `Chip`                                                              | `@kerfjs/ui/chip`                       | `@kerfjs/ui/chip.css`                    |
-| `DisclosureArrow`                                                   | `@kerfjs/ui/disclosure-arrow`           | `@kerfjs/ui/disclosure-arrow.css`        |
-| `Toolbar`                                                           | `@kerfjs/ui/toolbar`                    | `@kerfjs/ui/toolbar.css`                 |
-| `ToolbarControlGroup`, `ToolbarActionLink`                          | `@kerfjs/ui/toolbar-control-group`      | `@kerfjs/ui/toolbar-control-group.css`   |
-| `DialogSurface`, `PopupSurface`                                     | `@kerfjs/ui/surface-scaffold`           | `@kerfjs/ui/surface-scaffold.css`        |
-| `FloatingToolbar`                                                   | `@kerfjs/ui/floating-toolbar`           | `@kerfjs/ui/floating-toolbar.css`        |
-| `PopupMenu` (register with `@kerfjs/ui/popup-menu/register`)        | `@kerfjs/ui/popup-menu`                 | `@kerfjs/ui/popup-menu.css`              |
-| `openAnchoredSurface`, `openAnchoredSurfaceAt`                      | `@kerfjs/ui/anchored-surface`           | `@kerfjs/ui/anchored-surface.css`        |
-| `ToolbarText`                                                       | `@kerfjs/ui/toolbar-text`               | `@kerfjs/ui/toolbar-text.css`            |
-| `Text`, `FieldLabel`                                                | `@kerfjs/ui/text`                       | `@kerfjs/ui/text.css`                    |
-| `List`                                                              | `@kerfjs/ui/list`                       | `@kerfjs/ui/list.css`                    |
-| `Row`                                                               | `@kerfjs/ui/row`                        | `@kerfjs/ui/row.css`                     |
-| `Grid`                                                              | `@kerfjs/ui/grid`                       | `@kerfjs/ui/grid.css`                    |
-| `Spacer`                                                            | `@kerfjs/ui/spacer`                     | `@kerfjs/ui/spacer.css`                  |
-| Typed CSS dimension builders                                        | `@kerfjs/ui/css-values`                 | —                                        |
-| `ListActionRow`                                                     | `@kerfjs/ui/list-action-row`            | `@kerfjs/ui/list-action-row.css`         |
-| `ListItem`                                                          | `@kerfjs/ui/list-item`                  | `@kerfjs/ui/list-item.css`               |
-| `wireListReorder`, `reorderListItems`                               | `@kerfjs/ui/wire-list-reorder`          | —                                        |
-| `wireListFocusScroll`                                               | `@kerfjs/ui/wire-list-focus-scroll`     | —                                        |
-| `ListHeader`                                                        | `@kerfjs/ui/list-header`                | `@kerfjs/ui/list-header.css`             |
-| `ListInsetControl`                                                  | `@kerfjs/ui/list-inset-control`         | `@kerfjs/ui/list-inset-control.css`      |
-| `ListInsetText`                                                     | `@kerfjs/ui/list-inset-text`            | `@kerfjs/ui/list-inset-text.css`         |
-| `ContentItem`                                                       | `@kerfjs/ui/content-item`               | `@kerfjs/ui/content-item.css`            |
-| `Pane`                                                              | `@kerfjs/ui/pane`                       | `@kerfjs/ui/pane.css`                    |
-| `NavStack`                                                          | `@kerfjs/ui/nav-stack`                  | `@kerfjs/ui/nav-stack.css`               |
-| `wireNavStack`                                                      | `@kerfjs/ui/wire-nav-stack`             | —                                        |
-| `SplitView`                                                         | `@kerfjs/ui/split-view`                 | `@kerfjs/ui/split-view.css`              |
-| `TabNavigator`                                                      | `@kerfjs/ui/tab-navigator`              | `@kerfjs/ui/tab-navigator.css`           |
-| `wireTabNavigator`                                                  | `@kerfjs/ui/wire-tab-navigator`         | —                                        |
-| `Workbench`                                                         | `@kerfjs/ui/workbench`                  | `@kerfjs/ui/workbench.css`               |
-| `wireWorkbench`                                                     | `@kerfjs/ui/wire-workbench`             | —                                        |
-| `CollapsiblePanel`, `CollapsiblePanelToggle`                        | `@kerfjs/ui/collapsible-panel`          | `@kerfjs/ui/collapsible-panel.css`       |
-| `wireSidebar`                                                       | `@kerfjs/ui/wire-sidebar`               | —                                        |
-| Content and navigation composition                                  | —                                       | `@kerfjs/ui/layout.css`                  |
-| `ResizableRegion`                                                   | `@kerfjs/ui/resizable-region`           | `@kerfjs/ui/resizable-region.css`        |
-| `wireResizableRegions`                                              | `@kerfjs/ui/wire-resizable-regions`     | —                                        |
-| `AppTab`                                                            | `@kerfjs/ui/app-tab`                    | `@kerfjs/ui/app-tab.css`                 |
-| `TabBar`                                                            | `@kerfjs/ui/tab-bar`                    | `@kerfjs/ui/tab-bar.css`                 |
-| `wireTabBars`, `reorderTabs`                                        | `@kerfjs/ui/wire-tab-bars`              | —                                        |
-| `wireScrollDividers`                                                | `@kerfjs/ui/wire-scroll-dividers`       | —                                        |
-| `wireToolbarVisibility`                                             | `@kerfjs/ui/wire-toolbar-visibility`    | —                                        |
-| `wireOverlaySheets`                                                 | `@kerfjs/ui/wire-overlay-sheets`        | `@kerfjs/ui/overlay-sheet.css`           |
-| `LoadingSpinner`                                                    | `@kerfjs/ui/loading-spinner`            | `@kerfjs/ui/loading-spinner.css`         |
-| `Skeleton`                                                          | `@kerfjs/ui/skeleton`                   | `@kerfjs/ui/skeleton.css`                |
-| `SunkenPanel`                                                       | `@kerfjs/ui/sunken-panel`               | `@kerfjs/ui/sunken-panel.css`            |
-| `BackdropImage`                                                     | `@kerfjs/ui/backdrop-image`             | `@kerfjs/ui/backdrop-image.css`          |
-| `Select`                                                            | `@kerfjs/ui/select`                     | `@kerfjs/ui/select.css`                  |
-| `SegmentedControl`                                                  | `@kerfjs/ui/segmented-control`          | `@kerfjs/ui/segmented-control.css`       |
-| `ChoiceChips`                                                       | `@kerfjs/ui/choice-chips`               | `@kerfjs/ui/choice-chips.css`            |
-| `Composer`                                                          | `@kerfjs/ui/composer`                   | `@kerfjs/ui/composer.css`                |
-| `wireComposers`                                                     | `@kerfjs/ui/wire-composers`             | —                                        |
-| `TokenSearchField`, `readTokenSearchField`, `placeTokenSearchCaret` | `@kerfjs/ui/token-search-field`         | `@kerfjs/ui/token-search-field.css`      |
-| `wireTokenSearchFields`                                             | `@kerfjs/ui/wire-token-search-fields`   | —                                        |
-| `createTokenSearchModel`                                            | `@kerfjs/ui/token-search-model`         | —                                        |
-| `StateBanner`                                                       | `@kerfjs/ui/state-banner`               | `@kerfjs/ui/state-banner.css`            |
-| `IconButton`                                                        | `@kerfjs/ui/icon-button`                | `@kerfjs/ui/icon-button.css`             |
-| `IconToggleButton`                                                  | `@kerfjs/ui/icon-toggle-button`         | `@kerfjs/ui/icon-toggle-button.css`      |
-| `SplitButton`                                                       | `@kerfjs/ui/split-button`               | `@kerfjs/ui/split-button.css`            |
-| `FramedList`, `FramedListRow`                                       | `@kerfjs/ui/framed-list`                | `@kerfjs/ui/framed-list.css`             |
-| `SummaryRow`                                                        | `@kerfjs/ui/summary-row`                | `@kerfjs/ui/summary-row.css`             |
-| `ColumnTrack`                                                       | `@kerfjs/ui/column-track`               | `@kerfjs/ui/column-track.css`            |
-| `ContentSwap`                                                       | `@kerfjs/ui/content-swap`               | `@kerfjs/ui/content-swap.css`            |
-| `FilePickerTrigger`, `FileDropZone`                                 | `@kerfjs/ui/file-picker`                | `@kerfjs/ui/file-picker.css`             |
-| `wireFilePickers`, `fileMatchesAccept`                              | `@kerfjs/ui/wire-file-pickers`          | —                                        |
-| `Combobox`                                                          | `@kerfjs/ui/combobox`                   | `@kerfjs/ui/combobox.css`                |
-| `wireComboboxes`                                                    | `@kerfjs/ui/wire-comboboxes`            | —                                        |
-| `CornerStatus`                                                      | `@kerfjs/ui/corner-status`              | `@kerfjs/ui/corner-status.css`           |
-| `EdgeActivityIndicator`                                             | `@kerfjs/ui/edge-activity-indicator`    | `@kerfjs/ui/edge-activity-indicator.css` |
-| `wireCornerStatus`                                                  | `@kerfjs/ui/wire-corner-status`         | —                                        |
-| `EmptyState`                                                        | `@kerfjs/ui/empty-state`                | `@kerfjs/ui/empty-state.css`             |
-| `ValueTable`, `ValueTableRow`                                       | `@kerfjs/ui/value-table`                | `@kerfjs/ui/value-table.css`             |
+| Component                                                    | Browser import (includes reachable CSS) | Manual CSS export                        |
+| ------------------------------------------------------------ | --------------------------------------- | ---------------------------------------- |
+| `LucideIcon`                                                 | `@kerfjs/ui/lucide-icon`                | `@kerfjs/ui/lucide-icon.css`             |
+| `Badge`                                                      | `@kerfjs/ui/badge`                      | `@kerfjs/ui/badge.css`                   |
+| `Chip`                                                       | `@kerfjs/ui/chip`                       | `@kerfjs/ui/chip.css`                    |
+| `DisclosureArrow`                                            | `@kerfjs/ui/disclosure-arrow`           | `@kerfjs/ui/disclosure-arrow.css`        |
+| `Toolbar`                                                    | `@kerfjs/ui/toolbar`                    | `@kerfjs/ui/toolbar.css`                 |
+| `ToolbarControlGroup`, `ToolbarActionLink`                   | `@kerfjs/ui/toolbar-control-group`      | `@kerfjs/ui/toolbar-control-group.css`   |
+| `DialogSurface`, `PopupSurface`                              | `@kerfjs/ui/surface-scaffold`           | `@kerfjs/ui/surface-scaffold.css`        |
+| `ListDetailDialog`                                           | `@kerfjs/ui/list-detail-dialog`         | `@kerfjs/ui/list-detail-dialog.css`      |
+| `WorkbenchDialog`                                            | `@kerfjs/ui/workbench-dialog`           | `@kerfjs/ui/workbench-dialog.css`        |
+| `Disclosure`                                                 | `@kerfjs/ui/disclosure`                 | `@kerfjs/ui/disclosure.css`              |
+| `ProgressBar`                                                | `@kerfjs/ui/progress-bar`               | `@kerfjs/ui/progress-bar.css`            |
+| `ProgressRing`                                               | `@kerfjs/ui/progress-ring`              | `@kerfjs/ui/progress-ring.css`           |
+| `Slider`                                                     | `@kerfjs/ui/slider`                     | `@kerfjs/ui/slider.css`                  |
+| `wireSliders`, `syncSlider`                                  | `@kerfjs/ui/wire-sliders`               | —                                        |
+| `TagField`                                                   | `@kerfjs/ui/tag-field`                  | `@kerfjs/ui/tag-field.css`               |
+| `wireTagFields`                                              | `@kerfjs/ui/wire-tag-fields`            | —                                        |
+| `ColorSwatches`                                              | `@kerfjs/ui/color-swatches`             | `@kerfjs/ui/color-swatches.css`          |
+| `ColorPicker`                                                | `@kerfjs/ui/color-picker`               | `@kerfjs/ui/color-picker.css`            |
+| `wireColorPickers`                                           | `@kerfjs/ui/wire-color-pickers`         | —                                        |
+| `ColorField`                                                 | `@kerfjs/ui/color-field`                | `@kerfjs/ui/color-field.css`             |
+| `wireColorFields`                                            | `@kerfjs/ui/wire-color-fields`          | —                                        |
+| `FloatingToolbar`                                            | `@kerfjs/ui/floating-toolbar`           | `@kerfjs/ui/floating-toolbar.css`        |
+| `PopupMenu` (register with `@kerfjs/ui/popup-menu/register`) | `@kerfjs/ui/popup-menu`                 | `@kerfjs/ui/popup-menu.css`              |
+| `openAnchoredSurface`, `openAnchoredSurfaceAt`               | `@kerfjs/ui/anchored-surface`           | `@kerfjs/ui/anchored-surface.css`        |
+| `ToolbarText`                                                | `@kerfjs/ui/toolbar-text`               | `@kerfjs/ui/toolbar-text.css`            |
+| `Text`, `FieldLabel`                                         | `@kerfjs/ui/text`                       | `@kerfjs/ui/text.css`                    |
+| `List`                                                       | `@kerfjs/ui/list`                       | `@kerfjs/ui/list.css`                    |
+| `Row`                                                        | `@kerfjs/ui/row`                        | `@kerfjs/ui/row.css`                     |
+| `Grid`                                                       | `@kerfjs/ui/grid`                       | `@kerfjs/ui/grid.css`                    |
+| `Spacer`                                                     | `@kerfjs/ui/spacer`                     | `@kerfjs/ui/spacer.css`                  |
+| Typed CSS dimension builders                                 | `@kerfjs/ui/css-values`                 | —                                        |
+| `ListActionRow`                                              | `@kerfjs/ui/list-action-row`            | `@kerfjs/ui/list-action-row.css`         |
+| `ListItem`                                                   | `@kerfjs/ui/list-item`                  | `@kerfjs/ui/list-item.css`               |
+| `wireListReorder`, `reorderListItems`                        | `@kerfjs/ui/wire-list-reorder`          | —                                        |
+| `wireListFocusScroll`                                        | `@kerfjs/ui/wire-list-focus-scroll`     | —                                        |
+| `ListHeader`                                                 | `@kerfjs/ui/list-header`                | `@kerfjs/ui/list-header.css`             |
+| `ListInsetControl`                                           | `@kerfjs/ui/list-inset-control`         | `@kerfjs/ui/list-inset-control.css`      |
+| `ListInsetText`                                              | `@kerfjs/ui/list-inset-text`            | `@kerfjs/ui/list-inset-text.css`         |
+| `ContentItem`                                                | `@kerfjs/ui/content-item`               | `@kerfjs/ui/content-item.css`            |
+| `Pane`                                                       | `@kerfjs/ui/pane`                       | `@kerfjs/ui/pane.css`                    |
+| `NavStack`                                                   | `@kerfjs/ui/nav-stack`                  | `@kerfjs/ui/nav-stack.css`               |
+| `wireNavStack`                                               | `@kerfjs/ui/wire-nav-stack`             | —                                        |
+| `wirePaneChrome`                                             | `@kerfjs/ui/wire-pane-chrome`           | —                                        |
+| `SplitView`                                                  | `@kerfjs/ui/split-view`                 | `@kerfjs/ui/split-view.css`              |
+| `TabNavigator`                                               | `@kerfjs/ui/tab-navigator`              | `@kerfjs/ui/tab-navigator.css`           |
+| `wireTabNavigator`                                           | `@kerfjs/ui/wire-tab-navigator`         | —                                        |
+| `Workbench`                                                  | `@kerfjs/ui/workbench`                  | `@kerfjs/ui/workbench.css`               |
+| `wireWorkbench`                                              | `@kerfjs/ui/wire-workbench`             | —                                        |
+| `CollapsiblePanel`, `CollapsiblePanelToggle`                 | `@kerfjs/ui/collapsible-panel`          | `@kerfjs/ui/collapsible-panel.css`       |
+| `wireSidebar`                                                | `@kerfjs/ui/wire-sidebar`               | —                                        |
+| Content and navigation composition                           | —                                       | `@kerfjs/ui/layout.css`                  |
+| `ResizableRegion`                                            | `@kerfjs/ui/resizable-region`           | `@kerfjs/ui/resizable-region.css`        |
+| `wireResizableRegions`                                       | `@kerfjs/ui/wire-resizable-regions`     | —                                        |
+| `TabBarItem`                                                 | `@kerfjs/ui/tab-bar-item`               | `@kerfjs/ui/tab-bar-item.css`            |
+| `TabBar`                                                     | `@kerfjs/ui/tab-bar`                    | `@kerfjs/ui/tab-bar.css`                 |
+| `wireTabBars`, `reorderTabs`                                 | `@kerfjs/ui/wire-tab-bars`              | —                                        |
+| `wireScrollDividers`                                         | `@kerfjs/ui/wire-scroll-dividers`       | —                                        |
+| `wireToolbarVisibility`                                      | `@kerfjs/ui/wire-toolbar-visibility`    | —                                        |
+| `wireOverlaySheets`                                          | `@kerfjs/ui/wire-overlay-sheets`        | `@kerfjs/ui/overlay-sheet.css`           |
+| Toasts for `kerfjs/overlay` `toast()`                        | —                                       | `@kerfjs/ui/overlay-toast.css`           |
+| Tooltips for `kerfjs/overlay` `tooltip()`                    | —                                       | `@kerfjs/ui/overlay-tooltip.css`         |
+| `LoadingSpinner`                                             | `@kerfjs/ui/loading-spinner`            | `@kerfjs/ui/loading-spinner.css`         |
+| `Skeleton`                                                   | `@kerfjs/ui/skeleton`                   | `@kerfjs/ui/skeleton.css`                |
+| `SunkenPanel`                                                | `@kerfjs/ui/sunken-panel`               | `@kerfjs/ui/sunken-panel.css`            |
+| `BackdropImage`                                              | `@kerfjs/ui/backdrop-image`             | `@kerfjs/ui/backdrop-image.css`          |
+| `Select`                                                     | `@kerfjs/ui/select`                     | `@kerfjs/ui/select.css`                  |
+| `SegmentedControl`                                           | `@kerfjs/ui/segmented-control`          | `@kerfjs/ui/segmented-control.css`       |
+| `ChoiceChips`                                                | `@kerfjs/ui/choice-chips`               | `@kerfjs/ui/choice-chips.css`            |
+| `TextField`                                                  | `@kerfjs/ui/text-field`                 | `@kerfjs/ui/text-field.css`              |
+| `wireTextFields`                                             | `@kerfjs/ui/wire-text-fields`           | —                                        |
+| `Checkbox`                                                   | `@kerfjs/ui/checkbox`                   | `@kerfjs/ui/checkbox.css`                |
+| `wireCheckboxes`                                             | `@kerfjs/ui/wire-checkboxes`            | —                                        |
+| `RadioGroup`                                                 | `@kerfjs/ui/radio-group`                | `@kerfjs/ui/radio-group.css`             |
+| `Switch`                                                     | `@kerfjs/ui/switch`                     | `@kerfjs/ui/switch.css`                  |
+| `MessageComposer`                                            | `@kerfjs/ui/message-composer`           | `@kerfjs/ui/message-composer.css`        |
+| `wireMessageComposers`                                       | `@kerfjs/ui/wire-message-composers`     | —                                        |
+| `SearchField`, `readSearchField`, `placeSearchFieldCaret`    | `@kerfjs/ui/search-field`               | `@kerfjs/ui/search-field.css`            |
+| `wireSearchFields`                                           | `@kerfjs/ui/wire-search-fields`         | —                                        |
+| `createSearchFieldModel`                                     | `@kerfjs/ui/search-field-model`         | —                                        |
+| `StateBanner`                                                | `@kerfjs/ui/state-banner`               | `@kerfjs/ui/state-banner.css`            |
+| `Button`                                                     | `@kerfjs/ui/button`                     | `@kerfjs/ui/button.css`                  |
+| `SplitButton`                                                | `@kerfjs/ui/split-button`               | `@kerfjs/ui/split-button.css`            |
+| `FramedList`, `FramedListRow`                                | `@kerfjs/ui/framed-list`                | `@kerfjs/ui/framed-list.css`             |
+| `SummaryRow`                                                 | `@kerfjs/ui/summary-row`                | `@kerfjs/ui/summary-row.css`             |
+| `ColumnTrack`                                                | `@kerfjs/ui/column-track`               | `@kerfjs/ui/column-track.css`            |
+| `ContentSwap`                                                | `@kerfjs/ui/content-swap`               | `@kerfjs/ui/content-swap.css`            |
+| `FilePickerTrigger`, `FileDropZone`                          | `@kerfjs/ui/file-picker`                | `@kerfjs/ui/file-picker.css`             |
+| `wireFilePickers`, `fileMatchesAccept`                       | `@kerfjs/ui/wire-file-pickers`          | —                                        |
+| `Combobox`                                                   | `@kerfjs/ui/combobox`                   | `@kerfjs/ui/combobox.css`                |
+| `wireComboboxes`                                             | `@kerfjs/ui/wire-comboboxes`            | —                                        |
+| `CornerStatus`                                               | `@kerfjs/ui/corner-status`              | `@kerfjs/ui/corner-status.css`           |
+| `EdgeActivityIndicator`                                      | `@kerfjs/ui/edge-activity-indicator`    | `@kerfjs/ui/edge-activity-indicator.css` |
+| `wireCornerStatus`                                           | `@kerfjs/ui/wire-corner-status`         | —                                        |
+| `EmptyState`                                                 | `@kerfjs/ui/empty-state`                | `@kerfjs/ui/empty-state.css`             |
+| `ValueTable`, `ValueTableRow`                                | `@kerfjs/ui/value-table`                | `@kerfjs/ui/value-table.css`             |
 
 Application layouts are separate component subpaths. Browser-condition imports
 include their reachable CSS; use the matching manual CSS export when your
@@ -311,6 +333,9 @@ when it adds useful context. Set `responsive="wrap"` on a heading whose title
 must stay whole: it keeps one row while everything fits and otherwise moves the
 trailing actions below the title instead of truncating it.
 
+A toolbar with a single zone gives it the whole content box, so content set to
+fill the row reaches both insets; an absent zone leaves no empty track or gap.
+
 A toolbar never clips an action. Its trailing zone wraps whole control groups
 onto another trailing-aligned row under every `responsive` policy, and a
 `responsive="stack"` toolbar wraps its stacked center and trailing groups the
@@ -322,7 +347,7 @@ app-owned "More" `PopupMenu` (in a `single` group with `nestedDropdown`).
 `DisclosureArrow` defaults to an 18px root-scaled decorative visual. Pass a
 typed `size` (for example `size={remify(24)}` from `@kerfjs/ui/css-values`)
 when a consumer needs another size; the owning control still supplies interaction, naming, and
-expanded state. Kerf `Select` retains its independent Web Awesome expand-glyph
+expanded state. Kerf `Select` keeps its own expand-glyph
 scale of `.5` through `--kui-disclosure-icon-scale`. Author replacement
 `DisclosureArrow` icon content facing right before its configured direction
 transform is applied. Direction changes take the shortest rotation path; a
@@ -612,8 +637,11 @@ the complete [layout contract](./docs/layout.md).
 
 ## Web Awesome theme
 
-Apps using Web Awesome's free components can opt into the same visual universe
-with one CSS import:
+Kerf components never need Web Awesome: every Kerf component draws native
+controls and reads only `--kui-*` tokens, which resolve to the same values with
+or without the Web Awesome theme. `@awesome.me/webawesome` is an optional peer
+for applications that also render Web Awesome's `wa-*` elements. Those apps opt
+into the same visual universe with one CSS import:
 
 ```ts
 import type {} from "@kerfjs/ui/webawesome";
@@ -633,7 +661,7 @@ radii, tooltips, and shadows through Web Awesome's public `--wa-*` contract.
 On `wa-dialog`, the optional `hide-actions` class hides the exported
 `header-actions` shadow part for compositions that provide another dismissal
 affordance.
-Those tokens flow into all free component families. Every free Web Awesome 3.12
+Those tokens flow into all free component families. Every free Web Awesome 3.14
 component has an individual UX-catalog route under the collapsible ecosystem
 section, but the theme entry does not import or register component JavaScript,
 so each component module remains independently tree-shakeable in consuming apps.
@@ -678,7 +706,7 @@ and `danger` palettes. Override an individual banner with
 `--kui-state-banner-action-hover-background`. To retheme one tone everywhere,
 override `--kui-state-banner-{tone}-{background|border|foreground}`. Other
 stateful components follow the same public-variable pattern, including
-`--kui-toolbar-control-*`, `--kui-segmented-*`, `--kui-app-tab-*`, and
+`--kui-toolbar-control-*`, `--kui-segmented-*`, `--kui-tab-bar-item-*`, and
 `--kui-tab-bar-*`.
 
 `SegmentedControl` is a controlled exclusive-choice component. Use
@@ -738,26 +766,26 @@ change handler. A multiple group takes no `required`. On dark inverse chrome,
 place the chips in a dark appearance scope (`.wa-dark`) instead of restyling
 them.
 
-`Composer` is the chat or prompt composer: a raised frame (the standard
+`MessageComposer` is the chat or prompt composer: a raised frame (the standard
 border, large radius, and `shadow-l`) whose border turns brand while focus is
 within. Its borderless message field grows with its content between `minRows`
 (default 1) and `maxRows` (default 8) lines, then scrolls, above an action row
 with an optional quiet `hint` and the trailing `actions`:
 
 ```tsx
-<Composer
+<MessageComposer
   id="assistant-message"
   name="message"
   label="Message"
   placeholder="Ask about this build"
   hint="Answers use the latest nightly build."
-  actions={<wa-button variant="brand" data-action="send-message">Send</wa-button>}
+  trailing={<Button tone="brand" action="send-message">Send</Button>}
 />
 ```
 
 The app reads and clears the textarea from its send action. For
-Enter-to-send, set `submitOnEnter` and call `wireComposers(root)` from
-`@kerfjs/ui/wire-composers` once: Enter or Cmd/Ctrl+Enter clicks the first
+Enter-to-send, set `submitOnEnter` and call `wireMessageComposers(root)` from
+`@kerfjs/ui/wire-message-composers` once: Enter or Cmd/Ctrl+Enter clicks the first
 trailing action, Shift+Enter inserts a newline, and an IME composition commit
 or an empty message never sends. Put it in a `DialogSurface` with
 `footerPresentation="floating"` (`slot="footer"`) to float it over a
@@ -767,21 +795,26 @@ Add `headerPresentation="floating"` with a `fill` body and
 `scrollClearance="both"` to let the transcript scroll beneath a translucent
 title bar as well.
 
-`TokenSearchField` is a token-controlled contenteditable searchbox that keeps
+`SearchField` is a token-controlled contenteditable searchbox that keeps
 free text and ordered filter chips in one field. Its editable text stays
 DOM-owned between token changes so typing does not replace the caret. Tokens
 expose stable edit/remove actions and remain atomic during editing; the app owns
 parsing, suggestions, query execution, and state in manual mode. For automatic
-handling, create a model with `createTokenSearchModel({ rules, evaluate })`,
+handling, create a model with `createSearchFieldModel({ rules, evaluate })`,
 pass it as the field's `model`, and register it under the field id in
-`wireTokenSearchFields(root, { models })`. Rules parse `name:value` expressions;
+`wireSearchFields(root, { models })`. Rules parse `name:value` expressions;
 their optional `suggest` function supplies selectable completions. The model
 commits valid expressions on whitespace or Enter, owns chips and clear/edit/
 remove actions, and exposes `state`, `suggestions`, and the latest `result` as
-signals. Omit the model to retain full manual control. Use `readTokenSearchField()`
+signals. The field subscribes only to `model.structure`, which changes when a
+token is committed or removed, the text becomes empty or non-empty, or the
+editor revision changes, so typing plain text never re-runs the host render.
+Keep it that way in the host: read `model.state.peek()` in render, and bind
+`model.result` (or a `computed`) as a fine-grained signal hole rather than
+reading `model.state.value`. Omit the model to retain full manual control. Use `readSearchField()`
 after browser input to recover text plus token offsets, and
-`placeTokenSearchCaret()` when restoring focus after a controlled update.
-Call `wireTokenSearchFields()` once at a stable root to make Enter submit through
+`placeSearchFieldCaret()` when restoring focus after a controlled update.
+Call `wireSearchFields()` once at a stable root to make Enter submit through
 `onSubmit` without inserting a contenteditable line break and to preserve focus
 plus the text-relative caret when keyboard deletion of a chip causes controlled
 rendering to replace the editor. A select-all deletion is normalized to a truly
@@ -803,12 +836,12 @@ and respect reduced-motion preferences. The field works standalone or inside a
 `ToolbarControlGroup`; the application owns the transient focused/open signal,
 focus transfer, and focusout policy. The catalog's Toolbar route demonstrates
 that composition at wide and narrow sizes.
-Override its surface through `--kui-token-search-{background|border}` and its
-chips through `--kui-token-search-token-{background|foreground}`. Override
-`--kui-token-search-line-size` only when the complete first-line geometry must
+Override its surface through `--kui-search-field-{background|border}` and its
+chips through `--kui-search-field-token-{background|foreground}`. Override
+`--kui-search-field-line-size` only when the complete first-line geometry must
 change together.
 
-`TabBar` is controlled: pass ordered `AppTab` children, then wire its keyboard
+`TabBar` is controlled: pass ordered `TabBarItem` children, then wire its keyboard
 and same-bar drag behavior with `wireTabBars(root, { onReorder })`. During a
 drag, the scroll strip automatically moves toward either edge with speed based
 on pointer proximity, exposing earlier or later drop targets. Apply the reported
@@ -819,53 +852,53 @@ at the opposite edge, set `trailingPlacement="adjacent"`, pass the local action
 through `trailing`, and pass the workspace action through `end`. TabBar owns the
 flex geometry: the tab strip shrinks and scrolls while both action regions stay
 visible. Do not recreate that split with descendant CSS overrides.
-Use `AppTab.rootAttributes` for domain `data-*` metadata and `closeIcon` for a
+Use `TabBarItem.rootAttributes` for domain `data-*` metadata and `closeIcon` for a
 decorative replacement glyph. The runtime rejects roles and case variants of
 the component- or wiring-owned action, tab identity, selection, drag, drop, and
 component markers. Keep the icon free of interactive descendants; the named
 close button retains all close interaction.
 
-`Select` uses Web Awesome but does not register anything by itself. Install the optional peer, import the shared theme if desired, and explicitly import the registration entry in the application:
+`Select` and `PopupMenu` draw their own native controls and need no Web Awesome. Each renders inert markup until its registration entry is imported once in the application:
 
 ```ts
-import "@kerfjs/ui/webawesome.css";
 import "@kerfjs/ui/select/register";
+import "@kerfjs/ui/popup-menu/register";
 ```
 
-That boundary keeps Web Awesome and its custom-element side effects out of bundles that use unrelated components. Automated consumer-bundle tests enforce it. `PopupMenu` follows the same rule: import `@kerfjs/ui/popup-menu/register` once to register the dropdown, item, button, and divider elements it renders. Either registration also installs help tags: an icon-only Select, PopupMenu, or `aria-label`-named `<button>` in a `ToolbarControlGroup` shows its name in an `aria-hidden` tooltip on hover and keyboard focus. A toolbar with icon-only buttons but neither control imports `@kerfjs/ui/help-tags/register`, which registers only the tooltip.
+`select/register` defines the form-associated `kui-select` root and wires every `Select` in the document; `popup-menu/register` wires every `PopupMenu` (opening, keyboard navigation, submenus, the `kui-menu-select` event, and focus return). That boundary keeps custom-element and document-listener side effects out of bundles that use unrelated components. Automated consumer-bundle tests enforce it, and also prove that no public entry except `@kerfjs/ui/webawesome.css` pulls in Web Awesome. Either registration also installs help tags: an icon-only Select, PopupMenu, or `aria-label`-named `<button>` in a `ToolbarControlGroup` shows its name in an `aria-hidden` tooltip on hover and keyboard focus. A toolbar with icon-only buttons but neither control imports `@kerfjs/ui/help-tags/register`, which registers only the tooltip.
 
 `PopupMenu` items may include `submenu` children, `checked` choices, a leading `icon`, trailing `details`, `disabledReason`, and a `danger` tone. The app owns choice state and dispatches each item's `action`. For a right-click menu, set `context: true`, a `label`, and `anchor={pointSignal.value}`; the app's `contextmenu` handler stores `{ x: event.clientX, y: event.clientY }` in that signal and calls `openPopupMenu(menu)`. The menu renders its own zero-footprint anchor host and keeps the point across re-renders, so it needs no wrapper or CSS (`openPopupMenuAt(menu, x, y)` still opens a menu rendered without `anchor`); `closePopupMenu(menu)` closes it programmatically. See [component selection](docs/component-selection.md#popup-menu-migration) for examples.
 Use `label` for a visible label or `ariaLabel` for a visually hidden name. A
 nonempty visible label takes precedence when both are supplied. Kerf names the
-actual shadow combobox without adding visible label spacing; this also works
-with `renderSelected`, and needs no application shadow-DOM patch. Use `hint`
+native trigger without adding visible label spacing; this also works with
+`renderSelected`. Use `hint`
 for persistent supporting text below the control and `placeholderText` for the
 empty value inside the closed control. Loading placeholders preserve the hint.
 
-`Select` also owns the Kerf/Web Awesome reconciliation boundary: option icons
-keep stable slotted elements across rerenders, and `renderSelected` content is
-replaced when the controlled value changes. Consumers do not need to add
+`Select` also owns its reconciliation boundary: option icons keep stable
+elements across rerenders, and `renderSelected` content is replaced when the
+controlled value changes. Consumers do not need to add
 `data-key` or `data-morph-skip` workarounds around choice icons. Icon-bearing
 options retain the standard icon-to-label gap. When a compact Select is wrapped
 in a `ToolbarControlGroup`, use `focusRingOwner="group"`; the group paints the
 focus ring with its configured pill or rounded geometry.
 
-For application choices and panes, prefer Kerf's purpose-built primitives:
-`Select` over direct Web Awesome selection/dropdown composition,
-`SegmentedControl` over Button Group, `TabBar` or `SegmentedControl` over Web
-Awesome Tabs, `LucideIcon` over Web Awesome Icon, and `ResizableRegion` over
-Split Panel. `ResizableRegion` includes Hot Sheet 2's 1px separator and
+For application choices and panes, use Kerf's purpose-built primitives;
+Web Awesome is an optional integration, and the
+[migration guide](./docs/webawesome-migration.md) maps each Web Awesome
+element a Kerf component replaces (`Select`, `PopupMenu`, `SegmentedControl`,
+`TabBar`, `LucideIcon`, `ResizableRegion`, and the native form controls). `ResizableRegion` includes Hot Sheet 2's 1px separator and
 hover/focus grip. Its optional `handleIcon` replaces only the decorative glyph;
 the component and `wireResizableRegions()` retain separator semantics and
 pointer/keyboard behavior. Typed policies cover separator visibility,
 instant-track/composited-content collapse, popup-safe overflow,
 inline/overlay/hidden responsive presentation, `responsiveFillAt` single-track
 replacement, and safe-area restore controls;
-the same policies are available on `Workbench` and `CollapsiblePanel`. Consider
-Web Awesome Popup when its anchored-positioning
-engine removes custom placement code; treat Tree, Animated Image, Comparison,
-Zoomable Frame, and the displaced alternatives above as exceptional rather
-than default patterns. The detailed rationale lives in the theme contract.
+the same policies are available on `Workbench` and `CollapsiblePanel`. In an
+integration application, consider Web Awesome Popup when its anchored-positioning
+engine removes custom placement code, and treat Tree, Animated Image,
+Comparison, and Zoomable Frame as exceptional rather than default patterns.
+The detailed rationale lives in the theme contract.
 
 ## Design and tool guidance
 
@@ -877,10 +910,11 @@ than default patterns. The detailed rationale lives in the theme contract.
 - [Component and integration contract](./docs/component-contract.md)
 - [Spacing and application layout](./docs/layout.md)
 - [Web Awesome theme contract](./docs/webawesome-theme.md)
+- [Moving an application off Web Awesome](./docs/webawesome-migration.md)
 - [UX catalog contract](./docs/ux-demo.md)
 - [AI guide](./ai/skill.md)
 
-Run `npm run dev` from this directory for the category-grouped master/detail catalog. Every public visual component has a focused route; all 70 free Web Awesome 3.12 components have focused routes under the collapsible ecosystem section. Every detail visibly links its first-party demo source and existing guidance while showing the repository-relative paths; first-party components also link their implementation source, and Web Awesome entries label local guidance as Kerf integration guidance. One grouped `Related components` selector contains derived `Uses` / `Used by` navigation across both sets. Run `npm run check` for static/unit/bundle gates and `npm run test:e2e` for the real-browser suite.
+Run `npm run dev` from this directory for the category-grouped master/detail catalog. Every public visual component has a focused route; all 73 free Web Awesome 3.14 components have focused routes under the collapsible Web Awesome Integration section. Every detail visibly links its first-party demo source and existing guidance while showing the repository-relative paths; first-party components also link their implementation source, and Web Awesome entries label local guidance as Kerf integration guidance. One grouped `Related components` selector contains derived `Uses` / `Used by` navigation across both sets. Run `npm run check` for static/unit/bundle gates and `npm run test:e2e` for the real-browser suite.
 
 Run `npm run format` after editing source or structured content. The narrower
 `npm run format:css` command remains available for style-only work. The normal
@@ -904,3 +938,16 @@ negative, unresolved, or contradictory values leave the item visible under this
 width policy. Keep primary actions visible and offer a complementary overflow
 group. See `docs/component-contract.md` "Toolbar width visibility" for lifecycle
 details.
+
+## License and third-party notices
+
+`@kerfjs/ui` is MIT licensed (see `LICENSE`).
+
+Web Awesome (`@awesome.me/webawesome`, copyright Fonticons, Inc., MIT) is an
+optional peer dependency. This package does not copy or bundle Web Awesome
+code: `@kerfjs/ui/webawesome.css` imports Web Awesome's stylesheet from the
+application's own installation, and `@kerfjs/ui/webawesome` contains only type
+declarations. An application that bundles Web Awesome components
+redistributes them, so it should retain Web Awesome's MIT notice; Font Awesome
+Free, whose icons Web Awesome embeds, asks that the attribution comments in
+those icons stay intact.