fix(library): keep custom-colored elements visible in exports (#829)

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: FelixTJDietrich

.changeset/colored-elements-export-visible.md

@@ -0,0 +1,5 @@
+---
+"@tumaet/apollon": patch
+---
+
+Fix custom-colored elements vanishing from exports. Picking a swatch line/fill/text colour stored it as a bare `var(--apollon-swatch-*)` with no fallback, and the compat export pipeline (SVG, PNG, PDF, PPTX, server, VS Code) had no static value for those tokens, so it resolved them to an empty string — the coloured stroke/fill disappeared and only the default-black text survived. The swatch palette now has export fallbacks, so custom-coloured elements render in every format and diagram type (using the light-theme swatch value, matching the rest of the export pipeline). A test keeps the fallbacks in lockstep with the palette so retuning a swatch can't silently drift the exported colour.

library/lib/constants.ts

@@ -92,6 +92,19 @@ export const CSS_VARIABLE_FALLBACKS: Readonly<Record<string, string>> =
     "--apollon-collaboration-color-8": "#1098ad",
     "--apollon-guide-vertical": "#d63031",
     "--apollon-guide-horizontal": "#0984e3",
+    // Color-picker swatches are stored as a fallback-less `var(--apollon-swatch-*)`,
+    // so without a value here a swatched element resolves to "" and vanishes from
+    // headless/compat export (issue #828). Light-theme primitives, like the rest of
+    // this map; kept in sync with tokens.css by cssVariableContract.test.ts.
+    "--apollon-swatch-slate": "#64748b",
+    "--apollon-swatch-red": "#dc2626",
+    "--apollon-swatch-orange": "#ea580c",
+    "--apollon-swatch-amber": "#d97706",
+    "--apollon-swatch-green": "#16a34a",
+    "--apollon-swatch-teal": "#0d9488",
+    "--apollon-swatch-blue": "#2563eb",
+    "--apollon-swatch-violet": "#7c3aed",
+    "--apollon-swatch-pink": "#db2777",
     "--apollon-background": "#ffffff",
     "--apollon-background-variant": "#f8f9fa",
     "--apollon-hover-neutral":

library/tests/unit/cssVariableContract.test.ts

@@ -1,6 +1,7 @@
 import { describe, it, expect } from "vitest"
 import { readFileSync } from "node:fs"
 import { resolve } from "node:path"
+import { SWATCH_NAMES } from "@tumaet/ui/lib/color-swatch-tokens"
 import { CSS_VARIABLE_FALLBACKS } from "@/constants"
 
 // Drift guard for the design-token contract.
@@ -63,3 +64,39 @@ describe("CSS variable contract: CSS_VARIABLE_FALLBACKS ⊆ THEMING.md ∩ token
     }
   )
 })
+
+// The color-picker swatches are the one token family a user can paint directly
+// onto exported geometry (as `var(--apollon-swatch-*)` with no inline fallback),
+// so unlike the general one-directional guard above they MUST have a compat
+// fallback or the element vanishes from every headless/embed export (issue
+// #828). And because the fallback duplicates a hex that really lives in
+// tokens.css, guard the VALUE too: each fallback must equal the light-theme
+// `--primitive-swatch-*` the swatch resolves to, so retuning the palette can't
+// silently ship a stale export color.
+//
+// tokens.css layers `--apollon-swatch-red: var(--primitive-swatch-red)` and
+// `--primitive-swatch-red: #dc2626`; the hex lives in the primitive, defined
+// once for light (`:root`, authored first) and again for the dark override.
+// Compat export is always light (like every other entry in the fallback map),
+// so read the first — i.e. light — declaration of each primitive.
+const lightPrimitiveHex = (name: string): string | undefined =>
+  tokensCss.match(
+    new RegExp(`--primitive-swatch-${name}\\s*:\\s*(#[0-9a-fA-F]{3,8})`)
+  )?.[1]
+
+describe("swatch tokens ⊆ CSS_VARIABLE_FALLBACKS (export must never blank or drift a swatch)", () => {
+  it.each(SWATCH_NAMES)(
+    "--apollon-swatch-%s exports the light-theme primitive hex",
+    (name) => {
+      const fallback = CSS_VARIABLE_FALLBACKS[`--apollon-swatch-${name}`]
+      expect(
+        fallback,
+        `--apollon-swatch-${name} has no CSS_VARIABLE_FALLBACKS entry; a swatch of this color would export invisible`
+      ).toBeDefined()
+      expect(
+        fallback,
+        `--apollon-swatch-${name} fallback ${fallback} != light --primitive-swatch-${name} ${lightPrimitiveHex(name)} in tokens.css — retune both together`
+      ).toBe(lightPrimitiveHex(name))
+    }
+  )
+})

library/tests/unit/exportUtils.test.ts

@@ -309,6 +309,42 @@ describe("replaceCSSVariables", () => {
   })
 })
 
+// ---------------------------------------------------------------------------
+// Swatch color export (issue #828)
+//
+// A chosen swatch is stored as a fallback-less `var(--apollon-swatch-*)`
+// (ColorButtons.tsx). While those tokens were absent from
+// CSS_VARIABLE_FALLBACKS the compat export resolved them to "", wiping the
+// element's stroke/fill and leaving only the default-black text. (All swatches
+// are guarded present in cssVariableContract.test.ts; here we assert the paint
+// actually survives the export path.)
+// ---------------------------------------------------------------------------
+describe("swatch color export (issue #828)", () => {
+  let svg: SVGSVGElement
+
+  beforeEach(() => {
+    svg = document.createElementNS("http://www.w3.org/2000/svg", "svg")
+  })
+
+  it("resolves a fallback-less swatch color to its hex", () => {
+    const rect = document.createElementNS("http://www.w3.org/2000/svg", "rect")
+    rect.setAttribute("stroke", "var(--apollon-swatch-red)")
+    svg.appendChild(rect)
+
+    replaceCSSVariables(svg)
+    expect(rect.getAttribute("stroke")).toBe("#dc2626")
+  })
+
+  it("leaves a native custom hex untouched", () => {
+    const rect = document.createElementNS("http://www.w3.org/2000/svg", "rect")
+    rect.setAttribute("stroke", "#123456")
+    svg.appendChild(rect)
+
+    replaceCSSVariables(svg)
+    expect(rect.getAttribute("stroke")).toBe("#123456")
+  })
+})
+
 // ---------------------------------------------------------------------------
 // convertStyleToAttributes
 // ---------------------------------------------------------------------------