@takazudo/zudo-doc 0.2.21 → 1.0.0

package/dist/route-enumerators/index.d.ts

@@ -0,0 +1,204 @@
+import type { NavSourceDocs } from "../nav-source-docs/index.js";
+import type { DocPageEntry, DocNavNode } from "../doc-page-props/index.js";
+export type { DocPageEntry, DocNavNode, NavSourceDocs };
+/**
+ * Minimal docs entry shape needed for tag enumeration (no Content/module_specifier).
+ */
+export interface DocsEntryForTags {
+    id: string;
+    data: {
+        slug?: string;
+        draft?: boolean;
+        unlisted?: boolean;
+        category_no_page?: boolean;
+        tags?: string[];
+        [key: string]: unknown;
+    };
+}
+/**
+ * Minimal version config shape needed for route enumeration.
+ */
+export interface VersionConfigForEnum {
+    slug: string;
+    docsDir?: string;
+    locales?: Record<string, {
+        dir?: string;
+    }>;
+}
+/**
+ * Minimal tag info shape — only the keys the tag URL enumerator needs.
+ */
+export interface TagInfoForEnum {
+    tag: string;
+    count: number;
+}
+/**
+ * Injected context for `createRouteEnumerators`.
+ *
+ * All host-specific singletons and utilities are passed in so the package
+ * factory never imports `@/` aliases.
+ */
+export interface RouteEnumeratorsContext {
+    /** Default locale code. Host passes `defaultLocale` from `@/config/i18n`. */
+    defaultLocale: string;
+    /**
+     * Getter for all non-default locale codes.
+     * Host passes `() => Object.keys(settings.locales)`.
+     * Called per invocation so mutations to settings.locales are picked up.
+     */
+    getLocaleKeys: () => readonly string[];
+    /**
+     * Getter for the configured versions list (or false/undefined).
+     * Host passes `() => settings.versions`.
+     * Called per invocation so mutations to settings.versions are picked up.
+     */
+    getVersions: () => VersionConfigForEnum[] | false | undefined;
+    /**
+     * Getter for whether tag pages are enabled.
+     * Host passes `() => settings.docTags`.
+     */
+    getDocTags: () => boolean | undefined;
+    /** `docsUrl(slug, lang)` from `@/utils/base` (resolved with settings). */
+    docsUrl: (slug: string, lang?: string) => string;
+    /** `versionedDocsUrl(slug, versionSlug, lang)` from `@/utils/base`. */
+    versionedDocsUrl: (slug: string, versionSlug: string, lang?: string) => string;
+    /** `withBase(path)` from `@/utils/base`. */
+    withBase: (path: string) => string;
+    /**
+     * Load docs from a named collection.
+     * Host passes `loadDocs` from `pages/_data.ts`.
+     */
+    loadDocs: (collectionName: string) => DocsEntryForTags[];
+    /**
+     * Returns true for paths that are only shown in the default locale.
+     * Host passes `isDefaultLocaleOnlyPath` from `@/utils/base`.
+     */
+    isDefaultLocaleOnlyPath: (path: string) => boolean;
+    /**
+     * Collect tags from a docs array.
+     * Host passes `collectTags` from `@/utils/tags`.
+     */
+    collectTags: (docs: DocsEntryForTags[], slugFn: (id: string, data: {
+        slug?: string;
+    }) => string) => Map<string, TagInfoForEnum>;
+    /**
+     * Convert a content entry slug to a canonical route slug.
+     * Host passes `toRouteSlug` from `@/utils/slug`.
+     */
+    toRouteSlug: (id: string) => string;
+    /**
+     * Build the nav tree for a locale.
+     * Host passes `buildNavTree` from `@/utils/docs`.
+     */
+    buildNavTree: (docs: DocPageEntry[], locale: string, categoryMeta: Map<string, unknown>) => DocNavNode[];
+    /**
+     * Collect auto-generated index nodes.
+     * Host passes `collectAutoIndexNodes` from `@/utils/docs`.
+     */
+    collectAutoIndexNodes: (tree: DocNavNode[]) => DocNavNode[];
+    /**
+     * Resolve the identity-stable nav source for an EN/locale context.
+     * Host passes `resolveNavSource` from `pages/lib/_nav-source-docs.ts`.
+     */
+    resolveNavSource: (lang: string, currentVersion: string | undefined, options?: {
+        applyDefaultLocaleOnlyFilter?: boolean;
+        keepUnlisted?: boolean;
+    }) => NavSourceDocs;
+    /**
+     * Resolve the identity-stable nav source for a versioned non-default-locale
+     * context.
+     * Host passes `resolveVersionedLocaleSource` from `pages/lib/_nav-source-docs.ts`.
+     */
+    resolveVersionedLocaleSource: (versionSlug: string, versionDocsDir: string | undefined, lang: string, localeDir: string | undefined, options?: {
+        applyDefaultLocaleOnlyFilter?: boolean;
+        keepUnlisted?: boolean;
+    }) => NavSourceDocs;
+    /**
+     * Merge locale docs with base-locale fallbacks.
+     * Host passes `mergeLocaleDocs` from `pages/lib/locale-merge.ts`.
+     */
+    mergeLocaleDocs: (options: {
+        baseDocs: DocsEntryForTags[];
+        localeDocs: DocsEntryForTags[];
+        applyDefaultLocaleOnlyFilter?: boolean;
+        keepUnlisted?: boolean;
+        isDefaultLocaleOnlyPath?: (path: string) => boolean;
+    }) => {
+        docs: DocsEntryForTags[];
+        localeSlugSet: ReadonlySet<string>;
+    };
+}
+export interface RouteEnumeratorsAPI {
+    /**
+     * Enumerate all doc page URLs for a locale.
+     *
+     * For the default locale: loads the "docs" collection directly.
+     * For non-default locales: locale-first merge with EN fallback, with
+     * default-locale-only paths excluded. A nav-tree pass adds auto-generated
+     * category index pages.
+     */
+    enumerateDocsRoutes: (locale: string) => string[];
+    /**
+     * Enumerate tag-index and per-tag URLs for a locale.
+     *
+     * Returns `/docs/tags/` and `/docs/tags/{tag}/` for each unique tag.
+     */
+    enumerateTagsRoutes: (locale: string) => string[];
+    /**
+     * Enumerate doc URLs for a single (version, locale) combination.
+     *
+     * For the default locale: loads the versioned EN collection.
+     * For non-default locales: locale-first merge over the version's EN base.
+     */
+    enumerateVersionedRoutes: (version: VersionConfigForEnum, locale: string) => string[];
+    /**
+     * Compose all route enumerators into a deduped Map<url, lastmod>.
+     *
+     * Covers site root, default-locale docs + tags, per-locale docs + tags,
+     * versioned EN docs, and versioned locale docs.
+     */
+    enumerateAllRoutes: () => Map<string, string>;
+}
+/**
+ * Create the route-enumeration functions bound to the host's injected context.
+ *
+ * @example
+ * ```ts
+ * // pages/lib/route-enumerators.ts (thin stub)
+ * import { createRouteEnumerators } from "@takazudo/zudo-doc/route-enumerators";
+ * import { settings } from "@/config/settings";
+ * import { defaultLocale } from "@/config/i18n";
+ * import { docsUrl, versionedDocsUrl, withBase, isDefaultLocaleOnlyPath } from "@/utils/base";
+ * import { buildNavTree, collectAutoIndexNodes } from "@/utils/docs";
+ * import { collectTags } from "@/utils/tags";
+ * import { toRouteSlug } from "@/utils/slug";
+ * import { loadDocs } from "../_data";
+ * import { resolveNavSource, resolveVersionedLocaleSource } from "./_nav-source-docs";
+ * import { mergeLocaleDocs } from "./locale-merge";
+ *
+ * export const {
+ *   enumerateDocsRoutes,
+ *   enumerateTagsRoutes,
+ *   enumerateVersionedRoutes,
+ *   enumerateAllRoutes,
+ * } = createRouteEnumerators({
+ *   defaultLocale,
+ *   getLocaleKeys: () => Object.keys(settings.locales),
+ *   getVersions: () => settings.versions,
+ *   getDocTags: () => settings.docTags,
+ *   docsUrl,
+ *   versionedDocsUrl,
+ *   withBase,
+ *   loadDocs,
+ *   isDefaultLocaleOnlyPath,
+ *   collectTags,
+ *   toRouteSlug,
+ *   buildNavTree,
+ *   collectAutoIndexNodes,
+ *   resolveNavSource,
+ *   resolveVersionedLocaleSource,
+ *   mergeLocaleDocs,
+ * });
+ * ```
+ */
+export declare function createRouteEnumerators(ctx: RouteEnumeratorsContext): RouteEnumeratorsAPI;

package/dist/route-enumerators/index.js

@@ -0,0 +1,156 @@
+function createRouteEnumerators(ctx) {
+  const {
+    defaultLocale,
+    getLocaleKeys,
+    getVersions,
+    getDocTags,
+    docsUrl,
+    versionedDocsUrl,
+    withBase,
+    loadDocs,
+    isDefaultLocaleOnlyPath,
+    collectTags,
+    toRouteSlug,
+    buildNavTree,
+    collectAutoIndexNodes,
+    resolveNavSource,
+    resolveVersionedLocaleSource,
+    mergeLocaleDocs
+  } = ctx;
+  function enumerateDocsRoutes(locale) {
+    const urls = [];
+    const { docs: allDocs, navDocs, categoryMeta } = resolveNavSource(
+      locale,
+      void 0,
+      { applyDefaultLocaleOnlyFilter: true, keepUnlisted: true }
+    );
+    const tree = buildNavTree(navDocs, locale, categoryMeta);
+    for (const doc of allDocs) {
+      if (doc.data.category_no_page === true) continue;
+      urls.push(docsUrl(doc.data.slug ?? toRouteSlug(doc.id), locale));
+    }
+    for (const node of collectAutoIndexNodes(tree)) {
+      urls.push(docsUrl(node.slug, locale));
+    }
+    return [...new Set(urls)];
+  }
+  function enumerateTagsRoutes(locale) {
+    if (!getDocTags()) return [];
+    const urls = [];
+    const tagsBase = locale === defaultLocale ? "/docs/tags" : `/${locale}/docs/tags`;
+    urls.push(withBase(tagsBase));
+    let docs;
+    if (locale === defaultLocale) {
+      docs = loadDocs("docs").filter(
+        (d) => !d.data.unlisted && !d.data.draft && !d.data.category_no_page
+      );
+    } else {
+      const result = mergeLocaleDocs({
+        baseDocs: loadDocs("docs").filter((d) => !d.data.draft),
+        localeDocs: loadDocs(`docs-${locale}`).filter((d) => !d.data.draft),
+        applyDefaultLocaleOnlyFilter: true,
+        isDefaultLocaleOnlyPath
+      });
+      docs = result.docs.filter((d) => !d.data.category_no_page);
+    }
+    const tagMap = collectTags(docs, (id, data) => data.slug ?? toRouteSlug(id));
+    for (const tag of tagMap.keys()) {
+      const encoded = encodeURIComponent(tag);
+      const tagPath = locale === defaultLocale ? `/docs/tags/${encoded}` : `/${locale}/docs/tags/${encoded}`;
+      urls.push(withBase(tagPath));
+    }
+    return urls;
+  }
+  function enumerateVersionedRoutes(version, locale) {
+    const urls = [];
+    if (locale === defaultLocale) {
+      const { docs: allDocs, navDocs, categoryMeta } = resolveNavSource(
+        defaultLocale,
+        version.slug
+      );
+      const tree = buildNavTree(navDocs, defaultLocale, categoryMeta);
+      for (const doc of allDocs) {
+        if (doc.data.category_no_page === true) continue;
+        const slug = doc.data.slug ?? toRouteSlug(doc.id);
+        urls.push(versionedDocsUrl(slug, version.slug));
+      }
+      for (const node of collectAutoIndexNodes(tree)) {
+        urls.push(versionedDocsUrl(node.slug, version.slug));
+      }
+    } else {
+      const localeDir = version.locales?.[locale]?.dir;
+      const { docs: allDocs, navDocs, categoryMeta } = resolveVersionedLocaleSource(
+        version.slug,
+        version.docsDir,
+        locale,
+        localeDir,
+        { applyDefaultLocaleOnlyFilter: true, keepUnlisted: true }
+      );
+      const tree = buildNavTree(navDocs, locale, categoryMeta);
+      for (const doc of allDocs) {
+        if (doc.data.category_no_page === true) continue;
+        const slug = doc.data.slug ?? toRouteSlug(doc.id);
+        urls.push(versionedDocsUrl(slug, version.slug, locale));
+      }
+      for (const node of collectAutoIndexNodes(tree)) {
+        urls.push(versionedDocsUrl(node.slug, version.slug, locale));
+      }
+    }
+    return [...new Set(urls)];
+  }
+  function enumerateAllRoutes() {
+    const today = (/* @__PURE__ */ new Date()).toISOString().split("T")[0] ?? "";
+    const routes = /* @__PURE__ */ new Map();
+    const localeKeys = getLocaleKeys();
+    const versions = getVersions();
+    function add(url) {
+      if (!routes.has(url)) {
+        routes.set(url, today);
+      }
+    }
+    add(withBase("/"));
+    for (const url of enumerateDocsRoutes(defaultLocale)) {
+      add(url);
+    }
+    for (const url of enumerateTagsRoutes(defaultLocale)) {
+      add(url);
+    }
+    for (const locale of localeKeys) {
+      add(withBase(`/${locale}`));
+      for (const url of enumerateDocsRoutes(locale)) {
+        add(url);
+      }
+      for (const url of enumerateTagsRoutes(locale)) {
+        add(url);
+      }
+    }
+    if (versions) {
+      add(withBase("/docs/versions"));
+      for (const locale of localeKeys) {
+        add(withBase(`/${locale}/docs/versions`));
+      }
+    }
+    if (versions) {
+      for (const version of versions) {
+        for (const url of enumerateVersionedRoutes(version, defaultLocale)) {
+          add(url);
+        }
+        for (const locale of localeKeys) {
+          for (const url of enumerateVersionedRoutes(version, locale)) {
+            add(url);
+          }
+        }
+      }
+    }
+    return routes;
+  }
+  return {
+    enumerateDocsRoutes,
+    enumerateTagsRoutes,
+    enumerateVersionedRoutes,
+    enumerateAllRoutes
+  };
+}
+export {
+  createRouteEnumerators
+};

package/dist/routes/404.d.ts

@@ -0,0 +1,7 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+import type { JSX } from "preact";
+export declare const frontmatter: {
+    title: string;
+};
+export default function NotFoundPage(): JSX.Element;

package/dist/routes/404.js

@@ -0,0 +1,47 @@
+import { Fragment, jsx, jsxs } from "preact/jsx-runtime";
+import { DocLayoutWithDefaults } from "../doclayout/index.js";
+import { settings, defaultLocale, withBase } from "./_context.js";
+import {
+  HeadWithDefaults,
+  HeaderWithDefaults,
+  FooterWithDefaults,
+  BodyEndIslandsStub,
+  composeMetaTitle
+} from "./_chrome.js";
+const frontmatter = { title: "404" };
+function NotFoundPage() {
+  const locale = defaultLocale;
+  const title = "Page Not Found";
+  return /* @__PURE__ */ jsx(
+    DocLayoutWithDefaults,
+    {
+      title: composeMetaTitle(title),
+      head: /* @__PURE__ */ jsx(HeadWithDefaults, { title }),
+      lang: locale,
+      noindex: true,
+      hideSidebar: true,
+      hideToc: true,
+      sidebarOverride: /* @__PURE__ */ jsx(Fragment, {}),
+      headerOverride: /* @__PURE__ */ jsx(HeaderWithDefaults, { lang: locale }),
+      footerOverride: /* @__PURE__ */ jsx(FooterWithDefaults, { lang: locale }),
+      bodyEndComponents: /* @__PURE__ */ jsx(BodyEndIslandsStub, { basePath: settings.base ?? "/" }),
+      enableClientRouter: settings.dynamicPageTransition,
+      children: /* @__PURE__ */ jsxs("div", { class: "min-h-[60vh] flex flex-col items-center justify-center px-hsp-2xl py-vsp-xl", children: [
+        /* @__PURE__ */ jsx("h1", { class: "text-display font-bold mb-vsp-md", children: "404" }),
+        /* @__PURE__ */ jsx("p", { class: "text-title text-muted mb-vsp-xl", children: "Page not found." }),
+        /* @__PURE__ */ jsx(
+          "a",
+          {
+            href: withBase("/"),
+            class: "bg-accent px-hsp-lg py-vsp-xs font-medium text-bg hover:bg-accent-hover",
+            children: "Back to Home"
+          }
+        )
+      ] })
+    }
+  );
+}
+export {
+  NotFoundPage as default,
+  frontmatter
+};

package/dist/routes/_chrome.d.ts

@@ -0,0 +1,32 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+import type { JSX, VNode } from "preact";
+import type { DocNavNode } from "./_docs-helpers.js";
+/** Package no-op body-end islands. The host's `BodyEndIslands` wires project
+ *  island bootstraps (client-router / design-token-panel) that cannot live in
+ *  the package; the package default renders nothing. */
+declare function BodyEndIslandsStub(_props: {
+    basePath: string;
+}): JSX.Element;
+export declare const composeMetaTitle: (title: string) => string;
+export declare const HeadWithDefaults: (props: import("../head-with-defaults/index.js").HeadWithDefaultsProps) => JSX.Element;
+export declare const HeaderWithDefaults: (props: import("../header-with-defaults/index.js").HeaderWithDefaultsProps) => JSX.Element;
+export declare const FooterWithDefaults: (props: {
+    lang?: string;
+}) => VNode;
+export declare const SidebarWithDefaults: (props: import("../sidebar-with-defaults/index.js").SidebarWithDefaultsProps) => JSX.Element;
+declare const SiteTreeNavWrapper: (props: import("../site-tree-nav/index.js").SiteTreeNavWrapperProps) => JSX.Element | null;
+export declare function createMdxComponentsBound(lang?: string): Record<string, unknown>;
+export declare const renderDocPage: (props: import("../doc-page-props/index.js").DocPageBaseProps, opts: import("../doc-page-renderer/index.js").RenderDocPageOptions) => JSX.Element;
+export declare const VersionsPageView: (props: import("../versions-page/index.js").VersionsPageViewProps) => JSX.Element;
+export declare const collectTagMapForLocale: (locale: string) => Map<string, import("../tag-pages/index.js").TagInfo>, TagDetailPageView: (props: {
+    locale: string;
+    tag: string;
+    tagInfo: import("../tag-pages/index.js").TagInfo;
+}) => JSX.Element, TagsIndexPageView: (props: {
+    locale: string;
+    children?: import("preact").ComponentChildren;
+}) => JSX.Element;
+export { SiteTreeNavWrapper, BodyEndIslandsStub };
+export { buildDocRouteEntries, } from "./_context.js";
+export type { DocNavNode };