ggaction 0.0.17 → 0.0.19

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

@@ -1,3 +1,5 @@
+import { selectCartesianAxis } from "../../../selectors/axes.js";
+import { withGuideLayoutValidation } from "../../../materialization/guides/layout.js";
 import { action } from "../../../core/action.js";
 import { validateKeys } from "../../../core/validation.js";
 import { axisGraphicIds } from
@@ -14,16 +16,19 @@ function makeRemoveAxis(channel) {
         ? "Theta"
         : "Radial";
   const operation = `remove${prefix}Axis`;
-  const graphicIds = axisGraphicIds(channel);
   return action(
     {
       op: operation,
       description: `Remove the complete ${channel}-axis resource.`
     },
-    function (args = {}) {
-      validateKeys(args, OPTIONS, operation);
-      const semantic = this.semanticSpec.guides.axis?.[channel];
-      const config = this.guideConfigs.axis?.[channel];
+    withGuideLayoutValidation(function (args = {}) {
+      const cartesian = ["x", "y"].includes(channel);
+      validateKeys(args, cartesian ? [...OPTIONS, "target"] : OPTIONS, operation);
+      const selected = cartesian ? selectCartesianAxis(this, channel, args, { whole: true }) : { id: channel, options: args };
+      const axisId = selected.id; args = selected.options;
+      const graphicIds = axisGraphicIds(channel, axisId);
+      const semantic = this.semanticSpec.guides.axis?.[axisId];
+      const config = this.guideConfigs.axis?.[axisId];
       const hasGraphic = graphicIds.some(
         id => this.graphicSpec.objects[id] !== undefined
       );
@@ -41,7 +46,7 @@ function makeRemoveAxis(channel) {
       let next = semantic === undefined
         ? this
         : this.editSemantic({
-            property: `guide.axis.${channel}`,
+            property: `guide.axis.${axisId}`,
             remove: true
           });
       for (const id of graphicIds) {
@@ -49,8 +54,8 @@ function makeRemoveAxis(channel) {
           next = next.editGraphics({ target: id, remove: true });
         }
       }
-      return next._withoutMaterializationConfig(["guides", "axis", channel]);
-    }
+      return next._withoutMaterializationConfig(["guides", "axis", axisId]);
+    })
   );
 }
 

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

@@ -3,7 +3,7 @@ import { action } from "../../../core/action.js";
 import { isPlainObject } from "../../../core/immutable.js";
 import { validateKeys, validateOptionObject } from "../../../core/validation.js";
 
-const CREATE_OPTIONS = Object.freeze([
+const CREATE_OPTIONS = Object.freeze(["target",
   "scale",
   "position",
   "count",
@@ -11,14 +11,14 @@ const CREATE_OPTIONS = Object.freeze([
   "ticks",
   "labels"
 ]);
-const EDIT_OPTIONS = Object.freeze([
+const EDIT_OPTIONS = Object.freeze(["target",
   "position",
   "count",
   "values",
   "ticks",
   "labels"
 ]);
-const TICK_OPTIONS = Object.freeze(["length", "color", "lineWidth"]);
+const TICK_OPTIONS = Object.freeze(["length", "color", "lineWidth", "alongOffset", "strokeDash", "strokeDashMap"]);
 const LABEL_OPTIONS = Object.freeze([
   "offset",
   "format",
@@ -31,10 +31,14 @@ const LABEL_OPTIONS = Object.freeze([
   "wrap",
   "lineHeight",
   "overlap",
-  "labelMap"
+  "labelMap",
+  "alongOffset",
+  "flush",
+  "colorMap",
+  "align"
 ]);
-const SHARED_CREATE = Object.freeze(["scale", "position", "count", "values"]);
-const SHARED_EDIT = Object.freeze(["position", "count", "values"]);
+const SHARED_CREATE = Object.freeze(["target", "scale", "position", "count", "values"]);
+const SHARED_EDIT = Object.freeze(["target", "position", "count", "values"]);
 
 function validateNested(value, supported, label) {
   if (!isPlainObject(value)) {
@@ -101,7 +105,7 @@ function makeCreate(channel) {
       const shared = select(args, SHARED_CREATE);
       const tickArgs = { ...shared, ...(args.ticks ?? {}) };
       const labelArgs = {
-        ...select(shared, ["scale", "position"]),
+        ...select(shared, ["target", "scale", "position"]),
         ...(args.labels ?? {})
       };
 

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

@@ -1,3 +1,7 @@
+import { selectCartesianAxis, axisTargetArgs } from "../../../selectors/axes.js";
+import { axisGraphicIds } from "../../../materialization/guides/resources.js";
+import { canvasOverflowError } from "../../../layout/canvas.js";
+import { patchGuideDash, validateGuideDash, normalizeGuideDashMap, resolveGuideDashes } from "../../../grammar/guideDash.js";
 import { editGraphicProperties } from "../../primitives/graphicProperties.js";
 import { withGuideLayoutValidation } from "../../../materialization/guides/layout.js";
 import { applyMaterializationPlan } from "../../../materialization/planner.js";
@@ -10,7 +14,7 @@ import {
   validateNonNegativeFinite,
   validateOptionObject
 } from "../../../core/validation.js";
-import { resolveGuideCoordinateBounds } from "../../../materialization/coordinateBounds.js";
+import { resolveCartesianAxisFrameBounds } from "../../../materialization/coordinateBounds.js";
 import {
   isTransformedScaleType,
   mapContinuousScaleValues,
@@ -31,7 +35,7 @@ import {
 import { findCanvasGraphic, resolvePlotGraphicPlacement } from
   "../../../materialization/graphicHierarchy.js";
 
-const OPTIONS = Object.freeze(["scale", "position", "count", "values", "length", "color", "lineWidth"]);
+const OPTIONS = Object.freeze(["target", "scale", "position", "count", "values", "length", "color", "lineWidth", "alongOffset", "strokeDash", "strokeDashMap"]);
 const DEFAULTS = Object.freeze({
   count: DEFAULT_TICK_COUNT,
   length: 6,
@@ -45,6 +49,7 @@ function validateOptions(args, operation, create) {
     create ? OPTIONS : OPTIONS.filter(key => key !== "scale"),
     operation
   );
+  if (Object.hasOwn(args, "alongOffset") && !Number.isFinite(args.alongOffset)) throw new TypeError("Tick alongOffset must be a finite number.");
   if (Object.hasOwn(args, "count") && Object.hasOwn(args, "values")) throw new Error(`${operation} cannot use count and values together.`);
   if (Array.isArray(args.values)) {
     validateGeneratedItemLimit(args.values.length, "Tick value count");
@@ -52,6 +57,8 @@ function validateOptions(args, operation, create) {
 }
 
 function validateConfig(channel, config) {
+  if (config.strokeDash !== undefined) validateGuideDash(config.strokeDash, "Tick strokeDash");
+  if (config.strokeDashMap !== undefined) normalizeGuideDashMap(config.strokeDashMap, { reset: false });
   validateAxisPosition(channel, config.position);
   if (config.mode === "count") {
     if (!Number.isInteger(config.count) || config.count <= 0) throw new RangeError("Tick count must be a positive integer.");
@@ -65,18 +72,15 @@ function validateConfig(channel, config) {
       (typeof value === "number" && Number.isFinite(value))
     ))
   ) throw new TypeError("Tick values must be nominal values or finite numbers.");
+  if (config.alongOffset !== undefined && !Number.isFinite(config.alongOffset)) throw new TypeError("Tick alongOffset must be a finite number.");
   validateNonNegativeFinite(config.length, "Tick length");
   validateNonNegativeFinite(config.lineWidth, "Tick lineWidth");
   validateNonEmptyString(config.color, "Tick color");
 }
 
-function geometry(program, channel, config) {
+function geometry(program, channel, config, axisId = channel) {
   const scale = program.resolvedScales[config.scale];
-  const bounds = resolveGuideCoordinateBounds(program, {
-    coordinate: program.semanticSpec.guides.axis?.[channel]?.coordinate,
-    scale: config.scale,
-    channel
-  });
+  const bounds = resolveCartesianAxisFrameBounds(program, channel, config.position, config.scale, axisId);
   const discrete = ["ordinal", "band", "point"].includes(scale?.type);
   if ((
     !["linear", "time", "ordinal", "band", "point"].includes(scale?.type) &&
@@ -102,7 +106,7 @@ function geometry(program, channel, config) {
       bounds,
       channel,
       position: config.position,
-      positions,
+      positions: positions.map(value => value + (config.alongOffset ?? 0)),
       length: config.length
     })
   };
@@ -127,7 +131,7 @@ function geometry(program, channel, config) {
     coordinates.some(value => !Number.isFinite(value)) ||
     !fits
   ) {
-    throw new Error(`The ${channel}-axis ticks do not fit the Canvas margin.`);
+    throw canvasOverflowError(`The ${channel}-axis ticks do not fit the Canvas margin.`, [{ left: left - strokeExtent, right: right + strokeExtent, top: top - strokeExtent, bottom: bottom + strokeExtent }], canvas);
   }
   return resolved;
 }
@@ -136,9 +140,11 @@ function makeEdit(channel) {
   const op = channel === "x" ? "editXAxisTicks" : "editYAxisTicks";
   return action({ op, description: `Edit concrete ${channel}-axis ticks.` }, withGuideLayoutValidation(function (args = {}) {
     validateOptions(args, op, false);
-    const id = `${channel}AxisTicks`;
+    const selected = selectCartesianAxis(this, channel, args, { create: false });
+    const axisId = selected.id; args = selected.options;
+    const id = axisGraphicIds(channel, axisId)[1];
     if (this.graphicSpec.objects[id]?.type !== "line") throw new Error(`${op} requires existing axis ticks.`);
-    const previous = this.guideConfigs.axis?.[channel]?.ticks;
+    const previous = this.guideConfigs.axis?.[axisId]?.ticks;
     if (!previous) throw new Error(`${op} requires tick configuration.`);
     const explicitMode = Object.hasOwn(args, "values") || Object.hasOwn(args, "count");
     const inferredValues = !explicitMode && previous.inferredValues === true
@@ -152,24 +158,28 @@ function makeEdit(channel) {
     const mode = Object.hasOwn(args, "values") || inferredValues !== undefined
       ? "values"
       : Object.hasOwn(args, "count") ? "count" : previous.mode;
-    const config = {
+    const config = patchGuideDash({
       ...previous,
       ...args,
       ...(inferredValues === undefined ? {} : { values: inferredValues }),
       ...(explicitMode ? { inferredValues: false } : {}),
       mode
-    };
+    }, args);
     if (mode === "values") delete config.count; else delete config.values;
     validateConfig(channel, config);
-    const resolved = geometry(this, channel, config);
-    let next = this._withGuideConfig(channel, config).editGraphics({ target: id, property: "length", value: resolved.values.length });
+    const resolved = geometry(this, channel, config, axisId);
+    let next = this._withGuideConfig(axisId, config).editGraphics({ target: id, property: "length", value: resolved.values.length });
     for (const property of ["x1", "y1", "x2", "y2"]) next = next.editGraphics({ target: id, property, value: resolved[property] });
     next = editGraphicProperties(next, id, {
       stroke: config.color,
       strokeWidth: config.lineWidth
     });
+    if (config.strokeDash !== undefined || config.strokeDashMap !== undefined ||
+        previous.strokeDashMap !== undefined) {
+      next = next.editGraphics({ target: id, property: "strokeDash", value: resolveGuideDashes(resolved.values, config) });
+    }
     // Structural dependency plans own grids during a scale/role handoff.
-    return explicitMode ? applyMaterializationPlan(next, planAxisTickGridRematerialization(next, channel)) : next;
+    return explicitMode ? applyMaterializationPlan(next, planAxisTickGridRematerialization(next, channel, axisId)) : next;
   }));
 }
 
@@ -180,10 +190,12 @@ function makeCreate(channel) {
   const edit = channel === "x" ? "editXAxisTicks" : "editYAxisTicks";
   return action({ op, description: `Create concrete ${channel}-axis ticks.` }, withGuideLayoutValidation(function (args = {}) {
     validateOptions(args, op, true);
+    const selected = selectCartesianAxis(this, channel, args, { create: true });
+    const axisId = selected.id; args = selected.options;
     const scale = validateUserId(args.scale ?? channel, "Scale id");
-    const existingGuide = this.semanticSpec.guides.axis?.[channel]?.scale;
+    const existingGuide = this.semanticSpec.guides.axis?.[axisId]?.scale;
     if (existingGuide && existingGuide !== scale) throw new Error(`${op} conflicts with the existing axis scale.`);
-    const id = `${channel}AxisTicks`;
+    const id = axisGraphicIds(channel, axisId)[1];
     if (this.graphicSpec.objects[id]) throw new Error(`${op} requires missing axis ticks.`);
     const resolvedScale = this.resolvedScales[scale];
     const inferredValues =
@@ -194,18 +206,18 @@ function makeCreate(channel) {
           : inferHistogramBoundaries(this, channel, scale);
     const options =
       inferredValues === undefined ? args : { ...args, values: inferredValues };
-    const config = { scale, position: defaultAxisPosition(channel), length: DEFAULTS.length, color: DEFAULTS.color, lineWidth: DEFAULTS.lineWidth, ...options, inferredValues: inferredValues !== undefined, mode: Object.hasOwn(options, "values") ? "values" : "count" };
+    const config = patchGuideDash({ scale, position: defaultAxisPosition(channel), length: DEFAULTS.length, color: DEFAULTS.color, lineWidth: DEFAULTS.lineWidth, ...options, inferredValues: inferredValues !== undefined, mode: Object.hasOwn(options, "values") ? "values" : "count" }, args);
     if (config.mode === "values") delete config.count; else config.count ??= DEFAULTS.count;
-    validateConfig(channel, config); geometry(this, channel, config);
-    const next = this.editSemantic({ property: `guide.axis.${channel}.scale`, value: scale })
+    validateConfig(channel, config); geometry(this, channel, config, axisId);
+    const next = this.editSemantic({ property: `guide.axis.${axisId}.scale`, value: scale })
       .createGraphics({
         id,
         type: "line",
         length: 0,
         ...resolvePlotGraphicPlacement(this)
       })
-      ._withGuideConfig(channel, config)[edit]();
-    return applyMaterializationPlan(next, planAxisTickGridRematerialization(next, channel));
+      ._withGuideConfig(axisId, config)[edit](axisId === channel ? undefined : axisTargetArgs(axisId, channel));
+    return applyMaterializationPlan(next, planAxisTickGridRematerialization(next, channel, axisId));
   }));
 }
 

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

@@ -1,19 +1,24 @@
+import { selectCartesianAxis, axisTargetArgs } from "../../../selectors/axes.js";
+import { axisGraphicIds } from "../../../materialization/guides/resources.js";
+import { materializeTextLines } from "../../../materialization/textLines.js";
+import { axisTitleTextLines as titleLines, validateAxisTextPlacement } from "../../../grammar/axisTextPlacement.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";
 import { validateUserId } from "../../../core/identifiers.js";
 import {
   validateKeys,
-  validateNonEmptyString,
-  validateNonNegativeFinite
+  validateNonEmptyString
 } from "../../../core/validation.js";
-import { resolveGuideCoordinateBounds } from "../../../materialization/coordinateBounds.js";
+import { axisScaleBindings, resolveCartesianAxisFrameBounds } 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";
@@ -40,24 +45,49 @@ function titleBounds(geometry, config, text, profile) {
   return resolveTextBounds({
     ...geometry,
     text,
+    lines: titleLines(text, config),
     fontSize: config.fontSize,
     fontFamily: config.fontFamily,
     fontWeight: config.fontWeight,
-    textAlign: "center",
-    textBaseline: "middle",
+    textAlign: config.align ?? "center",
+    textBaseline: config.baseline ?? "middle",
     rotation: config.rotation
   }, profile);
 }
 
-function inferredTitleOffset(program, channel, config) {
-  const plot = resolveGuideCoordinateBounds(program, {
-    coordinate: program.semanticSpec.guides.axis?.[channel]?.coordinate,
-    scale: config.scale,
-    channel
-  });
+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 + (config.alongOffset ?? 0);
+}
+
+function axisLabelBounds(program, channel, axisId = channel) {
+  const id = axisGraphicIds(channel, axisId)[2], 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, axisId = channel) {
+  const plot = resolveCartesianAxisFrameBounds(program, channel, config.position, config.scale, axisId);
   const canvas = findCanvasGraphic(program)?.properties;
-  const labels = program.graphicSpec.objects[`${channel}AxisLabels`]
-    ? resolveConcreteGraphicBounds(program.graphicSpec, `${channel}AxisLabels`, program.materializationConfigs.textMetrics)
+  const labels = program.graphicSpec.objects[axisGraphicIds(channel, axisId)[2]]
+    ? resolveConcreteGraphicBounds(program.graphicSpec, axisGraphicIds(channel, axisId)[2], program.materializationConfigs.textMetrics)
     : undefined;
   const preferred = channel === "x" ? 42 : 52;
   if (!plot || !canvas || !labels) return preferred;
@@ -71,24 +101,43 @@ function inferredTitleOffset(program, channel, config) {
     position: config.position,
     along: 0,
     offset: preferred
-  }), config, program.semanticSpec.guides.axis?.[channel]?.title ?? "", program.materializationConfigs.textMetrics);
+  }), config, program.semanticSpec.guides.axis?.[axisId]?.title ?? "", program.materializationConfigs.textMetrics);
   const needed = positive
     ? labels[far] + 4 - bounds[near]
     : bounds[far] - labels[near] + 4;
   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?.[axisId]?.title ?? "", program.materializationConfigs.textMetrics);
+  // Optional ink reserve must not introduce a label collision.
+  return preferred + (axisLabelBounds(program, channel, axisId).some(label => label && textBoundsIntersect(candidateBounds, label))
+    ? legacyAdjustment : adjustment);
 }
 
-const CREATE_OPTIONS = [
+const CREATE_OPTIONS = ["target",
   "text", "scale", "position", "at", "offset", "rotation", "color",
-  "fontSize", "fontFamily", "fontWeight"
+  "fontSize", "fontFamily", "fontWeight", "alongOffset", "align", "baseline"
 ];
 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
 };
@@ -100,7 +149,7 @@ function validateText(text) {
 function validateConfig(channel, config) {
   validateAxisPosition(channel, config.position);
   if (!["start", "center", "end"].includes(config.at) && !Number.isFinite(config.at)) throw new TypeError("Axis title at must be start, center, end, or a finite number.");
-  validateNonNegativeFinite(config.offset, "Axis title offset");
+  validateAxisTextPlacement(config, { title: true });
   if (!Number.isFinite(config.rotation)) throw new TypeError("Axis title rotation must be finite radians.");
   validateAxisTextStyle(config, "Axis title");
 }
@@ -149,37 +198,19 @@ 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];
 }
 
-function resolveGeometry(program, channel, config) {
+function resolveGeometry(program, channel, config, axisId = channel) {
   const scale = program.resolvedScales[config.scale];
-  const bounds = resolveGuideCoordinateBounds(program, {
-    coordinate: program.semanticSpec.guides.axis?.[channel]?.coordinate,
-    scale: config.scale,
-    channel
-  });
-  const discrete = ["ordinal", "band", "point"].includes(scale?.type);
+  const bounds = resolveCartesianAxisFrameBounds(program, channel, config.position, config.scale, axisId);
   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,
@@ -190,16 +221,14 @@ function resolveGeometry(program, channel, config) {
   const resolvedBounds = titleBounds(
     geometry,
     config,
-    program.semanticSpec.guides.axis?.[channel]?.title ?? ""
+    program.semanticSpec.guides.axis?.[axisId]?.title ?? ""
   , 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, axisId);
+  if (labelBounds.some(bounds => bounds && textBoundsIntersect(resolvedBounds, bounds))) {
     throw new Error(`The ${channel}-axis title overlaps the axis labels.`);
   }
   return geometry;
@@ -207,15 +236,19 @@ function resolveGeometry(program, channel, config) {
 
 function names(channel) {
   const prefix = channel === "x" ? "X" : "Y";
-  return { create: `create${prefix}AxisTitle`, edit: `edit${prefix}AxisTitle`, graphic: `${channel}AxisTitle` };
+  return { create: `create${prefix}AxisTitle`, edit: `edit${prefix}AxisTitle` };
 }
 
 function makeEdit(channel) {
   const operation = names(channel);
   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;
+    const selected = selectCartesianAxis(this, channel, args, { create: false });
+    const axisId = selected.id; args = selected.options;
+    const graphic = axisGraphicIds(channel, axisId)[3];
+    validateAxisTextPlacement(args, { title: true });
+    if (this.graphicSpec.objects[graphic]?.type !== "text") throw new Error(`${operation.edit} requires an existing axis title.`);
+    const previous = this.guideConfigs.axis?.[axisId]?.title;
     if (!previous) throw new Error(`${operation.edit} requires title configuration.`);
     const { text, rotation: requestedRotation, ...appearance } = args;
     const explicitText = Object.hasOwn(args, "text");
@@ -245,27 +278,27 @@ function makeEdit(channel) {
       ? validateText(text)
       : config.inferredText === true
         ? inferAxisTitleText(this, channel, config.scale)
-        : this.semanticSpec.guides.axis?.[channel]?.title;
-    if (resolvedTitle !== this.semanticSpec.guides.axis?.[channel]?.title) {
+        : this.semanticSpec.guides.axis?.[axisId]?.title;
+    if (resolvedTitle !== this.semanticSpec.guides.axis?.[axisId]?.title) {
       next = next.editSemantic({
-        property: `guide.axis.${channel}.title`,
+        property: `guide.axis.${axisId}.title`,
         value: validateText(resolvedTitle)
       });
     }
-    const resolvedText = validateText(next.semanticSpec.guides.axis?.[channel]?.title);
+    const resolvedText = validateText(next.semanticSpec.guides.axis?.[axisId]?.title);
     if (config.inferredOffset) {
-      config.offset = inferredTitleOffset(next, channel, config);
+      config.offset = inferredTitleOffset(next, channel, config, axisId);
     }
-    const geometry = resolveGeometry(next, channel, config);
-    next = next._withGuideConfig(channel, "title", config);
+    const geometry = resolveGeometry(next, channel, config, axisId);
+    next = next._withGuideConfig(axisId, "title", config);
     const properties = {
       x: geometry.x, y: geometry.y, text: resolvedText, fill: config.color,
       fontSize: config.fontSize, fontFamily: config.fontFamily,
-      fontWeight: config.fontWeight, textAlign: "center", textBaseline: "middle",
+      fontWeight: config.fontWeight, textAlign: config.align ?? "center", textBaseline: config.baseline ?? "middle",
       rotation: config.rotation
     };
-    for (const [property, value] of Object.entries(properties)) next = next.editGraphics({ target: operation.graphic, property, value });
-    return next;
+    for (const [property, value] of Object.entries(properties)) next = next.editGraphics({ target: graphic, property, value });
+    return materializeTextLines(next, graphic, titleLines(resolvedText, config));
   }));
 }
 
@@ -276,6 +309,10 @@ function makeCreate(channel) {
   const operation = names(channel);
   return action({ op: operation.create, description: `Create the ${channel}-axis title.` }, withGuideLayoutValidation(function (args = {}) {
       validateKeys(args, CREATE_OPTIONS, operation.create);
+    const selected = selectCartesianAxis(this, channel, args, { create: true });
+    const axisId = selected.id; args = selected.options;
+    const graphic = axisGraphicIds(channel, axisId)[3];
+    validateAxisTextPlacement(args, { title: true });
     const {
       text: requestedText,
       scale: requestedScale,
@@ -284,9 +321,9 @@ function makeCreate(channel) {
       ...appearance
     } = args;
     const scale = validateUserId(requestedScale ?? channel, "Scale id");
-    const guideScale = this.semanticSpec.guides.axis?.[channel]?.scale;
+    const guideScale = this.semanticSpec.guides.axis?.[axisId]?.scale;
     if (guideScale && guideScale !== scale) throw new Error(`${operation.create} conflicts with the existing axis scale.`);
-    if (this.graphicSpec.objects[operation.graphic]) throw new Error(`${operation.create} requires a missing axis title.`);
+    if (this.graphicSpec.objects[graphic]) throw new Error(`${operation.create} requires a missing axis title.`);
     const inferredText = !Object.hasOwn(args, "text");
     const text = validateText(
       requestedText ?? inferAxisTitleText(this, channel, scale)
@@ -309,21 +346,22 @@ function makeCreate(channel) {
       fontSize: DEFAULTS.fontSize,
       fontFamily: DEFAULTS.fontFamily,
       fontWeight: DEFAULTS.fontWeight,
+      ...axisThemeTypography(this.materializationConfigs.theme, "title"),
       ...appearance
     };
     let next = this
-      .editSemantic({ property: `guide.axis.${channel}.scale`, value: scale })
-      .editSemantic({ property: `guide.axis.${channel}.title`, value: text });
-    if (inferredOffset) config.offset = inferredTitleOffset(next, channel, config);
+      .editSemantic({ property: `guide.axis.${axisId}.scale`, value: scale })
+      .editSemantic({ property: `guide.axis.${axisId}.title`, value: text });
+    if (inferredOffset) config.offset = inferredTitleOffset(next, channel, config, axisId);
     validateConfig(channel, config);
-    resolveGeometry(next, channel, config);
+    resolveGeometry(next, channel, config, axisId);
     return next
       .createGraphics({
-        id: operation.graphic,
+        id: graphic,
         type: "text",
         ...resolvePlotGraphicPlacement(this)
       })
-      ._withGuideConfig(channel, "title", config)[operation.edit]();
+      ._withGuideConfig(axisId, "title", config)[operation.edit](axisId === channel ? undefined : axisTargetArgs(axisId, channel));
   }));
 }
 

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);