ggaction 0.0.16 → 0.0.18

package/src/actions/boxPlots/materialize.js

@@ -1,3 +1,4 @@
+import { boxBarWidth, boxWhiskerAppearance } from "./options.js";
 import { applyFacadeGuides } from "../charts/shared.js";
 import { action } from "../../core/action.js";
 import { validateUserId } from "../../core/identifiers.js";
@@ -60,7 +61,7 @@ export const materializeBoxPlot = /* @__PURE__ */ action(
         medianId,
         outlierId
       },
-      barWidth: { band: config.width },
+      barWidth: boxBarWidth(config.width),
       fill: config.box.fill,
       opacity: config.box.opacity,
       stroke: config.box.stroke,
@@ -73,6 +74,7 @@ export const materializeBoxPlot = /* @__PURE__ */ action(
       source,
       category: category.field,
       field: measure.field,
+      ...(config.summary === undefined ? {} : { summary: config.summary }),
       whisker: config.whisker.type,
       ...(config.whisker.factor === undefined
         ? {}
@@ -144,7 +146,8 @@ export const materializeBoxPlot = /* @__PURE__ */ action(
           }),
       coordinate: layer.coordinate,
       stroke: "#111111",
-      strokeWidth: 1.5
+      strokeWidth: 1.5,
+      ...boxWhiskerAppearance(config.whisker)
     });
     next = next
       .editSemantic({
@@ -156,7 +159,8 @@ export const materializeBoxPlot = /* @__PURE__ */ action(
         id: ownerId,
         type: "rect",
         length: 0,
-        ...resolvePlotGraphicPlacement(next)
+        ...resolvePlotGraphicPlacement(next, next.graphicSpec.objects.plotBorder === undefined
+          ? {} : { before: "plotBorder" })
       })
       .rematerializeBarMark({ id: ownerId })
       .createBoxMedian({

package/src/actions/boxPlots/options.js

@@ -15,12 +15,13 @@ import {
   requestedStrokeDetails,
   STROKE_STYLE_PROPERTIES
 } from "../../grammar/strokeStyle.js";
+import { ERROR_BAR_APPEARANCE_OPTIONS, resolveErrorBarAppearance } from "../errorBars/edit.js";
 import { DEFAULT_COLORS } from "../../theme/defaults.js";
 import { normalizeGuides } from "../charts/shared.js";
 
 export const BOX_PLOT_OPTIONS = Object.freeze([
   "id", "target", "data", "x", "y", "coordinate", "whisker",
-  "width", "outliers", "box", "median", "outlier", "guides"
+  "width", "summary", "outliers", "box", "median", "outlier", "guides"
 ]);
 
 const DEFAULT_BOX = {
@@ -97,15 +98,20 @@ export function resolveBoxGuides(value) {
     : normalizeGuides(value, "createBoxPlot");
 }
 
-export function resolveBoxWhisker(value, operation = "createBoxPlot") {
-  if (value === undefined) return Object.freeze({ type: "tukey", factor: 1.5 });
+export function resolveBoxWhisker(value, operation = "createBoxPlot", defaultType = "tukey") {
+  if (value === undefined) return Object.freeze(defaultType === "tukey" ? { type: "tukey", factor: 1.5 } : { type: defaultType });
   const options = plainOptions(
     value,
-    ["type", "factor"],
+    ["type", "factor", ...ERROR_BAR_APPEARANCE_OPTIONS],
     "whisker",
     operation
   );
-  const type = options.type ?? "tukey";
+  const requestedAppearance = boxWhiskerAppearance(options);
+  const appearance = Object.keys(requestedAppearance).length === 0 ? {} : resolveErrorBarAppearance(requestedAppearance, {
+    defaults: { caps: true, capSize: 8, stroke: "#111111", strokeWidth: 1.5, strokeDash: "solid", opacity: 1 }, operation
+  });
+  const style = Object.fromEntries(Object.keys(requestedAppearance).map(key => [key, appearance[key]]));
+  const type = options.type ?? defaultType;
   if (!["tukey", "minmax"].includes(type)) {
     throw new Error(`Unsupported createBoxPlot whisker type "${type}".`);
   }
@@ -113,7 +119,7 @@ export function resolveBoxWhisker(value, operation = "createBoxPlot") {
     if (options.factor !== undefined) {
       throw new Error("createBoxPlot minmax whiskers do not accept factor.");
     }
-    return Object.freeze({ type });
+    return Object.freeze({ type, ...style });
   }
   const factor = options.factor ?? 1.5;
   if (!Number.isFinite(factor) || factor <= 0) {
@@ -121,11 +127,15 @@ export function resolveBoxWhisker(value, operation = "createBoxPlot") {
       "createBoxPlot whisker factor must be positive and finite."
     );
   }
-  return Object.freeze({ type, factor });
+  return Object.freeze({ type, factor, ...style });
 }
 
 export function resolveBoxWidth(value, operation = "createBoxPlot") {
-  const options = plainOptions(value, ["band"], "width", operation);
+  const options = plainOptions(value, ["band", "pixels"], "width", operation);
+  if (options.pixels !== undefined) {
+    if (options.band !== undefined) throw new Error(`${operation} width accepts band or pixels, not both.`);
+    return Object.freeze({ pixels: validatePositiveFinite(options.pixels, `${operation} width.pixels`) });
+  }
   const band = options.band ?? 0.7;
   if (!Number.isFinite(band) || band <= 0 || band >= 1) {
     throw new RangeError(
@@ -135,6 +145,15 @@ export function resolveBoxWidth(value, operation = "createBoxPlot") {
   return band;
 }
 
+export function boxBarWidth(width) {
+  return typeof width === "number" ? { band: width } : width;
+}
+
+export function boxWhiskerAppearance(whisker) {
+  return Object.fromEntries(ERROR_BAR_APPEARANCE_OPTIONS.filter(key => Object.hasOwn(whisker, key))
+    .map(key => [key, whisker[key]]));
+}
+
 export function resolveBoxAppearance(value, operation = "createBoxPlot") {
   return resolveAppearance(
     value,
@@ -146,13 +165,20 @@ export function resolveBoxAppearance(value, operation = "createBoxPlot") {
 }
 
 export function resolveBoxMedianAppearance(value, operation = "createBoxPlot") {
-  return resolveAppearance(
-    value,
+  const options = value === undefined ? {} : value;
+  if (!isPlainObject(options)) throw new TypeError(`${operation} median must be a plain object.`);
+  const { width, ...appearance } = options;
+  if (width !== undefined && width !== "auto") {
+    plainOptions(width, ["pixels"], "median.width", operation);
+    validatePositiveFinite(width.pixels, `${operation} median.width.pixels`);
+  }
+  return Object.freeze({ ...resolveAppearance(
+    appearance,
     DEFAULT_MEDIAN,
     "median",
     operation,
     requestedStrokeDetails
-  );
+  ), ...(width === undefined || width === "auto" ? {} : { width: Object.freeze({ pixels: width.pixels }) }) });
 }
 
 export function resolveBoxOutlierAppearance(value, operation = "createBoxPlot") {

package/src/actions/canvas/actions.js

@@ -1,8 +1,11 @@
 import { action } from "../../core/action.js";
+import { findLayer } from "../../selectors/layers.js";
 import {
   DEFAULT_CANVAS,
   DEFAULT_MARGIN,
   normalizeMargin,
+  normalizePlotBorder,
+  resolveCanvasPlot,
   validateCanvasState
 } from "../../layout/canvas.js";
 import { cloneAndFreeze } from "../../core/immutable.js";
@@ -22,7 +25,9 @@ const CANVAS_OPTIONS = Object.freeze([
   "width",
   "height",
   "background",
-  "margin"
+  "margin",
+  "plot",
+  "plotBorder"
 ]);
 
 function validateOptions(args, operation, { allowEmpty = false } = {}) {
@@ -39,34 +44,60 @@ function requireCanvas(program) {
   return canvas;
 }
 
-function resolveCanvasState(program, args) {
-  const canvas = requireCanvas(program);
-  const canvasConfig = program.materializationConfigs.canvas;
-  const baseMargin = canvasConfig?.margin ?? DEFAULT_MARGIN;
-  const baseSize = canvasConfig?.size ?? { width: "explicit", height: "explicit" };
+function resolveCanvasState(properties, args, config = {}) {
+  const baseMargin = config.margin ?? DEFAULT_MARGIN;
+  const baseSize = config.size ?? { width: "explicit", height: "explicit" };
   const state = {
-    width: Object.hasOwn(args, "width")
-      ? args.width
-      : canvas.properties.width,
-    height: Object.hasOwn(args, "height")
-      ? args.height
-      : canvas.properties.height,
-    background: Object.hasOwn(args, "background")
-      ? args.background
-      : canvas.properties.background,
-    margin: Object.hasOwn(args, "margin")
-      ? normalizeMargin(args.margin, baseMargin)
-      : baseMargin,
+    width: properties.width, height: properties.height, background: properties.background,
+    ...args,
+    margin: Object.hasOwn(args, "margin") ? normalizeMargin(args.margin, baseMargin) : baseMargin,
+    plotBorder: normalizePlotBorder(Object.hasOwn(args, "plotBorder") ? args.plotBorder : (config.plotBorder ?? false)),
     size: {
       width: Object.hasOwn(args, "width") ? "explicit" : baseSize.width,
       height: Object.hasOwn(args, "height") ? "explicit" : baseSize.height
     }
   };
-
+  delete state.plot;
+  const plot = resolveCanvasPlot(args, config.plot);
+  if (plot !== undefined) {
+    state.plot = plot;
+    state.width = plot.width + state.margin.left + state.margin.right;
+    state.height = plot.height + state.margin.top + state.margin.bottom;
+    state.size = { width: "explicit", height: "explicit" };
+  }
   validateCanvasState(state);
   return cloneAndFreeze(state);
 }
 
+function applyCanvasState(program, args, state) {
+  let next = program;
+  for (const property of ["width", "height", "background"]) {
+    if (Object.hasOwn(args, property) || state.plot !== undefined && property !== "background") {
+      next = next.editGraphics({ target: CANVAS_GRAPHIC_ID, property, value: state[property] });
+    }
+  }
+  return next._withCanvasConfig({ margin: state.margin, size: state.size,
+    ...(state.plot === undefined ? {} : { plot: state.plot }),
+    ...(state.plotBorder === false ? {} : { plotBorder: state.plotBorder }) });
+}
+
+function assertBorderAvailable(program, state) {
+  if (state.plotBorder !== false && program.materializationConfigs.canvas?.plotBorder === undefined &&
+      (program.graphicSpec.objects.plotBorder !== undefined || findLayer(program, "plotBorder") !== undefined)) {
+    throw new Error('Canvas plotBorder requires the reserved graphic id "plotBorder".');
+  }
+}
+
+function createHierarchy(program) {
+  return program.createGraphics({ id: CANVAS_GRAPHIC_ID, type: "canvas" })
+    .createGraphics({ id: PLOT_GRAPHIC_ID, type: "collection", parent: CANVAS_GRAPHIC_ID });
+}
+
+function initialSize(args) {
+  return Object.fromEntries(["width", "height"].map(key =>
+    [key, args.plot || Object.hasOwn(args, key) ? "explicit" : "auto"]));
+}
+
 export const editCanvas = /* @__PURE__ */ action(
   {
     op: "editCanvas",
@@ -74,30 +105,25 @@ export const editCanvas = /* @__PURE__ */ action(
   },
   function (args = {}) {
     validateOptions(args, "editCanvas");
-    const state = resolveCanvasState(this, args);
+    const state = resolveCanvasState(requireCanvas(this).properties, args, this.materializationConfigs.canvas);
+    assertBorderAvailable(this, state);
     let next = this;
-
-    for (const property of ["width", "height", "background"]) {
-      if (Object.hasOwn(args, property)) {
-        next = next.editGraphics({
-          target: "canvas",
-          property,
-          value: state[property]
-        });
-      }
+    if (state.plotBorder === false && this.materializationConfigs.canvas?.plotBorder !== undefined) {
+      next = next.editGraphics({ target: "plotBorder", remove: true });
     }
-
-    next = next._withCanvasConfig({ margin: state.margin, size: state.size });
+    next = applyCanvasState(next, args, state);
 
     if (
       Object.hasOwn(args, "width") ||
       Object.hasOwn(args, "height") ||
-      Object.hasOwn(args, "margin")
+      Object.hasOwn(args, "margin") || Object.hasOwn(args, "plot")
     ) {
       next = applyMaterializationPlan(
         next,
         planCanvasRematerialization(next)
       );
+    } else if (state.plotBorder !== false && Object.hasOwn(args, "plotBorder")) {
+      next = next.rematerializePlotBorder();
     }
 
     return next;
@@ -114,36 +140,14 @@ export const createCanvas = /* @__PURE__ */ action(
 
     assertCanvasHierarchyAvailable(this);
 
-    const options = {
-      width: Object.hasOwn(args, "width")
-        ? args.width
-        : DEFAULT_CANVAS.width,
-      height: Object.hasOwn(args, "height")
-        ? args.height
-        : DEFAULT_CANVAS.height,
-      background: Object.hasOwn(args, "background")
-        ? args.background
-        : DEFAULT_CANVAS.background,
-      margin: Object.hasOwn(args, "margin")
-        ? args.margin
-        : DEFAULT_CANVAS.margin
-    };
-
-    const next = this
-      .createGraphics({ id: CANVAS_GRAPHIC_ID, type: "canvas" })
-      .createGraphics({
-        id: PLOT_GRAPHIC_ID,
-        type: "collection",
-        parent: CANVAS_GRAPHIC_ID
-      })
-      .editCanvas(options);
-    return next._withCanvasConfig({
-      ...next.materializationConfigs.canvas,
-      size: {
-        width: Object.hasOwn(args, "width") ? "explicit" : "auto",
-        height: Object.hasOwn(args, "height") ? "explicit" : "auto"
-      }
-    });
+    const plot = resolveCanvasPlot(args);
+    const options = { ...DEFAULT_CANVAS, ...args };
+    if (plot !== undefined) {
+      delete options.width;
+      delete options.height;
+    }
+    const next = createHierarchy(this).editCanvas(options);
+    return next._withCanvasConfig({ ...next.materializationConfigs.canvas, size: initialSize(args) });
   }
 );
 
@@ -155,38 +159,9 @@ export const createBasicCanvas = /* @__PURE__ */ action(
   function (args = {}) {
     validateOptions(args, "createCanvas", { allowEmpty: true });
     assertCanvasHierarchyAvailable(this);
-    const state = {
-      width: Object.hasOwn(args, "width") ? args.width : DEFAULT_CANVAS.width,
-      height: Object.hasOwn(args, "height") ? args.height : DEFAULT_CANVAS.height,
-      background: Object.hasOwn(args, "background")
-        ? args.background
-        : DEFAULT_CANVAS.background,
-      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"
-      }
-    };
-    validateCanvasState(state);
-    let next = this
-      .createGraphics({
-        id: CANVAS_GRAPHIC_ID,
-        type: "canvas"
-      })
-      .createGraphics({
-        id: PLOT_GRAPHIC_ID,
-        type: "collection",
-        parent: CANVAS_GRAPHIC_ID
-      });
-    for (const property of ["width", "height", "background"]) {
-      next = next.editGraphics({
-        target: CANVAS_GRAPHIC_ID,
-        property,
-        value: state[property]
-      });
-    }
-    return next._withCanvasConfig({ margin: state.margin, size: state.size });
+    const state = resolveCanvasState(DEFAULT_CANVAS, args, { size: initialSize(args) });
+    assertBorderAvailable(this, state);
+    const next = applyCanvasState(createHierarchy(this), state, state);
+    return state.plotBorder === false ? next : next.rematerializePlotBorder();
   }
 );

package/src/actions/canvas/fitting.js

@@ -7,6 +7,8 @@ import {
 import { resolveGraphicBounds } from "../../layout/canvas.js";
 import { findCanvasGraphic } from
   "../../materialization/graphicHierarchy.js";
+import { resolveConcreteGraphicBounds } from "../../grammar/schemas/graphicBounds.js";
+import { textBoundsFitCanvas } from "../../core/textMetrics.js";
 
 const OPTIONS = Object.freeze([
   "padding",
@@ -45,7 +47,17 @@ function normalizeOptions(args) {
 
 function probe(program, margin) {
   try {
-    return { ok: true, program: program.editCanvas({ margin }) };
+    const next = program.editCanvas({ margin });
+    const title = next.guideConfigs.axis?.y?.title;
+    if (title?.inferredOffset && Math.abs(Math.cos(title.rotation)) < 1e-10) {
+      const bounds = resolveConcreteGraphicBounds(next.graphicSpec, "yAxisTitle", next.materializationConfigs.textMetrics);
+      const edge = title.position === "right" ? "right" : "left";
+      const reserve = title.fontSize / 4 * (edge === "right" ? 1 : -1);
+      if (!textBoundsFitCanvas({...bounds, [edge]: bounds[edge] + reserve}, findCanvasGraphic(next).properties)) {
+        return {ok:false, message:"Fitting retains inferred axis-title ink clearance."};
+      }
+    }
+    return { ok: true, program: next };
   } catch (error) {
     return {
       ok: false,
@@ -171,6 +183,9 @@ export const fitCanvas = /* @__PURE__ */ action(
         this.materializationConfigs.canvas?.margin === undefined) {
       throw new Error("fitCanvas requires an existing Canvas.");
     }
+    if (this.materializationConfigs.canvas.plot !== undefined) {
+      throw new Error("fitCanvas requires fixed outer dimensions; disable Canvas plot sizing first.");
+    }
     const previous = this.materializationConfigs.fitting;
     if (samePolicy(previous?.policy, policy) &&
         previous?.result?.signature === layoutSignature(this)) {

package/src/actions/canvas/index.js

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

package/src/actions/canvas/plotBorder.js

@@ -0,0 +1,28 @@
+import { action } from "../../core/action.js";
+import { noOptions } from "../../core/validation.js";
+import { resolveGraphicBounds } from "../../layout/canvas.js";
+import { resolvePlotGraphicPlacement } from "../../materialization/graphicHierarchy.js";
+
+export const rematerializePlotBorder = /* @__PURE__ */ action(
+  { op: "rematerializePlotBorder", description: "Materialize the optional inset plot border." },
+  function (args = {}) {
+    noOptions(args, "rematerializePlotBorder");
+    const border = this.materializationConfigs.canvas?.plotBorder;
+    if (border === undefined) return this;
+    const plot = resolveGraphicBounds(this);
+    const half = border.lineWidth / 2;
+    const axis = this.graphicSpec.objects["plot-main"].children?.find(id =>
+      /^(?:(?:x|y|theta|radial)Axis(?:Line|Ticks|Labels|Title)|parallelAxis(?:Lines|Ticks|Labels|Titles))$/.test(id));
+    let next = this.graphicSpec.objects.plotBorder === undefined
+      ? this.createGraphics({ id: "plotBorder", type: "rect",
+        ...resolvePlotGraphicPlacement(this, axis === undefined ? {} : { before: axis }) })
+      : this;
+    const properties = { x: plot.x + half, y: plot.y + half,
+      width: plot.width - border.lineWidth, height: plot.height - border.lineWidth,
+      fill: "transparent", stroke: border.color, strokeWidth: border.lineWidth };
+    for (const [property, value] of Object.entries(properties)) {
+      next = next.editGraphics({ target: "plotBorder", property, value });
+    }
+    return next;
+  }
+);

package/src/actions/charts/area.js

@@ -21,8 +21,8 @@ export const createAreaPlot = /* @__PURE__ */ action({ op: OPERATION, descriptio
   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.");
+  if (independent.fieldType !== undefined && !["quantitative", "temporal", "nominal", "ordinal"].includes(independent.fieldType)) {
+    throw new Error("createAreaPlot independent position must be quantitative, temporal, or categorical.");
   }
   const measurement = omitUndefinedOptions(normalizeFieldEncoding(args[valueChannel], `${OPERATION} ${valueChannel}`));
   const ranged = Object.hasOwn(measurement, "lower") || Object.hasOwn(measurement, "upper");

package/src/actions/charts/bar.js

@@ -17,12 +17,26 @@ import {
 } from "./shared.js";
 
 const OPTIONS = Object.freeze([
-  "id", "data", "coordinate", "x", "y", "color", "width", "bar", "guides"
+  "id", "data", "coordinate", "orientation", "x", "y", "color", "width", "bar", "guides"
 ]);
 const BAR_OPTIONS = Object.freeze([
   "fill", "opacity", "stroke", "strokeWidth", ...RECT_STYLE_PROPERTIES
 ]);
 
+function normalizeBarPosition(value, label) {
+  const encoding = normalizeFieldEncoding(value, label);
+  if (!Object.hasOwn(encoding, "lower") && !Object.hasOwn(encoding, "upper")) return encoding;
+  validateFacadeOptions(encoding, ["lower", "upper", "fieldType", "scale"], label);
+  if (typeof encoding.lower !== "string" || !encoding.lower.length ||
+      typeof encoding.upper !== "string" || !encoding.upper.length) {
+    throw new TypeError(`${label} range requires lower and upper field names.`);
+  }
+  if (encoding.fieldType !== undefined && encoding.fieldType !== "quantitative") {
+    throw new Error(`${label} range must be quantitative.`);
+  }
+  return { ...encoding, fieldType: "quantitative" };
+}
+
 export const createBarPlot = /* @__PURE__ */ action(
   {
     op: "createBarPlot",
@@ -36,18 +50,31 @@ export const createBarPlot = /* @__PURE__ */ action(
     });
     const data = resolveFacadeData(this, args.data, "createBarPlot");
     const bar = normalizeAppearance(args.bar, BAR_OPTIONS, "createBarPlot bar");
-    const x = normalizeFieldEncoding(args.x, "createBarPlot x");
-    const y = normalizeFieldEncoding(args.y, "createBarPlot y");
+    const x = normalizeBarPosition(args.x, "createBarPlot x");
+    const y = normalizeBarPosition(args.y, "createBarPlot y");
+    const xRange = Object.hasOwn(x, "lower");
+    const yRange = Object.hasOwn(y, "lower");
+    if (xRange && yRange) throw new Error("createBarPlot accepts only one range channel.");
     x.fieldType = inferFacadeFieldType(this, data, x, "createBarPlot x");
     y.fieldType = inferFacadeFieldType(this, data, y, "createBarPlot y");
     const color = normalizeEncoding(args.color, "createBarPlot color");
     const width = normalizeTargetOptions(args.width, "createBarPlot width");
     const guides = normalizeGuides(args.guides, "createBarPlot");
+    const numeric = x.fieldType === "quantitative" && y.fieldType === "quantitative" &&
+      x.bin === undefined && y.bin === undefined && x.aggregate === undefined && y.aggregate === undefined;
+    if (args.orientation !== undefined && !numeric) throw new Error("createBarPlot orientation requires raw numeric positions.");
+    const orientation = numeric ? args.orientation ?? (xRange ? "horizontal" : "vertical") : undefined;
+    if (numeric && ((xRange && orientation !== "horizontal") || (yRange && orientation !== "vertical"))) {
+      throw new Error("createBarPlot range must match its numeric measure orientation.");
+    }
 
-    const positions = isBarCategoryEncoding(y)
-      ? [["encodeY", y], ["encodeX", x]]
-      : [["encodeX", x], ["encodeY", y]];
-    let next = this.createBarMark({ id, data, ...bar });
+    if (!numeric && ((xRange && !isBarCategoryEncoding(y)) || (yRange && !isBarCategoryEncoding(x)))) {
+      throw new Error("createBarPlot range requires a categorical or temporal opposite position.");
+    }
+    const positions = isBarCategoryEncoding(y) || orientation === "horizontal"
+      ? [["encodeY", y], [xRange ? "encodeXRange" : "encodeX", x]]
+      : [["encodeX", x], [yRange ? "encodeYRange" : "encodeY", y]];
+    let next = this.createBarMark({ id, data, ...bar, ...(orientation === undefined ? {} : { orientation }) });
     for (const [operation, encoding] of positions) {
       next = next[operation](positionArgs(encoding, {
         target: id, coordinate: args.coordinate

package/src/actions/charts/ecdf.js

@@ -1,5 +1,6 @@
-import { action } from "../../core/action.js";
 import { validateUserId } from "../../core/identifiers.js";
+import { action } from "../../core/action.js";
+import { resolveConfiguredOwner } from "../../selectors/layers.js";
 import { validateNonEmptyString, validateOptionObject } from "../../core/validation.js";
 import { normalizeGroupFields } from "../../grammar/pathSeries.js";
 import { STROKE_STYLE_PROPERTIES } from "../../grammar/strokeStyle.js";
@@ -55,22 +56,7 @@ function normalizeOutputs(value, id, operation) {
   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 = /* @__PURE__ */ action(
   {
@@ -169,7 +155,7 @@ export const editECDFPlot = /* @__PURE__ */ action(
     if (changes.length === 0) {
       throw new Error("editECDFPlot requires at least one ECDF option.");
     }
-    const owner = resolveOwner(this, args.target);
+    const owner = resolveConfiguredOwner(this, args.target, { config: "ecdfPlot", operation: "editECDFPlot", kind: "ECDF", article: "an" }, validateUserId);
     const current = this.markConfigs[owner.id].ecdfPlot;
     const revised = { ...current.options };
     for (const key of changes) {

package/src/actions/charts/endpoints.js

@@ -1,7 +1,8 @@
+import { validateUserId } from "../../core/identifiers.js";
 import { action } from "../../core/action.js";
 import { STROKE_STYLE_PROPERTIES } from "../../grammar/strokeStyle.js";
 import { isPlainObject } from "../../core/immutable.js";
-import { validateUserId } from "../../core/identifiers.js";
+import { resolveConfiguredOwner } from "../../selectors/layers.js";
 import { isNominalValue } from "../../grammar/scales/fields.js";
 import {
   validateNonEmptyString,
@@ -400,22 +401,7 @@ export const createDumbbellPlot = /* @__PURE__ */ action(
   }
 );
 
-function resolveEndpointOwner(program, requested) {
-  const eligible = program.semanticSpec.layers.filter(
-    layer => program.markConfigs[layer.id]?.endpointPlot !== undefined
-  );
-  if (requested !== undefined) {
-    const id = validateUserId(requested, "Endpoint-plot owner id");
-    const owner = eligible.find(layer => layer.id === id);
-    if (owner === undefined) throw new Error(`Unknown endpoint-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("editEndpointPlot requires an endpoint plot.");
-  throw new Error("editEndpointPlot target is ambiguous; provide target.");
-}
+
 
 const KIND_METHOD = Object.freeze({
   dot: "createDotPlot",
@@ -457,7 +443,7 @@ export const editEndpointPlot = /* @__PURE__ */ action(
     if (changes.length === 0) {
       throw new Error("editEndpointPlot requires at least one endpoint-plot option.");
     }
-    const owner = resolveEndpointOwner(this, args.target);
+    const owner = resolveConfiguredOwner(this, args.target, { config: "endpointPlot", operation: "editEndpointPlot", kind: "endpoint", article: "an" }, validateUserId);
     const current = this.markConfigs[owner.id].endpointPlot;
     const allowed = KIND_ROLES[current.kind];
     const invalid = changes.find(key => !allowed.has(key));

package/src/actions/charts/heatmap.js

@@ -153,12 +153,12 @@ export const createHeatmap = /* @__PURE__ */ action(
     if (args.bin === undefined) {
       const x = normalizePosition(args.x, "x", true);
       const y = normalizePosition(args.y, "y", true);
-      const color = normalizeFieldEncoding(args.color, `${OPERATION} color`);
-      const next = this
+      const color = args.color === undefined ? undefined : normalizeFieldEncoding(args.color, `${OPERATION} color`);
+      let next = this
         .createRectMark({ id, data, ...rect })
         .encodeX(positionArgs(x, { target: id, coordinate: args.coordinate }))
-        .encodeY(positionArgs(y, { target: id, coordinate: args.coordinate }))
-        .encodeColor(targetArgs(color, id));
+        .encodeY(positionArgs(y, { target: id, coordinate: args.coordinate }));
+      if (color !== undefined) next = next.encodeColor(targetArgs(color, id));
       return applyFacadeGuides(next, guides, id);
     }
 

package/src/actions/charts/index.js

@@ -5,6 +5,7 @@ import { createBarPlot } from "./bar.js";
 import { createHistogram } from "./histogram.js";
 import { createLinePlot } from "./line.js";
 import { createScatterPlot } from "./scatter.js";
+import { createTextPlot } from "./text.js";
 import { createParallelCoordinates } from "./parallel.js";
 import { createPiePlot } from "./pie.js";
 import { createDensityPlot } from "./density.js";
@@ -28,6 +29,7 @@ export function registerChartActions(ProgramClass) {
   ProgramClass.prototype.createHeatmap = createHeatmap;
   ProgramClass.prototype.createHistogram = createHistogram;
   ProgramClass.prototype.createScatterPlot = createScatterPlot;
+  ProgramClass.prototype.createTextPlot = createTextPlot;
   ProgramClass.prototype.createLinePlot = createLinePlot;
   ProgramClass.prototype.createParallelCoordinates = createParallelCoordinates;
   ProgramClass.prototype.createPiePlot = createPiePlot;