@kerfjs/ui 5.0.0-beta.17 → 5.0.0-beta.21

package/dist/tab-scaffold.js

@@ -1,14 +1,49 @@
 import { jsxs, jsx } from 'kerfjs/jsx-runtime';
 
 // src/tab-scaffold.tsx
-function TabScaffold({ id, label, tabs, active, className = "" }) {
-  return /* @__PURE__ */ jsxs("section", { class: `kui-tab-scaffold ${className}`.trim(), id, "data-component": "tab-scaffold", "data-tab-scaffold-id": id, children: [
-    /* @__PURE__ */ jsx("div", { class: "kui-tab-scaffold__scenes", children: tabs.map((tab) => /* @__PURE__ */ jsx("div", { class: "kui-tab-scaffold__scene", "data-tab-scaffold-scene": tab.id, "data-active": String(tab.id === active), "aria-hidden": String(tab.id !== active), children: tab.content })) }),
-    /* @__PURE__ */ jsx("nav", { class: "kui-tab-scaffold__bar", role: "tablist", "aria-label": label, children: tabs.map((tab) => /* @__PURE__ */ jsxs("button", { type: "button", class: "kui-tab-scaffold__tab", role: "tab", "data-tab-scaffold-tab": tab.id, "aria-selected": String(tab.id === active), tabindex: tab.id === active ? "0" : "-1", children: [
-      tab.icon && /* @__PURE__ */ jsx("span", { class: "kui-tab-scaffold__tab-icon", "aria-hidden": "true", children: tab.icon }),
-      /* @__PURE__ */ jsx("span", { class: "kui-tab-scaffold__tab-label", children: tab.label })
-    ] })) })
-  ] });
+function TabScaffold({
+  id,
+  label,
+  tabs,
+  active,
+  className = ""
+}) {
+  return /* @__PURE__ */ jsxs(
+    "section",
+    {
+      class: `kui-tab-scaffold ${className}`.trim(),
+      id,
+      "data-component": "tab-scaffold",
+      "data-tab-scaffold-id": id,
+      children: [
+        /* @__PURE__ */ jsx("div", { class: "kui-tab-scaffold__scenes", children: tabs.map((tab) => /* @__PURE__ */ jsx(
+          "div",
+          {
+            class: "kui-tab-scaffold__scene",
+            "data-tab-scaffold-scene": tab.id,
+            "data-active": String(tab.id === active),
+            "aria-hidden": String(tab.id !== active),
+            children: tab.content
+          }
+        )) }),
+        /* @__PURE__ */ jsx("nav", { class: "kui-tab-scaffold__bar", role: "tablist", "aria-label": label, children: tabs.map((tab) => /* @__PURE__ */ jsxs(
+          "button",
+          {
+            type: "button",
+            class: "kui-tab-scaffold__tab",
+            role: "tab",
+            "data-tab-scaffold-tab": tab.id,
+            "aria-selected": String(tab.id === active),
+            tabindex: tab.id === active ? "0" : "-1",
+            children: [
+              tab.icon && /* @__PURE__ */ jsx("span", { class: "kui-tab-scaffold__tab-icon", "aria-hidden": "true", children: tab.icon }),
+              /* @__PURE__ */ jsx("span", { class: "kui-tab-scaffold__tab-label", children: tab.label })
+            ]
+          }
+        )) })
+      ]
+    }
+  );
 }
 
 export { TabScaffold };

package/dist/tab-scaffold.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/tab-scaffold.tsx"],"names":[],"mappings":";;;AA6BO,SAAS,WAAA,CAAY,EAAE,EAAA,EAAI,KAAA,EAAO,MAAM,MAAA,EAAQ,SAAA,GAAY,IAAG,EAAqB;AACzF,EAAA,uBAAO,IAAA,CAAC,SAAA,EAAA,EAAQ,KAAA,EAAO,CAAA,iBAAA,EAAoB,SAAS,CAAA,CAAA,CAAG,IAAA,EAAK,EAAG,EAAA,EAAQ,gBAAA,EAAe,cAAA,EAAe,sBAAA,EAAsB,EAAA,EACzH,QAAA,EAAA;AAAA,oBAAA,GAAA,CAAC,KAAA,EAAA,EAAI,KAAA,EAAM,0BAAA,EACR,QAAA,EAAA,IAAA,CAAK,GAAA,CAAI,CAAC,GAAA,qBAAQ,GAAA,CAAC,KAAA,EAAA,EAAI,KAAA,EAAM,yBAAA,EAA0B,yBAAA,EAAyB,GAAA,CAAI,EAAA,EAAI,aAAA,EAAa,MAAA,CAAO,GAAA,CAAI,EAAA,KAAO,MAAM,CAAA,EAAG,aAAA,EAAa,MAAA,CAAO,GAAA,CAAI,EAAA,KAAO,MAAM,CAAA,EAAI,QAAA,EAAA,GAAA,CAAI,OAAA,EAAQ,CAAM,CAAA,EAC9L,CAAA;AAAA,oBACA,GAAA,CAAC,KAAA,EAAA,EAAI,KAAA,EAAM,uBAAA,EAAwB,MAAK,SAAA,EAAU,YAAA,EAAY,KAAA,EAC3D,QAAA,EAAA,IAAA,CAAK,IAAI,CAAC,GAAA,qBAAQ,IAAA,CAAC,QAAA,EAAA,EAAO,MAAK,QAAA,EAAS,KAAA,EAAM,uBAAA,EAAwB,IAAA,EAAK,KAAA,EAAM,uBAAA,EAAuB,GAAA,CAAI,EAAA,EAAI,iBAAe,MAAA,CAAO,GAAA,CAAI,EAAA,KAAO,MAAM,GAAG,QAAA,EAAU,GAAA,CAAI,EAAA,KAAO,MAAA,GAAS,MAAM,IAAA,EAC5L,QAAA,EAAA;AAAA,MAAA,GAAA,CAAI,IAAA,wBAAS,MAAA,EAAA,EAAK,KAAA,EAAM,8BAA6B,aAAA,EAAY,MAAA,EAAQ,cAAI,IAAA,EAAK,CAAA;AAAA,sBACnF,GAAA,CAAC,MAAA,EAAA,EAAK,KAAA,EAAM,6BAAA,EAA+B,cAAI,KAAA,EAAM;AAAA,KAAA,EACvD,CAAS,CAAA,EACX;AAAA,GAAA,EACF,CAAA;AACF","file":"tab-scaffold.js","sourcesContent":["import type { SafeHtml } from 'kerfjs';\n\nexport interface TabScaffoldTab {\n  id: string;\n  label: string;\n  /** Decorative icon shown above the label in the bottom bar. */\n  icon?: SafeHtml;\n  /** The tab's content — typically a `NavStack` so each tab keeps its own stack. */\n  content: SafeHtml;\n}\n\nexport interface TabScaffoldProps {\n  id: string;\n  /** Accessible name for the tab bar. */\n  label: string;\n  tabs: TabScaffoldTab[];\n  /** The controlled active tab id (the app owns selection). */\n  active: string;\n  className?: string;\n}\n\n/**\n * A mobile-first, iOS-like bottom tab scaffold: a bottom tab bar that switches\n * between major sections, each tab keeping its own content (usually a `NavStack`)\n * mounted so its stack and scroll survive a switch. Controlled — the app owns\n * `active`; wire selection with `@kerfjs/ui/wire-tab-scaffold`'s `wireTabScaffold`.\n * On larger classes, promote the tabs to a `Workbench` rail or sidebar instead of\n * a bottom bar. See `docs/23-app-layouts.md` §3.4.\n */\nexport function TabScaffold({ id, label, tabs, active, className = '' }: TabScaffoldProps) {\n  return <section class={`kui-tab-scaffold ${className}`.trim()} id={id} data-component=\"tab-scaffold\" data-tab-scaffold-id={id}>\n    <div class=\"kui-tab-scaffold__scenes\">\n      {tabs.map((tab) => <div class=\"kui-tab-scaffold__scene\" data-tab-scaffold-scene={tab.id} data-active={String(tab.id === active)} aria-hidden={String(tab.id !== active)}>{tab.content}</div>)}\n    </div>\n    <nav class=\"kui-tab-scaffold__bar\" role=\"tablist\" aria-label={label}>\n      {tabs.map((tab) => <button type=\"button\" class=\"kui-tab-scaffold__tab\" role=\"tab\" data-tab-scaffold-tab={tab.id} aria-selected={String(tab.id === active)} tabindex={tab.id === active ? '0' : '-1'}>\n        {tab.icon && <span class=\"kui-tab-scaffold__tab-icon\" aria-hidden=\"true\">{tab.icon}</span>}\n        <span class=\"kui-tab-scaffold__tab-label\">{tab.label}</span>\n      </button>)}\n    </nav>\n  </section>;\n}\n"]}
+{"version":3,"sources":["../src/tab-scaffold.tsx"],"names":[],"mappings":";;;AA6BO,SAAS,WAAA,CAA+B;AAAA,EAC7C,EAAA;AAAA,EACA,KAAA;AAAA,EACA,IAAA;AAAA,EACA,MAAA;AAAA,EACA,SAAA,GAAY;AACd,CAAA,EAAyB;AACvB,EAAA,uBACE,IAAA;AAAA,IAAC,SAAA;AAAA,IAAA;AAAA,MACC,KAAA,EAAO,CAAA,iBAAA,EAAoB,SAAS,CAAA,CAAA,CAAG,IAAA,EAAK;AAAA,MAC5C,EAAA;AAAA,MACA,gBAAA,EAAe,cAAA;AAAA,MACf,sBAAA,EAAsB,EAAA;AAAA,MAEtB,QAAA,EAAA;AAAA,wBAAA,GAAA,CAAC,SAAI,KAAA,EAAM,0BAAA,EACR,QAAA,EAAA,IAAA,CAAK,GAAA,CAAI,CAAC,GAAA,qBACT,GAAA;AAAA,UAAC,KAAA;AAAA,UAAA;AAAA,YACC,KAAA,EAAM,yBAAA;AAAA,YACN,2BAAyB,GAAA,CAAI,EAAA;AAAA,YAC7B,aAAA,EAAa,MAAA,CAAO,GAAA,CAAI,EAAA,KAAO,MAAM,CAAA;AAAA,YACrC,aAAA,EAAa,MAAA,CAAO,GAAA,CAAI,EAAA,KAAO,MAAM,CAAA;AAAA,YAEpC,QAAA,EAAA,GAAA,CAAI;AAAA;AAAA,SAER,CAAA,EACH,CAAA;AAAA,wBACA,GAAA,CAAC,KAAA,EAAA,EAAI,KAAA,EAAM,uBAAA,EAAwB,IAAA,EAAK,SAAA,EAAU,YAAA,EAAY,KAAA,EAC3D,QAAA,EAAA,IAAA,CAAK,GAAA,CAAI,CAAC,GAAA,qBACT,IAAA;AAAA,UAAC,QAAA;AAAA,UAAA;AAAA,YACC,IAAA,EAAK,QAAA;AAAA,YACL,KAAA,EAAM,uBAAA;AAAA,YACN,IAAA,EAAK,KAAA;AAAA,YACL,yBAAuB,GAAA,CAAI,EAAA;AAAA,YAC3B,eAAA,EAAe,MAAA,CAAO,GAAA,CAAI,EAAA,KAAO,MAAM,CAAA;AAAA,YACvC,QAAA,EAAU,GAAA,CAAI,EAAA,KAAO,MAAA,GAAS,GAAA,GAAM,IAAA;AAAA,YAEnC,QAAA,EAAA;AAAA,cAAA,GAAA,CAAI,IAAA,wBACF,MAAA,EAAA,EAAK,KAAA,EAAM,8BAA6B,aAAA,EAAY,MAAA,EAClD,cAAI,IAAA,EACP,CAAA;AAAA,8BAEF,GAAA,CAAC,MAAA,EAAA,EAAK,KAAA,EAAM,6BAAA,EAA+B,cAAI,KAAA,EAAM;AAAA;AAAA;AAAA,SAExD,CAAA,EACH;AAAA;AAAA;AAAA,GACF;AAEJ","file":"tab-scaffold.js","sourcesContent":["import type { SafeHtml } from 'kerfjs';\n\nexport interface TabScaffoldTab<Id extends string = string> {\n  id: Id;\n  label: string;\n  /** Decorative icon shown above the label in the bottom bar. */\n  icon?: SafeHtml;\n  /** The tab's content — typically a `NavStack` so each tab keeps its own stack. */\n  content: SafeHtml;\n}\n\nexport interface TabScaffoldProps<Id extends string = string> {\n  id: string;\n  /** Accessible name for the tab bar. */\n  label: string;\n  tabs: readonly TabScaffoldTab<Id>[];\n  /** The controlled active tab id (the app owns selection). */\n  active: NoInfer<Id>;\n  className?: string;\n}\n\n/**\n * A mobile-first, iOS-like bottom tab scaffold: a bottom tab bar that switches\n * between major sections, each tab keeping its own content (usually a `NavStack`)\n * mounted so its stack and scroll survive a switch. Controlled — the app owns\n * `active`; wire selection with `@kerfjs/ui/wire-tab-scaffold`'s `wireTabScaffold`.\n * On larger classes, promote the tabs to a `Workbench` rail or sidebar instead of\n * a bottom bar. See `docs/23-app-layouts.md` §3.4.\n */\nexport function TabScaffold<Id extends string>({\n  id,\n  label,\n  tabs,\n  active,\n  className = '',\n}: TabScaffoldProps<Id>) {\n  return (\n    <section\n      class={`kui-tab-scaffold ${className}`.trim()}\n      id={id}\n      data-component=\"tab-scaffold\"\n      data-tab-scaffold-id={id}\n    >\n      <div class=\"kui-tab-scaffold__scenes\">\n        {tabs.map((tab) => (\n          <div\n            class=\"kui-tab-scaffold__scene\"\n            data-tab-scaffold-scene={tab.id}\n            data-active={String(tab.id === active)}\n            aria-hidden={String(tab.id !== active)}\n          >\n            {tab.content}\n          </div>\n        ))}\n      </div>\n      <nav class=\"kui-tab-scaffold__bar\" role=\"tablist\" aria-label={label}>\n        {tabs.map((tab) => (\n          <button\n            type=\"button\"\n            class=\"kui-tab-scaffold__tab\"\n            role=\"tab\"\n            data-tab-scaffold-tab={tab.id}\n            aria-selected={String(tab.id === active)}\n            tabindex={tab.id === active ? '0' : '-1'}\n          >\n            {tab.icon && (\n              <span class=\"kui-tab-scaffold__tab-icon\" aria-hidden=\"true\">\n                {tab.icon}\n              </span>\n            )}\n            <span class=\"kui-tab-scaffold__tab-label\">{tab.label}</span>\n          </button>\n        ))}\n      </nav>\n    </section>\n  );\n}\n"]}

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

@@ -6,7 +6,15 @@ interface TokenSearchToken {
     offset?: number;
     accessibleLabel?: string;
 }
-interface TokenSearchFieldProps {
+type TokenSearchEditorAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
+    'data-component'?: never;
+    'data-key'?: never;
+    'data-morph-skip'?: never;
+    'data-token-search-editor'?: never;
+    'data-token-count'?: never;
+    'data-placeholder'?: never;
+}>;
+interface TokenSearchFieldBaseProps {
     id: string;
     label: string;
     query?: string;
@@ -15,12 +23,6 @@ interface TokenSearchFieldProps {
     tokenPlaceholder?: string;
     disabled?: boolean;
     autofocus?: boolean;
-    /** Allow an empty field to render as one iconic action. */
-    collapsible?: boolean;
-    /** Keep an empty collapsible field open while the application owns focus. */
-    expanded?: boolean;
-    expandAction?: string;
-    expandLabel?: string;
     leading?: SafeHtml;
     trailing?: SafeHtml;
     editAction?: string;
@@ -28,8 +30,22 @@ interface TokenSearchFieldProps {
     clearAction?: string;
     clearLabel?: string;
     className?: string;
-    editorAttributes?: Readonly<Record<`data-${string}`, string>>;
+    editorAttributes?: TokenSearchEditorAttributes;
 }
+type TokenSearchCollapsibleProps = {
+    /** Allow an empty field to render as one iconic action. */
+    collapsible: true;
+    /** Keep an empty collapsible field open while the application owns focus. */
+    expanded?: boolean;
+    expandAction?: string;
+    expandLabel?: string;
+} | {
+    collapsible?: false;
+    expanded?: never;
+    expandAction?: never;
+    expandLabel?: never;
+};
+type TokenSearchFieldProps = TokenSearchFieldBaseProps & TokenSearchCollapsibleProps;
 interface TokenSearchFieldValue {
     query: string;
     tokens: TokenSearchToken[];
@@ -40,4 +56,4 @@ declare function readTokenSearchField(editor: HTMLElement, knownTokens?: readonl
 /** Focus an editor and place its caret at a text offset, skipping atomic token chips. */
 declare function placeTokenSearchCaret(editor: HTMLElement, offset?: number): void;
 
-export { TokenSearchField, type TokenSearchFieldProps, type TokenSearchFieldValue, type TokenSearchToken, placeTokenSearchCaret, readTokenSearchField };
+export { type TokenSearchEditorAttributes, TokenSearchField, type TokenSearchFieldProps, type TokenSearchFieldValue, type TokenSearchToken, placeTokenSearchCaret, readTokenSearchField };

package/dist/token-search-field.js

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

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

@@ -1,17 +1,21 @@
 import { SafeHtml } from 'kerfjs';
 
+type ToolbarControlGroupAppearance = 'contained' | 'borderless';
+type ToolbarControlGroupTone = 'default' | 'dark';
+type ToolbarControlGroupButtonAppearance = 'plain' | 'push';
+type ToolbarControlGroupShape = 'pill' | 'rounded';
 interface ToolbarControlGroupProps {
     children: SafeHtml | SafeHtml[];
     label?: string;
     className?: string;
     expanded?: boolean;
     single?: boolean;
-    appearance?: 'contained' | 'borderless';
-    tone?: 'default' | 'dark';
-    buttonAppearance?: 'plain' | 'push';
+    appearance?: ToolbarControlGroupAppearance;
+    tone?: ToolbarControlGroupTone;
+    buttonAppearance?: ToolbarControlGroupButtonAppearance;
     /** Corner shape: fully round `pill` (default) or a softer `rounded` rectangle. */
-    shape?: 'pill' | 'rounded';
+    shape?: ToolbarControlGroupShape;
 }
-declare function ToolbarControlGroup({ children, label, className, expanded, single, appearance, tone, buttonAppearance, shape }: ToolbarControlGroupProps): SafeHtml;
+declare function ToolbarControlGroup({ children, label, className, expanded, single, appearance, tone, buttonAppearance, shape, }: ToolbarControlGroupProps): SafeHtml;
 
-export { ToolbarControlGroup, type ToolbarControlGroupProps };
+export { ToolbarControlGroup, type ToolbarControlGroupAppearance, type ToolbarControlGroupButtonAppearance, type ToolbarControlGroupProps, type ToolbarControlGroupShape, type ToolbarControlGroupTone };

package/dist/toolbar-control-group.js

@@ -1,3 +1,3 @@
-export { ToolbarControlGroup } from './chunk-RNPGFQ33.js';
+export { ToolbarControlGroup } from './chunk-5VTB2BKP.js';
 
 //# sourceMappingURL=toolbar-control-group.js.map

package/dist/toolbar-text.d.ts

@@ -3,7 +3,7 @@ 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 {
+interface ToolbarTextBaseProps {
     text: string;
     size?: ToolbarTextSize;
     className?: string;
@@ -17,23 +17,22 @@ interface ToolbarTextProps {
     headingLevel?: HeadingLevel;
     /** Render the text as an unanimated loading skeleton instead of its value. */
     placeholder?: boolean;
-    /**
-     * Wrap onto multiple lines when the text does not fit, instead of the default
-     * single line. Combine with `maxLines` to cap the number of lines. Default false.
-     */
-    wrap?: boolean;
     /**
      * Show a trailing ellipsis (…) where the text is truncated — on the single line
      * (default), or at the `maxLines` boundary when wrapping. Set false to hard-clip
      * instead. Default true.
      */
     ellipsis?: boolean;
-    /**
-     * Cap wrapped text to this many lines, truncating past it. Only takes effect with
-     * `wrap`; ignored on a single line. `null`/omitted wraps without a line cap. Default null.
-     */
-    maxLines?: number | null;
 }
+type ToolbarTextWrappingProps = {
+    /** Wrap onto multiple lines; combine with `maxLines` to cap them. */
+    wrap: true;
+    maxLines?: number | null;
+} | {
+    wrap?: false;
+    maxLines?: never;
+};
+type ToolbarTextProps = ToolbarTextBaseProps & ToolbarTextWrappingProps;
 declare function ToolbarText({ text, size, className, id, headingLevel, placeholder, wrap, ellipsis, maxLines, }: ToolbarTextProps): kerfjs.SafeHtml;
 
 export { type HeadingLevel, ToolbarText, type ToolbarTextProps, type ToolbarTextSize };

package/dist/toolbar-text.js

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

package/dist/toolbar.d.ts

@@ -8,6 +8,6 @@ interface ToolbarProps {
     divider?: boolean;
     className?: string;
 }
-declare function Toolbar({ leading, center, trailing, label, divider, className }: ToolbarProps): SafeHtml;
+declare function Toolbar({ leading, center, trailing, label, divider, className, }: ToolbarProps): SafeHtml;
 
 export { Toolbar, type ToolbarProps };

package/dist/toolbar.js

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

package/dist/value-table.d.ts

@@ -8,13 +8,13 @@ interface ValueTableRowProps {
     /** Render the value as an unanimated loading skeleton, keeping the field label. */
     placeholder?: boolean;
 }
-declare function ValueTableRow({ label, value, icon, className, placeholder }: ValueTableRowProps): SafeHtml;
+declare function ValueTableRow({ label, value, icon, className, placeholder, }: ValueTableRowProps): SafeHtml;
 
 interface ValueTableProps {
     label: string;
     className?: string;
     children: SafeHtml | readonly SafeHtml[];
 }
-declare function ValueTable({ label, className, children }: ValueTableProps): SafeHtml;
+declare function ValueTable({ label, className, children, }: ValueTableProps): SafeHtml;
 
 export { ValueTable, type ValueTableProps, ValueTableRow, type ValueTableRowProps };

package/dist/value-table.js

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

package/dist/wire-catalog.d.ts

@@ -9,11 +9,40 @@ interface WireCatalogOptions {
     onToggleSecondary?: () => void;
     /** When set, `?<urlParam>=<id>` is written on select via `history.replaceState`. */
     urlParam?: string;
+    /**
+     * Reveal the chosen sidebar row after selection. `true` uses desktop-safe
+     * defaults; pass options to customize scroll alignment or the media guard.
+     */
+    revealSelection?: boolean | CatalogRevealOptions;
     selectAction?: string;
     toggleSidebarAction?: string;
     toggleThemeAction?: string;
     toggleSecondaryAction?: string;
 }
+interface CatalogRevealOptions {
+    /** Scroll alignment within the sidebar. Default `'nearest'`. */
+    block?: ScrollLogicalPosition;
+    /** Cross-axis alignment. Default `'nearest'`. */
+    inline?: ScrollLogicalPosition;
+    /** Scroll behavior. Default `'auto'`. */
+    behavior?: ScrollBehavior;
+    /**
+     * Only reveal when this media query matches. Defaults to the Catalog's
+     * desktop layout; pass `false` to reveal at every viewport size.
+     */
+    media?: string | false;
+}
+/**
+ * Reveal one Catalog sidebar entry after the controlled render settles without
+ * moving focus. Returns a cancellation function for rapid selection changes.
+ */
+declare function revealCatalogEntry(root: HTMLElement, id: string, { block, inline, behavior, media, }?: CatalogRevealOptions): () => void;
+/**
+ * Keep a Catalog's opt-in geometry overlay synchronized with its preview.
+ * Transparent specimens receive a dashed outer bound and positive margins use
+ * devtools-style orange bands. Returns a disposer.
+ */
+declare function wireCatalogGeometryOverlay(root: HTMLElement): () => void;
 /**
  * Wire a {@link Catalog}'s interactions with one delegated listener set: sidebar
  * item selection (and the related-entry popup menu), the sidebar collapse toggle, and
@@ -21,6 +50,6 @@ interface WireCatalogOptions {
  * 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;
+declare function wireCatalog(root: HTMLElement, { onSelect, onToggleSidebar, onToggleTheme, onToggleSecondary, urlParam, revealSelection, selectAction, toggleSidebarAction, toggleThemeAction, toggleSecondaryAction, }: WireCatalogOptions): () => void;
 
-export { type WireCatalogOptions, wireCatalog };
+export { type CatalogRevealOptions, type WireCatalogOptions, revealCatalogEntry, wireCatalog, wireCatalogGeometryOverlay };

package/dist/wire-catalog.js

@@ -1,17 +1,177 @@
 import { delegate } from 'kerfjs';
 
 // src/wire-catalog.ts
+var catalogDesktopMedia = "(min-width: 52.01rem)";
+function revealCatalogEntry(root, id, {
+  block = "nearest",
+  inline = "nearest",
+  behavior = "auto",
+  media = catalogDesktopMedia
+} = {}) {
+  const view = root.ownerDocument.defaultView;
+  if (!view || media && !view.matchMedia(media).matches) return () => {
+  };
+  const frame = view.requestAnimationFrame(() => {
+    for (const item of root.querySelectorAll("[data-item-id]")) {
+      if (item.dataset.itemId !== id) continue;
+      item.scrollIntoView({ block, inline, behavior });
+      break;
+    }
+  });
+  return () => view.cancelAnimationFrame(frame);
+}
+function pixels(value) {
+  const number = Number.parseFloat(value);
+  if (!Number.isFinite(number)) return 0;
+  return value.trim().endsWith("rem") ? number * 16 : number;
+}
+function isTransparent(color) {
+  const normalized = color.replace(/\s+/g, "");
+  return normalized === "transparent" || /(?:,|\/)0(?:\.0+)?\)$/.test(normalized);
+}
+function isExampleLabel(element) {
+  const parent = element.parentElement;
+  if (!element.classList.contains("kui-list-header") || !parent?.classList.contains("kui-catalog-example") || element !== parent.firstElementChild)
+    return false;
+  for (let sibling = element.nextElementSibling; sibling; sibling = sibling.nextElementSibling)
+    if (!sibling.classList.contains("kui-catalog-example__note")) return true;
+  return false;
+}
+function geometrySpecimens(canvas) {
+  const result = [];
+  for (const example of canvas.querySelectorAll(
+    ".kui-catalog-example"
+  )) {
+    if (example.closest("[data-catalog-geometry-overlay-skip]")) continue;
+    for (const child of example.children) {
+      if (child.matches("[data-catalog-geometry-overlay]") || child.classList.contains("kui-catalog-example__note") || isExampleLabel(child))
+        continue;
+      result.push(child);
+    }
+  }
+  for (const element of canvas.querySelectorAll(
+    "[data-component]"
+  )) {
+    if (element.closest("[data-catalog-geometry-overlay]") || element.closest("[data-catalog-geometry-overlay-skip]") || element.closest(".kui-catalog-example"))
+      continue;
+    const parent = element.parentElement?.closest("[data-component]");
+    if (parent && canvas.contains(parent)) continue;
+    result.push(element);
+  }
+  return result;
+}
+function geometryBox(document, className, left, top, width, height) {
+  const element = document.createElement("div");
+  element.className = className;
+  element.style.transform = `translate(${left}px, ${top}px)`;
+  element.style.width = `${Math.max(0, width)}px`;
+  element.style.height = `${Math.max(0, height)}px`;
+  return element;
+}
+function wireCatalogGeometryOverlay(root) {
+  const catalog = root.matches('[data-component="catalog"]') ? root : root.querySelector('[data-component="catalog"]');
+  const canvas = catalog?.querySelector(".kui-catalog__canvas");
+  const layer = catalog?.querySelector(
+    "[data-catalog-geometry-overlay]"
+  );
+  const view = root.ownerDocument.defaultView;
+  if (!catalog || !canvas || !layer || !view) return () => {
+  };
+  let frame = 0;
+  const render = () => {
+    frame = 0;
+    layer.replaceChildren();
+    if (catalog.dataset.geometryOverlay !== "true") return;
+    const base = canvas.getBoundingClientRect();
+    for (const element of geometrySpecimens(canvas)) {
+      const rect = element.getBoundingClientRect();
+      const style = view.getComputedStyle(element);
+      const align = pixels(
+        style.getPropertyValue("--kui-catalog-example-align")
+      );
+      const top = pixels(style.marginTop);
+      const right = Math.max(
+        0,
+        pixels(style.marginRight) - (style.direction === "rtl" ? align : 0)
+      );
+      const bottom = pixels(style.marginBottom);
+      const left = Math.max(
+        0,
+        pixels(style.marginLeft) - (style.direction === "rtl" ? 0 : align)
+      );
+      const x = rect.left - base.left + canvas.scrollLeft;
+      const y = rect.top - base.top + canvas.scrollTop;
+      if (isTransparent(style.backgroundColor))
+        layer.append(
+          geometryBox(
+            root.ownerDocument,
+            "kui-catalog__geometry-bound",
+            x,
+            y,
+            rect.width,
+            rect.height
+          )
+        );
+      const margins = [
+        [top, x - left, y - top, rect.width + left + right, top],
+        [bottom, x - left, y + rect.height, rect.width + left + right, bottom],
+        [left, x - left, y, left, rect.height],
+        [right, x + rect.width, y, right, rect.height]
+      ];
+      for (const [size, marginX, marginY, width, height] of margins) {
+        if (size <= 0) continue;
+        layer.append(
+          geometryBox(
+            root.ownerDocument,
+            "kui-catalog__geometry-margin",
+            marginX,
+            marginY,
+            width,
+            height
+          )
+        );
+      }
+    }
+  };
+  const schedule = () => {
+    if (!frame) frame = view.requestAnimationFrame(render);
+  };
+  const resizeObserver = new view.ResizeObserver(schedule);
+  resizeObserver.observe(canvas);
+  const mutationObserver = new view.MutationObserver((records) => {
+    if (records.some(
+      ({ target }) => target !== layer && !layer.contains(target)
+    ))
+      schedule();
+  });
+  mutationObserver.observe(catalog, {
+    attributes: true,
+    childList: true,
+    subtree: true
+  });
+  view.addEventListener("resize", schedule);
+  render();
+  return () => {
+    if (frame) view.cancelAnimationFrame(frame);
+    resizeObserver.disconnect();
+    mutationObserver.disconnect();
+    view.removeEventListener("resize", schedule);
+    layer.replaceChildren();
+  };
+}
 function wireCatalog(root, {
   onSelect,
   onToggleSidebar,
   onToggleTheme,
   onToggleSecondary,
   urlParam,
+  revealSelection,
   selectAction = "catalog-select",
   toggleSidebarAction = "catalog-toggle-sidebar",
   toggleThemeAction = "catalog-toggle-theme",
   toggleSecondaryAction = "catalog-toggle-secondary"
 }) {
+  let cancelReveal;
   const select = (id) => {
     onSelect(id);
     const view = root.ownerDocument.defaultView;
@@ -20,29 +180,64 @@ function wireCatalog(root, {
       url.searchParams.set(urlParam, id);
       view.history.replaceState(null, "", url);
     }
+    if (revealSelection) {
+      cancelReveal?.();
+      cancelReveal = revealCatalogEntry(
+        root,
+        id,
+        revealSelection === true ? void 0 : revealSelection
+      );
+    }
   };
   const disposers = [
     // 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(root, "click", `[data-action="${selectAction}"]`, (_event, element) => {
-      const id = element.dataset.itemId;
-      if (id) select(id);
-    })
+    delegate(
+      root,
+      "click",
+      `[data-action="${selectAction}"]`,
+      (_event, element) => {
+        const id = element.dataset.itemId;
+        if (id) select(id);
+      }
+    )
   ];
   if (onToggleSidebar) {
-    disposers.push(delegate(root, "click", `[data-action="${toggleSidebarAction}"]`, () => onToggleSidebar()));
+    disposers.push(
+      delegate(
+        root,
+        "click",
+        `[data-action="${toggleSidebarAction}"]`,
+        () => onToggleSidebar()
+      )
+    );
   }
   if (onToggleTheme) {
-    disposers.push(delegate(root, "click", `[data-action="${toggleThemeAction}"]`, () => onToggleTheme()));
+    disposers.push(
+      delegate(
+        root,
+        "click",
+        `[data-action="${toggleThemeAction}"]`,
+        () => onToggleTheme()
+      )
+    );
   }
   if (onToggleSecondary) {
-    disposers.push(delegate(root, "click", `[data-action="${toggleSecondaryAction}"]`, () => onToggleSecondary()));
+    disposers.push(
+      delegate(
+        root,
+        "click",
+        `[data-action="${toggleSecondaryAction}"]`,
+        () => onToggleSecondary()
+      )
+    );
   }
   return () => {
+    cancelReveal?.();
     for (const dispose of disposers.splice(0)) dispose();
   };
 }
 
-export { wireCatalog };
+export { revealCatalogEntry, wireCatalog, wireCatalogGeometryOverlay };
 
 //# sourceMappingURL=wire-catalog.js.map

package/dist/wire-catalog.js.map

@@ -1 +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;AAAA;AAAA,IAGnC,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;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 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    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    // 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(root, 'click', `[data-action=\"${selectAction}\"]`, (_event, element) => {\n      const id = (element as HTMLElement).dataset.itemId;\n      if (id) select(id);\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"]}
+{"version":3,"sources":["../src/wire-catalog.ts"],"names":[],"mappings":"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","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  /**\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\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\nconst catalogDesktopMedia = '(min-width: 52.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 isExampleLabel(element: Element): boolean {\n  const parent = element.parentElement;\n  if (\n    !element.classList.contains('kui-list-header') ||\n    !parent?.classList.contains('kui-catalog-example') ||\n    element !== parent.firstElementChild\n  )\n    return false;\n  for (\n    let sibling = element.nextElementSibling;\n    sibling;\n    sibling = sibling.nextElementSibling\n  )\n    if (!sibling.classList.contains('kui-catalog-example__note')) return true;\n  return false;\n}\n\nfunction geometrySpecimens(canvas: HTMLElement): Element[] {\n  const result: Element[] = [];\n  for (const example of canvas.querySelectorAll<HTMLElement>(\n    '.kui-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.classList.contains('kui-catalog-example__note') ||\n        isExampleLabel(child)\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\n/**\n * Keep a Catalog's opt-in geometry overlay synchronized with its preview.\n * Transparent specimens receive a dashed outer bound and positive margins use\n * devtools-style orange bands. 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') return;\n    const base = canvas.getBoundingClientRect();\n    for (const element of geometrySpecimens(canvas)) {\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      if (isTransparent(style.backgroundColor))\n        layer.append(\n          geometryBox(\n            root.ownerDocument,\n            'kui-catalog__geometry-bound',\n            x,\n            y,\n            rect.width,\n            rect.height,\n          ),\n        );\n      const margins = [\n        [top, x - left, y - top, rect.width + left + right, top],\n        [bottom, x - left, y + rect.height, rect.width + left + right, bottom],\n        [left, x - left, y, left, rect.height],\n        [right, x + rect.width, y, right, rect.height],\n      ];\n      for (const [size, marginX, marginY, width, height] of margins) {\n        if (size <= 0) continue;\n        layer.append(\n          geometryBox(\n            root.ownerDocument,\n            'kui-catalog__geometry-margin',\n            marginX,\n            marginY,\n            width,\n            height,\n          ),\n        );\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 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  view.addEventListener('resize', schedule);\n  render();\n  return () => {\n    if (frame) view.cancelAnimationFrame(frame);\n    resizeObserver.disconnect();\n    mutationObserver.disconnect();\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  }: 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    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  return () => {\n    cancelReveal?.();\n    for (const dispose of disposers.splice(0)) dispose();\n  };\n}\n"]}