@takazudo/zudo-doc 4.4.13 → 5.0.0

package/dist/version-availability/index.js

@@ -0,0 +1,56 @@
+function createGetUnavailableVersions(deps) {
+  const availableSlugCache = /* @__PURE__ */ new Map();
+  function getAvailableSlugs(locale, versionSlug) {
+    const key = `${locale}
+${versionSlug}`;
+    const cached = availableSlugCache.get(key);
+    if (cached) return cached;
+    const { docs, navDocs, categoryMeta } = deps.resolveNavSource(locale, versionSlug, {
+      applyDefaultLocaleOnlyFilter: true,
+      keepUnlisted: true
+    });
+    const slugs = /* @__PURE__ */ new Set();
+    for (const d of docs) {
+      if (d.data.category_no_page === true) continue;
+      slugs.add(d.data.slug ?? deps.toRouteSlug(d.slug));
+    }
+    const tree = deps.buildNavTree(navDocs, locale, categoryMeta);
+    for (const node of deps.collectAutoIndexNodes(tree)) {
+      slugs.add(node.slug);
+    }
+    availableSlugCache.set(key, slugs);
+    return slugs;
+  }
+  return function getUnavailableVersions(slug, locale) {
+    if (slug === void 0) return void 0;
+    if (!deps.versions || deps.versions.length === 0) return void 0;
+    const unavailable = /* @__PURE__ */ new Set();
+    for (const v of deps.versions) {
+      if (!getAvailableSlugs(locale, v.slug).has(slug)) {
+        unavailable.add(v.slug);
+      }
+    }
+    return unavailable;
+  };
+}
+const UNAVAILABLE_VERSIONS_ATTR = "data-doc-unavailable-versions";
+function serializeUnavailableVersions(unavailableVersions) {
+  if (unavailableVersions === void 0) return {};
+  return { [UNAVAILABLE_VERSIONS_ATTR]: Array.from(unavailableVersions).sort().join(",") };
+}
+function assertNoCommaInVersionSlugs(versions) {
+  if (!versions) return;
+  for (const v of versions) {
+    if (v.slug.includes(",")) {
+      throw new TypeError(
+        `Invalid version slug "${v.slug}": version slugs must not contain commas (commas are the delimiter in the version-switcher's client-side availability payload \u2014 see version-availability/index.ts).`
+      );
+    }
+  }
+}
+export {
+  UNAVAILABLE_VERSIONS_ATTR,
+  assertNoCommaInVersionSlugs,
+  createGetUnavailableVersions,
+  serializeUnavailableVersions
+};

package/dist/versions-page/index.d.ts

@@ -15,6 +15,11 @@ export interface VersionsPageSettings {
     dynamicPageTransition?: boolean;
     versions: VersionsPageVersionEntry[] | false;
     base: string;
+    /**
+     * Route slug of the doc page linked as "latest docs" / each version's docs
+     * entry point. Defaults to `"getting-started"` when omitted.
+     */
+    entryDocSlug?: string;
 }
 /** Host-supplied component bindings injected into the versions page factory. */
 export interface VersionsPageComponents {
@@ -32,7 +37,10 @@ export interface VersionsPageComponents {
         basePath: string;
     }) => JSX.Element;
 }
-/** Injected dependencies for {@link createVersionsPageView}. */
+/**
+ * Legacy shape, unused by createVersionsPageView — reads ChromeContext
+ * directly; do not extend.
+ */
 export interface VersionsPageDeps {
     settings: VersionsPageSettings;
     /** Default locale code (e.g. `"en"`). */

package/dist/versions-page/index.js

@@ -12,6 +12,7 @@ function createVersionsPageView(ctx) {
   const defaultLocale = ctx.defaultLocale;
   const t = ctx.t;
   const withBase = ctx.withBase;
+  const isDefaultLocaleOnlyPath = ctx.isDefaultLocaleOnlyPath;
   const composeMetaTitle = deriveComposeMetaTitle(ctx);
   const HeadWithDefaults = createHeadWithDefaults(ctx);
   const { Header: HeaderWithDefaults, Footer: FooterWithDefaults } = derivePrimaryChromeSlots(ctx);
@@ -37,13 +38,16 @@ function createVersionsPageView(ctx) {
       statusCol: t("version.page.status", locale),
       docsCol: t("version.page.docs", locale)
     };
-    const latestHref = withBase(`${prefix}/docs/getting-started`);
+    const entryDocSlug = settings.entryDocSlug ?? "getting-started";
+    const entryDocPath = `/docs/${entryDocSlug}`;
+    const entryDocPrefix = isDefaultLocaleOnlyPath(entryDocPath) ? "" : prefix;
+    const latestHref = withBase(`${entryDocPrefix}${entryDocPath}`);
     const versions = 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/`),
+      docsHref: withBase(`/v/${v.slug}${entryDocPrefix}/docs/${entryDocSlug}/`),
       banner: v.banner
     })) : [];
     return /* @__PURE__ */ jsx(

package/eject/header/header.tsx

@@ -76,6 +76,7 @@ export interface HeaderUrlHelpers {
     path: string,
     lang?: Locale,
     currentVersion?: string,
+    versioned?: boolean,
   ): string;
 }
 
@@ -444,7 +445,7 @@ function renderNavItem(
   const isActive =
     isNavItemActiveByCategory(item, activeCategory) ||
     isNavItemActive(item, activeNavPath);
-  const href = urlHelpers.navHref(item.path, lang, currentVersion);
+  const href = urlHelpers.navHref(item.path, lang, currentVersion, item.versioned);
   const label = item.labelKey ? i18n.t(item.labelKey, lang) : item.label;
 
   if (item.children && item.children.length > 0) {
@@ -488,7 +489,7 @@ function renderNavItem(
         <div class="absolute left-0 top-full z-dropdown hidden group-hover:block group-focus-within:block pt-vsp-3xs">
           <div class="min-w-[10rem] border border-muted rounded bg-surface shadow-lg py-vsp-3xs">
             {item.children.map((child) => {
-              const childHref = urlHelpers.navHref(child.path, lang, currentVersion);
+              const childHref = urlHelpers.navHref(child.path, lang, currentVersion, child.versioned);
               const childLabel = child.labelKey
                 ? i18n.t(child.labelKey, lang)
                 : child.label;

package/eject/header/types.ts

@@ -26,6 +26,13 @@ export interface HeaderNavChildItem {
   labelKey?: string;
   path: string;
   categoryMatch?: string;
+  /**
+   * Whether links built from this item's `path` carry the active `/v/{version}`
+   * prefix. `false` targets a route that has no versioned counterpart, so its
+   * href must stay unversioned even when rendered under an active version.
+   * Default `true`.
+   */
+  versioned?: boolean;
 }
 
 export interface HeaderNavItem extends HeaderNavChildItem {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takazudo/zudo-doc",
-  "version": "4.4.13",
+  "version": "5.0.0",
   "type": "module",
   "description": "zudo-doc framework primitives layer that sits on top of zfb's engine — sidebar, theme, TOC, breadcrumb, layouts, head injection, View Transitions, SSR-skip wrappers (per ADR-003).",
   "license": "MIT",
@@ -227,6 +227,14 @@
       "types": "./dist/home-page/index.d.ts",
       "default": "./dist/home-page/index.js"
     },
+    "./desktop-toc-toggle-island": {
+      "types": "./dist/desktop-toc-toggle-island/index.d.ts",
+      "default": "./dist/desktop-toc-toggle-island/index.js"
+    },
+    "./toc-prepaint": {
+      "types": "./dist/toc-prepaint/index.d.ts",
+      "default": "./dist/toc-prepaint/index.js"
+    },
     "./theme.css": "./dist/theme.css",
     "./safelist.css": "./dist/safelist.css",
     "./content.css": "./dist/content.css",
@@ -598,10 +606,10 @@
   ],
   "peerDependencies": {
     "@takazudo/zdtp": "^0.4.9",
-    "@takazudo/zfb": "^0.1.0-next.99",
-    "@takazudo/zfb-md-wasm": "^0.1.0-next.99",
-    "@takazudo/zfb-runtime": "^0.1.0-next.99",
-    "@takazudo/zudo-doc-history-server": "^4.4.11",
+    "@takazudo/zfb": "^2.1.0",
+    "@takazudo/zfb-md-wasm": "^2.1.0",
+    "@takazudo/zfb-runtime": "^2.1.0",
+    "@takazudo/zudo-doc-history-server": "^5.0.0",
     "diff": "^8.0.0",
     "katex": "^0.16.0",
     "preact": "^10.29.1",
@@ -635,15 +643,14 @@
     "tsx": "^4.21.0"
   },
   "devDependencies": {
-    "@takazudo/zfb": "0.1.0-next.99",
-    "@takazudo/zfb-md-wasm": "0.1.0-next.99",
-    "@takazudo/zfb-runtime": "0.1.0-next.99",
+    "@takazudo/zfb": "2.1.0",
+    "@takazudo/zfb-md-wasm": "2.1.0",
+    "@takazudo/zfb-runtime": "2.1.0",
     "@types/fs-extra": "^11.0.4",
     "@types/minimist": "^1.2.5",
     "@types/node": "^25.3.5",
     "@types/pluralize": "^0.0.33",
     "@types/string-similarity": "^4.0.2",
-    "cross-env": "^7.0.3",
     "happy-dom": "^20.10.6",
     "npm-run-all2": "^7.0.2",
     "preact": "^10.29.1",
@@ -652,7 +659,7 @@
     "typescript": "^5.0.0",
     "vitest": "^4.1.0",
     "zod": "^4.3.6",
-    "@takazudo/zudo-doc-history-server": "4.4.13"
+    "@takazudo/zudo-doc-history-server": "5.0.0"
   },
   "scripts": {
     "build": "tsup && tsc -p tsconfig.build.json",

package/tsconfig.base.json

@@ -13,7 +13,8 @@
     "esModuleInterop": true,
     "skipLibCheck": true,
     "allowJs": true,
-    "jsx": "preserve",
+    "jsx": "react-jsx",
+    "jsxImportSource": "preact",
     "strict": true,
     "noImplicitAny": true,
     "strictNullChecks": true,

package/zfb-config-shim.d.ts

@@ -1,210 +1,28 @@
-// Package-shipped type shim for the bare `zfb/config` specifier (#2656).
+// Package-shipped type shim for the bare `zfb/config` specifier (#2656, #3237).
 //
-// `@takazudo/zfb` is consumed as a published npm package. The package
-// exposes its real config types under the *scoped* subpath
-// `@takazudo/zfb/config` → `dist/config.d.ts`. But `zfb.config.ts` imports
-// from the *bare* specifier `zfb/config`, which zfb's build tool aliases to
-// a runtime-only stub at parse time (`zfb-config-stub.mjs` — `defineConfig`
-// is identity, carrying no types). No real file backs `zfb/config` in
-// `node_modules`, so this ambient declaration is what supplies the
-// `ZfbConfig` type to `zfb.config.ts`.
+// `zfb.config.ts` imports from the *bare* specifier `zfb/config`, which zfb's
+// config loader aliases to a runtime-only stub at parse time
+// (`zfb-config-stub.mjs` — `defineConfig` is identity, carrying no types). No
+// real file backs `zfb/config` in `node_modules`, so an ambient declaration is
+// what supplies its type. An ambient `declare module` wins over node
+// resolution AND over tsconfig `paths`, so this file — not any `paths` entry —
+// is what `zfb check` (plain `tsc --noEmit`) binds `zfb.config.ts` against.
 //
-// Pulled into a consuming project via `tsconfig.base.json`'s
-// `files: ["./zfb-config-shim.d.ts", "./virtual-modules.d.ts"]` — a project
-// extending the base no longer needs its own local `zfb-shim.d.ts`.
+// It re-exports the real, installed `@takazudo/zfb/config` rather than
+// restating its shape. There is NO hand-sync duty: this file tracks whatever
+// `@takazudo/zfb` version the consumer has installed, automatically. The
+// previous hand-copied field list drifted twice — `bundle`
+// (Takazudo/zudo-front-builder#678 + zudolab/zudo-doc#1834) and then 12
+// top-level fields including `copyPublicWithBase` (#3237) — each drift
+// surfacing as a TS2353 on a config field the engine already honoured.
+//
+// Do NOT add a top-level `import`/`export` to this file: that would turn it
+// into a module and the `declare module` would stop being ambient. The
+// `export *` must stay INSIDE the block.
 //
-// IMPORTANT — this block is the source of truth for the type `zfb check`
-// (plain `tsc --noEmit`) binds against the config. An ambient `declare
-// module` wins over node resolution AND over tsconfig `paths`, so it must
-// be kept in sync BY HAND with the published `@takazudo/zfb/config`
-// (`dist/config.d.ts`). When it lags the engine, valid config fields fail
-// `pnpm check` with TS2353 (see Takazudo/zudo-front-builder#678 +
-// zudolab/zudo-doc#1834 — `bundle` was missing here, blocking next.22's
-// `bundle.exclude`). See `packages/zudo-doc/CLAUDE.md` ("Shipped ambient
-// type shims") for the hand-sync duty this file carries.
+// Pulled into a consuming project via `tsconfig.base.json`'s
+// `files: ["./zfb-config-shim.d.ts", "./virtual-modules.d.ts"]`.
 
 declare module "zfb/config" {
-  /** JSX framework runtime. */
-  export type Framework = "preact" | "react";
-
-  /** A content collection registered with the zfb engine. */
-  export interface CollectionDef {
-    /** Identifier used at the call site (e.g. `"docs"`). */
-    name: string;
-    /** Directory (relative to the project root) holding the entries. */
-    path: string;
-    /**
-     * Optional schema. Reserved for v1.1 — accepted but not enforced
-     * today. Authored as zod and converted to JSON Schema via
-     * `z.toJSONSchema()` at the boundary.
-     */
-    schema?: Record<string, unknown>;
-  }
-
-  /** Tailwind options; absent = defaults. */
-  export interface TailwindConfig {
-    enabled?: boolean;
-  }
-
-  /** User-supplied plugin configuration entry. */
-  export interface PluginConfig {
-    name: string;
-    options?: Record<string, unknown>;
-  }
-
-  /** Output mode for zfb fenced-code highlighting. */
-  export type CodeHighlightMode = "inline" | "class";
-
-  /** Fixed semantic taxonomy accepted by class-mode `roleClasses`. */
-  export type CodeHighlightRole =
-    | "escape"
-    | "operator"
-    | "comment"
-    | "string"
-    | "number"
-    | "constant"
-    | "keyword"
-    | "function"
-    | "type"
-    | "namespace"
-    | "property"
-    | "variable"
-    | "tag"
-    | "attribute"
-    | "punctuation"
-    | "inserted"
-    | "deleted"
-    | "heading";
-
-  /** zfb inline-theme or semantic class-mode configuration. */
-  export type CodeHighlightConfig = {
-    theme?: string;
-    themesDir?: string;
-    themeLight?: string;
-    themeDark?: string;
-    mode?: CodeHighlightMode;
-    classPrefix?: string;
-    roleClasses?: Partial<Record<CodeHighlightRole, string>>;
-    defaultStylesheet?: boolean;
-  };
-
-  /**
-   * Bundler options. Mirrors `BundleConfig` in crates/zfb/src/config.rs
-   * and the published `@takazudo/zfb/config` (`dist/config.d.ts`). Added
-   * in next.22 (`bundle.exclude`, #664) and extended in next.23
-   * (`mainFields` / `external`, #676).
-   */
-  export interface BundleConfig {
-    /**
-     * Project-relative, gitignore-style globs for source files the bundler
-     * must NOT pull into the esbuild graph (e.g. test fixtures or
-     * `*.stories.tsx`). Matched files are skipped from the shadow-tree walk
-     * and dropped from any eager `import.meta.glob(...)` expansion.
-     */
-    exclude?: string[];
-    /**
-     * Explicit esbuild `main-fields` for the `--platform=neutral` page/SSR
-     * pass (empty by default under `neutral`), letting CJS-`main`-only deps
-     * resolve. Mirrors `BundleConfig::main_fields`.
-     */
-    mainFields?: string[];
-    /**
-     * Bare specifiers to mark external in the `--platform=neutral` pass so
-     * esbuild leaves them unbundled. Mirrors `BundleConfig::external`.
-     */
-    external?: string[];
-  }
-
-  /** Mirrors the Rust `Config` struct one-for-one. */
-  export interface ZfbConfig {
-    outDir?: string;
-    publicDir?: string;
-    host?: string;
-    port?: number;
-    framework?: Framework;
-    collections?: CollectionDef[];
-    tailwind?: TailwindConfig;
-    /**
-     * Bundler options. `bundle.exclude` keeps project-relative globs out of
-     * the esbuild graph — used e.g. to skip `e2e/fixtures/**` so the MDX link
-     * resolver doesn't walk committed test-fixture trees (silences spurious
-     * broken-link warnings). Mirrors `Config::bundle`.
-     */
-    bundle?: BundleConfig;
-    plugins?: PluginConfig[];
-    adapter?: string;
-    /**
-     * Strip `.md` / `.mdx` from in-page `<a href>` paths and append a
-     * trailing `/` so author-written `[label](other.mdx)` references
-     * resolve to the rendered route URL. Mirrors Config::strip_md_ext
-     * in crates/zfb/src/config.rs (zudolab/zfb#131).
-     */
-    stripMdExt?: boolean;
-    /**
-     * Site base path. Prefixed onto stable HTML asset URLs (CSS / JS
-     * `<link>` and `<script>` tags). Normalised to start AND end with
-     * `/`; `undefined` / `""` / `"/"` all behave identically (no
-     * prefix). Mirrors Config::base in crates/zfb/src/config.rs
-     * (Takazudo/zudo-front-builder#154).
-     */
-    base?: string;
-    /**
-     * Configures zfb's code highlighter. Class mode is mutually exclusive
-     * with every theme field and emits semantic role classes; inline mode
-     * retains the single/dual theme fields for general zfb consumers.
-     */
-    codeHighlight?: CodeHighlightConfig;
-    /**
-     * Markdown link resolver (port of `remarkResolveMarkdownLinks`).
-     * Mirrors `Config::resolve_markdown_links` in crates/zfb/src/config.rs
-     * (Takazudo/zudo-front-builder PR #234 / zudolab/zudo-doc#1577).
-     * When `enabled: true`, the build appends `ResolveLinksPlugin` to the
-     * mdast pipeline so author-written `[label](./other.mdx)` links are
-     * rewritten to the corresponding rendered route URL — bypassing the
-     * file→directory transformation that breaks relative paths in dist
-     * HTML when `foo.mdx` becomes `foo/index.html`.
-     */
-    resolveMarkdownLinks?: {
-      enabled?: boolean;
-      docsDir?: string;
-      dirs?: Array<{ dir: string; routePrefix: string }>;
-      onBrokenLinks?: "warn" | "error" | "ignore";
-    };
-    /**
-     * Whether the basePath rewriter should append a trailing `/` to
-     * extensionless absolute hrefs. Mirrors `Config::trailing_slash` in
-     * crates/zfb/src/config.rs (Takazudo/zudo-front-builder PR #234 /
-     * zudolab/zudo-doc#1579). Off by default — preserves byte-for-byte
-     * parity with the pre-`trailingSlash` build for projects that
-     * haven't opted in.
-     */
-    trailingSlash?: boolean;
-    /**
-     * Minify production HTML output from `zfb build`.
-     * Mirrors `Config::minify_html` in crates/zfb/src/config.rs.
-     */
-    minifyHtml?: boolean;
-    /**
-     * Markdown / MDX pipeline options. Mirrors `Config::markdown` →
-     * `MarkdownConfig` in crates/zfb/src/config.rs. zfb next.12 moved the
-     * former-Core features under `markdown.features` and next.13 ships the
-     * rest as opt-in; zudo-doc uses `markdown.features` to opt back into the
-     * former-Core four plus the additional opt-in features (#1804). Each
-     * `features` value is per-feature: `true` for boolean-shorthand features,
-     * or an options object for object-typed features.
-     */
-    markdown?: {
-      gfm?: boolean | Record<string, boolean>;
-      toc?: Record<string, unknown>;
-      externalLinks?: Record<string, unknown>;
-      cjkFriendly?: boolean;
-      features?: Record<string, boolean | Record<string, unknown>>;
-    };
-  }
-
-  /**
-   * Identity helper: returns the supplied config as-is, but typed
-   * against `ZfbConfig`. Use as the default export of `zfb.config.ts`.
-   */
-  export function defineConfig(config: ZfbConfig): ZfbConfig;
+  export * from "@takazudo/zfb/config";
 }