@takazudo/zudo-doc 6.1.1 → 7.0.0

package/dist/theme-toggle/index.js

@@ -5,7 +5,6 @@ import { hydrationPending } from "../hydration-pending.js";
 import { AFTER_NAVIGATE_EVENT } from "../transitions/index.js";
 import {
   applyThemePreference,
-  readColorSchemeFromDom,
   readThemePreference,
   subscribeColorSchemeChanged,
   subscribeThemePreferenceChanged
@@ -43,11 +42,31 @@ const englishLabels = {
   system: "System",
   systemHelper: "Follows device \xB7 currently {mode}"
 };
-function AppearanceMenu({ id, labels, preference, resolved, activeIndex, triggerRef, rootRef, close, select, move }) {
+const MENU_WIDTH_REM = 14.75;
+const VIEWPORT_GAP = 8;
+function viewportSize() {
+  const root = document.documentElement;
+  return {
+    width: Math.min(window.innerWidth, root.clientWidth || window.innerWidth),
+    height: Math.min(window.innerHeight, root.clientHeight || window.innerHeight)
+  };
+}
+function AppearanceMenu({ id, labels, preference, deviceMode, activeIndex, triggerRef, rootRef, close, select, move }) {
   const scope = getScope();
   const menuRef = { current: null };
   const itemRefs = preferences.map(() => ({ current: null }));
-  const placement = signal({ visibility: "hidden", left: "0px", top: "0px", right: "auto", bottom: "auto", margin: "0", width: "260px", "max-height": "none" });
+  const systemDescriptionId = `${id}-system-desc`;
+  const placement = signal({ visibility: "hidden", left: "0px", top: "0px", right: "auto", bottom: "auto", margin: "0", width: `${MENU_WIDTH_REM}rem`, "max-height": "none", overflow: "visible" });
+  const focusItem = (index) => {
+    const item = itemRefs[index]?.current;
+    const menu = menuRef.current;
+    if (!item) return;
+    item.focus({ preventScroll: true });
+    if (!menu || menu.scrollHeight <= menu.clientHeight) return;
+    const bottom = item.offsetTop + item.offsetHeight;
+    if (item.offsetTop < menu.scrollTop) menu.scrollTop = item.offsetTop;
+    else if (bottom > menu.scrollTop + menu.clientHeight) menu.scrollTop = bottom - menu.clientHeight;
+  };
   scope.onActivate(() => {
     const menu = menuRef.current;
     if (!menu) return;
@@ -55,35 +74,58 @@ function AppearanceMenu({ id, labels, preference, resolved, activeIndex, trigger
     const position = () => {
       const rect = triggerRef.current?.getBoundingClientRect();
       if (!rect) return;
-      const gap = 8;
-      const width = Math.max(0, Math.min(260, window.innerWidth - gap * 2));
-      const desiredHeight = menu.scrollHeight || 280;
-      const roomBelow = window.innerHeight - rect.bottom - gap * 2;
+      const gap = VIEWPORT_GAP;
+      const viewport = viewportSize();
+      const rootFontSize = parseFloat(getComputedStyle(document.documentElement).fontSize) || 16;
+      const width = Math.max(0, Math.min(MENU_WIDTH_REM * rootFontSize, viewport.width - gap * 2));
+      menu.style.width = `${width}px`;
+      const height = menu.scrollHeight + menu.offsetHeight - menu.clientHeight;
+      const roomBelow = viewport.height - rect.bottom - gap * 2;
       const roomAbove = rect.top - gap * 2;
-      const above = roomBelow < desiredHeight && roomAbove > roomBelow;
-      const maxHeight = Math.max(80, Math.min(desiredHeight, above ? roomAbove : roomBelow));
-      const left = Math.max(gap, Math.min(rect.right - width, window.innerWidth - width - gap));
-      const top = above ? Math.max(gap, rect.top - gap - maxHeight) : rect.bottom + gap;
-      placement.value = { visibility: "visible", left: `${left}px`, top: `${top}px`, right: "auto", bottom: "auto", margin: "0", width: `${width}px`, "max-height": `${maxHeight}px` };
+      const above = height > roomBelow && roomAbove > roomBelow;
+      const room = above ? roomAbove : roomBelow;
+      const fits = height <= viewport.height - gap * 2;
+      const shownHeight = fits ? height : viewport.height - gap * 2;
+      const preferredTop = above ? rect.top - gap - Math.min(height, room) : rect.bottom + gap;
+      const top = Math.max(gap, Math.min(preferredTop, viewport.height - gap - shownHeight));
+      const left = Math.max(gap, Math.min(rect.right - width, viewport.width - width - gap));
+      placement.value = {
+        visibility: "visible",
+        left: `${left}px`,
+        top: `${top}px`,
+        right: "auto",
+        bottom: "auto",
+        margin: "0",
+        width: `${width}px`,
+        // Scrolling is only a last resort when the natural menu is taller than the viewport.
+        "max-height": fits ? "none" : `${shownHeight}px`,
+        overflow: fits ? "visible" : "auto"
+      };
     };
     const onPointerDown = (event) => {
       if (!rootRef.current?.contains(event.target) && !menu.contains(event.target)) close();
     };
     const onNavigate = () => close();
+    const onScroll = (event) => {
+      if (event.target !== menu) position();
+    };
     position();
     const focusFrame = requestAnimationFrame(() => {
-      if (!scope.abortSignal.aborted) itemRefs[activeIndex.value]?.current?.focus();
+      if (!scope.abortSignal.aborted) focusItem(activeIndex.value);
     });
+    const resizeObserver = typeof ResizeObserver === "undefined" ? null : new ResizeObserver(() => position());
+    resizeObserver?.observe(menu);
     document.addEventListener("pointerdown", onPointerDown);
     window.addEventListener("resize", position);
-    window.addEventListener("scroll", position, true);
+    window.addEventListener("scroll", onScroll, true);
     document.addEventListener(AFTER_NAVIGATE_EVENT, onNavigate);
     return () => {
       cancelAnimationFrame(focusFrame);
+      resizeObserver?.disconnect();
       if (menu.hidePopover && menu.matches(":popover-open")) menu.hidePopover();
       document.removeEventListener("pointerdown", onPointerDown);
       window.removeEventListener("resize", position);
-      window.removeEventListener("scroll", position, true);
+      window.removeEventListener("scroll", onScroll, true);
       document.removeEventListener(AFTER_NAVIGATE_EVENT, onNavigate);
     };
   });
@@ -100,7 +142,7 @@ function AppearanceMenu({ id, labels, preference, resolved, activeIndex, trigger
       keyboard.preventDefault();
       const next = keyboard.key === "Home" ? 0 : keyboard.key === "End" ? 2 : activeIndex.value + (keyboard.key === "ArrowDown" ? 1 : -1);
       move(next);
-      itemRefs[(next + preferences.length) % preferences.length]?.current?.focus();
+      focusItem((next + preferences.length) % preferences.length);
     }
   };
   return /* @__PURE__ */ jsxs(
@@ -111,29 +153,31 @@ function AppearanceMenu({ id, labels, preference, resolved, activeIndex, trigger
       role: "menu",
       "aria-label": labels.appearance,
       "on:keydown": onMenuKeyDown,
-      class: "fixed z-tooltip overflow-y-auto rounded-lg border border-muted bg-surface p-hsp-xs text-fg shadow-lg",
+      class: "fixed z-tooltip flex flex-col gap-hsp-2xs rounded-lg border border-muted bg-surface p-hsp-xs text-fg shadow-lg",
       style: placement,
       popover: "manual",
       children: [
-        /* @__PURE__ */ jsx("div", { class: "px-hsp-sm py-vsp-xs text-small font-semibold", "aria-hidden": "true", children: labels.appearance }),
         preferences.map((option, index) => /* @__PURE__ */ jsxs(
           "button",
           {
             ref: itemRefs[index],
             type: "button",
             role: "menuitemradio",
+            tabindex: -1,
             "aria-checked": computed(() => preference.value === option),
+            "aria-describedby": option === "system" ? systemDescriptionId : void 0,
             "on:focus": () => move(index),
             "on:click": () => select(option),
-            class: computed(() => `flex min-h-[44px] w-full items-center gap-hsp-sm rounded px-hsp-sm text-left text-small ${preference.value === option ? "bg-accent/10" : ""} hover:bg-accent/10 focus-visible:bg-accent/10 focus-visible:outline-2 focus-visible:outline-accent`),
+            class: computed(() => `flex min-h-[44px] w-full items-center gap-hsp-sm rounded px-hsp-sm text-left text-small ${preference.value === option ? "bg-accent/10" : "hover:bg-accent/5"} focus-visible:outline-2 focus-visible:outline-accent`),
             children: [
               /* @__PURE__ */ jsx(PreferenceIcon, { preference: option }),
-              /* @__PURE__ */ jsx("span", { class: "flex-1", children: labels[option] }),
-              /* @__PURE__ */ jsx("span", { "aria-hidden": "true", class: "text-accent", children: computed(() => preference.value === option ? "\u2713" : "") })
+              /* @__PURE__ */ jsx("span", { class: "min-w-0 flex-1 break-words", children: labels[option] }),
+              option === "system" ? /* @__PURE__ */ jsx("span", { "aria-hidden": "true", "data-zd-device-mode": "", class: "shrink-0 text-caption text-muted", children: computed(() => labels[deviceMode.value]) }) : null,
+              /* @__PURE__ */ jsx("span", { "aria-hidden": "true", class: "w-[1.25rem] shrink-0 text-center text-accent", children: computed(() => preference.value === option ? "\u2713" : "") })
             ]
           }
         )),
-        /* @__PURE__ */ jsx("div", { class: "px-hsp-sm py-vsp-xs text-small text-muted", children: computed(() => labels.systemHelper.replace("{mode}", labels[resolved.value])) })
+        /* @__PURE__ */ jsx("span", { id: systemDescriptionId, hidden: true, children: computed(() => labels.systemHelper.replace("{mode}", labels[deviceMode.value])) })
       ]
     }
   );
@@ -144,7 +188,7 @@ function ThemeToggle({ defaultMode = "dark", respectPrefersColorScheme = true, l
   const rootRef = { current: null };
   const triggerRef = { current: null };
   const preference = signal(respectPrefersColorScheme ? "system" : defaultMode);
-  const resolved = signal(defaultMode);
+  const deviceMode = signal(defaultMode);
   const open = signal(false);
   const activeIndex = signal(0);
   let menuId = "";
@@ -154,9 +198,14 @@ function ThemeToggle({ defaultMode = "dark", respectPrefersColorScheme = true, l
   scope.onActivate(() => {
     const sync = () => {
       preference.value = readThemePreference(defaultMode, respectPrefersColorScheme);
-      resolved.value = readColorSchemeFromDom(defaultMode);
     };
     sync();
+    const deviceQuery = window.matchMedia?.("(prefers-color-scheme: dark)");
+    const syncDevice = () => {
+      deviceMode.value = deviceQuery?.matches ? "dark" : "light";
+    };
+    if (deviceQuery) syncDevice();
+    deviceQuery?.addEventListener?.("change", syncDevice);
     const unsubscribePreference = subscribeThemePreferenceChanged(() => {
       sync();
       open.value = false;
@@ -165,19 +214,19 @@ function ThemeToggle({ defaultMode = "dark", respectPrefersColorScheme = true, l
     return () => {
       unsubscribePreference();
       unsubscribeScheme();
+      deviceQuery?.removeEventListener?.("change", syncDevice);
     };
   });
   const close = (restoreFocus = false) => {
     open.value = false;
     if (restoreFocus) requestAnimationFrame(() => {
-      if (!scope.abortSignal.aborted && !open.value) triggerRef.current?.focus();
+      if (!scope.abortSignal.aborted && !open.value) triggerRef.current?.focus({ preventScroll: true });
     });
   };
   const select = (next) => {
     close(true);
     applyThemePreference(next);
     preference.value = next;
-    resolved.value = readColorSchemeFromDom(defaultMode);
   };
   const move = (index) => {
     activeIndex.value = (index + preferences.length) % preferences.length;
@@ -228,7 +277,7 @@ function ThemeToggle({ defaultMode = "dark", respectPrefersColorScheme = true, l
         ]
       }
     ),
-    /* @__PURE__ */ jsx(Show, { when: open, children: () => /* @__PURE__ */ jsx(AppearanceMenu, { id: menuId, labels, preference, resolved, activeIndex, triggerRef, rootRef, close, select, move }) })
+    /* @__PURE__ */ jsx(Show, { when: open, children: () => /* @__PURE__ */ jsx(AppearanceMenu, { id: menuId, labels, preference, deviceMode, activeIndex, triggerRef, rootRef, close, select, move }) })
   ] });
 }
 ThemeToggle.displayName = "ThemeToggle";

package/dist/transitions/chrome-transition-bootstrap.d.ts

@@ -0,0 +1,2 @@
+/** Visual snapshot policy only; persistence and sidebar state keep their owners. */
+export declare function buildChromeTransitionBootstrap(): string;

package/dist/transitions/chrome-transition-bootstrap.js

@@ -0,0 +1,23 @@
+import { BEFORE_SWAP_EVENT } from "./page-events.js";
+function buildChromeTransitionBootstrap() {
+  return `(function(){
+if(document.__zdChromeTransitionPolicy)return;
+document.__zdChromeTransitionPolicy=true;
+function identity(doc){
+var sidebar=doc.getElementById("desktop-sidebar");
+var context=sidebar&&sidebar.querySelector("[data-sidebar-context]");
+var band=doc.querySelector("[data-zd-nav-section]");
+return {section:band&&band.getAttribute("data-zd-nav-section"),context:band&&!band.hasAttribute("data-zd-nosidebar")&&context&&context.getAttribute("data-sidebar-context")};
+}
+document.addEventListener(${JSON.stringify(BEFORE_SWAP_EVENT)},function(ev){
+var incoming=ev.newDocument;
+if(!incoming||incoming.nodeType!==9)return;
+var from=identity(document),to=identity(incoming);
+var stationary=!!from.section&&!!from.context&&from.section===to.section&&from.context===to.context;
+incoming.documentElement.setAttribute("data-zd-sidebar-transition",stationary?"stationary":"changing");
+});
+})();`;
+}
+export {
+  buildChromeTransitionBootstrap
+};

package/dist/transitions/page-events.d.ts

@@ -7,6 +7,10 @@
  * the v2 vocabulary.
  */
 export declare const BEFORE_NAVIGATE_EVENT = "zfb:before-preparation";
+/** Fetch/preparation finished, before the native old snapshot is captured. */
+export declare const AFTER_PREPARATION_EVENT = "zfb:after-preparation";
+/** A navigation was abandoned before committing the destination DOM. */
+export declare const NAVIGATION_ABORTED_EVENT = "zfb:navigation-aborted";
 /**
  * Event name fired after a SPA body swap. Today resolves to
  * `"zfb:after-swap"`. The initial page load uses `zfb:page-load` instead;

package/dist/transitions/page-events.js

@@ -1,4 +1,6 @@
 const BEFORE_NAVIGATE_EVENT = "zfb:before-preparation";
+const AFTER_PREPARATION_EVENT = "zfb:after-preparation";
+const NAVIGATION_ABORTED_EVENT = "zfb:navigation-aborted";
 const AFTER_NAVIGATE_EVENT = "zfb:after-swap";
 const BEFORE_SWAP_EVENT = "zfb:before-swap";
 function onBeforeNavigate(handler) {
@@ -15,8 +17,10 @@ function onAfterNavigate(handler) {
 }
 export {
   AFTER_NAVIGATE_EVENT,
+  AFTER_PREPARATION_EVENT,
   BEFORE_NAVIGATE_EVENT,
   BEFORE_SWAP_EVENT,
+  NAVIGATION_ABORTED_EVENT,
   onAfterNavigate,
   onBeforeNavigate
 };

package/dist/wind.json

@@ -175,6 +175,7 @@
     "hover:bg-[color-mix(in_srgb,var(--color-surface)_80%,var(--color-fg)_20%)]",
     "hover:bg-accent-hover",
     "hover:bg-accent/10",
+    "hover:bg-accent/5",
     "hover:bg-bg/10",
     "hover:bg-danger/10",
     "hover:bg-surface",
@@ -457,6 +458,7 @@
     "w-[0.625rem]",
     "w-[0.875rem]",
     "w-[1.125rem]",
+    "w-[1.25rem]",
     "w-[1.575rem]",
     "w-[1.5rem]",
     "w-[1.75rem]",

package/eject/page-loading/page-loading-overlay.tsx

@@ -1,5 +1,5 @@
 /** @jsxRuntime automatic */
-// Server-rendered, zero-hydration full-page loading overlay.
+// Server-rendered, zero-hydration content loading overlay.
 //
 // Renders the overlay and its bootstrap into the document:
 //
@@ -15,12 +15,13 @@
 //      `zfb:after-swap` (AFTER_NAVIGATE_EVENT); see
 //      `transitions/page-events.ts` for rationale.
 //
-// Its CSS stays in the host's global stylesheet, and the component is not
+// Its package CSS is imported by the host, and the component is not
 // hydrated: the static script owns its navigation listeners.
 
 import {
   AFTER_NAVIGATE_EVENT,
   BEFORE_NAVIGATE_EVENT,
+  NAVIGATION_ABORTED_EVENT,
 } from "../transitions/page-events.js";
 
 /** Default `id` for the overlay element. Stable so test rigs can target it. */
@@ -52,7 +53,7 @@ export function buildPageLoadingOverlayBootstrap(overlayId: string): string {
   const after = JSON.stringify(AFTER_NAVIGATE_EVENT);
   return `(function(){
 var id=${id};
-function show(){var el=document.getElementById(id);if(!el)return;el.setAttribute("data-visible","");el.setAttribute("aria-hidden","false");}
+function show(){var el=document.getElementById(id);if(!el)return;var content=document.querySelector(".zd-sidebar-content-wrapper");var header=document.querySelector("body > header");el.style.left=Math.max(0,content?content.getBoundingClientRect().left:0)+"px";el.style.top=Math.max(0,header?header.getBoundingClientRect().bottom:0)+"px";el.setAttribute("data-visible","");el.setAttribute("aria-hidden","false");}
 function hide(){var el=document.getElementById(id);if(!el)return;el.removeAttribute("data-visible");el.setAttribute("aria-hidden","true");}
 function setPending(ev){document.querySelectorAll("[data-zd-nav-pending]").forEach(function(el){el.removeAttribute("data-zd-nav-pending");});var src=ev&&ev.sourceElement;if(src&&src instanceof Element)src.setAttribute("data-zd-nav-pending","");}
 function clearPending(){document.querySelectorAll("[data-zd-nav-pending]").forEach(function(el){el.removeAttribute("data-zd-nav-pending");});}
@@ -60,17 +61,18 @@ document.addEventListener(${before},show);
 document.addEventListener(${after},hide);
 document.addEventListener(${before},setPending);
 document.addEventListener(${after},clearPending);
+document.addEventListener(${JSON.stringify(NAVIGATION_ABORTED_EVENT)},function(){hide();clearPending();});
 })();`;
 }
 
 /**
- * Full-page loading overlay shown during view-transition navigations.
+ * Content loading overlay shown while a dynamic navigation is pending.
  *
  * Mount this once per layout (typically inside `DocLayoutWithDefaults`'s
  * `bodyEnd` slot, alongside the existing body-end providers). It is
  * server-rendered and self-wires its visibility — no hydration needed.
  *
- * CSS lives in the host project's `src/styles/global.css` (`.page-loading-overlay`,
+ * CSS ships in `@takazudo/zudo-doc/page-loading.css` (`.page-loading-overlay`,
  * `.page-loading-spinner`, `[data-zd-nav-pending]` rules) rather than in an
  * inline `<style>` block here — a `<style>` inside `<body>` violates HTML5
  * element-permitted-content and fails html-validate (same fix applied to the

package/eject/sidebar-toggle-island/index.tsx

@@ -9,6 +9,7 @@ import { computed, getScope, signal, type Ref } from "@takazudo/zfb/zudo-react";
 // collapse into duplicate import statements in an ejected copy.
 import { AFTER_NAVIGATE_EVENT, ensureNestedIslandPropsRefresh } from "../transitions/index.js";
 import { SidebarTree } from "../sidebar-tree-island/index.js";
+import { notifySidebarScrollReady } from "../sidebar-tree-island/sidebar-scroll-preserve.js";
 import type { ThemeToggleLabels } from "../theme-toggle/index.js";
 import type { SidebarNavNode, SidebarRootMenuItem, SidebarLocaleLink, SidebarNavigationContext } from "../sidebar/types.js";
 import type { ResolvedDateFormats } from "../settings.js";
@@ -93,6 +94,10 @@ export function SidebarToggle({
     document.body.style.overflow = isOpen ? "hidden" : "";
     if (isOpen) closeIconRef.current?.style.removeProperty("display");
     else closeIconRef.current?.style.setProperty("display", "none");
+    if (isOpen) {
+      const scroller = document.querySelector("aside[data-zd-mobile-sidebar] .flex-1.overflow-y-auto");
+      if (scroller) notifySidebarScrollReady(scroller);
+    }
     if (isOpen) menuIconRef.current?.style.setProperty("display", "none");
     else menuIconRef.current?.style.removeProperty("display");
     return () => {

package/eject/sidebar-tree-island/index.tsx

@@ -34,7 +34,7 @@ import {
   CURRENT_PATH_DATASET_KEY,
   readCurrentPath,
 } from "../current-path/index.js";
-import { ensureSidebarScrollPreserve } from "./sidebar-scroll-preserve.js";
+import { ensureSidebarScrollPreserve, notifySidebarScrollReady } from "./sidebar-scroll-preserve.js";
 import {
   formatYearLabel,
   formatYearMonthLabel,
@@ -309,6 +309,15 @@ export function SidebarTree({
   const filteredNodes = computed(() =>
     query.value ? filterTree(selectedNodes.value, query.value) : selectedNodes.value,
   );
+  // Notify after scope, filter, and disclosure have committed. The controller
+  // restores only while a navigation is waiting, so later edits do not scroll.
+  scope.effect(() => {
+    void selected.value;
+    void selectedNodes.value;
+    void query.value;
+    const nav = navRef.current;
+    if (nav) notifySidebarScrollReady(nav);
+  });
   const locale =
     localeProp ?? localeLinks?.find((link) => link.active)?.code ?? "en";
   const footer = (
@@ -333,7 +342,12 @@ export function SidebarTree({
             () => activeSlug.value === undefined && !!rootMenuItems,
           )}
           fallback={() => (
-            <nav ref={navRef} tabindex={-1}>
+            <nav
+              ref={navRef}
+              tabindex={-1}
+              data-sidebar-context={navigation?.id}
+              data-sidebar-scope={computed(() => selected.value ?? "")}
+            >
               {rootMenuItems ? (
                 <button
                   type="button"