ggaction 0.0.16 → 0.0.18

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

@@ -1,11 +1,13 @@
+import { axisThemeTypography } from "../../theme/state.js";
+import { canvasOverflowError } from "../../../layout/canvas.js";
 import { withGuideLayoutValidation } from "../../../materialization/guides/layout.js";
 import { action } from "../../../core/action.js";
 import { validateUserId } from "../../../core/identifiers.js";
 import {
   sameOrderedValues,
   validateGeneratedItemLimit,
+  validateTextStyle,
   validateOptionObject,
-  validateNonEmptyString,
   validateNonNegativeFinite,
   validatePositiveFinite
 } from "../../../core/validation.js";
@@ -19,7 +21,7 @@ import {
 import { formatTimeTick, formatTimeTicks } from "../../../grammar/ticks.js";
 import { resolveRotation } from "../../../grammar/rotation.js";
 import { valuesFromTickConfig } from "../tickValues.js";
-import { DEFAULT_COLORS, DEFAULT_FONT_FAMILY } from
+import { AXIS_LABEL_FONT_SIZES, DEFAULT_COLORS, DEFAULT_FONT_FAMILY } from
   "../../../theme/defaults.js";
 import {
   defaultAxisPosition,
@@ -40,19 +42,21 @@ import { resolveConcreteGraphicBounds } from
 import { wrapText } from "../../../layout/text.js";
 import {
   normalizeDisplayLabelMap,
+  normalizeDisplayColorMap,
+  resolveDisplayLabelColor,
   resolveDisplayLabel
 } from "../../../grammar/displayLabels.js";
 
 const OPTIONS = [
   "scale", "position", "count", "values", "offset", "format", "color",
   "fontSize", "fontFamily", "fontWeight", "rotation", "maxWidth", "wrap",
-  "lineHeight", "overlap", "labelMap"
+  "lineHeight", "overlap", "labelMap", "alongOffset", "flush", "colorMap"
 ];
 
 const DEFAULTS = {
   count: 5,
   color: DEFAULT_COLORS.text,
-  fontSize: 12,
+  fontSize: AXIS_LABEL_FONT_SIZES.cartesian,
   fontFamily: DEFAULT_FONT_FAMILY,
   fontWeight: "normal",
   rotation: 0,
@@ -78,15 +82,7 @@ function normalizeLabelLayout(config, args, operation) {
   return next;
 }
 
-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.`);
-  }
-}
+export { validateTextStyle as validateAxisTextStyle };
 
 function validateOptions(args, operation, create) {
   validateOptionObject(
@@ -94,6 +90,8 @@ function validateOptions(args, operation, create) {
     create ? OPTIONS : OPTIONS.filter(key => key !== "scale"),
     operation
   );
+  if (Object.hasOwn(args, "flush") && typeof args.flush !== "boolean") throw new TypeError("Label flush must be a boolean.");
+  if (Object.hasOwn(args, "alongOffset") && !Number.isFinite(args.alongOffset)) throw new TypeError("Label 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.`);
   }
@@ -116,9 +114,11 @@ function validateConfig(channel, config) {
   if (config.mode === "values") {
     validateGeneratedItemLimit(config.values.length, "Label value count");
   }
+  if (config.alongOffset !== undefined && !Number.isFinite(config.alongOffset)) throw new TypeError("Label alongOffset must be a finite number.");
   validateNonNegativeFinite(config.offset, "Label offset");
-  validateAxisTextStyle(config, "Label");
+  validateTextStyle(config, "Label");
   validateAxisFormat(config.format);
+  if (config.flush === true && config.rotation !== 0) throw new Error("Label flush requires unrotated Cartesian labels.");
   if (!Number.isFinite(config.rotation)) {
     throw new TypeError("Label rotation must resolve to finite radians.");
   }
@@ -140,24 +140,30 @@ function validateConfig(channel, config) {
   }
 }
 
-function normalizeAxisLabelMap(program, config, args, operation) {
-  if (!Object.hasOwn(args, "labelMap")) return config;
-  const scale = program.resolvedScales[config.scale];
-  if (!["ordinal", "band", "point"].includes(scale?.type)) {
-    throw new Error(`${operation} labelMap requires a categorical scale.`);
-  }
+function normalizeAxisLabelMaps(program, config, args, operation) {
   const next = { ...config };
-  if (args.labelMap === "auto") {
-    delete next.labelMap;
-  } else {
-    next.labelMap = normalizeDisplayLabelMap(
-      args.labelMap,
-      `${operation} labelMap`
-    );
+  for (const [property, normalize] of [
+    ["labelMap", normalizeDisplayLabelMap],
+    ["colorMap", normalizeDisplayColorMap]
+  ]) {
+    if (!Object.hasOwn(args, property)) continue;
+    if (args[property] === "auto") delete next[property];
+    else next[property] = normalize(args[property], `${operation} ${property}`);
   }
+  validateAxisLabelMapScale(next, program.resolvedScales[config.scale], operation);
   return next;
 }
 
+function validateAxisLabelMapScale(config, scale, operation = "Axis") {
+  if (["ordinal", "band", "point"].includes(scale?.type)) return;
+  for (const property of ["labelMap", "colorMap"]) {
+    if (config[property] !== undefined &&
+        !config[property].every(entry => Number.isFinite(entry.value))) {
+      throw new TypeError(`${operation} continuous ${property} values must be finite numbers or timestamps.`);
+    }
+  }
+}
+
 function assertTickCompatibility(ticks, config, operation) {
   if (!ticks) return;
   if (ticks.scale !== config.scale || ticks.mode !== config.mode) throw new Error(`${operation} conflicts with axis ticks.`);
@@ -226,15 +232,13 @@ function resolve(program, channel, config) {
     channel
   });
   const discrete = ["ordinal", "band", "point"].includes(scale?.type);
-  if (config.labelMap !== undefined && !discrete) {
-    throw new Error("Axis labelMap requires a categorical scale.");
-  }
+  validateAxisLabelMapScale(config, scale);
   if ((
     !["linear", "time", "ordinal", "band", "point"].includes(scale?.type) &&
     !isTransformedScaleType(scale?.type)
   ) || !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);
+  let values = valuesFromTickConfig(program, config);
   validateGeneratedItemLimit(values.length, "Label value count");
   if (discrete) {
     const domainValues = new Set(scale.domain);
@@ -243,7 +247,7 @@ function resolve(program, channel, config) {
     const low = Math.min(...scale.domain), high = Math.max(...scale.domain);
     if (!values.every(value => value >= low && value <= high)) throw new RangeError("Label values must be inside the scale domain.");
   }
-  const positions = discrete
+  let positions = discrete
     ? mapOrdinalPositionValues(values, scale)
     : mapContinuousScaleValues(values, scale);
   const fallback = value => formatAxisValue(
@@ -256,24 +260,39 @@ function resolve(program, channel, config) {
             ? formatTransformedTick(scale.type, item)
             : String(item)
       );
-  const text = discrete
-    ? values.map(value => resolveDisplayLabel(value, config.labelMap, fallback))
-    : scale.type === "time" && config.format === "auto"
-      ? formatTimeTicks(values, scale.domain)
-      : values.map(fallback);
+  const automaticTimeLabels = scale.type === "time" && config.format === "auto"
+    ? formatTimeTicks(values, scale.domain)
+    : undefined;
+  let text = values.map((value, index) =>
+    resolveDisplayLabel(value, config.labelMap, raw =>
+      automaticTimeLabels?.[index] ?? fallback(raw)));
+  // Empty mapped text suppresses the label, never its raw tick or scale value.
+  // Filter all aligned arrays before wrapping so group/color indices stay dense.
+  if (text.includes("")) {
+    const visible = text.map((value, index) => value === "" ? -1 : index)
+      .filter(index => index !== -1);
+    values = visible.map(index => values[index]);
+    positions = visible.map(index => positions[index]);
+    text = visible.map(index => text[index]);
+  }
   const geometry = {
     values,
     ...resolveAxisLabelGeometry({
       bounds,
       channel,
       position: config.position,
-      positions,
+      positions: positions.map(value => value + (config.alongOffset ?? 0)),
       offset: config.offset
     })
   };
   const resolved = expandWrappedLabels(geometry, text, config, channel, program.materializationConfigs.textMetrics);
+  if (channel === "x" && Math.abs(Math.sin(config.rotation)) > 1e-9) {
+    const outward = config.position === "bottom" ? 1 : -1;
+    resolved.textAlign = Math.sin(config.rotation) * outward < 0 ? "right" : "left";
+    resolved.textBaseline = "middle";
+  }
   const canvas = findCanvasGraphic(program)?.properties;
-  const labelBounds = resolved.text.map((value, index) => resolveTextBounds({
+  let labelBounds = resolved.text.map((value, index) => resolveTextBounds({
     x: Array.isArray(resolved.x) ? resolved.x[index] : resolved.x,
     y: Array.isArray(resolved.y) ? resolved.y[index] : resolved.y,
     text: value,
@@ -284,7 +303,58 @@ function resolve(program, channel, config) {
     textBaseline: resolved.textBaseline,
     rotation: config.rotation
   }, program.materializationConfigs.textMetrics));
-  const groupedBounds = unionLabelBounds(labelBounds.map((bounds, index) => ({
+  if (program.materializationConfigs.canvas?.plot !== undefined || config.rotation !== 0) {
+    const horizontal = channel === "x";
+    const near = ["bottom", "right"].includes(config.position);
+    const edge = horizontal ? bounds.y + (near ? bounds.height : 0)
+      : bounds.x + (near ? bounds.width : 0);
+    const boundKey = horizontal ? (near ? "top" : "bottom") : (near ? "left" : "right");
+    const grouped = unionLabelBounds(labelBounds.map((bounds, index) => ({ bounds, group: resolved.groups[index] })));
+    const shifts = grouped.map(item => edge + (near ? config.offset : -config.offset) - item[boundKey]);
+    const axis = horizontal ? "y" : "x";
+    const positions = resolved[axis];
+    resolved[axis] = resolved.text.map((_, index) =>
+      (Array.isArray(positions) ? positions[index] : positions) + shifts[resolved.groups[index]]);
+    labelBounds = labelBounds.map((item, index) => {
+      const delta = shifts[resolved.groups[index]];
+      return horizontal ? { ...item, top: item.top + delta, bottom: item.bottom + delta }
+        : { ...item, left: item.left + delta, right: item.right + delta };
+    });
+  }
+  if (config.flush === true) {
+    const along = channel === "x" ? "x" : "y";
+    const lowKey = channel === "x" ? "left" : "top";
+    const highKey = channel === "x" ? "right" : "bottom";
+    const low = Math.min(...scale.range) + (config.alongOffset ?? 0);
+    const high = Math.max(...scale.range) + (config.alongOffset ?? 0);
+    const grouped = unionLabelBounds(labelBounds.map((bounds, index) => ({ bounds, group: resolved.groups[index] })));
+    const shifts = grouped.map(item => {
+      if (item[highKey] - item[lowKey] > high - low + 1e-9) {
+        throw new Error(`The ${channel}-axis label cannot flush inside the scale span.`);
+      }
+      return item[lowKey] < low ? low - item[lowKey]
+        : item[highKey] > high ? high - item[highKey] : 0;
+    });
+    const positions = resolved[along];
+    resolved[along] = resolved.text.map((_, index) =>
+      (Array.isArray(positions) ? positions[index] : positions) + shifts[resolved.groups[index]]);
+    labelBounds = labelBounds.map((item, index) => {
+      const delta = shifts[resolved.groups[index]];
+      return { ...item, [lowKey]: item[lowKey] + delta, [highKey]: item[highKey] + delta };
+    });
+  }
+  const rotatedOverlap = config.rotation !== 0;
+  const collisionBounds = rotatedOverlap ? resolved.text.map((text, index) => {
+    const x = Array.isArray(resolved.x) ? resolved.x[index] : resolved.x;
+    const y = Array.isArray(resolved.y) ? resolved.y[index] : resolved.y;
+    const cosine = Math.cos(config.rotation), sine = Math.sin(config.rotation);
+    return resolveTextBounds({
+      x: x * cosine + y * sine, y: -x * sine + y * cosine, text,
+      fontSize: config.fontSize, fontFamily: config.fontFamily, fontWeight: config.fontWeight,
+      textAlign: resolved.textAlign, textBaseline: resolved.textBaseline
+    }, program.materializationConfigs.textMetrics);
+  }) : labelBounds;
+  const groupedBounds = unionLabelBounds(collisionBounds.map((bounds, index) => ({
     bounds,
     group: resolved.groups[index]
   })));
@@ -292,10 +362,11 @@ function resolve(program, channel, config) {
     ? 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.`);
+    throw canvasOverflowError(`The ${channel}-axis labels do not fit the Canvas margin.`, labelBounds, canvas);
   }
-  if (config.overlap === "error" && orderedBounds.some((item, index) => index > 0 &&
-    textBoundsIntersect(orderedBounds[index - 1], item))) {
+  if (config.overlap === "error" && orderedBounds.some((item, index) => rotatedOverlap
+    ? orderedBounds.slice(0, index).some(previous => textBoundsIntersect(previous, item))
+    : index > 0 && textBoundsIntersect(orderedBounds[index - 1], item))) {
     throw new Error(`The ${channel}-axis labels overlap each other.`);
   }
   const title = program.graphicSpec.objects[`${channel}AxisTitle`]
@@ -333,7 +404,7 @@ function makeEdit(channel) {
       ...(explicitMode ? { inferredValues: false } : {}),
       mode
     }, args, op);
-    config = normalizeAxisLabelMap(this, config, args, op);
+    config = normalizeAxisLabelMaps(this, config, args, op);
     if (mode === "values") delete config.count; else delete config.values;
     validateConfig(channel, config);
     assertTickCompatibility(this.guideConfigs.axis?.[channel]?.ticks, config, op);
@@ -344,7 +415,9 @@ function makeEdit(channel) {
       x: resolved.x,
       y: resolved.y,
       text: resolved.text,
-      fill: config.color,
+      fill: config.colorMap === undefined ? config.color
+        : resolved.text.map((_, index) => resolveDisplayLabelColor(
+          resolved.values[resolved.groups[index]], config.colorMap, config.color)),
       fontSize: config.fontSize,
       fontFamily: config.fontFamily,
       fontWeight: config.fontWeight,
@@ -399,6 +472,7 @@ function makeCreate(channel) {
       fontSize: DEFAULTS.fontSize,
       fontFamily: DEFAULTS.fontFamily,
       fontWeight: DEFAULTS.fontWeight,
+      ...axisThemeTypography(this.materializationConfigs.theme, "labels"),
       rotation: DEFAULTS.rotation,
       overlap: DEFAULTS.overlap,
       ...args,
@@ -406,7 +480,7 @@ function makeCreate(channel) {
         (ticks?.inferredValues === true || inferredDiscreteValues !== undefined),
       mode
     }, args, op);
-    config = normalizeAxisLabelMap(this, config, args, op);
+    config = normalizeAxisLabelMaps(this, config, args, op);
     if (mode === "values") {
       config.values ??= ticks?.values ?? inferredDiscreteValues;
     } else {

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

@@ -1,3 +1,4 @@
+import { requireSemanticScale } from "../../../selectors/scales.js";
 import { editGraphicProperties } from "../../primitives/graphicProperties.js";
 import { isSourceOwnedText } from "../../../grammar/text.js";
 import { withGuideLayoutValidation } from "../../../materialization/guides/layout.js";
@@ -8,7 +9,7 @@ import {
   validateNonEmptyString,
   validateNonNegativeFinite
 } from "../../../core/validation.js";
-import { resolveGuideCoordinateBounds } from "../../../materialization/coordinateBounds.js";
+import { axisScaleBindings, resolveGuideCoordinateBounds } from "../../../materialization/coordinateBounds.js";
 import { DEFAULT_COLORS } from "../../../theme/defaults.js";
 import {
   defaultAxisPosition,
@@ -27,10 +28,10 @@ function validateStyle({ color, lineWidth }) {
   validateNonNegativeFinite(lineWidth, "Axis lineWidth");
 }
 
-function resolveLineRange(resolvedScale, bounds, channel) {
+function resolveLineRange(resolvedScale, bounds, channel, explicitRange) {
   const range = resolvedScale?.range;
   if (
-    resolvedScale?.type !== "time" ||
+    explicitRange || resolvedScale?.type !== "time" ||
     !Number.isFinite(resolvedScale.bandwidth)
   ) return range;
   const plotRange = channel === "x"
@@ -46,7 +47,7 @@ function resolveGeometry(program, channel, scaleId, position) {
     layer => !isSourceOwnedText(layer) && layer.encoding?.[channel]?.scale === scaleId
   );
 
-  if (!hasConsumer) {
+  if (!hasConsumer && !axisScaleBindings(program, scaleId).some(binding => binding.channel === channel)) {
     throw new Error(
       `Axis line requires scale "${scaleId}" on the ${channel} channel.`
     );
@@ -75,7 +76,7 @@ function resolveGeometry(program, channel, scaleId, position) {
     bounds,
     channel,
     position,
-    resolveLineRange(resolvedScale, bounds, channel)
+    resolveLineRange(resolvedScale, bounds, channel, Array.isArray(requireSemanticScale(program, scaleId).range))
   );
 }
 

package/src/actions/guides/axes/parallel/lifecycle.js

@@ -68,7 +68,7 @@ function makeAxisAction(create) {
       ? { mode: "selected", dimensions: resolved.dimensions.map(dimension => ({ field: dimension.field })) }
       : resolveParallelAxisConfigs(this, resolved.dimensions);
     const previous = config.dimensions.find(dimension => dimension.field === args.field);
-    const updated = patchParallelAxis(previous, args, create, operation);
+    const updated = patchParallelAxis(previous, args, create, operation, this.materializationConfigs.theme);
     const next = withTitle(withOwner(this, resolved, {
       ...config, dimensions: config.dimensions.map(dimension => dimension.field === args.field ? updated : dimension)
     }), args, create);

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

@@ -1,10 +1,11 @@
+import { axisThemeTypography } from "../../../theme/state.js";
 import {
   validateGeneratedItemLimit,
   validateNonEmptyString,
   validateNonNegativeFinite,
   validateOptionObject
 } from "../../../../core/validation.js";
-import { DEFAULT_COLORS, DEFAULT_FONT_FAMILY } from "../../../../theme/defaults.js";
+import { AXIS_LABEL_FONT_SIZES, AXIS_TITLE_FONT_SIZE, DEFAULT_COLORS, DEFAULT_FONT_FAMILY } from "../../../../theme/defaults.js";
 import { validateAxisTextStyle } from "../labels.js";
 import { validateAxisFormat } from "../policy.js";
 
@@ -20,15 +21,15 @@ const STYLE_OPTIONS = Object.freeze({
   title: ["text", "offset", "color", "fontSize", "fontFamily", "fontWeight"]
 });
 
-export function defaultParallelAxis(field) {
+export function defaultParallelAxis(field, theme) {
   return {
     field,
     line: { color: DEFAULT_COLORS.axis, lineWidth: 1.25 },
     ticks: { mode: "auto", length: 8, color: DEFAULT_COLORS.mutedText, lineWidth: 1 },
     labels: { mode: "auto", offset: 9, format: "auto", color: DEFAULT_COLORS.axis,
-      fontSize: 11, fontFamily: DEFAULT_FONT_FAMILY, fontWeight: "normal" },
+      fontSize: AXIS_LABEL_FONT_SIZES.parallel, fontFamily: DEFAULT_FONT_FAMILY, fontWeight: "normal", ...axisThemeTypography(theme, "labels") },
     title: { offset: 20, color: DEFAULT_COLORS.axisTitle,
-      fontSize: 13, fontFamily: DEFAULT_FONT_FAMILY, fontWeight: 600 }
+      fontSize: AXIS_TITLE_FONT_SIZE, fontFamily: DEFAULT_FONT_FAMILY, fontWeight: 600, ...axisThemeTypography(theme, "title") }
   };
 }
 
@@ -98,8 +99,8 @@ function patchComponent(previous, defaults, options, part, create, operation) {
   return next;
 }
 
-export function patchParallelAxis(previous, args, create, operation) {
-  const defaults = defaultParallelAxis(args.field);
+export function patchParallelAxis(previous, args, create, operation, theme) {
+  const defaults = defaultParallelAxis(args.field, theme);
   const next = { ...previous, field: args.field };
   const updates = {};
   for (const part of ["line", "title"]) {
@@ -132,6 +133,6 @@ export function resolveParallelAxisConfigs(program, dimensions) {
   const previous = program.guideConfigs.axis?.parallel?.axes;
   const mode = previous?.mode ?? "all";
   const configs = dimensions.map(dimension => previous?.dimensions?.find(config => config.field === dimension.field) ??
-    (mode === "all" ? defaultParallelAxis(dimension.field) : { field: dimension.field }));
+    (mode === "all" ? defaultParallelAxis(dimension.field, program.materializationConfigs.theme) : { field: dimension.field }));
   return { mode, dimensions: configs };
 }

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

@@ -1,3 +1,4 @@
+import { withGuideLayoutValidation } from "../../../materialization/guides/layout.js";
 import { action } from "../../../core/action.js";
 import { validateKeys } from "../../../core/validation.js";
 import { axisGraphicIds } from
@@ -20,7 +21,7 @@ function makeRemoveAxis(channel) {
       op: operation,
       description: `Remove the complete ${channel}-axis resource.`
     },
-    function (args = {}) {
+    withGuideLayoutValidation(function (args = {}) {
       validateKeys(args, OPTIONS, operation);
       const semantic = this.semanticSpec.guides.axis?.[channel];
       const config = this.guideConfigs.axis?.[channel];
@@ -50,7 +51,7 @@ function makeRemoveAxis(channel) {
         }
       }
       return next._withoutMaterializationConfig(["guides", "axis", channel]);
-    }
+    })
   );
 }
 

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

@@ -18,7 +18,7 @@ const EDIT_OPTIONS = Object.freeze([
   "ticks",
   "labels"
 ]);
-const TICK_OPTIONS = Object.freeze(["length", "color", "lineWidth"]);
+const TICK_OPTIONS = Object.freeze(["length", "color", "lineWidth", "alongOffset"]);
 const LABEL_OPTIONS = Object.freeze([
   "offset",
   "format",
@@ -31,7 +31,10 @@ const LABEL_OPTIONS = Object.freeze([
   "wrap",
   "lineHeight",
   "overlap",
-  "labelMap"
+  "labelMap",
+  "alongOffset",
+  "flush",
+  "colorMap"
 ]);
 const SHARED_CREATE = Object.freeze(["scale", "position", "count", "values"]);
 const SHARED_EDIT = Object.freeze(["position", "count", "values"]);

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

@@ -1,3 +1,4 @@
+import { canvasOverflowError } from "../../../layout/canvas.js";
 import { editGraphicProperties } from "../../primitives/graphicProperties.js";
 import { withGuideLayoutValidation } from "../../../materialization/guides/layout.js";
 import { applyMaterializationPlan } from "../../../materialization/planner.js";
@@ -31,7 +32,7 @@ import {
 import { findCanvasGraphic, resolvePlotGraphicPlacement } from
   "../../../materialization/graphicHierarchy.js";
 
-const OPTIONS = Object.freeze(["scale", "position", "count", "values", "length", "color", "lineWidth"]);
+const OPTIONS = Object.freeze(["scale", "position", "count", "values", "length", "color", "lineWidth", "alongOffset"]);
 const DEFAULTS = Object.freeze({
   count: DEFAULT_TICK_COUNT,
   length: 6,
@@ -45,6 +46,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");
@@ -65,6 +67,7 @@ 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");
@@ -102,7 +105,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 +130,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;
 }