create-zudo-doc 0.2.21 → 1.0.0

package/templates/features/versioning/files/pages/lib/_versions-page.tsx

@@ -1,85 +1,33 @@
 /** @jsxRuntime automatic */
 /** @jsxImportSource preact */
-// Shared renderer for the documentation-versions pages (#2010).
-//
-// Collapses the per-locale page pair:
-//   pages/docs/versions.tsx + pages/[locale]/docs/versions.tsx
-// into one locale-parameterized renderer. The page files stay thin shells
-// that own only their paths() param shapes; URL prefixes and the
-// default-vs-locale href shapes live here.
+// Thin stub — versions-page moved to the package (epic #2344, S8).
+// Calls `createVersionsPageView(deps)` from
+// @takazudo/zudo-doc/versions-page with host singletons injected,
+// then re-exports the resulting component so all existing call sites continue
+// to work unchanged.
 
+import { createVersionsPageView } from "@takazudo/zudo-doc/versions-page";
 import { settings } from "@/config/settings";
-import { defaultLocale, t, type Locale } from "@/config/i18n";
+import { defaultLocale, t } from "@/config/i18n";
 import { withBase } from "@/utils/base";
-import { DocLayoutWithDefaults } from "@takazudo/zudo-doc/doclayout";
-import { VersionsPageContent } from "@takazudo/zudo-doc/nav-indexing";
-import type { VersionPageEntry, VersionsPageLabels } from "@takazudo/zudo-doc/nav-indexing";
-import type { JSX } from "preact";
 import { FooterWithDefaults } from "./_footer-with-defaults";
 import { HeaderWithDefaults } from "./_header-with-defaults";
 import { HeadWithDefaults } from "./_head-with-defaults";
 import { composeMetaTitle } from "./_compose-meta-title";
 import { BodyEndIslands } from "./_body-end-islands";
 
-/** Versions index page for one locale. Lists the latest version and any past
- *  versions configured in settings.versions. */
-export function VersionsPageView({ locale }: { locale: string }): JSX.Element {
-  const isDefault = locale === defaultLocale;
-  const prefix = isDefault ? "" : `/${locale}`;
-  const pageTitle = t("version.page.title", locale);
+export { type VersionsPageViewProps } from "@takazudo/zudo-doc/versions-page";
 
-  const labels: VersionsPageLabels = {
-    pageTitle,
-    latestTitle: t("version.page.latest.title", locale),
-    latestDescription: t("version.page.latest.description", locale),
-    latestLink: t("version.page.latest.link", locale),
-    pastTitle: t("version.page.past.title", locale),
-    pastDescription: t("version.page.past.description", locale),
-    unmaintained: t("version.page.unmaintained", locale),
-    unreleased: t("version.page.unreleased", locale),
-    versionCol: t("version.switcher.label", locale),
-    statusCol: t("version.page.status", locale),
-    docsCol: t("version.page.docs", locale),
-  };
-
-  // Latest docs href — points to the default docs entry point
-  const latestHref = withBase(`${prefix}/docs/getting-started`);
-
-  // Past version entries from settings
-  const versions: VersionPageEntry[] = settings.versions
-    ? settings.versions.map((v) => ({
-        slug: v.slug,
-        label: v.label ?? v.slug,
-        // Version prefix comes BEFORE the locale — the only routed shape is
-        // pages/v/[version]/{locale}/docs/...; /{locale}/v/... has no route.
-        docsHref: withBase(`/v/${v.slug}${prefix}/docs/getting-started/`),
-        banner: v.banner as "unmaintained" | "unreleased" | undefined,
-      }))
-    : [];
-
-  return (
-    <DocLayoutWithDefaults
-      title={composeMetaTitle(pageTitle)}
-      head={<HeadWithDefaults title={pageTitle} />}
-      lang={locale}
-      noindex={settings.noindex}
-      hideSidebar={true}
-      hideToc={true}
-      // Empty fragment suppresses DocLayoutWithDefaults' empty-data default
-      // Sidebar island — its marker never hydrates for published-package
-      // consumers (zfb#999) and zfb >= next.38 warns about it; the sidebar is
-      // hidden on this page anyway (zudolab/zudo-doc#2057).
-      sidebarOverride={<></>}
-      headerOverride={<HeaderWithDefaults lang={locale as Locale} currentPath={withBase(`${prefix}/docs/versions`)} />}
-      footerOverride={<FooterWithDefaults lang={locale} />}
-      bodyEndComponents={<BodyEndIslands basePath={settings.base ?? "/"} />}
-      enableClientRouter={settings.dynamicPageTransition}
-    >
-      <VersionsPageContent
-        latestHref={latestHref}
-        versions={versions}
-        labels={labels}
-      />
-    </DocLayoutWithDefaults>
-  );
-}
+export const VersionsPageView = createVersionsPageView({
+  settings,
+  defaultLocale,
+  t,
+  withBase,
+  composeMetaTitle,
+  components: {
+    HeadWithDefaults,
+    HeaderWithDefaults,
+    FooterWithDefaults,
+    BodyEndIslands,
+  },
+});

package/templates/base/pages/404.tsx

@@ -1,61 +0,0 @@
-/** @jsxRuntime automatic */
-/** @jsxImportSource preact */
-// Page module for the 404 route.
-//
-// The 404 page is a static route with no dynamic params. zfb emits it as
-// dist/404.html so the host platform (Cloudflare Pages, Netlify, etc.) can
-// serve it for unmatched requests. No paths() export needed.
-//
-// The original Astro page rendered the full html/head/body inline without
-// DocLayout because the 404 page intentionally has no sidebar/TOC/header.
-// This port wraps via DocLayoutWithDefaults with hideSidebar/hideToc plus
-// a noindex meta so search engines do not index it.
-
-import { defaultLocale } from "@/config/i18n";
-import { settings } from "@/config/settings";
-import { withBase } from "@/utils/base";
-import { DocLayoutWithDefaults } from "@takazudo/zudo-doc/doclayout";
-import type { JSX } from "preact";
-import { FooterWithDefaults } from "./lib/_footer-with-defaults";
-import { HeaderWithDefaults } from "./lib/_header-with-defaults";
-import { HeadWithDefaults } from "./lib/_head-with-defaults";
-import { composeMetaTitle } from "./lib/_compose-meta-title";
-import { BodyEndIslands } from "./lib/_body-end-islands";
-
-export const frontmatter = { title: "404" };
-
-export default function NotFoundPage(): JSX.Element {
-  const locale = defaultLocale;
-  const title = "Page Not Found";
-
-  return (
-    <DocLayoutWithDefaults
-      title={composeMetaTitle(title)}
-      head={<HeadWithDefaults title={title} />}
-      lang={locale}
-      noindex={true}
-      hideSidebar={true}
-      hideToc={true}
-      // Empty fragment suppresses DocLayoutWithDefaults' empty-data default
-      // Sidebar island — its marker never hydrates for published-package
-      // consumers (zfb#999) and zfb >= next.38 warns about it; the sidebar is
-      // hidden on this page anyway (zudolab/zudo-doc#2057).
-      sidebarOverride={<></>}
-      headerOverride={<HeaderWithDefaults lang={locale} />}
-      footerOverride={<FooterWithDefaults lang={locale} />}
-      bodyEndComponents={<BodyEndIslands basePath={settings.base ?? "/"} />}
-      enableClientRouter={settings.dynamicPageTransition}
-    >
-      <div class="min-h-[60vh] flex flex-col items-center justify-center px-hsp-2xl py-vsp-xl">
-        <h1 class="text-display font-bold mb-vsp-md">404</h1>
-        <p class="text-title text-muted mb-vsp-xl">Page not found.</p>
-        <a
-          href={withBase("/")}
-          class="bg-accent px-hsp-lg py-vsp-xs font-medium text-bg hover:bg-accent-hover"
-        >
-          Back to Home
-        </a>
-      </div>
-    </DocLayoutWithDefaults>
-  );
-}

package/templates/base/pages/robots.txt.tsx

@@ -1,29 +0,0 @@
-// Prerendered robots.txt page route, gated by settings.noindex.
-//
-// Filename → output extension mapping (zfb convention): the
-// second-to-last `.`-separated segment of the stem becomes the output
-// extension, so `robots.txt.tsx` builds `dist/robots.txt`. The
-// explicit `contentType` export pins the dev-server Content-Type
-// header to `text/plain` regardless of the filename hint.
-
-import { settings } from "@/config/settings";
-
-export const frontmatter = { title: "Robots" };
-export const contentType = "text/plain";
-
-export default function Robots(): string {
-  if (settings.noindex) {
-    // noindex: disallow all crawlers. Omit Sitemap: — advertising a sitemap
-    // while disallowing all crawlers is contradictory.
-    return `User-agent: *\nDisallow: /\n`;
-  }
-
-  const siteUrlBase = (settings.siteUrl ?? "").replace(/\/$/, "");
-  const hasSitemapLine = siteUrlBase !== "" && settings.sitemap;
-
-  const sitemapLine = hasSitemapLine
-    ? `Sitemap: ${siteUrlBase}/sitemap.xml\n`
-    : "";
-
-  return `User-agent: *\nAllow: /\n${sitemapLine}`;
-}

package/templates/base/pages/sitemap.xml.tsx

@@ -1,59 +0,0 @@
-// Port of `src/integrations/sitemap.ts` onto zfb's pages-style filename
-// convention.
-//
-// Filename → output extension mapping (zfb convention): the
-// second-to-last `.`-separated segment of the stem becomes the output
-// extension, so `sitemap.xml.tsx` builds `dist/sitemap.xml`. The
-// explicit `contentType` export pins the dev-server `Content-Type`
-// header to `application/xml` regardless of the filename hint.
-//
-// URL enumeration is delegated to `pages/lib/route-enumerators.ts` so
-// the sitemap cannot drift from the actual routes the page modules build.
-// Previously the sitemap walked raw collection slugs directly and missed:
-//   (a) tag pages           (b) JA fallback URLs
-//   (c) versioned JA routes (d) wrong URL pattern for versioned-locale pages
-//   (e) emitted /index/ suffix on category pages (closes #690)
-
-import { settings } from "@/config/settings";
-import { enumerateAllRoutes } from "./lib/route-enumerators";
-
-export const frontmatter = { title: "Sitemap" };
-export const contentType = "application/xml";
-
-function escapeXml(str: string): string {
-  return str
-    .replace(/&/g, "&")
-    .replace(/</g, "&lt;")
-    .replace(/>/g, "&gt;")
-    .replace(/"/g, "&quot;")
-    .replace(/'/g, "&apos;");
-}
-
-export default function Sitemap(): string {
-  // When sitemap is disabled, return an empty urlset so the route still
-  // resolves (returns XML, not 404) but contains no URLs.
-  if (!settings.sitemap) {
-    return `<?xml version="1.0" encoding="UTF-8"?>
-<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
-</urlset>`;
-  }
-
-  const routeMap = enumerateAllRoutes();
-  const siteUrlBase = (settings.siteUrl ?? "").replace(/\/$/, "");
-
-  const urlEntries = [...routeMap.entries()]
-    .sort(([a], [b]) => a.localeCompare(b))
-    .map(
-      ([url, lastmod]) => `  <url>
-    <loc>${escapeXml(siteUrlBase + url)}</loc>
-    <lastmod>${lastmod}</lastmod>
-  </url>`,
-    )
-    .join("\n");
-
-  return `<?xml version="1.0" encoding="UTF-8"?>
-<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
-${urlEntries}
-</urlset>
-`;
-}

package/templates/base/plugins/connect-adapter.mjs

@@ -1,169 +0,0 @@
-// @ts-check
-// Adapter from Connect-style middleware (`(req, res, next) => void`) to
-// the request-response shape zfb's `devMiddleware` lifecycle hook
-// expects (`(req: ZfbDevMiddlewareRequest) => Promise<ZfbDevMiddlewareResponse | undefined>`).
-//
-// zfb's plugin host runs in a separate Node subprocess and only sees a
-// JSON envelope of the request — `{ method, url, headers, body? }` —
-// not real Node IPC. The adapter mocks just enough of `IncomingMessage`
-// and `ServerResponse` for the v2 integration middlewares (which were
-// written against Node's `http` types) to think they are talking to a
-// regular HTTP server, then captures the response status / headers /
-// body and returns them in the shape the host expects.
-//
-// The adapter is shared by every plugin module under this directory so
-// any future Connect-style middleware can be wired into zfb's
-// devMiddleware hook without rewriting it. Lives at the host repo —
-// the v2 integration package keeps its Connect-style API surface so
-// non-zfb embedders (Astro, plain Vite, a unit test) continue to work.
-
-/** @import { ZfbDevMiddlewareRequest, ZfbDevMiddlewareResponse } from "@takazudo/zfb/plugins" */
-
-import { Buffer } from "node:buffer";
-
-/**
- * Connect-style middleware: `(req, res, next) => void`.
- * The req/res parameters are typed as `any` here because this adapter
- * intentionally passes a plain-object shim that structurally satisfies the
- * subset of `IncomingMessage` / `ServerResponse` that the v2 integration
- * middlewares actually access — not the full Node.js types.
- * @typedef {(req: any, res: any, next: (err?: unknown) => void) => void} ConnectMiddleware
- */
-
-/**
- * Convert a Connect-style middleware to a zfb devMiddleware handler.
- * The returned async function takes a `ZfbDevMiddlewareRequest` and
- * returns either `undefined` (passthrough — zfb falls through to its
- * built-in routes) or a `ZfbDevMiddlewareResponse` envelope.
- *
- * Behaviour:
- *
- *   - `next()` from the middleware → resolves with `undefined`
- *     (passthrough).
- *   - `res.end(body)` → resolves with `{ status, headers, body }`.
- *     `status` defaults to 200 if the middleware didn't set one,
- *     mirroring Node's `ServerResponse` default.
- *   - `next(err)` or a thrown error → rejects so the host surfaces a
- *     500 with the error message the same way it does for any other
- *     plugin throw.
- *   - Binary bodies (Buffer / Uint8Array) → encoded as base64 and
- *     flagged `bodyEncoding: "base64"` so the JSON envelope round-trip
- *     stays loss-less.
- *
- * @param {ConnectMiddleware} middleware
- * @returns {(zfbReq: ZfbDevMiddlewareRequest) => Promise<ZfbDevMiddlewareResponse | undefined>}
- */
-export function connectToZfbHandler(middleware) {
-  return (zfbReq) => {
-    return new Promise((resolveResponse, rejectResponse) => {
-      // Build a minimal `IncomingMessage` shim. Only the fields the v2
-      // integration middlewares actually read are populated — `method`,
-      // `url`, and `headers`. Body parsing is not used by any of the
-      // three middlewares (they're all GET routes), so we leave the
-      // stream surface unimplemented.
-      const req = {
-        method: zfbReq.method,
-        url: zfbReq.url,
-        headers: zfbReq.headers ?? {},
-      };
-
-      // Build a `ServerResponse` shim that captures status, headers,
-      // and body. We expose the API surface the v2 middlewares touch
-      // today (`statusCode`, `setHeader`, `getHeader`, `end`) — extend
-      // here if a future middleware needs more.
-      let statusCode = 200;
-      /** @type {Record<string, string>} */
-      const headers = {};
-      let settled = false;
-
-      /**
-       * @param {string | Buffer | Uint8Array | null | undefined} body
-       * @returns {void}
-       */
-      const finish = (body) => {
-        if (settled) return;
-        settled = true;
-        // Lower-case header names so the host's response shape matches
-        // axum's expectation (`Record<string, string>` of arbitrary
-        // case). Last-wins on collision; with `setHeader` callers this
-        // shouldn't happen.
-        /** @type {Record<string, string>} */
-        const normalisedHeaders = {};
-        for (const [k, v] of Object.entries(headers)) {
-          normalisedHeaders[k.toLowerCase()] = String(v);
-        }
-
-        if (Buffer.isBuffer(body) || body instanceof Uint8Array) {
-          resolveResponse({
-            status: statusCode,
-            headers: normalisedHeaders,
-            body: Buffer.from(body).toString("base64"),
-            bodyEncoding: "base64",
-          });
-          return;
-        }
-        resolveResponse({
-          status: statusCode,
-          headers: normalisedHeaders,
-          body: body == null ? "" : String(body),
-          bodyEncoding: "utf8",
-        });
-      };
-
-      const res = {
-        get statusCode() {
-          return statusCode;
-        },
-        /** @param {number} v */
-        set statusCode(v) {
-          statusCode = v;
-        },
-        /**
-         * @param {string} name
-         * @param {string | number | readonly string[]} value
-         */
-        setHeader(name, value) {
-          // Store under lowercased key to avoid duplicate-case collisions
-          // when finish() merges headers — last-wins is then unambiguous.
-          headers[name.toLowerCase()] = String(value);
-        },
-        /** @param {string} name */
-        getHeader(name) {
-          // Keys are always stored lowercased (see setHeader), so a direct
-          // lowercased lookup is sufficient and avoids an O(n) scan.
-          return headers[name.toLowerCase()];
-        },
-        get headersSent() {
-          return settled;
-        },
-        /** @param {string | Buffer | Uint8Array | null | undefined} [body] */
-        end(body) {
-          finish(body);
-        },
-      };
-
-      /** @param {unknown} [err] */
-      const next = (err) => {
-        if (settled) return;
-        if (err) {
-          settled = true;
-          rejectResponse(err instanceof Error ? err : new Error(String(err)));
-          return;
-        }
-        // Connect's `next()` with no error means "I did not handle
-        // this request". Resolve with `undefined` so zfb's host
-        // surfaces a passthrough.
-        settled = true;
-        resolveResponse(undefined);
-      };
-
-      try {
-        middleware(req, res, next);
-      } catch (err) {
-        if (settled) return;
-        settled = true;
-        rejectResponse(err instanceof Error ? err : new Error(String(err)));
-      }
-    });
-  };
-}

package/templates/base/plugins/copy-public-plugin.mjs

@@ -1,58 +0,0 @@
-// @ts-check
-// zfb plugin module: copy-public.
-//
-// Workaround for upstream zfb gap — `zfb build` does not copy `public/`
-// contents to `outDir`. See: zudolab/zudo-doc#1394;
-// upstream issue: https://github.com/Takazudo/zudo-front-builder/issues/158
-//
-// postBuild — recursively copies `<projectRoot>/public/` directly into
-//             `<outDir>/` (FLAT, matching zfb's own dist/ convention —
-//             zfb emits dist/index.html, dist/assets/..., NOT
-//             dist/<base>/index.html). Under the Workers static assets
-//             deploy (base="/"), `dist/` is served at root directly by
-//             `wrangler deploy` — no deploy-pipeline relocation step is
-//             needed. The `base` option is intentionally unused here.
-//
-//             Example: `public/img/logo.svg` becomes `dist/img/logo.svg`,
-//             served at `/img/logo.svg` by the Workers static asset layer.
-//
-// Missing or empty `public/` is treated as a no-op (no error).
-//
-// `options` carries `{ publicDir }` from the matching entry in
-// `zfb.config.ts`. The `base` option is intentionally unused — see
-// rationale above.
-
-/** @import { ZfbBuildHookContext, ZfbPlugin } from "@takazudo/zfb/plugins" */
-
-import { cp } from "node:fs/promises";
-import { resolve } from "node:path";
-
-/** @type {ZfbPlugin} */
-export default {
-  name: "copy-public",
-
-  /** @param {ZfbBuildHookContext} ctx */
-  async postBuild(ctx) {
-    const { publicDir: publicDirOption } = ctx.options;
-    const publicDir = resolve(
-      ctx.projectRoot,
-      typeof publicDirOption === "string" ? publicDirOption : "public",
-    );
-    const dest = ctx.outDir;
-
-    ctx.logger.info(`copying ${publicDir} → ${dest}`);
-
-    await cp(publicDir, dest, {
-      recursive: true,
-      force: true,
-      errorOnExist: false,
-    }).catch((/** @type {NodeJS.ErrnoException} */ err) => {
-      if (err.code === "ENOENT") {
-        // publicDir does not exist or is empty — treat as no-op.
-        ctx.logger.info("public/ not found — skipping copy");
-        return;
-      }
-      throw err;
-    });
-  },
-};

package/templates/base/plugins/search-index-plugin.mjs

@@ -1,66 +0,0 @@
-// @ts-check
-// zfb plugin module: search-index.
-//
-// Wires two lifecycle hooks for the search-index integration:
-//
-//   postBuild — invokes `emitSearchIndex` to write `dist/search-index.json`.
-//               There is no settings gate — the index is always emitted,
-//               matching the legacy Astro behaviour.
-//
-//   devMiddleware — rebuilds the in-memory search index from disk on every
-//               request so authoring edits surface without a dev-server
-//               restart. Registered at `/search-index.json`.
-//
-// `options` carries `{ docsDir, locales, base }` from the matching entry
-// in `zfb.config.ts`.
-//
-// Inline functions are not supported by zfb's plugin runtime; see the
-// sibling `doc-history-plugin.mjs` for the rationale.
-
-/** @import { ZfbBuildHookContext, ZfbDevMiddlewareContext, ZfbPlugin } from "@takazudo/zfb/plugins" */
-/** @import { SearchIndexBuildOptions, SearchIndexConfig } from "@takazudo/zudo-doc/integrations/search-index" */
-
-import { emitSearchIndex, createSearchIndexDevMiddleware } from "@takazudo/zudo-doc/integrations/search-index";
-import { connectToZfbHandler } from "./connect-adapter.mjs";
-
-/** @type {ZfbPlugin} */
-export default {
-  name: "search-index",
-
-  /** @param {ZfbBuildHookContext} ctx */
-  async postBuild(ctx) {
-    await emitSearchIndex(/** @type {SearchIndexBuildOptions} */ (/** @type {unknown} */ ({
-      ...ctx.options,
-      outDir: ctx.outDir,
-      logger: ctx.logger,
-    })));
-  },
-
-  /** @param {ZfbDevMiddlewareContext} ctx */
-  devMiddleware(ctx) {
-    const middleware = createSearchIndexDevMiddleware(
-      /** @type {SearchIndexConfig} */ (/** @type {unknown} */ (ctx.options)),
-    );
-    // zfb's `register(path, handler)` matches against the FULL request
-    // URL (no base-stripping). For a non-root base (e.g. "/my-docs/"),
-    // requests arrive as `/my-docs/search-index.json`, so we register
-    // the full base-prefixed route. For base="/", the prefix is empty
-    // and the route is `/search-index.json` as expected. The v2
-    // middleware itself is base-tolerant (matches via
-    // `endsWith("/search-index.json")`), so it does not need a
-    // separate base-stripping pass.
-    const basePrefix = stripTrailingSlash(
-      typeof ctx.options["base"] === "string" ? ctx.options["base"] : "",
-    );
-    ctx.register(`${basePrefix}/search-index.json`, connectToZfbHandler(middleware));
-  },
-};
-
-/**
- * @param {string} s
- * @returns {string}
- */
-function stripTrailingSlash(s) {
-  if (typeof s !== "string" || s.length === 0) return "";
-  return s.endsWith("/") ? s.slice(0, -1) : s;
-}