@kerfjs/ui 5.0.0-beta.4 → 5.0.0-beta.7

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.4` and `kerfjs@5.0.0-beta.4`. 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.7` and `kerfjs@5.0.0-beta.7`. This bounded reference covers only APIs used by the seven-task corpus. It is interface evidence, not an implementation or runtime guarantee.
 
 ## `@kerfjs/ui/disclosure-arrow`
 
@@ -44,13 +44,17 @@ export { Toolbar, type ToolbarProps };
 ```ts
 import * as kerfjs from 'kerfjs';
 
-type ToolbarTextSize = 'large' | 'default' | 'small';
+type ToolbarTextSize = 'xlarge' | 'large' | 'default' | 'small';
 interface ToolbarTextProps {
     text: string;
     size?: ToolbarTextSize;
     className?: string;
+    /** Optional id, e.g. so a dialog can reference the title via aria-labelledby. */
+    id?: string;
+    /** Render the text as an unanimated loading skeleton instead of its value. */
+    placeholder?: boolean;
 }
-declare function ToolbarText({ text, size, className }: ToolbarTextProps): kerfjs.SafeHtml;
+declare function ToolbarText({ text, size, className, id, placeholder }: ToolbarTextProps): kerfjs.SafeHtml;
 
 export { ToolbarText, type ToolbarTextProps, type ToolbarTextSize };
 ```
@@ -103,6 +107,8 @@ interface MenuHeaderBaseProps {
     disabledReason?: string;
     expanded?: boolean;
     toggle?: boolean;
+    /** Render as an unanimated loading skeleton: keep the label and action affordance, disable interaction. */
+    placeholder?: boolean;
     rootAttributes?: MenuHeaderRootAttributes;
     triggerAttributes?: MenuHeaderTriggerAttributes;
 }
@@ -116,7 +122,7 @@ type MenuHeaderIndicatorProps = {
     badge?: SafeHtml;
 };
 type MenuHeaderProps = MenuHeaderBaseProps & MenuHeaderIndicatorProps;
-declare function MenuHeader({ label, count, countLabel, badge, action, actionLabel, actionIcon, actionDisabled, disabledReason, expanded, toggle, rootAttributes, triggerAttributes }: MenuHeaderProps): SafeHtml;
+declare function MenuHeader({ label, count, countLabel, badge, action, actionLabel, actionIcon, actionDisabled, disabledReason, expanded, toggle, placeholder, rootAttributes, triggerAttributes }: MenuHeaderProps): SafeHtml;
 
 export { MenuHeader, type MenuHeaderProps };
 ```
@@ -160,6 +166,8 @@ interface MenuActionRowProps {
     state?: string;
     disabled?: boolean;
     tabIndex?: number;
+    /** Render as an unanimated loading skeleton, disabling both actions. */
+    placeholder?: boolean;
     trailingAction: string;
     trailingActionLabel: string;
     /** Decorative dormant content for the trailing button. Must not contain interactive descendants. */
@@ -171,7 +179,7 @@ interface MenuActionRowProps {
     rootAttributes?: MenuActionRowRootAttributes;
     trailingActionAttributes?: MenuActionRowTrailingAttributes;
 }
-declare function MenuActionRow({ label, icon, action, itemId, selected, pressed, accessibleLabel, title, multiline, state, disabled, tabIndex, trailingAction, trailingActionLabel, trailingActionIcon, trailingActionDisabled, trailingActionTitle, className, style, rootAttributes, trailingActionAttributes }: MenuActionRowProps): SafeHtml;
+declare function MenuActionRow({ label, icon, action, itemId, selected, pressed, accessibleLabel, title, multiline, state, disabled, tabIndex, placeholder, trailingAction, trailingActionLabel, trailingActionIcon, trailingActionDisabled, trailingActionTitle, className, style, rootAttributes, trailingActionAttributes }: MenuActionRowProps): SafeHtml;
 
 export { MenuActionRow, type MenuActionRowProps };
 ```
@@ -205,33 +213,21 @@ interface MenuItemProps {
     state?: string;
     disabled?: boolean;
     tabIndex?: number;
+    /** Render the row as an unanimated loading skeleton, disabling its action. */
+    placeholder?: boolean;
     rootAttributes?: MenuItemRootAttributes;
 }
-declare function MenuItem({ label, icon, trailing, selected, action, itemId, className, style, pressed, accessibleLabel, title, multiline, state, disabled, tabIndex, rootAttributes }: MenuItemProps): SafeHtml;
+declare function MenuItem({ label, icon, trailing, selected, action, itemId, className, style, pressed, accessibleLabel, title, multiline, state, disabled, tabIndex, placeholder, rootAttributes }: MenuItemProps): SafeHtml;
 
 export { MenuItem, type MenuItemProps };
 ```
 
-## `@kerfjs/ui/page-header`
+## `@kerfjs/ui/panel-header`
 
 ```ts
 import { SafeHtml } from 'kerfjs';
 
-interface PageHeaderProps {
-    title: string | SafeHtml;
-    action?: SafeHtml;
-}
-declare function PageHeader({ title, action }: PageHeaderProps): SafeHtml;
-
-export { PageHeader, type PageHeaderProps };
-```
-
-## `@kerfjs/ui/dialog-header`
-
-```ts
-import { SafeHtml } from 'kerfjs';
-
-interface DialogHeaderProps {
+interface PanelHeaderProps {
     title: string;
     titleId: string;
     summary?: string;
@@ -239,11 +235,24 @@ interface DialogHeaderProps {
     icon?: SafeHtml;
     iconClassName?: string;
     actions?: SafeHtml;
-    actionsLabel?: string;
+    /** Render the title and summary as unanimated loading skeletons, keeping the icon and actions. */
+    placeholder?: boolean;
 }
-declare function DialogHeader({ title, titleId, summary, summaryId, icon, iconClassName, actions, actionsLabel }: DialogHeaderProps): SafeHtml;
+/**
+ * The heading of a panel, dialog, or page: a plain `Toolbar` whose leading zone
+ * holds an optional icon control group and the title as extra-large `ToolbarText`,
+ * whose trailing zone holds the app's action controls, and with an optional
+ * subtitle on its own row, left-aligned with the title.
+ *
+ * PanelHeader overrides no Toolbar styles — it is just a Toolbar with an xl title.
+ * The only styling it adds is the icon group's fill/border color and the subtitle.
+ * When no icon is provided, the icon group is omitted entirely. The `actions` slot
+ * is passed straight into the toolbar's trailing zone; the app supplies whatever
+ * trailing controls it needs (typically a `ToolbarControlGroup`).
+ */
+declare function PanelHeader({ title, titleId, summary, summaryId, icon, iconClassName, actions, placeholder }: PanelHeaderProps): SafeHtml;
 
-export { DialogHeader, type DialogHeaderProps };
+export { PanelHeader, type PanelHeaderProps };
 ```
 
 ## `@kerfjs/ui/value-table`
@@ -256,8 +265,10 @@ interface ValueTableRowProps {
     value: string | SafeHtml;
     icon?: SafeHtml;
     className?: string;
+    /** Render the value as an unanimated loading skeleton, keeping the field label. */
+    placeholder?: boolean;
 }
-declare function ValueTableRow({ label, value, icon, className }: ValueTableRowProps): SafeHtml;
+declare function ValueTableRow({ label, value, icon, className, placeholder }: ValueTableRowProps): SafeHtml;
 
 interface ValueTableProps {
     label: string;
@@ -295,9 +306,11 @@ interface AppTabProps {
     selectAction?: string;
     closeAction?: string;
     className?: string;
+    /** Render as an unanimated loading skeleton, disabling select/close and dragging. */
+    placeholder?: boolean;
     rootAttributes?: AppTabRootAttributes;
 }
-declare function AppTab({ id, name, selected, closable, draggable, leading, trailing, closeIcon, selectAction, closeAction, className, rootAttributes }: AppTabProps): SafeHtml;
+declare function AppTab({ id, name, selected, closable, draggable, leading, trailing, closeIcon, selectAction, closeAction, className, placeholder, rootAttributes }: AppTabProps): SafeHtml;
 
 export { AppTab, type AppTabProps };
 ```
@@ -343,6 +356,205 @@ declare function wireTabBars(root: HTMLElement | Document, { onReorder }: WireTa
 export { type TabDropPosition, type TabReorder, type TabReorderSource, type WireTabBarsOptions, reorderTabs, wireTabBars };
 ```
 
+## `@kerfjs/ui/nav-stack`
+
+```ts
+import { SafeHtml } from 'kerfjs';
+
+/**
+ * One entry in a {@link NavStack}. The app owns the stack as an array (usually a
+ * signal); `NavStack` renders it and `wireNavStack` animates the transitions.
+ */
+interface NavStackView {
+    /** Stable identity for keyed reconcile and transition direction. */
+    key: string;
+    content: SafeHtml;
+    /** Title shown in the top toolbar for this view. */
+    title?: string;
+    /** Trailing actions for this view's top toolbar. */
+    toolbar?: SafeHtml;
+}
+interface NavStackProps {
+    id: string;
+    /** Accessible name for the stack region. */
+    label: string;
+    /** The stack, root first; the last entry is the active top view. */
+    views: NavStackView[];
+    /** Accessible label for the back control (default "Back"). */
+    backLabel?: string;
+    /** Hide the top toolbar entirely (rare — a fully custom-chrome view). */
+    hideToolbar?: boolean;
+    /** Optional persistent bottom toolbar. */
+    bottomToolbar?: SafeHtml;
+    className?: string;
+}
+/**
+ * A navigation stack (iOS-style push/pop). Renders every entry stacked, the last
+ * one active; `@kerfjs/ui/wire-nav-stack`'s `wireNavStack` slides the content and
+ * cross-fades the chrome across a change. A single-pane layout is a `NavStack`
+ * with one entry. See `docs/23-app-layouts.md` §3.1.
+ */
+declare function NavStack({ id, label, views, backLabel, hideToolbar, bottomToolbar, className }: NavStackProps): SafeHtml;
+
+export { NavStack, type NavStackProps, type NavStackView };
+```
+
+## `@kerfjs/ui/wire-nav-stack`
+
+```ts
+interface WireNavStackOptions {
+    /** Invoked when the back control is activated. The app pops its own stack. */
+    onBack?: () => void;
+    /** Transition duration in ms (default 200). Set 0 to disable animation. */
+    duration?: number;
+}
+/**
+ * Animate a `NavStack`'s push/pop transitions and wire its back control. The app
+ * owns the stack (a signal of `NavStackView[]`) and re-renders `NavStack` when it
+ * changes; this helper slides the content and settles the chrome across each
+ * change, and calls `onBack` when the back control is used. Returns a disposer.
+ */
+declare function wireNavStack(root: Element, options?: WireNavStackOptions): () => void;
+
+export { type WireNavStackOptions, wireNavStack };
+```
+
+## `@kerfjs/ui/split-view`
+
+```ts
+import { SafeHtml } from 'kerfjs';
+
+interface SplitViewResizable {
+    size: number;
+    min: number;
+    max: number;
+}
+interface SplitViewProps {
+    id: string;
+    label: string;
+    /** The list (primary) pane. */
+    list: SafeHtml;
+    /** The detail (secondary) pane. */
+    detail: SafeHtml;
+    /**
+     * Compact ("one pane at a time") classes — a handset or portrait tablet.
+     * Derive from `deviceClass().value.compact`. When true the split collapses to
+     * a `NavStack`: the list is the root and the detail is pushed over it.
+     */
+    compact?: boolean;
+    /** In compact mode, whether the detail is currently pushed over the list. */
+    detailActive?: boolean;
+    /** Title/label for the list (compact NavStack root + region label). */
+    listTitle?: string;
+    /** Title/label for the detail (compact NavStack pushed view + region label). */
+    detailTitle?: string;
+    /** Back label for the compact NavStack (default "Back"). */
+    backLabel?: string;
+    /** A resizable separator on roomy classes (min/max px). Omit for a fixed split. */
+    resizable?: SplitViewResizable;
+    className?: string;
+}
+/**
+ * A list-detail (master-detail) split. On roomy classes it shows both panes side
+ * by side with an optional resizable separator; on compact classes it collapses
+ * to a `NavStack` (list → detail). See `docs/23-app-layouts.md` §3.2. Compose the
+ * resizable wiring with `wireResizableRegions` and the compact back with
+ * `wireNavStack`.
+ */
+declare function SplitView({ id, label, list, detail, compact, detailActive, listTitle, detailTitle, backLabel, resizable, className }: SplitViewProps): SafeHtml;
+
+export { SplitView, type SplitViewProps, type SplitViewResizable };
+```
+
+## `@kerfjs/ui/workbench`
+
+```ts
+import { SafeHtml } from 'kerfjs';
+
+/** A collapsible Workbench panel — a side rail or the bottom drawer. */
+interface WorkbenchPanel {
+    content: SafeHtml;
+    /** Whether the panel is currently collapsed (the app owns this). */
+    collapsed?: boolean;
+    /** Rail width, or drawer height, in px. Overrides the CSS default. */
+    size?: number;
+    /** Accessible name for the panel region. */
+    label?: string;
+}
+interface WorkbenchProps {
+    id: string;
+    label: string;
+    /** The central work area. */
+    main: SafeHtml;
+    leftRail?: WorkbenchPanel;
+    rightRail?: WorkbenchPanel;
+    bottomDrawer?: WorkbenchPanel;
+    className?: string;
+}
+/**
+ * The Xcode-like multi-panel workspace: a collapsible left rail, right rail, and
+ * bottom drawer around a central work area (any absent). Collapsing snaps the
+ * panel's track to zero in one reflow while its fixed-size content slides out via
+ * a composited transform — the instant-width / sliding-content technique, so the
+ * work area relayouts once, not per frame. The app owns each `collapsed` flag;
+ * the collapse is pure CSS (no wire). See `docs/23-app-layouts.md` §3.3.
+ */
+declare function Workbench({ id, label, main, leftRail, rightRail, bottomDrawer, className }: WorkbenchProps): SafeHtml;
+
+export { Workbench, type WorkbenchPanel, type WorkbenchProps };
+```
+
+## `@kerfjs/ui/tab-scaffold`
+
+```ts
+import { SafeHtml } from 'kerfjs';
+
+interface TabScaffoldTab {
+    id: string;
+    label: string;
+    /** Decorative icon shown above the label in the bottom bar. */
+    icon?: SafeHtml;
+    /** The tab's content — typically a `NavStack` so each tab keeps its own stack. */
+    content: SafeHtml;
+}
+interface TabScaffoldProps {
+    id: string;
+    /** Accessible name for the tab bar. */
+    label: string;
+    tabs: TabScaffoldTab[];
+    /** The controlled active tab id (the app owns selection). */
+    active: string;
+    className?: string;
+}
+/**
+ * A mobile-first, iOS-like bottom tab scaffold: a bottom tab bar that switches
+ * between major sections, each tab keeping its own content (usually a `NavStack`)
+ * mounted so its stack and scroll survive a switch. Controlled — the app owns
+ * `active`; wire selection with `@kerfjs/ui/wire-tab-scaffold`'s `wireTabScaffold`.
+ * On larger classes, promote the tabs to a `Workbench` rail or sidebar instead of
+ * a bottom bar. See `docs/23-app-layouts.md` §3.4.
+ */
+declare function TabScaffold({ id, label, tabs, active, className }: TabScaffoldProps): SafeHtml;
+
+export { TabScaffold, type TabScaffoldProps, type TabScaffoldTab };
+```
+
+## `@kerfjs/ui/wire-tab-scaffold`
+
+```ts
+interface WireTabScaffoldOptions {
+    /** Invoked with the selected tab id when a bottom-bar tab is activated. */
+    onSelect: (tabId: string) => void;
+}
+/**
+ * Wire a `TabScaffold`'s bottom tab bar: clicking a tab calls `onSelect` with its
+ * id (the app then updates its controlled `active`). Returns a disposer.
+ */
+declare function wireTabScaffold(root: Element, options: WireTabScaffoldOptions): () => void;
+
+export { type WireTabScaffoldOptions, wireTabScaffold };
+```
+
 ## `@kerfjs/ui/resizable-region`
 
 ```ts
@@ -391,6 +603,73 @@ declare function wireResizableRegions(root: HTMLElement, { step, largeStep, onPr
 export { type ResizeCommit, type WireResizableRegionsOptions, wireResizableRegions };
 ```
 
+## `@kerfjs/ui/device-class`
+
+```ts
+import { ReadonlySignal } from 'kerfjs';
+
+/**
+ * Reactive device-class detection for `@kerfjs/ui` (see `docs/23-app-layouts.md`
+ * §2). `deviceClass()` returns a `ReadonlySignal<DeviceClass>` describing the
+ * current viewport as a size bucket × orientation × viewport-segment count, so a
+ * layout can pick its presentation reactively instead of hand-wiring `matchMedia`.
+ *
+ * One shared viewport source backs every reader; the pure `classifyViewport`
+ * core is DOM-free and directly unit-tested.
+ */
+type DeviceSize = 'xs-mobile' | 'mobile' | 'tablet' | 'desktop' | 'xl-desktop';
+type DeviceOrientation = 'portrait' | 'landscape';
+/** Minimum widths (px) at which each larger bucket begins. `xs-mobile` is 0. */
+interface DeviceBreakpoints {
+    mobile: number;
+    tablet: number;
+    desktop: number;
+    'xl-desktop': number;
+}
+interface DeviceClass {
+    size: DeviceSize;
+    orientation: DeviceOrientation;
+    /** Horizontal viewport segments (foldables / dual-screen); 1 on ordinary devices. */
+    segments: number;
+    /** Vertical viewport segments; 1 on ordinary devices. */
+    verticalSegments: number;
+    /** Small phones — `xs-mobile` or `mobile`. */
+    handset: boolean;
+    /** "One pane at a time" — a handset or a portrait tablet. */
+    compact: boolean;
+    /** True when the current size is `size` or larger, e.g. `atLeast('tablet')`. */
+    atLeast(size: DeviceSize): boolean;
+}
+/** A raw viewport snapshot, before breakpoints are applied. */
+interface Viewport {
+    width: number;
+    height: number;
+    segments: number;
+    verticalSegments: number;
+}
+interface DeviceClassOptions {
+    /** Override any of the default bucket thresholds. */
+    breakpoints?: Partial<DeviceBreakpoints>;
+    /** The viewport assumed when there is no DOM (SSR). Defaults to 1024×768, one segment. */
+    ssr?: Partial<Viewport>;
+}
+declare const DEFAULT_BREAKPOINTS: DeviceBreakpoints;
+/**
+ * Classify a raw viewport into a {@link DeviceClass}. Pure and DOM-free — the
+ * single source of truth for the bucketing rules.
+ */
+declare function classifyViewport(width: number, orientation: DeviceOrientation, segments?: number, verticalSegments?: number, breakpoints?: DeviceBreakpoints): DeviceClass;
+/**
+ * A reactive signal of the current {@link DeviceClass}. Reading it inside an
+ * `effect`/`computed` re-runs when the viewport crosses a breakpoint, rotates,
+ * or changes its segment count. Without a DOM it resolves to `options.ssr`
+ * (default 1024×768, landscape, one segment).
+ */
+declare function deviceClass(options?: DeviceClassOptions): ReadonlySignal<DeviceClass>;
+
+export { DEFAULT_BREAKPOINTS, type DeviceBreakpoints, type DeviceClass, type DeviceClassOptions, type DeviceOrientation, type DeviceSize, type Viewport, classifyViewport, deviceClass };
+```
+
 ## `@kerfjs/ui/segmented-control`
 
 ```ts
@@ -418,8 +697,10 @@ interface SegmentedControlProps {
     size?: SegmentedControlSize;
     layout?: SegmentedControlLayout;
     className?: string;
+    /** Render as an unanimated loading skeleton, disabling every segment. */
+    placeholder?: boolean;
 }
-declare function SegmentedControl({ id, label, value, choices, action, appearance, shape, size, layout, className, }: SegmentedControlProps): SafeHtml;
+declare function SegmentedControl({ id, label, value, choices, action, appearance, shape, size, layout, className, placeholder, }: SegmentedControlProps): SafeHtml;
 
 export { SegmentedControl, type SegmentedControlAppearance, type SegmentedControlChoice, type SegmentedControlLayout, type SegmentedControlProps, type SegmentedControlShape, type SegmentedControlSize };
 ```
@@ -438,8 +719,10 @@ interface StateBannerProps {
     tone?: StateBannerTone;
     urgency?: 'status' | 'alert';
     className?: string;
+    /** Render the title and detail as unanimated loading skeletons, keeping the icon and tone. */
+    placeholder?: boolean;
 }
-declare function StateBanner({ title, detail, icon, action, tone, urgency, className }: StateBannerProps): SafeHtml;
+declare function StateBanner({ title, detail, icon, action, tone, urgency, className, placeholder }: StateBannerProps): SafeHtml;
 
 export { StateBanner, type StateBannerProps, type StateBannerTone };
 ```
@@ -477,6 +760,35 @@ declare function LoadingSpinner({ className, label }: LoadingSpinnerProps): kerf
 export { LoadingSpinner, type LoadingSpinnerProps };
 ```
 
+## `@kerfjs/ui/skeleton`
+
+```ts
+import * as kerfjs from 'kerfjs';
+
+interface SkeletonProps {
+    /** Width as any CSS length (e.g. `remify(120px)`, `60%`). Defaults to filling its slot. */
+    width?: string;
+    /** Height as any CSS length. Defaults to a single text line. */
+    height?: string;
+    /** Corner radius override (a CSS length). Defaults to the small radius token. */
+    radius?: string;
+    /** Render this many stacked lines (the last one shorter), for multi-line text. */
+    lines?: number;
+    /** Accessible label. Omit to keep the block decorative (`aria-hidden`). */
+    label?: string;
+    className?: string;
+}
+/**
+ * A subtle, deliberately **unanimated** loading placeholder block. Use it for a
+ * value slot whose content is not yet known, on its own or via a component's
+ * `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 }: SkeletonProps): kerfjs.SafeHtml;
+
+export { Skeleton, type SkeletonProps };
+```
+
 ## `@kerfjs/ui/token-search-field`
 
 ```ts
@@ -528,17 +840,59 @@ export { TokenSearchField, type TokenSearchFieldProps, type TokenSearchFieldValu
 ## `@kerfjs/ui/wire-token-search-fields`
 
 ```ts
+import { Signal } from 'kerfjs';
+
 interface TokenSearchSubmit {
     id: string;
     editor: HTMLElement;
 }
+/**
+ * Managed collapsible behavior for the iconic TokenSearchField. Every piece is on
+ * by default; disable a specific one to own it in the app. Provide `signals` to
+ * drive app-owned `expanded` signals per field id instead of helper-created ones.
+ */
+interface TokenSearchCollapsibleOptions {
+    /** Expand the field and focus its editor when the iconic trigger is activated. Default: true. */
+    expandOnActivate?: boolean;
+    /** Collapse the field when focus leaves it while it is empty. Default: true. */
+    collapseOnEmptyBlur?: boolean;
+    /** Collapse an empty field on Escape and restore focus to its trigger. Default: true. */
+    collapseOnEscape?: boolean;
+    /** Focus the editor on expand and the trigger on Escape-collapse. Default: true. */
+    manageFocus?: boolean;
+    /** App-owned `expanded` signals keyed by field id; adopted instead of helper-created. */
+    signals?: Readonly<Record<string, Signal<boolean>>>;
+}
 interface WireTokenSearchFieldsOptions {
-    onSubmit: (submission: TokenSearchSubmit) => void;
+    onSubmit?: (submission: TokenSearchSubmit) => void;
+    /** Managed collapsible transient behavior. `true`/omitted = on with defaults; `false` = fully off. */
+    collapsible?: boolean | TokenSearchCollapsibleOptions;
+}
+/**
+ * The value returned from {@link wireTokenSearchFields}: call it (or `dispose()`) to
+ * tear down. When collapsible behavior is managed, it also exposes the transient
+ * `expanded` state per field id so the app can read it in render, hand in its own
+ * signal, or drive it imperatively.
+ */
+interface TokenSearchFieldsHandle {
+    (): void;
+    dispose(): void;
+    /** The managed `expanded` signal for a field id (adopted or helper-created); undefined when unmanaged. */
+    expanded(id: string): Signal<boolean> | undefined;
+    /** Expand the field (and, when focus is managed, focus its editor). */
+    open(id: string): void;
+    /** Collapse the field (and, when focus is managed, restore focus to its trigger). */
+    close(id: string): void;
 }
-/** Keep TokenSearchField wrapping, submit Enter, and preserve its caret across controlled token deletion. */
-declare function wireTokenSearchFields(root: HTMLElement, { onSubmit }: WireTokenSearchFieldsOptions): () => void;
+/**
+ * Wire every TokenSearchField under `root`: submit on Enter, preserve the caret across
+ * controlled token deletion, and (by default) manage the collapsible field's transient
+ * expand/collapse/focus. Returns a {@link TokenSearchFieldsHandle} — a disposer that also
+ * exposes the managed `expanded` state per field id.
+ */
+declare function wireTokenSearchFields(root: HTMLElement, { onSubmit, collapsible }?: WireTokenSearchFieldsOptions): TokenSearchFieldsHandle;
 
-export { type TokenSearchSubmit, type WireTokenSearchFieldsOptions, wireTokenSearchFields };
+export { type TokenSearchCollapsibleOptions, type TokenSearchFieldsHandle, type TokenSearchSubmit, type WireTokenSearchFieldsOptions, wireTokenSearchFields };
 ```
 
 ## `kerfjs/actions`

package/ai/skill.md

@@ -1,7 +1,7 @@
 ---
 name: kerf-ui
 description: Build interfaces with kerfjs and the @kerfjs/ui production component package. Use whenever code imports @kerfjs/ui or a task asks for Kerf UI components.
-kerf-ui-skill-version: 1.32.0
+kerf-ui-skill-version: 1.34.0
 ---
 
 # Building with @kerfjs/ui
@@ -29,9 +29,10 @@ Quick routing:
 | --- | --- | --- |
 | Navigation row | `MenuItem` | Use an ordinary link or button when sidebar/menu anatomy and state do not apply. Multiline leading icons stay aligned with the first text line. |
 | Navigation row with a trailing action | `MenuActionRow` | Use `MenuItem` when the trailing region is dormant; never put controls inside either component's SafeHtml slots. Multiline leading icons stay aligned with the first text line. |
-| Page chrome or heading | `Toolbar`, `PageHeader`, or `DialogHeader` | Toolbar is persistent chrome; page and dialog headers identify different scopes. |
+| Page, panel, or dialog heading | `Toolbar` or `PanelHeader` | Toolbar is persistent chrome; `PanelHeader` heads a panel, dialog, or page. |
 | Exclusive choice | `TabBar`, `SegmentedControl`, or `Select` | Tabs switch tabpanels; segments expose a few choices; Select handles a longer value list. |
 | Status or absent content | `StateBanner` or `EmptyState` | Web Awesome callouts suit ecosystem content; toasts are transient and never the only record of important state. |
+| Loading placeholder | a component's `placeholder` prop, or `Skeleton` | Set `placeholder` on a value-bearing component (`Select`, `MenuHeader`, `MenuItem`, `ValueTableRow`, `PanelHeader`, `SegmentedControl`, `StateBanner`, `AppTab`, `ToolbarText`, `MenuActionRow`) to render its real chrome with value slots as subtle **unanimated** skeletons and interactivity disabled — do not hand-rebuild an empty state. `Skeleton` is the standalone block for a custom slot. Use `LoadingSpinner` for known busy activity, not a skeleton; never animate a skeleton; prefer it over `wa-skeleton`. |
 | Adjustable or static columns | `ResizableRegion` or CSS grid | Use the component only for a user-operable controlled separator. |
 | Structured or ordinary search | `TokenSearchField` or an input | Use token search only when text and ordered filter chips form one editor. |
 | Key/value facts | `ValueTable` with `ValueTableRow` | Use rows with `icon` only when the optional 24px leading visual adds context. |
@@ -56,16 +57,18 @@ Hard rules:
 8. `ResizableRegion` uses `wireResizableRegions()` for Arrow, Shift+Arrow, Home/End, and pointer behavior. The app owns size persistence. `handleIcon` replaces decorative dormant glyph content only.
 9. Use controlled `SegmentedControl` for a small exclusive choice set. Select `appearance="toolbar"` when nesting it inside `ToolbarControlGroup`; use rounded or pill shapes for standalone contexts. Handle its action, update `value`, keep meaningful choice labels, and preserve every enabled native button in sequential Tab order.
 10. Compose `AppTab` inside controlled `TabBar`; call `wireTabBars()` once and retain its disposer. It owns same-bar drag mechanics, including proximity-based horizontal edge autoscroll, while the app applies `onReorder` and owns order, selection, panels, close policy, routing, and persistence. Use runtime-filtered `rootAttributes` for domain metadata and keep an optional `closeIcon` decorative and noninteractive.
-11. Use token-controlled `TokenSearchField` when free text and removable structured filters share one editor. Editable text stays DOM-owned between token changes. The leading icon, first text line, clear action, and trailing slot share one fixed row when content wraps. The app owns parsing and suggestions; call `readTokenSearchField()` on input, empty `textContent` on clear, use `placeTokenSearchCaret()` after explicit controlled focus changes, and call `wireTokenSearchFields()` once so Enter submits without inserting a line break and keyboard chip deletion restores focus plus the text-relative caret after controlled replacement. Enable `collapsible` for an animated iconic closed state, standalone or inside `ToolbarControlGroup`; the field keeps text or tokens expanded while the app controls transient `expanded` state, focus transfer, and focusout timing.
+11. Use token-controlled `TokenSearchField` when free text and removable structured filters share one editor. Editable text stays DOM-owned between token changes. The leading icon, first text line, clear action, and trailing slot share one fixed row when content wraps. The app owns parsing and suggestions; call `readTokenSearchField()` on input, empty `textContent` on clear, use `placeTokenSearchCaret()` after explicit controlled focus changes, and call `wireTokenSearchFields()` once so Enter submits without inserting a line break and keyboard chip deletion restores focus plus the text-relative caret after controlled replacement. Enable `collapsible` for an animated iconic closed state, standalone or inside `ToolbarControlGroup`; the field keeps text or tokens expanded, and `wireTokenSearchFields()` manages the transient expand/collapse/focus by default (activate to reveal + focus, Escape or empty blur to collapse). Bind the field's `expanded` to the returned handle's `expanded(id)` signal or adopt your own via `collapsible.signals`; opt a behavior out only when the app must own it. Do not hand-roll the open handler, the focusout collapse, or a clear-button mousedown guard — the helper owns them.
 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. Project its 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.
 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.
 14. Treat the complete Web Awesome catalog as support coverage, not a recommendation list. 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`. 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 or duplicate item geometry in wrappers.
 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.
-16. Wrap every toolbar item, including dormant text, in `ToolbarControlGroup`. 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: `MenuHeader` 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-menu-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`. `MenuItem.trailing` is dormant; use `MenuActionRow` 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. 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, `DialogHeader` title/summary 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.
+16. 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. `SegmentedControl`, `Select`, a collapsible `TokenSearchField`, and Web Awesome controls all live inside a `ToolbarControlGroup`. A popup menu in a toolbar is a `single` `ToolbarControlGroup` 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`. `PanelHeader` composes these for you as a panel/dialog/page heading. Wrap every toolbar item, including dormant text, in `ToolbarControlGroup`. 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: `MenuHeader` 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-menu-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`. `MenuItem.trailing` is dormant; use `MenuActionRow` 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. 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, `PanelHeader` title/summary 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.
 18. 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.
-19. Use `DialogHeader` for dialog hierarchy, not a custom heading row. Its real top `Toolbar` puts the optional 24px icon in a 34px circular background and the first title line in a borderless `ToolbarControlGroup`, centered against the automatic action `ToolbarControlGroup`; pass action children directly and add a localized `actionsLabel` when that group needs a name. Its optional `summary`/`summaryId` row stays below the title. The app owns modal behavior, focus, dismissal, command policy, and action handling.
+19. Use `PanelHeader` for a panel, dialog, or page heading, not a custom heading row. It is a plain top `Toolbar` (overriding no Toolbar styles): the leading zone holds an optional icon (a normal bordered `ToolbarControlGroup` given a brand fill with a matching border) and the title as extra-large `ToolbarText`; the app's trailing controls (typically a `ToolbarControlGroup`) go straight in the trailing zone, and the icon group is omitted when no icon is passed. Its optional `summary`/`summaryId` row stays below the title. The app owns modal behavior, focus, dismissal, command policy, and action handling.
+20. 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; prefer the five canonical remify-authored tokens. See `docs/layout.md` "Spacing scale".
+21. 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`. 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. Dialogs pick the same inner layout, then present per device class (full-screen modal on `compact`, inline on desktop). See `docs/app-layouts.md`.
 
 Common mistakes:
 
@@ -89,4 +92,9 @@ Common mistakes:
 | Let the document, pane, and list all scroll | Keep fixed chrome outside one `.kui-pane__content` scroll owner per pane |
 | Invent an `@kerfjs/ui` command-palette export | Keep the semantics application-local, reuse public layout vocabulary, and propose recurring behavior upstream |
 | Handwrite `ValueTable` row wrappers or compensate their padding or separators | Compose `ValueTableRow`; its root-scaled block padding, optional icon hook, and separator geometry are public contract |
-| Rebuild a dialog heading or pre-wrap new `DialogHeader.actions` in groups | Pass action children directly; `DialogHeader` supplies aligned identity/action groups and keeps the optional subtitle below |
+| Rebuild a panel/dialog heading row by hand | Use `PanelHeader`: a plain toolbar with an optional bordered icon group, an xl title, trailing controls you pass, and the optional subtitle below |
+| Force a `width`/`height`/`padding` on a component to size or space it | Let it size to its content and tokens; a forced box leaves a halo or a stretched oval — adjust an icon-size or spacing token, not the box |
+| Wrap a component or region in a card, border, backdrop, or outline to "contain" it | Let it sit on the surface; add a `.kui-content-item` only for a real distinction — hierarchy comes from alignment, spacing, and type first |
+| Add another container's padding on top of a content-item's own margin | Pick one owner of the inset; a pane has no padding and its `.kui-content` children own the 8/1/8 geometry — stacking them double-insets |
+| Keep chrome, a label, or a readout that aids no decision | Delete it; every element must help a person decide or act |
+| Override a component's default size or color because it "looks off" | Trust the default (a LucideIcon is 24px) and fix the surrounding layout instead |

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.4` 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.7` 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/app-tab.d.ts

@@ -21,8 +21,10 @@ interface AppTabProps {
     selectAction?: string;
     closeAction?: string;
     className?: string;
+    /** Render as an unanimated loading skeleton, disabling select/close and dragging. */
+    placeholder?: boolean;
     rootAttributes?: AppTabRootAttributes;
 }
-declare function AppTab({ id, name, selected, closable, draggable, leading, trailing, closeIcon, selectAction, closeAction, className, rootAttributes }: AppTabProps): SafeHtml;
+declare function AppTab({ id, name, selected, closable, draggable, leading, trailing, closeIcon, selectAction, closeAction, className, placeholder, rootAttributes }: AppTabProps): SafeHtml;
 
 export { AppTab, type AppTabProps };

package/dist/app-tab.js

@@ -1,4 +1,5 @@
-export { AppTab } from './chunk-XZXRLY5Q.js';
+export { AppTab } from './chunk-2Z5TWHKQ.js';
+
 
 
 //# sourceMappingURL=app-tab.js.map