ggaction 0.0.17 → 0.0.19

package/src/actions/guides/facadeAxes.js

@@ -1,3 +1,4 @@
+import { axisTargetArgs } from "../../selectors/axes.js";
 import { validatePolarAxisArgs } from "./polar/axes/facade.js";
 import { prefix as polarPrefix, resolveAngle } from "./polar/axes/shared.js";
 import { validateAxesArgs } from "./axes/axes.js";
@@ -47,24 +48,26 @@ export function scopeFacadeAxes(program, layer, args) {
   }
   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);
-    }
+    const scope = option => {
+      if (option === false || (option === undefined && layer.encoding?.[channel] === undefined)) {
+        return false;
+      }
+      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`);
+      }
+      const scopedOption = { ...option, scale, coordinate: coordinate.id };
+      validateAxisArgs(scopedOption, `create${channel.toUpperCase()}Axis`);
+      if (scopedOption.ticksAndLabels !== false) {
+        validateAxisTickGroupArgs(scopedOption.ticksAndLabels ?? {}, "createAxisTicksAndLabels", true);
+      }
+      return scopedOption;
+    };
+    scoped[channel] = Array.isArray(args[channel]) ? args[channel].map(scope) : scope(args[channel]);
   }
   return scoped;
 }
@@ -76,21 +79,25 @@ function tickMode(config) {
 
 function planAxis(program, channel, args, explicit) {
   const prefix = channel.toUpperCase();
-  const guide = program.semanticSpec.guides.axis?.[channel];
-  const configs = program.guideConfigs.axis?.[channel] ?? {};
+  const axisId = args.id ?? channel;
+  const guide = program.semanticSpec.guides.axis?.[axisId];
+  const configs = program.guideConfigs.axis?.[axisId] ?? {};
   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`);
   }
+  if (explicit.offset !== undefined && explicit.offset !== (configs.frame?.offset ?? 0)) {
+    guideConflict(`${channel} axis uses a different frame offset`);
+  }
   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 shared = { ...axisTargetArgs(axisId, channel), 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 }
+    op: "editSemantic", args: { property: `guide.axis.${axisId}.coordinate`, value: args.coordinate }
   }] : [];
   const group = args.ticksAndLabels ?? {};
   const explicitGroup = explicit.ticksAndLabels ?? {};
@@ -106,7 +113,7 @@ function planAxis(program, channel, args, explicit) {
   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}`);
+      if (hasAxisComponent(program, channel, component, axisId)) guideConflict(`${channel} axis already has ${component}`);
       continue;
     }
     if (config === undefined) continue;
@@ -154,7 +161,9 @@ export function planFacadeAxes(program, layer, scoped, explicit = {}) {
       : planPolarAxis(program, channel, scoped[channel], explicit[channel] ?? {}));
   }
   return ["x", "y"].flatMap(channel => scoped[channel] === false ? []
-    : planAxis(program, channel, scoped[channel], explicit[channel] ?? {}));
+    : Array.isArray(scoped[channel])
+      ? scoped[channel].flatMap((entry, index) => planAxis(program, channel, entry, explicit[channel]?.[index] ?? {}))
+      : planAxis(program, channel, scoped[channel], explicit[channel] ?? {}));
 }
 
 function planPolarAxis(program, channel, args, explicit) {

package/src/actions/guides/facadeLegend.js

@@ -4,8 +4,8 @@ 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];
+  const expectedScales = kind === "colorSize" ? [requested.colorScale,requested.sizeScale] : requested.scales ?? [requested.scale];
+  const actualScales = kind === "colorSize" ? [existing.colorScale,existing.sizeScale] : existing.scales ?? [existing.scale];
   if (!sameGuideValue(expectedScales, actualScales) ||
     !sameGuideValue(requested.channels, existing.channels)) {
     guideConflict(`${kind} legend uses different channels or scales`);
@@ -17,10 +17,18 @@ function compatibleLegend(program, kind, requested, existing, explicit) {
   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`);
+  if (explicit.representation !== undefined && (requested.representation ?? "gradient") !== (existing.representation ?? "gradient")) guideConflict(`${kind} legend uses a different color representation`);
+  if (requested.representation === "symbols" || kind === "colorSize") {
+    if (explicit.values !== undefined && !sameGuideValue(requested.sampling.values, existing.sampling?.values)) guideConflict(`${kind} legend uses different exact samples`);
+    if (explicit.count !== undefined && (existing.sampling?.mode !== "auto" || requested.sampling.count !== existing.sampling?.count)) guideConflict(`${kind} legend uses a different sample count`);
+  }
   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) {
+    if (["target", "channels", "representation", "values"].includes(key) || requested[key] === undefined) continue;
+    if (key === "title") {
+      appearance.titleVisible = value !== false;
+      if (value !== false) appearance.title = value;
+    } else 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 }] };

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

@@ -8,6 +8,7 @@ import {
   refreshGridConfig,
   resolveGridConfig,
   resolveGridGeometry,
+  resolveGridPlacement,
   resolveGridResources,
   validateGridCreateArgs,
   validateGridEditArgs
@@ -60,7 +61,12 @@ function makeRematerialize(direction) {
 
       const config = refreshGridConfig(this, storedConfig);
       const geometry = resolveGridGeometry(this, config);
-      let next = this._withGridConfig(direction, config).editGraphics({
+      let next = this._withGridConfig(direction, config);
+      if (config.zIndex !== undefined) {
+        const placement = resolveGridPlacement(next, config);
+        next = next.editGraphics({ target: operation.graphic, remove: true }).createGraphics({ id: operation.graphic, type: "line", length: 0, ...placement });
+      }
+      next = next.editGraphics({
         target: operation.graphic,
         property: "length",
         value: geometry.values.length
@@ -79,7 +85,7 @@ function makeRematerialize(direction) {
         .editGraphics({
           target: operation.graphic,
           property: "strokeDash",
-          value: geometry.values.map(() => config.strokeDash)
+          value: geometry.strokeDash
         });
     }
   );

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

@@ -1,3 +1,7 @@
+import { cartesianAxisOwners } from "../../../selectors/axes.js";
+import { axisGraphicIds } from "../../../materialization/guides/resources.js";
+import { isNominalValue } from "../../../grammar/scales/fields.js";
+import { patchGuideDash, validateGuideDash, normalizeGuideDashMap, resolveGuideDashes } from "../../../grammar/guideDash.js";
 import { isSourceOwnedText } from "../../../grammar/text.js";
 import { validateUserId } from "../../../core/identifiers.js";
 import {
@@ -8,6 +12,7 @@ import {
 } from "../../../core/validation.js";
 import {
   isTransformedScaleType,
+  mapOrdinalPositionValues,
   mapContinuousScaleValues
 } from "../../../grammar/scales/index.js";
 import { resolveGuideCoordinateBounds } from "../../../materialization/coordinateBounds.js";
@@ -20,14 +25,15 @@ import {
 } from "../tickValues.js";
 import {
   findGraphicParent,
+  graphicSiblings,
   walkGraphicDrawOrder
 } from "../../../grammar/schemas/graphicTree.js";
 
 const GRID_OPTIONS = Object.freeze([
-  "scale", "coordinate", "count", "values", "color", "lineWidth", "strokeDash"
+  "scale", "coordinate", "count", "values", "color", "lineWidth", "strokeDash", "strokeDashMap", "zIndex", "bandPosition", "alongOffset"
 ]);
 const GRID_EDIT_OPTIONS = Object.freeze([
-  "count", "values", "color", "lineWidth", "strokeDash"
+  "count", "values", "color", "lineWidth", "strokeDash", "strokeDashMap", "zIndex", "bandPosition", "alongOffset"
 ]);
 const DEFAULT_STYLE = Object.freeze({
   color: DEFAULT_COLORS.grid,
@@ -46,19 +52,11 @@ export function gridNames(direction) {
 }
 
 function validateStrokeDash(value) {
-  if (
-    !Array.isArray(value) ||
-    value.length % 2 !== 0 ||
-    !value.every(item => Number.isFinite(item) && item >= 0)
-  ) {
-    throw new TypeError(
-      "Grid strokeDash must be an even-length array of non-negative finite numbers."
-    );
-  }
-  return value;
+  return validateGuideDash(value, "Grid strokeDash");
 }
 
 export function validateGridCreateArgs(args, operation) {
+  if (Object.hasOwn(args, "strokeDashMap")) normalizeGuideDashMap(args.strokeDashMap);
   validateOptionObject(args, GRID_OPTIONS, operation);
   if (Array.isArray(args.values)) {
     validateGeneratedItemLimit(args.values.length, "Grid value count");
@@ -75,20 +73,24 @@ export function validateGridCreateArgs(args, operation) {
   if (Object.hasOwn(args, "values") && (
     !Array.isArray(args.values) ||
     args.values.length === 0 ||
-    !args.values.every(Number.isFinite)
+    !args.values.every(isNominalValue)
   )) {
-    throw new TypeError("Grid values must be a non-empty finite number array.");
+    throw new TypeError("Grid values must be a non-empty finite number array or nominal category array; continuous grids require finite numbers.");
   }
+  if (Object.hasOwn(args, "alongOffset") && !Number.isFinite(args.alongOffset)) throw new TypeError("Grid alongOffset must be a finite number.");
   if (Object.hasOwn(args, "color")) {
     validateNonEmptyString(args.color, "Grid color");
   }
   if (Object.hasOwn(args, "lineWidth")) {
     validateNonNegativeFinite(args.lineWidth, "Grid lineWidth");
   }
+  if (Object.hasOwn(args, "bandPosition") && !["center", "boundary"].includes(args.bandPosition)) throw new TypeError("Grid bandPosition must be center or boundary.");
+  if (Object.hasOwn(args, "zIndex") && !Number.isFinite(args.zIndex)) throw new TypeError("Grid zIndex must be a finite number.");
   if (Object.hasOwn(args, "strokeDash")) validateStrokeDash(args.strokeDash);
 }
 
 export function validateGridEditArgs(args, operation) {
+  if (Object.hasOwn(args, "strokeDashMap")) normalizeGuideDashMap(args.strokeDashMap);
   validateOptionObject(args, GRID_EDIT_OPTIONS, operation, {
     allowEmpty: false
   });
@@ -109,18 +111,21 @@ export function validateGridEditArgs(args, operation) {
   if (Object.hasOwn(args, "values") && args.values !== "auto" && (
     !Array.isArray(args.values) ||
     args.values.length === 0 ||
-    !args.values.every(Number.isFinite)
+    !args.values.every(isNominalValue)
   )) {
     throw new TypeError(
       'Grid values must be "auto" or a non-empty finite number array.'
     );
   }
+  if (Object.hasOwn(args, "alongOffset") && !Number.isFinite(args.alongOffset)) throw new TypeError("Grid alongOffset must be a finite number.");
   if (Object.hasOwn(args, "color")) {
     validateNonEmptyString(args.color, "Grid color");
   }
   if (Object.hasOwn(args, "lineWidth")) {
     validateNonNegativeFinite(args.lineWidth, "Grid lineWidth");
   }
+  if (Object.hasOwn(args, "bandPosition") && !["center", "boundary"].includes(args.bandPosition)) throw new TypeError("Grid bandPosition must be center or boundary.");
+  if (Object.hasOwn(args, "zIndex") && !Number.isFinite(args.zIndex)) throw new TypeError("Grid zIndex must be a finite number.");
   if (Object.hasOwn(args, "strokeDash")) validateStrokeDash(args.strokeDash);
 }
 
@@ -129,44 +134,30 @@ export function resolveGridResources(program, direction, args) {
   let layers = program.semanticSpec.layers.filter(
     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
-    ? undefined
-    : validateUserId(args.coordinate, "Grid coordinate id");
-  const requestedScale = args.scale === undefined
-    ? undefined
-    : validateUserId(args.scale, "Grid scale id");
-  if (requestedCoordinate !== undefined) {
-    layers = layers.filter(layer => layer.coordinate === requestedCoordinate);
-  }
-  if (requestedScale !== undefined) {
-    layers = layers.filter(layer => layer.encoding[channel].scale === requestedScale);
-  }
-  if (layers.length === 0) throw new Error(`${direction} grid found no matching encoded layers.`);
-  const coordinateIds = [...new Set(layers.map(layer => layer.coordinate).filter(Boolean))];
-  if (layers.some(layer => layer.coordinate === undefined)) {
-    throw new Error(`${direction} grid requires a stored coordinate.`);
-  }
-  if (coordinateIds.length === 0) throw new Error(`Unknown grid coordinate "${requestedCoordinate}".`);
-  if (coordinateIds.length > 1) {
-    throw new Error(`${direction} grid found multiple coordinates; provide coordinate explicitly.`);
-  }
+  const requestedCoordinate = args.coordinate === undefined ? undefined : validateUserId(args.coordinate, "Grid coordinate id");
+  const requestedScale = args.scale === undefined ? undefined : validateUserId(args.scale, "Grid scale id");
+  const axes = cartesianAxisOwners(program).filter(owner => owner.channel === channel && owner.scale !== undefined && owner.coordinate !== undefined);
+  const bindings = [...layers.map(layer => ({ coordinate: layer.coordinate, scale: layer.encoding[channel].scale })),
+    ...axes.map(owner => ({ coordinate: owner.coordinate, scale: owner.scale }))]
+    .filter(binding => (requestedCoordinate === undefined || binding.coordinate === requestedCoordinate) &&
+      (requestedScale === undefined || binding.scale === requestedScale));
+  if (bindings.length === 0) throw new Error(layers.length === 0
+    ? `${direction} grid requires a ${channel} encoding or bound Cartesian axis.`
+    : `${direction} grid found no matching encoded layers.`);
+  if (bindings.some(binding => binding.coordinate === undefined)) throw new Error(`${direction} grid requires a stored coordinate.`);
+  const coordinateIds = [...new Set(bindings.map(binding => binding.coordinate))];
+  if (coordinateIds.length > 1) throw new Error(`${direction} grid found multiple coordinates; provide coordinate explicitly.`);
   const coordinate = requestedCoordinate ?? coordinateIds[0];
-  const definition = findCoordinate(program, coordinate);
-  if (definition?.type !== "cartesian") {
-    throw new Error(`${direction} grid requires a Cartesian coordinate.`);
-  }
-  const scaleIds = [...new Set(layers.map(layer => layer.encoding[channel].scale))];
-  if (scaleIds.length === 0) throw new Error(`Unknown grid scale "${requestedScale}".`);
-  if (scaleIds.length > 1) {
-    throw new Error(`${direction} grid found multiple ${channel} scales; provide scale explicitly.`);
-  }
+  if (findCoordinate(program, coordinate)?.type !== "cartesian") throw new Error(`${direction} grid requires a Cartesian coordinate.`);
+  const scaleIds = [...new Set(bindings.map(binding => binding.scale))];
+  if (scaleIds.length > 1) throw new Error(`${direction} grid found multiple ${channel} scales; provide scale explicitly.`);
   const scale = requestedScale ?? scaleIds[0];
+  layers = layers.filter(layer => layer.coordinate === coordinate && layer.encoding[channel].scale === scale);
   if (
-    !["linear", "time"].includes(program.resolvedScales[scale]?.type) &&
+    !["linear", "time", "band", "point"].includes(program.resolvedScales[scale]?.type) &&
     !isTransformedScaleType(program.resolvedScales[scale]?.type)
   ) {
-    throw new Error(`${direction} grid requires resolved continuous scale "${scale}".`);
+    throw new Error(`${direction} grid requires resolved continuous, band or point scale "${scale}".`);
   }
   const sourceIds = new Set(layers.map(layer => layer.id));
   const relatedLayers = [...layers, ...program.semanticSpec.layers.filter(layer =>
@@ -176,9 +167,15 @@ export function resolveGridResources(program, direction, args) {
     const leader = program.materializationConfigs.labelLayouts?.[layer.id]?.leaderId;
     return leader === undefined ? [layer.id] : [leader, layer.id];
   }));
+  if (related.size === 0) {
+    for (const owner of axes.filter(owner => owner.scale === scale && owner.coordinate === coordinate)) {
+      for (const id of axisGraphicIds(channel, owner.id)) if (program.graphicSpec.objects[id] !== undefined) related.add(id);
+    }
+  }
   let before;
+  let after;
   walkGraphicDrawOrder(program.graphicSpec, ({ id }) => {
-    if (before === undefined && related.has(id)) before = id;
+    if (related.has(id)) { if (before === undefined) before = id; after = id; }
   });
   if (before === undefined) throw new Error(`${direction} grid requires related mark graphics.`);
   const owner = findGraphicParent(program.graphicSpec, before);
@@ -187,6 +184,7 @@ export function resolveGridResources(program, direction, args) {
     coordinate,
     scale,
     before,
+    after,
     ...(owner?.kind === "parent" ? { parent: owner.id } : {})
   };
 }
@@ -199,8 +197,11 @@ export function resolveGridConfig(program, direction, args, resources) {
     : Object.hasOwn(args, "count")
       ? { mode: "count", count: args.count }
       : inferGridTickConfig(program, resources.channel, resources.scale);
-  return {
+  return patchGuideDash({
     direction,
+    ...(args.bandPosition === undefined ? {} : { bandPosition: args.bandPosition }),
+    ...(args.zIndex === undefined ? {} : { zIndex: args.zIndex }),
+    ...(args.alongOffset === undefined ? {} : { alongOffset: args.alongOffset }),
     scale: resources.scale,
     coordinate: resources.coordinate,
     ...explicit,
@@ -208,7 +209,7 @@ export function resolveGridConfig(program, direction, args, resources) {
     color: args.color ?? DEFAULT_STYLE.color,
     lineWidth: args.lineWidth ?? DEFAULT_STYLE.lineWidth,
     strokeDash: args.strokeDash ?? DEFAULT_STYLE.strokeDash
-  };
+  }, args);
 }
 
 export function refreshGridConfig(program, config) {
@@ -243,7 +244,7 @@ export function editGridConfig(previous, args) {
   } else if (args.values === "auto") {
     config.inferredValues = true;
   }
-  return config;
+  return patchGuideDash(config, args);
 }
 
 export function resolveGridGeometry(program, config) {
@@ -255,23 +256,66 @@ export function resolveGridGeometry(program, config) {
     channel
   });
   if ((
-    !["linear", "time"].includes(scale?.type) &&
+    !["linear", "time", "band", "point"].includes(scale?.type) &&
     !isTransformedScaleType(scale?.type)
   ) || bounds === undefined) {
-    throw new Error("Grid materialization requires a continuous scale and Canvas bounds.");
+    throw new Error("Grid materialization requires a continuous, band or point scale and Canvas bounds.");
+  }
+  if (config.bandPosition !== undefined && scale.type !== "band") throw new Error("Grid bandPosition requires a band scale.");
+  if (["band", "point"].includes(scale.type)) {
+    if (config.mode === "count") throw new Error("Categorical grid values cannot use count.");
+    const values = valuesFromTickConfig(program, config);
+    if (!values.every(value => scale.domain.includes(value))) throw new RangeError("Grid values must be inside the scale domain.");
+    const centers = mapOrdinalPositionValues(values, scale);
+    const direction = scale.range[1] >= scale.range[0] ? 1 : -1;
+    const owners = new Map();
+    if (config.bandPosition === "boundary") {
+      centers.forEach((center, index) => {
+        for (const edge of [center - direction * scale.bandwidth / 2, center + direction * scale.bandwidth / 2]) {
+          if (!owners.has(edge)) owners.set(edge, values[index]);
+        }
+      });
+    }
+    const positions = config.bandPosition === "boundary"
+      ? [...owners.keys()].sort((a, b) => direction * (a - b)) : centers;
+    validateGeneratedItemLimit(positions.length, "Grid value count");
+    return {
+      ...resolveGridLineGeometry({ direction: config.direction, values: positions, positions: positions.map(value => value + (config.alongOffset ?? 0)), bounds }),
+      strokeDash: resolveGuideDashes(config.bandPosition === "boundary" ? positions.map(value => owners.get(value)) : values, config)
+    };
   }
   const values = valuesFromTickConfig(program, config);
   validateGeneratedItemLimit(values.length, "Grid value count");
   const low = Math.min(...scale.domain);
   const high = Math.max(...scale.domain);
-  if (!values.every(value => value >= low && value <= high)) {
+  if (!values.every(value => Number.isFinite(value) && value >= low && value <= high)) {
     throw new RangeError("Grid values must be inside the scale domain.");
   }
   const positions = mapContinuousScaleValues(values, scale);
-  return resolveGridLineGeometry({
+  return { ...resolveGridLineGeometry({
     direction: config.direction,
     values,
-    positions,
+    positions: positions.map(value => value + (config.alongOffset ?? 0)),
     bounds
-  });
+  }), strokeDash: resolveGuideDashes(values, config) };
+}
+
+
+export function resolveGridPlacement(program, config) {
+  const resources = resolveGridResources(program, config.direction, { scale: config.scale, coordinate: config.coordinate });
+  const id = gridNames(config.direction).graphic;
+  const siblings = graphicSiblings(program.graphicSpec, resources.before);
+  const rank = direction => [program.guideConfigs.grid?.[direction]?.zIndex ?? 0, direction === "horizontal" ? 0 : 1];
+  const ownRank = [config.zIndex ?? 0, config.direction === "horizontal" ? 0 : 1];
+  const compare = (a, b) => a[0] - b[0] || a[1] - b[1];
+  const neighbors = ["horizontal", "vertical"].filter(direction => {
+    const other = gridNames(direction).graphic;
+    return other !== id && siblings.includes(other) && ((rank(direction)[0] > 0) === (ownRank[0] > 0));
+  }).sort((a, b) => compare(rank(a), rank(b)));
+  const greater = neighbors.find(direction => compare(rank(direction), ownRank) > 0);
+  const lower = neighbors.filter(direction => compare(rank(direction), ownRank) < 0).at(-1);
+  return {
+    ...(resources.parent === undefined ? {} : { parent: resources.parent }),
+    ...(greater ? { before: gridNames(greater).graphic } : lower ? { after: gridNames(lower).graphic } : ownRank[0] > 0 ? { after: resources.after } : { before: resources.before })
+  };
 }

package/src/actions/guides/legends/blocks.js

@@ -1,3 +1,7 @@
+import { editFacetParentLegend } from "../../../materialization/facetGuides/edit.js";
+
+import {patchLegendClipHeight, validateLegendClip} from "../../../grammar/legendClip.js";
+import { LEGEND_POSITIONS } from "../../../core/vocabulary.js";
 import { action } from "../../../core/action.js";
 import { isPlainObject } from "../../../core/immutable.js";
 import {
@@ -23,11 +27,11 @@ import {
   resolveLegendBlock
 } from "./target.js";
 import { validateFontWeight } from "./categorical/validation.js";
-import { normalizeDisplayLabelMap } from "../../../grammar/displayLabels.js";
+import { normalizeDisplayLabelMap, normalizeNumericDisplayLabelMap } from "../../../grammar/displayLabels.js";
 
 const OPTIONS = Object.freeze([
   "target", "channel", "title", "values", "count", "order", "gap", "text", "symbol",
-  "labelMap"
+  "labelMap", "position", "clipHeight"
 ]);
 const TEXT_OPTIONS = Object.freeze(["fontSize", "fontFamily", "fontWeight", "color"]);
 const SYMBOL_OPTIONS = Object.freeze(["size", "fill", "stroke", "strokeWidth", "opacity"]);
@@ -63,10 +67,12 @@ function categoricalSupports(config, property) {
 
 function validateSymbolSupport(descriptor, property) {
   const { channels, family, kind, config } = descriptor;
+  if(kind === "colorSize" && ["fill","size"].includes(property)) throw new Error("Color-size symbols cannot override mapped fill or size.");
   if (family === "gradient") {
     throw new Error(`editLegendBlock symbol.${property} is unsupported for gradient blocks.`);
   }
   if (family === "categorical") {
+    if (property === "size" && channels.includes("size")) throw new Error("Combined size-shape block cannot override mapped size.");
     if (property === "fill" && channels.includes("color")) {
       throw new Error("editLegendBlock symbol.fill conflicts with the color mapping.");
     }
@@ -78,6 +84,7 @@ function validateSymbolSupport(descriptor, property) {
     }
     return;
   }
+  if (kind === "gradient" && property === "fill") throw new Error("editLegendBlock symbol.fill conflicts with the color mapping.");
   if (kind === "size" && property === "size") {
     throw new Error("editLegendBlock symbol.size conflicts with the size mapping.");
   }
@@ -124,13 +131,21 @@ function normalizeSymbolPatch(value, descriptor) {
   return { ...value };
 }
 
+function normalizeBlockLabelMap(descriptor, map) {
+  if (["size","colorSize"].includes(descriptor.kind) && descriptor.family === "sampled") {
+    return normalizeNumericDisplayLabelMap(map, "editLegendBlock labelMap");
+  }
+  if (descriptor.family !== "categorical") {
+    throw new Error("editLegendBlock labelMap requires a categorical or continuous size block.");
+  }
+  return normalizeDisplayLabelMap(map, "editLegendBlock labelMap");
+}
+
 export function validateLegendBlockOverride(descriptor, override) {
+  if (override.position !== undefined && !LEGEND_POSITIONS.includes(override.position)) throw new Error("Invalid local legend position.");
   if (override.symbol !== undefined) normalizeSymbolPatch(override.symbol, descriptor);
   if (override.labelMap !== undefined) {
-    if (descriptor.family !== "categorical") {
-      throw new Error("editLegendBlock labelMap requires a categorical block.");
-    }
-    normalizeDisplayLabelMap(override.labelMap, "editLegendBlock labelMap");
+    normalizeBlockLabelMap(descriptor, override.labelMap);
   }
   return override;
 }
@@ -175,6 +190,8 @@ export function patchLegendBlockOverride(config, key, patch) {
     entry = withoutEmptyNested(entry, "symbol", patch.symbol);
   }
   if (Object.hasOwn(patch, "labelMap")) entry.labelMap = patch.labelMap;
+  if (Object.hasOwn(patch, "position")) entry.position = patch.position;
+  if (patch.removePosition === true) delete entry.position;
   if (patch.removeLabelMap === true) delete entry.labelMap;
   const blockOverrides = { ...(config.blockOverrides ?? {}) };
   if (Object.keys(entry).length === 0) delete blockOverrides[key];
@@ -207,7 +224,7 @@ function applyCategoricalSymbol(symbol, patch) {
 }
 
 export function resolveEffectiveLegendBlockConfig(program, kind, config) {
-  const channels = kind === "series" || kind === "color" || kind === "stroke"
+  const channels = kind === "colorSize" ? ["color","size"] : kind === "series" || kind === "color" || kind === "stroke"
     ? config.channels
     : [{ size: "size", opacity: "opacity", strokeWidth: "strokeWidth",
       gradient: "color", interval: "color", strokeGradient: "stroke",
@@ -232,6 +249,7 @@ export function resolveEffectiveLegendBlockConfig(program, kind, config) {
       : {})
   };
   if (override.symbol === undefined) return effective;
+  if(kind === "colorSize") return {...effective,symbol:{...config.symbol,...override.symbol}};
   if (["series", "color", "stroke"].includes(kind)) {
     return {
       ...effective,
@@ -239,7 +257,7 @@ export function resolveEffectiveLegendBlockConfig(program, kind, config) {
       blockSymbol: override.symbol
     };
   }
-  if (kind === "opacity") {
+  if (kind === "opacity" || kind === "gradient" && config.representation === "symbols") {
     return {
       ...effective,
       symbol: {
@@ -289,6 +307,8 @@ export function reconcileLegendBlockTitleGraphic(program, kind, visible) {
 }
 
 const SPECIALIZED_SYMBOLS = Object.freeze({
+  colorSize: Object.freeze({id:"colorSizeLegendSymbols",type:"circle"}),
+  gradient: Object.freeze({ id: "colorGradientSymbols", type: "circle" }),
   size: Object.freeze({ id: "sizeLegendSymbols", type: "circle" }),
   opacity: Object.freeze({ id: "opacityLegendSymbols", type: "circle" }),
   strokeWidth: Object.freeze({ id: "strokeWidthLegendSymbols", type: "line" }),
@@ -324,6 +344,13 @@ function recreateSymbolGraphics(program, descriptor) {
 
 function normalizeBlockPatch(args, descriptor) {
   const patch = {};
+  if (Object.hasOwn(args, "position")) {
+    if (args.position === "inherit") patch.removePosition = true;
+    else {
+      if (!LEGEND_POSITIONS.includes(args.position)) throw new Error("Legend block position requires an anchor or inherit.");
+      patch.position = args.position;
+    }
+  }
   if (Object.hasOwn(args, "title")) {
     if (typeof args.title !== "string") {
       throw new TypeError("editLegendBlock title must be a string.");
@@ -339,26 +366,21 @@ function normalizeBlockPatch(args, descriptor) {
     patch.symbol = normalizeSymbolPatch(args.symbol, descriptor);
   }
   if (Object.hasOwn(args, "labelMap")) {
-    if (descriptor.family !== "categorical") {
-      throw new Error("editLegendBlock labelMap requires a categorical block.");
-    }
+    // Validate eligibility even for a reset, without introducing an empty map owner.
+    const map = normalizeBlockLabelMap(descriptor, args.labelMap === "auto" ? [] : args.labelMap);
     if (args.labelMap === "auto") patch.removeLabelMap = true;
-    else {
-      patch.labelMap = normalizeDisplayLabelMap(
-        args.labelMap,
-        "editLegendBlock labelMap"
-      );
-    }
+    else patch.labelMap = map;
   }
   return patch;
 }
 
 export const editLegendBlock = /* @__PURE__ */ action(
   {
-    op: "editLegendBlock",
+    op: "editLegendBlock", scope: "any",
     description: "Edit one logical legend block selected by channel."
   },
   withGuideLayoutValidation(function (args = {}) {
+    if (this.compositionSpec !== undefined) return editFacetParentLegend(this, "editLegendBlock", args);
     validateOptionObject(args, OPTIONS, "editLegendBlock");
     if (!Object.hasOwn(args, "target") || typeof args.target !== "string") {
       throw new TypeError("editLegendBlock target must be an explicit legend target id.");
@@ -375,7 +397,9 @@ export const editLegendBlock = /* @__PURE__ */ action(
       throw new Error("editLegendBlock values and count require a sampled legend block.");
     }
     const patch = normalizeBlockPatch(args, descriptor);
-    let config = descriptor.config;
+    let config = Object.hasOwn(args, "clipHeight")
+      ? patchLegendClipHeight(descriptor.config, args.clipHeight) : descriptor.config;
+    validateLegendClip(descriptor.kind, config);
     const blockOverrides = patchLegendBlockOverride(config, descriptor.key, patch);
     if (blockOverrides === undefined) {
       const { blockOverrides: _removed, ...rest } = config;
@@ -421,6 +445,8 @@ export const editLegendBlock = /* @__PURE__ */ action(
     }
     next = reconcileLegendBlockTitleGraphic(next, descriptor.kind,
       effective.titleVisible !== false);
-    return next.rematerializeLegend();
+    return Object.hasOwn(args, "position")
+      ? next.editLegend({target: args.target, channel: args.channel, position: args.position})
+      : next.rematerializeLegend();
   })
 );