@takazudo/zudo-doc 0.2.22 → 1.0.1

package/eject/header/index.ts

@@ -0,0 +1,36 @@
+/**
+ * Public entry for the JSX `<Header />` port.
+ *
+ * Consumers import from `@takazudo/zudo-doc/header`:
+ *
+ *   import { Header } from "@takazudo/zudo-doc/header";
+ *
+ * The pure helpers used to compute active-link state are also exposed
+ * so downstream tests / custom layouts can reuse them without rebuilding
+ * the `pathForMatch` / `computeActiveNavPath` regex logic.
+ */
+
+export type {
+  Locale,
+  HeaderNavChildItem,
+  HeaderNavItem,
+  HeaderRightComponentItem,
+  HeaderRightComponentName,
+  HeaderRightHtmlItem,
+  HeaderRightItem,
+  HeaderRightLinkItem,
+  HeaderRightTriggerItem,
+  HeaderRightTriggerName,
+} from "./types.js";
+export {
+  filterHeaderRightItems,
+  type HeaderRightItemFlags,
+} from "./right-items.js";
+export { Header, type HeaderProps } from "./header.js";
+export {
+  computeActiveNavPath,
+  isNavItemActive,
+  pathForMatch,
+  type NavItemLike,
+} from "./nav-active.js";
+export { NAV_OVERFLOW_SCRIPT } from "./nav-overflow-script.js";

package/eject/header/nav-active.ts

@@ -0,0 +1,122 @@
+// Pure, settings-free helpers backing the JSX <Header /> port.
+//
+// These exist as their own module so unit tests can exercise the active-
+// path resolution logic without booting the host project's @/config or
+// @/utils modules. The Header component imports from here too so the
+// runtime and the tests share a single source of truth.
+
+/** Minimal shape the active-path resolver needs from a header nav item. */
+export interface NavItemLike {
+  path: string;
+  /**
+   * The "big category" this nav entry claims (mirrors the host's
+   * `getNavSectionForSlug` / sidebar `categoryMatch`). When the host knows
+   * which category the current page belongs to, category matching is
+   * preferred over URL-path heuristics — see `isNavItemActiveByCategory`.
+   */
+  categoryMatch?: string;
+  children?: { path: string; categoryMatch?: string }[];
+}
+
+/**
+ * Strip the locale prefix from `pathWithoutBase` when the page is being
+ * served under a non-default locale. Mirrors the inline regex inside
+ * `header` so the JSX port matches the legacy template's
+ * active-link behaviour.
+ *
+ * Examples:
+ *   pathForMatch("/ja/docs/intro", "ja", "en") === "/docs/intro"
+ *   pathForMatch("/docs/intro",   "en", "en") === "/docs/intro"
+ *   pathForMatch(null,            "ja", "en") === ""
+ */
+export function pathForMatch(
+  pathWithoutBase: string,
+  lang: string | undefined,
+  defaultLocale: string,
+): string {
+  if (lang == null || lang === defaultLocale) return pathWithoutBase;
+  // Segment boundary required: "/ja-tutorial/..." must not lose its "/ja".
+  return pathWithoutBase.replace(new RegExp(`^/${lang}(?=/|$)`), "");
+}
+
+/**
+ * Pick the deepest header-nav path that the current page lives under.
+ *
+ * The legacy template flattens parent + child paths, filters by
+ * `pathForMatch.startsWith(p)`, and picks the longest match — this keeps
+ * a child link active even when its parent's path is also a prefix of
+ * the current page.
+ *
+ * Returns `undefined` when no nav entry matches; callers should treat
+ * that as "no active link."
+ */
+/**
+ * Segment-aware prefix test: nav path `/docs/guides` matches `/docs/guides`
+ * and `/docs/guides/...` but NOT `/docs/guideship`.
+ */
+function pathMatchesNavPath(currentPath: string, navPath: string): boolean {
+  if (currentPath === navPath) return true;
+  const prefix = navPath.endsWith("/") ? navPath : `${navPath}/`;
+  return currentPath.startsWith(prefix);
+}
+
+export function computeActiveNavPath(
+  navItems: readonly NavItemLike[],
+  pathForMatchValue: string,
+): string | undefined {
+  const allNavPaths = navItems.flatMap((item) => {
+    const paths = [item.path];
+    if (item.children) {
+      paths.push(...item.children.map((child) => child.path));
+    }
+    return paths;
+  });
+  return allNavPaths
+    .filter((p) => pathMatchesNavPath(pathForMatchValue, p))
+    .sort((a, b) => b.length - a.length)[0];
+}
+
+/**
+ * Active-state predicate for a top-level nav item: the item itself, or
+ * any of its children, matches the active path. Mirrors the inline
+ * `isNavItemActive` helper in the legacy template.
+ */
+export function isNavItemActive(
+  item: NavItemLike,
+  activeNavPath: string | undefined,
+): boolean {
+  if (activeNavPath === item.path) return true;
+  if (item.children?.some((child) => activeNavPath === child.path)) return true;
+  return false;
+}
+
+/**
+ * Category-based active-state predicate. A nav entry is active when its
+ * own `categoryMatch` equals the page's resolved big category
+ * (`activeCategory`), or when any of its children claim that category.
+ *
+ * This is the authoritative "is the page under this big category?" check
+ * — it mirrors how the sidebar scopes its tree (`getNavSectionForSlug`),
+ * so the header highlight stays correct even when a category's page URLs
+ * do not share a prefix with the nav item's `path` (the case the older
+ * path-only heuristic missed). Callers prefer this over `isNavItemActive`
+ * and fall back to path matching when `activeCategory` is absent (e.g.
+ * home, 404, tag, and version pages, which carry no nav section).
+ *
+ * Works for both top-level items and child items: a child has no
+ * `children` of its own, so the call collapses to a single
+ * `categoryMatch` comparison.
+ */
+export function isNavItemActiveByCategory(
+  item: NavItemLike,
+  activeCategory: string | undefined,
+): boolean {
+  if (activeCategory == null) return false;
+  // `activeCategory` is non-null here, so a plain `===` already rejects an
+  // entry whose `categoryMatch` is undefined — no extra null guard needed.
+  if (item.categoryMatch === activeCategory) return true;
+  if (item.children?.some((child) => child.categoryMatch === activeCategory)) {
+    return true;
+  }
+  return false;
+}

package/eject/header/nav-overflow-script.ts

@@ -0,0 +1,302 @@
+// Inline-script source for the desktop-nav overflow controller.
+//
+// In the original `header` template the script lived directly
+// inside a `<script>` tag (which Astro pipes through the bundler). For
+// the JSX port we emit the same logic verbatim via
+// `dangerouslySetInnerHTML`, so the value below is plain ECMAScript —
+// any TypeScript-only constructs (generic params, type casts, parameter
+// type annotations) have been dropped so the browser can parse it
+// directly.
+//
+// The behaviour matches the original modulo lifecycle vocabulary:
+//   1. Locate the `[data-header-nav]` flex container, its `[data-nav-more]`
+//      overflow trigger, and its dropdown menu.
+//   2. Measure each top-level nav item, then greedily hide items that
+//      would overflow and rebuild the "..." dropdown to mirror them
+//      (including the bold-parent + indented-children pattern for
+//      `[data-nav-item-dropdown]` entries).
+//   3. Wire toggle / outside-click / Escape handlers to the overflow
+//      menu and aria-expanded state to the in-place dropdowns.
+//   4. Re-run on the v2 after-navigate event so the overflow stays
+//      correct after an SPA body-swap navigation. The event name is
+//      pulled from `AFTER_NAVIGATE_EVENT` in
+//      `transitions/page-events.ts` (today: `zfb:after-swap`) rather
+//      than a hard-coded `astro:*` literal — see that module for the
+//      vocabulary rationale. The first-paint init relies on the
+//      top-level `initNavOverflow()` call further down (after-swap
+//      does NOT fire on the initial page load).
+//
+// Kept as a separate module (rather than inlined in `header.tsx`) so
+// the JSX file stays focused on markup and so future edits to the
+// script can be reviewed in isolation.
+
+import { AFTER_NAVIGATE_EVENT } from "../transitions/page-events.js";
+
+export const NAV_OVERFLOW_SCRIPT = `(function () {
+  var cleanupNavOverflow = null;
+
+  function trimSlashes(p) {
+    while (p.length > 1 && p.charAt(p.length - 1) === "/") p = p.slice(0, -1);
+    return p || "/";
+  }
+
+  function navPathname(a) {
+    try { return trimSlashes(new URL(a.href, location.href).pathname); }
+    catch (e) { return ""; }
+  }
+
+  function isUnderPath(cur, p) {
+    if (!p) return false;
+    if (cur === p) return true;
+    return p !== "/" && cur.indexOf(p + "/") === 0;
+  }
+
+  // Recompute which header nav item is "active" from the CURRENT URL and
+  // repaint the highlight. SSR sets the active item on first paint, but the
+  // header is persisted across same-locale client-router swaps
+  // (data-zfb-transition-persist), so without this the highlight would stay
+  // frozen on the page where the header was first rendered. Mirrors the
+  // sidebar island's client-side approach (match location.pathname against
+  // each entry's href) and the SSR longest-match + dropdown-parent rules.
+  // URL-based: hrefs and location.pathname both carry the base + locale
+  // prefix, so they compare directly without stripping.
+  function applyActiveNav() {
+    var nav = document.querySelector("[data-header-nav]");
+    if (!nav) return;
+    var topItems = Array.from(nav.querySelectorAll(":scope > [data-nav-item]"));
+    if (topItems.length === 0) return;
+
+    var cur = trimSlashes(location.pathname);
+
+    // Deepest (longest) nav path the current URL lives under, across both
+    // top-level and dropdown-child paths — matches computeActiveNavPath.
+    var activePath = "";
+    topItems.forEach(function (it) {
+      var isDropdown = it.hasAttribute("data-nav-item-dropdown");
+      var topA = isDropdown ? it.querySelector(":scope > a") : it;
+      if (topA) {
+        var tp = navPathname(topA);
+        if (isUnderPath(cur, tp) && tp.length > activePath.length) activePath = tp;
+      }
+      if (isDropdown) {
+        it.querySelectorAll(":scope > div a").forEach(function (c) {
+          var cp = navPathname(c);
+          if (isUnderPath(cur, cp) && cp.length > activePath.length) activePath = cp;
+        });
+      }
+    });
+
+    function setTopActive(a, active) {
+      if (!a) return;
+      if (active) {
+        a.classList.add("bg-fg", "text-bg");
+        a.classList.remove("text-muted", "hover:underline", "focus:underline");
+        a.setAttribute("aria-current", "page");
+      } else {
+        a.classList.remove("bg-fg", "text-bg");
+        a.classList.add("text-muted", "hover:underline", "focus:underline");
+        a.removeAttribute("aria-current");
+      }
+    }
+
+    topItems.forEach(function (it) {
+      var isDropdown = it.hasAttribute("data-nav-item-dropdown");
+      var topA = isDropdown ? it.querySelector(":scope > a") : it;
+      var topActive = false;
+
+      if (isDropdown) {
+        var parentMatch = !!topA && navPathname(topA) === activePath && activePath !== "";
+        var anyChild = false;
+        it.querySelectorAll(":scope > div a").forEach(function (c) {
+          var childActive = navPathname(c) === activePath && activePath !== "";
+          if (childActive) {
+            anyChild = true;
+            c.setAttribute("data-active", "");
+            c.classList.add("font-bold", "text-accent");
+            c.classList.remove("text-fg");
+          } else {
+            c.removeAttribute("data-active");
+            c.classList.remove("font-bold", "text-accent");
+            c.classList.add("text-fg");
+          }
+        });
+        topActive = parentMatch || anyChild;
+        var svg = topA ? topA.querySelector("svg") : null;
+        if (svg) {
+          if (topActive) { svg.classList.add("text-bg"); svg.classList.remove("text-muted"); }
+          else { svg.classList.add("text-muted"); svg.classList.remove("text-bg"); }
+        }
+      } else {
+        topActive = activePath !== "" && navPathname(topA) === activePath;
+      }
+
+      setTopActive(topA, topActive);
+    });
+  }
+
+  function initNavOverflow() {
+    if (cleanupNavOverflow) cleanupNavOverflow();
+
+    // Repaint the active highlight for the current URL before measuring /
+    // cloning, so the overflow "···" menu mirrors the correct active state.
+    applyActiveNav();
+
+    var nav = document.querySelector("[data-header-nav]");
+    var moreContainer = document.querySelector("[data-nav-more]");
+    var moreMenu = document.querySelector("[data-nav-more-menu]");
+    var moreToggle = document.querySelector("[data-nav-more-toggle]");
+    if (!nav || !moreContainer || !moreMenu || !moreToggle) return;
+
+    var items = Array.from(nav.querySelectorAll(":scope > [data-nav-item]"));
+    if (items.length === 0) return;
+
+    var controller = new AbortController();
+
+    function update() {
+      items.forEach(function (el) { el.style.display = ""; });
+      moreContainer.style.display = "";
+      moreMenu.innerHTML = "";
+      moreMenu.classList.add("hidden");
+      moreToggle.setAttribute("aria-expanded", "false");
+
+      var itemWidths = items.map(function (el) { return el.offsetWidth; });
+      var moreWidth = moreContainer.offsetWidth;
+      var navGap = parseFloat(getComputedStyle(nav).columnGap) || 0;
+      var available = nav.clientWidth;
+
+      if (available <= 0) {
+        moreContainer.style.display = "none";
+        return;
+      }
+
+      var total = 0;
+      for (var i = 0; i < itemWidths.length; i++) {
+        total += itemWidths[i] + (i > 0 ? navGap : 0);
+      }
+
+      if (total <= available) {
+        moreContainer.style.display = "none";
+        return;
+      }
+
+      var used = 0;
+      var cutoffIndex = 0;
+
+      for (var i2 = 0; i2 < items.length; i2++) {
+        var w = itemWidths[i2] + (i2 > 0 ? navGap : 0);
+        if (used + w > available - moreWidth - navGap) break;
+        used += w;
+        cutoffIndex = i2 + 1;
+      }
+
+      for (var i3 = cutoffIndex; i3 < items.length; i3++) {
+        items[i3].style.display = "none";
+      }
+
+      for (var i4 = cutoffIndex; i4 < items.length; i4++) {
+        var el = items[i4];
+        var isDropdown = el.hasAttribute("data-nav-item-dropdown");
+
+        if (isDropdown) {
+          var parentLink = el.querySelector(":scope > a");
+          var childLinks = el.querySelectorAll(":scope > div a");
+          if (parentLink) {
+            var li = document.createElement("li");
+            var a = document.createElement("a");
+            a.href = parentLink.href;
+            var parentText = parentLink.textContent ? parentLink.textContent.trim().replace(/\\s+/g, " ") : "";
+            a.textContent = parentText;
+            a.className = "block px-hsp-md py-vsp-2xs text-small font-bold hover:bg-accent/10 hover:underline focus-visible:underline text-fg";
+            if (parentLink.getAttribute("aria-current") === "page") {
+              a.className += " text-accent";
+            }
+            li.appendChild(a);
+            moreMenu.appendChild(li);
+          }
+          childLinks.forEach(function (child) {
+            var li = document.createElement("li");
+            var a = document.createElement("a");
+            a.href = child.href;
+            a.textContent = child.textContent ? child.textContent.trim() : "";
+            var isChildActive = child.hasAttribute("data-active");
+            a.className = isChildActive
+              ? "block pl-hsp-xl pr-hsp-md py-vsp-2xs text-small font-bold text-accent hover:bg-accent/10 hover:underline focus-visible:underline"
+              : "block pl-hsp-xl pr-hsp-md py-vsp-2xs text-small text-muted hover:bg-accent/10 hover:text-fg hover:underline focus-visible:underline";
+            li.appendChild(a);
+            moreMenu.appendChild(li);
+          });
+        } else {
+          var anchor = el;
+          var li2 = document.createElement("li");
+          var a2 = document.createElement("a");
+          a2.href = anchor.href;
+          a2.textContent = anchor.textContent ? anchor.textContent.trim() : "";
+          a2.className = "block px-hsp-md py-vsp-2xs text-small hover:bg-accent/10 hover:underline focus-visible:underline text-fg";
+          if (anchor.getAttribute("aria-current") === "page") {
+            a2.className += " font-bold text-accent";
+          }
+          li2.appendChild(a2);
+          moreMenu.appendChild(li2);
+        }
+      }
+    }
+
+    moreToggle.addEventListener("click", function () {
+      var isOpen = !moreMenu.classList.contains("hidden");
+      moreMenu.classList.toggle("hidden", isOpen);
+      moreToggle.setAttribute("aria-expanded", String(!isOpen));
+    }, { signal: controller.signal });
+
+    document.addEventListener("click", function (e) {
+      if (!moreContainer.contains(e.target)) {
+        moreMenu.classList.add("hidden");
+        moreToggle.setAttribute("aria-expanded", "false");
+      }
+    }, { signal: controller.signal });
+
+    document.addEventListener("keydown", function (e) {
+      if (e.key !== "Escape") return;
+      if (!moreMenu.classList.contains("hidden")) {
+        moreMenu.classList.add("hidden");
+        moreToggle.setAttribute("aria-expanded", "false");
+        moreToggle.focus();
+        return;
+      }
+      var active = document.activeElement;
+      var dropdown = active && active.closest ? active.closest("[data-nav-item-dropdown]") : null;
+      if (dropdown && active && active.blur) {
+        active.blur();
+      }
+    }, { signal: controller.signal });
+
+    var dropdowns = nav.querySelectorAll("[data-nav-item-dropdown]");
+    dropdowns.forEach(function (dd) {
+      var trigger = dd.querySelector(":scope > a");
+      if (!trigger) return;
+      function setExpanded(v) {
+        trigger.setAttribute("aria-expanded", String(v));
+      }
+      dd.addEventListener("mouseenter", function () { setExpanded(true); }, { signal: controller.signal });
+      dd.addEventListener("mouseleave", function () { setExpanded(false); }, { signal: controller.signal });
+      dd.addEventListener("focusin", function () { setExpanded(true); }, { signal: controller.signal });
+      dd.addEventListener("focusout", function (e) {
+        if (!dd.contains(e.relatedTarget)) {
+          setExpanded(false);
+        }
+      }, { signal: controller.signal });
+    });
+
+    var ro = new ResizeObserver(update);
+    ro.observe(nav);
+    controller.signal.addEventListener("abort", function () { ro.disconnect(); });
+
+    document.fonts.ready.then(update);
+
+    update();
+
+    cleanupNavOverflow = function () { controller.abort(); };
+  }
+
+  initNavOverflow();
+  document.addEventListener(${JSON.stringify(AFTER_NAVIGATE_EVENT)}, initNavOverflow);
+})();`;

package/eject/header/right-items.ts

@@ -0,0 +1,78 @@
+// `filterHeaderRightItems` was moved here from the host's
+// `src/utils/header-right-items.ts` (super-epic #1724, sub-issue #1729).
+//
+// Why it moved: keeping the filter inside v2 lets the package own the full
+// header-rendering contract — `<Header>` only renders items the caller has
+// approved, and the approval rule is colocated with the renderer. The
+// previous version pulled `settings` straight from the host's `@/config`
+// alias, which is exactly the kind of host-coupling W3A removes.
+//
+// The new shape takes a `flags` object instead. The host computes the
+// flags from its own `settings` / `i18n` modules and passes them in,
+// preserving the original filter logic without dragging any `@/` import
+// across the package boundary.
+
+import type { HeaderRightItem } from "./types.js";
+
+/**
+ * Runtime gates for `filterHeaderRightItems`.
+ *
+ * Mirrors the predicates in the legacy host-side helper (`src/utils/
+ * header-right-items.ts` pre-#1729). Each flag corresponds to a specific
+ * `settings.*` switch the original implementation consulted directly:
+ *
+ *   - `designTokenPanel` — `settings.designTokenPanel`
+ *   - `aiAssistant`      — `settings.aiAssistant`
+ *   - `colorMode`        — `Boolean(settings.colorMode)`
+ *   - `hasLocales`       — `Object.keys(settings.locales).length > 0`
+ *   - `hasVersions`      — `Boolean(settings.versions)`
+ *   - `hasGithubUrl`     — `Boolean(settings.githubUrl)`
+ */
+export interface HeaderRightItemFlags {
+  designTokenPanel: boolean;
+  aiAssistant: boolean;
+  colorMode: boolean;
+  hasLocales: boolean;
+  hasVersions: boolean;
+  hasGithubUrl: boolean;
+}
+
+/**
+ * Drop header-right items whose gating flag is off. Pure function — the
+ * caller is responsible for computing the flags from host config.
+ *
+ * Items not gated by any flag (links, raw HTML, version-switcher when
+ * versions are configured, search, …) pass through untouched.
+ */
+export function filterHeaderRightItems(
+  items: HeaderRightItem[],
+  flags: HeaderRightItemFlags,
+): HeaderRightItem[] {
+  return items.filter((item) => {
+    if (item.type === "trigger") {
+      if (item.trigger === "design-token-panel") {
+        return flags.designTokenPanel;
+      }
+      if (item.trigger === "ai-chat") {
+        return flags.aiAssistant;
+      }
+    }
+
+    if (item.type === "component") {
+      if (item.component === "theme-toggle") {
+        return flags.colorMode;
+      }
+      if (item.component === "language-switcher") {
+        return flags.hasLocales;
+      }
+      if (item.component === "version-switcher") {
+        return flags.hasVersions;
+      }
+      if (item.component === "github-link") {
+        return flags.hasGithubUrl;
+      }
+    }
+
+    return true;
+  });
+}

package/eject/header/types.ts

@@ -0,0 +1,69 @@
+// Boundary types for the v2 `<Header />` shell.
+//
+// The host project (`src/config/settings-types.ts`) owns the canonical
+// shapes for these structures. We copy them here so v2 has its own
+// self-contained type surface — consumers import `HeaderNavItem` /
+// `HeaderRightItem` from `@takazudo/zudo-doc/header` and don't reach
+// into the host's `@/config` alias.
+//
+// Structural-only: the v2 copies are intentionally simple and broad. If
+// the host extends a field (e.g. adds a new `HeaderRightTriggerName`),
+// downstream consumers may continue to use the v2 types until the v2
+// package itself widens them. Changes here are v2 breaking changes.
+
+/**
+ * Locale code as seen by the header. Widened from the host's literal
+ * union (`"en" | "ja" | …`) to plain `string` at the v2 boundary so the
+ * package can render for any project's locale set without a generic
+ * parameter (super-epic #1724, sub-issue #1729).
+ */
+export type Locale = string;
+
+export interface HeaderNavChildItem {
+  label: string;
+  labelKey?: string;
+  path: string;
+  categoryMatch?: string;
+}
+
+export interface HeaderNavItem extends HeaderNavChildItem {
+  children?: HeaderNavChildItem[];
+}
+
+export type HeaderRightComponentName =
+  | "theme-toggle"
+  | "language-switcher"
+  | "version-switcher"
+  | "github-link"
+  | "search";
+
+export type HeaderRightTriggerName = "design-token-panel" | "ai-chat";
+
+export interface HeaderRightComponentItem {
+  type: "component";
+  component: HeaderRightComponentName;
+}
+
+export interface HeaderRightTriggerItem {
+  type: "trigger";
+  trigger: HeaderRightTriggerName;
+}
+
+export interface HeaderRightLinkItem {
+  type: "link";
+  href: string;
+  label?: string;
+  ariaLabel?: string;
+  icon?: "github";
+}
+
+export interface HeaderRightHtmlItem {
+  type: "html";
+  html: string;
+}
+
+export type HeaderRightItem =
+  | HeaderRightComponentItem
+  | HeaderRightTriggerItem
+  | HeaderRightLinkItem
+  | HeaderRightHtmlItem;

package/eject/page-loading/index.ts

@@ -0,0 +1,10 @@
+// E5 framework primitives — page-loading overlay.
+//
+// Subpath: `@takazudo/zudo-doc/page-loading`.
+
+export {
+  default as PageLoadingOverlay,
+  PAGE_LOADING_OVERLAY_ID,
+  buildPageLoadingOverlayBootstrap,
+  type PageLoadingOverlayProps,
+} from "./page-loading-overlay.js";