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

package/docs/catalog.md

@@ -0,0 +1,154 @@
+# Catalog — a reusable component-gallery shell
+
+`@kerfjs/ui/catalog` is an opt-in, whole-screen shell for building a **component
+catalog** — the collapsible category sidebar + titled preview stage + resources
+footer that the kerf UI catalog itself uses. Point it at your own components and
+you get the same shell without rebuilding it. Like the app layouts, it is a
+subpath-only, tree-shakeable module that adds nothing to the main barrel.
+
+```bash
+npm install @kerfjs/ui   # kerfjs is a peer; @kerfjs/ui/select/register is needed only if entries use `related`
+```
+
+- `Catalog(props)` returns the shell as `SafeHtml` (a `<main class="kui-catalog">`).
+  It is **controlled and stateless**: your app owns the `active`, `collapsed`, and
+  `theme` signals and computes the preview `content` from `active` in its own
+  `mount()` render.
+- `wireCatalog(root, options)` wires the interactions (sidebar selection, the
+  related-entry selector, and the collapse/theme toggles) with one delegated
+  listener set and returns a disposer; it can also mirror the active id into the
+  URL.
+
+## What you supply
+
+- **`sections`** — category-grouped entries: `{ category, entries: [{ id, name,
+  description?, resources?, related? }] }`. Each entry becomes a sidebar `ListItem`
+  under a `ListHeader` for its category.
+- **`content`** — the rendered preview for the active entry. Keep a map of `id →
+  () => SafeHtml` in your app and call `renderers[active]()` in your render.
+- **`brand`** — `{ title, subtitle?, logoUrl? }` for the sidebar header.
+- **`secondarySections`** — an optional secondary "ecosystem" group shown below the
+  primary sections with a quieter treatment: `{ label, sections, collapsible?,
+  expanded? }`. When `collapsible`, the label is a disclosure toggle controlling
+  `expanded` (the app owns it; wire it with `wireCatalog`'s `onToggleSecondary`).
+- Optional slots: `headerActions` (extra header controls), `sidebarFooter` (extra
+  sidebar content), and `status` (a footer status line).
+
+Per-entry `resources` render as "open in new tab" links in the footer, and
+`related` renders a "Related entries" selector (a `Select`, so register it with
+`@kerfjs/ui/select/register` when you use it).
+
+## Preview examples
+
+Compose each entry's `content` from `CatalogExample` (and `CatalogExampleStack`)
+instead of hand-rolled example markup, so labels, notes, and left-edge alignment
+stay consistent:
+
+```tsx
+import { CatalogExample, CatalogExampleStack } from '@kerfjs/ui/catalog';
+
+const buttonPreview = (
+  <CatalogExampleStack label="Button variants">
+    <CatalogExample label="Icon" note="A bare glyph." align="glyph">
+      <LucideIcon icon={Plus} name="plus" />
+    </CatalogExample>
+    <CatalogExample label="Control" align="inline-control">
+      <SegmentedControl id="view" label="View" value="list" choices={choices} />
+    </CatalogExample>
+    <CatalogExample label="In composition">
+      <ValueTable label="Metadata">{rows}</ValueTable>
+    </CatalogExample>
+  </CatalogExampleStack>
+);
+```
+
+`label` is optional — omit it for a bare specimen with no `ListHeader`. `align`
+lines a specimen's visible left edge up with its label text: `'glyph'`
+(16px) for a bare glyph/text specimen, `'inline-control'` (8px) for a control that
+already carries ~8px of its own inline padding, and `'none'` (the default) for a
+content-item/composition that already owns its geometry. 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.
+
+## Complete example
+
+```tsx
+import { mount, signal } from 'kerfjs';
+import { Catalog, type CatalogSection } from '@kerfjs/ui/catalog';
+import { wireCatalog } from '@kerfjs/ui/wire-catalog';
+import '@kerfjs/ui/styles.css'; // or import each primitive's CSS + @kerfjs/ui/catalog.css
+
+// 1. Describe your components once.
+const sections: CatalogSection[] = [
+  {
+    category: 'Controls',
+    entries: [
+      { id: 'button', name: 'Button', description: 'A pressable control.',
+        resources: [{ label: 'Source', href: '/src/button.tsx', detail: 'src/button.tsx' }] },
+      { id: 'field', name: 'Field', description: 'A labeled input.',
+        related: [{ id: 'button', name: 'Button', group: 'Used with' }] },
+    ],
+  },
+  { category: 'Feedback', entries: [{ id: 'toast', name: 'Toast', description: 'A transient message.' }] },
+];
+
+// 2. One preview render per entry id.
+const renderers: Record<string, () => ReturnType<typeof Button>> = {
+  button: () => <Button label="Save" />,
+  field: () => <Field label="Name" />,
+  toast: () => <Toast>Saved</Toast>,
+};
+
+// 3. App-owned state (domain: which entry; transient: collapsed; global: theme).
+const initial = new URLSearchParams(location.search).get('c') ?? sections[0].entries[0].id;
+const active = signal(initial);
+const collapsed = signal(false);
+const theme = signal<'light' | 'dark'>('light');
+
+const app = document.getElementById('app')!;
+mount(app, () => (
+  <Catalog
+    brand={{ title: 'Acme UI', subtitle: 'Design system' }}
+    sections={sections}
+    active={active.value}
+    content={renderers[active.value]?.() ?? <></>}
+    collapsed={collapsed.value}
+    theme={theme.value}
+  />
+));
+
+wireCatalog(app, {
+  onSelect: (id) => { active.value = id; },
+  onToggleSidebar: () => { collapsed.value = !collapsed.value; },
+  onToggleTheme: () => {
+    theme.value = theme.value === 'dark' ? 'light' : 'dark';
+    document.documentElement.dataset.theme = theme.value; // apply your theme however you like
+  },
+  urlParam: 'c', // mirror the active id into ?c=<id>
+});
+```
+
+## Ownership boundary
+
+`Catalog` renders the shell; the app owns everything stateful:
+
+- **`active`** is domain state (which entry is shown) — the app's signal, updated in
+  `onSelect`, read to compute `content`.
+- **`collapsed`** is transient UI — the app's signal, flipped in `onToggleSidebar`.
+- **`theme`** is a global preference — the app's signal; `wireCatalog` only reports
+  the toggle, the app applies the theme (the shell reads `theme` to show the toggle's
+  opposite-state label). Omit `theme` to hide the toggle entirely.
+
+## Custom action names
+
+The shell emits `data-action="catalog-select"` (sidebar items),
+`catalog-toggle-sidebar`, and `catalog-toggle-theme`. Override them with
+`selectAction` / `toggleSidebarAction` / `toggleThemeAction` on `Catalog` (and the
+matching options on `wireCatalog`) if they collide with your own action table.
+
+## CSS
+
+`Catalog` composes public primitives (`Toolbar`, `ListHeader`, `ListItem`, `Select`,
+…). Import `@kerfjs/ui/styles.css` for the whole layer, or `@kerfjs/ui/catalog.css`
+plus each composed primitive's CSS. The shell is theme-aware and responsive: it
+stacks the sidebar above the detail below ~832px and hides it when collapsed.

package/docs/component-contract.md

@@ -26,11 +26,11 @@ remains authored rather than generated.
 - A reusable component never owns per-instance mutable module state.
 - Consumers style through `--kui-*` semantic tokens and public component classes. Foundation tokens provide opinionated neutral, brand/info, success, warning, and danger fill/border/foreground roles. Stateful components expose local override variables; prefer an equivalent prop or token before writing a selector.
 
-`MenuItem.rootAttributes`, `MenuActionRow.rootAttributes`,
-`MenuHeader.rootAttributes`, and `AppTab.rootAttributes` accept
+`ListItem.rootAttributes`, `ListActionRow.rootAttributes`,
+`ListHeader.rootAttributes`, and `AppTab.rootAttributes` accept
 application-owned `data-*` metadata without
-adding product fields to the shared API. A `MenuActionRow` trailing action uses
-`trailingActionAttributes`, and a `MenuHeader` action/disclosure uses
+adding product fields to the shared API. A `ListActionRow` trailing action uses
+`trailingActionAttributes`, and a `ListHeader` action/disclosure uses
 `triggerAttributes`, for `data-*`, native popover target/action attributes, and
 the corresponding `aria-controls`/`aria-haspopup` relationship. These slots do
 not accept roles or component-owned action, selection, disclosure, accessible
@@ -46,10 +46,10 @@ component continues to own the named close button or focusable separator, and
 `wireTabBars()` / `wireResizableRegions()` continue to own transient behavior
 and disposal.
 
-`MenuItem.trailing`, `MenuActionRow.label`, `MenuActionRow.icon`, and
-`MenuActionRow.trailingActionIcon` are dormant SafeHtml slots. They must not
+`ListItem.trailing`, `ListActionRow.label`, `ListActionRow.icon`, and
+`ListActionRow.trailingActionIcon` are dormant SafeHtml slots. They must not
 contain controls. When a row needs an independently interactive trailing
-region, `MenuActionRow` owns the noninteractive root and the two sibling native
+region, `ListActionRow` owns the noninteractive root and the two sibling native
 buttons; the application owns their delegated behavior and controlled state.
 Both row components align a leading icon with the first label line when
 `multiline` allows the label to wrap; additional lines extend below that fixed
@@ -67,7 +67,7 @@ ownership to the application.
 
 Do not select a component's descendant by element name, id, attribute alone, or
 an unlisted implementation class. Selectors such as `.kui-state-banner span`,
-`.kui-menu-item [data-state]`, and `.kui-menu-item .local-label` depend on
+`.kui-list-item [data-state]`, and `.kui-list-item .local-label` depend on
 private structure. If no prop, token, or cataloged class expresses a recurring
 need, request a supported hook instead of inferring one from rendered markup.
 
@@ -78,13 +78,13 @@ glyph contract, `--kui-disclosure-icon-scale: .5`; changing one contract does
 not implicitly change the other. Direction changes take the shortest rotation
 path; a 180-degree closed-to-open tie uses counterclockwise rotation.
 
-In `MenuHeader` toggle mode, omitting `actionIcon` composes the production
+In `ListHeader` toggle mode, omitting `actionIcon` composes the production
 `DisclosureArrow` and derives its visual direction from `expanded`. The app
 must update that controlled state and reveal or hide real content. Passing a
 custom `actionIcon` replaces the default rather than layering or rotating both.
 The root fills the available inline width after its standard margins. A
 separate action stays at the logical end in its 44px target while the visible
-glyph defaults to 18px through `--kui-menu-header-action-icon-size`.
+glyph defaults to 18px through `--kui-list-header-action-icon-size`.
 
 `StateBanner` exposes instance-level `--kui-state-banner-background`,
 `--kui-state-banner-border`, `--kui-state-banner-foreground`,
@@ -113,7 +113,7 @@ changing geometry. `.kui-content-item--pill` selects the 22px radius.
 
 `ToolbarControlGroup` is the unit of toolbar organization, even for dormant
 text. Each group reserves `calc(2px + remify(42px))`, or 44px, with 8px between
-groups and inside items. `MenuHeader` similarly separates its dormant title and
+groups and inside items. `ListHeader` similarly separates its dormant title and
 optional count or badge from its optional 44px action. Use the mutually
 exclusive `count`/`countLabel` pair for non-negative safe-integer section
 quantities; reserve `badge` for non-count `SafeHtml`. Do not concatenate counts
@@ -172,7 +172,7 @@ and tab order are data, a `ResizableRegion`'s committed size and a
 Each helper already owns only the *ephemeral mechanics* around that state —
 `wireNavStack` the push/pop animation, `wireTabBars` the overflow autoscroll and
 drag preview, `wireResizableRegions` the live drag preview — and reports committed
-changes through callbacks. A `MenuHeader` `toggle` disclosure's `expanded` is
+changes through callbacks. A `ListHeader` `toggle` disclosure's `expanded` is
 likewise app-owned: it is a one-line boolean the app already tracks and must read to
 render the section body, so a managed helper would remove no real complexity. Reach
 for a managed default only when the transient behavior is substantial enough that

package/docs/component-selection.md

@@ -34,11 +34,12 @@ application boundary:
 | Desktop application shell | [Catalog](../ux-demo/) · `?component=recipe-app-shell` |
 | Navigation sidebar | [Catalog](../ux-demo/) · `?component=recipe-navigation-sidebar` |
 | Workspace header | [Catalog](../ux-demo/) · `?component=recipe-workspace-header` |
-| Master-detail dialog | [Catalog](../ux-demo/) · `?component=recipe-master-detail-dialog` |
+| List-detail dialog | [Catalog](../ux-demo/) · `?component=recipe-list-detail-dialog` |
 | Composer form | [Catalog](../ux-demo/) · `?component=recipe-composer-form` |
 | List workspace states | [Catalog](../ux-demo/) · `?component=recipe-list-workspace-states` |
 | Compact toolbar choices and actions | [Catalog](../ux-demo/) · `?component=recipe-compact-toolbar` |
 | Navigation stack | [Catalog](../ux-demo/) · `?component=recipe-navigation-stack` |
+| Loading inspector | [Catalog](../ux-demo/) · `?component=recipe-loading-inspector` |
 
 Recipes use public production exports and show ownership boundaries; they are
 copyable reference compositions, not new monolithic components.
@@ -63,18 +64,18 @@ an upstream component or recipe request.
 | Application toolbar — `Toolbar` | Leading identity, optional centered content, and trailing controls form one horizontal app bar. | Do not use it for a page, panel, or dialog heading; use `PanelHeader`. | Compose `ToolbarText` and `ToolbarControlGroup` where their contracts fit. | Actions, command availability, responsive relocation, and state. | `@kerfjs/ui/toolbar` | [Toolbar composition](../README.md#component-subpaths) |
 | Toolbar control cluster — `ToolbarControlGroup` | Related toolbar controls need contained, borderless, pressed, or single-control treatment. | Do not use it merely to align unrelated buttons; use toolbar slots or ordinary layout. Web Awesome `wa-button-group` is only for an exceptional grouped-action contract. | Delegate child actions; use `SegmentedControl` for an exclusive choice. | Actions, pressed/expanded state, and policy. | `@kerfjs/ui/toolbar-control-group` | [Component ownership](./component-contract.md#ownership-boundaries) |
 | Toolbar identity text — `ToolbarText` | A toolbar needs extra-large (page/panel title), large, default, or compact textual identity. | Plain text is not a heading by default; when a title needs heading semantics pass `headingLevel` (or prefer `PanelHeader`, which forwards it). | Optional `headingLevel` for `role="heading"` + `aria-level`. | Text, heading level, and responsive priority. | `@kerfjs/ui/toolbar-text` | [Toolbar composition](../README.md#component-subpaths) |
-| Navigation row — `MenuItem` | A pane or navigation area needs a selectable, disabled, dormant-trailing, or multiline action row. | Do not put a control in `trailing`; use `MenuActionRow` when the trailing region must be independently interactive. Use an `<a>` for navigation that must retain link behavior, a native `<button>` for an ordinary action, or implement the complete ARIA menu widget. | Delegate its `data-action`; compose inside a `.kui-content` section. Put domain event/drop metadata in `rootAttributes` rather than adding wrapper markup. | Routing, selection, permissions, copy, action handling, and domain `data-*` values. | `@kerfjs/ui/menu-item` | [Pane geometry](../README.md#pane-and-content-geometry) |
-| Navigation row with trailing action — `MenuActionRow` | A full-width row needs a selectable primary action and an independently focusable trailing action. | Use `MenuItem` when trailing content is dormant metadata. Do not put controls inside the row's `label`, `icon`, or `trailingActionIcon` SafeHtml slots. Do not use `AppTab` outside tablist semantics or `ToolbarControlGroup` outside a toolbar. | Delegate both action strings; update controlled selection and any popover/context-menu state in the app. | Routing, selection, both action policies, domain metadata, and popover/context-menu behavior. | `@kerfjs/ui/menu-action-row` | [Accessibility](./accessibility.md#menuactionrow) |
-| Navigation section heading — `MenuHeader` | A menu section needs a full-width label, semantic count, non-count badge, logical-end action, or real disclosure state. | Do not concatenate counts into `label` or put numeric content in `badge`; use `count` with the localized full phrase in `countLabel`. Do not add a disclosure arrow to navigation that reveals nothing. Do not shrink its 44px action target to the 18px visual. Do not use it as a page, panel, or dialog title; use `PanelHeader`. | Delegate its optional action; the app controls expanded state and revealed content. Toggle mode supplies `DisclosureArrow` unless `actionIcon` replaces it. Use `triggerAttributes` only for domain `data-*` or a native popover relationship. | Section organization, valid count and localized count label, disclosure state and content, non-count badge content, popover target behavior, and policy. | `@kerfjs/ui/menu-header` | [Pane geometry](../README.md#pane-and-content-geometry) |
+| Navigation row — `ListItem` | A pane or navigation area needs a selectable, disabled, dormant-trailing, or multiline action row. | Do not put a control in `trailing`; use `ListActionRow` when the trailing region must be independently interactive. Use an `<a>` for navigation that must retain link behavior, a native `<button>` for an ordinary action, or implement the complete ARIA menu widget. | Delegate its `data-action`; compose inside a `.kui-content` section. Put domain event/drop metadata in `rootAttributes` rather than adding wrapper markup. | Routing, selection, permissions, copy, action handling, and domain `data-*` values. | `@kerfjs/ui/list-item` | [Pane geometry](../README.md#pane-and-content-geometry) |
+| Navigation row with trailing action — `ListActionRow` | A full-width row needs a selectable primary action and an independently focusable trailing action. | Use `ListItem` when trailing content is dormant metadata. Do not put controls inside the row's `label`, `icon`, or `trailingActionIcon` SafeHtml slots. Do not use `AppTab` outside tablist semantics or `ToolbarControlGroup` outside a toolbar. | Delegate both action strings; update controlled selection and any popover/context-menu state in the app. | Routing, selection, both action policies, domain metadata, and popover/context-menu behavior. | `@kerfjs/ui/list-action-row` | [Accessibility](./accessibility.md#listactionrow) |
+| Navigation section heading — `ListHeader` | A menu section needs a full-width label, semantic count, non-count badge, logical-end action, or real disclosure state. | Do not concatenate counts into `label` or put numeric content in `badge`; use `count` with the localized full phrase in `countLabel`. Do not add a disclosure arrow to navigation that reveals nothing. Do not shrink its 44px action target to the 18px visual. Do not use it as a page, panel, or dialog title; use `PanelHeader`. | Delegate its optional action; the app controls expanded state and revealed content. Toggle mode supplies `DisclosureArrow` unless `actionIcon` replaces it. Use `triggerAttributes` only for domain `data-*` or a native popover relationship. | Section organization, valid count and localized count label, disclosure state and content, non-count badge content, popover target behavior, and policy. | `@kerfjs/ui/list-header` | [Pane geometry](../README.md#pane-and-content-geometry) |
 | Application layout composition | A sidebar, main area, inspector, or dialog needs shared toolbar/content/footer and child geometry. | Do not pad the pane shell, wrap child-owned geometry in competing insets, invent unrelated centered measures, or leave an icon-only rail for a hidden pane. | Use `.kui-pane` and one `.kui-pane__content`; add `.kui-content` and `.kui-content-item` as needed. A visible pane owns collapse in its toolbar; move a hidden inline-start pane's restore control to the main toolbar leading edge and an inline-end pane's restore control to its trailing edge. | Layout hierarchy, reading width, scroll ownership, responsive relocation, and pane visibility state. | `@kerfjs/ui/layout.css` | [Pane anatomy](./layout.md#anatomy) |
-| Menu composition | Navigation sections need full-size rows and the same content-item geometry as every other pane. | Do not add sidebar-specific wrapper padding, shrink targets to icon size, nest an interactive trailing control in `MenuItem`, or use a chevron on a row that does not disclose content. Use ordinary links for a different navigation contract. | Compose `MenuHeader`, `MenuItem`, and `MenuActionRow` in `.kui-content`; use `MenuHeader` toggle mode with real controlled content, and use `.kui-content-item` for other surfaces plus a pane footer for toolbar actions. | Information architecture, disclosure content and state, responsive drawer/shell behavior, and token overrides. | `@kerfjs/ui/layout.css` | [Pane geometry](../README.md#pane-and-content-geometry) |
+| Menu composition | Navigation sections need full-size rows and the same content-item geometry as every other pane. | Do not add sidebar-specific wrapper padding, shrink targets to icon size, nest an interactive trailing control in `ListItem`, or use a chevron on a row that does not disclose content. Use ordinary links for a different navigation contract. | Compose `ListHeader`, `ListItem`, and `ListActionRow` in `.kui-content`; use `ListHeader` toggle mode with real controlled content, and use `.kui-content-item` for other surfaces plus a pane footer for toolbar actions. | Information architecture, disclosure content and state, responsive drawer/shell behavior, and token overrides. | `@kerfjs/ui/layout.css` | [Pane geometry](../README.md#pane-and-content-geometry) |
 | Resizable application pane — `ResizableRegion`, `clampRegionSize`, `resizeRegionFromPointer` | A controlled split pane needs the Kerf separator, collapse state, pointer plus keyboard resizing, or a product-specific decorative grip. | Do not use it for a static two-column layout; use CSS grid. Prefer it over Web Awesome `wa-split-panel` unless that component's distinct API is required. Keep `handleIcon` noninteractive. | Call `wireResizableRegions` from `@kerfjs/ui/wire-resizable-regions` once and retain its disposer. | Size signal, min/max policy, collapse policy, persistence, and optional decorative handle icon. | `@kerfjs/ui/resizable-region` | [ResizableRegion contract](./accessibility.md#resizableregion) |
 | One application tab — `AppTab` | A controlled app tab needs selection, close, drag, leading/trailing anatomy, safe domain metadata, or a product-specific close glyph. | Do not render it alone or use it for a small settings choice; compose in `TabBar`, or use `SegmentedControl`. Keep `closeIcon` noninteractive. | Compose in `TabBar`; let `wireTabBars` manage interaction. Put only domain `data-*` values in `rootAttributes`. | Tab identity, order, selection, close policy, content, and domain metadata values. | `@kerfjs/ui/app-tab` | [Tabs contract](./accessibility.md#tabs) |
 | Application tab strip — `TabBar`, `wireTabBars`, `reorderTabs` | Tabs switch page regions and may overflow, close, or reorder. | Do not use it for a compact local view toggle; use `SegmentedControl`. Do not use it for a long choice list; use `Select`. Prefer it over Web Awesome `wa-tab-group`, `wa-tab`, and `wa-tab-panel` for Kerf app tabs. | Call `wireTabBars` once, retain the disposer, and apply `onReorder` synchronously; `reorderTabs` is the default array helper. | Ordered tabs, selection, panels, routing, closing, and persistence. | `@kerfjs/ui/tab-bar` plus `@kerfjs/ui/wire-tab-bars` | [Tabs contract](./accessibility.md#tabs) |
 | Panel, dialog, or page heading — `PanelHeader` | A panel, dialog, or page needs a heading with an extra-large title, an optional icon and subtitle, and trailing actions. | Do not use it as persistent app chrome; use `Toolbar`. It supplies header structure, not modal behavior; use an application overlay or Web Awesome `wa-dialog` for that behavior. | Connect the title id and any provided summary id to the dialog or panel host, pass the trailing controls (typically a `ToolbarControlGroup`), and delegate their actions. **For a page or view title set `headingLevel` (usually `1`)** so the title is a real heading landmark (`role="heading"` + `aria-level`) for screen-reader heading navigation; omit it for a dialog title, which is referenced via `aria-labelledby` to `titleId` and needs no heading. | Open state, focus lifecycle, dismissal, the trailing controls, labels, copy, and the heading level for page use. | `@kerfjs/ui/panel-header` | [Header ownership](./component-contract.md#extracted-versus-application-specific) |
 | Key/value facts — `ValueTable`, `ValueTableRow` | Read-only labels and values form a semantic definition list, optionally with a leading icon. | Do not use it for editable form fields or a row/column data grid; use native form or table semantics. | Compose typed `ValueTableRow` entries; pass `icon` when a 24px leading icon adds useful context. | Values, formatting, icon meaning, and empty/loading policy. | `@kerfjs/ui/value-table` | [Component ownership](./component-contract.md#ownership-boundaries) |
 | Indeterminate activity — `LoadingSpinner` | A Kerf surface needs compact, labeled or decorative indeterminate progress. | Do not use it for known progress; use Web Awesome `wa-progress-bar` or `wa-progress-ring`. Direct Web Awesome UI may use `wa-spinner`; do not mix spinner systems within one surface. | None; pass a label when the spinner conveys status. | Loading lifecycle and adjacent status copy. | `@kerfjs/ui/loading-spinner` | [Accessibility](./accessibility.md#shared-rules) |
-| Loading placeholder — `Skeleton` + a component's `placeholder` prop | A value or a whole component is still loading and should hold its space as a subtle, unanimated block, keeping the layout stable — an inspector or detail view rendering its real chrome with per-record values absent. | Do not use it for known progress (use `LoadingSpinner`), do not animate it, and do not hand-rebuild a component's empty state — set `placeholder` on the component instead. Prefer it over `wa-skeleton`, which the pure-Kerf primitives avoid to stay Web-Awesome-free. | Set `placeholder` on a value-bearing component (`Select`, `MenuHeader`, `MenuItem`, `ValueTableRow`, `PanelHeader`, `SegmentedControl`, `StateBanner`, `AppTab`, `ToolbarText`, `MenuActionRow`) to render skeletons in its value slots with interactivity disabled; use the standalone `Skeleton` for a custom slot. | Loading lifecycle, which slots are unknown, and announcing the loading region. | `@kerfjs/ui/skeleton` | [Accessibility](./accessibility.md#shared-rules) |
+| Loading placeholder — `Skeleton` + a component's `placeholder` prop | A value or a whole component is still loading and should hold its space as a subtle, unanimated block, keeping the layout stable — an inspector or detail view rendering its real chrome with per-record values absent. | Do not use it for known progress (use `LoadingSpinner`), do not animate it, and do not hand-rebuild a component's empty state — set `placeholder` on the component instead. Prefer it over `wa-skeleton`, which the pure-Kerf primitives avoid to stay Web-Awesome-free. | Set `placeholder` on a value-bearing component (`Select`, `ListHeader`, `ListItem`, `ValueTableRow`, `PanelHeader`, `SegmentedControl`, `StateBanner`, `AppTab`, `ToolbarText`, `ListActionRow`) to render skeletons in its value slots with interactivity disabled; use the standalone `Skeleton` for a custom slot. | Loading lifecycle, which slots are unknown, and announcing the loading region. | `@kerfjs/ui/skeleton` | [Accessibility](./accessibility.md#shared-rules) |
 | Value selection — `Select` | A controlled form value comes from a moderate or long choice list, possibly grouped or icon-bearing. | Do not use it for commands; use a real action menu. Do not use it for a small visible choice set; use `SegmentedControl`. Prefer it over direct `wa-select`, `wa-option`, or value-like `wa-dropdown`/`wa-dropdown-item` composition. | Import `@kerfjs/ui/select/register` once; listen for standard input/change events. | Controlled value, validation, choices, and domain mapping. | `@kerfjs/ui/select` | [Web Awesome integration](../README.md#web-awesome-theme) |
 | Small exclusive choice — `SegmentedControl` | A few visible choices switch a compact view or setting, with toolbar, rounded, or pill presentation. | Do not use it for tabpanel semantics; use `TabBar`. Do not use it for many choices; use `Select`. Prefer it over `wa-button-group` when the controls select one value. | Delegate its action, read `data-segment-value`, update `value`, and rerender. | Controlled value, labels, action, and persistence. | `@kerfjs/ui/segmented-control` | [SegmentedControl contract](./accessibility.md#segmentedcontrol) |
 | Structured search editor — `TokenSearchField`, `readTokenSearchField`, `placeTokenSearchCaret`, `wireTokenSearchFields` | Free text and ordered, editable, removable filter tokens share one searchbox; enable `collapsible` when an empty, unfocused field should reduce to one iconic action, standalone or in a toolbar group. | Do not use it for ordinary text entry; use a native input or Web Awesome `wa-input`. Do not use it when filters belong in separate form controls. | Read DOM-owned text on input, empty `textContent` on clear, and use `placeTokenSearchCaret` after explicit controlled focus changes. Call `wireTokenSearchFields` from `@kerfjs/ui/wire-token-search-fields` once so Enter submits without adding a line break and keyboard chip deletion restores focus plus the text-relative caret after controlled replacement. In `collapsible` mode it also 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 signal on the returned handle (`handle.expanded(id)`) or adopt your own via `collapsible.signals`, and opt out per behavior only when the app must own it. | Parsing, suggestions, tokens, query execution, results, announcements, and — only if overriding the default — the collapsible `expanded` signal. | `@kerfjs/ui/token-search-field` | [TokenSearchField contract](./accessibility.md#tokensearchfield) |
@@ -138,9 +139,9 @@ geometry and 44px targets.
 <aside class="kui-pane">
   <nav class="kui-pane__content kui-content">
     <section>
-    <MenuHeader label="Workspace" />
-    <MenuItem action="open" label="Inbox" icon={inboxIcon} />
-    <MenuActionRow action="open-file" label="main.ts" trailingAction="file-actions" trailingActionLabel="Actions for main.ts" trailingActionIcon={moreIcon} />
+    <ListHeader label="Workspace" />
+    <ListItem action="open" label="Inbox" icon={inboxIcon} />
+    <ListActionRow action="open-file" label="main.ts" trailingAction="file-actions" trailingActionLabel="Actions for main.ts" trailingActionIcon={moreIcon} />
     </section>
     <div class="kui-content-item">Workspace details</div>
   </nav>
@@ -152,7 +153,7 @@ forks the package anatomy and spacing contract.
 
 ```tsx
 <aside class="sidebar padded">
-  <h2 class="menu-header-copy">Workspace</h2>
+  <h2 class="list-header-copy">Workspace</h2>
   <button class="menu-row-copy padded">Inbox</button>
   <div class="panel indented-with-negative-margin">Workspace details</div>
 </aside>
@@ -166,7 +167,7 @@ registration, and the CSS-only `@kerfjs/ui/webawesome.css` theme.
 
 | Web Awesome choice | Kerf decision |
 | --- | --- |
-| `wa-button`, `wa-dropdown`, `wa-dropdown-item` | Use buttons and command menus for actions. Use `MenuItem` for a navigation row and `Select` when the user chooses a value. |
+| `wa-button`, `wa-dropdown`, `wa-dropdown-item` | Use buttons and command menus for actions. Use `ListItem` for a navigation row and `Select` when the user chooses a value. |
 | `wa-button-group` | Use only for exceptional grouped actions; use `SegmentedControl` for one-of-many selection. |
 | `wa-input`, `wa-tag` | Use for ordinary text and tags; use `TokenSearchField` only when text and ordered filter tokens form one editor. |
 | `wa-select`, `wa-option` | Use `Select`, which owns Kerf spacing, controlled rendering, icon stability, and explicit registration. |

package/docs/design-philosophy.md

@@ -53,9 +53,9 @@ Use the package composition so the geometry has one owner:
 <aside class="kui-pane">
   <nav class="kui-pane__content kui-content">
     <section>
-    <MenuHeader label="Workspace" />
-    <MenuItem action="open" label="Inbox" icon={inboxIcon} />
-    <MenuItem action="open" label="Drafts" />
+    <ListHeader label="Workspace" />
+    <ListItem action="open" label="Inbox" icon={inboxIcon} />
+    <ListItem action="open" label="Drafts" />
     </section>
     <div class="kui-content-item">Panel contents</div>
   </nav>
@@ -68,7 +68,7 @@ and makes transparent borders behave differently from visible ones:
 ```tsx
 <aside class="pane padded">
   <section class="padded">
-    <MenuHeader label="Workspace" />
+    <ListHeader label="Workspace" />
     <div class="panel padded-again">Panel contents</div>
   </section>
 </aside>

package/docs/layout.md

@@ -23,7 +23,7 @@ omits the footer; a navigation pane commonly uses all three. Fixed chrome stays
 outside `.kui-pane__content`, which is the pane's scroll owner.
 
 `.kui-content` is a vertical stack with a 24px gap between major children.
-Sections may contain adjacent `MenuItem` rows without adding another major gap.
+Sections may contain adjacent `ListItem` rows without adding another major gap.
 Ordinary surface-like children use `.kui-content-item` and own their complete
 geometry:
 
@@ -57,8 +57,8 @@ semantic status.
 | Inline metadata | `.kui-inline-metadata` | `--kui-layout-metadata-gap: 4px` |
 | Explicit scroll owner outside a pane | `.kui-scroll-owner` | `overflow: auto` |
 
-The component layer applies the same contract to `Toolbar`, `MenuHeader`,
-`MenuItem`, `PanelHeader`, `StateBanner`, `ValueTable`,
+The component layer applies the same contract to `Toolbar`, `ListHeader`,
+`ListItem`, `PanelHeader`, `StateBanner`, `ValueTable`,
 `ValueTableRow`, tabs, and form controls. A value-table row separator starts at
 the row's 8px content inset, or at 40px when the row contains its 24px leading
 icon and 8px gap, and always ends 8px from the right edge. Each value-table row
@@ -83,7 +83,7 @@ fixed 16px baseline, so it delivers as `rem`.
 
 | Value | Token | Relationship — when to use |
 | --- | --- | --- |
-| 0px | `--kui-space-none` | No separation. The elements read as a single unit (a control and its own affordance, adjacent `MenuItem` rows). |
+| 0px | `--kui-space-none` | No separation. The elements read as a single unit (a control and its own affordance, adjacent `ListItem` rows). |
 | 4px | `--kui-space-2xs` | Very minor. Still one connected cluster, but readability or aesthetics demand a hair of air (inline metadata, an icon beside its label). |
 | 8px | `--kui-space-xs` | Standard. Between elements **within a group** — the content-item padding/gutter, gaps between toolbar controls in a group. |
 | 16px | `--kui-space-m` | Minor. Between **homogeneous groups** — two lists, two sibling sections of the same kind. |
@@ -109,14 +109,14 @@ consistent across every surface.
 4. Keep one scrolling content owner per pane. Toolbar and footer siblings stay
    fixed while the content scrolls.
 5. A split item keeps dormant and interactive regions separate. For example,
-   `MenuHeader` renders its title/count-or-badge cluster separately from its optional
+   `ListHeader` renders its title/count-or-badge cluster separately from its optional
    logical-end 44px action. The header fills the available inline width and its
    action glyph defaults to 18px; disclosure mode makes the title cluster itself
    the button and supplies the production `DisclosureArrow` unless `actionIcon`
    replaces it.
-   `MenuActionRow` uses a noninteractive row root around sibling 44px primary
-   and trailing buttons. `MenuItem.trailing` remains dormant content.
-   In multiline `MenuItem` and `MenuActionRow` rows, the leading icon stays
+   `ListActionRow` uses a noninteractive row root around sibling 44px primary
+   and trailing buttons. `ListItem.trailing` remains dormant content.
+   In multiline `ListItem` and `ListActionRow` rows, the leading icon stays
    centered on the label's first line rather than the full wrapped label.
 6. Reading width, column placement, and responsive relocation remain application
    decisions. The shared classes define local geometry, not the whole shell.

package/docs/recipes.md

@@ -44,12 +44,12 @@ Adapt only public `--kui-layout-*` and component variables.
 [Open the recipe](../ux-demo/?component=recipe-navigation-sidebar) · [TSX source](../ux-demo/recipes/navigation-sidebar.tsx)
 
 One unpadded `.kui-pane` owns toolbar/content/footer structure. Its
-`.kui-content` uses 24px major gaps; `MenuHeader`, `MenuItem`, and other
+`.kui-content` uses 24px major gaps; `ListHeader`, `ListItem`, and other
 `.kui-content-item` children own their 8px margin, 1px border, and 8px padding.
 Rows and footer toolbar groups remain 44px tall. The app owns routes,
 permissions, labels, selection, valid section counts and their localized
 `countLabel` phrases, non-count badge content, disclosure state, and revealed
-content. A toggled `MenuHeader` supplies the production `DisclosureArrow` when
+content. A toggled `ListHeader` supplies the production `DisclosureArrow` when
 no custom `actionIcon` is needed; ordinary navigation rows stay chevron-free.
 
 ## Workspace header
@@ -60,13 +60,13 @@ no custom `actionIcon` is needed; ordinary navigation rows stay chevron-free.
 overflow, and primary actions. The app owns authorization and command policy;
 controls relocate without changing focus order.
 
-## Master-detail dialog
+## List-detail dialog
 
-[Open the recipe](../ux-demo/?component=recipe-master-detail-dialog) · [TSX source](../ux-demo/recipes/master-detail-dialog.tsx)
+[Open the recipe](../ux-demo/?component=recipe-list-detail-dialog) · [TSX source](../ux-demo/recipes/list-detail-dialog.tsx)
 
 The production Web Awesome dialog owns modal focus and Escape; the thin recipe
 adapter restores the invoking control consistently after the hide event.
-`PanelHeader`, `MenuHeader`, `MenuItem`, and `ValueTable` own their included
+`PanelHeader`, `ListHeader`, `ListItem`, and `ValueTable` own their included
 anatomy. The application owns open state, selection, dismissal policy, and
 record actions. `PanelHeader` places the trailing controls the app passes
 directly into its top toolbar's trailing zone.
@@ -121,6 +121,18 @@ settles the chrome (reduced motion collapses the slide to instant). A live
 [`app-layouts.md`](app-layouts.md) for choosing among `NavStack`, `SplitView`,
 `Workbench`, and `TabScaffold`.
 
+## Loading inspector
+
+[Open the recipe](../ux-demo/?component=recipe-loading-inspector) · [TSX source](../ux-demo/recipes/loading-inspector.tsx)
+
+A record inspector whose per-record values load asynchronously. Every
+value-bearing component (`PanelHeader`, `ValueTable`/`ValueTableRow`, `Select`,
+`SegmentedControl`, `ListItem`, `StateBanner`) takes its `placeholder` from one
+loading flag, so the same real chrome renders a faithful loading state and then
+the populated record — no separate skeleton markup. The composition is the point;
+`Skeleton` is the primitive it builds on. The app owns the loading lifecycle and
+which values are still unknown.
+
 ## Rules shared by every recipe
 
 - Import `@kerfjs/ui/layout.css`; keep every pane unpadded and use exactly one

package/docs/split-view.md

@@ -1,6 +1,6 @@
 # Split view (list-detail)
 
-`@kerfjs/ui/split-view` is a list-detail (master-detail) layout: a list and a
+`@kerfjs/ui/split-view` is a list-detail layout: a list and a
 detail side by side on roomy screens, collapsing to a `NavStack` (list → detail)
 on compact ones. One of the opt-in app layouts (see
 [`../../docs/23-app-layouts.md`](../../docs/23-app-layouts.md)).

package/docs/ux-demo.md

@@ -7,21 +7,21 @@ Each `?component=recipe-*` route uses public package primitives, real wiring,
 deterministic state, and semantic layout owners from the [recipe guide](./recipes.md).
 
 - It imports public component subpaths, exercising their browser-selected reachable CSS rather than a catalog-only style path.
-- The `MenuActionRow` route demonstrates sibling primary/trailing native controls, independent disabled states, controlled selection, first-line leading-icon alignment for wrapped labels, and an application-owned native popover relationship without nesting controls. The `MenuItem` route demonstrates the same multiline leading-icon anchor alongside its single-control navigation contract.
+- The `ListActionRow` route demonstrates sibling primary/trailing native controls, independent disabled states, controlled selection, first-line leading-icon alignment for wrapped labels, and an application-owned native popover relationship without nesting controls. The `ListItem` route demonstrates the same multiline leading-icon anchor alongside its single-control navigation contract.
 - The `AppTab` route demonstrates a runtime-filtered domain metadata slot and a decorative replacement close icon without changing TabBar selection, close, reorder, or focus ownership. The `ResizableRegion` route likewise replaces only the decorative handle glyph while retaining separator semantics and shared wiring.
 - Every first-party visual component and every free Web Awesome 3.12 component has its own stable `?component=<id>` URL and focused demo. Composite header, menu, feedback, and theme scenarios remain addressable alongside their subcomponents; the root opens the first Kerf component.
 - `ai/component-catalog.json` is the canonical catalog metadata. A deterministic checked-in projection supplies the demo's unique id, category, kind (`component`, `composition`, or `recipe`), source (`kerf` or `webawesome`), name, description, direct `uses` dependencies, existing documentation path, and demo-source path; first-party, recipe, and Web Awesome renderer maps are exhaustively typed against its generated id unions. Demo paths resolve to `ui/ux-demo/main.tsx`, the matching `ui/ux-demo/recipes/*.tsx` file, or `ui/ux-demo/webawesome-demos.tsx` according to the canonical entry. First-party component entries additionally derive `ui/src/<browser-subpath>.tsx` from their canonical `delivery.browserImport`.
 - Every detail footer groups compact `Demo source` and `Guidance` actions; first-party component details also expose `Component source`. Web Awesome details say `Integration guidance` to distinguish the local integration contract from the upstream component implementation. Each button retains its repository-relative path in the DOM for verification and uses a deploy-safe absolute GitHub blob URL with a contextual new-tab name; the demo does not depend on a local source server or add a package runtime export. At phone widths, the resource group and related-component selector stack as full-width rows, with any resource overflow contained locally so labels cannot overlap the selector or widen the document.
-- The master/detail shell groups first-party routes by category with production `MenuHeader` and `MenuItem` components. The 70 ecosystem components live in a separate `Web Awesome` disclosure with seven subgroups, so they remain discoverable without being presented as first-class `@kerfjs/ui` exports. Direct Web Awesome routes open the disclosure and reveal the selected row at wide sizes; narrow layouts keep the expanded list in document flow rather than introducing a competing nested scroller.
+- The master/detail shell groups first-party routes by category with production `ListHeader` and `ListItem` components. The 70 ecosystem components live in a separate `Web Awesome` disclosure with seven subgroups, so they remain discoverable without being presented as first-class `@kerfjs/ui` exports. Direct Web Awesome routes open the disclosure and reveal the selected row at wide sizes; narrow layouts keep the expanded list in document flow rather than introducing a competing nested scroller.
 - The shell itself uses `@kerfjs/ui/layout.css`: sidebars, details, previews, dialogs, and resize specimens share unpadded panes plus self-contained content items. Its sidebar identity uses the Kerf logo beside a vertically centered title, with the subtitle in its own aligned row like `PanelHeader`; the current-view heading is also a toolbar. Collapsing the catalog removes the pane completely and moves its restore action to the main toolbar's leading edge instead of leaving an icon-only rail. The selected view description remains inset below the page toolbar. The checkerboard belongs to the complete scrollable preview region rather than a nested card. A lightly separated footer keeps live status above compact source, guidance, and relationship groups. The focused `ResizableRegion` specimen stretches its surface through the available stage height and reports committed width in that shared status footer; narrow layouts retain local horizontal access when the pane is resized wider than the stage, and the split remains readable at 200% root scaling. Geometry coverage checks wide, intermediate, narrow, and 200% zoom layouts.
 - The composer-form recipe demonstrates one coherent visible form surface with `PanelHeader` title/summary hierarchy, fields and actions on the shared 8px control gutter, and 24px major rhythm. Its conditional error or success `StateBanner` is the only nested semantic surface. Reset synchronizes the upgraded Web Awesome fields' live value properties with their empty controlled attributes and announces `Draft reset`; browser coverage preserves behavior and verifies wide, narrow, dark, validation, success, reset, 200% zoom, and forced-colors states.
-- The master-detail dialog recipe places its header directly on the dialog edge while preserving the header's internal inset, gives the selected project title the complete outer-plus-inner content gutter, lets the value table fill the available detail column between the shared outer margins, and keeps record actions on one outer gutter without an extra content-item inset. Browser geometry coverage protects those relationships at wide and narrow widths.
+- The list-detail dialog recipe places its header directly on the dialog edge while preserving the header's internal inset, gives the selected project title the complete outer-plus-inner content gutter, lets the value table fill the available detail column between the shared outer margins, and keeps record actions on one outer gutter without an extra content-item inset. Browser geometry coverage protects those relationships at wide and narrow widths.
 - Catalog-only brand marks, preview dimensions, checkerboard tiles, and the compound display-settings control retain local geometry because they are specimen chrome or intrinsic control anatomy rather than reusable application spacing roles.
-- The menu composition route demonstrates toolbar/content/footer anatomy, 24px major gaps, 8/1/8 child geometry, the full-width `MenuHeader` count-or-badge/action split, logical-end 44px action targets with 18px visuals, and 44px row/header/toolbar targets. Its one chevron is a production 18px `DisclosureArrow` inside a controlled Tools header that actually reveals and hides content; ordinary Projects navigation has no false disclosure affordance. Browser assertions cover stable naming, expanded/content transitions, visual rotation, node identity, reduced motion, RTL alignment and containment, and wide, narrow, dark, and 200% layouts. The focused MenuHeader route separately shows the shared neutral count pill for Attachments, Notes (including zero), and Duplicates plus a non-count legacy badge, full-width logical-end actions, and no disclosure without content.
+- The menu composition route demonstrates toolbar/content/footer anatomy, 24px major gaps, 8/1/8 child geometry, the full-width `ListHeader` count-or-badge/action split, logical-end 44px action targets with 18px visuals, and 44px row/header/toolbar targets. Its one chevron is a production 18px `DisclosureArrow` inside a controlled Tools header that actually reveals and hides content; ordinary Projects navigation has no false disclosure affordance. Browser assertions cover stable naming, expanded/content transitions, visual rotation, node identity, reduced motion, RTL alignment and containment, and wide, narrow, dark, and 200% layouts. The focused ListHeader route separately shows the shared neutral count pill for Attachments, Notes (including zero), and Duplicates plus a non-count legacy badge, full-width logical-end actions, and no disclosure without content.
 - The `DisclosureArrow` route renders the production 18px root-scaled default without a catalog-only size override. Its two native buttons independently control the default right-to-down chevron and a recognizable right-facing replacement arrow with left-to-up custom directions; both use shortest-path rotation and their names stay stable while `aria-expanded` communicates state. Browser coverage verifies the custom clockwise path, pointer and native keyboard activation, focus, narrow and 200%-zoom stacking with contained labels, consumer sizing, and the independent `.5` Web Awesome glyph scale retained by Kerf `Select`.
 - A detail with relationships renders one grouped footer selector: `Uses` links to direct dependencies and `Used by` links to reverse dependents. Choosing either navigates to that component's demo. The relationship group is absent when both sets are empty; no duplicate summary is rendered.
 - Demo-only CSS supplies only the catalog shell and stages; component appearance stays in package CSS. Decorative chrome and Web Awesome controls share the same semantic system palette instead of carrying a separate demo identity.
-- Scenarios use deterministic data and cover real variants, long content, disabled state, selection, progress, feedback, overlays, media, helpers, and stateful interactions. The Web Awesome theme route remains the broad system view, while individual action, form, layout, navigation, feedback, media, and helper routes provide focused specimens; MenuItem and MenuHeader demonstrate typed domain metadata, protected native button/disclosure semantics, and a native popover trigger relationship without product props; PanelHeader demonstrates its plain top-toolbar identity, extra-large title, optional subtitle row, and bordered brand-filled icon group; the Select route verifies that option icons survive unrelated Kerf rerenders and selected slot content follows value changes; the Animation route exposes preset, easing, duration, playback-rate, and transport controls with live lifecycle status; observer routes provide user-driven intersection, mutation, and resize events with live results; ToolbarControlGroup exposes all eight Hot Sheet 2 variants, loads the Web Awesome registrations needed by its popup specimen, and preserves the upgraded dropdown's managed light-DOM children across Kerf rerenders; the Toolbar route composes a collapsible TokenSearchField inside a group, animates between the empty iconic and complete field states, stays open while populated, and focuses the revealed editor; SegmentedControl covers toolbar, rounded-rectangle, pill, equal-width, and disabled presentations; TokenSearchField covers editable ordered chips, pointer and keyboard removal, caret-preserving controlled deletion, editing, clearing, free text, disabled state, and fixed first-line alignment while content wraps; StateBanner exposes every built-in tone plus a scoped override; TabBar demonstrates overflow, edge autoscroll, and controlled pointer/keyboard reordering.
+- Scenarios use deterministic data and cover real variants, long content, disabled state, selection, progress, feedback, overlays, media, helpers, and stateful interactions. The Web Awesome theme route remains the broad system view, while individual action, form, layout, navigation, feedback, media, and helper routes provide focused specimens; ListItem and ListHeader demonstrate typed domain metadata, protected native button/disclosure semantics, and a native popover trigger relationship without product props; PanelHeader demonstrates its plain top-toolbar identity, extra-large title, optional subtitle row, and bordered brand-filled icon group; the Select route verifies that option icons survive unrelated Kerf rerenders and selected slot content follows value changes; the Animation route exposes preset, easing, duration, playback-rate, and transport controls with live lifecycle status; observer routes provide user-driven intersection, mutation, and resize events with live results; ToolbarControlGroup exposes all eight Hot Sheet 2 variants, loads the Web Awesome registrations needed by its popup specimen, and preserves the upgraded dropdown's managed light-DOM children across Kerf rerenders; the Toolbar route composes a collapsible TokenSearchField inside a group, animates between the empty iconic and complete field states, stays open while populated, and focuses the revealed editor; SegmentedControl covers toolbar, rounded-rectangle, pill, equal-width, and disabled presentations; TokenSearchField covers editable ordered chips, pointer and keyboard removal, caret-preserving controlled deletion, editing, clearing, free text, disabled state, and fixed first-line alignment while content wraps; StateBanner exposes every built-in tone plus a scoped override; TabBar demonstrates overflow, edge autoscroll, and controlled pointer/keyboard reordering.
 - Recipe ownership notes are hidden by default. A page-toolbar toggle reveals them as floating warning-toned notes with a folded corner, keeping instructional copy visually distinct and removable from the specimen flow.
 - Settings exercise light/dark, increased contrast, and reduced motion without changing component code. The theme action starts from the operating system's effective color scheme, always names the appearance it will switch to, and installs an explicit light or dark override when activated; contrast and reduced motion expose their independent preferences through `aria-pressed`.
 - The footer action log is an `aria-live` region, making interactions visible to both people and browser tests.

package/llms.txt

@@ -9,7 +9,7 @@
 npm install kerfjs @kerfjs/ui   # kerfjs is a peer; Web Awesome is an optional peer
 ```
 
-Import each component from its own subpath (`@kerfjs/ui/menu-item`, `@kerfjs/ui/toolbar`,
+Import each component from its own subpath (`@kerfjs/ui/list-item`, `@kerfjs/ui/toolbar`,
 …); the browser build pulls that component's reachable CSS automatically, so do not
 maintain a central style list. Configure JSX with `"jsxImportSource": "kerfjs"`.
 
@@ -82,9 +82,9 @@ maintain a central style list. Configure JSX with `"jsxImportSource": "kerfjs"`.
   provides; but do keep a plain disclosure toggle (a one-line boolean the app already
   renders from) in the app.
 - **Placeholder loading state, don't rebuild it.** For a value or component that is
-  still loading, set `placeholder` on the component (`Select`, `MenuHeader`,
-  `MenuItem`, `ValueTableRow`, `PanelHeader`, `SegmentedControl`, `StateBanner`,
-  `AppTab`, `ToolbarText`, `MenuActionRow`): it renders its real chrome with value
+  still loading, set `placeholder` on the component (`Select`, `ListHeader`,
+  `ListItem`, `ValueTableRow`, `PanelHeader`, `SegmentedControl`, `StateBanner`,
+  `AppTab`, `ToolbarText`, `ListActionRow`): it renders its real chrome with value
   slots as subtle **unanimated** skeleton blocks and interactivity disabled, so a
   parent composes a faithful loading view (e.g. an inspector) without hand-rebuilding
   markup. Use the standalone `Skeleton` for a custom slot. Prefer it over `wa-skeleton`
@@ -94,15 +94,19 @@ maintain a central style list. Configure JSX with `"jsxImportSource": "kerfjs"`.
 ## Public exports
 
 `LucideIcon`, `DisclosureArrow`, `Toolbar`, `ToolbarControlGroup`, `ToolbarText`,
-`PanelHeader`, `MenuItem`, `MenuActionRow`, `MenuHeader`, `SegmentedControl`,
+`PanelHeader`, `ListItem`, `ListActionRow`, `ListHeader`, `SegmentedControl`,
 `Select`, `TokenSearchField` (+ `readTokenSearchField`, `placeTokenSearchCaret`,
 `wireTokenSearchFields`), `AppTab`, `TabBar` (+ `wireTabBars`, `reorderTabs`),
 `ResizableRegion` (+ `wireResizableRegions`), `StateBanner`, `EmptyState`,
 `LoadingSpinner`, `Skeleton`, `ValueTable`, `ValueTableRow`. Whole-screen layouts (opt-in,
 tree-shakeable, declarative with `wire…` helpers, each with a companion CSS import):
 `NavStack`, `SplitView`, `Workbench`, `TabScaffold`, driven by `deviceClass()` from
-`@kerfjs/ui/device-class`. `@kerfjs/ui/webawesome` is a type-only boundary for
-`wa-*` JSX; `@kerfjs/ui/select/register` and the CSS are the declared side effects.
+`@kerfjs/ui/device-class`. `@kerfjs/ui/catalog` is another opt-in shell — a
+`Catalog` component + `wireCatalog` helper for building a component-gallery catalog
+(collapsible category sidebar + preview stage + resources footer) from your own
+entries; controlled/stateless like the layouts. `@kerfjs/ui/webawesome` is a
+type-only boundary for `wa-*` JSX; `@kerfjs/ui/select/register` and the CSS are the
+declared side effects.
 
 ## Reference
 
@@ -111,7 +115,7 @@ tree-shakeable, declarative with `wire…` helpers, each with a companion CSS im
 - [layout.md](./docs/layout.md): the pane/content-item geometry, public roles/tokens, and the spacing scale.
 - [component-contract.md](./docs/component-contract.md): what a component owns vs. what the app owns.
 - [accessibility.md](./docs/accessibility.md): keyboard and ARIA contracts per component.
-- [recipes.md](./docs/recipes.md): production compositions (app shell, master-detail dialog, composer form, …) as copyable references.
+- [recipes.md](./docs/recipes.md): production compositions (app shell, list-detail dialog, composer form, …) as copyable references.
 - [app-layouts.md](./docs/app-layouts.md): choosing `NavStack`/`SplitView`/`Workbench`/`TabScaffold` by data + interaction + device, and dialog presentation.
 - [webawesome-theme.md](./docs/webawesome-theme.md): the optional Web Awesome theme; catalog coverage means themed-and-supported, not preferred (prefer the Kerf primitive when one exists).
 - [component-catalog.json](./ai/component-catalog.json) + [public-api-signatures-v1.md](./ai/public-api-signatures-v1.md) + [webawesome-jsx-signatures-v1.md](./ai/webawesome-jsx-signatures-v1.md): machine-readable facts and exact signatures.