create-zudo-doc 0.1.0

package/templates/features/versioning/files/pages/v/[version]/ja/docs/[...slug].tsx

@@ -0,0 +1,490 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+// Port of src/pages/v/[version]/ja/docs/[...slug].astro → zfb page module.
+//
+// Versioned JA docs route. paths() cross-products settings.versions with a
+// locale-first merge strategy: locale-specific collection (`docs-v-${version.slug}-ja`)
+// takes priority; the base EN collection (`docs-v-${version.slug}`) fills in
+// pages not translated yet (shown with a fallback notice).
+//
+// If version.locales?.ja is not configured, only the base EN collection is used.
+//
+// paths() contract (zfb ADR-004 — synchronous):
+//   params: { version: string; slug: string[] }
+//   props:  { entry, autoIndex, version, contentDir, isFallback, breadcrumbs, prev, next }
+//
+// Prev/next hrefs are pre-resolved to the versioned JA URL form
+// (e.g. /v/1.0/ja/docs/…) so the component needs no URL computation.
+
+import { getCollection } from "zfb/content";
+import type { CollectionEntry } from "zfb/content";
+import type { DocsEntry } from "@/types/docs-entry";
+import { settings } from "@/config/settings";
+import type { VersionConfig } from "@/config/settings";
+import { t } from "@/config/i18n";
+import { docsUrl, versionedDocsUrl, isDefaultLocaleOnlyPath } from "@/utils/base";
+import {
+  buildNavTree,
+  buildBreadcrumbs,
+  flattenTree,
+  findNode,
+  loadCategoryMeta,
+  collectAutoIndexNodes,
+  isNavVisible,
+  type NavNode,
+  type BreadcrumbItem,
+} from "@/utils/docs";
+import { getNavSectionForSlug, getNavSubtree } from "@/utils/nav-scope";
+import { toRouteSlug } from "@/utils/slug";
+import { DocLayoutWithDefaults } from "@takazudo/zudo-doc/doclayout";
+import { Breadcrumb } from "@takazudo/zudo-doc/breadcrumb";
+import { NavCardGrid } from "@takazudo/zudo-doc/nav-indexing";
+import { FrontmatterPreview } from "@takazudo/zudo-doc/metainfo";
+import { frontmatterRenderers } from "@/config/frontmatter-preview-renderers";
+// Locale-aware MDX components factory — see `pages/_mdx-components.ts`.
+import { createMdxComponents } from "../../../../_mdx-components";
+import type { JSX } from "preact";
+import { bridgeEntries } from "../../../../_data";
+import { extractHeadings } from "../../../../lib/_extract-headings";
+import { FooterWithDefaults } from "../../../../lib/_footer-with-defaults";
+import { SidebarWithDefaults } from "../../../../lib/_sidebar-with-defaults";
+import { HeaderWithDefaults } from "../../../../lib/_header-with-defaults";
+import { HeadWithDefaults } from "../../../../lib/_head-with-defaults";
+import { DocHistoryArea } from "../../../../lib/_doc-history-area";
+import { DocMetainfoArea } from "../../../../lib/_doc-metainfo-area";
+import { DocTagsArea } from "../../../../lib/_doc-tags-area";
+import { BodyEndIslands } from "../../../../lib/_body-end-islands";
+import { buildFrontmatterPreviewEntries } from "../../../../lib/_frontmatter-preview-data";
+import { composeMetaTitle } from "../../../../lib/_compose-meta-title";
+import { buildInlineVersionSwitcher } from "../../../../lib/_inline-version-switcher";
+import DesktopSidebarToggle from "@/components/desktop-sidebar-toggle";
+import { SidebarResizerInit } from "@takazudo/zudo-doc/sidebar-resizer";
+import type { VNode } from "preact";
+import { Island } from "@takazudo/zfb";
+
+export const frontmatter = { title: "Docs" };
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface DocPageEntry extends DocsEntry {
+  Content: CollectionEntry<unknown>["Content"];
+  module_specifier: string;
+}
+
+interface AutoIndexNode extends NavNode {
+  children: NavNode[];
+}
+
+interface DocPageProps {
+  entry: DocPageEntry | null;
+  autoIndex?: AutoIndexNode;
+  /** The version config for the active version. */
+  version: VersionConfig;
+  /** Content directory for this page (locale dir if translated, version docsDir if fallback). */
+  contentDir: string;
+  /** True when this page falls back to the base EN collection for this version. */
+  isFallback: boolean;
+  breadcrumbs: BreadcrumbItem[];
+  prev: NavNode | null;
+  next: NavNode | null;
+  /** Depth-2/3/4 headings extracted from the MDX body, for SSG TOC links. */
+  headings: ReturnType<typeof extractHeadings>;
+}
+
+// ---------------------------------------------------------------------------
+// paths() — synchronous (ADR-004)
+// ---------------------------------------------------------------------------
+
+/**
+ * Emit one route per (version, slug) combination for JA locale.
+ *
+ * Merge strategy per version:
+ *   1. Load locale docs (e.g. "docs-v-1.0-ja") if version.locales.ja is set.
+ *   2. Load base EN docs ("docs-v-1.0").
+ *   3. Locale docs take priority; base EN fills in slugs not translated.
+ *   4. Track fallback slugs for the fallback-notice banner.
+ *   5. Build nav tree with "ja" locale, compute breadcrumbs and prev/next.
+ *
+ * Prev/next hrefs are pre-resolved to the versioned JA URL form.
+ */
+export function paths(): Array<{
+  params: { version: string; slug: string[] };
+  props: DocPageProps;
+}> {
+  if (!settings.versions) return [];
+
+  const result: Array<{
+    params: { version: string; slug: string[] };
+    props: DocPageProps;
+  }> = [];
+
+  for (const version of settings.versions) {
+    const baseCollectionName = `docs-v-${version.slug}`;
+    const localeDir = (version.locales as Record<string, { dir: string }> | undefined)?.ja?.dir;
+    const localeCollectionName = localeDir ? `docs-v-${version.slug}-ja` : null;
+
+    const baseDocs = ((bridgeEntries(getCollection(baseCollectionName), baseCollectionName) as unknown as DocPageEntry[])).filter(
+      (doc) => !doc.data.draft,
+    );
+    const localeDocs = localeCollectionName
+      ? ((bridgeEntries(getCollection(localeCollectionName), localeCollectionName) as unknown as DocPageEntry[])).filter(
+          (doc) => !doc.data.draft,
+        )
+      : [];
+
+    // Build slug set from locale docs (locale takes priority)
+    const localeSlugSet = new Set(localeDocs.map((d) => d.data.slug ?? toRouteSlug(d.slug)));
+
+    // Merge: locale docs first, then base docs for missing pages
+    const fallbackDocs = baseDocs.filter(
+      (d) => !localeSlugSet.has(d.data.slug ?? toRouteSlug(d.slug)) && !isDefaultLocaleOnlyPath(`/docs/${d.data.slug ?? toRouteSlug(d.slug)}`),
+    );
+    const fallbackSlugs = new Set(fallbackDocs.map((d) => d.data.slug ?? toRouteSlug(d.slug)));
+    const allDocs = [...localeDocs, ...fallbackDocs];
+
+    // Merge category metadata: base first, locale overrides
+    const baseCategoryMeta = loadCategoryMeta(version.docsDir);
+    const localeCategoryMeta = localeDir ? loadCategoryMeta(localeDir) : new Map();
+    const categoryMeta = new Map([...baseCategoryMeta, ...localeCategoryMeta]);
+
+    const navDocs = allDocs.filter(isNavVisible);
+    const tree = buildNavTree(navDocs as unknown as DocsEntry[], "ja", categoryMeta);
+
+    // Regular doc pages
+    for (const entry of allDocs) {
+      const slug = entry.data.slug ?? toRouteSlug(entry.slug);
+      const isFallback = fallbackSlugs.has(slug);
+      const entryContentDir = isFallback ? version.docsDir : (localeDir ?? version.docsDir);
+
+      const navSection = getNavSectionForSlug(slug);
+      const subtree = getNavSubtree(tree, navSection);
+      const flat = flattenTree(subtree);
+      const idx = flat.findIndex((n) => n.slug === slug);
+
+      let prevNode = idx > 0 ? flat[idx - 1] ?? null : null;
+      let nextNode = idx >= 0 && idx < flat.length - 1 ? flat[idx + 1] ?? null : null;
+
+      if (entry.data.pagination_prev !== undefined) {
+        if (entry.data.pagination_prev === null) {
+          prevNode = null;
+        } else {
+          const found = findNode(tree, entry.data.pagination_prev);
+          prevNode = found ?? prevNode;
+        }
+      }
+      if (entry.data.pagination_next !== undefined) {
+        if (entry.data.pagination_next === null) {
+          nextNode = null;
+        } else {
+          const found = findNode(tree, entry.data.pagination_next);
+          nextNode = found ?? nextNode;
+        }
+      }
+
+      result.push({
+        params: { version: version.slug, slug: slug.split("/") },
+        props: {
+          entry,
+          version,
+          contentDir: entryContentDir,
+          isFallback,
+          breadcrumbs: buildBreadcrumbs(tree, slug, "ja"),
+          // Pre-resolve prev/next hrefs to versioned JA URLs
+          prev: prevNode
+            ? { ...prevNode, href: versionedDocsUrl(prevNode.slug, version.slug, "ja") }
+            : null,
+          next: nextNode
+            ? { ...nextNode, href: versionedDocsUrl(nextNode.slug, version.slug, "ja") }
+            : null,
+          headings: extractHeadings(entry.body ?? ""),
+        },
+      });
+    }
+
+    // Auto-generated index pages for categories without index.mdx
+    for (const node of collectAutoIndexNodes(tree)) {
+      result.push({
+        params: { version: version.slug, slug: node.slug.split("/") },
+        props: {
+          entry: null,
+          autoIndex: {
+            ...node,
+            children: node.children.map((c: NavNode) => ({
+              ...c,
+              href: c.href ?? versionedDocsUrl(c.slug, version.slug, "ja"),
+            })) as NavNode[],
+          } as AutoIndexNode,
+          version,
+          contentDir: localeDir ?? version.docsDir,
+          isFallback: false,
+          breadcrumbs: buildBreadcrumbs(tree, node.slug, "ja"),
+          prev: null,
+          next: null,
+          headings: [],
+        },
+      });
+    }
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Page component
+// ---------------------------------------------------------------------------
+
+interface PageArgs {
+  params: { version: string; slug: string[] };
+  entry: DocPageProps["entry"];
+  autoIndex?: DocPageProps["autoIndex"];
+  version: DocPageProps["version"];
+  isFallback: DocPageProps["isFallback"];
+  breadcrumbs: DocPageProps["breadcrumbs"];
+  prev: DocPageProps["prev"];
+  next: DocPageProps["next"];
+  headings: DocPageProps["headings"];
+}
+
+export default function VersionedJaDocsPage({ entry, autoIndex, version, isFallback, breadcrumbs, prev, next, headings }: PageArgs): JSX.Element {
+  const locale = "ja";
+
+  const slug = autoIndex
+    ? autoIndex.slug
+    : (entry!.data.slug ?? toRouteSlug(entry!.slug));
+
+  const title = autoIndex ? autoIndex.label : entry!.data.title;
+  const description = autoIndex ? autoIndex.description : entry!.data.description;
+
+  // Locale-aware components bag — creates nav wrappers bound to the active
+  // locale so CategoryNav/CategoryTreeNav/SiteTreeNav query the right collection.
+  const components = createMdxComponents(locale);
+
+  const autoIndexChildren = autoIndex
+    ? autoIndex.children.filter((c: NavNode) => c.hasPage || c.children.length > 0)
+    : [];
+
+  // Version banner: drives the `<VersionBanner>` element inside
+  // DocLayoutWithDefaults when `version.banner` is "unmaintained" or
+  // "unreleased". The banner links out to the latest version of the
+  // current page (slug-preserving — strips the /v/{version}/ prefix,
+  // keeps the /ja/ locale prefix).
+  const versionBannerType = version.banner ? version.banner : undefined;
+  const versionBannerLatestUrl = versionBannerType
+    ? docsUrl(slug, locale)
+    : undefined;
+  const versionBannerLabels = versionBannerType
+    ? {
+        message:
+          versionBannerType === "unmaintained"
+            ? t("version.banner.unmaintained", locale)
+            : t("version.banner.unreleased", locale),
+        latestLink: t("version.banner.latestLink", locale),
+      }
+    : undefined;
+
+  // Canonical URL — versioned JA pages use the versioned JA URL as canonical.
+  const pageUrl = versionedDocsUrl(slug, version.slug, locale);
+  const canonical = settings.siteUrl
+    ? settings.siteUrl.replace(/\/$/, "") + pageUrl
+    : undefined;
+
+  // Persist key: locale + nav-section so the sidebar DOM node is reused
+  // across same-locale + same-section navigations only. No sanitizer needed —
+  // both lang (BCP-47 locale string) and navSection (filesystem-derived
+  // kebab-case slug) come from controlled, trusted sources.
+  const navSection = getNavSectionForSlug(slug);
+  const hideSidebar = entry?.data?.hide_sidebar;
+  const sidebarPersistKey = hideSidebar
+    ? undefined
+    : `sidebar-${locale}-${navSection ?? "default"}`;
+
+  return (
+    <DocLayoutWithDefaults
+      title={composeMetaTitle(title)}
+      description={description}
+      head={<HeadWithDefaults title={title} description={description} canonical={canonical} />}
+      lang={locale}
+      noindex={settings.noindex}
+      hideSidebar={hideSidebar}
+      hideToc={entry?.data?.hide_toc}
+      headings={headings}
+      canonical={canonical}
+      sidebarPersistKey={sidebarPersistKey}
+      versionBanner={versionBannerType ?? false}
+      versionBannerLatestUrl={versionBannerLatestUrl}
+      versionBannerLabels={versionBannerLabels}
+      headerOverride={
+        <HeaderWithDefaults
+          lang={locale}
+          currentSlug={slug}
+          navSection={getNavSectionForSlug(slug)}
+          currentVersion={version.slug}
+          currentPath={versionedDocsUrl(slug, version.slug, locale)}
+        />
+      }
+      breadcrumbOverride={
+        breadcrumbs.length > 0 ? (
+          <Breadcrumb
+            items={breadcrumbs}
+            rightSlot={buildInlineVersionSwitcher(slug, locale, version.slug)}
+          />
+        ) : undefined
+      }
+      sidebarOverride={
+        <SidebarWithDefaults
+          currentSlug={slug}
+          lang={locale}
+          navSection={getNavSectionForSlug(slug)}
+          currentVersion={version.slug}
+          currentPath={versionedDocsUrl(slug, version.slug, locale)}
+        />
+      }
+      afterSidebar={
+        settings.sidebarToggle ? (
+          <>
+            <script dangerouslySetInnerHTML={{
+              __html: `(function(){try{if(localStorage.getItem('zudo-doc-sidebar-visible')==='false'){document.documentElement.setAttribute('data-sidebar-hidden','');}}catch(e){}})();`,
+            }} />
+            {Island({
+              when: "load",
+              children: <DesktopSidebarToggle />,
+            }) as unknown as VNode}
+          </>
+        ) : undefined
+      }
+      footerOverride={<FooterWithDefaults lang={locale} />}
+      bodyEndComponents={
+        <>
+          <BodyEndIslands basePath={settings.base ?? "/"} />
+          {settings.sidebarResizer && <SidebarResizerInit />}
+        </>
+      }
+    >
+      {autoIndex ? (
+        /* Auto-index page: category without an index.mdx.
+           Fragment (not <div>) so children become direct children of
+           <article class="zd-content">, picking up the flow-space rule
+           (.zd-content > :where(* + *) { margin-top: var(--flow-space) }).
+           Wrapping in <div> would make h1/description p children-of-children
+           and the flow gap (~24px) would never apply — see #1460. */
+        <>
+          <h1 class="text-heading font-bold mb-vsp-xs">{autoIndex.label}</h1>
+          {autoIndex.description && (
+            <p class="mb-vsp-lg text-title text-muted">
+              {autoIndex.description}
+            </p>
+          )}
+          <NavCardGrid children={autoIndexChildren} />
+        </>
+      ) : (
+        /* Regular doc page. Fragment (not <div>) for the same reason as
+           the auto-index branch above — see #1460. */
+        <>
+          <h1 class="text-heading font-bold mb-vsp-xs">{entry!.data.title}</h1>
+
+          {/* Build-time date block (Created / Updated / Author). Mirrors the
+              Astro `doc-metainfo.astro` placement — between <h1> and description.
+              Data from `.zfb/doc-history-meta.json` (esbuild-inlined, no fs). */}
+          <DocMetainfoArea slug={slug} locale={locale} />
+
+          {/* Page-level tag chips — mirroring doc-tags.astro placement (#1658). */}
+          <DocTagsArea slug={slug} locale={locale} tags={entry!.data.tags} />
+
+          {/* Fallback notice for non-translated pages */}
+          {isFallback && !entry!.data.generated && (
+            <div
+              class="mb-vsp-md border border-info/30 bg-info/5 px-hsp-lg py-vsp-sm text-small text-muted rounded"
+              role="note"
+            >
+              {t("doc.fallbackNotice", locale)}
+            </div>
+          )}
+
+          {entry!.data.description && (
+            <p class="mb-vsp-lg text-title text-muted">
+              {entry!.data.description}
+            </p>
+          )}
+
+          {/* Frontmatter preview — non-system, custom keys only. Returns
+              null when the entries array is empty, so pages without
+              custom frontmatter emit nothing. */}
+          <FrontmatterPreview
+            entries={buildFrontmatterPreviewEntries(entry!.data)}
+            title={t("frontmatter.preview.title", locale)}
+            keyColLabel={t("frontmatter.preview.keyCol", locale)}
+            valueColLabel={t("frontmatter.preview.valueCol", locale)}
+            renderers={frontmatterRenderers}
+            data={entry!.data as Record<string, unknown>}
+            locale={locale}
+          />
+
+          {entry && <entry.Content components={components} />}
+
+          {/* Prev / Next pagination — placed before the document utilities
+              section to match the Astro reference order: content → pager →
+              view-source / history. Fixes #1535. */}
+          <nav class="mt-vsp-2xl grid grid-cols-2 gap-hsp-xl">
+            {prev ? (
+              <a
+                href={prev.href}
+                class="group border border-muted rounded-lg p-hsp-lg hover:border-accent"
+              >
+                <div class="flex items-center gap-hsp-xs text-caption text-muted mb-vsp-2xs">
+                  <svg
+                    xmlns="http://www.w3.org/2000/svg"
+                    class="h-[1.125rem] w-[1.125rem]"
+                    fill="none"
+                    viewBox="0 0 24 24"
+                    stroke="currentColor"
+                    stroke-width="2"
+                  >
+                    <path stroke-linecap="round" stroke-linejoin="round" d="M15 19l-7-7 7-7" />
+                  </svg>
+                  <span class="no-underline">{t("nav.previous", locale)}</span>
+                </div>
+                <p class="text-small font-semibold underline group-hover:text-accent">
+                  {prev.label}
+                </p>
+              </a>
+            ) : (
+              <div />
+            )}
+            {next ? (
+              <a
+                href={next.href}
+                class="group border border-muted rounded-lg p-hsp-lg hover:border-accent text-right"
+              >
+                <div class="flex items-center justify-end gap-hsp-xs text-caption text-muted mb-vsp-2xs">
+                  <span class="no-underline">{t("nav.next", locale)}</span>
+                  <svg
+                    xmlns="http://www.w3.org/2000/svg"
+                    class="h-[1.125rem] w-[1.125rem]"
+                    fill="none"
+                    viewBox="0 0 24 24"
+                    stroke="currentColor"
+                    stroke-width="2"
+                  >
+                    <path stroke-linecap="round" stroke-linejoin="round" d="M9 5l7 7-7 7" />
+                  </svg>
+                </div>
+                <p class="text-small font-semibold underline group-hover:text-accent">
+                  {next.label}
+                </p>
+              </a>
+            ) : (
+              <div />
+            )}
+          </nav>
+
+          {/* Document utilities (revision history) — gated on entry, matching regular slug page pattern */}
+          {entry && (
+            <DocHistoryArea slug={slug} locale={locale} />
+          )}
+        </>
+      )}
+    </DocLayoutWithDefaults>
+  );
+}