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

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`).
 

package/ai/components/toolbar.md

@@ -9,6 +9,7 @@
 Leading, centered, and trailing toolbar composition.
 
 - Compose application chrome or a page, panel, or dialog heading with leading, center, and trailing regions.
+- 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:**
 
@@ -17,13 +18,15 @@ Leading, centered, and trailing toolbar composition.
 ## Imports
 
 - JavaScript: `@kerfjs/ui/toolbar` — exports `Toolbar`.
+- JavaScript: `@kerfjs/ui/wire-toolbar-visibility` — exports `wireToolbarVisibility`.
 - CSS: the browser build of `@kerfjs/ui/toolbar` pulls its CSS automatically; import `@kerfjs/ui/toolbar.css` manually only without the `browser` export condition.
 - Wiring: `wireScrollDividers` from `@kerfjs/ui/wire-scroll-dividers` (optional).
+- Wiring: `wireToolbarVisibility` from `@kerfjs/ui/wire-toolbar-visibility` (optional).
 - Declared side effects: browser-condition-css.
 
 ## Props
 
-Exact prop names and types: [`@kerfjs/ui/toolbar`](../public-api-signatures-v1.md#kerfjsuitoolbar), [`@kerfjs/ui/wire-scroll-dividers`](../public-api-signatures-v1.md#kerfjsuiwire-scroll-dividers) in `public-api-signatures-v1.md`. Do not infer props from examples.
+Exact prop names and types: [`@kerfjs/ui/toolbar`](../public-api-signatures-v1.md#kerfjsuitoolbar), [`@kerfjs/ui/wire-toolbar-visibility`](../public-api-signatures-v1.md#kerfjsuiwire-toolbar-visibility), [`@kerfjs/ui/wire-scroll-dividers`](../public-api-signatures-v1.md#kerfjsuiwire-scroll-dividers) in `public-api-signatures-v1.md`. Do not infer props from examples.
 
 **Variants (configure, do not restyle):**
 
@@ -38,13 +41,14 @@ Exact prop names and types: [`@kerfjs/ui/toolbar`](../public-api-signatures-v1.m
 - 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)
+- typed hideBelow/showBelow thresholds at the nearest Toolbar content width
 
 ## Composition
 
 - Parents: any.
 - Contexts: `application-chrome`, `page-header`, `panel-header`, `dialog-header`.
 - 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).
+- Built from: [ToolbarText](./toolbar-text.md), [ToolbarControlGroup](./toolbar-control-group.md), [Button](./wa-button.md), [PopupMenu](./popup-menu.md).
 
 Zones (a zone is bound to JSX only through its listed prop; never assume the zone id is a prop):
 
@@ -56,12 +60,14 @@ Zones (a zone is bound to JSX only through its listed prop; never assume the zon
 
 **The app owns:** actions; command availability; responsive relocation; which screen edges an app bar or bottom bar outside a Pane header or footer claims for device safe areas (safeAreaEdges).
 
-**Wiring:** `wireScrollDividers` is optional.
+**Wiring:** `wireScrollDividers`, `wireToolbarVisibility` is optional.
 
 **Wiring-owned state attributes** — never render, remove, or branch on these as app state:
 
 - `data-scroll-overflow` on `the targets scroller` (`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 `a Toolbar named as targets chrome` (`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.
+- `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
 
@@ -92,6 +98,6 @@ Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-
 
 ## Related
 
-- Components: [ToolbarText](./toolbar-text.md), [ToolbarControlGroup](./toolbar-control-group.md), [Button](./wa-button.md).
+- Components: [ToolbarText](./toolbar-text.md), [ToolbarControlGroup](./toolbar-control-group.md), [Button](./wa-button.md), [PopupMenu](./popup-menu.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.76` and `kerfjs@5.0.0-beta.76`. 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.77` and `kerfjs@5.0.0-beta.77`. 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`
 
@@ -217,13 +217,21 @@ export { Sides, Toolbar, type ToolbarConfig, type ToolbarPosition, type ToolbarP
 
 ```ts
 import * as kerfjs from 'kerfjs';
+import { CssLength } from './css-values.js';
 
 type ToolbarTextSize = 'xlarge' | 'xlarge-fixed' | 'large' | 'default' | 'small' | 'xsmall';
+type ToolbarTextTone = 'default' | 'dark';
 /** ARIA heading level for a title exposed as a heading landmark. */
 type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
 interface ToolbarTextBaseProps {
     text: string;
     size?: ToolbarTextSize;
+    /** Use dark-toolbar foregrounds on a dark or photo-backed toolbar. */
+    tone?: ToolbarTextTone;
+    /** Hide below this Toolbar content width; requires wireToolbarVisibility. */
+    hideBelow?: CssLength;
+    /** Show only below this Toolbar content width; requires wireToolbarVisibility. */
+    showBelow?: CssLength;
     className?: string;
     /** Optional id, e.g. so a dialog can reference the title via aria-labelledby. */
     id?: string;
@@ -264,9 +272,9 @@ type ToolbarTextProps = ToolbarTextBaseProps & (({
     wrap?: never;
     maxLines?: never;
 });
-declare function ToolbarText({ text, size, className, id, headingLevel, placeholder, wrap, ellipsis, maxLines, fill, slot, action, }: ToolbarTextProps): kerfjs.SafeHtml;
+declare function ToolbarText({ text, size, tone, hideBelow, showBelow, className, id, headingLevel, placeholder, wrap, ellipsis, maxLines, fill, slot, action, }: ToolbarTextProps): kerfjs.SafeHtml;
 
-export { type HeadingLevel, ToolbarText, type ToolbarTextProps, type ToolbarTextSize };
+export { type HeadingLevel, ToolbarText, type ToolbarTextProps, type ToolbarTextSize, type ToolbarTextTone };
 ```
 
 ## `@kerfjs/ui/toolbar-control-group`
@@ -274,9 +282,12 @@ export { type HeadingLevel, ToolbarText, type ToolbarTextProps, type ToolbarText
 ```ts
 import * as kerfjs from 'kerfjs';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { CssLength } from './css-values.js';
 
 type ToolbarControlGroupAppearance = 'contained' | 'borderless';
 type ToolbarControlGroupTone = 'default' | 'dark';
+/** Quiet palette for a contained, single decorative icon tile. */
+type ToolbarControlGroupTileTone = 'neutral' | 'brand' | 'success' | 'warning' | 'danger';
 type ToolbarControlGroupButtonAppearance = 'plain' | 'push';
 type ToolbarControlGroupShape = 'pill' | 'rounded';
 type ToolbarControlGroupSize = 'default' | 'compact';
@@ -286,6 +297,7 @@ type ToolbarControlGroupFocusRing = 'control' | 'outline' | 'halo';
 type ToolbarControlGroupSelectedChrome = 'raised' | 'filled' | 'outline';
 type ToolbarControlGroupSelectedTone = 'brand' | 'neutral' | 'pop';
 type ToolbarControlGroupOverflow = 'visible' | 'scroll' | 'wrap';
+type ToolbarControlGroupExpandedOverflow = 'clip' | 'visible';
 type ToolbarControlGroupMenuInset = 'standard' | 'compact' | 'list-zero';
 type ToolbarControlGroupVisibility = 'always' | 'compact-only' | 'hide-collapsed-tiny' | 'yield-to-expanded-sibling';
 type ToolbarControlGroupSizing = 'content' | 'grow' | 'fill';
@@ -314,6 +326,8 @@ interface ToolbarControlGroupProps {
     single?: boolean;
     appearance?: ToolbarControlGroupAppearance;
     tone?: ToolbarControlGroupTone;
+    /** Quiet fill, matching border and foreground for a contained single group whose only child is a decorative SVG. Ignored for interactive or mixed content. */
+    tileTone?: ToolbarControlGroupTileTone;
     buttonAppearance?: ToolbarControlGroupButtonAppearance;
     /** Corner shape: fully round `pill` (default) or a softer `rounded` rectangle. */
     shape?: ToolbarControlGroupShape;
@@ -330,8 +344,14 @@ interface ToolbarControlGroupProps {
     menuInset?: ToolbarControlGroupMenuInset;
     /** Keep an overlong row inside the available width by scrolling or wrapping. */
     overflow?: ToolbarControlGroupOverflow;
+    /** Let app-owned anchored surfaces extend outside an expanded search group. Collapsed searches retain their clipping. */
+    expandedOverflow?: ToolbarControlGroupExpandedOverflow;
     /** Responsive visibility owned by the enclosing Toolbar container. */
     visibility?: ToolbarControlGroupVisibility;
+    /** Hide below this Toolbar content width; requires wireToolbarVisibility. */
+    hideBelow?: CssLength;
+    /** Show only below this Toolbar content width; requires wireToolbarVisibility. */
+    showBelow?: CssLength;
     /** Intrinsic (default), grow from a basis, or occupy a full wrapping row. */
     sizing?: ToolbarControlGroupSizing;
     /** Place this group at the end of its flex row in a wrapping Toolbar zone. */
@@ -354,9 +374,9 @@ interface ToolbarControlGroupProps {
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
 }
-declare function ToolbarControlGroup({ children, label, className, expanded, single, appearance, tone, buttonAppearance, shape, size, density, content, focusRing, selectedChrome, selectedTone, nestedDropdown, menuInset, overflow, visibility, sizing, placement, growBasis, relocateOnCollapse, scrim, busy, busyLabel, avatarImage, slot, }: ToolbarControlGroupProps): kerfjs.SafeHtml;
+declare function ToolbarControlGroup({ children, label, className, expanded, single, appearance, tone, tileTone, buttonAppearance, shape, size, density, content, focusRing, selectedChrome, selectedTone, nestedDropdown, menuInset, overflow, expandedOverflow, visibility, hideBelow, showBelow, sizing, placement, growBasis, relocateOnCollapse, scrim, busy, busyLabel, avatarImage, slot, }: ToolbarControlGroupProps): kerfjs.SafeHtml;
 
-export { ToolbarActionLink, type ToolbarActionLinkProps, ToolbarControlGroup, type ToolbarControlGroupAppearance, type ToolbarControlGroupButtonAppearance, type ToolbarControlGroupContent, type ToolbarControlGroupDensity, type ToolbarControlGroupFocusRing, type ToolbarControlGroupMenuInset, type ToolbarControlGroupOverflow, type ToolbarControlGroupPlacement, type ToolbarControlGroupProps, type ToolbarControlGroupSelectedChrome, type ToolbarControlGroupSelectedTone, type ToolbarControlGroupShape, type ToolbarControlGroupSize, type ToolbarControlGroupSizing, type ToolbarControlGroupTone, type ToolbarControlGroupVisibility };
+export { ToolbarActionLink, type ToolbarActionLinkProps, ToolbarControlGroup, type ToolbarControlGroupAppearance, type ToolbarControlGroupButtonAppearance, type ToolbarControlGroupContent, type ToolbarControlGroupDensity, type ToolbarControlGroupExpandedOverflow, type ToolbarControlGroupFocusRing, type ToolbarControlGroupMenuInset, type ToolbarControlGroupOverflow, type ToolbarControlGroupPlacement, type ToolbarControlGroupProps, type ToolbarControlGroupSelectedChrome, type ToolbarControlGroupSelectedTone, type ToolbarControlGroupShape, type ToolbarControlGroupSize, type ToolbarControlGroupSizing, type ToolbarControlGroupTileTone, type ToolbarControlGroupTone, type ToolbarControlGroupVisibility };
 ```
 
 ## `@kerfjs/ui/floating-toolbar`
@@ -525,6 +545,7 @@ export { PopupMenu, type PopupMenuDivider, type PopupMenuElement, type PopupMenu
 ```ts
 import { SafeHtml } from 'kerfjs';
 import { HeadingLevel } from './toolbar-text.js';
+import './css-values.js';
 
 type ListHeaderRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
     'data-component'?: never;
@@ -1270,6 +1291,7 @@ import { ToolbarConfig } from './toolbar.js';
 import { ToolbarTextSize, HeadingLevel } from './toolbar-text.js';
 import { PaneAppearance } from './pane.js';
 import './sides-BPSWde0A.js';
+import './css-values.js';
 
 /**
  * One entry in a {@link NavStack}. The app owns the stack as an array (usually a
@@ -2751,6 +2773,7 @@ interface SelectBaseProps<Value extends string = string> {
     /** Supporting text shown below the control and associated with its combobox. */
     hint?: string;
     disabled?: boolean;
+    /** Match menu width to the trigger; default menus grow to content within viewport gutters. */
     fitMenu?: boolean;
     /** Render as an unanimated loading skeleton: the label above a static, empty control box. */
     placeholder?: boolean;
@@ -3312,6 +3335,24 @@ declare function LucideIcon({ icon, name, appearance, className, color, inline,
 export { LucideIcon, type LucideIconProps, type LucideIconSize, type LucideNode };
 ```
 
+## `@kerfjs/ui/wire-toolbar-visibility`
+
+```ts
+type Root = HTMLElement | Document;
+/**
+ * Wire ToolbarText and ToolbarControlGroup width thresholds below root.
+ * Below is strict: hideBelow hides at width < threshold; showBelow hides at
+ * width >= threshold. Percentages use the closest Toolbar's content box;
+ * em and custom properties use the item's own inherited context. Invalid,
+ * negative, unresolved, or contradictory thresholds leave the item visible.
+ * This helper changes only a component-owned visibility marker. Existing
+ * CSS visibility policies still apply. Dispose with the owning application.
+ */
+declare function wireToolbarVisibility(root: Root): () => void;
+
+export { wireToolbarVisibility };
+```
+
 ## `@kerfjs/ui/surface-scaffold`
 
 ```ts
@@ -3353,6 +3394,7 @@ export { DialogSurface, type DialogSurfacePresentation, type DialogSurfaceProps,
 import * as kerfjs from 'kerfjs';
 import { KerfBaseAttrs } from 'kerfjs/jsx-runtime';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { S as Sides } from './sides-BPSWde0A.js';
 import { CssForegroundColor } from './css-values.js';
 
 type FieldLabelProps = Omit<KerfBaseAttrs, 'children' | 'class' | 'className'> & {
@@ -3384,6 +3426,8 @@ type TextCommonProps = Omit<KerfBaseAttrs, 'children' | 'class' | 'className'> &
     font?: TextFont;
     /** Transparent alignment border or no border when embedded in owner chrome. */
     border?: TextBorder;
+    /** Add the shared control gutter outside selected physical edges. */
+    controlMargins?: Sides;
     /** Remove the block variant's item padding and border in compact content. */
     flush?: boolean;
     /** Use compact leading for short dialog or metadata copy. */
@@ -3407,9 +3451,9 @@ type TextProps = TextCommonProps & ({
  * content-item padding; `span` adds no box geometry.
  * All ordinary native heading/paragraph attributes pass through to the element.
  */
-declare function Text({ variant: Variant, tone, color, size, font, border, flush, lineHeight, wrap, maxLines, children, class: classValue, className, style, ...attributes }: TextProps): kerfjs.SafeHtml;
+declare function Text({ variant: Variant, tone, color, size, font, border, flush, controlMargins, lineHeight, wrap, maxLines, children, class: classValue, className, style, ...attributes }: TextProps): kerfjs.SafeHtml;
 
-export { FieldLabel, type FieldLabelProps, Text, type TextBorder, type TextContent, type TextFont, type TextLineHeight, type TextProps, type TextSize, type TextTone, type TextVariant, type TextWrap };
+export { FieldLabel, type FieldLabelProps, Sides, Text, type TextBorder, type TextContent, type TextFont, type TextLineHeight, type TextProps, type TextSize, type TextTone, type TextVariant, type TextWrap };
 ```
 
 ## `@kerfjs/ui/row`

package/ai/skill.md

@@ -1,7 +1,7 @@
 ---
 name: kerf-ui
 description: Build interfaces with kerfjs and the @kerfjs/ui production component package. Use whenever code imports @kerfjs/ui or a task asks for Kerf UI components.
-kerf-ui-skill-version: 1.51.0
+kerf-ui-skill-version: 1.55.0
 ---
 
 # Building with @kerfjs/ui
@@ -250,7 +250,8 @@ Hard rules:
 13. The Web Awesome theme makes Tooltip and Popover arrowless by default. Keep that default unless a pointer materially clarifies the anchor; opt back in with `--wa-tooltip-arrow-size`, `--kui-wa-popover-arrow-size`, or a popover's public `--arrow-size`, and use `without-arrow` when local no-arrow intent should survive theme changes. Its non-field chrome uses `--kui-wa-control-inset` (8px controls/items), `--kui-wa-surface-margin` / `--kui-wa-surface-inset` (8px around/inside Accordion, Card, Details, Callout, and Include), and `--kui-wa-container-inset` (16px Tab Panel content and framed disclosure regions). Plain Details use the 8px surface inset on the trigger and keep the body flush; plain Accordion items use it on both trigger and body. Outlined and sunken Details use the 16px container inset on the trigger and 8px on the body; framed Accordion items use 16px on both. Dialog maps its body to the 8px surface tier and its footer to the 16px container tier independently of `--spacing`. Override those tiers instead of restyling individual parts. Filled badges use each variant's quiet fill with normal text so their compact copy stays WCAG-AA readable; override the pair with `--kui-wa-badge-filled-background` / `--kui-wa-badge-filled-foreground`, not host selectors. When a dialog provides another dismissal affordance, put `hide-actions` on the `wa-dialog` host to hide its directly exported `header-actions` part; never chain `::part()` selectors through internal parts. Checkbox and Radio Group option regions, the Color Picker trigger, and Slider's complete interactive region receive the shared 8px logical inline outer inset because those controls have no bordered field shell. Known Date field captions and bordered text-like field hints align with values at the 9px border-plus-padding inset. OTP Input's label uses the same uppercase xs/650 treatment as other field labels, and both its label and hint use that 9px inset.
 14. Treat the complete Web Awesome catalog as support coverage, not a recommendation list. Its UX sidebar marks superseded and exceptional entries `Discouraged`. Consider Popup when it replaces custom anchored positioning. Prefer Kerf `Select` over direct Dropdown/Dropdown Item/Select/Option composition, `SegmentedControl` over Button Group, `TabBar` or `SegmentedControl` over Web Awesome Tabs, `LucideIcon` over Web Awesome Icon, and `ResizableRegion` over Split Panel. Use Tree/Tree Item, Animated Image, and Comparison only for a specific required behavior; avoid Zoomable Frame. Never render a `Discouraged` element directly in application, demo, or recipe markup; reach it only through the Kerf component that wraps it (`PopupMenu` renders `wa-dropdown`, `Select` renders `wa-select` / `wa-option`), and treat a Kerf component gap as a request to file, not a reason to drop to the raw element.
 15. Build sidebars, main areas, inspectors, and dialogs by rendering `Pane` (`@kerfjs/ui/pane`): an unpadded `.kui-pane` root, an optional `header`, one scrolling `.kui-pane__content`, and an optional `footer`; pick landmarks with `element` / `contentElement`. Never write a component's anatomy classes (`kui-pane`, `kui-toolbar`, `kui-list-item`, …) onto your own element to recreate it — render the component (`KUI-L103`). Only the catalog's `placeableClasses` (the `.kui-content` / `.kui-scroll-owner` / `.kui-control-cluster` / `.kui-inline-metadata` layout utilities, `.kui-app-root`, and `.kui-content-item` geometry on a non-div carrier) belong on elements you write. Use `Row` instead of a hand-written flex-row wrapper, `List` instead of a hand-written flex-column wrapper, and `Grid` instead of repeated equal-track CSS when children need a fixed positive count of evenly distributed columns. `Row` defaults to left/full with an `xs` gap and no wrapping; Grid defaults to an `xs` gap and keeps each track at `minmax(0, 1fr)`; List retains full/top and zero-gap defaults. The app owns Grid's responsive column-count changes. When a Row, List, or Grid is the layout root of a definite-height parent (an app root or a fixed-height frame), pass `fill` so it takes that full height, and put route/test/recipe `data-*` markers in its `rootAttributes`; never wrap a layout in a frame `Pane` just for height or a root attribute, because its content slot becomes a scroll owner that never scrolls. Inside a flex layout use `flex`, not `fill`. Use `List` when rows or sections also need flex growth, one vertical scroll owner, or physical-edge dividers. `dividerSides`, `textInsets`, and `controlInsets` use canonical physical `t`/`r`/`b`/`l` order; text geometry wins where text and control selections overlap. `ListInsetText` and `ListInsetControl` inset all four sides by default and accept the same `sides` grammar for selective edges. A dialog body is generally a `List`: set `DialogSurface bodyInset="none"` when its list children own geometry, and wrap bare dialog prose in `ListInsetText` so it aligns with bordered siblings without a second inset. Add `.kui-content` for 24px major vertical separation and render each ordinary surface-like child as `ContentItem` (`@kerfjs/ui/content-item`) for a child-owned 8px inline margin, 1px border, 8px padding, and 12px radius. Choose `frame="framed"` (neutral border in the always-reserved 1px, same geometry) only for a real distinction and `shape="pill"` for 22px; do not hand-write `<div class="kui-content-item">` or its modifier classes. There is no filled variant: a lowered filled surface is `SunkenPanel`. Do not pad pane shells, duplicate item geometry in wrappers, or create nested scroll owners. Align text to text and icons to icons across a pane — a title, a row label, and bare prose share the same text column (`ListInsetText` puts bare text on it); a border is decoration and never the alignment anchor, so a bordered surface extends to the pane gutter instead of being indented to line its border up with a heading's text.
-    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`.
+    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 in default tone; a normal-color subsection title is `Text` with an `h2`–`h6` variant (or `ListHeader` for a list or menu section), never a recolored `ToolbarText`. Use `controlMargins` with canonical physical Sides for an exterior 8px control gutter without a Row wrapper; avoid stacking parent insets, and remember spans retain native inline margin behavior.
+
 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 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.
@@ -291,6 +292,8 @@ When importing the opt-in `@kerfjs/ui/document.css` baseline, native `th`, `td`,
 
 For a read-only field preview that replaces a Web Awesome input, use `FieldLabel` from `@kerfjs/ui/text` above the preview. Put it in `ListInsetControl sides="trl"` beside a `ContentItem` value; give it an id and use `aria-labelledby` on the preview group. The app owns preview/edit state and hint copy.
 
+`ToolbarControlGroup.tileTone` selects `neutral`, `brand`, `success`, `warning`, or `danger` quiet fill, matching quiet border, and on-quiet foreground for a non-interactive icon tile. Compose a contained `single` group whose only child is a direct decorative LucideIcon (`aria-hidden="true"`). Omission preserves the normal group palette. The prop does not recolor interactive, mixed, multi-control, or borderless groups; keep real actions in controls with their existing focus/hover/pressed treatments.
+
 Common mistakes:
 
 | Mistake                                                                                                                           | Fix                                                                                                                                                                                                                                                                                           |
@@ -351,3 +354,24 @@ remain with Web Awesome. Do not add popup delays, position repairs, or animation
 completion handlers in consumers. Raw `wa-select` elements remain native.
 
 Neutral lowered surfaces and decorative neutral fills/borders are translucent theme colors; compose nested public components directly. Default/raised canvases, foregrounds, focus indicators, and loud contrast-bearing fills remain opaque. Do not assign depth-specific component tokens in demo wrappers.
+
+Use `ToolbarText tone="dark"` on a loud or photo-backed toolbar surface to
+match dark control groups. It applies to read-only headings and actionable
+titles at every size; default tone retains existing identity and heading colors.
+
+Navigation transition continuity: `wireNavStack` slides the incoming view over the preserved previous view on push and the outgoing view off on pop, cross-fades both live chrome surfaces with inert snapshots, and settles/cancels an interrupted transition before starting the next. Reduced motion and duration zero settle immediately.
+
+Expanded search groups accept `expandedOverflow="visible"` to anchor app-owned suggestion/date/help surfaces below their relative root; collapsed/default groups retain existing clipping. Apps own surface placement/dismissal and use `data-token-search-keep-open` or `collapsible.keepOpenOn` for focus.
+
+`ToolbarText` and `ToolbarControlGroup` accept typed `hideBelow`/`showBelow`
+lengths (for example `px(416)`). Wire `wireToolbarVisibility(root)` from
+`@kerfjs/ui/wire-toolbar-visibility` and dispose on unmount. Thresholds use the
+nearest Toolbar content-box width: hideBelow hides strictly below, showBelow
+shows strictly below, with complementary behavior at equality. Percentages use
+that content width; em and custom properties use the item's own context. Invalid,
+negative, unresolved, or contradictory values leave the item visible under this
+width policy. Keep primary actions visible and offer a complementary overflow
+group. See `docs/component-contract.md` "Toolbar width visibility" for lifecycle
+details.
+
+Select menus use native viewport shifting with 10px gutters: default menus grow to content (up to 20rem), while `fitMenu` matches trigger width and long labels wrap. Keep popup sizing and position repairs out of consumer CSS.

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.76` 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.77` 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/dist/catalog.js

@@ -1,14 +1,14 @@
-import { Workbench } from './chunk-7QWIJEK5.js';
+import { Workbench } from './chunk-6VQPLV3O.js';
 
 
 import { PopupMenu } from './chunk-NJZMR7HM.js';
 
 import { Row } from './chunk-5D3WDMIK.js';
-import { ListHeader } from './chunk-IVLTEBBT.js';
-import { Text } from './chunk-ZVYA6TLR.js';
+import { ListHeader } from './chunk-M6BWQMQY.js';
+import { Text } from './chunk-4Y4L5YEI.js';
 import { ListInsetText } from './chunk-NMWDHZVM.js';
 import { ListItem } from './chunk-HFQDSSED.js';
-import { ToolbarText } from './chunk-5PAVAR4B.js';
+import { ToolbarText } from './chunk-VHXHLZ6R.js';
 
 
 
@@ -18,7 +18,7 @@ import { ToolbarText } from './chunk-5PAVAR4B.js';
 
 import { List } from './chunk-NVRJ7C3W.js';
 
-import { ToolbarControlGroup, ToolbarActionLink } from './chunk-GO2CZX4M.js';
+import { ToolbarControlGroup, ToolbarActionLink } from './chunk-RRCD3A6G.js';
 import { Toolbar } from './chunk-BYHGRKC3.js';
 import { LucideIcon } from './chunk-PQQQXJGV.js';
 

package/dist/{chunk-ZVYA6TLR.js → chunk-4Y4L5YEI.js}

@@ -18,6 +18,7 @@ function Text({
   font = "default",
   border = "transparent",
   flush = false,
+  controlMargins = "",
   lineHeight = "default",
   wrap = "normal",
   maxLines,
@@ -42,6 +43,7 @@ function Text({
       "data-size": size,
       "data-font": font,
       "data-border": border,
+      "data-control-margins": controlMargins || void 0,
       "data-flush": flush ? "true" : void 0,
       "data-line-height": lineHeight === "tight" ? "tight" : void 0,
       "data-wrap": wrap === "normal" ? void 0 : wrap,
@@ -61,4 +63,4 @@ function Text({
 
 export { FieldLabel, Text };
 
-//# sourceMappingURL=chunk-ZVYA6TLR.js.map
+//# sourceMappingURL=chunk-4Y4L5YEI.js.map

package/dist/chunk-4Y4L5YEI.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/components/forms/field-label/field-label.tsx","../src/components/typography/text/text.tsx"],"names":["jsx"],"mappings":";;;AAYO,SAAS,UAAA,CAAW;AAAA,EACzB,QAAA;AAAA,EACA,OAAO,UAAA,GAAa,EAAA;AAAA,EACpB,SAAA,GAAY,EAAA;AAAA,EACZ,GAAG;AACL,CAAA,EAAoB;AAClB,EAAA,MAAM,OAAA,GAAU,CAAC,uBAAA,EAAyB,UAAA,EAAY,SAAS,EAC5D,MAAA,CAAO,OAAO,CAAA,CACd,IAAA,CAAK,GAAG,CAAA;AACX,EAAA,uBACE,GAAA,CAAC,SAAK,GAAG,UAAA,EAAY,OAAO,OAAA,EAAS,gBAAA,EAAe,eACjD,QAAA,EACH,CAAA;AAEJ;AC4CO,SAAS,IAAA,CAAK;AAAA,EACnB,SAAS,OAAA,GAAU,GAAA;AAAA,EACnB,IAAA,GAAO,SAAA;AAAA,EACP,KAAA;AAAA,EACA,IAAA,GAAO,SAAA;AAAA,EACP,IAAA,GAAO,SAAA;AAAA,EACP,MAAA,GAAS,aAAA;AAAA,EACT,KAAA,GAAQ,KAAA;AAAA,EACR,cAAA,GAAiB,EAAA;AAAA,EACjB,UAAA,GAAa,SAAA;AAAA,EACb,IAAA,GAAO,QAAA;AAAA,EACP,QAAA;AAAA,EACA,QAAA;AAAA,EACA,OAAO,UAAA,GAAa,EAAA;AAAA,EACpB,SAAA,GAAY,EAAA;AAAA,EACZ,KAAA;AAAA,EACA,GAAG;AACL,CAAA,EAAc;AACZ,EAAA,IACE,QAAA,KAAa,MAAA,KACZ,CAAC,MAAA,CAAO,aAAA,CAAc,QAAQ,CAAA,IAC7B,QAAA,GAAW,CAAA,IACX,IAAA,KAAS,QAAA,IACT,IAAA,KAAS,UAAA,CAAA;AAEX,IAAA,MAAM,IAAI,UAAA;AAAA,MACR;AAAA,KACF;AACF,EAAA,MAAM,OAAA,GAAU,CAAC,UAAA,EAAY,UAAA,EAAY,SAAS,EAAE,MAAA,CAAO,OAAO,CAAA,CAAE,IAAA,CAAK,GAAG,CAAA;AAC5E,EAAA,uBACEA,GAAAA;AAAA,IAAC,OAAA;AAAA,IAAA;AAAA,MACE,GAAG,UAAA;AAAA,MACJ,KAAA,EAAO,OAAA;AAAA,MACP,gBAAA,EAAe,MAAA;AAAA,MACf,WAAA,EAAW,IAAA;AAAA,MACX,WAAA,EAAW,IAAA;AAAA,MACX,WAAA,EAAW,IAAA;AAAA,MACX,aAAA,EAAa,MAAA;AAAA,MACb,wBAAsB,cAAA,IAAkB,MAAA;AAAA,MACxC,YAAA,EAAY,QAAQ,MAAA,GAAS,MAAA;AAAA,MAC7B,kBAAA,EAAkB,UAAA,KAAe,OAAA,GAAU,OAAA,GAAU,MAAA;AAAA,MACrD,WAAA,EAAW,IAAA,KAAS,QAAA,GAAW,MAAA,GAAY,IAAA;AAAA,MAC3C,gBAAA,EAAgB,QAAA,KAAa,MAAA,GAAY,MAAA,GAAY,OAAO,QAAQ,CAAA;AAAA,MACpE,KAAA,EACE,KAAA,KAAU,MAAA,GACN,KAAA,GACA,GAAG,KAAA,KAAU,MAAA,IAAa,KAAA,KAAU,IAAA,GAAO,EAAA,GAAK,CAAA,EAAG,KAAK,CAAA,CAAA,CAAG,SAAS,KAAK,CAAA,CAAA;AAAA,MAG9E,QAAA,EAAA,QAAA,KAAa,MAAA,GACZ,QAAA,mBAEAA,GAAAA;AAAA,QAAC,MAAA;AAAA,QAAA;AAAA,UACC,KAAA,EAAM,iBAAA;AAAA,UACN,KAAA,EAAO,yBAAyB,QAAQ,CAAA,CAAA;AAAA,UAEvC;AAAA;AAAA;AACH;AAAA,GAEJ;AAEJ","file":"chunk-4Y4L5YEI.js","sourcesContent":["import type { KerfBaseAttrs } from 'kerfjs/jsx-runtime';\n\nexport type FieldLabelProps = Omit<\n  KerfBaseAttrs,\n  'children' | 'class' | 'className'\n> & {\n  children: string;\n  class?: string;\n  className?: string;\n};\n\n/** Visible field heading for a read-only preview; use its id with aria-labelledby on the preview group. */\nexport function FieldLabel({\n  children,\n  class: classValue = '',\n  className = '',\n  ...attributes\n}: FieldLabelProps) {\n  const classes = ['kui-text__field-label', classValue, className]\n    .filter(Boolean)\n    .join(' ');\n  return (\n    <div {...attributes} class={classes} data-component=\"field-label\">\n      {children}\n    </div>\n  );\n}\n","import type { KerfBaseAttrs } from 'kerfjs/jsx-runtime';\n\nimport type { KerfUiContent } from '../../../shared/content/semantic-content.js';\nimport type { Sides } from '../../../shared/layout/sides.js';\nimport type { CssForegroundColor } from '../../../shared/styles/css-values.js';\n\nexport {\n  FieldLabel,\n  type FieldLabelProps,\n} from '../../forms/field-label/field-label.js';\n\nexport type TextVariant =\n  'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p' | 'span';\nexport type TextTone = 'default' | 'quiet' | 'danger';\nexport type TextSize = 'compact' | 'default' | 'large' | 'xlarge';\nexport type TextFont = 'default' | 'monospace';\nexport type TextBorder = 'transparent' | 'none';\nexport type TextLineHeight = 'default' | 'tight';\nexport type TextWrap = 'normal' | 'anywhere' | 'nowrap' | 'truncate';\n\nexport type TextContent =\n  KerfUiContent | string | number | readonly TextContent[];\n\ntype TextCommonProps = Omit<\n  KerfBaseAttrs,\n  'children' | 'class' | 'className'\n> & {\n  /** Native heading, paragraph, or inline span element to render. Defaults to `p`. */\n  variant?: TextVariant;\n  /** Semantic foreground treatment. Defaults to the inherited foreground. */\n  tone?: TextTone;\n  /** Foreground color; overrides tone when supplied, or inherits when omitted. */\n  color?: CssForegroundColor;\n  /** Text sizing independent of the native semantic element. */\n  size?: TextSize;\n  /** Font family independent of the native semantic element. */\n  font?: TextFont;\n  /** Transparent alignment border or no border when embedded in owner chrome. */\n  border?: TextBorder;\n  /** Add the shared control gutter outside selected physical edges. */\n  controlMargins?: Sides;\n  /** Remove the block variant's item padding and border in compact content. */\n  flush?: boolean;\n  /** Use compact leading for short dialog or metadata copy. */\n  lineHeight?: TextLineHeight;\n  children: TextContent;\n  class?: string;\n  className?: string;\n};\n\nexport type TextProps = TextCommonProps &\n  (\n    | {\n        /** Wrap normally or break long unbroken strings. Defaults to normal. */\n        wrap?: 'normal' | 'anywhere';\n        /** Cap wrapped text to this positive number of lines. */\n        maxLines?: number;\n      }\n    | {\n        /** Keep one line, with or without an ellipsis. */\n        wrap: 'nowrap' | 'truncate';\n        maxLines?: never;\n      }\n  );\n\n/**\n * Semantic heading, paragraph, or inline text. Block variants use the standard\n * content-item padding; `span` adds no box geometry.\n * All ordinary native heading/paragraph attributes pass through to the element.\n */\nexport function Text({\n  variant: Variant = 'p',\n  tone = 'default',\n  color,\n  size = 'default',\n  font = 'default',\n  border = 'transparent',\n  flush = false,\n  controlMargins = '',\n  lineHeight = 'default',\n  wrap = 'normal',\n  maxLines,\n  children,\n  class: classValue = '',\n  className = '',\n  style,\n  ...attributes\n}: TextProps) {\n  if (\n    maxLines !== undefined &&\n    (!Number.isSafeInteger(maxLines) ||\n      maxLines < 1 ||\n      wrap === 'nowrap' ||\n      wrap === 'truncate')\n  )\n    throw new RangeError(\n      'Text maxLines requires a positive integer and wrapping',\n    );\n  const classes = ['kui-text', classValue, className].filter(Boolean).join(' ');\n  return (\n    <Variant\n      {...attributes}\n      class={classes}\n      data-component=\"text\"\n      data-tone={tone}\n      data-size={size}\n      data-font={font}\n      data-border={border}\n      data-control-margins={controlMargins || undefined}\n      data-flush={flush ? 'true' : undefined}\n      data-line-height={lineHeight === 'tight' ? 'tight' : undefined}\n      data-wrap={wrap === 'normal' ? undefined : wrap}\n      data-max-lines={maxLines === undefined ? undefined : String(maxLines)}\n      style={\n        color === undefined\n          ? style\n          : `${style === undefined || style === null ? '' : `${style};`}color:${color}`\n      }\n    >\n      {maxLines === undefined ? (\n        children\n      ) : (\n        <span\n          class=\"kui-text__clamp\"\n          style={`--_kui-text-max-lines:${maxLines}`}\n        >\n          {children}\n        </span>\n      )}\n    </Variant>\n  );\n}\n\nexport type { Sides } from '../../../shared/layout/sides.js';\n"]}

package/dist/{chunk-7QWIJEK5.js → chunk-6VQPLV3O.js}

@@ -1,8 +1,8 @@
 import { WORKBENCH_MAIN_MIN_SIZE, WORKBENCH_MAIN_MIN_HEIGHT, workbenchRegionId, WORKBENCH_RESIZE_DEFAULTS } from './chunk-S4ZGTDSG.js';
-import { NavStack } from './chunk-SJY7KC45.js';
+import { NavStack } from './chunk-Z4EPMX25.js';
 import { clampRegionSize, ResizeGrip } from './chunk-Y6KT7ZTR.js';
 import { FloatingToolbar } from './chunk-S3ECMF23.js';
-import { panelToggleGroup, composedPanelBody, relocatedPanelGroups } from './chunk-HGSTMZZ6.js';
+import { panelToggleGroup, composedPanelBody, relocatedPanelGroups } from './chunk-Z6PE5T7N.js';
 import { Pane } from './chunk-AOAW55JN.js';
 import { List } from './chunk-NVRJ7C3W.js';
 import { Toolbar } from './chunk-BYHGRKC3.js';
@@ -489,4 +489,4 @@ function Workbench({
 
 export { Workbench };
 
-//# sourceMappingURL=chunk-7QWIJEK5.js.map
+//# sourceMappingURL=chunk-6VQPLV3O.js.map