create-zudo-doc 0.2.21 → 1.0.0

package/templates/base/pages/lib/_footer-with-defaults.tsx

@@ -1,30 +1,9 @@
 /** @jsxRuntime automatic */
 /** @jsxImportSource preact */
-// Locale-aware Footer wrapper for the zfb doc pages.
-//
-// Footer data-prep utilities — reads settings.footer, localizes link
-// hrefs and titles, and optionally collects tag columns when taglist is
-// enabled — then feeds the result into the presentational <Footer> shell
-// from @takazudo/zudo-doc/footer.
-//
-// Callers pass a `lang` prop (the active locale string, e.g. "en", "ja").
-// The component returns a fully populated <Footer> when settings.footer is
-// configured, or a bare <Footer /> shell when it is not (the shell still
-// emits the contentinfo ARIA landmark).
-//
-// Data-prep helpers used:
-//   settings.footer            — link columns, copyright, taglist config
-//   isExternal / resolveHref / withBase  — href normalization
-//   defaultLocale              — determines when locale prefix is needed
-//   tagVocabulary              — group-by ordering for grouped taglist mode
-//   collectTags                — builds tag → { count, docs } map
-//   toRouteSlug                — derives route slug from collection id
-//   loadDocs / filterDrafts    — synchronous zfb collection helpers (ADR-004)
-
-import type { VNode } from "preact";
+// Host thin-stub — see @takazudo/zudo-doc/footer-with-defaults (epic #2344, S5).
+// Wires host singletons into the package factory and passes the tag loading
+// function as a dependency so the factory never imports @/ aliases.
 import { settings } from "@/config/settings";
-import { Footer } from "@takazudo/zudo-doc/footer";
-import type { FooterLinkColumn, FooterTagColumn } from "@takazudo/zudo-doc/footer";
 import { isExternal, resolveHref, withBase } from "@/utils/base";
 import { defaultLocale } from "@/config/i18n";
 import { tagVocabulary } from "@/config/tag-vocabulary";
@@ -33,214 +12,47 @@ import { toRouteSlug } from "@/utils/slug";
 import { mergeLocaleDocs } from "./locale-merge";
 import { stableDocs, memoizeDerived } from "./_nav-source-cache";
 import type { DocsEntry } from "@/types/docs-entry";
+import { createFooterWithDefaults } from "@takazudo/zudo-doc/footer-with-defaults";
 
 // ---------------------------------------------------------------------------
-// Internal helpers
+// Tag loading (host-side, reads collections via stableDocs / memoizeDerived)
 // ---------------------------------------------------------------------------
 
-/**
- * Prefix an internal href with the locale path for non-default locales,
- * then apply the configured base prefix. External hrefs pass through.
- */
-function localizeHref(href: string, lang: string): string {
-  if (isExternal(href)) return href;
-  if (lang !== defaultLocale) {
-    const path = href.startsWith("/") ? href : `/${href}`;
-    return resolveHref(`/${lang}${path}`);
+function loadTagsForLocale(lang: string) {
+  if (lang === defaultLocale) {
+    const baseDocs = stableDocs("docs");
+    return memoizeDerived([baseDocs], "footerTaglist;default", () => {
+      const docs: DocsEntry[] = baseDocs.filter(
+        (d) => !d.data.draft && !d.data.unlisted && !d.data.category_no_page,
+      );
+      const tagMap = collectTags(docs, (id, data) => data.slug ?? toRouteSlug(id));
+      return [...tagMap.values()].sort((a, b) => a.tag.localeCompare(b.tag, lang));
+    });
   }
-  return resolveHref(href);
-}
-
-/**
- * Build the base-prefixed tag detail page href for the given locale.
- * The tag segment is URL-encoded at the href site only — route params stay
- * raw, so the built output dir keeps the raw tag name and the server decodes
- * the percent-encoded href back to it (e.g. "type:guide" → "type%3Aguide").
- */
-function tagHref(tag: string, lang: string): string {
-  const encoded = encodeURIComponent(tag);
-  const path =
-    lang === defaultLocale
-      ? `/docs/tags/${encoded}`
-      : `/${lang}/docs/tags/${encoded}`;
-  return withBase(path);
+  const baseDocs = stableDocs("docs");
+  const localeDocs = stableDocs(`docs-${lang}`);
+  return memoizeDerived([baseDocs, localeDocs], `footerTaglist;${lang}`, () => {
+    const result = mergeLocaleDocs({
+      baseDocs: baseDocs.filter((d) => !d.data.draft),
+      localeDocs: localeDocs.filter((d) => !d.data.draft),
+      applyDefaultLocaleOnlyFilter: true,
+    });
+    const docs: DocsEntry[] = result.docs.filter((d) => !d.data.category_no_page);
+    const tagMap = collectTags(docs, (id, data) => data.slug ?? toRouteSlug(id));
+    return [...tagMap.values()].sort((a, b) => a.tag.localeCompare(b.tag, lang));
+  });
 }
 
 // ---------------------------------------------------------------------------
-// Component
+// Thin-stub export
 // ---------------------------------------------------------------------------
 
-interface FooterWithDefaultsProps {
-  /** Active locale string, e.g. "en", "ja". Defaults to defaultLocale. */
-  lang?: string;
-}
-
-/**
- * Locale-aware Footer wrapper.
- *
- * Reads settings.footer and assembles the linkColumns / tagColumns /
- * copyright props expected by the presentational <Footer> shell.  When
- * settings.footer is false, a bare <Footer /> shell is returned (the
- * contentinfo ARIA landmark is still present).
- */
-export function FooterWithDefaults({
-  lang = defaultLocale,
-}: FooterWithDefaultsProps): VNode {
-  const footer = settings.footer;
-
-  // Locale-keyed persist key: same-locale swaps preserve DOM identity;
-  // cross-locale swaps discard the stale footer and re-render. (#1546)
-  const persistKey = `footer-${lang}`;
-
-  // When footer is not configured, return the bare shell so the
-  // contentinfo ARIA landmark is present.
-  if (!footer) {
-    return <Footer persistKey={persistKey} />;
-  }
-
-  const { links, copyright, taglist } = footer;
-
-  // ── Link columns ────────────────────────────────────────────────────────
-
-  const linkColumns: FooterLinkColumn[] = links.map((column) => ({
-    title: (column.locales as Record<string, { title: string }> | undefined)?.[lang]?.title ?? column.title,
-    items: column.items.map((item) => ({
-      label: (item.locales as Record<string, { label: string }> | undefined)?.[lang]?.label ?? item.label,
-      href: localizeHref(item.href, lang),
-      isExternal: isExternal(item.href),
-    })),
-  }));
-
-  // ── Tag columns (optional) ───────────────────────────────────────────────
-
-  let tagColumns: FooterTagColumn[] = [];
-
-  if (taglist?.enabled) {
-    // Memoize docs loading and tag aggregation on the snapshot-anchored stable
-    // docs identity — same pattern as _nav-source-cache — so this block runs
-    // once per locale per build, not once per page render.
-    const allTags = (() => {
-      if (lang === defaultLocale) {
-        const baseDocs = stableDocs("docs");
-        return memoizeDerived([baseDocs], "footerTaglist;default", () => {
-          // category_no_page index files build no route — drop them so the
-          // footer taglist matches the tag-route pages (which all now filter too).
-          const docs: DocsEntry[] = baseDocs.filter(
-            (d) => !d.data.draft && !d.data.unlisted && !d.data.category_no_page,
-          );
-          const tagMap = collectTags(docs, (id, data) => data.slug ?? toRouteSlug(id));
-          return [...tagMap.values()].sort((a, b) => a.tag.localeCompare(b.tag, lang));
-        });
-      }
-      // Apply the default-locale-only filter so the footer taglist only counts
-      // tags that have a locale-routable tag page — matching the tag-route
-      // pages ([tag].tsx / tags/index.tsx) and enumerateTagsRoutes, which all
-      // now filter. Without this, the footer would link to /{locale}/docs/tags/
-      // pages that are never built for tags living only on default-locale-only
-      // prefix pages. category_no_page is dropped for the same reason — AFTER
-      // the merge, so a locale override carrying the flag first wins the merge
-      // (pre-merge filtering would let the unflagged base doc resurface).
-      const baseDocs = stableDocs("docs");
-      const localeDocs = stableDocs(`docs-${lang}`);
-      return memoizeDerived([baseDocs, localeDocs], `footerTaglist;${lang}`, () => {
-        const result = mergeLocaleDocs({
-          baseDocs: baseDocs.filter((d) => !d.data.draft),
-          localeDocs: localeDocs.filter((d) => !d.data.draft),
-          applyDefaultLocaleOnlyFilter: true,
-        });
-        const docs: DocsEntry[] = result.docs.filter((d) => !d.data.category_no_page);
-        const tagMap = collectTags(docs, (id, data) => data.slug ?? toRouteSlug(id));
-        return [...tagMap.values()].sort((a, b) => a.tag.localeCompare(b.tag, lang));
-      });
-    })();
-
-    const vocabularyActive =
-      Boolean(settings.tagVocabulary) && settings.tagGovernance !== "off";
-    const requestedGroupBy = taglist.groupBy ?? "group";
-    const effectiveGroupBy = vocabularyActive ? requestedGroupBy : "flat";
-
-    const localeOverrides = (taglist.locales as Record<string, { title?: string; groupTitles?: Record<string, string> }> | undefined)?.[lang];
-    const groupTitles: Record<string, string> = {
-      ...taglist.groupTitles,
-      ...localeOverrides?.groupTitles,
-    };
-    const flatTitle = localeOverrides?.title ?? taglist.title ?? "Tags";
-
-    if (effectiveGroupBy === "flat" || !vocabularyActive) {
-      if (allTags.length > 0) {
-        tagColumns = [
-          {
-            group: "__flat__",
-            title: flatTitle,
-            tags: allTags.map(({ tag, count }) => ({
-              tag,
-              count,
-              href: tagHref(tag, lang),
-            })),
-          },
-        ];
-      }
-    } else {
-      // Grouped mode: one column per vocabulary group, in declaration order.
-      const groupByCanonical = new Map<string, string>();
-      const groupOrder: string[] = [];
-      const seenGroups = new Set<string>();
-      for (const entry of tagVocabulary) {
-        if (!entry.group) continue;
-        groupByCanonical.set(entry.id, entry.group);
-        if (!seenGroups.has(entry.group)) {
-          seenGroups.add(entry.group);
-          groupOrder.push(entry.group);
-        }
-      }
-
-      const buckets = new Map<string, typeof allTags>();
-      for (const group of groupOrder) buckets.set(group, []);
-      const ungrouped: typeof allTags = [];
-
-      for (const info of allTags) {
-        const group = groupByCanonical.get(info.tag);
-        if (group && buckets.has(group)) {
-          buckets.get(group)!.push(info);
-        } else {
-          ungrouped.push(info);
-        }
-      }
-
-      tagColumns = groupOrder
-        .filter((g) => (buckets.get(g)?.length ?? 0) > 0)
-        .map((g) => ({
-          group: g,
-          title:
-            groupTitles[g] ??
-            g.charAt(0).toUpperCase() + g.slice(1),
-          tags: buckets.get(g)!.map(({ tag, count }) => ({
-            tag,
-            count,
-            href: tagHref(tag, lang),
-          })),
-        }));
-
-      if (ungrouped.length > 0) {
-        tagColumns.push({
-          group: "__flat__",
-          title: flatTitle,
-          tags: ungrouped.map(({ tag, count }) => ({
-            tag,
-            count,
-            href: tagHref(tag, lang),
-          })),
-        });
-      }
-    }
-  }
-
-  return (
-    <Footer
-      linkColumns={linkColumns}
-      tagColumns={tagColumns}
-      copyright={copyright}
-      persistKey={persistKey}
-    />
-  );
-}
+export const FooterWithDefaults = createFooterWithDefaults({
+  settings,
+  defaultLocale,
+  tagVocabulary,
+  isExternal,
+  resolveHref,
+  withBase,
+  loadTagsForLocale,
+});

package/templates/base/pages/lib/_frontmatter-preview-data.ts

@@ -17,37 +17,11 @@
 // are wired by the page template directly on the `<FrontmatterPreview>` call site
 // via the `renderers` prop. This helper only produces the filtered entries array.
 
+import { createBuildFrontmatterPreviewEntries } from "@takazudo/zudo-doc/frontmatter-preview-data";
 import { settings } from "@/config/settings";
 import { DEFAULT_FRONTMATTER_IGNORE_KEYS } from "@/config/frontmatter-preview-defaults";
 
-export function buildFrontmatterPreviewEntries(
-  data: Record<string, unknown> | null | undefined,
-): Array<[string, unknown]> {
-  if (!data) return [];
-
-  // `frontmatterPreview` may be absent (undefined) in fixtures that
-  // don't opt into the feature. `false` means the host explicitly
-  // disabled the block. Both should produce an empty entries array.
-  const config = (settings as { frontmatterPreview?: unknown })
-    .frontmatterPreview;
-  if (config === false || config === undefined) return [];
-
-  const cfg = config as {
-    ignoreKeys?: string[];
-    extraIgnoreKeys?: string[];
-  };
-  const ignoreSet = new Set<string>(
-    cfg.ignoreKeys ?? [
-      ...DEFAULT_FRONTMATTER_IGNORE_KEYS,
-      ...(cfg.extraIgnoreKeys ?? []),
-    ],
-  );
-
-  const entries: Array<[string, unknown]> = [];
-  for (const [key, value] of Object.entries(data)) {
-    if (ignoreSet.has(key)) continue;
-    if (value === null || value === undefined) continue;
-    entries.push([key, value]);
-  }
-  return entries;
-}
+export const buildFrontmatterPreviewEntries = createBuildFrontmatterPreviewEntries({
+  frontmatterPreview: settings.frontmatterPreview,
+  defaultIgnoreKeys: DEFAULT_FRONTMATTER_IGNORE_KEYS,
+});

package/templates/base/pages/lib/_head-with-defaults.tsx

@@ -1,147 +1,22 @@
 /** @jsxRuntime automatic */
 /** @jsxImportSource preact */
-// og:title / og:description / color-scheme head injection for the zfb doc pages.
-//
-// Why this wrapper exists: the v2 `<DocLayout>` shell exposes a `head` slot
-// but intentionally does NOT emit og:* meta or mount `<ColorSchemeProvider>` —
-// that is the host's responsibility.
-//
-// Without OgTags the SSG output is missing og:title / og:description,
-// which crawlers and link-preview tools rely on. Without ColorSchemeProvider
-// the runtime `:root { --zd-* }` palette is missing, so every component that
-// resolves a color via `--zd-*` (search match-keyword highlight, image-overlay,
-// etc.) falls back to UA defaults — and the smoke-search "matched
-// keywords" regression guard at e2e/smoke-search.spec.ts:167 fires
-// because `getComputedStyle(root).getPropertyValue("--zd-matched-keyword-bg")`
-// returns "" instead of the resolved palette token.
-//
-// (#1355 wave 13 — ColorSchemeProvider mount restored after the retirement of
-// the zfb cutover's initial setup.)
-
-import type { JSX } from "preact";
-import { OgTags, TwitterCard } from "@takazudo/zudo-doc/head";
-import { SIDEBAR_RESIZER_RESTORE_SCRIPT } from "@takazudo/zudo-doc/sidebar-resizer";
-// Import ColorSchemeProvider from the dedicated
-// `./theme/color-scheme-provider` subpath rather than the
-// "@takazudo/zudo-doc/theme" barrel — the barrel also re-exports the
-// ColorTweakExportModal island and the design-token SerDe/iframe-bridge
-// modules, which this SSR-only head emission does not need in its zfb
-// esbuild graph.
-import ColorSchemeProvider from "@takazudo/zudo-doc/theme/color-scheme-provider";
-import { composeMetaTitle } from "./_compose-meta-title";
-import { withBase, absoluteUrl } from "@/utils/base";
+// Host thin-stub — see @takazudo/zudo-doc/head-with-defaults (epic #2344, S5).
 import { settings } from "@/config/settings";
-// W3B (#1730): cssText + colorMode are precomputed here — the v2
-// ColorSchemeProvider no longer reaches into the host config tree.
+import { withBase, absoluteUrl } from "@/utils/base";
 import {
   generateCssCustomProperties,
   generateLightDarkCssProperties,
 } from "@/config/color-scheme-utils";
+import { composeMetaTitle } from "./_compose-meta-title";
+import { createHeadWithDefaults } from "@takazudo/zudo-doc/head-with-defaults";
 
-export interface HeadWithDefaultsProps {
-  /** Page title forwarded to og:title. Required. */
-  title: string;
-  /** Optional page description forwarded to og:description. */
-  description?: string;
-  /**
-   * Absolute canonical URL for this page. When supplied, emits
-   * <link rel="canonical" href="...">. Compute via `absoluteUrl(pageUrl)`
-   * (@/utils/base) in each host page; it returns undefined when
-   * settings.siteUrl is empty so the link is simply omitted.
-   */
-  canonical?: string;
-}
-
-/**
- * Default-bearing host wrapper that injects og:title / og:description,
- * the ColorSchemeProvider (`:root { --zd-* }` palette + theme bootstrap),
- * the favicon link, and an optional canonical link into the v2 layout's
- * `head` slot.
- *
- * og:title is run through composeMetaTitle so it matches the
- * "<title> | <siteName>" shape emitted by the host's <title> element
- * (the legacy Astro layout produced both shapes; the zfb host has to
- * compose them itself).
- *
- * og:title is always emitted — it is the unconditional DocHead contract
- * (OgTags always emits og:title regardless of settings). All other tags
- * are gated by settings.metaTags.
- *
- * Pure SSR — no state, no client-only imports. Intended for use as:
- *   head={<HeadWithDefaults title={title} description={description} canonical={canonical} />}
- * on every DocLayoutWithDefaults call site in the host pages.
- */
-export function HeadWithDefaults({
-  title,
-  description,
-  canonical,
-}: HeadWithDefaultsProps): JSX.Element {
-  const { metaTags } = settings;
-
-  // og:image / twitter:image must be absolute URLs — crawlers silently drop
-  // relative og:image values. absoluteUrl joins siteUrl (no trailing slash) +
-  // the base-prefixed asset path, and returns undefined when siteUrl is empty
-  // (e.g. a freshly scaffolded create-zudo-doc project that hasn't configured
-  // siteUrl yet) so we never ship a useless relative og:image. OgTags /
-  // TwitterCard already gate their image emission on the prop being defined;
-  // the og:image:* companion tags below are gated explicitly because they
-  // would dangle without the parent og:image.
-  const ogImageUrl =
-    metaTags.ogImage !== false
-      ? absoluteUrl(withBase(metaTags.ogImage))
-      : undefined;
-
-  // Resolve the palette CSS body once per page render (the v2 component
-  // is pure SSR — no caching needed).
-  const colorMode = settings.colorMode ? settings.colorMode : null;
-  const cssText = colorMode
-    ? generateLightDarkCssProperties()
-    : generateCssCustomProperties();
+export type { HeadWithDefaultsProps } from "@takazudo/zudo-doc/head-with-defaults";
 
-  return (
-    <>
-      <OgTags
-        title={composeMetaTitle(title)}
-        description={metaTags.description ? description : undefined}
-        ogType="website"
-        ogUrl={canonical}
-        ogImage={ogImageUrl}
-        ogSiteName={metaTags.ogSiteName ? settings.siteName : undefined}
-      />
-      {metaTags.keywords !== false && metaTags.keywords.length > 0 && (
-        <meta name="keywords" content={metaTags.keywords} />
-      )}
-      {/* og:image:width / og:image:height / og:image:alt — not in OgTags API;
-          emitted here directly to avoid expanding the shared HeadProps surface.
-          Standard 1200×630 social preview dimensions. Gated on ogImageUrl so
-          the companion tags don't dangle when og:image itself was suppressed. */}
-      {ogImageUrl !== undefined && (
-        <>
-          <meta property="og:image:width" content="1200" />
-          <meta property="og:image:height" content="630" />
-          <meta property="og:image:alt" content={composeMetaTitle(title)} />
-        </>
-      )}
-      {metaTags.twitterCard !== false && (
-        <TwitterCard
-          card={metaTags.twitterCard}
-          image={ogImageUrl}
-          site={metaTags.twitterSite}
-          creator={metaTags.twitterCreator}
-        />
-      )}
-      <ColorSchemeProvider cssText={cssText} colorMode={colorMode} />
-      {/* Pre-paint inline script: restore persisted sidebar width to
-          --zd-sidebar-w on :root before first paint, so a reload after
-          drag-resizing the sidebar doesn't snap back to the CSS default
-          clamp() width. Mirrors the sibling sidebar-toggle restore
-          script emitted from the page's afterSidebar slot. */}
-      {settings.sidebarResizer && <script dangerouslySetInnerHTML={{ __html: SIDEBAR_RESIZER_RESTORE_SCRIPT }} />}
-      {/* favicon set — withBase() handles the configured base path prefix */}
-      <link rel="icon" href={withBase("/favicon.ico")} sizes="any" />
-      <link rel="icon" type="image/png" sizes="32x32" href={withBase("/favicon-32x32.png")} />
-      <link rel="icon" type="image/png" sizes="16x16" href={withBase("/favicon-16x16.png")} />
-      {canonical !== undefined && <link rel="canonical" href={canonical} />}
-    </>
-  );
-}
+export const HeadWithDefaults = createHeadWithDefaults({
+  settings,
+  composeMetaTitle,
+  withBase,
+  absoluteUrl,
+  generateCssCustomProperties,
+  generateLightDarkCssProperties,
+});