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

package/dist/wire-catalog.js

@@ -0,0 +1,327 @@
+import { wireWorkbench } from './chunk-NNMLEDMD.js';
+
+import { wireScrollDividers } from './chunk-JCV4GXWB.js';
+
+
+import { delegate } from 'kerfjs';
+
+var catalogDesktopMedia = "(min-width: 44.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 geometrySpecimens(canvas) {
+  const result = [];
+  for (const example of canvas.querySelectorAll(
+    "[data-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.matches("[data-catalog-example-label]") || child.matches("[data-catalog-example-note]"))
+        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 effectiveBorderWidth(width, style) {
+  return style === "none" || style === "hidden" ? 0 : pixels(width);
+}
+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") {
+      syncObservedSpecimens([]);
+      return;
+    }
+    const base = canvas.getBoundingClientRect();
+    const specimens = geometrySpecimens(canvas);
+    syncObservedSpecimens(specimens);
+    for (const [specimenIndex, element] of specimens.entries()) {
+      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;
+      const borderWidths = [
+        effectiveBorderWidth(style.borderTopWidth, style.borderTopStyle),
+        effectiveBorderWidth(style.borderRightWidth, style.borderRightStyle),
+        effectiveBorderWidth(style.borderBottomWidth, style.borderBottomStyle),
+        effectiveBorderWidth(style.borderLeftWidth, style.borderLeftStyle)
+      ];
+      if (borderWidths.some((width) => width > 0)) {
+        const border = geometryBox(
+          root.ownerDocument,
+          "kui-catalog__geometry-border",
+          x,
+          y,
+          rect.width,
+          rect.height
+        );
+        border.dataset.catalogGeometrySpecimen = String(specimenIndex);
+        border.style.borderTopWidth = `${borderWidths[0]}px`;
+        border.style.borderRightWidth = `${borderWidths[1]}px`;
+        border.style.borderBottomWidth = `${borderWidths[2]}px`;
+        border.style.borderLeftWidth = `${borderWidths[3]}px`;
+        border.style.borderRadius = style.borderRadius;
+        layer.append(border);
+      } else if (isTransparent(style.backgroundColor)) {
+        const bound = geometryBox(
+          root.ownerDocument,
+          "kui-catalog__geometry-bound",
+          x,
+          y,
+          rect.width,
+          rect.height
+        );
+        bound.dataset.catalogGeometrySpecimen = String(specimenIndex);
+        layer.append(bound);
+      }
+      const margins = [
+        ["top", top, x - left, y - top, rect.width + left + right, top],
+        [
+          "bottom",
+          bottom,
+          x - left,
+          y + rect.height,
+          rect.width + left + right,
+          bottom
+        ],
+        ["left", left, x - left, y, left, rect.height],
+        ["right", right, x + rect.width, y, right, rect.height]
+      ];
+      for (const [side, size, marginX, marginY, width, height] of margins) {
+        if (size <= 0) continue;
+        const margin = geometryBox(
+          root.ownerDocument,
+          "kui-catalog__geometry-margin",
+          marginX,
+          marginY,
+          width,
+          height
+        );
+        margin.dataset.catalogGeometrySpecimen = String(specimenIndex);
+        margin.dataset.catalogGeometrySide = side;
+        layer.append(margin);
+      }
+    }
+  };
+  const schedule = () => {
+    if (!frame) frame = view.requestAnimationFrame(render);
+  };
+  const resizeObserver = new view.ResizeObserver(schedule);
+  resizeObserver.observe(canvas);
+  const observedSpecimens = /* @__PURE__ */ new Set();
+  const syncObservedSpecimens = (specimens) => {
+    const next = new Set(specimens);
+    for (const specimen of observedSpecimens) {
+      if (next.has(specimen)) continue;
+      resizeObserver.unobserve(specimen);
+      observedSpecimens.delete(specimen);
+    }
+    for (const specimen of next) {
+      if (observedSpecimens.has(specimen)) continue;
+      resizeObserver.observe(specimen);
+      observedSpecimens.add(specimen);
+    }
+  };
+  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
+  });
+  mutationObserver.observe(root.ownerDocument.documentElement, {
+    attributes: true
+  });
+  const documentHead = root.ownerDocument.head;
+  if (documentHead)
+    mutationObserver.observe(documentHead, {
+      attributes: true,
+      characterData: true,
+      childList: true,
+      subtree: true
+    });
+  const stylesheetLoaded = () => schedule();
+  documentHead?.addEventListener("load", stylesheetLoaded, true);
+  view.addEventListener("resize", schedule);
+  render();
+  return () => {
+    if (frame) view.cancelAnimationFrame(frame);
+    resizeObserver.disconnect();
+    mutationObserver.disconnect();
+    documentHead?.removeEventListener("load", stylesheetLoaded, true);
+    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",
+  collapsed,
+  sidebarSize,
+  sidebarStorageKey,
+  id: catalogId = "kui-catalog"
+}) {
+  let cancelReveal;
+  const select = (id) => {
+    onSelect(id);
+    const view = root.ownerDocument.defaultView;
+    if (urlParam && view) {
+      const url = new URL(view.location.href);
+      url.searchParams.set(urlParam, id);
+      view.history.replaceState(null, "", url);
+    }
+    const rail = root.ownerDocument.getElementById(`${catalogId}-left-rail`);
+    if (collapsed && !collapsed.peek() && rail && root.ownerDocument.defaultView?.getComputedStyle(rail).position === "absolute")
+      collapsed.value = true;
+    if (revealSelection) {
+      cancelReveal?.();
+      cancelReveal = revealCatalogEntry(
+        root,
+        id,
+        revealSelection === true ? void 0 : revealSelection
+      );
+    }
+  };
+  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(
+      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()
+      )
+    );
+  }
+  if (onToggleTheme) {
+    disposers.push(
+      delegate(
+        root,
+        "click",
+        `[data-action="${toggleThemeAction}"]`,
+        () => onToggleTheme()
+      )
+    );
+  }
+  if (onToggleSecondary) {
+    disposers.push(
+      delegate(
+        root,
+        "click",
+        `[data-action="${toggleSecondaryAction}"]`,
+        () => onToggleSecondary()
+      )
+    );
+  }
+  if (collapsed || sidebarSize)
+    disposers.push(
+      wireWorkbench(root, {
+        id: catalogId,
+        panels: {
+          leftRail: {
+            collapsed,
+            size: sidebarSize,
+            storageKey: sidebarStorageKey
+          }
+        }
+      })
+    );
+  return () => {
+    cancelReveal?.();
+    for (const dispose of disposers.splice(0)) dispose();
+  };
+}
+
+export { revealCatalogEntry, wireCatalog, wireCatalogGeometryOverlay };
+
+//# sourceMappingURL=wire-catalog.js.map

package/dist/wire-catalog.js.map

@@ -0,0 +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 { 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-nav-stack.d.ts

@@ -8,7 +8,10 @@ interface WireNavStackOptions {
  * Animate a `NavStack`'s push/pop transitions and wire its back control. The app
  * owns the stack (a signal of `NavStackView[]`) and re-renders `NavStack` when it
  * changes; this helper slides the content and settles the chrome across each
- * change, and calls `onBack` when the back control is used. Returns a disposer.
+ * change, moves focus into every new top view, restores that view's last focused
+ * descendant on pop, and calls `onBack` when the back control is used. Mark a
+ * preferred initial target with `data-nav-focus`; otherwise the first focusable
+ * descendant (or the view itself) receives focus. Returns a disposer.
  */
 declare function wireNavStack(root: Element, options?: WireNavStackOptions): () => void;
 

package/dist/wire-nav-stack.js

@@ -2,16 +2,38 @@ import { delegate } from 'kerfjs';
 
 // src/wire-nav-stack.ts
 var DEFAULT_DURATION = 200;
+var FOCUSABLE_SELECTOR = [
+  "a[href]",
+  "button:not([disabled])",
+  "input:not([disabled])",
+  "select:not([disabled])",
+  "textarea:not([disabled])",
+  '[tabindex]:not([tabindex="-1"])'
+].join(",");
 function viewsOf(viewport) {
-  return Array.from(viewport.querySelectorAll(":scope > .kui-nav-stack__view"));
+  return Array.from(
+    viewport.querySelectorAll(":scope > .kui-nav-stack__view")
+  );
 }
 function topView(viewport) {
-  const live = viewsOf(viewport).filter((view) => view.dataset.navExiting !== "true");
+  const live = viewsOf(viewport).filter(
+    (view) => view.dataset.navExiting !== "true"
+  );
   return live[live.length - 1];
 }
 function reducedMotion(view) {
   return typeof view.matchMedia === "function" && view.matchMedia("(prefers-reduced-motion: reduce)").matches;
 }
+function chromeOf(section) {
+  return Array.from(
+    section.querySelectorAll(
+      ":scope > [data-nav-stack-chrome], :scope > [data-nav-stack-bottom]"
+    )
+  );
+}
+function availableFocusTarget(element) {
+  return element instanceof HTMLElement && element.isConnected && !element.matches('[disabled], [aria-disabled="true"]') && !element.closest('[inert], [hidden], [aria-hidden="true"]');
+}
 function wireNavStack(root, options = {}) {
   const section = root.matches('[data-component="nav-stack"]') ? root : root.querySelector('[data-component="nav-stack"]');
   const viewport = section?.querySelector("[data-nav-stack-viewport]");
@@ -19,9 +41,26 @@ function wireNavStack(root, options = {}) {
   };
   const view = section.ownerDocument.defaultView ?? window;
   const duration = options.duration ?? DEFAULT_DURATION;
-  const disposeBack = delegate(section, "click", "[data-nav-back]", () => options.onBack?.());
+  const previousDuration = section.style.getPropertyValue(
+    "--kui-nav-stack-transition-duration"
+  );
+  section.style.setProperty(
+    "--kui-nav-stack-transition-duration",
+    `${Math.max(0, duration)}ms`
+  );
+  const disposeBack = delegate(
+    section,
+    "click",
+    "[data-nav-back]",
+    () => options.onBack?.()
+  );
   let activeKey = topView(viewport)?.dataset.navKey;
   const timers = /* @__PURE__ */ new Set();
+  const rememberedFocus = /* @__PURE__ */ new Map();
+  const generatedFallbacks = /* @__PURE__ */ new Map();
+  let chromeSnapshots = chromeOf(section).map(
+    (element) => element.cloneNode(true)
+  );
   const settle = (fn) => {
     if (duration <= 0 || reducedMotion(view)) {
       fn();
@@ -39,25 +78,105 @@ function wireNavStack(root, options = {}) {
       el.classList.add("kui-nav-stack__view--entering");
       if (animated) {
         void el.offsetWidth;
-        view.requestAnimationFrame(() => el.classList.remove("kui-nav-stack__view--entering"));
+        view.requestAnimationFrame(
+          () => el.classList.remove("kui-nav-stack__view--entering")
+        );
       } else {
         el.classList.remove("kui-nav-stack__view--entering");
       }
     } else if (animated) {
-      view.requestAnimationFrame(() => el.classList.add("kui-nav-stack__view--exiting"));
+      view.requestAnimationFrame(
+        () => el.classList.add("kui-nav-stack__view--exiting")
+      );
     } else {
       el.classList.add("kui-nav-stack__view--exiting");
     }
   };
+  const rememberFocusedView = (target) => {
+    if (!(target instanceof HTMLElement)) return;
+    const owner = target.closest(".kui-nav-stack__view");
+    const key = owner?.dataset.navKey;
+    if (key && owner !== target && viewport.contains(owner))
+      rememberedFocus.set(key, target);
+  };
+  const focusInto = (targetView) => {
+    const key = targetView.dataset.navKey;
+    const remembered = key ? rememberedFocus.get(key) : void 0;
+    const preferred = Array.from(
+      targetView.querySelectorAll("[data-nav-focus]")
+    ).find(availableFocusTarget);
+    const first = Array.from(
+      targetView.querySelectorAll(FOCUSABLE_SELECTOR)
+    ).find(availableFocusTarget);
+    const target = (availableFocusTarget(remembered) && targetView.contains(remembered) ? remembered : void 0) ?? preferred ?? first;
+    if (target) {
+      target.focus({ preventScroll: true });
+      return;
+    }
+    if (!generatedFallbacks.has(targetView)) {
+      generatedFallbacks.set(
+        targetView,
+        targetView.hasAttribute("tabindex") ? targetView.getAttribute("tabindex") : null
+      );
+      targetView.tabIndex = -1;
+    }
+    targetView.focus({ preventScroll: true });
+  };
+  const onFocusIn = (event) => rememberFocusedView(event.target);
+  section.addEventListener("focusin", onFocusIn);
+  rememberFocusedView(section.ownerDocument.activeElement);
+  const crossFadeChrome = () => {
+    const current = chromeOf(section);
+    const animated = duration > 0 && !reducedMotion(view);
+    if (!animated) {
+      chromeSnapshots = current.map(
+        (element) => element.cloneNode(true)
+      );
+      return;
+    }
+    section.dataset.navChromeTransition = "true";
+    const copies = chromeSnapshots.map((snapshot) => {
+      const copy = snapshot.cloneNode(true);
+      copy.classList.add("kui-nav-stack__chrome-copy");
+      copy.dataset.navChromeCopy = "";
+      copy.setAttribute("aria-hidden", "true");
+      copy.setAttribute("inert", "");
+      if (copy.hasAttribute("data-nav-stack-bottom"))
+        copy.classList.add("kui-nav-stack__chrome-copy--bottom");
+      section.append(copy);
+      return copy;
+    });
+    current.forEach(
+      (element) => element.classList.add("kui-nav-stack__chrome--entering")
+    );
+    void section.offsetWidth;
+    view.requestAnimationFrame(() => {
+      current.forEach(
+        (element) => element.classList.remove("kui-nav-stack__chrome--entering")
+      );
+      copies.forEach(
+        (copy) => copy.classList.add("kui-nav-stack__chrome-copy--exiting")
+      );
+    });
+    settle(() => {
+      copies.forEach((copy) => copy.remove());
+      delete section.dataset.navChromeTransition;
+    });
+    chromeSnapshots = current.map(
+      (element) => element.cloneNode(true)
+    );
+  };
   const observer = new MutationObserver((records) => {
     const removed = [];
     let added = false;
     for (const record of records) {
       record.removedNodes.forEach((node) => {
-        if (node instanceof HTMLElement && node.classList.contains("kui-nav-stack__view") && node.dataset.navExiting !== "true") removed.push(node);
+        if (node instanceof HTMLElement && node.classList.contains("kui-nav-stack__view") && node.dataset.navExiting !== "true")
+          removed.push(node);
       });
       record.addedNodes.forEach((node) => {
-        if (node instanceof HTMLElement && node.classList.contains("kui-nav-stack__view")) added = true;
+        if (node instanceof HTMLElement && node.classList.contains("kui-nav-stack__view"))
+          added = true;
       });
     }
     const top = topView(viewport);
@@ -68,18 +187,39 @@ function wireNavStack(root, options = {}) {
       poppedTop.setAttribute("aria-hidden", "true");
       viewport.append(poppedTop);
       play(poppedTop, "exiting");
+      crossFadeChrome();
+      if (top) focusInto(top);
       settle(() => poppedTop.remove());
     } else if (added && currentKey !== activeKey && top) {
+      rememberFocusedView(section.ownerDocument.activeElement);
       play(top, "entering");
+      crossFadeChrome();
+      focusInto(top);
     }
     activeKey = currentKey;
   });
   observer.observe(viewport, { childList: true });
   return () => {
     disposeBack();
+    section.removeEventListener("focusin", onFocusIn);
     observer.disconnect();
     for (const timer of timers) view.clearTimeout(timer);
     timers.clear();
+    section.querySelectorAll("[data-nav-chrome-copy]").forEach((copy) => copy.remove());
+    delete section.dataset.navChromeTransition;
+    for (const [element, previousTabIndex] of generatedFallbacks) {
+      if (!element.isConnected || element.tabIndex !== -1) continue;
+      if (previousTabIndex === null) element.removeAttribute("tabindex");
+      else element.setAttribute("tabindex", previousTabIndex);
+    }
+    generatedFallbacks.clear();
+    rememberedFocus.clear();
+    if (previousDuration)
+      section.style.setProperty(
+        "--kui-nav-stack-transition-duration",
+        previousDuration
+      );
+    else section.style.removeProperty("--kui-nav-stack-transition-duration");
   };
 }