diff --git a/CHANGELOG.md b/CHANGELOG.md index dc755e1..dacc023 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,8 @@ All notable user-visible changes are recorded here. Versions follow [Semantic Ve ### Changed +- Prevented Mermaid labels from being clipped by waiting for fonts before + layout and reserving consistent padding around every diagram node. - Added responsive Mermaid diagrams to the principal documentation guides; desktop uses wide flows while phones receive compact top-to-bottom layouts. - Added proper inner spacing to the landing page's live phone captures and made diff --git a/scripts/test-landing-seo.mjs b/scripts/test-landing-seo.mjs index 1b757bf..47e0e0d 100644 --- a/scripts/test-landing-seo.mjs +++ b/scripts/test-landing-seo.mjs @@ -2,10 +2,11 @@ import { readFile } from "node:fs/promises"; const repositoryRoot = new URL("../", import.meta.url); const readSource = (path) => readFile(new URL(path, repositoryRoot), "utf8"); -const [indexHtml, documentationHtml, landingSource, documentationRenderer, documentationRoutes, viteSource, sitemap, robots, manifestSource, readme, workerSource, docsSource, packageSource] = await Promise.all([ +const [indexHtml, documentationHtml, landingSource, landingStyles, documentationRenderer, documentationRoutes, viteSource, sitemap, robots, manifestSource, readme, workerSource, docsSource, packageSource] = await Promise.all([ readSource("index.html"), readSource("web/documentation.html"), readSource("web/main.ts"), + readSource("web/landing.css"), readSource("web/documentation.ts"), readSource("shared/documentation.ts"), readSource("vite.config.ts"), @@ -159,6 +160,9 @@ for (const page of ["docs", "app", "cli", "platforms", "mobile", "refstream", "r } check(documentationRenderer.includes('import documentationSource from "../docs/content.json"'), "Website must render from the repository documentation source"); check(documentationRenderer.includes('import("mermaid")'), "Documentation diagrams must load Mermaid only on documentation pages"); +check(documentationRenderer.includes("await document.fonts?.ready"), "Documentation diagrams must wait for fonts before measuring labels"); +check(documentationRenderer.includes("padding: 18"), "Documentation diagrams must leave enough room around labels"); +check(landingStyles.includes(".knowledge-diagram-canvas foreignObject p"), "Mermaid labels must retain their measured font size inside documentation sections"); const diagramPages = Object.values(docsContent.pages).filter((page) => Array.isArray(page.diagrams)); check(diagramPages.length >= 7, "The knowledge base should contain responsive diagrams across its principal guides"); for (const page of diagramPages) { diff --git a/web/documentation.ts b/web/documentation.ts index 66baed8..0ed59b7 100644 --- a/web/documentation.ts +++ b/web/documentation.ts @@ -111,6 +111,11 @@ async function renderDocumentationDiagrams(): Promise { const figures = Array.from(document.querySelectorAll(".knowledge-diagram")); if (figures.length === 0) return; + // Mermaid measures labels before it draws their nodes. Waiting here prevents + // a fallback font from producing boxes that are too narrow once web fonts + // finish loading, which otherwise clips the final characters on slower + // browsers and mobile connections. + await document.fonts?.ready; const { default: mermaid } = await import("mermaid"); mermaid.initialize({ startOnLoad: false, @@ -130,10 +135,17 @@ async function renderDocumentationDiagrams(): Promise { tertiaryBorderColor: "#cbd6e2", lineColor: "#697386", edgeLabelBackground: "#ffffff", - fontFamily: "Uncut Sans, system-ui, sans-serif", + fontFamily: "system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif", fontSize: "14px", }, - flowchart: { curve: "basis", htmlLabels: false, useMaxWidth: true }, + flowchart: { + curve: "basis", + htmlLabels: false, + useMaxWidth: true, + padding: 18, + nodeSpacing: 34, + rankSpacing: 42, + }, }); const compact = window.matchMedia("(max-width: 720px)"); diff --git a/web/landing.css b/web/landing.css index 9dad74c..fed78d6 100644 --- a/web/landing.css +++ b/web/landing.css @@ -275,6 +275,15 @@ margin: auto; } +/* Keep rendered labels at the exact size Mermaid used to measure them. The + surrounding documentation article gives paragraphs a larger font, and that + otherwise leaks into Mermaid's foreignObject labels after layout. */ +.knowledge-diagram-canvas foreignObject p { + font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; + font-size: 14px; + line-height: 1.5; +} + .knowledge-diagram-canvas .node rect, .knowledge-diagram-canvas .node polygon, .knowledge-diagram-canvas .node circle {