@kerfjs/ui 5.0.0-beta.94 → 5.0.0-beta.96

package/README.md

@@ -207,60 +207,76 @@ 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`             |
-| `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`    | —                                      |
-| `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`          |
-| `Select`                                                            | `@kerfjs/ui/select`                     | `@kerfjs/ui/select.css`                |
-| `SegmentedControl`                                                  | `@kerfjs/ui/segmented-control`          | `@kerfjs/ui/segmented-control.css`     |
-| `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`          |
-| `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`        |
+| `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`          | —                                        |
+| `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`    | —                                        |
+| `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`            |
+| `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`            |
+| `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`             |
 
 Application layouts are separate component subpaths. Browser-condition imports
 include their reachable CSS; use the matching manual CSS export when your
@@ -382,8 +398,10 @@ relationships from that extension; `kerf-catalog-demo --write` emits a typed
 module and `--check` catches drift. See the [catalog guide](./docs/catalog.md)
 for repository base and source path configuration. To offer the catalog's
 **Capture region** link to UX Review on a local server, add the Node-only
-`uxReviewPlugin` from `@kerfjs/ui/vite-ux-review` to the Vite config and pass
-`wireCatalog`'s `onUxReviewProject` result to `Catalog`'s `uxReview` (the
+`uxReviewPlugin` from `@kerfjs/ui/vite-ux-review` to the Vite config (or, for a
+catalog your own backend serves, mount its `uxReviewProjectResponse` /
+`uxReviewMiddleware` on the development server) and pass `wireCatalog`'s
+`onUxReviewProject` result to `Catalog`'s `uxReview` (the
 [catalog guide](./docs/catalog.md#ux-review-capture) has the wiring).
 
 Composition-aware consumers use
@@ -683,6 +701,30 @@ value through `data-segment-value`. Override an instance through
 `--kui-segmented-{background|border|foreground|hover-background}` and
 `--kui-segmented-selected-{background|foreground|border|shadow}`.
 
+`ChoiceChips` is the wrapping exclusive choice for a visible set too large for
+one segmented track, such as a labeled color palette. Each choice is a separate
+pill backed by a native radio, so the group is one Tab stop, arrow keys move
+the selection, and the checked radio submits the form value under `name`. A
+choice may lead with a `swatch` (a `CssColor`, or `'transparent'` for the
+struck-through no-color dot) or a decorative `icon`:
+
+```tsx
+<ChoiceChips
+  name="color"
+  label="Command color"
+  value={color.value}
+  action="select-command-color"
+  choices={[
+    { value: "transparent", label: "Transparent", swatch: "transparent" },
+    { value: "blue", label: "Blue", swatch: foregroundColor("#3b82f6") },
+  ]}
+/>
+```
+
+Listen for `change` on the supplied action (for example
+`delegateActions(root, "change", { "select-command-color": … })`), read the
+radio's `value`, and re-render.
+
 `TokenSearchField` 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
@@ -750,7 +792,7 @@ import "@kerfjs/ui/select/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.
 
-`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` and a `label`, then call `openPopupMenuAt(menu, event.clientX, event.clientY)` from the app's `contextmenu` handler; `closePopupMenu(menu)` closes it programmatically. See [component selection](docs/component-selection.md#popup-menu-migration) for examples.
+`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