@kerfjs/ui 5.0.0-beta.62 → 5.0.0-beta.64

package/dist/text.js

@@ -1,3 +1,3 @@
-export { Text } from './chunk-AUKT3KMG.js';
+export { Text } from './chunk-CQHN45XR.js';
 
 //# sourceMappingURL=text.js.map

package/dist/{token-search-field-DvgFLhLL.d.ts → token-search-field-Xk8jiw8Y.d.ts}

@@ -60,6 +60,12 @@ interface TokenSearchToken {
     offset?: number;
     accessibleLabel?: string;
 }
+interface TokenSearchTrailingAction {
+    icon: SafeHtml;
+    label: string;
+    action: string;
+    id?: string;
+}
 type TokenSearchEditorAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
     'data-component'?: never;
     'data-key'?: never;
@@ -88,8 +94,9 @@ interface TokenSearchFieldBaseProps {
     tokenPlaceholder?: string;
     disabled?: boolean;
     autofocus?: boolean;
+    /** Let an expanded collapsible field consume the available inline width. */
+    fill?: boolean;
     leading?: KerfUiContent;
-    trailing?: KerfUiContent;
     /** Standalone field chrome or the inset visual layer of a configured toolbar group. */
     presentation?: 'standalone' | 'toolbar-group';
     editAction?: string;
@@ -103,6 +110,13 @@ interface TokenSearchFieldBaseProps {
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
 }
+type TokenSearchTrailingProps = {
+    trailing?: KerfUiContent;
+    trailingAction?: never;
+} | {
+    trailing?: never;
+    trailingAction: TokenSearchTrailingAction;
+};
 type TokenSearchCollapsibleProps = {
     /** Allow an empty field to render as one iconic action. */
     collapsible: true;
@@ -116,15 +130,15 @@ type TokenSearchCollapsibleProps = {
     expandAction?: never;
     expandLabel?: never;
 };
-type TokenSearchFieldProps = TokenSearchFieldBaseProps & TokenSearchCollapsibleProps;
+type TokenSearchFieldProps = TokenSearchFieldBaseProps & TokenSearchCollapsibleProps & TokenSearchTrailingProps;
 interface TokenSearchFieldValue {
     query: string;
     tokens: TokenSearchToken[];
 }
-declare function TokenSearchField({ id, label, query, tokens, model, revision, placeholder, tokenPlaceholder, disabled, autofocus, collapsible, expanded, expandAction, expandLabel, leading, trailing, presentation, editAction, removeAction, clearAction, clearLabel, clearIcon, className, editorAttributes, slot, }: TokenSearchFieldProps): SafeHtml;
+declare function TokenSearchField({ id, label, query, tokens, model, revision, placeholder, tokenPlaceholder, disabled, autofocus, fill, collapsible, expanded, expandAction, expandLabel, leading, trailing, trailingAction, presentation, editAction, removeAction, clearAction, clearLabel, clearIcon, className, editorAttributes, slot, }: TokenSearchFieldProps): SafeHtml;
 /** Read editable text and ordered token offsets from a rendered TokenSearchField editor. */
 declare function readTokenSearchField(editor: HTMLElement, knownTokens?: readonly TokenSearchToken[]): TokenSearchFieldValue;
 /** Focus an editor and place its caret at a text offset, skipping atomic token chips. */
 declare function placeTokenSearchCaret(editor: HTMLElement, offset?: number): void;
 
-export { type TokenSearchEditorAttributes as T, TokenSearchField as a, type TokenSearchFieldProps as b, type TokenSearchFieldValue as c, type TokenSearchModel as d, type TokenSearchModelOptions as e, type TokenSearchResolvedToken as f, type TokenSearchRule as g, type TokenSearchState as h, type TokenSearchSuggestion as i, type TokenSearchToken as j, createTokenSearchModel as k, placeTokenSearchCaret as p, readTokenSearchField as r };
+export { type TokenSearchEditorAttributes as T, TokenSearchField as a, type TokenSearchFieldProps as b, type TokenSearchFieldValue as c, type TokenSearchModel as d, type TokenSearchModelOptions as e, type TokenSearchResolvedToken as f, type TokenSearchRule as g, type TokenSearchState as h, type TokenSearchSuggestion as i, type TokenSearchToken as j, type TokenSearchTrailingAction as k, createTokenSearchModel as l, placeTokenSearchCaret as p, readTokenSearchField as r };

package/dist/token-search-field.d.ts

@@ -1,3 +1,3 @@
 import 'kerfjs';
 import './semantic-content-BbzjvSu9.js';
-export { T as TokenSearchEditorAttributes, a as TokenSearchField, b as TokenSearchFieldProps, c as TokenSearchFieldValue, j as TokenSearchToken, p as placeTokenSearchCaret, r as readTokenSearchField } from './token-search-field-DvgFLhLL.js';
+export { T as TokenSearchEditorAttributes, a as TokenSearchField, b as TokenSearchFieldProps, c as TokenSearchFieldValue, j as TokenSearchToken, k as TokenSearchTrailingAction, p as placeTokenSearchCaret, r as readTokenSearchField } from './token-search-field-Xk8jiw8Y.js';

package/dist/token-search-field.js

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

package/dist/token-search-model.d.ts

@@ -1,3 +1,3 @@
 import 'kerfjs';
-export { d as TokenSearchModel, e as TokenSearchModelOptions, f as TokenSearchResolvedToken, g as TokenSearchRule, h as TokenSearchState, i as TokenSearchSuggestion, k as createTokenSearchModel } from './token-search-field-DvgFLhLL.js';
+export { d as TokenSearchModel, e as TokenSearchModelOptions, f as TokenSearchResolvedToken, g as TokenSearchRule, h as TokenSearchState, i as TokenSearchSuggestion, l as createTokenSearchModel } from './token-search-field-Xk8jiw8Y.js';
 import './semantic-content-BbzjvSu9.js';

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.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
@@ -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-N2DRU35S.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-TJK44RQC.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,66 @@
+// 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, event) {
+  const target = event.target;
+  if (!(target instanceof Element)) return null;
+  const item = target.closest(ITEM_SELECTOR);
+  if (!item || !root.contains(item) || item.dataset.disabled === "true")
+    return null;
+  for (const node of event.composedPath()) {
+    if (node === item) break;
+    if (node instanceof Element && node.matches(NESTED_CONTROL_SELECTOR))
+      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);
+    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) && 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, event: Event) {\n  const target = event.target;\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  // Composed events expose native controls inside a custom element's shadow\n  // root even though event.target is retargeted to its host here.\n  for (const node of event.composedPath()) {\n    if (node === item) break;\n    if (node instanceof Element && node.matches(NESTED_CONTROL_SELECTOR))\n      return null;\n  }\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);\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) &&\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-token-search-fields.d.ts

@@ -1,5 +1,5 @@
 import { Signal } from 'kerfjs';
-import { d as TokenSearchModel } from './token-search-field-DvgFLhLL.js';
+import { d as TokenSearchModel } from './token-search-field-Xk8jiw8Y.js';
 import './semantic-content-BbzjvSu9.js';
 
 interface TokenSearchSubmit {

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

@@ -1,4 +1,5 @@
-export { wireTokenSearchFields } from './chunk-A3CKOW2R.js';
+export { wireTokenSearchFields } from './chunk-M5H2RMCH.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-TJK44RQC.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-X6ADHJNI.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.
@@ -203,9 +206,15 @@ are presentational. A keyboard-focused item is the menu's current row, painted
 with the Select's current-option fill rather than a second focus ring inside the
 open popup. A disabled item stays in the menu but cannot be
 chosen; disable the whole trigger only when every command is unavailable.
+Clicking outside dismisses a context `PopupMenu`, including one reopened while
+its previous hide animation is still finishing.
 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. If a submenu is reopened during
+its close animation, it remains visible; pointer and ArrowRight actions also
+recover a submenu left hidden with an open state. 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
@@ -427,7 +436,11 @@ it) with `data-token-search-keep-open`, or pass `collapsible.keepOpenOn(target)`
 so focus or pointer activation moving into it does not collapse an empty field.
 The helper preserves the pointer target when a browser omits
 `focusout.relatedTarget`, preventing the field or target from disappearing
-between pointerdown and click. `wireTokenSearchFields`
+between pointerdown and click. For an empty field losing focus during a pointer
+press, managed collapse waits until that press's click has dispatched (or the
+press ends without a click), then rechecks focus and content before closing.
+This keeps a shifting search row from moving the pressed control mid-click.
+`wireTokenSearchFields`
 can also, opt-in via `keyboard`, own atomic-chip editing keys: from a collapsed
 caret with no selection, Backspace removes the token before the caret and Delete
 the token after it (reported through `onRemoveToken` for the app to apply to its
@@ -443,10 +456,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

@@ -117,8 +117,12 @@ own overlay implementation.
   spacing wrapper. A composition row may place the composition root there.
 
 Use `align="glyph"` for a bare glyph/text specimen, `align="inline-control"`
-for a control whose own inline padding contributes about 8px, and `align="none"`
-(the default) for a content item or composition that owns its geometry.
+for a control whose own inline padding contributes about 8px, and
+`align="text-trigger"` for a Web Awesome dropdown's text trigger whose visible
+label needs an 8px inset (such as a plain `PopupMenu` trigger). The dropdown host
+has no layout box, so this inset applies to its button child. Use
+`align="none"` (the default) for a content item or composition that owns its
+geometry.
 
 ```tsx
 import { CatalogExample, CatalogExampleStack } from "@kerfjs/ui/catalog";
@@ -215,6 +219,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

@@ -134,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;
@@ -142,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.
@@ -425,7 +428,9 @@ tones can be rethemed globally with
 segmented-control, app-tab, and tab-bar colors likewise use their public
 `--kui-*-*` variables. `SegmentedControl` exposes surface, border, foreground,
 hover, and selected-state variables, so rounded, pill, and toolbar presentations
-remain opinionated but locally overridable.
+remain opinionated but locally overridable. Its label color switches with the
+theme without Web Awesome's native button color transition, so a dark filled
+track never briefly pairs with an interpolated low-contrast label.
 
 Inset hover and selection surfaces follow the outer control shape instead of
 choosing an independent radius. `--kui-layout-highlight-inset` is the full
@@ -478,6 +483,15 @@ declarations.
 one child 8px inline margin, a real 1px border, 8px padding, and 12px corners;
 the border stays transparent unless `frame="framed"`, so framing never changes
 geometry. `shape="pill"` selects the 22px radius.
+`flush` removes block padding and borders while preserving inline geometry;
+`title` passes through as the native tooltip. Interactive hover uses the normal
+neutral fill so it remains visible on a lowered surface. For a card with
+multiple actions, put sibling buttons in a static ContentItem (or use
+`ListActionRow` for a simple two-action row).
+For an interactive ContentItem, `wireContentItems` activates the card on Enter
+or Space only when the key event originated from the card itself. A nested
+native control, including one inside a custom element's shadow root, keeps its
+own keyboard activation.
 
 `ToolbarControlGroup` is the unit of toolbar organization, even for dormant
 text. Each group reserves `calc(2px + remify(42px))`, or 44px, with 8px between
@@ -504,13 +518,26 @@ 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, beside the group title rather than the
+farther-in Select option label. Checked submenu items keep their checkmark and
+label inside the submenu surface. 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,
 and the shadow caret determine the width without a fixed host measurement.
+With `popup-menu/register` loaded, PopupMenu and a raw dropdown inside
+`PopupSurface` preserve item navigation made during the Web Awesome show
+animation across its final initial-focus handoff.
+At viewport widths of 480px or less, `PopupMenu` places an open submenu above
+or below its parent menu, choosing the side with room and constraining the
+submenu to the viewport. It never paints over the parent list. The submenu
+remains a native Web Awesome `menu`: the reverse horizontal arrow (ArrowLeft in
+LTR, ArrowRight in RTL) returns focus to its parent item, Escape dismisses the
+menu, and choosing a child dispatches the normal
+`data-action` and `wa-select` events. Wider viewports retain the side cascade.
 The enclosing `Toolbar` owns zone alignment and responsive topology: use
 `centerAlign="stretch"` when the center group should consume its track, and
 choose `responsive="stack"` with `responsiveAt="compact" | "narrow"`,
@@ -578,7 +605,18 @@ 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.
+`TokenSearchField.trailingAction` supplies an icon, accessible `label`, delegated
+`action`, and optional `id`; the field renders a 24px wide button that fills its
+34px line slot, including the hit target, disabled state, hover, and focus ring.
+Use `trailing` for passive content. The two props are mutually exclusive.
+For a collapsible search in a stretched Toolbar center, `fill` lets the expanded
+field and its enclosing search `ToolbarControlGroup` consume the available width;
+the collapsed action retains its fixed icon width.
+Grammar suggestion rows align their labels to one leading edge inside the
+anchored popover, including when the labels have different lengths.
 
 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