@kerfjs/ui 5.0.0-beta.61 → 5.0.0-beta.63

package/dist/token-search-field.js

@@ -1,4 +1,5 @@
-export { TokenSearchField, placeTokenSearchCaret, readTokenSearchField } from './chunk-RRB26JRJ.js';
+export { TokenSearchField, placeTokenSearchCaret, readTokenSearchField } from './chunk-RTJNJTG3.js';
+
 
 
 //# sourceMappingURL=token-search-field.js.map

package/dist/toolbar-control-group.d.ts

@@ -60,6 +60,10 @@ interface ToolbarControlGroupProps {
     relocateOnCollapse?: boolean;
     /** Add contrast behind photo-backed avatar content. */
     scrim?: boolean;
+    /** Block the group's controls and show a spinner without changing its dimensions. */
+    busy?: boolean;
+    /** Announced status while busy; defaults to “Working”. */
+    busyLabel?: string;
     /**
      * Avatar image URL. A single-control group paints it on the group; a
      * multi-control group paints it only on the pressed selection highlight.
@@ -68,6 +72,6 @@ interface ToolbarControlGroupProps {
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
 }
-declare function ToolbarControlGroup({ children, label, className, expanded, single, appearance, tone, buttonAppearance, shape, size, density, content, focusRing, selectedChrome, selectedTone, nestedDropdown, menuInset, overflow, visibility, relocateOnCollapse, scrim, avatarImage, slot, }: ToolbarControlGroupProps): kerfjs.SafeHtml;
+declare function ToolbarControlGroup({ children, label, className, expanded, single, appearance, tone, buttonAppearance, shape, size, density, content, focusRing, selectedChrome, selectedTone, nestedDropdown, menuInset, overflow, visibility, relocateOnCollapse, scrim, busy, busyLabel, avatarImage, slot, }: ToolbarControlGroupProps): kerfjs.SafeHtml;
 
 export { ToolbarActionLink, type ToolbarActionLinkProps, ToolbarControlGroup, type ToolbarControlGroupAppearance, type ToolbarControlGroupButtonAppearance, type ToolbarControlGroupContent, type ToolbarControlGroupDensity, type ToolbarControlGroupFocusRing, type ToolbarControlGroupMenuInset, type ToolbarControlGroupOverflow, type ToolbarControlGroupProps, type ToolbarControlGroupSelectedChrome, type ToolbarControlGroupSelectedTone, type ToolbarControlGroupShape, type ToolbarControlGroupSize, type ToolbarControlGroupTone, type ToolbarControlGroupVisibility };

package/dist/toolbar-control-group.js

@@ -1,3 +1,4 @@
-export { ToolbarActionLink, ToolbarControlGroup } from './chunk-7JUBXOIV.js';
+export { ToolbarActionLink, ToolbarControlGroup } from './chunk-NXWE5S57.js';
+
 
 //# sourceMappingURL=toolbar-control-group.js.map

package/dist/toolbar-text.d.ts

@@ -1,6 +1,6 @@
 import * as kerfjs from 'kerfjs';
 
-type ToolbarTextSize = 'xlarge' | 'large' | 'default' | 'small' | 'xsmall';
+type ToolbarTextSize = 'xlarge' | 'xlarge-fixed' | 'large' | 'default' | 'small' | 'xsmall';
 /** ARIA heading level for a title exposed as a heading landmark. */
 type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
 interface ToolbarTextBaseProps {

package/dist/toolbar-text.js

@@ -1,4 +1,4 @@
-export { ToolbarText } from './chunk-3SXMEK3B.js';
+export { ToolbarText } from './chunk-V3DX3K65.js';
 
 
 

package/dist/toolbar.d.ts

@@ -3,11 +3,14 @@ import { PaneSeparatorSide } from './pane.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 import { S as Sides } from './sides-BPSWde0A.js';
 
+type ToolbarPosition = 'header' | 'footer';
 interface ToolbarProps {
     leading?: KerfUiContent;
     center?: KerfUiContent;
     trailing?: KerfUiContent;
     label?: string;
+    /** Use footer semantics for a bottom toolbar; defaults to header. */
+    position?: ToolbarPosition;
     /**
      * Physical divider edges in canonical top/right/bottom/left order, drawn
      * always. Defaults to none: a toolbar pinned over or under scrolling content
@@ -17,8 +20,8 @@ interface ToolbarProps {
      * then draws its facing side the same way.
      */
     dividerSides?: Sides;
-    /** Horizontal treatment of the center zone. Defaults to centered content. */
-    centerAlign?: 'center' | 'stretch';
+    /** `balanced` gives both side zones equal tracks, centering the middle zone on the toolbar even if only one side has controls. */
+    centerAlign?: 'center' | 'stretch' | 'balanced';
     /**
      * Component-owned responsive layout; applications choose the policy rather
      * than restyling toolbar internals. Under every policy the trailing zone
@@ -57,6 +60,6 @@ interface ToolbarProps {
  * toolbar) forwards, so the app configures that toolbar instead of styling it.
  */
 type ToolbarConfig = Pick<ToolbarProps, 'dividerSides' | 'centerAlign' | 'responsive' | 'responsiveAt' | 'safeAreaEdges'>;
-declare function Toolbar({ leading, center, trailing, label, dividerSides, centerAlign, responsive, responsiveAt, safeAreaEdges, className, slot, }: ToolbarProps): kerfjs.SafeHtml;
+declare function Toolbar({ leading, center, trailing, label, position, dividerSides, centerAlign, responsive, responsiveAt, safeAreaEdges, className, slot, }: ToolbarProps): kerfjs.SafeHtml;
 
-export { Sides, Toolbar, type ToolbarConfig, type ToolbarProps };
+export { Sides, Toolbar, type ToolbarConfig, type ToolbarPosition, type ToolbarProps };

package/dist/toolbar.js

@@ -1,3 +1,3 @@
-export { Toolbar } from './chunk-MERWRTBG.js';
+export { Toolbar } from './chunk-RGS4WX2M.js';
 
 //# sourceMappingURL=toolbar.js.map

package/dist/wire-catalog.js

@@ -1,4 +1,4 @@
-import { wireWorkbench } from './chunk-NNMLEDMD.js';
+import { wireWorkbench } from './chunk-OBAFAH5B.js';
 
 import { wireScrollDividers } from './chunk-JCV4GXWB.js';
 

package/dist/wire-content-items.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Give interactive ContentItems native-like Enter/Space activation with one
+ * delegated listener pair. Space activates on release and is cancelled if
+ * focus moves; the item's own `data-action` still goes through the app's
+ * ordinary delegated click handler. Returns a disposer.
+ */
+declare function wireContentItems(root: HTMLElement): () => void;
+
+export { wireContentItems };

package/dist/wire-content-items.js

@@ -0,0 +1,62 @@
+// src/wire-content-items.ts
+var ITEM_SELECTOR = '[data-component="content-item"][data-interactive="true"]';
+var NESTED_CONTROL_SELECTOR = 'button, a[href], input, select, textarea, [contenteditable="true"], [role="button"]';
+function actionItem(root, target) {
+  if (!(target instanceof Element)) return null;
+  const item = target.closest(ITEM_SELECTOR);
+  if (!item || !root.contains(item) || item.dataset.disabled === "true")
+    return null;
+  const nested = target.closest(NESTED_CONTROL_SELECTOR);
+  if (nested && nested !== item && item.contains(nested)) return null;
+  return item;
+}
+function wireContentItems(root) {
+  let pendingSpace = null;
+  const clearSpace = () => {
+    pendingSpace?.removeAttribute("data-kui-pressed");
+    pendingSpace = null;
+  };
+  const keydown = (event) => {
+    if (event.defaultPrevented || event.altKey || event.ctrlKey || event.metaKey)
+      return;
+    const item = actionItem(root, event.target);
+    if (!item) return;
+    if (event.key === "Enter") {
+      event.preventDefault();
+      item.click();
+      return;
+    }
+    if (event.key === " " || event.key === "Spacebar") {
+      event.preventDefault();
+      if (event.repeat) return;
+      clearSpace();
+      pendingSpace = item;
+      item.setAttribute("data-kui-pressed", "true");
+    }
+  };
+  const keyup = (event) => {
+    if (event.key !== " " && event.key !== "Spacebar") return;
+    const item = pendingSpace;
+    if (!item) return;
+    event.preventDefault();
+    clearSpace();
+    if (item === actionItem(root, event.target) && item.ownerDocument.activeElement === item)
+      item.click();
+  };
+  const focusout = (event) => {
+    if (event.target === pendingSpace) clearSpace();
+  };
+  root.addEventListener("keydown", keydown);
+  root.addEventListener("keyup", keyup);
+  root.addEventListener("focusout", focusout);
+  return () => {
+    clearSpace();
+    root.removeEventListener("keydown", keydown);
+    root.removeEventListener("keyup", keyup);
+    root.removeEventListener("focusout", focusout);
+  };
+}
+
+export { wireContentItems };
+
+//# sourceMappingURL=wire-content-items.js.map

package/dist/wire-content-items.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/wire-content-items.ts"],"names":[],"mappings":"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","file":"wire-content-items.js","sourcesContent":["const ITEM_SELECTOR =\n  '[data-component=\"content-item\"][data-interactive=\"true\"]';\nconst NESTED_CONTROL_SELECTOR =\n  'button, a[href], input, select, textarea, [contenteditable=\"true\"], [role=\"button\"]';\n\nfunction actionItem(root: HTMLElement, target: EventTarget | null) {\n  if (!(target instanceof Element)) return null;\n  const item = target.closest<HTMLElement>(ITEM_SELECTOR);\n  if (!item || !root.contains(item) || item.dataset.disabled === 'true')\n    return null;\n  const nested = target.closest(NESTED_CONTROL_SELECTOR);\n  if (nested && nested !== item && item.contains(nested)) return null;\n  return item;\n}\n\n/**\n * Give interactive ContentItems native-like Enter/Space activation with one\n * delegated listener pair. Space activates on release and is cancelled if\n * focus moves; the item's own `data-action` still goes through the app's\n * ordinary delegated click handler. Returns a disposer.\n */\nexport function wireContentItems(root: HTMLElement): () => void {\n  let pendingSpace: HTMLElement | null = null;\n\n  const clearSpace = () => {\n    pendingSpace?.removeAttribute('data-kui-pressed');\n    pendingSpace = null;\n  };\n\n  const keydown = (event: KeyboardEvent) => {\n    if (\n      event.defaultPrevented ||\n      event.altKey ||\n      event.ctrlKey ||\n      event.metaKey\n    )\n      return;\n    const item = actionItem(root, event.target);\n    if (!item) return;\n    if (event.key === 'Enter') {\n      event.preventDefault();\n      item.click();\n      return;\n    }\n    if (event.key === ' ' || event.key === 'Spacebar') {\n      event.preventDefault();\n      if (event.repeat) return;\n      clearSpace();\n      pendingSpace = item;\n      item.setAttribute('data-kui-pressed', 'true');\n    }\n  };\n\n  const keyup = (event: KeyboardEvent) => {\n    if (event.key !== ' ' && event.key !== 'Spacebar') return;\n    const item = pendingSpace;\n    if (!item) return;\n    event.preventDefault();\n    clearSpace();\n    if (\n      item === actionItem(root, event.target) &&\n      item.ownerDocument.activeElement === item\n    )\n      item.click();\n  };\n\n  const focusout = (event: FocusEvent) => {\n    if (event.target === pendingSpace) clearSpace();\n  };\n\n  root.addEventListener('keydown', keydown);\n  root.addEventListener('keyup', keyup);\n  root.addEventListener('focusout', focusout);\n  return () => {\n    clearSpace();\n    root.removeEventListener('keydown', keydown);\n    root.removeEventListener('keyup', keyup);\n    root.removeEventListener('focusout', focusout);\n  };\n}\n"]}

package/dist/wire-tab-bars.js

@@ -1,3 +1,3 @@
-export { reorderTabs, wireTabBars } from './chunk-C4OYOKWX.js';
+export { reorderTabs, wireTabBars } from './chunk-UA6JW52D.js';
 
 //# sourceMappingURL=wire-tab-bars.js.map

package/dist/wire-token-search-fields.js

@@ -1,4 +1,5 @@
-export { wireTokenSearchFields } from './chunk-A3CKOW2R.js';
+export { wireTokenSearchFields } from './chunk-R75GGNWY.js';
+
 
 
 

package/dist/wire-workbench.d.ts

@@ -32,6 +32,13 @@ interface WireWorkbenchPanel {
      * keeps Tab inside it, and it closes on Escape or a press outside it.
      */
     collapsed?: Signal<boolean>;
+    /**
+     * Treat presses in a portal surface launched by this panel (for example a
+     * body-level menu or dialog) as inside it. The predicate receives each Node
+     * in the press's composed path; return true for the portal root. Ordinary
+     * presses outside the panel and its allowed surfaces still dismiss it.
+     */
+    keepOpenOn?: (target: Node) => boolean;
 }
 /** A resize the user made, after `wireWorkbench` wrote it to the size signal. */
 interface WorkbenchResize {

package/dist/wire-workbench.js

@@ -1,4 +1,4 @@
-export { wireWorkbench } from './chunk-NNMLEDMD.js';
+export { wireWorkbench } from './chunk-OBAFAH5B.js';
 
 
 

package/dist/workbench.d.ts

@@ -3,7 +3,7 @@ import { ListConfig } from './list.js';
 import { PaneConfig } from './pane.js';
 import { ResizableRegionSeparator, ResizableRegionCollapseMotion, ResizableRegionContentOverflow, ResizableRegionPresentation, ResizableRegionRestorePosition } from './resizable-region.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
-import { a as PanelToolbar, b as PanelToggle } from './panel-toolbar-DqwtBxQL.js';
+import { a as PanelToolbar, b as PanelChromePlacement, c as PanelBottomToolbar, d as PanelToggle } from './panel-toolbar-DDKh4uKd.js';
 import { ToolbarConfig } from './toolbar.js';
 import './css-values.js';
 import './flex-alignment-4ms8ZbV8.js';
@@ -22,6 +22,7 @@ type WorkbenchPanelToggle = PanelToggle;
  * `FloatingToolbar` in the work area's bottom-end corner.
  */
 type WorkbenchPanelToolbar = PanelToolbar;
+type WorkbenchPanelBottomToolbar = PanelBottomToolbar;
 /**
  * The work area's top toolbar; collapsed rails add their groups to it. Its
  * configuration forwards to its `Toolbar`. It draws no divider of its own by
@@ -57,7 +58,7 @@ interface WorkbenchMainBottomToolbar extends ToolbarConfig {
  * the Pane's `chromePlacement="auto"`; it applies to the pinned header and
  * footer together).
  */
-type WorkbenchChromePlacement = 'fixed' | 'scroll' | 'auto';
+type WorkbenchChromePlacement = PanelChromePlacement;
 
 /**
  * The Workbench container breakpoint below which a panel presents as an
@@ -65,7 +66,7 @@ type WorkbenchChromePlacement = 'fixed' | 'scroll' | 'auto';
  * breakpoints as `ResizableRegion`'s `responsiveFillAt` — or `never` to keep
  * it inline at every width.
  */
-type WorkbenchResponsiveOverlayAt = 'compact' | 'narrow' | 'never';
+type WorkbenchResponsiveOverlayAt = 'compact' | 'narrow' | 'never' | number;
 /**
  * How wide a rail's overlay is in a compact (448px or less) Workbench: `inset`
  * fills the Workbench less a dismiss margin on the side away from the rail's
@@ -88,8 +89,20 @@ interface WorkbenchPanel {
      * collapsed. With it, `content` renders in a `Pane` below the toolbar.
      */
     toolbar?: WorkbenchPanelToolbar;
-    /** Optional bottom toolbar under a `toolbar` panel's content. */
+    /** Fixed content below a toolbar panel's top toolbar, above its scroll region. */
+    header?: KerfUiContent;
+    /** List layout for `header`; omitted fields keep List defaults. */
+    headerList?: ListConfig;
+    /** Placement of the top toolbar and header together; default `fixed`. */
+    headerPlacement?: WorkbenchChromePlacement;
+    /** Fixed content above a toolbar panel's bottom toolbar. */
     footer?: KerfUiContent;
+    /** List layout for `footer`; omitted fields keep List defaults. */
+    footerList?: ListConfig;
+    /** Fixed toolbar below `footer`, using footer semantics. */
+    bottomToolbar?: WorkbenchPanelBottomToolbar;
+    /** Placement of the footer and bottom toolbar together; default `fixed`. */
+    footerPlacement?: WorkbenchChromePlacement;
     /**
      * Configuration for a `toolbar` panel's `Pane` (`contentElement`,
      * `contentLabel`, `separators`, `safeAreaEdges`, `chromeDividers`) — for example
@@ -121,8 +134,9 @@ interface WorkbenchPanel {
     presentation?: ResizableRegionPresentation;
     /**
      * Present the panel as an overlay, without a separator, below a Workbench
-     * container breakpoint, and inline above it — the CSS decides, so the app
-     * needs no device-class check. A rail overlays from its side at full
+     * container breakpoint, and inline above it. `compact` and `narrow` use
+     * CSS container queries; a positive number is a pixel threshold measured
+     * by `wireWorkbench` and requires a `collapsed` signal. A rail overlays from its side at full
      * height, over the work area and an open drawer; the bottom drawer
      * overlays the bottom of the work-area column. Rails default to `narrow`
      * (pass `never` to keep one inline); the drawer defaults to inline.
@@ -222,6 +236,8 @@ interface WorkbenchProps {
      * shorter. Workbenches without a drawer ignore it.
      */
     mainMinHeight?: number;
+    /** Dim the work area below any open overlay and absorb outside presses; off by default. */
+    overlayBackdrop?: boolean;
     className?: string;
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
@@ -239,6 +255,6 @@ interface WorkbenchProps {
  * lives outside it and stays reachable). A panel may opt in to drag and keyboard resizing with
  * `resizable`, which `wireWorkbench` drives. See `docs/23-app-layouts.md` §3.3.
  */
-declare function Workbench({ id, label, main, leftRail, rightRail, bottomDrawer, mainToolbar, mainHeader, mainFooter, mainBottomToolbar, mainHeaderPlacement, mainFooterPlacement, mainPane, mainHeaderList, mainFooterList, mainMinSize, mainMinHeight, className, slot, }: WorkbenchProps): SafeHtml;
+declare function Workbench({ id, label, main, leftRail, rightRail, bottomDrawer, mainToolbar, mainHeader, mainFooter, mainBottomToolbar, mainHeaderPlacement, mainFooterPlacement, mainPane, mainHeaderList, mainFooterList, mainMinSize, mainMinHeight, overlayBackdrop, className, slot, }: WorkbenchProps): SafeHtml;
 
-export { Workbench, type WorkbenchChromePlacement, type WorkbenchCompactOverlay, type WorkbenchMainBottomToolbar, type WorkbenchMainToolbar, type WorkbenchPanel, type WorkbenchPanelResizable, type WorkbenchPanelToggle, type WorkbenchPanelToolbar, type WorkbenchProps, type WorkbenchResponsiveOverlayAt };
+export { Workbench, type WorkbenchChromePlacement, type WorkbenchCompactOverlay, type WorkbenchMainBottomToolbar, type WorkbenchMainToolbar, type WorkbenchPanel, type WorkbenchPanelBottomToolbar, type WorkbenchPanelResizable, type WorkbenchPanelToggle, type WorkbenchPanelToolbar, type WorkbenchProps, type WorkbenchResponsiveOverlayAt };

package/dist/workbench.js

@@ -1,4 +1,5 @@
-export { Workbench } from './chunk-Y74NWGQW.js';
+export { Workbench } from './chunk-KFYANKJI.js';
+
 
 
 

package/docs/accessibility.md

@@ -5,7 +5,7 @@ These are normative contracts for package components and consuming applications.
 ## Shared rules
 
 - All controls have accessible names and visible `:focus-visible` treatment.
-- Decorative `LucideIcon` output is `aria-hidden`; pass `label` only when the SVG itself conveys meaning.
+- Decorative `LucideIcon` output is `aria-hidden`; pass `label` only when the SVG itself conveys meaning. `size="xs|s|m|l|xl"` selects the 12/16/20/24/32px root-scaled icon steps, and a positive numeric `size` converts pixels to rem; omitting `size` keeps 1em. Size changes the visual only, never the owning control's hit target or accessible name.
 - `ListItem` uses native button Enter/Space behavior. `selected` maps to `aria-current="page"`; `pressed` maps to `aria-pressed`. Selected rows keep the normal foreground over their brand-tinted fill so text retains WCAG AA contrast in light and dark themes. Its leading icon visual is 18px while the row retains its 44px minimum target; multiline icons align to the first text line. Its `trailing` content is dormant and must not contain controls. Its `rootAttributes` slot accepts only application `data-*` metadata and deliberately cannot emit `role="menuitem"` in isolation—a true ARIA menu must own arrow, Home/End, Escape, and focus behavior as one widget.
 - `ListItemLink` shares that row content and geometry but uses native anchor Enter behavior and requires `href`. It has no `action` or `pressed` state. `external` opens a new tab with `rel="noopener noreferrer"`; the default accessible name announces the new tab for a string label, so an explicit `accessibleLabel` should do the same. Disabled and loading links omit `href`, expose `aria-disabled`, and leave the tab order. Its trailing content remains dormant.
 - `ListHeader` owns action naming, disabled state, and disclosure `aria-expanded`. Toggle mode supplies one decorative 18px `DisclosureArrow` when `actionIcon` is omitted; it mirrors `expanded` while the native button's accessible name stays stable. The application must update that controlled state and reveal or hide real content. A valid `count` is visually rendered in an `aria-hidden` neutral pill while the required localized `countLabel` becomes part of the owning heading or disclosure button's accessible name; zero remains a real count. Its narrow `triggerAttributes` slot may describe a native popover or controlled-content relationship with `popoverTarget`, `popoverTargetAction`, `aria-controls`, and `aria-haspopup`; the application owns the target surface and its focus/dismissal behavior.
@@ -13,9 +13,12 @@ These are normative contracts for package components and consuming applications.
 - `wireNavStack` moves focus into every newly active top view and remembers the last focused descendant of each mounted view for pop restoration. Mark a preferred initial heading or control with `data-nav-focus` (and `tabindex="-1"` when it is not normally tabbable); otherwise the helper uses the first enabled focusable descendant, then a programmatically focusable view-container fallback.
 - In any `.kui-pane`, menu rows, `ListHeader` actions, and toolbar groups keep a minimum 44px target in both dimensions. A `ListHeader` fills the available inline width and keeps that action at the logical end, including in RTL. Its action visual defaults to 18px through `--kui-list-header-action-icon-size` inside a fitted 36px hover square; a transparent hit layer extends the pointer target to at least 44 × 44 around that square without moving layout or enlarging the painted surface. Compact headers are 36px tall like the rest of the compact List family, so their action target is 44px wide and clamped to the 36px header height instead of reaching into a neighboring row. Do not reduce the target to the visible icon, and do not force the button itself to 44px.
 - `LoadingSpinner` is either labeled (`role="img"`) or hidden. Its rotation stops for reduced motion.
+- A busy `ToolbarControlGroup` makes its controls inert and exposes `aria-busy`; its `busyLabel` is announced by an adjacent status node outside the inert group. Clear `busy` when the operation finishes so the controls rejoin the focus order.
+- A bottom `Toolbar` uses `position="footer"` for footer semantics; top toolbars keep the default `header`. Workbench's main bottom toolbar sets this automatically.
+- Interactive `ContentItem` cards have a keyboard reachable button or option role. Set `selectionMode="toggle"` for `aria-pressed`, or `selectionMode="single"` inside a listbox for `aria-selected`; wire `wireContentItems` once so Enter and Space activate their delegated action. Disabled cards expose `aria-disabled` and leave the Tab order.
 - An unlabeled `Skeleton` (including the value slots a component's `placeholder` prop renders) is decorative loading chrome: it is `aria-hidden`, conveys no information a user needs to act on, and is deliberately exempt from the WCAG 3:1 non-text-contrast target. Inside a solid `Badge` it stays subtle (about 2.1–4.4:1 in light, 2.4–2.8:1 in dark, depending on tone); `tests/browser/tone-contrast.spec.ts` holds those values as a regression floor rather than an accessibility threshold. Announce loading through a labeled `Skeleton`, `LoadingSpinner`, or `aria-busy` on the owning region, never through the skeleton's visibility.
 - `StateBanner` defaults to polite `role="status"`; use `urgency="alert"` only for an attention-requiring failure. Its optional `badge` is persistent inline status/count content beside the title and is announced as part of the banner; keep it terse and do not rely on color alone for its meaning.
-- A removable `Chip` has a native button with a specific `removeLabel`, such as "Remove Urgent tag". The button is absent for a plain chip and disabled for a disabled chip. Tag text remains visible because tone does not convey meaning alone.
+- A removable `Chip` has a native button with a specific `removeLabel`, such as "Remove Urgent tag". The button is absent for a plain chip and disabled for a disabled chip. Its leading `icon` is decorative; the visible label names the tag. `truncate` retains the full plain-text label as a native tooltip. Tag text remains visible because tone does not convey meaning alone.
 - `EmptyState` reports busy state through `aria-busy` and never relies on an illustration as its label.
 - `Select` follows the Web Awesome host's standard `input`/`change` events. Application tests verify the live `value`, focus, and events—not attributes alone. Its decorative option icons and value-dependent selected content remain present after controlled rerenders, so the visible choice does not silently lose its non-text cue.
 - `DisclosureArrow` is an 18px root-scaled decorative visual by default, not an interaction target. Its owning native control supplies a stable accessible name, pointer and keyboard interaction, and `aria-expanded`; multiple arrows keep independently controlled state. Consumers may resize it with the typed `size` prop without changing that ownership. Configured directions animate over the shortest path; a 180-degree closed-to-open tie uses counterclockwise rotation.
@@ -205,7 +208,9 @@ open popup. A disabled item stays in the menu but cannot be
 chosen; disable the whole trigger only when every command is unavailable.
 Nested items use Web Awesome's submenu pointer and Left/Right arrow routing;
 headings and dividers can separate nested groups without becoming keyboard
-choices. Checked items expose checkbox menu semantics. `details` supplies optional
+choices. A rapid ArrowDown or ArrowUp after opening a submenu keeps the chosen
+item focused when its show animation finishes. Set `checked` to `true` or `false` for checkbox menu semantics; omit it
+for a plain command. `details` supplies optional
 trailing visual content without changing a command's accessible label. A
 `context` menu's invisible anchor is outside the accessibility tree and normal
 Tab order; opening the menu moves focus into its commands and Escape dismisses
@@ -443,10 +448,21 @@ remove actions, and suggestions are managed. Arrow Down moves from the editor
 to suggestions, arrow keys move between suggestions, Enter selects one, and
 Escape returns focus to the editor. The application still announces results
 when needed and can supply an `evaluate` callback to compute them. Omitting the
-model leaves the manual behavior above intact.
+model leaves the manual behavior above intact. After a chip commit, suggestion
+choice, chip edit, or Backspace/Delete chip removal, focus restoration runs at
+the controlled render checkpoint and keeps the query-relative caret offset;
+it leaves focus on a different control if the user moved there in the meantime.
+Suggestions use Floating UI positioning, following the same viewport-aware
+popup behavior as the Web Awesome controls behind Select and PopupMenu. They
+follow the field while scrolling, flip above it at the bottom edge, and shift
+within narrow viewports without growing its toolbar row. One
+suggestion keeps a pill outline; lists with multiple choices use the standard
+rounded surface and scroll once they reach 240px. The clear button's hover and focus
+highlight follows the field's pill shape or its toolbar group's rounded shape.
 
 Managed clear captures the action before application handlers run, keeps the adopted
-expanded signal open during editor replacement, and restores focus at the actual
+expanded signal open for a collapsible field, and restores the editor focus for
+both collapsible and plain model fields at the actual
 mutation checkpoint before the next input task. It also returns keyboard activation
 from the clear button to a surviving editor immediately. No animation frame owns
 clear focus, so fast typing cannot escape to page shortcuts or lose its first letter. The app still owns clearing query/tokens and emptying

package/docs/catalog.md

@@ -215,6 +215,42 @@ border, and padding. Catalogs for downstream components should conform to the
 contract and can start from the checked
 [`component-catalog-extension.json`](./examples/component-catalog-extension.json)
 example; provide those entries beside Kerf's shipped catalog to AI tools.
+An extension entry may declare `uses` with direct Kerf or extension entry ids,
+plus repository-relative `source` and `demoSource` paths. Keep the ids unique
+and resolvable across both catalogs; paths use `/` separators and cannot
+traverse outside the repository. These fields let consumer demos derive source
+links and composition relationships from the catalog.
+
+For a consumer UX demo, `@kerfjs/ui/catalog-projection` exports
+`projectConsumerCatalog(extension, kerfCatalog, options)` and
+`projectCatalogEntries(entries, options)`. The projection maps `purpose` to
+`description`, `uses` to related-entry ids, `source` to `componentSource`, and
+`demoSource` to the demo source link. It defaults the source identity to
+`consumer` and category to `Application`. Explicit paths in an extension entry
+take precedence over templates. Template placeholders are `{id}`, `{name}`,
+`{kind}`, and `{package}`. Design templates are omitted unless configured.
+
+The package also ships `kerf-catalog-demo` for a committed TypeScript module:
+
+```sh
+kerf-catalog-demo --extension ai/component-catalog-extension.json \
+  --out ux-demo/catalog.generated.ts \
+  --repo-base https://github.com/acme/app/blob/main/ \
+  --source-template 'src/{id}.tsx' \
+  --demo-template 'ux-demo/demos/{id}.tsx' --write
+kerf-catalog-demo --extension ai/component-catalog-extension.json \
+  --out ux-demo/catalog.generated.ts \
+  --repo-base https://github.com/acme/app/blob/main/ \
+  --source-template 'src/{id}.tsx' \
+  --demo-template 'ux-demo/demos/{id}.tsx' --check
+```
+
+The command uses the Kerf catalog shipped with the package to resolve `uses`;
+`--kerf-catalog` selects another catalog file. `--category`,
+`--documentation-template`, and `--design-template` configure optional row
+fields. `--check` fails if the generated file is missing or stale. The output
+exports `generatedConsumerCatalog` and `catalogRepositoryBlobUrl`; the latter
+is normalized to a trailing slash for source and documentation links.
 
 ### Automated conformance and reviewed exceptions
 

package/docs/collapsible-panel.md

@@ -80,9 +80,10 @@ and that of the components it renders (`Pane`, `Toolbar`, `ToolbarControlGroup`,
   corners, with typed `restoreInset` for the corner distance. Set
   `restorePlacement="inline"` when the container should place the control in
   normal flow. An inline region's surface uses
-  `--kui-resizable-region-background`; set `contentOverflow="visible"` while
-  an anchored popup must escape the region's content box, then return to the
-  normal overflow policy when it closes.
+  `--kui-resizable-region-background`; an open descendant `PopupMenu` or Web
+  Awesome dropdown releases clipping and raises the popup layer for its
+  lifecycle. Set `contentOverflow="visible"` for other anchored content that
+  must escape the region's content box.
   Overlay presentation also clamps fixed-size animated content to the configured
   responsive overlay maximum, so a remembered desktop size cannot escape a narrow
   viewport.
@@ -133,7 +134,7 @@ and that of the components it renders (`Pane`, `Toolbar`, `ToolbarControlGroup`,
 
 Give a panel a `toolbar` (the same roles as a
 [Workbench panel toolbar](workbench.md#panel-toolbars)) and it composes its own
-top toolbar over a `Pane`, with an optional `footer` below its content:
+top toolbar over a `Pane`:
 
 - `title` precedes the `leading` zone; `leading`, `center`, and `trailing`
   place groups wherever the open panel needs them;
@@ -141,6 +142,13 @@ top toolbar over a `Pane`, with an optional `footer` below its content:
   work area when the panel closes; the standard `toggle: { action, name,
 showLabel?, hideLabel? }` is always the final group.
 
+The panel can also take `header` under its toolbar, `footer` below its content,
+`bottomToolbar` below that, `headerList` / `footerList` for those fixed content
+stacks, and `headerPlacement` / `footerPlacement` (`fixed`, `scroll`, or `auto`).
+These slots share the panel's one `Pane` scroll owner; the bottom toolbar uses
+footer semantics. With no `toolbar`, the panel renders its children directly
+and ignores the chrome slots.
+
 The toolbar also takes the `Toolbar`'s configuration (`dividerSides`,
 `centerAlign`, `responsive`, `responsiveAt`, `safeAreaEdges`); it draws no
 divider of its own unless `dividerSides` says so. The `Pane` under it draws

package/docs/component-contract.md

@@ -243,6 +243,9 @@ example. Keep app and Kerf entries as package-qualified inputs, then let people
 or AI tools search their combined entries and compare `geometry` before adding
 wrappers or insets. Do not add app-owned entries to Kerf's canonical catalog or
 claim Kerf delivery paths for them.
+Extension entries may add `uses` for direct composition dependencies and
+repository-relative `source` and `demoSource` files. Resolve each dependency
+against the combined Kerf and consumer catalogs; do not duplicate a Kerf id.
 
 - Components own semantic markup, stable anatomy, documented variants, ARIA projection, and package CSS hooks.
 - Applications own signals/stores, product copy, domain-state mapping, persistence, routing, permissions, and transport.
@@ -504,9 +507,10 @@ without application `::part(menu)` CSS; the default `standard` keeps each menu's
 own inset (8px for a raw `wa-dropdown`, the Select listbox's 4px for a
 `PopupMenu`), while `compact` and `list-zero` apply to every nested menu. A
 `PopupMenu` and a `Select` draw one popup: the same caret that turns to face the
-open popup, fade-in surface, surface inset, row height and padding, reserved
-check column, current-row fill, and group titles, all read from one private
-popup-choice contract in `foundation.css`. Compact mixed controls retain the standard
+open popup, fade-in surface, surface inset, row height and padding, current-row
+fill, and group titles, all read from one private popup-choice contract in
+`foundation.css`. Checkbox items reserve a check column; plain commands start
+at the checkmark's leading edge. Compact mixed controls retain the standard
 item padding, omit an internal separator, and let the raised selected item paint
 over the outer border instead of shrinking to an inset highlight. The Web
 Awesome trigger's shadow base owns max-content sizing, so icons, localized text,
@@ -578,7 +582,9 @@ by default it also owns the collapsible field's transient expand/collapse/focus
 state in a signal it exposes on the returned handle. An app reads that signal in
 render, hands in its own via `collapsible.signals`, drives it through
 `handle.open`/`handle.close`, or disables any individual behavior — so transient
-UI is consistent by default without every app reinventing it.
+UI is consistent by default without every app reinventing it. A collapsed
+field may reveal its editor after the current microtask; the helper keeps a
+bounded render-frame focus handoff for that reveal and cancels it on disposal.
 
 A public subpath that exposes several visual components is a folder-backed
 surface. Put each component in its own source file and give each visual