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

package/README.md

@@ -243,6 +243,7 @@ interchangeable. `ListItem` and `ListActionRow` deliberately expose no raw
 | `TabBar`                                                            | `@kerfjs/ui/tab-bar`                    | `@kerfjs/ui/tab-bar.css`               |
 | `wireTabBars`, `reorderTabs`                                        | `@kerfjs/ui/wire-tab-bars`              | —                                      |
 | `wireScrollDividers`                                                | `@kerfjs/ui/wire-scroll-dividers`       | —                                      |
+| `wireToolbarVisibility`                                             | `@kerfjs/ui/wire-toolbar-visibility`    | —                                      |
 | `LoadingSpinner`                                                    | `@kerfjs/ui/loading-spinner`            | `@kerfjs/ui/loading-spinner.css`       |
 | `Skeleton`                                                          | `@kerfjs/ui/skeleton`                   | `@kerfjs/ui/skeleton.css`              |
 | `SunkenPanel`                                                       | `@kerfjs/ui/sunken-panel`               | `@kerfjs/ui/sunken-panel.css`          |
@@ -794,3 +795,14 @@ explicit. `npm run build` emits standard CSS to `dist/styles`; `npm run dev`
 applies the same transform directly to source styles and hot-reloads edits.
 
 Lowered surfaces and decorative neutral fills/borders use translucent shared theme colors. Nested surfaces compound naturally; demos compose public components without per-depth overrides. See [contextual transparency](docs/webawesome-theme.md#contextual-transparency).
+
+`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.

package/ai/component-catalog.json

@@ -821,6 +821,11 @@
               "on": "kui-nav-stack__chrome-copy",
               "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",
+              "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",
@@ -978,6 +983,11 @@
               "on": "kui-nav-stack__chrome-copy",
               "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",
+              "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",
@@ -1518,14 +1528,17 @@
       "uses": [
         "toolbar-text",
         "toolbar-control-group",
-        "wa-button"
+        "wa-button",
+        "popup-menu"
       ],
       "purpose": "Leading, centered, and trailing toolbar composition.",
       "publicExports": [
-        "Toolbar"
+        "Toolbar",
+        "wireToolbarVisibility"
       ],
       "useWhen": [
-        "Compose application chrome or a page, panel, or dialog heading with leading, center, and trailing regions."
+        "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."
       ],
       "avoidWhen": [
         "Do not use it as a generic wrapper when no toolbar or heading relationship exists."
@@ -1548,7 +1561,8 @@
         "trailing priority for an expanded trailing control at compact or narrow widths",
         "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)"
+        "app bar or bottom bar claiming its screen edges (safeAreaEdges)",
+        "typed hideBelow/showBelow thresholds at the nearest Toolbar content width"
       ],
       "accessibility": [
         "Supply a label when the toolbar needs an accessible name."
@@ -1586,6 +1600,23 @@
               "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."
             }
           ]
+        },
+        {
+          "export": "wireToolbarVisibility",
+          "import": "@kerfjs/ui/wire-toolbar-visibility",
+          "required": false,
+          "stateAttributes": [
+            {
+              "name": "data-toolbar-width-hidden",
+              "on": "ToolbarText, ToolbarControlGroup and its paired busy status",
+              "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",
+              "meaning": "Internal out-of-flow CSS length resolver; created and removed by wireToolbarVisibility."
+            }
+          ]
         }
       ],
       "publicClasses": [
@@ -1612,6 +1643,9 @@
         "catalogRoute": "?component=toolbar",
         "documentation": "docs/component-selection.md",
         "recipe": "docs/component-selection.md#ambiguous-choices"
+      },
+      "publicExportImports": {
+        "wireToolbarVisibility": "@kerfjs/ui/wire-toolbar-visibility"
       }
     },
     {
@@ -1635,7 +1669,10 @@
         "Use ToolbarActionLink for navigation or external resources that must retain native anchor semantics inside a group.",
         "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."
+        "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."
       ],
       "avoidWhen": [
         "Do not use merely to align unrelated buttons or to imitate an exclusive choice.",
@@ -1674,7 +1711,10 @@
         "always visible or compact-only responsive visibility",
         "relocate on panel collapse",
         "avatar scrim",
-        "contained avatar background on a single group or selected multi-button highlight"
+        "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"
       ],
       "accessibility": [
         "Name the group when its relationship is not evident from context.",
@@ -1692,7 +1732,25 @@
           "browser-condition-css"
         ]
       },
-      "wiring": [],
+      "wiring": [
+        {
+          "export": "wireToolbarVisibility",
+          "import": "@kerfjs/ui/wire-toolbar-visibility",
+          "required": false,
+          "stateAttributes": [
+            {
+              "name": "data-toolbar-width-hidden",
+              "on": "ToolbarText, ToolbarControlGroup and its paired busy status",
+              "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",
+              "meaning": "Internal out-of-flow CSS length resolver; created and removed by wireToolbarVisibility."
+            }
+          ]
+        }
+      ],
       "publicClasses": [
         "kui-toolbar-action-link",
         "kui-toolbar-control-group"
@@ -1722,13 +1780,74 @@
         "--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"
       ],
       "links": {
         "catalogRoute": "?component=toolbar-control-group",
         "documentation": "docs/component-selection.md",
         "recipe": "docs/component-selection.md#problem-to-component-matrix"
-      }
+      },
+      "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)}"
+          ]
+        }
+      ]
     },
     {
       "id": "surface-scaffold",
@@ -1913,11 +2032,13 @@
       ],
       "useWhen": [
         "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 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."
       ],
       "avoidWhen": [
         "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": [
         {
@@ -1943,7 +2064,9 @@
         "default",
         "small",
         "xsmall",
-        "placeholder (loading)"
+        "placeholder (loading)",
+        "dark (loud-surface foreground)",
+        "typed hideBelow/showBelow thresholds at the nearest Toolbar content width"
       ],
       "accessibility": [
         "Plain text is not a heading; pass headingLevel to expose role=heading + aria-level for a page/section title.",
@@ -1961,7 +2084,25 @@
           "browser-condition-css"
         ]
       },
-      "wiring": [],
+      "wiring": [
+        {
+          "export": "wireToolbarVisibility",
+          "import": "@kerfjs/ui/wire-toolbar-visibility",
+          "required": false,
+          "stateAttributes": [
+            {
+              "name": "data-toolbar-width-hidden",
+              "on": "ToolbarText, ToolbarControlGroup and its paired busy status",
+              "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",
+              "meaning": "Internal out-of-flow CSS length resolver; created and removed by wireToolbarVisibility."
+            }
+          ]
+        }
+      ],
       "publicClasses": [
         "kui-toolbar-text"
       ],
@@ -1973,13 +2114,62 @@
         "--kui-font-l",
         "--kui-font-m",
         "--kui-font-s",
-        "--kui-font-xs"
+        "--kui-font-xs",
+        "--kui-color-neutral-on-loud"
       ],
       "links": {
         "catalogRoute": "?component=toolbar-text",
         "documentation": "docs/component-selection.md",
         "recipe": "docs/component-selection.md#problem-to-component-matrix"
-      }
+      },
+      "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)}"
+          ]
+        }
+      ]
     },
     {
       "id": "text",
@@ -2026,7 +2216,8 @@
         "default, quiet, or danger tone",
         "compact, default, large, or xlarge size",
         "default or monospace font",
-        "flush item geometry and tight line height"
+        "flush item geometry and tight line height",
+        "controlMargins selects exterior 8px gutters with canonical physical Sides"
       ],
       "accessibility": [
         "Text renders a native paragraph by default; choose an h1 through h6 variant by document outline rather than appearance, or span for inline secondary text.",
@@ -2035,11 +2226,12 @@
         "FieldLabel is plain text, not a native label; give it an id and associate the preview group with aria-labelledby."
       ],
       "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."
         ]
       },
       "delivery": {
@@ -4231,7 +4423,8 @@
       ],
       "useWhen": [
         "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."
+        "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."
       ],
       "avoidWhen": [
         "Do not use for commands or a small choice set that should stay visible."

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."
           ]
         }
       },

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