@kerfjs/ui 4.4.1 → 5.0.0-beta.11

package/ai/skill.md

@@ -1,28 +1,74 @@
 ---
 name: kerf-ui
 description: Build interfaces with kerfjs and the @kerfjs/ui production component package. Use whenever code imports @kerfjs/ui or a task asks for Kerf UI components.
-kerf-ui-skill-version: 1.5.0
+kerf-ui-skill-version: 1.34.0
 ---
 
 # Building with @kerfjs/ui
 
-Read `../README.md`, `../docs/component-contract.md`, and `../docs/accessibility.md` before changing a consuming interface. Read `../docs/webawesome-theme.md` when using Web Awesome components or changing shared theme tokens.
+Read `../docs/component-selection.md` first, then `./component-catalog.json`,
+`./public-api-signatures-v1.md`, `./webawesome-jsx-signatures-v1.md`,
+`../docs/recipes.md`, `../README.md`,
+`../docs/component-contract.md`, and `../docs/accessibility.md` before changing
+a consuming interface. Use the signature snapshot for exact props, callbacks,
+return values, and supported import paths; do not infer them from examples.
+Read `../docs/webawesome-theme.md` when using Web Awesome components or changing
+shared theme tokens.
+
+Choose from the need, not from visual resemblance:
+
+1. Search the Kerf catalog and preferred Web Awesome subset.
+2. Reuse a primitive when purpose, anatomy, state, and interaction match.
+3. Compose primitives for recurring layout. Prefer public props and tokens; use only cataloged `publicClasses` when composition-specific CSS needs a selector.
+4. Add a thin application adapter for copy, domain mapping, actions, routing, persistence, permissions, and transport.
+5. Build custom markup only when the semantic contract differs; if it recurs across products, open an upstream component or recipe request.
+
+Quick routing:
+
+| Need | Choose | Nearest alternatives / boundary |
+| --- | --- | --- |
+| 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`, `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, 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.
+
+The concise human decision matrix is in [`component-selection.md`](../docs/component-selection.md). For exhaustive tool retrieval, load [`component-catalog.json`](./component-catalog.json), the canonical metadata for every public component/helper, composition, and supported Web Awesome entry. Use its linked current recipes instead of inferring behavior from CSS.
 
 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.
+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; do not hard-code appearance-specific colors or replace private descendant rules.
-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 uses Web Awesome components, import the CSS-only `@kerfjs/ui/webawesome.css` theme once and keep importing individual Web Awesome component modules so their JavaScript remains tree-shakeable.
-7. Decorative icons are hidden; controls are named; focus is visible; state never relies on color alone; reduced motion and increased contrast remain usable.
-8. `ResizableRegion` uses `wireResizableRegions()` for Arrow, Shift+Arrow, Home/End, and pointer behavior. The app owns size persistence.
+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`. `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.
-11. Demo work uses public production component subpaths and their browser-selected CSS. Give every public visual component its own category-grouped catalog route; list themed third-party components under a clearly labeled collapsible ecosystem section, with a focused route for each. Declare direct `uses` relationships so `Used by` stays derivable, and theme shell chrome through the same semantic tokens as the stage instead of drawing a substitute.
-12. The Web Awesome theme makes Tooltip and Popover arrowless by default. Keep that default unless a pointer materially clarifies the anchor; opt back in with `--wa-tooltip-arrow-size`, `--kui-wa-popover-arrow-size`, or a popover's public `--arrow-size`, and use `without-arrow` when local no-arrow intent should survive theme changes.
-13. 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.
+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. Arrow/Home/End select on move by default; pass `activation: 'manual'` (or `TabBar activation="manual"` per strip) so arrow keys move focus only and the user selects with Enter/Space/click — use it when selecting a tab is a heavy action. Use runtime-filtered `rootAttributes` for domain metadata and keep an optional `closeIcon` decorative and noninteractive.
+11. Use token-controlled `TokenSearchField` when free text and removable structured filters share one editor. Editable text stays DOM-owned between token changes. The leading icon, first text line, clear action, and trailing slot share one fixed row when content wraps. The app owns parsing and suggestions; call `readTokenSearchField()` on input, empty `textContent` on clear, use `placeTokenSearchCaret()` after explicit controlled focus changes, and call `wireTokenSearchFields()` once so Enter submits without inserting a line break and keyboard chip deletion restores focus plus the text-relative caret after controlled replacement. Enable `collapsible` for an animated iconic closed state, standalone or inside `ToolbarControlGroup`; the field keeps text or tokens expanded, and `wireTokenSearchFields()` manages the transient expand/collapse/focus by default (activate to reveal + focus, Escape or empty blur to collapse). Bind the field's `expanded` to the returned handle's `expanded(id)` signal or adopt your own via `collapsible.signals`; opt a behavior out only when the app must own it. Do not hand-roll the open handler, the focusout collapse, or a clear-button mousedown guard — the helper owns them. For real-app adoption it also provides a focusout keep-open exception (`data-token-search-keep-open` regions or `collapsible.keepOpenOn(target)`, so a sibling suggestions/date/help surface does not collapse an empty field), opt-in atomic-chip keyboard (`keyboard`: Backspace/Delete remove the adjacent chip via `onRemoveToken`, ArrowRight moves the caret past a trailing chip), and an `onEdit({id, editor, event})` input callback (the `InputEvent` lets you gate on `inputType`/`data`) — reach for these instead of re-adding hand-rolled keydown/input handlers around the field.
+12. Demo work uses public production component subpaths and their browser-selected CSS. Give every public visual component its own category-grouped catalog route; list themed third-party components under a clearly labeled collapsible ecosystem section, with a focused route for each. Project its deterministic repository-relative demo source and existing documentation path so the detail can expose `View demo source` and `Read guidance` links without a runtime export; also derive first-party component implementation paths from their canonical browser imports, and label Web Awesome documentation as Kerf integration guidance. Declare direct `uses` relationships so `Used by` stays derivable, and theme shell chrome through the same semantic tokens as the stage instead of drawing a substitute.
+13. The Web Awesome theme makes Tooltip and Popover arrowless by default. Keep that default unless a pointer materially clarifies the anchor; opt back in with `--wa-tooltip-arrow-size`, `--kui-wa-popover-arrow-size`, or a popover's public `--arrow-size`, and use `without-arrow` when local no-arrow intent should survive theme changes.
+14. Treat the complete Web Awesome catalog as support coverage, not a recommendation list. Consider Popup when it replaces custom anchored positioning. Prefer Kerf `Select` over direct Dropdown/Dropdown Item/Select/Option composition, `SegmentedControl` over Button Group, `TabBar` or `SegmentedControl` over Web Awesome Tabs, `LucideIcon` over Web Awesome Icon, and `ResizableRegion` over Split Panel. Use Tree/Tree Item, Animated Image, and Comparison only for a specific required behavior; avoid Zoomable Frame.
+15. Build sidebars, main areas, inspectors, and dialogs from `@kerfjs/ui/layout.css`: an unpadded `.kui-pane`, optional `.kui-pane__toolbar`, one scrolling `.kui-pane__content`, and optional `.kui-pane__footer`. Add `.kui-content` for 24px major vertical separation and `.kui-content-item` for a child-owned 8px inline margin, 1px transparent-or-visible border, 8px padding, and 12px radius. Use the pill modifier for 22px. Do not pad pane shells or duplicate item geometry in wrappers.
+16. Keep a visible collapsible pane's collapse control in its own toolbar. When hidden, move its restore control into the adjacent main toolbar on the corresponding logical edge: leading for an inline-start sidebar and trailing for an inline-end inspector. Collapse the pane completely; do not preserve an empty icon-only rail.
+16. 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.
+20. Space with the official five-step scale, picked by how connected two elements are — not by eye. `0` `--kui-space-none` = no separation (one unit); `4px` `--kui-space-2xs` = very minor air on a connected cluster; `8px` `--kui-space-xs` = standard, between elements within a group; `16px` `--kui-space-m` = minor, between homogeneous groups; `24px` `--kui-space-l` = major, between heterogeneous groups (the `.kui-content` rhythm). The 8px-vs-24px distinction is inside-a-group vs between-major-differing-regions. `--kui-space-s` (12px) and `--kui-space-xl` (32px) are off-scale exceptions; prefer the five canonical remify-authored tokens. See `docs/layout.md` "Spacing scale".
+21. Pick a whole-screen layout from the opt-in, tree-shakeable subpaths by data + interaction + device, and derive responsiveness from `@kerfjs/ui/device-class`'s `deviceClass()` (`compact` = handset or portrait tablet = one pane at a time). Simple/flat → `NavStack` with one entry (single pane), plus `TabScaffold` (`@kerfjs/ui/tab-scaffold`, iOS bottom tabs, each tab its own `NavStack`) for 2–5 co-equal sections on `compact`. Drill-down → `NavStack` (`@kerfjs/ui/nav-stack`), upgrading to `SplitView` (`@kerfjs/ui/split-view`, list-detail) once both panes fit (`atLeast('tablet')` landscape); `SplitView` collapses to a `NavStack` on `compact`. Complex tool with peripheral panels → `Workbench` (`@kerfjs/ui/workbench`, collapsible rails + drawer) `atLeast('desktop')`, degrading to `NavStack`/overlays below. These are declarative (the app owns the stack/selection/collapsed/active state as signals) with disposer-returning `wire…` helpers; each ships a companion CSS import and stays out of the barrel. For a standalone collapsible rail or bottom drawer outside a full shell, use `CollapsiblePanel` + `CollapsiblePanelToggle` (`@kerfjs/ui/collapsible-panel`) with `wireSidebar` (`@kerfjs/ui/wire-sidebar`): the standard collapse animation and per-side icon convention (`PanelLeft*`/`PanelRight*`/`PanelBottom*`) plus toggle, focus, compact overlay, and persistence semantics. Dialogs pick the same inner layout, then present per device class (full-screen modal on `compact`, inline on desktop). See `docs/app-layouts.md` and `docs/collapsible-panel.md`.
 
 Common mistakes:
 
@@ -31,8 +77,24 @@ 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 `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 `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 |
+| Handwrite `ValueTable` row wrappers or compensate their padding or separators | Compose `ValueTableRow`; its root-scaled block padding, optional icon hook, and separator geometry are public contract |
+| Rebuild a panel/dialog heading row by hand | Use `PanelHeader`: a plain toolbar with an optional bordered icon group, an xl title, trailing controls you pass, and the optional subtitle below |
+| Force a `width`/`height`/`padding` on a component to size or space it | Let it size to its content and tokens; a forced box leaves a halo or a stretched oval — adjust an icon-size or spacing token, not the box |
+| Wrap a component or region in a card, border, backdrop, or outline to "contain" it | Let it sit on the surface; add a `.kui-content-item` only for a real distinction — hierarchy comes from alignment, spacing, and type first |
+| Add another container's padding on top of a content-item's own margin | Pick one owner of the inset; a pane has no padding and its `.kui-content` children own the 8/1/8 geometry — stacking them double-insets |
+| Keep chrome, a label, or a readout that aids no decision | Delete it; every element must help a person decide or act |
+| Override a component's default size or color because it "looks off" | Trust the default (a LucideIcon is 24px) and fix the surrounding layout instead |

package/ai/webawesome-jsx-signatures-v1.md

@@ -0,0 +1,106 @@
+# Web Awesome JSX signatures for the UI authoring corpus
+
+Generated from the emitted `@kerfjs/ui@5.0.0-beta.11` 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';
+
+/**
+ * Opt-in Kerf JSX declarations for the Web Awesome elements supported by the
+ * @kerfjs/ui catalog. Import this module for type effects only; component
+ * registration remains an explicit application concern.
+ */
+declare module 'kerfjs/jsx-runtime' {
+    namespace JSX {
+        interface IntrinsicElements {
+            'wa-accordion': KerfCustomElement;
+            'wa-accordion-item': KerfCustomElement;
+            'wa-animated-image': KerfCustomElement;
+            'wa-animation': KerfCustomElement;
+            'wa-avatar': KerfCustomElement;
+            'wa-badge': KerfCustomElement;
+            'wa-breadcrumb': KerfCustomElement;
+            'wa-breadcrumb-item': KerfCustomElement;
+            'wa-select': KerfCustomElement & {
+                class?: string;
+                name?: string;
+                label?: string;
+                'aria-label'?: string;
+                value?: string;
+                placeholder?: string;
+                disabled?: boolean;
+            };
+            'wa-option': KerfCustomElement & {
+                value?: string;
+            };
+            'wa-button-group': KerfCustomElement;
+            'wa-callout': KerfCustomElement;
+            'wa-card': KerfCustomElement;
+            'wa-carousel': KerfCustomElement;
+            'wa-carousel-item': KerfCustomElement;
+            'wa-checkbox': KerfCustomElement;
+            'wa-checkbox-group': KerfCustomElement;
+            'wa-color-picker': KerfCustomElement;
+            'wa-comparison': KerfCustomElement;
+            'wa-copy-button': KerfCustomElement;
+            'wa-details': KerfCustomElement;
+            'wa-divider': KerfCustomElement;
+            'wa-dialog': KerfCustomElement;
+            'wa-drawer': KerfCustomElement;
+            'wa-button': KerfCustomElement & {
+                slot?: string;
+                appearance?: string;
+                'with-caret'?: boolean;
+                'aria-label'?: string;
+            };
+            'wa-dropdown': KerfCustomElement & {
+                placement?: string;
+            };
+            'wa-dropdown-item': KerfCustomElement;
+            'wa-format-bytes': KerfCustomElement;
+            'wa-format-date': KerfCustomElement;
+            'wa-format-number': KerfCustomElement;
+            'wa-icon': KerfCustomElement;
+            'wa-include': KerfCustomElement;
+            'wa-input': KerfCustomElement;
+            'wa-intersection-observer': KerfCustomElement;
+            'wa-known-date': KerfCustomElement;
+            'wa-markdown': KerfCustomElement;
+            'wa-mutation-observer': KerfCustomElement;
+            'wa-number-input': KerfCustomElement;
+            'wa-otp-input': KerfCustomElement;
+            'wa-page': KerfCustomElement;
+            'wa-pagination': KerfCustomElement;
+            'wa-popover': KerfCustomElement;
+            'wa-popup': KerfCustomElement;
+            'wa-progress-bar': KerfCustomElement;
+            'wa-progress-ring': KerfCustomElement;
+            'wa-qr-code': KerfCustomElement;
+            'wa-radio': KerfCustomElement;
+            'wa-radio-group': KerfCustomElement;
+            'wa-random-content': KerfCustomElement;
+            'wa-rating': KerfCustomElement;
+            'wa-relative-time': KerfCustomElement;
+            'wa-resize-observer': KerfCustomElement;
+            'wa-scroller': KerfCustomElement;
+            'wa-skeleton': KerfCustomElement;
+            'wa-slider': KerfCustomElement;
+            'wa-spinner': KerfCustomElement;
+            'wa-split-panel': KerfCustomElement;
+            'wa-switch': KerfCustomElement;
+            'wa-tab': KerfCustomElement;
+            'wa-tab-group': KerfCustomElement;
+            'wa-tab-panel': KerfCustomElement;
+            'wa-tag': KerfCustomElement;
+            'wa-textarea': KerfCustomElement;
+            'wa-time-input': KerfCustomElement;
+            'wa-toast': KerfCustomElement;
+            'wa-toast-item': KerfCustomElement;
+            'wa-tooltip': KerfCustomElement;
+            'wa-tree': KerfCustomElement;
+            'wa-tree-item': KerfCustomElement;
+            'wa-zoomable-frame': KerfCustomElement;
+        }
+    }
+}
+```

package/dist/app-tab.d.ts

@@ -1,5 +1,13 @@
 import { SafeHtml } from 'kerfjs';
 
+type AppTabRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+    'data-component'?: never;
+    'data-action'?: never;
+    'data-tab-id'?: never;
+    'data-selected'?: never;
+    'data-tab-dragging'?: never;
+    'data-tab-drop-position'?: never;
+}>;
 interface AppTabProps {
     id: string;
     name: string;
@@ -8,11 +16,15 @@ interface AppTabProps {
     draggable?: boolean;
     leading?: SafeHtml;
     trailing?: SafeHtml;
+    /** Decorative dormant content for the close button. Must not contain interactive descendants. */
+    closeIcon?: SafeHtml;
     selectAction?: string;
     closeAction?: string;
     className?: string;
-    rootAttributes?: Readonly<Record<`data-${string}`, string>>;
+    /** Render as an unanimated loading skeleton, disabling select/close and dragging. */
+    placeholder?: boolean;
+    rootAttributes?: AppTabRootAttributes;
 }
-declare function AppTab({ id, name, selected, closable, draggable, leading, trailing, selectAction, closeAction, className, rootAttributes }: AppTabProps): SafeHtml;
+declare function AppTab({ id, name, selected, closable, draggable, leading, trailing, closeIcon, selectAction, closeAction, className, placeholder, rootAttributes }: AppTabProps): SafeHtml;
 
 export { AppTab, type AppTabProps };

package/dist/app-tab.js

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

package/dist/browser/app-tab.js

@@ -1,3 +1,4 @@
-import '../../src/foundation.css';
-import '../../src/app-tab.css';
+import '../styles/foundation.css';
+import '../styles/skeleton.css';
+import '../styles/app-tab.css';
 export * from '../app-tab.js';

package/dist/browser/disclosure-arrow.js

@@ -0,0 +1,4 @@
+import '../styles/foundation.css';
+import '../styles/lucide-icon.css';
+import '../styles/disclosure-arrow.css';
+export * from '../disclosure-arrow.js';

package/dist/browser/empty-state.js

@@ -1,4 +1,4 @@
-import '../../src/foundation.css';
-import '../../src/loading-spinner.css';
-import '../../src/empty-state.css';
+import '../styles/foundation.css';
+import '../styles/loading-spinner.css';
+import '../styles/empty-state.css';
 export * from '../empty-state.js';

package/dist/browser/floating-toolbar.js

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

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/list-header.js

@@ -0,0 +1,6 @@
+import '../styles/foundation.css';
+import '../styles/lucide-icon.css';
+import '../styles/disclosure-arrow.css';
+import '../styles/skeleton.css';
+import '../styles/list-header.css';
+export * from '../list-header.js';

package/dist/browser/list-item.js

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

package/dist/browser/loading-spinner.js

@@ -1,3 +1,3 @@
-import '../../src/foundation.css';
-import '../../src/loading-spinner.css';
+import '../styles/foundation.css';
+import '../styles/loading-spinner.css';
 export * from '../loading-spinner.js';

package/dist/browser/lucide-icon.js

@@ -1,3 +1,3 @@
-import '../../src/foundation.css';
-import '../../src/lucide-icon.css';
+import '../styles/foundation.css';
+import '../styles/lucide-icon.css';
 export * from '../lucide-icon.js';

package/dist/browser/panel-header.js

@@ -0,0 +1,7 @@
+import '../styles/foundation.css';
+import '../styles/skeleton.css';
+import '../styles/toolbar.css';
+import '../styles/toolbar-control-group.css';
+import '../styles/toolbar-text.css';
+import '../styles/panel-header.css';
+export * from '../panel-header.js';

package/dist/browser/resizable-region.js

@@ -1,3 +1,3 @@
-import '../../src/foundation.css';
-import '../../src/resizable-region.css';
+import '../styles/foundation.css';
+import '../styles/resizable-region.css';
 export * from '../resizable-region.js';

package/dist/browser/segmented-control.js

@@ -1,3 +1,4 @@
-import '../../src/foundation.css';
-import '../../src/segmented-control.css';
+import '../styles/foundation.css';
+import '../styles/skeleton.css';
+import '../styles/segmented-control.css';
 export * from '../segmented-control.js';

package/dist/browser/select.js

@@ -1,4 +1,5 @@
-import '../../src/foundation.css';
-import '../../src/lucide-icon.css';
-import '../../src/select.css';
+import '../styles/foundation.css';
+import '../styles/lucide-icon.css';
+import '../styles/skeleton.css';
+import '../styles/select.css';
 export * from '../select.js';

package/dist/browser/skeleton.js

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

package/dist/browser/state-banner.js

@@ -1,3 +1,4 @@
-import '../../src/foundation.css';
-import '../../src/state-banner.css';
+import '../styles/foundation.css';
+import '../styles/skeleton.css';
+import '../styles/state-banner.css';
 export * from '../state-banner.js';

package/dist/browser/tab-bar.js

@@ -1,3 +1,3 @@
-import '../../src/foundation.css';
-import '../../src/tab-bar.css';
+import '../styles/foundation.css';
+import '../styles/tab-bar.css';
 export * from '../tab-bar.js';

package/dist/browser/token-search-field.js

@@ -0,0 +1,4 @@
+import '../styles/foundation.css';
+import '../styles/lucide-icon.css';
+import '../styles/token-search-field.css';
+export * from '../token-search-field.js';

package/dist/browser/toolbar-control-group.js

@@ -1,3 +1,3 @@
-import '../../src/foundation.css';
-import '../../src/toolbar-control-group.css';
+import '../styles/foundation.css';
+import '../styles/toolbar-control-group.css';
 export * from '../toolbar-control-group.js';

package/dist/browser/toolbar-text.js

@@ -1,3 +1,4 @@
-import '../../src/foundation.css';
-import '../../src/toolbar-text.css';
+import '../styles/foundation.css';
+import '../styles/skeleton.css';
+import '../styles/toolbar-text.css';
 export * from '../toolbar-text.js';

package/dist/browser/toolbar.js

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

package/dist/browser/value-table.js

@@ -1,3 +1,4 @@
-import '../../src/foundation.css';
-import '../../src/value-table.css';
+import '../styles/foundation.css';
+import '../styles/skeleton.css';
+import '../styles/value-table.css';
 export * from '../value-table.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 entries" popup menu. */
+interface CatalogRelated {
+    id: string;
+    name: string;
+    /** Group heading in the menu, 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 popup menu. 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 };