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

package/dist/styles/{menu-header.css → list-header.css}

@@ -1,8 +1,8 @@
-.kui-menu-header {
-  --kui-menu-header-color: var(--kui-color-neutral-on-quiet);
-  --kui-menu-header-hover-background: var(--kui-color-neutral-border-quiet);
-  --_kui-menu-header-action-icon-size: var(
-    --kui-menu-header-action-icon-size,
+.kui-list-header {
+  --kui-list-header-color: var(--kui-color-neutral-on-quiet);
+  --kui-list-header-hover-background: var(--kui-color-neutral-border-quiet);
+  --_kui-list-header-action-icon-size: var(
+    --kui-list-header-action-icon-size,
     1.125rem
   );
   display: flex;
@@ -12,14 +12,14 @@
   margin-inline: var(--kui-layout-inline-margin, 0.5rem);
   padding: 0;
   box-sizing: border-box;
-  color: var(--kui-menu-header-color);
+  color: var(--kui-list-header-color);
   background: transparent;
   align-items: stretch;
   gap: var(--kui-layout-item-gap, 0.5rem);
 }
 
-.kui-menu-header__title,
-.kui-menu-header__action {
+.kui-list-header__title,
+.kui-list-header__action {
   box-sizing: border-box;
   border: 1px solid transparent;
   border-radius: var(--kui-layout-rounded-radius, calc(1px + 0.6875rem));
@@ -27,7 +27,7 @@
   background: transparent;
 }
 
-.kui-menu-header__title {
+.kui-list-header__title {
   display: flex;
   min-width: 0;
   min-height: 2.75rem;
@@ -39,7 +39,7 @@
   text-align: start;
 }
 
-.kui-menu-header__label {
+.kui-list-header__label {
   min-width: 0;
   margin: 0;
   overflow: hidden;
@@ -51,7 +51,7 @@
   white-space: nowrap;
 }
 
-.kui-menu-header__badge {
+.kui-list-header__badge {
   display: inline-flex;
   min-height: 1.5rem;
   padding-inline: var(--kui-layout-item-padding, 0.5rem);
@@ -66,7 +66,7 @@
   line-height: 1;
 }
 
-.kui-menu-header__count {
+.kui-list-header__count {
   display: inline-grid;
   min-width: 1.35rem;
   height: 1.35rem;
@@ -78,7 +78,7 @@
   place-items: center;
   flex: none;
   font-size: var(
-    --kui-menu-header-count-font-size,
+    --kui-list-header-count-font-size,
     var(--wa-font-size-3xs, 0.625rem)
   );
   font-weight: 700;
@@ -86,26 +86,26 @@
   line-height: 1;
 }
 
-.kui-menu-header__action,
-.kui-menu-header__action-layer {
+.kui-list-header__action,
+.kui-list-header__action-layer {
   display: grid;
   place-items: center;
 }
 
-.kui-menu-header__action {
+.kui-list-header__action {
   /* A fitted square: the icon size plus its padding and 1px border, instead of a
      forced 44px box that left an oversized halo around the ~18px icon and, via the
      parent's align-items: stretch, a vertically stretched oval. `align-self:
      center` keeps it centered in the header's 44px row without stretching. Sizing
      off the icon variable keeps it square and correct at any icon size. */
-  --_kui-menu-header-action-size: calc(
-    var(--_kui-menu-header-action-icon-size) +
+  --_kui-list-header-action-size: calc(
+    var(--_kui-list-header-action-icon-size) +
       (2 * var(--kui-layout-item-padding, 0.5rem)) + 2px
   );
   appearance: none;
   display: inline-flex;
-  width: var(--_kui-menu-header-action-size);
-  height: var(--_kui-menu-header-action-size);
+  width: var(--_kui-list-header-action-size);
+  height: var(--_kui-list-header-action-size);
   padding: var(--kui-layout-item-padding, 0.5rem);
   align-items: center;
   justify-content: center;
@@ -114,47 +114,47 @@
   flex: none;
 }
 
-.kui-menu-header__toggle {
+.kui-list-header__toggle {
   appearance: none;
   width: 100%;
   cursor: pointer;
 }
 
-.kui-menu-header__action-layer {
+.kui-list-header__action-layer {
   width: 1.5rem;
   height: 1.5rem;
   margin-inline-start: auto;
   flex: none;
 }
 
-.kui-menu-header__action:hover,
-.kui-menu-header__toggle:hover {
+.kui-list-header__action:hover,
+.kui-list-header__toggle:hover {
   border-color: var(--kui-color-neutral-border-normal);
-  background: var(--kui-menu-header-hover-background);
+  background: var(--kui-list-header-hover-background);
 }
 
-.kui-menu-header__action:focus-visible,
-.kui-menu-header__toggle:focus-visible {
+.kui-list-header__action:focus-visible,
+.kui-list-header__toggle:focus-visible {
   outline: var(--kui-focus-ring);
   outline-offset: 1px;
 }
 
-.kui-menu-header__action:disabled {
+.kui-list-header__action:disabled {
   cursor: not-allowed;
   opacity: 0.48;
 }
 
-.kui-menu-header__action:disabled:hover {
+.kui-list-header__action:disabled:hover {
   border-color: transparent;
   background: transparent;
 }
 
-.kui-menu-header__action > svg,
-.kui-menu-header__action-layer > svg {
+.kui-list-header__action > svg,
+.kui-list-header__action-layer > svg {
   /* min-block-size: 0 overrides the flex item's automatic minimum, which would
      otherwise resolve to the icon SVG's intrinsic 24px viewBox height and stretch
      the button past its used icon size. */
-  width: var(--_kui-menu-header-action-icon-size);
-  height: var(--_kui-menu-header-action-icon-size);
+  width: var(--_kui-list-header-action-icon-size);
+  height: var(--_kui-list-header-action-icon-size);
   min-block-size: 0;
 }

package/dist/styles/list-item.css

@@ -0,0 +1,123 @@
+.kui-list-item {
+  --kui-list-item-color: var(--kui-color-neutral-on-normal);
+  --kui-list-item-border: transparent;
+  --kui-list-item-background: transparent;
+  --kui-list-item-hover-border: var(--kui-color-neutral-border-normal);
+  --kui-list-item-hover-background: var(--kui-color-neutral-fill-quiet);
+  --kui-list-item-selected-color: var(--kui-color-brand-on-quiet);
+  --kui-list-item-selected-border: var(--kui-color-brand-border-quiet);
+  --kui-list-item-selected-background: var(--kui-color-brand-fill-normal);
+  display: grid;
+  width: calc(100% - (2 * var(--kui-layout-inline-margin, 0.5rem)));
+  min-height: 2.75rem;
+  margin-inline: var(--kui-layout-inline-margin, 0.5rem);
+  padding: var(--kui-layout-item-padding, 0.5rem);
+  box-sizing: border-box;
+  border: 1px solid var(--kui-list-item-border);
+  border-radius: var(--kui-layout-rounded-radius, calc(1px + 0.6875rem));
+  color: var(--kui-list-item-color);
+  background: var(--kui-list-item-background);
+  cursor: pointer;
+  grid-template-columns: minmax(0, 1fr) auto;
+  align-items: center;
+  column-gap: var(--kui-layout-item-gap, 0.5rem);
+  font: inherit;
+  text-align: start;
+}
+
+.kui-list-item[data-has-icon="true"] {
+  grid-template-columns: 1.5rem minmax(0, 1fr) auto;
+}
+
+.kui-list-item[data-has-icon="true"] .kui-list-item__icon {
+  grid-column: 1;
+}
+
+.kui-list-item[data-has-icon="true"] .kui-list-item__label {
+  grid-column: 2;
+}
+
+.kui-list-item[data-has-icon="true"] .kui-list-item__trailing {
+  grid-column: 3;
+}
+
+.kui-list-item[data-has-icon="false"] .kui-list-item__label {
+  grid-column: 1;
+}
+
+.kui-list-item[data-has-icon="false"] .kui-list-item__trailing {
+  grid-column: 2;
+}
+
+.kui-list-item:hover {
+  border-color: var(--kui-list-item-hover-border);
+  background: var(--kui-list-item-hover-background);
+}
+
+.kui-list-item:disabled {
+  color: var(--kui-color-neutral-on-quiet);
+  cursor: not-allowed;
+  opacity: 0.58;
+}
+
+.kui-list-item[aria-current="page"],
+.kui-list-item[aria-pressed="true"] {
+  border-color: var(--kui-list-item-selected-border);
+  color: var(--kui-list-item-selected-color);
+  background: var(--kui-list-item-selected-background);
+  font-weight: 650;
+}
+
+.kui-list-item:focus-visible {
+  outline: var(--kui-focus-ring);
+  outline-offset: 1px;
+}
+
+.kui-list-item__icon {
+  display: grid;
+  width: 1.5rem;
+  height: 1.5rem;
+  color: currentColor;
+  place-items: center;
+}
+
+.kui-list-item__icon svg {
+  display: block;
+  width: 1.5rem;
+  height: 1.5rem;
+}
+
+.kui-list-item__label {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.kui-list-item[data-multiline="true"] {
+  height: fit-content;
+  white-space: normal;
+}
+
+.kui-list-item[data-multiline="true"] .kui-list-item__label {
+  overflow: visible;
+  white-space: normal;
+}
+
+.kui-list-item[data-multiline="true"] .kui-list-item__icon {
+  align-self: start;
+  margin-block-start: calc((1lh - 1.5rem) / 2);
+}
+
+.kui-list-item__trailing {
+  display: inline-flex;
+  min-width: 0;
+  align-items: center;
+  justify-content: flex-end;
+  gap: var(--kui-layout-item-gap, 0.5rem);
+}
+
+.kui-list-item__trailing > svg {
+  width: 1rem;
+  height: 1rem;
+}

package/dist/styles/styles.css

@@ -5,11 +5,12 @@
 @import "./toolbar.css";
 @import "./toolbar-control-group.css";
 @import "./toolbar-text.css";
-@import "./menu-action-row.css";
-@import "./menu-item.css";
-@import "./menu-header.css";
+@import "./list-action-row.css";
+@import "./list-item.css";
+@import "./list-header.css";
 @import "./resizable-region.css";
 @import "./app-tab.css";
+@import "./catalog.css";
 @import "./tab-bar.css";
 @import "./loading-spinner.css";
 @import "./skeleton.css";

package/dist/toolbar-text.d.ts

@@ -1,15 +1,23 @@
 import * as kerfjs from 'kerfjs';
 
 type ToolbarTextSize = 'xlarge' | 'large' | 'default' | 'small';
+/** ARIA heading level for a title exposed as a heading landmark. */
+type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
 interface ToolbarTextProps {
     text: string;
     size?: ToolbarTextSize;
     className?: string;
     /** Optional id, e.g. so a dialog can reference the title via aria-labelledby. */
     id?: string;
+    /**
+     * Expose heading semantics (`role="heading"` + `aria-level`) so the text acts as
+     * a heading landmark — e.g. a page's primary title. Omit to keep the plain span
+     * (the default), which suits a dialog title referenced via `aria-labelledby`.
+     */
+    headingLevel?: HeadingLevel;
     /** Render the text as an unanimated loading skeleton instead of its value. */
     placeholder?: boolean;
 }
-declare function ToolbarText({ text, size, className, id, placeholder }: ToolbarTextProps): kerfjs.SafeHtml;
+declare function ToolbarText({ text, size, className, id, headingLevel, placeholder }: ToolbarTextProps): kerfjs.SafeHtml;
 
-export { ToolbarText, type ToolbarTextProps, type ToolbarTextSize };
+export { type HeadingLevel, ToolbarText, type ToolbarTextProps, type ToolbarTextSize };

package/dist/toolbar-text.js

@@ -1,4 +1,4 @@
-export { ToolbarText } from './chunk-KJYXOTG3.js';
+export { ToolbarText } from './chunk-RUNWEPR4.js';
 
 
 //# sourceMappingURL=toolbar-text.js.map

package/dist/value-table.js

@@ -1,4 +1,4 @@
-export { ValueTable, ValueTableRow } from './chunk-PONXLV5U.js';
+export { ValueTable, ValueTableRow } from './chunk-37T3VNIZ.js';
 
 
 //# sourceMappingURL=value-table.js.map

package/dist/wire-catalog.d.ts

@@ -0,0 +1,26 @@
+interface WireCatalogOptions {
+    /** Invoked with the entry id when a sidebar item or a related-entry option is chosen. */
+    onSelect: (id: string) => void;
+    /** Invoked when the sidebar collapse/expand control is activated. */
+    onToggleSidebar?: () => void;
+    /** Invoked when the theme toggle is activated. */
+    onToggleTheme?: () => void;
+    /** Invoked when the secondary (ecosystem) group's disclosure toggle is activated. */
+    onToggleSecondary?: () => void;
+    /** When set, `?<urlParam>=<id>` is written on select via `history.replaceState`. */
+    urlParam?: string;
+    selectAction?: string;
+    toggleSidebarAction?: string;
+    toggleThemeAction?: string;
+    toggleSecondaryAction?: string;
+}
+/**
+ * Wire a {@link Catalog}'s interactions with one delegated listener set: sidebar
+ * item selection (and the related-entry selector), the sidebar collapse toggle, and
+ * the theme toggle. The app owns the `active`/`collapsed`/`theme` signals and updates
+ * them in the callbacks; optionally mirror the active id into the URL via `urlParam`.
+ * Returns a disposer.
+ */
+declare function wireCatalog(root: HTMLElement, { onSelect, onToggleSidebar, onToggleTheme, onToggleSecondary, urlParam, selectAction, toggleSidebarAction, toggleThemeAction, toggleSecondaryAction, }: WireCatalogOptions): () => void;
+
+export { type WireCatalogOptions, wireCatalog };

package/dist/wire-catalog.js

@@ -0,0 +1,50 @@
+import { delegate } from 'kerfjs';
+
+// src/wire-catalog.ts
+function wireCatalog(root, {
+  onSelect,
+  onToggleSidebar,
+  onToggleTheme,
+  onToggleSecondary,
+  urlParam,
+  selectAction = "catalog-select",
+  toggleSidebarAction = "catalog-toggle-sidebar",
+  toggleThemeAction = "catalog-toggle-theme",
+  toggleSecondaryAction = "catalog-toggle-secondary"
+}) {
+  const select = (id) => {
+    onSelect(id);
+    const view = root.ownerDocument.defaultView;
+    if (urlParam && view) {
+      const url = new URL(view.location.href);
+      url.searchParams.set(urlParam, id);
+      view.history.replaceState(null, "", url);
+    }
+  };
+  const disposers = [
+    delegate(root, "click", `[data-action="${selectAction}"]`, (_event, element) => {
+      const id = element.dataset.itemId;
+      if (id) select(id);
+    }),
+    delegate(root, "change", '[data-catalog-related] [data-component="select"]', (event) => {
+      const value = event.target.value;
+      if (value) select(value);
+    })
+  ];
+  if (onToggleSidebar) {
+    disposers.push(delegate(root, "click", `[data-action="${toggleSidebarAction}"]`, () => onToggleSidebar()));
+  }
+  if (onToggleTheme) {
+    disposers.push(delegate(root, "click", `[data-action="${toggleThemeAction}"]`, () => onToggleTheme()));
+  }
+  if (onToggleSecondary) {
+    disposers.push(delegate(root, "click", `[data-action="${toggleSecondaryAction}"]`, () => onToggleSecondary()));
+  }
+  return () => {
+    for (const dispose of disposers.splice(0)) dispose();
+  };
+}
+
+export { wireCatalog };
+
+//# sourceMappingURL=wire-catalog.js.map

package/dist/wire-catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/wire-catalog.ts"],"names":[],"mappings":";;;AA0BO,SAAS,YACd,IAAA,EACA;AAAA,EACE,QAAA;AAAA,EACA,eAAA;AAAA,EACA,aAAA;AAAA,EACA,iBAAA;AAAA,EACA,QAAA;AAAA,EACA,YAAA,GAAe,gBAAA;AAAA,EACf,mBAAA,GAAsB,wBAAA;AAAA,EACtB,iBAAA,GAAoB,sBAAA;AAAA,EACpB,qBAAA,GAAwB;AAC1B,CAAA,EACY;AACZ,EAAA,MAAM,MAAA,GAAS,CAAC,EAAA,KAAe;AAC7B,IAAA,QAAA,CAAS,EAAE,CAAA;AACX,IAAA,MAAM,IAAA,GAAO,KAAK,aAAA,CAAc,WAAA;AAChC,IAAA,IAAI,YAAY,IAAA,EAAM;AACpB,MAAA,MAAM,GAAA,GAAM,IAAI,GAAA,CAAI,IAAA,CAAK,SAAS,IAAI,CAAA;AACtC,MAAA,GAAA,CAAI,YAAA,CAAa,GAAA,CAAI,QAAA,EAAU,EAAE,CAAA;AACjC,MAAA,IAAA,CAAK,OAAA,CAAQ,YAAA,CAAa,IAAA,EAAM,EAAA,EAAI,GAAG,CAAA;AAAA,IACzC;AAAA,EACF,CAAA;AAEA,EAAA,MAAM,SAAA,GAA+B;AAAA,IACnC,QAAA,CAAS,MAAM,OAAA,EAAS,CAAA,cAAA,EAAiB,YAAY,CAAA,EAAA,CAAA,EAAM,CAAC,QAAQ,OAAA,KAAY;AAC9E,MAAA,MAAM,EAAA,GAAM,QAAwB,OAAA,CAAQ,MAAA;AAC5C,MAAA,IAAI,EAAA,SAAW,EAAE,CAAA;AAAA,IACnB,CAAC,CAAA;AAAA,IACD,QAAA,CAAS,IAAA,EAAM,QAAA,EAAU,kDAAA,EAAoD,CAAC,KAAA,KAAU;AACtF,MAAA,MAAM,KAAA,GAAS,MAAM,MAAA,CAA4C,KAAA;AACjE,MAAA,IAAI,KAAA,SAAc,KAAK,CAAA;AAAA,IACzB,CAAC;AAAA,GACH;AACA,EAAA,IAAI,eAAA,EAAiB;AACnB,IAAA,SAAA,CAAU,IAAA,CAAK,QAAA,CAAS,IAAA,EAAM,OAAA,EAAS,CAAA,cAAA,EAAiB,mBAAmB,CAAA,EAAA,CAAA,EAAM,MAAM,eAAA,EAAiB,CAAC,CAAA;AAAA,EAC3G;AACA,EAAA,IAAI,aAAA,EAAe;AACjB,IAAA,SAAA,CAAU,IAAA,CAAK,QAAA,CAAS,IAAA,EAAM,OAAA,EAAS,CAAA,cAAA,EAAiB,iBAAiB,CAAA,EAAA,CAAA,EAAM,MAAM,aAAA,EAAe,CAAC,CAAA;AAAA,EACvG;AACA,EAAA,IAAI,iBAAA,EAAmB;AACrB,IAAA,SAAA,CAAU,IAAA,CAAK,QAAA,CAAS,IAAA,EAAM,OAAA,EAAS,CAAA,cAAA,EAAiB,qBAAqB,CAAA,EAAA,CAAA,EAAM,MAAM,iBAAA,EAAmB,CAAC,CAAA;AAAA,EAC/G;AACA,EAAA,OAAO,MAAM;AACX,IAAA,KAAA,MAAW,OAAA,IAAW,SAAA,CAAU,MAAA,CAAO,CAAC,GAAG,OAAA,EAAQ;AAAA,EACrD,CAAA;AACF","file":"wire-catalog.js","sourcesContent":["import { delegate } from 'kerfjs';\n\nexport interface WireCatalogOptions {\n  /** Invoked with the entry id when a sidebar item or a related-entry option is chosen. */\n  onSelect: (id: string) => void;\n  /** Invoked when the sidebar collapse/expand control is activated. */\n  onToggleSidebar?: () => void;\n  /** Invoked when the theme toggle is activated. */\n  onToggleTheme?: () => void;\n  /** Invoked when the secondary (ecosystem) group's disclosure toggle is activated. */\n  onToggleSecondary?: () => void;\n  /** When set, `?<urlParam>=<id>` is written on select via `history.replaceState`. */\n  urlParam?: string;\n  selectAction?: string;\n  toggleSidebarAction?: string;\n  toggleThemeAction?: string;\n  toggleSecondaryAction?: string;\n}\n\n/**\n * Wire a {@link Catalog}'s interactions with one delegated listener set: sidebar\n * item selection (and the related-entry selector), the sidebar collapse toggle, and\n * the theme toggle. The app owns the `active`/`collapsed`/`theme` signals and updates\n * them in the callbacks; optionally mirror the active id into the URL via `urlParam`.\n * Returns a disposer.\n */\nexport function wireCatalog(\n  root: HTMLElement,\n  {\n    onSelect,\n    onToggleSidebar,\n    onToggleTheme,\n    onToggleSecondary,\n    urlParam,\n    selectAction = 'catalog-select',\n    toggleSidebarAction = 'catalog-toggle-sidebar',\n    toggleThemeAction = 'catalog-toggle-theme',\n    toggleSecondaryAction = 'catalog-toggle-secondary',\n  }: WireCatalogOptions,\n): () => void {\n  const select = (id: string) => {\n    onSelect(id);\n    const view = root.ownerDocument.defaultView;\n    if (urlParam && view) {\n      const url = new URL(view.location.href);\n      url.searchParams.set(urlParam, id);\n      view.history.replaceState(null, '', url);\n    }\n  };\n\n  const disposers: Array<() => void> = [\n    delegate(root, 'click', `[data-action=\"${selectAction}\"]`, (_event, element) => {\n      const id = (element as HTMLElement).dataset.itemId;\n      if (id) select(id);\n    }),\n    delegate(root, 'change', '[data-catalog-related] [data-component=\"select\"]', (event) => {\n      const value = (event.target as HTMLElement & { value?: string }).value;\n      if (value) select(value);\n    }),\n  ];\n  if (onToggleSidebar) {\n    disposers.push(delegate(root, 'click', `[data-action=\"${toggleSidebarAction}\"]`, () => onToggleSidebar()));\n  }\n  if (onToggleTheme) {\n    disposers.push(delegate(root, 'click', `[data-action=\"${toggleThemeAction}\"]`, () => onToggleTheme()));\n  }\n  if (onToggleSecondary) {\n    disposers.push(delegate(root, 'click', `[data-action=\"${toggleSecondaryAction}\"]`, () => onToggleSecondary()));\n  }\n  return () => {\n    for (const dispose of disposers.splice(0)) dispose();\n  };\n}\n"]}

package/docs/accessibility.md

@@ -6,18 +6,18 @@ These are normative contracts for package components and consuming applications.
 
 - 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.
-- `MenuItem` uses native button Enter/Space behavior. `selected` maps to `aria-current="page"`; `pressed` maps to `aria-pressed`. 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.
-- `MenuHeader` 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.
-- In any `.kui-pane`, menu rows, `MenuHeader` actions, and toolbar groups keep a minimum 44px target in both dimensions. A `MenuHeader` fills the available inline width and keeps that action at the logical end, including in RTL. Its action visual defaults to 18px through `--kui-menu-header-action-icon-size`; do not reduce the target to the visible icon.
+- `ListItem` uses native button Enter/Space behavior. `selected` maps to `aria-current="page"`; `pressed` maps to `aria-pressed`. 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.
+- `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.
+- 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`; do not reduce the target to the visible icon.
 - `LoadingSpinner` is either labeled (`role="img"`) or hidden. Its rotation stops for reduced motion.
 - `StateBanner` defaults to polite `role="status"`; use `urgency="alert"` only for an attention-requiring failure.
 - `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 override `--kui-disclosure-arrow-size` without changing that ownership. Configured directions animate over the shortest path; a 180-degree closed-to-open tie uses counterclockwise rotation.
 
-## MenuActionRow
+## ListActionRow
 
-`MenuActionRow` renders a noninteractive visual root containing primary and
+`ListActionRow` renders a noninteractive visual root containing primary and
 trailing native buttons as siblings. The primary comes first in DOM and Tab
 order and alone receives `aria-current` or `aria-pressed`; the trailing button
 has its own required accessible name and disabled state. Both controls carry
@@ -46,11 +46,16 @@ The application owns persistence and collapsed/expanded policy. Keep the last ex
 `PanelHeader` is a plain `Toolbar` heading. Its leading zone holds an optional
 icon (a normal bordered `ToolbarControlGroup`) and the title as extra-large
 `ToolbarText`, and the app's trailing controls go straight into the trailing
-zone. The title carries no native heading role, so the application connects
-`titleId` and an optional `summaryId` to the owning dialog or panel through
-`aria-labelledby` and `aria-describedby` (and provides a document heading
-separately when one is required). Pass the trailing controls as a labeled
-`ToolbarControlGroup` when that group needs an accessible name.
+zone. By default the title carries no native heading role, so for a **dialog or
+panel** the application connects `titleId` and an optional `summaryId` to the
+owning host through `aria-labelledby` and `aria-describedby`. For a **page or
+view** title, pass `headingLevel` (usually `1`): the title then exposes
+`role="heading"` with a matching `aria-level`, giving the view a heading landmark
+so screen-reader heading navigation and "main heading" semantics work — the same
+role/level pair `ToolbarText` exposes when it is given `headingLevel` directly.
+Keep the levels meaningful and non-skipping within a view. Pass the trailing
+controls as a labeled `ToolbarControlGroup` when that group needs an accessible
+name.
 
 ## Tabs
 

package/docs/catalog.md

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