@takazudo/zudo-doc 5.24.2 → 5.26.0

package/dist/config-assertions/index.js

@@ -19,6 +19,16 @@ function assertNoEmptyStringFaviconOrLogo(settings) {
     }
   }
 }
+function resolvesBundleZdtp(settings) {
+  return settings.bundleZdtp ?? settings.designTokenPanel === true;
+}
+function assertZdtpBundlingConsistent(settings) {
+  if (settings.designTokenPanel === true && settings.bundleZdtp === false) {
+    throw new TypeError(
+      "Invalid combination: designTokenPanel: true with bundleZdtp: false. The package-owned design token panel needs @takazudo/zdtp in the build, but bundleZdtp: false shadows @takazudo/zudo-doc/zdtp-loader with a throwing stub, so the panel would fail to load at runtime. Drop bundleZdtp (it follows designTokenPanel by default), or set designTokenPanel: false if you only meant to keep zdtp out of the build."
+    );
+  }
+}
 function warnAmbiguousDropdownCategoryMatch(headerNav, logger = console) {
   if (!headerNav) return;
   for (const item of headerNav) {
@@ -60,5 +70,7 @@ function warnAmbiguousDropdownCategoryMatch(headerNav, logger = console) {
 }
 export {
   assertNoEmptyStringFaviconOrLogo,
+  assertZdtpBundlingConsistent,
+  resolvesBundleZdtp,
   warnAmbiguousDropdownCategoryMatch
 };

package/dist/config.d.ts

@@ -155,6 +155,16 @@ export interface ZudoDocConfig {
      * @default []
      */
     siteTreeNavIgnore?: string[];
+    /**
+     * Top-level category slugs moved OUT of the package-owned home-page category
+     * grid on `/` and locale homes and rendered instead as one row of small
+     * links directly under the grid, in this list's order. Home page only — the
+     * `<SiteTreeNav />` MDX tag is unchanged. Slugs absent from the tree are
+     * skipped, `siteTreeNavIgnore` wins over this list, and a category with no
+     * page of its own stays in the grid.
+     * @default []
+     */
+    siteTreeNavSecondary?: string[];
     /**
      * Minify production HTML output from `zfb build`.
      * @default true
@@ -330,6 +340,24 @@ export interface ZudoDocConfig {
      * @default false
      */
     designTokenPanel?: boolean;
+    /**
+     * Bundle `@takazudo/zdtp` into the island build. Controls ONLY whether
+     * `@takazudo/zudo-doc/zdtp-loader` resolves to the real zdtp re-export or to
+     * a throwing stub — it never mounts the package panel or its header trigger
+     * (that stays `designTokenPanel`'s job).
+     *
+     * Set it to `true` when the host mounts its OWN panel through
+     * `@takazudo/zudo-doc/design-token-panel-bootstrap` while leaving
+     * `designTokenPanel` off (#4261); otherwise the bootstrap's `loadZdtp()`
+     * hits the stub and rejects at runtime. The host must then have
+     * `@takazudo/zdtp` installed — it is an optional peer, and the build fails
+     * resolving `zdtp-loader` if it is missing.
+     *
+     * `designTokenPanel: true` with `bundleZdtp: false` is rejected at config
+     * resolution: a mounted package panel with a stubbed loader can only throw.
+     * @default undefined (follows designTokenPanel)
+     */
+    bundleZdtp?: boolean;
     /**
      * Minimum heading depth included in the TOC (2–4).
      * @default 2

package/dist/config.js

@@ -4,7 +4,10 @@ import { defaultDirectiveVocabulary } from "./directive-vocabulary-defaults/inde
 import { defaultTranslations } from "./i18n-defaults/index.js";
 import { defaultColorSchemes } from "./color-schemes-defaults/index.js";
 import { assertNoCommaInVersionSlugs } from "./version-availability/index.js";
-import { assertNoEmptyStringFaviconOrLogo } from "./config-assertions/index.js";
+import {
+  assertNoEmptyStringFaviconOrLogo,
+  assertZdtpBundlingConsistent
+} from "./config-assertions/index.js";
 import { validateAssetViewerSettings } from "./asset-path/index.js";
 function mergeDefaultTranslations(overrides) {
   if (overrides === void 0) return defaultTranslations;
@@ -47,6 +50,7 @@ const DEFAULT_SETTINGS = {
   trailingSlash: false,
   home: { wide: false, introMarkdown: "", sitemapHeading: "" },
   siteTreeNavIgnore: [],
+  siteTreeNavSecondary: [],
   minifyHtml: true,
   docsDir: "src/content/docs",
   entryDocSlug: "getting-started",
@@ -147,6 +151,7 @@ function zudoDoc(user = {}) {
   );
   assertNoCommaInVersionSlugs(settings.versions);
   assertNoEmptyStringFaviconOrLogo(settings);
+  assertZdtpBundlingConsistent(settings);
   const fragment = zudoDocPreset({
     settings,
     buildDocsSchema: userBuildDocsSchema ?? (() => defaultBuildDocsSchema({

package/dist/doc-pager/index.js

@@ -19,7 +19,7 @@ function createDocPager(ctx) {
               /* @__PURE__ */ jsx(ChevronLeft, { className: "h-[1.125rem] w-[1.125rem]" }),
               /* @__PURE__ */ jsx("span", { class: "no-underline", children: t("nav.previous", locale) })
             ] }),
-            /* @__PURE__ */ jsx("p", { class: "text-small font-semibold underline group-hover:text-accent", children: prev.label }),
+            /* @__PURE__ */ jsx("p", { class: "text-small font-semibold text-fg group-hover:text-accent group-hover:underline group-focus-visible:text-accent group-focus-visible:underline", children: prev.label }),
             prev.date && /* @__PURE__ */ jsx("p", { class: "text-caption text-muted", children: formatDate(prev.date, locale, dateFormatsFor(locale).full) })
           ]
         }
@@ -34,7 +34,7 @@ function createDocPager(ctx) {
               /* @__PURE__ */ jsx("span", { class: "no-underline", children: t("nav.next", locale) }),
               /* @__PURE__ */ jsx(ChevronRight, { className: "h-[1.125rem] w-[1.125rem]" })
             ] }),
-            /* @__PURE__ */ jsx("p", { class: "text-small font-semibold underline group-hover:text-accent", children: next.label }),
+            /* @__PURE__ */ jsx("p", { class: "text-small font-semibold text-fg group-hover:text-accent group-hover:underline group-focus-visible:text-accent group-focus-visible:underline", children: next.label }),
             next.date && /* @__PURE__ */ jsx("p", { class: "text-caption text-muted", children: formatDate(next.date, locale, dateFormatsFor(locale).full) })
           ]
         }

package/dist/footer/footer.js

@@ -6,7 +6,7 @@ function Footer(props) {
   const persistKey = props.persistKey;
   const hasColumns = linkColumns.length > 0 || tagColumns.length > 0;
   const hasCopyright = copyright.length > 0;
-  const copyrightClass = hasColumns ? "text-center text-caption text-muted [&_a]:text-accent [&_a]:underline mt-vsp-lg border-t border-muted pt-vsp-md" : "text-center text-caption text-muted [&_a]:text-accent [&_a]:underline";
+  const copyrightClass = hasColumns ? "text-center text-caption text-muted [&_a]:underline [&_a:hover]:text-accent [&_a:focus-visible]:text-accent mt-vsp-lg border-t border-muted pt-vsp-md" : "text-center text-caption text-muted [&_a]:underline [&_a:hover]:text-accent [&_a:focus-visible]:text-accent";
   return /* @__PURE__ */ jsx(
     "footer",
     {
@@ -25,7 +25,7 @@ function Footer(props) {
                   "a",
                   {
                     href: item.href,
-                    class: "text-caption text-muted hover:text-accent hover:underline focus-visible:underline",
+                    class: "text-caption text-muted hover:text-accent hover:underline focus-visible:text-accent focus-visible:underline",
                     ...item.isExternal ? {
                       target: "_blank",
                       rel: "noopener noreferrer"
@@ -47,7 +47,7 @@ function Footer(props) {
                   "a",
                   {
                     href,
-                    class: "text-caption text-muted hover:text-accent hover:underline focus-visible:underline",
+                    class: "text-caption text-muted hover:text-accent hover:underline focus-visible:text-accent focus-visible:underline",
                     children: [
                       "#",
                       tag,

package/dist/header/header.js

@@ -65,7 +65,8 @@ function Header(props) {
           "a",
           {
             href: urlHelpers.withBase(isNonDefaultLocale ? `/${lang}/` : "/"),
-            class: "whitespace-nowrap text-title font-bold text-fg hover:underline focus:underline shrink-0",
+            class: "min-w-0 truncate text-title font-bold text-fg hover:underline focus:underline",
+            title: siteName,
             "data-header-logo": true,
             children: siteName
           }

package/dist/header-with-defaults/index.d.ts

@@ -3,6 +3,7 @@
 import type { JSX } from "preact";
 import type { ChromeContext } from "../factory-context/index.js";
 import type { Settings } from "../settings.js";
+import type { SidebarNavNode } from "../sidebar/types.js";
 export interface HeaderWithDefaultsProps {
     /** Active locale; defaults to the configured defaultLocale. */
     lang?: string;
@@ -16,6 +17,25 @@ export interface HeaderWithDefaultsProps {
     navSection?: string;
     /** Omit the mobile sidebar toggle and its drawer landmark. */
     hideSidebarToggle?: boolean;
+    /**
+     * Override the mobile-drawer sidebar tree passed to `SidebarToggle`,
+     * resolved per render against that render's `lang`/`navSection`/
+     * `currentVersion`.
+     *
+     * - An array is passed to `SidebarToggle` as-is — no default build, no
+     *   version-href remapping.
+     * - A callback receives the resolved `lang`/`navSection`/`currentVersion`
+     *   plus a lazy `buildDefault()` that reproduces today's default tree
+     *   (`buildSidebarNodes(lang, navSection, currentVersion)`) only when
+     *   called.
+     * - Omitted: behavior is unchanged from before this prop existed.
+     */
+    sidebarNodes?: SidebarNavNode[] | ((args: {
+        lang: string;
+        navSection: string | undefined;
+        currentVersion: string | undefined;
+        buildDefault: () => SidebarNavNode[];
+    }) => SidebarNavNode[]);
 }
 /** Version config entry subset the factory reads. */
 export interface HeaderVersionEntry {

package/dist/header-with-defaults/index.js

@@ -39,14 +39,21 @@ function createHeaderWithDefaults(ctx) {
       currentVersion,
       currentSlug,
       navSection,
-      hideSidebarToggle = false
+      hideSidebarToggle = false,
+      sidebarNodes: sidebarNodesProp
     } = props;
     const lang = langProp;
     const rootMenuItems = buildRootMenuItems(lang, currentVersion);
     const backToMenuLabel = t("nav.backToMenu", lang);
     const localeLinks = buildLocaleLinksForNav(currentPath, lang, locales.length);
     const themeDefaultMode = getThemeDefaultMode();
-    const sidebarNodes = buildSidebarNodes(lang, navSection, currentVersion);
+    const buildDefaultSidebarNodes = () => buildSidebarNodes(lang, navSection, currentVersion);
+    const sidebarNodes = sidebarNodesProp === void 0 ? buildDefaultSidebarNodes() : typeof sidebarNodesProp === "function" ? sidebarNodesProp({
+      lang,
+      navSection,
+      currentVersion,
+      buildDefault: buildDefaultSidebarNodes
+    }) : sidebarNodesProp;
     const sidebarToggle = hideSidebarToggle ? false : Island({
       when: "visible",
       children: /* @__PURE__ */ jsx(

package/dist/home-page/index.js

@@ -16,6 +16,39 @@ import { prepareHomeData } from "./prepare-home-data.js";
 function HomeSectionHeading({ children }) {
   return /* @__PURE__ */ jsx("h2", { class: `${HOME_SECTION_HEADING_CLASS} mb-vsp-md`, children });
 }
+function HomeMetaLink({ href, children }) {
+  return /* @__PURE__ */ jsxs(
+    "a",
+    {
+      href,
+      class: "group inline-flex items-center gap-hsp-xs text-small text-fg hover:text-accent hover:underline focus-visible:text-accent focus-visible:underline",
+      children: [
+        /* @__PURE__ */ jsx(CategoryLinkIcon, { className: "w-icon-sm text-muted group-hover:text-accent group-focus-visible:text-accent" }),
+        /* @__PURE__ */ jsx("span", { children })
+      ]
+    }
+  );
+}
+function selectSecondaryNodes(tree, secondary, categoryIgnore) {
+  const moved = [];
+  const seen = new Set(categoryIgnore);
+  for (const slug of secondary) {
+    if (seen.has(slug)) continue;
+    seen.add(slug);
+    const node = tree.find((n) => n.slug === slug);
+    if (!node) continue;
+    if (!node.href) {
+      if (typeof process !== "undefined" && process.env?.NODE_ENV !== "production") {
+        console.warn(
+          `[zudo-doc] siteTreeNavSecondary: category "${slug}" has no page (href) \u2014 left in the grid`
+        );
+      }
+      continue;
+    }
+    moved.push(node);
+  }
+  return moved;
+}
 function cssUrl(url) {
   return `url("${url.replace(/[\\"]/g, "\\$&")}")`;
 }
@@ -24,6 +57,7 @@ function createHomePageView(ctx) {
   const settings = ctx.settings;
   const dateFormatsFor = deriveDateFormats(ctx);
   const categoryIgnore = settings.siteTreeNavIgnore ?? [];
+  const secondary = settings.siteTreeNavSecondary ?? [];
   const t = ctx.t;
   const withBase = ctx.withBase;
   const defaultLocale = ctx.defaultLocale;
@@ -64,6 +98,7 @@ function createHomePageView(ctx) {
       t("home.sitemapHeading", locale)
     ).sitemapHeading;
     const hasExtras = resolvedExtras != null && typeof resolvedExtras !== "boolean";
+    const movedNodes = selectSecondaryNodes(tree, secondary, categoryIgnore);
     const rowItems = [];
     if (primary) {
       rowItems.push(
@@ -133,7 +168,7 @@ function createHomePageView(ctx) {
               }
             ) : null,
             /* @__PURE__ */ jsxs("div", { class: "zd-home-copy min-w-0 lg:flex-1", children: [
-              /* @__PURE__ */ jsx("h1", { class: "text-heading font-bold mb-vsp-2xs break-words", children: settings.siteName }),
+              /* @__PURE__ */ jsx("h1", { class: "text-heading font-bold mb-vsp-2xs wrap-anywhere", children: settings.siteName }),
               /* @__PURE__ */ jsx("p", { class: "text-muted text-small mb-vsp-sm", children: rawDescription }),
               /* @__PURE__ */ jsx("div", { class: "zd-home-links flex flex-wrap items-center justify-center lg:justify-start gap-hsp-md text-small", children: rowItems.map((item, index) => /* @__PURE__ */ jsxs(Fragment2, { children: [
                 index > 0 && /* @__PURE__ */ jsx("span", { class: "text-muted", children: "/" }),
@@ -155,14 +190,23 @@ function createHomePageView(ctx) {
                 {
                   tree,
                   categoryOrder,
-                  categoryIgnore,
+                  categoryIgnore: [...categoryIgnore, ...movedNodes.map((n) => n.slug)],
                   initiallyCollapsedCategorySlugs,
                   locale,
                   updatedLabel: t("doc.updated", locale),
                   dateFormats: dateFormatsFor(locale)
                 }
               )
-            })
+            }),
+            movedNodes.length > 0 && /* @__PURE__ */ jsx(
+              "nav",
+              {
+                "aria-label": t("home.secondaryNav", locale),
+                "data-home-secondary-nav": true,
+                class: "mt-vsp-md flex flex-wrap items-center gap-x-hsp-xl gap-y-vsp-xs",
+                children: movedNodes.map((n) => /* @__PURE__ */ jsx(HomeMetaLink, { href: n.href, children: n.label }, n.slug))
+              }
+            )
           ] }),
           settings.docTags && tagCount > 0 && /* @__PURE__ */ jsxs(Fragment, { children: [
             /* @__PURE__ */ jsx("hr", { class: "zd-home-rule", "data-home-rule": "tags" }),
@@ -180,31 +224,14 @@ function createHomePageView(ctx) {
                 }
               ),
               tags.length > tagLimit && /* @__PURE__ */ jsx("div", { class: "mt-vsp-sm text-title text-muted", "aria-hidden": "true", children: "\u2026" }),
-              /* @__PURE__ */ jsx("div", { class: "mt-vsp-md", children: /* @__PURE__ */ jsxs(
-                "a",
-                {
-                  href: withBase(`${prefix}/docs/tags`),
-                  class: "group inline-flex items-center gap-hsp-xs text-accent hover:underline",
-                  children: [
-                    /* @__PURE__ */ jsx(CategoryLinkIcon, { className: "w-icon-sm text-accent" }),
-                    /* @__PURE__ */ jsx("span", { children: t("doc.seeAllTags", locale) })
-                  ]
-                }
-              ) })
+              /* @__PURE__ */ jsx("div", { class: "mt-vsp-md", children: /* @__PURE__ */ jsx(HomeMetaLink, { href: withBase(`${prefix}/docs/tags`), children: t("doc.seeAllTags", locale) }) })
             ] }) : (
               // Legacy fallback: caller passed only `tagCount` (no tag list) —
               // reproduce the pre-#3027 single "All Tags" link so existing
               // `@takazudo/zudo-doc/home-page` consumers are unaffected.
               /* @__PURE__ */ jsxs(Fragment, { children: [
                 /* @__PURE__ */ jsx(HomeSectionHeading, { children: t("doc.allTags", locale) }),
-                /* @__PURE__ */ jsx(
-                  "a",
-                  {
-                    href: withBase(`${prefix}/docs/tags`),
-                    class: "text-accent underline hover:text-accent-hover",
-                    children: t("doc.allTags", locale)
-                  }
-                )
+                /* @__PURE__ */ jsx(HomeMetaLink, { href: withBase(`${prefix}/docs/tags`), children: t("doc.allTags", locale) })
               ] })
             ) })
           ] })

package/dist/i18n-defaults/index.js

@@ -1,6 +1,7 @@
 const defaultTranslations = {
   en: {
     "home.sitemapHeading": "Explore the documentation",
+    "home.secondaryNav": "More categories",
     "nav.gettingStarted": "Getting Started",
     "nav.learn": "Learn",
     "nav.guides": "Guides",
@@ -130,6 +131,7 @@ const defaultTranslations = {
   },
   ja: {
     "home.sitemapHeading": "\u30C9\u30AD\u30E5\u30E1\u30F3\u30C8\u3092\u63A2\u3059",
+    "home.secondaryNav": "\u305D\u306E\u4ED6\u306E\u30AB\u30C6\u30B4\u30EA",
     "nav.gettingStarted": "\u306F\u3058\u3081\u306B",
     "nav.learn": "\u5B66\u3076",
     "nav.guides": "\u30AC\u30A4\u30C9",
@@ -258,6 +260,7 @@ const defaultTranslations = {
     "version.page.docs": "\u30C9\u30AD\u30E5\u30E1\u30F3\u30C8"
   },
   de: {
+    "home.secondaryNav": "Weitere Kategorien",
     "nav.gettingStarted": "Erste Schritte",
     "nav.learn": "Lernen",
     "nav.guides": "Anleitungen",

package/dist/integrations/changelog/generate.js

@@ -1,3 +1,8 @@
+import {
+  buildChangelogAnchorMap,
+  formatChangelogEntryHeadingText,
+  rewriteChangelogEntryLinks
+} from "./links.js";
 function generateChangelogMarkdown(entries, options = {}) {
   const title = options.title ?? "Changelog";
   const lines = [`# ${title}`, ""];
@@ -8,12 +13,13 @@ function generateChangelogMarkdown(entries, options = {}) {
   }
   lines.push("");
   lines.push("The format is based on Keep a Changelog, and release notes are generated from the changelog MDX pages.");
+  const anchorsByFilename = buildChangelogAnchorMap(title, entries);
   for (const entry of entries) {
     lines.push("");
-    lines.push(entry.date ? `## [${entry.version}] - ${entry.date}` : `## [${entry.version}]`);
+    lines.push(`## ${formatChangelogEntryHeadingText(entry)}`);
     if (entry.content) {
       lines.push("");
-      lines.push(entry.content);
+      lines.push(rewriteChangelogEntryLinks(entry.content, anchorsByFilename));
     }
   }
   lines.push("");

package/dist/integrations/changelog/links.d.ts

@@ -0,0 +1,25 @@
+import type { ChangelogEntry } from "./types.js";
+/**
+ * Heading text shared by the emitted `## [version] - date` line and the
+ * anchor map, so the two cannot drift out of step with each other.
+ */
+export declare function formatChangelogEntryHeadingText(entry: Pick<ChangelogEntry, "version" | "date">): string;
+/**
+ * Build the anchor map (exact source filename -> in-file anchor) for a full
+ * generated changelog document. Anchors must reflect the WHOLE document's
+ * heading order, not just the version headings: the `# <title>` line and any
+ * ATX or setext headings inside entry bodies consume slugs too, and an earlier
+ * entry's body heading can shift a later entry's anchor via GitHub's `-1`,
+ * `-2`, … de-duplication.
+ */
+export declare function buildChangelogAnchorMap(title: string, entries: readonly ChangelogEntry[]): ReadonlyMap<string, string>;
+/**
+ * Rewrite one entry's already-sanitized markdown content: same-directory
+ * `.md`/`.mdx` links to another emitted entry become an in-file anchor link
+ * (`#<anchor>`, original `#fragment` dropped, title preserved); any other
+ * relative `.md`/`.mdx` link is unlinked to its label text. Everything else
+ * (absolute URLs, protocol-relative, root-absolute, pure fragments, images,
+ * other extensions, reference-style links, and anything inside fenced or
+ * inline code) passes through byte-unchanged.
+ */
+export declare function rewriteChangelogEntryLinks(content: string, anchorByFilename: ReadonlyMap<string, string>): string;