@kerfjs/ui 5.0.0-beta.76 → 5.0.0-beta.78

package/ai/component-composition.json

@@ -697,7 +697,7 @@
           "required": false
         },
         {
-          "id": "view content and titles",
+          "id": "view content and structured top and bottom toolbar configurations",
           "owner": "application",
           "required": false
         },
@@ -712,7 +712,7 @@
           "required": false
         },
         {
-          "id": "per-view bottom toolbar content or a persistent fallback",
+          "id": "per-view bottom toolbar or a persistent structured fallback",
           "owner": "application",
           "required": false
         },
@@ -722,12 +722,12 @@
           "required": false
         },
         {
-          "id": "per-view fixed header content above the active view's scroll area",
+          "id": "per-view header and footer with List and Pane configuration",
           "owner": "application",
           "required": false
         },
         {
-          "id": "top-toolbar configuration, title size, and heading level",
+          "id": "top-toolbar defaults, title size, and heading level",
           "owner": "application",
           "required": false
         },
@@ -754,6 +754,12 @@
             "helper": "wireNavStack",
             "meaning": "Marks the inert, aria-hidden snapshot of the outgoing chrome shown during the cross-fade."
           },
+          {
+            "name": "data-nav-revealed",
+            "on": "kui-nav-stack__view",
+            "helper": "wireNavStack",
+            "meaning": "\"true\" on the preserved, aria-hidden previous view while an incoming view slides over it."
+          },
           {
             "name": "data-nav-exiting",
             "on": "kui-nav-stack__view",
@@ -806,7 +812,6 @@
           "kui-nav-stack__chrome-copy",
           "kui-nav-stack__chrome-copy--bottom",
           "kui-nav-stack__chrome-copy--exiting",
-          "kui-nav-stack__header",
           "kui-nav-stack__viewport",
           "kui-nav-stack__view",
           "kui-nav-stack__view--entering",
@@ -908,6 +913,12 @@
             "helper": "wireNavStack",
             "meaning": "Marks the inert, aria-hidden snapshot of the outgoing chrome shown during the cross-fade."
           },
+          {
+            "name": "data-nav-revealed",
+            "on": "kui-nav-stack__view",
+            "helper": "wireNavStack",
+            "meaning": "\"true\" on the preserved, aria-hidden previous view while an incoming view slides over it."
+          },
           {
             "name": "data-nav-exiting",
             "on": "kui-nav-stack__view",
@@ -1460,7 +1471,7 @@
       ],
       "wiring": {
         "required": false,
-        "helpers": ["wireScrollDividers"],
+        "helpers": ["wireScrollDividers", "wireToolbarVisibility"],
         "obligations": [],
         "stateAttributes": [
           {
@@ -1474,6 +1485,30 @@
             "on": "a Toolbar named as targets chrome",
             "helper": "wireScrollDividers",
             "meaning": "The sides, in t/r/b/l order, on which this chrome currently draws its scroll divider: the side facing the scroller while content is hidden beyond it. Re-applied if a re-render drops it."
+          },
+          {
+            "name": "data-toolbar-width-hidden",
+            "on": "ToolbarText, ToolbarControlGroup and its paired busy status",
+            "helper": "wireToolbarVisibility",
+            "meaning": "True when typed hideBelow/showBelow thresholds hide this item at the nearest Toolbar content width. Re-applied after rendering; disposal restores prior markers."
+          },
+          {
+            "name": "data-toolbar-visibility-probe",
+            "on": "private aria-hidden measurement boxes under Toolbar",
+            "helper": "wireToolbarVisibility",
+            "meaning": "Internal out-of-flow CSS length resolver; created and removed by wireToolbarVisibility."
+          },
+          {
+            "name": "data-morph-preserve",
+            "on": "private aria-hidden measurement boxes and visibility state children",
+            "helper": "wireToolbarVisibility",
+            "meaning": "Keeps helper-owned geometry and state across Kerf renders; replacement and explicit removal are repaired, and disposal removes them."
+          },
+          {
+            "name": "data-toolbar-visibility-state",
+            "on": "private hidden children of width-managed items and paired busy statuses",
+            "helper": "wireToolbarVisibility",
+            "meaning": "Preserves actual CSS visibility while rendering removes a transient parent marker, preventing geometry-driven render feedback."
           }
         ]
       },
@@ -1570,9 +1605,34 @@
       ],
       "wiring": {
         "required": false,
-        "helpers": [],
+        "helpers": ["wireToolbarVisibility"],
         "obligations": [],
-        "stateAttributes": []
+        "stateAttributes": [
+          {
+            "name": "data-toolbar-width-hidden",
+            "on": "ToolbarText, ToolbarControlGroup and its paired busy status",
+            "helper": "wireToolbarVisibility",
+            "meaning": "True when typed hideBelow/showBelow thresholds hide this item at the nearest Toolbar content width. Re-applied after rendering; disposal restores prior markers."
+          },
+          {
+            "name": "data-toolbar-visibility-probe",
+            "on": "private aria-hidden measurement boxes under Toolbar",
+            "helper": "wireToolbarVisibility",
+            "meaning": "Internal out-of-flow CSS length resolver; created and removed by wireToolbarVisibility."
+          },
+          {
+            "name": "data-morph-preserve",
+            "on": "private aria-hidden measurement boxes and visibility state children",
+            "helper": "wireToolbarVisibility",
+            "meaning": "Keeps helper-owned geometry and state across Kerf renders; replacement and explicit removal are repaired, and disposal removes them."
+          },
+          {
+            "name": "data-toolbar-visibility-state",
+            "on": "private hidden children of width-managed items and paired busy statuses",
+            "helper": "wireToolbarVisibility",
+            "meaning": "Preserves actual CSS visibility while rendering removes a transient parent marker, preventing geometry-driven render feedback."
+          }
+        ]
       },
       "responsive": { "owner": "not-applicable", "behaviors": [] },
       "layout": {
@@ -1585,7 +1645,30 @@
           "Name an icon-only button or link with aria-label, not title. Once any help-tag installer is imported (select/register, popup-menu/register, or help-tags/register), it shows an aria-hidden Web Awesome help tag repeating that name after a 500ms hover and at once on keyboard focus, hidden on a press and on Escape, and never joins aria-labelledby. A native title keeps the browser tooltip and gets no second tag."
         ]
       },
-      "cssValueProps": [],
+      "cssValueProps": [
+        {
+          "path": "hideBelow",
+          "grammar": "length",
+          "helpers": ["px", "rem", "em", "pct", "space", "lengthVar", "calc"],
+          "nonStandaloneHelpers": ["plus"],
+          "shorthands": [],
+          "canonicalShorthands": [],
+          "exceptionalShorthands": [],
+          "rawPolicy": "forbid",
+          "examples": ["hideBelow={px(416)}"]
+        },
+        {
+          "path": "showBelow",
+          "grammar": "length",
+          "helpers": ["px", "rem", "em", "pct", "space", "lengthVar", "calc"],
+          "nonStandaloneHelpers": ["plus"],
+          "shorthands": [],
+          "canonicalShorthands": [],
+          "exceptionalShorthands": [],
+          "rawPolicy": "forbid",
+          "examples": ["showBelow={px(416)}"]
+        }
+      ],
       "boundaries": {
         "rootClass": "kui-toolbar-control-group",
         "publicClasses": [
@@ -1617,7 +1700,20 @@
           "--kui-toolbar-control-pressed-color",
           "--kui-toolbar-control-selected-background",
           "--kui-toolbar-control-selected-color",
-          "--kui-toolbar-control-selected-shadow"
+          "--kui-toolbar-control-selected-shadow",
+          "--kui-color-neutral-fill-quiet",
+          "--kui-color-neutral-border-quiet",
+          "--kui-color-brand-fill-quiet",
+          "--kui-color-brand-border-quiet",
+          "--kui-color-success-fill-quiet",
+          "--kui-color-success-border-quiet",
+          "--kui-color-success-on-quiet",
+          "--kui-color-warning-fill-quiet",
+          "--kui-color-warning-border-quiet",
+          "--kui-color-warning-on-quiet",
+          "--kui-color-danger-fill-quiet",
+          "--kui-color-danger-border-quiet",
+          "--kui-color-danger-on-quiet"
         ]
       },
       "diagnostics": [],
@@ -1669,7 +1765,68 @@
           "Use popup surfaces only for real dropdown menus with named triggers."
         ]
       },
-      "cssValueProps": [],
+      "cssValueProps": [
+        {
+          "path": "preferredWidth",
+          "grammar": "length",
+          "helpers": [
+            "px",
+            "rem",
+            "remify",
+            "em",
+            "pct",
+            "space",
+            "lengthVar",
+            "calc"
+          ],
+          "nonStandaloneHelpers": ["plus"],
+          "shorthands": [],
+          "canonicalShorthands": [],
+          "exceptionalShorthands": [],
+          "rawPolicy": "forbid",
+          "examples": ["preferredWidth={remify(832)}"]
+        },
+        {
+          "path": "viewportGutter",
+          "grammar": "length",
+          "helpers": [
+            "px",
+            "rem",
+            "remify",
+            "em",
+            "pct",
+            "space",
+            "lengthVar",
+            "calc"
+          ],
+          "nonStandaloneHelpers": ["plus"],
+          "shorthands": [],
+          "canonicalShorthands": [],
+          "exceptionalShorthands": [],
+          "rawPolicy": "forbid",
+          "examples": ["viewportGutter={remify(8)}"]
+        },
+        {
+          "path": "maxHeight",
+          "grammar": "length",
+          "helpers": [
+            "px",
+            "rem",
+            "remify",
+            "em",
+            "pct",
+            "space",
+            "lengthVar",
+            "calc"
+          ],
+          "nonStandaloneHelpers": ["plus"],
+          "shorthands": ["viewport"],
+          "canonicalShorthands": ["viewport"],
+          "exceptionalShorthands": [],
+          "rawPolicy": "forbid",
+          "examples": ["maxHeight=\"viewport\"", "maxHeight={remify(640)}"]
+        }
+      ],
       "boundaries": {
         "rootClass": "kui-dialog-surface",
         "publicClasses": ["kui-dialog-surface", "kui-popup-surface"],
@@ -1775,9 +1932,34 @@
       ],
       "wiring": {
         "required": false,
-        "helpers": [],
+        "helpers": ["wireToolbarVisibility"],
         "obligations": [],
-        "stateAttributes": []
+        "stateAttributes": [
+          {
+            "name": "data-toolbar-width-hidden",
+            "on": "ToolbarText, ToolbarControlGroup and its paired busy status",
+            "helper": "wireToolbarVisibility",
+            "meaning": "True when typed hideBelow/showBelow thresholds hide this item at the nearest Toolbar content width. Re-applied after rendering; disposal restores prior markers."
+          },
+          {
+            "name": "data-toolbar-visibility-probe",
+            "on": "private aria-hidden measurement boxes under Toolbar",
+            "helper": "wireToolbarVisibility",
+            "meaning": "Internal out-of-flow CSS length resolver; created and removed by wireToolbarVisibility."
+          },
+          {
+            "name": "data-morph-preserve",
+            "on": "private aria-hidden measurement boxes and visibility state children",
+            "helper": "wireToolbarVisibility",
+            "meaning": "Keeps helper-owned geometry and state across Kerf renders; replacement and explicit removal are repaired, and disposal removes them."
+          },
+          {
+            "name": "data-toolbar-visibility-state",
+            "on": "private hidden children of width-managed items and paired busy statuses",
+            "helper": "wireToolbarVisibility",
+            "meaning": "Preserves actual CSS visibility while rendering removes a transient parent marker, preventing geometry-driven render feedback."
+          }
+        ]
       },
       "responsive": { "owner": "not-applicable", "behaviors": [] },
       "layout": {
@@ -1790,7 +1972,30 @@
           "Actionable text is a native button with its full text as its accessible name; action cannot be combined with headingLevel, placeholder, or wrap."
         ]
       },
-      "cssValueProps": [],
+      "cssValueProps": [
+        {
+          "path": "hideBelow",
+          "grammar": "length",
+          "helpers": ["px", "rem", "em", "pct", "space", "lengthVar", "calc"],
+          "nonStandaloneHelpers": ["plus"],
+          "shorthands": [],
+          "canonicalShorthands": [],
+          "exceptionalShorthands": [],
+          "rawPolicy": "forbid",
+          "examples": ["hideBelow={px(416)}"]
+        },
+        {
+          "path": "showBelow",
+          "grammar": "length",
+          "helpers": ["px", "rem", "em", "pct", "space", "lengthVar", "calc"],
+          "nonStandaloneHelpers": ["plus"],
+          "shorthands": [],
+          "canonicalShorthands": [],
+          "exceptionalShorthands": [],
+          "rawPolicy": "forbid",
+          "examples": ["showBelow={px(416)}"]
+        }
+      ],
       "boundaries": {
         "rootClass": "kui-toolbar-text",
         "publicClasses": ["kui-toolbar-text"],
@@ -1802,7 +2007,8 @@
           "--kui-font-l",
           "--kui-font-m",
           "--kui-font-s",
-          "--kui-font-xs"
+          "--kui-font-xs",
+          "--kui-color-neutral-on-loud"
         ]
       },
       "diagnostics": [],
@@ -1849,11 +2055,12 @@
       "layout": {
         "roles": ["structure"],
         "geometry": {
-          "margin": "none",
+          "margin": "self",
           "border": "self",
           "padding": "self",
           "notes": [
-            "Block Text variants reset native margins and add a 1px transparent border plus the standard 8px item padding; flush removes the border and padding. Tight line height is available for compact copy. Span has no margin, border, or padding. FieldLabel mirrors the themed Web Awesome label typography, 9px inline inset, and bottom gap."
+            "Block Text variants reset native margins and add a 1px transparent border plus the standard 8px item padding; flush removes the border and padding. Tight line height is available for compact copy. Span has no margin by default, border, or padding. FieldLabel mirrors the themed Web Awesome label typography, 9px inline inset, and bottom gap.",
+            "controlMargins adds the shared control gutter outside selected physical edges without changing border or padding; avoid duplicating a parent inset. Spans retain inline display and native inline margin behavior."
           ]
         }
       },

package/ai/components/nav-stack.md

@@ -57,7 +57,7 @@ Exact prop names and types: [`@kerfjs/ui/nav-stack`](../public-api-signatures-v1
 
 ## State and wiring
 
-**The app owns:** ordered view stack and stable keys; view content and titles; push and pop actions; preferred initial focus targets when DOM order is insufficient; per-view bottom toolbar content or a persistent fallback; per-view leading, center, and trailing top-toolbar groups; per-view fixed header content above the active view's scroll area; top-toolbar configuration, title size, and heading level; whether the chrome and bottom-toolbar dividers follow the scroll, always show, or never show (chromeDividers).
+**The app owns:** ordered view stack and stable keys; view content and structured top and bottom toolbar configurations; push and pop actions; preferred initial focus targets when DOM order is insufficient; per-view bottom toolbar or a persistent structured fallback; per-view leading, center, and trailing top-toolbar groups; per-view header and footer with List and Pane configuration; top-toolbar defaults, title size, and heading level; whether the chrome and bottom-toolbar dividers follow the scroll, always show, or never show (chromeDividers).
 
 **Wiring:** `wireNavStack`, `wireScrollDividers` is required.
 
@@ -67,6 +67,7 @@ Exact prop names and types: [`@kerfjs/ui/nav-stack`](../public-api-signatures-v1
 
 - `data-nav-chrome-transition` on `kui-nav-stack` (`wireNavStack`): "true" while the chrome cross-fades between the outgoing and incoming view.
 - `data-nav-chrome-copy` on `kui-nav-stack__chrome-copy` (`wireNavStack`): Marks the inert, aria-hidden snapshot of the outgoing chrome shown during the cross-fade.
+- `data-nav-revealed` on `kui-nav-stack__view` (`wireNavStack`): "true" on the preserved, aria-hidden previous view while an incoming view slides over it.
 - `data-nav-exiting` on `kui-nav-stack__view` (`wireNavStack`): "true" on a popped view the helper briefly re-inserts to slide it out.
 - `data-scroll-overflow` on `the active kui-nav-stack__view, or the kui-pane__content of a sole Pane in it` (`wireScrollDividers`): The physical edges, in canonical t/r/b/l order, beyond which content is scrolled out of view; absent when nothing is hidden (content that fits never reports its far edges). Re-applied if a re-render drops it.
 - `data-scroll-divider` on `kui-nav-stack__chrome and kui-nav-stack__bottom` (`wireScrollDividers`): The sides, in t/r/b/l order, on which this chrome currently draws its scroll divider: the side facing the scroller while content is hidden beyond it. Re-applied if a re-render drops it.
@@ -89,9 +90,9 @@ Margin: none · border: conditional · padding: child (layout role: structure).
 
 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-nav-stack`, `kui-nav-stack__chrome`, `kui-nav-stack__bottom`, `kui-nav-stack__chrome--entering`, `kui-nav-stack__chrome-copy`, `kui-nav-stack__chrome-copy--bottom`, `kui-nav-stack__chrome-copy--exiting`, `kui-nav-stack__header`, `kui-nav-stack__viewport`, `kui-nav-stack__view`, `kui-nav-stack__view--entering`, `kui-nav-stack__view--exiting`.
+Public class hooks (select for layout placement only, never to change the component's look): `kui-nav-stack`, `kui-nav-stack__chrome`, `kui-nav-stack__bottom`, `kui-nav-stack__chrome--entering`, `kui-nav-stack__chrome-copy`, `kui-nav-stack__chrome-copy--bottom`, `kui-nav-stack__chrome-copy--exiting`, `kui-nav-stack__viewport`, `kui-nav-stack__view`, `kui-nav-stack__view--entering`, `kui-nav-stack__view--exiting`.
 
-Never put `kui-nav-stack`, `kui-nav-stack__chrome`, `kui-nav-stack__bottom`, `kui-nav-stack__chrome--entering`, `kui-nav-stack__chrome-copy`, `kui-nav-stack__chrome-copy--bottom`, `kui-nav-stack__chrome-copy--exiting`, `kui-nav-stack__header`, `kui-nav-stack__viewport`, `kui-nav-stack__view`, `kui-nav-stack__view--entering`, `kui-nav-stack__view--exiting` on an element you write; render `NavStack` instead (`KUI-L103`).
+Never put `kui-nav-stack`, `kui-nav-stack__chrome`, `kui-nav-stack__bottom`, `kui-nav-stack__chrome--entering`, `kui-nav-stack__chrome-copy`, `kui-nav-stack__chrome-copy--bottom`, `kui-nav-stack__chrome-copy--exiting`, `kui-nav-stack__viewport`, `kui-nav-stack__view`, `kui-nav-stack__view--entering`, `kui-nav-stack__view--exiting` on an element you write; render `NavStack` instead (`KUI-L103`).
 
 Public tokens it reads: `--kui-nav-stack-transition-duration`. Set a token only where its public contract allows; prefer a prop.
 

package/ai/components/select.md

@@ -12,6 +12,7 @@ Choose one or more controlled values, keep unavailable choices visible, and opti
 
 - Choose a controlled value from a moderate or long list, including grouped and icon-bearing choices.
 - Color an optional choice icon with a CssForegroundColor: uiColor() with a foreground token such as success-on-quiet, foregroundColorVar() for an app-owned property, or foregroundColor() for a direct custom CSS color. Fill tokens such as success are backgrounds that leave the icon nearly invisible, so they, lengths, raw color strings, and unqualified colorVar() values are rejected.
+- Use the default content-sized menu for long option labels; native popup shifting keeps it within 10px viewport gutters. fitMenu instead matches trigger width and wraps labels.
 
 **Not when:**
 

package/ai/components/split-view.md

@@ -70,6 +70,7 @@ Zones (a zone is bound to JSX only through its listed prop; never assume the zon
 - `data-resizing` on `kui-resizable-region` (`wireResizableRegions`): "true" during an active pointer drag of the handle.
 - `data-nav-chrome-transition` on `kui-nav-stack` (`wireNavStack`): "true" while the chrome cross-fades between the outgoing and incoming view.
 - `data-nav-chrome-copy` on `kui-nav-stack__chrome-copy` (`wireNavStack`): Marks the inert, aria-hidden snapshot of the outgoing chrome shown during the cross-fade.
+- `data-nav-revealed` on `kui-nav-stack__view` (`wireNavStack`): "true" on the preserved, aria-hidden previous view while an incoming view slides over it.
 - `data-nav-exiting` on `kui-nav-stack__view` (`wireNavStack`): "true" on a popped view the helper briefly re-inserts to slide it out.
 
 ## Geometry

package/ai/components/surface-scaffold.md

@@ -4,7 +4,7 @@
 
 `@kerfjs/ui:surface-scaffold` · Kerf UI · component · Structure
 
-Typed Web Awesome dialog and popup surface sizing, presentation, and inset composition.
+Typed Web Awesome dialog preferred widths and viewport bounds, presentation, and popup inset composition.
 
 ## When to use
 
@@ -12,6 +12,7 @@ Configure recurring dialog and popup geometry without consumer ::part() override
 
 - A Web Awesome dialog or dropdown needs a standard size, presentation, body/footer inset, or list-compatible menu inset.
 - A dialog body should compose rows, sections, or aligned bare prose through List and ListInsetText.
+- A modal needs a typed preferred width, viewport gutter, or dynamic viewport-bounded height cap while retaining native body scrolling and footer actions.
 
 **Not when:**
 
@@ -22,7 +23,8 @@ Configure recurring dialog and popup geometry without consumer ::part() override
 
 - JavaScript: `@kerfjs/ui/surface-scaffold` — exports `DialogSurface`, `PopupSurface`.
 - CSS: the browser build of `@kerfjs/ui/surface-scaffold` pulls its CSS automatically; import `@kerfjs/ui/surface-scaffold.css` manually only without the `browser` export condition.
-- Declared side effects: browser-condition-css.
+- Registration: import `@kerfjs/ui/surface-scaffold/register` once (a side effect).
+- Declared side effects: browser-condition-css, custom-element-registration.
 
 ## Props
 
@@ -32,9 +34,16 @@ Exact prop names and types: [`@kerfjs/ui/surface-scaffold`](../public-api-signat
 
 - small, medium, or large dialog
 - modal, side-sheet, or fullscreen dialog
+- typed modal preferred width, viewport gutter, and maximum height, including viewport cap
 - none, compact, or comfortable body and footer inset
 - standard, compact, or zero-inset popup menu
 
+**CSS-value props** (typed builders from `@kerfjs/ui/css-values`; raw CSS strings are rejected):
+
+- `preferredWidth`: length grammar; raw values: forbid; helpers `px`, `rem`, `remify`, `em`, `pct`, `space`, `lengthVar`, `calc` — e.g. `preferredWidth={remify(832)}`
+- `viewportGutter`: length grammar; raw values: forbid; helpers `px`, `rem`, `remify`, `em`, `pct`, `space`, `lengthVar`, `calc` — e.g. `viewportGutter={remify(8)}`
+- `maxHeight`: length grammar; raw values: forbid; shorthands `viewport`; helpers `px`, `rem`, `remify`, `em`, `pct`, `space`, `lengthVar`, `calc` — e.g. `maxHeight="viewport"`
+
 ## Composition
 
 - Parents: any.

package/ai/components/text.md

@@ -40,6 +40,7 @@ Exact prop names and types: [`@kerfjs/ui/text`](../public-api-signatures-v1.md#k
 - compact, default, large, or xlarge size
 - default or monospace font
 - flush item geometry and tight line height
+- controlMargins selects exterior 8px gutters with canonical physical Sides
 
 ## Composition
 
@@ -55,9 +56,10 @@ No wiring helper.
 
 ## Geometry
 
-Margin: none · border: self · padding: self (layout role: structure). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+Margin: self · border: self · padding: self (layout role: structure). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
 
-- Block Text variants reset native margins and add a 1px transparent border plus the standard 8px item padding; flush removes the border and padding. Tight line height is available for compact copy. Span has no margin, border, or padding. FieldLabel mirrors the themed Web Awesome label typography, 9px inline inset, and bottom gap.
+- Block Text variants reset native margins and add a 1px transparent border plus the standard 8px item padding; flush removes the border and padding. Tight line height is available for compact copy. Span has no margin by default, border, or padding. FieldLabel mirrors the themed Web Awesome label typography, 9px inline inset, and bottom gap.
+- controlMargins adds the shared control gutter outside selected physical edges without changing border or padding; avoid duplicating a parent inset. Spans retain inline display and native inline margin behavior.
 
 ## Accessibility
 

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

@@ -15,6 +15,9 @@ Provide complete toolbar action geometry through configuration, including semant
 - 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. Each control stays whole: an icon sits beside its label on one row and no trigger gets a fixed width. Use overflow=wrap for independent links that should move as whole actions to another row on narrow surfaces.
 - 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.
+- Use tileTone for a contained single group containing only a direct decorative SVG icon; interactive or mixed groups retain their existing control chrome.
+- Set expandedOverflow=visible on an expanded search to anchor application suggestions, date pickers, or help below the group without overriding its geometry.
+- Use typed hideBelow/showBelow lengths with wireToolbarVisibility(root) for per-item toolbar priority; keep primary actions available and provide a showBelow overflow alternative.
 
 **Not when:**
 
@@ -30,11 +33,12 @@ Provide complete toolbar action geometry through configuration, including semant
 
 - JavaScript: `@kerfjs/ui/toolbar-control-group` — exports `ToolbarActionLink`, `ToolbarControlGroup`.
 - CSS: the browser build of `@kerfjs/ui/toolbar-control-group` pulls its CSS automatically; import `@kerfjs/ui/toolbar-control-group.css` manually only without the `browser` export condition.
+- Wiring: `wireToolbarVisibility` from `@kerfjs/ui/wire-toolbar-visibility` (optional).
 - Declared side effects: browser-condition-css.
 
 ## Props
 
-Exact prop names and types: [`@kerfjs/ui/toolbar-control-group`](../public-api-signatures-v1.md#kerfjsuitoolbar-control-group) in `public-api-signatures-v1.md`. Do not infer props from examples.
+Exact prop names and types: [`@kerfjs/ui/toolbar-control-group`](../public-api-signatures-v1.md#kerfjsuitoolbar-control-group), [`@kerfjs/ui/wire-toolbar-visibility`](../public-api-signatures-v1.md#kerfjsuiwire-toolbar-visibility) in `public-api-signatures-v1.md`. Do not infer props from examples.
 
 **Variants (configure, do not restyle):**
 
@@ -54,6 +58,14 @@ Exact prop names and types: [`@kerfjs/ui/toolbar-control-group`](../public-api-s
 - relocate on panel collapse
 - avatar scrim
 - contained avatar background on a single group or selected multi-button highlight
+- neutral, brand, success, warning, or danger quiet icon tile tone
+- clip or visible app-owned overflow while a search is expanded
+- typed hideBelow/showBelow thresholds at the nearest Toolbar content width
+
+**CSS-value props** (typed builders from `@kerfjs/ui/css-values`; raw CSS strings are rejected):
+
+- `hideBelow`: length grammar; raw values: forbid; helpers `px`, `rem`, `em`, `pct`, `space`, `lengthVar`, `calc` — e.g. `hideBelow={px(416)}`
+- `showBelow`: length grammar; raw values: forbid; helpers `px`, `rem`, `em`, `pct`, `space`, `lengthVar`, `calc` — e.g. `showBelow={px(416)}`
 
 ## Composition
 
@@ -70,7 +82,14 @@ Zones (a zone is bound to JSX only through its listed prop; never assume the zon
 
 **The app owns:** actions; link destination and copy; pressed state; expanded state; avatar image URL.
 
-No wiring helper.
+**Wiring:** `wireToolbarVisibility` is optional.
+
+**Wiring-owned state attributes** — never render, remove, or branch on these as app state:
+
+- `data-toolbar-width-hidden` on `ToolbarText, ToolbarControlGroup and its paired busy status` (`wireToolbarVisibility`): True when typed hideBelow/showBelow thresholds hide this item at the nearest Toolbar content width. Re-applied after rendering; disposal restores prior markers.
+- `data-toolbar-visibility-probe` on `private aria-hidden measurement boxes under Toolbar` (`wireToolbarVisibility`): Internal out-of-flow CSS length resolver; created and removed by wireToolbarVisibility.
+- `data-morph-preserve` on `private aria-hidden measurement boxes and visibility state children` (`wireToolbarVisibility`): Keeps helper-owned geometry and state across Kerf renders; replacement and explicit removal are repaired, and disposal removes them.
+- `data-toolbar-visibility-state` on `private hidden children of width-managed items and paired busy statuses` (`wireToolbarVisibility`): Preserves actual CSS visibility while rendering removes a transient parent marker, preventing geometry-driven render feedback.
 
 ## Geometry
 
@@ -91,7 +110,7 @@ Never put `kui-toolbar-action-link` on an element you write; render `ToolbarActi
 
 Never put `kui-toolbar-control-group` on an element you write; render `ToolbarControlGroup` instead (`KUI-L103`).
 
-Public tokens it reads: `--kui-color-brand-on-quiet`, `--kui-color-pop-border-normal`, `--kui-color-pop-fill-normal`, `--kui-color-pop-on-normal`, `--kui-color-pop-on-quiet`, `--kui-color-neutral-border-loud`, `--kui-color-neutral-border-normal`, `--kui-color-neutral-fill-loud`, `--kui-color-neutral-fill-normal`, `--kui-color-neutral-on-loud`, `--kui-color-neutral-on-quiet`, `--kui-color-surface`, `--kui-focus-ring`, `--kui-shadow-s`, `--kui-toolbar-control-background`, `--kui-toolbar-control-border`, `--kui-toolbar-control-color`, `--kui-toolbar-control-dark-border`, `--kui-toolbar-control-hover-background`, `--kui-toolbar-control-pressed-background`, `--kui-toolbar-control-pressed-border`, `--kui-toolbar-control-pressed-color`, `--kui-toolbar-control-selected-background`, `--kui-toolbar-control-selected-color`, `--kui-toolbar-control-selected-shadow`. Set a token only where its public contract allows; prefer a prop.
+Public tokens it reads: `--kui-color-brand-on-quiet`, `--kui-color-pop-border-normal`, `--kui-color-pop-fill-normal`, `--kui-color-pop-on-normal`, `--kui-color-pop-on-quiet`, `--kui-color-neutral-border-loud`, `--kui-color-neutral-border-normal`, `--kui-color-neutral-fill-loud`, `--kui-color-neutral-fill-normal`, `--kui-color-neutral-on-loud`, `--kui-color-neutral-on-quiet`, `--kui-color-surface`, `--kui-focus-ring`, `--kui-shadow-s`, `--kui-toolbar-control-background`, `--kui-toolbar-control-border`, `--kui-toolbar-control-color`, `--kui-toolbar-control-dark-border`, `--kui-toolbar-control-hover-background`, `--kui-toolbar-control-pressed-background`, `--kui-toolbar-control-pressed-border`, `--kui-toolbar-control-pressed-color`, `--kui-toolbar-control-selected-background`, `--kui-toolbar-control-selected-color`, `--kui-toolbar-control-selected-shadow`, `--kui-color-neutral-fill-quiet`, `--kui-color-neutral-border-quiet`, `--kui-color-brand-fill-quiet`, `--kui-color-brand-border-quiet`, `--kui-color-success-fill-quiet`, `--kui-color-success-border-quiet`, `--kui-color-success-on-quiet`, `--kui-color-warning-fill-quiet`, `--kui-color-warning-border-quiet`, `--kui-color-warning-on-quiet`, `--kui-color-danger-fill-quiet`, `--kui-color-danger-border-quiet`, `--kui-color-danger-on-quiet`. 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/toolbar-text.md

@@ -10,11 +10,13 @@ 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.
+- Use tone=dark for title or filename text on a loud toolbar surface, matching dark ToolbarControlGroups.
+- Use typed hideBelow/showBelow lengths with wireToolbarVisibility(root) for per-item toolbar priority; keep primary actions available and provide a showBelow overflow alternative.
 
 **Not when:**
 
 - Do not omit headingLevel when the text is the page or section heading.
-- Large, default, and small are intentionally quiet toolbar identity text and have no tone option. Use xlarge-fixed for a normal-color toolbar heading at the fixed font-l step; use Text with an h2-h6 variant for a content subsection title, or ListHeader for a list or menu section.
+- Large, default, and small are intentionally quiet toolbar identity text in default tone. Use xlarge-fixed for a normal-color toolbar heading at the fixed font-l step; use Text with an h2-h6 variant for a content subsection title, or ListHeader for a list or menu section.
 
 **Alternatives:**
 
@@ -25,11 +27,12 @@ Extra-large through extra-small toolbar identity text.
 
 - JavaScript: `@kerfjs/ui/toolbar-text` — exports `ToolbarText`.
 - CSS: the browser build of `@kerfjs/ui/toolbar-text` pulls its CSS automatically; import `@kerfjs/ui/toolbar-text.css` manually only without the `browser` export condition.
+- Wiring: `wireToolbarVisibility` from `@kerfjs/ui/wire-toolbar-visibility` (optional).
 - Declared side effects: browser-condition-css.
 
 ## Props
 
-Exact prop names and types: [`@kerfjs/ui/toolbar-text`](../public-api-signatures-v1.md#kerfjsuitoolbar-text) in `public-api-signatures-v1.md`. Do not infer props from examples.
+Exact prop names and types: [`@kerfjs/ui/toolbar-text`](../public-api-signatures-v1.md#kerfjsuitoolbar-text), [`@kerfjs/ui/wire-toolbar-visibility`](../public-api-signatures-v1.md#kerfjsuiwire-toolbar-visibility) in `public-api-signatures-v1.md`. Do not infer props from examples.
 
 **Variants (configure, do not restyle):**
 
@@ -40,6 +43,13 @@ Exact prop names and types: [`@kerfjs/ui/toolbar-text`](../public-api-signatures
 - small
 - xsmall
 - placeholder (loading)
+- dark (loud-surface foreground)
+- typed hideBelow/showBelow thresholds at the nearest Toolbar content width
+
+**CSS-value props** (typed builders from `@kerfjs/ui/css-values`; raw CSS strings are rejected):
+
+- `hideBelow`: length grammar; raw values: forbid; helpers `px`, `rem`, `em`, `pct`, `space`, `lengthVar`, `calc` — e.g. `hideBelow={px(416)}`
+- `showBelow`: length grammar; raw values: forbid; helpers `px`, `rem`, `em`, `pct`, `space`, `lengthVar`, `calc` — e.g. `showBelow={px(416)}`
 
 ## Composition
 
@@ -51,7 +61,14 @@ Exact prop names and types: [`@kerfjs/ui/toolbar-text`](../public-api-signatures
 
 **The app owns:** text; responsive priority; the delegated action handler and display-to-input editing swap.
 
-No wiring helper.
+**Wiring:** `wireToolbarVisibility` is optional.
+
+**Wiring-owned state attributes** — never render, remove, or branch on these as app state:
+
+- `data-toolbar-width-hidden` on `ToolbarText, ToolbarControlGroup and its paired busy status` (`wireToolbarVisibility`): True when typed hideBelow/showBelow thresholds hide this item at the nearest Toolbar content width. Re-applied after rendering; disposal restores prior markers.
+- `data-toolbar-visibility-probe` on `private aria-hidden measurement boxes under Toolbar` (`wireToolbarVisibility`): Internal out-of-flow CSS length resolver; created and removed by wireToolbarVisibility.
+- `data-morph-preserve` on `private aria-hidden measurement boxes and visibility state children` (`wireToolbarVisibility`): Keeps helper-owned geometry and state across Kerf renders; replacement and explicit removal are repaired, and disposal removes them.
+- `data-toolbar-visibility-state` on `private hidden children of width-managed items and paired busy statuses` (`wireToolbarVisibility`): Preserves actual CSS visibility while rendering removes a transient parent marker, preventing geometry-driven render feedback.
 
 ## Geometry
 
@@ -70,7 +87,7 @@ Public class hooks (select for layout placement only, never to change the compon
 
 Never put `kui-toolbar-text` on an element you write; render `ToolbarText` instead (`KUI-L103`).
 
-Public tokens it reads: `--kui-color-neutral-on-quiet`, `--kui-color-text`, `--kui-font-2xs`, `--kui-font-2xl`, `--kui-font-l`, `--kui-font-m`, `--kui-font-s`, `--kui-font-xs`. Set a token only where its public contract allows; prefer a prop.
+Public tokens it reads: `--kui-color-neutral-on-quiet`, `--kui-color-text`, `--kui-font-2xs`, `--kui-font-2xl`, `--kui-font-l`, `--kui-font-m`, `--kui-font-s`, `--kui-font-xs`, `--kui-color-neutral-on-loud`. 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`).