ggaction 0.0.12 → 0.0.13

package/src/materialization/bars/aggregate.js

@@ -1,161 +1,47 @@
-import { deriveBarAggregates } from "../../grammar/bars/aggregate.js";
-import {
-  BAR_ORIENTATIONS,
-  resolveBarChannels,
-  resolveBarColorLayout
-} from "../../grammar/bars/policy.js";
-import {
-  DEFAULT_SERIES_BASELINE,
-  layoutSeriesPartition
-} from "../../grammar/seriesLayout.js";
-import {
-  isDiscretePositionScaleType,
-  mapContinuousScaleValues,
-  mapOrdinalPositionValues
-} from "../../grammar/scales/index.js";
+import { deriveSeriesBarCells } from "../../grammar/bars/aggregate.js";
+import { resolveBarChannels, resolveBarColorLayout, resolveBarOffsetChannel } from "../../grammar/bars/policy.js";
+import { mapContinuousScaleValues, mapOrdinalPositionValues } from "../../grammar/scales/index.js";
 import { mapScaleConsumerValues } from "../scales/map.js";
-import {
-  DEFAULT_BAR_FILL,
-  resolveBarAppearance
-} from "./resolve.js";
-import { deriveGroupedRectangles } from "./grouped.js";
+import { DEFAULT_BAR_FILL, resolveBarAppearance } from "./resolve.js";
 import { resolveBarWidth } from "../../grammar/bars/geometry.js";
+import { finiteMidpoint } from "../../grammar/numeric.js";
 
 export function deriveAggregateRectangles(required, resolved, widthConfig) {
   const { dataset, layer } = required;
-  const layout = resolveBarColorLayout(layer);
-  if (layout === "group") {
-    return deriveGroupedRectangles(required, resolved, widthConfig);
-  }
-
-  const xScale = resolved.resolvedScales[required.xEncoding.scale];
-  const yScale = resolved.resolvedScales[required.yEncoding.scale];
-  const channels = resolveBarChannels(layer);
-  const vertical = channels.orientation === BAR_ORIENTATIONS.vertical;
-  const categoryScale = vertical ? xScale : yScale;
-  const measureScale = vertical ? yScale : xScale;
-  const colorEncoding = layer.encoding?.color;
-  const colorScale = resolved.resolvedScales[colorEncoding?.scale];
-  if (colorEncoding !== undefined && colorScale === undefined) {
-    throw new Error(
-      `Bar mark "${layer.id}" requires a resolved color scale.`
-    );
-  }
-
-  const seriesDomain = colorScale?.domain ?? [undefined];
-  const seriesIndex = new Map(
-    seriesDomain.map((value, index) => [value, index])
-  );
-  const colors = new Map(seriesDomain.map((value, index) => [
-    value,
-    colorScale?.range[index % colorScale.range.length] ?? DEFAULT_BAR_FILL
-  ]));
-  const cells = deriveBarAggregates(dataset.values, layer).values;
-  const discreteCategory = categoryScale.type === "ordinal" ||
-    isDiscretePositionScaleType(categoryScale.type);
-  const categoryDomain = discreteCategory
-    ? categoryScale.domain
-    : [...new Set(cells.map(cell => cell[channels.category]))]
-        .sort((left, right) => left - right);
-  const categoryIndex = new Map(
-    categoryDomain.map((value, index) => [value, index])
-  );
-  const cellMap = new Map(cells.map(cell => [
-    JSON.stringify([cell[channels.category], cell.color]),
-    cell
-  ]));
-  const thickness = resolveBarWidth(
-    widthConfig,
-    Math.abs(categoryScale.bandwidth ?? categoryScale.step)
-  );
-  const baseline = DEFAULT_SERIES_BASELINE;
-  const continuousColor = colorEncoding?.fieldType === "quantitative";
-  if (continuousColor) {
-    const mappedColors = mapScaleConsumerValues(
-      cells.map(cell => cell.color), colorScale, "color"
-    );
-    const cellByCategory = new Map(
-      cells.map((cell, index) => [cell[channels.category], { cell, index }])
-    );
-    const existing = resolved.graphicSpec.objects[layer.id].items;
-    const config = resolved.markConfigs[layer.id] ?? {};
-    const appearance = config.barAppearance ?? {};
-    return categoryDomain.flatMap(categoryValue => {
-      const entry = cellByCategory.get(categoryValue);
-      if (entry === undefined) return [];
-      const { cell, index } = entry;
-      const categoryCenter = discreteCategory
-        ? mapOrdinalPositionValues([categoryValue], categoryScale)[0]
-        : mapContinuousScaleValues(
-            [categoryValue],
-            categoryScale
-          )[0];
-      const [segment] = layoutSeriesPartition(
-        [cell[channels.measure]],
-        layout,
-        { baseline }
-      );
-      if (segment === undefined) return [];
-      const [start, end] = mapContinuousScaleValues(
-        [segment.start, segment.end],
-        measureScale
-      );
-      return [{
-        x: vertical ? categoryCenter - thickness / 2 : Math.min(start, end),
-        y: vertical ? Math.min(start, end) : categoryCenter - thickness / 2,
-        width: vertical ? thickness : Math.abs(start - end),
-        height: vertical ? Math.abs(start - end) : thickness,
-        fill: mappedColors[index],
-        ...resolveBarAppearance(config, existing[index]?.properties)
-      }];
-    });
-  }
-  const segments = [];
-
-  for (const category of categoryDomain) {
-    const partition = seriesDomain.map(color =>
-      cellMap.get(JSON.stringify([category, color]))?.[channels.measure] ?? 0
-    );
-    for (const segment of layoutSeriesPartition(partition, layout, { baseline })) {
-      const color = seriesDomain[segment.index];
-      const cell = cellMap.get(JSON.stringify([category, color]));
-      if (cell === undefined) continue;
-      segments.push({ category, color, ...segment });
-    }
-  }
-
-  const existing = resolved.graphicSpec.objects[layer.id].items;
+  const channels = resolveBarChannels(layer), vertical = channels.orientation === "vertical";
+  const categoryScale = resolved.resolvedScales[layer.encoding[channels.category].scale];
+  const measureScale = resolved.resolvedScales[layer.encoding[channels.measure].scale];
+  const color = layer.encoding.color, colorScale = resolved.resolvedScales[color?.scale];
+  const grouped = resolveBarColorLayout(layer) === "group";
+  const offsetScale = resolved.resolvedScales[layer.encoding[resolveBarOffsetChannel(layer)]?.scale];
+  if (grouped && offsetScale === undefined) throw new Error("Grouped bar requires a resolved offset scale.");
+  const temporal = categoryScale.type === "time";
+  const segments = deriveSeriesBarCells(dataset.values, layer, temporal ? undefined : categoryScale.domain,
+    grouped ? offsetScale.domain : layer.encoding.group === undefined && color?.fieldType !== "quantitative" ? colorScale?.domain : undefined);
+  const fills = color === undefined ? undefined : mapScaleConsumerValues(segments.map(segment => segment.cell.color), colorScale, "color");
   const config = resolved.markConfigs[layer.id] ?? {};
-  const appearance = config.barAppearance ?? {};
-  return segments.map((segment, index) => {
-    const category = categoryIndex.get(segment.category);
-    const color = seriesIndex.get(segment.color);
-    if (category === undefined || color === undefined) {
-      throw new Error("Bar value is outside a resolved ordinal domain.");
+  const existing = resolved.graphicSpec.objects[layer.id].items;
+  const width = resolveBarWidth(widthConfig, grouped ? offsetScale.bandwidth : Math.abs(categoryScale.bandwidth ?? categoryScale.step));
+  const indices = new Map(categoryScale.domain.map((value, index) => [value, index]));
+  return segments.map(({ cell, start, end, seriesIndex }, index) => {
+    const categoryValue = cell[channels.category];
+    const categoryCenter = (temporal ? mapContinuousScaleValues : mapOrdinalPositionValues)([categoryValue], categoryScale)[0];
+    let position = !grouped && layer.encoding.group !== undefined && layer.encoding.group.inferredFrom === undefined && !temporal && categoryScale.step > 0
+      ? (categoryScale.start ?? categoryScale.range[0]) + indices.get(categoryValue) * categoryScale.step + categoryScale.bandwidth / 2 - width / 2
+      : categoryCenter - width / 2;
+    if (grouped) {
+      const direction = Math.sign(categoryScale.step ?? categoryScale.range[1] - categoryScale.range[0]) || 1;
+      const offsetCenter = offsetScale.start + seriesIndex * offsetScale.step + (Math.sign(offsetScale.step) || 1) * offsetScale.bandwidth / 2;
+      if (vertical && direction > 0 && offsetScale.step > 0) {
+        const categoryStart = temporal ? categoryCenter - categoryScale.bandwidth / 2
+          : (categoryScale.start ?? categoryScale.range[0]) + indices.get(categoryValue) * categoryScale.step;
+        position = categoryStart + offsetScale.start + seriesIndex * offsetScale.step + (offsetScale.bandwidth - width) / 2;
+      } else position = categoryCenter + direction * (offsetCenter - finiteMidpoint(...offsetScale.range)) - width / 2;
     }
-    const categoryCenter = discreteCategory
-      ? mapOrdinalPositionValues([segment.category], categoryScale)[0]
-      : mapContinuousScaleValues(
-          [segment.category],
-          categoryScale
-        )[0];
-    const [start, end] = mapContinuousScaleValues(
-      [segment.start, segment.end],
-      measureScale
-    );
-    return {
-      x: vertical
-        ? categoryCenter - thickness / 2
-        : Math.min(start, end),
-      y: vertical
-        ? Math.min(start, end)
-        : categoryCenter - thickness / 2,
-      width: vertical ? thickness : Math.abs(start - end),
-      height: vertical ? Math.abs(start - end) : thickness,
-      fill: segment.color === undefined
-        ? appearance.fill ?? config.fill ?? colors.get(segment.color)
-        : colors.get(segment.color),
-      ...resolveBarAppearance(config, existing[index]?.properties)
-    };
+    const [a, b] = mapContinuousScaleValues([start, end], measureScale);
+    return { x: vertical ? position : Math.min(a, b), y: vertical ? Math.min(a, b) : position,
+      width: vertical ? width : Math.abs(a - b), height: vertical ? Math.abs(a - b) : width,
+      fill: fills?.[index] ?? config.barAppearance?.fill ?? config.fill ?? DEFAULT_BAR_FILL,
+      ...resolveBarAppearance(config, existing[index]?.properties) };
   });
 }

package/src/materialization/bars/histogram.js

@@ -1,3 +1,4 @@
+import { readSeriesIdentity } from "../../grammar/pathSeries.js";
 import {
   countHistogramBins,
   findHistogramBinIndex,
@@ -34,6 +35,29 @@ export function deriveHistogramSegments({
   const colorEncoding = layer.encoding?.color;
   const layout = resolveBarColorLayout(layer);
 
+  if (layer.encoding?.group !== undefined) {
+    const identity = readSeriesIdentity(dataset.values, layer);
+    const cellRows = bins.boundaries.slice(0, -1).map(() => identity.domain.map(() => []));
+    const index = new Map(identity.domain.map((value, i) => [value, i]));
+    xValues.forEach((value, i) => { const bin = findHistogramBinIndex(value, bins.boundaries);
+      if (bin !== -1) cellRows[bin][index.get(identity.values[i])].push(dataset.values[i]); });
+    return cellRows.flatMap((cells, bin) => layoutSeriesPartition(cells.map(rows => rows.length), layout).map(segment => {
+      const members = cells[segment.index];
+      let color, colorValue;
+      if (colorEncoding !== undefined) {
+        const values = readNominalField(members, colorEncoding.field);
+        if (new Set(values).size !== 1) throw new Error("Histogram color requires one value within each bin/series cell.");
+        colorValue = values[0];
+        const scale = resolvedScales[colorEncoding.scale];
+        color = mapOrdinalValues([colorValue], scale.domain, scale.range)[0];
+      }
+      return { bin, start: bins.boundaries[bin], end: bins.boundaries[bin + 1],
+        category: segment.index, categoryCount: identity.domain.length,
+        stackStart: segment.start, stackEnd: segment.end, members,
+        ...(color === undefined ? {} : { color, colorValue }) };
+    }));
+  }
+
   if (colorEncoding?.scale === undefined) {
     return countHistogramBins(xValues, bins.boundaries).flatMap((count, bin) =>
       layoutSeriesPartition([count], layout).map(segment => ({

package/src/materialization/categorySlotOffset.js

@@ -0,0 +1,40 @@
+export function resolveCategorySlotOffset(program, layer) {
+  const policy = program.markConfigs[layer.id]?.categorySlotOffset;
+  if (policy === undefined) return undefined;
+  if (!["x", "y"].includes(policy.channel)) {
+    throw new Error(`Category slot offset for "${layer.id}" requires channel x or y.`);
+  }
+  if (!Number.isFinite(policy.band) || policy.band < -0.5 || policy.band > 0.5) {
+    throw new RangeError(`Category slot offset for "${layer.id}" must be within [-0.5, 0.5] band.`);
+  }
+  const encoding = layer.encoding?.[policy.channel];
+  if (!["nominal", "ordinal"].includes(encoding?.fieldType)) {
+    throw new Error(`Category slot offset for "${layer.id}" requires a categorical position.`);
+  }
+  const scale = program.resolvedScales[encoding.scale];
+  if (scale?.type !== "band" || !Number.isFinite(scale.bandwidth) || scale.bandwidth <= 0) {
+    throw new Error(`Category slot offset for "${layer.id}" requires a positive band scale.`);
+  }
+  return { channel: policy.channel, pixels: scale.bandwidth * policy.band };
+}
+
+export function offsetCategoryPositions(program, layer, positions) {
+  const offset = resolveCategorySlotOffset(program, layer);
+  if (offset === undefined || offset.pixels === 0) return positions;
+  const shift = values => values === undefined
+    ? undefined
+    : values.map(value => Number.isFinite(value) ? value + offset.pixels : value);
+  return {
+    ...positions,
+    [offset.channel]: shift(positions[offset.channel])
+  };
+}
+
+export function offsetCategoryRectangles(program, layer, rectangles) {
+  const offset = resolveCategorySlotOffset(program, layer);
+  if (offset === undefined || offset.pixels === 0) return rectangles;
+  return rectangles.map(rectangle => ({
+    ...rectangle,
+    [offset.channel]: rectangle[offset.channel] + offset.pixels
+  }));
+}

package/src/materialization/compositionSnapshot.js

@@ -32,7 +32,7 @@ export function namespaceGraphicId(namespace, id) {
   const encode = value => Array.from(value, character =>
     character.codePointAt(0).toString(16).padStart(6, "0")
   ).join("");
-  return `g${encode(namespace)}_${encode(id)}`;
+  return `g${encode(namespace)}_${id}`;
 }
 
 function rewriteItem(item, namespace) {

package/src/materialization/dependencies.js

@@ -1,12 +1,16 @@
+import { withGuideLayoutTransaction } from "./guides/layout.js";
 import {
   canDeferScaleConsumerApplication,
+  getLayerScaleIds,
   getExistingMarkRematerializationStep,
   getMarkMaterializationStep,
-  getSourceDependentMarkSteps
+  getScaleConsumerMarkSteps,
+  getSourceDependentMarkSteps,
+  reusePlannedMarkScales
 } from "./marks/index.js";
-import { requireLayer } from "../selectors/layers.js";
+import { findLayer, requireLayer } from "../selectors/layers.js";
 import {
-  applyMaterializationPlan,
+  applyMaterializationPlan as executeMaterializationPlan,
   buildMaterializationPlan
 } from "./planner.js";
 import { hasMaterializedLegend } from "./legends.js";
@@ -16,13 +20,6 @@ import {
 } from "./scaleGuideDependencies.js";
 import { planLayoutRematerialization } from "./layout.js";
 
-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) {
   const marks = [];
   for (const layer of program.semanticSpec.layers) {
@@ -38,7 +35,7 @@ export function planCanvasRematerialization(program) {
     if (needsCanvasScaleRematerialization(program, scale)) {
       const deferredConsumers = program.semanticSpec.layers.filter(layer =>
         canDeferScaleConsumerApplication(layer) &&
-        layerScaleIds(layer).includes(scale.id)
+        getLayerScaleIds(layer).includes(scale.id)
       );
       const canDeferMarks = deferredConsumers.length === 0 ||
         deferredConsumers.every(layer => deferredMarkIds.has(layer.id));
@@ -66,7 +63,7 @@ export function planCanvasRematerialization(program) {
 
 export function planLayerDataRematerialization(program, id) {
   const layer = requireLayer(program, id);
-  const scaleIds = [...new Set(layerScaleIds(layer))];
+  const scaleIds = [...new Set(getLayerScaleIds(layer))];
   const markStep = getMarkMaterializationStep(program, layer);
   const scales = scaleIds.map(scale => ({
       op: "rematerializeScale",
@@ -76,15 +73,19 @@ export function planLayerDataRematerialization(program, id) {
         ...(markStep === undefined ? {} : { marks: false })
       }
     }));
-  const marks = [
+  const directMarks = [
     ...(markStep === undefined ? [] : [markStep]),
-    ...getSourceDependentMarkSteps(program, id)
+    ...getScaleConsumerMarkSteps(program, scaleIds)
+  ];
+  const marks = [
+    ...directMarks,
+    ...directMarks.flatMap(step => getSourceDependentMarkSteps(program, step.args.id))
   ];
   if (scales.length > 0 || marks.length > 0) {
     const guides = scaleIds.flatMap(scale =>
       planScaleGuideRematerialization(program, scale)
     );
-    return buildMaterializationPlan({ scales, marks, guides });
+    return buildMaterializationPlan({ scales, marks: reusePlannedMarkScales(program, marks, scaleIds), guides });
   }
   const existingStep = getExistingMarkRematerializationStep(program, layer);
   return buildMaterializationPlan({
@@ -99,5 +100,45 @@ export function applyLayerDataRematerialization(program, id) {
   );
 }
 
-export { applyMaterializationPlan } from "./planner.js";
+export function applyLayerEmptyDataView(program, id) {
+  requireLayer(program, id);
+  const targets = [
+    id,
+    ...getSourceDependentMarkSteps(program, id).map(step => step.args.id)
+  ];
+  let next = program;
+  for (const target of new Set(targets)) {
+    const graphic = next.graphicSpec.objects[target];
+    if (graphic === undefined) continue;
+    next = graphic.type === "collection"
+      ? next.editGraphics({ target, property: "items", value: [] })
+      : next.editGraphics({ target, property: "length", value: 0 });
+  }
+  return next;
+}
+
+export function applyDetachedScaleRematerialization(program, previousLayers) {
+  const retained = new Set(program.semanticSpec.layers.flatMap(getLayerScaleIds));
+  const scaleIds = [...new Set(previousLayers.flatMap(layer => {
+    const current = findLayer(program, layer.id);
+    const currentIds = current === undefined ? [] : getLayerScaleIds(current);
+    return getLayerScaleIds(layer).filter(id => !currentIds.includes(id) && retained.has(id));
+  }))];
+  if (scaleIds.length === 0) return program;
+  const directMarks = getScaleConsumerMarkSteps(program, scaleIds);
+  return applyMaterializationPlan(program, buildMaterializationPlan({
+    scales: scaleIds.map(id => ({
+      op: "rematerializeScale", args: { id, guides: false, marks: false }
+    })),
+    marks: [
+      ...directMarks,
+      ...directMarks.flatMap(step => getSourceDependentMarkSteps(program, step.args.id))
+    ],
+    guides: scaleIds.flatMap(id => planScaleGuideRematerialization(program, id))
+  }));
+}
+
+export function applyMaterializationPlan(program, plan) {
+  return withGuideLayoutTransaction(program, next => executeMaterializationPlan(next, plan));
+}
 export { planScaleGuideRematerialization };

package/src/materialization/encodings.js

@@ -25,7 +25,7 @@ export function planEncodingRematerialization(program, {
   );
   const marks = [
     ...directMarks,
-    ...getSourceDependentMarkSteps(program, target)
+    ...directMarks.flatMap(step => getSourceDependentMarkSteps(program, step.args.id))
   ];
 
   const guides = [];

package/src/materialization/facets.js

@@ -162,10 +162,17 @@ export function resolveFacetProgramLayout(program, preparedLegend) {
   }
   const title = titleLayout(program);
   const spec = program.compositionSpec;
+  const gridCells = new Map(
+    (spec.facet.grid?.cells ?? []).map(cell => [cell.id, cell])
+  );
   const layout = resolveFacetLayout({
     children: spec.children.map((id, index) => ({
       ...compositionChildDescriptor(id, program.children[id]),
-      value: spec.facet.values[index]
+      value: spec.facet.values[index],
+      ...(gridCells.has(id) ? {
+        row: gridCells.get(id).row,
+        column: gridCells.get(id).column
+      } : {})
     })),
     columns: spec.columns,
     gap: spec.gap,

package/src/materialization/guides/layout.js

@@ -0,0 +1,57 @@
+import { assertGuideCollisionBlocks } from "../../layout/guideCollisions.js";
+import { unionConcreteGraphicBounds } from "../../grammar/schemas/graphicBounds.js";
+import { axisGraphicIds, legendResourcePolicies } from "./resources.js";
+
+// Only domain-owned guides participate. Extension primitives may deliberately
+// overlap, and a combined categorical/size legend is one occupied group.
+export function resolveGuideCollisionBlocks(graphicSpec, guideConfigs, titleConfig) {
+  const blocks = [];
+  const append = (id, kind, position, ids) => {
+    if (position === undefined) return;
+    const existing = ids.filter(id => graphicSpec.objects[id] !== undefined);
+    const bounds = unionConcreteGraphicBounds(graphicSpec, existing);
+    if (bounds !== undefined) blocks.push({ id, kind, position, bounds });
+  };
+  append("chart title", "title", titleConfig?.position, ["chartTitle", "chartSubtitle"]);
+  for (const channel of ["x", "y"]) {
+    for (const id of axisGraphicIds(channel)) {
+      const component = id.slice(`${channel}Axis`.length).toLowerCase();
+      append(`${channel}-axis ${component}`, "axis", guideConfigs.axis?.[channel]?.[component]?.position, [id]);
+    }
+  }
+  const policies = legendResourcePolicies();
+  const configs = guideConfigs.legend ?? {};
+  const categorical = policies.find(policy => policy.family === "categorical" && configs[policy.kind] !== undefined);
+  const combined = categorical !== undefined && configs.size !== undefined &&
+    configs[categorical.kind].target === configs.size.target;
+  for (const policy of policies) {
+    const config = configs[policy.kind];
+    if (config === undefined || combined && policy.kind === "size") continue;
+    const ids = combined && policy === categorical
+      ? [...policy.graphicIds, ...policies.find(item => item.kind === "size").graphicIds]
+      : policy.graphicIds;
+    append(`${policy.kind}${combined && policy === categorical ? "+size" : ""} legend`, "legend", config.position, ids);
+  }
+  return blocks;
+}
+
+
+// Defer cross-guide checks while sibling materializers still carry old
+// coordinates. The scope is transient and never survives a returned program.
+export function withGuideLayoutTransaction(program, apply) {
+  if (program.context.deferGuideLayoutValidation === true) return apply(program);
+  const result = apply(program._withContext({ deferGuideLayoutValidation: true }));
+  const { deferGuideLayoutValidation: _deferred, ...context } = result.context;
+  if (Object.hasOwn(program.context, "deferGuideLayoutValidation")) {
+    context.deferGuideLayoutValidation = program.context.deferGuideLayoutValidation;
+  }
+  const next = result._clone({ context });
+  assertGuideCollisionBlocks(resolveGuideCollisionBlocks(next.graphicSpec, next.guideConfigs, next.titleConfig));
+  return next;
+}
+
+export function withGuideLayoutValidation(implementation) {
+  return function (args) {
+    return withGuideLayoutTransaction(this, program => implementation.call(program, args));
+  };
+}

package/src/materialization/guides/resources.js

@@ -27,7 +27,7 @@ const LEGEND_RESOURCE_POLICIES = Object.freeze({
     family: "size",
     rematerializeOp: "rematerializeSizeLegend",
     graphicIds: Object.freeze([
-      "sizeLegendSymbols", "sizeLegendLabels", "sizeLegendTitle"
+      "sizeLegendBackground", "sizeLegendSymbols", "sizeLegendLabels", "sizeLegendTitle"
     ])
   }),
   gradient: Object.freeze({
@@ -62,7 +62,7 @@ const LEGEND_RESOURCE_POLICIES = Object.freeze({
     family: "strokeWidth",
     rematerializeOp: "rematerializeStrokeWidthLegend",
     graphicIds: Object.freeze([
-      "strokeWidthLegendSymbols", "strokeWidthLegendLabels",
+      "strokeWidthLegendBackground", "strokeWidthLegendSymbols", "strokeWidthLegendLabels",
       "strokeWidthLegendTitle"
     ])
   })

package/src/materialization/legends.js

@@ -1,5 +1,11 @@
+import { findLayer } from "../selectors/layers.js";
 import { LEGEND_CONFIG_KINDS } from "../core/vocabulary.js";
 
+export function isOpacityLegendLayer(layer) {
+  return ["point", "line"].includes(layer.mark?.type) &&
+    layer.encoding?.opacity?.scale !== undefined;
+}
+
 export function hasMaterializedLegend(program) {
   return LEGEND_CONFIG_KINDS.some(kind => {
     const config = program.guideConfigs?.legend?.[kind];
@@ -15,6 +21,9 @@ export function materializedLegendUsesScale(program, id) {
   return LEGEND_CONFIG_KINDS.some(kind => {
     const config = program.guideConfigs?.legend?.[kind];
     if (config === undefined) return false;
-    return config.scale === id || config.scales?.includes(id);
+    const order = program.semanticSpec.guides.legend?.[kind]?.order;
+    const linkedScale = order?.channel === undefined ? undefined
+      : findLayer(program, config.target)?.encoding?.[order.channel]?.scale;
+    return config.scale === id || config.scales?.includes(id) || linkedScale === id;
   });
 }

package/src/materialization/marks/capabilities.js

@@ -145,9 +145,9 @@ export function canMaterializeBar(program, layer) {
   ) {
     const offsetChannel = resolveBarOffsetChannel(layer);
     return (
-      layer.encoding?.color?.field !== undefined &&
-      layer.encoding?.[offsetChannel]?.field === layer.encoding.color.field &&
-      layer.encoding[offsetChannel].scale !== undefined
+      (layer.encoding?.group !== undefined || (layer.encoding?.color?.field !== undefined &&
+      layer.encoding?.[offsetChannel]?.field === layer.encoding.color.field)) &&
+      layer.encoding[offsetChannel]?.scale !== undefined
     );
   }
   return true;
@@ -163,14 +163,29 @@ export function canMaterializeRule(program, layer) {
   );
 }
 
+const TEXT_SOURCE_CAPABILITIES = Object.freeze({
+  point: canMaterializePoint,
+  line: canMaterializeLine,
+  bar: canMaterializeBar,
+  rule: canMaterializeRule,
+  rect: (program, layer) => canMaterializeRect(program, layer) ||
+    program.markConfigs[layer.id]?.gradientPlot?.materialized === true,
+  arc: canMaterializeArc
+});
+
+export function isTextSource(layer) {
+  return layer?.data !== undefined &&
+    Object.hasOwn(TEXT_SOURCE_CAPABILITIES, layer.mark?.type);
+}
+
 export function canMaterializeText(program, layer) {
   if (layer.mark?.type !== "text" || layer.encoding?.text === undefined) {
     return false;
   }
   if (layer.source !== undefined) {
     const source = findLayer(program, layer.source);
-    return source !== undefined &&
-      ["point", "bar", "rule", "rect", "arc"].includes(source.mark?.type) &&
+    return isTextSource(source) &&
+      TEXT_SOURCE_CAPABILITIES[source.mark.type](program, source) &&
       Array.isArray(program.graphicSpec.objects[source.id]?.items);
   }
   return hasCartesianPositionScales(layer);

package/src/materialization/marks/grouping.js

@@ -0,0 +1,52 @@
+import { findUpstreamTransform } from "../dataProvenance.js";
+import { readPathSeriesFields, validatePathSeriesAppearance } from "../../grammar/pathSeries.js";
+
+export function validatePathGroupAppearance(program, layer, dataset) {
+  if (layer.mark.type === "area" && findUpstreamTransform(program, dataset, "density")) {
+    // Density placement owns a category/split grain beyond the visible group field.
+    readPathSeriesFields(dataset.values, layer);
+    return;
+  }
+  validatePathSeriesAppearance(dataset.values, layer);
+}
+
+export function assertPathGroupCompatible(program, layer, dataset, group) {
+  if (layer.encoding?.parallel !== undefined) {
+    throw new Error("Parallel paths have row identity and do not support encodeGroup.");
+  }
+  const field = group?.field;
+  for (const [type, editor] of [
+    ["density", "editDensity"],
+    ["horizon", "editHorizon"],
+    ["regression", "editRegression"],
+    ["interval", "editErrorBand"]
+  ]) {
+    const transform = findUpstreamTransform(program, dataset, type);
+    if (transform === undefined) continue;
+    const fields = type === "horizon" ? [transform.as.group]
+      : type === "interval"
+        ? transform.groupBy.filter(value =>
+            value !== layer.encoding?.x?.field && value !== layer.encoding?.y?.field
+          )
+        : [transform.groupBy];
+    if (group?.fields !== undefined || group === undefined ||
+        field === undefined || !fields.includes(field)) {
+      throw new Error(
+        `${type === "density" ? "Density area" : type + " path"} mark "${layer.id}" must group by ${fields.length === 1 && fields[0] !== undefined ? JSON.stringify(fields[0]) : "its owned field"}; use ${editor}.`
+      );
+    }
+  }
+  if (layer.layout?.mode !== undefined) {
+    if (group === undefined && !["overlay"].includes(layer.layout.mode)) throw new Error("Remove active series layout before removing its group.");
+    return;
+  }
+  if (layer.mark?.type === "area" && (
+    layer.encoding?.y?.stack === "center" ||
+    ![undefined, "overlay"].includes(layer.encoding?.color?.layout)
+  )) {
+    if (group?.fields !== undefined ||
+        (layer.encoding?.color !== undefined && field !== layer.encoding.color.field)) {
+      throw new Error("Area layout requires one group field matching its color field.");
+    }
+  }
+}