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

package/dist/popup-menu.d.ts

@@ -18,9 +18,19 @@ interface PopupMenuItem {
     value?: string;
     /** Leading icon, typically a `LucideIcon`; it is placed in the item's icon slot. */
     icon?: SafeHtml;
+    /** A checked menu choice, including nested choices. */
+    checked?: boolean;
+    /** Trailing safe content, such as a selected-choice tick. */
+    details?: SafeHtml;
+    /** Destructive command styling. */
+    tone?: 'default' | 'danger';
     disabled?: boolean;
+    /** Native tooltip text for a disabled command. */
+    disabledReason?: string;
     /** Application `data-*` metadata such as a record id. */
     attributes?: PopupMenuDataAttributes;
+    /** Child commands opened by hover or keyboard navigation. */
+    submenu?: readonly PopupMenuItem[];
 }
 /** A labeled group heading; items that follow it belong to the group. */
 interface PopupMenuHeading {
@@ -44,7 +54,17 @@ type PopupMenuTriggerName = {
      */
     label: string;
 };
-type PopupMenuProps = PopupMenuTriggerName & {
+type PopupMenuTrigger = (PopupMenuTriggerName & {
+    context?: false;
+}) | {
+    context: true;
+    label: string;
+    text?: never;
+    icon?: never;
+    caret?: never;
+    disabled?: never;
+};
+type PopupMenuProps = PopupMenuTrigger & {
     /** Trigger icon, typically a `LucideIcon`, before any visible text. */
     icon?: KerfUiContent;
     items: readonly PopupMenuEntry[];
@@ -58,6 +78,14 @@ type PopupMenuProps = PopupMenuTriggerName & {
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
 };
+/** A rendered context PopupMenu with Web Awesome's controlled open state. */
+type PopupMenuElement = HTMLElement & {
+    open: boolean;
+};
+/** Open a context PopupMenu at viewport pointer coordinates. */
+declare function openPopupMenuAt(menu: PopupMenuElement, x: number, y: number): void;
+/** Close a programmatically opened PopupMenu. */
+declare function closePopupMenu(menu: PopupMenuElement): void;
 /**
  * An action menu: a trigger button that opens a list of commands. Renders the
  * `wa-dropdown` root directly, so a `single` `ToolbarControlGroup` (with
@@ -66,6 +94,6 @@ type PopupMenuProps = PopupMenuTriggerName & {
  * open-state reaction. Import `@kerfjs/ui/popup-menu/register` once to register
  * the Web Awesome elements.
  */
-declare function PopupMenu({ text, label, icon, items, placement, caret, disabled, rootAttributes, slot, }: PopupMenuProps): SafeHtml;
+declare function PopupMenu({ text, label, icon, items, placement, caret, disabled, rootAttributes, slot, context, }: PopupMenuProps): SafeHtml;
 
-export { PopupMenu, type PopupMenuDivider, type PopupMenuEntry, type PopupMenuHeading, type PopupMenuItem, type PopupMenuPlacement, type PopupMenuProps };
+export { PopupMenu, type PopupMenuDivider, type PopupMenuElement, type PopupMenuEntry, type PopupMenuHeading, type PopupMenuItem, type PopupMenuPlacement, type PopupMenuProps, closePopupMenu, openPopupMenuAt };

package/dist/popup-menu.js

@@ -1,3 +1,3 @@
-export { PopupMenu } from './chunk-WLG6SSNT.js';
+export { PopupMenu, closePopupMenu, openPopupMenuAt } from './chunk-UWONG4QE.js';
 
 //# sourceMappingURL=popup-menu.js.map

package/dist/styles/popup-menu.css

@@ -33,7 +33,7 @@
   scale: none !important;
 }
 
-.kui-popup-menu > wa-dropdown-item {
+.kui-popup-menu wa-dropdown-item {
   /* Leading inset plus the Select's check column, so item icons and labels
      start where a Select option's do. */
   padding: var(--_kui-popup-row-padding-block)
@@ -43,13 +43,13 @@
         var(--_kui-popup-row-check-width)
     );
 }
-.kui-popup-menu > wa-dropdown-item::part(label) {
+.kui-popup-menu wa-dropdown-item::part(label) {
   padding-block: var(--_kui-popup-row-label-padding-block);
   line-height: var(--_kui-popup-row-label-line-height);
 }
 /* A keyboard-focused item is the menu's current row: the Select's brand fill,
    with no second focus ring inside the open popup. */
-.kui-popup-menu > wa-dropdown-item:focus-visible {
+.kui-popup-menu wa-dropdown-item:focus-visible {
   outline: none;
   color: var(--_kui-popup-row-current-color);
   background-color: var(--_kui-popup-row-current-background);
@@ -59,7 +59,7 @@
 }
 
 /* Center the icon on the label's line, like the Select's start slot. */
-.kui-popup-menu > wa-dropdown-item::part(icon) {
+.kui-popup-menu wa-dropdown-item::part(icon) {
   display: flex;
   align-self: center;
 }
@@ -78,6 +78,35 @@
   height: 100%;
 }
 
+.kui-popup-menu__details {
+  display: inline-flex;
+  align-items: center;
+}
+
+.kui-popup-menu__details svg {
+  display: block;
+  width: var(--_kui-popup-row-icon-size);
+  height: var(--_kui-popup-row-icon-size);
+}
+
+.kui-popup-menu[data-trigger="context"] {
+  display: inline-block;
+  width: 0;
+  height: 0;
+}
+
+.kui-popup-menu__context-anchor {
+  position: fixed;
+  top: var(--kui-popup-menu-context-y, 0px);
+  left: var(--kui-popup-menu-context-x, 0px);
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  border: 0;
+  opacity: 0;
+  pointer-events: none;
+}
+
 /* A group title matches the Select's group title. It is a styled element
    rather than a slotted heading, whose Web Awesome metrics are !important. */
 .kui-popup-menu__heading {

package/dist/styles/text.css

@@ -17,6 +17,14 @@
   font-size: var(--kui-font-xs);
 }
 
+.kui-text[data-size="large"] {
+  font-size: var(--kui-font-l);
+}
+
+.kui-text[data-size="xlarge"] {
+  font-size: var(--kui-font-2xl);
+}
+
 .kui-text[data-font="monospace"] {
   font-family: var(--kui-font-mono);
 }

package/dist/styles/token-search-field.css

@@ -145,6 +145,35 @@
   grid-column: 4;
 }
 
+.kui-token-search__suggestions {
+  display: grid;
+  grid-column: 2 / -1;
+  min-width: 0;
+  padding: 0.25rem;
+  border: 1px solid var(--kui-token-search-border);
+  border-radius: var(--kui-radius-pill);
+  background: var(--kui-token-search-background);
+  gap: 0.125rem;
+}
+
+.kui-token-search__suggestion {
+  width: 100%;
+  padding: 0.375rem 0.5rem;
+  border: 0;
+  border-radius: var(--kui-radius-pill);
+  color: var(--kui-color-text);
+  background: transparent;
+  font: inherit;
+  text-align: start;
+  cursor: pointer;
+}
+
+.kui-token-search__suggestion:hover,
+.kui-token-search__suggestion:focus-visible {
+  background: var(--kui-color-surface-lowered);
+  outline: var(--kui-focus-ring);
+}
+
 .kui-token-search[data-has-trailing="false"] .kui-token-search__clear {
   grid-column: 4;
 }

package/dist/text.d.ts

@@ -4,7 +4,7 @@ import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
 type TextVariant = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p' | 'span';
 type TextTone = 'default' | 'quiet' | 'danger';
-type TextSize = 'default' | 'compact';
+type TextSize = 'compact' | 'default' | 'large' | 'xlarge';
 type TextFont = 'default' | 'monospace';
 type TextBorder = 'transparent' | 'none';
 type TextContent = KerfUiContent | string | number | readonly TextContent[];

package/dist/text.js

@@ -1,3 +1,3 @@
-export { Text } from './chunk-24PHKUR3.js';
+export { Text } from './chunk-UXT7TE6B.js';
 
 //# sourceMappingURL=text.js.map

package/dist/token-search-field-CCke1yvQ.d.ts

@@ -0,0 +1,126 @@
+import { Signal, SafeHtml } from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+
+interface TokenSearchRule {
+    /** The word before `:` (for example `tag` or `status`). */
+    name: string;
+    /** Return a canonical value, or undefined to leave invalid input as text. */
+    parse?: (input: string) => string | undefined;
+    /** Label for a committed chip. Defaults to `name:input`. */
+    label?: (value: string, input: string) => string;
+    /** Suggestions for the unfinished value after `name:`. */
+    suggest?: (input: string) => readonly (string | {
+        value: string;
+        label: string;
+    })[];
+}
+interface TokenSearchResolvedToken extends TokenSearchToken {
+    kind: string;
+    parsedValue: string;
+}
+interface TokenSearchState {
+    query: string;
+    tokens: TokenSearchResolvedToken[];
+}
+interface TokenSearchSuggestion {
+    value: string;
+    label: string;
+}
+interface TokenSearchModel<Result = unknown> {
+    state: Signal<TokenSearchState>;
+    /** Changes when a model action must replace DOM-owned editor text. */
+    editorRevision: Signal<number>;
+    suggestions: Signal<readonly TokenSearchSuggestion[]>;
+    result: Signal<Result | undefined>;
+    edit(value: TokenSearchFieldValue, commit?: boolean): void;
+    submit(value: TokenSearchFieldValue): void;
+    choose(value: string): void;
+    expandToken(value: string): void;
+    remove(value: string): void;
+    clear(): void;
+    dismiss(): void;
+}
+interface TokenSearchModelOptions<Result> {
+    rules?: readonly TokenSearchRule[];
+    initial?: TokenSearchFieldValue;
+    /** Runs after every state change, including initial state. */
+    evaluate?: (state: TokenSearchState) => Result;
+    onSubmit?: (state: TokenSearchState, result: Result | undefined) => void;
+}
+/** Opt-in state, token parsing, suggestions, and evaluation for TokenSearchField. */
+declare function createTokenSearchModel<Result = unknown>({ rules, initial, evaluate, onSubmit, }?: TokenSearchModelOptions<Result>): TokenSearchModel<Result>;
+
+interface TokenSearchToken {
+    value: string;
+    label: string;
+    offset?: number;
+    accessibleLabel?: string;
+}
+type TokenSearchEditorAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+    'data-component'?: never;
+    'data-key'?: never;
+    'data-morph-skip'?: never;
+    'data-token-search-editor'?: never;
+    'data-token-count'?: never;
+    'data-placeholder'?: never;
+}>;
+interface TokenSearchFieldBaseProps {
+    id: string;
+    label: string;
+    query?: string;
+    tokens?: readonly TokenSearchToken[];
+    /** Opt-in grammar, suggestion, and evaluation state. Overrides `query` and `tokens`. */
+    model?: TokenSearchModel;
+    /**
+     * Editor identity for a programmatic text replacement. The editor's text is
+     * DOM-owned between token changes, so a new `query` with the same tokens
+     * does not re-render it (that would reset the caret on every keystroke).
+     * Change `revision` when the app replaces the text itself — reseeding a
+     * persistent dialog's field on reopen, applying a saved search — and the
+     * editor is rebuilt from `query` and `tokens`.
+     */
+    revision?: string | number;
+    placeholder?: string;
+    tokenPlaceholder?: string;
+    disabled?: boolean;
+    autofocus?: boolean;
+    leading?: KerfUiContent;
+    trailing?: KerfUiContent;
+    /** Standalone field chrome or the inset visual layer of a configured toolbar group. */
+    presentation?: 'standalone' | 'toolbar-group';
+    editAction?: string;
+    removeAction?: string;
+    clearAction?: string;
+    clearLabel?: string;
+    /** Icon for the clear button. Default: the Lucide `x` glyph token chips also use. */
+    clearIcon?: SafeHtml;
+    className?: string;
+    editorAttributes?: TokenSearchEditorAttributes;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
+}
+type TokenSearchCollapsibleProps = {
+    /** Allow an empty field to render as one iconic action. */
+    collapsible: true;
+    /** Keep an empty collapsible field open while the application owns focus. */
+    expanded?: boolean;
+    expandAction?: string;
+    expandLabel?: string;
+} | {
+    collapsible?: false;
+    expanded?: never;
+    expandAction?: never;
+    expandLabel?: never;
+};
+type TokenSearchFieldProps = TokenSearchFieldBaseProps & TokenSearchCollapsibleProps;
+interface TokenSearchFieldValue {
+    query: string;
+    tokens: TokenSearchToken[];
+}
+declare function TokenSearchField({ id, label, query, tokens, model, revision, placeholder, tokenPlaceholder, disabled, autofocus, collapsible, expanded, expandAction, expandLabel, leading, trailing, presentation, editAction, removeAction, clearAction, clearLabel, clearIcon, className, editorAttributes, slot, }: TokenSearchFieldProps): SafeHtml;
+/** Read editable text and ordered token offsets from a rendered TokenSearchField editor. */
+declare function readTokenSearchField(editor: HTMLElement, knownTokens?: readonly TokenSearchToken[]): TokenSearchFieldValue;
+/** Focus an editor and place its caret at a text offset, skipping atomic token chips. */
+declare function placeTokenSearchCaret(editor: HTMLElement, offset?: number): void;
+
+export { type TokenSearchEditorAttributes as T, TokenSearchField as a, type TokenSearchFieldProps as b, type TokenSearchFieldValue as c, type TokenSearchModel as d, type TokenSearchModelOptions as e, type TokenSearchResolvedToken as f, type TokenSearchRule as g, type TokenSearchState as h, type TokenSearchSuggestion as i, type TokenSearchToken as j, createTokenSearchModel as k, placeTokenSearchCaret as p, readTokenSearchField as r };

package/dist/token-search-field.d.ts

@@ -1,75 +1,3 @@
-import { SafeHtml } from 'kerfjs';
-import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
-
-interface TokenSearchToken {
-    value: string;
-    label: string;
-    offset?: number;
-    accessibleLabel?: string;
-}
-type TokenSearchEditorAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
-    'data-component'?: never;
-    'data-key'?: never;
-    'data-morph-skip'?: never;
-    'data-token-search-editor'?: never;
-    'data-token-count'?: never;
-    'data-placeholder'?: never;
-}>;
-interface TokenSearchFieldBaseProps {
-    id: string;
-    label: string;
-    query?: string;
-    tokens?: readonly TokenSearchToken[];
-    /**
-     * Editor identity for a programmatic text replacement. The editor's text is
-     * DOM-owned between token changes, so a new `query` with the same tokens
-     * does not re-render it (that would reset the caret on every keystroke).
-     * Change `revision` when the app replaces the text itself — reseeding a
-     * persistent dialog's field on reopen, applying a saved search — and the
-     * editor is rebuilt from `query` and `tokens`.
-     */
-    revision?: string | number;
-    placeholder?: string;
-    tokenPlaceholder?: string;
-    disabled?: boolean;
-    autofocus?: boolean;
-    leading?: KerfUiContent;
-    trailing?: KerfUiContent;
-    /** Standalone field chrome or the inset visual layer of a configured toolbar group. */
-    presentation?: 'standalone' | 'toolbar-group';
-    editAction?: string;
-    removeAction?: string;
-    clearAction?: string;
-    clearLabel?: string;
-    /** Icon for the clear button. Default: the Lucide `x` glyph token chips also use. */
-    clearIcon?: SafeHtml;
-    className?: string;
-    editorAttributes?: TokenSearchEditorAttributes;
-    /** Native named-slot assignment when composed inside a web component. */
-    slot?: string;
-}
-type TokenSearchCollapsibleProps = {
-    /** Allow an empty field to render as one iconic action. */
-    collapsible: true;
-    /** Keep an empty collapsible field open while the application owns focus. */
-    expanded?: boolean;
-    expandAction?: string;
-    expandLabel?: string;
-} | {
-    collapsible?: false;
-    expanded?: never;
-    expandAction?: never;
-    expandLabel?: never;
-};
-type TokenSearchFieldProps = TokenSearchFieldBaseProps & TokenSearchCollapsibleProps;
-interface TokenSearchFieldValue {
-    query: string;
-    tokens: TokenSearchToken[];
-}
-declare function TokenSearchField({ id, label, query, tokens, revision, placeholder, tokenPlaceholder, disabled, autofocus, collapsible, expanded, expandAction, expandLabel, leading, trailing, presentation, editAction, removeAction, clearAction, clearLabel, clearIcon, className, editorAttributes, slot, }: TokenSearchFieldProps): SafeHtml;
-/** Read editable text and ordered token offsets from a rendered TokenSearchField editor. */
-declare function readTokenSearchField(editor: HTMLElement, knownTokens?: readonly TokenSearchToken[]): TokenSearchFieldValue;
-/** Focus an editor and place its caret at a text offset, skipping atomic token chips. */
-declare function placeTokenSearchCaret(editor: HTMLElement, offset?: number): void;
-
-export { type TokenSearchEditorAttributes, TokenSearchField, type TokenSearchFieldProps, type TokenSearchFieldValue, type TokenSearchToken, placeTokenSearchCaret, readTokenSearchField };
+import 'kerfjs';
+import './semantic-content-BbzjvSu9.js';
+export { T as TokenSearchEditorAttributes, a as TokenSearchField, b as TokenSearchFieldProps, c as TokenSearchFieldValue, j as TokenSearchToken, p as placeTokenSearchCaret, r as readTokenSearchField } from './token-search-field-CCke1yvQ.js';

package/dist/token-search-field.js

@@ -1,4 +1,4 @@
-export { TokenSearchField, placeTokenSearchCaret, readTokenSearchField } from './chunk-63ZWBGE3.js';
+export { TokenSearchField, placeTokenSearchCaret, readTokenSearchField } from './chunk-RRB26JRJ.js';
 
 
 //# sourceMappingURL=token-search-field.js.map

package/dist/token-search-model.d.ts

@@ -0,0 +1,3 @@
+import 'kerfjs';
+export { d as TokenSearchModel, e as TokenSearchModelOptions, f as TokenSearchResolvedToken, g as TokenSearchRule, h as TokenSearchState, i as TokenSearchSuggestion, k as createTokenSearchModel } from './token-search-field-CCke1yvQ.js';
+import './semantic-content-BbzjvSu9.js';

package/dist/token-search-model.js

@@ -0,0 +1,3 @@
+export { createTokenSearchModel } from './chunk-F7F7KRO2.js';
+
+//# sourceMappingURL=token-search-model.js.map

package/dist/token-search-model.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"token-search-model.js"}

package/dist/wire-token-search-fields.d.ts

@@ -1,4 +1,6 @@
 import { Signal } from 'kerfjs';
+import { d as TokenSearchModel } from './token-search-field-CCke1yvQ.js';
+import './semantic-content-BbzjvSu9.js';
 
 interface TokenSearchSubmit {
     id: string;
@@ -76,6 +78,8 @@ interface TokenSearchCollapsibleOptions {
     signals?: Readonly<Record<string, Signal<boolean>>>;
 }
 interface WireTokenSearchFieldsOptions {
+    /** Optional automatic grammar/suggestion models, keyed by TokenSearchField id. */
+    models?: Readonly<Record<string, TokenSearchModel>>;
     onSubmit?: (submission: TokenSearchSubmit) => void;
     /** Fired on every editor `input`, after the browser mutates it, so a caller can drop its own `input` listener. */
     onEdit?: (edit: TokenSearchEdit) => void;
@@ -106,6 +110,6 @@ interface TokenSearchFieldsHandle {
  * expand/collapse/focus. Returns a {@link TokenSearchFieldsHandle} — a disposer that also
  * exposes the managed `expanded` state per field id.
  */
-declare function wireTokenSearchFields(root: HTMLElement, { onSubmit, onEdit, collapsible, keyboard, }?: WireTokenSearchFieldsOptions): TokenSearchFieldsHandle;
+declare function wireTokenSearchFields(root: HTMLElement, { models, onSubmit, onEdit, collapsible, keyboard, }?: WireTokenSearchFieldsOptions): TokenSearchFieldsHandle;
 
 export { type TokenSearchCollapsibleOptions, type TokenSearchEdit, type TokenSearchFieldsHandle, type TokenSearchKeyboardOptions, type TokenSearchSubmit, type TokenSearchTokenRemoval, type WireTokenSearchFieldsOptions, wireTokenSearchFields };

package/dist/wire-token-search-fields.js

@@ -1,4 +1,4 @@
-export { wireTokenSearchFields } from './chunk-NBYTIVHS.js';
+export { wireTokenSearchFields } from './chunk-UFYZHYWU.js';
 
 
 

package/docs/accessibility.md

@@ -195,6 +195,12 @@ are presentational. A keyboard-focused item is the menu's current row, painted
 with the Select's current-option fill rather than a second focus ring inside the
 open popup. A disabled item stays in the menu but cannot be
 chosen; disable the whole trigger only when every command is unavailable.
+Nested items use Web Awesome's submenu pointer and Left/Right arrow routing;
+checked items expose checkbox menu semantics. `details` supplies optional
+trailing visual content without changing a command's accessible label. A
+`context` menu's invisible anchor is outside the accessibility tree and normal
+Tab order; opening the menu moves focus into its commands and Escape dismisses
+it. Keep a separate visible row action named even when it is disabled.
 
 ## ListActionRow
 
@@ -405,6 +411,14 @@ originating `InputEvent` so a caller can gate on `inputType`/`data` — fires on
 `input`, letting a caller drop its own `input` listener; the application still
 owns query parsing and result-count/loading announcements.
 
+With a `createTokenSearchModel` passed to the field and registered in
+`wireTokenSearchFields(root, { models })`, grammar parsing, chips, clear/edit/
+remove actions, and suggestions are managed. Arrow Down moves from the editor
+to suggestions, arrow keys move between suggestions, Enter selects one, and
+Escape returns focus to the editor. The application still announces results
+when needed and can supply an `evaluate` callback to compute them. Omitting the
+model leaves the manual behavior above intact.
+
 Managed clear captures the action before application handlers run, keeps the adopted
 expanded signal open during editor replacement, and restores focus at the actual
 mutation checkpoint before the next input task. It also returns keyboard activation

package/docs/component-contract.md

@@ -50,7 +50,8 @@ responsive ownership, layout and geometry, accessibility obligations, public
 CSS boundaries, diagnostics, and provenance. A wrapper entry may add
 `rendersAs`: the cataloged roots it renders (any one of them, or nothing), so
 composition checks treat its elements as each root rather than as an unknown
-child.
+child. A placement with listed parent constraints produces one `KUI-L201`
+diagnostic even when both the wrapper and a rendered root reject that parent.
 
 `boundaries.placeableClasses` names the subset of `publicClasses` an
 application may write onto its own elements (layout utilities, the document

package/docs/component-integration.md

@@ -33,7 +33,14 @@ For each catalog component, the validator checks:
 The existing catalog sync and compatibility gates remain responsible for the
 typed catalog projections, catalog count/order, and artifact digests. Public
 API signatures derive component subpaths from the catalog, so a newly cataloged
-component can no longer be silently omitted from that corpus.
+component can no longer be silently omitted from that corpus. Overrides in
+`publicExportImports` also add their subpaths to the signature reference.
+
+Generated component pages group `publicExports` by import subpath. Exports use
+the component `delivery.browserImport` or `delivery.moduleImport` by default;
+set `publicExportImports` for helpers shipped from a different subpath. The
+catalog check verifies each override names a public export and a package
+subpath, and the generated Props section links each relevant signature.
 
 Non-component helpers, wiring modules, compositions, recipes, and development
 tools remain explicit package surfaces. They do not masquerade as visual

package/docs/component-selection.md

@@ -210,6 +210,8 @@ an upstream component or recipe request.
   hidden compact replacement and keeps compact overlays exclusive by default.
 - `TokenSearchField` is a structured editor. A native input or `wa-input` is the right answer for ordinary text.
 
+For common structured search, use `createTokenSearchModel` from `@kerfjs/ui/token-search-model`, pass the model to `TokenSearchField`, and register it under the field id in `wireTokenSearchFields(root, { models })`. Rules parse `name:value` expressions and provide suggestions; the model owns chips, selection, removal, clear, and an optional evaluation result. Omit `model` and `models` for full manual control.
+
 ## Toolbar composition
 
 A `Toolbar` has three zones — `leading`, `center`, and `trailing`. In almost
@@ -250,6 +252,8 @@ Common toolbar patterns:
 | A command menu                | `<ToolbarControlGroup single nestedDropdown><PopupMenu … /></ToolbarControlGroup>`     | Register `@kerfjs/ui/popup-menu/register` once; set `menuInset` on the group                                      |
 | A collapsible search box      | `<ToolbarControlGroup single><TokenSearchField collapsible … /></ToolbarControlGroup>` | The group animates the iconic ↔ expanded states; `wireTokenSearchFields` manages expand/collapse/focus by default |
 
+### Popup menu migration
+
 A **popup menu in a toolbar** is a `PopupMenu` (`@kerfjs/ui/popup-menu`) in a
 `single` `ToolbarControlGroup` with `nestedDropdown`; the group sizes the trigger
 as a toolbar button and `menuInset` sets the menu's inset. `PopupMenu` renders the
@@ -271,6 +275,42 @@ menu.
 </ToolbarControlGroup>
 ```
 
+Nested decisions use an item with `submenu`. Children keep their own actions,
+`attributes` metadata, icons, `checked` state, disabled state and
+`disabledReason` tooltip. `tone: 'danger'` maps to the Web Awesome destructive
+variant. A parent can sit among ordinary commands and dividers, so the same
+items shape covers single-line and batch actions; compute each batch child's
+`disabled` state from the current selection.
+
+```tsx
+<PopupMenu
+  label="Line actions"
+  items={[
+    { label: 'Copy reference', action: 'copy-reference', attributes: { 'data-item-id': lineId } },
+    { label: 'Decide', submenu: [
+      { label: 'Approve', action: 'decide', checked: current === 'approve', attributes: { 'data-item-id': lineId, 'data-decision': 'approve' } },
+      { label: 'Reject', action: 'decide', tone: 'danger', disabled: needsPrice, disabledReason: needsPrice ? 'Add a price first' : undefined, attributes: { 'data-item-id': lineId, 'data-decision': 'reject' } },
+    ] },
+    { kind: 'divider' },
+    { label: 'Remove', action: 'remove', tone: 'danger' },
+  ]}
+/>
+```
+
+For a flat command menu with persistent sort choices, group commands under
+`heading` entries and set `details` to a safe trailing tick for the chosen
+item. Set `checked` when checkbox menu semantics fit. Commands still dispatch
+their own `data-action` once on pointer and keyboard selection.
+
+For a row opened by right-click, render `PopupMenu` with `context`, `label`,
+and a stable root `data-*` marker. Its trigger is an invisible anchor removed
+from the accessibility tree; a separate visible button may stay disabled. In
+the app's `contextmenu` handler, find that root, call `openPopupMenuAt` with
+the menu and `event.clientX` / `event.clientY`, and prevent the browser
+menu. Call `closePopupMenu` for programmatic dismissal. The pointer anchor
+retains Web Awesome's collision placement, focus management, submenu keyboard
+navigation, and outside/Escape dismissal.
+
 ## Configuring recurring list rows
 
 Configure the List family instead of selecting its descendant classes. Use

package/docs/layout.md

@@ -285,7 +285,8 @@ rail) and pane identity should stay quiet.
 
 Presentation is independent of the native element: use `tone="quiet"` for
 supporting copy, `tone="danger"` for error or validation copy, `size="compact"`
-for compact metadata, and `font="monospace"` for code or identifiers (the
+for compact metadata, `size="large"` for prominent copy, `size="xlarge"` for
+display copy, and `font="monospace"` for code or identifiers (the
 `--kui-font-mono` stack, which Kerf owns even with Web Awesome loaded). These
 finite props compose with each other and with every semantic `variant`; omit
 them to inherit the surrounding color, size, and font.
@@ -297,6 +298,8 @@ import { Text } from "@kerfjs/ui/text";
 <Text variant="h3">Notifications</Text>; // normal-color subsection title
 <Text aria-describedby="details-title">Supporting copy</Text>;
 <Text tone="quiet" size="compact">Updated yesterday</Text>;
+<Text size="large">A prominent summary</Text>;
+<Text variant="h2" size="xlarge">A display-sized section title</Text>;
 <strong>Inbox<Text variant="span" tone="quiet" size="compact"> · 3 msg</Text></strong>;
 <Text tone="danger" font="monospace">ERR_INVALID_ID</Text>;
 ```

package/llms.txt

@@ -242,7 +242,10 @@ headingLevel`, `TokenSearchField clearIcon`, `ContentItem frame="framed"` for a
   (`@kerfjs/ui/popup-menu`, registered once via `@kerfjs/ui/popup-menu/register`)
   in a `single` `ToolbarControlGroup` with `nestedDropdown`; never hand-write
   `wa-dropdown` markup for a menu. Let the group size the trigger from its icon,
-  localized text, and caret; do not force a dropdown or button width. Nothing
+  localized text, and caret. `PopupMenu` items also support nested `submenu`
+  actions, checked or trailing choice marks, danger tone, and disabled reasons;
+  use `context` with `openPopupMenuAt`/`closePopupMenu` for pointer-anchored row
+  menus. Do not force a dropdown or button width. Nothing
   wraps inside a group: an icon sits beside its label on one row, and a
   `ToolbarText` is one ellipsized line unless you opt into `wrap`/`maxLines`. A
   Select or PopupMenu trigger drops its focus ring while its popup is open and
@@ -265,8 +268,8 @@ headingLevel`, `TokenSearchField clearIcon`, `ContentItem frame="framed"` for a
   text outside toolbar title zones.** Omit `variant` for the default `p`, pass
   `h1`–`h6` based on the document outline, or use `variant="span"` inside a row,
   label, or table cell without adding box geometry. Independently compose `tone="quiet|danger"`,
-  `size="compact"`, and `font="monospace"` for supporting, error, compact, and
-  code roles instead of global utility classes. It passes native attributes
+  `size="compact|large|xlarge"`, and `font="monospace"` for supporting, error,
+  compact, prominent, display, and code roles instead of global utility classes. It passes native attributes
   through; block variants own the standard transparent border plus item padding, while `span` owns none. Keep
   toolbar titles on `ToolbarText` and list-aligned bare prose on `ListInsetText`.
 - **Space by the five-step scale, by relationship not by eye.** `0`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kerfjs/ui",
-  "version": "5.0.0-beta.58",
+  "version": "5.0.0-beta.59",
   "description": "Accessible, composable UI primitives for kerf applications.",
   "type": "module",
   "license": "MIT",
@@ -281,6 +281,10 @@
       "browser": "./dist/browser/token-search-field.js",
       "import": "./dist/token-search-field.js"
     },
+    "./token-search-model": {
+      "types": "./dist/token-search-model.d.ts",
+      "import": "./dist/token-search-model.js"
+    },
     "./wire-token-search-fields": {
       "types": "./dist/wire-token-search-fields.d.ts",
       "import": "./dist/wire-token-search-fields.js"

package/dist/chunk-24PHKUR3.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/text.tsx"],"names":[],"mappings":";;;AAsCO,SAAS,IAAA,CAAK;AAAA,EACnB,SAAS,OAAA,GAAU,GAAA;AAAA,EACnB,IAAA,GAAO,SAAA;AAAA,EACP,IAAA,GAAO,SAAA;AAAA,EACP,IAAA,GAAO,SAAA;AAAA,EACP,MAAA,GAAS,aAAA;AAAA,EACT,QAAA;AAAA,EACA,OAAO,UAAA,GAAa,EAAA;AAAA,EACpB,SAAA,GAAY,EAAA;AAAA,EACZ,GAAG;AACL,CAAA,EAAc;AACZ,EAAA,MAAM,OAAA,GAAU,CAAC,UAAA,EAAY,UAAA,EAAY,SAAS,EAAE,MAAA,CAAO,OAAO,CAAA,CAAE,IAAA,CAAK,GAAG,CAAA;AAC5E,EAAA,uBACE,GAAA;AAAA,IAAC,OAAA;AAAA,IAAA;AAAA,MACE,GAAG,UAAA;AAAA,MACJ,KAAA,EAAO,OAAA;AAAA,MACP,gBAAA,EAAe,MAAA;AAAA,MACf,WAAA,EAAW,IAAA;AAAA,MACX,WAAA,EAAW,IAAA;AAAA,MACX,WAAA,EAAW,IAAA;AAAA,MACX,aAAA,EAAa,MAAA;AAAA,MAEZ;AAAA;AAAA,GACH;AAEJ","file":"chunk-24PHKUR3.js","sourcesContent":["import type { KerfBaseAttrs } from 'kerfjs/jsx-runtime';\n\nimport type { KerfUiContent } from './semantic-content.js';\n\nexport type TextVariant =\n  'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p' | 'span';\nexport type TextTone = 'default' | 'quiet' | 'danger';\nexport type TextSize = 'default' | 'compact';\nexport type TextFont = 'default' | 'monospace';\nexport type TextBorder = 'transparent' | 'none';\n\nexport type TextContent =\n  KerfUiContent | string | number | readonly TextContent[];\n\nexport type TextProps = Omit<\n  KerfBaseAttrs,\n  'children' | 'class' | 'className'\n> & {\n  /** Native heading, paragraph, or inline span element to render. Defaults to `p`. */\n  variant?: TextVariant;\n  /** Semantic foreground treatment. Defaults to the inherited foreground. */\n  tone?: TextTone;\n  /** Text sizing independent of the native semantic element. */\n  size?: TextSize;\n  /** Font family independent of the native semantic element. */\n  font?: TextFont;\n  /** Transparent alignment border or no border when embedded in owner chrome. */\n  border?: TextBorder;\n  children: TextContent;\n  class?: string;\n  className?: string;\n};\n\n/**\n * Semantic heading, paragraph, or inline text. Block variants use the standard\n * content-item padding; `span` adds no box geometry.\n * All ordinary native heading/paragraph attributes pass through to the element.\n */\nexport function Text({\n  variant: Variant = 'p',\n  tone = 'default',\n  size = 'default',\n  font = 'default',\n  border = 'transparent',\n  children,\n  class: classValue = '',\n  className = '',\n  ...attributes\n}: TextProps) {\n  const classes = ['kui-text', classValue, className].filter(Boolean).join(' ');\n  return (\n    <Variant\n      {...attributes}\n      class={classes}\n      data-component=\"text\"\n      data-tone={tone}\n      data-size={size}\n      data-font={font}\n      data-border={border}\n    >\n      {children}\n    </Variant>\n  );\n}\n"]}