@kerfjs/ui 5.0.0-beta.36 → 5.0.0-beta.38

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
@@ -165,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`             |

package/ai/component-catalog-v2.json

@@ -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",
@@ -3620,7 +3706,7 @@
       "boundaries": {
         "rootClass": null,
         "publicClasses": [],
-        "publicTokens": []
+        "publicTokens": ["--kui-wa-surface-margin", "--kui-wa-surface-inset"]
       },
       "diagnostics": [],
       "provenance": {

package/ai/component-catalog.json

@@ -1733,6 +1733,98 @@
         "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",
@@ -4422,6 +4514,10 @@
       ],
       "recommendation": "supported",
       "alternatives": [],
+      "publicTokens": [
+        "--kui-wa-surface-margin",
+        "--kui-wa-surface-inset"
+      ],
       "geometry": {
         "margin": "self",
         "border": "self",

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.36` and `kerfjs@5.0.0-beta.36`. 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.38` and `kerfjs@5.0.0-beta.38`. 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`
 
@@ -2036,3 +2036,24 @@ declare function Row({ children, hAlign, vAlign, gap, flex, wrap, textInsets, co
 
 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

@@ -134,7 +134,7 @@ Hard rules:
 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:

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.36` 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.38` 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/browser/spacer.js

@@ -0,0 +1,3 @@
+import '../styles/foundation.css';
+import '../styles/spacer.css';
+export * from '../spacer.js';

package/dist/catalog.js

@@ -3,7 +3,7 @@ import { Toolbar } from './chunk-VXFGMDA7.js';
 import { Pane } from './chunk-I4V3UDSA.js';
 import { ListHeader } from './chunk-5FJ53EOF.js';
 import { ListItem } from './chunk-I45QO2IZ.js';
-import { List } from './chunk-TNXDXSGP.js';
+import { List } from './chunk-C34NZOLJ.js';
 
 import { filterDataAttributes } from './chunk-SRSJO5QE.js';
 

package/dist/{chunk-TNXDXSGP.js → chunk-C34NZOLJ.js}

@@ -40,8 +40,8 @@ function List({
       "data-v-align": verticalAlignment(vAlign),
       "data-scrollable": String(scrollable),
       "divider-sides": dividerSides || void 0,
-      "text-insets": textInsets || void 0,
-      "control-insets": controlInsets || void 0,
+      "data-text-insets": textInsets || void 0,
+      "data-control-insets": controlInsets || void 0,
       style: style || void 0,
       children
     }
@@ -50,4 +50,4 @@ function List({
 
 export { List };
 
-//# sourceMappingURL=chunk-TNXDXSGP.js.map
+//# sourceMappingURL=chunk-C34NZOLJ.js.map

package/dist/chunk-C34NZOLJ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/list.tsx"],"names":[],"mappings":";;;;AAgBA,IAAM,UAAA,GAAqC;AAAA,EACzC,MAAA;AAAA,EACA,KAAA;AAAA,EACA,IAAA;AAAA,EACA,GAAA;AAAA,EACA,GAAA;AAAA,EACA,GAAA;AAAA,EACA;AACF,CAAA;AAwBO,SAAS,IAAA,CAAK;AAAA,EACnB,QAAA;AAAA,EACA,GAAA,GAAM,KAAA;AAAA,EACN,IAAA,GAAO,KAAA;AAAA,EACP,MAAA,GAAS,MAAA;AAAA,EACT,MAAA,GAAS,KAAA;AAAA,EACT,UAAA,GAAa,KAAA;AAAA,EACb,YAAA,GAAe,EAAA;AAAA,EACf,UAAA,GAAa,EAAA;AAAA,EACb,aAAA,GAAgB,EAAA;AAAA,EAChB,SAAA,GAAY;AACd,CAAA,EAAc;AACZ,EAAA,MAAM,QAAA,GACJ,GAAA,KAAQ,IAAA,GACJ,qBAAA,GACA,UAAA,CAAW,QAAA,CAAS,GAAkB,CAAA,GACpC,KAAA,CAAM,GAAkB,CAAA,GACxB,GAAA,IAAO,MAAA;AACf,EAAA,MAAM,SAAA,GAAY,IAAA,KAAS,IAAA,GAAO,UAAA,GAAa,IAAA,IAAQ,MAAA;AACvD,EAAA,MAAM,KAAA,GAAQ;AAAA,IACZ,QAAA,GAAW,CAAA,gBAAA,EAAmB,QAAQ,CAAA,CAAA,GAAK,EAAA;AAAA,IAC3C,SAAA,GAAY,CAAA,iBAAA,EAAoB,SAAS,CAAA,CAAA,GAAK;AAAA,GAChD,CACG,MAAA,CAAO,OAAO,CAAA,CACd,KAAK,GAAG,CAAA;AAEX,EAAA,uBACE,GAAA;AAAA,IAAC,KAAA;AAAA,IAAA;AAAA,MACC,KAAA,EAAO,CAAA,SAAA,EAAY,SAAS,CAAA,CAAA,CAAG,IAAA,EAAK;AAAA,MACpC,gBAAA,EAAe,MAAA;AAAA,MACf,UAAA,EAAU,MAAA,CAAO,OAAA,CAAQ,GAAG,CAAC,CAAA;AAAA,MAC7B,WAAA,EAAW,MAAA,CAAO,OAAA,CAAQ,IAAI,CAAC,CAAA;AAAA,MAC/B,cAAA,EAAc,oBAAoB,MAAM,CAAA;AAAA,MACxC,cAAA,EAAc,kBAAkB,MAAM,CAAA;AAAA,MACtC,iBAAA,EAAiB,OAAO,UAAU,CAAA;AAAA,MAClC,iBAAe,YAAA,IAAgB,MAAA;AAAA,MAC/B,oBAAkB,UAAA,IAAc,MAAA;AAAA,MAChC,uBAAqB,aAAA,IAAiB,MAAA;AAAA,MACtC,OAAO,KAAA,IAAS,MAAA;AAAA,MAEf;AAAA;AAAA,GACH;AAEJ","file":"chunk-C34NZOLJ.js","sourcesContent":["import {\n  type CssFlex,\n  type CssFlexKeyword,\n  type CssLength,\n  space,\n  type UiSpaceName,\n} from './css-values.js';\nimport type { DividerSides, Sides } from './divider-sides.js';\nimport {\n  type HorizontalAlignment,\n  horizontalAlignment,\n  type VerticalAlignment,\n  verticalAlignment,\n} from './flex-alignment.js';\nimport type { KerfUiContent } from './semantic-content.js';\n\nconst spaceNames: readonly UiSpaceName[] = [\n  'none',\n  '2xs',\n  'xs',\n  's',\n  'm',\n  'l',\n  'xl',\n];\n\nexport interface ListProps {\n  children?: KerfUiContent;\n  /** Use the standard item gap, a named UI spacing token, or a typed CSS length. Defaults to no gap. */\n  gap?: boolean | UiSpaceName | CssLength;\n  /** Allow this list to grow/shrink, use a keyword, or supply a typed CSS flex shorthand. */\n  flex?: boolean | CssFlexKeyword | CssFlex;\n  /** Horizontal alignment. Defaults to full to preserve stretch-aligned list children. */\n  hAlign?: HorizontalAlignment;\n  /** Vertical distribution. Defaults to top. */\n  vAlign?: VerticalAlignment;\n  /** Own vertical scrolling and overscroll containment. */\n  scrollable?: boolean;\n  /** Physical divider edges in canonical top/right/bottom/left order. */\n  dividerSides?: DividerSides;\n  /** Physical sides that receive the standard 17px text inset. */\n  textInsets?: Sides;\n  /** Physical sides that receive the standard 8px control inset. Text insets win on overlap. */\n  controlInsets?: Sides;\n  className?: string;\n}\n\n/** A stretch-aligned vertical stack with optional gap, flex, scroll, and dividers. */\nexport function List({\n  children,\n  gap = false,\n  flex = false,\n  hAlign = 'full',\n  vAlign = 'top',\n  scrollable = false,\n  dividerSides = '',\n  textInsets = '',\n  controlInsets = '',\n  className = '',\n}: ListProps) {\n  const gapValue =\n    gap === true\n      ? 'var(--kui-list-gap)'\n      : spaceNames.includes(gap as UiSpaceName)\n        ? space(gap as UiSpaceName)\n        : gap || undefined;\n  const flexValue = flex === true ? '1 1 auto' : flex || undefined;\n  const style = [\n    gapValue ? `--_kui-list-gap:${gapValue}` : '',\n    flexValue ? `--_kui-list-flex:${flexValue}` : '',\n  ]\n    .filter(Boolean)\n    .join(';');\n\n  return (\n    <div\n      class={`kui-list ${className}`.trim()}\n      data-component=\"list\"\n      data-gap={String(Boolean(gap))}\n      data-flex={String(Boolean(flex))}\n      data-h-align={horizontalAlignment(hAlign)}\n      data-v-align={verticalAlignment(vAlign)}\n      data-scrollable={String(scrollable)}\n      divider-sides={dividerSides || undefined}\n      data-text-insets={textInsets || undefined}\n      data-control-insets={controlInsets || undefined}\n      style={style || undefined}\n    >\n      {children}\n    </div>\n  );\n}\n\nexport type {\n  CssFlex,\n  CssFlexKeyword,\n  CssLength,\n  UiSpaceName,\n} from './css-values.js';\nexport type { DividerSides, Sides } from './divider-sides.js';\nexport type {\n  HorizontalAlignment,\n  VerticalAlignment,\n} from './flex-alignment.js';\n"]}

package/dist/chunk-OGTJNHRG.js

@@ -0,0 +1,42 @@
+import { space } from './chunk-OL4TC3U2.js';
+import { jsx } from 'kerfjs/jsx-runtime';
+
+var spaceNames = [
+  "none",
+  "2xs",
+  "xs",
+  "s",
+  "m",
+  "l",
+  "xl"
+];
+function dimension(value) {
+  return spaceNames.includes(value) ? space(value) : value;
+}
+function Spacer({
+  flex = false,
+  width,
+  height,
+  className = ""
+}) {
+  const widthValue = dimension(width);
+  const heightValue = dimension(height);
+  const style = [
+    widthValue ? `width:${widthValue}` : "",
+    heightValue ? `height:${heightValue}` : ""
+  ].filter(Boolean).join(";");
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      class: `kui-spacer ${className}`.trim(),
+      "data-component": "spacer",
+      "data-flex": String(flex),
+      "aria-hidden": "true",
+      style: style || void 0
+    }
+  );
+}
+
+export { Spacer };
+
+//# sourceMappingURL=chunk-OGTJNHRG.js.map

package/dist/chunk-OGTJNHRG.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/spacer.tsx"],"names":[],"mappings":";;;AAEA,IAAM,UAAA,GAAqC;AAAA,EACzC,MAAA;AAAA,EACA,KAAA;AAAA,EACA,IAAA;AAAA,EACA,GAAA;AAAA,EACA,GAAA;AAAA,EACA,GAAA;AAAA,EACA;AACF,CAAA;AAYA,SAAS,UAAU,KAAA,EAAwD;AACzE,EAAA,OAAO,WAAW,QAAA,CAAS,KAAoB,CAAA,GAC3C,KAAA,CAAM,KAAoB,CAAA,GACzB,KAAA;AACP;AAGO,SAAS,MAAA,CAAO;AAAA,EACrB,IAAA,GAAO,KAAA;AAAA,EACP,KAAA;AAAA,EACA,MAAA;AAAA,EACA,SAAA,GAAY;AACd,CAAA,EAAgB;AACd,EAAA,MAAM,UAAA,GAAa,UAAU,KAAK,CAAA;AAClC,EAAA,MAAM,WAAA,GAAc,UAAU,MAAM,CAAA;AACpC,EAAA,MAAM,KAAA,GAAQ;AAAA,IACZ,UAAA,GAAa,CAAA,MAAA,EAAS,UAAU,CAAA,CAAA,GAAK,EAAA;AAAA,IACrC,WAAA,GAAc,CAAA,OAAA,EAAU,WAAW,CAAA,CAAA,GAAK;AAAA,GAC1C,CACG,MAAA,CAAO,OAAO,CAAA,CACd,KAAK,GAAG,CAAA;AAEX,EAAA,uBACE,GAAA;AAAA,IAAC,KAAA;AAAA,IAAA;AAAA,MACC,KAAA,EAAO,CAAA,WAAA,EAAc,SAAS,CAAA,CAAA,CAAG,IAAA,EAAK;AAAA,MACtC,gBAAA,EAAe,QAAA;AAAA,MACf,WAAA,EAAW,OAAO,IAAI,CAAA;AAAA,MACtB,aAAA,EAAY,MAAA;AAAA,MACZ,OAAO,KAAA,IAAS;AAAA;AAAA,GACjB;AAEL","file":"chunk-OGTJNHRG.js","sourcesContent":["import { type CssLength, space, type UiSpaceName } from './css-values.js';\n\nconst spaceNames: readonly UiSpaceName[] = [\n  'none',\n  '2xs',\n  'xs',\n  's',\n  'm',\n  'l',\n  'xl',\n];\n\nexport interface SpacerProps {\n  /** Grow and shrink to fill the available space along a parent's flex axis. */\n  flex?: boolean;\n  /** A named UI spacing token or typed physical width. */\n  width?: UiSpaceName | CssLength;\n  /** A named UI spacing token or typed physical height. */\n  height?: UiSpaceName | CssLength;\n  className?: string;\n}\n\nfunction dimension(value?: UiSpaceName | CssLength): CssLength | undefined {\n  return spaceNames.includes(value as UiSpaceName)\n    ? space(value as UiSpaceName)\n    : (value as CssLength | undefined);\n}\n\n/** A decorative fixed-size or flexible gap for Row, List, and other flex layouts. */\nexport function Spacer({\n  flex = false,\n  width,\n  height,\n  className = '',\n}: SpacerProps) {\n  const widthValue = dimension(width);\n  const heightValue = dimension(height);\n  const style = [\n    widthValue ? `width:${widthValue}` : '',\n    heightValue ? `height:${heightValue}` : '',\n  ]\n    .filter(Boolean)\n    .join(';');\n\n  return (\n    <div\n      class={`kui-spacer ${className}`.trim()}\n      data-component=\"spacer\"\n      data-flex={String(flex)}\n      aria-hidden=\"true\"\n      style={style || undefined}\n    ></div>\n  );\n}\n\nexport type { CssLength, UiSpaceName } from './css-values.js';\n"]}

package/dist/{chunk-AVZ2IMWG.js → chunk-X5GRDQ7V.js}

@@ -37,8 +37,8 @@ function Row({
       "data-v-align": verticalAlignment(vAlign),
       "data-flex": String(Boolean(flex)),
       "data-wrap": String(wrap),
-      "text-insets": textInsets || void 0,
-      "control-insets": controlInsets || void 0,
+      "data-text-insets": textInsets || void 0,
+      "data-control-insets": controlInsets || void 0,
       style,
       children
     }
@@ -47,4 +47,4 @@ function Row({
 
 export { Row };
 
-//# sourceMappingURL=chunk-AVZ2IMWG.js.map
+//# sourceMappingURL=chunk-X5GRDQ7V.js.map

package/dist/chunk-X5GRDQ7V.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/row.tsx"],"names":[],"mappings":";;;;AAgBA,IAAM,UAAA,GAAqC;AAAA,EACzC,MAAA;AAAA,EACA,KAAA;AAAA,EACA,IAAA;AAAA,EACA,GAAA;AAAA,EACA,GAAA;AAAA,EACA,GAAA;AAAA,EACA;AACF,CAAA;AAsBO,SAAS,GAAA,CAAI;AAAA,EAClB,QAAA;AAAA,EACA,MAAA,GAAS,MAAA;AAAA,EACT,MAAA,GAAS,MAAA;AAAA,EACT,GAAA,GAAM,IAAA;AAAA,EACN,IAAA,GAAO,KAAA;AAAA,EACP,IAAA,GAAO,KAAA;AAAA,EACP,UAAA,GAAa,EAAA;AAAA,EACb,aAAA,GAAgB,EAAA;AAAA,EAChB,SAAA,GAAY;AACd,CAAA,EAAa;AACX,EAAA,MAAM,WAAW,UAAA,CAAW,QAAA,CAAS,GAAkB,CAAA,GACnD,KAAA,CAAM,GAAkB,CAAA,GACxB,GAAA;AACJ,EAAA,MAAM,SAAA,GAAY,IAAA,KAAS,IAAA,GAAO,UAAA,GAAa,IAAA,IAAQ,MAAA;AACvD,EAAA,MAAM,KAAA,GAAQ;AAAA,IACZ,kBAAkB,QAAQ,CAAA,CAAA;AAAA,IAC1B,SAAA,GAAY,CAAA,gBAAA,EAAmB,SAAS,CAAA,CAAA,GAAK;AAAA,GAC/C,CACG,MAAA,CAAO,OAAO,CAAA,CACd,KAAK,GAAG,CAAA;AAEX,EAAA,uBACE,GAAA;AAAA,IAAC,KAAA;AAAA,IAAA;AAAA,MACC,KAAA,EAAO,CAAA,QAAA,EAAW,SAAS,CAAA,CAAA,CAAG,IAAA,EAAK;AAAA,MACnC,gBAAA,EAAe,KAAA;AAAA,MACf,cAAA,EAAc,oBAAoB,MAAM,CAAA;AAAA,MACxC,cAAA,EAAc,kBAAkB,MAAM,CAAA;AAAA,MACtC,WAAA,EAAW,MAAA,CAAO,OAAA,CAAQ,IAAI,CAAC,CAAA;AAAA,MAC/B,WAAA,EAAW,OAAO,IAAI,CAAA;AAAA,MACtB,oBAAkB,UAAA,IAAc,MAAA;AAAA,MAChC,uBAAqB,aAAA,IAAiB,MAAA;AAAA,MACtC,KAAA;AAAA,MAEC;AAAA;AAAA,GACH;AAEJ","file":"chunk-X5GRDQ7V.js","sourcesContent":["import {\n  type CssFlex,\n  type CssFlexKeyword,\n  type CssLength,\n  space,\n  type UiSpaceName,\n} from './css-values.js';\nimport type { Sides } from './divider-sides.js';\nimport {\n  type HorizontalAlignment,\n  horizontalAlignment,\n  type VerticalAlignment,\n  verticalAlignment,\n} from './flex-alignment.js';\nimport type { KerfUiContent } from './semantic-content.js';\n\nconst spaceNames: readonly UiSpaceName[] = [\n  'none',\n  '2xs',\n  'xs',\n  's',\n  'm',\n  'l',\n  'xl',\n];\n\nexport interface RowProps {\n  children?: KerfUiContent;\n  /** Horizontal distribution. Defaults to left. */\n  hAlign?: HorizontalAlignment;\n  /** Vertical alignment and wrapped-line distribution. Defaults to full. */\n  vAlign?: VerticalAlignment;\n  /** A named UI spacing token or typed CSS length. Defaults to xs. */\n  gap?: UiSpaceName | CssLength;\n  /** Allow this row to grow/shrink, use a keyword, or supply a typed CSS flex shorthand. */\n  flex?: boolean | CssFlexKeyword | CssFlex;\n  /** Allow children to wrap onto additional lines. */\n  wrap?: boolean;\n  /** Physical sides that receive the standard 17px text inset. */\n  textInsets?: Sides;\n  /** Physical sides that receive the standard 8px control inset. Text insets win on overlap. */\n  controlInsets?: Sides;\n  className?: string;\n}\n\n/** A horizontal flex row with explicit physical-axis alignment and spacing. */\nexport function Row({\n  children,\n  hAlign = 'left',\n  vAlign = 'full',\n  gap = 'xs',\n  flex = false,\n  wrap = false,\n  textInsets = '',\n  controlInsets = '',\n  className = '',\n}: RowProps) {\n  const gapValue = spaceNames.includes(gap as UiSpaceName)\n    ? space(gap as UiSpaceName)\n    : gap;\n  const flexValue = flex === true ? '1 1 auto' : flex || undefined;\n  const style = [\n    `--_kui-row-gap:${gapValue}`,\n    flexValue ? `--_kui-row-flex:${flexValue}` : '',\n  ]\n    .filter(Boolean)\n    .join(';');\n\n  return (\n    <div\n      class={`kui-row ${className}`.trim()}\n      data-component=\"row\"\n      data-h-align={horizontalAlignment(hAlign)}\n      data-v-align={verticalAlignment(vAlign)}\n      data-flex={String(Boolean(flex))}\n      data-wrap={String(wrap)}\n      data-text-insets={textInsets || undefined}\n      data-control-insets={controlInsets || undefined}\n      style={style}\n    >\n      {children}\n    </div>\n  );\n}\n\nexport type {\n  CssFlex,\n  CssFlexKeyword,\n  CssLength,\n  UiSpaceName,\n} from './css-values.js';\nexport type { Sides } from './divider-sides.js';\nexport type {\n  HorizontalAlignment,\n  VerticalAlignment,\n} from './flex-alignment.js';\n"]}

package/dist/index.d.ts

@@ -18,6 +18,7 @@ export { SegmentedControl, SegmentedControlAppearance, SegmentedControlChoice, S
 export { Select, SelectChoice, SelectFocusRingOwner, SelectPresentation, SelectProps, SelectSelectedPresentation, SelectSize } from './select.js';
 export { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 export { Skeleton, SkeletonProps } from './skeleton.js';
+export { Spacer, SpacerProps } from './spacer.js';
 export { StateBanner, StateBannerProps, StateBannerTone, StateBannerUrgency } from './state-banner.js';
 export { SunkenPanel, SunkenPanelProps, SunkenPanelShape } from './sunken-panel.js';
 export { DialogSurface, DialogSurfacePresentation, DialogSurfaceProps, DialogSurfaceSize, PopupSurface, PopupSurfaceInset, PopupSurfaceProps, SurfaceInset } from './surface-scaffold.js';

package/dist/index.js

@@ -4,13 +4,14 @@ export { wireTokenSearchFields } from './chunk-VDUJZF5G.js';
 export { TokenSearchField, placeTokenSearchCaret, readTokenSearchField } from './chunk-TIGSG6BX.js';
 export { ValueTable, ValueTableRow } from './chunk-V6HCTCVD.js';
 export { Select } from './chunk-CK6P5AUK.js';
+export { Spacer } from './chunk-OGTJNHRG.js';
 export { StateBanner } from './chunk-UDHHKZWO.js';
 export { SunkenPanel } from './chunk-SOK5EUF7.js';
 export { DialogSurface, PopupSurface } from './chunk-WSXUPSID.js';
 export { TabBar } from './chunk-ZPWZIVI6.js';
 export { ToolbarText } from './chunk-V6GQKOX2.js';
 export { ResizableRegion, clampRegionSize, resizeRegionFromPointer } from './chunk-CAB6NQ2T.js';
-export { Row } from './chunk-AVZ2IMWG.js';
+export { Row } from './chunk-X5GRDQ7V.js';
 export { SegmentedControl } from './chunk-E34TE2ZI.js';
 export { FloatingToolbar } from './chunk-DYBPI5O2.js';
 export { ListActionRow } from './chunk-DAO2VFTT.js';
@@ -22,7 +23,7 @@ export { Toolbar } from './chunk-VXFGMDA7.js';
 export { Pane } from './chunk-I4V3UDSA.js';
 export { ListHeader } from './chunk-5FJ53EOF.js';
 export { ListItem } from './chunk-I45QO2IZ.js';
-export { List } from './chunk-TNXDXSGP.js';
+export { List } from './chunk-C34NZOLJ.js';
 
 
 export { Skeleton } from './chunk-T7DOWS6T.js';

package/dist/list.js

@@ -1,4 +1,4 @@
-export { List } from './chunk-TNXDXSGP.js';
+export { List } from './chunk-C34NZOLJ.js';
 
 
 

package/dist/row.js

@@ -1,4 +1,4 @@
-export { Row } from './chunk-AVZ2IMWG.js';
+export { Row } from './chunk-X5GRDQ7V.js';
 
 
 

package/dist/spacer.d.ts

@@ -0,0 +1,16 @@
+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/dist/spacer.js

@@ -0,0 +1,4 @@
+export { Spacer } from './chunk-OGTJNHRG.js';
+
+
+//# sourceMappingURL=spacer.js.map

package/dist/spacer.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"spacer.js"}

package/dist/styles/list-header.css

@@ -39,7 +39,7 @@
 }
 
 .kui-list-header[data-inline="true"] {
-  display: inline-block;
+  display: inline-flex;
   width: auto;
   margin: 0;
   border: 0;

package/dist/styles/list.css

@@ -25,44 +25,44 @@
     inset 1px 0 var(--_kui-list-divider-left);
 }
 
-.kui-list[control-insets*="t"] {
+.kui-list[data-control-insets*="t"] {
   --_kui-list-inset-top: var(--kui-layout-inline-margin, 0.5rem);
 }
 
-.kui-list[control-insets*="r"] {
+.kui-list[data-control-insets*="r"] {
   --_kui-list-inset-right: var(--kui-layout-inline-margin, 0.5rem);
 }
 
-.kui-list[control-insets*="b"] {
+.kui-list[data-control-insets*="b"] {
   --_kui-list-inset-bottom: var(--kui-layout-inline-margin, 0.5rem);
 }
 
-.kui-list[control-insets*="l"] {
+.kui-list[data-control-insets*="l"] {
   --_kui-list-inset-left: var(--kui-layout-inline-margin, 0.5rem);
 }
 
-.kui-list[text-insets*="t"] {
+.kui-list[data-text-insets*="t"] {
   --_kui-list-inset-top: calc(
     var(--kui-layout-inline-margin, 0.5rem) + 1px +
       var(--kui-layout-item-padding, 0.5rem)
   );
 }
 
-.kui-list[text-insets*="r"] {
+.kui-list[data-text-insets*="r"] {
   --_kui-list-inset-right: calc(
     var(--kui-layout-inline-margin, 0.5rem) + 1px +
       var(--kui-layout-item-padding, 0.5rem)
   );
 }
 
-.kui-list[text-insets*="b"] {
+.kui-list[data-text-insets*="b"] {
   --_kui-list-inset-bottom: calc(
     var(--kui-layout-inline-margin, 0.5rem) + 1px +
       var(--kui-layout-item-padding, 0.5rem)
   );
 }
 
-.kui-list[text-insets*="l"] {
+.kui-list[data-text-insets*="l"] {
   --_kui-list-inset-left: calc(
     var(--kui-layout-inline-margin, 0.5rem) + 1px +
       var(--kui-layout-item-padding, 0.5rem)

package/dist/styles/row.css

@@ -16,44 +16,44 @@
   gap: var(--_kui-row-gap, var(--kui-row-gap));
 }
 
-.kui-row[control-insets*="t"] {
+.kui-row[data-control-insets*="t"] {
   --_kui-row-inset-top: var(--kui-layout-inline-margin, 0.5rem);
 }
 
-.kui-row[control-insets*="r"] {
+.kui-row[data-control-insets*="r"] {
   --_kui-row-inset-right: var(--kui-layout-inline-margin, 0.5rem);
 }
 
-.kui-row[control-insets*="b"] {
+.kui-row[data-control-insets*="b"] {
   --_kui-row-inset-bottom: var(--kui-layout-inline-margin, 0.5rem);
 }
 
-.kui-row[control-insets*="l"] {
+.kui-row[data-control-insets*="l"] {
   --_kui-row-inset-left: var(--kui-layout-inline-margin, 0.5rem);
 }
 
-.kui-row[text-insets*="t"] {
+.kui-row[data-text-insets*="t"] {
   --_kui-row-inset-top: calc(
     var(--kui-layout-inline-margin, 0.5rem) + 1px +
       var(--kui-layout-item-padding, 0.5rem)
   );
 }
 
-.kui-row[text-insets*="r"] {
+.kui-row[data-text-insets*="r"] {
   --_kui-row-inset-right: calc(
     var(--kui-layout-inline-margin, 0.5rem) + 1px +
       var(--kui-layout-item-padding, 0.5rem)
   );
 }
 
-.kui-row[text-insets*="b"] {
+.kui-row[data-text-insets*="b"] {
   --_kui-row-inset-bottom: calc(
     var(--kui-layout-inline-margin, 0.5rem) + 1px +
       var(--kui-layout-item-padding, 0.5rem)
   );
 }
 
-.kui-row[text-insets*="l"] {
+.kui-row[data-text-insets*="l"] {
   --_kui-row-inset-left: calc(
     var(--kui-layout-inline-margin, 0.5rem) + 1px +
       var(--kui-layout-item-padding, 0.5rem)

package/dist/styles/spacer.css

@@ -0,0 +1,11 @@
+.kui-spacer {
+  box-sizing: border-box;
+  flex: 0 0 auto;
+  min-width: 0;
+  min-height: 0;
+  pointer-events: none;
+}
+
+.kui-spacer[data-flex="true"] {
+  flex: 1 1 auto;
+}

package/dist/styles/styles.css

@@ -8,6 +8,7 @@
 @import "./toolbar-text.css";
 @import "./list.css";
 @import "./row.css";
+@import "./spacer.css";
 @import "./list-action-row.css";
 @import "./list-item.css";
 @import "./list-header.css";

package/docs/component-selection.md

@@ -38,8 +38,10 @@ foreground/background contrast relationships and visible focus ring.
 
 ### Typed runtime dimensions
 
-Use `Row` or `List` spacing shorthands for the common case: `gap="xs"`, `gap="m"`, and
-the other `UiSpaceName` values resolve to their matching `--kui-space-*` token.
+Use `Row` or `List` spacing shorthands for repeated sibling spacing: `gap="xs"`,
+`gap="m"`, and the other `UiSpaceName` values resolve to their matching
+`--kui-space-*` token. Use `Spacer` for one deliberate empty width or height, or
+pass `flex` to consume the remaining space along a flex parent's main axis.
 The canonical rhythm is `none`, `2xs`, `xs`, `m`, and `l`; use `s` and `xl`
 only as deliberate exceptions.
 
@@ -65,7 +67,8 @@ Raw strings such as `"0.25rem"` no longer satisfy `Row.gap` or `List.gap`; this
 contract lands before the 5.0 stable release so misspelled tokens and incomplete
 expressions fail during typechecking rather than in the browser.
 
-Other CSS-valued props use distinct contracts: `flex()` creates `CssFlex` for
+Other CSS-valued props use distinct contracts: `Spacer.width` and
+`Spacer.height` take `UiSpaceName | CssLength`; `flex()` creates `CssFlex` for
 `Row.flex` and `List.flex`; `Skeleton` dimensions take typed lengths (plus finite intrinsic
 keywords for width/height); and `uiColor()`/`colorVar()` create `CssColor` for
 `SelectChoice.color`. Do not substitute one brand for another. Row components

package/docs/layout.md

@@ -118,6 +118,31 @@ Use `rem`, `em`, `px`, `pct`, `lengthVar`, and `calc(plus(...))` only when a
 named spacing relationship does not express the requirement; do not pass raw
 CSS strings.
 
+## Spacer
+
+Use `Spacer` from `@kerfjs/ui/spacer` for one intentional empty dimension that
+is not the repeated relationship owned by a parent's `gap`. Its `width` and
+`height` accept the same finite `UiSpaceName` vocabulary or a complete typed
+`CssLength`. Fixed spacers use `flex: 0 0 auto`, so flex layouts do not compress
+the requested dimension. Pass `flex` to use `1 1 auto` and consume the remaining
+space along a `Row`, `List`, or other flex parent's main axis.
+
+```tsx
+import { Row } from "@kerfjs/ui/row";
+import { Spacer } from "@kerfjs/ui/spacer";
+
+<Row gap="none">
+  <button>Back</button>
+  <Spacer flex />
+  <button>Save</button>
+</Row>;
+```
+
+Spacer is always decorative (`aria-hidden="true"`), accepts no children, and
+uses physical width and height. Prefer `Row.gap` or `List.gap` for uniform
+sibling rhythm, and never use Spacer to cancel or duplicate component-owned
+insets.
+
 ## Row and List alignment
 
 Use `Row` for a horizontal flex layout and `List` for a vertical one. `Row`

package/llms.txt

@@ -162,7 +162,8 @@ maintain a central style list. Configure JSX with `"jsxImportSource": "kerfjs"`.
   `--kui-space-none`, `4px` `--kui-space-2xs`, `8px` `--kui-space-xs` (inside a
   group), `16px` `--kui-space-m`, `24px` `--kui-space-l` (between major differing
   regions). 12px/32px are off-scale exceptions. Prefer direct `Row.gap`/`List.gap`
-  shorthands; use `space`, `px`, `rem`, `em`, `pct`, `lengthVar`, and
+  shorthands for repeated rhythm; use `Spacer` for one typed empty width/height
+  or flexible main-axis gap. Use `space`, `px`, `rem`, `em`, `pct`, `lengthVar`, and
   `calc(plus(...))` for typed runtime composition. `remify()` is source-CSS only.
 - **Keep nested highlight corners concentric.** Inset hover and selection surfaces
   follow the owning control's pill or rounded shape; their radius is the outer

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kerfjs/ui",
-  "version": "5.0.0-beta.36",
+  "version": "5.0.0-beta.38",
   "description": "Accessible, composable UI primitives for kerf applications.",
   "type": "module",
   "license": "MIT",
@@ -93,6 +93,11 @@
       "browser": "./dist/browser/row.js",
       "import": "./dist/row.js"
     },
+    "./spacer": {
+      "types": "./dist/spacer.d.ts",
+      "browser": "./dist/browser/spacer.js",
+      "import": "./dist/spacer.js"
+    },
     "./list-action-row": {
       "types": "./dist/list-action-row.d.ts",
       "browser": "./dist/browser/list-action-row.js",
@@ -284,6 +289,7 @@
     "./toolbar-text.css": "./dist/styles/toolbar-text.css",
     "./list.css": "./dist/styles/list.css",
     "./row.css": "./dist/styles/row.css",
+    "./spacer.css": "./dist/styles/spacer.css",
     "./list-action-row.css": "./dist/styles/list-action-row.css",
     "./list-item.css": "./dist/styles/list-item.css",
     "./list-header.css": "./dist/styles/list-header.css",

package/dist/chunk-AVZ2IMWG.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/row.tsx"],"names":[],"mappings":";;;;AAgBA,IAAM,UAAA,GAAqC;AAAA,EACzC,MAAA;AAAA,EACA,KAAA;AAAA,EACA,IAAA;AAAA,EACA,GAAA;AAAA,EACA,GAAA;AAAA,EACA,GAAA;AAAA,EACA;AACF,CAAA;AAsBO,SAAS,GAAA,CAAI;AAAA,EAClB,QAAA;AAAA,EACA,MAAA,GAAS,MAAA;AAAA,EACT,MAAA,GAAS,MAAA;AAAA,EACT,GAAA,GAAM,IAAA;AAAA,EACN,IAAA,GAAO,KAAA;AAAA,EACP,IAAA,GAAO,KAAA;AAAA,EACP,UAAA,GAAa,EAAA;AAAA,EACb,aAAA,GAAgB,EAAA;AAAA,EAChB,SAAA,GAAY;AACd,CAAA,EAAa;AACX,EAAA,MAAM,WAAW,UAAA,CAAW,QAAA,CAAS,GAAkB,CAAA,GACnD,KAAA,CAAM,GAAkB,CAAA,GACxB,GAAA;AACJ,EAAA,MAAM,SAAA,GAAY,IAAA,KAAS,IAAA,GAAO,UAAA,GAAa,IAAA,IAAQ,MAAA;AACvD,EAAA,MAAM,KAAA,GAAQ;AAAA,IACZ,kBAAkB,QAAQ,CAAA,CAAA;AAAA,IAC1B,SAAA,GAAY,CAAA,gBAAA,EAAmB,SAAS,CAAA,CAAA,GAAK;AAAA,GAC/C,CACG,MAAA,CAAO,OAAO,CAAA,CACd,KAAK,GAAG,CAAA;AAEX,EAAA,uBACE,GAAA;AAAA,IAAC,KAAA;AAAA,IAAA;AAAA,MACC,KAAA,EAAO,CAAA,QAAA,EAAW,SAAS,CAAA,CAAA,CAAG,IAAA,EAAK;AAAA,MACnC,gBAAA,EAAe,KAAA;AAAA,MACf,cAAA,EAAc,oBAAoB,MAAM,CAAA;AAAA,MACxC,cAAA,EAAc,kBAAkB,MAAM,CAAA;AAAA,MACtC,WAAA,EAAW,MAAA,CAAO,OAAA,CAAQ,IAAI,CAAC,CAAA;AAAA,MAC/B,WAAA,EAAW,OAAO,IAAI,CAAA;AAAA,MACtB,eAAa,UAAA,IAAc,MAAA;AAAA,MAC3B,kBAAgB,aAAA,IAAiB,MAAA;AAAA,MACjC,KAAA;AAAA,MAEC;AAAA;AAAA,GACH;AAEJ","file":"chunk-AVZ2IMWG.js","sourcesContent":["import {\n  type CssFlex,\n  type CssFlexKeyword,\n  type CssLength,\n  space,\n  type UiSpaceName,\n} from './css-values.js';\nimport type { Sides } from './divider-sides.js';\nimport {\n  type HorizontalAlignment,\n  horizontalAlignment,\n  type VerticalAlignment,\n  verticalAlignment,\n} from './flex-alignment.js';\nimport type { KerfUiContent } from './semantic-content.js';\n\nconst spaceNames: readonly UiSpaceName[] = [\n  'none',\n  '2xs',\n  'xs',\n  's',\n  'm',\n  'l',\n  'xl',\n];\n\nexport interface RowProps {\n  children?: KerfUiContent;\n  /** Horizontal distribution. Defaults to left. */\n  hAlign?: HorizontalAlignment;\n  /** Vertical alignment and wrapped-line distribution. Defaults to full. */\n  vAlign?: VerticalAlignment;\n  /** A named UI spacing token or typed CSS length. Defaults to xs. */\n  gap?: UiSpaceName | CssLength;\n  /** Allow this row to grow/shrink, use a keyword, or supply a typed CSS flex shorthand. */\n  flex?: boolean | CssFlexKeyword | CssFlex;\n  /** Allow children to wrap onto additional lines. */\n  wrap?: boolean;\n  /** Physical sides that receive the standard 17px text inset. */\n  textInsets?: Sides;\n  /** Physical sides that receive the standard 8px control inset. Text insets win on overlap. */\n  controlInsets?: Sides;\n  className?: string;\n}\n\n/** A horizontal flex row with explicit physical-axis alignment and spacing. */\nexport function Row({\n  children,\n  hAlign = 'left',\n  vAlign = 'full',\n  gap = 'xs',\n  flex = false,\n  wrap = false,\n  textInsets = '',\n  controlInsets = '',\n  className = '',\n}: RowProps) {\n  const gapValue = spaceNames.includes(gap as UiSpaceName)\n    ? space(gap as UiSpaceName)\n    : gap;\n  const flexValue = flex === true ? '1 1 auto' : flex || undefined;\n  const style = [\n    `--_kui-row-gap:${gapValue}`,\n    flexValue ? `--_kui-row-flex:${flexValue}` : '',\n  ]\n    .filter(Boolean)\n    .join(';');\n\n  return (\n    <div\n      class={`kui-row ${className}`.trim()}\n      data-component=\"row\"\n      data-h-align={horizontalAlignment(hAlign)}\n      data-v-align={verticalAlignment(vAlign)}\n      data-flex={String(Boolean(flex))}\n      data-wrap={String(wrap)}\n      text-insets={textInsets || undefined}\n      control-insets={controlInsets || undefined}\n      style={style}\n    >\n      {children}\n    </div>\n  );\n}\n\nexport type {\n  CssFlex,\n  CssFlexKeyword,\n  CssLength,\n  UiSpaceName,\n} from './css-values.js';\nexport type { Sides } from './divider-sides.js';\nexport type {\n  HorizontalAlignment,\n  VerticalAlignment,\n} from './flex-alignment.js';\n"]}

package/dist/chunk-TNXDXSGP.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/list.tsx"],"names":[],"mappings":";;;;AAgBA,IAAM,UAAA,GAAqC;AAAA,EACzC,MAAA;AAAA,EACA,KAAA;AAAA,EACA,IAAA;AAAA,EACA,GAAA;AAAA,EACA,GAAA;AAAA,EACA,GAAA;AAAA,EACA;AACF,CAAA;AAwBO,SAAS,IAAA,CAAK;AAAA,EACnB,QAAA;AAAA,EACA,GAAA,GAAM,KAAA;AAAA,EACN,IAAA,GAAO,KAAA;AAAA,EACP,MAAA,GAAS,MAAA;AAAA,EACT,MAAA,GAAS,KAAA;AAAA,EACT,UAAA,GAAa,KAAA;AAAA,EACb,YAAA,GAAe,EAAA;AAAA,EACf,UAAA,GAAa,EAAA;AAAA,EACb,aAAA,GAAgB,EAAA;AAAA,EAChB,SAAA,GAAY;AACd,CAAA,EAAc;AACZ,EAAA,MAAM,QAAA,GACJ,GAAA,KAAQ,IAAA,GACJ,qBAAA,GACA,UAAA,CAAW,QAAA,CAAS,GAAkB,CAAA,GACpC,KAAA,CAAM,GAAkB,CAAA,GACxB,GAAA,IAAO,MAAA;AACf,EAAA,MAAM,SAAA,GAAY,IAAA,KAAS,IAAA,GAAO,UAAA,GAAa,IAAA,IAAQ,MAAA;AACvD,EAAA,MAAM,KAAA,GAAQ;AAAA,IACZ,QAAA,GAAW,CAAA,gBAAA,EAAmB,QAAQ,CAAA,CAAA,GAAK,EAAA;AAAA,IAC3C,SAAA,GAAY,CAAA,iBAAA,EAAoB,SAAS,CAAA,CAAA,GAAK;AAAA,GAChD,CACG,MAAA,CAAO,OAAO,CAAA,CACd,KAAK,GAAG,CAAA;AAEX,EAAA,uBACE,GAAA;AAAA,IAAC,KAAA;AAAA,IAAA;AAAA,MACC,KAAA,EAAO,CAAA,SAAA,EAAY,SAAS,CAAA,CAAA,CAAG,IAAA,EAAK;AAAA,MACpC,gBAAA,EAAe,MAAA;AAAA,MACf,UAAA,EAAU,MAAA,CAAO,OAAA,CAAQ,GAAG,CAAC,CAAA;AAAA,MAC7B,WAAA,EAAW,MAAA,CAAO,OAAA,CAAQ,IAAI,CAAC,CAAA;AAAA,MAC/B,cAAA,EAAc,oBAAoB,MAAM,CAAA;AAAA,MACxC,cAAA,EAAc,kBAAkB,MAAM,CAAA;AAAA,MACtC,iBAAA,EAAiB,OAAO,UAAU,CAAA;AAAA,MAClC,iBAAe,YAAA,IAAgB,MAAA;AAAA,MAC/B,eAAa,UAAA,IAAc,MAAA;AAAA,MAC3B,kBAAgB,aAAA,IAAiB,MAAA;AAAA,MACjC,OAAO,KAAA,IAAS,MAAA;AAAA,MAEf;AAAA;AAAA,GACH;AAEJ","file":"chunk-TNXDXSGP.js","sourcesContent":["import {\n  type CssFlex,\n  type CssFlexKeyword,\n  type CssLength,\n  space,\n  type UiSpaceName,\n} from './css-values.js';\nimport type { DividerSides, Sides } from './divider-sides.js';\nimport {\n  type HorizontalAlignment,\n  horizontalAlignment,\n  type VerticalAlignment,\n  verticalAlignment,\n} from './flex-alignment.js';\nimport type { KerfUiContent } from './semantic-content.js';\n\nconst spaceNames: readonly UiSpaceName[] = [\n  'none',\n  '2xs',\n  'xs',\n  's',\n  'm',\n  'l',\n  'xl',\n];\n\nexport interface ListProps {\n  children?: KerfUiContent;\n  /** Use the standard item gap, a named UI spacing token, or a typed CSS length. Defaults to no gap. */\n  gap?: boolean | UiSpaceName | CssLength;\n  /** Allow this list to grow/shrink, use a keyword, or supply a typed CSS flex shorthand. */\n  flex?: boolean | CssFlexKeyword | CssFlex;\n  /** Horizontal alignment. Defaults to full to preserve stretch-aligned list children. */\n  hAlign?: HorizontalAlignment;\n  /** Vertical distribution. Defaults to top. */\n  vAlign?: VerticalAlignment;\n  /** Own vertical scrolling and overscroll containment. */\n  scrollable?: boolean;\n  /** Physical divider edges in canonical top/right/bottom/left order. */\n  dividerSides?: DividerSides;\n  /** Physical sides that receive the standard 17px text inset. */\n  textInsets?: Sides;\n  /** Physical sides that receive the standard 8px control inset. Text insets win on overlap. */\n  controlInsets?: Sides;\n  className?: string;\n}\n\n/** A stretch-aligned vertical stack with optional gap, flex, scroll, and dividers. */\nexport function List({\n  children,\n  gap = false,\n  flex = false,\n  hAlign = 'full',\n  vAlign = 'top',\n  scrollable = false,\n  dividerSides = '',\n  textInsets = '',\n  controlInsets = '',\n  className = '',\n}: ListProps) {\n  const gapValue =\n    gap === true\n      ? 'var(--kui-list-gap)'\n      : spaceNames.includes(gap as UiSpaceName)\n        ? space(gap as UiSpaceName)\n        : gap || undefined;\n  const flexValue = flex === true ? '1 1 auto' : flex || undefined;\n  const style = [\n    gapValue ? `--_kui-list-gap:${gapValue}` : '',\n    flexValue ? `--_kui-list-flex:${flexValue}` : '',\n  ]\n    .filter(Boolean)\n    .join(';');\n\n  return (\n    <div\n      class={`kui-list ${className}`.trim()}\n      data-component=\"list\"\n      data-gap={String(Boolean(gap))}\n      data-flex={String(Boolean(flex))}\n      data-h-align={horizontalAlignment(hAlign)}\n      data-v-align={verticalAlignment(vAlign)}\n      data-scrollable={String(scrollable)}\n      divider-sides={dividerSides || undefined}\n      text-insets={textInsets || undefined}\n      control-insets={controlInsets || undefined}\n      style={style || undefined}\n    >\n      {children}\n    </div>\n  );\n}\n\nexport type {\n  CssFlex,\n  CssFlexKeyword,\n  CssLength,\n  UiSpaceName,\n} from './css-values.js';\nexport type { DividerSides, Sides } from './divider-sides.js';\nexport type {\n  HorizontalAlignment,\n  VerticalAlignment,\n} from './flex-alignment.js';\n"]}