ggaction 0.0.13 → 0.0.16

package/src/actions/theme/reconcile.js

@@ -1,7 +1,27 @@
+import { rematerializeTypography } from "../../materialization/typography.js";
 import { themeTokens } from "../../theme/defaults.js";
+import {
+  normalizeThemeState,
+  resolveEffectiveThemeTokens,
+  setThemeStateOverrides
+} from "./state.js";
 import { findLayer } from "../../selectors/layers.js";
 
-const COLOR_PROPERTIES = Object.freeze(["background", "fill", "stroke"]);
+let rematerializeThemeHighlights = program => program;
+
+export function registerThemeHighlightReconciler(reconciler) {
+  if (typeof reconciler !== "function") {
+    throw new TypeError("Theme highlight reconciler must be a function.");
+  }
+  rematerializeThemeHighlights = reconciler;
+}
+
+const THEME_STYLE_PROPERTIES = Object.freeze([
+  "background",
+  "fill",
+  "stroke",
+  "fontFamily"
+]);
 const COLOR_TOKENS = Object.freeze([
   "mark",
   "text",
@@ -20,51 +40,57 @@ const COLOR_TOKENS = Object.freeze([
   "gradientCenter"
 ]);
 
-function tokenFor(value, names) {
-  for (const name of names) {
-    const tokens = themeTokens(name);
-    for (const token of COLOR_TOKENS) {
-      if (value === tokens[token]) return token;
-    }
-  }
-  return undefined;
+function tokenFor(value, sourceTokens, targetTokens) {
+  const matches = COLOR_TOKENS.filter(token =>
+    value === sourceTokens[token] || value === themeTokens("light")[token]
+  );
+  if (matches.length === 0) return undefined;
+  const targets = new Set(matches.map(token => targetTokens[token]));
+  if (targets.size !== 1) return undefined;
+  return matches[0];
 }
 
-function roleValues(role, names, legacy = []) {
+function roleValues(role, sourceTokens, legacy = []) {
   return new Set([
-    ...names.map(name => themeTokens(name)[role]),
+    sourceTokens[role],
     themeTokens("light")[role],
     ...legacy.map(token => themeTokens("light")[token] ?? token)
   ]);
 }
 
-function mapRoleValue(value, role, names, targetTokens, legacy) {
+function mapRoleValue(value, role, sourceTokens, targetTokens, legacy) {
   if (Array.isArray(value)) {
     let changed = false;
     const next = value.map(item => {
-      const mapped = mapRoleValue(item, role, names, targetTokens, legacy);
+      const mapped = mapRoleValue(
+        item,
+        role,
+        sourceTokens,
+        targetTokens,
+        legacy
+      );
       changed ||= mapped.changed;
       return mapped.value;
     });
     return { changed, value: changed ? next : value };
   }
-  if (!roleValues(role, names, legacy).has(value)) {
+  if (!roleValues(role, sourceTokens, legacy).has(value)) {
     return { changed: false, value };
   }
   return { changed: value !== targetTokens[role], value: targetTokens[role] };
 }
 
-function mapColorValue(value, names, targetTokens) {
+function mapColorValue(value, sourceTokens, targetTokens) {
   if (Array.isArray(value)) {
     let changed = false;
     const next = value.map(item => {
-      const mapped = mapColorValue(item, names, targetTokens);
+      const mapped = mapColorValue(item, sourceTokens, targetTokens);
       changed ||= mapped.changed;
       return mapped.value;
     });
     return { changed, value: changed ? next : value };
   }
-  const token = tokenFor(value, names);
+  const token = tokenFor(value, sourceTokens, targetTokens);
   if (token === undefined) return { changed: false, value };
   const next = targetTokens[token];
   return { changed: next !== value, value: next };
@@ -73,7 +99,10 @@ function mapColorValue(value, names, targetTokens) {
 function isFieldDrivenMark(program, id, property) {
   if (!(["fill", "stroke"].includes(property))) return false;
   const layer = findLayer(program, id);
-  return layer?.encoding?.color?.field !== undefined;
+  return property === "stroke"
+    ? layer?.encoding?.stroke?.field !== undefined ||
+      (layer?.mark?.type === "line" && layer.encoding?.color?.field !== undefined)
+    : layer?.encoding?.color?.field !== undefined;
 }
 
 function isRegressionBand(program, id) {
@@ -128,12 +157,16 @@ function componentRole(program, id, property) {
 }
 
 function graphicRole(program, id, property) {
+  if (property === "fontFamily") return "fontFamily";
   if (id === "canvas" && property === "background") return "background";
+  if (id === `${program.compositionSpec?.id}-headers` && property === "fill") {
+    return "strongText";
+  }
   const component = componentRole(program, id, property);
   if (component !== undefined) return component;
   const layer = findLayer(program, id);
   if (layer !== undefined && ["fill", "stroke"].includes(property)) {
-    if (layer.encoding?.color?.field !== undefined) return undefined;
+    if (isFieldDrivenMark(program, id, property)) return undefined;
     if (property === "fill" && isRegressionBand(program, id)) {
       return "regressionBand";
     }
@@ -176,7 +209,7 @@ function isOverridden(overrides, key) {
 }
 
 function isFieldDrivenLegendSymbol(id) {
-  return /(?:color|series)Legend(?:Symbol|Symbols|Gradient|Swatches|Lines|Points)/iu
+  return /(?:color|series|stroke)(?:Legend|Gradient|Interval)(?:Symbol|Symbols|Strips|Swatches|Lines|Points)/iu
     .test(id);
 }
 
@@ -185,14 +218,14 @@ function mapGraphicProperties(
   id,
   type,
   properties,
-  names,
+  sourceTokens,
   targetTokens,
   overrides,
   overrideId = id
 ) {
   let changed = false;
   const next = { ...properties };
-  for (const property of COLOR_PROPERTIES) {
+  for (const property of THEME_STYLE_PROPERTIES) {
     if (!Object.hasOwn(properties, property)) continue;
     if (isOverridden(overrides, `g:${overrideId}.${property}`) ||
         isOverridden(overrides, `g:${id}.${property}`)) continue;
@@ -202,7 +235,7 @@ function mapGraphicProperties(
     const mapped = mapRoleValue(
       properties[property],
       role,
-      names,
+      sourceTokens,
       targetTokens,
       roleLegacy(role)
     );
@@ -214,21 +247,28 @@ function mapGraphicProperties(
   return { changed, properties: changed ? next : properties, type };
 }
 
-function recolorGraphic(program, id, graphic, names, targetTokens, overrides) {
+function recolorGraphic(
+  program,
+  id,
+  graphic,
+  sourceTokens,
+  targetTokens,
+  overrides
+) {
   if (graphic.items === undefined) {
     const mapped = mapGraphicProperties(
       program,
       id,
       graphic.type,
       graphic.properties,
-      names,
+      sourceTokens,
       targetTokens,
       overrides,
       id
     );
     if (!mapped.changed) return program;
     let next = program;
-    for (const property of COLOR_PROPERTIES) {
+    for (const property of THEME_STYLE_PROPERTIES) {
       if (mapped.properties[property] !== graphic.properties[property]) {
         next = next.editGraphics({
           target: id,
@@ -248,7 +288,7 @@ function recolorGraphic(program, id, graphic, names, targetTokens, overrides) {
       id,
       type,
       item.properties,
-      names,
+      sourceTokens,
       targetTokens,
       overrides,
       item.id
@@ -263,6 +303,13 @@ function recolorGraphic(program, id, graphic, names, targetTokens, overrides) {
 
 function configRole(program, path) {
   const property = path.at(-1);
+  if (property === "fontFamily") return "fontFamily";
+  if (path[0] === "facets" && path.includes("headers") &&
+      property === "color") {
+    return path[path.indexOf("headers") + 1] === "row"
+      ? "mutedText"
+      : "strongText";
+  }
   if (path[0] === "marks" && ["fill", "stroke"].includes(property)) {
     if (path.includes("boxPlot") && path.includes("median") &&
         property === "stroke") return "boxMedian";
@@ -271,7 +318,7 @@ function configRole(program, path) {
     const component = componentRole(program, path[1], property);
     if (component !== undefined) return component;
     const layer = findLayer(program, path[1]);
-    if (layer?.encoding?.color?.field !== undefined) return undefined;
+    if (isFieldDrivenMark(program, path[1], property)) return undefined;
     if (property === "fill" && isRegressionBand(program, path[1])) {
       return "regressionBand";
     }
@@ -298,7 +345,7 @@ function configRole(program, path) {
 function recolorConfig(
   program,
   value,
-  names,
+  sourceTokens,
   targetTokens,
   overrides,
   path = []
@@ -309,7 +356,7 @@ function recolorConfig(
       const mapped = recolorConfig(
         program,
         item,
-        names,
+        sourceTokens,
         targetTokens,
         overrides,
         [...path, index]
@@ -321,7 +368,8 @@ function recolorConfig(
   }
   if (value === null || typeof value !== "object") {
     const property = path.at(-1);
-    if (!["color", "fill", "stroke", "background"].includes(property)) {
+    if (!["color", "fill", "stroke", "background", "fontFamily"]
+      .includes(property)) {
       return { changed: false, value };
     }
     if (isOverridden(overrides, `c:${path.join(".")}`)) {
@@ -332,8 +380,14 @@ function recolorConfig(
     }
     const role = configRole(program, path);
     return role === undefined
-      ? mapColorValue(value, names, targetTokens)
-      : mapRoleValue(value, role, names, targetTokens, roleLegacy(role));
+      ? mapColorValue(value, sourceTokens, targetTokens)
+      : mapRoleValue(
+          value,
+          role,
+          sourceTokens,
+          targetTokens,
+          roleLegacy(role)
+        );
   }
   if (["theme", "highlights", "selections"].includes(path[0])) {
     return { changed: false, value };
@@ -344,7 +398,7 @@ function recolorConfig(
     const mapped = recolorConfig(
       program,
       item,
-      names,
+      sourceTokens,
       targetTokens,
       overrides,
       [...path, key]
@@ -355,6 +409,11 @@ function recolorConfig(
   return { changed, value: changed ? next : value };
 }
 
+function addMarkPropertyOverrides(overrides, id, property) {
+  overrides.add(`c:marks.${id}.${property}`);
+  overrides.add(`g:${id}.${property}`);
+}
+
 function addMarkOverrides(overrides, program, op, args) {
   const match = /^(?:create|edit)(Point|Line|Area|Arc|Bar|Rect|Rule|Tick|Text)Mark$/u
     .exec(op);
@@ -367,44 +426,45 @@ function addMarkOverrides(overrides, program, op, args) {
     (op.startsWith("create") ? type : undefined) ??
     (candidates.length === 1 ? candidates[0].id : program.context.currentMark);
   if (typeof id !== "string") return;
-  for (const property of ["fill", "stroke"]) {
+  for (const property of ["fill", "stroke", "fontFamily"]) {
     if (!Object.hasOwn(args, property)) continue;
-    overrides.add(`c:marks.${id}.${property}`);
-    overrides.add(`g:${id}.${property}`);
+    addMarkPropertyOverrides(overrides, id, property);
   }
 }
 
 function addFacadeMarkOverrides(overrides, op, args) {
   const facades = {
-    createScatterPlot: ["scatterPlot", "point", ["fill", "stroke"]],
-    createLinePlot: ["linePlot", "line", ["stroke"]],
-    createPolarScatterPlot: ["polarScatterPlot", "point", ["fill", "stroke"]],
-    createPolarLinePlot: ["polarLinePlot", "line", ["stroke"]],
-    createRadarPlot: ["radarPlot", "line", ["stroke"]],
-    createRugPlot: ["rugPlot", "tick", ["stroke"]],
-    createStripPlot: ["stripPlot", "point", ["fill", "stroke"]],
-    createBeeswarmPlot: ["beeswarmPlot", "point", ["fill", "stroke"]],
-    createBarPlot: ["barPlot", "bar", ["fill", "stroke"]],
-    createAreaPlot: ["areaPlot", "area", ["fill", "stroke"]],
-    createPiePlot: ["piePlot", "arc", ["fill", "stroke"]],
-    createRosePlot: ["rosePlot", "arc", ["fill", "stroke"]],
-    createRadialBarPlot: ["radialBarPlot", "arc", ["fill", "stroke"]],
-    createDensityPlot: ["densityPlot", "area", ["fill", "stroke"]],
-    createParallelCoordinates: ["parallelCoordinates", "line", ["stroke"]],
-    createHistogram: ["histogram", "bar", ["fill", "stroke"]],
-    createHeatmap: ["heatmap", "rect", ["stroke"]],
-    createHorizonPlot: ["horizonPlot", "area", ["stroke"]],
-    editHorizon: ["horizonPlot", "area", ["stroke"]],
-    createViolinPlot: ["violinPlot", "area", ["fill", "stroke"]]
+    createScatterPlot: ["point", true],
+    createLinePlot: ["line", false],
+    createPolarScatterPlot: ["point", true],
+    createPolarLinePlot: ["line", false],
+    createRadarPlot: ["line", false],
+    createRugPlot: ["tick", false],
+    createStripPlot: ["point", true],
+    createBeeswarmPlot: ["point", true],
+    createBarPlot: ["bar", true],
+    createAreaPlot: ["area", true],
+    createPiePlot: ["arc", true],
+    createRosePlot: ["arc", true],
+    createRadialBarPlot: ["arc", true],
+    createDensityPlot: ["area", true],
+    createParallelCoordinates: ["line", false],
+    createHistogram: ["bar", true],
+    createHeatmap: ["rect", false],
+    createHorizonPlot: ["area", false],
+    editHorizon: ["area", false],
+    createViolinPlot: ["area", true]
   };
   const facade = facades[op];
   if (facade === undefined) return;
-  const [defaultId, option, properties] = facade;
+  const [option, includesFill] = facade;
+  const subject = op === "editHorizon" ? "HorizonPlot" : op.slice(6);
+  const defaultId = subject[0].toLowerCase() + subject.slice(1);
+  const properties = includesFill ? ["fill", "stroke"] : ["stroke"];
   const id = args.id ?? defaultId;
   for (const property of properties) {
     if (!Object.hasOwn(args[option] ?? {}, property)) continue;
-    overrides.add(`c:marks.${id}.${property}`);
-    overrides.add(`g:${id}.${property}`);
+    addMarkPropertyOverrides(overrides, id, property);
   }
 }
 
@@ -431,12 +491,13 @@ function resolveConfiguredOwner(program, key, requested, defaultId) {
 }
 
 function addTextFacadeOverrides(overrides, node) {
-  if (!["createAnnotation", "createMarkLabels"].includes(node.op) ||
-      !Object.hasOwn(node.args, "fill")) return;
+  if (!["createAnnotation", "createMarkLabels"].includes(node.op)) return;
   const id = findDescendant(node, "createTextMark")?.args.id ?? node.args.id;
   if (typeof id !== "string") return;
-  overrides.add(`c:marks.${id}.fill`);
-  overrides.add(`g:${id}.fill`);
+  for (const property of ["fill", "fontFamily"]) {
+    if (!Object.hasOwn(node.args, property)) continue;
+    addMarkPropertyOverrides(overrides, id, property);
+  }
 }
 
 function addErrorBarOverrides(overrides, program, node) {
@@ -451,8 +512,7 @@ function addErrorBarOverrides(overrides, program, node) {
   if (id === undefined) return;
   const config = program.markConfigs[id].errorBar;
   for (const target of [id, config.lowerCapId, config.upperCapId]) {
-    overrides.add(`c:marks.${target}.stroke`);
-    overrides.add(`g:${target}.stroke`);
+    addMarkPropertyOverrides(overrides, target, "stroke");
   }
 }
 
@@ -478,8 +538,7 @@ function addErrorBandOverrides(overrides, program, node) {
   const targets = errorBandTargets(program, node);
   if (targets === undefined) return;
   if (Object.hasOwn(node.args, "fill") && node.args.fill !== false) {
-    overrides.add(`c:marks.${targets.id}.fill`);
-    overrides.add(`g:${targets.id}.fill`);
+    addMarkPropertyOverrides(overrides, targets.id, "fill");
   }
   const boundary = node.op === "editErrorBandBoundary"
     ? node.args
@@ -490,8 +549,7 @@ function addErrorBandOverrides(overrides, program, node) {
     ? [targets.lower, targets.upper]
     : [(node.args.boundary === "lower" ? targets.lower : targets.upper)];
   for (const id of ids) {
-    overrides.add(`c:marks.${id}.stroke`);
-    overrides.add(`g:${id}.stroke`);
+    addMarkPropertyOverrides(overrides, id, "stroke");
   }
 }
 
@@ -531,8 +589,7 @@ function addReferenceOverrides(overrides, op, args) {
   const id = args.id ?? defaultId;
   for (const property of properties) {
     if (!Object.hasOwn(args, property)) continue;
-    overrides.add(`c:marks.${id}.${property}`);
-    overrides.add(`g:${id}.${property}`);
+    addMarkPropertyOverrides(overrides, id, property);
   }
 }
 
@@ -553,12 +610,10 @@ function addRegressionOverrides(overrides, node) {
       : child?.args.id ?? child?.args.target;
   if (typeof id !== "string") return;
   if (Object.hasOwn(style ?? {}, "color")) {
-    overrides.add(`c:marks.${id}.fill`);
-    overrides.add(`g:${id}.fill`);
+    addMarkPropertyOverrides(overrides, id, "fill");
   }
   if (Object.hasOwn(style ?? {}, "stroke")) {
-    overrides.add(`c:marks.${id}.stroke`);
-    overrides.add(`g:${id}.stroke`);
+    addMarkPropertyOverrides(overrides, id, "stroke");
   }
 }
 
@@ -651,7 +706,7 @@ function clearRecreatedOverrides(overrides, op, args) {
 function addAxisOverrides(overrides, op, args) {
   const match = /^(?:create|edit)(X|Y|Theta|Radial)Axis(Line|Ticks|Labels|Title)$/u
     .exec(op);
-  if (match === null || !Object.hasOwn(args, "color")) return;
+  if (match === null) return;
   const channel = {
     X: "x",
     Y: "y",
@@ -660,10 +715,17 @@ function addAxisOverrides(overrides, op, args) {
   }[match[1]];
   const component = match[2].toLowerCase();
   const idPrefix = match[1] === "Radial" ? "radial" : channel;
-  overrides.add(`c:guides.axis.${channel}.${component}.color`);
-  overrides.add(
-    `g:${idPrefix}Axis${match[2]}.${component === "line" || component === "ticks" ? "stroke" : "fill"}`
-  );
+  if (Object.hasOwn(args, "color")) {
+    overrides.add(`c:guides.axis.${channel}.${component}.color`);
+    overrides.add(
+      `g:${idPrefix}Axis${match[2]}.${component === "line" || component === "ticks" ? "stroke" : "fill"}`
+    );
+  }
+  if (["labels", "title"].includes(component) &&
+      Object.hasOwn(args, "fontFamily")) {
+    overrides.add(`c:guides.axis.${channel}.${component}.fontFamily`);
+    overrides.add(`g:${idPrefix}Axis${match[2]}.fontFamily`);
+  }
 }
 
 function addCompleteAxisOverride(overrides, name, args) {
@@ -680,12 +742,18 @@ function addCompleteAxisOverride(overrides, name, args) {
     components.labels = args.ticksAndLabels.labels;
   }
   for (const [component, options] of Object.entries(components)) {
-    if (!Object.hasOwn(options ?? {}, "color")) continue;
     const suffix = `${component[0].toUpperCase()}${component.slice(1)}`;
-    overrides.add(`c:guides.axis.${channel}.${component}.color`);
-    overrides.add(
-      `g:${idPrefix}Axis${suffix}.${component === "line" || component === "ticks" ? "stroke" : "fill"}`
-    );
+    if (Object.hasOwn(options ?? {}, "color")) {
+      overrides.add(`c:guides.axis.${channel}.${component}.color`);
+      overrides.add(
+        `g:${idPrefix}Axis${suffix}.${component === "line" || component === "ticks" ? "stroke" : "fill"}`
+      );
+    }
+    if (["labels", "title"].includes(component) &&
+        Object.hasOwn(options ?? {}, "fontFamily")) {
+      overrides.add(`c:guides.axis.${channel}.${component}.fontFamily`);
+      overrides.add(`g:${idPrefix}Axis${suffix}.fontFamily`);
+    }
   }
 }
 
@@ -722,9 +790,14 @@ function addTitleOverrides(overrides, args) {
     ["titleStyle", "chartTitle"],
     ["subtitleStyle", "chartSubtitle"]
   ]) {
-    if (!Object.hasOwn(args[option] ?? {}, "color")) continue;
-    overrides.add(`c:title.${option}.color`);
-    overrides.add(`g:${id}.fill`);
+    if (Object.hasOwn(args[option] ?? {}, "color")) {
+      overrides.add(`c:title.${option}.color`);
+      overrides.add(`g:${id}.fill`);
+    }
+    if (Object.hasOwn(args[option] ?? {}, "fontFamily")) {
+      overrides.add(`c:title.${option}.fontFamily`);
+      overrides.add(`g:${id}.fontFamily`);
+    }
   }
 }
 
@@ -744,46 +817,110 @@ function addParallelOverrides(overrides, program, op, args) {
     components.labels = args.ticksAndLabels.labels;
   }
   for (const [component, options] of Object.entries(components)) {
-    if (!Object.hasOwn(options ?? {}, "color")) continue;
-    overrides.add(
-      `c:guides.axis.parallel.axes.dimensions.${index}.${component}.color`
-    );
+    if (Object.hasOwn(options ?? {}, "color")) {
+      overrides.add(
+        `c:guides.axis.parallel.axes.dimensions.${index}.${component}.color`
+      );
+    }
+    if (["labels", "title"].includes(component) &&
+        Object.hasOwn(options ?? {}, "fontFamily")) {
+      overrides.add(
+        `c:guides.axis.parallel.axes.dimensions.${index}.${component}.fontFamily`
+      );
+    }
   }
 }
 
 function addLegendOverrides(overrides, program, args) {
-  const legend = program.guideConfigs.legend ?? {};
-  const prefixes = {
+  for (const kind of Object.keys(program.guideConfigs.legend ?? {})) {
+    const prefix = legendPrefix(kind);
+    for (const [option, suffix, property, graphicProperty] of [
+      ["labels", "Labels", "color", "fill"],
+      ["labels", "Labels", "fontFamily", "fontFamily"],
+      ["titleStyle", "Title", "color", "fill"],
+      ["titleStyle", "Title", "fontFamily", "fontFamily"],
+      ["border", "Background", "color", "stroke"]
+    ]) {
+      if (!Object.hasOwn(args[option] ?? {}, property)) continue;
+      overrides.add(`c:guides.legend.${kind}.${option}.${property}`);
+      if (prefix) overrides.add(`g:${prefix}${suffix}.${graphicProperty}`);
+    }
+  }
+}
+
+function legendPrefix(kind) {
+  return {
     series: "seriesLegend",
     color: "colorLegend",
+    stroke: "strokeLegend",
     interval: "colorLegend",
     gradient: "colorGradient",
+    strokeInterval: "strokeInterval",
+    strokeGradient: "strokeGradient",
     size: "sizeLegend",
     strokeWidth: "strokeWidthLegend",
     opacity: "opacityLegend"
-  };
-  for (const kind of Object.keys(legend)) {
-    if (Object.hasOwn(args.labels ?? {}, "color")) {
-      overrides.add(`c:guides.legend.${kind}.labels.color`);
-      if (prefixes[kind]) overrides.add(`g:${prefixes[kind]}Labels.fill`);
-    }
-    if (Object.hasOwn(args.titleStyle ?? {}, "color")) {
-      overrides.add(`c:guides.legend.${kind}.titleStyle.color`);
-      if (prefixes[kind]) overrides.add(`g:${prefixes[kind]}Title.fill`);
+  }[kind];
+}
+
+function addLegendBlockOverrides(overrides, program, args) {
+  if (typeof args.target !== "string" || typeof args.channel !== "string") return;
+  for (const [kind, config] of Object.entries(program.guideConfigs.legend ?? {})) {
+    if (config.target !== args.target) continue;
+    const key = Object.keys(config.blockOverrides ?? {}).find(value => {
+      try {
+        return JSON.parse(value).includes(args.channel);
+      } catch {
+        return false;
+      }
+    });
+    if (key === undefined) continue;
+    const prefix = `c:guides.legend.${kind}.blockOverrides.${key}`;
+    const graphic = legendPrefix(kind);
+    for (const [property, graphicProperty] of [
+      ["color", "fill"],
+      ["fontFamily", "fontFamily"]
+    ]) {
+      if (!Object.hasOwn(args.text ?? {}, property)) continue;
+      overrides.add(`${prefix}.text.${property}`);
+      if (graphic !== undefined) {
+        overrides.add(`g:${graphic}Labels.${graphicProperty}`);
+      }
     }
-    if (Object.hasOwn(args.border ?? {}, "color")) {
-      overrides.add(`c:guides.legend.${kind}.border.color`);
-      if (prefixes[kind]) overrides.add(`g:${prefixes[kind]}Background.stroke`);
+    for (const property of ["fill", "stroke"]) {
+      if (!Object.hasOwn(args.symbol ?? {}, property)) continue;
+      overrides.add(`${prefix}.symbol.${property}`);
+      if (graphic !== undefined) {
+        overrides.add(`g:${graphic}Symbols.${property}`);
+      }
     }
   }
 }
 
+function addFacetOverrides(overrides, program, args) {
+  const id = program.compositionSpec?.type === "facet"
+    ? program.compositionSpec.id
+    : undefined;
+  if (id === undefined) return;
+  const owner = args.role === undefined || args.role === "all"
+    ? "common"
+    : args.role;
+  for (const [property, graphicProperty] of [
+    ["color", "fill"],
+    ["fontFamily", "fontFamily"]
+  ]) {
+    if (!Object.hasOwn(args, property)) continue;
+    overrides.add(`c:facets.${id}.headers.${owner}.${property}`);
+    overrides.add(`g:${id}-headers.${graphicProperty}`);
+  }
+}
+
 function explicitOverrides(program, node) {
   const { op, args } = node;
   const overrides = new Set();
   if (op === "editGraphics" &&
       typeof args.target === "string" &&
-      ["background", "fill", "stroke"].includes(args.property)) {
+      ["background", "fill", "stroke", "fontFamily"].includes(args.property)) {
     overrides.add(`g:${args.target}.${args.property}`);
   }
   if (["createCanvas", "editCanvas"].includes(op) &&
@@ -818,6 +955,12 @@ function explicitOverrides(program, node) {
   if (op === "editLegendBorder") {
     addLegendOverrides(overrides, program, args);
   }
+  if (op === "editLegendBlock") {
+    addLegendBlockOverrides(overrides, program, args);
+  }
+  if (op === "editFacetHeaders") {
+    addFacetOverrides(overrides, program, args);
+  }
   return overrides;
 }
 
@@ -836,22 +979,41 @@ function collectOverrides(program) {
 }
 
 export function reconcileProgramTheme(program, { source, metadata }) {
-  const state = program.materializationConfigs.theme;
-  if (state === undefined) return program;
-  const sourceName = source.materializationConfigs.theme?.name ?? "light";
-  const targetTokens = themeTokens(state.name);
-  const names = sourceName === "light" ? ["light"] : [sourceName, "light"];
+  const storedState = program.materializationConfigs.theme;
+  if (storedState === undefined) return program;
+  // Data/context/trace-only transitions cannot change authored appearance.
+  // Preserve all visual identities instead of rescanning every existing mark.
+  if (program.graphicSpec === source.graphicSpec &&
+      program.materializationConfigs === source.materializationConfigs &&
+      program.children === source.children &&
+      program.compositionSpec === source.compositionSpec &&
+      ["layers", "scales", "coordinates", "guides", "title"].every(
+        key => program.semanticSpec[key] === source.semanticSpec[key]
+      )) return program;
+  const composition = program.compositionSpec !== undefined;
+  const state = normalizeThemeState(storedState, { composition });
+  const sourceState = normalizeThemeState(
+    source.materializationConfigs.theme,
+    { composition }
+  );
+  const sourceRootTokens = resolveEffectiveThemeTokens(sourceState);
+  const targetRootTokens = resolveEffectiveThemeTokens(state);
+  const contentState = current => composition
+    ? { frames: current.frames.filter(frame => frame.scope === "descendants") }
+    : current;
+  const sourceTokens = resolveEffectiveThemeTokens(contentState(sourceState));
+  const targetTokens = resolveEffectiveThemeTokens(contentState(state));
   const overrides = collectOverrides(program);
 
-  let themed = program._withMaterializationConfig(["theme"], {
-    ...state,
-    overrides: [...overrides].sort()
-  });
+  let themed = program._withMaterializationConfig(
+    ["theme"],
+    setThemeStateOverrides(state, [...overrides])
+  );
 
   const configs = recolorConfig(
     themed,
     themed.materializationConfigs,
-    names,
+    sourceTokens,
     targetTokens,
     overrides
   );
@@ -863,19 +1025,49 @@ export function reconcileProgramTheme(program, { source, metadata }) {
   if (configs.changed && configs.value.title !== undefined) {
     next = next._withMaterializationConfig(["title"], configs.value.title);
   }
+  if (configs.changed && configs.value.facets !== undefined) {
+    next = next._withMaterializationConfig(["facets"], configs.value.facets);
+  }
+
+  const facetsChanged = configs.value.facets !==
+    themed.materializationConfigs.facets;
+  const typographyChanged = sourceTokens.fontFamily !== targetTokens.fontFamily;
+  if (facetsChanged && next.compositionSpec?.type === "facet") {
+    next = next.materializeComposition();
+  } else if (typographyChanged) {
+    next = rematerializeTypography(next);
+  }
 
   const parallelChanged = configs.value.guides.axis?.parallel !==
     themed.guideConfigs.axis?.parallel;
-  if (parallelChanged && typeof next.rematerializeParallelAxes === "function") {
+  if (parallelChanged && !typographyChanged && typeof next.rematerializeParallelAxes === "function") {
     next = next.rematerializeParallelAxes();
   }
 
   for (const [id, graphic] of Object.entries(next.graphicSpec.objects)) {
     if (parallelChanged && id.startsWith("parallelAxis")) continue;
-    next = recolorGraphic(next, id, graphic, names, targetTokens, overrides);
+    const graphicSourceTokens = id === "canvas"
+      ? sourceRootTokens
+      : sourceTokens;
+    const graphicTargetTokens = id === "canvas"
+      ? targetRootTokens
+      : targetTokens;
+    next = recolorGraphic(
+      next,
+      id,
+      graphic,
+      graphicSourceTokens,
+      graphicTargetTokens,
+      overrides
+    );
+  }
+
+  if (sourceTokens.highlight !== targetTokens.highlight) {
+    next = rematerializeThemeHighlights(next);
   }
 
-  if (state.removing === true && metadata.op === "removeTheme") {
+  if (metadata.op === "removeTheme" && state.frames.length === 0 &&
+      (state.descendantFrames?.length ?? 0) === 0) {
     next = next._withoutMaterializationConfig(["theme"]);
   }
   return next;