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

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.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.
+Generated from emitted declarations for `@kerfjs/ui@5.0.0-beta.9` and `kerfjs@5.0.0-beta.9`. 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`
 
@@ -45,18 +45,26 @@ export { Toolbar, type ToolbarProps };
 import * as kerfjs from 'kerfjs';
 
 type ToolbarTextSize = 'xlarge' | 'large' | 'default' | 'small';
+/** ARIA heading level for a title exposed as a heading landmark. */
+type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
 interface ToolbarTextProps {
     text: string;
     size?: ToolbarTextSize;
     className?: string;
     /** Optional id, e.g. so a dialog can reference the title via aria-labelledby. */
     id?: string;
+    /**
+     * Expose heading semantics (`role="heading"` + `aria-level`) so the text acts as
+     * a heading landmark — e.g. a page's primary title. Omit to keep the plain span
+     * (the default), which suits a dialog title referenced via `aria-labelledby`.
+     */
+    headingLevel?: HeadingLevel;
     /** Render the text as an unanimated loading skeleton instead of its value. */
     placeholder?: boolean;
 }
-declare function ToolbarText({ text, size, className, id, placeholder }: ToolbarTextProps): kerfjs.SafeHtml;
+declare function ToolbarText({ text, size, className, id, headingLevel, placeholder }: ToolbarTextProps): kerfjs.SafeHtml;
 
-export { ToolbarText, type ToolbarTextProps, type ToolbarTextSize };
+export { type HeadingLevel, ToolbarText, type ToolbarTextProps, type ToolbarTextSize };
 ```
 
 ## `@kerfjs/ui/toolbar-control-group`
@@ -79,26 +87,26 @@ declare function ToolbarControlGroup({ children, label, className, expanded, sin
 export { ToolbarControlGroup, type ToolbarControlGroupProps };
 ```
 
-## `@kerfjs/ui/menu-header`
+## `@kerfjs/ui/list-header`
 
 ```ts
 import { SafeHtml } from 'kerfjs';
 
-type MenuHeaderRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+type ListHeaderRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
     'data-component'?: never;
     'data-action'?: never;
     'data-has-badge'?: never;
     'data-has-count'?: never;
     'data-toggle'?: never;
 }>;
-type MenuHeaderTriggerAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+type ListHeaderTriggerAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
     'data-action'?: never;
     popoverTarget?: string;
     popoverTargetAction?: 'toggle' | 'show' | 'hide';
     'aria-controls'?: string;
     'aria-haspopup'?: 'dialog' | 'menu' | 'listbox' | 'tree' | 'grid' | 'true';
 }>;
-interface MenuHeaderBaseProps {
+interface ListHeaderBaseProps {
     label: string;
     action?: string;
     actionLabel?: string;
@@ -109,10 +117,10 @@ interface MenuHeaderBaseProps {
     toggle?: boolean;
     /** Render as an unanimated loading skeleton: keep the label and action affordance, disable interaction. */
     placeholder?: boolean;
-    rootAttributes?: MenuHeaderRootAttributes;
-    triggerAttributes?: MenuHeaderTriggerAttributes;
+    rootAttributes?: ListHeaderRootAttributes;
+    triggerAttributes?: ListHeaderTriggerAttributes;
 }
-type MenuHeaderIndicatorProps = {
+type ListHeaderIndicatorProps = {
     count: number;
     countLabel: string;
     badge?: never;
@@ -121,18 +129,18 @@ type MenuHeaderIndicatorProps = {
     countLabel?: never;
     badge?: SafeHtml;
 };
-type MenuHeaderProps = MenuHeaderBaseProps & MenuHeaderIndicatorProps;
-declare function MenuHeader({ label, count, countLabel, badge, action, actionLabel, actionIcon, actionDisabled, disabledReason, expanded, toggle, placeholder, rootAttributes, triggerAttributes }: MenuHeaderProps): SafeHtml;
+type ListHeaderProps = ListHeaderBaseProps & ListHeaderIndicatorProps;
+declare function ListHeader({ label, count, countLabel, badge, action, actionLabel, actionIcon, actionDisabled, disabledReason, expanded, toggle, placeholder, rootAttributes, triggerAttributes }: ListHeaderProps): SafeHtml;
 
-export { MenuHeader, type MenuHeaderProps };
+export { ListHeader, type ListHeaderProps };
 ```
 
-## `@kerfjs/ui/menu-action-row`
+## `@kerfjs/ui/list-action-row`
 
 ```ts
 import { SafeHtml } from 'kerfjs';
 
-type MenuActionRowRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+type ListActionRowRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
     'data-component'?: never;
     'data-action'?: never;
     'data-item-id'?: never;
@@ -142,7 +150,7 @@ type MenuActionRowRootAttributes = Readonly<Record<`data-${string}`, string | un
     'data-selected'?: never;
     'data-pressed'?: never;
 }>;
-type MenuActionRowTrailingAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+type ListActionRowTrailingAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
     'data-component'?: never;
     'data-action'?: never;
     'data-item-id'?: never;
@@ -151,7 +159,7 @@ type MenuActionRowTrailingAttributes = Readonly<Record<`data-${string}`, string
     'aria-controls'?: string;
     'aria-haspopup'?: 'dialog' | 'menu' | 'listbox' | 'tree' | 'grid' | 'true';
 }>;
-interface MenuActionRowProps {
+interface ListActionRowProps {
     /** Visible dormant content for the primary button. Must not contain interactive descendants. */
     label: string | SafeHtml;
     /** Decorative dormant content for the primary button. Must not contain interactive descendants. */
@@ -176,20 +184,20 @@ interface MenuActionRowProps {
     trailingActionTitle?: string;
     className?: string;
     style?: string;
-    rootAttributes?: MenuActionRowRootAttributes;
-    trailingActionAttributes?: MenuActionRowTrailingAttributes;
+    rootAttributes?: ListActionRowRootAttributes;
+    trailingActionAttributes?: ListActionRowTrailingAttributes;
 }
-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;
+declare function ListActionRow({ label, icon, action, itemId, selected, pressed, accessibleLabel, title, multiline, state, disabled, tabIndex, placeholder, trailingAction, trailingActionLabel, trailingActionIcon, trailingActionDisabled, trailingActionTitle, className, style, rootAttributes, trailingActionAttributes }: ListActionRowProps): SafeHtml;
 
-export { MenuActionRow, type MenuActionRowProps };
+export { ListActionRow, type ListActionRowProps };
 ```
 
-## `@kerfjs/ui/menu-item`
+## `@kerfjs/ui/list-item`
 
 ```ts
 import { SafeHtml } from 'kerfjs';
 
-type MenuItemRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+type ListItemRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
     'data-component'?: never;
     'data-action'?: never;
     'data-item-id'?: never;
@@ -197,7 +205,7 @@ type MenuItemRootAttributes = Readonly<Record<`data-${string}`, string | undefin
     'data-multiline'?: never;
     'data-state'?: never;
 }>;
-interface MenuItemProps {
+interface ListItemProps {
     label: string | SafeHtml;
     icon?: SafeHtml;
     trailing?: SafeHtml;
@@ -215,17 +223,18 @@ interface MenuItemProps {
     tabIndex?: number;
     /** Render the row as an unanimated loading skeleton, disabling its action. */
     placeholder?: boolean;
-    rootAttributes?: MenuItemRootAttributes;
+    rootAttributes?: ListItemRootAttributes;
 }
-declare function MenuItem({ label, icon, trailing, selected, action, itemId, className, style, pressed, accessibleLabel, title, multiline, state, disabled, tabIndex, placeholder, rootAttributes }: MenuItemProps): SafeHtml;
+declare function ListItem({ label, icon, trailing, selected, action, itemId, className, style, pressed, accessibleLabel, title, multiline, state, disabled, tabIndex, placeholder, rootAttributes }: ListItemProps): SafeHtml;
 
-export { MenuItem, type MenuItemProps };
+export { ListItem, type ListItemProps };
 ```
 
 ## `@kerfjs/ui/panel-header`
 
 ```ts
 import { SafeHtml } from 'kerfjs';
+import { HeadingLevel } from './toolbar-text.js';
 
 interface PanelHeaderProps {
     title: string;
@@ -235,6 +244,13 @@ interface PanelHeaderProps {
     icon?: SafeHtml;
     iconClassName?: string;
     actions?: SafeHtml;
+    /**
+     * Expose the title as a heading landmark (`role="heading"` + `aria-level`). Set it
+     * for a PAGE or view heading so screen-reader heading navigation works and the view
+     * has a primary heading; omit it (the default) for a dialog title, which is instead
+     * referenced via `aria-labelledby={titleId}` and needs no heading landmark.
+     */
+    headingLevel?: HeadingLevel;
     /** Render the title and summary as unanimated loading skeletons, keeping the icon and actions. */
     placeholder?: boolean;
 }
@@ -250,7 +266,7 @@ interface PanelHeaderProps {
  * 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;
+declare function PanelHeader({ title, titleId, summary, summaryId, icon, iconClassName, actions, headingLevel, placeholder }: PanelHeaderProps): SafeHtml;
 
 export { PanelHeader, type PanelHeaderProps };
 ```
@@ -455,7 +471,7 @@ interface SplitViewProps {
     className?: string;
 }
 /**
- * A list-detail (master-detail) split. On roomy classes it shows both panes side
+ * A list-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
@@ -670,6 +686,161 @@ declare function deviceClass(options?: DeviceClassOptions): ReadonlySignal<Devic
 export { DEFAULT_BREAKPOINTS, type DeviceBreakpoints, type DeviceClass, type DeviceClassOptions, type DeviceOrientation, type DeviceSize, type Viewport, classifyViewport, deviceClass };
 ```
 
+## `@kerfjs/ui/catalog`
+
+```ts
+import { SafeHtml } from 'kerfjs';
+
+/** A reference link shown in the detail footer for the active entry. */
+interface CatalogResource {
+    label: string;
+    href: string;
+    /** Optional monospace detail (e.g. a file path) shown after the label. */
+    detail?: string;
+}
+/** A related entry offered in the detail footer's "Related" selector. */
+interface CatalogRelated {
+    id: string;
+    name: string;
+    /** Group heading in the selector, e.g. "Uses" / "Used by". */
+    group: string;
+}
+interface CatalogEntry {
+    id: string;
+    name: string;
+    description?: string;
+    resources?: readonly CatalogResource[];
+    related?: readonly CatalogRelated[];
+}
+interface CatalogSection {
+    category: string;
+    entries: readonly CatalogEntry[];
+}
+/**
+ * A secondary group of sections shown below the primary sidebar sections with a
+ * quieter "ecosystem" treatment (e.g. third-party components). Optionally
+ * collapsible — the app owns `expanded` and toggles it from `wireCatalog`'s
+ * `onToggleSecondary`.
+ */
+interface CatalogSecondaryGroup {
+    label: string;
+    sections: readonly CatalogSection[];
+    /** When true, the group's label is a disclosure toggle controlling `expanded`. */
+    collapsible?: boolean;
+    /** Whether the group is expanded (controlled). Ignored unless `collapsible`. */
+    expanded?: boolean;
+}
+interface CatalogBrand {
+    title: string;
+    subtitle?: string;
+    /** Logo image URL (rendered decorative). Omit for a text-only brand. */
+    logoUrl?: string;
+}
+interface CatalogProps {
+    brand: CatalogBrand;
+    sections: readonly CatalogSection[];
+    /** The controlled active entry id — the app owns this signal. */
+    active: string;
+    /** The rendered preview for the active entry; the app computes it from `active`. */
+    content: SafeHtml;
+    /** Whether the sidebar is collapsed (controlled). */
+    collapsed?: boolean;
+    /** Current theme; when set, a theme toggle is shown that switches to the opposite. Omit to hide it. */
+    theme?: 'light' | 'dark';
+    /** Extra header controls placed before the theme toggle (each a `ToolbarControlGroup`). */
+    headerActions?: SafeHtml;
+    /** A secondary "ecosystem" group of sections below the primary category groups. */
+    secondarySections?: CatalogSecondaryGroup;
+    /** Extra sidebar content below the category groups (and the secondary group). */
+    sidebarFooter?: SafeHtml;
+    /** Status line content shown at the start of the detail footer. */
+    status?: SafeHtml;
+    selectAction?: string;
+    toggleSidebarAction?: string;
+    toggleThemeAction?: string;
+    /** Action fired by the secondary group's disclosure toggle (when collapsible). */
+    toggleSecondaryAction?: string;
+    className?: string;
+}
+/**
+ * A reusable component-catalog shell: a collapsible category sidebar, a titled
+ * detail stage that renders the active entry's preview, and a footer with
+ * reference links and a related-entry selector. Built entirely from public
+ * `@kerfjs/ui` primitives. Controlled and stateless — the app owns the `active`,
+ * `collapsed`, and `theme` signals and computes `content` from `active` in its own
+ * render; wire the sidebar/collapse/theme actions with `wireCatalog`.
+ */
+declare function Catalog({ brand, sections, active, content, collapsed, theme, headerActions, secondarySections, sidebarFooter, status, selectAction, toggleSidebarAction, toggleThemeAction, toggleSecondaryAction, className, }: CatalogProps): SafeHtml;
+/**
+ * How a {@link CatalogExample}'s content aligns its visible left edge with the
+ * example's `ListHeader` label (which sits 16px in — 8px title + 8px label):
+ * - `'glyph'` — a bare glyph/text specimen with no inline geometry insets the full 16px.
+ * - `'inline-control'` — a control that already carries ~8px of its own inline padding insets 8px so its content lands on the same line.
+ * - `'none'` — a content-item / composition that owns its geometry and already aligns; no inset (default).
+ */
+type CatalogExampleAlign = 'glyph' | 'inline-control' | 'none';
+interface CatalogExampleProps {
+    /** The example's label, shown as a `ListHeader` above the specimen. Omit for a bare specimen. */
+    label?: string;
+    /** Optional explanatory note between the label and the specimen. */
+    note?: SafeHtml | string;
+    /** Alignment inset for the specimen — see {@link CatalogExampleAlign}. Default `'none'`. */
+    align?: CatalogExampleAlign;
+    className?: string;
+    children?: SafeHtml | readonly SafeHtml[];
+}
+/**
+ * One labeled example in a catalog preview: a `ListHeader` label, an optional
+ * note, and the specimen. `align` insets the specimen so its visible left edge
+ * lines up with the label text, encoding the catalog's alignment rules as a
+ * first-class prop instead of per-demo CSS. The inset is published as the
+ * `--kui-catalog-example-align` custom property so a debug overlay can exclude it
+ * from a specimen's measured margin.
+ */
+declare function CatalogExample({ label, note, align, className, children }: CatalogExampleProps): SafeHtml;
+interface CatalogExampleStackProps {
+    /** Accessible label for the stack region. */
+    label?: string;
+    className?: string;
+    children?: SafeHtml | readonly SafeHtml[];
+}
+/** A vertically-stacked group of {@link CatalogExample}s with the catalog's example rhythm. */
+declare function CatalogExampleStack({ label, className, children }: CatalogExampleStackProps): SafeHtml;
+
+export { Catalog, type CatalogBrand, type CatalogEntry, CatalogExample, type CatalogExampleAlign, type CatalogExampleProps, CatalogExampleStack, type CatalogExampleStackProps, type CatalogProps, type CatalogRelated, type CatalogResource, type CatalogSecondaryGroup, type CatalogSection };
+```
+
+## `@kerfjs/ui/wire-catalog`
+
+```ts
+interface WireCatalogOptions {
+    /** Invoked with the entry id when a sidebar item or a related-entry option is chosen. */
+    onSelect: (id: string) => void;
+    /** Invoked when the sidebar collapse/expand control is activated. */
+    onToggleSidebar?: () => void;
+    /** Invoked when the theme toggle is activated. */
+    onToggleTheme?: () => void;
+    /** Invoked when the secondary (ecosystem) group's disclosure toggle is activated. */
+    onToggleSecondary?: () => void;
+    /** When set, `?<urlParam>=<id>` is written on select via `history.replaceState`. */
+    urlParam?: string;
+    selectAction?: string;
+    toggleSidebarAction?: string;
+    toggleThemeAction?: string;
+    toggleSecondaryAction?: string;
+}
+/**
+ * Wire a {@link Catalog}'s interactions with one delegated listener set: sidebar
+ * item selection (and the related-entry selector), the sidebar collapse toggle, and
+ * the theme toggle. The app owns the `active`/`collapsed`/`theme` signals and updates
+ * them in the callbacks; optionally mirror the active id into the URL via `urlParam`.
+ * Returns a disposer.
+ */
+declare function wireCatalog(root: HTMLElement, { onSelect, onToggleSidebar, onToggleTheme, onToggleSecondary, urlParam, selectAction, toggleSidebarAction, toggleThemeAction, toggleSecondaryAction, }: WireCatalogOptions): () => void;
+
+export { type WireCatalogOptions, wireCatalog };
+```
+
 ## `@kerfjs/ui/segmented-control`
 
 ```ts

package/ai/skill.md

@@ -27,18 +27,18 @@ Quick routing:
 
 | Need | Choose | Nearest alternatives / boundary |
 | --- | --- | --- |
-| 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. |
+| Navigation row | `ListItem` | 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 | `ListActionRow` | Use `ListItem` 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, 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`. |
+| Loading placeholder | a component's `placeholder` prop, or `Skeleton` | Set `placeholder` on a value-bearing component (`Select`, `ListHeader`, `ListItem`, `ValueTableRow`, `PanelHeader`, `SegmentedControl`, `StateBanner`, `AppTab`, `ToolbarText`, `ListActionRow`) 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. |
 | Command search | Application-local semantics using shared layout vocabulary | No runtime component or production recipe is exported; the app owns behavior, policy, and copy. |
 
-For a complete shell, sidebar, workspace header, master-detail dialog, composer
+For a complete shell, sidebar, workspace header, list-detail dialog, composer
 form, list-state lifecycle, or mixed-control toolbar, start from the runnable
 reference in [`docs/recipes.md`](../docs/recipes.md). Preserve its production
 primitives and semantic ownership; replace application state, policy, and copy.
@@ -49,11 +49,11 @@ Hard rules:
 
 1. Import visual components from explicit JavaScript subpaths. In CSS-aware browser builds each subpath brings in its own reachable CSS, including UI subcomponents, while unrelated CSS remains out. The root barrel and `@kerfjs/ui/unstyled` are CSS-free; pair the root barrel with `styles.css` only when the complete layer is intentional. Manual CSS subpaths remain available for custom pipelines.
 2. Components return Kerf `SafeHtml`. Never pass DOM nodes as children or use inline JSX event handlers.
-3. Keep state, product copy, persistence, and domain mappings in the application. Do not add product-specific actions or fields to a generic component. Put MenuItem/MenuActionRow/MenuHeader/AppTab domain `data-*` metadata in `rootAttributes`; use MenuActionRow `trailingActionAttributes` and MenuHeader `triggerAttributes` only for domain `data-*` or native popover target/action and `aria-controls`/`aria-haspopup`. These slots do not replace component-owned action, item/tab identity, selection, disclosure, naming, disabled, icon, or role semantics.
+3. Keep state, product copy, persistence, and domain mappings in the application. Do not add product-specific actions or fields to a generic component. Put ListItem/ListActionRow/ListHeader/AppTab domain `data-*` metadata in `rootAttributes`; use ListActionRow `trailingActionAttributes` and ListHeader `triggerAttributes` only for domain `data-*` or native popover target/action and `aria-controls`/`aria-haspopup`. These slots do not replace component-owned action, item/tab identity, selection, disclosure, naming, disabled, icon, or role semantics.
 4. Wire `data-action` hooks from one stable root with `delegate()` or `delegateActions()` and retain disposers.
 5. Use the opinionated `--kui-color-*` semantic ramps and component-level override properties. Override tokens at the narrowest useful scope and prefer equivalent props/tokens. Public-class-to-public-class selectors are supported when every Kerf class appears in the catalog entry's `publicClasses`; never target descendant tags, ids, attribute-only anatomy, or unlisted implementation classes.
 6. `Select` is pure until the app explicitly imports `@kerfjs/ui/select/register`; do not import Web Awesome's full registration bundle. When an app writes direct `wa-*` JSX, add `import type {} from '@kerfjs/ui/webawesome'` for the catalog-supported intrinsic-element declarations, import the CSS-only `@kerfjs/ui/webawesome.css` theme once, and keep importing individual Web Awesome component modules so their JavaScript remains tree-shakeable. The type boundary emits no code and registers nothing. Pass icon-bearing `choices` and `renderSelected` content normally: `Select` preserves its slotted option icons across Kerf rerenders and keys selected content by the controlled value, so app wrappers must not add competing morph-control attributes.
-7. Decorative icons are hidden; controls are named; focus is visible; state never relies on color alone; reduced motion and increased contrast remain usable. `DisclosureArrow` defaults to an 18px root-scaled visual and exposes `--kui-disclosure-arrow-size` for consumer sizing; it never becomes the interaction or accessible-name owner. Put it in an owning native control with a stable accessible name and controlled `aria-expanded`. `MenuHeader` toggle mode supplies it when `actionIcon` is omitted, but the app must reveal matching content; a custom icon replaces it. Author replacement icon content facing right before its configured direction transform is applied. Direction changes take the shortest rotation path, with counterclockwise chosen for a 180-degree closed-to-open tie. Kerf `Select` separately keeps its intrinsic Web Awesome expand glyph at `--kui-disclosure-icon-scale: .5`.
+7. Decorative icons are hidden; controls are named; focus is visible; state never relies on color alone; reduced motion and increased contrast remain usable. `DisclosureArrow` defaults to an 18px root-scaled visual and exposes `--kui-disclosure-arrow-size` for consumer sizing; it never becomes the interaction or accessible-name owner. Put it in an owning native control with a stable accessible name and controlled `aria-expanded`. `ListHeader` toggle mode supplies it when `actionIcon` is omitted, but the app must reveal matching content; a custom icon replaces it. Author replacement icon content facing right before its configured direction transform is applied. Direction changes take the shortest rotation path, with counterclockwise chosen for a 180-degree closed-to-open tie. Kerf `Select` separately keeps its intrinsic Web Awesome expand glyph at `--kui-disclosure-icon-scale: .5`.
 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.
@@ -63,7 +63,7 @@ Hard rules:
 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. 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.
+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: `ListHeader` fills the available inline width and keeps its label and mutually exclusive semantic count or non-count `badge` together, with an independent logical-end 44px action unless disclosure mode makes the title cluster the button. Its action visual defaults to 18px through `--kui-list-header-action-icon-size`; never shrink the target to match it. Pass every non-negative safe-integer section quantity through `count` with a localized full spoken `countLabel`; never concatenate it into `label` or put a number in `badge`. `ListItem.trailing` is dormant; use `ListActionRow` when primary and trailing actions need sibling 44px native buttons. Its `label`, `icon`, and `trailingActionIcon` slots are also dormant and cannot contain controls. Let panes relocate at narrow widths instead of shrinking targets.
 17. 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 `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.
@@ -77,17 +77,17 @@ Common mistakes:
 | Hard-coded project/transport action in a component | Pass a semantic `data-action` string from an application adapter |
 | Per-instance signal at module scope | Create state in the application or a factory and pass it in |
 | `role="menuitem"` on one button | Use the native button, or implement the complete ARIA menu widget |
-| Put a button/link/interactive role in `MenuItem.trailing` or a `MenuActionRow` SafeHtml slot | Use `MenuActionRow` for the sibling controls and keep its label/icon slots dormant |
-| Copy MenuItem/MenuHeader markup to add product data or a popover target | Use the typed `rootAttributes`/`triggerAttributes` slots and retain the component's protected semantics |
-| Concatenate a section count into a MenuHeader label or numeric badge | Pass `count={value}` and a localized full phrase such as `countLabel="3 notes"`; reserve `badge` for non-count SafeHtml |
-| Put a chevron on navigation that reveals nothing | Remove it, or model a real controlled `MenuHeader` disclosure; omit `actionIcon` to use the production `DisclosureArrow` |
+| Put a button/link/interactive role in `ListItem.trailing` or a `ListActionRow` SafeHtml slot | Use `ListActionRow` for the sibling controls and keep its label/icon slots dormant |
+| Copy ListItem/ListHeader markup to add product data or a popover target | Use the typed `rootAttributes`/`triggerAttributes` slots and retain the component's protected semantics |
+| Concatenate a section count into a ListHeader label or numeric badge | Pass `count={value}` and a localized full phrase such as `countLabel="3 notes"`; reserve `badge` for non-count SafeHtml |
+| Put a chevron on navigation that reveals nothing | Remove it, or model a real controlled `ListHeader` disclosure; omit `actionIcon` to use the production `DisclosureArrow` |
 | Test only a custom-element attribute | Assert live property, emitted event, focus, and rendered output |
 | Import all Web Awesome components | Import only `@kerfjs/ui/select/register` for `Select`, or individual Web Awesome modules for other controls; `webawesome.css` registers no JavaScript |
 | Write `wa-*` JSX without activating its types | Add `import type {} from '@kerfjs/ui/webawesome'`; registration and theme imports remain separate |
 | Maintain a root list of component styles | Import each visual component from its JS subpath; its reachable CSS follows automatically |
 | Add demo-only markup for a production state | Add the state to the production component, then render that export in the catalog |
 | Choose a listed ecosystem component by default | Apply the component-selection guidance above; catalog coverage means supported and themed, not preferred |
-| Add sidebar-specific wrapper padding | Use the unpadded `.kui-pane`; let `MenuHeader`, `MenuItem`, and `.kui-content-item` own their 8/1/8 geometry |
+| Add sidebar-specific wrapper padding | Use the unpadded `.kui-pane`; let `ListHeader`, `ListItem`, and `.kui-content-item` own their 8/1/8 geometry |
 | Put bare text or controls directly in a toolbar slot | Wrap every item in `ToolbarControlGroup`, using `appearance="borderless"` for transparent chrome |
 | 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 |

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.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.
+Generated from the emitted `@kerfjs/ui@5.0.0-beta.9` 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/list-action-row.js

@@ -0,0 +1,4 @@
+import '../styles/foundation.css';
+import '../styles/skeleton.css';
+import '../styles/list-action-row.css';
+export * from '../list-action-row.js';

package/dist/browser/{menu-header.js → list-header.js}

@@ -2,5 +2,5 @@ import '../styles/foundation.css';
 import '../styles/lucide-icon.css';
 import '../styles/disclosure-arrow.css';
 import '../styles/skeleton.css';
-import '../styles/menu-header.css';
-export * from '../menu-header.js';
+import '../styles/list-header.css';
+export * from '../list-header.js';

package/dist/browser/{menu-item.js → list-item.js}

@@ -1,4 +1,4 @@
 import '../styles/foundation.css';
 import '../styles/skeleton.css';
-import '../styles/menu-item.css';
-export * from '../menu-item.js';
+import '../styles/list-item.css';
+export * from '../list-item.js';

package/dist/catalog.d.ts

@@ -0,0 +1,119 @@
+import { SafeHtml } from 'kerfjs';
+
+/** A reference link shown in the detail footer for the active entry. */
+interface CatalogResource {
+    label: string;
+    href: string;
+    /** Optional monospace detail (e.g. a file path) shown after the label. */
+    detail?: string;
+}
+/** A related entry offered in the detail footer's "Related" selector. */
+interface CatalogRelated {
+    id: string;
+    name: string;
+    /** Group heading in the selector, e.g. "Uses" / "Used by". */
+    group: string;
+}
+interface CatalogEntry {
+    id: string;
+    name: string;
+    description?: string;
+    resources?: readonly CatalogResource[];
+    related?: readonly CatalogRelated[];
+}
+interface CatalogSection {
+    category: string;
+    entries: readonly CatalogEntry[];
+}
+/**
+ * A secondary group of sections shown below the primary sidebar sections with a
+ * quieter "ecosystem" treatment (e.g. third-party components). Optionally
+ * collapsible — the app owns `expanded` and toggles it from `wireCatalog`'s
+ * `onToggleSecondary`.
+ */
+interface CatalogSecondaryGroup {
+    label: string;
+    sections: readonly CatalogSection[];
+    /** When true, the group's label is a disclosure toggle controlling `expanded`. */
+    collapsible?: boolean;
+    /** Whether the group is expanded (controlled). Ignored unless `collapsible`. */
+    expanded?: boolean;
+}
+interface CatalogBrand {
+    title: string;
+    subtitle?: string;
+    /** Logo image URL (rendered decorative). Omit for a text-only brand. */
+    logoUrl?: string;
+}
+interface CatalogProps {
+    brand: CatalogBrand;
+    sections: readonly CatalogSection[];
+    /** The controlled active entry id — the app owns this signal. */
+    active: string;
+    /** The rendered preview for the active entry; the app computes it from `active`. */
+    content: SafeHtml;
+    /** Whether the sidebar is collapsed (controlled). */
+    collapsed?: boolean;
+    /** Current theme; when set, a theme toggle is shown that switches to the opposite. Omit to hide it. */
+    theme?: 'light' | 'dark';
+    /** Extra header controls placed before the theme toggle (each a `ToolbarControlGroup`). */
+    headerActions?: SafeHtml;
+    /** A secondary "ecosystem" group of sections below the primary category groups. */
+    secondarySections?: CatalogSecondaryGroup;
+    /** Extra sidebar content below the category groups (and the secondary group). */
+    sidebarFooter?: SafeHtml;
+    /** Status line content shown at the start of the detail footer. */
+    status?: SafeHtml;
+    selectAction?: string;
+    toggleSidebarAction?: string;
+    toggleThemeAction?: string;
+    /** Action fired by the secondary group's disclosure toggle (when collapsible). */
+    toggleSecondaryAction?: string;
+    className?: string;
+}
+/**
+ * A reusable component-catalog shell: a collapsible category sidebar, a titled
+ * detail stage that renders the active entry's preview, and a footer with
+ * reference links and a related-entry selector. Built entirely from public
+ * `@kerfjs/ui` primitives. Controlled and stateless — the app owns the `active`,
+ * `collapsed`, and `theme` signals and computes `content` from `active` in its own
+ * render; wire the sidebar/collapse/theme actions with `wireCatalog`.
+ */
+declare function Catalog({ brand, sections, active, content, collapsed, theme, headerActions, secondarySections, sidebarFooter, status, selectAction, toggleSidebarAction, toggleThemeAction, toggleSecondaryAction, className, }: CatalogProps): SafeHtml;
+/**
+ * How a {@link CatalogExample}'s content aligns its visible left edge with the
+ * example's `ListHeader` label (which sits 16px in — 8px title + 8px label):
+ * - `'glyph'` — a bare glyph/text specimen with no inline geometry insets the full 16px.
+ * - `'inline-control'` — a control that already carries ~8px of its own inline padding insets 8px so its content lands on the same line.
+ * - `'none'` — a content-item / composition that owns its geometry and already aligns; no inset (default).
+ */
+type CatalogExampleAlign = 'glyph' | 'inline-control' | 'none';
+interface CatalogExampleProps {
+    /** The example's label, shown as a `ListHeader` above the specimen. Omit for a bare specimen. */
+    label?: string;
+    /** Optional explanatory note between the label and the specimen. */
+    note?: SafeHtml | string;
+    /** Alignment inset for the specimen — see {@link CatalogExampleAlign}. Default `'none'`. */
+    align?: CatalogExampleAlign;
+    className?: string;
+    children?: SafeHtml | readonly SafeHtml[];
+}
+/**
+ * One labeled example in a catalog preview: a `ListHeader` label, an optional
+ * note, and the specimen. `align` insets the specimen so its visible left edge
+ * lines up with the label text, encoding the catalog's alignment rules as a
+ * first-class prop instead of per-demo CSS. The inset is published as the
+ * `--kui-catalog-example-align` custom property so a debug overlay can exclude it
+ * from a specimen's measured margin.
+ */
+declare function CatalogExample({ label, note, align, className, children }: CatalogExampleProps): SafeHtml;
+interface CatalogExampleStackProps {
+    /** Accessible label for the stack region. */
+    label?: string;
+    className?: string;
+    children?: SafeHtml | readonly SafeHtml[];
+}
+/** A vertically-stacked group of {@link CatalogExample}s with the catalog's example rhythm. */
+declare function CatalogExampleStack({ label, className, children }: CatalogExampleStackProps): SafeHtml;
+
+export { Catalog, type CatalogBrand, type CatalogEntry, CatalogExample, type CatalogExampleAlign, type CatalogExampleProps, CatalogExampleStack, type CatalogExampleStackProps, type CatalogProps, type CatalogRelated, type CatalogResource, type CatalogSecondaryGroup, type CatalogSection };