ggaction 0.0.16 → 0.0.18

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

@@ -1,3 +1,6 @@
+import { materializeTextLines } from "../../../materialization/textLines.js";
+import { axisThemeTypography } from "../../theme/state.js";
+import { canvasOverflowError } from "../../../layout/canvas.js";
 import { isSourceOwnedText } from "../../../grammar/text.js";
 import { withGuideLayoutValidation } from "../../../materialization/guides/layout.js";
 import { action } from "../../../core/action.js";
@@ -7,13 +10,13 @@ import {
   validateNonEmptyString,
   validateNonNegativeFinite
 } from "../../../core/validation.js";
-import { resolveGuideCoordinateBounds } from "../../../materialization/coordinateBounds.js";
+import { axisScaleBindings, resolveGuideCoordinateBounds } from "../../../materialization/coordinateBounds.js";
 import {
   isTransformedScaleType,
   mapContinuousScaleValues,
   mapOrdinalPositionValues
 } from "../../../grammar/scales/index.js";
-import { DEFAULT_COLORS, DEFAULT_FONT_FAMILY } from
+import { AXIS_TITLE_FONT_SIZE, DEFAULT_COLORS, DEFAULT_FONT_FAMILY } from
   "../../../theme/defaults.js";
 import { findDataset } from "../../../selectors/datasets.js";
 import { formatAggregateTitle } from "../../../grammar/aggregate.js";
@@ -28,6 +31,7 @@ import { findCanvasGraphic, resolvePlotGraphicPlacement } from
   "../../../materialization/graphicHierarchy.js";
 import {
   resolveTextBounds,
+  resolveTextLines,
   textBoundsFitCanvas,
   textBoundsIntersect
 } from "../../../core/textMetrics.js";
@@ -36,10 +40,19 @@ import { resolveConcreteGraphicBounds } from
 import { validateAxisTextStyle } from "./labels.js";
 import { resolveRotation } from "../../../grammar/rotation.js";
 
+function titleLines(text, config) {
+  if (!/[\r\n]/u.test(text)) return undefined;
+  const lines = resolveTextLines(text, {
+    fontSize: config.fontSize, align: "center", baseline: "middle", blockAlign: "middle"
+  });
+  return lines.length > 1 ? lines : undefined;
+}
+
 function titleBounds(geometry, config, text, profile) {
   return resolveTextBounds({
     ...geometry,
     text,
+    lines: titleLines(text, config),
     fontSize: config.fontSize,
     fontFamily: config.fontFamily,
     fontWeight: config.fontWeight,
@@ -49,6 +62,34 @@ function titleBounds(geometry, config, text, profile) {
   }, profile);
 }
 
+function resolveTitleAlong(scale, config) {
+  const discrete = ["ordinal", "band", "point"].includes(scale?.type);
+  let along;
+  if (config.at === "center") {
+    along = finiteMidpoint(scale.range[0], scale.range[1]);
+  } else if (config.at === "start" || config.at === "end") {
+    along = scale.range[config.at === "start" ? 0 : 1];
+  } else {
+    if (discrete) {
+      if (!scale.domain.includes(config.at)) throw new RangeError("Axis title at value must be inside the scale domain.");
+      along = mapOrdinalPositionValues([config.at], scale)[0];
+    } else {
+      const low = Math.min(...scale.domain), high = Math.max(...scale.domain);
+      if (config.at < low || config.at > high) throw new RangeError("Axis title at value must be inside the scale domain.");
+      along = mapContinuousScaleValues([config.at], scale)[0];
+    }
+  }
+  return along;
+}
+
+function axisLabelBounds(program, channel) {
+  const id = `${channel}AxisLabels`, labels = program.graphicSpec.objects[id];
+  const bounds = target => resolveConcreteGraphicBounds(
+    program.graphicSpec, target, program.materializationConfigs.textMetrics
+  );
+  return labels?.items?.map(item => bounds(item.id)) ?? (labels ? [bounds(id)] : []);
+}
+
 function inferredTitleOffset(program, channel, config) {
   const plot = resolveGuideCoordinateBounds(program, {
     coordinate: program.semanticSpec.guides.axis?.[channel]?.coordinate,
@@ -78,7 +119,26 @@ function inferredTitleOffset(program, channel, config) {
   const available = positive
     ? canvas[horizontal ? "height" : "width"] - bounds[far]
     : bounds[near];
-  return preferred + Math.min(available, Math.max(0, needed));
+  // Font ink can extend beyond the one-em layout box, especially after
+  // rotating a middle-baseline title. Keep inferred edge-clamped placement
+  // inside the Canvas; explicit offsets retain their exact geometry.
+  const inkClearance = channel === "y" &&
+    Math.abs(Math.cos(config.rotation)) < 1e-10
+    ? config.fontSize / 4 : 0;
+  if (program.materializationConfigs.canvas?.plot !== undefined) {
+    return preferred + Math.max(0, needed);
+  }
+  const legacyAdjustment = Math.min(available, Math.max(0, needed));
+  if (inkClearance === 0) return preferred + legacyAdjustment;
+  const adjustment = Math.min(available - inkClearance, Math.max(0, needed));
+  const candidateBounds = titleBounds(resolveAxisTitleGeometry({
+    bounds: plot, channel, position: config.position,
+    along: resolveTitleAlong(program.resolvedScales[config.scale], config),
+    offset: preferred + adjustment
+  }), config, program.semanticSpec.guides.axis?.[channel]?.title ?? "", program.materializationConfigs.textMetrics);
+  // Optional ink reserve must not introduce a label collision.
+  return preferred + (axisLabelBounds(program, channel).some(label => label && textBoundsIntersect(candidateBounds, label))
+    ? legacyAdjustment : adjustment);
 }
 
 const CREATE_OPTIONS = [
@@ -88,7 +148,7 @@ const CREATE_OPTIONS = [
 const EDIT_OPTIONS = CREATE_OPTIONS.filter(key => key !== "scale");
 const DEFAULTS = {
   color: DEFAULT_COLORS.text,
-  fontSize: 13,
+  fontSize: AXIS_TITLE_FONT_SIZE,
   fontFamily: DEFAULT_FONT_FAMILY,
   fontWeight: 600
 };
@@ -149,6 +209,7 @@ export function inferAxisTitleText(program, channel, scaleId) {
     }
   }
   if (primaryTitles.size === 1) return [...primaryTitles][0];
+  if (titles.size === 0 && axisScaleBindings(program, scaleId).some(binding => binding.channel === channel)) return scaleId;
   if (titles.size !== 1) throw new Error(`Axis title text cannot be inferred for scale "${scaleId}".`);
   return [...titles][0];
 }
@@ -160,26 +221,11 @@ function resolveGeometry(program, channel, config) {
     scale: config.scale,
     channel
   });
-  const discrete = ["ordinal", "band", "point"].includes(scale?.type);
   if ((
     !["linear", "time", "ordinal", "band", "point"].includes(scale?.type) &&
     !isTransformedScaleType(scale?.type)
   ) || !bounds) throw new Error("Axis title requires a supported resolved scale and Canvas bounds.");
-  let along;
-  if (config.at === "center") {
-    along = finiteMidpoint(scale.range[0], scale.range[1]);
-  } else if (config.at === "start" || config.at === "end") {
-    along = scale.range[config.at === "start" ? 0 : 1];
-  } else {
-    if (discrete) {
-      if (!scale.domain.includes(config.at)) throw new RangeError("Axis title at value must be inside the scale domain.");
-      along = mapOrdinalPositionValues([config.at], scale)[0];
-    } else {
-      const low = Math.min(...scale.domain), high = Math.max(...scale.domain);
-      if (config.at < low || config.at > high) throw new RangeError("Axis title at value must be inside the scale domain.");
-      along = mapContinuousScaleValues([config.at], scale)[0];
-    }
-  }
+  const along = resolveTitleAlong(scale, config);
   const geometry = resolveAxisTitleGeometry({
     bounds,
     channel,
@@ -194,12 +240,10 @@ function resolveGeometry(program, channel, config) {
   , program.materializationConfigs.textMetrics);
   const canvas = findCanvasGraphic(program)?.properties;
   if (!canvas || !textBoundsFitCanvas(resolvedBounds, canvas)) {
-    throw new Error(`The ${channel}-axis title does not fit the Canvas margin.`);
+    throw canvasOverflowError(`The ${channel}-axis title does not fit the Canvas margin.`, [resolvedBounds], canvas);
   }
-  const labelsBounds = program.graphicSpec.objects[`${channel}AxisLabels`]
-    ? resolveConcreteGraphicBounds(program.graphicSpec, `${channel}AxisLabels`, program.materializationConfigs.textMetrics)
-    : undefined;
-  if (labelsBounds && textBoundsIntersect(resolvedBounds, labelsBounds)) {
+  const labelBounds = axisLabelBounds(program, channel);
+  if (labelBounds.some(bounds => bounds && textBoundsIntersect(resolvedBounds, bounds))) {
     throw new Error(`The ${channel}-axis title overlaps the axis labels.`);
   }
   return geometry;
@@ -265,7 +309,7 @@ function makeEdit(channel) {
       rotation: config.rotation
     };
     for (const [property, value] of Object.entries(properties)) next = next.editGraphics({ target: operation.graphic, property, value });
-    return next;
+    return materializeTextLines(next, operation.graphic, titleLines(resolvedText, config));
   }));
 }
 
@@ -309,6 +353,7 @@ function makeCreate(channel) {
       fontSize: DEFAULTS.fontSize,
       fontFamily: DEFAULTS.fontFamily,
       fontWeight: DEFAULTS.fontWeight,
+      ...axisThemeTypography(this.materializationConfigs.theme, "title"),
       ...appearance
     };
     let next = this

package/src/actions/guides/basic.js

@@ -1,3 +1,4 @@
+import { registerStrokeColorLegendActions } from "./legends/continuous/stroke.js";
 import { registerBasicCartesianAxisActions } from "./axes/index.js";
 import { registerGuideCollectionActions } from "./guides.js";
 import { registerBasicGridActions } from "./grids/index.js";
@@ -15,6 +16,7 @@ export function registerBasicGuideActions(ProgramClass) {
   registerBasicCategoricalLegendActions(ProgramClass);
   registerGradientLegendActions(ProgramClass);
   registerIntervalLegendActions(ProgramClass);
+  registerStrokeColorLegendActions(ProgramClass);
   registerSizeLegendActions(ProgramClass);
   registerBasicGridActions(ProgramClass);
   registerGuideCollectionActions(ProgramClass);

package/src/actions/guides/facadeLegend.js

@@ -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") {
+    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

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

@@ -1,3 +1,4 @@
+import { isNominalValue } from "../../../grammar/scales/fields.js";
 import { isSourceOwnedText } from "../../../grammar/text.js";
 import { validateUserId } from "../../../core/identifiers.js";
 import {
@@ -8,6 +9,7 @@ import {
 } from "../../../core/validation.js";
 import {
   isTransformedScaleType,
+  mapOrdinalPositionValues,
   mapContinuousScaleValues
 } from "../../../grammar/scales/index.js";
 import { resolveGuideCoordinateBounds } from "../../../materialization/coordinateBounds.js";
@@ -20,14 +22,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", "zIndex", "bandPosition", "alongOffset"
 ]);
 const GRID_EDIT_OPTIONS = Object.freeze([
-  "count", "values", "color", "lineWidth", "strokeDash"
+  "count", "values", "color", "lineWidth", "strokeDash", "zIndex", "bandPosition", "alongOffset"
 ]);
 const DEFAULT_STYLE = Object.freeze({
   color: DEFAULT_COLORS.grid,
@@ -75,16 +78,19 @@ 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);
 }
 
@@ -109,18 +115,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);
 }
 
@@ -163,10 +172,10 @@ export function resolveGridResources(program, direction, args) {
   }
   const scale = requestedScale ?? scaleIds[0];
   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 =>
@@ -177,8 +186,9 @@ export function resolveGridResources(program, direction, args) {
     return leader === undefined ? [layer.id] : [leader, layer.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 +197,7 @@ export function resolveGridResources(program, direction, args) {
     coordinate,
     scale,
     before,
+    after,
     ...(owner?.kind === "parent" ? { parent: owner.id } : {})
   };
 }
@@ -201,6 +212,9 @@ export function resolveGridConfig(program, direction, args, resources) {
       : inferGridTickConfig(program, resources.channel, resources.scale);
   return {
     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,
@@ -255,23 +269,56 @@ 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 positions = config.bandPosition === "boundary"
+      ? [...new Set(centers.flatMap(center => [center - direction * scale.bandwidth / 2, center + direction * scale.bandwidth / 2]))].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 });
   }
   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({
     direction: config.direction,
     values,
-    positions,
+    positions: positions.map(value => value + (config.alongOffset ?? 0)),
     bounds
   });
 }
+
+
+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

@@ -78,6 +78,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.");
   }
@@ -239,7 +240,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 +290,7 @@ export function reconcileLegendBlockTitleGraphic(program, kind, visible) {
 }
 
 const SPECIALIZED_SYMBOLS = Object.freeze({
+  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" }),

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

@@ -1,3 +1,8 @@
+import { recordLegendOffsetIntent } from "../group.js";
+import { prepareLegendGroup, creationLegendTarget, validateLegendGroupOptions } from "../group.js";
+import { PLOT_LEGEND_POSITIONS } from "../../../../layout/legend.js";
+import { normalizeInitialLegendTitle } from "../continuous/common.js";
+import { isContinuousColorScaleType } from "../../../../grammar/scales/types.js";
 import { withGuideLayoutValidation } from "../../../../materialization/guides/layout.js";
 import { sameGuideValue } from "../../reuse.js";
 import { normalizeLegendOrder } from "../../../../grammar/categoryOrder.js";
@@ -17,8 +22,7 @@ import { legendResourcePolicies } from
   "../../../../materialization/guides/resources.js";
 import {
   hasHorizontalLegendLane,
-  hasLegendLane,
-  hasMultiSideLegendLane
+  hasLegendLane
 } from "../lane.js";
 import {
   resolveCurrentDefinition,
@@ -33,7 +37,8 @@ import {
 } from "../blocks.js";
 
 function finishLegend(program) {
-  return hasLegendLane(program) ? program.rematerializeLegend() : program;
+  return hasLegendLane(program) || Object.keys(program.guideConfigs.legendGroups ?? {}).length > 0
+    ? program.rematerializeLegend() : program;
 }
 
 function requestedCandidate(program, target, candidates) {
@@ -162,9 +167,6 @@ export const rematerializeLegend = /* @__PURE__ */ action(
         next = next[policy.rematerializeOp]();
       }
     }
-    if (hasMultiSideLegendLane(next)) {
-      next = next.rematerializeSideLegendLane();
-    }
     if (hasHorizontalLegendLane(next)) {
       next = next.rematerializeHorizontalLegendLane();
     }
@@ -178,7 +180,7 @@ export function resolveCategoricalLegendConfig(program, args = {}) {
     program,
     layer,
     args.channels,
-    args.title,
+    args.title === false ? undefined : args.title,
     args.order === undefined ? undefined : normalizeLegendOrder(args.order)
   );
   const inferredSymbol = args.symbol === undefined || args.symbol === "auto";
@@ -194,7 +196,8 @@ export function resolveCategoricalLegendConfig(program, args = {}) {
   const config = {
     target: layer.id,
     ...definition,
-    inferredTitle: !Object.hasOwn(args, "title"),
+    ...normalizeInitialLegendTitle(args.title, definition.title),
+    inferredTitle: args.title === false || !Object.hasOwn(args, "title"),
     inferredSymbol,
     position: options.position,
     align: options.align,
@@ -207,8 +210,8 @@ export function resolveCategoricalLegendConfig(program, args = {}) {
     titleStyle: options.titleStyle,
     itemGap: options.itemGap,
     layout: options.layout,
-    border: options.border,
-    titleVisible: true
+    ...(options.overflow === undefined ? {} : { overflow: options.overflow }),
+    border: options.border
   };
   return config;
 }
@@ -228,7 +231,7 @@ export const createCategoricalLegend = /* @__PURE__ */ action(
   })
 );
 
-export function resolveLegendCreationPlan(program, args = {}, layers = program.semanticSpec.layers) {
+function resolveRawLegendCreationPlan(program, args = {}, layers = program.semanticSpec.layers) {
   validateOptionObject(args, undefined, "createLegend");
   const candidates = args.target === undefined ? layers : layers.filter(layer => layer.id === args.target);
   const channels = args.channels;
@@ -252,15 +255,23 @@ export function resolveLegendCreationPlan(program, args = {}, layers = program.s
     }
   }
   const continuousColorCandidates = candidates.filter(layer => {
-    const encoding = ["point", "bar", "rect"].includes(layer.mark?.type)
+    const encoding = ["point", "bar", "rect", "text"].includes(layer.mark?.type)
       ? layer.encoding?.color
       : undefined;
     const scale = findSemanticScale(program, encoding?.scale);
-    return scale?.type === "sequential";
+    return isContinuousColorScaleType(scale?.type);
   });
   const continuousColor = requestedCandidate(
     program, args.target, continuousColorCandidates
   );
+  if (args.representation !== undefined && channels !== undefined && channels.length > 1) {
+    if (!continuousColor || !channels.includes("color")) throw new Error("Legend representation requires selected continuous color.");
+    const { representation, values, count, symbol, gradient, ...common } = args;
+    const steps = channels.flatMap(channel => resolveRawLegendCreationPlan(program,
+      channel === "color" ? { ...args, channels: [channel] }
+        : { ...common, channels: [channel] }, layers).steps);
+    return { steps, finish: "always" };
+  }
   if (
     (channels?.length === 1 && channels[0] === "color" && continuousColor) ||
     (channels === undefined && continuousColor)
@@ -268,7 +279,7 @@ export function resolveLegendCreationPlan(program, args = {}, layers = program.s
     return { steps: [{ op: "createGradientLegend", args }], finish: "auto" };
   }
   const intervalColorCandidates = candidates.filter(layer => {
-    const encoding = ["point", "bar", "rect"].includes(layer.mark?.type) ? layer.encoding?.color : undefined;
+    const encoding = ["point", "bar", "rect", "text"].includes(layer.mark?.type) ? layer.encoding?.color : undefined;
     const scale = findSemanticScale(program, encoding?.scale);
     return ["quantize", "quantile", "threshold"].includes(scale?.type);
   });
@@ -281,7 +292,7 @@ export function resolveLegendCreationPlan(program, args = {}, layers = program.s
   }
   const continuousStrokeCandidates = candidates.filter(layer => {
     const scale = findSemanticScale(program, layer.encoding?.stroke?.scale);
-    return scale?.type === "sequential";
+    return isContinuousColorScaleType(scale?.type);
   });
   const continuousStroke = requestedCandidate(
     program,
@@ -365,6 +376,9 @@ export function resolveLegendCreationPlan(program, args = {}, layers = program.s
     if (combined) steps.push({ op: "createSizeLegend", args: {
       target: requestedPoint.id,
       ...(count === undefined ? {} : { count }),
+      ...(categoricalArgs.overflow !== undefined &&
+        findSemanticScale(program, requestedPoint.encoding.size.scale)?.type === "ordinal"
+        ? { overflow: categoricalArgs.overflow } : {}),
       ...(categoricalArgs.labels === undefined ? {} : { labels: {
         ...(categoricalArgs.labels.offset === undefined ? {} : { offset: categoricalArgs.labels.offset }),
         ...(sizeFormat === undefined ? {} : { format: sizeFormat })
@@ -389,11 +403,50 @@ export function resolveLegendCreationPlan(program, args = {}, layers = program.s
   return { steps: [{ op: "createCategoricalLegend", args }], finish: "auto" };
 }
 
+export function resolveLegendCreationPlan(program, args = {}, layers = program.semanticSpec.layers) {
+  validateLegendGroupOptions(args);
+  const { blockLayout: _layout, at: _at, ...raw } = args;
+  const groups = program.guideConfigs.legendGroups ?? {};
+  if (Object.keys(groups).length > 0 && raw.position === undefined) {
+    const target = creationLegendTarget(program, args);
+    const placement = groups[target]?.placement;
+    if (placement?.position !== undefined) {
+      raw.position = placement.position;
+      raw.align = args.align ?? placement.align;
+      raw.offset = args.offset ?? placement.offset;
+    }
+  }
+  if (raw.position === undefined && args.direction === "horizontal" &&
+      (args.at !== undefined || Object.keys(groups).length > 0)) raw.position = "top";
+  const initial = resolveRawLegendCreationPlan(program, raw, layers);
+  const inherited = Object.keys(program.guideConfigs.legendGroups ?? {}).length > 0;
+  const corner = PLOT_LEGEND_POSITIONS.includes(args.position) &&
+    (initial.steps.length > 1 || initial.steps[0]?.op !== "createCategoricalLegend" ||
+      Object.keys(program.guideConfigs.legend ?? {}).length > 0);
+  if (args.blockLayout === undefined && args.at === undefined && !inherited && !corner) return initial;
+  const target = creationLegendTarget(program, args);
+  const first = initial.steps[0];
+  const nativeOffset = program.guideConfigs.legendGroups?.[target] !== undefined ? 30 : first?.op === "createCategoricalLegend"
+    ? resolveCategoricalLegendConfig(program, first.args).offset
+    : first?.op === "createSizeLegend" ? resolveSizeLegendConfig(program, first.args).offset : 30;
+  const prepared = prepareLegendGroup(program, args, target, { creation: true, corner, nativeOffset });
+  if (!prepared.grouped) return initial;
+  if (prepared.options.position === undefined && raw.position !== undefined) {
+    prepared.options.position = raw.position;
+  }
+  return { ...resolveRawLegendCreationPlan(prepared.program, prepared.options, layers),
+    legendGroup: { target, config: prepared.program.guideConfigs.legendGroups[target] } };
+}
+
 export function applyLegendCreationPlan(program, plan) {
   if (plan.steps.length === 0) return program;
-  let next = program;
+  let next = plan.legendGroup === undefined ? program : program._withMaterializationConfig(
+    ["guides", "legendGroups", plan.legendGroup.target], plan.legendGroup.config);
   for (const step of plan.steps) {
     const existingSize = next.guideConfigs.legend?.size;
+    if (plan.combined && existingSize !== undefined && step.op === "createCategoricalLegend") {
+      next = next._withLegendConfig("size", { ...existingSize, inheritPosition: true });
+    }
     // The plan already validated that a retained size block is compatible.
     if (!(plan.combined && step.op === "createSizeLegend" && existingSize !== undefined)) {
       next = next[step.op](step.args);
@@ -406,7 +459,7 @@ export function applyLegendCreationPlan(program, plan) {
 export const createLegend = /* @__PURE__ */ action(
   { op: "createLegend", description: "Create an inferred legend for selected channels." },
   withGuideLayoutValidation(function (args = {}) {
-    return applyLegendCreationPlan(this, resolveLegendCreationPlan(this, args));
+    return recordLegendOffsetIntent(this, applyLegendCreationPlan(this, resolveLegendCreationPlan(this, args)), args, { creation: true });
   })
 );