Merge pull request #40 from zazuko/export-design

Improve design of exports

Author: ludovicm67

.changeset/dry-corners-dream.md

@@ -0,0 +1,5 @@
+---
+"graph-explorer": patch
+---
+
+Improve design of exported content

src/graph-explorer/viewUtils/toSvg.ts

@@ -104,9 +104,14 @@ function exportSVG(options: ToSVGOptions): Promise<SVGElement> {
   return convertingImages.then(() => {
     // workaround to include only graph-explorer-related stylesheets
     const exportedCssText = extractCSSFromDocument(svgClone);
+    // design tokens have to be re-declared on the detached export root,
+    // otherwise the `var(--…)` references in the rules above resolve to nothing
+    const exportedVariables = extractCSSVariables(
+      options.paper.closest(".graph-explorer")
+    );
 
     const defs = document.createElementNS("http://www.w3.org/2000/svg", "defs");
-    defs.innerHTML = `<style>${exportedCssText}</style>`;
+    defs.innerHTML = `<style>${exportedVariables}\n${exportedCssText}</style>`;
     svgClone.insertBefore(defs, svgClone.firstChild);
 
     if (options.elementsToRemoveSelector) {
@@ -176,8 +181,7 @@ function _clearAttributes(svg: SVGElement) {
   }
 }
 
-function extractCSSFromDocument(targetSubtree: Element): string {
-  const exportedRules = new Set<CSSStyleRule>();
+function forEachStyleRule(callback: (rule: CSSStyleRule) => void) {
   for (let i = 0; i < document.styleSheets.length; i++) {
     let rules: CSSRuleList;
     try {
@@ -187,18 +191,68 @@ function extractCSSFromDocument(targetSubtree: Element): string {
         continue;
       }
     } catch (_e) {
+      // cross-origin stylesheets cannot be inspected
       continue;
     }
 
     for (let j = 0; j < rules.length; j++) {
       const rule = rules[j];
       if (rule instanceof CSSStyleRule) {
-        if (targetSubtree.querySelector(rule.selectorText)) {
-          exportedRules.add(rule);
-        }
+        callback(rule);
       }
     }
   }
+}
+
+/**
+ * The exported SVG is detached from the workspace, so CSS custom properties
+ * (the design tokens) declared on the workspace root are not in scope and every
+ * `var(--…)` reference in the exported rules would resolve to nothing, dropping
+ * colours, radii and shadows. Re-declare the resolved values on the exported
+ * root so the export matches what is on the canvas.
+ */
+function extractCSSVariables(source: Element | null | undefined): string {
+  if (!source) {
+    return "";
+  }
+  const computed = getComputedStyle(source);
+  const declarations = new Map<string, string>();
+
+  forEachStyleRule((rule) => {
+    for (let i = 0; i < rule.style.length; i++) {
+      const property = rule.style.item(i);
+      if (!property.startsWith("--") || declarations.has(property)) {
+        continue;
+      }
+      const value = computed.getPropertyValue(property).trim();
+      if (value) {
+        declarations.set(property, value);
+      }
+    }
+  });
+
+  if (declarations.size === 0) {
+    return "";
+  }
+  const variables = Array.from(
+    declarations,
+    ([name, value]) => `${name}: ${value};`
+  ).join(" ");
+  return `svg { ${variables} }`;
+}
+
+function extractCSSFromDocument(targetSubtree: Element): string {
+  const exportedRules = new Set<CSSStyleRule>();
+  forEachStyleRule((rule) => {
+    try {
+      if (targetSubtree.querySelector(rule.selectorText)) {
+        exportedRules.add(rule);
+      }
+    } catch (_e) {
+      // selectors that are not valid for querySelector (e.g. pseudo-elements)
+      // must not abort the whole export
+    }
+  });
 
   const exportedCssTexts: string[] = [];
   exportedRules.forEach((rule) => exportedCssTexts.push(rule.cssText));

styles/diagram/_elementLayer.scss

@@ -5,12 +5,24 @@
 
 .graph-explorer-overlayed-element,
 .graph-explorer-exported-element {
-  // set defaults for all inherited properties
+  // Set defaults for all inherited properties. These also apply to the exported
+  // SVG/PNG, which is detached from the workspace root, so the design tokens are
+  // spelled out with fallbacks to keep exports looking like the canvas.
   box-sizing: border-box;
-  color: black;
-  font-family: "Helvetica Neue",Helvetica,Arial,sans-serif;
+  color: var(--ge-text, #0f172a);
+  font-family: var(
+    --ge-font-sans,
+    "Inter",
+    system-ui,
+    -apple-system,
+    "Segoe UI",
+    Roboto,
+    "Helvetica Neue",
+    Arial,
+    sans-serif
+  );
   font-size: 14px;
-  line-height: 1.42857143;
+  line-height: 1.5;
 
   // http://stackoverflow.com/questions/6664460/line-height-affects-images
   img { vertical-align: middle; }

tests/e2e/export.spec.ts

@@ -0,0 +1,75 @@
+import { readFileSync } from "node:fs";
+
+import { expect, test } from "@playwright/test";
+
+import { createElementOnCanvas, openLocalDemo } from "./helpers";
+
+/** Clicks a toolbar export button and returns the downloaded file's contents. */
+async function download(
+  page: import("@playwright/test").Page,
+  title: string
+): Promise<Buffer> {
+  const [downloaded] = await Promise.all([
+    page.waitForEvent("download", { timeout: 30_000 }),
+    page.getByTitle(title).click(),
+  ]);
+  return readFileSync(await downloaded.path());
+}
+
+test.describe("diagram export", () => {
+  test.beforeEach(async ({ page }) => {
+    await openLocalDemo(page);
+    await createElementOnCanvas(page);
+  });
+
+  /**
+   * Regression guard: the exported SVG is detached from the workspace root, so
+   * the design tokens declared there are out of scope. If they are not
+   * re-declared on the export, every `var(--…)` resolves to nothing and the
+   * diagram loses its background, corner radius, shadow and text colour.
+   */
+  test("SVG export declares every design token it references", async ({
+    page,
+  }) => {
+    const svg = (await download(page, "Export diagram as SVG")).toString(
+      "utf8"
+    );
+
+    const referenced = new Set(
+      (svg.match(/var\(\s*(--[\w-]+)/g) ?? []).map((match) =>
+        match.replace(/var\(\s*/, "")
+      )
+    );
+    const declared = new Set(svg.match(/--[\w-]+(?=\s*:)/g) ?? []);
+
+    // the templates do use tokens - otherwise this test proves nothing
+    expect(referenced.size).toBeGreaterThan(0);
+
+    const undeclared = [...referenced].filter((name) => !declared.has(name));
+    expect(undeclared, "tokens referenced but never declared").toEqual([]);
+  });
+
+  test("SVG export contains the diagram content and its styles", async ({
+    page,
+  }) => {
+    const svg = (await download(page, "Export diagram as SVG")).toString(
+      "utf8"
+    );
+
+    expect(svg).toContain("<svg");
+    expect(svg).toContain("<style>");
+    // the element is exported as foreignObject content
+    expect(svg).toContain("graph-explorer-exported-element");
+    expect(svg).toContain("lemma");
+  });
+
+  test("PNG export produces a real image", async ({ page }) => {
+    const png = await download(page, "Export diagram as PNG");
+
+    // PNG magic number
+    expect([...png.subarray(0, 8)]).toEqual([
+      0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a,
+    ]);
+    expect(png.byteLength).toBeGreaterThan(2000);
+  });
+});