@kerfjs/ui 5.0.0-beta.55 → 5.0.0-beta.57

package/dist/value-table.js

@@ -1,4 +1,4 @@
-export { ValueTable, ValueTableRow } from './chunk-44IG7PFV.js';
+export { ValueTable, ValueTableRow } from './chunk-6CINWX2E.js';
 
 
 

package/dist/webawesome.d.ts

@@ -25,6 +25,9 @@ declare module 'kerfjs/jsx-runtime' {
                 placeholder?: string;
                 hint?: string;
                 disabled?: boolean;
+                size?: 'xs' | 's' | 'm' | 'l' | 'xl';
+                appearance?: 'filled' | 'outlined' | 'filled-outlined';
+                placement?: 'top' | 'bottom';
             };
             'wa-option': KerfCustomElement & {
                 value?: string;
@@ -40,7 +43,9 @@ declare module 'kerfjs/jsx-runtime' {
             'wa-comparison': KerfCustomElement;
             'wa-copy-button': KerfCustomElement;
             'wa-details': KerfCustomElement;
-            'wa-divider': KerfCustomElement;
+            'wa-divider': KerfCustomElement & {
+                orientation?: 'horizontal' | 'vertical';
+            };
             'wa-dialog': KerfCustomElement;
             'wa-drawer': KerfCustomElement;
             'wa-button': KerfCustomElement & {
@@ -51,6 +56,7 @@ declare module 'kerfjs/jsx-runtime' {
             };
             'wa-dropdown': KerfCustomElement & {
                 placement?: string;
+                size?: 'xs' | 's' | 'm' | 'l' | 'xl';
             };
             'wa-dropdown-item': KerfCustomElement;
             'wa-format-bytes': KerfCustomElement;

package/dist/wire-catalog.d.ts

@@ -28,6 +28,17 @@ interface WireCatalogOptions {
      * open overlay closes it.
      */
     collapsed?: Signal<boolean>;
+    /**
+     * The app-owned sidebar width signal for a Catalog rendered with
+     * `sidebar={{ resizable: true, size: sidebarSize.value }}`. Each committed
+     * drag or keyboard resize is written to it.
+     */
+    sidebarSize?: Signal<number>;
+    /**
+     * With `sidebarSize`, load and save the width under this storage key so the
+     * catalog remembers the user's sidebar width.
+     */
+    sidebarStorageKey?: string;
     /** The Catalog's `id`, when it is not the default `kui-catalog`. */
     id?: string;
 }
@@ -62,8 +73,10 @@ declare function wireCatalogGeometryOverlay(root: HTMLElement): () => void;
  * item selection (and the related-entry popup menu), 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.
+ * It also wires the scroll dividers below root (`wireScrollDividers`), so the
+ * catalog's panes and every example in it show their chrome dividers only
+ * while scrolled. Returns a disposer.
  */
-declare function wireCatalog(root: HTMLElement, { onSelect, onToggleSidebar, onToggleTheme, onToggleSecondary, urlParam, revealSelection, selectAction, toggleSidebarAction, toggleThemeAction, toggleSecondaryAction, collapsed, id: catalogId, }: WireCatalogOptions): () => void;
+declare function wireCatalog(root: HTMLElement, { onSelect, onToggleSidebar, onToggleTheme, onToggleSecondary, urlParam, revealSelection, selectAction, toggleSidebarAction, toggleThemeAction, toggleSecondaryAction, collapsed, sidebarSize, sidebarStorageKey, id: catalogId, }: WireCatalogOptions): () => void;
 
 export { type CatalogRevealOptions, type WireCatalogOptions, revealCatalogEntry, wireCatalog, wireCatalogGeometryOverlay };

package/dist/wire-catalog.js

@@ -1,4 +1,5 @@
 import { wireWorkbench } from './chunk-KH6VUGHU.js';
+import { wireScrollDividers } from './chunk-JCV4GXWB.js';
 
 
 
@@ -233,6 +234,8 @@ function wireCatalog(root, {
   toggleThemeAction = "catalog-toggle-theme",
   toggleSecondaryAction = "catalog-toggle-secondary",
   collapsed,
+  sidebarSize,
+  sidebarStorageKey,
   id: catalogId = "kui-catalog"
 }) {
   let cancelReveal;
@@ -257,6 +260,7 @@ function wireCatalog(root, {
     }
   };
   const disposers = [
+    wireScrollDividers(root),
     // Sidebar items AND the footer's related-entry popup-menu items both carry
     // `data-action={selectAction}` + `data-item-id`, so one delegated click covers both.
     delegate(
@@ -299,11 +303,17 @@ function wireCatalog(root, {
       )
     );
   }
-  if (collapsed)
+  if (collapsed || sidebarSize)
     disposers.push(
       wireWorkbench(root, {
         id: catalogId,
-        panels: { leftRail: { collapsed } }
+        panels: {
+          leftRail: {
+            collapsed,
+            size: sidebarSize,
+            storageKey: sidebarStorageKey
+          }
+        }
       })
     );
   return () => {

package/dist/wire-catalog.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/wire-catalog.ts"],"names":[],"mappings":"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","file":"wire-catalog.js","sourcesContent":["import { delegate, type Signal } from 'kerfjs';\n\nimport { wireWorkbench } from './wire-workbench.js';\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  /**\n   * Reveal the chosen sidebar row after selection. `true` uses desktop-safe\n   * defaults; pass options to customize scroll alignment or the media guard.\n   */\n  revealSelection?: boolean | CatalogRevealOptions;\n  selectAction?: string;\n  toggleSidebarAction?: string;\n  toggleThemeAction?: string;\n  toggleSecondaryAction?: string;\n  /**\n   * The sidebar's app-owned collapsed flag. With it, the catalog's Workbench\n   * sidebar is wired like any Workbench rail: it becomes a transient overlay\n   * on a small screen (collapsed as the breakpoint applies, closed on Escape\n   * or a press outside, focus handed back), and choosing an entry from the\n   * open overlay closes it.\n   */\n  collapsed?: Signal<boolean>;\n  /** The Catalog's `id`, when it is not the default `kui-catalog`. */\n  id?: string;\n}\n\nexport interface CatalogRevealOptions {\n  /** Scroll alignment within the sidebar. Default `'nearest'`. */\n  block?: ScrollLogicalPosition;\n  /** Cross-axis alignment. Default `'nearest'`. */\n  inline?: ScrollLogicalPosition;\n  /** Scroll behavior. Default `'auto'`. */\n  behavior?: ScrollBehavior;\n  /**\n   * Only reveal when this media query matches. Defaults to the Catalog's\n   * desktop layout; pass `false` to reveal at every viewport size.\n   */\n  media?: string | false;\n}\n\n// The Workbench keeps the sidebar inline above its `narrow` breakpoint (704px).\nconst catalogDesktopMedia = '(min-width: 44.01rem)';\n\n/**\n * Reveal one Catalog sidebar entry after the controlled render settles without\n * moving focus. Returns a cancellation function for rapid selection changes.\n */\nexport function revealCatalogEntry(\n  root: HTMLElement,\n  id: string,\n  {\n    block = 'nearest',\n    inline = 'nearest',\n    behavior = 'auto',\n    media = catalogDesktopMedia,\n  }: CatalogRevealOptions = {},\n): () => void {\n  const view = root.ownerDocument.defaultView;\n  if (!view || (media && !view.matchMedia(media).matches)) return () => {};\n  const frame = view.requestAnimationFrame(() => {\n    for (const item of root.querySelectorAll<HTMLElement>('[data-item-id]')) {\n      if (item.dataset.itemId !== id) continue;\n      item.scrollIntoView({ block, inline, behavior });\n      break;\n    }\n  });\n  return () => view.cancelAnimationFrame(frame);\n}\n\nfunction pixels(value: string): number {\n  const number = Number.parseFloat(value);\n  if (!Number.isFinite(number)) return 0;\n  return value.trim().endsWith('rem') ? number * 16 : number;\n}\n\nfunction isTransparent(color: string): boolean {\n  const normalized = color.replace(/\\s+/g, '');\n  return (\n    normalized === 'transparent' || /(?:,|\\/)0(?:\\.0+)?\\)$/.test(normalized)\n  );\n}\n\nfunction geometrySpecimens(canvas: HTMLElement): Element[] {\n  const result: Element[] = [];\n  for (const example of canvas.querySelectorAll<HTMLElement>(\n    '[data-catalog-example]',\n  )) {\n    if (example.closest('[data-catalog-geometry-overlay-skip]')) continue;\n    for (const child of example.children) {\n      if (\n        child.matches('[data-catalog-geometry-overlay]') ||\n        child.matches('[data-catalog-example-label]') ||\n        child.matches('[data-catalog-example-note]')\n      )\n        continue;\n      result.push(child);\n    }\n  }\n  for (const element of canvas.querySelectorAll<HTMLElement>(\n    '[data-component]',\n  )) {\n    if (\n      element.closest('[data-catalog-geometry-overlay]') ||\n      element.closest('[data-catalog-geometry-overlay-skip]') ||\n      element.closest('.kui-catalog-example')\n    )\n      continue;\n    const parent =\n      element.parentElement?.closest<HTMLElement>('[data-component]');\n    if (parent && canvas.contains(parent)) continue;\n    result.push(element);\n  }\n  return result;\n}\n\nfunction geometryBox(\n  document: Document,\n  className: string,\n  left: number,\n  top: number,\n  width: number,\n  height: number,\n): HTMLElement {\n  const element = document.createElement('div');\n  element.className = className;\n  element.style.transform = `translate(${left}px, ${top}px)`;\n  element.style.width = `${Math.max(0, width)}px`;\n  element.style.height = `${Math.max(0, height)}px`;\n  return element;\n}\n\nfunction effectiveBorderWidth(width: string, style: string): number {\n  return style === 'none' || style === 'hidden' ? 0 : pixels(width);\n}\n\n/**\n * Keep a Catalog's opt-in geometry overlay synchronized with its preview.\n * Specimens receive computed border highlights (or a dashed bound when they\n * have no border and are transparent), while positive computed margins use\n * devtools-style orange bands. CSS/stylesheet-only changes are observed too.\n * Returns a disposer.\n */\nexport function wireCatalogGeometryOverlay(root: HTMLElement): () => void {\n  const catalog = root.matches('[data-component=\"catalog\"]')\n    ? root\n    : root.querySelector<HTMLElement>('[data-component=\"catalog\"]');\n  const canvas = catalog?.querySelector<HTMLElement>('.kui-catalog__canvas');\n  const layer = catalog?.querySelector<HTMLElement>(\n    '[data-catalog-geometry-overlay]',\n  );\n  const view = root.ownerDocument.defaultView;\n  if (!catalog || !canvas || !layer || !view) return () => {};\n\n  let frame = 0;\n  const render = (): void => {\n    frame = 0;\n    layer.replaceChildren();\n    if (catalog.dataset.geometryOverlay !== 'true') {\n      syncObservedSpecimens([]);\n      return;\n    }\n    const base = canvas.getBoundingClientRect();\n    const specimens = geometrySpecimens(canvas);\n    syncObservedSpecimens(specimens);\n    for (const [specimenIndex, element] of specimens.entries()) {\n      const rect = element.getBoundingClientRect();\n      const style = view.getComputedStyle(element);\n      const align = pixels(\n        style.getPropertyValue('--kui-catalog-example-align'),\n      );\n      const top = pixels(style.marginTop);\n      const right = Math.max(\n        0,\n        pixels(style.marginRight) - (style.direction === 'rtl' ? align : 0),\n      );\n      const bottom = pixels(style.marginBottom);\n      const left = Math.max(\n        0,\n        pixels(style.marginLeft) - (style.direction === 'rtl' ? 0 : align),\n      );\n      const x = rect.left - base.left + canvas.scrollLeft;\n      const y = rect.top - base.top + canvas.scrollTop;\n      const borderWidths = [\n        effectiveBorderWidth(style.borderTopWidth, style.borderTopStyle),\n        effectiveBorderWidth(style.borderRightWidth, style.borderRightStyle),\n        effectiveBorderWidth(style.borderBottomWidth, style.borderBottomStyle),\n        effectiveBorderWidth(style.borderLeftWidth, style.borderLeftStyle),\n      ];\n      if (borderWidths.some((width) => width > 0)) {\n        const border = geometryBox(\n          root.ownerDocument,\n          'kui-catalog__geometry-border',\n          x,\n          y,\n          rect.width,\n          rect.height,\n        );\n        border.dataset.catalogGeometrySpecimen = String(specimenIndex);\n        border.style.borderTopWidth = `${borderWidths[0]}px`;\n        border.style.borderRightWidth = `${borderWidths[1]}px`;\n        border.style.borderBottomWidth = `${borderWidths[2]}px`;\n        border.style.borderLeftWidth = `${borderWidths[3]}px`;\n        border.style.borderRadius = style.borderRadius;\n        layer.append(border);\n      } else if (isTransparent(style.backgroundColor)) {\n        const bound = geometryBox(\n          root.ownerDocument,\n          'kui-catalog__geometry-bound',\n          x,\n          y,\n          rect.width,\n          rect.height,\n        );\n        bound.dataset.catalogGeometrySpecimen = String(specimenIndex);\n        layer.append(bound);\n      }\n      const margins: Array<\n        readonly [string, number, number, number, number, number]\n      > = [\n        ['top', top, x - left, y - top, rect.width + left + right, top],\n        [\n          'bottom',\n          bottom,\n          x - left,\n          y + rect.height,\n          rect.width + left + right,\n          bottom,\n        ],\n        ['left', left, x - left, y, left, rect.height],\n        ['right', right, x + rect.width, y, right, rect.height],\n      ];\n      for (const [side, size, marginX, marginY, width, height] of margins) {\n        if (size <= 0) continue;\n        const margin = geometryBox(\n          root.ownerDocument,\n          'kui-catalog__geometry-margin',\n          marginX,\n          marginY,\n          width,\n          height,\n        );\n        margin.dataset.catalogGeometrySpecimen = String(specimenIndex);\n        margin.dataset.catalogGeometrySide = side;\n        layer.append(margin);\n      }\n    }\n  };\n  const schedule = (): void => {\n    if (!frame) frame = view.requestAnimationFrame(render);\n  };\n  const resizeObserver = new view.ResizeObserver(schedule);\n  resizeObserver.observe(canvas);\n  const observedSpecimens = new Set<Element>();\n  const syncObservedSpecimens = (specimens: Element[]): void => {\n    const next = new Set(specimens);\n    for (const specimen of observedSpecimens) {\n      if (next.has(specimen)) continue;\n      resizeObserver.unobserve(specimen);\n      observedSpecimens.delete(specimen);\n    }\n    for (const specimen of next) {\n      if (observedSpecimens.has(specimen)) continue;\n      resizeObserver.observe(specimen);\n      observedSpecimens.add(specimen);\n    }\n  };\n  const mutationObserver = new view.MutationObserver((records) => {\n    if (\n      records.some(\n        ({ target }) => target !== layer && !layer.contains(target as Node),\n      )\n    )\n      schedule();\n  });\n  mutationObserver.observe(catalog, {\n    attributes: true,\n    childList: true,\n    subtree: true,\n  });\n  mutationObserver.observe(root.ownerDocument.documentElement, {\n    attributes: true,\n  });\n  const documentHead = root.ownerDocument.head;\n  if (documentHead)\n    mutationObserver.observe(documentHead, {\n      attributes: true,\n      characterData: true,\n      childList: true,\n      subtree: true,\n    });\n  const stylesheetLoaded = (): void => schedule();\n  documentHead?.addEventListener('load', stylesheetLoaded, true);\n  view.addEventListener('resize', schedule);\n  render();\n  return () => {\n    if (frame) view.cancelAnimationFrame(frame);\n    resizeObserver.disconnect();\n    mutationObserver.disconnect();\n    documentHead?.removeEventListener('load', stylesheetLoaded, true);\n    view.removeEventListener('resize', schedule);\n    layer.replaceChildren();\n  };\n}\n\n/**\n * Wire a {@link Catalog}'s interactions with one delegated listener set: sidebar\n * item selection (and the related-entry popup menu), 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    revealSelection,\n    selectAction = 'catalog-select',\n    toggleSidebarAction = 'catalog-toggle-sidebar',\n    toggleThemeAction = 'catalog-toggle-theme',\n    toggleSecondaryAction = 'catalog-toggle-secondary',\n    collapsed,\n    id: catalogId = 'kui-catalog',\n  }: WireCatalogOptions,\n): () => void {\n  let cancelReveal: (() => void) | undefined;\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    // An open overlay sidebar gives way to the entry just chosen from it.\n    const rail = root.ownerDocument.getElementById(`${catalogId}-left-rail`);\n    if (\n      collapsed &&\n      !collapsed.peek() &&\n      rail &&\n      root.ownerDocument.defaultView?.getComputedStyle(rail).position ===\n        'absolute'\n    )\n      collapsed.value = true;\n    if (revealSelection) {\n      cancelReveal?.();\n      cancelReveal = revealCatalogEntry(\n        root,\n        id,\n        revealSelection === true ? undefined : revealSelection,\n      );\n    }\n  };\n\n  const disposers: Array<() => void> = [\n    // Sidebar items AND the footer's related-entry popup-menu items both carry\n    // `data-action={selectAction}` + `data-item-id`, so one delegated click covers both.\n    delegate(\n      root,\n      'click',\n      `[data-action=\"${selectAction}\"]`,\n      (_event, element) => {\n        const id = (element as HTMLElement).dataset.itemId;\n        if (id) select(id);\n      },\n    ),\n  ];\n  if (onToggleSidebar) {\n    disposers.push(\n      delegate(root, 'click', `[data-action=\"${toggleSidebarAction}\"]`, () =>\n        onToggleSidebar(),\n      ),\n    );\n  }\n  if (onToggleTheme) {\n    disposers.push(\n      delegate(root, 'click', `[data-action=\"${toggleThemeAction}\"]`, () =>\n        onToggleTheme(),\n      ),\n    );\n  }\n  if (onToggleSecondary) {\n    disposers.push(\n      delegate(root, 'click', `[data-action=\"${toggleSecondaryAction}\"]`, () =>\n        onToggleSecondary(),\n      ),\n    );\n  }\n  if (collapsed)\n    disposers.push(\n      wireWorkbench(root, {\n        id: catalogId,\n        panels: { leftRail: { collapsed } },\n      }),\n    );\n  return () => {\n    cancelReveal?.();\n    for (const dispose of disposers.splice(0)) dispose();\n  };\n}\n"]}
+{"version":3,"sources":["../src/wire-catalog.ts"],"names":[],"mappings":";;;;;;;AA+DA,IAAM,mBAAA,GAAsB,uBAAA;AAMrB,SAAS,kBAAA,CACd,MACA,EAAA,EACA;AAAA,EACE,KAAA,GAAQ,SAAA;AAAA,EACR,MAAA,GAAS,SAAA;AAAA,EACT,QAAA,GAAW,MAAA;AAAA,EACX,KAAA,GAAQ;AACV,CAAA,GAA0B,EAAC,EACf;AACZ,EAAA,MAAM,IAAA,GAAO,KAAK,aAAA,CAAc,WAAA;AAChC,EAAA,IAAI,CAAC,IAAA,IAAS,KAAA,IAAS,CAAC,IAAA,CAAK,WAAW,KAAK,CAAA,CAAE,OAAA,EAAU,OAAO,MAAM;AAAA,EAAC,CAAA;AACvE,EAAA,MAAM,KAAA,GAAQ,IAAA,CAAK,qBAAA,CAAsB,MAAM;AAC7C,IAAA,KAAA,MAAW,IAAA,IAAQ,IAAA,CAAK,gBAAA,CAA8B,gBAAgB,CAAA,EAAG;AACvE,MAAA,IAAI,IAAA,CAAK,OAAA,CAAQ,MAAA,KAAW,EAAA,EAAI;AAChC,MAAA,IAAA,CAAK,cAAA,CAAe,EAAE,KAAA,EAAO,MAAA,EAAQ,UAAU,CAAA;AAC/C,MAAA;AAAA,IACF;AAAA,EACF,CAAC,CAAA;AACD,EAAA,OAAO,MAAM,IAAA,CAAK,oBAAA,CAAqB,KAAK,CAAA;AAC9C;AAEA,SAAS,OAAO,KAAA,EAAuB;AACrC,EAAA,MAAM,MAAA,GAAS,MAAA,CAAO,UAAA,CAAW,KAAK,CAAA;AACtC,EAAA,IAAI,CAAC,MAAA,CAAO,QAAA,CAAS,MAAM,GAAG,OAAO,CAAA;AACrC,EAAA,OAAO,MAAM,IAAA,EAAK,CAAE,SAAS,KAAK,CAAA,GAAI,SAAS,EAAA,GAAK,MAAA;AACtD;AAEA,SAAS,cAAc,KAAA,EAAwB;AAC7C,EAAA,MAAM,UAAA,GAAa,KAAA,CAAM,OAAA,CAAQ,MAAA,EAAQ,EAAE,CAAA;AAC3C,EAAA,OACE,UAAA,KAAe,aAAA,IAAiB,uBAAA,CAAwB,IAAA,CAAK,UAAU,CAAA;AAE3E;AAEA,SAAS,kBAAkB,MAAA,EAAgC;AACzD,EAAA,MAAM,SAAoB,EAAC;AAC3B,EAAA,KAAA,MAAW,WAAW,MAAA,CAAO,gBAAA;AAAA,IAC3B;AAAA,GACF,EAAG;AACD,IAAA,IAAI,OAAA,CAAQ,OAAA,CAAQ,sCAAsC,CAAA,EAAG;AAC7D,IAAA,KAAA,MAAW,KAAA,IAAS,QAAQ,QAAA,EAAU;AACpC,MAAA,IACE,KAAA,CAAM,OAAA,CAAQ,iCAAiC,CAAA,IAC/C,KAAA,CAAM,QAAQ,8BAA8B,CAAA,IAC5C,KAAA,CAAM,OAAA,CAAQ,6BAA6B,CAAA;AAE3C,QAAA;AACF,MAAA,MAAA,CAAO,KAAK,KAAK,CAAA;AAAA,IACnB;AAAA,EACF;AACA,EAAA,KAAA,MAAW,WAAW,MAAA,CAAO,gBAAA;AAAA,IAC3B;AAAA,GACF,EAAG;AACD,IAAA,IACE,OAAA,CAAQ,OAAA,CAAQ,iCAAiC,CAAA,IACjD,OAAA,CAAQ,QAAQ,sCAAsC,CAAA,IACtD,OAAA,CAAQ,OAAA,CAAQ,sBAAsB,CAAA;AAEtC,MAAA;AACF,IAAA,MAAM,MAAA,GACJ,OAAA,CAAQ,aAAA,EAAe,OAAA,CAAqB,kBAAkB,CAAA;AAChE,IAAA,IAAI,MAAA,IAAU,MAAA,CAAO,QAAA,CAAS,MAAM,CAAA,EAAG;AACvC,IAAA,MAAA,CAAO,KAAK,OAAO,CAAA;AAAA,EACrB;AACA,EAAA,OAAO,MAAA;AACT;AAEA,SAAS,YACP,QAAA,EACA,SAAA,EACA,IAAA,EACA,GAAA,EACA,OACA,MAAA,EACa;AACb,EAAA,MAAM,OAAA,GAAU,QAAA,CAAS,aAAA,CAAc,KAAK,CAAA;AAC5C,EAAA,OAAA,CAAQ,SAAA,GAAY,SAAA;AACpB,EAAA,OAAA,CAAQ,KAAA,CAAM,SAAA,GAAY,CAAA,UAAA,EAAa,IAAI,OAAO,GAAG,CAAA,GAAA,CAAA;AACrD,EAAA,OAAA,CAAQ,MAAM,KAAA,GAAQ,CAAA,EAAG,KAAK,GAAA,CAAI,CAAA,EAAG,KAAK,CAAC,CAAA,EAAA,CAAA;AAC3C,EAAA,OAAA,CAAQ,MAAM,MAAA,GAAS,CAAA,EAAG,KAAK,GAAA,CAAI,CAAA,EAAG,MAAM,CAAC,CAAA,EAAA,CAAA;AAC7C,EAAA,OAAO,OAAA;AACT;AAEA,SAAS,oBAAA,CAAqB,OAAe,KAAA,EAAuB;AAClE,EAAA,OAAO,UAAU,MAAA,IAAU,KAAA,KAAU,QAAA,GAAW,CAAA,GAAI,OAAO,KAAK,CAAA;AAClE;AASO,SAAS,2BAA2B,IAAA,EAA+B;AACxE,EAAA,MAAM,OAAA,GAAU,KAAK,OAAA,CAAQ,4BAA4B,IACrD,IAAA,GACA,IAAA,CAAK,cAA2B,4BAA4B,CAAA;AAChE,EAAA,MAAM,MAAA,GAAS,OAAA,EAAS,aAAA,CAA2B,sBAAsB,CAAA;AACzE,EAAA,MAAM,QAAQ,OAAA,EAAS,aAAA;AAAA,IACrB;AAAA,GACF;AACA,EAAA,MAAM,IAAA,GAAO,KAAK,aAAA,CAAc,WAAA;AAChC,EAAA,IAAI,CAAC,WAAW,CAAC,MAAA,IAAU,CAAC,KAAA,IAAS,CAAC,IAAA,EAAM,OAAO,MAAM;AAAA,EAAC,CAAA;AAE1D,EAAA,IAAI,KAAA,GAAQ,CAAA;AACZ,EAAA,MAAM,SAAS,MAAY;AACzB,IAAA,KAAA,GAAQ,CAAA;AACR,IAAA,KAAA,CAAM,eAAA,EAAgB;AACtB,IAAA,IAAI,OAAA,CAAQ,OAAA,CAAQ,eAAA,KAAoB,MAAA,EAAQ;AAC9C,MAAA,qBAAA,CAAsB,EAAE,CAAA;AACxB,MAAA;AAAA,IACF;AACA,IAAA,MAAM,IAAA,GAAO,OAAO,qBAAA,EAAsB;AAC1C,IAAA,MAAM,SAAA,GAAY,kBAAkB,MAAM,CAAA;AAC1C,IAAA,qBAAA,CAAsB,SAAS,CAAA;AAC/B,IAAA,KAAA,MAAW,CAAC,aAAA,EAAe,OAAO,CAAA,IAAK,SAAA,CAAU,SAAQ,EAAG;AAC1D,MAAA,MAAM,IAAA,GAAO,QAAQ,qBAAA,EAAsB;AAC3C,MAAA,MAAM,KAAA,GAAQ,IAAA,CAAK,gBAAA,CAAiB,OAAO,CAAA;AAC3C,MAAA,MAAM,KAAA,GAAQ,MAAA;AAAA,QACZ,KAAA,CAAM,iBAAiB,6BAA6B;AAAA,OACtD;AACA,MAAA,MAAM,GAAA,GAAM,MAAA,CAAO,KAAA,CAAM,SAAS,CAAA;AAClC,MAAA,MAAM,QAAQ,IAAA,CAAK,GAAA;AAAA,QACjB,CAAA;AAAA,QACA,OAAO,KAAA,CAAM,WAAW,KAAK,KAAA,CAAM,SAAA,KAAc,QAAQ,KAAA,GAAQ,CAAA;AAAA,OACnE;AACA,MAAA,MAAM,MAAA,GAAS,MAAA,CAAO,KAAA,CAAM,YAAY,CAAA;AACxC,MAAA,MAAM,OAAO,IAAA,CAAK,GAAA;AAAA,QAChB,CAAA;AAAA,QACA,OAAO,KAAA,CAAM,UAAU,KAAK,KAAA,CAAM,SAAA,KAAc,QAAQ,CAAA,GAAI,KAAA;AAAA,OAC9D;AACA,MAAA,MAAM,CAAA,GAAI,IAAA,CAAK,IAAA,GAAO,IAAA,CAAK,OAAO,MAAA,CAAO,UAAA;AACzC,MAAA,MAAM,CAAA,GAAI,IAAA,CAAK,GAAA,GAAM,IAAA,CAAK,MAAM,MAAA,CAAO,SAAA;AACvC,MAAA,MAAM,YAAA,GAAe;AAAA,QACnB,oBAAA,CAAqB,KAAA,CAAM,cAAA,EAAgB,KAAA,CAAM,cAAc,CAAA;AAAA,QAC/D,oBAAA,CAAqB,KAAA,CAAM,gBAAA,EAAkB,KAAA,CAAM,gBAAgB,CAAA;AAAA,QACnE,oBAAA,CAAqB,KAAA,CAAM,iBAAA,EAAmB,KAAA,CAAM,iBAAiB,CAAA;AAAA,QACrE,oBAAA,CAAqB,KAAA,CAAM,eAAA,EAAiB,KAAA,CAAM,eAAe;AAAA,OACnE;AACA,MAAA,IAAI,aAAa,IAAA,CAAK,CAAC,KAAA,KAAU,KAAA,GAAQ,CAAC,CAAA,EAAG;AAC3C,QAAA,MAAM,MAAA,GAAS,WAAA;AAAA,UACb,IAAA,CAAK,aAAA;AAAA,UACL,8BAAA;AAAA,UACA,CAAA;AAAA,UACA,CAAA;AAAA,UACA,IAAA,CAAK,KAAA;AAAA,UACL,IAAA,CAAK;AAAA,SACP;AACA,QAAA,MAAA,CAAO,OAAA,CAAQ,uBAAA,GAA0B,MAAA,CAAO,aAAa,CAAA;AAC7D,QAAA,MAAA,CAAO,KAAA,CAAM,cAAA,GAAiB,CAAA,EAAG,YAAA,CAAa,CAAC,CAAC,CAAA,EAAA,CAAA;AAChD,QAAA,MAAA,CAAO,KAAA,CAAM,gBAAA,GAAmB,CAAA,EAAG,YAAA,CAAa,CAAC,CAAC,CAAA,EAAA,CAAA;AAClD,QAAA,MAAA,CAAO,KAAA,CAAM,iBAAA,GAAoB,CAAA,EAAG,YAAA,CAAa,CAAC,CAAC,CAAA,EAAA,CAAA;AACnD,QAAA,MAAA,CAAO,KAAA,CAAM,eAAA,GAAkB,CAAA,EAAG,YAAA,CAAa,CAAC,CAAC,CAAA,EAAA,CAAA;AACjD,QAAA,MAAA,CAAO,KAAA,CAAM,eAAe,KAAA,CAAM,YAAA;AAClC,QAAA,KAAA,CAAM,OAAO,MAAM,CAAA;AAAA,MACrB,CAAA,MAAA,IAAW,aAAA,CAAc,KAAA,CAAM,eAAe,CAAA,EAAG;AAC/C,QAAA,MAAM,KAAA,GAAQ,WAAA;AAAA,UACZ,IAAA,CAAK,aAAA;AAAA,UACL,6BAAA;AAAA,UACA,CAAA;AAAA,UACA,CAAA;AAAA,UACA,IAAA,CAAK,KAAA;AAAA,UACL,IAAA,CAAK;AAAA,SACP;AACA,QAAA,KAAA,CAAM,OAAA,CAAQ,uBAAA,GAA0B,MAAA,CAAO,aAAa,CAAA;AAC5D,QAAA,KAAA,CAAM,OAAO,KAAK,CAAA;AAAA,MACpB;AACA,MAAA,MAAM,OAAA,GAEF;AAAA,QACF,CAAC,KAAA,EAAO,GAAA,EAAK,CAAA,GAAI,IAAA,EAAM,CAAA,GAAI,GAAA,EAAK,IAAA,CAAK,KAAA,GAAQ,IAAA,GAAO,KAAA,EAAO,GAAG,CAAA;AAAA,QAC9D;AAAA,UACE,QAAA;AAAA,UACA,MAAA;AAAA,UACA,CAAA,GAAI,IAAA;AAAA,UACJ,IAAI,IAAA,CAAK,MAAA;AAAA,UACT,IAAA,CAAK,QAAQ,IAAA,GAAO,KAAA;AAAA,UACpB;AAAA,SACF;AAAA,QACA,CAAC,QAAQ,IAAA,EAAM,CAAA,GAAI,MAAM,CAAA,EAAG,IAAA,EAAM,KAAK,MAAM,CAAA;AAAA,QAC7C,CAAC,SAAS,KAAA,EAAO,CAAA,GAAI,KAAK,KAAA,EAAO,CAAA,EAAG,KAAA,EAAO,IAAA,CAAK,MAAM;AAAA,OACxD;AACA,MAAA,KAAA,MAAW,CAAC,MAAM,IAAA,EAAM,OAAA,EAAS,SAAS,KAAA,EAAO,MAAM,KAAK,OAAA,EAAS;AACnE,QAAA,IAAI,QAAQ,CAAA,EAAG;AACf,QAAA,MAAM,MAAA,GAAS,WAAA;AAAA,UACb,IAAA,CAAK,aAAA;AAAA,UACL,8BAAA;AAAA,UACA,OAAA;AAAA,UACA,OAAA;AAAA,UACA,KAAA;AAAA,UACA;AAAA,SACF;AACA,QAAA,MAAA,CAAO,OAAA,CAAQ,uBAAA,GAA0B,MAAA,CAAO,aAAa,CAAA;AAC7D,QAAA,MAAA,CAAO,QAAQ,mBAAA,GAAsB,IAAA;AACrC,QAAA,KAAA,CAAM,OAAO,MAAM,CAAA;AAAA,MACrB;AAAA,IACF;AAAA,EACF,CAAA;AACA,EAAA,MAAM,WAAW,MAAY;AAC3B,IAAA,IAAI,CAAC,KAAA,EAAO,KAAA,GAAQ,IAAA,CAAK,sBAAsB,MAAM,CAAA;AAAA,EACvD,CAAA;AACA,EAAA,MAAM,cAAA,GAAiB,IAAI,IAAA,CAAK,cAAA,CAAe,QAAQ,CAAA;AACvD,EAAA,cAAA,CAAe,QAAQ,MAAM,CAAA;AAC7B,EAAA,MAAM,iBAAA,uBAAwB,GAAA,EAAa;AAC3C,EAAA,MAAM,qBAAA,GAAwB,CAAC,SAAA,KAA+B;AAC5D,IAAA,MAAM,IAAA,GAAO,IAAI,GAAA,CAAI,SAAS,CAAA;AAC9B,IAAA,KAAA,MAAW,YAAY,iBAAA,EAAmB;AACxC,MAAA,IAAI,IAAA,CAAK,GAAA,CAAI,QAAQ,CAAA,EAAG;AACxB,MAAA,cAAA,CAAe,UAAU,QAAQ,CAAA;AACjC,MAAA,iBAAA,CAAkB,OAAO,QAAQ,CAAA;AAAA,IACnC;AACA,IAAA,KAAA,MAAW,YAAY,IAAA,EAAM;AAC3B,MAAA,IAAI,iBAAA,CAAkB,GAAA,CAAI,QAAQ,CAAA,EAAG;AACrC,MAAA,cAAA,CAAe,QAAQ,QAAQ,CAAA;AAC/B,MAAA,iBAAA,CAAkB,IAAI,QAAQ,CAAA;AAAA,IAChC;AAAA,EACF,CAAA;AACA,EAAA,MAAM,gBAAA,GAAmB,IAAI,IAAA,CAAK,gBAAA,CAAiB,CAAC,OAAA,KAAY;AAC9D,IAAA,IACE,OAAA,CAAQ,IAAA;AAAA,MACN,CAAC,EAAE,MAAA,EAAO,KAAM,WAAW,KAAA,IAAS,CAAC,KAAA,CAAM,QAAA,CAAS,MAAc;AAAA,KACpE;AAEA,MAAA,QAAA,EAAS;AAAA,EACb,CAAC,CAAA;AACD,EAAA,gBAAA,CAAiB,QAAQ,OAAA,EAAS;AAAA,IAChC,UAAA,EAAY,IAAA;AAAA,IACZ,SAAA,EAAW,IAAA;AAAA,IACX,OAAA,EAAS;AAAA,GACV,CAAA;AACD,EAAA,gBAAA,CAAiB,OAAA,CAAQ,IAAA,CAAK,aAAA,CAAc,eAAA,EAAiB;AAAA,IAC3D,UAAA,EAAY;AAAA,GACb,CAAA;AACD,EAAA,MAAM,YAAA,GAAe,KAAK,aAAA,CAAc,IAAA;AACxC,EAAA,IAAI,YAAA;AACF,IAAA,gBAAA,CAAiB,QAAQ,YAAA,EAAc;AAAA,MACrC,UAAA,EAAY,IAAA;AAAA,MACZ,aAAA,EAAe,IAAA;AAAA,MACf,SAAA,EAAW,IAAA;AAAA,MACX,OAAA,EAAS;AAAA,KACV,CAAA;AACH,EAAA,MAAM,gBAAA,GAAmB,MAAY,QAAA,EAAS;AAC9C,EAAA,YAAA,EAAc,gBAAA,CAAiB,MAAA,EAAQ,gBAAA,EAAkB,IAAI,CAAA;AAC7D,EAAA,IAAA,CAAK,gBAAA,CAAiB,UAAU,QAAQ,CAAA;AACxC,EAAA,MAAA,EAAO;AACP,EAAA,OAAO,MAAM;AACX,IAAA,IAAI,KAAA,EAAO,IAAA,CAAK,oBAAA,CAAqB,KAAK,CAAA;AAC1C,IAAA,cAAA,CAAe,UAAA,EAAW;AAC1B,IAAA,gBAAA,CAAiB,UAAA,EAAW;AAC5B,IAAA,YAAA,EAAc,mBAAA,CAAoB,MAAA,EAAQ,gBAAA,EAAkB,IAAI,CAAA;AAChE,IAAA,IAAA,CAAK,mBAAA,CAAoB,UAAU,QAAQ,CAAA;AAC3C,IAAA,KAAA,CAAM,eAAA,EAAgB;AAAA,EACxB,CAAA;AACF;AAWO,SAAS,YACd,IAAA,EACA;AAAA,EACE,QAAA;AAAA,EACA,eAAA;AAAA,EACA,aAAA;AAAA,EACA,iBAAA;AAAA,EACA,QAAA;AAAA,EACA,eAAA;AAAA,EACA,YAAA,GAAe,gBAAA;AAAA,EACf,mBAAA,GAAsB,wBAAA;AAAA,EACtB,iBAAA,GAAoB,sBAAA;AAAA,EACpB,qBAAA,GAAwB,0BAAA;AAAA,EACxB,SAAA;AAAA,EACA,WAAA;AAAA,EACA,iBAAA;AAAA,EACA,IAAI,SAAA,GAAY;AAClB,CAAA,EACY;AACZ,EAAA,IAAI,YAAA;AACJ,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;AAEA,IAAA,MAAM,OAAO,IAAA,CAAK,aAAA,CAAc,cAAA,CAAe,CAAA,EAAG,SAAS,CAAA,UAAA,CAAY,CAAA;AACvE,IAAA,IACE,SAAA,IACA,CAAC,SAAA,CAAU,IAAA,EAAK,IAChB,IAAA,IACA,IAAA,CAAK,aAAA,CAAc,WAAA,EAAa,gBAAA,CAAiB,IAAI,CAAA,CAAE,QAAA,KACrD,UAAA;AAEF,MAAA,SAAA,CAAU,KAAA,GAAQ,IAAA;AACpB,IAAA,IAAI,eAAA,EAAiB;AACnB,MAAA,YAAA,IAAe;AACf,MAAA,YAAA,GAAe,kBAAA;AAAA,QACb,IAAA;AAAA,QACA,EAAA;AAAA,QACA,eAAA,KAAoB,OAAO,MAAA,GAAY;AAAA,OACzC;AAAA,IACF;AAAA,EACF,CAAA;AAEA,EAAA,MAAM,SAAA,GAA+B;AAAA,IACnC,mBAAmB,IAAI,CAAA;AAAA;AAAA;AAAA,IAGvB,QAAA;AAAA,MACE,IAAA;AAAA,MACA,OAAA;AAAA,MACA,iBAAiB,YAAY,CAAA,EAAA,CAAA;AAAA,MAC7B,CAAC,QAAQ,OAAA,KAAY;AACnB,QAAA,MAAM,EAAA,GAAM,QAAwB,OAAA,CAAQ,MAAA;AAC5C,QAAA,IAAI,EAAA,SAAW,EAAE,CAAA;AAAA,MACnB;AAAA;AACF,GACF;AACA,EAAA,IAAI,eAAA,EAAiB;AACnB,IAAA,SAAA,CAAU,IAAA;AAAA,MACR,QAAA;AAAA,QAAS,IAAA;AAAA,QAAM,OAAA;AAAA,QAAS,iBAAiB,mBAAmB,CAAA,EAAA,CAAA;AAAA,QAAM,MAChE,eAAA;AAAgB;AAClB,KACF;AAAA,EACF;AACA,EAAA,IAAI,aAAA,EAAe;AACjB,IAAA,SAAA,CAAU,IAAA;AAAA,MACR,QAAA;AAAA,QAAS,IAAA;AAAA,QAAM,OAAA;AAAA,QAAS,iBAAiB,iBAAiB,CAAA,EAAA,CAAA;AAAA,QAAM,MAC9D,aAAA;AAAc;AAChB,KACF;AAAA,EACF;AACA,EAAA,IAAI,iBAAA,EAAmB;AACrB,IAAA,SAAA,CAAU,IAAA;AAAA,MACR,QAAA;AAAA,QAAS,IAAA;AAAA,QAAM,OAAA;AAAA,QAAS,iBAAiB,qBAAqB,CAAA,EAAA,CAAA;AAAA,QAAM,MAClE,iBAAA;AAAkB;AACpB,KACF;AAAA,EACF;AACA,EAAA,IAAI,SAAA,IAAa,WAAA;AACf,IAAA,SAAA,CAAU,IAAA;AAAA,MACR,cAAc,IAAA,EAAM;AAAA,QAClB,EAAA,EAAI,SAAA;AAAA,QACJ,MAAA,EAAQ;AAAA,UACN,QAAA,EAAU;AAAA,YACR,SAAA;AAAA,YACA,IAAA,EAAM,WAAA;AAAA,YACN,UAAA,EAAY;AAAA;AACd;AACF,OACD;AAAA,KACH;AACF,EAAA,OAAO,MAAM;AACX,IAAA,YAAA,IAAe;AACf,IAAA,KAAA,MAAW,OAAA,IAAW,SAAA,CAAU,MAAA,CAAO,CAAC,GAAG,OAAA,EAAQ;AAAA,EACrD,CAAA;AACF","file":"wire-catalog.js","sourcesContent":["import { delegate, type Signal } from 'kerfjs';\n\nimport { wireScrollDividers } from './wire-scroll-dividers.js';\nimport { wireWorkbench } from './wire-workbench.js';\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  /**\n   * Reveal the chosen sidebar row after selection. `true` uses desktop-safe\n   * defaults; pass options to customize scroll alignment or the media guard.\n   */\n  revealSelection?: boolean | CatalogRevealOptions;\n  selectAction?: string;\n  toggleSidebarAction?: string;\n  toggleThemeAction?: string;\n  toggleSecondaryAction?: string;\n  /**\n   * The sidebar's app-owned collapsed flag. With it, the catalog's Workbench\n   * sidebar is wired like any Workbench rail: it becomes a transient overlay\n   * on a small screen (collapsed as the breakpoint applies, closed on Escape\n   * or a press outside, focus handed back), and choosing an entry from the\n   * open overlay closes it.\n   */\n  collapsed?: Signal<boolean>;\n  /**\n   * The app-owned sidebar width signal for a Catalog rendered with\n   * `sidebar={{ resizable: true, size: sidebarSize.value }}`. Each committed\n   * drag or keyboard resize is written to it.\n   */\n  sidebarSize?: Signal<number>;\n  /**\n   * With `sidebarSize`, load and save the width under this storage key so the\n   * catalog remembers the user's sidebar width.\n   */\n  sidebarStorageKey?: string;\n  /** The Catalog's `id`, when it is not the default `kui-catalog`. */\n  id?: string;\n}\n\nexport interface CatalogRevealOptions {\n  /** Scroll alignment within the sidebar. Default `'nearest'`. */\n  block?: ScrollLogicalPosition;\n  /** Cross-axis alignment. Default `'nearest'`. */\n  inline?: ScrollLogicalPosition;\n  /** Scroll behavior. Default `'auto'`. */\n  behavior?: ScrollBehavior;\n  /**\n   * Only reveal when this media query matches. Defaults to the Catalog's\n   * desktop layout; pass `false` to reveal at every viewport size.\n   */\n  media?: string | false;\n}\n\n// The Workbench keeps the sidebar inline above its `narrow` breakpoint (704px).\nconst catalogDesktopMedia = '(min-width: 44.01rem)';\n\n/**\n * Reveal one Catalog sidebar entry after the controlled render settles without\n * moving focus. Returns a cancellation function for rapid selection changes.\n */\nexport function revealCatalogEntry(\n  root: HTMLElement,\n  id: string,\n  {\n    block = 'nearest',\n    inline = 'nearest',\n    behavior = 'auto',\n    media = catalogDesktopMedia,\n  }: CatalogRevealOptions = {},\n): () => void {\n  const view = root.ownerDocument.defaultView;\n  if (!view || (media && !view.matchMedia(media).matches)) return () => {};\n  const frame = view.requestAnimationFrame(() => {\n    for (const item of root.querySelectorAll<HTMLElement>('[data-item-id]')) {\n      if (item.dataset.itemId !== id) continue;\n      item.scrollIntoView({ block, inline, behavior });\n      break;\n    }\n  });\n  return () => view.cancelAnimationFrame(frame);\n}\n\nfunction pixels(value: string): number {\n  const number = Number.parseFloat(value);\n  if (!Number.isFinite(number)) return 0;\n  return value.trim().endsWith('rem') ? number * 16 : number;\n}\n\nfunction isTransparent(color: string): boolean {\n  const normalized = color.replace(/\\s+/g, '');\n  return (\n    normalized === 'transparent' || /(?:,|\\/)0(?:\\.0+)?\\)$/.test(normalized)\n  );\n}\n\nfunction geometrySpecimens(canvas: HTMLElement): Element[] {\n  const result: Element[] = [];\n  for (const example of canvas.querySelectorAll<HTMLElement>(\n    '[data-catalog-example]',\n  )) {\n    if (example.closest('[data-catalog-geometry-overlay-skip]')) continue;\n    for (const child of example.children) {\n      if (\n        child.matches('[data-catalog-geometry-overlay]') ||\n        child.matches('[data-catalog-example-label]') ||\n        child.matches('[data-catalog-example-note]')\n      )\n        continue;\n      result.push(child);\n    }\n  }\n  for (const element of canvas.querySelectorAll<HTMLElement>(\n    '[data-component]',\n  )) {\n    if (\n      element.closest('[data-catalog-geometry-overlay]') ||\n      element.closest('[data-catalog-geometry-overlay-skip]') ||\n      element.closest('.kui-catalog-example')\n    )\n      continue;\n    const parent =\n      element.parentElement?.closest<HTMLElement>('[data-component]');\n    if (parent && canvas.contains(parent)) continue;\n    result.push(element);\n  }\n  return result;\n}\n\nfunction geometryBox(\n  document: Document,\n  className: string,\n  left: number,\n  top: number,\n  width: number,\n  height: number,\n): HTMLElement {\n  const element = document.createElement('div');\n  element.className = className;\n  element.style.transform = `translate(${left}px, ${top}px)`;\n  element.style.width = `${Math.max(0, width)}px`;\n  element.style.height = `${Math.max(0, height)}px`;\n  return element;\n}\n\nfunction effectiveBorderWidth(width: string, style: string): number {\n  return style === 'none' || style === 'hidden' ? 0 : pixels(width);\n}\n\n/**\n * Keep a Catalog's opt-in geometry overlay synchronized with its preview.\n * Specimens receive computed border highlights (or a dashed bound when they\n * have no border and are transparent), while positive computed margins use\n * devtools-style orange bands. CSS/stylesheet-only changes are observed too.\n * Returns a disposer.\n */\nexport function wireCatalogGeometryOverlay(root: HTMLElement): () => void {\n  const catalog = root.matches('[data-component=\"catalog\"]')\n    ? root\n    : root.querySelector<HTMLElement>('[data-component=\"catalog\"]');\n  const canvas = catalog?.querySelector<HTMLElement>('.kui-catalog__canvas');\n  const layer = catalog?.querySelector<HTMLElement>(\n    '[data-catalog-geometry-overlay]',\n  );\n  const view = root.ownerDocument.defaultView;\n  if (!catalog || !canvas || !layer || !view) return () => {};\n\n  let frame = 0;\n  const render = (): void => {\n    frame = 0;\n    layer.replaceChildren();\n    if (catalog.dataset.geometryOverlay !== 'true') {\n      syncObservedSpecimens([]);\n      return;\n    }\n    const base = canvas.getBoundingClientRect();\n    const specimens = geometrySpecimens(canvas);\n    syncObservedSpecimens(specimens);\n    for (const [specimenIndex, element] of specimens.entries()) {\n      const rect = element.getBoundingClientRect();\n      const style = view.getComputedStyle(element);\n      const align = pixels(\n        style.getPropertyValue('--kui-catalog-example-align'),\n      );\n      const top = pixels(style.marginTop);\n      const right = Math.max(\n        0,\n        pixels(style.marginRight) - (style.direction === 'rtl' ? align : 0),\n      );\n      const bottom = pixels(style.marginBottom);\n      const left = Math.max(\n        0,\n        pixels(style.marginLeft) - (style.direction === 'rtl' ? 0 : align),\n      );\n      const x = rect.left - base.left + canvas.scrollLeft;\n      const y = rect.top - base.top + canvas.scrollTop;\n      const borderWidths = [\n        effectiveBorderWidth(style.borderTopWidth, style.borderTopStyle),\n        effectiveBorderWidth(style.borderRightWidth, style.borderRightStyle),\n        effectiveBorderWidth(style.borderBottomWidth, style.borderBottomStyle),\n        effectiveBorderWidth(style.borderLeftWidth, style.borderLeftStyle),\n      ];\n      if (borderWidths.some((width) => width > 0)) {\n        const border = geometryBox(\n          root.ownerDocument,\n          'kui-catalog__geometry-border',\n          x,\n          y,\n          rect.width,\n          rect.height,\n        );\n        border.dataset.catalogGeometrySpecimen = String(specimenIndex);\n        border.style.borderTopWidth = `${borderWidths[0]}px`;\n        border.style.borderRightWidth = `${borderWidths[1]}px`;\n        border.style.borderBottomWidth = `${borderWidths[2]}px`;\n        border.style.borderLeftWidth = `${borderWidths[3]}px`;\n        border.style.borderRadius = style.borderRadius;\n        layer.append(border);\n      } else if (isTransparent(style.backgroundColor)) {\n        const bound = geometryBox(\n          root.ownerDocument,\n          'kui-catalog__geometry-bound',\n          x,\n          y,\n          rect.width,\n          rect.height,\n        );\n        bound.dataset.catalogGeometrySpecimen = String(specimenIndex);\n        layer.append(bound);\n      }\n      const margins: Array<\n        readonly [string, number, number, number, number, number]\n      > = [\n        ['top', top, x - left, y - top, rect.width + left + right, top],\n        [\n          'bottom',\n          bottom,\n          x - left,\n          y + rect.height,\n          rect.width + left + right,\n          bottom,\n        ],\n        ['left', left, x - left, y, left, rect.height],\n        ['right', right, x + rect.width, y, right, rect.height],\n      ];\n      for (const [side, size, marginX, marginY, width, height] of margins) {\n        if (size <= 0) continue;\n        const margin = geometryBox(\n          root.ownerDocument,\n          'kui-catalog__geometry-margin',\n          marginX,\n          marginY,\n          width,\n          height,\n        );\n        margin.dataset.catalogGeometrySpecimen = String(specimenIndex);\n        margin.dataset.catalogGeometrySide = side;\n        layer.append(margin);\n      }\n    }\n  };\n  const schedule = (): void => {\n    if (!frame) frame = view.requestAnimationFrame(render);\n  };\n  const resizeObserver = new view.ResizeObserver(schedule);\n  resizeObserver.observe(canvas);\n  const observedSpecimens = new Set<Element>();\n  const syncObservedSpecimens = (specimens: Element[]): void => {\n    const next = new Set(specimens);\n    for (const specimen of observedSpecimens) {\n      if (next.has(specimen)) continue;\n      resizeObserver.unobserve(specimen);\n      observedSpecimens.delete(specimen);\n    }\n    for (const specimen of next) {\n      if (observedSpecimens.has(specimen)) continue;\n      resizeObserver.observe(specimen);\n      observedSpecimens.add(specimen);\n    }\n  };\n  const mutationObserver = new view.MutationObserver((records) => {\n    if (\n      records.some(\n        ({ target }) => target !== layer && !layer.contains(target as Node),\n      )\n    )\n      schedule();\n  });\n  mutationObserver.observe(catalog, {\n    attributes: true,\n    childList: true,\n    subtree: true,\n  });\n  mutationObserver.observe(root.ownerDocument.documentElement, {\n    attributes: true,\n  });\n  const documentHead = root.ownerDocument.head;\n  if (documentHead)\n    mutationObserver.observe(documentHead, {\n      attributes: true,\n      characterData: true,\n      childList: true,\n      subtree: true,\n    });\n  const stylesheetLoaded = (): void => schedule();\n  documentHead?.addEventListener('load', stylesheetLoaded, true);\n  view.addEventListener('resize', schedule);\n  render();\n  return () => {\n    if (frame) view.cancelAnimationFrame(frame);\n    resizeObserver.disconnect();\n    mutationObserver.disconnect();\n    documentHead?.removeEventListener('load', stylesheetLoaded, true);\n    view.removeEventListener('resize', schedule);\n    layer.replaceChildren();\n  };\n}\n\n/**\n * Wire a {@link Catalog}'s interactions with one delegated listener set: sidebar\n * item selection (and the related-entry popup menu), 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 * It also wires the scroll dividers below root (`wireScrollDividers`), so the\n * catalog's panes and every example in it show their chrome dividers only\n * while scrolled. Returns a disposer.\n */\nexport function wireCatalog(\n  root: HTMLElement,\n  {\n    onSelect,\n    onToggleSidebar,\n    onToggleTheme,\n    onToggleSecondary,\n    urlParam,\n    revealSelection,\n    selectAction = 'catalog-select',\n    toggleSidebarAction = 'catalog-toggle-sidebar',\n    toggleThemeAction = 'catalog-toggle-theme',\n    toggleSecondaryAction = 'catalog-toggle-secondary',\n    collapsed,\n    sidebarSize,\n    sidebarStorageKey,\n    id: catalogId = 'kui-catalog',\n  }: WireCatalogOptions,\n): () => void {\n  let cancelReveal: (() => void) | undefined;\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    // An open overlay sidebar gives way to the entry just chosen from it.\n    const rail = root.ownerDocument.getElementById(`${catalogId}-left-rail`);\n    if (\n      collapsed &&\n      !collapsed.peek() &&\n      rail &&\n      root.ownerDocument.defaultView?.getComputedStyle(rail).position ===\n        'absolute'\n    )\n      collapsed.value = true;\n    if (revealSelection) {\n      cancelReveal?.();\n      cancelReveal = revealCatalogEntry(\n        root,\n        id,\n        revealSelection === true ? undefined : revealSelection,\n      );\n    }\n  };\n\n  const disposers: Array<() => void> = [\n    wireScrollDividers(root),\n    // Sidebar items AND the footer's related-entry popup-menu items both carry\n    // `data-action={selectAction}` + `data-item-id`, so one delegated click covers both.\n    delegate(\n      root,\n      'click',\n      `[data-action=\"${selectAction}\"]`,\n      (_event, element) => {\n        const id = (element as HTMLElement).dataset.itemId;\n        if (id) select(id);\n      },\n    ),\n  ];\n  if (onToggleSidebar) {\n    disposers.push(\n      delegate(root, 'click', `[data-action=\"${toggleSidebarAction}\"]`, () =>\n        onToggleSidebar(),\n      ),\n    );\n  }\n  if (onToggleTheme) {\n    disposers.push(\n      delegate(root, 'click', `[data-action=\"${toggleThemeAction}\"]`, () =>\n        onToggleTheme(),\n      ),\n    );\n  }\n  if (onToggleSecondary) {\n    disposers.push(\n      delegate(root, 'click', `[data-action=\"${toggleSecondaryAction}\"]`, () =>\n        onToggleSecondary(),\n      ),\n    );\n  }\n  if (collapsed || sidebarSize)\n    disposers.push(\n      wireWorkbench(root, {\n        id: catalogId,\n        panels: {\n          leftRail: {\n            collapsed,\n            size: sidebarSize,\n            storageKey: sidebarStorageKey,\n          },\n        },\n      }),\n    );\n  return () => {\n    cancelReveal?.();\n    for (const dispose of disposers.splice(0)) dispose();\n  };\n}\n"]}

package/dist/wire-scroll-dividers.d.ts

@@ -0,0 +1,69 @@
+/**
+ * An app-owned scroll arrangement outside a `Pane`: the `id` of the element
+ * that scrolls and the `id`s of the pinned chrome on each physical side of it.
+ * Each named chrome element shows its divider on the side facing the scroller
+ * while content is scrolled away beyond that side. Ids are resolved below the
+ * wired root on every refresh, so a re-render that replaces an element keeps
+ * the pairing.
+ */
+interface ScrollDividerTarget {
+    /** The `id` of the scrolling element. */
+    scroller: string;
+    /** Chrome above the scroller: shows its bottom divider once scrolled down. */
+    top?: string;
+    /**
+     * Chrome right of the scroller: shows its left divider while content is
+     * hidden beyond the scroller's right edge (never when nothing overflows).
+     */
+    right?: string;
+    /**
+     * Chrome below the scroller: shows its top divider while content is hidden
+     * beyond the scroller's bottom edge (never when nothing overflows).
+     */
+    bottom?: string;
+    /** Chrome left of the scroller: shows its right divider once scrolled right. */
+    left?: string;
+}
+interface WireScrollDividersOptions {
+    /**
+     * App-owned scroll arrangements to pair beyond the ones found by structure
+     * (every `Pane`'s header and footer around its content, every `NavStack`'s
+     * and `TabScaffold`'s chrome around its active region, and every `TabBar`
+     * strip).
+     */
+    targets?: readonly ScrollDividerTarget[];
+}
+/**
+ * Wire scroll dividers below `root`: a divider between pinned chrome and the
+ * content that scrolls beside it shows only while content is scrolled away
+ * from that edge. Near edges (top, left) hide at the scroll start; far edges
+ * (bottom, right) hide at the scroll end and whenever nothing overflows.
+ *
+ * The wiring only reports scroll state; each component draws its own divider
+ * from it. It writes `data-scroll-overflow` (the edges with hidden content, in
+ * canonical `t`/`r`/`b`/`l` order) on each scroller, and `data-scroll-divider`
+ * (the sides to draw) on each paired chrome element:
+ *
+ * - every `Pane` with a header or footer: its header shows a bottom divider and
+ *   its footer a top divider (drawn by the Pane, per its `chromeDividers`);
+ * - every `NavStack`'s top chrome and bottom toolbar around its active view,
+ *   and every `TabScaffold`'s bar under its active scene: the chrome shows a
+ *   bottom (top chrome) or top (bottom toolbar, bar) divider. The scroller is
+ *   whichever element actually scrolls there: the view or scene itself, or,
+ *   through a sole child with no chrome of its own on that edge, a `Pane`'s
+ *   content or a nested `NavStack` / `TabScaffold` region (a Pane's own header
+ *   or footer draws that boundary instead);
+ * - every `TabBar` strip: the bar draws a divider on each side of the strip
+ *   whose tabs are scrolled out of view;
+ * - each app-owned `targets` pairing: a `Toolbar` or `List` named as chrome
+ *   draws the divider on its facing side.
+ *
+ * Structure is re-read after every DOM change below root (a re-render that
+ * drops the attributes gets them back before paint), scroll is tracked with
+ * one capturing listener, and size changes of each scroller and its children
+ * with a `ResizeObserver`. Returns a disposer that removes every attribute it
+ * wrote. See `docs/23-app-layouts.md` §3.7.
+ */
+declare function wireScrollDividers(root: HTMLElement | Document, { targets }?: WireScrollDividersOptions): () => void;
+
+export { type ScrollDividerTarget, type WireScrollDividersOptions, wireScrollDividers };

package/dist/wire-scroll-dividers.js

@@ -0,0 +1,3 @@
+export { wireScrollDividers } from './chunk-JCV4GXWB.js';
+
+//# sourceMappingURL=wire-scroll-dividers.js.map

package/dist/wire-scroll-dividers.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"wire-scroll-dividers.js"}

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

@@ -1,4 +1,4 @@
-export { wireTokenSearchFields } from './chunk-BSKEH3UC.js';
+export { wireTokenSearchFields } from './chunk-NBYTIVHS.js';
 
 
 

package/dist/workbench.d.ts

@@ -1,12 +1,15 @@
 import { SafeHtml } from 'kerfjs';
+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-BFQxFITu.js';
-import { ToolbarProps } from './toolbar.js';
+import { a as PanelToolbar, b as PanelToggle } from './panel-toolbar-BN4x0rth.js';
+import { ToolbarConfig } from './toolbar.js';
+import './css-values.js';
+import './flex-alignment-4ms8ZbV8.js';
+import './sides-BPSWde0A.js';
 import './lucide-icon.js';
 import 'lucide';
-import './divider-sides-BzB6rphT.js';
-import './pane.js';
 
 /** The standard toggle a Workbench renders for a panel (see {@link PanelToggle}). */
 type WorkbenchPanelToggle = PanelToggle;
@@ -19,8 +22,13 @@ type WorkbenchPanelToggle = PanelToggle;
  * `FloatingToolbar` in the work area's bottom-end corner.
  */
 type WorkbenchPanelToolbar = PanelToolbar;
-/** The work area's top toolbar; collapsed rails add their groups to it. */
-interface WorkbenchMainToolbar {
+/**
+ * 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
+ * default: the work area's `Pane` draws one under its header chrome, wherever
+ * that chrome ends, while `main` is scrolled (`mainPane.chromeDividers`).
+ */
+interface WorkbenchMainToolbar extends ToolbarConfig {
     label: string;
     /** The work area's title, usually an extra-large `ToolbarText`. */
     title?: KerfUiContent;
@@ -29,26 +37,27 @@ interface WorkbenchMainToolbar {
     center?: KerfUiContent;
     /** Groups at the trailing edge, before a collapsed right rail's groups. */
     trailing?: KerfUiContent;
-    /** The toolbar's narrow-width policy (see `Toolbar.responsive`). */
-    responsive?: ToolbarProps['responsive'];
-    responsiveAt?: ToolbarProps['responsiveAt'];
 }
-/** The work area's bottom toolbar; a collapsed drawer adds its groups to it. */
-interface WorkbenchMainBottomToolbar {
+/**
+ * The work area's bottom toolbar; a collapsed drawer adds its groups to it.
+ * Its configuration forwards to its `Toolbar`. It draws no divider of its own
+ * by default: the work area's `Pane` draws one over its footer chrome while
+ * more of `main` lies below (`mainPane.chromeDividers`).
+ */
+interface WorkbenchMainBottomToolbar extends ToolbarConfig {
     label: string;
     leading?: KerfUiContent;
+    center?: KerfUiContent;
     trailing?: KerfUiContent;
 }
 /**
- * The work area: the app's `main` under `mainToolbar` (and above
- * `mainBottomToolbar`), with each collapsed panel's groups added to the
- * toolbar on its side. Without either toolbar, `main` renders as given.
- */
-/**
- * Whether the work area's header or footer chrome stays pinned (`fixed`) or
- * scrolls away with the content (`scroll`).
+ * Whether the work area's header or footer chrome stays pinned (`fixed`),
+ * scrolls away with the content (`scroll`), or stays pinned while the work
+ * area is tall enough and scrolls with the content when it is short (`auto`,
+ * the Pane's `chromePlacement="auto"`; it applies to the pinned header and
+ * footer together).
  */
-type WorkbenchChromePlacement = 'fixed' | 'scroll';
+type WorkbenchChromePlacement = 'fixed' | 'scroll' | 'auto';
 
 /**
  * The Workbench container breakpoint below which a panel presents as an
@@ -81,6 +90,14 @@ interface WorkbenchPanel {
     toolbar?: WorkbenchPanelToolbar;
     /** Optional bottom toolbar under a `toolbar` panel's content. */
     footer?: KerfUiContent;
+    /**
+     * Configuration for a `toolbar` panel's `Pane` (`contentElement`,
+     * `contentLabel`, `separators`, `safeAreaEdges`, `chromeDividers`) — for example
+     * `{ contentElement: 'nav', contentLabel: 'Sections' }` for a navigation
+     * rail. Omitted or `undefined` fields keep the `Pane` defaults. Ignored
+     * without a `toolbar`, where `content` renders as given.
+     */
+    pane?: PaneConfig;
     /** Whether the panel is currently collapsed (the app owns this). */
     collapsed?: boolean;
     /**
@@ -158,13 +175,34 @@ interface WorkbenchProps {
      */
     mainBottomToolbar?: WorkbenchMainBottomToolbar;
     /**
-     * Whether `mainToolbar` and `mainHeader` stay pinned (`fixed`, default) or
+     * Whether `mainToolbar` and `mainHeader` stay pinned (`fixed`, default),
      * scroll away with `main` (`scroll`) — useful where large text would leave
-     * pinned chrome little room.
+     * pinned chrome little room — or stay pinned while the work area is tall
+     * enough and scroll with `main` when it is short (`auto`).
      */
     mainHeaderPlacement?: WorkbenchChromePlacement;
     /** The same for `mainFooter` and `mainBottomToolbar` (default `fixed`). */
     mainFooterPlacement?: WorkbenchChromePlacement;
+    /**
+     * Configuration for the work area's `Pane` (`contentElement`,
+     * `contentLabel`, `separators`, `safeAreaEdges`, `chromeDividers`), which it has whenever it
+     * has a toolbar, `mainHeader`, or `mainFooter`; without that chrome, `main`
+     * renders as given and this is ignored. Omitted or `undefined` fields keep
+     * the `Pane` defaults.
+     */
+    mainPane?: PaneConfig;
+    /**
+     * Configuration for the `List` that holds `mainHeader` (`gap`, `hAlign`,
+     * `vAlign`, `dividerSides`, `textInsets`, `controlInsets`). Omitted or
+     * `undefined` fields keep the defaults (no divider: the work area's
+     * `Pane` draws the line under its header chrome).
+     */
+    mainHeaderList?: ListConfig;
+    /**
+     * The same for the `List` that holds `mainFooter` (no divider by default:
+     * the work area's `Pane` draws the line over its footer chrome).
+     */
+    mainFooterList?: ListConfig;
     leftRail?: WorkbenchPanel;
     rightRail?: WorkbenchPanel;
     bottomDrawer?: WorkbenchPanel;
@@ -201,6 +239,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, 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, 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 };

package/dist/workbench.js

@@ -1,4 +1,4 @@
-export { Workbench } from './chunk-EAX2GSS4.js';
+export { Workbench } from './chunk-G2RKFVRB.js';
 
 
 

package/docs/accessibility.md

@@ -16,7 +16,7 @@ These are normative contracts for package components and consuming applications.
 - `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.
 - `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.
+- `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.
 - `List` is layout-only and adds no `list` role. Children own their native or ARIA semantics. Give a scrollable List a bounded block size, avoid nested scroll owners, and keep focused children visible while scrolling.
 
 ## Select
@@ -30,6 +30,27 @@ adding height or spacing. This also applies to `renderSelected`: selected conten
 stays separate from the control's stable accessible name. Applications do not
 need shadow-DOM patches or extra label styling.
 
+Set `multiple` (with an array `value`) to let the person choose any number
+of choices. The popup stays open while they toggle choices with the pointer,
+Enter, or Space, and closes on an outside press, Escape, or focus leaving,
+returning focus to the combobox. The listbox is `aria-multiselectable`, each
+chosen option shows its check, and the closed control reads the chosen labels
+in choice order as one short localized list (the `placeholderText` when none
+are chosen) instead of a removable tag per choice. `change` and `input` report
+the value array; in a form, every chosen value is submitted under `name`.
+
+A toolbar filter menu (a "Filter by label" funnel) is a multiple Select with
+`selectedPresentation="icon-only"` and a fixed `triggerIcon`; the types accept
+`triggerIcon` only there, and require it there, because no single chosen
+choice has an icon to show. The trigger keeps the icon-only pill geometry
+below: the fixed icon, then, while any choice is chosen, a compact brand
+`Badge` with the count 4px after it, then the caret. The badge is hidden from
+assistive technology; instead the combobox's accessible name ends with the
+chosen labels in choice order ("Filter by label: Bug, Docs", just "Filter by
+label" when none are chosen), and its hidden value text stays empty so screen
+readers do not announce the list twice. With a visible `label` the same summary
+reads in the label, standing in for the hidden value.
+
 Use `presentation="toolbar-borderless"` inside a `ToolbarControlGroup`, with
 `size="compact"` in a compact group; set `focusRingOwner="group"` when that
 parent paints the composed focus ring. `selectedPresentation="icon-only"` hides
@@ -41,7 +62,12 @@ trigger (8px inline padding on both sides, 12px from the icon to the caret, a
 choice list. Inside a group the trigger is inset evenly on every side (2px in a
 default group, 1px in a compact one) with a concentric radius; the group grows
 to the trigger's width, so a single group is wider than it is tall and its
-focus ring follows the pill while focused and while its listbox is open.
+focus ring follows the pill while focused. While the listbox is open the
+trigger drops its ring, as a `PopupMenu` trigger does: the open popup and its
+current option show where focus is, and the ring returns when the listbox
+closes with focus still on the control. A group that owns the ring
+(`focusRing="outline"` or `"halo"`) drops it the same way while a Select
+listbox or `PopupMenu` inside the group is open.
 Beside other controls in one group, the icon-only trigger is one more segment:
 it keeps the group's gap and its siblings' block inset, height, item radius,
 and hover pill. In a group with per-control rings (`focusRing="control"`, the
@@ -81,6 +107,79 @@ repeated and out-of-order completions, cancellation, instance isolation, and
 removal. `tests/browser/select-lifecycle.spec.ts` repeats animation/resize/reopen
 sequences at wide and narrow widths in Chromium, Firefox, and WebKit.
 
+### Help tags on icon-only triggers
+
+An icon-only control has no visible title, so sighted pointer and keyboard users
+would otherwise see only its icon (and a filter's count). Following the Apple
+HIG convention for toolbar items, three kinds of icon-only control show a help
+tag: a Web Awesome `wa-tooltip` in the theme's tooltip palette, below the
+control.
+
+- an icon-only `Select` (`selectedPresentation="icon-only"`, single or
+  `multiple`);
+- an icon-only `PopupMenu` (named by `label` rather than visible `text`);
+- an icon-only `<button>` or link (`<a href>`) inside a `ToolbarControlGroup`,
+  named by a non-empty `aria-label`, with no visible text, no native `title`,
+  and no Web Awesome tooltip `for` it.
+
+Tags are on by default and take no props. One document-level installer covers
+all three kinds, and any of `@kerfjs/ui/select/register`,
+`@kerfjs/ui/popup-menu/register`, or `@kerfjs/ui/help-tags/register` installs
+it (once per document, however many are imported). An application whose
+toolbars have icon-only buttons but no registered `Select` or `PopupMenu`
+imports `@kerfjs/ui/help-tags/register`, which registers only the tooltip
+element. Pure `SafeHtml` rendering stays zero-JS: without an installer, nothing
+shows a tag.
+
+- **Text.** The tag says what the accessible name says: a filter's name and
+  chosen labels ("Filter by label: Bug, Docs", or "Filter by label" when none
+  are chosen), a single Select's name and current choice ("Rendering balance:
+  Balanced"), a menu's `label` ("Sort tickets"), or a toolbar button's
+  `aria-label` ("Pin view"). It updates with the selection.
+- **Showing.** It appears after the pointer rests on the control for 500ms, at
+  once when a neighboring tag closed moments ago (so scanning along a toolbar
+  stays quick, across buttons, Selects, and menus alike), and immediately on
+  keyboard focus (`:focus-visible`). A pointer press that focuses the control
+  and touch input never show it.
+- **Hiding.** It hides when the pointer and keyboard focus have both left the
+  control, on a press, on Escape, and whenever a popup opens. It does not come
+  back when the popup closes and focus returns to the trigger, or while the
+  pointer stays on a pressed button; it returns after the pointer moves onto
+  something else or focus leaves and comes back.
+- **Assistive technology.** The tag is `aria-hidden` and never joins the
+  control's `aria-labelledby` or `aria-describedby` (kerf anchors it directly
+  rather than through `for`), so the accessible name is unchanged and announced
+  once; the accessibility tree is identical with the tag open or closed.
+- **Isolation.** A Select's or PopupMenu's tag lives in the control's own
+  shadow root, so the morph never touches it and light-DOM `:has([open])`
+  selectors do not see it. A plain button cannot host a shadow root, so its tag
+  lives in one `aria-hidden`, `data-morph-skip` layer at the end of `<body>`
+  (fixed and zero-sized, so it never joins a grid or flex body's flow, and
+  re-attached if a body re-render drops it) and leaves that layer once hidden.
+  It copies the button's `color-scheme`, so it matches a subtree theme, and its
+  popup renders in the browser's top layer, so it shows above a modal dialog
+  that holds the button. Tags' `wa-show` / `wa-hide` lifecycle events stop at
+  the tag, so a listener on the control (or a delegated one above it) hears only
+  the popup; a document capture-phase listener still observes them. A long tag
+  wraps at the tooltip's maximum width and keeps 8px clear of the viewport
+  edge.
+
+A labeled Select, a `PopupMenu` with visible `text`, and a toolbar button with
+visible text get no tag: their visible text already names them. A button that
+carries a native `title`, or that the application has already given a
+`wa-tooltip` `for` its `id`, keeps that and gets no second tag, so nothing is
+shown twice. Zero-JS components that name an icon control with a native `title`
+(the `ListHeader` action, the `AppTab` close button, the `TokenSearchField`
+reveal and clear buttons, and `SegmentedControl` choice titles) keep the
+browser's own tooltip, which needs no script; the installer deliberately skips
+them rather than stacking a second tag on the first. Icon-only buttons outside
+a `ToolbarControlGroup` are application markup and keep whatever naming the
+application gives them.
+`tests/unit/help-tag.test.ts` walks the hover, focus, press, Escape, popup, and
+warm-window transitions for every kind; `tests/browser/select-help-tag.spec.ts`
+and `tests/browser/toolbar-help-tag.spec.ts` check the real elements in
+Chromium.
+
 ## PopupMenu
 
 `PopupMenu` renders a Web Awesome dropdown, so the menu roles, arrow-key and
@@ -88,8 +187,13 @@ typeahead navigation, Escape, and focus return to the trigger come from
 `wa-dropdown`. Kerf's part is the trigger's name. A Web Awesome button takes its
 name from its content and ignores an `aria-label` on the host, so an icon-only
 trigger requires `label`, which renders as visually hidden text inside the
-button; a trigger with visible `text` is named by that text. Group headings render as the dropdown's native menu labels, and
-dividers are presentational. A disabled item stays in the menu but cannot be
+button; a trigger with visible `text` is named by that text. An icon-only
+trigger also shows its `label` as an `aria-hidden` help tag on hover and
+keyboard focus (see [Help tags on icon-only triggers](#help-tags-on-icon-only-triggers)). Group headings
+render as the same uppercase group titles a grouped `Select` shows, and dividers
+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.
 
 ## ListActionRow
@@ -183,10 +287,15 @@ forced to a dark color scheme, but it is **not** in the top layer, so it never
 covers dialogs, popovers, or other overlays. Its children are the app's controls
 (normally `ToolbarControlGroup`s), which keep their own names, focus, and
 keyboard behavior; the application owns their actions, the toolbar's visibility,
-and — via `position` and `--kui-floating-toolbar-inset`, set on the toolbar
-or an ancestor — where it sits. Inside a `Workbench`, `CollapsiblePanel`, or
+and — via `position` and the typed `inset` prop — where it sits. Inside a `Workbench`, `CollapsiblePanel`, or
 `ResizableRegion` `restoreControl` the restore corner owns the inset, so the
-toolbar floats from that corner.
+toolbar floats from that corner. While one of those layouts has a side overlay
+open over the toolbar's region (a Workbench rail overlay, a `wireSidebar`
+compact overlay, an overlay `CollapsiblePanel` or horizontal
+`ResizableRegion`), the toolbar is hidden (`visibility: hidden`), so it is
+unfocusable and out of the accessibility tree rather than a control stranded
+behind the overlay's focus trap; it returns when the overlay closes. The
+overlay's own floating toolbars stay.
 
 ## Tabs