@kerfjs/ui 5.0.0-beta.70 → 5.0.0-beta.72

package/ai/component-catalog.json

@@ -187,6 +187,18 @@
       },
       "wiring": [],
       "publicClasses": [],
+      "rootElement": "svg",
+      "descendantRootAttribute": "data-lucide",
+      "descendantElements": [
+        "circle",
+        "ellipse",
+        "g",
+        "line",
+        "path",
+        "polygon",
+        "polyline",
+        "rect"
+      ],
       "publicTokens": [],
       "links": {
         "catalogRoute": "?component=lucide-icon",
@@ -1492,7 +1504,8 @@
       "description": "Leading, centered, and trailing toolbar composition.",
       "uses": [
         "toolbar-text",
-        "toolbar-control-group"
+        "toolbar-control-group",
+        "wa-button"
       ],
       "purpose": "Leading, centered, and trailing toolbar composition.",
       "publicExports": [
@@ -1520,7 +1533,7 @@
         "content-driven wrap that keeps a heading title whole",
         "center priority for an expanded center control",
         "trailing priority for an expanded trailing control at compact or narrow widths",
-        "trailing groups wrap instead of clipping",
+        "trailing groups and a standalone primary wa-button wrap instead of clipping",
         "outer inset independently configurable from zone gap",
         "app bar or bottom bar claiming its screen edges (safeAreaEdges)"
       ],
@@ -1886,7 +1899,8 @@
         "ToolbarText"
       ],
       "useWhen": [
-        "Render toolbar identity or heading text at a supported hierarchy size; pass headingLevel for heading semantics."
+        "Render toolbar identity or heading text at a supported hierarchy size; pass headingLevel for heading semantics.",
+        "Use action for an editable toolbar title: it renders a native button that shrinks and ellipsizes beside sibling status chips."
       ],
       "avoidWhen": [
         "Do not omit headingLevel when the text is the page or section heading.",
@@ -1906,7 +1920,8 @@
       ],
       "appOwns": [
         "text",
-        "responsive priority"
+        "responsive priority",
+        "the delegated action handler and display-to-input editing swap"
       ],
       "variants": [
         "xlarge",
@@ -1918,7 +1933,8 @@
         "placeholder (loading)"
       ],
       "accessibility": [
-        "Plain text is not a heading; pass headingLevel to expose role=heading + aria-level for a page/section title."
+        "Plain text is not a heading; pass headingLevel to expose role=heading + aria-level for a page/section title.",
+        "Actionable text is a native button with its full text as its accessible name; action cannot be combined with headingLevel, placeholder, or wrap."
       ],
       "geometry": {
         "margin": "none",

package/ai/component-catalog.schema.json

@@ -61,6 +61,8 @@
         "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 },
         "rootElement": { "description": "The intrinsic element the component renders at its root. Required when a component renders placeableClasses; also enables classless child-root ownership checks.", "type": "string", "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$" },
+        "descendantRootAttribute": { "description": "A root data attribute that anchors ownership checks for arbitrary unclassed descendant tags; requires rootElement.", "type": "string", "pattern": "^data-[a-z][a-z0-9]*(?:-[a-z0-9]+)*$" },
+        "descendantElements": { "description": "Intrinsic element tags the component can render below its root, for composed-child selector ownership checks.", "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$" }, "uniqueItems": true },
         "publicTokens": { "type": "array", "items": { "type": "string" }, "uniqueItems": true },
         "cssValueProps": { "type": "array", "items": { "$ref": "#/$defs/cssValueProp" }, "uniqueItems": true },
         "geometry": { "$ref": "#/$defs/geometry" },

package/ai/component-composition-rules.json

@@ -25,22 +25,22 @@
       {
         "id": "trailing",
         "jsx": { "prop": "trailing" },
-        "accepts": ["toolbar-text", "toolbar-control-group"],
+        "accepts": ["toolbar-text", "toolbar-control-group", "wa-button"],
         "cardinality": { "min": 0, "max": "unbounded" },
         "exclusiveWith": []
       }
     ],
     "children": {
       "mode": "listed",
-      "concepts": ["toolbar-text", "toolbar-control-group"],
+      "concepts": ["toolbar-text", "toolbar-control-group", "wa-button"],
       "requiredConcepts": []
     },
     "diagnostics": [
       {
         "id": "KUI-C101",
         "severity": "error",
-        "when": "a direct zone child is neither ToolbarText nor ToolbarControlGroup",
-        "message": "Wrap toolbar controls in ToolbarControlGroup; only ToolbarText and ToolbarControlGroup are direct zone children."
+        "when": "a direct zone child is neither ToolbarText nor ToolbarControlGroup nor a standalone wa-button in trailing",
+        "message": "Wrap toolbar controls in ToolbarControlGroup; only ToolbarText and ToolbarControlGroup, plus one standalone primary wa-button in trailing, are direct zone children."
       }
     ]
   },

package/ai/component-composition.d.ts

@@ -111,6 +111,8 @@ export interface CatalogCompositionEntry {
     placeableClasses?: string[];
     /** The intrinsic element the component renders at its root; a placeable class on a plain element of this tag recreates the component. */
     rootElement?: string;
+    descendantElements?: string[];
+    descendantRootAttribute?: string;
     publicTokens: string[];
     publicParts?: string[];
   };

package/ai/component-composition.json

@@ -148,6 +148,18 @@
       "boundaries": {
         "rootClass": null,
         "publicClasses": [],
+        "rootElement": "svg",
+        "descendantElements": [
+          "circle",
+          "ellipse",
+          "g",
+          "line",
+          "path",
+          "polygon",
+          "polyline",
+          "rect"
+        ],
+        "descendantRootAttribute": "data-lucide",
         "publicTokens": []
       },
       "diagnostics": [],
@@ -1412,14 +1424,14 @@
         {
           "id": "trailing",
           "jsx": { "prop": "trailing" },
-          "accepts": ["toolbar-text", "toolbar-control-group"],
+          "accepts": ["toolbar-text", "toolbar-control-group", "wa-button"],
           "cardinality": { "min": 0, "max": "unbounded" },
           "exclusiveWith": []
         }
       ],
       "children": {
         "mode": "listed",
-        "concepts": ["toolbar-text", "toolbar-control-group"],
+        "concepts": ["toolbar-text", "toolbar-control-group", "wa-button"],
         "requiredConcepts": []
       },
       "state": [
@@ -1505,8 +1517,8 @@
         {
           "id": "KUI-C101",
           "severity": "error",
-          "when": "a direct zone child is neither ToolbarText nor ToolbarControlGroup",
-          "message": "Wrap toolbar controls in ToolbarControlGroup; only ToolbarText and ToolbarControlGroup are direct zone children."
+          "when": "a direct zone child is neither ToolbarText nor ToolbarControlGroup nor a standalone wa-button in trailing",
+          "message": "Wrap toolbar controls in ToolbarControlGroup; only ToolbarText and ToolbarControlGroup, plus one standalone primary wa-button in trailing, are direct zone children."
         }
       ],
       "provenance": {
@@ -1748,6 +1760,11 @@
           "id": "responsive priority",
           "owner": "application",
           "required": false
+        },
+        {
+          "id": "the delegated action handler and display-to-input editing swap",
+          "owner": "application",
+          "required": false
         }
       ],
       "wiring": {
@@ -1763,7 +1780,8 @@
       },
       "accessibility": {
         "obligations": [
-          "Plain text is not a heading; pass headingLevel to expose role=heading + aria-level for a page/section title."
+          "Plain text is not a heading; pass headingLevel to expose role=heading + aria-level for a page/section title.",
+          "Actionable text is a native button with its full text as its accessible name; action cannot be combined with headingLevel, placeholder, or wrap."
         ]
       },
       "cssValueProps": [],

package/ai/component-composition.schema.json

@@ -335,6 +335,15 @@
               "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$",
               "description": "The intrinsic element the component renders at its root. It identifies composed child roots for ownership checks; a placeableClasses class on a plain element of this tag recreates the component, while the class stays placeable on another carrier."
             },
+            "descendantElements": {
+              "$ref": "#/$defs/stringList",
+              "description": "Intrinsic element tags that can appear below the component root."
+            },
+            "descendantRootAttribute": {
+              "type": "string",
+              "pattern": "^data-[a-z][a-z0-9]*(?:-[a-z0-9]+)*$",
+              "description": "Root data attribute anchoring ownership of arbitrary unclassed descendants."
+            },
             "publicTokens": { "$ref": "#/$defs/stringList" },
             "publicParts": { "$ref": "#/$defs/stringList" }
           },

package/ai/components/toolbar-text.md

@@ -9,6 +9,7 @@
 Extra-large through extra-small toolbar identity text.
 
 - Render toolbar identity or heading text at a supported hierarchy size; pass headingLevel for heading semantics.
+- Use action for an editable toolbar title: it renders a native button that shrinks and ellipsizes beside sibling status chips.
 
 **Not when:**
 
@@ -48,7 +49,7 @@ Exact prop names and types: [`@kerfjs/ui/toolbar-text`](../public-api-signatures
 
 ## State and wiring
 
-**The app owns:** text; responsive priority.
+**The app owns:** text; responsive priority; the delegated action handler and display-to-input editing swap.
 
 No wiring helper.
 
@@ -59,6 +60,7 @@ Margin: none · border: none · padding: none (layout role: structure). `self` m
 ## Accessibility
 
 - Plain text is not a heading; pass headingLevel to expose role=heading + aria-level for a page/section title.
+- Actionable text is a native button with its full text as its accessible name; action cannot be combined with headingLevel, placeholder, or wrap.
 
 ## Styling boundary
 

package/ai/components/toolbar.md

@@ -35,7 +35,7 @@ Exact prop names and types: [`@kerfjs/ui/toolbar`](../public-api-signatures-v1.m
 - content-driven wrap that keeps a heading title whole
 - center priority for an expanded center control
 - trailing priority for an expanded trailing control at compact or narrow widths
-- trailing groups wrap instead of clipping
+- trailing groups and a standalone primary wa-button wrap instead of clipping
 - outer inset independently configurable from zone gap
 - app bar or bottom bar claiming its screen edges (safeAreaEdges)
 
@@ -43,14 +43,14 @@ Exact prop names and types: [`@kerfjs/ui/toolbar`](../public-api-signatures-v1.m
 
 - Parents: any.
 - Contexts: `application-chrome`, `page-header`, `panel-header`, `dialog-header`.
-- Children: only [ToolbarText](./toolbar-text.md), [ToolbarControlGroup](./toolbar-control-group.md).
-- Built from: [ToolbarText](./toolbar-text.md), [ToolbarControlGroup](./toolbar-control-group.md).
+- Children: only [ToolbarText](./toolbar-text.md), [ToolbarControlGroup](./toolbar-control-group.md), [Button](./wa-button.md).
+- Built from: [ToolbarText](./toolbar-text.md), [ToolbarControlGroup](./toolbar-control-group.md), [Button](./wa-button.md).
 
 Zones (a zone is bound to JSX only through its listed prop; never assume the zone id is a prop):
 
 - `leading` — JSX prop `leading`; accepts [ToolbarText](./toolbar-text.md), [ToolbarControlGroup](./toolbar-control-group.md); any number.
 - `center` — JSX prop `center`; accepts [ToolbarText](./toolbar-text.md), [ToolbarControlGroup](./toolbar-control-group.md); any number.
-- `trailing` — JSX prop `trailing`; accepts [ToolbarText](./toolbar-text.md), [ToolbarControlGroup](./toolbar-control-group.md); any number.
+- `trailing` — JSX prop `trailing`; accepts [ToolbarText](./toolbar-text.md), [ToolbarControlGroup](./toolbar-control-group.md), [Button](./wa-button.md); any number.
 
 ## State and wiring
 
@@ -88,10 +88,10 @@ Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-
 
 ## Diagnostics
 
-- `KUI-C101` (error) when a direct zone child is neither ToolbarText nor ToolbarControlGroup: Wrap toolbar controls in ToolbarControlGroup; only ToolbarText and ToolbarControlGroup are direct zone children.
+- `KUI-C101` (error) when a direct zone child is neither ToolbarText nor ToolbarControlGroup nor a standalone wa-button in trailing: Wrap toolbar controls in ToolbarControlGroup; only ToolbarText and ToolbarControlGroup, plus one standalone primary wa-button in trailing, are direct zone children.
 
 ## Related
 
-- Components: [ToolbarText](./toolbar-text.md), [ToolbarControlGroup](./toolbar-control-group.md).
+- Components: [ToolbarText](./toolbar-text.md), [ToolbarControlGroup](./toolbar-control-group.md), [Button](./wa-button.md).
 - Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/component-selection.md#ambiguous-choices`](../../docs/component-selection.md#ambiguous-choices).
 - UX catalog route: `?component=toolbar`.

package/ai/public-api-signatures-v1.md

@@ -1,6 +1,6 @@
 # Public API signatures for the UI authoring corpus
 
-Generated from emitted declarations for `@kerfjs/ui@5.0.0-beta.70` and `kerfjs@5.0.0-beta.70`. This bounded reference covers only APIs used by the seven-task corpus. It is interface evidence, not an implementation or runtime guarantee.
+Generated from emitted declarations for `@kerfjs/ui@5.0.0-beta.72` and `kerfjs@5.0.0-beta.72`. This bounded reference covers only APIs used by the seven-task corpus. It is interface evidence, not an implementation or runtime guarantee.
 
 ## `@kerfjs/ui/css-values`
 
@@ -222,14 +222,6 @@ interface ToolbarTextBaseProps {
     className?: string;
     /** Optional id, e.g. so a dialog can reference the title via aria-labelledby. */
     id?: string;
-    /**
-     * Expose heading semantics (`role="heading"` + `aria-level`) so the text acts as
-     * a heading landmark — e.g. a page's primary title. Omit to keep the plain span
-     * (the default), which suits a dialog title referenced via `aria-labelledby`.
-     */
-    headingLevel?: HeadingLevel;
-    /** Render the text as an unanimated loading skeleton instead of its value. */
-    placeholder?: boolean;
     /**
      * Show a trailing ellipsis (…) where the text is truncated — on the single line
      * (default), or at the `maxLines` boundary when wrapping. Set false to hard-clip
@@ -253,8 +245,21 @@ type ToolbarTextWrappingProps = {
     wrap?: false;
     maxLines?: never;
 };
-type ToolbarTextProps = ToolbarTextBaseProps & ToolbarTextWrappingProps;
-declare function ToolbarText({ text, size, className, id, headingLevel, placeholder, wrap, ellipsis, maxLines, fill, slot, }: ToolbarTextProps): kerfjs.SafeHtml;
+type ToolbarTextProps = ToolbarTextBaseProps & (({
+    action?: never;
+    /** Expose `role="heading"` and `aria-level` on read-only text. */
+    headingLevel?: HeadingLevel;
+    /** Render an unanimated loading skeleton instead of the text. */
+    placeholder?: boolean;
+} & ToolbarTextWrappingProps) | {
+    /** Render a native button with this delegated action; the app owns editing. */
+    action: string;
+    headingLevel?: never;
+    placeholder?: never;
+    wrap?: never;
+    maxLines?: never;
+});
+declare function ToolbarText({ text, size, className, id, headingLevel, placeholder, wrap, ellipsis, maxLines, fill, slot, action, }: ToolbarTextProps): kerfjs.SafeHtml;
 
 export { type HeadingLevel, ToolbarText, type ToolbarTextProps, type ToolbarTextSize };
 ```

package/ai/skill.md

@@ -228,7 +228,7 @@ Hard rules:
     15a. Use `Text` from `@kerfjs/ui/text` for ordinary headings, paragraphs, and inline secondary text outside toolbar title zones. Omit `variant` for the default `p`, pass `h1`–`h6` according to the document outline, or use `variant="span"` inside a row, label, or table cell; ordinary native attributes pass through. Express supporting, error, compact, or code text with the independent finite `tone="quiet|danger"`, `size="compact"`, and `font="monospace"` props instead of global utility classes or appearance-only heading choices. Block Text variants own a transparent 1px border and the standard item padding; `span` owns no box geometry. Keep toolbar identity/title content on `ToolbarText` and list-aligned bare prose on `ListInsetText`. `ToolbarText` below `xlarge` is intentionally quiet identity text with no tone option; a normal-color subsection title is `Text` with an `h2`–`h6` variant (or `ListHeader` for a list or menu section), never a recolored `ToolbarText`.
 16. Keep a visible collapsible pane's collapse control in its own toolbar. When hidden, move its restore control into the adjacent main toolbar on the corresponding logical edge: leading for an inline-start sidebar and trailing for an inline-end inspector. Collapse the pane completely; do not preserve an empty icon-only rail.
     16a. Dividers between pinned chrome and scrolling content are component chrome: a `Toolbar` draws none by default (`dividerSides` is for a permanent edge only). Call `wireScrollDividers(appRoot)` from `@kerfjs/ui/wire-scroll-dividers` once and retain its disposer; a plain `Pane` with `chromeDividers="scroll"` draws the line under its header only while content is scrolled beneath it and over its footer only while more content lies below (never when the content fits), every `NavStack`'s top chrome and bottom toolbar and every `TabScaffold` bar do the same around the active view or scene (keyed on whatever actually scrolls there, including a sole `Pane`'s content), and every `TabBar` marks each side of its strip with tabs scrolled out of view. Configure a pane with `chromeDividers` (`scroll` by default for plain panes, `always` by default for sunken panes, or explicit `scroll`, `always`, `none`, also via `PaneConfig`); `always` draws both lines even when content fits. A `NavStack` or `TabScaffold` has its own `chromeDividers` (same values: `always` draws the chrome lines without the wiring, `none` never, even when wired; a `SplitView` forwards it through `compactStack`); a `toolbarConfig.dividerSides` edge stays the Toolbar's own. Name app-owned chrome by id in `targets`. The wiring writes only `data-scroll-overflow` / `data-scroll-divider` state; never write a border onto a component to show a divider.
-17. The only direct children of a `Toolbar` zone (`leading`/`center`/`trailing`) are `ToolbarText` (identity/title text) and `ToolbarControlGroup`; never drop bare buttons, inputs, links, or arbitrary markup straight into a zone. Put identity/title text directly in the zone as `ToolbarText`; wrap interactive controls and icon tiles in `ToolbarControlGroup`. `SegmentedControl`, `Select`, a collapsible `TokenSearchField`, and Web Awesome controls all live inside a group. Configure zone behavior with `Toolbar.centerAlign` and its `responsive` / `responsiveAt` policy instead of selecting toolbar zone classes. No policy clips an action: trailing (and stacked center) zones wrap whole groups onto another row, and the center zone never compresses below its content (a leading title too long for the row truncates with an ellipsis instead), so never hide or shrink a toolbar control to make it fit; use `responsive="wrap"` for a heading whose title must stay whole, and move genuinely lower-priority commands into an app-owned "More" popup menu. For an ordinary icon/action control inside a group, use a plain `<button>` (the group styles `> button` fully) — that is the default; reach for `wa-button` only when you need a Web Awesome feature. A popup menu in a toolbar is a `PopupMenu` (`@kerfjs/ui/popup-menu`, registered once via `@kerfjs/ui/popup-menu/register`) in a `single` group with `nestedDropdown` and a `menuInset`: give it typed `items` (commands with `action`s, `heading`s, `divider`s) and a trigger `icon` plus visible `text` or an accessible `label`; never hand-write `wa-dropdown` / `wa-dropdown-item` markup for a menu. Let the group size that trigger from its icon, localized text, and caret; do not force a width on the menu or button. By default a group stays on one row: each icon sits beside its label, and the toolbar's `responsive` policy relocates whole groups when needed. Set `overflow="wrap"` only for independent links that should move as whole actions to another row within the group; use `overflow="scroll"` for a bounded one-row action strip. A `ToolbarText` is one line ending in an ellipsis by default; opt into `wrap` (capped by `maxLines`) or `ellipsis={false}` deliberately. Inside a group, a `Select` or `PopupMenu` trigger drops its focus ring while its popup is open (the open popup and its current row show where focus is) and the ring returns when the popup closes; a ring follows the control's shape (a pill for an icon-and-caret trigger, a circle for a compact icon button) — set `focusRingOwner="group"` on a Select whose group paints the composed ring, and never add CSS to show, hide, or reshape a ring. For a compact mixed group, keep the standard item padding and raised selected chrome; the selected item paints over the outer border without an internal separator. For an avatar control, set `content="avatar"` and `avatarImage` on the group instead of inserting an `img`: a lone control paints the contained image on the outer group and a multi-button group paints it only on the pressed selection highlight. Compose panel/dialog/page headings with a direct extra-large `ToolbarText`, optional grouped icon, grouped trailing controls, and app-owned supporting copy below. A non-interactive heading icon is an icon tile: put the `LucideIcon` directly in its `ToolbarControlGroup` (it takes an icon button's 40px slot and centers), never inside a `<button>` that does nothing. A group remains 44px outside (`calc(2px + remify(42px))`) when its border/background are transparent; use 8px between groups and inside items. Each zone item sits in the toolbar's top 44px control band, centered by its own size; a taller item (a wrapped title, a second trailing row) starts at the band's top and grows down without moving the others, so a wrapped `ToolbarText` keeps trailing controls beside its first line — do not add alignment CSS for this. Split dormant and interactive regions: `ListHeader` fills the available inline width by default; set `width="content"` to shrink-wrap while retaining its normal geometry, or `inline` when it belongs in surrounding text without outer margin, border, or padding. It keeps its label and mutually exclusive semantic count or non-count `badge` together, with an independent logical-end action unless disclosure mode makes the title cluster the button. Its action visual defaults to 18px through `--kui-list-header-action-icon-size` inside a fitted 36px hover square whose transparent hit layer keeps the pointer target at least 44px (44px wide by the 36px row in `density="compact"`); never shrink the target to match the visual, and never force the button to 44px. Pass every non-negative safe-integer section quantity through `count` with a localized full spoken `countLabel`; never concatenate it into `label` or put a number in `badge`. `ListItem.trailing` is dormant; use `ListActionRow` when primary and trailing actions need sibling native buttons. Its `label`, `icon`, and `trailingActionIcon` slots are also dormant and cannot contain controls. Let panes relocate at narrow widths instead of shrinking targets. Dividers are chrome and earn their place: a `Toolbar` draws none by default, and the line between pinned chrome and scrolling content comes from scroll state (rule 16a), so never add a border, a permanent `dividerSides`, or a margin to fake or adjust one.
+17. The direct children of a `Toolbar` zone are `ToolbarText` (identity/title text) and `ToolbarControlGroup`; `trailing` also accepts one standalone primary `wa-button` that keeps its own Web Awesome chrome. Never drop other bare buttons, inputs, links, or arbitrary markup straight into a zone. Put identity/title text directly in the zone as `ToolbarText`; wrap interactive controls and icon tiles in `ToolbarControlGroup`. `SegmentedControl`, `Select`, a collapsible `TokenSearchField`, and other Web Awesome controls live inside a group. Configure zone behavior with `Toolbar.centerAlign` and its `responsive` / `responsiveAt` policy instead of selecting toolbar zone classes. No policy clips an action: trailing (and stacked center) zones wrap whole groups onto another row, and the center zone never compresses below its content (a leading title too long for the row truncates with an ellipsis instead), so never hide or shrink a toolbar control to make it fit; use `responsive="wrap"` for a heading whose title must stay whole, and move genuinely lower-priority commands into an app-owned "More" popup menu. For an ordinary icon/action control inside a group, use a plain `<button>` (the group styles `> button` fully) — that is the default; reach for `wa-button` only when you need a Web Awesome feature. A popup menu in a toolbar is a `PopupMenu` (`@kerfjs/ui/popup-menu`, registered once via `@kerfjs/ui/popup-menu/register`) in a `single` group with `nestedDropdown` and a `menuInset`: give it typed `items` (commands with `action`s, `heading`s, `divider`s) and a trigger `icon` plus visible `text` or an accessible `label`; never hand-write `wa-dropdown` / `wa-dropdown-item` markup for a menu. Let the group size that trigger from its icon, localized text, and caret; do not force a width on the menu or button. By default a group stays on one row: each icon sits beside its label, and the toolbar's `responsive` policy relocates whole groups when needed. Set `overflow="wrap"` only for independent links that should move as whole actions to another row within the group; use `overflow="scroll"` for a bounded one-row action strip. A `ToolbarText` is one line ending in an ellipsis by default; opt into `wrap` (capped by `maxLines`) or `ellipsis={false}` deliberately. Inside a group, a `Select` or `PopupMenu` trigger drops its focus ring while its popup is open (the open popup and its current row show where focus is) and the ring returns when the popup closes; a ring follows the control's shape (a pill for an icon-and-caret trigger, a circle for a compact icon button) — set `focusRingOwner="group"` on a Select whose group paints the composed ring, and never add CSS to show, hide, or reshape a ring. For a compact mixed group, keep the standard item padding and raised selected chrome; the selected item paints over the outer border without an internal separator. For an avatar control, set `content="avatar"` and `avatarImage` on the group instead of inserting an `img`: a lone control paints the contained image on the outer group and a multi-button group paints it only on the pressed selection highlight. Compose panel/dialog/page headings with a direct extra-large `ToolbarText`, optional grouped icon, grouped trailing controls, and app-owned supporting copy below. A non-interactive heading icon is an icon tile: put the `LucideIcon` directly in its `ToolbarControlGroup` (it takes an icon button's 40px slot and centers), never inside a `<button>` that does nothing. A group remains 44px outside (`calc(2px + remify(42px))`) when its border/background are transparent; use 8px between groups and inside items. Each zone item sits in the toolbar's top 44px control band, centered by its own size; a taller item (a wrapped title, a second trailing row) starts at the band's top and grows down without moving the others, so a wrapped `ToolbarText` keeps trailing controls beside its first line — do not add alignment CSS for this. Split dormant and interactive regions: `ListHeader` fills the available inline width by default; set `width="content"` to shrink-wrap while retaining its normal geometry, or `inline` when it belongs in surrounding text without outer margin, border, or padding. It keeps its label and mutually exclusive semantic count or non-count `badge` together, with an independent logical-end action unless disclosure mode makes the title cluster the button. Its action visual defaults to 18px through `--kui-list-header-action-icon-size` inside a fitted 36px hover square whose transparent hit layer keeps the pointer target at least 44px (44px wide by the 36px row in `density="compact"`); never shrink the target to match the visual, and never force the button to 44px. Pass every non-negative safe-integer section quantity through `count` with a localized full spoken `countLabel`; never concatenate it into `label` or put a number in `badge`. `ListItem.trailing` is dormant; use `ListActionRow` when primary and trailing actions need sibling native buttons. Its `label`, `icon`, and `trailingActionIcon` slots are also dormant and cannot contain controls. Let panes relocate at narrow widths instead of shrinking targets. Dividers are chrome and earn their place: a `Toolbar` draws none by default, and the line between pinned chrome and scrolling content comes from scroll state (rule 16a), so never add a border, a permanent `dividerSides`, or a margin to fake or adjust one.
     For a toolbar heading that must remain at the 20px `--kui-font-l` step, use `ToolbarText size="xlarge-fixed"`; `xlarge` retains the responsive page-title clamp. Pass `headingLevel` when it is a section landmark.
 
 18. When a recurring concept has no matching export or production recipe, keep its semantics in a thin application adapter while reusing the public layout vocabulary. The composer recipe uses one visible form surface, toolbar title/supporting-copy ids, shared 8px field/action gutters, 24px major rhythm, and a conditional StateBanner as its only nested semantic surface; do not turn every section into a card or double-inset intrinsically bordered controls. For multi-line banner copy use `copyLayout="stacked"`; use `actionPlacement="below"` for an action on its own trailing row. The application-local `../docs/examples/command-palette-adapter.tsx` is reference source for one such missing concept, not an `@kerfjs/ui` runtime export or catalog recipe. The application owns its registration, ranking, history, permissions, availability, shortcut policy, focus policy, dispatch, and copy. If a missing concept recurs across products, open an upstream component or recipe request.

package/ai/webawesome-jsx-signatures-v1.md

@@ -1,6 +1,6 @@
 # Web Awesome JSX signatures for the UI authoring corpus
 
-Generated from the emitted `@kerfjs/ui@5.0.0-beta.70` declaration boundary. Import `@kerfjs/ui/webawesome` for type effects when authoring direct `wa-*` JSX. The module emits no runtime behavior and does not register custom elements.
+Generated from the emitted `@kerfjs/ui@5.0.0-beta.72` declaration boundary. Import `@kerfjs/ui/webawesome` for type effects when authoring direct `wa-*` JSX. The module emits no runtime behavior and does not register custom elements.
 
 ```ts
 import { KerfCustomElement } from 'kerfjs/jsx-runtime';

package/analyzer/component-ownership.mjs

@@ -21,9 +21,26 @@ import {
   subjectTypes,
   withoutRelationalArguments,
 } from './selectors.mjs';
+import { resolve } from 'node:path';
 
 const kebab = (value) =>
   value.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+const bemBlock = (name) => name.split(/__|--/, 1)[0];
+
+export function classOwnerFor(facts, className, componentMode = false) {
+  if (facts.classOwners.has(className)) return facts.classOwners.get(className);
+  if (!componentMode || bemBlock(className) === className) return undefined;
+  return facts.blockOwners.get(bemBlock(className));
+}
+
+export function ownsClassBlock(facts, className, componentMode = false) {
+  return (
+    facts.classOwners.has(className) ||
+    (componentMode &&
+      bemBlock(className) !== className &&
+      facts.blockOwners.has(bemBlock(className)))
+  );
+}
 
 function isWebAwesomeTagEntry(entry) {
   return entry.source === 'webawesome' && /^wa-[a-z0-9-]+$/.test(entry.id);
@@ -37,17 +54,51 @@ function isWebAwesomeTagEntry(entry) {
  */
 export function componentOwnershipFacts(entries) {
   const classOwners = new Map();
+  const blockOwners = new Map();
   const dataComponentOwners = new Map();
   const tagOwners = new Map();
+  const descendantRootAttributeOwners = [];
   const privatePrefixes = [];
   const typedTokens = new Map();
   const setOnce = (map, key, entry) => {
     if (!map.has(key)) map.set(key, entry);
   };
+  const sharesStylesheet = (left, right) => {
+    if (
+      left.package !== right.package ||
+      !left.catalogDirectory ||
+      !right.catalogDirectory
+    )
+      return false;
+    const styles = new Set(
+      (left.styleSources ?? []).map((path) =>
+        resolve(left.catalogDirectory, path),
+      ),
+    );
+    return (right.styleSources ?? []).some((path) =>
+      styles.has(resolve(right.catalogDirectory, path)),
+    );
+  };
   for (const entry of entries) {
     const boundaries = entry.boundaries ?? {};
-    for (const className of boundaries.publicClasses ?? []) {
-      setOnce(classOwners, className, entry);
+    if (boundaries.rootElement && boundaries.descendantRootAttribute)
+      descendantRootAttributeOwners.push(entry);
+    for (const className of new Set(
+      [boundaries.rootClass, ...(boundaries.publicClasses ?? [])].filter(
+        Boolean,
+      ),
+    )) {
+      const previous = classOwners.get(className);
+      if (!classOwners.has(className)) classOwners.set(className, entry);
+      else if (previous && sharesStylesheet(previous, entry))
+        // The class is co-owned. A selector cannot attribute it to one
+        // component without depending on catalog order.
+        classOwners.set(className, null);
+      const block = bemBlock(className);
+      const previousBlock = blockOwners.get(block);
+      if (!blockOwners.has(block)) blockOwners.set(block, entry);
+      else if (previousBlock && sharesStylesheet(previousBlock, entry))
+        blockOwners.set(block, null);
       if (
         className.startsWith('kui-') &&
         !className.includes('__') &&
@@ -81,8 +132,10 @@ export function componentOwnershipFacts(entries) {
   privatePrefixes.sort((a, b) => b.prefix.length - a.prefix.length);
   return {
     classOwners,
+    blockOwners,
     dataComponentOwners,
     tagOwners,
+    descendantRootAttributeOwners,
     privatePrefixes,
     typedTokens,
   };
@@ -106,6 +159,7 @@ export function restyledComponents(
     ownPackage,
     hooks = new Map(),
     composedChildren = new Map(),
+    composedDescendants = new Map(),
   } = {},
 ) {
   const found = [];
@@ -123,7 +177,11 @@ export function restyledComponents(
     const bare = withoutRelationalArguments(subject);
     const subjectClasses = classNames(bare);
     for (const className of classNames(bare))
-      add(facts.classOwners.get(className), 'class', `.${className}`);
+      add(
+        classOwnerFor(facts, className, componentMode),
+        'class',
+        `.${className}`,
+      );
     for (const value of dataComponents(bare))
       add(
         facts.dataComponentOwners.get(value),
@@ -132,13 +190,38 @@ export function restyledComponents(
       );
     // An application class on the subject scopes a Web Awesome tag to the
     // application's own element; a component package never places one there.
-    if (subjectClasses.some((name) => !facts.classOwners.has(name))) continue;
+    if (
+      subjectClasses.some((name) => !ownsClassBlock(facts, name, componentMode))
+    )
+      continue;
     for (const type of subjectTypes(subject) ?? [])
       add(facts.tagOwners.get(type), 'tag', type);
     // A raw descendant of a component's cataloged anatomy is still inside
     // that component. Do not infer ownership through its root, where an app
     // may place its own children, or through an app-named intermediate node.
     if (subjectClasses.length || parts.length < 2) continue;
+    if (componentMode)
+      for (const ancestor of parts.slice(0, -1))
+        for (const entry of facts.descendantRootAttributeOwners) {
+          const { rootElement, descendantRootAttribute } = entry.boundaries;
+          if (
+            (subjectTypes(subject) ?? []).some((type) =>
+              entry.boundaries.descendantElements?.includes(type),
+            )
+          )
+            continue;
+          if (
+            subjectTypes(ancestor.compound)?.includes(rootElement) &&
+            new RegExp(
+              `\\[\\s*${descendantRootAttribute}(?=\\s|\\]|[~|^$*]?=)`,
+            ).test(withoutRelationalArguments(ancestor.compound))
+          )
+            add(
+              entry,
+              'descendant',
+              `${rootElement}[${descendantRootAttribute}]`,
+            );
+        }
     if (componentMode && parts.at(-1).combinator === '>') {
       const types = subjectTypes(subject) ?? [];
       for (const name of classNames(
@@ -155,6 +238,14 @@ export function restyledComponents(
       const classes = classNames(
         withoutRelationalArguments(parts[index].compound),
       );
+      if (componentMode && parts.at(-1).combinator !== '>')
+        for (const name of classes)
+          for (const type of subjectTypes(subject) ?? [])
+            add(
+              composedDescendants.get(`${name}|${type}`),
+              'descendant',
+              `.${name}`,
+            );
       const hook = componentMode
         ? classes.find((name) => hooks.has(name))
         : undefined;
@@ -162,19 +253,27 @@ export function restyledComponents(
         add(hooks.get(hook), 'descendant', `.${hook}`);
         break;
       }
-      if (classes.some((name) => !facts.classOwners.has(name))) break;
+      if (classes.some((name) => !ownsClassBlock(facts, name, componentMode)))
+        break;
       const anatomy = classes.find(
-        (name) => name.includes('__') && facts.classOwners.has(name),
+        (name) =>
+          name.includes('__') && ownsClassBlock(facts, name, componentMode),
       );
       if (anatomy) {
-        add(facts.classOwners.get(anatomy), 'descendant', `.${anatomy}`);
+        add(
+          classOwnerFor(facts, anatomy, componentMode),
+          'descendant',
+          `.${anatomy}`,
+        );
         break;
       }
       if (componentMode) {
-        const root = classes.find((name) => facts.classOwners.has(name));
+        const root = classes.find((name) =>
+          ownsClassBlock(facts, name, componentMode),
+        );
         if (root) {
-          const entry = facts.classOwners.get(root);
-          if (entry.package === ownPackage)
+          const entry = classOwnerFor(facts, root, componentMode);
+          if (entry?.package === ownPackage)
             add(entry, 'descendant', `.${root}`);
           break;
         }
@@ -184,12 +283,13 @@ export function restyledComponents(
   return found;
 }
 
-/** Same-package classes used to key another component's selector. */
+/** Foreign component handles used to key another component's selector. */
 export function contextualComponents(
   selectorList,
   facts,
   isForeign,
   ownPackage,
+  anyPackage = false,
 ) {
   const found = [];
   const seen = new Set();
@@ -197,13 +297,28 @@ export function contextualComponents(
   for (const parts of complexSelectorParts(selectorList)) {
     for (const [index, part] of parts.entries()) {
       const compound = part.compound;
-      for (const name of selectorClasses(compound)) {
-        const entry = facts.classOwners.get(name);
-        if (!entry || entry.package !== ownPackage || !isForeign(entry))
+      const handles = [
+        ...selectorClasses(compound).map((name) => ({
+          entry: classOwnerFor(facts, name, true),
+          name: `.${name}`,
+          inArgument: (argument) => selectorClasses(argument).includes(name),
+        })),
+        ...(anyPackage ? dataComponents(compound) : []).map((value) => ({
+          entry: facts.dataComponentOwners.get(value),
+          name: `[data-component="${value}"]`,
+          inArgument: (argument) => dataComponents(argument).includes(value),
+        })),
+      ];
+      for (const { entry, name, inArgument } of handles) {
+        if (
+          !entry ||
+          (!anyPackage && entry.package !== ownPackage) ||
+          !isForeign(entry)
+        )
           continue;
         const pseudo = ['has', 'is', 'where', 'not'].find((candidate) =>
           pseudoArguments(compound, candidate).some((argument) =>
-            selectorClasses(argument).includes(name),
+            inArgument(argument),
           ),
         );
         const position = pseudo
@@ -218,7 +333,7 @@ export function contextualComponents(
         seen.add(key);
         found.push({
           entry,
-          name: `.${name}`,
+          name,
           position,
         });
       }

package/analyzer/index.d.mts

@@ -44,8 +44,9 @@ export function analyzeUiProject(options?: {
   knownRules?: Iterable<string>;
   adoption?: boolean;
   ownership?: 'package' | 'component';
-  ownershipContext?: 'subject' | 'any';
+  ownershipContext?: 'subject' | 'any' | 'any-package';
   implicitComponentOwnership?: boolean;
+  ownershipGroups?: Array<{ styleSources: string[]; sources: string[] }>;
 }): Promise<UiAnalysisReport>;
 
 export function formatUiAnalysisText(report: UiAnalysisReport): string;