@takazudo/zudo-doc 6.1.1 → 6.2.0

package/dist/sidebar-tree-island/sidebar-scroll-preserve.js

@@ -3,53 +3,350 @@ import {
   BEFORE_NAVIGATE_EVENT
 } from "../transitions/index.js";
 const installedControllers = /* @__PURE__ */ new WeakMap();
+const HISTORY_KEY = "zdSidebarScroll";
+const PENDING_KEY = "zd-sidebar-scroll-pending";
+const VIEWPORTS = ["desktop", "mobile"];
+function canonicalPath(pathname) {
+  return pathname.length > 1 && pathname.endsWith("/") ? pathname.slice(0, -1) : pathname;
+}
 function installSidebarScrollPreserve({
   document: document2,
   requestAnimationFrame,
-  cancelAnimationFrame
+  cancelAnimationFrame,
+  ResizeObserver: ResizeObserverImpl
 }) {
-  let snapshot;
+  const view = document2.defaultView;
+  let epoch = 0;
+  let shortRetries = 0;
+  let traverse = false;
+  let awaiting = false;
   let restoreFrame;
-  const cancelPendingRestore = () => {
+  let didInitial = false;
+  let writing = false;
+  let observer;
+  const observed = /* @__PURE__ */ new Set();
+  const skipped = /* @__PURE__ */ new Set();
+  const applied = /* @__PURE__ */ new Set();
+  let elements = {};
+  let memory = {};
+  let pending;
+  let held = {};
+  const cancelFrame = () => {
     if (restoreFrame === void 0) return;
     cancelAnimationFrame(restoreFrame);
     restoreFrame = void 0;
   };
-  const onBefore = () => {
-    cancelPendingRestore();
-    const element = document2.querySelector("#desktop-sidebar");
-    snapshot = element ? { element, scrollTop: element.scrollTop } : void 0;
+  const disconnectObserver = () => {
+    observer?.disconnect();
+    observer = void 0;
   };
-  const onAfter = () => {
-    if (!snapshot) return;
-    const saved = snapshot;
-    snapshot = void 0;
+  const capture = () => {
+    const next = { ...memory };
+    for (const kind of VIEWPORTS) {
+      const element = findViewport(document2, kind);
+      if (!element) {
+        delete next[kind];
+        delete elements[kind];
+        continue;
+      }
+      if (!measurable(element)) continue;
+      if (isEmptyTree(element) && element.scrollTop === 0 && (next[kind]?.scrollTop ?? 0) > 0) continue;
+      next[kind] = readSlot(element);
+      elements[kind] = element;
+    }
+    memory = next;
+    return next;
+  };
+  const writeHistory = (slots) => {
+    if (!view || traverse) return;
+    const state = view.history.state;
+    if (!state || typeof state !== "object") return;
+    if (JSON.stringify(state.zdSidebarScroll) === JSON.stringify(slots)) return;
+    try {
+      view.history.replaceState({ ...state, [HISTORY_KEY]: slots }, "");
+    } catch {
+    }
+  };
+  const schedule = () => {
+    if (restoreFrame !== void 0) return;
     restoreFrame = requestAnimationFrame(() => {
       restoreFrame = void 0;
-      const current = document2.querySelector("#desktop-sidebar");
-      if (current === saved.element) current.scrollTop = saved.scrollTop;
+      apply();
     });
   };
+  const arm = (kind, element) => {
+    const Observer = ResizeObserverImpl ?? view?.ResizeObserver;
+    if (!Observer || observed.has(kind)) return false;
+    observed.add(kind);
+    disconnectObserver();
+    const epochAt = epoch;
+    try {
+      const next = new Observer(() => {
+        disconnectObserver();
+        if (epochAt !== epoch) return;
+        apply();
+      });
+      next.observe(element);
+      observer = next;
+      return true;
+    } catch {
+      return false;
+    }
+  };
+  const finishIfSettled = (waiting) => {
+    if (waiting) return;
+    pending = void 0;
+    awaiting = false;
+    writeHistory(memory);
+  };
+  const applyHeld = () => {
+    let restored = false;
+    for (const kind of VIEWPORTS) {
+      const slot = held[kind];
+      if (!slot) continue;
+      const element = findViewport(document2, kind);
+      if (!element || !measurable(element)) continue;
+      const outcome = restoreViewport(kind, element, slot);
+      if (outcome === "wait") {
+        arm(kind, element);
+        continue;
+      }
+      memory[kind] = readSlot(element);
+      delete held[kind];
+      restored = true;
+    }
+    if (restored && !awaiting) writeHistory(memory);
+  };
+  const apply = () => {
+    if (!pending) {
+      if (Object.keys(held).length) applyHeld();
+      if (!didInitial) {
+        didInitial = true;
+        for (const kind of VIEWPORTS) {
+          const element = findViewport(document2, kind);
+          if (element && measurable(element)) revealCurrent(element, writeScroll);
+        }
+      }
+      return;
+    }
+    let waiting = false;
+    for (const kind of VIEWPORTS) {
+      const slot = pending[kind];
+      if (!slot || skipped.has(kind) || applied.has(kind)) continue;
+      const element = findViewport(document2, kind);
+      if (!element || !measurable(element)) {
+        if (element) {
+          held[kind] = slot;
+          memory[kind] = slot;
+        }
+        applied.add(kind);
+        continue;
+      }
+      const outcome = restoreViewport(kind, element, slot);
+      if (outcome === "wait") {
+        if (!isEmptyTree(element)) shortRetries += 1;
+        arm(kind, element);
+        waiting = true;
+        if (!isEmptyTree(element) && shortRetries < 8) schedule();
+        continue;
+      }
+      memory[kind] = readSlot(element);
+      applied.add(kind);
+    }
+    finishIfSettled(waiting);
+  };
+  const restoreViewport = (kind, element, slot) => {
+    const context = readContext(element);
+    if (slot.contextId) {
+      if (!context) return observed.has(kind) ? "done" : "wait";
+      if (context !== slot.contextId) {
+        revealCurrent(element, writeScroll);
+        return "done";
+      }
+    } else if (elements[kind] !== element) {
+      return "done";
+    }
+    const canHold = slot.scrollTop === 0 || element.scrollHeight - element.clientHeight + 2 >= slot.scrollTop;
+    if (!canHold) {
+      if (!isEmptyTree(element) && shortRetries >= 8) {
+        revealCurrent(element, writeScroll);
+        return "done";
+      }
+      return "wait";
+    }
+    const compatible = readViewKey(element) === slot.viewKey && readScope(element) === slot.scopeId && Math.abs(element.scrollHeight - slot.contentHeight) <= 2;
+    if (compatible) {
+      writeScroll(element, slot.scrollTop);
+      return "done";
+    }
+    if (slot.anchorId) {
+      const row = findAnchor(element, slot.anchorId);
+      if (row) {
+        const delta = row.getBoundingClientRect().top - element.getBoundingClientRect().top - (slot.anchorOffset ?? 0);
+        const next = element.scrollTop + delta;
+        if (next > element.scrollHeight - element.clientHeight + 2) return "wait";
+        writeScroll(element, next);
+        return "done";
+      }
+    }
+    revealCurrent(element, writeScroll);
+    return "done";
+  };
+  const writeScroll = (element, next) => {
+    if (Math.abs(element.scrollTop - next) <= 2) return;
+    writing = true;
+    element.scrollTop = next;
+    writing = false;
+  };
+  const begin = (slots) => {
+    epoch += 1;
+    cancelFrame();
+    disconnectObserver();
+    observed.clear();
+    skipped.clear();
+    applied.clear();
+    pending = slots;
+    held = {};
+    awaiting = true;
+    didInitial = true;
+    shortRetries = 0;
+  };
+  const onBefore = () => {
+    if (traverse) {
+      traverse = false;
+      return;
+    }
+    const slots = capture();
+    begin(slots);
+    awaiting = false;
+    writeHistory(slots);
+  };
+  const onAfter = () => {
+    try {
+      view?.sessionStorage.removeItem(PENDING_KEY);
+    } catch {
+    }
+    if (!pending) return;
+    awaiting = true;
+  };
+  const onPopState = () => {
+    traverse = true;
+    begin(readHistory(view) ?? {});
+  };
+  const onClick = (event) => {
+    const mouse = event;
+    if (mouse.button !== 0 || mouse.metaKey || mouse.ctrlKey || mouse.shiftKey || mouse.altKey) return;
+    const target = mouse.target;
+    if (!(target instanceof Element) || !view) return;
+    const link = target.closest("a[href]");
+    if (!(link instanceof HTMLAnchorElement) || link.target === "_blank") return;
+    if (!link.closest("#desktop-sidebar, [data-zd-mobile-sidebar]")) return;
+    let url;
+    try {
+      url = new URL(link.href, view.location.href);
+    } catch {
+      return;
+    }
+    if (url.origin !== view.location.origin) return;
+    if (url.pathname === view.location.pathname && url.search === view.location.search) return;
+    try {
+      view.sessionStorage.setItem(PENDING_KEY, JSON.stringify({ to: canonicalPath(url.pathname), slots: capture() }));
+    } catch {
+    }
+  };
+  const onUserScroll = (event) => {
+    if (writing) return;
+    const kind = viewportKind(event.target);
+    if (!kind || skipped.has(kind)) return;
+    if (!awaiting && !held[kind]) return;
+    if (event.type === "keydown") {
+      const key = event.key;
+      if (!["ArrowUp", "ArrowDown", "PageUp", "PageDown", "Home", "End", " "].includes(key)) return;
+    }
+    skipped.add(kind);
+    applied.add(kind);
+    delete held[kind];
+    cancelFrame();
+    schedule();
+  };
+  const onScroll = (event) => {
+    if (writing || traverse || awaiting) return;
+    if (!viewportKind(event.target)) return;
+    capture();
+    scheduleHistory();
+  };
+  let historyFrame;
+  const scheduleHistory = () => {
+    if (historyFrame !== void 0) return;
+    historyFrame = requestAnimationFrame(() => {
+      historyFrame = void 0;
+      writeHistory(memory);
+    });
+  };
+  const notify = (root) => {
+    if (root.ownerDocument !== document2) return;
+    if (awaiting) schedule();
+    else if (Object.keys(held).length || !didInitial) schedule();
+  };
+  const consumePendingStorage = () => {
+    if (!view) return;
+    try {
+      const raw = view.sessionStorage.getItem(PENDING_KEY);
+      if (!raw) return;
+      view.sessionStorage.removeItem(PENDING_KEY);
+      const parsed = JSON.parse(raw);
+      if (!isRecord(parsed) || typeof parsed.to !== "string") return;
+      if (canonicalPath(parsed.to) !== canonicalPath(view.location.pathname)) return;
+      const slots = sanitizeSlots(parsed.slots);
+      if (!slots) return;
+      begin(slots);
+    } catch {
+    }
+  };
+  consumePendingStorage();
+  if (!pending) {
+    const stored = readHistory(view);
+    if (stored) begin(stored);
+  }
   document2.addEventListener(BEFORE_NAVIGATE_EVENT, onBefore);
   document2.addEventListener(AFTER_NAVIGATE_EVENT, onAfter);
-  return () => {
+  document2.addEventListener("click", onClick, true);
+  document2.addEventListener("pointerdown", onUserScroll, true);
+  document2.addEventListener("wheel", onUserScroll, true);
+  document2.addEventListener("touchmove", onUserScroll, true);
+  document2.addEventListener("keydown", onUserScroll, true);
+  document2.addEventListener("scroll", onScroll, true);
+  view?.addEventListener("popstate", onPopState);
+  const cleanup = () => {
     document2.removeEventListener(BEFORE_NAVIGATE_EVENT, onBefore);
     document2.removeEventListener(AFTER_NAVIGATE_EVENT, onAfter);
-    cancelPendingRestore();
-    snapshot = void 0;
+    document2.removeEventListener("click", onClick, true);
+    document2.removeEventListener("pointerdown", onUserScroll, true);
+    document2.removeEventListener("wheel", onUserScroll, true);
+    document2.removeEventListener("touchmove", onUserScroll, true);
+    document2.removeEventListener("keydown", onUserScroll, true);
+    document2.removeEventListener("scroll", onScroll, true);
+    view?.removeEventListener("popstate", onPopState);
+    cancelFrame();
+    if (historyFrame !== void 0) cancelAnimationFrame(historyFrame);
+    disconnectObserver();
+    pending = void 0;
+    awaiting = false;
+    if (installedControllers.get(document2)?.cleanup === cleanup) installedControllers.delete(document2);
   };
+  installedControllers.set(document2, { cleanup, notify });
+  return cleanup;
 }
 function ensureSidebarScrollPreserve(options) {
   const resolved = options ?? resolveBrowserOptions();
   if (!resolved || installedControllers.has(resolved.document)) return;
-  installedControllers.set(
-    resolved.document,
-    installSidebarScrollPreserve(resolved)
-  );
+  installSidebarScrollPreserve(resolved);
+}
+function notifySidebarScrollReady(root) {
+  installedControllers.get(root.ownerDocument)?.notify(root);
 }
 function resolveBrowserOptions() {
-  if (typeof document === "undefined" || typeof window === "undefined")
-    return void 0;
+  if (typeof document === "undefined" || typeof window === "undefined") return void 0;
   return {
     document,
     requestAnimationFrame: window.requestAnimationFrame.bind(window),
@@ -57,11 +354,114 @@ function resolveBrowserOptions() {
   };
 }
 function disposeSidebarScrollPreserve(document2) {
-  installedControllers.get(document2)?.();
+  installedControllers.get(document2)?.cleanup();
   installedControllers.delete(document2);
 }
+function findViewport(document2, kind) {
+  if (kind === "desktop") return document2.querySelector("#desktop-sidebar");
+  return document2.querySelector("aside[data-zd-mobile-sidebar] .flex-1.overflow-y-auto");
+}
+function measurable(element) {
+  if (element.clientHeight <= 0 || element.closest("[inert]")) return false;
+  const style = element.ownerDocument.defaultView?.getComputedStyle(element);
+  return !style || style.display !== "none" && style.visibility !== "hidden";
+}
+function isEmptyTree(element) {
+  return element.querySelector("a[href], [data-sidebar-focus-scope]") === null;
+}
+function readContext(element) {
+  const value = element.querySelector("nav")?.getAttribute("data-sidebar-context");
+  return value || void 0;
+}
+function readScope(element) {
+  return element.querySelector("nav")?.getAttribute("data-sidebar-scope") ?? "";
+}
+function readViewKey(element) {
+  const parts = [];
+  for (const node of element.querySelectorAll("[data-sidebar-focus-scope], a[href]")) {
+    const id = node.dataset.sidebarFocusScope || node.getAttribute("href");
+    if (id) parts.push(id);
+  }
+  let hash = 2166136261;
+  const serialized = parts.join("\n");
+  for (let i = 0; i < serialized.length; i++) hash = Math.imul(hash ^ serialized.charCodeAt(i), 16777619);
+  return String(hash >>> 0);
+}
+function readSlot(element) {
+  const anchor = captureAnchor(element);
+  return {
+    scrollTop: element.scrollTop,
+    ...anchor,
+    contextId: readContext(element),
+    scopeId: readScope(element),
+    viewKey: readViewKey(element),
+    contentHeight: element.scrollHeight
+  };
+}
+function captureAnchor(element) {
+  const bounds = element.getBoundingClientRect();
+  for (const row of element.querySelectorAll("[data-sidebar-focus-scope], a[href]")) {
+    const rect = row.getBoundingClientRect();
+    if (rect.height === 0 && rect.top === 0 && rect.bottom === 0) continue;
+    if (rect.bottom > bounds.top && rect.top < bounds.bottom) {
+      const anchorId = row.dataset.sidebarFocusScope || row.getAttribute("href") || void 0;
+      return anchorId ? { anchorId, anchorOffset: rect.top - bounds.top } : {};
+    }
+  }
+  return {};
+}
+function findAnchor(element, id) {
+  for (const node of element.querySelectorAll("[data-sidebar-focus-scope], a[href]")) {
+    if (node.dataset.sidebarFocusScope === id || node.getAttribute("href") === id) return node;
+  }
+  return null;
+}
+function revealCurrent(element, write) {
+  const current = element.querySelector('[aria-current="page"]');
+  if (!current) return;
+  const bounds = element.getBoundingClientRect();
+  const row = current.getBoundingClientRect();
+  if (row.height === 0 && row.top === 0 && row.bottom === 0) return;
+  if (row.top < bounds.top) write(element, element.scrollTop + row.top - bounds.top - 8);
+  else if (row.bottom > bounds.bottom) write(element, element.scrollTop + row.bottom - bounds.bottom + 8);
+}
+function viewportKind(target) {
+  if (!(target instanceof Element)) return void 0;
+  if (target.id === "desktop-sidebar" || target.closest("#desktop-sidebar")) return "desktop";
+  if (target.closest("[data-zd-mobile-sidebar]")) return "mobile";
+  return void 0;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function sanitizeSlots(value) {
+  if (!isRecord(value)) return void 0;
+  const slots = {};
+  for (const kind of VIEWPORTS) {
+    const slot = value[kind];
+    if (!isRecord(slot) || typeof slot.scrollTop !== "number" || !Number.isFinite(slot.scrollTop)) continue;
+    if (typeof slot.viewKey !== "string" || typeof slot.scopeId !== "string" || typeof slot.contentHeight !== "number") continue;
+    const next = {
+      scrollTop: slot.scrollTop,
+      scopeId: slot.scopeId,
+      viewKey: slot.viewKey,
+      contentHeight: slot.contentHeight
+    };
+    if (typeof slot.contextId === "string") next.contextId = slot.contextId;
+    if (typeof slot.anchorId === "string") next.anchorId = slot.anchorId;
+    if (typeof slot.anchorOffset === "number") next.anchorOffset = slot.anchorOffset;
+    slots[kind] = next;
+  }
+  return slots;
+}
+function readHistory(view) {
+  const state = view?.history.state;
+  if (!isRecord(state)) return void 0;
+  return sanitizeSlots(state[HISTORY_KEY]);
+}
 export {
   disposeSidebarScrollPreserve,
   ensureSidebarScrollPreserve,
-  installSidebarScrollPreserve
+  installSidebarScrollPreserve,
+  notifySidebarScrollReady
 };

package/dist/sidebar-utils/index.d.ts

@@ -36,6 +36,14 @@ export interface SidebarDefinition {
      * @default "children"
      */
     initialPathMode?: "children" | "node";
+    /**
+     * Highest tree Broaden can reach. `"editorial"` keeps the current forest,
+     * including the full automatic tree where that is already reachable.
+     * `"configured"` stops at the authored forest. `initialPath` stays the
+     * starting view and the Restore baseline.
+     * @default "editorial"
+     */
+    scopeRoot?: "configured" | "editorial";
     /** Share across sections using the same editorial tree. Locale/version are added by chrome. */
     contextId?: string;
 }

package/dist/sidebar-utils/index.js

@@ -78,11 +78,48 @@ function buildSidebarForSection(docs, lang, categoryMatch, categoryMeta, sidebar
   const tree = buildNavTree(docs, lang, categoryMeta);
   const sectionKey = categoryMatch ?? "default";
   const config = sidebars[sectionKey];
-  if (!config || (Array.isArray(config) ? config.length === 0 : config.items.length === 0)) {
-    return filterByCategory(tree, categoryMatch, explicitCategoryPrefixes);
+  const definition = config && !Array.isArray(config) ? config : void 0;
+  scopeRootOf(definition, sectionKey);
+  const items = Array.isArray(config) ? config : definition?.items;
+  const forest = items?.length ? resolveItems(items, tree, lang) : filterByCategory(tree, categoryMatch, explicitCategoryPrefixes);
+  return followInitialPath(forest, definition, sectionKey).nodes;
+}
+function scopeRootOf(definition, sectionKey) {
+  const value = definition?.scopeRoot;
+  if (value === void 0 || value === "editorial") return "editorial";
+  if (value === "configured") return "configured";
+  throw new Error(`Invalid sidebar scopeRoot for ${sectionKey}`);
+}
+function retainForest(roots, parents) {
+  const ids = /* @__PURE__ */ new Set();
+  const visit = (nodes) => {
+    for (const node of nodes) {
+      if (node.occurrenceId) ids.add(node.occurrenceId);
+      visit(node.children);
+    }
+  };
+  visit(roots);
+  for (const id of Object.keys(parents)) if (!ids.has(id)) delete parents[id];
+  for (const root of roots) if (root.occurrenceId) parents[root.occurrenceId] = null;
+}
+function applyConfiguredCap(items, categoryMatch, prefixes, automatic, state, parents) {
+  if (!items?.length) {
+    if (!categoryMatch) return;
+    state.roots = filterByCategory(automatic, categoryMatch, prefixes);
+    state.nodes = state.roots;
+    retainForest(state.roots, parents);
+    return;
+  }
+  const only = items.length === 1 && typeof items[0] !== "string" ? items[0] : void 0;
+  if (only?.type === "autogenerated") {
+    if (!only.dirName) return;
+    const source = findNode(automatic, only.dirName);
+    state.roots = source ? [source] : [];
+    state.nodes = source?.children ?? [];
+    retainForest(state.roots, parents);
+    return;
   }
-  if (Array.isArray(config)) return resolveItems(config, tree, lang);
-  return followInitialPath(resolveItems(config.items, tree, lang), config, sectionKey).nodes;
+  retainForest(state.roots, parents);
 }
 function followInitialPath(forest, definition, sectionKey) {
   const mode = definition?.initialPathMode;
@@ -108,8 +145,10 @@ function buildSidebarNavigation(...args) {
     }
   }
   const tree = buildTree(docs, lang, meta);
-  const config = sidebars[categoryMatch ?? "default"];
+  const sectionKey = categoryMatch ?? "default";
+  const config = sidebars[sectionKey];
   const definition = config && !Array.isArray(config) ? config : void 0;
+  const scopeRoot = scopeRootOf(definition, sectionKey);
   const items = Array.isArray(config) ? config : definition?.items;
   const parents = {};
   function identify(nodes2, prefix, parent) {
@@ -165,7 +204,13 @@ function buildSidebarNavigation(...args) {
     roots = result.canonical;
     nodes = result.visible;
   }
-  const { nodes: local, target } = followInitialPath(nodes, definition, categoryMatch ?? "default");
+  if (scopeRoot === "configured") {
+    const state = { roots, nodes };
+    applyConfiguredCap(items, categoryMatch, prefixes, automatic, state, parents);
+    roots = state.roots;
+    nodes = state.nodes;
+  }
+  const { nodes: local, target } = followInitialPath(nodes, definition, sectionKey);
   nodes = local;
   const localParentId = definition?.initialPathMode === "node" && target?.occurrenceId ? parents[target.occurrenceId] ?? void 0 : target?.occurrenceId;
   let hash = 2166136261;