@kerfjs/ui 5.0.0-beta.50 → 5.0.0-beta.52

package/ai/component-catalog.schema.json

@@ -92,7 +92,27 @@
     "wiring": {
       "type": "object",
       "required": ["export", "import", "required"],
-      "properties": { "export": { "type": "string" }, "import": { "type": "string" }, "required": { "type": "boolean" }, "reason": { "type": "string" } },
+      "properties": {
+        "export": { "type": "string" },
+        "import": { "type": "string" },
+        "required": { "type": "boolean" },
+        "reason": { "type": "string" },
+        "stateAttributes": {
+          "description": "Wiring-owned state attributes: data-* attributes this helper writes at runtime on the entry's elements. The application must not render, remove, or treat them as its own state.",
+          "type": "array",
+          "items": { "$ref": "#/$defs/stateAttribute" }
+        }
+      },
+      "additionalProperties": false
+    },
+    "stateAttribute": {
+      "type": "object",
+      "required": ["name", "on", "meaning"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1, "pattern": "^data-[a-z0-9]+(-[a-z0-9]+)*$" },
+        "on": { "type": "string", "minLength": 1, "description": "The element that carries it: a public class, or the element passed to the helper." },
+        "meaning": { "type": "string", "minLength": 1, "description": "What its presence or value means." }
+      },
       "additionalProperties": false
     },
     "delivery": {

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.50` and `kerfjs@5.0.0-beta.50`. 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.52` and `kerfjs@5.0.0-beta.52`. 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`
 
@@ -10,6 +10,7 @@ declare const cssLengthBrand: unique symbol;
 declare const cssLengthExpressionBrand: unique symbol;
 declare const cssFlexBrand: unique symbol;
 declare const cssColorBrand: unique symbol;
+declare const cssForegroundColorBrand: unique symbol;
 /**
  * A complete typed CSS value minted by a property-specific Kerf UI builder.
  *
@@ -42,6 +43,18 @@ type CssFlex = CssValue & {
 type CssColor = CssValue & {
     readonly [cssColorBrand]: 'CssColor';
 };
+/**
+ * A complete CSS color meant to paint a foreground: text or an icon drawn over
+ * a surface. Mint it with {@link uiColor} and a foreground token name
+ * ({@link UiForegroundColorName}) or with {@link foregroundColorVar}. It is a
+ * {@link CssColor}, but a plain `CssColor` is not a foreground color: fill,
+ * border, and surface tokens (including the `success` / `warning` / `danger` /
+ * `pop` fill aliases) are pale backgrounds that leave a foreground nearly
+ * invisible.
+ */
+type CssForegroundColor = CssColor & {
+    readonly [cssForegroundColorBrand]: 'CssForegroundColor';
+};
 type CssFlexKeyword = 'none' | 'auto' | 'initial';
 type CssFlexBasis = CssLength | 'auto' | 'content' | 'min-content' | 'max-content' | 'fit-content';
 type CssSizeKeyword = 'auto' | 'min-content' | 'max-content' | 'fit-content';
@@ -50,12 +63,21 @@ type CssSize = CssLength | CssSizeKeyword;
 declare const uiColorNames: readonly ["accent", "accent-text", "border", "border-quiet", "brand-border-loud", "brand-border-normal", "brand-border-quiet", "brand-fill-loud", "brand-fill-normal", "brand-fill-quiet", "brand-on-fill", "brand-on-loud", "brand-on-normal", "brand-on-quiet", "danger", "danger-border-loud", "danger-border-normal", "danger-border-quiet", "danger-fill-loud", "danger-fill-normal", "danger-fill-quiet", "danger-on-loud", "danger-on-normal", "danger-on-quiet", "danger-text", "neutral-border-loud", "neutral-border-normal", "neutral-border-quiet", "neutral-fill-loud", "neutral-fill-normal", "neutral-fill-quiet", "neutral-on-loud", "neutral-on-normal", "neutral-on-quiet", "pop", "pop-border-loud", "pop-border-normal", "pop-border-quiet", "pop-fill-loud", "pop-fill-normal", "pop-fill-quiet", "pop-on-fill", "pop-on-loud", "pop-on-normal", "pop-on-quiet", "pop-text", "success", "success-border-loud", "success-border-normal", "success-border-quiet", "success-fill-loud", "success-fill-normal", "success-fill-quiet", "success-on-fill", "success-on-loud", "success-on-normal", "success-on-quiet", "success-text", "surface", "surface-lowered", "surface-raised", "text", "text-link", "text-quiet", "warning", "warning-border-loud", "warning-border-normal", "warning-border-quiet", "warning-fill-loud", "warning-fill-normal", "warning-fill-quiet", "warning-on-fill", "warning-on-loud", "warning-on-normal", "warning-on-quiet", "warning-text"];
 /** Names of the public `--kui-color-*` semantic tokens. */
 type UiColorName = (typeof uiColorNames)[number];
+/**
+ * The semantic tokens that paint a foreground: the `*-on-*` roles, the text
+ * roles, and their `*-text` compatibility aliases. The bare `success`,
+ * `warning`, `danger`, `pop`, and `accent` aliases are quiet fills, not
+ * foregrounds.
+ */
+type UiForegroundColorName = Extract<UiColorName, `${string}-on-${string}` | `${string}-text` | 'text' | 'text-quiet' | 'text-link'>;
 /** Kerf UI's complete spacing-token vocabulary. `s` and `xl` are exceptions. */
 type UiSpaceName = 'none' | '2xs' | 'xs' | 's' | 'm' | 'l' | 'xl';
 /** Create a complete pixel length. */
 declare function px(value: number): CssLength;
 /** Create a complete root-font-relative length. */
 declare function rem(value: number): CssLength;
+/** Converts a pixel value into rem units by dividing by 16. */
+declare function remify(value: number): CssLength;
 /** Create a complete current-font-relative length. */
 declare function em(value: number): CssLength;
 /** Create a complete percentage length. */
@@ -74,12 +96,28 @@ declare function plus(first: CssLength, second: CssLength, ...rest: readonly Css
 declare function calc(expression: CssLengthExpression): CssLength;
 /** Build a complete, structured CSS flex shorthand. */
 declare function flex(grow: number, shrink?: number, basis?: CssFlexBasis): CssFlex;
-/** Resolve a public Kerf UI semantic color token. */
-declare function uiColor(name: UiColorName): CssColor;
+/**
+ * The brand {@link uiColor} returns for a token name: a
+ * {@link CssForegroundColor} for a foreground token, otherwise a plain
+ * {@link CssColor}.
+ */
+type UiColor<Name extends UiColorName> = Name extends UiForegroundColorName ? CssForegroundColor : CssColor;
+/**
+ * Resolve a public Kerf UI semantic color token. A foreground token name
+ * (`success-on-quiet`, `text-quiet`, …) returns a {@link CssForegroundColor};
+ * any other token returns a plain {@link CssColor}.
+ */
+declare function uiColor<Name extends UiColorName>(name: Name): UiColor<Name>;
 /** Reference an application-owned custom property whose contract is a color. */
 declare function colorVar(name: `--${string}`, fallback?: CssColor): CssColor;
+/**
+ * Reference an application-owned custom property whose contract is a
+ * foreground color (text or an icon over a surface). Use it where a prop
+ * accepts only {@link CssForegroundColor}, such as `SelectChoice.color`.
+ */
+declare function foregroundColorVar(name: `--${string}`, fallback?: CssForegroundColor): CssForegroundColor;
 
-export { type CssColor, type CssFlex, type CssFlexBasis, type CssFlexKeyword, type CssLength, type CssLengthExpression, type CssSize, type CssSizeKeyword, type CssValue, type UiColorName, type UiSpaceName, calc, colorVar, em, flex, lengthVar, pct, plus, px, rem, space, uiColor };
+export { type CssColor, type CssFlex, type CssFlexBasis, type CssFlexKeyword, type CssForegroundColor, type CssLength, type CssLengthExpression, type CssSize, type CssSizeKeyword, type CssValue, type UiColor, type UiColorName, type UiForegroundColorName, type UiSpaceName, calc, colorVar, em, flex, foregroundColorVar, lengthVar, pct, plus, px, rem, remify, space, uiColor };
 ```
 
 ## `@kerfjs/ui/disclosure-arrow`
@@ -108,6 +146,7 @@ export { DisclosureArrow, type DisclosureArrowProps, type DisclosureDirection };
 ```ts
 import * as kerfjs from 'kerfjs';
 import { D as DividerSides } from './divider-sides-BzB6rphT.js';
+import { PaneSeparatorSide } from './pane.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
 interface ToolbarProps {
@@ -119,15 +158,35 @@ interface ToolbarProps {
     dividerSides?: DividerSides;
     /** Horizontal treatment of the center zone. Defaults to centered content. */
     centerAlign?: 'center' | 'stretch';
-    /** Component-owned responsive layout; applications choose the policy rather than restyling toolbar internals. */
-    responsive?: 'none' | 'stack' | 'center-priority';
+    /**
+     * Component-owned responsive layout; applications choose the policy rather
+     * than restyling toolbar internals. Under every policy the trailing zone
+     * wraps its groups instead of clipping an action.
+     * - `none` keeps one row; the leading identity truncates first.
+     * - `stack` stacks the zones at `responsiveAt`, wrapping stacked control
+     *   groups onto further rows.
+     * - `wrap` keeps one row while every zone fits at its natural width, and
+     *   otherwise moves the trailing zone below a whole leading identity.
+     * - `center-priority` gives an expanded center control the full row.
+     */
+    responsive?: 'none' | 'stack' | 'wrap' | 'center-priority';
     /** Container width at which `responsive="stack"` activates. */
     responsiveAt?: 'compact' | 'narrow';
+    /**
+     * Screen edges this toolbar claims for device safe-area compensation, for an
+     * app bar or bottom bar that sits directly at a screen edge rather than in a
+     * Pane header or footer. Each listed side pads by the inset its surrounding
+     * layout reports through `--kui-edge-inset-*`, or the full device inset when
+     * nothing routes that edge, while the toolbar's box and dividers paint
+     * through. Omitted, the toolbar pads only the inline edges an owner such as
+     * a Pane header hands it, and never a block edge.
+     */
+    safeAreaEdges?: readonly PaneSeparatorSide[];
     className?: string;
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
 }
-declare function Toolbar({ leading, center, trailing, label, dividerSides, centerAlign, responsive, responsiveAt, className, slot, }: ToolbarProps): kerfjs.SafeHtml;
+declare function Toolbar({ leading, center, trailing, label, dividerSides, centerAlign, responsive, responsiveAt, safeAreaEdges, className, slot, }: ToolbarProps): kerfjs.SafeHtml;
 
 export { DividerSides, Toolbar, type ToolbarProps };
 ```
@@ -389,12 +448,29 @@ import { H as HorizontalAlignment, L as ListVerticalAlignment } from './flex-ali
 export { V as VerticalAlignment } from './flex-alignment-4ms8ZbV8.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
+type ListRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+    'data-component'?: never;
+    'data-gap'?: never;
+    'data-flex'?: never;
+    'data-fill'?: never;
+    'data-h-align'?: never;
+    'data-v-align'?: never;
+    'data-scrollable'?: never;
+    'data-text-insets'?: never;
+    'data-control-insets'?: never;
+}>;
 interface ListProps {
     children?: KerfUiContent;
     /** Use the standard item gap, a named UI spacing token, or a typed CSS length. Defaults to no gap. */
     gap?: boolean | UiSpaceName | CssLength;
     /** Allow this list to grow/shrink, use a keyword, or supply a typed CSS flex shorthand. */
     flex?: boolean | CssFlexKeyword | CssFlex;
+    /**
+     * Fill the height of a parent with a definite height, such as an app root or
+     * a fixed-height frame, when this list is that parent's layout root. Inside a
+     * flex layout use `flex` instead. Defaults to false.
+     */
+    fill?: boolean;
     /** Horizontal alignment. Defaults to full to preserve stretch-aligned list children. */
     hAlign?: HorizontalAlignment;
     /** Vertical distribution. Defaults to top. */
@@ -408,11 +484,13 @@ interface ListProps {
     /** Physical sides that receive the standard 8px control inset. Text insets win on overlap. */
     controlInsets?: Sides;
     className?: string;
+    /** Safe `data-*` metadata; List-owned structural attributes remain protected. */
+    rootAttributes?: ListRootAttributes;
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
 }
-/** A stretch-aligned vertical stack with optional gap, flex, scroll, and dividers. */
-declare function List({ children, gap, flex, hAlign, vAlign, scrollable, dividerSides, textInsets, controlInsets, className, slot, }: ListProps): kerfjs.SafeHtml;
+/** A stretch-aligned vertical stack with optional gap, flex, fill, scroll, and dividers. */
+declare function List({ children, gap, flex, fill, hAlign, vAlign, scrollable, dividerSides, textInsets, controlInsets, className, rootAttributes, slot, }: ListProps): kerfjs.SafeHtml;
 
 export { CssFlex, CssFlexKeyword, CssLength, DividerSides, HorizontalAlignment, List, type ListProps, ListVerticalAlignment, Sides, UiSpaceName };
 ```
@@ -668,11 +746,20 @@ interface AppTabProps {
     className?: string;
     /** Render as an unanimated loading skeleton, disabling select/close and dragging. */
     placeholder?: boolean;
+    /**
+     * Dormant but named: the tab is known and still opening. Keeps `name`
+     * visible in the quiet text color and as the tab's accessible name, shows
+     * `trailing` (for example a `LoadingSpinner`), and disables select, close,
+     * and dragging with `aria-busy`, like `placeholder`. Same pill geometry as
+     * the live tab, so swapping it in place does not shift the bar.
+     * `placeholder` wins when both are set.
+     */
+    pending?: boolean;
     rootAttributes?: AppTabRootAttributes;
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
 }
-declare function AppTab({ id, name, selected, closable, draggable, leading, trailing, presentation, size, labelMaxWidth, closeIcon, selectAction, closeAction, className, placeholder, rootAttributes, slot, }: AppTabProps): SafeHtml;
+declare function AppTab({ id, name, selected, closable, draggable, leading, trailing, presentation, size, labelMaxWidth, closeIcon, selectAction, closeAction, className, placeholder, pending, rootAttributes, slot, }: AppTabProps): SafeHtml;
 
 export { AppTab, type AppTabPresentation, type AppTabProps, type AppTabSize };
 ```
@@ -887,7 +974,10 @@ export { SplitView, type SplitViewProps, type SplitViewResizable };
 import * as kerfjs from 'kerfjs';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
-/** Logical sides that can show a {@link Pane} separator. */
+/**
+ * Logical pane sides: where a {@link Pane} can show a separator and where it can
+ * compensate for a device safe-area inset.
+ */
 type PaneSeparatorSide = 'block-start' | 'block-end' | 'inline-start' | 'inline-end';
 /** Semantic root elements supported by {@link Pane}. */
 type PaneElement = 'article' | 'aside' | 'div' | 'main' | 'section';
@@ -899,6 +989,10 @@ type PaneRootAttributes = Readonly<Record<`data-${string}`, string | undefined>
     'data-separator-block-end'?: never;
     'data-separator-inline-start'?: never;
     'data-separator-inline-end'?: never;
+    'data-safe-area-block-start'?: never;
+    'data-safe-area-block-end'?: never;
+    'data-safe-area-inline-start'?: never;
+    'data-safe-area-inline-end'?: never;
 }>;
 interface PaneProps {
     /** Optional fixed chrome above the scrolling content, arranged vertically. */
@@ -913,6 +1007,14 @@ interface PaneProps {
     contentElement?: PaneContentElement;
     /** Independent logical-edge separator lines. Defaults to none. */
     separators?: readonly PaneSeparatorSide[];
+    /**
+     * Sides on which the pane may compensate for a device safe-area inset.
+     * Defaults to every side: the pane pads its slots for each side that still
+     * reaches an unsafe screen edge, as its surrounding layout reports, while its
+     * background and separators paint through. List only the sides an app-owned
+     * layout places at a screen edge, or pass `[]` to opt out.
+     */
+    safeAreaEdges?: readonly PaneSeparatorSide[];
     id?: string;
     /** Accessible name for a landmark root such as `aside` or `main`. */
     label?: string;
@@ -933,7 +1035,7 @@ interface PaneProps {
  * each logical edge, so the same component works as a sidebar, main area,
  * inspector, or dialog column.
  */
-declare function Pane({ header, children, footer, element, contentElement, separators, id, label, contentLabel, className, headerClassName, contentClassName, footerClassName, rootAttributes, slot, }: PaneProps): kerfjs.SafeHtml;
+declare function Pane({ header, children, footer, element, contentElement, separators, safeAreaEdges, id, label, contentLabel, className, headerClassName, contentClassName, footerClassName, rootAttributes, slot, }: PaneProps): kerfjs.SafeHtml;
 
 export { Pane, type PaneContentElement, type PaneElement, type PaneProps, type PaneSeparatorSide };
 ```
@@ -1066,7 +1168,7 @@ interface CollapsiblePanelProps {
  * underneath the transform transition. The app owns the `collapsed` signal;
  * pair it with `wireSidebar` for the toggle, focus, compact-overlay, keyboard,
  * and persistence semantics, and with `CollapsiblePanelToggle` for the standard
- * affordance. See `docs/24-collapsible-panel.md`.
+ * affordance. See `ui/docs/collapsible-panel.md` and `docs/23-app-layouts.md`.
  */
 declare function CollapsiblePanel({ id, side, collapsed, size, label, children, separator, collapseMotion, contentOverflow, presentation, restoreControl, restorePosition, className, }: CollapsiblePanelProps): SafeHtml;
 
@@ -1092,9 +1194,18 @@ interface WireSidebarPanel {
     collapsed: Signal<boolean>;
     /** `data-action` value the panel's toggle button(s) carry. */
     toggleAction: string;
-    /** When set, the collapsed state is loaded from and saved to `storage` under
-     *  this key (a persistence hook), so the panel remembers its state. */
+    /** When set, the panel's inline collapsed state is loaded from and saved to
+     *  `storage` under this key (a persistence hook), so the panel remembers the
+     *  user's inline choice. A compact overlay's open/closed state is transient
+     *  and is never persisted. */
     storageKey?: string;
+    /** The panel's inline (non-compact) collapsed state when `storage` holds no
+     *  choice for it; wire-up seeds the signal with it. Defaults to the signal's
+     *  own value. Set it when the app seeds the signal from the device class
+     *  (`signal(device.value.compact)`) so a compact first render already starts
+     *  collapsed while a later crossing to a wide class still restores this
+     *  inline default. */
+    inlineCollapsed?: boolean;
 }
 interface WireSidebarOptions {
     panels: readonly WireSidebarPanel[];
@@ -1104,6 +1215,12 @@ interface WireSidebarOptions {
      * dismissable backdrop, Escape and backdrop-click collapse it, and focus is
      * trapped within the open panel (the ARIA dialog pattern). Without it the panel
      * is always inline.
+     *
+     * An overlay is transient and user-initiated: whenever the compact overlay
+     * presentation begins (wire-up on a compact device, or a crossing from a wide
+     * class), every panel starts collapsed so nothing blocks the page until the
+     * user opens it. The inline state is remembered and restored when the device
+     * crosses back to a wide class (and on disposal).
      */
     deviceClass?: ReadonlySignal<DeviceClass>;
     /** Compact devices either overlay the panels (default) or hide them in favor
@@ -1119,7 +1236,7 @@ interface WireSidebarOptions {
  * delegation with focus restore, focus-into on open, an optional compact overlay
  * (backdrop + Escape + focus trap) driven by {@link deviceClass}, and an optional
  * persistence hook. The app owns each `collapsed` signal and the layout; this wire
- * owns the interaction. Returns a disposer. See `docs/24-collapsible-panel.md`.
+ * owns the interaction. Returns a disposer. See `ui/docs/collapsible-panel.md` and `docs/23-app-layouts.md`.
  */
 declare function wireSidebar(root: HTMLElement, { panels, deviceClass, compactPresentation, exclusiveCompact, storage, }: WireSidebarOptions): () => void;
 
@@ -1321,15 +1438,34 @@ export { DEFAULT_BREAKPOINTS, type DeviceBreakpoints, type DeviceClass, type Dev
 ```ts
 import * as kerfjs from 'kerfjs';
 import { SafeHtml } from 'kerfjs';
-import { a as CatalogProps } from './types-CzgSrFXP.js';
-export { b as CatalogBrand, c as CatalogEntry, d as CatalogRelated, C as CatalogResource, e as CatalogSecondaryGroup, f as CatalogSection } from './types-CzgSrFXP.js';
+import { a as CatalogProps } from './types-CEsieBZi.js';
+export { b as CatalogBrand, c as CatalogEntry, d as CatalogRelated, C as CatalogResource, e as CatalogSecondaryGroup, f as CatalogSection, g as CatalogStageRootAttributes } from './types-CEsieBZi.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
 /** Controlled, stateless component-catalog shell. */
-declare function Catalog({ brand, sections, active, content, collapsed, theme, headerActions, secondarySections, sidebarFooter, status, geometryOverlay, selectAction, toggleSidebarAction, toggleThemeAction, toggleSecondaryAction, className, slot, }: CatalogProps): kerfjs.SafeHtml;
+declare function Catalog({ brand, sections, active, content, collapsed, theme, headerActions, secondarySections, sidebarFooter, status, geometryOverlay, stageRootAttributes, selectAction, toggleSidebarAction, toggleThemeAction, toggleSecondaryAction, className, slot, }: CatalogProps): kerfjs.SafeHtml;
 
 /** How a specimen aligns its visible edge with its `ListHeader` label. */
 type CatalogExampleAlign = 'glyph' | 'inline-control' | 'none';
+interface CatalogExampleViewport {
+    layout?: 'grid' | 'flex' | 'flex-column';
+    width?: 'full' | 'compact' | 'medium' | 'wide' | 'text' | 'control';
+    /** Fixed specimen height; `app` frames an application-sized recipe or layout.
+     *  A fixed height is definite, so a child that fills with `height: 100%`
+     *  (a horizontal `ResizableRegion`, say) spans the whole frame. */
+    height?: 'short' | 'reduced' | 'medium' | 'tall' | 'app';
+    /** A minimum the frame may grow past. It is not a definite height: a child
+     *  sized with `height: 100%` falls back to its content height, so use
+     *  `height` when the specimen must fill the frame. */
+    minHeight?: 'short' | 'medium';
+    frame?: 'solid' | 'dashed';
+    surface?: 'default' | 'lowered';
+    overflow?: 'hidden' | 'auto-x';
+    responsive?: 'roomy-only';
+    shadow?: boolean;
+    /** Public component custom properties applied to the specimen viewport. */
+    tokens?: Readonly<Record<`--${string}`, string>>;
+}
 type CatalogExampleRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
     'data-catalog-example'?: never;
     'data-catalog-example-stack'?: never;
@@ -1341,6 +1477,10 @@ interface CatalogExampleProps {
     label?: string;
     note?: SafeHtml | string;
     align?: CatalogExampleAlign;
+    /** Optional catalog-owned constraints for demonstrating layout components. */
+    viewport?: CatalogExampleViewport;
+    /** Replacement guidance shown when a roomy-only viewport is hidden. */
+    compactFallback?: SafeHtml | string;
     rootAttributes?: CatalogExampleRootAttributes;
     className?: string;
     children?: KerfUiContent;
@@ -1348,7 +1488,7 @@ interface CatalogExampleProps {
     slot?: string;
 }
 /** A labeled catalog specimen with optional explanatory text and alignment. */
-declare function CatalogExample({ label, note, align, rootAttributes, className, children, slot, }: CatalogExampleProps): SafeHtml;
+declare function CatalogExample({ label, note, align, viewport, compactFallback, rootAttributes, className, children, slot, }: CatalogExampleProps): SafeHtml;
 
 type CatalogExampleStackRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
     'data-catalog-example'?: never;
@@ -1368,13 +1508,13 @@ interface CatalogExampleStackProps {
 /** A vertically stacked group of catalog examples. */
 declare function CatalogExampleStack({ label, rootAttributes, className, children, slot, }: CatalogExampleStackProps): kerfjs.SafeHtml;
 
-export { Catalog, CatalogExample, type CatalogExampleAlign, type CatalogExampleProps, CatalogExampleStack, type CatalogExampleStackProps, CatalogProps };
+export { Catalog, CatalogExample, type CatalogExampleAlign, type CatalogExampleProps, CatalogExampleStack, type CatalogExampleStackProps, type CatalogExampleViewport, CatalogProps };
 ```
 
 ## `@kerfjs/ui/catalog-resources`
 
 ```ts
-import { C as CatalogResource } from './types-CzgSrFXP.js';
+import { C as CatalogResource } from './types-CEsieBZi.js';
 import './semantic-content-BbzjvSu9.js';
 import 'kerfjs';
 
@@ -1515,7 +1655,7 @@ export { SegmentedControl, type SegmentedControlAppearance, type SegmentedContro
 
 ```ts
 import { SafeHtml } from 'kerfjs';
-import { CssColor } from './css-values.js';
+import { CssForegroundColor } from './css-values.js';
 import { LucideNode } from './lucide-icon.js';
 import 'lucide';
 
@@ -1524,9 +1664,19 @@ interface SelectChoice<Value extends string = string> {
     label: string;
     icon?: LucideNode;
     iconName?: string;
-    /** Typed semantic or application-owned color for the optional icon. */
-    color?: CssColor;
+    /**
+     * Foreground color for the optional icon: a semantic foreground token such
+     * as `uiColor('success-on-quiet')`, or an application-owned
+     * `foregroundColorVar('--app-icon-color')`. Fill tokens such as
+     * `uiColor('success')` are pale background tints and do not type-check.
+     */
+    color?: CssForegroundColor;
     group?: string;
+    /**
+     * Draw a divider between this choice and the previous choice in the same
+     * list. A group boundary is already a separator, so the first choice of a
+     * group (or of the whole menu) never draws a second one.
+     */
     separatorBefore?: boolean;
 }
 type SelectAccessibleName = {
@@ -1653,6 +1803,10 @@ interface SkeletonProps {
     radius?: CssLength;
     /** Render this many stacked lines (the last one shorter), for multi-line text. */
     lines?: number;
+    /** Lay the block out as `display: block` instead of the default
+     *  `inline-block`, so it takes no text line of its own: no baseline gap
+     *  below it, and it centers like an icon in a slot. Defaults to `false`. */
+    block?: boolean;
     /** Accessible label. Omit to keep the block decorative (`aria-hidden`). */
     label?: string;
     className?: string;
@@ -1665,7 +1819,7 @@ interface SkeletonProps {
  * `placeholder` prop. Decorative by default (`aria-hidden`); pass `label` to
  * announce it. Sizes to its slot unless `width`/`height` are given.
  */
-declare function Skeleton({ width, height, radius, lines, label, className, slot, }: SkeletonProps): kerfjs.SafeHtml;
+declare function Skeleton({ width, height, radius, lines, block, label, className, slot, }: SkeletonProps): kerfjs.SafeHtml;
 
 export { Skeleton, type SkeletonProps };
 ```
@@ -2051,14 +2205,14 @@ import * as kerfjs from 'kerfjs';
 import { KerfBaseAttrs } from 'kerfjs/jsx-runtime';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
-type TextVariant = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p';
+type TextVariant = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p' | 'span';
 type TextTone = 'default' | 'quiet' | 'danger';
 type TextSize = 'default' | 'compact';
 type TextFont = 'default' | 'monospace';
 type TextBorder = 'transparent' | 'none';
 type TextContent = KerfUiContent | string | number | readonly TextContent[];
 type TextProps = Omit<KerfBaseAttrs, 'children' | 'class' | 'className'> & {
-    /** Native heading or paragraph element to render. Defaults to `p`. */
+    /** Native heading, paragraph, or inline span element to render. Defaults to `p`. */
     variant?: TextVariant;
     /** Semantic foreground treatment. Defaults to the inherited foreground. */
     tone?: TextTone;
@@ -2073,7 +2227,8 @@ type TextProps = Omit<KerfBaseAttrs, 'children' | 'class' | 'className'> & {
     className?: string;
 };
 /**
- * Semantic heading or paragraph text with the standard content-item padding.
+ * Semantic heading, paragraph, or inline text. Block variants use the standard
+ * content-item padding; `span` adds no box geometry.
  * All ordinary native heading/paragraph attributes pass through to the element.
  */
 declare function Text({ variant: Variant, tone, size, font, border, children, class: classValue, className, ...attributes }: TextProps): kerfjs.SafeHtml;
@@ -2090,6 +2245,16 @@ import { S as Sides } from './divider-sides-BzB6rphT.js';
 import { H as HorizontalAlignment, V as VerticalAlignment } from './flex-alignment-4ms8ZbV8.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
+type RowRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+    'data-component'?: never;
+    'data-h-align'?: never;
+    'data-v-align'?: never;
+    'data-flex'?: never;
+    'data-fill'?: never;
+    'data-wrap'?: never;
+    'data-text-insets'?: never;
+    'data-control-insets'?: never;
+}>;
 interface RowProps {
     children?: KerfUiContent;
     /** Horizontal distribution. Defaults to left. */
@@ -2100,6 +2265,12 @@ interface RowProps {
     gap?: UiSpaceName | CssLength;
     /** Allow this row to grow/shrink, use a keyword, or supply a typed CSS flex shorthand. */
     flex?: boolean | CssFlexKeyword | CssFlex;
+    /**
+     * Fill the height of a parent with a definite height, such as an app root or
+     * a fixed-height frame, when this row is that parent's layout root. Inside a
+     * flex layout use `flex` instead. Defaults to false.
+     */
+    fill?: boolean;
     /** Allow children to wrap onto additional lines. */
     wrap?: boolean;
     /** Physical sides that receive the standard 17px text inset. */
@@ -2107,11 +2278,13 @@ interface RowProps {
     /** Physical sides that receive the standard 8px control inset. Text insets win on overlap. */
     controlInsets?: Sides;
     className?: string;
+    /** Safe `data-*` metadata; Row-owned structural attributes remain protected. */
+    rootAttributes?: RowRootAttributes;
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
 }
 /** A horizontal flex row with explicit physical-axis alignment and spacing. */
-declare function Row({ children, hAlign, vAlign, gap, flex, wrap, textInsets, controlInsets, className, slot, }: RowProps): kerfjs.SafeHtml;
+declare function Row({ children, hAlign, vAlign, gap, flex, fill, wrap, textInsets, controlInsets, className, rootAttributes, slot, }: RowProps): kerfjs.SafeHtml;
 
 export { CssFlex, CssFlexKeyword, CssLength, HorizontalAlignment, Row, type RowProps, Sides, UiSpaceName, VerticalAlignment };
 ```
@@ -2123,6 +2296,12 @@ import * as kerfjs from 'kerfjs';
 import { UiSpaceName, CssLength, CssFlexKeyword, CssFlex } from './css-values.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
+type GridRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+    'data-component'?: never;
+    'data-columns'?: never;
+    'data-flex'?: never;
+    'data-fill'?: never;
+}>;
 interface GridProps {
     children?: KerfUiContent;
     /** Number of equal-width columns. Must be a positive safe integer. */
@@ -2131,12 +2310,20 @@ interface GridProps {
     gap?: UiSpaceName | CssLength;
     /** Allow this grid to grow/shrink, use a keyword, or supply a typed CSS flex shorthand. */
     flex?: boolean | CssFlexKeyword | CssFlex;
+    /**
+     * Fill the height of a parent with a definite height, such as an app root or
+     * a fixed-height frame, when this grid is that parent's layout root. Inside a
+     * flex layout use `flex` instead. Defaults to false.
+     */
+    fill?: boolean;
     className?: string;
+    /** Safe `data-*` metadata; Grid-owned structural attributes remain protected. */
+    rootAttributes?: GridRootAttributes;
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
 }
 /** A fixed-count grid whose columns share the available width equally. */
-declare function Grid({ children, columns, gap, flex, className, slot, }: GridProps): kerfjs.SafeHtml;
+declare function Grid({ children, columns, gap, flex, fill, className, rootAttributes, slot, }: GridProps): kerfjs.SafeHtml;
 
 export { CssFlex, CssFlexKeyword, CssLength, Grid, type GridProps, UiSpaceName };
 ```