@kerfjs/ui 5.0.0-beta.75 → 5.0.0-beta.77

package/ai/component-composition.json

@@ -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",
@@ -908,6 +914,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 +1472,7 @@
       ],
       "wiring": {
         "required": false,
-        "helpers": ["wireScrollDividers"],
+        "helpers": ["wireScrollDividers", "wireToolbarVisibility"],
         "obligations": [],
         "stateAttributes": [
           {
@@ -1474,6 +1486,18 @@
             "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."
           }
         ]
       },
@@ -1570,9 +1594,22 @@
       ],
       "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."
+          }
+        ]
       },
       "responsive": { "owner": "not-applicable", "behaviors": [] },
       "layout": {
@@ -1585,7 +1622,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 +1677,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": [],
@@ -1775,9 +1848,22 @@
       ],
       "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."
+          }
+        ]
       },
       "responsive": { "owner": "not-applicable", "behaviors": [] },
       "layout": {
@@ -1790,7 +1876,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 +1911,8 @@
           "--kui-font-l",
           "--kui-font-m",
           "--kui-font-s",
-          "--kui-font-xs"
+          "--kui-font-xs",
+          "--kui-color-neutral-on-loud"
         ]
       },
       "diagnostics": [],
@@ -1849,11 +1959,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."
           ]
         }
       },
@@ -2107,7 +2218,7 @@
           "required": false
         },
         {
-          "id": "typed gap and flex choices",
+          "id": "typed gap, flex, and physical-side inset choices",
           "owner": "application",
           "required": false
         }
@@ -2124,8 +2235,9 @@
         "geometry": {
           "margin": "none",
           "border": "none",
-          "padding": "none",
+          "padding": "conditional",
           "notes": [
+            "textInsets adds 17px and controlInsets adds 8px on selected physical sides; text wins on overlap.",
             "Fixed tracks use minmax(0, 1fr); responsive tracks use auto-fit with a minimum width capped at 100%, preserving equal distribution without narrow overflow."
           ]
         }
@@ -2786,6 +2898,11 @@
           "owner": "application",
           "required": false
         },
+        {
+          "id": "whether the item needs a surface or semantic appearance",
+          "owner": "application",
+          "required": false
+        },
         { "id": "corner shape", "owner": "application", "required": false },
         {
           "id": "region semantics and accessible name",
@@ -2817,7 +2934,7 @@
           "border": "self",
           "padding": "self",
           "notes": [
-            "The 1px border is always reserved and transparent unless frame=\"framed\", so framed and unframed items share the same geometry."
+            "The 1px border is always reserved; transparent items paint it only when frame=\"framed\", while surface and semantic appearances coordinate its color with their background and foreground."
           ]
         }
       },

package/ai/components/README.md

@@ -38,7 +38,7 @@ Exact prop and callback types live in [`public-api-signatures-v1.md`](../public-
 - [Spacer](./spacer.md) — Express an intentional empty dimension or consume remaining flex space without application-owned spacer markup or raw CSS lengths.
 - [ListInsetControl](./list-inset-control.md) — Apply the standard 8px outer margin to all physical sides of a self-bordered control by default, or only the sides selected with the canonical Sides contract.
 - [ListInsetText](./list-inset-text.md) — Apply the full 8px margin + 1px transparent border + 8px padding to all physical sides of bare text by default, or only the sides selected with the canonical Sides contract.
-- [ContentItem](./content-item.md) — Render one self-contained .kui-content child that owns its 8px inline margin, real 1px border, 8px padding, and radius, with framing and shape chosen by typed props instead of hand-written modifier classes.
+- [ContentItem](./content-item.md) — Render one self-contained .kui-content child that owns its 8px inline margin, real 1px border, 8px padding, radius, and optional coordinated surface colors.
 
 ## Kerf UI — Navigation
 

package/ai/components/badge.md

@@ -29,7 +29,7 @@ Exact prop names and types: [`@kerfjs/ui/badge`](../public-api-signatures-v1.md#
 
 **Variants (configure, do not restyle):**
 
-- neutral, brand, pop, success, warning, or danger tone
+- neutral, info, pop, success, warning, or danger tone
 - quiet, solid, or outline appearance
 - pill or rounded shape
 - compact or default size, or a text-free dot (size: 'dot')

package/ai/components/chip.md

@@ -29,7 +29,7 @@ Exact prop names and types: [`@kerfjs/ui/chip`](../public-api-signatures-v1.md#k
 
 **Variants (configure, do not restyle):**
 
-- neutral, brand, pop, success, warning, or danger tone
+- neutral, info, pop, success, warning, or danger tone
 - quiet, solid, or outline appearance
 - pill or rounded shape
 - compact or default size

package/ai/components/content-item.md

@@ -4,14 +4,15 @@
 
 `@kerfjs/ui:content-item` · Kerf UI · component · Structure
 
-One self-contained content child with the shared 8px margin + 1px border + 8px padding geometry, a typed frame, and a rounded or pill shape.
+One self-contained content child with shared geometry plus typed transparent, surface, or semantic appearance, frame, and shape choices.
 
 ## When to use
 
-Render one self-contained .kui-content child that owns its 8px inline margin, real 1px border, 8px padding, and radius, with framing and shape chosen by typed props instead of hand-written modifier classes.
+Render one self-contained .kui-content child that owns its 8px inline margin, real 1px border, 8px padding, radius, and optional coordinated surface colors.
 
 - An ordinary surface-like child of a Pane or .kui-content stack needs the shared content-item geometry so its content edge lands at the standard 17px inset.
 - A content item marks a real distinction and must read as visibly bounded: pass frame="framed" (the border is always reserved, so geometry does not change).
+- A content item needs the base surface or a coordinated semantic status treatment: pass appearance="surface" or a semantic appearance such as success or danger.
 - A content item should follow a pill control's 22px radius: pass shape="pill".
 - A selectable rich card needs nested controls: use selectionMode="multiple" inside a labeled List multi-select grid.
 
@@ -19,7 +20,7 @@ Render one self-contained .kui-content child that owns its 8px inline margin, re
 
 - Do not wrap a component that already owns content-item geometry (ListItem, ListHeader, StateBanner, Toolbar, ValueTable) or pad around a ContentItem; either double-insets.
 - Do not frame an item only to make it look contained; hierarchy comes from alignment, spacing, and type first.
-- Do not use it as a filled or lowered card; use SunkenPanel for a lowered surface.
+- Do not use its surface appearance for a lowered inset panel around a stack; use SunkenPanel for that structure.
 - Do not use it for bare text alone; use ListInsetText, which adds the same inset without claiming a surface.
 
 **Alternatives:**
@@ -44,6 +45,8 @@ Exact prop names and types: [`@kerfjs/ui/content-item`](../public-api-signatures
 - framed rounded item
 - pill item
 - framed pill item
+- base surface item
+- neutral, info, pop, success, warning, or danger semantic item
 - named focus-target region
 - multi-select rich grid row
 
@@ -55,7 +58,7 @@ Exact prop names and types: [`@kerfjs/ui/content-item`](../public-api-signatures
 
 ## State and wiring
 
-**The app owns:** the item content; whether the item marks a real distinction that warrants a visible frame; corner shape; region semantics and accessible name; whether the item is a programmatic focus target; the selection set and Shift/Cmd extension for multi-select rich cards.
+**The app owns:** the item content; whether the item marks a real distinction that warrants a visible frame; whether the item needs a surface or semantic appearance; corner shape; region semantics and accessible name; whether the item is a programmatic focus target; the selection set and Shift/Cmd extension for multi-select rich cards.
 
 No wiring helper.
 
@@ -63,7 +66,7 @@ No wiring helper.
 
 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.
 
-- The 1px border is always reserved and transparent unless frame="framed", so framed and unframed items share the same geometry.
+- The 1px border is always reserved; transparent items paint it only when frame="framed", while surface and semantic appearances coordinate its color with their background and foreground.
 
 ## Accessibility
 

package/ai/components/document-baseline.md

@@ -4,13 +4,13 @@
 
 `@kerfjs/ui:document-baseline` · Kerf UI · CSS composition · Foundation
 
-Opt-in document-level defaults: border-box sizing, body margin/font/surface, link color, and the html → body → .kui-app-root full-height chain.
+Opt-in document-level defaults: border-box sizing, body margin/font/surface, native table-cell and form-control font metrics, link color, and the html → body → .kui-app-root full-height chain.
 
 ## When to use
 
 Let an application opt into Kerf UI-owned document defaults and a definite full-height chain for a percentage-height application shell.
 
-- An application wants Kerf UI to own document-level box sizing, body typography, surface, and link color.
+- An application wants Kerf UI to own document-level box sizing, body typography, native table-cell and form-control font metrics, surface, and link color.
 - A full-height shell (Workbench, SplitView, NavStack, or TabScaffold) mounts into one direct container: put .kui-app-root on that container.
 
 **Not when:**

package/ai/components/grid.md

@@ -4,7 +4,7 @@
 
 `@kerfjs/ui:grid` · Kerf UI · component · Structure
 
-Equal-width columns with a fixed count or a minimum-width responsive mode, typed gaps, and optional flex participation.
+Equal-width columns with a fixed count or a minimum-width responsive mode, typed gaps, physical-side text/control insets, and optional flex participation.
 
 ## When to use
 
@@ -45,6 +45,7 @@ Exact prop names and types: [`@kerfjs/ui/grid`](../public-api-signatures-v1.md#k
 - named none/2xs/xs/s/m/l/xl token gap
 - typed CssLength gap
 - boolean, finite-keyword, or typed CssFlex flex
+- top/right/bottom/left text and control inset combinations
 - fill: the layout root fills a definite-height parent
 - rootAttributes: safe data-\* metadata on the root
 - selectionMode=multiple: labeled multi-select grid for ContentItem tiles
@@ -63,14 +64,15 @@ Exact prop names and types: [`@kerfjs/ui/grid`](../public-api-signatures-v1.md#k
 
 ## State and wiring
 
-**The app owns:** child semantics and content; fixed column count or responsive minimum width; typed gap and flex choices.
+**The app owns:** child semantics and content; fixed column count or responsive minimum width; typed gap, flex, and physical-side inset choices.
 
 No wiring helper.
 
 ## Geometry
 
-Margin: none · border: none · padding: none (layout role: structure). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+Margin: none · border: none · padding: conditional (layout role: structure). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
 
+- textInsets adds 17px and controlInsets adds 8px on selected physical sides; text wins on overlap.
 - Fixed tracks use minmax(0, 1fr); responsive tracks use auto-fit with a minimum width capped at 100%, preserving equal distribution without narrow overflow.
 
 ## Accessibility

package/ai/components/lucide-icon.md

@@ -32,6 +32,7 @@ Exact prop names and types: [`@kerfjs/ui/lucide-icon`](../public-api-signatures-
 
 - decorative
 - labeled
+- inline text flow
 - outline (default appearance)
 - solid (appearance=solid)
 
@@ -73,6 +74,16 @@ Set an icon foreground with a semantic color token; omit color to inherit from s
 <LucideIcon icon={Bell} name="alert" color={uiColor('warning-on-quiet')} />
 ```
 
+### Inline with text
+
+Let a decorative icon flow inside Text or other prose while preserving its inherited 1em size.
+
+```tsx
+<Text>
+  Ready <LucideIcon icon={Bell} name="notification" inline /> now.
+</Text>
+```
+
 ## Styling boundary
 
 The component owns its own styles. Configure it through its props and variants; do not override its internals.

package/ai/components/nav-stack.md

@@ -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.

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/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,12 @@ 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.
 
 ## Geometry
 
@@ -91,7 +108,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,12 @@ 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.
 
 ## Geometry
 
@@ -70,7 +85,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`).