ggaction 0.0.23 → 0.0.24

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

@@ -141,6 +141,38 @@ function geometry(program, channel, config, axisId = channel) {
   return resolved;
 }
 
+export function resolveAxisTickEditConfig(program, channel, args, axisId = channel) {
+  const op = channel === "x" ? "editXAxisTicks" : "editYAxisTicks";
+  validateOptions(args, op, false);
+  const previous = program.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
+    ? inferHistogramBoundaries(program, channel, previous.scale) ??
+      (["ordinal", "band", "point"].includes(
+        program.resolvedScales[previous.scale]?.type
+      )
+        ? program.resolvedScales[previous.scale].domain
+        : undefined)
+    : undefined;
+  const mode = Object.hasOwn(args, "values") || inferredValues !== undefined
+    ? "values"
+    : Object.hasOwn(args, "count") ? "count" : previous.mode;
+  const config = patchGuideDash({
+    ...previous,
+    ...args,
+    ...(inferredValues === undefined ? {} : { values: inferredValues }),
+    ...(explicitMode ? { inferredValues: false } : {}),
+    mode
+  }, args);
+  if (mode === "values") {
+    delete config.count;
+    if (!Object.hasOwn(args, "rounding")) delete config.rounding;
+  } else delete config.values;
+  validateConfig(channel, config);
+  return config;
+}
+
 function makeEdit(channel) {
   const op = channel === "x" ? "editXAxisTicks" : "editYAxisTicks";
   return action({ op, description: `Edit concrete ${channel}-axis ticks.` }, withGuideLayoutValidation(function (args = {}) {
@@ -149,32 +181,9 @@ function makeEdit(channel) {
     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 config = resolveAxisTickEditConfig(this, channel, args, axisId);
     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
-      ? inferHistogramBoundaries(this, channel, previous.scale) ??
-        (["ordinal", "band", "point"].includes(
-          this.resolvedScales[previous.scale]?.type
-        )
-          ? this.resolvedScales[previous.scale].domain
-          : undefined)
-      : undefined;
-    const mode = Object.hasOwn(args, "values") || inferredValues !== undefined
-      ? "values"
-      : Object.hasOwn(args, "count") ? "count" : previous.mode;
-    const config = patchGuideDash({
-      ...previous,
-      ...args,
-      ...(inferredValues === undefined ? {} : { values: inferredValues }),
-      ...(explicitMode ? { inferredValues: false } : {}),
-      mode
-    }, args);
-    if (mode === "values") {
-      delete config.count;
-      if (!Object.hasOwn(args, "rounding")) delete config.rounding;
-    } else delete config.values;
-    validateConfig(channel, config);
     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] });

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

@@ -1,389 +1 @@
-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, axisTitleAllowsLabelOverlap } 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
-} from "../../../core/validation.js";
-import { axisScaleBindings, resolveCartesianAxisFrameBounds } from "../../../materialization/coordinateBounds.js";
-import {
-  isTransformedScaleType,
-  mapContinuousScaleValues,
-  mapOrdinalPositionValues
-} from "../../../grammar/scales/index.js";
-import { AXIS_TITLE_FONT_SIZE, DEFAULT_COLORS, DEFAULT_FONT_FAMILY } from
-  "../../../theme/defaults.js";
-import { findDataset } from "../../../selectors/datasets.js";
-import { findUpstreamTransform } from "../../../materialization/dataProvenance.js";
-import { formatAggregateTitle } from "../../../grammar/aggregate.js";
-import { finiteMidpoint } from "../../../grammar/numeric.js";
-import {
-  defaultAxisPosition,
-  defaultAxisTitleRotation,
-  resolveAxisTitleGeometry,
-  validateAxisPosition
-} from "./policy.js";
-import { findCanvasGraphic, resolvePlotGraphicPlacement } from
-  "../../../materialization/graphicHierarchy.js";
-import {
-  resolveTextBounds,
-  textBoundsFitCanvas,
-  textBoundsIntersect
-} from "../../../core/textMetrics.js";
-import { resolveConcreteGraphicBounds } from
-  "../../../grammar/schemas/graphicBounds.js";
-import { validateAxisTextStyle } from "./labels.js";
-import { resolveRotation } from "../../../grammar/rotation.js";
-
-function titleBounds(geometry, config, text, profile) {
-  return resolveTextBounds({
-    ...geometry,
-    text,
-    lines: titleLines(text, config),
-    fontSize: config.fontSize,
-    fontFamily: config.fontFamily,
-    fontWeight: config.fontWeight,
-    textAlign: config.align ?? "center",
-    textBaseline: config.baseline ?? "middle",
-    rotation: config.rotation
-  }, profile);
-}
-
-function resolveTitleAlong(scale, config) {
-  const discrete = ["ordinal", "band", "point"].includes(scale?.type);
-  let along;
-  if (config.at === "center") {
-    along = finiteMidpoint(scale.range[0], scale.range[1]);
-  } else if (config.at === "start" || config.at === "end") {
-    along = scale.range[config.at === "start" ? 0 : 1];
-  } else {
-    if (discrete) {
-      if (!scale.domain.includes(config.at)) throw new RangeError("Axis title at value must be inside the scale domain.");
-      along = mapOrdinalPositionValues([config.at], scale)[0];
-    } else {
-      const low = Math.min(...scale.domain), high = Math.max(...scale.domain);
-      if (config.at < low || config.at > high) throw new RangeError("Axis title at value must be inside the scale domain.");
-      along = mapContinuousScaleValues([config.at], scale)[0];
-    }
-  }
-  return along + (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[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;
-  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?.[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];
-  // 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 = ["target",
-  "text", "scale", "position", "at", "offset", "rotation", "color",
-  "fontSize", "fontFamily", "fontWeight", "alongOffset", "align", "baseline", "overlap"
-];
-const EDIT_OPTIONS = CREATE_OPTIONS.filter(key => key !== "scale");
-const DEFAULTS = {
-  color: DEFAULT_COLORS.text,
-  fontSize: AXIS_TITLE_FONT_SIZE,
-  fontFamily: DEFAULT_FONT_FAMILY,
-  fontWeight: 600
-};
-
-function validateText(text) {
-  return validateNonEmptyString(text, "Axis title 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.");
-  validateAxisTextPlacement(config, { title: true });
-  if (!Number.isFinite(config.rotation)) throw new TypeError("Axis title rotation must be finite radians.");
-  validateAxisTextStyle(config, "Axis title");
-}
-
-export function inferAxisTitleText(program, channel, scaleId) {
-  const titles = new Set();
-  const primaryTitles = new Set();
-  for (const layer of program.semanticSpec.layers) {
-    if (isSourceOwnedText(layer)) continue;
-    // Reference statistics reuse the source axis title.
-    if (program.markConfigs[layer.id]?.statisticalReference !== undefined) continue;
-    const primary = layer.encoding?.[channel];
-    const encoding = layer.mark?.type === "area" && Object.hasOwn(primary ?? {}, "datum")
-      ? layer.encoding?.[`${channel}2`] : primary;
-    if (channel === "radius" && layer.mark?.type === "arc" &&
-      encoding?.scale === scaleId && encoding.aggregate === "count" && encoding.field === undefined) {
-      titles.add(encoding.title ?? "count");
-      continue;
-    }
-    if (
-      encoding?.scale === scaleId &&
-      typeof encoding.field === "string" &&
-      encoding.field.length
-    ) {
-      const dataset = findDataset(program, layer.data);
-      const transform = findUpstreamTransform(program, dataset,
-        ["density", "ecdf", "interval", "boxSummary", "gradientProfile", "summary"]);
-      let derivedTitle;
-      if (transform?.type === "density") {
-        derivedTitle = encoding.field === transform.as?.[0]
-          ? transform.field
-          : encoding.field === transform.as?.[1]
-            ? "Density"
-            : undefined;
-      } else if (transform?.type === "ecdf") {
-        derivedTitle = encoding.field === transform.as.value ? transform.field
-          : encoding.field === transform.as.probability ? "Cumulative probability"
-            : encoding.field === transform.as.cumulative ? "Cumulative count" : 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;
-      } else if (transform?.type === "gradientProfile" &&
-        [transform.as.lower, transform.as.upper, transform.as.center].includes(encoding.field)) {
-        // Profile bounds and the optional center share one source measure.
-        derivedTitle = transform.field;
-      } else if (transform?.type === "summary") {
-        const aggregate = transform.aggregates.find(value => value.as === encoding.field);
-        if (aggregate) derivedTitle = formatAggregateTitle(aggregate.op, aggregate.field);
-      }
-      const title = encoding.title ?? derivedTitle ?? (encoding.aggregate === undefined
-        ? encoding.field
-        : formatAggregateTitle(encoding.aggregate, encoding.field));
-      titles.add(title);
-      if (layer.mark?.type === "point") primaryTitles.add(title);
-    }
-  }
-  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, axisId = channel) {
-  const scale = program.resolvedScales[config.scale];
-  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.");
-  const along = resolveTitleAlong(scale, config);
-  const geometry = resolveAxisTitleGeometry({
-    bounds,
-    channel,
-    position: config.position,
-    along,
-    offset: config.offset
-  });
-  const resolvedBounds = titleBounds(
-    geometry,
-    config,
-    program.semanticSpec.guides.axis?.[axisId]?.title ?? ""
-  , program.materializationConfigs.textMetrics);
-  const canvas = findCanvasGraphic(program)?.properties;
-  if (!canvas || !textBoundsFitCanvas(resolvedBounds, canvas)) {
-    throw canvasOverflowError(`The ${channel}-axis title does not fit the Canvas margin.`, [resolvedBounds], canvas);
-  }
-  const labelBounds = axisLabelBounds(program, channel, axisId);
-  if (!axisTitleAllowsLabelOverlap(config) && labelBounds.some(bounds => bounds && textBoundsIntersect(resolvedBounds, bounds))) {
-    throw new Error(`The ${channel}-axis title overlaps the axis labels.`);
-  }
-  return geometry;
-}
-
-function names(channel) {
-  const prefix = channel === "x" ? "X" : "Y";
-  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);
-    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");
-    const explicitRotation = Object.hasOwn(args, "rotation");
-    const position = appearance.position ?? previous.position;
-    const inferredRotation = explicitRotation
-      ? false
-      : previous.inferredRotation === true;
-    const config = {
-      ...previous,
-      ...appearance,
-      position,
-      rotation: inferredRotation
-        ? defaultAxisTitleRotation(channel, position)
-        : explicitRotation
-          ? resolveRotation(requestedRotation, "Axis title rotation")
-          : previous.rotation,
-      inferredRotation,
-      inferredOffset: Object.hasOwn(args, "offset")
-        ? false
-        : previous.inferredOffset === true,
-      ...(explicitText ? { inferredText: false } : {})
-    };
-    validateConfig(channel, config);
-    let next = this;
-    const resolvedTitle = explicitText
-      ? validateText(text)
-      : config.inferredText === true
-        ? inferAxisTitleText(this, channel, config.scale)
-        : this.semanticSpec.guides.axis?.[axisId]?.title;
-    if (resolvedTitle !== this.semanticSpec.guides.axis?.[axisId]?.title) {
-      next = next.editSemantic({
-        property: `guide.axis.${axisId}.title`,
-        value: validateText(resolvedTitle)
-      });
-    }
-    const resolvedText = validateText(next.semanticSpec.guides.axis?.[axisId]?.title);
-    if (config.inferredOffset) {
-      config.offset = inferredTitleOffset(next, channel, config, axisId);
-    }
-    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: config.align ?? "center", textBaseline: config.baseline ?? "middle",
-      rotation: config.rotation
-    };
-    for (const [property, value] of Object.entries(properties)) next = next.editGraphics({ target: graphic, property, value });
-    return materializeTextLines(next, graphic, titleLines(resolvedText, config));
-  }));
-}
-
-const editXAxisTitle = /* @__PURE__ */ makeEdit("x");
-const editYAxisTitle = /* @__PURE__ */ makeEdit("y");
-
-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,
-      position: requestedPosition,
-      rotation: requestedRotation,
-      ...appearance
-    } = args;
-    const scale = validateUserId(requestedScale ?? channel, "Scale id");
-    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[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)
-    );
-    const position = requestedPosition ?? defaultAxisPosition(channel);
-    const inferredRotation = !Object.hasOwn(args, "rotation");
-    const inferredOffset = !Object.hasOwn(args, "offset");
-    const config = {
-      scale,
-      inferredText,
-      position,
-      at: "center",
-      offset: channel === "x" ? 42 : 52,
-      rotation: inferredRotation
-        ? defaultAxisTitleRotation(channel, position)
-        : resolveRotation(requestedRotation, "Axis title rotation"),
-      inferredRotation,
-      inferredOffset,
-      color: DEFAULTS.color,
-      fontSize: DEFAULTS.fontSize,
-      fontFamily: DEFAULTS.fontFamily,
-      fontWeight: DEFAULTS.fontWeight,
-      ...axisThemeTypography(this.materializationConfigs.theme, "title"),
-      ...appearance
-    };
-    let next = this
-      .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, axisId);
-    return next
-      .createGraphics({
-        id: graphic,
-        type: "text",
-        ...resolvePlotGraphicPlacement(this)
-      })
-      ._withGuideConfig(axisId, "title", config)[operation.edit](axisId === channel ? undefined : axisTargetArgs(axisId, channel));
-  }));
-}
-
-const createXAxisTitle = /* @__PURE__ */ makeCreate("x");
-const createYAxisTitle = /* @__PURE__ */ makeCreate("y");
-
-export function registerAxisTitleActions(Class) {
-  Class.prototype.createXAxisTitle = createXAxisTitle;
-  Class.prototype.createYAxisTitle = createYAxisTitle;
-  Class.prototype.editXAxisTitle = editXAxisTitle;
-  Class.prototype.editYAxisTitle = editYAxisTitle;
-}
+import{selectCartesianAxis as E,axisTargetArgs as J}from"../../../selectors/axes.js";import{axisGraphicIds as h}from"../../../materialization/guides/resources.js";import{materializeTextLines as Q}from"../../../materialization/textLines.js";import{axisTitleTextLines as z,validateAxisTextPlacement as g,axisTitleAllowsLabelOverlap as I,isLabelRelativeTitleOffset as M,axisLabelHasText as tt}from"../../../grammar/axisTextPlacement.js";import{axisThemeTypography as et}from"../../theme/state.js";import{canvasOverflowError as it}from"../../../layout/canvas.js";import{isSourceOwnedText as ot}from"../../../grammar/text.js";import{withGuideLayoutValidation as F}from"../../../materialization/guides/layout.js";import{action as $}from"../../../core/action.js";import{validateUserId as st}from"../../../core/identifiers.js";import{validateKeys as j,validateNonEmptyString as rt}from"../../../core/validation.js";import{axisScaleBindings as nt,resolveCartesianAxisFrameBounds as L}from"../../../materialization/coordinateBounds.js";import{isTransformedScaleType as at,mapContinuousScaleValues as lt,mapOrdinalPositionValues as ft}from"../../../grammar/scales/index.js";import{AXIS_TITLE_FONT_SIZE as dt,DEFAULT_COLORS as ct,DEFAULT_FONT_FAMILY as ut}from"../../../theme/defaults.js";import{findDataset as pt}from"../../../selectors/datasets.js";import{findUpstreamTransform as mt}from"../../../materialization/dataProvenance.js";import{formatAggregateTitle as R}from"../../../grammar/aggregate.js";import{finiteMidpoint as xt}from"../../../grammar/numeric.js";import{defaultAxisPosition as bt,defaultAxisTitleRotation as B,resolveAxisTitleGeometry as w,validateAxisPosition as yt}from"./policy.js";import{findCanvasGraphic as q,resolvePlotGraphicPlacement as vt}from"../../../materialization/graphicHierarchy.js";import{resolveTextBounds as Tt,textBoundsFitCanvas as ht,textBoundsIntersect as G}from"../../../core/textMetrics.js";import{resolveConcreteGraphicBounds as C}from"../../../grammar/schemas/graphicBounds.js";import{validateAxisTextStyle as wt}from"./labels.js";import{resolveRotation as P}from"../../../grammar/rotation.js";function S(t,e,i,o){return Tt({...t,text:i,lines:z(i,e),fontSize:e.fontSize,fontFamily:e.fontFamily,fontWeight:e.fontWeight,textAlign:e.align??"center",textBaseline:e.baseline??"middle",rotation:e.rotation},o)}function _(t,e){const i=["ordinal","band","point"].includes(t?.type);let o;if(e.at==="center")o=xt(t.range[0],t.range[1]);else if(e.at==="start"||e.at==="end")o=t.range[e.at==="start"?0:1];else if(i){if(!t.domain.includes(e.at))throw new RangeError("Axis title at value must be inside the scale domain.");o=ft([e.at],t)[0]}else{const s=Math.min(...t.domain),a=Math.max(...t.domain);if(e.at<s||e.at>a)throw new RangeError("Axis title at value must be inside the scale domain.");o=lt([e.at],t)[0]}return o+(e.alongOffset??0)}function N(t,e,i=e){const o=h(e,i)[2],s=t.graphicSpec.objects[o],a=f=>C(t.graphicSpec,f,t.materializationConfigs.textMetrics);return s?.items?.map(f=>a(f.id))??(s?[a(o)]:[])}function W(t,e,i,o=e){const s=L(t,e,i.position,i.scale,o),a=q(t)?.properties,f=t.graphicSpec.objects[h(e,o)[2]]?C(t.graphicSpec,h(e,o)[2],t.materializationConfigs.textMetrics):void 0,n=e==="x"?42:52;if(!s||!a||!f)return n;const u=e==="x",r=i.position===(u?"bottom":"right"),d=u?"top":"left",c=u?"bottom":"right",p=S(w({bounds:s,channel:e,position:i.position,along:0,offset:n}),i,t.semanticSpec.guides.axis?.[o]?.title??"",t.materializationConfigs.textMetrics),x=r?f[c]+4-p[d]:p[c]-f[d]+4,l=r?a[u?"height":"width"]-p[c]:p[d],m=e==="y"&&Math.abs(Math.cos(i.rotation))<1e-10?i.fontSize/4:0;if(t.materializationConfigs.canvas?.plot!==void 0)return n+Math.max(0,x);const y=Math.min(l,Math.max(0,x));if(m===0)return n+y;const v=Math.min(l-m,Math.max(0,x)),b=S(w({bounds:s,channel:e,position:i.position,along:_(t.resolvedScales[i.scale],i),offset:n+v}),i,t.semanticSpec.guides.axis?.[o]?.title??"",t.materializationConfigs.textMetrics);return n+(N(t,e,o).some(T=>T&&G(b,T))?y:v)}function St(t,e,i,o,s,a){const f=t.graphicSpec.objects[h(e,o)[2]];if(t.guideConfigs.axis?.[o]?.labels?.position!==i.position)throw new Error("Label-relative title offset requires labels on the same axis side.");const u=(f?.items??(f?[f]:[])).filter(l=>tt(l.properties)).map(l=>C(t.graphicSpec,l.id,t.materializationConfigs.textMetrics));if(u.length===0)throw new Error("Label-relative title offset requires nonempty axis labels.");const r=e==="x"?"top":"left",d=e==="x"?"bottom":"right",c=i.position===(e==="x"?"bottom":"right"),p=S(w({bounds:s,channel:e,position:i.position,along:a,offset:0}),i,t.semanticSpec.guides.axis?.[o]?.title??"",t.materializationConfigs.textMetrics),x=c?Math.max(...u.map(l=>l[d]))+i.offset.gap-p[r]:p[d]-Math.min(...u.map(l=>l[r]))+i.offset.gap;if(!Number.isFinite(x))throw new RangeError("Label-relative title offset must resolve to a finite distance.");return x}const k=["target","text","scale","position","at","offset","rotation","color","fontSize","fontFamily","fontWeight","alongOffset","align","baseline","overlap"],At=k.filter(t=>t!=="scale"),A={color:ct.text,fontSize:dt,fontFamily:ut,fontWeight:600};function O(t){return rt(t,"Axis title text")}function D(t,e){if(yt(t,e.position),!["start","center","end"].includes(e.at)&&!Number.isFinite(e.at))throw new TypeError("Axis title at must be start, center, end, or a finite number.");if(g(e,{title:!0}),!Number.isFinite(e.rotation))throw new TypeError("Axis title rotation must be finite radians.");wt(e,"Axis title")}function X(t,e,i){const o=new Set,s=new Set;for(const a of t.semanticSpec.layers){if(ot(a)||t.markConfigs[a.id]?.statisticalReference!==void 0)continue;const f=a.encoding?.[e],n=a.mark?.type==="area"&&Object.hasOwn(f??{},"datum")?a.encoding?.[`${e}2`]:f;if(e==="radius"&&a.mark?.type==="arc"&&n?.scale===i&&n.aggregate==="count"&&n.field===void 0){o.add(n.title??"count");continue}if(n?.scale===i&&typeof n.field=="string"&&n.field.length){const u=pt(t,a.data),r=mt(t,u,["density","ecdf","interval","boxSummary","gradientProfile","summary"]);let d;if(r?.type==="density")d=n.field===r.as?.[0]?r.field:n.field===r.as?.[1]?"Density":void 0;else if(r?.type==="ecdf")d=n.field===r.as.value?r.field:n.field===r.as.probability?"Cumulative probability":n.field===r.as.cumulative?"Cumulative count":void 0;else if(r?.type==="interval"&&Object.values(r.as).includes(n.field))d=`${r.center}(${r.field})`;else if(r?.type==="boxSummary"&&Object.values(r.as).includes(n.field))d=r.field;else if(r?.type==="gradientProfile"&&[r.as.lower,r.as.upper,r.as.center].includes(n.field))d=r.field;else if(r?.type==="summary"){const p=r.aggregates.find(x=>x.as===n.field);p&&(d=R(p.op,p.field))}const c=n.title??d??(n.aggregate===void 0?n.field:R(n.aggregate,n.field));o.add(c),a.mark?.type==="point"&&s.add(c)}}if(s.size===1)return[...s][0];if(o.size===0&&nt(t,i).some(a=>a.channel===e))return i;if(o.size!==1)throw new Error(`Axis title text cannot be inferred for scale "${i}".`);return[...o][0]}function Y(t,e,i,o=e){const s=t.resolvedScales[i.scale],a=L(t,e,i.position,i.scale,o);if(!["linear","time","ordinal","band","point"].includes(s?.type)&&!at(s?.type)||!a)throw new Error("Axis title requires a supported resolved scale and Canvas bounds.");const f=_(s,i),n=w({bounds:a,channel:e,position:i.position,along:f,offset:M(i.offset)?St(t,e,i,o,a,f):i.offset}),u=S(n,i,t.semanticSpec.guides.axis?.[o]?.title??"",t.materializationConfigs.textMetrics),r=q(t)?.properties;if(!r||!ht(u,r))throw M(i.offset)?new RangeError(`The ${e}-axis label-relative title does not fit the Canvas margin.`):it(`The ${e}-axis title does not fit the Canvas margin.`,[u],r);const d=N(t,e,o);if(!I(i)&&d.some(c=>c&&G(u,c)))throw new Error(`The ${e}-axis title overlaps the axis labels.`);return n}function U(t){const e=t==="x"?"X":"Y";return{create:`create${e}AxisTitle`,edit:`edit${e}AxisTitle`}}function V(t){const e=U(t);return $({op:e.edit,description:`Edit the ${t}-axis title.`},F(function(i={}){j(i,At,e.edit);const o=E(this,t,i,{create:!1}),s=o.id;i=o.options;const a=h(t,s)[3];if(g(i,{title:!0}),this.graphicSpec.objects[a]?.type!=="text")throw new Error(`${e.edit} requires an existing axis title.`);const f=this.guideConfigs.axis?.[s]?.title;if(!f)throw new Error(`${e.edit} requires title configuration.`);const{text:n,rotation:u,...r}=i,d=Object.hasOwn(i,"text"),c=Object.hasOwn(i,"rotation"),p=r.position??f.position,x=c?!1:f.inferredRotation===!0,l={...f,...r,position:p,rotation:x?B(t,p):c?P(u,"Axis title rotation"):f.rotation,inferredRotation:x,inferredOffset:Object.hasOwn(i,"offset")?!1:f.inferredOffset===!0,...d?{inferredText:!1}:{}};D(t,l);let m=this;const y=d?O(n):l.inferredText===!0?X(this,t,l.scale):this.semanticSpec.guides.axis?.[s]?.title;y!==this.semanticSpec.guides.axis?.[s]?.title&&(m=m.editSemantic({property:`guide.axis.${s}.title`,value:O(y)}));const v=O(m.semanticSpec.guides.axis?.[s]?.title);l.inferredOffset&&(l.offset=W(m,t,l,s));const b=Y(m,t,l,s);m=m._withGuideConfig(s,"title",l);const T={x:b.x,y:b.y,text:v,fill:l.color,fontSize:l.fontSize,fontFamily:l.fontFamily,fontWeight:l.fontWeight,textAlign:l.align??"center",textBaseline:l.baseline??"middle",rotation:l.rotation};for(const[K,Z]of Object.entries(T))m=m.editGraphics({target:a,property:K,value:Z});return Q(m,a,z(v,l))}))}const Ot=V("x"),gt=V("y");function H(t){const e=U(t);return $({op:e.create,description:`Create the ${t}-axis title.`},F(function(i={}){j(i,k,e.create);const o=E(this,t,i,{create:!0}),s=o.id;i=o.options;const a=h(t,s)[3];g(i,{title:!0});const{text:f,scale:n,position:u,rotation:r,...d}=i,c=st(n??t,"Scale id"),p=this.semanticSpec.guides.axis?.[s]?.scale;if(p&&p!==c)throw new Error(`${e.create} conflicts with the existing axis scale.`);if(this.graphicSpec.objects[a])throw new Error(`${e.create} requires a missing axis title.`);const x=!Object.hasOwn(i,"text"),l=O(f??X(this,t,c)),m=u??bt(t),y=!Object.hasOwn(i,"rotation"),v=!Object.hasOwn(i,"offset"),b={scale:c,inferredText:x,position:m,at:"center",offset:t==="x"?42:52,rotation:y?B(t,m):P(r,"Axis title rotation"),inferredRotation:y,inferredOffset:v,color:A.color,fontSize:A.fontSize,fontFamily:A.fontFamily,fontWeight:A.fontWeight,...et(this.materializationConfigs.theme,"title"),...d};let T=this.editSemantic({property:`guide.axis.${s}.scale`,value:c}).editSemantic({property:`guide.axis.${s}.title`,value:l});return v&&(b.offset=W(T,t,b,s)),D(t,b),Y(T,t,b,s),T.createGraphics({id:a,type:"text",...vt(this)})._withGuideConfig(s,"title",b)[e.edit](s===t?void 0:J(s,t))}))}const Ct=H("x"),Et=H("y");function Qt(t){t.prototype.createXAxisTitle=Ct,t.prototype.createYAxisTitle=Et,t.prototype.editXAxisTitle=Ot,t.prototype.editYAxisTitle=gt}export{X as inferAxisTitleText,Qt as registerAxisTitleActions};

package/src/actions/titles/resolve.js

@@ -24,7 +24,7 @@ import { findCanvasGraphic } from
 
 const OPTIONS = Object.freeze([
   "text", "subtitle", "position", "align", "offset", "alongOffset", "gap", "titleStyle",
-  "subtitleStyle", "maxWidth", "wrap", "lineHeight"
+  "subtitleStyle", "maxWidth", "wrap", "lineHeight", "subtitleLineHeight"
 ]);
 const STYLE_OPTIONS = Object.freeze([
   "color", "fontSize", "fontFamily", "fontWeight", "fontStyle"
@@ -101,6 +101,9 @@ function normalizeConfig(args, defaults, { hasSubtitle }) {
   const maxWidth = args.maxWidth ?? defaults.maxWidth;
   const wrap = args.wrap ?? defaults.wrap ?? (maxWidth === undefined ? undefined : "word");
   const lineHeight = args.lineHeight ?? defaults.lineHeight;
+  const subtitleLineHeight = args.subtitleLineHeight === undefined
+    ? defaults.subtitleLineHeight
+    : args.subtitleLineHeight;
   if (!POSITIONS.includes(position)) {
     throw new Error(`Unsupported title position "${position}".`);
   }
@@ -128,6 +131,12 @@ function normalizeConfig(args, defaults, { hasSubtitle }) {
   )) {
     throw new RangeError("Chart title lineHeight must cover every visible fontSize.");
   }
+  if (subtitleLineHeight !== undefined && (
+    !Number.isFinite(subtitleLineHeight) ||
+    subtitleLineHeight < subtitleStyle.fontSize
+  )) {
+    throw new RangeError("Chart subtitleLineHeight must cover subtitleStyle.fontSize.");
+  }
   return {
     position,
     align,
@@ -136,6 +145,7 @@ function normalizeConfig(args, defaults, { hasSubtitle }) {
     gap,
     titleStyle,
     subtitleStyle,
+    ...(subtitleLineHeight === undefined ? {} : { subtitleLineHeight }),
     ...(maxWidth === undefined ? {} : { maxWidth, wrap, ...(lineHeight === undefined
       ? {}
       : { lineHeight }) })

package/src/core/compositionState.js

@@ -1,3 +1,4 @@
+import { normalizeFacetGap } from "./facetGap.js";
 import { normalizeFacetAxes } from "./facetAxisPolicy.js";
 import { isOwned, isPlainObject } from "./immutable.js";
 import { ownProgramState } from "./programState.js";
@@ -242,7 +243,9 @@ function validateCompositionChildren(compositionSpec, childIds, facet) {
 }
 
 function validateLayout(compositionSpec) {
-  if (!Number.isFinite(compositionSpec.gap) || compositionSpec.gap < 0) {
+  if (compositionSpec.type === "facet") {
+    normalizeFacetGap(compositionSpec.gap, "compositionSpec.gap");
+  } else if (!Number.isFinite(compositionSpec.gap) || compositionSpec.gap < 0) {
     throw new RangeError("compositionSpec.gap must be a non-negative finite number.");
   }
   if (!["start", "center", "end"].includes(compositionSpec.align)) {

package/src/core/facetGap.js

@@ -0,0 +1,44 @@
+import { cloneAndFreeze, isPlainObject } from "./immutable.js";
+import { annotateError } from "./diagnostics.js";
+export function validateCompositionSpacing(value, label) {
+  if (!Number.isFinite(value) || value < 0) {
+    throw new RangeError(`${label} must be a non-negative finite number.`);
+  }
+  return value;
+}
+
+/** Keep scalar intent intact; a facet pair always declares both axes. */
+export function normalizeFacetGap(value, label = "Facet gap") {
+  if (!isPlainObject(value)) return validateCompositionSpacing(value, label);
+  const keys = Reflect.ownKeys(value);
+  if (keys.length !== 2 || !keys.includes("x") || !keys.includes("y")) {
+    throw annotateError(new TypeError(`${label} must contain exactly x and y.`), {
+      code: "invalid-value", optionPath: "gap", actual: value
+    });
+  }
+  const result = {};
+  for (const axis of ["x", "y"]) {
+    try {
+      result[axis] = validateCompositionSpacing(value[axis], `${label}.${axis}`);
+    } catch (error) {
+      throw annotateError(error, {
+        code: "invalid-value", optionPath: `gap.${axis}`, actual: value[axis], limit: 0
+      });
+    }
+  }
+  return cloneAndFreeze(result);
+}
+
+/** Accept only a previously normalized scalar or pair. */
+export function facetGapAxis(gap, axis) {
+  return typeof gap === "number" ? gap : gap[axis];
+}
+
+/** Overflow remains axis-specific for a pair; scalar callers keep their old error. */
+export function assertFacetGapFinite(gap, axis, values, message) {
+  if (values.every(Number.isFinite)) return;
+  const error = new RangeError(message);
+  throw typeof gap === "number" ? error : annotateError(error, {
+    code: "invalid-value", optionPath: `gap.${axis}`, actual: gap[axis]
+  });
+}

package/src/grammar/axisTextPlacement.js

@@ -1 +1 @@
-import{resolveTextLines as l}from"../core/textMetrics.js";function a(e,{title:i=!1}={}){if(Object.hasOwn(e,"align")&&!["left","center","right"].includes(e.align))throw new TypeError("Axis text align must be left, center, or right.");if(i){if(Object.hasOwn(e,"overlap")&&!["error","allow"].includes(e.overlap))throw new TypeError("Axis title overlap must be error or allow.");if(Object.hasOwn(e,"baseline")&&!["top","hanging","middle","alphabetic","ideographic","bottom"].includes(e.baseline))throw new TypeError("Axis title baseline must be a supported text baseline.");for(const t of["offset","alongOffset"])if(Object.hasOwn(e,t)&&!Number.isFinite(e[t]))throw new TypeError(`Axis title ${t} must be a finite number.`)}}function f(e,i){if(!/[\r\n]/u.test(e))return;const t=i.baseline??"middle",n=l(e,{fontSize:i.fontSize,align:i.align??"center",baseline:t,...t==="middle"?{blockAlign:"middle"}:{}});if(["bottom","ideographic"].includes(t)){const o=(n.length-1)*i.fontSize*1.2;return n.map(r=>({...r,y:r.y-o}))}return n.length>1?n:void 0}function b(e){return e?.overlap==="allow"}export{b as axisTitleAllowsLabelOverlap,f as axisTitleTextLines,a as validateAxisTextPlacement};
+import{validateKeys as a,validateNonNegativeFinite as o}from"../core/validation.js";import{isPlainObject as s}from"../core/immutable.js";import{resolveTextLines as b}from"../core/textMetrics.js";function c(e,{title:t=!1}={}){if(Object.hasOwn(e,"align")&&!["left","center","right"].includes(e.align))throw new TypeError("Axis text align must be left, center, or right.");if(t){if(Object.hasOwn(e,"overlap")&&!["error","allow"].includes(e.overlap))throw new TypeError("Axis title overlap must be error or allow.");if(Object.hasOwn(e,"baseline")&&!["top","hanging","middle","alphabetic","ideographic","bottom"].includes(e.baseline))throw new TypeError("Axis title baseline must be a supported text baseline.");if(Object.hasOwn(e,"offset")&&s(e.offset)){if(a(e.offset,["from","gap"],"Axis title offset"),e.offset.from!=="labels"||!Object.hasOwn(e.offset,"gap"))throw new TypeError("Axis title offset requires from: labels and gap.");o(e.offset.gap,"Axis title label gap")}for(const i of["offset","alongOffset"])if(!(i==="offset"&&f(e.offset))&&Object.hasOwn(e,i)&&!Number.isFinite(e[i]))throw new TypeError(`Axis title ${i} must be a finite number.`)}}function f(e){return s(e)&&e.from==="labels"}function h(e){return e?.inferredOffset===!0||f(e?.offset)}function m(e){return(e?.lines??[{text:e?.text}]).some(t=>typeof t.text=="string"&&t.text.length>0)}function w(e,t){if(!/[\r\n]/u.test(e))return;const i=t.baseline??"middle",r=b(e,{fontSize:t.fontSize,align:t.align??"center",baseline:i,...i==="middle"?{blockAlign:"middle"}:{}});if(["bottom","ideographic"].includes(i)){const l=(r.length-1)*t.fontSize*1.2;return r.map(n=>({...n,y:n.y-l}))}return r.length>1?r:void 0}function u(e){return e?.overlap==="allow"}function g(e,{allowReset:t=!1}={}){e===void 0||t&&e==="auto"||o(e,"Label flushThreshold")}export{m as axisLabelHasText,u as axisTitleAllowsLabelOverlap,h as axisTitleFollowsLabels,w as axisTitleTextLines,f as isLabelRelativeTitleOffset,g as validateAxisLabelFlushThreshold,c as validateAxisTextPlacement};