@kerfjs/ui 5.0.0-beta.35 → 5.0.0-beta.37

package/README.md

@@ -126,7 +126,7 @@ Do not concatenate a count into `label` or pass a numeric `badge`; the mutually
 exclusive legacy `badge` slot remains available for non-count `SafeHtml` such
 as a `New` marker.
 
-`Row.gap` and `List.gap` accept a direct spacing name such as
+`Row.gap`, `List.gap`, and `Spacer` dimensions accept a direct spacing name such as
 `gap="xs"` or `gap="m"`, or a branded `CssLength`. Import `space`, `rem`, `em`,
 `px`, `pct`, `lengthVar`, `plus`, and `calc` from the CSS-free
 `@kerfjs/ui/css-values` subpath when a named step is not enough. `plus` returns
@@ -138,7 +138,12 @@ Use `Row` for horizontal flex composition and `List` for vertical composition.
 Both accept `hAlign` (`left`, `center`, `right`, `full`) and `vAlign` (`top`,
 `middle`, `bottom`, `full`), plus their documented short/CSS aliases. `Row`
 defaults to left/full alignment, the `xs` gap, and `wrap={false}`; List keeps
-its existing full/top alignment and zero-gap defaults.
+its existing full/top alignment and zero-gap defaults. Set `textInsets` or
+`controlInsets` with canonical physical sides in `t`/`r`/`b`/`l` order (for
+example, `textInsets="tbl"` or `controlInsets="r"`). Text geometry takes
+precedence where both select the same side. `ListInsetText` and
+`ListInsetControl` inset all four sides by default and accept the same `sides`
+grammar for selective insets.
 
 The same property-specific boundary applies beyond spacing: use `flex()` (or a
 finite keyword) for `Row.flex` and `List.flex`; length builders and intrinsic-size keywords for
@@ -160,6 +165,7 @@ interchangeable. `ListItem` and `ListActionRow` deliberately expose no raw
 | `ToolbarText`                                                       | `@kerfjs/ui/toolbar-text`               | `@kerfjs/ui/toolbar-text.css`          |
 | `List`                                                              | `@kerfjs/ui/list`                       | `@kerfjs/ui/list.css`                  |
 | `Row`                                                               | `@kerfjs/ui/row`                        | `@kerfjs/ui/row.css`                   |
+| `Spacer`                                                            | `@kerfjs/ui/spacer`                     | `@kerfjs/ui/spacer.css`                |
 | Typed CSS dimension builders                                        | `@kerfjs/ui/css-values`                 | —                                      |
 | `ListActionRow`                                                     | `@kerfjs/ui/list-action-row`            | `@kerfjs/ui/list-action-row.css`       |
 | `ListItem`                                                          | `@kerfjs/ui/list-item`                  | `@kerfjs/ui/list-item.css`             |
@@ -221,8 +227,9 @@ transform is applied. Direction changes take the shortest rotation path; a
 real controlled content and preserve the button's stable label; ordinary
 navigation must not display a disclosure arrow. A custom `actionIcon` remains
 an escape hatch and replaces the default arrow entirely. The header fills its
-available inline width, keeping a separate action at the logical end in a 44px
-target. Its visible action glyph defaults to 18px through
+available inline width by default; set `inline` to shrink-wrap it beside other
+content and remove its root margin, border, and padding. It keeps a separate
+action at the logical end. Its visible action glyph defaults to 18px through
 `--kui-list-header-action-icon-size`.
 
 ## Machine-readable catalog

package/ai/component-catalog-v2.json

@@ -1436,9 +1436,9 @@
         "geometry": {
           "margin": "none",
           "border": "none",
-          "padding": "none",
+          "padding": "conditional",
           "notes": [
-            "Row adds no margin, border, or padding; it owns only flex participation, alignment, wrapping, and the gap between children."
+            "Row adds no margin or border. textInsets adds the full 17px content inset and controlInsets adds 8px on selected physical sides; text wins when both select a side."
           ]
         }
       },
@@ -1486,6 +1486,92 @@
         "composition": "docs/layout.md#row-and-list-alignment"
       }
     },
+    {
+      "key": "@kerfjs/ui:spacer",
+      "package": "@kerfjs/ui",
+      "id": "spacer",
+      "name": "Spacer",
+      "kind": "component",
+      "source": "kerf",
+      "parents": { "mode": "any", "entries": [] },
+      "contexts": ["application-ui"],
+      "zones": [],
+      "children": { "mode": "any", "concepts": [], "requiredConcepts": [] },
+      "state": [
+        {
+          "id": "whether the empty space carries structural meaning",
+          "owner": "application",
+          "required": false
+        },
+        {
+          "id": "the named or typed dimensions",
+          "owner": "application",
+          "required": false
+        },
+        {
+          "id": "whether the spacer fills the flex main axis",
+          "owner": "application",
+          "required": false
+        }
+      ],
+      "wiring": { "required": false, "helpers": [], "obligations": [] },
+      "responsive": { "owner": "not-applicable", "behaviors": [] },
+      "layout": {
+        "roles": ["structure"],
+        "geometry": {
+          "margin": "none",
+          "border": "none",
+          "padding": "none",
+          "notes": [
+            "A fixed Spacer does not shrink. flex changes its flex shorthand from 0 0 auto to 1 1 auto; width and height remain physical dimensions."
+          ]
+        }
+      },
+      "accessibility": {
+        "obligations": [
+          "Spacer is always decorative and hidden from the accessibility tree.",
+          "Spacer must not contain content or become an interaction target."
+        ]
+      },
+      "cssValueProps": [
+        {
+          "path": "width",
+          "grammar": "length",
+          "helpers": ["px", "rem", "em", "pct", "space", "lengthVar", "calc"],
+          "nonStandaloneHelpers": ["plus"],
+          "shorthands": ["none", "2xs", "xs", "s", "m", "l", "xl"],
+          "canonicalShorthands": ["none", "2xs", "xs", "m", "l"],
+          "exceptionalShorthands": ["s", "xl"],
+          "rawPolicy": "forbid",
+          "examples": [
+            "width=\"m\"",
+            "width={space(\"m\")}",
+            "width={calc(plus(rem(0.25), pct(10)))}"
+          ]
+        },
+        {
+          "path": "height",
+          "grammar": "length",
+          "helpers": ["px", "rem", "em", "pct", "space", "lengthVar", "calc"],
+          "nonStandaloneHelpers": ["plus"],
+          "shorthands": ["none", "2xs", "xs", "s", "m", "l", "xl"],
+          "canonicalShorthands": ["none", "2xs", "xs", "m", "l"],
+          "exceptionalShorthands": ["s", "xl"],
+          "rawPolicy": "forbid",
+          "examples": ["height=\"xs\"", "height={rem(1)}"]
+        }
+      ],
+      "boundaries": {
+        "rootClass": "kui-spacer",
+        "publicClasses": ["kui-spacer"],
+        "publicTokens": []
+      },
+      "diagnostics": [],
+      "provenance": {
+        "selection": "ai/component-catalog.json",
+        "composition": "generated-permissive-default"
+      }
+    },
     {
       "key": "@kerfjs/ui:list",
       "package": "@kerfjs/ui",
@@ -1521,9 +1607,9 @@
         "geometry": {
           "margin": "none",
           "border": "conditional",
-          "padding": "none",
+          "padding": "conditional",
           "notes": [
-            "List adds no margin or padding; dividerSides draws only the selected physical edges without changing box geometry."
+            "List adds no margin. dividerSides draws selected physical edges without changing geometry; textInsets adds the full 17px content inset and controlInsets adds 8px on selected sides, with text winning on overlap."
           ]
         }
       },

package/ai/component-catalog.json

@@ -1642,9 +1642,9 @@
     "category": "Structure",
       "kind": "component",
       "source": "kerf",
-      "description": "A horizontal flex row with physical-axis alignment, a typed xs gap by default, flex participation, and opt-in wrapping.",
+      "description": "A horizontal flex row with physical-axis alignment, side-selectable text/control insets, a typed xs gap by default, flex participation, and opt-in wrapping.",
       "uses": [],
-      "purpose": "Arrange related content horizontally with consistent spacing and explicit left/center/right/full plus top/middle/bottom/full alignment instead of application-owned flex wrappers.",
+      "purpose": "Arrange related content horizontally with consistent spacing, optional physical-side text/control insets, and explicit left/center/right/full plus top/middle/bottom/full alignment instead of application-owned flex wrappers.",
     "publicExports": ["Row"],
       "cssValueProps": [
         {
@@ -1674,6 +1674,7 @@
         "Choose physical horizontal distribution and vertical alignment without writing one-off flex CSS.",
         "Use a finite flex keyword or the flex() builder when Row participates in a flexible parent layout.",
         "Allow a bounded group to wrap while retaining the same typed gap and alignment contract."
+        ,"Apply the standard text or control inset to selected physical sides without an application wrapper."
       ],
       "avoidWhen": [
         "Do not use Row when content belongs in a semantic list or when a named-zone component such as Toolbar owns the composition.",
@@ -1703,7 +1704,8 @@
         "named none/2xs/xs/s/m/l/xl token gap",
         "typed CssLength gap",
         "boolean, finite-keyword, or typed CssFlex flex",
-        "nowrap or wrapping"
+        "nowrap or wrapping",
+        "top/right/bottom/left text and control inset combinations"
       ],
       "accessibility": [
         "Row adds layout only and no grouping role; children retain responsibility for native or ARIA semantics.",
@@ -1712,9 +1714,9 @@
       "geometry": {
         "margin": "none",
         "border": "none",
-        "padding": "none",
+        "padding": "conditional",
         "notes": [
-          "Row adds no margin, border, or padding; it owns only flex participation, alignment, wrapping, and the gap between children."
+          "Row adds no margin or border. textInsets adds the full 17px content inset and controlInsets adds 8px on selected physical sides; text wins when both select a side."
         ]
       },
       "delivery": {
@@ -1731,19 +1733,111 @@
         "recipe": "docs/layout.md#row-and-list-alignment"
       }
     },
+    {
+      "id": "spacer",
+      "name": "Spacer",
+      "category": "Structure",
+      "kind": "component",
+      "source": "kerf",
+      "description": "A decorative, non-shrinking fixed gap or flexible main-axis spacer with typed physical width and height.",
+      "uses": [],
+      "purpose": "Express an intentional empty dimension or consume remaining flex space without application-owned spacer markup or raw CSS lengths.",
+      "publicExports": ["Spacer"],
+      "cssValueProps": [
+        {
+          "path": "width",
+          "grammar": "length",
+          "helpers": ["px", "rem", "em", "pct", "space", "lengthVar", "calc"],
+          "nonStandaloneHelpers": ["plus"],
+          "shorthands": ["none", "2xs", "xs", "s", "m", "l", "xl"],
+          "canonicalShorthands": ["none", "2xs", "xs", "m", "l"],
+          "exceptionalShorthands": ["s", "xl"],
+          "rawPolicy": "forbid",
+          "examples": ["width=\"m\"", "width={space(\"m\")}", "width={calc(plus(rem(0.25), pct(10)))}"]
+        },
+        {
+          "path": "height",
+          "grammar": "length",
+          "helpers": ["px", "rem", "em", "pct", "space", "lengthVar", "calc"],
+          "nonStandaloneHelpers": ["plus"],
+          "shorthands": ["none", "2xs", "xs", "s", "m", "l", "xl"],
+          "canonicalShorthands": ["none", "2xs", "xs", "m", "l"],
+          "exceptionalShorthands": ["s", "xl"],
+          "rawPolicy": "forbid",
+          "examples": ["height=\"xs\"", "height={rem(1)}"]
+        }
+      ],
+      "useWhen": [
+        "Reserve a fixed empty width or height from the UI spacing scale inside a layout.",
+        "Push siblings to opposite ends of a Row or other flex container by passing flex.",
+        "Use a typed CssLength when the finite spacing scale cannot express the required dimension."
+      ],
+      "avoidWhen": [
+        "Do not use Spacer for ordinary rhythm between siblings; prefer Row.gap or List.gap so the parent owns repeated spacing.",
+        "Do not use Spacer to compensate for component-owned padding, margin, alignment, or responsive layout defects.",
+        "Do not pass raw CSS strings to width or height."
+      ],
+      "alternatives": [
+        {
+          "id": "row",
+          "relationship": "parent-spacing-alternative",
+          "when": "Use Row.gap when every horizontal sibling needs the same repeated separation."
+        },
+        {
+          "id": "list",
+          "relationship": "parent-spacing-alternative",
+          "when": "Use List.gap when every vertical sibling needs the same repeated separation."
+        }
+      ],
+      "appOwns": [
+        "whether the empty space carries structural meaning",
+        "the named or typed dimensions",
+        "whether the spacer fills the flex main axis"
+      ],
+      "variants": [
+        "fixed named width and/or height",
+        "fixed typed CssLength width and/or height",
+        "flexible main-axis space"
+      ],
+      "accessibility": [
+        "Spacer is always decorative and hidden from the accessibility tree.",
+        "Spacer must not contain content or become an interaction target."
+      ],
+      "geometry": {
+        "margin": "none",
+        "border": "none",
+        "padding": "none",
+        "notes": [
+          "A fixed Spacer does not shrink. flex changes its flex shorthand from 0 0 auto to 1 1 auto; width and height remain physical dimensions."
+        ]
+      },
+      "delivery": {
+        "browserImport": "@kerfjs/ui/spacer",
+        "manualCssImport": "@kerfjs/ui/spacer.css",
+        "sideEffects": ["browser-condition-css"]
+      },
+      "wiring": [],
+      "publicClasses": ["kui-spacer"],
+      "publicTokens": [],
+      "links": {
+        "catalogRoute": "?component=spacer",
+        "documentation": "docs/layout.md",
+        "recipe": "docs/layout.md#spacer"
+      }
+    },
     {
       "id": "list",
       "name": "List",
       "category": "Navigation",
       "kind": "component",
       "source": "kerf",
-      "description": "A vertical stack with physical-axis alignment, optional typed token/length gap, flex growth, vertical scrolling, and independently selectable divider edges.",
+      "description": "A vertical stack with physical-axis alignment, side-selectable text/control insets, optional typed token/length gap, flex growth, vertical scrolling, and independently selectable divider edges.",
       "uses": [
         "list-header",
         "list-action-row",
         "list-item"
       ],
-      "purpose": "Standardize vertical component layout and its scroll/divider ownership instead of repeating ad-hoc flex-column wrappers.",
+      "purpose": "Standardize vertical component layout, optional physical-side text/control insets, and scroll/divider ownership instead of repeating ad-hoc flex-column wrappers.",
       "publicExports": [
         "List",
         "px",
@@ -1783,7 +1877,8 @@
         "Arrange component rows or sections in a vertical stretch-aligned stack.",
         "Let one bounded list own vertical scrolling, flex growth, or one or more physical-edge dividers.",
         "Choose a finite gap shorthand such as xs or m, or compose a typed length with @kerfjs/ui/css-values when the spacing scale is insufficient.",
-        "Use a finite flex keyword or the flex() builder when List participates in flexible layout."
+        "Use a finite flex keyword or the flex() builder when List participates in flexible layout.",
+        "Apply the standard text or control inset to selected physical sides without an application wrapper."
         ,"Align children horizontally or distribute them vertically with the same physical alignment vocabulary as Row."
       ],
       "avoidWhen": [
@@ -1806,7 +1901,8 @@
         "scrollable",
         "left/center/right/full horizontal alignment",
         "top/middle/bottom/full vertical alignment",
-        "top/right/bottom/left divider combinations"
+        "top/right/bottom/left divider combinations",
+        "top/right/bottom/left text and control inset combinations"
       ],
       "accessibility": [
         "List adds layout only and no list role; children retain responsibility for their native or ARIA semantics.",
@@ -1815,9 +1911,9 @@
       "geometry": {
         "margin": "none",
         "border": "conditional",
-        "padding": "none",
+        "padding": "conditional",
         "notes": [
-          "List adds no margin or padding; dividerSides draws only the selected physical edges without changing box geometry."
+          "List adds no margin. dividerSides draws selected physical edges without changing geometry; textInsets adds the full 17px content inset and controlInsets adds 8px on selected sides, with text winning on overlap."
         ]
       },
       "delivery": {
@@ -1849,12 +1945,12 @@
       "category": "Navigation",
       "kind": "component",
       "source": "kerf",
-      "description": "Configurable section headings with semantic count/status indicators, density, group dividers, a logical-end action, disclosure states, and protected native-popover trigger metadata.",
+      "description": "Configurable section headings with full-width or shrink-wrapped inline presentation, semantic count/status indicators, density, group dividers, a logical-end action, disclosure states, and protected native-popover trigger metadata.",
       "uses": [
         "lucide-icon",
         "disclosure-arrow"
       ],
-      "purpose": "Fill the available section width while splitting a dormant title and mutually exclusive semantic count or legacy badge from an optional logical-end 44px action with an 18px visual, or render that title cluster as a disclosure button with a default production DisclosureArrow.",
+      "purpose": "Fill the available section width by default, or shrink-wrap without outer geometry when inline, while splitting a dormant title and mutually exclusive semantic count or legacy badge from an optional logical-end action with an 18px visual; disclosure mode renders the title cluster as a button with a default production DisclosureArrow.",
       "publicExports": [
         "ListHeader"
       ],
@@ -1887,6 +1983,7 @@
         "action",
         "toggle",
         "placeholder (loading)",
+        "inline shrink-wrapped presentation",
         "compact density",
         "neutral, accent, pop, or danger indicator tone",
         "before, after, or paired group divider"
@@ -2186,9 +2283,9 @@
       "category": "Structure",
       "kind": "component",
       "source": "kerf",
-      "description": "Insets a self-bordered control into a pane/list content region.",
+      "description": "Insets selected physical sides of a self-bordered control in a pane/list content region.",
       "uses": [],
-      "purpose": "Insets a self-bordered control into a pane/list content region.",
+      "purpose": "Apply the standard 8px outer margin to all physical sides of a self-bordered control by default, or only the sides selected with the canonical Sides contract.",
       "publicExports": [
         "ListInsetControl"
       ],
@@ -2207,6 +2304,10 @@
       "appOwns": [
         "the wrapped control and its behavior"
       ],
+      "variants": [
+        "all-side inset by default",
+        "top/right/bottom/left inset combinations"
+      ],
       "accessibility": [
         "A layout wrapper only; it adds no role or name — the wrapped control keeps its own."
       ],
@@ -2241,9 +2342,9 @@
       "category": "Structure",
       "kind": "component",
       "source": "kerf",
-      "description": "Gives bare text the content-item geometry so it lines up with bordered items.",
+      "description": "Gives selected physical sides of bare text the content-item geometry so it lines up with bordered items.",
       "uses": [],
-      "purpose": "Gives bare text the content-item geometry so it lines up with bordered items.",
+      "purpose": "Apply the full 8px margin + 1px transparent border + 8px padding to all physical sides of bare text by default, or only the sides selected with the canonical Sides contract.",
       "publicExports": [
         "ListInsetText"
       ],
@@ -2262,6 +2363,11 @@
       "appOwns": [
         "the text content"
       ],
+      "variants": [
+        "all-side inset by default",
+        "top/right/bottom/left inset combinations",
+        "deprecated horizontalOnly compatibility alias for sides=\"rl\""
+      ],
       "accessibility": [
         "A layout wrapper only; it adds no role or name."
       ],

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.35` and `kerfjs@5.0.0-beta.35`. 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.37` and `kerfjs@5.0.0-beta.37`. 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`
 
@@ -105,7 +105,7 @@ export { DisclosureArrow, type DisclosureArrowProps, type DisclosureDirection };
 
 ```ts
 import * as kerfjs from 'kerfjs';
-import { D as DividerSides } from './divider-sides-267FA7sY.js';
+import { D as DividerSides } from './divider-sides-BzB6rphT.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
 interface ToolbarProps {
@@ -257,6 +257,7 @@ type ListHeaderRootAttributes = Readonly<Record<`data-${string}`, string | undef
     'data-has-count'?: never;
     'data-density'?: never;
     'data-divider'?: never;
+    'data-inline'?: never;
     'data-indicator-tone'?: never;
     'data-toggle'?: never;
 }>;
@@ -271,6 +272,8 @@ interface ListHeaderBaseProps {
     label: string;
     density?: 'standard' | 'compact';
     divider?: 'none' | 'before' | 'after' | 'both';
+    /** Shrink-wrap the header without its default outer margin, border, or padding. */
+    inline?: boolean;
     indicatorTone?: 'neutral' | 'accent' | 'pop' | 'danger';
     /** Render as an unanimated loading skeleton: keep the label and action affordance, disable interaction. */
     placeholder?: boolean;
@@ -322,7 +325,7 @@ type ListHeaderIndicatorProps = {
     status?: SafeHtml;
 };
 type ListHeaderProps = ListHeaderBaseProps & ListHeaderIndicatorProps & ListHeaderModeProps;
-declare function ListHeader({ label, count, countLabel, badge, status, density, divider, indicatorTone, action, actionLabel, actionIcon, actionDisabled, disabledReason, expanded, toggle, placeholder, rootAttributes, triggerAttributes, }: ListHeaderProps): SafeHtml;
+declare function ListHeader({ label, count, countLabel, badge, status, density, divider, inline, indicatorTone, action, actionLabel, actionIcon, actionDisabled, disabledReason, expanded, toggle, placeholder, rootAttributes, triggerAttributes, }: ListHeaderProps): SafeHtml;
 
 export { ListHeader, type ListHeaderProps };
 ```
@@ -332,7 +335,7 @@ export { ListHeader, type ListHeaderProps };
 ```ts
 import * as kerfjs from 'kerfjs';
 import { UiSpaceName, CssLength, CssFlexKeyword, CssFlex } from './css-values.js';
-import { D as DividerSides } from './divider-sides-267FA7sY.js';
+import { D as DividerSides, S as Sides } from './divider-sides-BzB6rphT.js';
 import { H as HorizontalAlignment, V as VerticalAlignment } from './flex-alignment-CF8NLj7i.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
@@ -350,12 +353,16 @@ interface ListProps {
     scrollable?: boolean;
     /** Physical divider edges in canonical top/right/bottom/left order. */
     dividerSides?: DividerSides;
+    /** Physical sides that receive the standard 17px text inset. */
+    textInsets?: Sides;
+    /** Physical sides that receive the standard 8px control inset. Text insets win on overlap. */
+    controlInsets?: Sides;
     className?: string;
 }
 /** A stretch-aligned vertical stack with optional gap, flex, scroll, and dividers. */
-declare function List({ children, gap, flex, hAlign, vAlign, scrollable, dividerSides, className, }: ListProps): kerfjs.SafeHtml;
+declare function List({ children, gap, flex, hAlign, vAlign, scrollable, dividerSides, textInsets, controlInsets, className, }: ListProps): kerfjs.SafeHtml;
 
-export { CssFlex, CssFlexKeyword, CssLength, DividerSides, HorizontalAlignment, List, type ListProps, UiSpaceName, VerticalAlignment };
+export { CssFlex, CssFlexKeyword, CssLength, DividerSides, HorizontalAlignment, List, type ListProps, Sides, UiSpaceName, VerticalAlignment };
 ```
 
 ## `@kerfjs/ui/list-action-row`
@@ -478,11 +485,14 @@ export { ListItem, type ListItemProps };
 
 ```ts
 import * as kerfjs from 'kerfjs';
+import { S as Sides } from './divider-sides-BzB6rphT.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
 interface ListInsetControlProps {
     /** Control(s) that own their own border and padding (e.g. an input, a `wa-*`). */
     children: KerfUiContent;
+    /** Physical inset sides in canonical top/right/bottom/left order. Defaults to all sides. */
+    sides?: Sides;
     className?: string;
 }
 /**
@@ -491,22 +501,25 @@ interface ListInsetControlProps {
  * Use it for controls that carry their own border and padding but no outer margin
  * — the wrapper adds only the alignment margin and layout, not a second inset.
  */
-declare function ListInsetControl({ children, className, }: ListInsetControlProps): kerfjs.SafeHtml;
+declare function ListInsetControl({ children, sides, className, }: ListInsetControlProps): kerfjs.SafeHtml;
 
-export { ListInsetControl, type ListInsetControlProps };
+export { ListInsetControl, type ListInsetControlProps, Sides };
 ```
 
 ## `@kerfjs/ui/list-inset-text`
 
 ```ts
 import * as kerfjs from 'kerfjs';
+import { S as Sides } from './divider-sides-BzB6rphT.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
 interface ListInsetTextProps {
     /** Text (or inline content) that carries no margin, border, or padding of its own. */
     children: KerfUiContent | string;
+    /** Physical inset sides in canonical top/right/bottom/left order. Defaults to all sides. */
+    sides?: Sides;
     /**
-     * Keep only the horizontal geometry (inline margin, left/right border, and
+     * @deprecated Pass `sides="rl"` instead. Keep only the horizontal geometry (inline margin, left/right border, and
      * left/right padding) and drop the vertical margin, border, and padding. Use it
      * when the text edge must still align with bordered items but the line should not
      * add its own vertical box space — tight text layout inside a content region.
@@ -522,9 +535,9 @@ interface ListInsetTextProps {
  * Pass `horizontalOnly` to keep the horizontal inset but drop the vertical box
  * space for tight text layout.
  */
-declare function ListInsetText({ children, horizontalOnly, className, }: ListInsetTextProps): kerfjs.SafeHtml;
+declare function ListInsetText({ children, sides, horizontalOnly, className, }: ListInsetTextProps): kerfjs.SafeHtml;
 
-export { ListInsetText, type ListInsetTextProps };
+export { ListInsetText, type ListInsetTextProps, Sides };
 ```
 
 ## `@kerfjs/ui/value-table`
@@ -1996,6 +2009,7 @@ export { DialogSurface, type DialogSurfacePresentation, type DialogSurfaceProps,
 ```ts
 import * as kerfjs from 'kerfjs';
 import { UiSpaceName, CssLength, CssFlexKeyword, CssFlex } from './css-values.js';
+import { S as Sides } from './divider-sides-BzB6rphT.js';
 import { H as HorizontalAlignment, V as VerticalAlignment } from './flex-alignment-CF8NLj7i.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
@@ -2011,10 +2025,35 @@ interface RowProps {
     flex?: boolean | CssFlexKeyword | CssFlex;
     /** Allow children to wrap onto additional lines. */
     wrap?: boolean;
+    /** Physical sides that receive the standard 17px text inset. */
+    textInsets?: Sides;
+    /** Physical sides that receive the standard 8px control inset. Text insets win on overlap. */
+    controlInsets?: Sides;
     className?: string;
 }
 /** A horizontal flex row with explicit physical-axis alignment and spacing. */
-declare function Row({ children, hAlign, vAlign, gap, flex, wrap, className, }: RowProps): kerfjs.SafeHtml;
+declare function Row({ children, hAlign, vAlign, gap, flex, wrap, textInsets, controlInsets, className, }: RowProps): kerfjs.SafeHtml;
 
-export { CssFlex, CssFlexKeyword, CssLength, HorizontalAlignment, Row, type RowProps, UiSpaceName, VerticalAlignment };
+export { CssFlex, CssFlexKeyword, CssLength, HorizontalAlignment, Row, type RowProps, Sides, UiSpaceName, VerticalAlignment };
+```
+
+## `@kerfjs/ui/spacer`
+
+```ts
+import * as kerfjs from 'kerfjs';
+import { UiSpaceName, CssLength } from './css-values.js';
+
+interface SpacerProps {
+    /** Grow and shrink to fill the available space along a parent's flex axis. */
+    flex?: boolean;
+    /** A named UI spacing token or typed physical width. */
+    width?: UiSpaceName | CssLength;
+    /** A named UI spacing token or typed physical height. */
+    height?: UiSpaceName | CssLength;
+    className?: string;
+}
+/** A decorative fixed-size or flexible gap for Row, List, and other flex layouts. */
+declare function Spacer({ flex, width, height, className, }: SpacerProps): kerfjs.SafeHtml;
+
+export { CssLength, Spacer, type SpacerProps, UiSpaceName };
 ```

package/ai/skill.md

@@ -128,13 +128,13 @@ Hard rules:
 12. Demo work uses public production component subpaths and their browser-selected CSS. Give every public visual component its own category-grouped catalog route; list themed third-party components under a clearly labeled collapsible ecosystem section, with a focused route for each. For the complete focused/composition decision, `CatalogExample` / `CatalogExampleStack` row/group nesting, exact specimen selection, geometry-overlay legend and exclusions, skip-marker behavior, and metadata ownership, follow the single [Catalog demo authoring contract](../docs/catalog.md#catalog-demo-authoring-contract), discovered machine-readably through [`catalog-authoring.json`](./catalog-authoring.json). Never infer structure from private `kui-catalog-*` classes. Project each component's deterministic repository-relative demo source and existing documentation path so the detail can expose `View demo source` and `Read guidance` links without a runtime export; also derive first-party component implementation paths from their canonical browser imports, and label Web Awesome documentation as Kerf integration guidance. Declare direct `uses` relationships so `Used by` stays derivable, and theme shell chrome through the same semantic tokens as the stage instead of drawing a substitute. Enable `wireCatalog({ revealSelection: true })` for long desktop sidebars so controlled selections remain visible without moving focus; keep its default compact media guard unless compact scrolling is an explicit product behavior, and use `revealCatalogEntry` for an initial deep link.
 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); 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. 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.
-15. Build sidebars, main areas, inspectors, and dialogs from `@kerfjs/ui/layout.css`: an unpadded `.kui-pane`, optional `.kui-pane__toolbar`, one scrolling `.kui-pane__content`, and optional `.kui-pane__footer`. Use `Row` instead of a hand-written flex-row wrapper and `List` instead of a hand-written flex-column wrapper when children need shared physical-axis alignment and typed spacing. `Row` defaults to left/full with an `xs` gap and no wrapping; `List` retains full/top and zero-gap defaults. Use `List` when rows or sections also need flex growth, one vertical scroll owner, or physical-edge dividers; `dividerSides` uses canonical `t`/`r`/`b`/`l` order. 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 `.kui-content-item` for a child-owned 8px inline margin, 1px transparent-or-visible border, 8px padding, and 12px radius. Use the pill modifier for 22px. Do not pad pane shells, duplicate item geometry in wrappers, or create nested scroll owners.
+15. Build sidebars, main areas, inspectors, and dialogs from `@kerfjs/ui/layout.css`: an unpadded `.kui-pane`, optional `.kui-pane__toolbar`, one scrolling `.kui-pane__content`, and optional `.kui-pane__footer`. Use `Row` instead of a hand-written flex-row wrapper and `List` instead of a hand-written flex-column wrapper when children need shared physical-axis alignment and typed spacing. `Row` defaults to left/full with an `xs` gap and no wrapping; `List` retains full/top and zero-gap defaults. 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 `.kui-content-item` for a child-owned 8px inline margin, 1px transparent-or-visible border, 8px padding, and 12px radius. Use the pill modifier for 22px. Do not pad pane shells, duplicate item geometry in wrappers, or create nested scroll owners.
 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.
-17. The only direct children of a `Toolbar` zone (`leading`/`center`/`trailing`) are `ToolbarText` (identity/title text) and `ToolbarControlGroup`; never drop bare buttons, inputs, links, or arbitrary markup straight into a zone. Put identity/title text directly in the zone as `ToolbarText`; wrap interactive controls and icon tiles in `ToolbarControlGroup`. `SegmentedControl`, `Select`, a collapsible `TokenSearchField`, and Web Awesome controls all live inside a group. 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, chiefly a `wa-dropdown` popup trigger. A popup menu in a toolbar is a `single` group wrapping a `wa-dropdown` whose `slot="trigger"` `wa-button` is the toolbar button and whose `wa-dropdown-item`s are the menu, with the dropdown kept under `data-morph-skip-children`. 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 group remains 44px outside (`calc(2px + remify(42px))`) when its border/background are transparent; use 8px between groups and inside items. Split dormant and interactive regions: `ListHeader` fills the available inline width and keeps its label and mutually exclusive semantic count or non-count `badge` together, with an independent logical-end 44px action unless disclosure mode makes the title cluster the button. Its action visual defaults to 18px through `--kui-list-header-action-icon-size`; never shrink the target to match it. 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 44px 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.
+17. The only direct children of a `Toolbar` zone (`leading`/`center`/`trailing`) are `ToolbarText` (identity/title text) and `ToolbarControlGroup`; never drop bare buttons, inputs, links, or arbitrary markup straight into a zone. Put identity/title text directly in the zone as `ToolbarText`; wrap interactive controls and icon tiles in `ToolbarControlGroup`. `SegmentedControl`, `Select`, a collapsible `TokenSearchField`, and Web Awesome controls all live inside a group. 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, chiefly a `wa-dropdown` popup trigger. A popup menu in a toolbar is a `single` group wrapping a `wa-dropdown` whose `slot="trigger"` `wa-button` is the toolbar button and whose `wa-dropdown-item`s are the menu, with the dropdown kept under `data-morph-skip-children`. 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 group remains 44px outside (`calc(2px + remify(42px))`) when its border/background are transparent; use 8px between groups and inside items. Split dormant and interactive regions: `ListHeader` fills the available inline width by default; set `inline` only when it should shrink-wrap in surrounding content 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`; never shrink the target to match it. 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.
 18. When a recurring concept has no matching export or production recipe, keep its semantics in a thin application adapter while reusing the public layout vocabulary. The composer recipe uses one visible form surface, toolbar title/supporting-copy ids, shared 8px field/action gutters, 24px major rhythm, and a conditional StateBanner as its only nested semantic surface; do not turn every section into a card or double-inset intrinsically bordered controls. The application-local `../docs/examples/command-palette-adapter.tsx` is reference source for one such missing concept, not an `@kerfjs/ui` runtime export or catalog recipe. The application owns its registration, ranking, history, permissions, availability, shortcut policy, focus policy, dispatch, and copy. If a missing concept recurs across products, open an upstream component or recipe request.
 19. Compose `ValueTable` from typed `ValueTableRow` entries instead of handwritten `dt`/`dd` wrappers. Pass `icon` for the optional 24px leading visual; the row owns 8px of root-scaled top and bottom padding, the 8px iconless or 40px icon-bearing separator start, and the common 8px right inset.
 20. Use the standard direct `Toolbar` composition for a panel, dialog, or page heading, not a private wrapper or custom heading row. Put an optional icon in a `ToolbarControlGroup`, the title directly in the leading zone as extra-large `ToolbarText`, and actions in a trailing group. Set `headingLevel` for page/section landmarks. Supporting copy stays below the toolbar as app-owned content. The app owns modal behavior, focus, dismissal, command policy, ids, and action handling.
-21. Space with the official five-step scale, picked by how connected two elements are — not by eye. `0` `--kui-space-none` = no separation (one unit); `4px` `--kui-space-2xs` = very minor air on a connected cluster; `8px` `--kui-space-xs` = standard, between elements within a group; `16px` `--kui-space-m` = minor, between homogeneous groups; `24px` `--kui-space-l` = major, between heterogeneous groups (the `.kui-content` rhythm). The 8px-vs-24px distinction is inside-a-group vs between-major-differing-regions. `--kui-space-s` (12px) and `--kui-space-xl` (32px) are off-scale exceptions. For `Row.gap` or `List.gap`, pass a finite shorthand such as `gap="xs"` or `gap="m"`; when one token is insufficient, import typed builders from the CSS-free `@kerfjs/ui/css-values` subpath. Preserve property grammar: lengths for gap/Skeleton geometry, `flex()` for List flex, and `uiColor()`/`colorVar()` for choice icons. Never cast between brands or emit raw row `style` declarations. `plus` is not standalone and must be wrapped in `calc`; `remify()` remains source-CSS syntax and is never a runtime prop value. See `docs/layout.md` "Spacing scale".
+21. Space with the official five-step scale, picked by how connected two elements are — not by eye. `0` `--kui-space-none` = no separation (one unit); `4px` `--kui-space-2xs` = very minor air on a connected cluster; `8px` `--kui-space-xs` = standard, between elements within a group; `16px` `--kui-space-m` = minor, between homogeneous groups; `24px` `--kui-space-l` = major, between heterogeneous groups (the `.kui-content` rhythm). The 8px-vs-24px distinction is inside-a-group vs between-major-differing-regions. `--kui-space-s` (12px) and `--kui-space-xl` (32px) are off-scale exceptions. For `Row.gap` or `List.gap`, pass a finite shorthand such as `gap="xs"` or `gap="m"`; use `Spacer` for one intentional typed empty width/height or a flexible main-axis gap. When one token is insufficient, import typed builders from the CSS-free `@kerfjs/ui/css-values` subpath. Preserve property grammar: lengths for gap/Spacer/Skeleton geometry, `flex()` for List flex, and `uiColor()`/`colorVar()` for choice icons. Never cast between brands or emit raw row `style` declarations. `plus` is not standalone and must be wrapped in `calc`; `remify()` remains source-CSS syntax and is never a runtime prop value. See `docs/layout.md` "Spacing scale".
 22. Pick a whole-screen layout from the opt-in, tree-shakeable subpaths by data + interaction + device, and derive responsiveness from `@kerfjs/ui/device-class`'s `deviceClass()` (`compact` = handset or portrait tablet = one pane at a time). Simple/flat → `NavStack` with one entry (single pane), plus `TabScaffold` (`@kerfjs/ui/tab-scaffold`, iOS bottom tabs, each tab its own `NavStack`) for 2–5 co-equal sections on `compact`. Drill-down → `NavStack` (`@kerfjs/ui/nav-stack`), upgrading to `SplitView` (`@kerfjs/ui/split-view`, list-detail) once both panes fit (`atLeast('tablet')` landscape); `SplitView` collapses to a `NavStack` on `compact`. Keep each stack's ordered views controlled; put view-specific bottom chrome on `NavStackView.bottomToolbar` (or use the component-level persistent fallback), then call `wireNavStack` so content slides while the active view's top and bottom chrome cross-fade and focus moves into the new top view/restores on pop. Mark a preferred initial heading or control with `data-nav-focus` when DOM order is not sufficient. Complex tool with peripheral panels → `Workbench` (`@kerfjs/ui/workbench`, collapsible rails + drawer) `atLeast('desktop')`, degrading to `NavStack`/overlays below. These are declarative (the app owns the stack/selection/collapsed/active state as signals) with disposer-returning `wire…` helpers; each ships a companion CSS import and stays out of the barrel. For a standalone collapsible rail or bottom drawer outside a full shell, use `CollapsiblePanel` + `CollapsiblePanelToggle` (`@kerfjs/ui/collapsible-panel`) with `wireSidebar` (`@kerfjs/ui/wire-sidebar`): the standard collapse animation and per-side icon convention (`PanelLeft*`/`PanelRight*`/`PanelBottom*`) plus toggle, focus, compact overlay, and persistence semantics. Dialogs pick the same inner layout, then present per device class (full-screen modal on `compact`, inline on desktop). See `docs/app-layouts.md` and `docs/collapsible-panel.md`.
 
 Common mistakes: