ggaction 0.0.9 → 0.0.11

package/src/actions/gradientPlots/resolve.js

@@ -1,7 +1,7 @@
 import { resolveOptionalUserId, validateUserId } from "../../core/identifiers.js";
 import { findLayer, hasLayer } from "../../selectors/layers.js";
 
-const CATEGORICAL = Object.freeze(["nominal", "ordinal", "temporal"]);
+const CATEGORICAL = Object.freeze(["nominal", "ordinal"]);
 
 export function resolveGradientOrientation(x, y) {
   const xType = x?.fieldType;

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

@@ -1,17 +1,17 @@
-import { registerAxisCollectionActions } from "./axes.js";
+import { registerAxisTickGroupActions } from "./tickGroups.js";
+import { registerCompleteAxisEditActions } from "./edit.js";
 import { registerAxisLabelActions } from "./labels.js";
 import { registerAxisLineActions } from "./lines.js";
-import { registerAxisTickGroupActions } from "./tickGroups.js";
 import { registerAxisTickActions } from "./ticks.js";
 import { registerAxisTitleActions } from "./titles.js";
 import { registerAxisActions } from "./axis.js";
-import { registerCompleteAxisEditActions } from "./edit.js";
 import {
   removeRadialAxis,
   removeThetaAxis,
   removeXAxis,
   removeYAxis
 } from "./remove.js";
+import { registerAxisCollectionActions } from "./axes.js";
 import { registerParallelAxisActions } from "./parallel.js";
 
 export function registerBasicCartesianAxisActions(ProgramClass) {

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

@@ -2,6 +2,7 @@ import { action } from "../../../core/action.js";
 import { validateUserId } from "../../../core/identifiers.js";
 import {
   sameOrderedValues,
+  validateGeneratedItemLimit,
   validateOptionObject,
   validateNonEmptyString,
   validateNonNegativeFinite,
@@ -27,20 +28,36 @@ import {
 } from "./policy.js";
 import { findCanvasGraphic, resolvePlotGraphicPlacement } from
   "../../../materialization/graphicHierarchy.js";
-import { resolveTextBounds } from "../../../core/textMetrics.js";
+import {
+  resolveTextBounds,
+  textBoundsFitCanvas,
+  textBoundsIntersect
+} from "../../../core/textMetrics.js";
+import { resolveConcreteGraphicBounds } from
+  "../../../grammar/schemas/graphicBounds.js";
 
-const OPTIONS = Object.freeze([
+const OPTIONS = [
   "scale", "position", "count", "values", "offset", "format", "color",
   "fontSize", "fontFamily", "fontWeight"
-]);
+];
 
-const DEFAULTS = Object.freeze({
+const DEFAULTS = {
   count: 5,
   color: DEFAULT_COLORS.text,
   fontSize: 12,
   fontFamily: DEFAULT_FONT_FAMILY,
   fontWeight: "normal"
-});
+};
+
+export function validateAxisTextStyle(config, label) {
+  validateNonEmptyString(config.color, `${label} color`);
+  validatePositiveFinite(config.fontSize, `${label} fontSize`);
+  validateNonEmptyString(config.fontFamily, `${label} fontFamily`);
+  if (typeof config.fontWeight !== "string" &&
+    !Number.isFinite(config.fontWeight)) {
+    throw new TypeError(`${label} fontWeight must be a string or number.`);
+  }
+}
 
 function validateOptions(args, operation, create) {
   validateOptionObject(
@@ -55,7 +72,10 @@ function validateOptions(args, operation, create) {
 
 function validateConfig(channel, config) {
   validateAxisPosition(channel, config.position);
-  if (config.mode === "count" && (!Number.isInteger(config.count) || config.count <= 0)) throw new RangeError("Label count must be a positive integer.");
+  if (config.mode === "count") {
+    if (!Number.isInteger(config.count) || config.count <= 0) throw new RangeError("Label count must be a positive integer.");
+    validateGeneratedItemLimit(config.count, "Label count");
+  }
   if (
     config.mode === "values" &&
     (!Array.isArray(config.values) || !config.values.every(value =>
@@ -64,11 +84,11 @@ function validateConfig(channel, config) {
       (typeof value === "number" && Number.isFinite(value))
     ))
   ) throw new TypeError("Label values must be nominal values or finite numbers.");
+  if (config.mode === "values") {
+    validateGeneratedItemLimit(config.values.length, "Label value count");
+  }
   validateNonNegativeFinite(config.offset, "Label offset");
-  validatePositiveFinite(config.fontSize, "Label fontSize");
-  validateNonEmptyString(config.color, "Label color");
-  validateNonEmptyString(config.fontFamily, "Label fontFamily");
-  if ((typeof config.fontWeight !== "string" && !Number.isFinite(config.fontWeight))) throw new TypeError("Label fontWeight must be a string or number.");
+  validateAxisTextStyle(config, "Label");
   validateAxisFormat(config.format);
 }
 
@@ -89,6 +109,7 @@ function resolve(program, channel, config) {
   ) || !bounds) throw new Error("Axis labels require a supported resolved scale and Canvas bounds.");
   if (discrete && config.mode !== "values") throw new Error("Discrete axis labels require explicit or inferred values, not count.");
   const values = valuesFromTickConfig(program, config);
+  validateGeneratedItemLimit(values.length, "Label value count");
   if (discrete) {
     const domainValues = new Set(scale.domain);
     if (!values.every(value => domainValues.has(value))) throw new RangeError("Label values must be inside the scale domain.");
@@ -128,17 +149,29 @@ function resolve(program, channel, config) {
     y: Array.isArray(resolved.y) ? resolved.y[index] : resolved.y,
     text: value,
     fontSize: config.fontSize,
+    fontFamily: config.fontFamily,
+    fontWeight: config.fontWeight,
     textAlign: resolved.textAlign,
     textBaseline: resolved.textBaseline
   }));
-  const fits = config.position === "top"
-    ? labelBounds.every(item => item.top >= 0)
-    : config.position === "right"
-      ? labelBounds.every(item => item.right <= canvas?.width)
-      : true;
-  if (!canvas || !fits) {
+  const orderedBounds = [...labelBounds].sort((left, right) => channel === "x"
+    ? left.left - right.left
+    : left.top - right.top);
+  if (!canvas || !labelBounds.every(item => textBoundsFitCanvas(item, canvas))) {
     throw new Error(`The ${channel}-axis labels do not fit the Canvas margin.`);
   }
+  if (orderedBounds.some((item, index) => index > 0 &&
+    textBoundsIntersect(orderedBounds[index - 1], item))) {
+    throw new Error(`The ${channel}-axis labels overlap each other.`);
+  }
+  const title = program.graphicSpec.objects[`${channel}AxisTitle`]
+    ? resolveConcreteGraphicBounds(program.graphicSpec, `${channel}AxisTitle`)
+    : undefined;
+  if (title &&
+    program.guideConfigs.axis?.[channel]?.title?.inferredOffset !== true &&
+    labelBounds.some(item => textBoundsIntersect(item, title))) {
+    throw new Error(`The ${channel}-axis labels overlap the axis title.`);
+  }
   return resolved;
 }
 
@@ -170,16 +203,25 @@ function makeEdit(channel) {
     validateConfig(channel, config);
     assertTickCompatibility(this.guideConfigs.axis?.[channel]?.ticks, config, op);
     const resolved = resolve(this, channel, config);
-    let next = this._withGuideConfig(channel, "labels", config)
-      .editGraphics({ target: id, property: "length", value: resolved.values.length });
-    for (const property of ["x", "y", "text"]) next = next.editGraphics({ target: id, property, value: resolved[property] });
-    return next
-      .editGraphics({ target: id, property: "fill", value: config.color })
-      .editGraphics({ target: id, property: "fontSize", value: config.fontSize })
-      .editGraphics({ target: id, property: "fontFamily", value: config.fontFamily })
-      .editGraphics({ target: id, property: "fontWeight", value: config.fontWeight })
-      .editGraphics({ target: id, property: "textAlign", value: resolved.textAlign })
-      .editGraphics({ target: id, property: "textBaseline", value: resolved.textBaseline });
+    let next = this._withGuideConfig(channel, "labels", config);
+    for (const [property, value] of Object.entries({
+      length: resolved.values.length,
+      x: resolved.x,
+      y: resolved.y,
+      text: resolved.text,
+      fill: config.color,
+      fontSize: config.fontSize,
+      fontFamily: config.fontFamily,
+      fontWeight: config.fontWeight,
+      textAlign: resolved.textAlign,
+      textBaseline: resolved.textBaseline
+    })) next = next.editGraphics({ target: id, property, value });
+    const titleConfig = next.guideConfigs.axis?.[channel]?.title;
+    if (titleConfig?.inferredOffset === true) {
+      const editTitle = channel === "x" ? "editXAxisTitle" : "editYAxisTitle";
+      next = next[editTitle]();
+    }
+    return next;
   });
 }
 

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

@@ -24,6 +24,20 @@ function validateStyle({ color, lineWidth }) {
   validateNonNegativeFinite(lineWidth, "Axis lineWidth");
 }
 
+function resolveLineRange(resolvedScale, bounds, channel) {
+  const range = resolvedScale?.range;
+  if (
+    resolvedScale?.type !== "time" ||
+    !Number.isFinite(resolvedScale.bandwidth)
+  ) return range;
+  const plotRange = channel === "x"
+    ? [bounds.x, bounds.x + bounds.width]
+    : [bounds.y + bounds.height, bounds.y];
+  return Math.sign(range[1] - range[0]) === Math.sign(plotRange[1] - plotRange[0])
+    ? plotRange
+    : plotRange.reverse();
+}
+
 function resolveGeometry(program, channel, scaleId, position) {
   const hasConsumer = program.semanticSpec.layers.some(
     layer => layer.encoding?.[channel]?.scale === scaleId
@@ -35,7 +49,8 @@ function resolveGeometry(program, channel, scaleId, position) {
     );
   }
 
-  const range = program.resolvedScales[scaleId]?.range;
+  const resolvedScale = program.resolvedScales[scaleId];
+  const range = resolvedScale?.range;
   const bounds = resolveGraphicBounds(program);
 
   if (!Array.isArray(range) || range.length !== 2 || !range.every(Number.isFinite)) {
@@ -49,7 +64,12 @@ function resolveGeometry(program, channel, scaleId, position) {
     throw new Error("Axis line requires graphical Canvas bounds.");
   }
 
-  return resolveAxisLineGeometry(bounds, channel, position, range);
+  return resolveAxisLineGeometry(
+    bounds,
+    channel,
+    position,
+    resolveLineRange(resolvedScale, bounds, channel)
+  );
 }
 
 function axisIds(channel) {

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

@@ -1,3 +1,5 @@
+import { formatVisibleText } from "../../../core/textMetrics.js";
+
 const AXIS_POSITIONS = Object.freeze({
   x: Object.freeze(["bottom", "top"]),
   y: Object.freeze(["left", "right"])
@@ -6,7 +8,24 @@ const AXIS_POSITIONS = Object.freeze({
 const NUMERIC_FORMATS = new Set([
   ".0f", ".1f", ".2f", ".0%", ".1%", ".2e"
 ]);
-const TIME_FORMATS = new Set(["%Y", "%Y-%m", "%Y-%m-%d"]);
+const TIME_DIRECTIVES = new Set(["Y", "m", "d", "b", "%"]);
+const MONTH_NAMES = Object.freeze([
+  "Jan", "Feb", "Mar", "Apr", "May", "Jun",
+  "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"
+]);
+
+function isTimeFormat(format) {
+  if (typeof format !== "string") return false;
+  let directives = 0;
+  for (let index = 0; index < format.length; index += 1) {
+    if (format[index] !== "%") continue;
+    const directive = format[index + 1];
+    if (!TIME_DIRECTIVES.has(directive)) return false;
+    if (directive !== "%") directives += 1;
+    index += 1;
+  }
+  return directives > 0;
+}
 
 export function defaultAxisPosition(channel) {
   return channel === "x" ? "bottom" : "left";
@@ -105,7 +124,7 @@ export function validateAxisFormat(format) {
     return format;
   }
   if (typeof format === "string" && (
-    NUMERIC_FORMATS.has(format) || TIME_FORMATS.has(format)
+    NUMERIC_FORMATS.has(format) || isTimeFormat(format)
   )) {
     return format;
   }
@@ -126,24 +145,25 @@ function formatTime(value, format) {
   const year = pad(date.getUTCFullYear(), 4);
   const month = pad(date.getUTCMonth() + 1);
   const day = pad(date.getUTCDate());
-  if (format === "%Y") return year;
-  if (format === "%Y-%m") return `${year}-${month}`;
-  return `${year}-${month}-${day}`;
+  const values = { Y: year, m: month, d: day, b: MONTH_NAMES[date.getUTCMonth()] };
+  return format.replace(/%([Ymdb%])/g, (_, directive) =>
+    directive === "%" ? "%" : values[directive]
+  );
 }
 
 export function formatAxisValue(value, scaleType, format, autoFormatter) {
   validateAxisFormat(format);
-  if (format === "auto") return autoFormatter(value);
+  if (format === "auto") return formatVisibleText(autoFormatter(value));
   if (["ordinal", "band", "point"].includes(scaleType)) {
     throw new Error('Discrete axis labels require format "auto".');
   }
   if (scaleType === "time") {
-    if (!TIME_FORMATS.has(format)) {
+    if (!isTimeFormat(format)) {
       throw new Error("Time axis labels require a supported time format string.");
     }
     return formatTime(value, format);
   }
-  if (TIME_FORMATS.has(format)) {
+  if (isTimeFormat(format)) {
     throw new Error("Quantitative axis labels cannot use a time format string.");
   }
   if (typeof format === "object") return value.toFixed(format.decimals);

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

@@ -1,6 +1,7 @@
 import { action } from "../../../core/action.js";
 import { validateUserId } from "../../../core/identifiers.js";
 import {
+  validateGeneratedItemLimit,
   validateNonEmptyString,
   validateNonNegativeFinite,
   validateOptionObject
@@ -11,6 +12,7 @@ import {
   mapContinuousScaleValues,
   mapOrdinalPositionValues
 } from "../../../grammar/scales/index.js";
+import { numericExtent } from "../../../grammar/numeric.js";
 import {
   DEFAULT_TICK_COUNT,
   inferHistogramBoundaries,
@@ -40,11 +42,17 @@ function validateOptions(args, operation, create) {
     operation
   );
   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");
+  }
 }
 
 function validateConfig(channel, config) {
   validateAxisPosition(channel, config.position);
-  if (config.mode === "count" && (!Number.isInteger(config.count) || config.count <= 0)) throw new RangeError("Tick count must be a positive integer.");
+  if (config.mode === "count") {
+    if (!Number.isInteger(config.count) || config.count <= 0) throw new RangeError("Tick count must be a positive integer.");
+    validateGeneratedItemLimit(config.count, "Tick count");
+  }
   if (
     config.mode === "values" &&
     (!Array.isArray(config.values) || !config.values.every(value =>
@@ -69,6 +77,7 @@ function geometry(program, channel, config) {
   if (discrete && config.mode !== "values") throw new Error("Discrete axis ticks require explicit or inferred values, not count.");
   const domain = scale.domain;
   const values = valuesFromTickConfig(program, config);
+  validateGeneratedItemLimit(values.length, "Tick value count");
   if (discrete) {
     const domainValues = new Set(domain);
     if (!values.every(value => domainValues.has(value))) throw new RangeError("Tick values must be inside the scale domain.");
@@ -90,16 +99,25 @@ function geometry(program, channel, config) {
     })
   };
   const canvas = findCanvasGraphic(program)?.properties;
-  const coordinates = channel === "x"
-    ? [...resolved.x1, ...resolved.x2, resolved.y1, resolved.y2]
-    : [resolved.x1, resolved.x2, ...resolved.y1, ...resolved.y2];
-  const newEdgeDoesNotFit =
-    (config.position === "top" && resolved.y2 < 0) ||
-    (config.position === "right" && resolved.x2 > canvas?.width);
+  const xCoordinates = channel === "x"
+    ? [...resolved.x1, ...resolved.x2]
+    : [resolved.x1, resolved.x2];
+  const yCoordinates = channel === "x"
+    ? [resolved.y1, resolved.y2]
+    : [...resolved.y1, ...resolved.y2];
+  const coordinates = [...xCoordinates, ...yCoordinates];
+  const [left, right] = numericExtent(xCoordinates);
+  const [top, bottom] = numericExtent(yCoordinates);
+  const strokeExtent = config.lineWidth / 2;
+  const epsilon = 1e-9;
+  const fits = canvas &&
+    left - strokeExtent >= -epsilon &&
+    right + strokeExtent <= canvas.width + epsilon &&
+    top - strokeExtent >= -epsilon &&
+    bottom + strokeExtent <= canvas.height + epsilon;
   if (
-    !canvas ||
     coordinates.some(value => !Number.isFinite(value)) ||
-    newEdgeDoesNotFit
+    !fits
   ) {
     throw new Error(`The ${channel}-axis ticks do not fit the Canvas margin.`);
   }

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

@@ -3,8 +3,7 @@ import { validateUserId } from "../../../core/identifiers.js";
 import {
   validateKeys,
   validateNonEmptyString,
-  validateNonNegativeFinite,
-  validatePositiveFinite
+  validateNonNegativeFinite
 } from "../../../core/validation.js";
 import { resolveGraphicBounds } from "../../../layout/canvas.js";
 import {
@@ -16,6 +15,7 @@ import { DEFAULT_COLORS, DEFAULT_FONT_FAMILY } from
   "../../../theme/defaults.js";
 import { findDataset } from "../../../selectors/datasets.js";
 import { formatAggregateTitle } from "../../../grammar/aggregate.js";
+import { finiteMidpoint } from "../../../grammar/numeric.js";
 import {
   defaultAxisPosition,
   defaultAxisTitleRotation,
@@ -24,19 +24,67 @@ import {
 } from "./policy.js";
 import { findCanvasGraphic, resolvePlotGraphicPlacement } from
   "../../../materialization/graphicHierarchy.js";
-import { resolveTextBounds } from "../../../core/textMetrics.js";
+import {
+  resolveTextBounds,
+  textBoundsFitCanvas,
+  textBoundsIntersect
+} from "../../../core/textMetrics.js";
+import { resolveConcreteGraphicBounds } from
+  "../../../grammar/schemas/graphicBounds.js";
+import { validateAxisTextStyle } from "./labels.js";
+
+function titleBounds(geometry, config, text) {
+  return resolveTextBounds({
+    ...geometry,
+    text,
+    fontSize: config.fontSize,
+    fontFamily: config.fontFamily,
+    fontWeight: config.fontWeight,
+    textAlign: "center",
+    textBaseline: "middle",
+    rotation: config.rotation
+  });
+}
+
+function inferredTitleOffset(program, channel, config) {
+  const plot = resolveGraphicBounds(program);
+  const canvas = findCanvasGraphic(program)?.properties;
+  const labels = program.graphicSpec.objects[`${channel}AxisLabels`]
+    ? resolveConcreteGraphicBounds(program.graphicSpec, `${channel}AxisLabels`)
+    : undefined;
+  const preferred = channel === "x" ? 42 : 52;
+  if (!plot || !canvas || !labels) return preferred;
+  const horizontal = channel === "x";
+  const positive = config.position === (horizontal ? "bottom" : "right");
+  const near = horizontal ? "top" : "left";
+  const far = horizontal ? "bottom" : "right";
+  const bounds = titleBounds(resolveAxisTitleGeometry({
+    bounds: plot,
+    channel,
+    position: config.position,
+    along: 0,
+    offset: preferred
+  }), config, program.semanticSpec.guides.axis?.[channel]?.title ?? "");
+  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));
+}
 
-const CREATE_OPTIONS = Object.freeze([
+const CREATE_OPTIONS = [
   "text", "scale", "position", "at", "offset", "rotation", "color",
   "fontSize", "fontFamily", "fontWeight"
-]);
+];
 const EDIT_OPTIONS = CREATE_OPTIONS.filter(key => key !== "scale");
-const DEFAULTS = Object.freeze({
+const DEFAULTS = {
   color: DEFAULT_COLORS.text,
   fontSize: 13,
   fontFamily: DEFAULT_FONT_FAMILY,
   fontWeight: 600
-});
+};
 
 function validateText(text) {
   return validateNonEmptyString(text, "Axis title text");
@@ -47,10 +95,7 @@ function validateConfig(channel, config) {
   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");
   if (!Number.isFinite(config.rotation)) throw new TypeError("Axis title rotation must be finite radians.");
-  validateNonEmptyString(config.color, "Axis title color");
-  validatePositiveFinite(config.fontSize, "Axis title fontSize");
-  validateNonEmptyString(config.fontFamily, "Axis title fontFamily");
-  if (typeof config.fontWeight !== "string" && !Number.isFinite(config.fontWeight)) throw new TypeError("Axis title fontWeight must be a string or number.");
+  validateAxisTextStyle(config, "Axis title");
 }
 
 export function inferAxisTitleText(program, channel, scaleId) {
@@ -64,34 +109,24 @@ export function inferAxisTitleText(program, channel, scaleId) {
       encoding.field.length
     ) {
       const dataset = findDataset(program, layer.data);
-      const density = dataset?.transform?.length === 1 &&
-        dataset.transform[0].type === "density"
+      const transform = dataset?.transform?.length === 1
         ? dataset.transform[0]
         : undefined;
-      const densityTitle = density === undefined
-        ? undefined
-        : encoding.field === density.as?.[0]
-          ? density.field
-          : encoding.field === density.as?.[1]
+      let derivedTitle;
+      if (transform?.type === "density") {
+        derivedTitle = encoding.field === transform.as?.[0]
+          ? transform.field
+          : encoding.field === transform.as?.[1]
             ? "Density"
             : undefined;
-      const interval = dataset?.transform?.length === 1 &&
-        dataset.transform[0].type === "interval"
-        ? dataset.transform[0]
-        : undefined;
-      const intervalTitle = interval !== undefined &&
-        Object.values(interval.as).includes(encoding.field)
-        ? `${interval.center}(${interval.field})`
-        : undefined;
-      const box = dataset?.transform?.length === 1 &&
-        dataset.transform[0].type === "boxSummary"
-        ? dataset.transform[0]
-        : undefined;
-      const boxTitle = box !== undefined &&
-        Object.values(box.as).includes(encoding.field)
-        ? box.field
-        : undefined;
-      const title = encoding.title ?? densityTitle ?? intervalTitle ?? boxTitle ?? (encoding.aggregate === undefined
+      } else if (transform?.type === "interval" &&
+        Object.values(transform.as).includes(encoding.field)) {
+        derivedTitle = `${transform.center}(${transform.field})`;
+      } else if (transform?.type === "boxSummary" &&
+        Object.values(transform.as).includes(encoding.field)) {
+        derivedTitle = transform.field;
+      }
+      const title = encoding.title ?? derivedTitle ?? (encoding.aggregate === undefined
         ? encoding.field
         : formatAggregateTitle(encoding.aggregate, encoding.field));
       titles.add(title);
@@ -112,10 +147,11 @@ function resolveGeometry(program, channel, config) {
     !isTransformedScaleType(scale?.type)
   ) || !bounds) throw new Error("Axis title requires a supported resolved scale and Canvas bounds.");
   let along;
-  if (config.at === "start") along = scale.range[0];
-  else if (config.at === "center") along = (scale.range[0] + scale.range[1]) / 2;
-  else if (config.at === "end") along = scale.range[1];
-  else {
+  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];
@@ -132,24 +168,21 @@ function resolveGeometry(program, channel, config) {
     along,
     offset: config.offset
   });
-  const text = program.semanticSpec.guides.axis?.[channel]?.title ?? "";
-  const titleBounds = resolveTextBounds({
-    ...geometry,
-    text,
-    fontSize: config.fontSize,
-    textAlign: "center",
-    textBaseline: "middle",
-    rotation: config.rotation
-  });
+  const resolvedBounds = titleBounds(
+    geometry,
+    config,
+    program.semanticSpec.guides.axis?.[channel]?.title ?? ""
+  );
   const canvas = findCanvasGraphic(program)?.properties;
-  const newEdgeFits = config.position === "top"
-    ? titleBounds.top >= 0
-    : config.position === "right"
-      ? titleBounds.right <= canvas?.width
-      : true;
-  if (!canvas || !newEdgeFits) {
+  if (!canvas || !textBoundsFitCanvas(resolvedBounds, canvas)) {
     throw new Error(`The ${channel}-axis title does not fit the Canvas margin.`);
   }
+  const labelsBounds = program.graphicSpec.objects[`${channel}AxisLabels`]
+    ? resolveConcreteGraphicBounds(program.graphicSpec, `${channel}AxisLabels`)
+    : undefined;
+  if (labelsBounds && textBoundsIntersect(resolvedBounds, labelsBounds)) {
+    throw new Error(`The ${channel}-axis title overlaps the axis labels.`);
+  }
   return geometry;
 }
 
@@ -180,6 +213,9 @@ function makeEdit(channel) {
         ? defaultAxisTitleRotation(channel, position)
         : appearance.rotation ?? previous.rotation,
       inferredRotation,
+      inferredOffset: Object.hasOwn(args, "offset")
+        ? false
+        : previous.inferredOffset === true,
       ...(explicitText ? { inferredText: false } : {})
     };
     validateConfig(channel, config);
@@ -196,6 +232,9 @@ function makeEdit(channel) {
       });
     }
     const resolvedText = validateText(next.semanticSpec.guides.axis?.[channel]?.title);
+    if (config.inferredOffset) {
+      config.offset = inferredTitleOffset(next, channel, config);
+    }
     const geometry = resolveGeometry(next, channel, config);
     next = next._withGuideConfig(channel, "title", config);
     const properties = {
@@ -216,16 +255,24 @@ function makeCreate(channel) {
   const operation = names(channel);
   return action({ op: operation.create, description: `Create the ${channel}-axis title.` }, function (args = {}) {
       validateKeys(args, CREATE_OPTIONS, operation.create);
-    const scale = validateUserId(args.scale ?? channel, "Scale id");
+    const {
+      text: requestedText,
+      scale: requestedScale,
+      position: requestedPosition,
+      rotation: requestedRotation,
+      ...appearance
+    } = args;
+    const scale = validateUserId(requestedScale ?? channel, "Scale id");
     const guideScale = this.semanticSpec.guides.axis?.[channel]?.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.`);
     const inferredText = !Object.hasOwn(args, "text");
     const text = validateText(
-      args.text ?? inferAxisTitleText(this, channel, scale)
+      requestedText ?? inferAxisTitleText(this, channel, scale)
     );
-    const position = args.position ?? defaultAxisPosition(channel);
+    const position = requestedPosition ?? defaultAxisPosition(channel);
     const inferredRotation = !Object.hasOwn(args, "rotation");
+    const inferredOffset = !Object.hasOwn(args, "offset");
     const config = {
       scale,
       inferredText,
@@ -234,21 +281,22 @@ function makeCreate(channel) {
       offset: channel === "x" ? 42 : 52,
       rotation: inferredRotation
         ? defaultAxisTitleRotation(channel, position)
-        : args.rotation,
+        : requestedRotation,
       inferredRotation,
+      inferredOffset,
       color: DEFAULTS.color,
       fontSize: DEFAULTS.fontSize,
       fontFamily: DEFAULTS.fontFamily,
       fontWeight: DEFAULTS.fontWeight,
-      ...Object.fromEntries(Object.entries(args).filter(
-        ([key]) => !["text", "scale", "position", "rotation"].includes(key)
-      ))
+      ...appearance
     };
-    validateConfig(channel, config);
-    resolveGeometry(this, channel, config);
-    return this
+    let next = this
       .editSemantic({ property: `guide.axis.${channel}.scale`, value: scale })
-      .editSemantic({ property: `guide.axis.${channel}.title`, value: text })
+      .editSemantic({ property: `guide.axis.${channel}.title`, value: text });
+    if (inferredOffset) config.offset = inferredTitleOffset(next, channel, config);
+    validateConfig(channel, config);
+    resolveGeometry(next, channel, config);
+    return next
       .createGraphics({
         id: operation.graphic,
         type: "text",