ggaction 0.0.3 → 0.0.5

package/src/materialization/dataProvenance.js

@@ -1,4 +1,56 @@
-import { findDataset } from "../selectors/datasets.js";
+import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
+import { validateUserId } from "../core/identifiers.js";
+import { findTransformPolicy } from "../grammar/transforms.js";
+import { findDataset, hasDataset } from "../selectors/datasets.js";
+import { requireLayer } from "../selectors/layers.js";
+
+function validateRevisionRole(value) {
+  if (typeof value !== "string" || !/^[A-Za-z][A-Za-z0-9]*$/.test(value)) {
+    throw new TypeError(
+      "Derived dataset revision role must be an alphanumeric identifier."
+    );
+  }
+  return value;
+}
+
+function nextRevisionId(program, owner, role) {
+  let revision = 1;
+  const prefix = `${owner}${role}Revision`;
+  while (hasDataset(program, `${prefix}${revision}`)) revision += 1;
+  return `${prefix}${revision}`;
+}
+
+export function planDerivedDataRevision(program, options = {}) {
+  if (!isPlainObject(options)) {
+    throw new TypeError("Derived dataset revision options must be a plain object.");
+  }
+  const owner = validateUserId(options.owner, "Derived dataset revision owner");
+  const role = validateRevisionRole(options.role);
+  const previous = options.previous === undefined
+    ? undefined
+    : validateUserId(options.previous, "Previous derived dataset id");
+  if (previous !== undefined && !hasDataset(program, previous)) {
+    throw new Error(`Unknown previous derived dataset "${previous}".`);
+  }
+  if (!Array.isArray(options.consumers)) {
+    throw new TypeError("Derived dataset revision consumers must be an array.");
+  }
+  const consumers = options.consumers.map(id => {
+    const validated = validateUserId(id, "Derived dataset consumer id");
+    requireLayer(program, validated);
+    return validated;
+  });
+  if (new Set(consumers).size !== consumers.length) {
+    throw new Error("Derived dataset revision consumers must be unique.");
+  }
+  const id = nextRevisionId(program, owner, role);
+  return cloneAndFreeze({
+    id,
+    ...(previous === undefined ? {} : { previous }),
+    rebinds: consumers.map(consumer => ({ id: consumer, data: id })),
+    ...(previous === undefined ? {} : { release: { id: previous } })
+  });
+}
 
 export function findUpstreamTransform(program, dataset, type) {
   const visited = new Set();
@@ -8,7 +60,9 @@ export function findUpstreamTransform(program, dataset, type) {
     if (current.transform?.length !== 1) return undefined;
     const transform = current.transform[0];
     if (transform.type === type) return transform;
-    if (transform.type !== "markFilter") return undefined;
+    if (findTransformPolicy(transform.type)?.provenanceTransparent !== true) {
+      return undefined;
+    }
     current = findDataset(program, current.source);
   }
   return undefined;

package/src/materialization/density.js

@@ -1,4 +1,4 @@
-import { getMarkMaterializationStep } from "./marks.js";
+import { getMarkMaterializationStep } from "./marks/index.js";
 import { requireLayer } from "../selectors/layers.js";
 import { buildMaterializationPlan } from "./planner.js";
 

package/src/materialization/dependencies.js

@@ -3,54 +3,24 @@ import {
   getExistingMarkRematerializationStep,
   getMarkMaterializationStep,
   getSourceDependentMarkSteps
-} from "./marks.js";
+} from "./marks/index.js";
 import { requireLayer } from "../selectors/layers.js";
 import {
   applyMaterializationPlan,
   buildMaterializationPlan
 } from "./planner.js";
+import { hasMaterializedLegend } from "./legends.js";
 import {
-  hasMaterializedLegend,
-  materializedLegendUsesScale
-} from "./legends.js";
-import { POSITION_ENCODING_CHANNELS } from "../core/vocabulary.js";
+  needsCanvasScaleRematerialization,
+  planScaleGuideRematerialization
+} from "./scaleGuideDependencies.js";
+import { planLayoutRematerialization } from "./layout.js";
 
-function usesPositionalScale(program, id) {
-  return program.semanticSpec.layers.some(layer =>
-    POSITION_ENCODING_CHANNELS.some(
-      channel => layer.encoding?.[channel]?.scale === id
-    )
-  );
-}
-
-function usesRadialScale(program, id) {
-  return program.semanticSpec.layers.some(layer =>
-    layer.encoding?.radius?.scale === id
-  );
-}
-
-function needsCanvasScaleRematerialization(program, scale) {
-  return (
-    (scale.range === "auto" ||
-      usesRadialScale(program, scale.id) ||
-      program.semanticSpec.guides.axis?.x?.scale === scale.id ||
-      program.semanticSpec.guides.axis?.y?.scale === scale.id ||
-      program.semanticSpec.guides.axis?.theta?.scale === scale.id ||
-      program.semanticSpec.guides.axis?.radius?.scale === scale.id ||
-      program.semanticSpec.guides.grid?.horizontal?.scale === scale.id ||
-      program.semanticSpec.guides.grid?.vertical?.scale === scale.id ||
-      program.semanticSpec.guides.grid?.theta?.scale === scale.id ||
-      program.semanticSpec.guides.grid?.radial?.scale === scale.id) &&
-    program.resolvedScales[scale.id] !== undefined &&
-    usesPositionalScale(program, scale.id)
-  );
-}
-
-function hasTitle(program) {
-  return (
-    program.semanticSpec.title.text !== undefined &&
-    program.titleConfig !== undefined
-  );
+function layerScaleIds(layer) {
+  return [
+    ...Object.values(layer.encoding ?? {}).map(encoding => encoding?.scale),
+    ...(layer.encoding?.parallel?.dimensions ?? []).map(dimension => dimension.scale)
+  ].filter(scale => scale !== undefined);
 }
 
 export function planCanvasRematerialization(program) {
@@ -68,9 +38,7 @@ export function planCanvasRematerialization(program) {
     if (needsCanvasScaleRematerialization(program, scale)) {
       const deferredConsumers = program.semanticSpec.layers.filter(layer =>
         canDeferScaleConsumerApplication(layer) &&
-        Object.values(layer.encoding ?? {}).some(
-          encoding => encoding?.scale === scale.id
-        )
+        layerScaleIds(layer).includes(scale.id)
       );
       const canDeferMarks = deferredConsumers.length === 0 ||
         deferredConsumers.every(layer => deferredMarkIds.has(layer.id));
@@ -92,68 +60,13 @@ export function planCanvasRematerialization(program) {
   if (hasMaterializedLegend(program)) {
     guides.push({ op: "rematerializeLegend" });
   }
-  const layout = hasTitle(program) ? [{ op: "rematerializeTitle" }] : [];
+  const layout = planLayoutRematerialization(program);
   return buildMaterializationPlan({ scales, marks, guides, layout });
 }
 
-export function planScaleGuideRematerialization(program, id) {
-  const guides = [];
-  const objects = program.graphicSpec?.objects ?? {};
-  const guideConfigs = program.guideConfigs ?? {};
-  if (
-    objects.xAxisLine &&
-    program.semanticSpec.guides.axis?.x?.scale === id
-  ) {
-    guides.push({ op: "editXAxisLine" });
-  }
-  if (
-    objects.yAxisLine &&
-    program.semanticSpec.guides.axis?.y?.scale === id
-  ) {
-    guides.push({ op: "editYAxisLine" });
-  }
-  for (const channel of ["x", "y"]) {
-    for (const component of ["ticks", "labels", "title"]) {
-      if (guideConfigs.axis?.[channel]?.[component]?.scale === id) {
-        const suffix = component[0].toUpperCase() + component.slice(1);
-        guides.push({ op: `edit${channel.toUpperCase()}Axis${suffix}` });
-      }
-    }
-  }
-  for (const channel of ["theta", "radius"]) {
-    const prefix = channel === "theta" ? "Theta" : "Radial";
-    for (const component of ["line", "ticks", "labels", "title"]) {
-      if (guideConfigs.axis?.[channel]?.[component]?.scale === id) {
-        const suffix = component[0].toUpperCase() + component.slice(1);
-        guides.push({ op: `edit${prefix}Axis${suffix}` });
-      }
-    }
-  }
-  if (guideConfigs.grid?.horizontal?.scale === id) {
-    guides.push({ op: "rematerializeHorizontalGrid" });
-  }
-  if (guideConfigs.grid?.vertical?.scale === id) {
-    guides.push({ op: "rematerializeVerticalGrid" });
-  }
-  if (guideConfigs.grid?.theta?.scale === id) {
-    guides.push({ op: "rematerializeThetaGrid" });
-  }
-  if (guideConfigs.grid?.radial?.scale === id) {
-    guides.push({ op: "rematerializeRadialGrid" });
-  }
-  if (materializedLegendUsesScale(program, id)) {
-    guides.push({ op: "rematerializeLegend" });
-  }
-  return buildMaterializationPlan({ guides });
-}
-
 export function planLayerDataRematerialization(program, id) {
   const layer = requireLayer(program, id);
-  const scaleIds = [...new Set(
-    Object.values(layer.encoding ?? {})
-      .map(encoding => encoding?.scale)
-      .filter(scale => scale !== undefined)
-  )];
+  const scaleIds = [...new Set(layerScaleIds(layer))];
   const markStep = getMarkMaterializationStep(program, layer);
   const scales = scaleIds.map(scale => ({
       op: "rematerializeScale",
@@ -187,3 +100,4 @@ export function applyLayerDataRematerialization(program, id) {
 }
 
 export { applyMaterializationPlan } from "./planner.js";
+export { planScaleGuideRematerialization };

package/src/materialization/encodings.js

@@ -2,9 +2,9 @@ import { hasMaterializedLegend } from "./legends.js";
 import { requireLayer } from "../selectors/layers.js";
 import {
   getEncodingMaterializationStages
-} from "./marks.js";
+} from "./marks/index.js";
 import { buildMaterializationPlan } from "./planner.js";
-import { getSourceDependentMarkSteps } from "./marks.js";
+import { getSourceDependentMarkSteps } from "./marks/index.js";
 
 export function planEncodingRematerialization(program, {
   target,

package/src/materialization/facetGuides/index.js

@@ -0,0 +1,2 @@
+export { prepareSharedFacetLegend } from "./preparation.js";
+export { applyFacetGuideComposition } from "./placement.js";

package/src/materialization/facetGuides/legacyCategorical.js

@@ -0,0 +1,125 @@
+import {
+  resolveSharedFacetLegends
+} from "../../grammar/facets/guides.js";
+import { mapOrdinalValues } from "../../grammar/scales/index.js";
+import { DEFAULT_COLORS, DEFAULT_FONT_FAMILY } from "../../theme/defaults.js";
+
+function textItem(text, x, y, options = {}) {
+  return {
+    type: "text",
+    properties: {
+      x,
+      y,
+      text: String(text),
+      fill: options.color ?? DEFAULT_COLORS.strongText,
+      fontSize: options.fontSize ?? 12,
+      fontFamily: options.fontFamily ?? DEFAULT_FONT_FAMILY,
+      fontWeight: options.fontWeight ?? "normal",
+      textAlign: options.textAlign ?? "left",
+      textBaseline: options.textBaseline ?? "middle"
+    }
+  };
+}
+
+function collection(program, id, items) {
+  return program
+    .createGraphics({ id, type: "collection", parent: "canvas" })
+    .editGraphics({ target: id, property: "items", value: items });
+}
+
+export function resolveLegacyCategoricalLegend(program) {
+  const encodings = program.semanticSpec.layers.flatMap(layer =>
+    layer.encoding?.color === undefined
+      ? []
+      : [{ layer, encoding: layer.encoding.color }]
+  );
+  if (encodings.length === 0) return undefined;
+  const fields = new Set(encodings.map(entry => entry.encoding.field));
+  const scales = new Set(encodings.map(entry => entry.encoding.scale));
+  const marks = new Set(encodings.map(entry => entry.layer.mark?.type));
+  if (fields.size !== 1 || scales.size !== 1 || marks.size !== 1) {
+    throw new Error(
+      "Shared facet legend requires one compatible color field, scale, and mark recipe."
+    );
+  }
+  if (encodings.some(entry =>
+    !["nominal", "ordinal"].includes(entry.encoding.fieldType)
+  )) {
+    return undefined;
+  }
+  const firstId = program.compositionSpec.children[0];
+  const scaleId = encodings[0].encoding.scale;
+  const scale = program.children[firstId].resolvedScales[scaleId];
+  if (scale?.type !== "ordinal") return undefined;
+  const config = {
+    kind: "color",
+    target: encodings[0].layer.id,
+    field: encodings[0].encoding.field,
+    scale: scaleId,
+    title: encodings[0].encoding.field
+  };
+  const compatibility = resolveSharedFacetLegends(
+    program.compositionSpec.children.map(id => ({
+      id,
+      guideConfigs: { legend: { color: config } },
+      resolvedScales: program.children[id].resolvedScales
+    }))
+  );
+  return {
+    mode: "legacyCategorical",
+    compatibility,
+    reservation: { gap: 18, width: 132 },
+    legend: {
+      field: config.field,
+      mark: encodings[0].layer.mark.type,
+      domain: scale.domain,
+      colors: mapOrdinalValues(scale.domain, scale.domain, scale.range)
+    }
+  };
+}
+
+export function materializeLegacyCategoricalLegend(program, prepared, layout) {
+  const legend = prepared.legend;
+  const items = [textItem(legend.field, layout.legend.x, layout.legend.y, {
+    fontSize: 12,
+    fontWeight: 700,
+    textBaseline: "top"
+  })];
+  legend.domain.forEach((value, index) => {
+    const y = layout.legend.y + 29 + index * 26;
+    items.push(legend.mark === "point"
+      ? {
+          type: "circle",
+          properties: {
+            x: layout.legend.x + 7,
+            y,
+            radius: 5.5,
+            fill: legend.colors[index],
+            stroke: "#ffffff",
+            strokeWidth: 0.35,
+            opacity: 1
+          }
+        }
+      : {
+          type: "rect",
+          properties: {
+            x: layout.legend.x + 1,
+            y: y - 6,
+            width: 12,
+            height: 12,
+            fill: legend.colors[index],
+            stroke: "#ffffff",
+            strokeWidth: 0.6,
+            opacity: 1
+          }
+        });
+    items.push(textItem(value, layout.legend.x + 22, y, {
+      fontSize: 10.5
+    }));
+  });
+  return collection(
+    program,
+    `${program.compositionSpec.id}-legend`,
+    items
+  );
+}

package/src/materialization/facetGuides/placement.js

@@ -0,0 +1,126 @@
+import { isPlainObject } from "../../core/immutable.js";
+import { planFacetGuideOwnership } from "../../grammar/facets/guides.js";
+import {
+  axisGraphicIds,
+  allLegendGraphicIds
+} from "../guides/resources.js";
+import { attachSnapshotObject } from "../composition.js";
+import { namespaceGraphicId } from "../compositionSnapshot.js";
+import {
+  materializeLegacyCategoricalLegend
+} from "./legacyCategorical.js";
+import { legendKinds, prepareSharedFacetLegend } from "./preparation.js";
+
+function copyLegendConfig(program, source) {
+  let next = program;
+  for (const [kind, config] of Object.entries(source.guideConfigs.legend ?? {})) {
+    next = next._withLegendConfig(kind, config);
+  }
+  return next;
+}
+
+function removeNamespacedGraphics(program, namespace, ids) {
+  let next = program;
+  for (const id of ids) {
+    const target = namespaceGraphicId(namespace, id);
+    if (next.graphicSpec.objects[target] !== undefined) {
+      next = next.editGraphics({ target, remove: true });
+    }
+  }
+  return next;
+}
+
+function gradientAnchor(prepared, plot, layout) {
+  const strips = prepared.source.graphicSpec.objects.colorGradientStrips;
+  if (strips?.items?.[0] === undefined) return undefined;
+  const properties = strips.items[0].properties;
+  const length = prepared.source.guideConfigs.legend.gradient.gradient.length;
+  return {
+    sourceX: properties.x,
+    sourceY: properties.y,
+    targetX: layout.legend.x,
+    targetY: plot.y + (plot.height - length) / 2
+  };
+}
+
+function legendTranslation(prepared, plot, layout) {
+  const gradient = gradientAnchor(prepared, plot, layout);
+  if (gradient !== undefined) {
+    return {
+      x: gradient.targetX - gradient.sourceX,
+      y: gradient.targetY - gradient.sourceY
+    };
+  }
+  const height = prepared.bounds.bottom - prepared.bounds.top;
+  return {
+    x: layout.legend.x - prepared.bounds.left,
+    y: plot.y + Math.max(0, (plot.height - height) / 2) - prepared.bounds.top
+  };
+}
+
+function attachParentLegend(program, prepared, plot, layout) {
+  const translation = legendTranslation(prepared, plot, layout);
+  const canvas = prepared.source.graphicSpec.objects.canvas;
+  const id = `${program.compositionSpec.id}-shared-legend`;
+  let next = copyLegendConfig(program, prepared.source)
+    .createGraphics({ id, type: "canvas", parent: "canvas" });
+  for (const [property, value] of Object.entries({
+    x: translation.x,
+    y: translation.y,
+    width: canvas.properties.width,
+    height: canvas.properties.height,
+    background: "transparent"
+  })) {
+    next = next.editGraphics({ target: id, property, value });
+  }
+  for (const root of prepared.roots) {
+    next = attachSnapshotObject(next, prepared.source.graphicSpec, root, id);
+  }
+  return next;
+}
+
+export function applyFacetGuideComposition(program, { layout, plot } = {}) {
+  if (!isPlainObject(layout) || !Array.isArray(layout.children)) {
+    throw new TypeError("Facet guide composition requires a resolved layout.");
+  }
+  if (!isPlainObject(plot)) {
+    throw new TypeError("Facet guide composition requires resolved plot bounds.");
+  }
+  const prepared = prepareSharedFacetLegend(program);
+  const children = layout.children.map(cell => {
+    const child = program.children[cell.id];
+    return {
+      id: cell.id,
+      axes: Object.keys(child.guideConfigs.axis ?? {})
+        .filter(channel => ["x", "y"].includes(channel)),
+      legendKinds: legendKinds(child)
+    };
+  });
+  const ownership = planFacetGuideOwnership({
+    placements: layout.children,
+    children,
+    axes: program.compositionSpec.facet.guides.axes,
+    legend: program.compositionSpec.facet.guides.legend,
+    ...(prepared === undefined ? {} : { sharedLegends: prepared.compatibility })
+  });
+  let next = program;
+  for (const cell of layout.children) {
+    const namespace = `${program.compositionSpec.id}-${cell.id}`;
+    const childPlan = ownership.children[cell.id];
+    for (const channel of childPlan.removeAxes) {
+      next = removeNamespacedGraphics(next, namespace, axisGraphicIds(channel));
+    }
+    if (childPlan.removeLegends.length > 0) {
+      next = removeNamespacedGraphics(
+        next,
+        namespace,
+        allLegendGraphicIds(childPlan.removeLegends)
+      );
+    }
+  }
+  if (prepared === undefined) return next;
+  if (prepared.mode === "legacyCategorical") {
+    return materializeLegacyCategoricalLegend(next, prepared, layout);
+  }
+  return attachParentLegend(next, prepared, plot, layout);
+}

package/src/materialization/facetGuides/preparation.js

@@ -0,0 +1,188 @@
+import {
+  unionConcreteGraphicBounds
+} from "../../grammar/schemas/graphicBounds.js";
+import {
+  resolveSharedFacetLegends
+} from "../../grammar/facets/guides.js";
+import { findLayer } from "../../selectors/layers.js";
+import { findSemanticScale } from "../../selectors/scales.js";
+import { allLegendGraphicIds } from "../guides/resources.js";
+import { DEFAULT_COLORS } from "../../theme/defaults.js";
+import { resolveLegacyCategoricalLegend } from "./legacyCategorical.js";
+
+const LEGEND_SOURCE_CANVAS = Object.freeze({
+  width: 640,
+  height: 400,
+  margin: Object.freeze({ top: 40, right: 170, bottom: 60, left: 70 })
+});
+
+export function legendKinds(program) {
+  return Object.keys(program.guideConfigs.legend ?? {});
+}
+
+function legendCandidates(program) {
+  const layers = program.semanticSpec.layers;
+  const color = layers.filter(layer => {
+    const encoding = layer.encoding?.color;
+    return encoding?.scale !== undefined &&
+      findSemanticScale(program, encoding.scale) !== undefined;
+  });
+  if (color.length === 1) {
+    const layer = color[0];
+    return {
+      target: layer.id,
+      channels: ["color", "shape", "strokeDash"].filter(
+        channel => layer.encoding?.[channel]?.scale !== undefined
+      )
+    };
+  }
+  if (color.length > 1) {
+    throw new Error(
+      "Shared facet legend requires one unambiguous color legend target."
+    );
+  }
+  for (const channel of ["shape", "strokeDash", "size", "opacity"]) {
+    const candidates = layers.filter(
+      layer => layer.encoding?.[channel]?.scale !== undefined
+    );
+    if (candidates.length === 1) {
+      return { target: candidates[0].id, channels: [channel] };
+    }
+    if (candidates.length > 1) {
+      throw new Error(
+        `Shared facet legend requires one unambiguous ${channel} legend target.`
+      );
+    }
+  }
+  throw new Error("Shared facet legend requires one eligible encoded scale.");
+}
+
+function compactNumber(value) {
+  if (Math.abs(value) >= 1_000_000_000) {
+    return `${+(value / 1_000_000_000).toFixed(1)}B`;
+  }
+  if (Math.abs(value) >= 1_000_000) {
+    return `${Math.round(value / 1_000_000)}M`;
+  }
+  if (Math.abs(value) >= 1_000) {
+    return `${Math.round(value / 1_000)}K`;
+  }
+  return String(+value.toPrecision(3));
+}
+
+function continuousValues(domain, count) {
+  return Array.from(
+    { length: count },
+    (_, index) => domain[0] + index / (count - 1) * (domain[1] - domain[0])
+  );
+}
+
+function prepareAutoLegendSource(child) {
+  const request = legendCandidates(child);
+  const canvas = child.graphicSpec.objects.canvas;
+  let source = child
+    ._withCanvasConfig({
+      margin: LEGEND_SOURCE_CANVAS.margin,
+      size: { width: "explicit", height: "explicit" }
+    })
+    .editGraphics({
+      target: "canvas",
+      property: "width",
+      value: LEGEND_SOURCE_CANVAS.width
+    })
+    .editGraphics({
+      target: "canvas",
+      property: "height",
+      value: LEGEND_SOURCE_CANVAS.height
+    });
+  if (canvas?.properties.background !== undefined) {
+    source = source.editGraphics({
+      target: "canvas",
+      property: "background",
+      value: canvas.properties.background
+    });
+  }
+  const scale = findSemanticScale(
+    source,
+    findLayer(source, request.target)?.encoding?.color?.scale
+  );
+  const gradient = scale?.type === "sequential";
+  source = source.createLegend({
+    target: request.target,
+    channels: request.channels,
+    ...(gradient ? {
+      count: 5,
+      gradient: { length: 180, thickness: 12 },
+      labels: { offset: 9, fontSize: 10 },
+      titleStyle: { color: DEFAULT_COLORS.strongText, fontSize: 11 }
+    } : {})
+  });
+  if (gradient) {
+    const resolved = source.resolvedScales[scale.id];
+    source = source
+      .editGraphics({
+        target: "colorGradientLabels",
+        property: "text",
+        value: continuousValues(resolved.domain, 5).map(compactNumber)
+      })
+      .editGraphics({
+        target: "colorGradientTitle",
+        property: "y",
+        value: source.graphicSpec.objects.colorGradientTitle.properties.y + 8
+      });
+  }
+  return source;
+}
+
+function compatibleLegendChildren(program, source, inferred) {
+  return program.compositionSpec.children.map(id => {
+    const child = program.children[id];
+    return {
+      id,
+      guideConfigs: inferred ? source.guideConfigs : child.guideConfigs,
+      resolvedScales: child.resolvedScales
+    };
+  });
+}
+
+export function prepareSharedFacetLegend(program) {
+  if (program.compositionSpec.facet.guides.legend !== "shared") {
+    return undefined;
+  }
+  const firstId = program.compositionSpec.children[0];
+  const first = program.children[firstId];
+  const inferred = legendKinds(first).length === 0;
+  if (inferred) {
+    const legacy = resolveLegacyCategoricalLegend(program);
+    if (legacy !== undefined) return legacy;
+  }
+  const source = inferred ? prepareAutoLegendSource(first) : first;
+  const kinds = legendKinds(source);
+  const compatibility = resolveSharedFacetLegends(
+    compatibleLegendChildren(program, source, inferred)
+  );
+  const roots = allLegendGraphicIds(kinds).filter(
+    id => source.graphicSpec.objects[id] !== undefined
+  );
+  if (roots.length === 0) {
+    throw new Error("Shared facet legend has no concrete guide graphics.");
+  }
+  const bounds = unionConcreteGraphicBounds(source.graphicSpec, roots);
+  if (bounds === undefined) {
+    throw new Error("Shared facet legend has no measurable concrete bounds.");
+  }
+  const gradient = kinds.includes("gradient");
+  return {
+    mode: "promoted",
+    source,
+    inferred,
+    kinds,
+    roots,
+    bounds,
+    compatibility,
+    reservation: {
+      gap: gradient ? 24 : 18,
+      width: gradient ? 112 : Math.max(132, Math.ceil(bounds.right - bounds.left))
+    }
+  };
+}

package/src/materialization/facets.js

@@ -6,7 +6,7 @@ import {
 } from "../layout/title.js";
 import { resolveFacetLayout } from "../layout/facets.js";
 import { namespaceGraphicSnapshot } from "./compositionSnapshot.js";
-import { prepareSharedFacetLegend } from "./facetGuides.js";
+import { prepareSharedFacetLegend } from "./facetGuides/index.js";
 import {
   attachSnapshotObject,
   clearCompositionChildren,