@takazudo/zudo-doc 0.2.21 → 1.0.0

package/eject/toc/mobile-toc.tsx

@@ -0,0 +1,133 @@
+"use client";
+
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+
+import type { VNode } from "preact";
+import { useMemo, useState } from "preact/hooks";
+
+import type { HeadingItem } from "./types.js";
+import { SmartBreak } from "../smart-break/index.js";
+import { cx } from "./cx.js";
+
+export interface MobileTocProps {
+  headings: readonly HeadingItem[];
+  title?: string;
+}
+
+/**
+ * Collapsible TOC for narrow viewports (`xl:hidden`) — a Preact island
+ * component. Closed by default; tapping the header toggles, and tapping
+ * any entry closes the panel after navigation.
+ *
+ * Renders the `<div class="xl:hidden …">` panel directly. **The caller
+ * is responsible for wrapping this in `<Island when="load">`** so the
+ * SSG output emits the `data-zfb-island="MobileToc"` hydration marker
+ * around the panel. `<DocLayoutWithDefaults>` does this for you;
+ * consumers who render `<MobileToc>` outside the default layout (e.g.
+ * via the `mobileTocOverride` prop or in a custom layout) must apply
+ * the wrapper themselves — otherwise the open/close toggle never
+ * hydrates on the client and the panel stays in its initial closed
+ * state.
+ *
+ * Wave 13 (zudolab/zudo-doc#1355): previously this module exported a
+ * `MobileToc` wrapper that called `Island(...)` itself; on hydration
+ * the runtime ran `hydrate(<MobileToc/>, dataIslandDiv)` and the
+ * wrapper re-emitted *another* `<div data-zfb-island="MobileToc">…</div>`
+ * inside the existing one, leaving two `xl:hidden …` panels in the
+ * post-hydration DOM. See `./toc.tsx` for the full diagnosis. Moving
+ * the `<Island>` wrapper to the call site lets the bundle hydrate the
+ * bare panel against the existing DOM in-place.
+ *
+ * Like `Toc`, this always includes the `title` text in the SSG HTML
+ * even when no headings qualify. When no headings are present, a
+ * CSS-hidden container carries the title string so no-JS users and
+ * crawlers can still find the locale label in the static markup. When
+ * headings are present the full interactive toggle UI is rendered.
+ */
+export function MobileToc({
+  headings,
+  title = "On this page",
+}: MobileTocProps): VNode {
+  const filtered = useMemo(
+    () => headings.filter((h) => h.depth >= 2 && h.depth <= 4),
+    [headings],
+  );
+  const [open, setOpen] = useState(false);
+
+  // No qualifying headings: emit a CSS-hidden container that still carries
+  // the locale title text. The `hidden` class sets display:none visually,
+  // but the text node remains in the serialized HTML so no-JS users and
+  // crawlers can still see the locale label ("On this page" / "目次").
+  // aria-hidden prevents screen readers from announcing the invisible label.
+  if (filtered.length === 0) {
+    return (
+      <div className="hidden" aria-hidden="true">
+        {title}
+      </div>
+    );
+  }
+
+  return (
+    <div className="xl:hidden border border-muted mb-vsp-lg">
+      <button
+        type="button"
+        onClick={() => setOpen((prev) => !prev)}
+        aria-expanded={open}
+        className="flex w-full items-center justify-between px-hsp-lg py-vsp-xs text-small font-medium text-fg"
+      >
+        <span>{title}</span>
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          aria-hidden="true"
+          className={cx(
+            "h-icon-sm w-icon-sm text-muted transition-transform duration-150",
+            open && "rotate-180",
+          )}
+          fill="none"
+          viewBox="0 0 24 24"
+          stroke="currentColor"
+          strokeWidth={2}
+        >
+          <path
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            d="M19 9l-7 7-7-7"
+          />
+        </svg>
+      </button>
+      {/* Items list is always in the SSG HTML so anchor links are visible to
+          crawlers and JS-off users. Visibility is toggled by the `hidden` CSS
+          class — when `open` is false the list is display:none but the <a>
+          elements remain in the static markup, satisfying the a11y requirement
+          for keyboard accessibility after hydration. */}
+      <ul
+        className={cx(
+          "border-t border-muted px-hsp-lg py-vsp-xs space-y-vsp-2xs",
+          !open && "hidden",
+        )}
+        aria-hidden={!open}
+      >
+        {filtered.map((heading, index) => (
+          <li
+            key={`${heading.slug}-${index}`}
+            className={cx(
+              heading.depth === 3 && "ml-hsp-lg",
+              heading.depth === 4 && "ml-hsp-2xl",
+            )}
+          >
+            <a
+              href={`#${heading.slug}`}
+              onClick={() => setOpen(false)}
+              className="block py-vsp-2xs text-small text-muted hover:text-fg hover:underline focus-visible:underline"
+            >
+              <SmartBreak>{heading.text}</SmartBreak>
+            </a>
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+// See `./toc.tsx` for rationale on the explicit displayName pin.
+MobileToc.displayName = "MobileToc";

package/eject/toc/toc-title.ts

@@ -0,0 +1,33 @@
+/**
+ * Locale-to-TOC-title mapping for the v2 package.
+ *
+ * Mirrors the `toc.title` key values from `src/config/i18n.ts` (and the
+ * create-zudo-doc template equivalent). This copy lives inside the v2
+ * package so `DocLayoutWithDefaults` can derive the correct default title
+ * from the `lang` HTML attribute without importing the host project's i18n
+ * module — keeping the package self-contained and host-agnostic.
+ *
+ * When adding a new locale to zudo-doc's supported set, add the
+ * corresponding entry here too.
+ */
+const TOC_TITLES: Record<string, string> = {
+  en: "On this page",
+  ja: "目次",
+  de: "Auf dieser Seite",
+};
+
+const DEFAULT_TOC_TITLE = "On this page";
+
+/**
+ * Return the TOC section label for the given BCP-47 language tag.
+ *
+ * Accepts full tags ("en-US", "ja-JP") by checking the primary subtag
+ * first, then falls back to the full tag, then falls back to the English
+ * default so callers always receive a non-empty string.
+ */
+export function getTocTitle(lang?: string): string {
+  if (!lang) return DEFAULT_TOC_TITLE;
+  // "en-US" → try "en" first, then "en-US", then fallback
+  const primary = lang.split("-")[0]!;
+  return TOC_TITLES[primary] ?? TOC_TITLES[lang] ?? DEFAULT_TOC_TITLE;
+}

package/eject/toc/toc.tsx

@@ -0,0 +1,119 @@
+"use client";
+
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+
+import type { VNode } from "preact";
+import { useMemo } from "preact/hooks";
+
+import { useActiveHeading } from "./use-active-heading.js";
+import type { HeadingItem } from "./types.js";
+import { SmartBreak } from "../smart-break/index.js";
+import { cx } from "./cx.js";
+
+export interface TocProps {
+  headings: readonly HeadingItem[];
+  /**
+   * Section label used by MobileToc. The desktop Toc no longer renders
+   * a visible heading (issue #1655 / T1) but the prop is kept so callers
+   * can share a single title value for both desktop and mobile surfaces.
+   * Defaults to "On this page" (English).
+   */
+  title?: string;
+}
+
+/**
+ * Desktop right-rail Table of Contents — a Preact island component.
+ *
+ * Renders the `<nav aria-label="Table of contents">` directly. **The
+ * caller is responsible for wrapping this in `<Island when="load">`**
+ * so the SSG output emits the `data-zfb-island="Toc"` hydration marker
+ * around the nav. `<DocLayoutWithDefaults>` does this for you; consumers
+ * who render `<Toc>` outside the default layout (e.g. via the
+ * `tocOverride` prop or in a custom layout) must apply the wrapper
+ * themselves — otherwise the active-section scroll-spy never hydrates
+ * on the client and the nav stays static.
+ *
+ * Wave 13 ("smoke-toc duplicate-nav regression", zudolab/zudo-doc#1355):
+ * before this refactor, this module exported a `Toc` wrapper that itself
+ * called `Island(...)` internally and an inner `TocInner` component that
+ * carried `displayName = "Toc"`. The zfb island scanner picked the
+ * exported `Toc` (the wrapper) as the hydration target, so on the
+ * client `mountIslands` ran `hydrate(<Toc/>, dataIslandDiv)` where the
+ * vnode itself rendered to *another* `<div data-zfb-island="Toc">…<nav>…</nav></div>`
+ * — Preact appended the new wrapper-div as a child of the existing
+ * data-zfb-island element instead of in-place hydrating the inner nav,
+ * leaving two `<nav aria-label="Table of contents">` elements in the
+ * post-hydration DOM. The host's Wave 12 prop-serialisation pin
+ * (`data-props`) made hydration succeed where it previously crashed
+ * silently on the missing `headings` prop, which is why the duplicate
+ * only became visible in CI smoke runs after Wave 12. Moving the
+ * `<Island>` wrapper to the call site lets the bundle hydrate the bare
+ * `<nav>` against the existing DOM in-place, eliminating the duplicate.
+ *
+ * Renders only depth 2–4 headings (h2/h3/h4), matching zudo-doc's
+ * historical behavior — the page title (h1) is rendered separately by
+ * the layout and h5+ are deemed too granular for the TOC.
+ *
+ * The `title` prop is kept on the signature (MobileToc and callers still
+ * use it) but the desktop Toc no longer renders a visible heading — the
+ * `<nav aria-label="Table of contents">` landmark provides the section
+ * semantics for screen readers. Issue #1655 / T1.
+ */
+export function Toc({ headings, title = "On this page" }: TocProps): VNode {
+  const filtered = useMemo(
+    () => headings.filter((h) => h.depth >= 2 && h.depth <= 4),
+    [headings],
+  );
+  const { activeId, activate } = useActiveHeading(filtered);
+
+  return (
+    <nav
+      aria-label="Table of contents"
+      className={cx(
+        "hidden xl:flex flex-col",
+        "w-[280px] shrink-0",
+        "sticky top-[3.5rem] self-start z-sidebar",
+        "pt-vsp-xl lg:pt-vsp-2xl",
+        "h-[calc(100vh-3.5rem)]",
+      )}
+    >
+      {filtered.length > 0 && (
+        <ul className="border-l border-muted pl-hsp-lg overflow-y-auto">
+          {filtered.map((heading, index) => {
+            const isActive = heading.slug === activeId;
+            return (
+              <li
+                key={`${heading.slug}-${index}`}
+                className={cx(
+                  heading.depth === 3 && "ml-hsp-lg",
+                  heading.depth === 4 && "ml-hsp-2xl",
+                )}
+              >
+                <a
+                  href={`#${heading.slug}`}
+                  onClick={() => activate(heading.slug)}
+                  aria-current={isActive ? "true" : undefined}
+                  className={cx(
+                    "block py-vsp-2xs text-small leading-snug transition-colors",
+                    isActive
+                      ? "bg-fg text-bg font-medium"
+                      : "text-muted hover:underline focus:underline",
+                  )}
+                >
+                  <SmartBreak>{heading.text}</SmartBreak>
+                </a>
+              </li>
+            );
+          })}
+        </ul>
+      )}
+    </nav>
+  );
+}
+// Pin the marker name to "Toc" explicitly so the SSR pass `<Island>` wrapper
+// resolves a stable component identity even after esbuild minification has
+// renamed the function. captureComponentName reads displayName first, then
+// falls back to function.name; setting both means the SSR marker stays
+// "Toc" no matter which path the runtime takes.
+Toc.displayName = "Toc";

package/eject/toc/types.ts

@@ -0,0 +1,14 @@
+/**
+ * Heading metadata consumed by the TOC primitives.
+ *
+ * Shape mirrors the `headings` array exported from MDX modules by the
+ * underlying engine — `depth` (1–6), DOM `slug` (matching the rendered
+ * heading element's id), and the rendered `text`. Keep field names and
+ * types byte-aligned with the engine so a page module's `headings`
+ * export drops in directly.
+ */
+export interface HeadingItem {
+  readonly depth: number;
+  readonly slug: string;
+  readonly text: string;
+}

package/eject/toc/use-active-heading.ts

@@ -0,0 +1,162 @@
+import { useCallback, useEffect, useRef, useState } from "preact/hooks";
+import type { HeadingItem } from "./types.js";
+
+/**
+ * Pixel offset from the viewport top used as the "above the fold"
+ * threshold. A heading whose top is above this line is treated as
+ * having scrolled past — matches the original zudo-doc behavior so the
+ * scroll-spy keeps the same feel after the migration.
+ */
+const SCROLL_MARGIN_TOP = 80;
+const DEBOUNCE_MS = 200;
+
+/**
+ * Pure helper that picks the active heading id given the heading slug
+ * order and a slug→element map. Extracted from the hook so it is unit-
+ * testable without DOM event plumbing.
+ *
+ * Algorithm: find the first heading whose top is at or below the
+ * SCROLL_MARGIN_TOP threshold ("first visible"). If none, the user has
+ * scrolled past every heading — return the last one. If the very first
+ * heading is the first visible AND its top is above the viewport
+ * midline, treat it as already active. Otherwise activate the
+ * predecessor of the first visible heading.
+ */
+export function getActiveHeadingId(
+  headingIds: readonly string[],
+  elementMap: ReadonlyMap<string, HTMLElement>,
+  viewportHeight: number,
+): string | null {
+  if (headingIds.length === 0) return null;
+
+  let firstVisibleIndex = -1;
+  for (let i = 0; i < headingIds.length; i++) {
+    const el = elementMap.get(headingIds[i]!);
+    if (!el) continue;
+    const { top } = el.getBoundingClientRect();
+    if (top >= SCROLL_MARGIN_TOP) {
+      firstVisibleIndex = i;
+      break;
+    }
+  }
+
+  if (firstVisibleIndex === -1) {
+    return headingIds[headingIds.length - 1] ?? null;
+  }
+
+  if (firstVisibleIndex === 0) {
+    const el = elementMap.get(headingIds[0]!);
+    if (el) {
+      const { top } = el.getBoundingClientRect();
+      if (top < viewportHeight / 2) {
+        return headingIds[0] ?? null;
+      }
+    }
+    return null;
+  }
+
+  const el = elementMap.get(headingIds[firstVisibleIndex]!);
+  if (el) {
+    const { top } = el.getBoundingClientRect();
+    if (top < viewportHeight / 2) {
+      return headingIds[firstVisibleIndex] ?? null;
+    }
+  }
+
+  return headingIds[firstVisibleIndex - 1] ?? null;
+}
+
+export interface UseActiveHeadingResult {
+  activeId: string | null;
+  activate: (id: string) => void;
+}
+
+/**
+ * Scroll-spy hook. Tracks which heading slug should be highlighted
+ * based on the current scroll position. Provides an `activate(id)`
+ * imperatively-callable helper used by click handlers — sets the
+ * active id immediately and suppresses the scroll-driven update until
+ * the smooth-scroll completes (`scrollend`, with a timeout fallback
+ * for older Safari).
+ */
+export function useActiveHeading(
+  headings: readonly HeadingItem[],
+): UseActiveHeadingResult {
+  const [activeId, setActiveId] = useState<string | null>(null);
+  const headingIdsRef = useRef<readonly string[]>([]);
+  const elementMapRef = useRef<Map<string, HTMLElement>>(new Map());
+  const suppressedRef = useRef(false);
+
+  const activate = useCallback((id: string) => {
+    setActiveId(id);
+    suppressedRef.current = true;
+    // Safety timeout: unsuppress if no scroll event fires (target already in view)
+    setTimeout(() => {
+      suppressedRef.current = false;
+    }, 2000);
+  }, []);
+
+  useEffect(() => {
+    const ids = headings.map((h) => h.slug);
+    headingIdsRef.current = ids;
+
+    const map = new Map<string, HTMLElement>();
+    for (const id of ids) {
+      const el = document.getElementById(id);
+      if (el) map.set(id, el);
+    }
+    elementMapRef.current = map;
+
+    let timerId: ReturnType<typeof setTimeout> | null = null;
+
+    function update() {
+      timerId = null;
+      setActiveId(
+        getActiveHeadingId(
+          headingIdsRef.current,
+          elementMapRef.current,
+          window.innerHeight,
+        ),
+      );
+    }
+
+    let fallbackTimerId: ReturnType<typeof setTimeout> | null = null;
+
+    function onScroll() {
+      if (suppressedRef.current) {
+        // Fallback for browsers without scrollend (Safari < 18)
+        if (fallbackTimerId !== null) clearTimeout(fallbackTimerId);
+        fallbackTimerId = setTimeout(onScrollEnd, 1500);
+        return;
+      }
+      if (timerId !== null) clearTimeout(timerId);
+      timerId = setTimeout(update, DEBOUNCE_MS);
+    }
+
+    function onScrollEnd() {
+      suppressedRef.current = false;
+      if (fallbackTimerId !== null) {
+        clearTimeout(fallbackTimerId);
+        fallbackTimerId = null;
+      }
+      if (timerId !== null) clearTimeout(timerId);
+      update();
+    }
+
+    update();
+
+    window.addEventListener("scroll", onScroll, { passive: true });
+    window.addEventListener("resize", onScroll, { passive: true });
+    window.addEventListener("scrollend", onScrollEnd, { passive: true });
+
+    return () => {
+      window.removeEventListener("scroll", onScroll);
+      window.removeEventListener("resize", onScroll);
+      window.removeEventListener("scrollend", onScrollEnd);
+      if (timerId !== null) clearTimeout(timerId);
+      if (fallbackTimerId !== null) clearTimeout(fallbackTimerId);
+    };
+  }, [headings]);
+
+  return { activeId, activate };
+}