@takazudo/zudo-doc 0.2.21 → 1.0.0

package/dist/eject/index.js

@@ -0,0 +1,229 @@
+import fs from "fs-extra";
+import path from "path";
+import pc from "picocolors";
+const EJECTABLE = {
+  header: {
+    packageSubpath: "@takazudo/zudo-doc/header",
+    localDir: "src/components/zudo-doc/header"
+  },
+  footer: {
+    packageSubpath: "@takazudo/zudo-doc/footer",
+    localDir: "src/components/zudo-doc/footer"
+  },
+  breadcrumb: {
+    packageSubpath: "@takazudo/zudo-doc/breadcrumb",
+    localDir: "src/components/zudo-doc/breadcrumb"
+  },
+  toc: {
+    packageSubpath: "@takazudo/zudo-doc/toc",
+    localDir: "src/components/zudo-doc/toc"
+  },
+  sidebar: {
+    packageSubpath: "@takazudo/zudo-doc/sidebar",
+    localDir: "src/components/zudo-doc/sidebar"
+  },
+  "theme-toggle": {
+    packageSubpath: "@takazudo/zudo-doc/theme-toggle",
+    localDir: "src/components/zudo-doc/theme-toggle"
+  },
+  "page-loading": {
+    packageSubpath: "@takazudo/zudo-doc/page-loading",
+    localDir: "src/components/zudo-doc/page-loading"
+  },
+  "tab-item": {
+    packageSubpath: "@takazudo/zudo-doc/tab-item",
+    localDir: "src/components/zudo-doc/tab-item"
+  },
+  "doc-pager": {
+    packageSubpath: "@takazudo/zudo-doc/doc-pager",
+    localDir: "src/components/zudo-doc/doc-pager"
+  },
+  "content-admonition": {
+    packageSubpath: "@takazudo/zudo-doc/content-admonition",
+    localDir: "src/components/zudo-doc/content-admonition"
+  },
+  "code-group": {
+    packageSubpath: "@takazudo/zudo-doc/code-group",
+    localDir: "src/components/zudo-doc/code-group"
+  },
+  details: {
+    packageSubpath: "@takazudo/zudo-doc/details",
+    localDir: "src/components/zudo-doc/details"
+  }
+};
+async function rewireImports(dir) {
+  const re = /(from\s+)(["'])\.\.\/([\w-]+)\/[^"']+\2/g;
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isDirectory()) continue;
+    if (!/\.[cm]?[jt]sx?$/.test(entry.name)) continue;
+    const filePath = path.join(dir, entry.name);
+    const original = await fs.readFile(filePath, "utf8");
+    const rewritten = original.replace(re, (_, from, quote, seg) => {
+      return `${from}${quote}@takazudo/zudo-doc/${seg}${quote}`;
+    });
+    if (rewritten !== original) {
+      await fs.writeFile(filePath, rewritten, "utf8");
+    }
+  }
+}
+async function rewireHostCallSites(projectRoot, component, localDir) {
+  const packageSubpath = EJECTABLE[component].packageSubpath;
+  const escapedSubpath = packageSubpath.replace(/[/\\^$*+?.()|[\]{}]/g, "\\$&");
+  const re = new RegExp(`(from\\s+)(["'])${escapedSubpath}\\2`, "g");
+  const searchDirs = [
+    path.join(projectRoot, "src"),
+    path.join(projectRoot, "pages")
+  ];
+  let rewroteCount = 0;
+  for (const searchDir of searchDirs) {
+    if (!await fs.pathExists(searchDir)) continue;
+    const rewriteDir = async (dir, relFromProject) => {
+      const entries = await fs.readdir(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        const abs = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+          await rewriteDir(abs, path.join(relFromProject, entry.name));
+          continue;
+        }
+        if (!/\.[cm]?[jt]sx?$/.test(entry.name)) continue;
+        const original = await fs.readFile(abs, "utf8");
+        if (!original.includes(packageSubpath)) continue;
+        const fileDir = path.join(projectRoot, relFromProject);
+        const destAbs = path.join(projectRoot, localDir);
+        let rel = path.relative(fileDir, destAbs).split(path.sep).join("/");
+        if (!rel.startsWith(".")) rel = `./${rel}`;
+        const rewritten = original.replace(re, (_, from, quote) => {
+          return `${from}${quote}${rel}${quote}`;
+        });
+        if (rewritten !== original) {
+          await fs.writeFile(abs, rewritten, "utf8");
+          rewroteCount++;
+        }
+      }
+    };
+    const relBase = path.relative(projectRoot, searchDir);
+    await rewriteDir(searchDir, relBase);
+  }
+  return rewroteCount;
+}
+function defaultResolvePackageRoot(cwd) {
+  let dir = cwd;
+  while (true) {
+    const candidate = path.join(dir, "node_modules/@takazudo/zudo-doc");
+    if (fs.pathExistsSync(candidate)) return candidate;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  throw new Error(
+    `Could not find @takazudo/zudo-doc in node_modules from ${cwd}.
+Run \`pnpm install\` first.`
+  );
+}
+async function eject(component, options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const resolvePackageRoot = options.resolvePackageRoot ?? defaultResolvePackageRoot;
+  if (!Object.prototype.hasOwnProperty.call(EJECTABLE, component)) {
+    const valid = Object.keys(EJECTABLE).sort().join(", ");
+    console.error(
+      pc.red(`Unknown component "${component}".`) + `
+Ejectable components: ${valid}`
+    );
+    process.exit(1);
+  }
+  const entry = EJECTABLE[component];
+  const localDir = entry.localDir;
+  const destAbs = path.join(cwd, localDir);
+  const provenancePath = path.join(cwd, ".zudo-doc.json");
+  let provenance = { packageVersion: "unknown", ejected: {} };
+  if (await fs.pathExists(provenancePath)) {
+    try {
+      provenance = await fs.readJson(provenancePath);
+    } catch {
+      provenance = { packageVersion: "unknown", ejected: {} };
+    }
+  }
+  if (Object.prototype.hasOwnProperty.call(provenance.ejected, component)) {
+    const recorded = provenance.ejected[component];
+    console.log(
+      pc.yellow(`already ejected at ${recorded}`) + ` \u2014 skipping (re-eject is a safe no-op)`
+    );
+    return;
+  }
+  if (await fs.pathExists(destAbs)) {
+    console.log(
+      pc.yellow(`Destination ${localDir} already exists`) + ` but is not recorded in .zudo-doc.json.
+Treating as already ejected \u2014 skipping to avoid clobbering local edits.
+If you want to re-eject, remove the directory and its .zudo-doc.json entry manually.`
+    );
+    return;
+  }
+  let pkgRoot;
+  try {
+    pkgRoot = resolvePackageRoot(cwd);
+  } catch (err) {
+    console.error(pc.red(String(err)));
+    process.exit(1);
+  }
+  const ejectSrcDir = path.join(pkgRoot, "eject", component);
+  if (!await fs.pathExists(ejectSrcDir)) {
+    const pkgJsonPath = path.join(pkgRoot, "package.json");
+    let version = "unknown";
+    try {
+      const pkgJson = await fs.readJson(pkgJsonPath);
+      version = pkgJson.version ?? "unknown";
+    } catch {
+    }
+    console.error(
+      pc.red(
+        `@takazudo/zudo-doc@${version} does not ship eject sources for "${component}".
+Bump @takazudo/zudo-doc to a version that includes the eject/ tree and retry.`
+      )
+    );
+    process.exit(1);
+  }
+  let installedVersion = provenance.packageVersion;
+  try {
+    const pkgJson = await fs.readJson(path.join(pkgRoot, "package.json"));
+    installedVersion = pkgJson.version ?? installedVersion;
+  } catch {
+  }
+  await fs.ensureDir(destAbs);
+  await fs.copy(ejectSrcDir, destAbs);
+  console.log(pc.green(`Copied ${component} source \u2192 ${localDir}`));
+  await rewireImports(destAbs);
+  console.log(pc.dim(`  Rewired cross-component imports in ${localDir}`));
+  const rewroteCount = await rewireHostCallSites(cwd, component, localDir);
+  if (rewroteCount > 0) {
+    console.log(
+      pc.dim(`  Rewrote ${rewroteCount} host file(s) to import from ${localDir}`)
+    );
+  } else {
+    console.log(
+      pc.dim(
+        `  No host call sites found for ${entry.packageSubpath}.
+  Update your imports manually: change the \`"${entry.packageSubpath}"\`
+  specifier to a local one, e.g. \`"@/${localDir}/index.js"\` or a relative path.`
+      )
+    );
+  }
+  provenance.packageVersion = installedVersion;
+  provenance.ejected[component] = localDir;
+  await fs.writeJson(provenancePath, provenance, { spaces: 2 });
+  console.log(pc.green(`Updated .zudo-doc.json`));
+  console.log(
+    pc.bold(
+      `
+${pc.green("\u2713")} Ejected ${component} from @takazudo/zudo-doc@${installedVersion}
+  Source:      node_modules/@takazudo/zudo-doc/eject/${component}/
+  Destination: ${localDir}/
+  Provenance:  .zudo-doc.json
+`
+    )
+  );
+}
+export {
+  EJECTABLE,
+  eject
+};

package/dist/extract-headings/index.d.ts

@@ -0,0 +1,43 @@
+/** Heading-ID (anchor) strategy. Mirrors `settings.headingIdStrategy`. */
+export type HeadingIdStrategy = "flat" | "hierarchical";
+/**
+ * Slugify one heading's text — a byte-faithful TS port of zfb's Rust `slugify`
+ * (`crates/zfb-content/src/plugins/heading_links.rs`). Using the exact upstream
+ * algorithm (rather than npm `github-slugger`, which strips punctuation
+ * differently) is what keeps the TOC anchor identical to the rendered `id`.
+ *
+ * Rule: walk code points; whitespace, ASCII control, or a {@link SLUGIFY_STRIPPED}
+ * char collapses to a single `-` (runs coalesce); every other char is lowercased
+ * and kept (Unicode letters/digits, `-`, `_` survive). A single trailing `-` is
+ * dropped; a leading `-` is never emitted.
+ */
+export declare function slugify(input: string): string;
+export interface HeadingItem {
+    readonly depth: number;
+    readonly slug: string;
+    readonly text: string;
+}
+/**
+ * Extract TOC headings from a raw MDX/markdown body.
+ *
+ * Uses the same slugging algorithm as zfb's `HeadingLinks` plugin (selected by
+ * `opts.strategy`) so the `href="#slug"` values in the TOC match the rendered
+ * heading element IDs. Allocates over ALL matched h2–h6 (keeping the dedup
+ * counter and hierarchical ancestor stack in sync with the renderer) but only
+ * pushes depth 2–4 items into the result (configurable via opts). h1 is not
+ * matched — the renderer does not assign ids to h1.
+ *
+ * Unlike the original showcase version, this function takes all settings as
+ * explicit parameters rather than reading from the project's `settings` singleton.
+ * This keeps the package import-graph free of project singletons.
+ *
+ * @param body - Raw markdown body string (frontmatter already stripped).
+ * @param opts - Settings for heading depth window and ID strategy. Production
+ *   call sites should pass values from the project's `settings` object.
+ * @returns Array of `{ depth, slug, text }` items in document order.
+ */
+export declare function extractHeadings(body: string, opts?: {
+    tocMinDepth?: number;
+    tocMaxDepth?: number;
+    strategy?: HeadingIdStrategy;
+}): HeadingItem[];

package/dist/extract-headings/index.js

@@ -0,0 +1,111 @@
+const SLUGIFY_STRIPPED = new Set(
+  "!\"#$%&'()*+,./:;<=>?@[\\]^`{|}~".split("")
+);
+function slugify(input) {
+  let out = "";
+  let lastDash = true;
+  for (const ch of input) {
+    const cp = ch.codePointAt(0) ?? 0;
+    const isControl = cp <= 31 || cp >= 127 && cp <= 159;
+    if (isControl || /\s/u.test(ch) || SLUGIFY_STRIPPED.has(ch)) {
+      if (!lastDash) {
+        out += "-";
+        lastDash = true;
+      }
+    } else {
+      out += ch.toLowerCase();
+      lastDash = false;
+    }
+  }
+  if (out.endsWith("-")) out = out.slice(0, -1);
+  return out;
+}
+class SlugAllocator {
+  strategy;
+  /** Dedup counter, keyed by the (possibly ancestor-prefixed) slug path. */
+  seen = /* @__PURE__ */ new Map();
+  /** Hierarchical ancestor stack of `{ depth, final id }` (unused when flat). */
+  stack = [];
+  constructor(strategy) {
+    this.strategy = strategy;
+  }
+  allocate(depth, text) {
+    const base = slugify(text);
+    if (this.strategy === "flat") {
+      return this.nextSlug(base);
+    }
+    if (base === "") return "";
+    for (let top = this.stack.at(-1); top !== void 0 && top.depth >= depth; top = this.stack.at(-1)) {
+      this.stack.pop();
+    }
+    const parent = this.stack.at(-1);
+    const candidate = parent !== void 0 ? `${parent.id}-${base}` : base;
+    const id = this.nextSlug(candidate);
+    this.stack.push({ depth, id });
+    return id;
+  }
+  /**
+   * Repeat-numbering on an already-slugified candidate: first occurrence returns
+   * `candidate`, later ones `candidate-1`, `candidate-2`, …. Mirrors zfb's
+   * `next_slug` — including the empty-string short-circuit (an empty base never
+   * advances the counter), so it does NOT re-slugify (the candidate is already a
+   * valid slug path).
+   */
+  nextSlug(candidate) {
+    if (candidate === "") return "";
+    const count = this.seen.get(candidate) ?? 0;
+    this.seen.set(candidate, count + 1);
+    return count === 0 ? candidate : `${candidate}-${count}`;
+  }
+}
+function stripInlineMarkdown(raw) {
+  return raw.replace(/\[([^\]]*)\]\([^)]*\)/g, "$1").replace(/`([^`]+)`/g, "$1").replace(/\*\*([^*]+)\*\*/g, "$1").replace(/(?<![\w])__([^_]+)__(?![\w])/g, "$1").replace(/\*([^*]+)\*/g, "$1").replace(/(?<![\w])_([^_]+)_(?![\w])/g, "$1").trim();
+}
+function resolveDepthWindow(rawMin, rawMax) {
+  const min = Math.trunc(Number(rawMin));
+  const max = Math.trunc(Number(rawMax));
+  if (Number.isFinite(min) && Number.isFinite(max) && min >= 2 && min <= max && max <= 4) {
+    return { lo: min, hi: max };
+  }
+  return { lo: 2, hi: 4 };
+}
+function extractHeadings(body, opts) {
+  const { lo, hi } = resolveDepthWindow(
+    opts?.tocMinDepth ?? 2,
+    opts?.tocMaxDepth ?? 4
+  );
+  const allocator = new SlugAllocator(opts?.strategy ?? "flat");
+  const headings = [];
+  let codeFenceOpener = null;
+  for (const line of body.split("\n")) {
+    const trimmed = line.trimStart();
+    const fenceMatch = /^([`~]{3,})/.exec(trimmed);
+    if (fenceMatch) {
+      const fence = fenceMatch[1];
+      if (fence === void 0) continue;
+      if (codeFenceOpener === null) {
+        codeFenceOpener = fence;
+      } else if (fence[0] === codeFenceOpener[0] && fence.length >= codeFenceOpener.length) {
+        codeFenceOpener = null;
+      }
+      continue;
+    }
+    if (codeFenceOpener !== null) continue;
+    const match = /^(#{2,6})[ \t]+(.+)$/.exec(line.trim());
+    if (!match) continue;
+    const hashes = match[1];
+    const rawText = match[2];
+    if (hashes === void 0 || rawText === void 0) continue;
+    const depth = hashes.length;
+    const text = stripInlineMarkdown(rawText.trim());
+    const slug = allocator.allocate(depth, text);
+    if (depth >= lo && depth <= hi) {
+      headings.push({ depth, slug, text });
+    }
+  }
+  return headings;
+}
+export {
+  extractHeadings,
+  slugify
+};

package/dist/factory-context/index.d.ts

@@ -0,0 +1,80 @@
+import type { Settings } from "../settings.js";
+/**
+ * The i18n surface a factory may read. Parameterizes what `base.ts` used to read
+ * off the project's `@/config/i18n` singleton directly, so URL/locale logic moves
+ * into the package as pure functions (see `makeUrlHelpers`).
+ *
+ * `Locale` is kept as a plain `string` at the package boundary — the concrete
+ * union (`"en" | "ja" | …`) is a project-specific narrowing the host supplies; the
+ * package only needs the structural contract.
+ */
+export interface FactoryI18n {
+    /** Default locale code (served from the un-prefixed `/docs/...` routes). */
+    defaultLocale: string;
+    /** All supported locale codes, default locale first. */
+    locales: readonly string[];
+    /** Display label for a locale (e.g. `"EN"`, `"日本語"`). */
+    getLocaleLabel: (locale: string) => string;
+    /**
+     * Translate a UI string key for a locale, falling back to the default locale
+     * then the key itself. Optional: factories that emit no UI strings omit it.
+     */
+    t?: (key: string, locale?: string) => string;
+}
+/**
+ * ALLOWED `{ components }` slots — the host-supplied, project-bound component
+ * bindings a factory may inject. This is an **explicit allowlist, NOT an open
+ * bag**: every key here is a component the package cannot own because it depends
+ * on the host's content collections, settings wiring, or showcase-specific
+ * markup. Each slot is documented in `packages/zudo-doc/CLAUDE.md`. Do NOT widen
+ * this into a dumping ground — a new slot needs a real cross-package coupling
+ * reason and a CLAUDE.md entry. All slots are optional so a factory takes only
+ * the ones it needs.
+ *
+ * Components are typed as the structural `FactoryComponent` (a function
+ * returning Preact-renderable output) rather than a concrete signature, so the
+ * type stays node-free and Preact-version-agnostic at the boundary.
+ */
+export interface FactoryComponents {
+    /** Locale-aware category nav wrapper (reads the project's content collection). */
+    CategoryNav?: FactoryComponent;
+    /** Locale-aware category-tree nav wrapper. */
+    CategoryTreeNav?: FactoryComponent;
+    /** Locale-aware site-tree nav wrapper (also used for the demo variant). */
+    SiteTreeNav?: FactoryComponent;
+    /** HTML-preview wrapper bound to the host's preview config. */
+    HtmlPreview?: FactoryComponent;
+    /** `<details>` content override. */
+    Details?: FactoryComponent;
+    /** zfb `<Island>` pass-through (host owns the import so the scanner walks it). */
+    Island?: FactoryComponent;
+    /** PresetGenerator SSR shell (showcase-only; downstream projects stub it). */
+    PresetGenerator?: FactoryComponent;
+}
+/** Any Preact-renderable component — a function returning a VNode/children. */
+export type FactoryComponent = (props: Record<string, unknown>) => unknown;
+/**
+ * Opaque per-locale nav-source handle. The host owns the actual content-loader
+ * implementation (it reads project content collections, which cannot live in the
+ * package); a factory receives this handle and passes it to the package's pure
+ * nav builders (`buildNavTree`, sidebar/nav-scope helpers) without knowing its
+ * internals. Typed `unknown` on purpose — narrowing belongs to the host stub.
+ */
+export type NavSource = unknown;
+/**
+ * The injected context every relocated `pages/lib/*` factory receives.
+ *
+ * @typeParam S - the host's concrete settings shape (defaults to the package
+ *   `Settings`). A factory that reads only a subset may accept `Pick<Settings, …>`
+ *   at its own call site; this context type carries the full object.
+ */
+export interface FactoryContext<S = Settings> {
+    /** The host's resolved settings object (single source of config truth). */
+    settings: S;
+    /** The i18n surface (locales, labels, optional translator). */
+    i18n: FactoryI18n;
+    /** Host-supplied, project-bound component bindings (explicit allowlist). */
+    components: FactoryComponents;
+    /** Opaque per-locale nav-source handle passed to the pure nav builders. */
+    navSource: NavSource;
+}