ggaction 0.0.12 → 0.0.13

package/src/actions/boxPlots/materialize.js

@@ -1,3 +1,4 @@
+import { applyFacadeGuides } from "../charts/shared.js";
 import { action } from "../../core/action.js";
 import { validateUserId } from "../../core/identifiers.js";
 import {
@@ -190,7 +191,7 @@ export const materializeBoxPlot = action(
       }
     });
     if (config.guides !== false) {
-      next = next.createGuides(config.guides);
+      next = applyFacadeGuides(next, config.guides, ownerId);
     }
     return next._withContext({ currentMark: ownerId, currentData: source });
   }

package/src/actions/canvas/actions.js

@@ -161,7 +161,9 @@ export const createBasicCanvas = action(
       background: Object.hasOwn(args, "background")
         ? args.background
         : DEFAULT_CANVAS.background,
-      margin: normalizeMargin(args.margin, DEFAULT_MARGIN),
+      margin: Object.hasOwn(args, "margin")
+        ? normalizeMargin(args.margin, DEFAULT_MARGIN)
+        : DEFAULT_MARGIN,
       size: {
         width: Object.hasOwn(args, "width") ? "explicit" : "auto",
         height: Object.hasOwn(args, "height") ? "explicit" : "auto"

package/src/actions/canvas/fitting.js

@@ -0,0 +1,211 @@
+import { action } from "../../core/action.js";
+import {
+  validateNonNegativeFinite,
+  validatePositiveFinite,
+  validateOptionObject
+} from "../../core/validation.js";
+import { resolveGraphicBounds } from "../../layout/canvas.js";
+import { findCanvasGraphic } from
+  "../../materialization/graphicHierarchy.js";
+
+const OPTIONS = Object.freeze([
+  "padding",
+  "minPlotWidth",
+  "minPlotHeight",
+  "iterationLimit",
+  "overflow"
+]);
+const SIDES = Object.freeze(["top", "right", "bottom", "left"]);
+const DEFAULTS = Object.freeze({
+  padding: 0,
+  minPlotWidth: 160,
+  minPlotHeight: 120,
+  iterationLimit: 32,
+  overflow: "error"
+});
+const UNITS_PER_PIXEL = 4;
+
+function normalizeOptions(args) {
+  validateOptionObject(args, OPTIONS, "fitCanvas", { allowEmpty: true });
+  const policy = { ...DEFAULTS, ...args };
+  validateNonNegativeFinite(policy.padding, "fitCanvas padding");
+  validatePositiveFinite(policy.minPlotWidth, "fitCanvas minPlotWidth");
+  validatePositiveFinite(policy.minPlotHeight, "fitCanvas minPlotHeight");
+  if (!Number.isInteger(policy.iterationLimit) ||
+      policy.iterationLimit <= 0 || policy.iterationLimit > 64) {
+    throw new RangeError(
+      "fitCanvas iterationLimit must be an integer from 1 through 64."
+    );
+  }
+  if (!["error", "report"].includes(policy.overflow)) {
+    throw new Error(`Unsupported fitCanvas overflow policy "${policy.overflow}".`);
+  }
+  return policy;
+}
+
+function probe(program, margin) {
+  try {
+    return { ok: true, program: program.editCanvas({ margin }) };
+  } catch (error) {
+    return {
+      ok: false,
+      message: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+
+function marginWith(margin, side, value) {
+  return { ...margin, [side]: value };
+}
+
+function minimizeSide(program, margin, side, policy) {
+  const current = margin[side];
+  const floor = Math.ceil(policy.padding * UNITS_PER_PIXEL) /
+    UNITS_PER_PIXEL;
+  if (floor > current) {
+    const expanded = marginWith(margin, side, floor);
+    const result = probe(program, expanded);
+    return result.ok
+      ? { program: result.program, margin: expanded, iterations: 1, issues: [] }
+      : {
+          program,
+          margin,
+          iterations: 1,
+          issues: [`${side} padding: ${result.message}`]
+        };
+  }
+
+  let low = Math.ceil(policy.padding * UNITS_PER_PIXEL);
+  let high = Math.floor(current * UNITS_PER_PIXEL);
+  if (low > high) {
+    return { program, margin, iterations: 0, issues: [] };
+  }
+
+  const cache = new Map();
+  const test = units => {
+    if (cache.has(units)) return cache.get(units);
+    const result = probe(
+      program,
+      marginWith(margin, side, units / UNITS_PER_PIXEL)
+    );
+    cache.set(units, result);
+    return result;
+  };
+  let iterations = 0;
+  const upper = test(high);
+  iterations += 1;
+  if (!upper.ok) {
+    return { program, margin, iterations, issues: [] };
+  }
+
+  while (low < high && iterations < policy.iterationLimit) {
+    const middle = Math.floor((low + high) / 2);
+    const result = test(middle);
+    iterations += 1;
+    if (result.ok) high = middle;
+    else low = middle + 1;
+  }
+  const best = test(high);
+  const fittedMargin = marginWith(
+    margin,
+    side,
+    high / UNITS_PER_PIXEL
+  );
+  return {
+    program: best.program,
+    margin: fittedMargin,
+    iterations,
+    issues: low === high
+      ? []
+      : [`${side} fitting reached iterationLimit ${policy.iterationLimit}`]
+  };
+}
+
+function fitMargins(program, policy) {
+  let probeProgram = program;
+  let margin = { ...program.materializationConfigs.canvas.margin };
+  let iterations = 0;
+  const issues = [];
+  for (const side of SIDES) {
+    const result = minimizeSide(probeProgram, margin, side, policy);
+    probeProgram = result.program;
+    margin = result.margin;
+    iterations += result.iterations;
+    issues.push(...result.issues);
+  }
+  return { margin, iterations, issues };
+}
+
+function sameMargin(first, second) {
+  return SIDES.every(side => first[side] === second[side]);
+}
+
+function samePolicy(first, second) {
+  return OPTIONS.every(option => first?.[option] === second[option]);
+}
+
+function layoutSignature(program) {
+  const source = JSON.stringify({
+    graphicSpec: program.graphicSpec,
+    canvas: program.materializationConfigs.canvas,
+    guides: program.materializationConfigs.guides,
+    title: program.materializationConfigs.title
+  });
+  let hash = 0xcbf29ce484222325n;
+  for (let index = 0; index < source.length; index += 1) {
+    hash ^= BigInt(source.charCodeAt(index));
+    hash = BigInt.asUintN(64, hash * 0x100000001b3n);
+  }
+  return hash.toString(16).padStart(16, "0");
+}
+
+export const fitCanvas = action(
+  {
+    op: "fitCanvas",
+    description: "Fit Canvas margins around existing layout resources."
+  },
+  function (args = {}) {
+    const policy = normalizeOptions(args);
+    const canvas = findCanvasGraphic(this);
+    if (canvas?.type !== "canvas" ||
+        this.materializationConfigs.canvas?.margin === undefined) {
+      throw new Error("fitCanvas requires an existing Canvas.");
+    }
+    const previous = this.materializationConfigs.fitting;
+    if (samePolicy(previous?.policy, policy) &&
+        previous?.result?.signature === layoutSignature(this)) {
+      return this;
+    }
+    const sourceMargin = this.materializationConfigs.canvas.margin;
+    const fitted = fitMargins(this, policy);
+    let next = sameMargin(sourceMargin, fitted.margin)
+      ? this
+      : this.editCanvas({ margin: fitted.margin });
+    const plot = resolveGraphicBounds(next);
+    if (plot.width < policy.minPlotWidth) {
+      fitted.issues.push(
+        `plot width ${plot.width} is smaller than minPlotWidth ${policy.minPlotWidth}`
+      );
+    }
+    if (plot.height < policy.minPlotHeight) {
+      fitted.issues.push(
+        `plot height ${plot.height} is smaller than minPlotHeight ${policy.minPlotHeight}`
+      );
+    }
+    if (fitted.issues.length > 0 && policy.overflow === "error") {
+      throw new Error(`fitCanvas overflow: ${fitted.issues.join("; ")}.`);
+    }
+    next = next._withMaterializationConfig(["fitting"], {
+      policy,
+      result: {
+        status: fitted.issues.length === 0 ? "fit" : "overflow",
+        margin: fitted.margin,
+        plot: { width: plot.width, height: plot.height },
+        iterations: fitted.iterations,
+        issues: fitted.issues,
+        signature: layoutSignature(next)
+      }
+    });
+    return next;
+  }
+);

package/src/actions/canvas/index.js

@@ -1,8 +1,10 @@
 import { createBasicCanvas, createCanvas, editCanvas } from "./actions.js";
+import { fitCanvas } from "./fitting.js";
 
 export function registerCanvasActions(ProgramClass) {
   ProgramClass.prototype.editCanvas = editCanvas;
   ProgramClass.prototype.createCanvas = createCanvas;
+  ProgramClass.prototype.fitCanvas = fitCanvas;
 }
 
 export function registerBasicCanvasActions(ProgramClass) {

package/src/actions/categoryOrder/index.js

@@ -11,6 +11,7 @@ import {
 import { getMarkMaterializationStep } from "../../materialization/marks/index.js";
 import { buildMaterializationPlan } from "../../materialization/planner.js";
 import {
+  CATEGORY_ORDER_CHANNELS,
   normalizeCategoryOrder,
   resolveCategoryOrder
 } from "../../grammar/categoryOrder.js";
@@ -19,8 +20,8 @@ const ORDER_OPTIONS = Object.freeze(["target", "channel", "values", "by", "direc
 const REMOVE_OPTIONS = Object.freeze(["target", "channel"]);
 
 function resolveAssignment(program, args, operation, { activeOnly = false } = {}) {
-  if (!["x", "y"].includes(args.channel)) {
-    throw new Error(`${operation} channel must be x or y.`);
+  if (!CATEGORY_ORDER_CHANNELS.includes(args.channel)) {
+    throw new Error(`${operation} channel must be x, y, or theta.`);
   }
   const requested = args.target === undefined
     ? undefined

package/src/actions/charts/area.js

@@ -0,0 +1,47 @@
+import { action } from "../../core/action.js";
+import { normalizeGroupFields } from "../../grammar/pathSeries.js";
+import { normalizeAreaBound, validateAreaEndpointPair } from "../../grammar/areaEndpoints.js";
+import {
+  applyFacadeGuides, normalizeAppearance, normalizeCategoricalColor, normalizeCategoricalGuides,
+  normalizeFieldEncoding, omitUndefinedOptions, positionArgs, resolveFacadeData, resolveFacadeId,
+  validateFacadeOptions
+} from "./shared.js";
+
+const OPERATION = "createAreaPlot";
+const OPTIONS = ["id", "data", "coordinate", "x", "y", "valueChannel", "baseline", "groupBy", "layout", "missing", "color", "area", "guides"];
+
+export const createAreaPlot = action({ op: OPERATION, description: "Create a simple, ranged, or stacked Cartesian area plot." }, function (args = {}) {
+  validateFacadeOptions(args, OPTIONS, OPERATION);
+  for (const [key, value] of Object.entries(args)) if (value === null) throw new TypeError(`${OPERATION} ${key} cannot be null.`);
+  const id = resolveFacadeId(this, args.id, { defaultId: "areaPlot", operation: OPERATION });
+  const data = resolveFacadeData(this, args.data, OPERATION);
+  const valueChannel = args.valueChannel ?? "y";
+  if (!["x", "y"].includes(valueChannel)) throw new Error("createAreaPlot valueChannel must be x or y.");
+  const independentChannel = valueChannel === "y" ? "x" : "y";
+  const independent = omitUndefinedOptions(normalizeFieldEncoding(args[independentChannel], `${OPERATION} ${independentChannel}`));
+  validateFacadeOptions(independent, ["field", "fieldType", "temporalUnit", "scale"], `${OPERATION} independent position`);
+  if (independent.fieldType !== undefined && !["quantitative", "temporal"].includes(independent.fieldType)) {
+    throw new Error("createAreaPlot independent position must be quantitative or temporal.");
+  }
+  const measurement = omitUndefinedOptions(normalizeFieldEncoding(args[valueChannel], `${OPERATION} ${valueChannel}`));
+  const ranged = Object.hasOwn(measurement, "lower") || Object.hasOwn(measurement, "upper");
+  validateFacadeOptions(measurement, ranged ? ["lower", "upper", "scale"] : ["field", "scale"], `${OPERATION} measurement`);
+  if (ranged && args.baseline !== undefined) throw new Error("createAreaPlot baseline cannot be combined with a range.");
+  const lower = ranged ? measurement.lower : measurement.field;
+  const upper = ranged ? measurement.upper : { datum: args.baseline ?? 0 };
+  validateAreaEndpointPair(normalizeAreaBound(lower), normalizeAreaBound(upper));
+  const groupBy = args.groupBy === undefined ? undefined : normalizeGroupFields(args.groupBy);
+  const area = omitUndefinedOptions(normalizeAppearance(args.area, ["fill", "opacity", "stroke", "strokeWidth", "curve"], `${OPERATION} area`));
+  const color = args.color === undefined ? undefined : normalizeCategoricalColor(args.color, `${OPERATION} color`);
+  if (color !== undefined && area.fill !== undefined) throw new Error("createAreaPlot area.fill cannot be combined with color.");
+  const guides = normalizeCategoricalGuides(args.guides, OPERATION, color);
+  let next = this.createAreaMark({ id, data, ...area, missing: args.missing ?? "error" });
+  if (groupBy !== undefined) next = next.encodeGroup({ target: id, fields: groupBy });
+  next = next[independentChannel === "x" ? "encodeX" : "encodeY"](positionArgs(independent, { target: id, coordinate: args.coordinate }))
+    [valueChannel === "y" ? "encodeYRange" : "encodeXRange"]({ target: id, lower, upper,
+      ...(measurement.scale === undefined ? {} : { scale: measurement.scale }),
+      ...(args.coordinate === undefined ? {} : { coordinate: args.coordinate }) })
+    .layoutSeries({ target: id, mode: args.layout ?? "overlay" });
+  if (color !== undefined) next = next.encodeColor({ target: id, ...color });
+  return applyFacadeGuides(next, guides, id, args.guides ?? {});
+});

package/src/actions/charts/bar.js

@@ -1,4 +1,5 @@
 import { action } from "../../core/action.js";
+import { isBarCategoryEncoding } from "../../grammar/bars/policy.js";
 import {
   applyFacadeGuides,
   inferFacadeFieldType,
@@ -42,12 +43,17 @@ export const createBarPlot = action(
     const width = normalizeTargetOptions(args.width, "createBarPlot width");
     const guides = normalizeGuides(args.guides, "createBarPlot");
 
-    let next = this
-      .createBarMark({ id, data, ...bar })
-      .encodeX(positionArgs(x, { target: id, coordinate: args.coordinate }))
-      .encodeY(positionArgs(y, { target: id, coordinate: args.coordinate }));
+    const positions = isBarCategoryEncoding(y)
+      ? [["encodeY", y], ["encodeX", x]]
+      : [["encodeX", x], ["encodeY", y]];
+    let next = this.createBarMark({ id, data, ...bar });
+    for (const [operation, encoding] of positions) {
+      next = next[operation](positionArgs(encoding, {
+        target: id, coordinate: args.coordinate
+      }));
+    }
     if (color !== undefined) next = next.encodeColor(targetArgs(color, id));
     if (width !== undefined) next = next.encodeBarWidth(targetArgs(width, id));
-    return applyFacadeGuides(next, guides);
+    return applyFacadeGuides(next, guides, id);
   }
 );

package/src/actions/charts/beeswarm.js

@@ -0,0 +1,70 @@
+import { action } from "../../core/action.js";
+import { isPlainObject } from "../../core/immutable.js";
+import { validateOptionObject } from "../../core/validation.js";
+import { findLayer } from "../../selectors/layers.js";
+import { resolveFacadeId, validateFacadeOptions } from "./shared.js";
+
+const OPTIONS = Object.freeze([
+  "id", "data", "coordinate", "x", "y", "color", "size", "shape",
+  "point", "packing", "guides"
+]);
+const PACKING_OPTIONS = Object.freeze(["maxOffset", "padding", "key", "overflow"]);
+
+function ownerScale(value, id, label) {
+  if (typeof value === "string") return { field: value, scale: { id } };
+  if (!isPlainObject(value)) return value;
+  if (value.scale !== undefined && !isPlainObject(value.scale)) {
+    throw new TypeError(`${label}.scale must be a plain object.`);
+  }
+  return {
+    ...value,
+    scale: { ...(value.scale ?? {}), id: value.scale?.id ?? id }
+  };
+}
+
+function normalizePacking(value, operation) {
+  if (value === false) return false;
+  const packing = value ?? {};
+  validateOptionObject(packing, PACKING_OPTIONS, `${operation} packing`);
+  return { ...packing };
+}
+
+export const createBeeswarmPlot = action(
+  {
+    op: "createBeeswarmPlot",
+    description: "Create a Point plot packed within categorical slots."
+  },
+  function (args = {}) {
+    const operation = "createBeeswarmPlot";
+    validateFacadeOptions(args, OPTIONS, operation);
+    if (args.x === undefined || args.y === undefined) {
+      throw new Error(`${operation} requires x and y.`);
+    }
+    const id = resolveFacadeId(this, args.id, {
+      defaultId: "beeswarmPlot",
+      operation
+    });
+    const packing = normalizePacking(args.packing, operation);
+    let next = this.createStripPlot({
+      id,
+      ...(args.data === undefined ? {} : { data: args.data }),
+      ...(args.coordinate === undefined ? {} : { coordinate: args.coordinate }),
+      x: ownerScale(args.x, `${id}X`, `${operation} x`),
+      y: ownerScale(args.y, `${id}Y`, `${operation} y`),
+      ...(args.color === undefined ? {} : { color: args.color }),
+      ...(args.size === undefined ? {} : { size: args.size }),
+      ...(args.shape === undefined ? {} : { shape: args.shape }),
+      ...(args.point === undefined ? {} : { point: args.point }),
+      ...(args.guides === undefined ? {} : { guides: args.guides })
+    });
+    if (packing === false) return next;
+    const layer = findLayer(next, id);
+    const categoryChannel = ["x", "y"].find(channel =>
+      ["nominal", "ordinal"].includes(layer?.encoding?.[channel]?.fieldType)
+    );
+    if (categoryChannel === undefined) {
+      throw new Error(`${operation} requires exactly one categorical position.`);
+    }
+    return next.packPoints({ target: id, channel: categoryChannel, ...packing });
+  }
+);

package/src/actions/charts/density.js

@@ -0,0 +1,44 @@
+import { action } from "../../core/action.js";
+import { validateNonEmptyString, validateOptionObject } from "../../core/validation.js";
+import {
+  applyFacadeGuides, normalizeAppearance, normalizeCategoricalColor, normalizeCategoricalGuides,
+  omitUndefinedOptions, resolveFacadeData, resolveFacadeId, validateFacadeOptions
+} from "./shared.js";
+
+const OPERATION = "createDensityPlot";
+const OPTIONS = ["id", "data", "coordinate", "field", "groupBy", "bandwidth", "extent", "steps",
+  "kernel", "normalization", "as", "densityChannel", "valueScale", "densityScale", "color", "area", "guides"];
+const AREA_OPTIONS = ["fill", "opacity", "stroke", "strokeWidth", "curve"];
+
+export const createDensityPlot = action({
+  op: OPERATION, description: "Create a baseline kernel-density area plot with optional explicit groups."
+}, function (args = {}) {
+  validateFacadeOptions(args, OPTIONS, OPERATION);
+  const id = resolveFacadeId(this, args.id, { defaultId: "densityPlot", operation: OPERATION });
+  const data = resolveFacadeData(this, args.data, OPERATION);
+  validateNonEmptyString(args.field, `${OPERATION} field`);
+  const { id: requestedId, data: requestedData, color: requestedColor, area: requestedArea,
+    guides: requestedGuides, ...density } = omitUndefinedOptions(args);
+  const area = omitUndefinedOptions(normalizeAppearance(requestedArea, AREA_OPTIONS, `${OPERATION} area`));
+  for (const [key, value] of Object.entries({ ...density, ...area })) {
+    if (value === null) throw new TypeError(`${OPERATION} ${key} cannot be null.`);
+  }
+  for (const key of ["valueScale", "densityScale"]) {
+    if (density[key] === undefined) continue;
+    validateOptionObject(density[key], undefined, `${OPERATION} ${key}`);
+    density[key] = omitUndefinedOptions(density[key]);
+  }
+  const color = requestedColor === undefined ? undefined
+    : normalizeCategoricalColor(requestedColor, `${OPERATION} color`, ["field", "fieldType", "scale", "palette", "layout"]);
+  if (color !== undefined && (color.field !== density.groupBy ||
+    color.layout !== undefined && color.layout !== "overlay")) {
+    throw new Error(`${OPERATION} color requires the same explicit groupBy field and overlay layout.`);
+  }
+  if (color !== undefined && area.fill !== undefined) {
+    throw new Error(`${OPERATION} area.fill cannot be combined with color.`);
+  }
+  const guides = normalizeCategoricalGuides(requestedGuides, OPERATION, color);
+  let next = this.createAreaMark({ id, data, ...area }).encodeDensity({ ...density, target: id });
+  if (color !== undefined) next = next.encodeColor({ ...color, target: id });
+  return applyFacadeGuides(next, guides, id, requestedGuides ?? {});
+});

package/src/actions/charts/ecdf.js

@@ -0,0 +1,183 @@
+import { action } from "../../core/action.js";
+import { validateUserId } from "../../core/identifiers.js";
+import { validateNonEmptyString, validateOptionObject } from "../../core/validation.js";
+import { normalizeGroupFields } from "../../grammar/pathSeries.js";
+import {
+  applyFacadeGuides,
+  normalizeAppearance,
+  normalizeCategoricalColor,
+  normalizeGuides,
+  resolveFacadeData,
+  resolveFacadeId,
+  targetArgs,
+  validateFacadeOptions
+} from "./shared.js";
+
+const OPTIONS = Object.freeze([
+  "id", "data", "coordinate", "field", "groupBy", "weight", "missing",
+  "as", "color", "line", "labels", "guides"
+]);
+const EDIT_OPTIONS = Object.freeze([
+  "target", "data", "coordinate", "field", "groupBy", "weight", "missing", "as", "color"
+]);
+const LINE_OPTIONS = Object.freeze(["strokeWidth", "stroke", "opacity"]);
+const LABEL_OPTIONS = Object.freeze([
+  "field", "value", "content", "normalizeBy", "format", "layout", "fill",
+  "opacity", "fontSize", "fontFamily", "fontWeight", "align", "baseline",
+  "rotation", "dx", "dy"
+]);
+
+function normalizeGrouping(value) {
+  return value === undefined ? [] : normalizeGroupFields(value);
+}
+
+function normalizeLabels(value, operation) {
+  if (value === undefined || value === false) return false;
+  validateOptionObject(value, LABEL_OPTIONS, `${operation} labels`);
+  return { ...value };
+}
+
+function normalizeOutputs(value, id, operation) {
+  if (value === undefined) {
+    return {
+      value: `__${id}ECDFData_value`,
+      cumulative: `__${id}ECDFData_cumulative`,
+      probability: `__${id}ECDFData_probability`
+    };
+  }
+  validateOptionObject(value, ["value", "cumulative", "probability"], `${operation} as`);
+  for (const field of ["value", "cumulative", "probability"]) {
+    validateNonEmptyString(value[field], `${operation} as.${field}`);
+  }
+  return { ...value };
+}
+
+function resolveOwner(program, requested) {
+  const eligible = program.semanticSpec.layers.filter(
+    layer => program.markConfigs[layer.id]?.ecdfPlot !== undefined
+  );
+  if (requested !== undefined) {
+    const id = validateUserId(requested, "ECDF-plot owner id");
+    const owner = eligible.find(layer => layer.id === id);
+    if (owner === undefined) throw new Error(`Unknown ECDF-plot owner "${id}".`);
+    return owner;
+  }
+  const current = eligible.find(layer => layer.id === program.context.currentMark);
+  if (current !== undefined) return current;
+  if (eligible.length === 1) return eligible[0];
+  if (eligible.length === 0) throw new Error("editECDFPlot requires an ECDF plot.");
+  throw new Error("editECDFPlot target is ambiguous; provide target.");
+}
+
+export const createECDFPlot = action(
+  {
+    op: "createECDFPlot",
+    description: "Create a right-continuous empirical cumulative distribution plot."
+  },
+  function (args = {}) {
+    const operation = "createECDFPlot";
+    validateFacadeOptions(args, OPTIONS, operation);
+    const id = resolveFacadeId(this, args.id, { defaultId: "ecdfPlot", operation });
+    const source = resolveFacadeData(this, args.data, operation);
+    validateNonEmptyString(args.field, `${operation} field`);
+    if (args.weight !== undefined) validateNonEmptyString(args.weight, `${operation} weight`);
+    const groupBy = normalizeGrouping(args.groupBy);
+    const as = normalizeOutputs(args.as, id, operation);
+    const color = args.color === undefined
+      ? undefined
+      : normalizeCategoricalColor(args.color, `${operation} color`);
+    if (color !== undefined && !groupBy.includes(color.field)) {
+      throw new Error(`${operation} color field must be included in groupBy.`);
+    }
+    const line = normalizeAppearance(args.line, LINE_OPTIONS, `${operation} line`);
+    const labels = normalizeLabels(args.labels, operation);
+    const guides = normalizeGuides(args.guides, operation);
+    const dataId = `${id}ECDFData`;
+
+    let next = this
+      .createECDFData({
+        id: dataId,
+        source,
+        field: args.field,
+        ...(groupBy.length === 0 ? {} : { groupBy }),
+        ...(args.weight === undefined ? {} : { weight: args.weight }),
+        ...(args.missing === undefined ? {} : { missing: args.missing }),
+        as
+      })
+      .createLineMark({ id, data: dataId, curve: "step-after", ...line })
+      .encodeX({
+        target: id,
+        field: as.value,
+        fieldType: "quantitative",
+        scale: { id: `${id}Value`, zero: false, nice: false },
+        ...(args.coordinate === undefined ? {} : { coordinate: args.coordinate })
+      })
+      .encodeY({
+        target: id,
+        field: as.probability,
+        fieldType: "quantitative",
+        scale: { id: `${id}Probability`, domain: [0, 1], zero: true, nice: false },
+        ...(args.coordinate === undefined ? {} : { coordinate: args.coordinate })
+      });
+    if (groupBy.length > 0) next = next.encodeGroup({ target: id, fields: groupBy });
+    if (color !== undefined) next = next.encodeColor(targetArgs(color, id));
+    if (labels !== false) {
+      const hasContent = ["field", "value", "content"].some(key => Object.hasOwn(labels, key));
+      next = next.createMarkLabels({
+        id: `${id}Label`,
+        source: id,
+        ...labels,
+        ...(hasContent ? {} : { field: as.probability })
+      });
+    }
+    next = applyFacadeGuides(next, guides, id, guides);
+    return next._withMarkConfig(id, {
+      ...next.markConfigs[id],
+      ecdfPlot: {
+        source,
+        data: dataId,
+        options: {
+          id,
+          data: source,
+          coordinate: args.coordinate,
+          field: args.field,
+          ...(groupBy.length === 0 ? {} : { groupBy }),
+          ...(args.weight === undefined ? {} : { weight: args.weight }),
+          missing: args.missing ?? "drop",
+          as,
+          ...(color === undefined ? {} : { color }),
+          line,
+          labels,
+          guides
+        }
+      }
+    });
+  }
+);
+
+export const editECDFPlot = action(
+  {
+    op: "editECDFPlot",
+    description: "Atomically revise an ECDF plot's source or statistical roles."
+  },
+  function (args = {}) {
+    validateFacadeOptions(args, EDIT_OPTIONS, "editECDFPlot");
+    const changes = Object.keys(args).filter(key => key !== "target");
+    if (changes.length === 0) {
+      throw new Error("editECDFPlot requires at least one ECDF option.");
+    }
+    const owner = resolveOwner(this, args.target);
+    const current = this.markConfigs[owner.id].ecdfPlot;
+    const revised = { ...current.options };
+    for (const key of changes) {
+      if (key === "groupBy" && args[key] === false) {
+        delete revised.groupBy;
+        if (!Object.hasOwn(args, "color")) delete revised.color;
+      }
+      else if (key === "weight" && args[key] === false) delete revised.weight;
+      else if (key === "color" && args[key] === false) delete revised.color;
+      else revised[key] = args[key];
+    }
+    return this.removeMark({ target: owner.id }).createECDFPlot(revised);
+  }
+);