ggaction 0.0.13 → 0.0.15

package/src/materialization/coordinateBounds.js

@@ -0,0 +1,204 @@
+import { isSourceOwnedText } from "../grammar/text.js";
+import { resolvePolarFrame } from "../grammar/polar.js";
+import { resolveEffectiveBounds } from "../layout/aspect.js";
+import { resolveGraphicBounds } from "../layout/canvas.js";
+import { findCoordinate, requireCoordinate } from "../selectors/coordinates.js";
+import { findSemanticScale } from "../selectors/scales.js";
+
+const DATA_CHANNELS = Object.freeze(["x", "y"]);
+const SECONDARY_CHANNELS = Object.freeze({ x2: "x", y2: "y" });
+
+function samePair(left, right) {
+  return left.x === right.x && left.y === right.y;
+}
+
+export function resolveDataAspectScalePair(program, target) {
+  const coordinate = typeof target === "string"
+    ? requireCoordinate(program, target)
+    : target;
+  if (coordinate.type !== "cartesian") {
+    throw new Error("Coordinate data aspect requires a Cartesian coordinate.");
+  }
+  const layers = program.semanticSpec.layers.filter(layer =>
+    layer.coordinate === coordinate.id &&
+    !isSourceOwnedText(layer) &&
+    DATA_CHANNELS.some(channel => layer.encoding?.[channel] !== undefined)
+  );
+  if (layers.length === 0) {
+    throw new Error(
+      `Coordinate "${coordinate.id}" data aspect requires active x and y consumers.`
+    );
+  }
+  const pairs = layers.map(layer => {
+    for (const channel of DATA_CHANNELS) {
+      const encoding = layer.encoding?.[channel];
+      if (
+        encoding?.scale === undefined ||
+        encoding.fieldType !== "quantitative"
+      ) {
+        throw new Error(
+          `Coordinate "${coordinate.id}" data aspect requires quantitative x and y scale consumers.`
+        );
+      }
+    }
+    for (const [secondary, primary] of Object.entries(SECONDARY_CHANNELS)) {
+      const encoding = layer.encoding?.[secondary];
+      if (encoding !== undefined && (
+        encoding.fieldType !== "quantitative" ||
+        encoding.scale !== layer.encoding[primary].scale
+      )) {
+        throw new Error(
+          `Coordinate "${coordinate.id}" data aspect requires ${secondary} to share its quantitative ${primary} scale.`
+        );
+      }
+    }
+    return { x: layer.encoding.x.scale, y: layer.encoding.y.scale };
+  });
+  if (pairs.some(pair => !samePair(pair, pairs[0]))) {
+    throw new Error(
+      `Coordinate "${coordinate.id}" data aspect requires one consistent x/y scale pair.`
+    );
+  }
+  const scales = {
+    x: findSemanticScale(program, pairs[0].x),
+    y: findSemanticScale(program, pairs[0].y)
+  };
+  for (const channel of DATA_CHANNELS) {
+    if (scales[channel]?.type !== "linear") {
+      throw new Error(
+        `Coordinate data aspect requires a linear ${channel} scale.`
+      );
+    }
+  }
+  return Object.freeze({
+    x: pairs[0].x,
+    y: pairs[0].y
+  });
+}
+
+export function findDataAspectCoordinatesForScale(program, scaleId) {
+  return program.semanticSpec.coordinates.filter(coordinate => {
+    if (coordinate.aspect?.mode !== "data") return false;
+    const pair = resolveDataAspectScalePair(program, coordinate);
+    return pair.x === scaleId || pair.y === scaleId;
+  });
+}
+
+function sameNumericPair(left, right) {
+  return Array.isArray(left) && left.length === 2 &&
+    left.every((value, index) => Number.isFinite(value) &&
+      Math.abs(value - right[index]) <= 1e-9);
+}
+
+function validateExplicitDataRanges(program, pair, bounds) {
+  const expected = {
+    x: [bounds.x, bounds.x + bounds.width],
+    y: [bounds.y + bounds.height, bounds.y]
+  };
+  for (const channel of DATA_CHANNELS) {
+    const scale = findSemanticScale(program, pair[channel]);
+    if (scale.range === "auto") continue;
+    const directed = scale.reverse === true
+      ? [...expected[channel]].reverse()
+      : expected[channel];
+    if (!sameNumericPair(scale.range, directed)) {
+      throw new Error(
+        `Coordinate data aspect conflicts with explicit ${channel} scale range "${scale.id}".`
+      );
+    }
+  }
+}
+
+export function resolveCoordinateBounds(program, target, {
+  resolvedScales = program.resolvedScales
+} = {}) {
+  const allocated = resolveGraphicBounds(program);
+  if (target === undefined) return allocated;
+  const coordinate = requireCoordinate(program, target);
+  const aspect = coordinate.aspect;
+  if (aspect === undefined || aspect === "auto") return allocated;
+  if (aspect.mode !== "data") {
+    return resolveEffectiveBounds(allocated, aspect);
+  }
+  const pair = resolveDataAspectScalePair(program, coordinate);
+  const x = resolvedScales[pair.x];
+  const y = resolvedScales[pair.y];
+  if (x?.type !== "linear" || y?.type !== "linear") {
+    throw new Error(
+      `Coordinate "${coordinate.id}" data aspect requires resolved linear x and y scales.`
+    );
+  }
+  const bounds = resolveEffectiveBounds(allocated, aspect, {
+    x: x.domain,
+    y: y.domain
+  });
+  validateExplicitDataRanges(program, pair, bounds);
+  return bounds;
+}
+
+export function resolveCoordinatePolarFrame(program, target, options) {
+  const coordinate = requireCoordinate(program, target);
+  if (coordinate.type !== "polar") {
+    throw new Error(`Coordinate "${coordinate.id}" is not Polar.`);
+  }
+  return resolvePolarFrame(
+    resolveCoordinateBounds(program, coordinate.id, options),
+    coordinate.polarFrame
+  );
+}
+
+function consumerCoordinateIds(consumers) {
+  return [...new Set(consumers.map(consumer => consumer.layer.coordinate))];
+}
+
+function sameBounds(left, right) {
+  return ["x", "y", "width", "height"].every(
+    property => Math.abs(left[property] - right[property]) <= 1e-9
+  );
+}
+
+export function resolveScaleConsumerBounds(program, consumers, options) {
+  const coordinateIds = consumerCoordinateIds(consumers);
+  if (coordinateIds.length === 0) return resolveGraphicBounds(program);
+  const allocated = resolveGraphicBounds(program);
+  const bounds = coordinateIds.map(id =>
+    id === undefined || findCoordinate(program, id) === undefined
+      ? allocated
+      : resolveCoordinateBounds(program, id, options)
+  );
+  if (bounds.slice(1).some(candidate => !sameBounds(candidate, bounds[0]))) {
+    throw new Error(
+      "A position scale cannot be shared across coordinates with different effective bounds."
+    );
+  }
+  return bounds[0];
+}
+
+export function resolveGuideCoordinateBounds(program, {
+  coordinate,
+  scale,
+  channel,
+  resolvedScales = program.resolvedScales
+}) {
+  let target = coordinate;
+  if (target === undefined && scale !== undefined) {
+    const candidates = new Set();
+    for (const layer of program.semanticSpec.layers) {
+      if (isSourceOwnedText(layer)) continue;
+      if (layer.encoding?.[channel]?.scale === scale) {
+        candidates.add(layer.coordinate);
+      }
+    }
+    if (candidates.has(undefined)) {
+      throw new Error("Guide scale consumers require stored coordinates.");
+    }
+    if (candidates.size > 1) {
+      throw new Error("Guide bounds found no unique compatible coordinate.");
+    }
+    target = candidates.values().next().value;
+  }
+  if (target !== undefined && findCoordinate(program, target) === undefined) {
+    throw new Error(`Unknown coordinate "${target}".`);
+  }
+  return resolveCoordinateBounds(program, target, { resolvedScales });
+}

package/src/materialization/dependencies.js

@@ -19,6 +19,7 @@ import {
   planScaleGuideRematerialization
 } from "./scaleGuideDependencies.js";
 import { planLayoutRematerialization } from "./layout.js";
+import { requireCoordinate } from "../selectors/coordinates.js";
 
 export function planCanvasRematerialization(program) {
   const marks = [];
@@ -61,6 +62,41 @@ export function planCanvasRematerialization(program) {
   return buildMaterializationPlan({ scales, marks, guides, layout });
 }
 
+export function planCoordinateRematerialization(program, target) {
+  requireCoordinate(program, target);
+  const layers = program.semanticSpec.layers.filter(
+    layer => layer.coordinate === target
+  );
+  const scaleIds = [...new Set(layers.flatMap(layer => [
+    ...["x", "y", "x2", "y2", "theta", "radius"].map(
+      channel => layer.encoding?.[channel]?.scale
+    ),
+    ...(layer.encoding?.parallel?.dimensions ?? []).map(
+      dimension => dimension.scale
+    )
+  ]).filter(id => id !== undefined))];
+  const directMarks = layers
+    .map(layer => getMarkMaterializationStep(program, layer))
+    .filter(step => step !== undefined);
+  const marks = [
+    ...directMarks,
+    ...directMarks.flatMap(step =>
+      getSourceDependentMarkSteps(program, step.args.id)
+    )
+  ];
+  return buildMaterializationPlan({
+    scales: scaleIds.map(id => ({
+      op: "rematerializeScale",
+      args: { id, guides: false, marks: false }
+    })),
+    marks: reusePlannedMarkScales(program, marks, scaleIds),
+    guides: scaleIds.flatMap(id =>
+      planScaleGuideRematerialization(program, id)
+    ),
+    layout: planLayoutRematerialization(program)
+  });
+}
+
 export function planLayerDataRematerialization(program, id) {
   const layer = requireLayer(program, id);
   const scaleIds = [...new Set(getLayerScaleIds(layer))];

package/src/materialization/facetGuides/legacyCategorical.js

@@ -29,6 +29,9 @@ function collection(program, id, items) {
 }
 
 export function resolveLegacyCategoricalLegend(program) {
+  if (program.semanticSpec.layers.some(layer =>
+    layer.encoding?.stroke?.scale !== undefined
+  )) return undefined;
   const encodings = program.semanticSpec.layers.flatMap(layer =>
     layer.encoding?.color === undefined
       ? []

package/src/materialization/facetGuides/placement.js

@@ -46,10 +46,16 @@ function legendTranslation(prepared, plot, layout) {
       y: layout.legend.y - prepared.bounds.top
     };
   }
-  const strips = prepared.source.graphicSpec.objects.colorGradientStrips;
+  const gradientKind = prepared.kinds?.find(kind =>
+    ["gradient", "strokeGradient"].includes(kind)
+  );
+  const prefix = gradientKind === "strokeGradient"
+    ? "strokeGradient"
+    : "colorGradient";
+  const strips = prepared.source.graphicSpec.objects[`${prefix}Strips`];
   if (strips?.items?.[0] !== undefined) {
     const properties = strips.items[0].properties;
-    const length = prepared.source.guideConfigs.legend.gradient.gradient.length;
+    const length = prepared.source.guideConfigs.legend[gradientKind].gradient.length;
     return {
       x: layout.legend.x - (position === "left"
         ? prepared.bounds.left

package/src/materialization/facetGuides/preparation.js

@@ -35,7 +35,7 @@ function legendCandidates(program) {
     const layer = color[0];
     return {
       target: layer.id,
-      channels: ["color", "shape", "strokeDash"].filter(
+      channels: ["color", "stroke", "shape", "strokeDash"].filter(
         channel => layer.encoding?.[channel]?.scale !== undefined
       )
     };
@@ -45,7 +45,7 @@ function legendCandidates(program) {
       "Shared facet legend requires one unambiguous color legend target."
     );
   }
-  for (const channel of ["shape", "strokeDash", "size", "opacity"]) {
+  for (const channel of ["stroke", "shape", "strokeDash", "size", "opacity"]) {
     const candidates = layers.filter(
       layer => layer.encoding?.[channel]?.scale !== undefined
     );
@@ -105,9 +105,14 @@ function prepareAutoLegendSource(child) {
   }
   const scale = findSemanticScale(
     source,
-    findLayer(source, request.target)?.encoding?.color?.scale
+    findLayer(source, request.target)?.encoding?.[
+      request.channels.includes("color") ? "color" : "stroke"
+    ]?.scale
   );
   const gradient = scale?.type === "sequential";
+  const gradientPrefix = request.channels.includes("color")
+    ? "colorGradient"
+    : "strokeGradient";
   source = source.createLegend({
     target: request.target,
     channels: request.channels,
@@ -122,7 +127,7 @@ function prepareAutoLegendSource(child) {
     const resolved = source.resolvedScales[scale.id];
     source = source
       .editGraphics({
-        target: "colorGradientLabels",
+        target: `${gradientPrefix}Labels`,
         property: "text",
         value: formatDistinctNumericSamples(
           continuousValues(resolved.domain, 5),
@@ -130,9 +135,9 @@ function prepareAutoLegendSource(child) {
         )
       })
       .editGraphics({
-        target: "colorGradientTitle",
+        target: `${gradientPrefix}Title`,
         property: "y",
-        value: source.graphicSpec.objects.colorGradientTitle.properties.y + 8
+        value: source.graphicSpec.objects[`${gradientPrefix}Title`].properties.y + 8
       });
   }
   return source;
@@ -196,7 +201,7 @@ export function prepareSharedFacetLegend(program) {
   if (bounds === undefined) {
     throw new Error("Shared facet legend has no measurable concrete bounds.");
   }
-  const gradient = kinds.includes("gradient");
+  const gradient = kinds.some(kind => ["gradient", "strokeGradient"].includes(kind));
   const placement = promotedLegendPlacement(source, kinds);
   const width = Math.ceil(bounds.right - bounds.left);
   return {

package/src/materialization/facetHeaders.js

@@ -0,0 +1,346 @@
+import { isPlainObject } from "../core/immutable.js";
+import {
+  formatVisibleText,
+  measureTextWidth,
+  resolveTextBounds,
+  textBoundsIntersect
+} from "../core/textMetrics.js";
+import { resolveDisplayLabel } from "../grammar/displayLabels.js";
+import { DEFAULT_COLORS, DEFAULT_FONT_FAMILY } from "../theme/defaults.js";
+
+const SIDES = Object.freeze(["top", "right", "bottom", "left"]);
+const ZERO_SIDES = Object.freeze({ top: 0, right: 0, bottom: 0, left: 0 });
+
+export function createDefaultFacetHeaders() {
+  return {
+    mode: "legacy",
+    common: {
+      fontSize: 12,
+      fontFamily: DEFAULT_FONT_FAMILY,
+      fontWeight: 600,
+      color: DEFAULT_COLORS.strongText,
+      offset: 10,
+      align: "center"
+    },
+    row: { side: "left" },
+    column: { side: "top" }
+  };
+}
+
+export function normalizeFacetHeadersConfig(value) {
+  if (!isPlainObject(value)) {
+    throw new TypeError("Facet headers config must be a plain object.");
+  }
+  if (value.common === undefined && value.mode === undefined) {
+    return {
+      ...createDefaultFacetHeaders(),
+      common: {
+        ...createDefaultFacetHeaders().common,
+        ...value
+      }
+    };
+  }
+  if (!["legacy", "roles"].includes(value.mode) ||
+      !isPlainObject(value.common) || !isPlainObject(value.row) ||
+      !isPlainObject(value.column)) {
+    throw new Error("Facet headers config must contain canonical mode and role objects.");
+  }
+  return {
+    mode: value.mode,
+    common: { ...value.common },
+    row: { ...value.row },
+    column: { ...value.column }
+  };
+}
+
+export function resolveFacetHeaderConfig(headers, role) {
+  const normalized = normalizeFacetHeadersConfig(headers);
+  return role === "all"
+    ? { ...normalized.common }
+    : { ...normalized.common, ...normalized[role] };
+}
+
+function mappedText(value, config) {
+  return resolveDisplayLabel(value, config.labelMap, formatVisibleText);
+}
+
+function gridCellById(spec) {
+  return new Map((spec.facet.grid?.cells ?? []).map(cell => [cell.id, cell]));
+}
+
+function legacyDescriptors(program, headers) {
+  const spec = program.compositionSpec;
+  const config = resolveFacetHeaderConfig(headers, "all");
+  const cells = gridCellById(spec);
+  return spec.children.map((id, index) => {
+    const cell = cells.get(id);
+    const text = cell === undefined
+      ? mappedText(spec.facet.values[index], config)
+      : `${mappedText(cell.rowValue, config)} · ${mappedText(cell.columnValue, config)}`;
+    return { topology: "legacy", role: "column", id, text, config };
+  });
+}
+
+function uniqueGridGroups(spec, role) {
+  const coordinate = role === "column" ? "column" : "row";
+  const valueKey = role === "column" ? "columnValue" : "rowValue";
+  const groups = new Map();
+  for (const cell of spec.facet.grid.cells) {
+    const existing = groups.get(cell[coordinate]);
+    if (existing === undefined) {
+      groups.set(cell[coordinate], {
+        coordinate: cell[coordinate],
+        value: cell[valueKey],
+        ids: [cell.id]
+      });
+    } else {
+      if (existing.value !== cell[valueKey]) {
+        throw new Error(`Facet ${role} header values conflict at coordinate ${cell[coordinate]}.`);
+      }
+      existing.ids.push(cell.id);
+    }
+  }
+  return [...groups.values()].sort((left, right) =>
+    left.coordinate - right.coordinate
+  );
+}
+
+function roleDescriptors(program, headers) {
+  const spec = program.compositionSpec;
+  const column = resolveFacetHeaderConfig(headers, "column");
+  if (spec.facet.grid === undefined) {
+    return spec.children.map((id, index) => ({
+      topology: "cell-column",
+      role: "column",
+      id,
+      ids: [id],
+      row: Math.floor(index / spec.columns),
+      text: mappedText(spec.facet.values[index], column),
+      config: column
+    }));
+  }
+  const row = resolveFacetHeaderConfig(headers, "row");
+  const columns = uniqueGridGroups(spec, "column").map(group => ({
+    topology: "grid-column",
+    role: "column",
+    ids: group.ids,
+    coordinate: group.coordinate,
+    text: mappedText(group.value, column),
+    config: column
+  }));
+  const rows = uniqueGridGroups(spec, "row").map(group => ({
+    topology: "grid-row",
+    role: "row",
+    ids: group.ids,
+    coordinate: group.coordinate,
+    text: mappedText(group.value, row),
+    config: row
+  }));
+  return [...columns, ...rows];
+}
+
+function laneThickness(descriptors, role) {
+  const visible = descriptors.filter(item => item.role === role && item.text !== "");
+  if (visible.length === 0) return 0;
+  if (role === "column") {
+    return Math.max(...visible.map(item => item.config.fontSize + item.config.offset));
+  }
+  return Math.max(...visible.map(item => measureTextWidth(item.text, item.config) +
+    item.config.offset));
+}
+
+export function prepareFacetHeaders(program, headersConfig) {
+  const headers = normalizeFacetHeadersConfig(headersConfig);
+  const descriptors = headers.mode === "legacy"
+    ? legacyDescriptors(program, headers)
+    : roleDescriptors(program, headers);
+  const rows = program.compositionSpec.facet.grid === undefined
+    ? Math.ceil(program.compositionSpec.children.length / program.compositionSpec.columns)
+    : Math.max(...program.compositionSpec.facet.grid.cells.map(cell => cell.row)) + 1;
+  const headerLayout = {
+    outer: { ...ZERO_SIDES },
+    cellRows: { top: Array(rows).fill(0), bottom: Array(rows).fill(0) }
+  };
+  if (headers.mode === "roles") {
+    const column = resolveFacetHeaderConfig(headers, "column");
+    const columnThickness = laneThickness(descriptors, "column");
+    if (program.compositionSpec.facet.grid === undefined) {
+      for (const descriptor of descriptors) {
+        if (descriptor.text !== "") {
+          headerLayout.cellRows[column.side][descriptor.row] = Math.max(
+            headerLayout.cellRows[column.side][descriptor.row],
+            descriptor.config.fontSize + descriptor.config.offset
+          );
+        }
+      }
+    } else {
+      headerLayout.outer[column.side] = columnThickness;
+      const row = resolveFacetHeaderConfig(headers, "row");
+      headerLayout.outer[row.side] = laneThickness(descriptors, "row");
+    }
+  }
+  return { headers, descriptors, headerLayout };
+}
+
+function horizontalAnchor(bounds, align) {
+  if (align === "start") return { x: bounds.left, textAlign: "left" };
+  if (align === "end") return { x: bounds.right, textAlign: "right" };
+  return { x: (bounds.left + bounds.right) / 2, textAlign: "center" };
+}
+
+function verticalAnchor(bounds, align) {
+  if (align === "start") return { y: bounds.top, textBaseline: "top" };
+  if (align === "end") return { y: bounds.bottom, textBaseline: "bottom" };
+  return { y: (bounds.top + bounds.bottom) / 2, textBaseline: "middle" };
+}
+
+function union(items) {
+  return {
+    left: Math.min(...items.map(item => item.left)),
+    right: Math.max(...items.map(item => item.right)),
+    top: Math.min(...items.map(item => item.top)),
+    bottom: Math.max(...items.map(item => item.bottom))
+  };
+}
+
+function placedPlot(cell, plot) {
+  return {
+    left: cell.x + plot.x,
+    right: cell.x + plot.x + plot.width,
+    top: cell.y + plot.y,
+    bottom: cell.y + plot.y + plot.height
+  };
+}
+
+function placedCell(cell) {
+  return {
+    left: cell.x,
+    right: cell.x + cell.width,
+    top: cell.y,
+    bottom: cell.y + cell.height
+  };
+}
+
+function roleItem(descriptor, cells, plots) {
+  const selectedCells = descriptor.ids.map(id => cells.get(id));
+  const missingCell = descriptor.ids.find((id, index) =>
+    selectedCells[index] === undefined
+  );
+  const missingPlot = descriptor.ids.find(id => plots.get(id) === undefined);
+  if (missingCell !== undefined || missingPlot !== undefined) {
+    throw new Error(
+      `Facet header requires cell and plot bounds for "${missingCell ?? missingPlot}".`
+    );
+  }
+  const selectedPlots = descriptor.ids.map((id, index) =>
+    placedPlot(selectedCells[index], plots.get(id))
+  );
+  const plot = union(selectedPlots);
+  const snapshots = union(selectedCells.map(placedCell));
+  const config = descriptor.config;
+  let anchor;
+  if (descriptor.role === "column") {
+    anchor = horizontalAnchor(plot, config.align);
+    const top = config.side === "top";
+    anchor.y = top
+      ? snapshots.top - config.offset - config.fontSize / 2
+      : snapshots.bottom + config.offset + config.fontSize / 2;
+    anchor.textBaseline = "middle";
+  } else {
+    anchor = verticalAnchor(plot, config.align);
+    const left = config.side === "left";
+    anchor.x = left
+      ? snapshots.left - config.offset
+      : snapshots.right + config.offset;
+    anchor.textAlign = left ? "right" : "left";
+  }
+  return { descriptor, snapshots, properties: anchor };
+}
+
+function legacyItem(descriptor, cell, plot) {
+  if (cell === undefined || plot === undefined) {
+    throw new Error(`Facet header requires cell and plot bounds for "${descriptor.id}".`);
+  }
+  return {
+    descriptor,
+    snapshots: placedCell(cell),
+    properties: {
+      ...horizontalAnchor(placedPlot(cell, plot), descriptor.config.align),
+      y: cell.y + descriptor.config.offset,
+      textBaseline: "middle"
+    }
+  };
+}
+
+function styledItem(item) {
+  const { config } = item.descriptor;
+  return {
+    type: "text",
+    properties: {
+      ...item.properties,
+      text: item.descriptor.text,
+      fill: config.color,
+      fontSize: config.fontSize,
+      fontFamily: config.fontFamily,
+      fontWeight: config.fontWeight
+    }
+  };
+}
+
+function assertRoleHeadersFit(records, items, layout) {
+  const bounds = items.map((item, index) => records[index].descriptor.text === ""
+    ? undefined
+    : resolveTextBounds(item.properties));
+  for (const [index, current] of bounds.entries()) {
+    if (current === undefined) continue;
+    if (current.left < -1e-9 || current.right > layout.width + 1e-9 ||
+        current.top < -1e-9 || current.bottom > layout.height + 1e-9 ||
+        bounds.some((other, otherIndex) => otherIndex < index &&
+          other !== undefined && textBoundsIntersect(other, current)) ||
+        layout.children.some(cell => textBoundsIntersect(current, placedCell(cell)))) {
+      throw new Error(
+        "Facet role headers require sufficient non-overlapping reserved space."
+      );
+    }
+  }
+}
+
+function assertLegacyHeadersFit(items, layout, plotById) {
+  const previous = [];
+  for (let index = 0; index < items.length; index += 1) {
+    if (items[index].properties.text === "") continue;
+    const bounds = resolveTextBounds(items[index].properties);
+    const cell = layout.children[index];
+    const plot = plotById.get(cell.id);
+    if (bounds.left < 0 || bounds.right > layout.width ||
+      bounds.top < 0 || bounds.bottom > layout.height ||
+      previous.some(item => textBoundsIntersect(item, bounds)) ||
+      textBoundsIntersect(bounds, placedPlot(cell, plot))) {
+      throw new Error(
+        "Facet headers require sufficient non-overlapping space above every child plot."
+      );
+    }
+    previous.push(bounds);
+  }
+}
+
+export function materializeFacetHeaders(program, layout, plots, prepared) {
+  const cells = new Map(layout.children.map(cell => [cell.id, cell]));
+  const plotById = new Map(plots.map(plot => [plot.id, plot]));
+  const records = prepared.descriptors.map(descriptor => {
+    if (descriptor.topology === "legacy") {
+      return legacyItem(descriptor, cells.get(descriptor.id), plotById.get(descriptor.id));
+    }
+    return roleItem(descriptor, cells, plotById);
+  });
+  const items = records.map(styledItem);
+  if (prepared.headers.mode === "legacy") {
+    assertLegacyHeadersFit(items, layout, plotById);
+  } else {
+    assertRoleHeadersFit(records, items, layout);
+  }
+  const id = `${program.compositionSpec.id}-headers`;
+  return program
+    .createGraphics({ id, type: "collection", parent: "canvas" })
+    .editGraphics({ target: id, property: "items", value: items });
+}