create-zudo-doc 0.2.20 → 0.2.22

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/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/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;
-}

package/templates/base/scripts/gen-z-index.mjs

@@ -1,157 +0,0 @@
-#!/usr/bin/env node
-// scripts/gen-z-index.mjs
-//
-// Codegen: rewrite the GENERATED:Z_INDEX marker block inside
-// src/styles/global.css from the single source of truth in
-// src/config/z-index-tokens.ts.
-//
-// The block is a Tailwind v4 `@theme { --z-index-<name>: <value>; }` for every
-// tier, so Tailwind generates `z-<name>` utilities (e.g. `--z-index-toolbar: 20`
-// → `.z-toolbar { z-index: 20 }`) and raw CSS can reference the same var via
-// `z-index: var(--z-index-<name>)`.
-//
-// Pure Node (fs only — NO npm deps). Idempotent: running twice produces no diff.
-//
-// Usage:
-//   node scripts/gen-z-index.mjs           # rewrite the block in global.css
-//   node scripts/gen-z-index.mjs --check   # verify committed block is up to date
-//                                          # (exit 1 on drift, no write)
-//
-// MAINTENANCE: edit src/config/z-index-tokens.ts (the source of truth), then run
-// `pnpm gen:z-index` and commit the regenerated global.css. Never hand-edit the
-// block between the BEGIN/END markers.
-
-import { readFileSync, writeFileSync } from "node:fs";
-import { resolve, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const ROOT = resolve(__dirname, "..");
-
-const TOKENS_PATH = resolve(ROOT, "src/config/z-index-tokens.ts");
-const CSS_PATH = resolve(ROOT, "src/styles/global.css");
-
-const BEGIN_MARKER = "GENERATED:Z_INDEX_BEGIN";
-const END_MARKER = "GENERATED:Z_INDEX_END";
-
-/**
- * Parse the Z_INDEX_TIERS array out of z-index-tokens.ts WITHOUT importing it
- * (this script is a dependency-free .mjs and cannot resolve TypeScript). Reads
- * each `{ name: "...", value: <n>, ... }` object literal. Throws on a malformed
- * source so drift between the parser and the file surfaces loudly.
- */
-function parseTiers(src) {
-  const arrayMatch = src.match(
-    /export const Z_INDEX_TIERS[^=]*=\s*\[([\s\S]*?)\];/,
-  );
-  if (!arrayMatch) {
-    throw new Error(
-      `Could not locate "export const Z_INDEX_TIERS = [ ... ]" in ${TOKENS_PATH}`,
-    );
-  }
-  const body = arrayMatch[1];
-  const tiers = [];
-  // Each tier is a `{ ... }` object literal; iterate top-level braces.
-  const objectRe = /\{([\s\S]*?)\}/g;
-  let m;
-  while ((m = objectRe.exec(body)) !== null) {
-    const obj = m[1];
-    const nameMatch = obj.match(/name:\s*"([^"]+)"/);
-    const valueMatch = obj.match(/value:\s*(-?\d+)/);
-    if (!nameMatch || !valueMatch) {
-      throw new Error(
-        `Malformed tier object in Z_INDEX_TIERS (missing name/value): ${obj.trim()}`,
-      );
-    }
-    tiers.push({ name: nameMatch[1], value: Number(valueMatch[1]) });
-  }
-  if (tiers.length === 0) {
-    throw new Error(`Z_INDEX_TIERS in ${TOKENS_PATH} parsed to an empty list`);
-  }
-  return tiers;
-}
-
-/**
- * Build the full generated block (markers included). Two leading spaces of
- * indentation match the surrounding `@theme` style in global.css.
- */
-function buildBlock(tiers) {
-  const lines = [];
-  lines.push(`  /* ${BEGIN_MARKER}`);
-  lines.push(
-    `   * GENERATED:Z_INDEX — do not hand-edit; run pnpm gen:z-index.`,
-  );
-  lines.push(
-    `   * Source of truth: src/config/z-index-tokens.ts. Tailwind v4 reads the`,
-  );
-  lines.push(
-    `   * --z-index-<name> theme key and generates a z-<name> utility. */`,
-  );
-  lines.push(`  @theme {`);
-  for (const tier of tiers) {
-    lines.push(`    --z-index-${tier.name}: ${tier.value};`);
-  }
-  lines.push(`  }`);
-  lines.push(`  /* ${END_MARKER} */`);
-  return lines.join("\n");
-}
-
-/**
- * Replace the existing BEGIN…END block in `css` with `block`. Throws if the
- * markers are missing (the block must be seeded once by hand — see global.css).
- */
-function replaceBlock(css, block) {
-  const beginIdx = css.indexOf(BEGIN_MARKER);
-  const endIdx = css.indexOf(END_MARKER);
-  if (beginIdx === -1 || endIdx === -1) {
-    throw new Error(
-      `Could not find ${BEGIN_MARKER} … ${END_MARKER} markers in ${CSS_PATH}.\n` +
-        `Seed the marker block once by hand, then re-run the generator.`,
-    );
-  }
-  // Expand to the full comment line that opens the block ("  /* GENERATED:...")
-  // and to the end of the closing "*/ " line so the whole region is replaced.
-  const lineStart = css.lastIndexOf("\n", beginIdx) + 1;
-  const afterEnd = css.indexOf("\n", endIdx);
-  const lineEnd = afterEnd === -1 ? css.length : afterEnd;
-  return css.slice(0, lineStart) + block + css.slice(lineEnd);
-}
-
-function main() {
-  const check = process.argv.includes("--check");
-
-  const tokensSrc = readFileSync(TOKENS_PATH, "utf8");
-  const css = readFileSync(CSS_PATH, "utf8");
-
-  const tiers = parseTiers(tokensSrc);
-  const block = buildBlock(tiers);
-  const next = replaceBlock(css, block);
-
-  if (check) {
-    if (next !== css) {
-      console.error(
-        "z-index codegen drift detected: src/styles/global.css is out of date.",
-      );
-      console.error("Run `pnpm gen:z-index` and commit the result.");
-      return 1;
-    }
-    console.log(
-      `OK — z-index @theme block is up to date (${tiers.length} tiers).`,
-    );
-    return 0;
-  }
-
-  if (next === css) {
-    console.log(
-      `z-index @theme block already up to date (${tiers.length} tiers); no change.`,
-    );
-    return 0;
-  }
-  writeFileSync(CSS_PATH, next);
-  console.log(
-    `Wrote z-index @theme block to src/styles/global.css (${tiers.length} tiers).`,
-  );
-  return 0;
-}
-
-process.exit(main());