@takazudo/zudo-doc 4.3.0 → 4.4.0

package/eject/header/nav-class-tokens.ts

@@ -0,0 +1,115 @@
+// Single source of truth for the header desktop-nav class tokens that must
+// stay in lockstep between the SSR markup (`header.tsx`) and the runtime
+// rebuild/toggle script (`nav-overflow-script.ts`).
+//
+// WHY THIS MODULE EXISTS: the same class strings used to live, duplicated, in
+// both files. `header.tsx` paints the active nav item on first render; the
+// inline script re-paints it after SPA navigation and rebuilds the "···"
+// overflow menu — so both files have to agree on the exact class lists. That
+// duplicated knowledge drifted twice (zudolab/zudo-doc#3011 stale-class after
+// navigation, #3016 divergence), each caught only by a throwaway script. Both
+// files now derive their class strings from the arrays below, so the two can
+// no longer silently diverge (guard: #3023).
+//
+// Tokens are ARRAYS, not whole strings, because the two consumers need
+// different shapes: `header.tsx` joins them into `class={}` attributes, while
+// the script both spreads them into `classList.add/remove(...)` calls and
+// joins them into `className` assignments. Keeping them composable per-part
+// also lets the overflow-menu recipes (which intentionally differ from the
+// header-bar items in padding/weight/base) reuse the shared color tokens
+// instead of re-typing them.
+
+// ── Header-bar top-level item: active-state color toggle ─────────────────
+// setTopActive() (script) ↔ the top-level <a> in renderNavItem() (SSR).
+export const NAV_TOP_ACTIVE: readonly string[] = ["bg-fg", "text-bg"];
+export const NAV_TOP_INACTIVE: readonly string[] = [
+  "text-muted",
+  "hover:text-accent",
+  "hover:underline",
+  "focus:underline",
+  "focus:text-accent",
+];
+
+// ── Header-bar dropdown chevron SVG: active-state color toggle ───────────
+// applyActiveNav() (script) ↔ the chevron <svg> in renderNavItem() (SSR).
+export const NAV_CHEVRON_ACTIVE: readonly string[] = ["text-bg"];
+export const NAV_CHEVRON_INACTIVE: readonly string[] = ["text-muted"];
+
+// ── Header-bar dropdown child link: active-state color toggle ────────────
+// applyActiveNav() (script) ↔ the child <a> in renderNavItem() (SSR). The
+// static base (`block px-hsp-md ... focus-visible:underline`) stays inline in
+// header.tsx — the script never rewrites it, so it can't drift across files.
+export const NAV_CHILD_ACTIVE: readonly string[] = ["font-bold", "text-accent"];
+export const NAV_CHILD_INACTIVE: readonly string[] = [
+  "text-fg",
+  "hover:text-accent",
+  "focus-visible:text-accent",
+];
+
+// ── Overflow "···" menu row recipes ──────────────────────────────────────
+// Assembled at runtime by update() in nav-overflow-script.ts. These are menu
+// rows (indented, their own padding/weight), NOT header-bar items, so they
+// intentionally differ from the toggle groups above. Co-located here so the
+// whole header-nav class vocabulary has one home; the shared color tokens
+// (e.g. NAV_CHILD_ACTIVE = "font-bold text-accent") are literally reused.
+const MENU_ROW_BASE: readonly string[] = [
+  "block",
+  "px-hsp-md",
+  "py-vsp-2xs",
+  "text-small",
+];
+const MENU_CHILD_BASE: readonly string[] = [
+  "block",
+  "pl-hsp-xl",
+  "pr-hsp-md",
+  "py-vsp-2xs",
+  "text-small",
+];
+// Resting (inactive) interactive appearance shared by the parent + plain rows.
+const MENU_ROW_RESTING: readonly string[] = [
+  "hover:bg-accent/10",
+  "hover:underline",
+  "focus-visible:underline",
+  "focus-visible:text-accent",
+  "text-fg",
+  "hover:text-accent",
+];
+
+// Overflow bucket: promoted dropdown-parent link (bold label). Active rows
+// additionally get NAV_MENU_PARENT_ACTIVE_SUFFIX appended.
+export const NAV_MENU_PARENT: readonly string[] = [
+  ...MENU_ROW_BASE,
+  "font-bold",
+  ...MENU_ROW_RESTING,
+];
+export const NAV_MENU_PARENT_ACTIVE_SUFFIX: readonly string[] = ["text-accent"];
+
+// Overflow bucket: plain (non-dropdown) item link. Active rows additionally
+// get NAV_MENU_PLAIN_ACTIVE_SUFFIX (= NAV_CHILD_ACTIVE) appended.
+export const NAV_MENU_PLAIN: readonly string[] = [
+  ...MENU_ROW_BASE,
+  ...MENU_ROW_RESTING,
+];
+export const NAV_MENU_PLAIN_ACTIVE_SUFFIX: readonly string[] = [
+  ...NAV_CHILD_ACTIVE,
+];
+
+// Overflow bucket: indented dropdown-child link (active vs resting variants
+// are whole strings — the resting variant interleaves menu affordances with
+// the child color tokens, so it is spelled out rather than composed).
+export const NAV_MENU_CHILD_ACTIVE: readonly string[] = [
+  ...MENU_CHILD_BASE,
+  ...NAV_CHILD_ACTIVE,
+  "hover:bg-accent/10",
+  "hover:underline",
+  "focus-visible:underline",
+];
+export const NAV_MENU_CHILD_INACTIVE: readonly string[] = [
+  ...MENU_CHILD_BASE,
+  "text-fg",
+  "hover:bg-accent/10",
+  "hover:text-accent",
+  "hover:underline",
+  "focus-visible:underline",
+  "focus-visible:text-accent",
+];

package/eject/header/nav-overflow-script.ts

@@ -31,6 +31,39 @@
 // script can be reviewed in isolation.
 
 import { AFTER_NAVIGATE_EVENT } from "../transitions/page-events.js";
+import {
+  NAV_CHEVRON_ACTIVE,
+  NAV_CHEVRON_INACTIVE,
+  NAV_CHILD_ACTIVE,
+  NAV_CHILD_INACTIVE,
+  NAV_MENU_CHILD_ACTIVE,
+  NAV_MENU_CHILD_INACTIVE,
+  NAV_MENU_PARENT,
+  NAV_MENU_PARENT_ACTIVE_SUFFIX,
+  NAV_MENU_PLAIN,
+  NAV_MENU_PLAIN_ACTIVE_SUFFIX,
+  NAV_TOP_ACTIVE,
+  NAV_TOP_INACTIVE,
+} from "./nav-class-tokens.js";
+
+// The class lists spliced into the script below are the SSR ↔ runtime
+// lockstep: they must match the strings header.tsx renders. Both files import
+// them from ./nav-class-tokens so they cannot drift (zudolab/zudo-doc#3023).
+// The script ships as plain text via dangerouslySetInnerHTML and cannot import
+// the arrays at runtime, so these helpers splice the token lists into the
+// script string at module-eval (build) time instead.
+
+// -> `"bg-fg", "text-bg"` — argument list for a classList.add/remove(...) call.
+const clsArgs = (tokens: readonly string[]): string =>
+  tokens.map((token) => JSON.stringify(token)).join(", ");
+
+// -> `"bg-fg text-bg"` — a single class-string literal for `className = ...`.
+const clsLiteral = (tokens: readonly string[]): string =>
+  JSON.stringify(tokens.join(" "));
+
+// -> `" font-bold text-accent"` — leading-space append for `className += ...`.
+const clsAppend = (tokens: readonly string[]): string =>
+  JSON.stringify(" " + tokens.join(" "));
 
 export const NAV_OVERFLOW_SCRIPT = `(function () {
   var cleanupNavOverflow = null;
@@ -89,12 +122,12 @@ export const NAV_OVERFLOW_SCRIPT = `(function () {
     function setTopActive(a, active) {
       if (!a) return;
       if (active) {
-        a.classList.add("bg-fg", "text-bg");
-        a.classList.remove("text-muted", "hover:underline", "focus:underline");
+        a.classList.add(${clsArgs(NAV_TOP_ACTIVE)});
+        a.classList.remove(${clsArgs(NAV_TOP_INACTIVE)});
         a.setAttribute("aria-current", "page");
       } else {
-        a.classList.remove("bg-fg", "text-bg");
-        a.classList.add("text-muted", "hover:underline", "focus:underline");
+        a.classList.remove(${clsArgs(NAV_TOP_ACTIVE)});
+        a.classList.add(${clsArgs(NAV_TOP_INACTIVE)});
         a.removeAttribute("aria-current");
       }
     }
@@ -112,19 +145,19 @@ export const NAV_OVERFLOW_SCRIPT = `(function () {
           if (childActive) {
             anyChild = true;
             c.setAttribute("data-active", "");
-            c.classList.add("font-bold", "text-accent");
-            c.classList.remove("text-fg");
+            c.classList.add(${clsArgs(NAV_CHILD_ACTIVE)});
+            c.classList.remove(${clsArgs(NAV_CHILD_INACTIVE)});
           } else {
             c.removeAttribute("data-active");
-            c.classList.remove("font-bold", "text-accent");
-            c.classList.add("text-fg");
+            c.classList.remove(${clsArgs(NAV_CHILD_ACTIVE)});
+            c.classList.add(${clsArgs(NAV_CHILD_INACTIVE)});
           }
         });
         topActive = parentMatch || anyChild;
         var svg = topA ? topA.querySelector("svg") : null;
         if (svg) {
-          if (topActive) { svg.classList.add("text-bg"); svg.classList.remove("text-muted"); }
-          else { svg.classList.add("text-muted"); svg.classList.remove("text-bg"); }
+          if (topActive) { svg.classList.add(${clsArgs(NAV_CHEVRON_ACTIVE)}); svg.classList.remove(${clsArgs(NAV_CHEVRON_INACTIVE)}); }
+          else { svg.classList.add(${clsArgs(NAV_CHEVRON_INACTIVE)}); svg.classList.remove(${clsArgs(NAV_CHEVRON_ACTIVE)}); }
         }
       } else {
         topActive = activePath !== "" && navPathname(topA) === activePath;
@@ -206,9 +239,9 @@ export const NAV_OVERFLOW_SCRIPT = `(function () {
             a.href = parentLink.href;
             var parentText = parentLink.textContent ? parentLink.textContent.trim().replace(/\\s+/g, " ") : "";
             a.textContent = parentText;
-            a.className = "block px-hsp-md py-vsp-2xs text-small font-bold hover:bg-accent/10 hover:underline focus-visible:underline text-fg";
+            a.className = ${clsLiteral(NAV_MENU_PARENT)};
             if (parentLink.getAttribute("aria-current") === "page") {
-              a.className += " text-accent";
+              a.className += ${clsAppend(NAV_MENU_PARENT_ACTIVE_SUFFIX)};
             }
             li.appendChild(a);
             moreMenu.appendChild(li);
@@ -220,8 +253,8 @@ export const NAV_OVERFLOW_SCRIPT = `(function () {
             a.textContent = child.textContent ? child.textContent.trim() : "";
             var isChildActive = child.hasAttribute("data-active");
             a.className = isChildActive
-              ? "block pl-hsp-xl pr-hsp-md py-vsp-2xs text-small font-bold text-accent hover:bg-accent/10 hover:underline focus-visible:underline"
-              : "block pl-hsp-xl pr-hsp-md py-vsp-2xs text-small text-muted hover:bg-accent/10 hover:text-fg hover:underline focus-visible:underline";
+              ? ${clsLiteral(NAV_MENU_CHILD_ACTIVE)}
+              : ${clsLiteral(NAV_MENU_CHILD_INACTIVE)};
             li.appendChild(a);
             moreMenu.appendChild(li);
           });
@@ -231,9 +264,9 @@ export const NAV_OVERFLOW_SCRIPT = `(function () {
           var a2 = document.createElement("a");
           a2.href = anchor.href;
           a2.textContent = anchor.textContent ? anchor.textContent.trim() : "";
-          a2.className = "block px-hsp-md py-vsp-2xs text-small hover:bg-accent/10 hover:underline focus-visible:underline text-fg";
+          a2.className = ${clsLiteral(NAV_MENU_PLAIN)};
           if (anchor.getAttribute("aria-current") === "page") {
-            a2.className += " font-bold text-accent";
+            a2.className += ${clsAppend(NAV_MENU_PLAIN_ACTIVE_SUFFIX)};
           }
           li2.appendChild(a2);
           moreMenu.appendChild(li2);

package/eject/sidebar-tree-island/index.tsx

@@ -447,7 +447,7 @@ const CategoryNode = memo(function CategoryNode({
             <a
               href={node.href}
               aria-current={isActive ? "page" : undefined}
-              className={`flex-1 flex items-start gap-hsp-xs py-vsp-xs hover:underline focus:underline break-words ${isActive ? "text-bg" : "text-fg"}`}
+              className={`flex-1 flex items-start gap-hsp-xs py-vsp-xs hover:underline focus:underline break-words ${isActive ? "text-bg" : "text-fg hover:text-accent focus:text-accent"}`}
               style={{ paddingLeft }}
             >
               {depth === 0 && (
@@ -471,7 +471,7 @@ const CategoryNode = memo(function CategoryNode({
           <button
             type="button"
             onClick={toggle}
-            className={`flex w-full items-center gap-hsp-md text-left text-small font-semibold py-vsp-xs text-fg hover:underline focus:underline break-words`}
+            className={`flex w-full items-center gap-hsp-md text-left text-small font-semibold py-vsp-xs text-fg hover:text-accent hover:underline focus:underline focus:text-accent break-words`}
             style={{ paddingLeft }}
             aria-expanded={isExpanded}
             aria-label={isExpanded ? `Collapse ${node.label}` : `Expand ${node.label}`}
@@ -536,12 +536,12 @@ const LeafNode = memo(function LeafNode({
           data-nav-active={!isRoot && isActive ? "" : undefined}
           className={isRoot
             ? `flex items-start gap-hsp-xs py-[calc(var(--spacing-vsp-xs)+0.15rem)] pr-[4px] text-small font-semibold break-words ${
-                isActive ? "bg-fg text-bg" : "text-fg hover:underline focus:underline"
+                isActive ? "bg-fg text-bg" : "text-fg hover:text-accent hover:underline focus:underline focus:text-accent"
               }`
             : `block py-vsp-2xs pr-[4px] text-small break-words ${
                 isActive
                   ? "bg-fg font-medium text-bg"
-                  : "text-muted hover:underline focus:underline"
+                  : "text-muted hover:text-accent hover:underline focus:underline focus:text-accent"
               }`
           }
           style={{ paddingLeft }}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takazudo/zudo-doc",
-  "version": "4.3.0",
+  "version": "4.4.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",
@@ -151,6 +151,10 @@
       "types": "./dist/preset.d.ts",
       "default": "./dist/preset.js"
     },
+    "./auto-logo": {
+      "types": "./dist/auto-logo/index.d.ts",
+      "default": "./dist/auto-logo/index.js"
+    },
     "./component-tokens": {
       "types": "./dist/config/component-tokens.d.ts",
       "default": "./dist/config/component-tokens.js"
@@ -567,6 +571,10 @@
     "./theme-cli": {
       "types": "./dist/theme-cli/index.d.ts",
       "default": "./dist/theme-cli/index.js"
+    },
+    "./eject-logo": {
+      "types": "./dist/eject-logo/index.d.ts",
+      "default": "./dist/eject-logo/index.js"
     }
   },
   "bin": {
@@ -589,9 +597,9 @@
   ],
   "peerDependencies": {
     "@takazudo/zdtp": "^0.4.9",
-    "@takazudo/zfb": "^0.1.0-next.89",
-    "@takazudo/zfb-md-wasm": "^0.1.0-next.89",
-    "@takazudo/zfb-runtime": "^0.1.0-next.89",
+    "@takazudo/zfb": "^0.1.0-next.90",
+    "@takazudo/zfb-md-wasm": "^0.1.0-next.90",
+    "@takazudo/zfb-runtime": "^0.1.0-next.90",
     "@takazudo/zudo-doc-history-server": "^4.0.0",
     "diff": "^8.0.0",
     "katex": "^0.16.0",
@@ -626,9 +634,9 @@
     "tsx": "^4.21.0"
   },
   "devDependencies": {
-    "@takazudo/zfb": "0.1.0-next.89",
-    "@takazudo/zfb-md-wasm": "0.1.0-next.89",
-    "@takazudo/zfb-runtime": "0.1.0-next.89",
+    "@takazudo/zfb": "0.1.0-next.90",
+    "@takazudo/zfb-md-wasm": "0.1.0-next.90",
+    "@takazudo/zfb-runtime": "0.1.0-next.90",
     "@types/fs-extra": "^11.0.4",
     "@types/minimist": "^1.2.5",
     "@types/node": "^25.3.5",
@@ -642,7 +650,7 @@
     "typescript": "^5.0.0",
     "vitest": "^4.1.0",
     "zod": "^4.3.6",
-    "@takazudo/zudo-doc-history-server": "4.3.0"
+    "@takazudo/zudo-doc-history-server": "4.4.0"
   },
   "scripts": {
     "build": "tsup && tsc -p tsconfig.build.json",

package/routes-src/index.tsx

@@ -20,7 +20,7 @@ export const frontmatter = { title: "Home" };
 export default function IndexPage(): JSX.Element {
   const locale = defaultLocale;
 
-  const { tree, categoryOrder, tagCount } = prepareHomeData(routeCtx, locale);
+  const { tree, categoryOrder, tagCount, tags } = prepareHomeData(routeCtx, locale);
 
   return (
     <HomePageView
@@ -28,6 +28,7 @@ export default function IndexPage(): JSX.Element {
       tree={tree}
       categoryOrder={categoryOrder}
       tagCount={tagCount}
+      tags={tags}
       wide={settings.home?.wide ?? false}
     />
   );

package/routes-src/locale-index.tsx

@@ -34,7 +34,7 @@ interface PageArgs {
 export default function LocaleIndexPage({ params }: PageArgs): JSX.Element {
   const locale = params.locale;
 
-  const { tree, categoryOrder, tagCount } = prepareHomeData(routeCtx, locale);
+  const { tree, categoryOrder, tagCount, tags } = prepareHomeData(routeCtx, locale);
 
   return (
     <HomePageView
@@ -42,6 +42,7 @@ export default function LocaleIndexPage({ params }: PageArgs): JSX.Element {
       tree={tree}
       categoryOrder={categoryOrder}
       tagCount={tagCount}
+      tags={tags}
       wide={settings.home?.wide ?? false}
     />
   );