ggaction 0.0.1

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

@@ -0,0 +1,179 @@
+import { action } from "../../../core/action.js";
+import { validateUserId } from "../../../core/identifiers.js";
+import {
+  validateNonEmptyString,
+  validateNonNegativeFinite
+} from "../../../core/validation.js";
+import { resolveGraphicBounds } from "../../../layout/canvas.js";
+import {
+  isTransformedScaleType,
+  mapContinuousScaleValues,
+  mapOrdinalPositionValues
+} from "../../../grammar/scales.js";
+import {
+  DEFAULT_TICK_COUNT,
+  inferHistogramBoundaries,
+  valuesFromTickConfig
+} from "../tickValues.js";
+import { DEFAULT_COLORS } from "../../../theme/defaults.js";
+import {
+  defaultAxisPosition,
+  resolveAxisTickGeometry,
+  validateAxisPosition
+} from "./policy.js";
+import { resolvePlotGraphicPlacement } from
+  "../../../materialization/graphicHierarchy.js";
+
+const OPTIONS = Object.freeze(["scale", "position", "count", "values", "length", "color", "lineWidth"]);
+const DEFAULTS = Object.freeze({
+  count: DEFAULT_TICK_COUNT,
+  length: 6,
+  color: DEFAULT_COLORS.mutedText,
+  lineWidth: 1
+});
+
+function validateOptions(args, operation, create) {
+  for (const key of Object.keys(args)) if (!OPTIONS.includes(key) || (!create && key === "scale")) throw new Error(`Unknown ${operation} option "${key}".`);
+  if (Object.hasOwn(args, "count") && Object.hasOwn(args, "values")) throw new Error(`${operation} cannot use count and values together.`);
+}
+
+function validateConfig(channel, config) {
+  validateAxisPosition(channel, config.position);
+  if (config.mode === "count" && (!Number.isInteger(config.count) || config.count <= 0)) throw new RangeError("Tick count must be a positive integer.");
+  if (
+    config.mode === "values" &&
+    (!Array.isArray(config.values) || !config.values.every(value =>
+      typeof value === "string" ||
+      typeof value === "boolean" ||
+      (typeof value === "number" && Number.isFinite(value))
+    ))
+  ) throw new TypeError("Tick values must be nominal values or finite numbers.");
+  validateNonNegativeFinite(config.length, "Tick length");
+  validateNonNegativeFinite(config.lineWidth, "Tick lineWidth");
+  validateNonEmptyString(config.color, "Tick color");
+}
+
+function geometry(program, channel, config) {
+  const scale = program.resolvedScales[config.scale];
+  const bounds = resolveGraphicBounds(program);
+  const discrete = ["ordinal", "band", "point"].includes(scale?.type);
+  if ((
+    !["linear", "time", "ordinal", "band", "point"].includes(scale?.type) &&
+    !isTransformedScaleType(scale?.type)
+  ) || !bounds) throw new Error("Axis ticks require a supported resolved scale and Canvas bounds.");
+  if (discrete && config.mode !== "values") throw new Error("Discrete axis ticks require explicit or inferred values, not count.");
+  const domain = scale.domain;
+  const values = valuesFromTickConfig(program, config);
+  if (discrete) {
+    const domainValues = new Set(domain);
+    if (!values.every(value => domainValues.has(value))) throw new RangeError("Tick values must be inside the scale domain.");
+  } else {
+    const low = Math.min(...domain), high = Math.max(...domain);
+    if (!values.every(value => value >= low && value <= high)) throw new RangeError("Tick values must be inside the scale domain.");
+  }
+  const positions = discrete
+    ? mapOrdinalPositionValues(values, scale)
+    : mapContinuousScaleValues(values, scale);
+  const resolved = {
+    values,
+    ...resolveAxisTickGeometry({
+      bounds,
+      channel,
+      position: config.position,
+      positions,
+      length: config.length
+    })
+  };
+  const canvas = program.graphicSpec.objects.canvas?.properties;
+  const coordinates = channel === "x"
+    ? [...resolved.x1, ...resolved.x2, resolved.y1, resolved.y2]
+    : [resolved.x1, resolved.x2, ...resolved.y1, ...resolved.y2];
+  const newEdgeDoesNotFit =
+    (config.position === "top" && resolved.y2 < 0) ||
+    (config.position === "right" && resolved.x2 > canvas?.width);
+  if (
+    !canvas ||
+    coordinates.some(value => !Number.isFinite(value)) ||
+    newEdgeDoesNotFit
+  ) {
+    throw new Error(`The ${channel}-axis ticks do not fit the Canvas margin.`);
+  }
+  return resolved;
+}
+
+function makeEdit(channel) {
+  const op = channel === "x" ? "editXAxisTicks" : "editYAxisTicks";
+  return action({ op, description: `Edit concrete ${channel}-axis ticks.` }, function (args = {}) {
+    validateOptions(args, op, false);
+    const id = `${channel}AxisTicks`;
+    if (this.graphicSpec.objects[id]?.type !== "line") throw new Error(`${op} requires existing axis ticks.`);
+    const previous = this.guideConfigs.axis?.[channel]?.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 = {
+      ...previous,
+      ...args,
+      ...(inferredValues === undefined ? {} : { values: inferredValues }),
+      ...(explicitMode ? { inferredValues: false } : {}),
+      mode
+    };
+    if (mode === "values") delete config.count; else delete config.values;
+    validateConfig(channel, config);
+    const resolved = geometry(this, channel, config);
+    let next = this._withGuideConfig(channel, 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] });
+    return next.editGraphics({ target: id, property: "stroke", value: config.color }).editGraphics({ target: id, property: "strokeWidth", value: config.lineWidth });
+  });
+}
+
+const editXAxisTicks = makeEdit("x"), editYAxisTicks = makeEdit("y");
+
+function makeCreate(channel) {
+  const op = channel === "x" ? "createXAxisTicks" : "createYAxisTicks";
+  const edit = channel === "x" ? "editXAxisTicks" : "editYAxisTicks";
+  return action({ op, description: `Create concrete ${channel}-axis ticks.` }, function (args = {}) {
+    validateOptions(args, op, true);
+    const scale = validateUserId(args.scale ?? channel, "Scale id");
+    const existingGuide = this.semanticSpec.guides.axis?.[channel]?.scale;
+    if (existingGuide && existingGuide !== scale) throw new Error(`${op} conflicts with the existing axis scale.`);
+    const id = `${channel}AxisTicks`;
+    if (this.graphicSpec.objects[id]) throw new Error(`${op} requires missing axis ticks.`);
+    const resolvedScale = this.resolvedScales[scale];
+    const inferredValues =
+      Object.hasOwn(args, "count") || Object.hasOwn(args, "values")
+        ? undefined
+        : ["ordinal", "band", "point"].includes(resolvedScale?.type)
+          ? resolvedScale.domain
+          : inferHistogramBoundaries(this, channel, scale);
+    const options =
+      inferredValues === undefined ? args : { ...args, values: inferredValues };
+    const config = { scale, position: defaultAxisPosition(channel), length: DEFAULTS.length, color: DEFAULTS.color, lineWidth: DEFAULTS.lineWidth, ...options, inferredValues: inferredValues !== undefined, mode: Object.hasOwn(options, "values") ? "values" : "count" };
+    if (config.mode === "values") delete config.count; else config.count ??= DEFAULTS.count;
+    validateConfig(channel, config); geometry(this, channel, config);
+    return this.editSemantic({ property: `guide.axis.${channel}.scale`, value: scale })
+      .createGraphics({
+        id,
+        type: "line",
+        length: 0,
+        ...resolvePlotGraphicPlacement(this)
+      })
+      ._withGuideConfig(channel, config)[edit]();
+  });
+}
+
+const createXAxisTicks = makeCreate("x"), createYAxisTicks = makeCreate("y");
+export function registerAxisTickActions(Class) {
+  Class.prototype.editXAxisTicks = editXAxisTicks; Class.prototype.editYAxisTicks = editYAxisTicks;
+  Class.prototype.createXAxisTicks = createXAxisTicks; Class.prototype.createYAxisTicks = createYAxisTicks;
+}

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

@@ -0,0 +1,264 @@
+import { action } from "../../../core/action.js";
+import { validateUserId } from "../../../core/identifiers.js";
+import {
+  validateKeys,
+  validateNonEmptyString,
+  validateNonNegativeFinite,
+  validatePositiveFinite
+} from "../../../core/validation.js";
+import { resolveGraphicBounds } from "../../../layout/canvas.js";
+import {
+  isTransformedScaleType,
+  mapContinuousScaleValues,
+  mapOrdinalPositionValues
+} from "../../../grammar/scales.js";
+import { DEFAULT_COLORS, DEFAULT_FONT_FAMILY } from
+  "../../../theme/defaults.js";
+import { findDataset } from "../../../selectors/datasets.js";
+import { formatAggregateTitle } from "../../../grammar/aggregate.js";
+import {
+  defaultAxisPosition,
+  defaultAxisTitleRotation,
+  resolveAxisTitleGeometry,
+  validateAxisPosition
+} from "./policy.js";
+import { resolvePlotGraphicPlacement } from
+  "../../../materialization/graphicHierarchy.js";
+
+const CREATE_OPTIONS = Object.freeze([
+  "text", "scale", "position", "at", "offset", "rotation", "color",
+  "fontSize", "fontFamily", "fontWeight"
+]);
+const EDIT_OPTIONS = CREATE_OPTIONS.filter(key => key !== "scale");
+const DEFAULTS = Object.freeze({
+  color: DEFAULT_COLORS.text,
+  fontSize: 13,
+  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.");
+  validateNonNegativeFinite(config.offset, "Axis title offset");
+  if (!Number.isFinite(config.rotation)) throw new TypeError("Axis title rotation must be finite radians.");
+  validateNonEmptyString(config.color, "Axis title color");
+  validatePositiveFinite(config.fontSize, "Axis title fontSize");
+  validateNonEmptyString(config.fontFamily, "Axis title fontFamily");
+  if (typeof config.fontWeight !== "string" && !Number.isFinite(config.fontWeight)) throw new TypeError("Axis title fontWeight must be a string or number.");
+}
+
+function inferText(program, channel, scaleId) {
+  const titles = new Set();
+  const primaryTitles = new Set();
+  for (const layer of program.semanticSpec.layers) {
+    const encoding = layer.encoding?.[channel];
+    if (
+      encoding?.scale === scaleId &&
+      typeof encoding.field === "string" &&
+      encoding.field.length
+    ) {
+      const dataset = findDataset(program, layer.data);
+      const density = dataset?.transform?.length === 1 &&
+        dataset.transform[0].type === "density"
+        ? dataset.transform[0]
+        : undefined;
+      const densityTitle = density === undefined
+        ? undefined
+        : encoding.field === density.as?.[0]
+          ? density.field
+          : encoding.field === density.as?.[1]
+            ? "Density"
+            : undefined;
+      const interval = dataset?.transform?.length === 1 &&
+        dataset.transform[0].type === "interval"
+        ? dataset.transform[0]
+        : undefined;
+      const intervalTitle = interval !== undefined &&
+        Object.values(interval.as).includes(encoding.field)
+        ? `${interval.center}(${interval.field})`
+        : undefined;
+      const box = dataset?.transform?.length === 1 &&
+        dataset.transform[0].type === "boxSummary"
+        ? dataset.transform[0]
+        : undefined;
+      const boxTitle = box !== undefined &&
+        Object.values(box.as).includes(encoding.field)
+        ? box.field
+        : undefined;
+      const title = encoding.title ?? densityTitle ?? intervalTitle ?? boxTitle ?? (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 !== 1) throw new Error(`Axis title text cannot be inferred for scale "${scaleId}".`);
+  return [...titles][0];
+}
+
+function resolveGeometry(program, channel, config) {
+  const scale = program.resolvedScales[config.scale];
+  const bounds = resolveGraphicBounds(program);
+  const discrete = ["ordinal", "band", "point"].includes(scale?.type);
+  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.");
+  let along;
+  if (config.at === "start") along = scale.range[0];
+  else if (config.at === "center") along = (scale.range[0] + scale.range[1]) / 2;
+  else if (config.at === "end") along = scale.range[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];
+    }
+  }
+  const geometry = resolveAxisTitleGeometry({
+    bounds,
+    channel,
+    position: config.position,
+    along,
+    offset: config.offset
+  });
+  const text = program.semanticSpec.guides.axis?.[channel]?.title ?? "";
+  const width = [...text].length * config.fontSize * 0.6;
+  const height = config.fontSize;
+  const cosine = Math.cos(config.rotation);
+  const sine = Math.sin(config.rotation);
+  const extentX = Math.abs(cosine) * width / 2 + Math.abs(sine) * height / 2;
+  const extentY = Math.abs(sine) * width / 2 + Math.abs(cosine) * height / 2;
+  const canvas = program.graphicSpec.objects.canvas?.properties;
+  const newEdgeFits = config.position === "top"
+    ? geometry.y - extentY >= 0
+    : config.position === "right"
+      ? geometry.x + extentX <= canvas?.width
+      : true;
+  if (!canvas || !newEdgeFits) {
+    throw new Error(`The ${channel}-axis title does not fit the Canvas margin.`);
+  }
+  return geometry;
+}
+
+function names(channel) {
+  const prefix = channel === "x" ? "X" : "Y";
+  return { create: `create${prefix}AxisTitle`, edit: `edit${prefix}AxisTitle`, graphic: `${channel}AxisTitle` };
+}
+
+function makeEdit(channel) {
+  const operation = names(channel);
+  return action({ op: operation.edit, description: `Edit the ${channel}-axis title.` }, function (args = {}) {
+      validateKeys(args, EDIT_OPTIONS, operation.edit);
+    if (this.graphicSpec.objects[operation.graphic]?.type !== "text") throw new Error(`${operation.edit} requires an existing axis title.`);
+    const previous = this.guideConfigs.axis?.[channel]?.title;
+    if (!previous) throw new Error(`${operation.edit} requires title configuration.`);
+    const { text, ...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)
+        : appearance.rotation ?? previous.rotation,
+      inferredRotation,
+      ...(explicitText ? { inferredText: false } : {})
+    };
+    validateConfig(channel, config);
+    let next = this;
+    const resolvedTitle = explicitText
+      ? validateText(text)
+      : config.inferredText === true
+        ? inferText(this, channel, config.scale)
+        : this.semanticSpec.guides.axis?.[channel]?.title;
+    if (resolvedTitle !== this.semanticSpec.guides.axis?.[channel]?.title) {
+      next = next.editSemantic({
+        property: `guide.axis.${channel}.title`,
+        value: validateText(resolvedTitle)
+      });
+    }
+    const resolvedText = validateText(next.semanticSpec.guides.axis?.[channel]?.title);
+    const geometry = resolveGeometry(next, channel, config);
+    next = next._withGuideConfig(channel, "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: "center", textBaseline: "middle",
+      rotation: config.rotation
+    };
+    for (const [property, value] of Object.entries(properties)) next = next.editGraphics({ target: operation.graphic, property, value });
+    return next;
+  });
+}
+
+const editXAxisTitle = makeEdit("x");
+const editYAxisTitle = makeEdit("y");
+
+function makeCreate(channel) {
+  const operation = names(channel);
+  return action({ op: operation.create, description: `Create the ${channel}-axis title.` }, function (args = {}) {
+      validateKeys(args, CREATE_OPTIONS, operation.create);
+    const scale = validateUserId(args.scale ?? channel, "Scale id");
+    const guideScale = this.semanticSpec.guides.axis?.[channel]?.scale;
+    if (guideScale && guideScale !== scale) throw new Error(`${operation.create} conflicts with the existing axis scale.`);
+    if (this.graphicSpec.objects[operation.graphic]) throw new Error(`${operation.create} requires a missing axis title.`);
+    const inferredText = !Object.hasOwn(args, "text");
+    const text = validateText(args.text ?? inferText(this, channel, scale));
+    const position = args.position ?? defaultAxisPosition(channel);
+    const inferredRotation = !Object.hasOwn(args, "rotation");
+    const config = {
+      scale,
+      inferredText,
+      position,
+      at: "center",
+      offset: channel === "x" ? 42 : 52,
+      rotation: inferredRotation
+        ? defaultAxisTitleRotation(channel, position)
+        : args.rotation,
+      inferredRotation,
+      color: DEFAULTS.color,
+      fontSize: DEFAULTS.fontSize,
+      fontFamily: DEFAULTS.fontFamily,
+      fontWeight: DEFAULTS.fontWeight,
+      ...Object.fromEntries(Object.entries(args).filter(
+        ([key]) => !["text", "scale", "position", "rotation"].includes(key)
+      ))
+    };
+    validateConfig(channel, config);
+    resolveGeometry(this, channel, config);
+    return this
+      .editSemantic({ property: `guide.axis.${channel}.scale`, value: scale })
+      .editSemantic({ property: `guide.axis.${channel}.title`, value: text })
+      .createGraphics({
+        id: operation.graphic,
+        type: "text",
+        ...resolvePlotGraphicPlacement(this)
+      })
+      ._withGuideConfig(channel, "title", config)[operation.edit]();
+  });
+}
+
+const createXAxisTitle = makeCreate("x");
+const createYAxisTitle = makeCreate("y");
+
+export function registerAxisTitleActions(Class) {
+  Class.prototype.createXAxisTitle = createXAxisTitle;
+  Class.prototype.createYAxisTitle = createYAxisTitle;
+  Class.prototype.editXAxisTitle = editXAxisTitle;
+  Class.prototype.editYAxisTitle = editYAxisTitle;
+}

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

@@ -0,0 +1,228 @@
+import { action } from "../../../core/action.js";
+import { isPlainObject } from "../../../core/immutable.js";
+import { validateKeys } from "../../../core/validation.js";
+import {
+  gridNames,
+  editGridConfig,
+  refreshGridConfig,
+  resolveGridConfig,
+  resolveGridGeometry,
+  resolveGridResources,
+  validateGridCreateArgs,
+  validateGridEditArgs
+} from "./resolve.js";
+
+const AGGREGATE_OPTIONS = Object.freeze(["horizontal", "vertical"]);
+
+function makeRematerialize(direction) {
+  const operation = gridNames(direction);
+  return action(
+    {
+      op: operation.rematerialize,
+      description: `Recompute concrete ${direction} grid lines.`
+    },
+    function (args = {}) {
+      if (!isPlainObject(args) || Object.keys(args).length !== 0) {
+        throw new TypeError(`${operation.rematerialize} does not accept options.`);
+      }
+      const storedConfig = this.guideConfigs.grid?.[direction];
+      const semantic = this.semanticSpec.guides.grid?.[direction];
+      if (
+        storedConfig === undefined ||
+        semantic?.scale !== storedConfig.scale ||
+        semantic.coordinate !== storedConfig.coordinate ||
+        this.graphicSpec.objects[operation.graphic]?.type !== "line"
+      ) {
+        throw new Error(
+          `${operation.rematerialize} requires an existing ${direction} grid.`
+        );
+      }
+
+      const config = refreshGridConfig(this, storedConfig);
+      const geometry = resolveGridGeometry(this, config);
+      let next = this._withGridConfig(direction, config).editGraphics({
+        target: operation.graphic,
+        property: "length",
+        value: geometry.values.length
+      });
+      for (const property of ["x1", "y1", "x2", "y2"]) {
+        next = next.editGraphics({
+          target: operation.graphic,
+          property,
+          value: geometry[property]
+        });
+      }
+      return next
+        .editGraphics({
+          target: operation.graphic,
+          property: "stroke",
+          value: config.color
+        })
+        .editGraphics({
+          target: operation.graphic,
+          property: "strokeWidth",
+          value: config.lineWidth
+        })
+        .editGraphics({
+          target: operation.graphic,
+          property: "strokeDash",
+          value: geometry.values.map(() => config.strokeDash)
+        });
+    }
+  );
+}
+
+function makeCreate(direction) {
+  const operation = gridNames(direction);
+  return action(
+    {
+      op: operation.create,
+      description: `Create a semantic and concrete ${direction} grid.`
+    },
+    function (args = {}) {
+      validateGridCreateArgs(args, operation.create);
+      if (
+        this.semanticSpec.guides.grid?.[direction] !== undefined ||
+        this.graphicSpec.objects[operation.graphic] !== undefined
+      ) {
+        throw new Error(`${operation.create} requires a missing grid.`);
+      }
+      const resources = resolveGridResources(this, direction, args);
+      const config = resolveGridConfig(this, direction, args, resources);
+      resolveGridGeometry(this, config);
+
+      return this
+        .editSemantic({
+          property: `guide.grid.${direction}.scale`,
+          value: resources.scale
+        })
+        .editSemantic({
+          property: `guide.grid.${direction}.coordinate`,
+          value: resources.coordinate
+        })
+        .createGraphics({
+          id: operation.graphic,
+          type: "line",
+          length: 0,
+          ...(resources.parent === undefined
+            ? {}
+            : { parent: resources.parent }),
+          before: resources.before
+        })
+        ._withGridConfig(direction, config)[operation.rematerialize]();
+    }
+  );
+}
+
+function makeEdit(direction) {
+  const operation = gridNames(direction);
+  const editOperation = `edit${direction === "horizontal" ? "Horizontal" : "Vertical"}Grid`;
+  return action(
+    {
+      op: editOperation,
+      description: `Edit the existing ${direction} grid.`
+    },
+    function (args = {}) {
+      validateGridEditArgs(args, editOperation);
+      const storedConfig = this.guideConfigs.grid?.[direction];
+      const semantic = this.semanticSpec.guides.grid?.[direction];
+      if (
+        storedConfig === undefined ||
+        semantic?.scale !== storedConfig.scale ||
+        semantic.coordinate !== storedConfig.coordinate ||
+        this.graphicSpec.objects[operation.graphic]?.type !== "line"
+      ) {
+        throw new Error(`${editOperation} requires an existing ${direction} grid.`);
+      }
+      const config = editGridConfig(storedConfig, args);
+      return this
+        ._withGridConfig(direction, config)
+        [operation.rematerialize]();
+    }
+  );
+}
+
+function normalizeDirection(value, direction) {
+  if (value === false) return undefined;
+  if (value === true || value === undefined) return {};
+  if (!isPlainObject(value)) {
+    throw new TypeError(
+      `createGrid ${direction} must be a boolean or plain object.`
+    );
+  }
+  return value;
+}
+
+const rematerializeHorizontalGrid = makeRematerialize("horizontal");
+const rematerializeVerticalGrid = makeRematerialize("vertical");
+const createHorizontalGrid = makeCreate("horizontal");
+const createVerticalGrid = makeCreate("vertical");
+const editHorizontalGrid = makeEdit("horizontal");
+const editVerticalGrid = makeEdit("vertical");
+
+const createGrid = action(
+  {
+    op: "createGrid",
+    description: "Create selected Cartesian grid directions."
+  },
+  function (args = {}) {
+    if (!isPlainObject(args)) {
+      throw new TypeError("createGrid options must be a plain object.");
+    }
+    validateKeys(args, AGGREGATE_OPTIONS, "createGrid");
+    const horizontal = normalizeDirection(args.horizontal, "horizontal");
+    const vertical = args.vertical === undefined
+      ? undefined
+      : normalizeDirection(args.vertical, "vertical");
+    if (horizontal === undefined && vertical === undefined) {
+      throw new Error("createGrid requires at least one selected direction.");
+    }
+
+    let next = this;
+    if (horizontal !== undefined) {
+      next = next.createHorizontalGrid(horizontal);
+    }
+    if (vertical !== undefined) {
+      next = next.createVerticalGrid(vertical);
+    }
+    return next;
+  }
+);
+
+const rematerializeGrid = action(
+  {
+    op: "rematerializeGrid",
+    description: "Recompute every existing grid direction."
+  },
+  function (args = {}) {
+    if (!isPlainObject(args) || Object.keys(args).length !== 0) {
+      throw new TypeError("rematerializeGrid does not accept options.");
+    }
+    let next = this;
+    let count = 0;
+    if (this.guideConfigs.grid?.horizontal !== undefined) {
+      next = next.rematerializeHorizontalGrid();
+      count += 1;
+    }
+    if (this.guideConfigs.grid?.vertical !== undefined) {
+      next = next.rematerializeVerticalGrid();
+      count += 1;
+    }
+    if (count === 0) {
+      throw new Error("rematerializeGrid requires an existing grid.");
+    }
+    return next;
+  }
+);
+
+export function registerGridActions(ProgramClass) {
+  ProgramClass.prototype.createGrid = createGrid;
+  ProgramClass.prototype.createHorizontalGrid = createHorizontalGrid;
+  ProgramClass.prototype.createVerticalGrid = createVerticalGrid;
+  ProgramClass.prototype.editHorizontalGrid = editHorizontalGrid;
+  ProgramClass.prototype.editVerticalGrid = editVerticalGrid;
+  ProgramClass.prototype.rematerializeGrid = rematerializeGrid;
+  ProgramClass.prototype.rematerializeHorizontalGrid =
+    rematerializeHorizontalGrid;
+  ProgramClass.prototype.rematerializeVerticalGrid = rematerializeVerticalGrid;
+}

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

@@ -0,0 +1 @@
+export { registerGridActions } from "./grid.js";