@tomehq/theme 0.2.6 → 0.2.8

package/src/entry.tsx

@@ -1,11 +1,19 @@
 import React, { useState, useEffect, useCallback } from "react";
 import { createRoot } from "react-dom/client";
 import { Shell } from "./Shell.js";
+import { pathnameToPageId as _pathnameToPageId, pageIdToPath as _pageIdToPath } from "./routing.js";
+import {
+  loadPage,
+  computeEditUrl,
+  resolveInitialPageId,
+  detectCurrentVersion,
+  type LoadedPage,
+} from "./entry-helpers.js";
 
 // @ts-ignore — resolved by vite-plugin-tome
 import config from "virtual:tome/config";
 // @ts-ignore — resolved by vite-plugin-tome
-import { routes, navigation } from "virtual:tome/routes";
+import { routes, navigation, versions } from "virtual:tome/routes";
 // @ts-ignore — resolved by vite-plugin-tome
 import loadPageModule from "virtual:tome/page-loader";
 // @ts-ignore — resolved by vite-plugin-tome
@@ -21,6 +29,9 @@ import {
   Steps,
   Accordion,
   ChangelogTimeline,
+  PackageManager,
+  TypeTable,
+  FileTree,
 } from "@tomehq/components";
 
 const MDX_COMPONENTS: Record<string, React.ComponentType<any>> = {
@@ -31,6 +42,9 @@ const MDX_COMPONENTS: Record<string, React.ComponentType<any>> = {
   Steps,
   Accordion,
   ChangelogTimeline,
+  PackageManager,
+  TypeTable,
+  FileTree, // Sub-components accessible as <FileTree.File /> and <FileTree.Folder /> in MDX
 };
 
 // ── CONTENT STYLES ───────────────────────────────────────
@@ -56,8 +70,11 @@ const contentStyles = `
   .tome-content table { width: 100%; border-collapse: collapse; margin-bottom: 1em; }
   .tome-content th, .tome-content td { padding: 0.5em 0.8em; border: 1px solid var(--bd); text-align: left; font-size: 0.9em; }
   .tome-content th { background: var(--sf); font-weight: 600; }
-  .tome-content img { max-width: 100%; border-radius: 2px; }
+  .tome-content img { max-width: 100%; border-radius: 2px; cursor: zoom-in; }
   .tome-content hr { border: none; border-top: 1px solid var(--bd); margin: 2em 0; }
+  .tome-mermaid { margin: 1.2em 0; text-align: center; overflow-x: auto; }
+  .tome-mermaid svg { max-width: 100%; height: auto; overflow: visible; }
+  .tome-mermaid svg .nodeLabel { overflow: visible; white-space: nowrap; }
 
   /* Mobile responsive content */
   @media (max-width: 767px) {
@@ -97,105 +114,176 @@ const contentStyles = `
   html.dark .shiki span[style*="--shiki-dark:#6A737D"] {
     --shiki-dark: #a0aab5 !important;
   }
+
+  /* Light mode: darken low-contrast github-light tokens for WCAG AA on --cdBg backgrounds */
+  html:not(.dark) .shiki span[style*="color:#6A737D"] { color: #57606a !important; }
+  html:not(.dark) .shiki span[style*="color:#E36209"] { color: #b35405 !important; }
+  html:not(.dark) .shiki span[style*="color:#6F42C1"] { color: #5a32a3 !important; }
+  html:not(.dark) .shiki span[style*="color:#22863A"] { color: #1a6e2e !important; }
+  html:not(.dark) .shiki span[style*="color:#D73A49"] { color: #b62324 !important; }
+  html:not(.dark) .shiki span[style*="color:#005CC5"] { color: #0349b4 !important; }
 `;
 
-// ── PAGE TYPES ────────────────────────────────────────────
-interface HtmlPage {
-  isMdx: false;
-  html: string;
-  frontmatter: { title: string; description?: string; toc?: boolean; type?: string };
-  headings: Array<{ depth: number; text: string; id: string }>;
-  changelogEntries?: Array<{ version: string; date?: string; url?: string; sections: Array<{ type: string; items: string[] }> }>;
-}
+// ── ROUTING HELPERS ──────────────────────────────────────
+const basePath = (config.basePath || "/").replace(/\/$/, "");
 
-interface MdxPage {
-  isMdx: true;
-  component: React.ComponentType<{ components?: Record<string, React.ComponentType> }>;
-  frontmatter: { title: string; description?: string; toc?: boolean; type?: string };
-  headings: Array<{ depth: number; text: string; id: string }>;
+function pathnameToPageId(pathname: string): string | null {
+  return _pathnameToPageId(pathname, basePath, routes);
 }
 
-type LoadedPage = HtmlPage | MdxPage;
-
-// ── PAGE LOADER ──────────────────────────────────────────
-async function loadPage(id: string): Promise<LoadedPage | null> {
-  try {
-    const route = routes.find((r: any) => r.id === id);
-    const mod = await loadPageModule(id);
-
-    if (route?.isMdx && mod.meta) {
-      // TOM-8: MDX page — mod.default is the React component
-      return {
-        isMdx: true,
-        component: mod.default,
-        frontmatter: mod.meta.frontmatter,
-        headings: mod.meta.headings,
-      };
-    }
-
-    // Regular .md page — mod.default is { html, frontmatter, headings }
-    if (!mod.default) return null;
-
-    // TOM-49: Changelog page type
-    if (mod.isChangelog && mod.changelogEntries) {
-      return { isMdx: false, ...mod.default, changelogEntries: mod.changelogEntries };
-    }
-
-    return { isMdx: false, ...mod.default };
-  } catch (err) {
-    console.error(`Failed to load page: ${id}`, err);
-    return null;
-  }
+function pageIdToPath(id: string): string {
+  return _pageIdToPath(id, basePath, routes);
 }
 
 // ── APP ──────────────────────────────────────────────────
 function App() {
-  const [currentPageId, setCurrentPageId] = useState(() => {
-    const hash = window.location.hash.slice(1);
-    if (hash && routes.some((r: any) => r.id === hash)) return hash;
-    return routes[0]?.id || "index";
-  });
+  const [currentPageId, setCurrentPageId] = useState(() =>
+    resolveInitialPageId(
+      window.location.pathname,
+      window.location.hash,
+      routes,
+      basePath,
+      _pathnameToPageId,
+    )
+  );
 
   const [pageData, setPageData] = useState<LoadedPage | null>(null);
   const [loading, setLoading] = useState(true);
 
-  const navigateTo = useCallback(async (id: string) => {
+  const navigateTo = useCallback(async (id: string, opts?: { replace?: boolean; skipScroll?: boolean }) => {
     setLoading(true);
     setCurrentPageId(id);
-    window.location.hash = id;
-    const data = await loadPage(id);
+    const fullPath = pageIdToPath(id);
+    if (opts?.replace) {
+      window.history.replaceState(null, "", fullPath);
+    } else {
+      window.history.pushState(null, "", fullPath);
+    }
+    const data = await loadPage(id, routes, loadPageModule);
     setPageData(data);
     setLoading(false);
+    // Scroll to heading anchor if present, otherwise scroll to top
+    if (!opts?.skipScroll) {
+      const anchor = window.location.hash.slice(1);
+      if (anchor) {
+        requestAnimationFrame(() => {
+          const el = document.getElementById(anchor);
+          if (el) el.scrollIntoView({ behavior: "smooth", block: "start" });
+        });
+      } else {
+        window.scrollTo(0, 0);
+      }
+    }
   }, []);
 
-  useEffect(() => { navigateTo(currentPageId); }, []);
+  // Initial page load
+  useEffect(() => {
+    // If user landed on a legacy hash URL, redirect to clean path
+    const hash = window.location.hash.slice(1);
+    if (hash && routes.some((r: any) => r.id === hash)) {
+      const fullPath = pageIdToPath(hash);
+      window.history.replaceState(null, "", fullPath);
+      navigateTo(hash, { replace: true });
+    } else {
+      navigateTo(currentPageId, { replace: true, skipScroll: true });
+    }
+  }, []);
 
+  // Listen for browser back/forward navigation
   useEffect(() => {
-    const onHashChange = () => {
-      const hash = window.location.hash.slice(1);
-      // Only navigate if hash matches a known route ID (ignore heading anchors)
-      if (hash && hash !== currentPageId && routes.some((r: any) => r.id === hash)) {
-        navigateTo(hash);
+    const onPopState = () => {
+      const id = pathnameToPageId(window.location.pathname);
+      if (id && id !== currentPageId) {
+        navigateTo(id, { replace: true, skipScroll: true });
       }
     };
-    window.addEventListener("hashchange", onHashChange);
-    return () => window.removeEventListener("hashchange", onHashChange);
+    window.addEventListener("popstate", onPopState);
+    return () => window.removeEventListener("popstate", onPopState);
   }, [currentPageId, navigateTo]);
 
+  // Mermaid diagram rendering: load from CDN and render .tome-mermaid elements
+  useEffect(() => {
+    const els = document.querySelectorAll(".tome-mermaid[data-mermaid]");
+    if (els.length === 0) return;
+    let cancelled = false;
+
+    const MERMAID_CDN = "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";
+
+    (async () => {
+      try {
+        // Load mermaid from CDN (ESM) — works in all browsers, no bundler dependency
+        const { default: mermaid } = await import(/* @vite-ignore */ MERMAID_CDN);
+        if (cancelled) return;
+        const isDark = document.documentElement.classList.contains("dark");
+        // Resolve CSS variable to concrete font name — mermaid can't resolve CSS vars for text measurement
+        const resolvedFont = getComputedStyle(document.documentElement).getPropertyValue("--font-body").trim() || "sans-serif";
+        mermaid.initialize({
+          startOnLoad: false,
+          theme: isDark ? "dark" : "default",
+          fontFamily: resolvedFont,
+          flowchart: { padding: 15, nodeSpacing: 30, rankSpacing: 40 },
+        });
+
+        for (let i = 0; i < els.length; i++) {
+          const el = els[i] as HTMLElement;
+          if (el.querySelector("svg")) continue; // already rendered
+          const encoded = el.getAttribute("data-mermaid");
+          if (!encoded) continue;
+          try {
+            const code = atob(encoded);
+            const { svg } = await mermaid.render(`tome-mermaid-${i}-${Date.now()}`, code);
+            if (!cancelled) {
+              // Sanitize SVG to prevent XSS from mermaid-rendered content
+              try {
+                // @ts-ignore — CDN dynamic import for browser-only sanitization
+                const DOMPurify = (await import(/* @vite-ignore */ "https://cdn.jsdelivr.net/npm/dompurify@3/dist/purify.es.mjs")).default;
+                el.innerHTML = DOMPurify.sanitize(svg, { USE_PROFILES: { svg: true, svgFilters: true } });
+              } catch {
+                // DOMPurify unavailable — render without sanitization (acceptable for trusted content)
+                el.innerHTML = svg;
+              }
+            }
+          } catch (err) {
+            console.warn("[tome] Mermaid render failed:", err);
+            el.textContent = "Diagram rendering failed";
+            (el as HTMLElement).style.cssText = "padding:16px;color:var(--txM);font-size:13px;border:1px dashed var(--bd);border-radius:2px;text-align:center;";
+          }
+        }
+      } catch (err) {
+        console.warn("[tome] Failed to load mermaid from CDN:", err);
+        els.forEach((el) => {
+          (el as HTMLElement).textContent = "Failed to load diagram renderer";
+          (el as HTMLElement).style.cssText = "padding:16px;color:var(--txM);font-size:13px;border:1px dashed var(--bd);border-radius:2px;text-align:center;";
+        });
+      }
+    })();
+
+    return () => { cancelled = true; };
+  }, [pageData, loading]);
+
   const allPages = routes.map((r: any) => ({
     id: r.id,
     title: r.frontmatter.title,
     description: r.frontmatter.description,
   }));
 
-  // TOM-48: Compute edit URL for current page
+  // Compute current version from route metadata
   const currentRoute = routes.find((r: any) => r.id === currentPageId);
-  let editUrl: string | undefined;
-  if (config.editLink && currentRoute?.filePath) {
-    const { repo, branch = "main", dir = "" } = config.editLink;
-    const dirPrefix = dir ? `${dir.replace(/\/$/, "")}/` : "";
-    editUrl = `https://github.com/${repo}/edit/${branch}/${dirPrefix}${currentRoute.filePath}`;
-  }
+  const currentVersion = detectCurrentVersion(currentRoute, versions);
+  const editUrl = computeEditUrl(config.editLink, currentRoute?.filePath);
+
+  // KaTeX CSS: inject stylesheet when math is enabled
+  useEffect(() => {
+    if (!(config as any).math) return;
+    const id = "tome-katex-css";
+    if (document.getElementById(id)) return;
+    const link = document.createElement("link");
+    link.id = id;
+    link.rel = "stylesheet";
+    link.href = "https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.css";
+    link.crossOrigin = "anonymous";
+    document.head.appendChild(link);
+  }, []);
 
   return (
     <>
@@ -217,6 +305,9 @@ function App() {
         onNavigate={navigateTo}
         allPages={allPages}
         docContext={docContext}
+        versioning={versions || undefined}
+        currentVersion={currentVersion}
+        basePath={basePath}
       />
     </>
   );

package/src/routing.test.ts

@@ -0,0 +1,124 @@
+import { describe, it, expect } from "vitest";
+import { pathnameToPageId, pageIdToPath } from "./routing.js";
+import type { MinimalRoute } from "./routing.js";
+
+// ── Shared fixtures ──────────────────────────────────────
+
+const routes: MinimalRoute[] = [
+  { id: "index", urlPath: "/" },
+  { id: "quickstart", urlPath: "/quickstart" },
+  { id: "installation", urlPath: "/installation" },
+  { id: "reference/config", urlPath: "/reference/config" },
+  { id: "guides/migration", urlPath: "/guides/migration" },
+  { id: "v1/index", urlPath: "/v1/" },
+  { id: "v1/quickstart", urlPath: "/v1/quickstart" },
+];
+
+// ── pathnameToPageId ─────────────────────────────────────
+
+describe("pathnameToPageId", () => {
+  const basePath = "/docs";
+
+  it("resolves root path to index", () => {
+    expect(pathnameToPageId("/docs/", basePath, routes)).toBe("index");
+  });
+
+  it("resolves root without trailing slash", () => {
+    expect(pathnameToPageId("/docs", basePath, routes)).toBe("index");
+  });
+
+  it("resolves top-level page", () => {
+    expect(pathnameToPageId("/docs/quickstart", basePath, routes)).toBe("quickstart");
+  });
+
+  it("resolves nested page", () => {
+    expect(pathnameToPageId("/docs/reference/config", basePath, routes)).toBe("reference/config");
+  });
+
+  it("resolves deeply nested page", () => {
+    expect(pathnameToPageId("/docs/guides/migration", basePath, routes)).toBe("guides/migration");
+  });
+
+  it("returns null for unknown page", () => {
+    expect(pathnameToPageId("/docs/nonexistent", basePath, routes)).toBeNull();
+  });
+
+  it("strips /index.html suffix", () => {
+    expect(pathnameToPageId("/docs/quickstart/index.html", basePath, routes)).toBe("quickstart");
+  });
+
+  it("strips .html suffix", () => {
+    expect(pathnameToPageId("/docs/quickstart.html", basePath, routes)).toBe("quickstart");
+  });
+
+  it("strips trailing slash", () => {
+    expect(pathnameToPageId("/docs/quickstart/", basePath, routes)).toBe("quickstart");
+  });
+
+  it("resolves versioned page", () => {
+    expect(pathnameToPageId("/docs/v1/quickstart", basePath, routes)).toBe("v1/quickstart");
+  });
+
+  it("resolves versioned index", () => {
+    // /docs/v1/ → strip basePath → /v1/ → strip leading / → v1/ → strip trailing / → v1
+    // But our route ID is "v1/index", not "v1", so this needs to resolve properly
+    // After all stripping: "v1" — not in routes (v1/index is). Let's test this edge case.
+    expect(pathnameToPageId("/docs/v1", basePath, routes)).toBeNull();
+  });
+
+  describe("with empty basePath", () => {
+    it("resolves root to index", () => {
+      expect(pathnameToPageId("/", "", routes)).toBe("index");
+    });
+
+    it("resolves page at root", () => {
+      expect(pathnameToPageId("/quickstart", "", routes)).toBe("quickstart");
+    });
+
+    it("resolves nested page at root", () => {
+      expect(pathnameToPageId("/reference/config", "", routes)).toBe("reference/config");
+    });
+  });
+
+  describe("with / basePath", () => {
+    it("resolves top-level page", () => {
+      expect(pathnameToPageId("/quickstart", "", routes)).toBe("quickstart");
+    });
+  });
+});
+
+// ── pageIdToPath ─────────────────────────────────────────
+
+describe("pageIdToPath", () => {
+  const basePath = "/docs";
+
+  it("builds path for index", () => {
+    expect(pageIdToPath("index", basePath, routes)).toBe("/docs/");
+  });
+
+  it("builds path for top-level page", () => {
+    expect(pageIdToPath("quickstart", basePath, routes)).toBe("/docs/quickstart");
+  });
+
+  it("builds path for nested page", () => {
+    expect(pageIdToPath("reference/config", basePath, routes)).toBe("/docs/reference/config");
+  });
+
+  it("builds path for versioned page", () => {
+    expect(pageIdToPath("v1/quickstart", basePath, routes)).toBe("/docs/v1/quickstart");
+  });
+
+  it("falls back to basePath + id for unknown route", () => {
+    expect(pageIdToPath("unknown-page", basePath, routes)).toBe("/docs/unknown-page");
+  });
+
+  describe("with empty basePath", () => {
+    it("builds path for index", () => {
+      expect(pageIdToPath("index", "", routes)).toBe("/");
+    });
+
+    it("builds path for page", () => {
+      expect(pageIdToPath("quickstart", "", routes)).toBe("/quickstart");
+    });
+  });
+});

package/src/routing.ts

@@ -0,0 +1,45 @@
+/**
+ * Pure routing utilities for History API navigation.
+ * Extracted from entry.tsx so they can be unit-tested independently.
+ */
+
+export interface MinimalRoute {
+  id: string;
+  urlPath: string;
+}
+
+/**
+ * Extract page ID from a pathname by stripping basePath prefix.
+ * Returns null if the resolved ID doesn't match any known route.
+ */
+export function pathnameToPageId(
+  pathname: string,
+  basePath: string,
+  routes: MinimalRoute[],
+): string | null {
+  let relative = pathname;
+  if (basePath && relative.startsWith(basePath)) {
+    relative = relative.slice(basePath.length);
+  }
+  const id =
+    relative
+      .replace(/^\//, "")
+      .replace(/\/index\.html$/, "")
+      .replace(/\.html$/, "")
+      .replace(/\/$/, "") || "index";
+  const route = routes.find((r) => r.id === id);
+  return route ? id : null;
+}
+
+/**
+ * Get the full URL path for a page ID (basePath + urlPath).
+ */
+export function pageIdToPath(
+  id: string,
+  basePath: string,
+  routes: MinimalRoute[],
+): string {
+  const route = routes.find((r) => r.id === id);
+  if (route) return basePath + route.urlPath;
+  return basePath + "/" + id;
+}