@takazudo/zudo-doc 8.1.3 → 9.1.0

package/dist/sidebar-tree-island/branch-preview.js

@@ -0,0 +1,199 @@
+import { computed, signal } from "@takazudo/zfb/zudo-react";
+const TIP_ATTR = "data-sidebar-tip";
+const TIP_DETAIL_ATTR = "data-sidebar-tip-detail";
+const TRIGGER_SELECTOR = `[${TIP_ATTR}]`;
+const FRAME_SELECTOR = "[data-sidebar-focus]";
+const POINTER_SHOW_DELAY_MS = 250;
+const HIDE_DELAY_MS = 120;
+const GAP_PX = 6;
+const VIEWPORT_MARGIN_PX = 8;
+let instanceCount = 0;
+const isHoverPointer = (event) => {
+  const type = event.pointerType;
+  return type === "mouse" || type === "pen";
+};
+const isFocusVisible = (element) => {
+  try {
+    return element.matches(":focus-visible");
+  } catch {
+    return true;
+  }
+};
+const isActionableFrame = (element) => element.matches(FRAME_SELECTOR) && element.getAttribute("aria-disabled") !== "true";
+const previewKey = (element) => isActionableFrame(element) ? element.dataset.sidebarFocusScope || null : null;
+function createBranchPreview(navRef) {
+  const pointerKey = signal(null);
+  const focusKey = signal(null);
+  const active = computed(() => pointerKey.value ?? focusKey.value);
+  let tooltip = null;
+  let owner = null;
+  let showTimer;
+  let hideTimer;
+  const hideTooltip = () => {
+    clearTimeout(showTimer);
+    clearTimeout(hideTimer);
+    if (owner?.getAttribute("aria-describedby") === tooltip?.id) owner?.removeAttribute("aria-describedby");
+    owner = null;
+    if (tooltip) tooltip.hidden = true;
+  };
+  const clear = () => {
+    pointerKey.value = null;
+    focusKey.value = null;
+    hideTooltip();
+  };
+  const place = (trigger, tip) => {
+    tip.style.left = "0px";
+    tip.style.top = "0px";
+    const anchor = trigger.getBoundingClientRect();
+    const box = tip.getBoundingClientRect();
+    const maxLeft = window.innerWidth - box.width - VIEWPORT_MARGIN_PX;
+    const edge = Math.max(anchor.right, navRef.current?.getBoundingClientRect().right ?? anchor.right);
+    let left = edge + GAP_PX;
+    let top = anchor.top + anchor.height / 2 - box.height / 2;
+    if (left > maxLeft) {
+      left = Math.max(VIEWPORT_MARGIN_PX, Math.min(anchor.left + anchor.width / 2 - box.width / 2, maxLeft));
+      top = anchor.bottom + GAP_PX;
+      if (top + box.height > window.innerHeight - VIEWPORT_MARGIN_PX) top = anchor.top - GAP_PX - box.height;
+    }
+    top = Math.max(VIEWPORT_MARGIN_PX, Math.min(top, window.innerHeight - box.height - VIEWPORT_MARGIN_PX));
+    tip.style.left = `${Math.round(left)}px`;
+    tip.style.top = `${Math.round(top)}px`;
+  };
+  const showTooltip = (trigger) => {
+    if (!tooltip) return;
+    clearTimeout(hideTimer);
+    if (owner && owner !== trigger && owner.getAttribute("aria-describedby") === tooltip.id) owner.removeAttribute("aria-describedby");
+    owner = trigger;
+    const title = document.createElement("strong");
+    title.textContent = trigger.getAttribute(TIP_ATTR) ?? "";
+    const parts = [title];
+    const detail = trigger.getAttribute(TIP_DETAIL_ATTR);
+    if (detail) {
+      const line = document.createElement("span");
+      line.textContent = detail;
+      parts.push(line);
+    }
+    tooltip.replaceChildren(...parts);
+    tooltip.hidden = false;
+    trigger.setAttribute("aria-describedby", tooltip.id);
+    place(trigger, tooltip);
+  };
+  const scheduleHide = () => {
+    clearTimeout(showTimer);
+    clearTimeout(hideTimer);
+    hideTimer = setTimeout(hideTooltip, HIDE_DELAY_MS);
+  };
+  const triggerOf = (target) => {
+    const nav = navRef.current;
+    if (!nav || !(target instanceof Element)) return null;
+    const trigger = target.closest(TRIGGER_SELECTOR);
+    return trigger && nav.contains(trigger) ? trigger : null;
+  };
+  const activate = () => {
+    const tip = document.createElement("div");
+    tip.id = `zd-sidebar-tip-${++instanceCount}`;
+    tip.setAttribute("role", "tooltip");
+    tip.setAttribute("data-sidebar-tooltip", "");
+    tip.hidden = true;
+    document.body.append(tip);
+    tooltip = tip;
+    const onPointerOver = (event) => {
+      const trigger = triggerOf(event.target);
+      if (!trigger || !isHoverPointer(event) || trigger.contains(event.relatedTarget)) return;
+      pointerKey.value = previewKey(trigger);
+      clearTimeout(hideTimer);
+      clearTimeout(showTimer);
+      if (owner === trigger && !tip.hidden) return;
+      showTimer = setTimeout(() => showTooltip(trigger), POINTER_SHOW_DELAY_MS);
+    };
+    const onPointerOut = (event) => {
+      const trigger = triggerOf(event.target);
+      const next = event.relatedTarget;
+      if (!trigger || trigger.contains(next)) return;
+      pointerKey.value = null;
+      if (next && tip.contains(next)) return;
+      if (owner === trigger && trigger === document.activeElement && isFocusVisible(trigger)) return;
+      scheduleHide();
+    };
+    const onFocusIn = (event) => {
+      const trigger = triggerOf(event.target);
+      if (!trigger || !isFocusVisible(trigger)) return;
+      focusKey.value = previewKey(trigger);
+      clearTimeout(showTimer);
+      showTooltip(trigger);
+    };
+    const onFocusOut = (event) => {
+      const trigger = triggerOf(event.target);
+      if (!trigger) return;
+      focusKey.value = null;
+      if (owner === trigger) scheduleHide();
+    };
+    const onTipEnter = () => clearTimeout(hideTimer);
+    const onTipLeave = (event) => {
+      const next = event.relatedTarget;
+      if (owner && next && owner.contains(next)) return;
+      if (owner && owner === document.activeElement && isFocusVisible(owner)) return;
+      scheduleHide();
+    };
+    const onKeyDown = (event) => {
+      const key = event;
+      if (key.key !== "Escape" || key.isComposing || tip.hidden) return;
+      const target = key.target;
+      if (target instanceof Element && target !== document.body && !navRef.current?.contains(target) && !tip.contains(target)) {
+        hideTooltip();
+        pointerKey.value = null;
+        return;
+      }
+      key.preventDefault();
+      key.stopPropagation();
+      hideTooltip();
+      pointerKey.value = null;
+    };
+    let scrollFrame = 0;
+    const onScroll = () => {
+      if (tip.hidden || scrollFrame) return;
+      scrollFrame = requestAnimationFrame(() => {
+        scrollFrame = 0;
+        if (tip.hidden) return;
+        if (owner?.isConnected) place(owner, tip);
+        else hideTooltip();
+      });
+    };
+    const drawer = navRef.current ? navRef.current.closest("[data-zd-mobile-sidebar]") : document.querySelector("[data-zd-mobile-sidebar]");
+    const observer = drawer ? new MutationObserver(() => {
+      if (drawer.hasAttribute("inert")) clear();
+    }) : void 0;
+    observer?.observe(drawer, { attributes: true, attributeFilter: ["inert"] });
+    const media = window.matchMedia?.("(min-width: 1024px)");
+    const onBreakpoint = () => clear();
+    media?.addEventListener?.("change", onBreakpoint);
+    document.addEventListener("pointerover", onPointerOver);
+    document.addEventListener("pointerout", onPointerOut);
+    document.addEventListener("focusin", onFocusIn);
+    document.addEventListener("focusout", onFocusOut);
+    document.addEventListener("keydown", onKeyDown, true);
+    document.addEventListener("scroll", onScroll, true);
+    tip.addEventListener("pointerenter", onTipEnter);
+    tip.addEventListener("pointerleave", onTipLeave);
+    return () => {
+      cancelAnimationFrame(scrollFrame);
+      clear();
+      observer?.disconnect();
+      media?.removeEventListener?.("change", onBreakpoint);
+      document.removeEventListener("pointerover", onPointerOver);
+      document.removeEventListener("pointerout", onPointerOut);
+      document.removeEventListener("focusin", onFocusIn);
+      document.removeEventListener("focusout", onFocusOut);
+      document.removeEventListener("keydown", onKeyDown, true);
+      document.removeEventListener("scroll", onScroll, true);
+      tip.remove();
+      tooltip = null;
+    };
+  };
+  return { active, clear, activate };
+}
+export {
+  TIP_ATTR,
+  TIP_DETAIL_ATTR,
+  createBranchPreview
+};

package/dist/sidebar-tree-island/index.js

@@ -10,15 +10,17 @@ import {
 import {
   INDENT,
   BASE_PAD,
+  CONNECTOR_OFFSET,
   connectorLeft,
   ConnectorLines,
   CategoryLinkIcon
 } from "../tree-nav-shared/index.js";
-import { ChevronRight, ChevronLeft, Search } from "../icons/index.js";
+import { ChevronRight, ChevronLeft, Search, FocusFrame, RestoreArrow } from "../icons/index.js";
 import { ThemeToggle } from "../theme-toggle/index.js";
 import { smartBreakToHtml } from "../smart-break/index.js";
 import { AFTER_NAVIGATE_EVENT } from "../transitions/index.js";
 import { useSidebarScope } from "./scope-state.js";
+import { createBranchPreview } from "./branch-preview.js";
 import { filterTree } from "../sidebar-filter/index.js";
 import { findActiveSlug, normalizePath } from "../sidebar-active-slug/index.js";
 import {
@@ -36,6 +38,7 @@ import {
 import { formatMonthDay } from "../format-date/index.js";
 const STORAGE_KEY = "zd-sidebar-open";
 const GROUPED_TRAY_ITEM_DEPTH = 3;
+const TOGGLE_BOX_SIZE = "1.5rem";
 function ToggleChevron({
   isExpanded,
   className
@@ -56,6 +59,9 @@ function padLeft(depth, forCategory) {
     return `calc(${BASE_PAD} + ${forCategory ? "0.15rem" : "0rem"})`;
   return `calc(${depth} * ${INDENT} + 1.25rem + 5px)`;
 }
+function toggleGuideLeft(depth) {
+  return `calc(${padLeft(depth, true)} + ${TOGGLE_BOX_SIZE} / 2 - 0.5px)`;
+}
 function getOpenSet() {
   try {
     const raw = sessionStorage.getItem(STORAGE_KEY);
@@ -207,13 +213,31 @@ function SidebarTree({
   const scope = getScope();
   const activeSlug = useActiveSlug(navigation?.roots ?? nodes, currentSlug, currentPath);
   const query = signal("");
-  const { selected, selectedNodes, broader, labels, canRestore, changeScope, save, navRef, scopeControls } = useSidebarScope({
+  const { selected, selectedNodes, broader, labels, canRestore, changeScope, save, navRef, scopeControls: baseScopeControls } = useSidebarScope({
     nodes,
     navigation,
     activeSlug,
     query,
     locale: localeProp ?? localeLinks?.find((link) => link.active)?.code ?? "en"
   });
+  const branchPreview = createBranchPreview(navRef);
+  const scopeControls = baseScopeControls ? { ...baseScopeControls, preview: branchPreview.active } : void 0;
+  if (navigation) {
+    scope.onActivate(() => {
+      const dispose = branchPreview.activate();
+      const onNavigate = () => branchPreview.clear();
+      document.addEventListener(AFTER_NAVIGATE_EVENT, onNavigate);
+      return () => {
+        document.removeEventListener(AFTER_NAVIGATE_EVENT, onNavigate);
+        dispose();
+      };
+    });
+    scope.effect(() => {
+      void selected.value;
+      void query.value;
+      branchPreview.clear();
+    });
+  }
   const showingRootMenu = signal(false);
   const filterRef = { current: null };
   const filterPlaceholder = signal("Filter...");
@@ -330,15 +354,11 @@ function SidebarTree({
                       type: "button",
                       "data-sidebar-restore": true,
                       "on:click": () => changeScope(null),
-                      title: labels.restore,
                       "aria-label": labels.restore,
+                      "data-sidebar-tip": labels.restoreTip,
                       style: "width:40px;height:40px",
-                      class: "grid place-items-center shrink-0 rounded text-muted hover:text-fg focus-visible:text-fg focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-accent",
-                      children: /* @__PURE__ */ jsxs("svg", { width: "15", height: "15", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", "stroke-width": "2", "aria-hidden": "true", children: [
-                        /* @__PURE__ */ jsx("circle", { cx: "12", cy: "12", r: "10" }),
-                        /* @__PURE__ */ jsx("circle", { cx: "12", cy: "12", r: "6" }),
-                        /* @__PURE__ */ jsx("circle", { cx: "12", cy: "12", r: "2" })
-                      ] })
+                      class: "grid place-items-center shrink-0 rounded text-muted hover:text-accent hover:bg-surface focus-visible:text-accent focus-visible:bg-surface focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-accent",
+                      children: /* @__PURE__ */ jsx(RestoreArrow, { class: "h-[1.0625rem] w-[1.0625rem]" })
                     }
                   ) })
                 ] }) }) }) : null,
@@ -478,6 +498,7 @@ function TrayItem({
   isLast,
   showDate = false,
   depth = 1,
+  guideLeft,
   locale,
   dateFormats
 }) {
@@ -491,7 +512,9 @@ function TrayItem({
       {
         depth,
         isLast,
-        topPad: "var(--spacing-vsp-2xs)"
+        topPad: "var(--spacing-vsp-2xs)",
+        left: guideLeft,
+        width: guideLeft ? `calc(${padLeft(depth, false)} - ${CONNECTOR_OFFSET} - ${guideLeft})` : void 0
       }
     ),
     /* @__PURE__ */ jsxs(
@@ -536,14 +559,16 @@ function TrayItem({
 function ConnectorLinesLive({
   depth,
   isLast,
-  topPad
+  topPad,
+  left,
+  width
 }) {
   return /* @__PURE__ */ jsx(
     Show,
     {
       when: isLast,
-      fallback: () => /* @__PURE__ */ jsx(ConnectorLines, { depth, isLast: false, topPad }),
-      children: () => /* @__PURE__ */ jsx(ConnectorLines, { depth, isLast: true, topPad })
+      fallback: () => /* @__PURE__ */ jsx(ConnectorLines, { depth, isLast: false, topPad, left, width }),
+      children: () => /* @__PURE__ */ jsx(ConnectorLines, { depth, isLast: true, topPad, left, width })
     }
   );
 }
@@ -647,20 +672,34 @@ function TrayGroupNode({
             }
           )
         ] }),
-        /* @__PURE__ */ jsx(Show, { when: expanded, children: () => /* @__PURE__ */ jsx("div", { children: /* @__PURE__ */ jsx(For, { each: items, by: (item) => item.slug, children: (item, index) => /* @__PURE__ */ jsx(
-          TrayItem,
-          {
-            item,
-            currentSlug,
-            isLast: computed(
-              () => index.value === items.value.length - 1
-            ),
-            showDate: true,
-            locale,
-            dateFormats,
-            depth: GROUPED_TRAY_ITEM_DEPTH
-          }
-        ) }) }) })
+        /* @__PURE__ */ jsx(Show, { when: expanded, children: () => /* @__PURE__ */ jsxs("div", { class: "relative", children: [
+          /* @__PURE__ */ jsx(
+            "div",
+            {
+              class: "absolute border-l border-dashed border-muted",
+              style: {
+                left: toggleGuideLeft(1),
+                top: "calc(-1 * var(--spacing-vsp-xs))",
+                height: "var(--spacing-vsp-xs)"
+              }
+            }
+          ),
+          /* @__PURE__ */ jsx(For, { each: items, by: (item) => item.slug, children: (item, index) => /* @__PURE__ */ jsx(
+            TrayItem,
+            {
+              item,
+              currentSlug,
+              isLast: computed(
+                () => index.value === items.value.length - 1
+              ),
+              showDate: true,
+              locale,
+              dateFormats,
+              depth: GROUPED_TRAY_ITEM_DEPTH,
+              guideLeft: toggleGuideLeft(1)
+            }
+          ) })
+        ] }) })
       ]
     }
   );
@@ -753,6 +792,9 @@ function CategoryNode({
     if (scopeControls) open.value = scopeControls.isOpen(occurrenceKey(), scopeControls.defaultOpen(node.value));
   });
   const expanded = computed(() => forceOpen.value || open.value);
+  const focusedRoot = computed(() => !!scopeControls?.isFocusedRoot(node.value.occurrenceId));
+  const previewed = computed(() => !!node.value.occurrenceId && scopeControls?.preview.value === node.value.occurrenceId);
+  const arrived = computed(() => !!node.value.occurrenceId && scopeControls?.arrived.value === node.value.occurrenceId);
   const focusButton = scopeControls ? /* @__PURE__ */ jsx(
     "button",
     {
@@ -760,16 +802,22 @@ function CategoryNode({
       "data-sidebar-focus": true,
       "data-sidebar-focus-scope": computed(() => node.value.occurrenceId ?? ""),
       "on:click": () => scopeControls.focus(node.value),
-      "aria-label": computed(() => `${scopeControls.focusLabel}: ${node.value.label}`),
-      title: computed(() => `${scopeControls.focusLabel}: ${node.value.label}`),
-      class: computed(() => `ml-auto shrink-0 rounded px-hsp-xs py-vsp-2xs ${active.value ? "text-bg hover:bg-bg/10 focus-visible:bg-bg/10" : "text-muted hover:bg-surface hover:text-fg focus-visible:bg-surface focus-visible:text-fg"}`),
-      children: /* @__PURE__ */ jsx("span", { "aria-hidden": "true", children: "\u25CE" })
+      "aria-disabled": computed(() => focusedRoot.value ? "true" : null),
+      tabindex: computed(() => focusedRoot.value ? -1 : null),
+      "aria-label": computed(() => focusedRoot.value ? scopeControls.labels.focused(node.value.label) : scopeControls.labels.focus(node.value.label)),
+      "data-sidebar-tip": computed(() => focusedRoot.value ? scopeControls.labels.focusedTip : scopeControls.labels.focusTip),
+      "data-sidebar-tip-detail": computed(() => node.value.label),
+      class: computed(() => `ml-auto grid shrink-0 place-items-center rounded w-[1.875rem] h-[1.875rem] ${focusedRoot.value ? `cursor-default opacity-50 ${active.value ? "text-bg" : "text-muted"}` : active.value ? "text-bg hover:bg-bg/10 focus-visible:bg-bg/10 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-accent" : "text-muted hover:bg-accent/10 hover:text-accent focus-visible:bg-accent/10 focus-visible:text-accent focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-accent"}`),
+      children: /* @__PURE__ */ jsx(FocusFrame, { class: "h-[1.125rem] w-[1.125rem]" })
     }
   ) : null;
   const paddingLeft = padLeft(depth, true);
   return /* @__PURE__ */ jsxs(
     "div",
     {
+      "data-sidebar-branch": true,
+      "data-sidebar-preview": computed(() => previewed.value ? "" : null),
+      "data-sidebar-arrived": computed(() => arrived.value ? "" : null),
       class: computed(
         () => `${depth === 0 ? "border-t border-muted first:border-t-0" : ""} ${depth >= 1 && !isLast.value ? "relative" : ""}`
       ),
@@ -782,12 +830,13 @@ function CategoryNode({
               "div",
               {
                 class: "absolute border-l border-solid border-muted z-local-1",
+                "data-tree-connector": true,
                 style: { left: connectorLeft(depth), top: "0px", bottom: "0px" }
               }
             )
           }
         ),
-        /* @__PURE__ */ jsxs("div", { class: "relative", children: [
+        /* @__PURE__ */ jsxs("div", { class: "relative", "data-sidebar-row": true, "data-sidebar-current": computed(() => active.value ? "" : null), children: [
           /* @__PURE__ */ jsx(
             ConnectorLinesLive,
             {
@@ -886,7 +935,7 @@ function CategoryNode({
             }
           )
         ] }),
-        /* @__PURE__ */ jsx(Show, { when: expanded, children: () => /* @__PURE__ */ jsx("div", { children: /* @__PURE__ */ jsx(
+        /* @__PURE__ */ jsx(Show, { when: expanded, children: () => /* @__PURE__ */ jsx("div", { "data-sidebar-children": true, children: /* @__PURE__ */ jsx(
           NodeList,
           {
             nodes: computed(() => node.value.children),

package/dist/sidebar-tree-island/scope-state.d.ts

@@ -1,8 +1,21 @@
 import { type ReadonlySignal, type Ref } from "@takazudo/zfb/zudo-react";
 import type { SidebarNavNode, SidebarNavigationContext } from "../sidebar/types.js";
+export interface ScopeLabels {
+    broaden: string;
+    restore: string;
+    restoreTip: string;
+    focus: (label: string) => string;
+    focusTip: string;
+    focused: (label: string) => string;
+    focusedTip: string;
+}
 export interface ScopeControls {
     focus: (node: SidebarNavNode) => void;
-    focusLabel: string;
+    labels: ScopeLabels;
+    /** True when the unfiltered scope is exactly this one occurrence as its single root. */
+    isFocusedRoot: (occurrenceId: string | undefined) => boolean;
+    /** The single root a scope change just arrived at, briefly; null otherwise. */
+    arrived: ReadonlySignal<string | null>;
     /** Effective disclosure: the user's explicit choice, else revealed/scope root, else `baseline`. */
     isOpen: (key: string, baseline: boolean) => boolean;
     /** Records an explicit user disclosure choice. */
@@ -28,11 +41,7 @@ export declare function useSidebarScope({ nodes, navigation, activeSlug, query,
     selected: import("@takazudo/zfb/zudo-react").Signal<string | null>;
     selectedNodes: ReadonlySignal<SidebarNavNode[]>;
     broader: ReadonlySignal<string | null>;
-    labels: {
-        broaden: string;
-        restore: string;
-        focus: string;
-    };
+    labels: ScopeLabels;
     canRestore: ReadonlySignal<boolean>;
     changeScope: (id: string | null) => void;
     save: (broadcast?: boolean) => void;

package/dist/sidebar-tree-island/scope-state.js

@@ -3,6 +3,7 @@ import { broaderSidebarScope, sidebarScopeNodes, reconcileSidebarScope, indexSid
 import { getNoteTrayItems, groupItems } from "../note-tray-model/index.js";
 import { AFTER_NAVIGATE_EVENT } from "../transitions/index.js";
 const STATE_VERSION = 2;
+const ARRIVAL_MS = 700;
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 function useSidebarScope({ nodes, navigation, activeSlug, query, locale }) {
   const selected = signal(null);
@@ -14,13 +15,23 @@ function useSidebarScope({ nodes, navigation, activeSlug, query, locale }) {
   const syncEvent = "zd:sidebar-scope";
   const labels = locale === "ja" ? {
     broaden: "\u30C4\u30EA\u30FC\u3092\u5E83\u3052\u308B",
-    restore: "\u73FE\u5728\u306E\u30DA\u30FC\u30B8\u306E\u30C4\u30EA\u30FC\u306B\u623B\u3059",
-    focus: "\u3053\u306E\u679D\u3060\u3051\u3092\u8868\u793A"
+    restore: "\u73FE\u5728\u306E\u30DA\u30FC\u30B8\u306E\u30B5\u30A4\u30C9\u30D0\u30FC\u306B\u623B\u3059",
+    restoreTip: "\u73FE\u5728\u306E\u30DA\u30FC\u30B8\u306E\u30B5\u30A4\u30C9\u30D0\u30FC\u306B\u623B\u3059",
+    focus: (label) => `\u30B5\u30A4\u30C9\u30D0\u30FC\u306B\u300C${label}\u300D\u3060\u3051\u3092\u8868\u793A`,
+    focusTip: "\u3053\u3053\u3060\u3051\u3092\u8868\u793A",
+    focused: (label) => `\u3059\u3067\u306B\u300C${label}\u300D\u3060\u3051\u3092\u8868\u793A\u3057\u3066\u3044\u307E\u3059`,
+    focusedTip: "\u3059\u3067\u306B\u3053\u3053\u3060\u3051\u3092\u8868\u793A\u3057\u3066\u3044\u307E\u3059"
   } : {
     broaden: "Broaden tree",
-    restore: "Restore current page\u2019s local tree",
-    focus: "Show only this branch"
+    restore: "Restore current page\u2019s sidebar",
+    restoreTip: "Restore this page\u2019s sidebar",
+    focus: (label) => `Focus sidebar on ${label}`,
+    focusTip: "Focus sidebar here",
+    focused: (label) => `Sidebar is already focused on ${label}`,
+    focusedTip: "Already focused here"
   };
+  const arrived = signal(null);
+  let arrivalTimer;
   const selectedNodes = computed(() => navigation ? sidebarScopeNodes(navigation, nodes, selected.value) : nodes);
   const broader = computed(() => navigation ? broaderSidebarScope(navigation, nodes, selected.value) : null);
   const occurrenceIndex = navigation ? indexSidebarOccurrences(navigation.roots) : /* @__PURE__ */ new Map();
@@ -87,17 +98,23 @@ function useSidebarScope({ nodes, navigation, activeSlug, query, locale }) {
       revealed.value = /* @__PURE__ */ new Set([...revealed.value, ...withAncestors(previous), ...withAncestors(id)]);
     }
     save();
+    clearTimeout(arrivalTimer);
+    arrived.value = id === null ? null : scopeRoot.value ?? null;
+    if (arrived.value !== null) arrivalTimer = setTimeout(() => {
+      arrived.value = null;
+    }, ARRIVAL_MS);
     queueMicrotask(() => {
       const nav = navRef.current;
-      const controls = [...nav?.querySelectorAll("[data-sidebar-focus]") ?? []];
+      const controls = [...nav?.querySelectorAll('[data-sidebar-focus]:not([aria-disabled="true"])') ?? []];
       const activeBranch = controls.reverse().find((button) => {
         const node = occurrenceIndex.get(button.dataset.sidebarFocusScope ?? "");
         const contains = (n) => n.slug === activeSlug.value || n.children.some(contains);
         return node && contains(node);
       });
-      const rootLink = id && id !== SIDEBAR_FOREST_SCOPE && broader.value !== null ? nav?.querySelector("[data-sidebar-tree-root] a") : null;
+      const rootAction = nav?.querySelector("[data-sidebar-tree-root] a") ?? nav?.querySelector("[data-sidebar-tree-root] button[aria-expanded]");
+      const rootLink = id && id !== SIDEBAR_FOREST_SCOPE && broader.value !== null ? rootAction : null;
       const currentLink = nav?.querySelector('[aria-current="page"]');
-      const control = (id === null ? currentLink : rootLink) ?? nav?.querySelector("[data-sidebar-broaden]") ?? activeBranch ?? currentLink ?? nav?.querySelector("[data-sidebar-focus], [data-sidebar-tree-root] a, input");
+      const control = (id === null ? currentLink : rootLink) ?? nav?.querySelector("[data-sidebar-broaden]") ?? activeBranch ?? currentLink ?? rootAction ?? nav?.querySelector('[data-sidebar-focus]:not([aria-disabled="true"]), [data-sidebar-tree-root] a, [data-sidebar-tree-root] button[aria-expanded], input');
       const target = control;
       let viewport = nav?.parentElement;
       while (viewport && viewport !== document.body && viewport.scrollHeight <= viewport.clientHeight) viewport = viewport.parentElement;
@@ -110,11 +127,14 @@ function useSidebarScope({ nodes, navigation, activeSlug, query, locale }) {
       control?.focus({ preventScroll: true });
     });
   };
+  const isFocusedRoot = (occurrenceId) => occurrenceId !== void 0 && scopeRoot.value === occurrenceId;
   const scopeControls = navigation ? {
     focus: (node) => {
-      if (node.occurrenceId) changeScope(node.occurrenceId);
+      if (node.occurrenceId && !isFocusedRoot(node.occurrenceId)) changeScope(node.occurrenceId);
     },
-    focusLabel: labels.focus,
+    labels,
+    isFocusedRoot,
+    arrived,
     defaultOpen,
     defaultGroupOpen,
     isOpen: (key, baseline) => expansion.value[key] ?? automaticOpen(key, baseline),
@@ -161,6 +181,7 @@ function useSidebarScope({ nodes, navigation, activeSlug, query, locale }) {
     document.addEventListener(syncEvent, sync);
     document.addEventListener(AFTER_NAVIGATE_EVENT, navigate);
     return () => {
+      clearTimeout(arrivalTimer);
       document.removeEventListener(syncEvent, sync);
       document.removeEventListener(AFTER_NAVIGATE_EVENT, navigate);
     };

package/dist/sidebar-utils/index.js

@@ -65,14 +65,17 @@ function resolveItem(item, tree, lang) {
     }
   }
 }
+function matchesCategory(slug, match) {
+  return slug === match || slug.startsWith(match + "/");
+}
 function filterByCategory(tree, categoryMatch, explicitPrefixes) {
   if (!categoryMatch) return tree;
   if (categoryMatch === "!") {
     return tree.filter(
-      (node) => !explicitPrefixes.some((prefix) => node.slug.startsWith(prefix))
+      (node) => !explicitPrefixes.some((prefix) => matchesCategory(node.slug, prefix))
     );
   }
-  return tree.filter((node) => node.slug.startsWith(categoryMatch));
+  return tree.filter((node) => matchesCategory(node.slug, categoryMatch));
 }
 function buildSidebarForSection(docs, lang, categoryMatch, categoryMeta, sidebars, buildNavTree, explicitCategoryPrefixes) {
   const tree = buildNavTree(docs, lang, categoryMeta);

package/dist/theme/theme-pack-provider.d.ts

@@ -30,7 +30,8 @@ export declare const THEME_PACK_LOAD_WATCHDOG_MS = 2000;
  */
 export declare const THEME_PACK_LATCH_CSS = "html[data-zd-theme-pack-loading] body{visibility:hidden}";
 export interface ThemePackProviderProps {
-    /** The build-configured pack slug (`settings.themePack`, default `"default"`). */
+    /** The build-configured pack slug (`settings.themePack`, normalized by
+     *  `resolveConfiguredThemePack` — `"graphite"` when omitted). */
     configuredSlug: string;
     /**
      * Ordered `{ slug → meta.version }` map of the ENABLED packs — build with
@@ -55,7 +56,8 @@ export declare function themePackVersionMap(registry: ThemePackRegistry): Record
  * `packageOwnedRoutes: false` host that builds its own payload).
  */
 export declare function resolveThemePackSsrSlug(registry: ThemePackRegistry | null, settings: {
-    themePack?: string;
+    themePack?: string | null;
+    colorMode?: unknown;
 }): string | undefined;
 /**
  * Bootstrap script for the theme-pack layer. Values are inlined as JSON

package/dist/theme/theme-pack-provider.js

@@ -11,6 +11,7 @@ import {
   THEME_PACK_STORAGE_KEY,
   buildPackCssUrl
 } from "../theme-pack-switcher/theme-pack-sync.js";
+import { resolveConfiguredThemePack } from "../theme-packs-registry/configured-theme-pack.js";
 const THEME_PACK_LOADING_ATTR = "data-zd-theme-pack-loading";
 const THEME_PACK_LOAD_WATCHDOG_MS = 2e3;
 const THEME_PACK_LATCH_CSS = `html[${THEME_PACK_LOADING_ATTR}] body{visibility:hidden}`;
@@ -23,7 +24,7 @@ function themePackVersionMap(registry) {
 }
 function resolveThemePackSsrSlug(registry, settings) {
   if (registry === null) return void 0;
-  return settings.themePack ?? DEFAULT_THEME_PACK_SLUG;
+  return resolveConfiguredThemePack(settings);
 }
 function buildThemePackBootstrap(configuredSlug, enabled, base) {
   const configured = JSON.stringify(configuredSlug);

package/dist/theme-cli/config-io.js

@@ -1,6 +1,9 @@
 import fs from "fs-extra";
 import path from "node:path";
-import { DEFAULT_THEME_PACK_SLUG } from "../theme-packs-registry/index.js";
+import {
+  CONFIGURED_DEFAULT_THEME_PACK_SLUG,
+  DEFAULT_THEME_PACK_SLUG
+} from "../theme-packs-registry/index.js";
 import {
   ConfigSyntaxError,
   findMatchingBrace,
@@ -16,7 +19,10 @@ function resolveZfbConfigPath(cwd) {
 }
 async function detectActiveThemePack(cwd) {
   const configPath = resolveZfbConfigPath(cwd);
-  const fallback = { slug: DEFAULT_THEME_PACK_SLUG, detected: false };
+  const fallback = {
+    slug: CONFIGURED_DEFAULT_THEME_PACK_SLUG,
+    detected: false
+  };
   if (!await fs.pathExists(configPath)) return fallback;
   let source;
   try {
@@ -33,7 +39,24 @@ async function detectActiveThemePack(cwd) {
     const members = splitTopLevelMembers(source, braceOpenIdx + 1, braceCloseIdx);
     if (members.some((m) => m.isSpread)) return fallback;
     const themePackMember = members.find((m) => m.key === "themePack");
-    if (!themePackMember) return { slug: DEFAULT_THEME_PACK_SLUG, detected: true };
+    if (!themePackMember) {
+      const valueText = (key) => {
+        const member = members.find((m) => m.key === key);
+        if (!member) return void 0;
+        if (member.valueStart === null || member.valueEnd === null) return null;
+        return source.slice(member.valueStart, member.valueEnd).trim();
+      };
+      const colorSchemes = valueText("colorSchemes");
+      const colorMode = valueText("colorMode");
+      if (colorSchemes === null || colorMode === null) return fallback;
+      const customSchemes = colorSchemes !== void 0 && colorSchemes !== "undefined" && colorSchemes !== "null" && colorSchemes !== "defaultColorSchemes";
+      if (customSchemes || colorMode === "false") {
+        return { slug: DEFAULT_THEME_PACK_SLUG, detected: true };
+      }
+      const colorModeKnownNotFalse = colorMode === void 0 || colorMode === "undefined" || colorMode === "true" || colorMode.startsWith("{");
+      if (!colorModeKnownNotFalse) return fallback;
+      return { slug: CONFIGURED_DEFAULT_THEME_PACK_SLUG, detected: true };
+    }
     if (themePackMember.valueStart === null || themePackMember.valueEnd === null || !isPlainStringLiteralSpan(source, themePackMember.valueStart, themePackMember.valueEnd)) {
       return fallback;
     }