ggaction 0.0.21 → 0.0.22

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

@@ -1,3 +1,4 @@
+import { axisTitleAllowsLabelOverlap } from "../../../grammar/axisTextPlacement.js";
 import { selectCartesianAxis, axisTargetArgs } from "../../../selectors/axes.js";
 import { axisGraphicIds } from "../../../materialization/guides/resources.js";
 import { axisThemeTypography } from "../../theme/state.js";
@@ -21,7 +22,7 @@ import {
   formatTransformedTick,
   mapOrdinalPositionValues
 } from "../../../grammar/scales/index.js";
-import { formatTimeTick, formatTimeTicks } from "../../../grammar/ticks.js";
+import { formatTimeTick, formatTimeTicks, validateTickRounding } from "../../../grammar/ticks.js";
 import { resolveRotation } from "../../../grammar/rotation.js";
 import { valuesFromTickConfig } from "../tickValues.js";
 import { AXIS_LABEL_FONT_SIZES, DEFAULT_COLORS, DEFAULT_FONT_FAMILY } from
@@ -29,6 +30,7 @@ import { AXIS_LABEL_FONT_SIZES, DEFAULT_COLORS, DEFAULT_FONT_FAMILY } from
 import {
   defaultAxisPosition,
   formatAxisValue,
+  formatNumericAxisTicks,
   resolveAxisLabelGeometry,
   validateAxisFormat,
   validateAxisPosition
@@ -51,7 +53,7 @@ import {
 } from "../../../grammar/displayLabels.js";
 
 const OPTIONS = [
-  "target", "scale", "position", "count", "values", "offset", "format", "color",
+  "target", "scale", "position", "count", "values", "rounding", "offset", "format", "color",
   "fontSize", "fontFamily", "fontWeight", "rotation", "maxWidth", "wrap",
   "lineHeight", "overlap", "labelMap", "alongOffset", "flush", "colorMap", "align"
 ];
@@ -88,6 +90,10 @@ function normalizeLabelLayout(config, args, operation) {
 export { validateTextStyle as validateAxisTextStyle };
 
 function validateOptions(args, operation, create) {
+  validateTickRounding(args.rounding, !Object.hasOwn(args, "rounding"));
+  if (Object.hasOwn(args, "rounding") && Object.hasOwn(args, "values")) {
+    throw new Error(`${operation} cannot use rounding and values together.`);
+  }
   validateAxisTextPlacement(args);
   validateOptionObject(
     args,
@@ -173,6 +179,9 @@ function assertTickCompatibility(ticks, config, operation) {
   if (!ticks) return;
   if (ticks.scale !== config.scale || ticks.mode !== config.mode) throw new Error(`${operation} conflicts with axis ticks.`);
   if (config.mode === "count" && ticks.count !== config.count) throw new Error(`${operation} conflicts with axis ticks.`);
+  if (config.mode === "count" && (ticks.rounding ?? "ceiling") !== (config.rounding ?? "ceiling")) {
+    throw new Error(`${operation} conflicts with axis tick rounding.`);
+  }
   if (config.mode === "values" && !sameOrderedValues(ticks.values, config.values)) throw new Error(`${operation} conflicts with axis ticks.`);
 }
 
@@ -261,12 +270,14 @@ function resolve(program, channel, config, axisId = channel) {
             ? formatTransformedTick(scale.type, item)
             : String(item)
       );
-  const automaticTimeLabels = scale.type === "time" && config.format === "auto"
-    ? formatTimeTicks(values, scale.domain)
-    : undefined;
+  const automaticLabels = config.format === "ticks"
+    ? formatNumericAxisTicks(values, scale.type)
+    : scale.type === "time" && config.format === "auto"
+      ? formatTimeTicks(values, scale.domain)
+      : undefined;
   let text = values.map((value, index) =>
     resolveDisplayLabel(value, config.labelMap, raw =>
-      automaticTimeLabels?.[index] ?? fallback(raw)));
+      automaticLabels?.[index] ?? fallback(raw)));
   // Empty mapped text suppresses the label, never its raw tick or scale value.
   // Filter all aligned arrays before wrapping so group/color indices stay dense.
   if (text.includes("")) {
@@ -378,7 +389,7 @@ function resolve(program, channel, config, axisId = channel) {
   const title = program.graphicSpec.objects[axisGraphicIds(channel, axisId)[3]]
     ? resolveConcreteGraphicBounds(program.graphicSpec, axisGraphicIds(channel, axisId)[3], program.materializationConfigs.textMetrics)
     : undefined;
-  if (title &&
+  if (title && !axisTitleAllowsLabelOverlap(program.guideConfigs.axis?.[axisId]?.title) &&
     program.guideConfigs.axis?.[axisId]?.title?.inferredOffset !== true &&
     labelBounds.some(item => textBoundsIntersect(item, title))) {
     throw new Error(`The ${channel}-axis labels overlap the axis title.`);
@@ -413,7 +424,10 @@ function makeEdit(channel) {
       mode
     }, args, op);
     config = normalizeAxisLabelMaps(this, config, args, op);
-    if (mode === "values") delete config.count; else delete config.values;
+    if (mode === "values") {
+      delete config.count;
+      if (!Object.hasOwn(args, "rounding")) delete config.rounding;
+    } else delete config.values;
     validateConfig(channel, config);
     assertTickCompatibility(this.guideConfigs.axis?.[axisId]?.ticks, config, op);
     const resolved = resolve(this, channel, config, axisId);
@@ -485,6 +499,7 @@ function makeCreate(channel) {
       ...axisThemeTypography(this.materializationConfigs.theme, "labels"),
       rotation: DEFAULTS.rotation,
       overlap: DEFAULTS.overlap,
+      ...(ticks?.rounding === undefined ? {} : { rounding: ticks.rounding }),
       ...args,
       inferredValues: !hasValues && !hasCount &&
         (ticks?.inferredValues === true || inferredDiscreteValues !== undefined),
@@ -493,6 +508,7 @@ function makeCreate(channel) {
     config = normalizeAxisLabelMaps(this, config, args, op);
     if (mode === "values") {
       config.values ??= ticks?.values ?? inferredDiscreteValues;
+      if (!Object.hasOwn(args, "rounding")) delete config.rounding;
     } else {
       config.count ??= ticks?.count ?? DEFAULTS.count;
     }

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

@@ -8,12 +8,10 @@ import {
 import { AXIS_LABEL_FONT_SIZES, AXIS_TITLE_FONT_SIZE, DEFAULT_COLORS, DEFAULT_FONT_FAMILY } from "../../../../theme/defaults.js";
 import { validateAxisTextStyle } from "../labels.js";
 import { validateAxisFormat } from "../policy.js";
+import { axisGraphicIds } from "../../../../selectors/axes.js";
 
-export const PARALLEL_AXIS_PARTS = Object.freeze(["line", "ticks", "labels", "title"]);
-export const PARALLEL_AXIS_GRAPHICS = Object.freeze({
-  line: "parallelAxisLines", ticks: "parallelAxisTicks",
-  labels: "parallelAxisLabels", title: "parallelAxisTitles"
-});
+import { PARALLEL_AXIS_PARTS, PARALLEL_AXIS_GRAPHICS } from "../../../../selectors/axes.js";
+export { PARALLEL_AXIS_PARTS, PARALLEL_AXIS_GRAPHICS };
 const STYLE_OPTIONS = Object.freeze({
   line: ["color", "lineWidth"],
   ticks: ["count", "values", "length", "color", "lineWidth"],

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

@@ -9,7 +9,7 @@ import { niceTicks } from "../../../../grammar/ticks.js";
 import { resolveCoordinateBounds } from "../../../../materialization/coordinateBounds.js";
 import { findCoordinate } from "../../../../selectors/coordinates.js";
 import { findLayer } from "../../../../selectors/layers.js";
-import { formatAxisValue } from "../policy.js";
+import { formatAxisValue, formatNumericAxisTicks } from "../policy.js";
 import { resolveParallelAxisConfigs } from "./policy.js";
 
 export function requireParallelAxisLayer(program, target) {
@@ -79,8 +79,9 @@ function componentValues(program, dimension, config) {
   return {
     values,
     y: discrete ? mapOrdinalPositionValues(values, scale) : mapContinuousScaleValues(values, scale),
-    text: config.format === undefined ? undefined : values.map(value =>
-      formatAxisValue(value, scale.type, config.format, formatValue))
+    text: config.format === undefined ? undefined
+      : config.format === "ticks" ? formatNumericAxisTicks(values, scale.type)
+        : values.map(value => formatAxisValue(value, scale.type, config.format, formatValue))
   };
 }
 

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

@@ -1,4 +1,6 @@
+import { formatNumericTickValues } from "../../../grammar/ticks.js";
 import { formatVisibleText } from "../../../core/textMetrics.js";
+import { validateBoolean } from "../../../core/validation.js";
 import {
   formatValue,
   isUtcValueFormat,
@@ -10,6 +12,15 @@ const AXIS_POSITIONS = Object.freeze({
   y: Object.freeze(["left", "right"])
 });
 
+export function resolveAxisFrameConfig(current, args) {
+  if (args.underlay !== undefined) validateBoolean(args.underlay, "Axis underlay");
+  const frame = { ...current };
+  if (Object.hasOwn(args, "offset")) frame.offset = args.offset;
+  if (args.underlay === true) frame.underlay = true;
+  else if (args.underlay === false) delete frame.underlay;
+  return Object.keys(frame).length === 0 ? undefined : frame;
+}
+
 export function defaultAxisPosition(channel) {
   return channel === "x" ? "bottom" : "left";
 }
@@ -96,12 +107,23 @@ export function resolveAxisTitleGeometry({
 }
 
 export function validateAxisFormat(format) {
+  if (format === "ticks") return format;
   return validateValueFormat(format, "Label format", {
     allowDecimalsObject: true
   });
 }
 
+export function formatNumericAxisTicks(values, scaleType) {
+  if (["ordinal", "band", "point", "time"].includes(scaleType)) {
+    throw new Error('Axis format "ticks" requires a quantitative scale.');
+  }
+  return formatNumericTickValues(values);
+}
+
 export function formatAxisValue(value, scaleType, format, autoFormatter) {
+  if (format === "ticks") {
+    throw new Error('Axis format "ticks" requires the complete settled tick values.');
+  }
   validateAxisFormat(format);
   if (format === "auto") return formatVisibleText(autoFormatter(value));
   if (["ordinal", "band", "point"].includes(scaleType)) {

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

@@ -8,6 +8,7 @@ const CREATE_OPTIONS = Object.freeze(["target",
   "position",
   "count",
   "values",
+  "rounding",
   "ticks",
   "labels"
 ]);
@@ -15,6 +16,7 @@ const EDIT_OPTIONS = Object.freeze(["target",
   "position",
   "count",
   "values",
+  "rounding",
   "ticks",
   "labels"
 ]);
@@ -37,8 +39,8 @@ const LABEL_OPTIONS = Object.freeze([
   "colorMap",
   "align"
 ]);
-const SHARED_CREATE = Object.freeze(["target", "scale", "position", "count", "values"]);
-const SHARED_EDIT = Object.freeze(["target", "position", "count", "values"]);
+const SHARED_CREATE = Object.freeze(["target", "scale", "position", "count", "values", "rounding"]);
+const SHARED_EDIT = Object.freeze(["target", "position", "count", "values", "rounding"]);
 
 function validateNested(value, supported, label) {
   if (!isPlainObject(value)) {

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

@@ -27,6 +27,7 @@ import {
   valuesFromTickConfig
 } from "../tickValues.js";
 import { DEFAULT_COLORS } from "../../../theme/defaults.js";
+import { validateTickRounding } from "../../../grammar/ticks.js";
 import {
   defaultAxisPosition,
   resolveAxisTickGeometry,
@@ -35,7 +36,7 @@ import {
 import { findCanvasGraphic, resolvePlotGraphicPlacement } from
   "../../../materialization/graphicHierarchy.js";
 
-const OPTIONS = Object.freeze(["target", "scale", "position", "count", "values", "length", "color", "lineWidth", "alongOffset", "strokeDash", "strokeDashMap"]);
+const OPTIONS = Object.freeze(["target", "scale", "position", "count", "values", "rounding", "length", "color", "lineWidth", "alongOffset", "strokeDash", "strokeDashMap"]);
 const DEFAULTS = Object.freeze({
   count: DEFAULT_TICK_COUNT,
   length: 6,
@@ -44,6 +45,10 @@ const DEFAULTS = Object.freeze({
 });
 
 function validateOptions(args, operation, create) {
+  validateTickRounding(args.rounding, !Object.hasOwn(args, "rounding"));
+  if (Object.hasOwn(args, "rounding") && Object.hasOwn(args, "values")) {
+    throw new Error(`${operation} cannot use rounding and values together.`);
+  }
   validateOptionObject(
     args,
     create ? OPTIONS : OPTIONS.filter(key => key !== "scale"),
@@ -165,7 +170,10 @@ function makeEdit(channel) {
       ...(explicitMode ? { inferredValues: false } : {}),
       mode
     }, args);
-    if (mode === "values") delete config.count; else delete config.values;
+    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 });
@@ -179,7 +187,11 @@ function makeEdit(channel) {
       next = next.editGraphics({ target: id, property: "strokeDash", value: resolveGuideDashes(resolved.values, config) });
     }
     // Structural dependency plans own grids during a scale/role handoff.
-    return explicitMode ? applyMaterializationPlan(next, planAxisTickGridRematerialization(next, channel, axisId)) : next;
+    const explicitSelection = explicitMode || Object.hasOwn(args, "rounding");
+    return explicitSelection ? applyMaterializationPlan(next,
+      planAxisTickGridRematerialization(next, channel, axisId, {
+        syncLabels: Object.hasOwn(config, "rounding") || Object.hasOwn(previous, "rounding")
+      })) : next;
   }));
 }
 
@@ -198,6 +210,10 @@ function makeCreate(channel) {
     const id = axisGraphicIds(channel, axisId)[1];
     if (this.graphicSpec.objects[id]) throw new Error(`${op} requires missing axis ticks.`);
     const resolvedScale = this.resolvedScales[scale];
+    const labels = this.guideConfigs.axis?.[axisId]?.labels;
+    const inheritedSelection = labels?.rounding !== undefined && !Object.hasOwn(args, "values")
+      ? { count: labels.count, rounding: labels.rounding } : {};
+    args = { ...inheritedSelection, ...args };
     const inferredValues =
       Object.hasOwn(args, "count") || Object.hasOwn(args, "values")
         ? undefined
@@ -217,7 +233,9 @@ function makeCreate(channel) {
         ...resolvePlotGraphicPlacement(this)
       })
       ._withGuideConfig(axisId, config)[edit](axisId === channel ? undefined : axisTargetArgs(axisId, channel));
-    return applyMaterializationPlan(next, planAxisTickGridRematerialization(next, channel, axisId));
+    return applyMaterializationPlan(next, planAxisTickGridRematerialization(next, channel, axisId, {
+      syncLabels: config.rounding !== undefined || labels?.rounding !== undefined
+    }));
   }));
 }
 

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

@@ -1,7 +1,7 @@
 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 } from "../../../grammar/axisTextPlacement.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";
@@ -21,6 +21,7 @@ import {
 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 {
@@ -132,7 +133,7 @@ function inferredTitleOffset(program, channel, config, axisId = channel) {
 
 const CREATE_OPTIONS = ["target",
   "text", "scale", "position", "at", "offset", "rotation", "color",
-  "fontSize", "fontFamily", "fontWeight", "alongOffset", "align", "baseline"
+  "fontSize", "fontFamily", "fontWeight", "alongOffset", "align", "baseline", "overlap"
 ];
 const EDIT_OPTIONS = CREATE_OPTIONS.filter(key => key !== "scale");
 const DEFAULTS = {
@@ -159,6 +160,8 @@ export function inferAxisTitleText(program, channel, scaleId) {
   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;
@@ -173,9 +176,8 @@ export function inferAxisTitleText(program, channel, scaleId) {
       encoding.field.length
     ) {
       const dataset = findDataset(program, layer.data);
-      const transform = dataset?.transform?.length === 1
-        ? dataset.transform[0]
-        : undefined;
+      const transform = findUpstreamTransform(program, dataset,
+        ["density", "ecdf", "interval", "boxSummary", "gradientProfile", "summary"]);
       let derivedTitle;
       if (transform?.type === "density") {
         derivedTitle = encoding.field === transform.as?.[0]
@@ -183,12 +185,23 @@ export function inferAxisTitleText(program, channel, scaleId) {
           : 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
@@ -228,7 +241,7 @@ function resolveGeometry(program, channel, config, axisId = channel) {
     throw canvasOverflowError(`The ${channel}-axis title does not fit the Canvas margin.`, [resolvedBounds], canvas);
   }
   const labelBounds = axisLabelBounds(program, channel, axisId);
-  if (labelBounds.some(bounds => bounds && textBoundsIntersect(resolvedBounds, bounds))) {
+  if (!axisTitleAllowsLabelOverlap(config) && labelBounds.some(bounds => bounds && textBoundsIntersect(resolvedBounds, bounds))) {
     throw new Error(`The ${channel}-axis title overlaps the axis labels.`);
   }
   return geometry;

package/src/actions/guides/facadeAxes.js

@@ -91,6 +91,9 @@ function planAxis(program, channel, args, explicit) {
   if (explicit.offset !== undefined && explicit.offset !== (configs.frame?.offset ?? 0)) {
     guideConflict(`${channel} axis uses a different frame offset`);
   }
+  if (explicit.underlay !== undefined && explicit.underlay !== (configs.frame?.underlay === true)) {
+    guideConflict(`${channel} axis uses a different underlay policy`);
+  }
   const positions = [...new Set(Object.values(configs).map(config => config.position).filter(Boolean))];
   if (positions.length > 1) guideConflict(`${channel} axis components have incompatible positions`);
   const position = explicit.position ?? positions[0];

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

@@ -15,6 +15,7 @@ import {
 } from "./resolve.js";
 import { polarGuideNames } from "../polar/resolve.js";
 import { resolveAutomaticGridOptions } from "../applicability.js";
+import { hasPlotUnderlays } from "../../../materialization/plotDrawOrder.js";
 
 const CARTESIAN_OPTIONS = Object.freeze(["horizontal", "vertical"]);
 const POLAR_OPTIONS = Object.freeze(["theta", "radial"]);
@@ -78,7 +79,7 @@ function makeRematerialize(direction) {
           value: geometry[property]
         });
       }
-      return editGraphicProperties(next, operation.graphic, {
+      next = editGraphicProperties(next, operation.graphic, {
         stroke: config.color,
         strokeWidth: config.lineWidth
       })
@@ -87,6 +88,7 @@ function makeRematerialize(direction) {
           property: "strokeDash",
           value: geometry.strokeDash
         });
+      return hasPlotUnderlays(next) ? next.rematerializePlotDrawOrder() : next;
     }
   );
 }

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

@@ -1,4 +1,6 @@
 import { cartesianAxisOwners } from "../../../selectors/axes.js";
+import { gridNames } from "../../../selectors/grids.js";
+export { gridNames };
 import { axisGraphicIds } from "../../../materialization/guides/resources.js";
 import { isNominalValue } from "../../../grammar/scales/fields.js";
 import { patchGuideDash, validateGuideDash, normalizeGuideDashMap, resolveGuideDashes } from "../../../grammar/guideDash.js";
@@ -41,16 +43,6 @@ const DEFAULT_STYLE = Object.freeze({
   strokeDash: Object.freeze([])
 });
 
-export function gridNames(direction) {
-  const prefix = direction === "horizontal" ? "Horizontal" : "Vertical";
-  return {
-    channel: direction === "horizontal" ? "y" : "x",
-    create: `create${prefix}Grid`,
-    rematerialize: `rematerialize${prefix}Grid`,
-    graphic: `${direction}GridLines`
-  };
-}
-
 function validateStrokeDash(value) {
   return validateGuideDash(value, "Grid strokeDash");
 }
@@ -215,10 +207,12 @@ export function resolveGridConfig(program, direction, args, resources) {
 export function refreshGridConfig(program, config) {
   if (config.inferredValues !== true) return config;
   const channel = config.direction === "horizontal" ? "y" : "x";
+  const inferred = inferGridTickConfig(program, channel, config.scale);
   const refreshed = {
     ...config,
-    ...inferGridTickConfig(program, channel, config.scale)
+    ...inferred
   };
+  if (inferred.rounding === undefined) delete refreshed.rounding;
   if (refreshed.mode === "values") delete refreshed.count;
   else delete refreshed.values;
   return refreshed;
@@ -232,11 +226,13 @@ export function editGridConfig(previous, args) {
     )
   };
   if (Object.hasOwn(args, "count")) {
+    delete config.rounding;
     config.mode = "count";
     config.count = args.count;
     config.inferredValues = false;
     delete config.values;
   } else if (Array.isArray(args.values)) {
+    delete config.rounding;
     config.mode = "values";
     config.values = args.values;
     config.inferredValues = false;

package/src/actions/guides/guides.js

@@ -37,6 +37,11 @@ function inferAxesOptions(program, applicability, layers) {
     ? { x: { ticksAndLabels: { count: 7 } } }
     : {};
   const directions = applicability.axes.directions;
+  for (const channel of ["x", "y"]) {
+    if (!directions[channel] && layers.some(layer => layer.encoding?.[channel] !== undefined)) {
+      inferred[channel] = false;
+    }
+  }
   const hasStoredY = layers.some(
     layer => layer.encoding?.y !== undefined
   );
@@ -126,11 +131,26 @@ export function resolveGuideOptions(program, args = {}, layers = program.semanti
 const createGuides = /* @__PURE__ */ action(
   {
     op: "createGuides",
-    description: "Create applicable axes, grid, and legend."
+    description: "Create applicable axes, grid, and legend.",
+    scope: "any"
   },
   function (args = {}) {
+    if (this.compositionSpec?.facet) {
+      validateOptions(args);
+      if (Object.keys(args).length === 0) {
+        const selected = Object.entries(resolveGuideOptions(this, args))
+          .filter(([, options]) => options !== undefined);
+        if (selected.length > 0 && selected.every(([kind]) =>
+          hasStoredGuideCollection(this, kind === "axes" ? "axis" : kind)
+        )) return this;
+      }
+      return this.editFacetSource({ action: { method: "createGuides", options: args } });
+    }
+    this._assertUnitProgram("createGuides");
     const { axes, grid, legend } = resolveGuideOptions(this, args);
     if (axes === undefined && grid === undefined && legend === undefined) {
+      if (this.semanticSpec.layers.length > 0 &&
+          OPTIONS.some(key => args[key] === undefined)) return this;
       throw new Error("createGuides requires at least one selected guide.");
     }