ggaction 0.0.23 → 0.0.26

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

@@ -1,9 +1,11 @@
+import { materializeHardTextLines } from "../../../materialization/textLines.js";
 import { closedAction } from "../../../core/action.js";
 import { validateGeneratedItemLimit } from "../../../core/validation.js";
 import { resolvePlotGraphicPlacement } from "../../../materialization/graphicHierarchy.js";
 import { requireParallelAxisLayer, resolveParallelAxisTarget, resolveStyledParallelAxes } from "./parallel/resolve.js";
 import { PARALLEL_AXIS_GRAPHICS, PARALLEL_AXIS_PARTS, hasParallelAxisParts } from "./parallel/policy.js";
 import { registerParallelAxisLifecycleActions } from "./parallel/lifecycle.js";
+import { withGuideLayoutValidation } from "../../../materialization/guides/layout.js";
 
 function uniform(values) {
   return values.length > 0 && values.every(value => value === values[0]) ? values[0] : values;
@@ -25,7 +27,7 @@ function collectionProperties(part, axes, bounds) {
     fontSize: uniform(axes.map(axis => axis.config.title.fontSize)),
     fontFamily: uniform(axes.map(axis => axis.config.title.fontFamily)),
     fontWeight: uniform(axes.map(axis => axis.config.title.fontWeight)),
-    textAlign: "center", textBaseline: "middle"
+    textAlign: uniform(axes.map(axis => axis.config.title.align ?? "center")), textBaseline: "middle"
   };
   const rows = axes.flatMap(axis => axis[part].values.map((value, index) => ({
     x: axis.x, y: axis[part].y[index], text: axis[part].text?.[index], config: axis.config[part]
@@ -43,14 +45,14 @@ function collectionProperties(part, axes, bounds) {
     fontSize: uniform(rows.map(row => row.config.fontSize)),
     fontFamily: uniform(rows.map(row => row.config.fontFamily)),
     fontWeight: uniform(rows.map(row => row.config.fontWeight)),
-    textAlign: "right", textBaseline: "middle"
+    textAlign: uniform(rows.map(row => row.config.align ?? "right")), textBaseline: "middle"
   };
 }
 
 export const rematerializeParallelAxes = /* @__PURE__ */ closedAction({
   op: "rematerializeParallelAxes",
   description: "Recompute concrete Parallel dimension axes."
-}, ["target"], function (args = {}) {
+}, ["target"], withGuideLayoutValidation(function (args = {}) {
 
   const stored = this.semanticSpec.guides.axis?.parallel;
   if (stored === undefined) throw new Error("rematerializeParallelAxes requires existing Parallel axes.");
@@ -64,6 +66,8 @@ export const rematerializeParallelAxes = /* @__PURE__ */ closedAction({
   const properties = Object.fromEntries(PARALLEL_AXIS_PARTS.map(part => {
     const selected = axes.filter(axis => axis.config[part] !== undefined);
     const value = collectionProperties(part, selected, bounds);
+    if (selected.some(axis => axis.config.visibility !== undefined)) value.opacity = selected.flatMap(axis => Array.from({ length: ["line", "title"].includes(part) ? 1 : axis[part].values.length },
+      () => axis.config.visibility?.all === false || axis.config.visibility?.[part] === false ? 0 : 1));
     validateGeneratedItemLimit(value.length, "Parallel axis item count");
     return [part, { enabled: selected.length > 0, value }];
   }));
@@ -94,9 +98,10 @@ export const rematerializeParallelAxes = /* @__PURE__ */ closedAction({
     for (const [property, item] of Object.entries(value)) {
       next = next.editGraphics({ target: id, property, value: item });
     }
+    if (["title", "labels"].includes(part)) next = materializeHardTextLines(next, id);
   }
   return next._withGuideConfig("parallel", "axes", { target, scales, ...configs });
-});
+}));
 
 export function registerParallelAxisActions(ProgramClass) {
   ProgramClass.prototype.rematerializeParallelAxes = rematerializeParallelAxes;

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

@@ -1,3 +1,5 @@
+import { resolveAxisTickEditConfig } from "./ticks.js";
+import { resolveAxisLabelEditConfig } from "./labels.js";
 import { withGuideLayoutValidation } from "../../../materialization/guides/layout.js";
 import { action } from "../../../core/action.js";
 import { isPlainObject } from "../../../core/immutable.js";
@@ -35,7 +37,7 @@ const LABEL_OPTIONS = Object.freeze([
   "overlap",
   "labelMap",
   "alongOffset",
-  "flush",
+  "flush", "flushThreshold",
   "colorMap",
   "align"
 ]);
@@ -94,6 +96,19 @@ function names(channel) {
   };
 }
 
+// Validate original options before a materialization plan stores normalized arguments.
+export function validateAxisTickGroupEditConfig(program, channel, args, axisId = channel) {
+  validateAxisTickGroupArgs(args, names(channel).edit, false);
+  const shared = select(args, SHARED_EDIT);
+  const hasShared = Object.keys(shared).length > 0;
+  if (hasShared || Object.hasOwn(args, "ticks")) {
+    resolveAxisTickEditConfig(program, channel, { ...shared, ...(args.ticks ?? {}) }, axisId);
+  }
+  if (hasShared || Object.hasOwn(args, "labels")) {
+    resolveAxisLabelEditConfig(program, channel, { ...shared, ...(args.labels ?? {}) }, axisId);
+  }
+}
+
 function makeCreate(channel) {
   const operation = names(channel);
 

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{compositionChannel as z}from"../../../selectors/plotComposition.js";import{selectCartesianAxis as E,axisTargetArgs as I}from"../../../selectors/axes.js";import{axisGraphicIds as h}from"../../../materialization/guides/resources.js";import{materializeTextLines as tt}from"../../../materialization/textLines.js";import{axisTitleTextLines as M,validateAxisTextPlacement as g,axisTitleAllowsLabelOverlap as et,isLabelRelativeTitleOffset as F,axisLabelHasText as it}from"../../../grammar/axisTextPlacement.js";import{axisThemeTypography as ot}from"../../theme/state.js";import{canvasOverflowError as j}from"../../../layout/canvas.js";import{isSourceOwnedText as st}from"../../../grammar/text.js";import{withGuideLayoutValidation as $}from"../../../materialization/guides/layout.js";import{action as L}from"../../../core/action.js";import{validateUserId as nt}from"../../../core/identifiers.js";import{validateKeys as R,validateNonEmptyString as rt}from"../../../core/validation.js";import{axisScaleBindings as at,resolveCartesianAxisFrameBounds as B}from"../../../materialization/coordinateBounds.js";import{isTransformedScaleType as lt,mapContinuousScaleValues as ft,mapOrdinalPositionValues as dt}from"../../../grammar/scales/index.js";import{AXIS_TITLE_FONT_SIZE as ct,DEFAULT_COLORS as ut,DEFAULT_FONT_FAMILY as pt}from"../../../theme/defaults.js";import{findDataset as mt}from"../../../selectors/datasets.js";import{findUpstreamTransform as xt}from"../../../materialization/dataProvenance.js";import{formatAggregateTitle as q}from"../../../grammar/aggregate.js";import{finiteMidpoint as vt}from"../../../grammar/numeric.js";import{defaultAxisPosition as yt,defaultAxisTitleRotation as G,resolveAxisTitleGeometry as S,validateAxisPosition as bt}from"./policy.js";import{findCanvasGraphic as P,resolvePlotGraphicPlacement as Tt}from"../../../materialization/graphicHierarchy.js";import{resolveTextBounds as ht,textBoundsFitCanvas as St,textBoundsIntersect as _}from"../../../core/textMetrics.js";import{resolveConcreteGraphicBounds as C}from"../../../grammar/schemas/graphicBounds.js";import{validateAxisTextStyle as wt}from"./labels.js";import{resolveRotation as N}from"../../../grammar/rotation.js";function w(t,e,i,n){return ht({...t,text:i,lines:M(i,e),fontSize:e.fontSize,fontFamily:e.fontFamily,fontWeight:e.fontWeight,textAlign:e.align??"center",textBaseline:e.baseline??"middle",rotation:e.rotation},n)}function W(t,e){const i=["ordinal","band","point"].includes(t?.type);let n;if(e.at==="center")n=vt(t.range[0],t.range[1]);else if(e.at==="start"||e.at==="end")n=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.");n=dt([e.at],t)[0]}else{const a=Math.min(...t.domain),s=Math.max(...t.domain);if(e.at<a||e.at>s)throw new RangeError("Axis title at value must be inside the scale domain.");n=ft([e.at],t)[0]}return n+(e.alongOffset??0)}function k(t,e,i=e){const n=h(e,i)[2],a=t.graphicSpec.objects[n],s=f=>C(t.graphicSpec,f,t.materializationConfigs.textMetrics);return a?.items?.map(f=>s(f.id))??(a?[s(n)]:[])}function D(t,e,i,n=e){const a=B(t,e,i.position,i.scale,n),s=P(t)?.properties,f=t.graphicSpec.objects[h(e,n)[2]]?C(t.graphicSpec,h(e,n)[2],t.materializationConfigs.textMetrics):void 0,o=e==="x"?42:52;if(!a||!s||!f)return o;const c=e==="x",r=i.position===(c?"bottom":"right"),d=c?"top":"left",u=c?"bottom":"right",p=w(S({bounds:a,channel:e,position:i.position,along:0,offset:o}),i,t.semanticSpec.guides.axis?.[n]?.title??"",t.materializationConfigs.textMetrics),x=r?f[u]+4-p[d]:p[u]-f[d]+4,l=r?s[c?"height":"width"]-p[u]: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 o+Math.max(0,x);const y=Math.min(l,Math.max(0,x));if(m===0)return o+y;const b=Math.min(l-m,Math.max(0,x)),v=w(S({bounds:a,channel:e,position:i.position,along:W(t.resolvedScales[i.scale],i),offset:o+b}),i,t.semanticSpec.guides.axis?.[n]?.title??"",t.materializationConfigs.textMetrics);return o+(k(t,e,n).some(T=>T&&_(v,T))?y:b)}function At(t,e,i,n,a,s){const f=t.graphicSpec.objects[h(e,n)[2]];if(t.guideConfigs.axis?.[n]?.labels?.position!==i.position)throw new Error("Label-relative title offset requires labels on the same axis side.");const c=(f?.items??(f?[f]:[])).filter(l=>it(l.properties)).map(l=>C(t.graphicSpec,l.id,t.materializationConfigs.textMetrics));if(c.length===0)throw new Error("Label-relative title offset requires nonempty axis labels.");const r=e==="x"?"top":"left",d=e==="x"?"bottom":"right",u=i.position===(e==="x"?"bottom":"right"),p=w(S({bounds:a,channel:e,position:i.position,along:s,offset:0}),i,t.semanticSpec.guides.axis?.[n]?.title??"",t.materializationConfigs.textMetrics),x=u?Math.max(...c.map(l=>l[d]))+i.offset.gap-p[r]:p[d]-Math.min(...c.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 X=["target","text","scale","position","at","offset","rotation","color","fontSize","fontFamily","fontWeight","alongOffset","align","baseline","overlap"],Ot=X.filter(t=>t!=="scale"),A={color:ut.text,fontSize:ct,fontFamily:pt,fontWeight:600};function O(t){return rt(t,"Axis title text")}function Y(t,e){if(bt(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 U(t,e,i){const n=new Set,a=new Set;for(const s of t.semanticSpec.layers){if(st(s)||s.derivedBindings?.overlay||t.markConfigs[s.id]?.statisticalReference!==void 0)continue;const f=s.encoding?.[e],o=s.mark?.type==="area"&&Object.hasOwn(f??{},"datum")?s.encoding?.[`${e}2`]:f;if(e==="radius"&&s.mark?.type==="arc"&&o?.scale===i&&o.aggregate==="count"&&o.field===void 0){n.add(o.title??"count");continue}if(o?.scale===i&&typeof o.field=="string"&&o.field.length){const c=mt(t,s.data),r=xt(t,c,["density","ecdf","interval","boxSummary","gradientProfile","summary"]);let d;if(r?.type==="density")d=o.field===r.as?.[0]?r.field:o.field===r.as?.[1]?"Density":void 0;else if(r?.type==="ecdf")d=o.field===r.as.value?r.field:o.field===r.as.probability?"Cumulative probability":o.field===r.as.cumulative?"Cumulative count":void 0;else if(r?.type==="interval"&&Object.values(r.as).includes(o.field))d=`${r.center}(${r.field})`;else if(r?.type==="boxSummary"&&Object.values(r.as).includes(o.field))d=r.field;else if(r?.type==="gradientProfile"&&[r.as.lower,r.as.upper,r.as.center].includes(o.field))d=r.field;else if(r?.type==="summary"){const p=r.aggregates.find(x=>x.as===o.field);p&&(d=q(p.op,p.field))}const u=o.title??d??(o.aggregate===void 0?o.field:q(o.aggregate,o.field));n.add(u),s.mark?.type==="point"&&a.add(u)}}if(a.size===1)return[...a][0];if(n.size===0&&at(t,i).some(s=>s.channel===e))return i;if(n.size>1){const s=t.semanticSpec.layers.filter(o=>o.encoding?.[e]?.scale===i).map(o=>z(t,o.encoding[e],o.data)).filter(Boolean),f=new Set(s.map(o=>JSON.stringify([o.field??o.fields,o.measurement.unit])));if(s.length&&f.size===1)return s[0].field??(s[0].measurement.unit==="dimensions"?"Dimension":"Value");if(s.length&&s.every(o=>o.field&&o.measurement.unit==="value")&&!t.semanticSpec.layers.some(o=>o.encoding?.[e]?.scale===i&&o.encoding[e].title!==void 0&&o.encoding[e].title!==z(t,o.encoding[e],o.data)?.field))return[...new Set(s.map(o=>o.field))].join(" / ")}if(n.size!==1)throw new Error(`Axis title text cannot be inferred for scale "${i}".`);return[...n][0]}function V(t,e,i,n=e){const a=t.resolvedScales[i.scale],s=B(t,e,i.position,i.scale,n);if(!["linear","time","ordinal","band","point"].includes(a?.type)&&!lt(a?.type)||!s)throw new Error("Axis title requires a supported resolved scale and Canvas bounds.");const f=W(a,i),o=S({bounds:s,channel:e,position:i.position,along:f,offset:F(i.offset)?At(t,e,i,n,s,f):i.offset}),c=w(o,i,t.semanticSpec.guides.axis?.[n]?.title??"",t.materializationConfigs.textMetrics),r=P(t)?.properties;if(!r||!St(c,r))throw F(i.offset)?j(`The ${e}-axis label-relative title does not fit the Canvas margin.`,[c],r):j(`The ${e}-axis title does not fit the Canvas margin.`,[c],r);const d=k(t,e,n);if(!et(i)&&d.some(u=>u&&_(c,u)))throw new Error(`The ${e}-axis title overlaps the axis labels.`);return o}function H(t){const e=t==="x"?"X":"Y";return{create:`create${e}AxisTitle`,edit:`edit${e}AxisTitle`}}function J(t){const e=H(t);return L({op:e.edit,description:`Edit the ${t}-axis title.`},$(function(i={}){R(i,Ot,e.edit);const n=E(this,t,i,{create:!1}),a=n.id;i=n.options;const s=h(t,a)[3];if(g(i,{title:!0}),this.graphicSpec.objects[s]?.type!=="text")throw new Error(`${e.edit} requires an existing axis title.`);const f=this.guideConfigs.axis?.[a]?.title;if(!f)throw new Error(`${e.edit} requires title configuration.`);const{text:o,rotation:c,...r}=i,d=Object.hasOwn(i,"text"),u=Object.hasOwn(i,"rotation"),p=r.position??f.position,x=u?!1:f.inferredRotation===!0,l={...f,...r,position:p,rotation:x?G(t,p):u?N(c,"Axis title rotation"):f.rotation,inferredRotation:x,inferredOffset:Object.hasOwn(i,"offset")?!1:f.inferredOffset===!0,...d?{inferredText:!1}:{}};Y(t,l);let m=this;const y=d?O(o):l.inferredText===!0?U(this,t,l.scale):this.semanticSpec.guides.axis?.[a]?.title;y!==this.semanticSpec.guides.axis?.[a]?.title&&(m=m.editSemantic({property:`guide.axis.${a}.title`,value:O(y)}));const b=O(m.semanticSpec.guides.axis?.[a]?.title);l.inferredOffset&&(l.offset=D(m,t,l,a));const v=V(m,t,l,a);m=m._withGuideConfig(a,"title",l);const T={x:v.x,y:v.y,text:b,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[Z,Q]of Object.entries(T))m=m.editGraphics({target:s,property:Z,value:Q});return tt(m,s,M(b,l))}))}const gt=J("x"),Ct=J("y");function K(t){const e=H(t);return L({op:e.create,description:`Create the ${t}-axis title.`},$(function(i={}){R(i,X,e.create);const n=E(this,t,i,{create:!0}),a=n.id;i=n.options;const s=h(t,a)[3];g(i,{title:!0});const{text:f,scale:o,position:c,rotation:r,...d}=i,u=nt(o??t,"Scale id"),p=this.semanticSpec.guides.axis?.[a]?.scale;if(p&&p!==u)throw new Error(`${e.create} conflicts with the existing axis scale.`);if(this.graphicSpec.objects[s])throw new Error(`${e.create} requires a missing axis title.`);const x=!Object.hasOwn(i,"text"),l=O(f??U(this,t,u)),m=c??yt(t),y=!Object.hasOwn(i,"rotation"),b=!Object.hasOwn(i,"offset"),v={scale:u,inferredText:x,position:m,at:"center",offset:t==="x"?42:52,rotation:y?G(t,m):N(r,"Axis title rotation"),inferredRotation:y,inferredOffset:b,color:A.color,fontSize:A.fontSize,fontFamily:A.fontFamily,fontWeight:A.fontWeight,...ot(this.materializationConfigs.theme,"title"),...d};let T=this.editSemantic({property:`guide.axis.${a}.scale`,value:u}).editSemantic({property:`guide.axis.${a}.title`,value:l});return b&&(v.offset=D(T,t,v,a)),Y(t,v),V(T,t,v,a),T.createGraphics({id:s,type:"text",...Tt(this)})._withGuideConfig(a,"title",v)[e.edit](a===t?void 0:I(a,t))}))}const zt=K("x"),Et=K("y");function te(t){t.prototype.createXAxisTitle=zt,t.prototype.createYAxisTitle=Et,t.prototype.editXAxisTitle=gt,t.prototype.editYAxisTitle=Ct}export{U as inferAxisTitleText,te as registerAxisTitleActions};

package/src/actions/guides/facadeLegend.js

@@ -1,11 +1,12 @@
+import {colorSizeScaleIds} from "../../grammar/colorSizeLegend.js";
 import { resolveLegendCreationPlan } from "./legends/categorical/actions.js";
 import { resolveLegendStepConfig } from "./legends/creation.js";
 import { legendResourcePolicy } from "../../materialization/guides/resources.js";
 import { assertGuideOptions, guideConflict, sameGuideValue } from "./reuse.js";
 
 function compatibleLegend(program, kind, requested, existing, explicit) {
-  const expectedScales = kind === "colorSize" ? [requested.colorScale,requested.sizeScale] : requested.scales ?? [requested.scale];
-  const actualScales = kind === "colorSize" ? [existing.colorScale,existing.sizeScale] : existing.scales ?? [existing.scale];
+  const expectedScales = kind === "colorSize" ? colorSizeScaleIds(requested) : requested.scales ?? [requested.scale];
+  const actualScales = kind === "colorSize" ? colorSizeScaleIds(existing) : existing.scales ?? [existing.scale];
   if (!sameGuideValue(expectedScales, actualScales) ||
     !sameGuideValue(requested.channels, existing.channels)) {
     guideConflict(`${kind} legend uses different channels or scales`);

package/src/actions/guides/grids/grid.js

@@ -1,3 +1,4 @@
+import { withGuideVisibilityPaint } from "../../../materialization/guides/visibility.js";
 import { editGraphicProperties } from "../../primitives/graphicProperties.js";
 import { action, closedAction } from "../../../core/action.js";
 import { isPlainObject } from "../../../core/immutable.js";
@@ -45,7 +46,7 @@ function makeRematerialize(direction) {
       op: operation.rematerialize,
       description: `Recompute concrete ${direction} grid lines.`
     },
-    function (args = {}) {
+    withGuideVisibilityPaint(function (args = {}) {
       noOptions(args, operation.rematerialize);
       const storedConfig = this.guideConfigs.grid?.[direction];
       const semantic = this.semanticSpec.guides.grid?.[direction];
@@ -89,7 +90,7 @@ function makeRematerialize(direction) {
           value: geometry.strokeDash
         });
       return hasPlotUnderlays(next) ? next.rematerializePlotDrawOrder() : next;
-    }
+    })
   );
 }
 

package/src/actions/guides/grids/resolve.js

@@ -34,7 +34,7 @@ import {
 const GRID_OPTIONS = Object.freeze([
   "scale", "coordinate", "count", "values", "color", "lineWidth", "strokeDash", "strokeDashMap", "zIndex", "bandPosition", "alongOffset"
 ]);
-const GRID_EDIT_OPTIONS = Object.freeze([
+const GRID_EDIT_OPTIONS = Object.freeze(["visible",
   "count", "values", "color", "lineWidth", "strokeDash", "strokeDashMap", "zIndex", "bandPosition", "alongOffset"
 ]);
 const DEFAULT_STYLE = Object.freeze({
@@ -82,6 +82,7 @@ export function validateGridCreateArgs(args, operation) {
 }
 
 export function validateGridEditArgs(args, operation) {
+  if (Object.hasOwn(args, "visible") && typeof args.visible !== "boolean") throw new TypeError("Grid visible must be a boolean.");
   if (Object.hasOwn(args, "strokeDashMap")) normalizeGuideDashMap(args.strokeDashMap);
   validateOptionObject(args, GRID_EDIT_OPTIONS, operation, {
     allowEmpty: false

package/src/actions/guides/guides.js

@@ -9,6 +9,7 @@ import { findDataset } from "../../selectors/datasets.js";
 import { findUpstreamTransform } from
   "../../materialization/dataProvenance.js";
 import { sampleNumericRange } from "../../grammar/numeric.js";
+import { automaticLegendOptions } from "./legends/automatic.js";
 
 const OPTIONS = Object.freeze(["axes", "grid", "legend"]);
 
@@ -121,10 +122,10 @@ export function resolveGuideOptions(program, args = {}, layers = program.semanti
         args.grid,
         applicability.grid.cartesian || applicability.grid.polar
       );
-  const legend = selectOption(
+  const legend = automaticLegendOptions(program, selectOption(
     args.legend,
     applicability.legend
-  );
+  ), layers);
   return { axes, grid, legend };
 }