@kerfjs/ui 5.0.0-beta.57 → 5.0.0-beta.59

package/README.md

@@ -39,13 +39,15 @@ npm install kerfjs @kerfjs/ui
 ```
 
 ```tsx
+import { mount } from "kerfjs";
 import { ListItem } from "@kerfjs/ui/list-item";
 import { ListHeader } from "@kerfjs/ui/list-header";
 import { ListActionRow } from "@kerfjs/ui/list-action-row";
 import { Toolbar } from "@kerfjs/ui/toolbar";
-import { ToolbarControlGroup } from "@kerfjs/ui/toolbar-control-group";
 import { ToolbarText } from "@kerfjs/ui/toolbar-text";
 
+const root = document.getElementById("app")!;
+
 mount(root, () => (
   <>
     <Toolbar
@@ -80,7 +82,7 @@ mount(root, () => (
         label="src/main.ts"
         trailingAction="open-file-actions"
         trailingActionLabel="Actions for src/main.ts"
-        trailingActionIcon={moreIcon}
+        trailingActionIcon={<span aria-hidden="true">⋯</span>}
       />
       <div id="workspace-actions" popover="auto">
         Application-owned actions
@@ -222,17 +224,29 @@ interchangeable. `ListItem` and `ListActionRow` deliberately expose no raw
 | `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`           |
 
-Opt-in application layouts keep JavaScript and CSS explicit. Import each
-layout from its component subpath, load the matching manual CSS export, and
-add its wire subpath when the layout has interactive behavior. The catalog
+Application layouts are separate component subpaths. Browser-condition imports
+include their reachable CSS; use the matching manual CSS export when your
+bundler does not select the browser condition. Add a wire subpath when the
+layout has interactive behavior. The catalog
 entries for `nav-stack`, `split-view`, `tab-scaffold`, `workbench`, and
 `collapsible-panel` document their selection rules, ownership boundaries,
 public classes, tokens, and focused demos. See
 [`docs/app-layouts.md`](./docs/app-layouts.md) for the layout decision matrix.
+`NavStack` and `TabScaffold` expose `chromeDividers="scroll" | "always" |
+"none"` for their chrome lines; `SplitView` forwards the setting to its
+compact stack. A sole `Pane` in a view or scene fills it, keeping the Pane's
+header in place while its own content scrolls.
+
+For a `Workbench` or `CollapsiblePanel`, place panel toolbar groups in its
+`leading`, `center`, and `trailing` zones. Add `relocateOnCollapse` to each
+`ToolbarControlGroup` that should remain available in the work-area toolbar
+while the panel is closed. The panel collects marked groups in zone order;
+its toggle follows them. See [Workbench panel toolbars](./docs/workbench.md#panel-toolbars).
 
 Compose panel, dialog, and page headings directly with `Toolbar`: put an optional
 icon in a `ToolbarControlGroup`, use a direct extra-large `ToolbarText` for the
@@ -625,7 +639,14 @@ value through `data-segment-value`. Override an instance through
 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. Use `readTokenSearchField()`
+parsing, suggestions, query execution, and state in manual mode. For automatic
+handling, create a model with `createTokenSearchModel({ 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;
+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()`
 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
@@ -680,6 +701,8 @@ 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.
 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

package/ai/component-catalog.json

@@ -1498,7 +1498,8 @@
         "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. Nothing wraps inside a group: an icon sits beside its label on one row and no trigger gets a fixed width.",
-        "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."
+        "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."
       ],
       "avoidWhen": [
         "Do not use merely to align unrelated buttons or to imitate an exclusive choice.",
@@ -1535,6 +1536,7 @@
         "standard, compact, or list-zero dropdown menu inset",
         "visible or horizontally scrollable overflow",
         "always visible or compact-only responsive visibility",
+        "relocate on panel collapse",
         "avatar scrim",
         "contained avatar background on a single group or selected multi-button highlight"
       ],
@@ -1838,7 +1840,7 @@
       "source": "kerf",
       "description": "Semantic native paragraph text by default, with heading and inline-span variants plus composable semantic presentation roles.",
       "uses": [],
-      "purpose": "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 size, or monospace font.",
+      "purpose": "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.",
       "publicExports": [
         "Text"
       ],
@@ -1870,7 +1872,7 @@
       "variants": [
         "p, h1 through h6, or inline span semantic variant",
         "default, quiet, or danger tone",
-        "default or compact size",
+        "compact, default, large, or xlarge size",
         "default or monospace font"
       ],
       "accessibility": [
@@ -1900,6 +1902,8 @@
       "publicTokens": [
         "--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"
@@ -3639,8 +3643,13 @@
         "TokenSearchField",
         "readTokenSearchField",
         "placeTokenSearchCaret",
-        "wireTokenSearchFields"
+        "wireTokenSearchFields",
+        "createTokenSearchModel"
       ],
+      "publicExportImports": {
+        "wireTokenSearchFields": "@kerfjs/ui/wire-token-search-fields",
+        "createTokenSearchModel": "@kerfjs/ui/token-search-model"
+      },
       "useWhen": [
         "Combine DOM-owned free text with ordered editable/removable filter tokens in one searchbox.",
         "Enable collapsible mode when an empty, unfocused search should reduce to one iconic action, standalone or inside a toolbar group."
@@ -3655,10 +3664,7 @@
         }
       ],
       "appOwns": [
-        "parsing",
-        "suggestions",
-        "tokens",
-        "query execution",
+        "the grammar and evaluation callback when using the optional managed model, or parsing, suggestions, tokens, and query execution in manual mode",
         "results",
         "the revision that rebuilds the DOM-owned editor for a programmatic text replacement",
         "optional override of the collapsible expand/collapse/focus, which wireTokenSearchFields manages by default (adopt an app expanded signal, opt out per behavior, or drive it via the returned handle)"
@@ -3725,6 +3731,8 @@
         "kui-token-search__token",
         "kui-token-search__token-edit",
         "kui-token-search__token-remove",
+        "kui-token-search__suggestions",
+        "kui-token-search__suggestion",
         "kui-token-search__trailing"
       ],
       "publicTokens": [
@@ -4016,20 +4024,23 @@
       "category": "Controls",
       "kind": "component",
       "source": "kerf",
-      "description": "A trigger button that opens a typed list of commands, built on the Web Awesome dropdown.",
+      "description": "A typed action menu with nested choices, selected state, and optional pointer-anchored context opening, built on the Web Awesome dropdown.",
       "uses": [
         "wa-dropdown",
         "wa-dropdown-item",
         "wa-button",
         "wa-divider"
       ],
-      "purpose": "A trigger button that opens a typed list of commands, built on the Web Awesome dropdown.",
+      "purpose": "A typed action menu with nested choices, selected state, and optional pointer-anchored context opening, built on the Web Awesome dropdown.",
       "publicExports": [
-        "PopupMenu"
+        "PopupMenu",
+        "openPopupMenuAt",
+        "closePopupMenu"
       ],
       "useWhen": [
         "Offer a short list of commands behind one trigger, such as a toolbar sort or More menu.",
-        "Group related commands under headings and dividers in one popup."
+        "Group related commands under headings and dividers in one popup.",
+        "Nest decisions under a parent command, show checked or trailing choice state, or open a context menu at pointer coordinates."
       ],
       "avoidWhen": [
         "Do not use it to choose a persistent value (use Select) or for navigation rows (use ListItem).",
@@ -4048,7 +4059,8 @@
       "appOwns": [
         "commands and their delegated actions",
         "which items are enabled",
-        "reactions to the menu opening or closing"
+        "reactions to the menu opening or closing",
+        "contextmenu event handling and identification of the menu root when using a pointer-anchored context menu"
       ],
       "variants": [
         "icon trigger",
@@ -4057,10 +4069,31 @@
         "headings and dividers",
         "item icons",
         "disabled items",
+        "nested actions",
+        "checked choices and trailing details",
+        "danger tone and disabled reasons",
+        "context trigger",
         "placement"
       ],
+      "usageExamples": [
+        {
+          "title": "Nested decisions",
+          "description": "The app owns the current decision, batch disabled state, and delegated actions. Each child keeps its own record metadata.",
+          "code": "<PopupMenu\n  label=\"Line actions\"\n  items={[\n    { label: 'Decide', submenu: [\n      { label: 'Approve', action: 'decide', checked: current === 'approve',\n        attributes: { 'data-line-id': lineId, 'data-decision': 'approve' } },\n      { label: 'Reject', action: 'decide', tone: 'danger',\n        disabled: needsPrice, disabledReason: needsPrice ? 'Add a price first' : undefined,\n        attributes: { 'data-line-id': lineId, 'data-decision': 'reject' } },\n    ] },\n    { kind: 'divider' },\n    { label: 'Remove', action: 'remove', tone: 'danger' },\n  ]}\n/>"
+        },
+        {
+          "title": "Flat selected choices",
+          "description": "Headings separate sort dimensions; trailing safe content marks the active command without changing its accessible label.",
+          "code": "<PopupMenu\n  label=\"Sort chat\"\n  items={[\n    { kind: 'heading', label: 'Sort by' },\n    { label: 'Updated', action: 'sort-updated', details: sort === 'updated' ? tick : undefined },\n    { label: 'Priority', action: 'sort-priority', details: sort === 'priority' ? tick : undefined },\n    { kind: 'heading', label: 'Order' },\n    { label: 'Newest first', action: 'order-newest', details: order === 'newest' ? tick : undefined },\n  ]}\n/>"
+        },
+        {
+          "title": "Pointer anchored context menu",
+          "description": "Keep the row's visible disabled action separate from the context menu anchor. Find the menu root with a stable data attribute.",
+          "code": "<PopupMenu\n  context\n  label=\"Demand actions\"\n  rootAttributes={{ 'data-demand-menu': '' }}\n  items={[{ label: 'Open', action: 'open-demand' }]}\n/>\n// In the app's row wiring:\nrow.addEventListener('contextmenu', (event) => {\n  event.preventDefault();\n  const menu = row.querySelector('[data-demand-menu]') as PopupMenuElement;\n  openPopupMenuAt(menu, event.clientX, event.clientY);\n});\n// Call closePopupMenu(menu) when the app needs to dismiss it."
+        }
+      ],
       "accessibility": [
-        "An icon-only trigger requires label, rendered as visually hidden slotted text because a Web Awesome button takes its accessible name from its content; a trigger with visible text is named by that text. Web Awesome provides menu roles, arrow-key navigation, typeahead, and Escape.",
+        "An icon-only trigger requires label, rendered as visually hidden slotted text because a Web Awesome button takes its accessible name from its content; a trigger with visible text is named by that text. The context anchor stays out of the accessibility tree. Web Awesome provides menu roles, nested arrow-key navigation, typeahead, and Escape.",
         "Once registered, an icon-only trigger shows its label as an aria-hidden Web Awesome help tag after a 500ms hover and at once on keyboard focus; it hides while the menu is open, on a press, and on Escape, and never joins aria-labelledby. Do not add a title or another tooltip."
       ],
       "geometry": {
@@ -4081,13 +4114,15 @@
       "wiring": [],
       "publicClasses": [
         "kui-popup-menu",
-        "kui-popup-menu__label"
+        "kui-popup-menu__label",
+        "kui-popup-menu__details",
+        "kui-popup-menu__context-anchor"
       ],
       "publicTokens": [],
       "links": {
         "catalogRoute": "?component=popup-menu",
         "documentation": "docs/component-selection.md",
-        "recipe": "docs/component-selection.md#web-awesome-overlap-policy"
+        "recipe": "docs/component-selection.md#popup-menu-migration"
       }
     },
     {

package/ai/component-catalog.schema.json

@@ -29,6 +29,11 @@
         "purpose": { "type": "string", "minLength": 1 },
         "customElement": { "type": "string" },
         "publicExports": { "type": "array", "items": { "type": "string" }, "uniqueItems": true },
+        "publicExportImports": {
+          "description": "Subpath overrides for public exports that do not live in the component delivery import.",
+          "type": "object",
+          "additionalProperties": { "type": "string", "minLength": 1 }
+        },
         "useWhen": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
         "avoidWhen": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
         "recommendation": { "enum": ["supported", "conditional", "exceptional", "underlying", "avoid"] },
@@ -37,6 +42,7 @@
         "wiring": { "type": "array", "items": { "$ref": "#/$defs/wiring" } },
         "appOwns": { "type": "array", "items": { "type": "string" } },
         "variants": { "type": "array", "items": { "type": "string" } },
+        "usageExamples": { "type": "array", "items": { "$ref": "#/$defs/usageExample" } },
         "accessibility": { "type": "array", "items": { "type": "string" } },
         "publicClasses": { "type": "array", "items": { "type": "string" }, "uniqueItems": true },
         "placeableClasses": { "description": "Public classes an application may place on its own elements (layout utilities, a document root, or item geometry on a non-div carrier). Every other public class is component anatomy: render the component instead.", "type": "array", "items": { "type": "string" }, "uniqueItems": true },
@@ -49,6 +55,16 @@
       },
       "additionalProperties": false
     },
+    "usageExample": {
+      "type": "object",
+      "required": ["title", "code"],
+      "properties": {
+        "title": { "type": "string", "minLength": 1 },
+        "description": { "type": "string" },
+        "code": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": false
+    },
     "geometry": {
       "type": "object",
       "required": ["margin", "border", "padding"],

package/ai/component-composition.json

@@ -1733,6 +1733,8 @@
         "publicTokens": [
           "--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"
@@ -3084,6 +3086,8 @@
           "kui-token-search__token",
           "kui-token-search__token-edit",
           "kui-token-search__token-remove",
+          "kui-token-search__suggestions",
+          "kui-token-search__suggestion",
           "kui-token-search__trailing"
         ],
         "publicTokens": [
@@ -3321,6 +3325,11 @@
           "id": "reactions to the menu opening or closing",
           "owner": "application",
           "required": false
+        },
+        {
+          "id": "contextmenu event handling and identification of the menu root when using a pointer-anchored context menu",
+          "owner": "application",
+          "required": false
         }
       ],
       "wiring": {
@@ -3336,14 +3345,19 @@
       },
       "accessibility": {
         "obligations": [
-          "An icon-only trigger requires label, rendered as visually hidden slotted text because a Web Awesome button takes its accessible name from its content; a trigger with visible text is named by that text. Web Awesome provides menu roles, arrow-key navigation, typeahead, and Escape.",
+          "An icon-only trigger requires label, rendered as visually hidden slotted text because a Web Awesome button takes its accessible name from its content; a trigger with visible text is named by that text. The context anchor stays out of the accessibility tree. Web Awesome provides menu roles, nested arrow-key navigation, typeahead, and Escape.",
           "Once registered, an icon-only trigger shows its label as an aria-hidden Web Awesome help tag after a 500ms hover and at once on keyboard focus; it hides while the menu is open, on a press, and on Escape, and never joins aria-labelledby. Do not add a title or another tooltip."
         ]
       },
       "cssValueProps": [],
       "boundaries": {
         "rootClass": "kui-popup-menu",
-        "publicClasses": ["kui-popup-menu", "kui-popup-menu__label"],
+        "publicClasses": [
+          "kui-popup-menu",
+          "kui-popup-menu__label",
+          "kui-popup-menu__details",
+          "kui-popup-menu__context-anchor"
+        ],
         "publicTokens": []
       },
       "diagnostics": [],

package/ai/components/README.md

@@ -29,7 +29,7 @@ Exact prop and callback types live in [`public-api-signatures-v1.md`](../public-
 - [Surface scaffolds](./surface-scaffold.md) — Configure recurring dialog and popup geometry without consumer ::part() overrides.
 - [FloatingToolbar](./floating-toolbar.md) — A transparent, forced-dark toolbar that floats over its container's content.
 - [ToolbarText](./toolbar-text.md) — Large, default, and compact toolbar identity text.
-- [Text](./text.md) — 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 size, or monospace font.
+- [Text](./text.md) — 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.
 - [Headers](./headers.md) — Page, dialog, and definition-list hierarchy.
 - [ValueTable](./value-table.md) — Key/value rows with optional icons and aligned separators.
 - [Row](./row.md) — Arrange related content horizontally with consistent spacing, optional physical-side text/control insets, and explicit left/center/right/full plus top/middle/bottom/full/baseline alignment instead of application-owned flex wrappers.
@@ -55,7 +55,7 @@ Exact prop and callback types live in [`public-api-signatures-v1.md`](../public-
 - [TokenSearchField](./token-search-field.md) — Token-controlled, optionally collapsible search editor with ordered, editable, removable filter chips.
 - [ResizableRegion](./resize.md) — Pointer and keyboard-operable split region with a customizable handle icon.
 - [Select](./select.md) — Controlled Web Awesome select with typed form, toolbar, navigation, compact, icon-only, truncating, hint, and grouped-choice presentations.
-- [PopupMenu](./popup-menu.md) — A trigger button that opens a typed list of commands, built on the Web Awesome dropdown.
+- [PopupMenu](./popup-menu.md) — A typed action menu with nested choices, selected state, and optional pointer-anchored context opening, built on the Web Awesome dropdown.
 
 ## Kerf UI — Feedback
 

package/ai/components/popup-menu.md

@@ -6,10 +6,11 @@
 
 ## When to use
 
-A trigger button that opens a typed list of commands, built on the Web Awesome dropdown.
+A typed action menu with nested choices, selected state, and optional pointer-anchored context opening, built on the Web Awesome dropdown.
 
 - Offer a short list of commands behind one trigger, such as a toolbar sort or More menu.
 - Group related commands under headings and dividers in one popup.
+- Nest decisions under a parent command, show checked or trailing choice state, or open a context menu at pointer coordinates.
 
 **Not when:**
 
@@ -23,7 +24,7 @@ A trigger button that opens a typed list of commands, built on the Web Awesome d
 
 ## Imports
 
-- JavaScript: `@kerfjs/ui/popup-menu` — exports `PopupMenu`.
+- JavaScript: `@kerfjs/ui/popup-menu` — exports `PopupMenu`, `openPopupMenuAt`, `closePopupMenu`.
 - CSS: the browser build of `@kerfjs/ui/popup-menu` pulls its CSS automatically; import `@kerfjs/ui/popup-menu.css` manually only without the `browser` export condition.
 - Theme CSS: import `@kerfjs/ui/webawesome.css` once.
 - Registration: import `@kerfjs/ui/popup-menu/register` once (a side effect).
@@ -41,6 +42,10 @@ Exact prop names and types: [`@kerfjs/ui/popup-menu`](../public-api-signatures-v
 - headings and dividers
 - item icons
 - disabled items
+- nested actions
+- checked choices and trailing details
+- danger tone and disabled reasons
+- context trigger
 - placement
 
 ## Composition
@@ -52,7 +57,7 @@ Exact prop names and types: [`@kerfjs/ui/popup-menu`](../public-api-signatures-v
 
 ## State and wiring
 
-**The app owns:** commands and their delegated actions; which items are enabled; reactions to the menu opening or closing.
+**The app owns:** commands and their delegated actions; which items are enabled; reactions to the menu opening or closing; contextmenu event handling and identification of the menu root when using a pointer-anchored context menu.
 
 No wiring helper.
 
@@ -62,21 +67,105 @@ Margin: none · border: child · padding: child (layout role: controls). `self`
 
 ## Accessibility
 
-- An icon-only trigger requires label, rendered as visually hidden slotted text because a Web Awesome button takes its accessible name from its content; a trigger with visible text is named by that text. Web Awesome provides menu roles, arrow-key navigation, typeahead, and Escape.
+- An icon-only trigger requires label, rendered as visually hidden slotted text because a Web Awesome button takes its accessible name from its content; a trigger with visible text is named by that text. The context anchor stays out of the accessibility tree. Web Awesome provides menu roles, nested arrow-key navigation, typeahead, and Escape.
 - Once registered, an icon-only trigger shows its label as an aria-hidden Web Awesome help tag after a 500ms hover and at once on keyboard focus; it hides while the menu is open, on a press, and on Escape, and never joins aria-labelledby. Do not add a title or another tooltip.
 
+## Usage examples
+
+### Nested decisions
+
+The app owns the current decision, batch disabled state, and delegated actions. Each child keeps its own record metadata.
+
+```tsx
+<PopupMenu
+  label="Line actions"
+  items={[
+    {
+      label: 'Decide',
+      submenu: [
+        {
+          label: 'Approve',
+          action: 'decide',
+          checked: current === 'approve',
+          attributes: { 'data-line-id': lineId, 'data-decision': 'approve' },
+        },
+        {
+          label: 'Reject',
+          action: 'decide',
+          tone: 'danger',
+          disabled: needsPrice,
+          disabledReason: needsPrice ? 'Add a price first' : undefined,
+          attributes: { 'data-line-id': lineId, 'data-decision': 'reject' },
+        },
+      ],
+    },
+    { kind: 'divider' },
+    { label: 'Remove', action: 'remove', tone: 'danger' },
+  ]}
+/>
+```
+
+### Flat selected choices
+
+Headings separate sort dimensions; trailing safe content marks the active command without changing its accessible label.
+
+```tsx
+<PopupMenu
+  label="Sort chat"
+  items={[
+    { kind: 'heading', label: 'Sort by' },
+    {
+      label: 'Updated',
+      action: 'sort-updated',
+      details: sort === 'updated' ? tick : undefined,
+    },
+    {
+      label: 'Priority',
+      action: 'sort-priority',
+      details: sort === 'priority' ? tick : undefined,
+    },
+    { kind: 'heading', label: 'Order' },
+    {
+      label: 'Newest first',
+      action: 'order-newest',
+      details: order === 'newest' ? tick : undefined,
+    },
+  ]}
+/>
+```
+
+### Pointer anchored context menu
+
+Keep the row's visible disabled action separate from the context menu anchor. Find the menu root with a stable data attribute.
+
+```tsx
+<PopupMenu
+  context
+  label="Demand actions"
+  rootAttributes={{ 'data-demand-menu': '' }}
+  items={[{ label: 'Open', action: 'open-demand' }]}
+/>;
+// In the app's row wiring:
+row.addEventListener('contextmenu', (event) => {
+  event.preventDefault();
+  const menu = row.querySelector('[data-demand-menu]') as PopupMenuElement;
+  openPopupMenuAt(menu, event.clientX, event.clientY);
+});
+// Call closePopupMenu(menu) when the app needs to dismiss 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-popup-menu`, `kui-popup-menu__label`.
+Public class hooks (select for layout placement only, never to change the component's look): `kui-popup-menu`, `kui-popup-menu__label`, `kui-popup-menu__details`, `kui-popup-menu__context-anchor`.
 
-Never put `kui-popup-menu`, `kui-popup-menu__label` on an element you write; render `PopupMenu` instead (`KUI-L103`).
+Never put `kui-popup-menu`, `kui-popup-menu__label`, `kui-popup-menu__details`, `kui-popup-menu__context-anchor` on an element you write; render `PopupMenu` 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: [Dropdown](./wa-dropdown.md), [Dropdown Item](./wa-dropdown-item.md), [Button](./wa-button.md), [Divider](./wa-divider.md), [Select](./select.md).
-- Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/component-selection.md#web-awesome-overlap-policy`](../../docs/component-selection.md#web-awesome-overlap-policy).
+- Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/component-selection.md#popup-menu-migration`](../../docs/component-selection.md#popup-menu-migration).
 - UX catalog route: `?component=popup-menu`.

package/ai/components/text.md

@@ -8,7 +8,7 @@ Semantic native paragraph text by default, with heading and inline-span variants
 
 ## 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 size, or monospace font.
+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.
 
@@ -36,7 +36,7 @@ Exact prop names and types: [`@kerfjs/ui/text`](../public-api-signatures-v1.md#k
 
 - p, h1 through h6, or inline span semantic variant
 - default, quiet, or danger tone
-- default or compact size
+- compact, default, large, or xlarge size
 - default or monospace font
 
 ## Composition
@@ -71,7 +71,7 @@ Public class hooks (select for layout placement only, never to change the compon
 
 Never put `kui-text` 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-mono`, `--kui-font-xs`, `--kui-layout-item-padding`. Set a token only where its public contract allows; prefer a prop.
+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`).
 

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

@@ -21,7 +21,9 @@ Token-controlled, optionally collapsible search editor with ordered, editable, r
 
 ## Imports
 
-- JavaScript: `@kerfjs/ui/token-search-field` — exports `TokenSearchField`, `readTokenSearchField`, `placeTokenSearchCaret`, `wireTokenSearchFields`.
+- JavaScript: `@kerfjs/ui/token-search-field` — exports `TokenSearchField`, `readTokenSearchField`, `placeTokenSearchCaret`.
+- JavaScript: `@kerfjs/ui/wire-token-search-fields` — exports `wireTokenSearchFields`.
+- JavaScript: `@kerfjs/ui/token-search-model` — exports `createTokenSearchModel`.
 - CSS: the browser build of `@kerfjs/ui/token-search-field` pulls its CSS automatically; import `@kerfjs/ui/token-search-field.css` manually only without the `browser` export condition.
 - Wiring: `readTokenSearchField` from `@kerfjs/ui/token-search-field` (required).
 - Wiring: `placeTokenSearchCaret` from `@kerfjs/ui/token-search-field` (optional).
@@ -30,7 +32,7 @@ Token-controlled, optionally collapsible search editor with ordered, editable, r
 
 ## Props
 
-Exact prop names and types: [`@kerfjs/ui/token-search-field`](../public-api-signatures-v1.md#kerfjsuitoken-search-field), [`@kerfjs/ui/wire-token-search-fields`](../public-api-signatures-v1.md#kerfjsuiwire-token-search-fields) in `public-api-signatures-v1.md`. Do not infer props from examples.
+Exact prop names and types: [`@kerfjs/ui/token-search-field`](../public-api-signatures-v1.md#kerfjsuitoken-search-field), [`@kerfjs/ui/wire-token-search-fields`](../public-api-signatures-v1.md#kerfjsuiwire-token-search-fields), [`@kerfjs/ui/token-search-model`](../public-api-signatures-v1.md#kerfjsuitoken-search-model) in `public-api-signatures-v1.md`. Do not infer props from examples.
 
 **Variants (configure, do not restyle):**
 
@@ -82,9 +84,9 @@ Margin: none · border: self · padding: self (layout role: controls). `self` me
 
 The component owns its own styles. Configure it through its props and variants; do not override its internals.
 
-Public class hooks (select for layout placement only, never to change the component's look): `kui-token-search`, `kui-token-search__clear`, `kui-token-search__editor`, `kui-token-search__expand`, `kui-token-search__leading`, `kui-token-search__token`, `kui-token-search__token-edit`, `kui-token-search__token-remove`, `kui-token-search__trailing`.
+Public class hooks (select for layout placement only, never to change the component's look): `kui-token-search`, `kui-token-search__clear`, `kui-token-search__editor`, `kui-token-search__expand`, `kui-token-search__leading`, `kui-token-search__token`, `kui-token-search__token-edit`, `kui-token-search__token-remove`, `kui-token-search__suggestions`, `kui-token-search__suggestion`, `kui-token-search__trailing`.
 
-Never put `kui-token-search`, `kui-token-search__clear`, `kui-token-search__editor`, `kui-token-search__expand`, `kui-token-search__leading`, `kui-token-search__token`, `kui-token-search__token-edit`, `kui-token-search__token-remove`, `kui-token-search__trailing` on an element you write; render `TokenSearchField` instead (`KUI-L103`).
+Never put `kui-token-search`, `kui-token-search__clear`, `kui-token-search__editor`, `kui-token-search__expand`, `kui-token-search__leading`, `kui-token-search__token`, `kui-token-search__token-edit`, `kui-token-search__token-remove`, `kui-token-search__suggestions`, `kui-token-search__suggestion`, `kui-token-search__trailing` on an element you write; render `TokenSearchField` instead (`KUI-L103`).
 
 Public tokens it reads: `--kui-color-brand-fill-normal`, `--kui-color-brand-on-quiet`, `--kui-color-neutral-border-normal`, `--kui-color-text-link`, `--kui-color-surface`, `--kui-color-text`, `--kui-color-text-quiet`, `--kui-focus-ring`, `--kui-font-s`, `--kui-font-xs`, `--kui-radius-pill`, `--kui-token-search-background`, `--kui-token-search-border`, `--kui-token-search-line-size`, `--kui-token-search-token-background`, `--kui-token-search-token-foreground`, `--kui-token-search-expanded-width`. Set a token only where its public contract allows; prefer a prop.
 

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

@@ -14,6 +14,7 @@ Provide complete toolbar action geometry through configuration, including semant
 - 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. Nothing wraps inside a group: an icon sits beside its label on one row and no trigger gets a fixed width.
 - 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.
 
 **Not when:**
 
@@ -50,6 +51,7 @@ Exact prop names and types: [`@kerfjs/ui/toolbar-control-group`](../public-api-s
 - standard, compact, or list-zero dropdown menu inset
 - visible or horizontally scrollable overflow
 - always visible or compact-only responsive visibility
+- relocate on panel collapse
 - avatar scrim
 - contained avatar background on a single group or selected multi-button highlight