ggaction 0.0.12 → 0.0.15

package/src/actions/guides/axes/titles.js

@@ -1,3 +1,5 @@
+import { isSourceOwnedText } from "../../../grammar/text.js";
+import { withGuideLayoutValidation } from "../../../materialization/guides/layout.js";
 import { action } from "../../../core/action.js";
 import { validateUserId } from "../../../core/identifiers.js";
 import {
@@ -5,7 +7,7 @@ import {
   validateNonEmptyString,
   validateNonNegativeFinite
 } from "../../../core/validation.js";
-import { resolveGraphicBounds } from "../../../layout/canvas.js";
+import { resolveGuideCoordinateBounds } from "../../../materialization/coordinateBounds.js";
 import {
   isTransformedScaleType,
   mapContinuousScaleValues,
@@ -32,6 +34,7 @@ import {
 import { resolveConcreteGraphicBounds } from
   "../../../grammar/schemas/graphicBounds.js";
 import { validateAxisTextStyle } from "./labels.js";
+import { resolveRotation } from "../../../grammar/rotation.js";
 
 function titleBounds(geometry, config, text) {
   return resolveTextBounds({
@@ -47,7 +50,11 @@ function titleBounds(geometry, config, text) {
 }
 
 function inferredTitleOffset(program, channel, config) {
-  const plot = resolveGraphicBounds(program);
+  const plot = resolveGuideCoordinateBounds(program, {
+    coordinate: program.semanticSpec.guides.axis?.[channel]?.coordinate,
+    scale: config.scale,
+    channel
+  });
   const canvas = findCanvasGraphic(program)?.properties;
   const labels = program.graphicSpec.objects[`${channel}AxisLabels`]
     ? resolveConcreteGraphicBounds(program.graphicSpec, `${channel}AxisLabels`)
@@ -102,7 +109,15 @@ export function inferAxisTitleText(program, channel, scaleId) {
   const titles = new Set();
   const primaryTitles = new Set();
   for (const layer of program.semanticSpec.layers) {
-    const encoding = layer.encoding?.[channel];
+    if (isSourceOwnedText(layer)) continue;
+    const primary = layer.encoding?.[channel];
+    const encoding = layer.mark?.type === "area" && Object.hasOwn(primary ?? {}, "datum")
+      ? layer.encoding?.[`${channel}2`] : primary;
+    if (channel === "radius" && layer.mark?.type === "arc" &&
+      encoding?.scale === scaleId && encoding.aggregate === "count" && encoding.field === undefined) {
+      titles.add(encoding.title ?? "count");
+      continue;
+    }
     if (
       encoding?.scale === scaleId &&
       typeof encoding.field === "string" &&
@@ -140,7 +155,11 @@ export function inferAxisTitleText(program, channel, scaleId) {
 
 function resolveGeometry(program, channel, config) {
   const scale = program.resolvedScales[config.scale];
-  const bounds = resolveGraphicBounds(program);
+  const bounds = resolveGuideCoordinateBounds(program, {
+    coordinate: program.semanticSpec.guides.axis?.[channel]?.coordinate,
+    scale: config.scale,
+    channel
+  });
   const discrete = ["ordinal", "band", "point"].includes(scale?.type);
   if ((
     !["linear", "time", "ordinal", "band", "point"].includes(scale?.type) &&
@@ -193,12 +212,12 @@ function names(channel) {
 
 function makeEdit(channel) {
   const operation = names(channel);
-  return action({ op: operation.edit, description: `Edit the ${channel}-axis title.` }, function (args = {}) {
+  return action({ op: operation.edit, description: `Edit the ${channel}-axis title.` }, withGuideLayoutValidation(function (args = {}) {
       validateKeys(args, EDIT_OPTIONS, operation.edit);
     if (this.graphicSpec.objects[operation.graphic]?.type !== "text") throw new Error(`${operation.edit} requires an existing axis title.`);
     const previous = this.guideConfigs.axis?.[channel]?.title;
     if (!previous) throw new Error(`${operation.edit} requires title configuration.`);
-    const { text, ...appearance } = args;
+    const { text, rotation: requestedRotation, ...appearance } = args;
     const explicitText = Object.hasOwn(args, "text");
     const explicitRotation = Object.hasOwn(args, "rotation");
     const position = appearance.position ?? previous.position;
@@ -211,7 +230,9 @@ function makeEdit(channel) {
       position,
       rotation: inferredRotation
         ? defaultAxisTitleRotation(channel, position)
-        : appearance.rotation ?? previous.rotation,
+        : explicitRotation
+          ? resolveRotation(requestedRotation, "Axis title rotation")
+          : previous.rotation,
       inferredRotation,
       inferredOffset: Object.hasOwn(args, "offset")
         ? false
@@ -245,7 +266,7 @@ function makeEdit(channel) {
     };
     for (const [property, value] of Object.entries(properties)) next = next.editGraphics({ target: operation.graphic, property, value });
     return next;
-  });
+  }));
 }
 
 const editXAxisTitle = makeEdit("x");
@@ -253,7 +274,7 @@ const editYAxisTitle = makeEdit("y");
 
 function makeCreate(channel) {
   const operation = names(channel);
-  return action({ op: operation.create, description: `Create the ${channel}-axis title.` }, function (args = {}) {
+  return action({ op: operation.create, description: `Create the ${channel}-axis title.` }, withGuideLayoutValidation(function (args = {}) {
       validateKeys(args, CREATE_OPTIONS, operation.create);
     const {
       text: requestedText,
@@ -281,7 +302,7 @@ function makeCreate(channel) {
       offset: channel === "x" ? 42 : 52,
       rotation: inferredRotation
         ? defaultAxisTitleRotation(channel, position)
-        : requestedRotation,
+        : resolveRotation(requestedRotation, "Axis title rotation"),
       inferredRotation,
       inferredOffset,
       color: DEFAULTS.color,
@@ -303,7 +324,7 @@ function makeCreate(channel) {
         ...resolvePlotGraphicPlacement(this)
       })
       ._withGuideConfig(channel, "title", config)[operation.edit]();
-  });
+  }));
 }
 
 const createXAxisTitle = makeCreate("x");

package/src/actions/guides/basic.js

@@ -5,6 +5,7 @@ import {
   registerBasicCategoricalLegendActions
 } from "./legends/categorical/index.js";
 import {
+  registerIntervalLegendActions,
   registerGradientLegendActions
 } from "./legends/continuous/index.js";
 import { registerSizeLegendActions } from "./legends/size.js";
@@ -13,6 +14,7 @@ export function registerBasicGuideActions(ProgramClass) {
   registerBasicCartesianAxisActions(ProgramClass);
   registerBasicCategoricalLegendActions(ProgramClass);
   registerGradientLegendActions(ProgramClass);
+  registerIntervalLegendActions(ProgramClass);
   registerSizeLegendActions(ProgramClass);
   registerBasicGridActions(ProgramClass);
   registerGuideCollectionActions(ProgramClass);

package/src/actions/guides/facade.js

@@ -0,0 +1,106 @@
+import { findCoordinate } from "../../selectors/coordinates.js";
+import { polarGuideNames } from "./polar/resolve.js";
+import { polarGridOperations, validatePolarGridOptions } from "./polar/grids.js";
+import { findLayer } from "../../selectors/layers.js";
+import { resolveGuideOptions } from "./guides.js";
+import { resolveGridOptions } from "./grids/grid.js";
+import { gridNames, validateGridCreateArgs } from "./grids/resolve.js";
+import { scopeFacadeAxes, planFacadeAxes } from "./facadeAxes.js";
+import { assertGuideOptions, guideConflict, resolveStoredGuideCoordinate } from "./reuse.js";
+import { planFacadeLegend } from "./facadeLegend.js";
+import { applyLegendCreationPlan } from "./legends/categorical/actions.js";
+
+function facadeGridNames(direction) {
+  return ["theta", "radial"].includes(direction)
+    ? { ...polarGridOperations(direction), channel: polarGuideNames(direction).channel }
+    : gridNames(direction);
+}
+
+function scopeGrid(program, layer, args) {
+  const directions = resolveGridOptions(program, args, [layer]);
+  const scoped = {};
+  const polar = findCoordinate(program, layer.coordinate)?.type === "polar";
+  for (const [direction, option] of Object.entries(directions)) {
+    if (option === undefined) continue;
+    if (polar !== ["theta", "radial"].includes(direction)) {
+      guideConflict("grid coordinate family does not belong to this facade");
+    }
+    const { channel, create } = facadeGridNames(direction);
+    const scale = layer.encoding?.[channel]?.scale;
+    if (scale === undefined || option.scale !== undefined && option.scale !== scale ||
+      option.coordinate !== undefined && option.coordinate !== layer.coordinate) {
+      guideConflict(`${direction} grid does not belong to this facade`);
+    }
+    scoped[direction] = { ...option, scale, coordinate: layer.coordinate };
+    if (polar) validatePolarGridOptions(scoped[direction], create, true);
+    else validateGridCreateArgs(scoped[direction], create);
+  }
+  // An explicit vertical-only request must not re-enable horizontal grid defaults.
+  if (polar) {
+    for (const direction of ["theta", "radial"]) if (scoped[direction] === undefined) scoped[direction] = false;
+  } else if (scoped.horizontal === undefined) scoped.horizontal = false;
+  return scoped;
+}
+
+function planGrid(program, args) {
+  return Object.entries(args).flatMap(([direction, option]) => {
+    if (option === false) return [];
+    const { channel, create } = facadeGridNames(direction);
+    const guide = program.semanticSpec.guides.grid?.[direction];
+    const config = program.guideConfigs.grid?.[direction];
+    if (guide === undefined && config === undefined) return [{ op: create, args: option }];
+    if (guide?.scale !== option.scale || config === undefined || config.scale !== option.scale ||
+      config.coordinate !== undefined && config.coordinate !== option.coordinate ||
+      resolveStoredGuideCoordinate(program, guide, channel) !== option.coordinate) {
+      guideConflict(`${direction} grid uses a different coordinate or scale`);
+    }
+    const { scale, coordinate, ...appearance } = option;
+    assertGuideOptions(appearance, config, `${direction} grid`);
+    return [];
+  });
+}
+
+export function fulfillFacadeGuides(program, guides, target, explicitGuides = guides) {
+  if (guides === false) return program;
+  const layer = findLayer(program, target);
+  if (layer === undefined) throw new Error(`Unknown facade guide target "${target}".`);
+  const resolved = resolveGuideOptions(program, guides, [layer]);
+  const axisDirections = Object.entries(resolved.axes ?? {}).filter(([key]) => key !== "coordinate");
+  const scopedAxes = resolved.axes === undefined || axisDirections.length > 0 && axisDirections.every(
+    ([, value]) => value === false
+  )
+    ? undefined
+    : scopeFacadeAxes(program, layer, resolved.axes);
+  const axes = scopedAxes;
+  const scopedGrid = resolved.grid === undefined || Object.values(resolved.grid).every(
+    value => value === false
+  )
+    ? undefined
+    : scopeGrid(program, layer, resolved.grid);
+  const grid = scopedGrid;
+  const legend = resolved.legend === undefined ? undefined : { ...resolved.legend, target };
+  if (resolved.legend?.target !== undefined && resolved.legend.target !== target) {
+    guideConflict("legend target does not belong to this facade");
+  }
+  if (axes === undefined && grid === undefined && legend === undefined) return program;
+  const legendPlan = legend === undefined ? undefined
+    : planFacadeLegend(program, layer, legend, explicitGuides.legend ?? {});
+  const steps = [
+    ...(axes === undefined ? [] : planFacadeAxes(program, layer, axes, explicitGuides.axes)),
+    ...(grid === undefined ? [] : planGrid(program, grid))
+  ];
+  const hasExisting = [program.guideConfigs.axis, program.guideConfigs.grid, program.guideConfigs.legend,
+    program.semanticSpec.guides.axis, program.semanticSpec.guides.grid, program.semanticSpec.guides.legend]
+    .some(config => Object.keys(config ?? {}).length > 0);
+  const unambiguousAxes = axes?.coordinate.type !== "parallel" ||
+    program.semanticSpec.layers.filter(candidate =>
+      candidate.coordinate === layer.coordinate && candidate.encoding?.parallel !== undefined
+    ).length === 1;
+  if (!hasExisting && unambiguousAxes) {
+    return program.createGuides({ axes: axes ?? false, grid: grid ?? false, legend: legendPlan?.args ?? false });
+  }
+  let next = program;
+  for (const step of steps) next = next[step.op](step.args);
+  if (legendPlan !== undefined) next = applyLegendCreationPlan(next, legendPlan);
+  return next;
+}

package/src/actions/guides/facadeAxes.js

@@ -0,0 +1,200 @@
+import { validatePolarAxisArgs } from "./polar/axes/facade.js";
+import { prefix as polarPrefix, resolveAngle } from "./polar/axes/shared.js";
+import { validateAxesArgs } from "./axes/axes.js";
+import { validateAxisArgs } from "./axes/axis.js";
+import { axisComponentDisabled, hasAxisComponent } from "./axes/components.js";
+import { validateAxisTickGroupArgs } from "./axes/tickGroups.js";
+import { findCoordinate } from "../../selectors/coordinates.js";
+import {
+  assertGuideOptions, guideConflict, resolveStoredGuideCoordinate, sameGuideValue
+} from "./reuse.js";
+
+export function scopeFacadeAxes(program, layer, args) {
+  const descriptor = validateAxesArgs(args);
+  const coordinate = findCoordinate(program, layer.coordinate);
+  if (coordinate === undefined) guideConflict(`layer "${layer.id}" has no coordinate`);
+  if (descriptor.id !== undefined && descriptor.id !== coordinate.id) {
+    guideConflict("axes.coordinate.id does not belong to this facade");
+  }
+  if (descriptor.type !== undefined && descriptor.type !== "auto" && descriptor.type !== coordinate.type) {
+    guideConflict("axes.coordinate.type does not match this facade");
+  }
+  if (coordinate.type === "polar") {
+    if (args.x !== undefined || args.y !== undefined) guideConflict("Polar facades do not own Cartesian axes");
+    const scoped = { coordinate: { id: coordinate.id, type: "polar" } };
+    for (const channel of ["theta", "radius"]) {
+      const option = args[channel];
+      const scale = layer.encoding?.[channel]?.scale;
+      if (option === false || option === undefined && scale === undefined) { scoped[channel] = false; continue; }
+      if (scale === undefined || option?.scale !== undefined && option.scale !== scale ||
+        option?.coordinate !== undefined && option.coordinate !== coordinate.id) {
+        guideConflict(`axes.${channel} does not belong to this facade`);
+      }
+      scoped[channel] = { ...option, scale, coordinate: coordinate.id };
+      validatePolarAxisArgs(channel, scoped[channel], `create${polarPrefix(channel)}Axis`);
+      resolveAngle(program, channel, scoped[channel]);
+    }
+    return scoped;
+  }
+  if (args.theta !== undefined || args.radius !== undefined) {
+    guideConflict("Cartesian and Parallel facades do not own Polar axes");
+  }
+  if (coordinate.type === "parallel") {
+    if (args.x !== undefined || args.y !== undefined) {
+      throw new Error("createAxes channel options are not supported for Parallel axes.");
+    }
+    return { coordinate: { id: coordinate.id, type: "parallel" } };
+  }
+  const scoped = { coordinate: { id: coordinate.id, type: "cartesian" } };
+  for (const channel of ["x", "y"]) {
+    const option = args[channel];
+    if (option === false || (option === undefined && layer.encoding?.[channel] === undefined)) {
+      scoped[channel] = false;
+      continue;
+    }
+    const scale = layer.encoding?.[channel]?.scale;
+    if (scale === undefined) guideConflict(`this facade has no ${channel} scale`);
+    if (option?.scale !== undefined && option.scale !== scale) {
+      guideConflict(`axes.${channel}.scale does not belong to this facade`);
+    }
+    if (option?.coordinate !== undefined && option.coordinate !== coordinate.id) {
+      guideConflict(`axes.${channel}.coordinate does not belong to this facade`);
+    }
+    scoped[channel] = { ...option, scale, coordinate: coordinate.id };
+    validateAxisArgs(scoped[channel], `create${channel.toUpperCase()}Axis`);
+    if (scoped[channel].ticksAndLabels !== false) {
+      validateAxisTickGroupArgs(scoped[channel].ticksAndLabels ?? {}, "createAxisTicksAndLabels", true);
+    }
+  }
+  return scoped;
+}
+
+function tickMode(config) {
+  return config?.mode === "values" ? { values: config.values }
+    : config?.mode === "count" ? { count: config.count } : {};
+}
+
+function planAxis(program, channel, args, explicit) {
+  const prefix = channel.toUpperCase();
+  const guide = program.semanticSpec.guides.axis?.[channel];
+  const configs = program.guideConfigs.axis?.[channel] ?? {};
+  if (guide === undefined && Object.keys(configs).length === 0) {
+    return [{ op: `create${prefix}Axis`, args }];
+  }
+  if (guide?.scale !== args.scale || resolveStoredGuideCoordinate(program, guide, channel) !== args.coordinate) {
+    guideConflict(`${channel} axis uses a different coordinate or scale`);
+  }
+  const positions = [...new Set(Object.values(configs).map(config => config.position).filter(Boolean))];
+  if (positions.length > 1) guideConflict(`${channel} axis components have incompatible positions`);
+  const position = explicit.position ?? positions[0];
+  const shared = { scale: args.scale, ...(position === undefined ? {} : { position }) };
+  const explicitShared = explicit.position === undefined ? {} : { position: explicit.position };
+  const steps = guide.coordinate === undefined ? [{
+    op: "editSemantic", args: { property: `guide.axis.${channel}.coordinate`, value: args.coordinate }
+  }] : [];
+  const group = args.ticksAndLabels ?? {};
+  const explicitGroup = explicit.ticksAndLabels ?? {};
+  const explicitMode = Object.fromEntries(["count", "values"].filter(key =>
+    Object.hasOwn(explicitGroup, key)
+  ).map(key => [key, explicitGroup[key]]));
+  const requested = {
+    line: { ...explicitShared, ...(explicit.line ?? {}) },
+    ticks: { ...explicitShared, ...explicitMode, ...(explicitGroup.ticks ?? {}) },
+    labels: { ...explicitShared, ...explicitMode, ...(explicitGroup.labels ?? {}) },
+    title: { ...explicitShared, ...(explicit.title ?? {}) }
+  };
+  for (const component of ["line", "ticks", "labels", "title"]) {
+    const config = configs[component];
+    if (axisComponentDisabled(args, component)) {
+      if (hasAxisComponent(program, channel, component)) guideConflict(`${channel} axis already has ${component}`);
+      continue;
+    }
+    if (config === undefined) continue;
+    if (config.scale !== undefined && config.scale !== args.scale) {
+      guideConflict(`${channel} ${component} uses a different scale`);
+    }
+    assertGuideOptions(requested[component], component === "title"
+      ? { ...config, text: guide.title } : config, `${channel} axis ${component}`);
+  }
+  if (args.line !== false && configs.line === undefined) {
+    steps.push({ op: `create${prefix}AxisLine`, args: { ...shared, ...args.line } });
+  }
+  if (args.ticksAndLabels !== false) {
+    if (configs.ticks === undefined && configs.labels === undefined) {
+      steps.push({ op: `create${prefix}AxisTicksAndLabels`, args: { ...shared, ...group } });
+    } else {
+      if (configs.ticks === undefined) {
+        steps.push({ op: `create${prefix}AxisTicks`, args: { ...shared, ...tickMode(configs.labels), ...explicitMode, ...group.ticks } });
+      }
+      if (configs.labels === undefined) {
+        steps.push({ op: `create${prefix}AxisLabels`, args: { ...shared, ...group.labels } });
+      }
+    }
+  }
+  if (args.title !== false && configs.title === undefined) {
+    steps.push({ op: `create${prefix}AxisTitle`, args: { ...shared, ...args.title } });
+  }
+  return steps;
+}
+
+export function planFacadeAxes(program, layer, scoped, explicit = {}) {
+  if (scoped.coordinate.type === "parallel") {
+    const existing = program.semanticSpec.guides.axis?.parallel;
+    if (existing === undefined) return [{
+      op: "createParallelAxes", args: { target: layer.id, coordinate: layer.coordinate }
+    }];
+    const scales = layer.encoding.parallel.dimensions.map(dimension => dimension.scale);
+    if (existing.coordinate !== layer.coordinate || !sameGuideValue(existing.scales, scales)) {
+      guideConflict("Parallel axes use a different coordinate or dimension scales");
+    }
+    return [];
+  }
+  if (scoped.coordinate.type === "polar") {
+    return ["theta", "radius"].flatMap(channel => scoped[channel] === false ? []
+      : planPolarAxis(program, channel, scoped[channel], explicit[channel] ?? {}));
+  }
+  return ["x", "y"].flatMap(channel => scoped[channel] === false ? []
+    : planAxis(program, channel, scoped[channel], explicit[channel] ?? {}));
+}
+
+function planPolarAxis(program, channel, args, explicit) {
+  const prefix = polarPrefix(channel);
+  const guide = program.semanticSpec.guides.axis?.[channel];
+  const configs = program.guideConfigs.axis?.[channel] ?? {};
+  if (guide === undefined && Object.keys(configs).length === 0) return [{ op: `create${prefix}Axis`, args }];
+  if (guide?.scale !== args.scale || resolveStoredGuideCoordinate(program, guide, channel) !== args.coordinate) {
+    guideConflict(`${channel} axis uses a different coordinate or scale`);
+  }
+  const shared = { scale: args.scale, coordinate: args.coordinate,
+    ...(channel === "radius" ? { angle: resolveAngle(program, channel, args) } : {}) };
+  const group = args.ticksAndLabels ?? {};
+  const explicitGroup = explicit.ticksAndLabels ?? {};
+  const mode = Object.fromEntries(["count", "values"].filter(key => Object.hasOwn(explicitGroup, key))
+    .map(key => [key, explicitGroup[key]]));
+  const requested = {
+    line: explicit.line ?? {},
+    ticks: { ...mode, ...explicitGroup.ticks },
+    labels: { ...mode, ...explicitGroup.labels },
+    title: explicit.title || {}
+  };
+  const steps = [];
+  for (const component of ["line", "ticks", "labels", "title"]) {
+    const config = configs[component];
+    if (axisComponentDisabled(args, component)) {
+      if (hasAxisComponent(program, channel, component)) guideConflict(`${channel} axis already has ${component}`);
+      continue;
+    }
+    if (config !== undefined) {
+      if (config.scale !== args.scale || config.coordinate !== args.coordinate) guideConflict(`${channel} ${component} uses different resources`);
+      assertGuideOptions(requested[component], component === "title" ? { ...config, text: guide.title } : config,
+        `${channel} axis ${component}`);
+      continue;
+    }
+    const options = component === "line" ? args.line ?? {} : component === "title" ? args.title ?? {}
+      : { ...tickMode(configs[component === "ticks" ? "labels" : "ticks"]),
+          ...Object.fromEntries(["count", "values"].filter(key => Object.hasOwn(group, key)).map(key => [key, group[key]])),
+          ...group[component] };
+    steps.push({ op: `create${prefix}Axis${component[0].toUpperCase() + component.slice(1)}`, args: { ...shared, ...options } });
+  }
+  return steps;
+}

package/src/actions/guides/facadeLegend.js

@@ -0,0 +1,63 @@
+import { resolveLegendCreationPlan } from "./legends/categorical/actions.js";
+import { resolveLegendStepConfig } from "./legends/creation.js";
+import { legendResourcePolicy } from "../../materialization/guides/resources.js";
+import { assertGuideOptions, guideConflict, sameGuideValue } from "./reuse.js";
+
+function compatibleLegend(program, kind, requested, existing, explicit) {
+  const expectedScales = requested.scales ?? [requested.scale];
+  const actualScales = existing.scales ?? [existing.scale];
+  if (!sameGuideValue(expectedScales, actualScales) ||
+    !sameGuideValue(requested.channels, existing.channels)) {
+    guideConflict(`${kind} legend uses different channels or scales`);
+  }
+  const domain = config => config.domain ?? program.resolvedScales[config.scale]?.domain;
+  if (!sameGuideValue(domain(requested), domain(existing))) {
+    guideConflict(`${kind} legend uses a different domain or order`);
+  }
+  if (requested.symbol?.layers !== undefined && !sameGuideValue(
+    requested.symbol.layers.map(layer => layer.type), existing.symbol?.layers?.map(layer => layer.type)
+  )) guideConflict(`${kind} legend uses a different symbol recipe`);
+  const appearance = {};
+  for (const [key, value] of Object.entries(explicit)) {
+    if (["target", "channels"].includes(key) || requested[key] === undefined) continue;
+    if (key === "symbol" && requested.symbol?.layers !== undefined) {
+      appearance.symbol = value === "auto" ? requested.symbol
+        : value.layers !== undefined ? value
+          : { layers: [{ type: requested.symbol.layers[0].type, ...value }] };
+    } else if (key === "border" && value === true) {
+      if (existing.border === false) guideConflict(`${kind} legend border is disabled`);
+      appearance.border = {};
+    } else appearance[key] = value;
+  }
+  assertGuideOptions(appearance, existing, `${kind} legend`);
+}
+
+export function planFacadeLegend(program, layer, args, explicit = args) {
+  const plan = resolveLegendCreationPlan(program, args, [layer]);
+  const steps = [];
+  for (const step of plan.steps) {
+    const { kind, config } = resolveLegendStepConfig(program, step);
+    const stored = program.guideConfigs.legend?.[kind];
+    const policy = legendResourcePolicy(kind);
+    const occupied = program.semanticSpec.guides.legend?.[policy.semanticKind];
+    if (stored === undefined) {
+      if (occupied !== undefined ||
+        policy.family === "categorical" && (
+          program.semanticSpec.guides.legend?.series !== undefined ||
+          program.semanticSpec.guides.legend?.color !== undefined
+        )) {
+        guideConflict(`${kind} legend slot belongs to an incompatible legend family`);
+      }
+      steps.push(step);
+    } else {
+      if (occupied === undefined) guideConflict(`${kind} legend has no semantic owner`);
+      compatibleLegend(program, kind, config, stored, explicit);
+    }
+  }
+  const first = plan.steps[0];
+  const scopedArgs = first?.op === "createCategoricalLegend" && first.args.symbol !== undefined
+    ? { ...args, symbol: first.args.symbol } : args;
+  // Reused blocks retain their original target. The direct createLegend combined
+  // owner check is inapplicable to independently verified shared blocks.
+  return { ...plan, combined: false, steps, args: scopedArgs };
+}

package/src/actions/guides/grids/grid.js

@@ -217,45 +217,49 @@ const editGrid = action(
   }
 );
 
+export function resolveGridOptions(program, args = {}, layers = program.semanticSpec.layers) {
+  validateOptionObject(args, AGGREGATE_OPTIONS, "createGrid");
+  const automatic = Object.keys(args).length === 0
+    ? resolveAutomaticGridOptions(program, layers)
+    : undefined;
+  const hasExplicitPolar = Object.hasOwn(args, "theta") ||
+    Object.hasOwn(args, "radial");
+  const polarDefault = automatic !== undefined &&
+    (Object.hasOwn(automatic, "theta") || Object.hasOwn(automatic, "radial"));
+  const horizontal = automatic !== undefined
+    ? automatic.horizontal === false ? undefined : automatic.horizontal
+    : polarDefault ||
+    (hasExplicitPolar && args.horizontal === undefined)
+    ? undefined
+    : normalizeDirection(args.horizontal, "horizontal");
+  const vertical = automatic !== undefined
+    ? automatic.vertical === false ? undefined : automatic.vertical
+    : args.vertical === undefined
+    ? undefined
+    : normalizeDirection(args.vertical, "vertical");
+  const theta = automatic !== undefined
+    ? automatic.theta
+    : args.theta === undefined
+      ? undefined
+      : normalizeDirection(args.theta, "theta");
+  const radial = automatic !== undefined
+    ? automatic.radial
+    : args.radial === undefined
+      ? undefined
+      : normalizeDirection(args.radial, "radial");
+  if ([horizontal, vertical, theta, radial].every(value => value === undefined)) {
+    throw new Error("createGrid requires at least one selected direction.");
+  }
+  return { horizontal, vertical, theta, radial };
+}
+
 const createGrid = action(
   {
     op: "createGrid",
     description: "Create selected Cartesian grid directions."
   },
   function (args = {}) {
-    validateOptionObject(args, AGGREGATE_OPTIONS, "createGrid");
-    const automatic = Object.keys(args).length === 0
-      ? resolveAutomaticGridOptions(this)
-      : undefined;
-    const hasExplicitPolar = Object.hasOwn(args, "theta") ||
-      Object.hasOwn(args, "radial");
-    const polarDefault = automatic !== undefined &&
-      (Object.hasOwn(automatic, "theta") || Object.hasOwn(automatic, "radial"));
-    const horizontal = automatic !== undefined
-      ? automatic.horizontal === false ? undefined : automatic.horizontal
-      : polarDefault ||
-      (hasExplicitPolar && args.horizontal === undefined)
-      ? undefined
-      : normalizeDirection(args.horizontal, "horizontal");
-    const vertical = automatic !== undefined
-      ? automatic.vertical === false ? undefined : automatic.vertical
-      : args.vertical === undefined
-      ? undefined
-      : normalizeDirection(args.vertical, "vertical");
-    const theta = automatic !== undefined
-      ? automatic.theta
-      : args.theta === undefined
-        ? undefined
-        : normalizeDirection(args.theta, "theta");
-    const radial = automatic !== undefined
-      ? automatic.radial
-      : args.radial === undefined
-        ? undefined
-        : normalizeDirection(args.radial, "radial");
-    if ([horizontal, vertical, theta, radial].every(value => value === undefined)) {
-      throw new Error("createGrid requires at least one selected direction.");
-    }
-
+    const { horizontal, vertical, theta, radial } = resolveGridOptions(this, args);
     let next = this;
     if (horizontal !== undefined) {
       next = next.createHorizontalGrid(horizontal);

package/src/actions/guides/grids/resolve.js

@@ -1,3 +1,4 @@
+import { isSourceOwnedText } from "../../../grammar/text.js";
 import { validateUserId } from "../../../core/identifiers.js";
 import {
   validateGeneratedItemLimit,
@@ -9,7 +10,7 @@ import {
   isTransformedScaleType,
   mapContinuousScaleValues
 } from "../../../grammar/scales/index.js";
-import { resolveGraphicBounds } from "../../../layout/canvas.js";
+import { resolveGuideCoordinateBounds } from "../../../materialization/coordinateBounds.js";
 import { resolveGridLineGeometry } from "../../../layout/grid.js";
 import { DEFAULT_COLORS } from "../../../theme/defaults.js";
 import { findCoordinate } from "../../../selectors/coordinates.js";
@@ -126,7 +127,7 @@ export function validateGridEditArgs(args, operation) {
 export function resolveGridResources(program, direction, args) {
   const { channel } = gridNames(direction);
   let layers = program.semanticSpec.layers.filter(
-    layer => layer.encoding?.[channel]?.scale !== undefined
+    layer => !isSourceOwnedText(layer) && layer.encoding?.[channel]?.scale !== undefined
   );
   if (layers.length === 0) throw new Error(`${direction} grid requires a ${channel} encoding.`);
   const requestedCoordinate = args.coordinate === undefined
@@ -167,7 +168,14 @@ export function resolveGridResources(program, direction, args) {
   ) {
     throw new Error(`${direction} grid requires resolved continuous scale "${scale}".`);
   }
-  const related = new Set(layers.map(layer => layer.id));
+  const sourceIds = new Set(layers.map(layer => layer.id));
+  const relatedLayers = [...layers, ...program.semanticSpec.layers.filter(layer =>
+    isSourceOwnedText(layer) && sourceIds.has(layer.source)
+  )];
+  const related = new Set(relatedLayers.flatMap(layer => {
+    const leader = program.materializationConfigs.labelLayouts?.[layer.id]?.leaderId;
+    return leader === undefined ? [layer.id] : [leader, layer.id];
+  }));
   let before;
   walkGraphicDrawOrder(program.graphicSpec, ({ id }) => {
     if (before === undefined && related.has(id)) before = id;
@@ -240,7 +248,12 @@ export function editGridConfig(previous, args) {
 
 export function resolveGridGeometry(program, config) {
   const scale = program.resolvedScales[config.scale];
-  const bounds = resolveGraphicBounds(program);
+  const channel = config.direction === "horizontal" ? "y" : "x";
+  const bounds = resolveGuideCoordinateBounds(program, {
+    coordinate: config.coordinate,
+    scale: config.scale,
+    channel
+  });
   if ((
     !["linear", "time"].includes(scale?.type) &&
     !isTransformedScaleType(scale?.type)