ggaction 0.0.17 → 0.0.19

package/src/actions/selection/actions.js

@@ -19,7 +19,6 @@ import {
   findSelectionPolicy,
   requireSelectionPolicy
 } from "../../materialization/selection/policies/index.js";
-import { legendGraphicIds } from "../../materialization/guides/resources.js";
 import {
   normalizeDimOthers,
   validateUnitInterval
@@ -84,18 +83,7 @@ function categoricalLegendKinds(program, target) {
 function resetCategoricalLegendSymbols(program, target) {
   const kinds = categoricalLegendKinds(program, target);
   if (kinds.length === 0) return program;
-  let next = program;
-  for (const kind of kinds) {
-    for (const id of legendGraphicIds(kind).filter(id => id.includes("Symbol"))) {
-      const graphic = next.graphicSpec.objects[id];
-      if (graphic === undefined) continue;
-      next = graphic.type === "collection"
-        ? next.editGraphics({ target: id, property: "items", value: [] })
-        : next.editGraphics({ target: id, property: "length", value: 0 });
-    }
-    next = next.rematerializeLegendSymbols({ kind });
-  }
-  return next;
+  return program.rematerializeLegend();
 }
 
 function targetHighlightEntries(program, target) {

package/src/actions/theme/reconcile.js

@@ -1,5 +1,6 @@
+import { synchronizeFacetLegendAppearance } from "../../materialization/facetGuides/owner.js";
 import { rematerializeTypography } from "../../materialization/typography.js";
-import { themeTokens } from "../../theme/defaults.js";
+import { AXIS_LABEL_FONT_SIZES, AXIS_TITLE_FONT_SIZE, themeTokens } from "../../theme/defaults.js";
 import {
   normalizeThemeState,
   resolveEffectiveThemeTokens,
@@ -21,7 +22,7 @@ const THEME_STYLE_PROPERTIES = Object.freeze([
   "background",
   "fill",
   "stroke",
-  "fontFamily"
+  "fontFamily", "fontSize"
 ]);
 const COLOR_TOKENS = Object.freeze([
   "mark",
@@ -51,15 +52,38 @@ function tokenFor(value, sourceTokens, targetTokens) {
   return matches[0];
 }
 
-function roleValues(role, sourceTokens, legacy = []) {
+function axisFamily(name) {
+  return name.startsWith("parallel") ? "parallel"
+    : /^(theta|radial|radius)/u.test(name) ? "polar" : "cartesian";
+}
+
+function axisTextRole(property, component) {
+  if (!["labels", "title"].includes(component)) return undefined;
+  const role = component === "labels" ? "axisLabel" : "axisTitle";
+  if (property === "fontFamily") return `${role}FontFamily`;
+  if (property === "fontSize") return `${role}FontSize`;
+  if (["fill", "color"].includes(property)) return role;
+  return undefined;
+}
+
+function roleToken(tokens, role, family = "cartesian") {
+  if (tokens[role] !== undefined) return tokens[role];
+  if (role === "axisLabel") return family === "parallel" ? tokens.axis : tokens.text;
+  if (["axisLabelFontFamily", "axisTitleFontFamily"].includes(role)) return tokens.fontFamily;
+  if (role === "axisLabelFontSize") return AXIS_LABEL_FONT_SIZES[family];
+  if (role === "axisTitleFontSize") return AXIS_TITLE_FONT_SIZE;
+  return undefined;
+}
+
+function roleValues(role, sourceTokens, legacy = [], family) {
   return new Set([
-    sourceTokens[role],
-    themeTokens("light")[role],
+    roleToken(sourceTokens, role, family),
+    roleToken(themeTokens("light"), role, family),
     ...legacy.map(token => themeTokens("light")[token] ?? token)
   ]);
 }
 
-function mapRoleValue(value, role, sourceTokens, targetTokens, legacy) {
+function mapRoleValue(value, role, sourceTokens, targetTokens, legacy, family) {
   if (Array.isArray(value)) {
     let changed = false;
     const next = value.map(item => {
@@ -68,17 +92,18 @@ function mapRoleValue(value, role, sourceTokens, targetTokens, legacy) {
         role,
         sourceTokens,
         targetTokens,
-        legacy
+        legacy, family
       );
       changed ||= mapped.changed;
       return mapped.value;
     });
     return { changed, value: changed ? next : value };
   }
-  if (!roleValues(role, sourceTokens, legacy).has(value)) {
+  if (!roleValues(role, sourceTokens, legacy, family).has(value)) {
     return { changed: false, value };
   }
-  return { changed: value !== targetTokens[role], value: targetTokens[role] };
+  const target = roleToken(targetTokens, role, family);
+  return { changed: value !== target, value: target };
 }
 
 function mapColorValue(value, sourceTokens, targetTokens) {
@@ -158,6 +183,9 @@ function componentRole(program, id, property) {
 }
 
 function graphicRole(program, id, property) {
+  const axisPart = /(?:Axis|^axis_.+__)(Labels|Titles?)$/u.exec(id);
+  const scoped = axisPart === null ? undefined : axisTextRole(property, axisPart[1] === "Labels" ? "labels" : "title");
+  if (scoped !== undefined) return scoped;
   if (property === "fontFamily") return "fontFamily";
   if (id === "canvas" && property === "background") return "background";
   if (id === `${program.compositionSpec?.id}-headers` && property === "fill") {
@@ -173,11 +201,11 @@ function graphicRole(program, id, property) {
     }
     return layer.mark?.type === "text" ? "text" : "mark";
   }
-  if (/AxisLines?$/u.test(id) && property === "stroke") return "axis";
-  if (/AxisTicks$/u.test(id) && property === "stroke") return "mutedText";
+  if (/(?:Axis|^axis_.+__)Lines?$/u.test(id) && property === "stroke") return "axis";
+  if (/(?:Axis|^axis_.+__)Ticks$/u.test(id) && property === "stroke") return "mutedText";
   if (/^parallelAxisLabels$/u.test(id) && property === "fill") return "axis";
-  if (/AxisLabels$/u.test(id) && property === "fill") return "text";
-  if (/AxisTitles?$/u.test(id) && property === "fill") return "axisTitle";
+  if (/(?:Axis|^axis_.+__)Labels$/u.test(id) && property === "fill") return "text";
+  if (/(?:Axis|^axis_.+__)Titles?$/u.test(id) && property === "fill") return "axisTitle";
   if (/Grid(?:Lines|Circles)?$/u.test(id) && property === "stroke") return "grid";
   if (id === "chartTitle" && property === "fill") return "strongText";
   if (id === "chartSubtitle" && property === "fill") return "mutedText";
@@ -198,6 +226,7 @@ function graphicRole(program, id, property) {
 }
 
 function roleLegacy(role) {
+  if (role === "axisLabel") return ["text", "axis"];
   if (role === "axis") return ["text"];
   if (role === "axisTitle") return ["text", "strongText"];
   if (role === "strongText") return ["text"];
@@ -238,7 +267,7 @@ function mapGraphicProperties(
       role,
       sourceTokens,
       targetTokens,
-      roleLegacy(role)
+      roleLegacy(role), axisFamily(id)
     );
     if (mapped.changed) {
       next[property] = mapped.value;
@@ -304,6 +333,11 @@ function recolorGraphic(
 
 function configRole(program, path) {
   const property = path.at(-1);
+  if (path[0] === "guides" && path[1] === "axis") {
+    const component = path[2] === "parallel" ? path.at(-2) : path[3];
+    const scoped = axisTextRole(property, component);
+    if (scoped !== undefined) return scoped;
+  }
   if (property === "fontFamily") return "fontFamily";
   if (path[0] === "facets" && path.includes("headers") &&
       property === "color") {
@@ -369,7 +403,7 @@ function recolorConfig(
   }
   if (value === null || typeof value !== "object") {
     const property = path.at(-1);
-    if (!["color", "fill", "stroke", "background", "fontFamily"]
+    if (!["color", "fill", "stroke", "background", "fontFamily", "fontSize"]
       .includes(property)) {
       return { changed: false, value };
     }
@@ -387,7 +421,7 @@ function recolorConfig(
           role,
           sourceTokens,
           targetTokens,
-          roleLegacy(role)
+          roleLegacy(role), axisFamily(String(path[2] ?? ""))
         );
   }
   if (["theme", "highlights", "selections"].includes(path[0])) {
@@ -643,12 +677,13 @@ function clearRemovedResources(overrides, node) {
       clearPrefix(overrides, `g:${mark[1]}.`);
       return;
     }
-    const axis = /^guide\.axis\.(x|y|theta|radius)$/u
+    const axis = /^guide\.axis\.([A-Za-z0-9_-]+)$/u
       .exec(current.args.property);
     if (axis !== null) {
       const prefix = axis[1] === "radius" ? "radial" : axis[1];
+      const graphicPrefix = ["x", "y", "theta", "radius"].includes(axis[1]) ? `${prefix}Axis` : `axis_${axis[1]}__`;
       clearPrefix(overrides, `c:guides.axis.${axis[1]}.`);
-      clearPrefix(overrides, `g:${prefix}Axis`);
+      clearPrefix(overrides, `g:${graphicPrefix}`);
       return;
     }
     const grid = /^guide\.grid\.([^\.]+)$/u.exec(current.args.property);
@@ -704,7 +739,23 @@ function clearRecreatedOverrides(overrides, op, args) {
   }
 }
 
-function addAxisOverrides(overrides, op, args) {
+function axisOverrideId(node, channel, args) {
+  if (args.target !== undefined || args.id !== undefined) return args.target ?? args.id;
+  const ids = new Set();
+  const visit = entry => {
+    if (["createGraphics", "editGraphics"].includes(entry.op)) {
+      const id = entry.args.target ?? entry.args.id;
+      const named = /^axis_(.+)__(Line|Ticks|Labels|Title)$/u.exec(id ?? "");
+      if (named !== null) ids.add(named[1]);
+      else if (new RegExp(`^${channel}Axis(?:Line|Ticks|Labels|Title)$`).test(id ?? "")) ids.add(channel);
+    }
+    entry.children?.forEach(visit);
+  };
+  if (node !== undefined) visit(node);
+  return ids.size === 1 ? [...ids][0] : channel;
+}
+
+function addAxisOverrides(overrides, op, args, node) {
   const match = /^(?:create|edit)(X|Y|Theta|Radial)Axis(Line|Ticks|Labels|Title)$/u
     .exec(op);
   if (match === null) return;
@@ -715,22 +766,25 @@ function addAxisOverrides(overrides, op, args) {
     Radial: "radius"
   }[match[1]];
   const component = match[2].toLowerCase();
+  const axisId = axisOverrideId(node, channel, args);
   const idPrefix = match[1] === "Radial" ? "radial" : channel;
   if (Object.hasOwn(args, "color")) {
-    overrides.add(`c:guides.axis.${channel}.${component}.color`);
+    overrides.add(`c:guides.axis.${axisId}.${component}.color`);
     overrides.add(
-      `g:${idPrefix}Axis${match[2]}.${component === "line" || component === "ticks" ? "stroke" : "fill"}`
+      `g:${axisId === channel ? `${idPrefix}Axis` : `axis_${axisId}__`}${match[2]}.${component === "line" || component === "ticks" ? "stroke" : "fill"}`
     );
   }
-  if (["labels", "title"].includes(component) &&
-      Object.hasOwn(args, "fontFamily")) {
-    overrides.add(`c:guides.axis.${channel}.${component}.fontFamily`);
-    overrides.add(`g:${idPrefix}Axis${match[2]}.fontFamily`);
+  for (const property of ["fontFamily", "fontSize"]) {
+    if (["labels", "title"].includes(component) && Object.hasOwn(args, property)) {
+      overrides.add(`c:guides.axis.${axisId}.${component}.${property}`);
+      overrides.add(`g:${axisId === channel ? `${idPrefix}Axis` : `axis_${axisId}__`}${match[2]}.${property}`);
+    }
   }
 }
 
-function addCompleteAxisOverride(overrides, name, args) {
+function addCompleteAxisOverride(overrides, name, args, node) {
   const channel = { X: "x", Y: "y", Theta: "theta", Radial: "radius" }[name];
+  const axisId = axisOverrideId(node, channel, args);
   const idPrefix = name === "Radial" ? "radial" : channel;
   const components = {
     line: args.line,
@@ -745,25 +799,32 @@ function addCompleteAxisOverride(overrides, name, args) {
   for (const [component, options] of Object.entries(components)) {
     const suffix = `${component[0].toUpperCase()}${component.slice(1)}`;
     if (Object.hasOwn(options ?? {}, "color")) {
-      overrides.add(`c:guides.axis.${channel}.${component}.color`);
+      overrides.add(`c:guides.axis.${axisId}.${component}.color`);
       overrides.add(
-        `g:${idPrefix}Axis${suffix}.${component === "line" || component === "ticks" ? "stroke" : "fill"}`
+        `g:${axisId === channel ? `${idPrefix}Axis` : `axis_${axisId}__`}${suffix}.${component === "line" || component === "ticks" ? "stroke" : "fill"}`
       );
     }
-    if (["labels", "title"].includes(component) &&
-        Object.hasOwn(options ?? {}, "fontFamily")) {
-      overrides.add(`c:guides.axis.${channel}.${component}.fontFamily`);
-      overrides.add(`g:${idPrefix}Axis${suffix}.fontFamily`);
+    for (const property of ["fontFamily", "fontSize"]) {
+      if (["labels", "title"].includes(component) && Object.hasOwn(options ?? {}, property)) {
+        overrides.add(`c:guides.axis.${axisId}.${component}.${property}`);
+        overrides.add(`g:${axisId === channel ? `${idPrefix}Axis` : `axis_${axisId}__`}${suffix}.${property}`);
+      }
     }
   }
 }
 
-function addCompleteAxisOverrides(overrides, op, args) {
+function addCompleteAxisOverrides(overrides, op, args, node) {
+  if (args.guides?.axes !== null && typeof args.guides?.axes === "object") {
+    addCompleteAxisOverrides(overrides, "createAxes", args.guides.axes);
+  }
+  if (op === "createGuides" && args.axes !== null && typeof args.axes === "object") {
+    addCompleteAxisOverrides(overrides, "createAxes", args.axes);
+  }
   const match = /^(?:create|edit)(X|Y|Theta|Radial)Axis$/u.exec(op);
-  if (match !== null) addCompleteAxisOverride(overrides, match[1], args);
+  if (match !== null) addCompleteAxisOverride(overrides, match[1], args, node);
   const group = /^(?:create|edit)(X|Y)AxisTicksAndLabels$/u.exec(op);
   if (group !== null) {
-    addCompleteAxisOverride(overrides, group[1], { ticksAndLabels: args });
+    addCompleteAxisOverride(overrides, group[1], { target: args.target, ticksAndLabels: args }, node);
   }
   if (op !== "createAxes") return;
   for (const [option, name] of [
@@ -773,7 +834,7 @@ function addCompleteAxisOverrides(overrides, op, args) {
     ["radius", "Radial"]
   ]) {
     if (args[option] && typeof args[option] === "object") {
-      addCompleteAxisOverride(overrides, name, args[option]);
+      for (const entry of Array.isArray(args[option]) ? args[option] : [args[option]]) addCompleteAxisOverride(overrides, name, entry);
     }
   }
 }
@@ -823,11 +884,10 @@ function addParallelOverrides(overrides, program, op, args) {
         `c:guides.axis.parallel.axes.dimensions.${index}.${component}.color`
       );
     }
-    if (["labels", "title"].includes(component) &&
-        Object.hasOwn(options ?? {}, "fontFamily")) {
-      overrides.add(
-        `c:guides.axis.parallel.axes.dimensions.${index}.${component}.fontFamily`
-      );
+    for (const property of ["fontFamily", "fontSize"]) {
+      if (["labels", "title"].includes(component) && Object.hasOwn(options ?? {}, property)) {
+        overrides.add(`c:guides.axis.parallel.axes.dimensions.${index}.${component}.${property}`);
+      }
     }
   }
 }
@@ -921,7 +981,7 @@ function explicitOverrides(program, node) {
   const overrides = new Set();
   if (op === "editGraphics" &&
       typeof args.target === "string" &&
-      ["background", "fill", "stroke", "fontFamily"].includes(args.property)) {
+      ["background", "fill", "stroke", "fontFamily", "fontSize"].includes(args.property)) {
     overrides.add(`g:${args.target}.${args.property}`);
   }
   if (["createCanvas", "editCanvas"].includes(op) &&
@@ -937,8 +997,8 @@ function explicitOverrides(program, node) {
   addErrorBarOverrides(overrides, program, node);
   addErrorBandOverrides(overrides, program, node);
   addRegressionOverrides(overrides, node);
-  addAxisOverrides(overrides, op, args);
-  addCompleteAxisOverrides(overrides, op, args);
+  addAxisOverrides(overrides, op, args, node);
+  addCompleteAxisOverrides(overrides, op, args, node);
   addGridOverrides(overrides, op, args);
   addParallelOverrides(overrides, program, op, args);
   if (["createTitle", "editTitle"].includes(op)) {
@@ -959,9 +1019,21 @@ function explicitOverrides(program, node) {
   if (op === "editLegendBlock") {
     addLegendBlockOverrides(overrides, program, args);
   }
+  const parentLegendOptions = op === "editFacetGuides" ? args.legend
+    : ["facet", "facetGrid", "repeatCharts"].includes(op) ? args.guides?.legend : undefined;
+  if (parentLegendOptions !== null && typeof parentLegendOptions === "object") {
+    addLegendOverrides(overrides, program, parentLegendOptions);
+  }
   if (op === "editFacetHeaders") {
     addFacetOverrides(overrides, program, args);
   }
+  if (["facet", "facetGrid", "repeatCharts"].includes(op) && args.headers !== undefined) {
+    const { row, column, ...common } = args.headers;
+    addFacetOverrides(overrides, program, common);
+    for (const [role, patch] of [["row", row], ["column", column]]) {
+      if (patch !== undefined) addFacetOverrides(overrides, program, { ...patch, role });
+    }
+  }
   return overrides;
 }
 
@@ -979,6 +1051,12 @@ function collectOverrides(program) {
   return overrides;
 }
 
+function axisTypographyChanged(before, after) {
+  if (before === after || after === null || typeof after !== "object") return false;
+  return Object.entries(after).some(([key, value]) => ["fontFamily", "fontSize"].includes(key)
+    ? value !== before?.[key] : axisTypographyChanged(before?.[key], value));
+}
+
 export function reconcileProgramTheme(program, { source, metadata }) {
   program = reconcileFollowingRegressions(program);
   const storedState = program.materializationConfigs.theme;
@@ -1031,9 +1109,12 @@ export function reconcileProgramTheme(program, { source, metadata }) {
     next = next._withMaterializationConfig(["facets"], configs.value.facets);
   }
 
+  if (configs.changed) next = synchronizeFacetLegendAppearance(next);
+
   const facetsChanged = configs.value.facets !==
     themed.materializationConfigs.facets;
-  const typographyChanged = sourceTokens.fontFamily !== targetTokens.fontFamily;
+  const typographyChanged = sourceTokens.fontFamily !== targetTokens.fontFamily ||
+    axisTypographyChanged(themed.guideConfigs.axis, configs.value.guides.axis);
   if (facetsChanged && next.compositionSpec?.type === "facet") {
     next = next.materializeComposition();
   } else if (typographyChanged) {

package/src/actions/theme/state.js

@@ -158,3 +158,15 @@ export function setThemeStateOverrides(state, overrides) {
     overrides: cloneAndFreeze([...overrides].sort())
   });
 }
+
+// Resolve active font defaults before guide layout validates their occupied bounds.
+export function axisThemeTypography(state, component) {
+  if (resolveEffectiveThemeFrame(state) === undefined) return {};
+  const tokens = resolveEffectiveThemeTokens(state);
+  const role = component === "labels" ? "axisLabel" : "axisTitle";
+  const fontSize = tokens[`${role}FontSize`];
+  return {
+    fontFamily: tokens[`${role}FontFamily`] ?? tokens.fontFamily,
+    ...(fontSize === undefined ? {} : { fontSize })
+  };
+}

package/src/actions/titles/actions.js

@@ -1,3 +1,4 @@
+import { paintedTitleComponent, titleTextProperties } from "../../layout/title.js";
 import { withGuideLayoutValidation } from "../../materialization/guides/layout.js";
 import { action } from "../../core/action.js";
 import { noOptions } from "../../core/validation.js";
@@ -56,24 +57,9 @@ function ensureTextShape(program, id, component) {
   return program;
 }
 
-function distributed(value, count) {
-  return count === 1 && Array.isArray(value) ? value[0] : value;
-}
-
 function editTextGraphic(program, id, component, style) {
-  const count = component.lines.length;
   let next = ensureTextShape(program, id, component);
-  for (const [property, value] of Object.entries({
-    x: distributed(component.x, count),
-    y: distributed(component.y, count),
-    text: distributed(component.lines, count),
-    fill: style.color,
-    fontSize: style.fontSize,
-    fontFamily: style.fontFamily,
-    fontWeight: style.fontWeight,
-    textAlign: component.textAlign,
-    textBaseline: "middle"
-  })) {
+  for (const [property, value] of Object.entries(titleTextProperties(component, style))) {
     next = next.editGraphics({ target: id, property, value });
   }
   if (component.explicitRotation) {
@@ -99,10 +85,11 @@ function titleTextAction(kind, create) {
     if (create && this.graphicSpec.objects[id] !== undefined) {
       throw new Error(`${op} requires a missing chart ${kind} graphic.`);
     }
-    const component = resolveTitleLayout(this, config)[kind];
-    if (component === undefined) {
+    const layout = resolveTitleLayout(this, config)[kind];
+    if (layout === undefined) {
       throw new Error(`${op} requires semantic subtitle text.`);
     }
+    const component = paintedTitleComponent(layout);
     if (!create) {
       return editTextGraphic(this, id, component, config[`${kind}Style`]);
     }

package/src/actions/titles/resolve.js

@@ -1,3 +1,7 @@
+import { textBoundsFitCanvas } from "../../core/textMetrics.js";
+import { resolveGuideCollisionBlocks } from "../../materialization/guides/resources.js";
+import { canvasOverflowError } from "../../layout/canvas.js";
+import { validateFontStyle } from "../../core/font.js";
 import { isPlainObject } from "../../core/immutable.js";
 import {
   validateKeys,
@@ -19,11 +23,11 @@ import { findCanvasGraphic } from
   "../../materialization/graphicHierarchy.js";
 
 const OPTIONS = Object.freeze([
-  "text", "subtitle", "position", "align", "offset", "gap", "titleStyle",
+  "text", "subtitle", "position", "align", "offset", "alongOffset", "gap", "titleStyle",
   "subtitleStyle", "maxWidth", "wrap", "lineHeight"
 ]);
 const STYLE_OPTIONS = Object.freeze([
-  "color", "fontSize", "fontFamily", "fontWeight"
+  "color", "fontSize", "fontFamily", "fontWeight", "fontStyle"
 ]);
 const POSITIONS = Object.freeze(["top", "bottom", "left", "right"]);
 const ALIGNS = Object.freeze(["left", "center", "right"]);
@@ -32,6 +36,7 @@ const DEFAULTS = Object.freeze({
   position: "top",
   align: "left",
   offset: 0,
+  alongOffset: 0,
   gap: 8,
   titleStyle: Object.freeze({
     color: DEFAULT_COLORS.strongText,
@@ -47,9 +52,12 @@ const DEFAULTS = Object.freeze({
   })
 });
 
-export function validateTitleString(value, label) {
+export function validateTitleString(value, label, multiline = false) {
   validateNonEmptyString(value, label);
-  if (/\r|\n/u.test(value)) {
+  if (multiline && value.split(/\r\n|\r|\n/u).every(line => line === "")) {
+    throw new Error(`${label} requires at least one non-empty line.`);
+  }
+  if (!multiline && /\r|\n/u.test(value)) {
     throw new Error(`${label} does not accept explicit newlines.`);
   }
   return value;
@@ -70,6 +78,7 @@ function normalizeStyle(value, defaults, label) {
   )) {
     throw new TypeError(`${label} fontWeight must be a non-empty string or number.`);
   }
+  if (style.fontStyle !== undefined) validateFontStyle(style.fontStyle, label);
   return style;
 }
 
@@ -78,6 +87,7 @@ function normalizeConfig(args, defaults, { hasSubtitle }) {
   const align = args.align ?? defaults.align;
   const offset = args.offset ?? defaults.offset;
   const gap = args.gap ?? defaults.gap;
+  const alongOffset = args.alongOffset ?? defaults.alongOffset ?? 0;
   const titleStyle = normalizeStyle(
     args.titleStyle,
     defaults.titleStyle,
@@ -100,6 +110,7 @@ function normalizeConfig(args, defaults, { hasSubtitle }) {
   if (!Number.isFinite(offset)) {
     throw new TypeError("Chart title offset must be a finite number.");
   }
+  if (!Number.isFinite(alongOffset)) throw new TypeError("Chart title alongOffset must be a finite number.");
   validateNonNegativeFinite(gap, "Chart title gap");
   if (maxWidth !== undefined) {
     validatePositiveFinite(maxWidth, "Chart title maxWidth");
@@ -121,6 +132,7 @@ function normalizeConfig(args, defaults, { hasSubtitle }) {
     position,
     align,
     offset,
+    alongOffset,
     gap,
     titleStyle,
     subtitleStyle,
@@ -132,10 +144,10 @@ function normalizeConfig(args, defaults, { hasSubtitle }) {
 
 export function normalizeTitleOptions(args) {
   validateOptionObject(args, OPTIONS, "createTitle");
-  const text = validateTitleString(args.text, "Chart title text");
+  const text = validateTitleString(args.text, "Chart title text", true);
   const subtitle = args.subtitle === undefined
     ? undefined
-    : validateTitleString(args.subtitle, "Chart subtitle");
+    : validateTitleString(args.subtitle, "Chart subtitle", true);
   return {
     text,
     subtitle,
@@ -151,12 +163,12 @@ export function normalizeTitleEditOptions(args, previous, semanticTitle) {
   });
   const text = args.text === undefined
     ? semanticTitle.text
-    : validateTitleString(args.text, "Chart title text");
+    : validateTitleString(args.text, "Chart title text", true);
   const subtitle = args.subtitle === false
     ? undefined
     : args.subtitle === undefined
       ? semanticTitle.subtitle
-      : validateTitleString(args.subtitle, "Chart subtitle");
+      : validateTitleString(args.subtitle, "Chart subtitle", true);
   if (args.subtitle !== undefined && args.subtitle !== false && typeof args.subtitle !== "string") {
     throw new TypeError("Chart subtitle must be a non-empty string or false.");
   }
@@ -175,11 +187,8 @@ export function requireTitleConfig(program) {
 }
 
 function validateLayout(position, titleBounds, plot, canvas) {
-  if (
-    titleBounds.left < 0 || titleBounds.top < 0 ||
-    titleBounds.right > canvas.width || titleBounds.bottom > canvas.height
-  ) {
-    throw new Error(`Chart title requires more ${position}-margin space.`);
+  if (!textBoundsFitCanvas(titleBounds, canvas)) {
+    throw canvasOverflowError(`Chart title requires more ${position}-margin space.`, [titleBounds], canvas);
   }
   const outsidePlot = {
     top: titleBounds.bottom <= plot.y,
@@ -205,19 +214,31 @@ export function resolveTitleLayout(program, config) {
     throw new Error("Chart title layout requires Canvas bounds and dimensions.");
   }
   const block = buildTitleReadingBlock({
-    text: validateTitleString(program.semanticSpec.title.text, "Chart title text"),
+    text: validateTitleString(program.semanticSpec.title.text, "Chart title text", true),
     subtitle: program.semanticSpec.title.subtitle === undefined
       ? undefined
       : validateTitleString(
           program.semanticSpec.title.subtitle,
-          "Chart subtitle"
+          "Chart subtitle", true
         )
   }, config, program.materializationConfigs.textMetrics);
+  const automatic = program.materializationConfigs.canvas?.plot !== undefined;
+  const near = ["top", "left"].includes(config.position);
   const horizontal = ["top", "bottom"].includes(config.position);
+  let titleEdge = horizontal ? plot.y + (near ? 0 : plot.height)
+    : plot.x + (near ? 0 : plot.width);
+  if (automatic) {
+    const occupied = resolveGuideCollisionBlocks(program.graphicSpec, program.guideConfigs,
+      undefined, program.materializationConfigs.textMetrics).filter(item => item.position === config.position);
+    const key = horizontal ? (near ? "top" : "bottom") : (near ? "left" : "right");
+    for (const item of occupied) titleEdge = near ? Math.min(titleEdge, item.bounds[key]) : Math.max(titleEdge, item.bounds[key]);
+    titleEdge += (near ? -1 : 1) * (16 + config.offset);
+  }
   let component;
   if (horizontal) {
-    const x = alignedTextAnchor(plot.x, plot.width, config.align);
-    const blockTop = config.position === "top"
+    const x = alignedTextAnchor(plot.x, plot.width, config.align) + (config.alongOffset ?? 0);
+    const blockTop = automatic ? titleEdge - (near ? block.height : 0)
+      : config.position === "top"
       ? 16 + config.offset
       : plot.y + plot.height + config.offset;
     component = (lines, centers) => ({
@@ -230,8 +251,9 @@ export function resolveTitleLayout(program, config) {
     });
   } else {
     const rotation = config.position === "left" ? -Math.PI / 2 : Math.PI / 2;
-    const y = alignedTitleAnchor(plot.y, plot.height, block.width, config.align);
-    const edge = config.position === "left"
+    const y = alignedTitleAnchor(plot.y, plot.height, block.width, config.align) + (config.alongOffset ?? 0);
+    const edge = automatic ? titleEdge + (near ? -block.height : block.height)
+      : config.position === "left"
       ? 16 + config.offset
       : canvas.properties.width - 16 + config.offset;
     const mapX = value => config.position === "left" ? edge + value : edge - value;

package/src/actions/violinPlots/edit.js

@@ -2,7 +2,7 @@ import { action } from "../../core/action.js";
 import { validateUserId } from "../../core/identifiers.js";
 import { validateKeys } from "../../core/validation.js";
 import { findDataset } from "../../selectors/datasets.js";
-import { findLayer } from "../../selectors/layers.js";
+import { findLayer, resolveConfiguredOwner } from "../../selectors/layers.js";
 import { rebindDistributionGuides } from "../distributions/revision.js";
 import {
   resolveViolinDensity,
@@ -15,24 +15,7 @@ const OPTIONS = Object.freeze([
   "target", "data", "x", "y", "split", "density"
 ]);
 
-function resolveOwner(program, requested) {
-  const eligible = program.semanticSpec.layers.filter(
-    layer => program.markConfigs[layer.id]?.violinPlot?.materialized === true
-  );
-  if (requested !== undefined) {
-    const id = validateUserId(requested, "Violin-plot owner id");
-    const layer = findLayer(program, id);
-    if (layer === undefined || !eligible.includes(layer)) {
-      throw new Error(`Unknown violin-plot owner "${id}".`);
-    }
-    return layer;
-  }
-  const current = findLayer(program, program.context.currentMark);
-  if (current !== undefined && eligible.includes(current)) return current;
-  if (eligible.length === 1) return eligible[0];
-  if (eligible.length === 0) throw new Error(`${OPERATION} requires a violin plot.`);
-  throw new Error(`${OPERATION} target is ambiguous; provide target.`);
-}
+
 
 function currentPosition(owner, current, channel) {
   const categorical = current.orientation === "vertical"
@@ -84,7 +67,7 @@ export const editViolinPlot = /* @__PURE__ */ action(
     if (!OPTIONS.slice(1).some(key => Object.hasOwn(args, key))) {
       throw new Error(`${OPERATION} requires at least one violin-plot option.`);
     }
-    const owner = resolveOwner(this, args.target);
+    const owner = resolveConfiguredOwner(this, args.target, { config: "violinPlot", operation: OPERATION, kind: "violin", materialized: true }, validateUserId);
     const current = this.markConfigs[owner.id].violinPlot;
     const source = Object.hasOwn(args, "data")
       ? validateUserId(args.data, "Violin-plot data id")