ggaction 0.0.11 → 0.0.13

package/src/actions/charts/rug-strip.js

@@ -0,0 +1,279 @@
+import { action } from "../../core/action.js";
+import { isPlainObject } from "../../core/immutable.js";
+import { validateNonEmptyString, validateNonNegativeFinite, validateOptionObject } from
+  "../../core/validation.js";
+import {
+  applyFacadeGuides,
+  normalizeAppearance,
+  normalizeEncoding,
+  normalizeFieldEncoding,
+  normalizeGuides,
+  omitUndefinedOptions,
+  positionArgs,
+  resolveFacadeData,
+  resolveFacadeId,
+  targetArgs,
+  inferFacadeFieldType,
+  validateFacadeOptions
+} from "./shared.js";
+
+const RUG_OPTIONS = Object.freeze(["id", "data", "coordinate", "x", "y", "edge", "tick", "guides"]);
+const MEASURE_OPTIONS = Object.freeze(["field", "fieldType", "temporalUnit", "scale"]);
+const TICK_OPTIONS = Object.freeze(["length", "stroke", "strokeWidth", "opacity"]);
+const STRIP_OPTIONS = Object.freeze([
+  "id", "data", "coordinate", "x", "y", "color", "size", "shape", "point", "jitter", "guides"
+]);
+const POINT_OPTIONS = Object.freeze([
+  "radius", "shape", "fill", "opacity", "stroke", "strokeWidth"
+]);
+const JITTER_OPTIONS = Object.freeze(["maxOffset", "seed", "key"]);
+
+function normalizeMeasure(value, operation, channel) {
+  const result = normalizeFieldEncoding(value, `${operation} ${channel}`);
+  validateOptionObject(result, MEASURE_OPTIONS, `${operation} ${channel}`);
+  validateNonEmptyString(result.field, `${operation} ${channel} field`);
+  const fieldType = result.fieldType ?? "quantitative";
+  if (!["quantitative", "temporal"].includes(fieldType)) {
+    throw new Error(`${operation} ${channel} must be quantitative or temporal.`);
+  }
+  return { ...result, fieldType };
+}
+
+function normalizeRugGuides(value, measure, operation) {
+  const guides = normalizeGuides(value, operation);
+  if (guides === false) return false;
+  validateOptionObject(guides, ["axes", "grid", "legend"], `${operation} guides`);
+  const anchor = measure === "x" ? "y" : "x";
+  if (guides.legend !== undefined && guides.legend !== false) {
+    throw new Error(`${operation} does not have a legend encoding.`);
+  }
+  let axes = guides.axes;
+  if (axes !== undefined && axes !== false) {
+    if (!isPlainObject(axes)) {
+      throw new TypeError(`${operation} guides.axes must be false or a plain object.`);
+    }
+    if (axes[anchor] !== undefined && axes[anchor] !== false) {
+      throw new Error(`${operation} cannot create an axis for its constant anchor.`);
+    }
+    axes = { ...axes, [anchor]: false };
+  } else if (axes === undefined) {
+    axes = { [measure]: {}, [anchor]: false };
+  }
+  let grid = guides.grid;
+  const anchorGrid = measure === "x" ? "horizontal" : "vertical";
+  if (grid !== undefined && grid !== false) {
+    if (!isPlainObject(grid)) {
+      throw new TypeError(`${operation} guides.grid must be false or a plain object.`);
+    }
+    if (grid[anchorGrid] !== undefined && grid[anchorGrid] !== false) {
+      throw new Error(`${operation} cannot create a grid for its constant anchor.`);
+    }
+    grid = { ...grid, [anchorGrid]: false };
+  } else if (grid === undefined) {
+    grid = false;
+  }
+  return { axes, grid, legend: false };
+}
+
+export const createRugPlot = action(
+  {
+    op: "createRugPlot",
+    description: "Create a one-dimensional Rug plot at an explicit plot edge."
+  },
+  function (args = {}) {
+    const operation = "createRugPlot";
+    validateFacadeOptions(args, RUG_OPTIONS, operation);
+    const hasX = args.x !== undefined;
+    const hasY = args.y !== undefined;
+    if (hasX === hasY) {
+      throw new Error(`${operation} requires exactly one of x or y.`);
+    }
+    const measure = hasX ? "x" : "y";
+    const edge = args.edge;
+    const supportedEdges = measure === "x" ? ["top", "bottom"] : ["left", "right"];
+    if (!supportedEdges.includes(edge)) {
+      throw new Error(`${operation} ${measure} requires edge ${supportedEdges.join(" or ")}.`);
+    }
+    const id = resolveFacadeId(this, args.id, {
+      defaultId: "rugPlot",
+      operation
+    });
+    const data = resolveFacadeData(this, args.data, operation);
+    const encoding = normalizeMeasure(args[measure], operation, measure);
+    const tick = normalizeAppearance(args.tick, TICK_OPTIONS, `${operation} tick`);
+    const guides = normalizeRugGuides(args.guides, measure, operation);
+    const anchor = measure === "x" ? "y" : "x";
+    const highEdge = edge === "top" || edge === "right";
+
+    let next = this.createTickMark({ id, data, ...tick });
+    if (args.coordinate !== undefined) {
+      next = next.createCoordinate({ id: args.coordinate, type: "cartesian", layers: [id] });
+    }
+    next = next[measure === "x" ? "encodeX" : "encodeY"](
+      positionArgs(encoding, { target: id })
+    );
+    next = next[anchor === "x" ? "encodeX" : "encodeY"]({
+      target: id,
+      datum: highEdge ? 1 : 0,
+      fieldType: "quantitative",
+      scale: { id: `${id}Anchor`, domain: [0, 1], zero: false, nice: false }
+    });
+    next = next.encodeAngle({ target: id, value: measure === "x" ? 0 : 90 });
+    return applyFacadeGuides(next, guides, id, guides);
+  }
+);
+
+function normalizeStripPosition(program, data, value, operation, channel) {
+  const result = normalizeFieldEncoding(value, `${operation} ${channel}`);
+  validateOptionObject(result, MEASURE_OPTIONS, `${operation} ${channel}`);
+  validateNonEmptyString(result.field, `${operation} ${channel} field`);
+  const fieldType = inferFacadeFieldType(
+    program,
+    data,
+    result,
+    `${operation} ${channel}`
+  );
+  if (!["quantitative", "temporal", "nominal", "ordinal"].includes(fieldType)) {
+    throw new Error(`${operation} ${channel} has an unsupported field type.`);
+  }
+  return { ...omitUndefinedOptions(result), fieldType };
+}
+
+function normalizeStripJitter(value, channel, slot, operation) {
+  if (value === undefined || value === false) return undefined;
+  if (!isPlainObject(value)) {
+    throw new TypeError(`${operation} jitter must be false or a plain object.`);
+  }
+  validateOptionObject(value, JITTER_OPTIONS, `${operation} jitter`);
+  if (!isPlainObject(value.maxOffset)) {
+    throw new TypeError(`${operation} jitter.maxOffset must be a plain object.`);
+  }
+  const keys = Object.keys(value.maxOffset);
+  const expected = slot === "category" ? "band" : "pixels";
+  if (keys.length !== 1 || keys[0] !== expected) {
+    throw new Error(
+      `${operation} ${slot} slot jitter requires maxOffset.${expected}.`
+    );
+  }
+  return { ...value, channel };
+}
+
+function normalizeStripGuides(value, actualChannels, hasLegend, operation) {
+  const guides = normalizeGuides(value, operation);
+  if (guides === false) return false;
+  validateOptionObject(guides, ["axes", "grid", "legend"], `${operation} guides`);
+  const anchor = actualChannels.length === 1
+    ? (actualChannels[0] === "x" ? "y" : "x")
+    : undefined;
+  let axes = guides.axes;
+  if (axes !== undefined && axes !== false) {
+    if (!isPlainObject(axes)) {
+      throw new TypeError(`${operation} guides.axes must be false or a plain object.`);
+    }
+    if (anchor !== undefined && axes[anchor] !== undefined && axes[anchor] !== false) {
+      throw new Error(`${operation} cannot create an axis for its constant slot.`);
+    }
+    axes = anchor === undefined ? { ...axes } : { ...axes, [anchor]: false };
+  } else if (axes === undefined) {
+    axes = {
+      x: actualChannels.includes("x") ? {} : false,
+      y: actualChannels.includes("y") ? {} : false
+    };
+  }
+  let grid = guides.grid;
+  if (grid === undefined) grid = false;
+  else if (grid !== false) {
+    if (!isPlainObject(grid)) {
+      throw new TypeError(`${operation} guides.grid must be false or a plain object.`);
+    }
+    const anchorGrid = anchor === "x" ? "vertical" : anchor === "y" ? "horizontal" : undefined;
+    if (
+      anchorGrid !== undefined && grid[anchorGrid] !== undefined &&
+      grid[anchorGrid] !== false
+    ) {
+      throw new Error(`${operation} cannot create a grid for its constant slot.`);
+    }
+    grid = anchorGrid === undefined ? { ...grid } : { ...grid, [anchorGrid]: false };
+  }
+  if (!hasLegend && guides.legend !== undefined && guides.legend !== false) {
+    throw new Error(`${operation} legend requires color, size, or shape.`);
+  }
+  const legend = guides.legend === undefined ? (hasLegend ? {} : false) : guides.legend;
+  return { axes, grid, legend };
+}
+
+export const createStripPlot = action(
+  {
+    op: "createStripPlot",
+    description: "Create a one-dimensional Strip plot with an optional categorical slot and jitter."
+  },
+  function (args = {}) {
+    const operation = "createStripPlot";
+    validateFacadeOptions(args, STRIP_OPTIONS, operation);
+    if (args.x === undefined) throw new Error(`${operation} requires x.`);
+    const id = resolveFacadeId(this, args.id, {
+      defaultId: "stripPlot",
+      operation
+    });
+    const data = resolveFacadeData(this, args.data, operation);
+    const x = normalizeStripPosition(this, data, args.x, operation, "x");
+    const y = args.y === undefined
+      ? undefined
+      : normalizeStripPosition(this, data, args.y, operation, "y");
+    const isMeasure = encoding => ["quantitative", "temporal"].includes(encoding.fieldType);
+    if (!isMeasure(x) && y === undefined) {
+      throw new Error(`${operation} x must be a quantitative or temporal measure when y is omitted.`);
+    }
+    if (y !== undefined && isMeasure(x) === isMeasure(y)) {
+      throw new Error(`${operation} requires exactly one measure and one categorical slot.`);
+    }
+    const color = normalizeEncoding(args.color, `${operation} color`);
+    const size = normalizeEncoding(args.size, `${operation} size`);
+    const shape = normalizeEncoding(args.shape, `${operation} shape`);
+    const { radius, ...point } = normalizeAppearance(
+      args.point,
+      POINT_OPTIONS,
+      `${operation} point`
+    );
+    if (radius !== undefined) {
+      validateNonNegativeFinite(radius, `${operation} point radius`);
+    }
+    if (radius !== undefined && size !== undefined) {
+      throw new Error(`${operation} point radius conflicts with size.`);
+    }
+    const categoryChannel = y === undefined ? undefined : (isMeasure(x) ? "y" : "x");
+    const jitterChannel = categoryChannel ?? "y";
+    const jitter = normalizeStripJitter(
+      args.jitter,
+      jitterChannel,
+      categoryChannel === undefined ? "constant" : "category",
+      operation
+    );
+    const guides = normalizeStripGuides(
+      args.guides,
+      y === undefined ? ["x"] : ["x", "y"],
+      color !== undefined || size !== undefined || shape !== undefined,
+      operation
+    );
+
+    let next = this.createPointMark({ id, data, ...point });
+    if (args.coordinate !== undefined) {
+      next = next.createCoordinate({ id: args.coordinate, type: "cartesian", layers: [id] });
+    }
+    next = next.encodeX(positionArgs(x, { target: id }));
+    next = y === undefined
+      ? next.encodeY({
+          target: id,
+          datum: 0.5,
+          fieldType: "quantitative",
+          scale: { id: `${id}Anchor`, domain: [0, 1], zero: false, nice: false }
+        })
+      : next.encodeY(positionArgs(y, { target: id }));
+    if (radius !== undefined) next = next.encodePointRadius({ target: id, value: radius });
+    if (color !== undefined) next = next.encodeColor(targetArgs(color, id));
+    if (size !== undefined) next = next.encodeSize(targetArgs(size, id));
+    if (shape !== undefined) next = next.encodeShape(targetArgs(shape, id));
+    if (jitter !== undefined) next = next.jitterPoints({ target: id, ...jitter });
+    return applyFacadeGuides(next, guides, id, guides);
+  }
+);

package/src/actions/charts/scatter.js

@@ -1,4 +1,5 @@
 import { action } from "../../core/action.js";
+import { validateNonNegativeFinite } from "../../core/validation.js";
 import {
   applyFacadeGuides,
   normalizeAppearance,
@@ -17,7 +18,7 @@ const OPTIONS = Object.freeze([
   "point", "guides"
 ]);
 const POINT_OPTIONS = Object.freeze([
-  "shape", "fill", "opacity", "stroke", "strokeWidth"
+  "shape", "fill", "opacity", "stroke", "strokeWidth", "radius"
 ]);
 
 export const createScatterPlot = action(
@@ -32,7 +33,7 @@ export const createScatterPlot = action(
       operation: "createScatterPlot"
     });
     const data = resolveFacadeData(this, args.data, "createScatterPlot");
-    const point = normalizeAppearance(
+    const { radius, ...point } = normalizeAppearance(
       args.point,
       POINT_OPTIONS,
       "createScatterPlot point"
@@ -43,14 +44,19 @@ export const createScatterPlot = action(
     const size = normalizeEncoding(args.size, "createScatterPlot size");
     const shape = normalizeEncoding(args.shape, "createScatterPlot shape");
     const guides = normalizeGuides(args.guides, "createScatterPlot");
+    if (Object.hasOwn(args.point ?? {}, "radius")) {
+      validateNonNegativeFinite(radius, "createScatterPlot point radius");
+      if (size !== undefined) throw new Error("createScatterPlot point radius conflicts with size.");
+    }
 
     let next = this
       .createPointMark({ id, data, ...point })
       .encodeX(positionArgs(x, { target: id, coordinate: args.coordinate }))
       .encodeY(positionArgs(y, { target: id, coordinate: args.coordinate }));
+    if (radius !== undefined) next = next.encodePointRadius({ target: id, value: radius });
     if (color !== undefined) next = next.encodeColor(targetArgs(color, id));
     if (size !== undefined) next = next.encodeSize(targetArgs(size, id));
     if (shape !== undefined) next = next.encodeShape(targetArgs(shape, id));
-    return applyFacadeGuides(next, guides);
+    return applyFacadeGuides(next, guides, id);
   }
 );

package/src/actions/charts/shared.js

@@ -1,9 +1,10 @@
 import { resolveOptionalUserId, validateUserId } from "../../core/identifiers.js";
 import { isPlainObject } from "../../core/immutable.js";
-import { validateOptionObject } from "../../core/validation.js";
-import { findDataset } from "../../selectors/datasets.js";
+import { validateNonEmptyString, validateOptionObject } from "../../core/validation.js";
+import { findDataset, requireMaterializedDataset } from "../../selectors/datasets.js";
 import { isNominalValue } from "../../grammar/scales/fields.js";
 import { hasLayer } from "../../selectors/layers.js";
+import { fulfillFacadeGuides } from "../guides/facade.js";
 
 export function validateFacadeOptions(args, supported, operation) {
   return validateOptionObject(args, supported, operation);
@@ -12,18 +13,17 @@ export function validateFacadeOptions(args, supported, operation) {
 export function resolveFacadeData(program, requested, operation) {
   if (requested !== undefined) {
     const id = validateUserId(requested, `${operation} dataset id`);
-    if (findDataset(program, id) === undefined) {
-      throw new Error(`Unknown dataset "${id}".`);
-    }
-    return id;
+    return requireMaterializedDataset(program, id).id;
   }
 
   const current = program.context.currentData;
   if (current !== undefined && findDataset(program, current) !== undefined) {
-    return current;
+    return requireMaterializedDataset(program, current).id;
   }
   const datasets = program.semanticSpec.datasets;
-  if (datasets.length === 1) return datasets[0].id;
+  if (datasets.length === 1) {
+    return requireMaterializedDataset(program, datasets[0].id).id;
+  }
   if (datasets.length > 1) {
     throw new Error(
       `${operation} requires data when multiple datasets are available.`
@@ -104,6 +104,39 @@ export function normalizeAppearance(value, supported, label) {
   return { ...value };
 }
 
+export function omitUndefinedOptions(value) {
+  return Object.fromEntries(Object.entries(value).filter(([, option]) => option !== undefined));
+}
+
+export function normalizeCategoricalColor(value, label, supported = ["field", "fieldType", "scale", "palette"]) {
+  const color = normalizeFieldEncoding(value, label);
+  validateOptionObject(color, supported, label);
+  validateNonEmptyString(color.field, `${label} field`);
+  if (color.fieldType !== undefined && !["nominal", "ordinal"].includes(color.fieldType)) {
+    throw new TypeError(`${label} must be nominal or ordinal.`);
+  }
+  if (color.scale !== undefined) validateOptionObject(color.scale, undefined, `${label}.scale`);
+  return { ...omitUndefinedOptions(color),
+    ...(color.scale === undefined ? {} : { scale: omitUndefinedOptions(color.scale) }) };
+}
+
+export function normalizeCategoricalGuides(value, operation, color) {
+  const guides = normalizeGuides(value, operation);
+  if (guides === false) return false;
+  validateOptionObject(guides, ["axes", "grid", "legend"], `${operation} guides`);
+  const legend = guides.legend;
+  if (legend !== undefined && legend !== false) {
+    validateOptionObject(legend, undefined, `${operation} guides.legend`);
+    if (color === undefined) throw new Error(`${operation} legend requires color.`);
+    if (Object.hasOwn(legend, "gradient") || Object.hasOwn(legend, "count") ||
+      legend.channels !== undefined && (!Array.isArray(legend.channels) ||
+        legend.channels.length !== 1 || legend.channels[0] !== "color")) {
+      throw new Error(`${operation} only supports a categorical color legend.`);
+    }
+  }
+  return guides;
+}
+
 export function normalizeTargetOptions(value, label) {
   if (value === undefined) return undefined;
   if (!isPlainObject(value)) {
@@ -136,6 +169,32 @@ export function targetArgs(encoding, target) {
   return { ...encoding, target };
 }
 
-export function applyFacadeGuides(program, guides) {
-  return guides === false ? program : program.createGuides(guides);
+export function applyFacadeGuides(program, guides, target, explicitGuides = guides) {
+  return fulfillFacadeGuides(program, guides, target, explicitGuides);
+}
+
+export function normalizeArcCategory(value, operation) {
+  const label = `${operation} category`;
+  const category = normalizeFieldEncoding(value, label);
+  validateOptionObject(category, ["field", "fieldType", "scale"], label);
+  validateNonEmptyString(category.field, `${label} field`);
+  const fieldType = category.fieldType === undefined ? "nominal" : category.fieldType;
+  if (!["nominal", "ordinal"].includes(fieldType)) throw new TypeError(`${label} must be nominal or ordinal.`);
+  if (category.scale !== undefined) {
+    validateOptionObject(category.scale, ["id", "type", "domain", "range", "reverse"], `${label}.scale`);
+    if (category.scale.type !== undefined && category.scale.type !== "band") {
+      throw new TypeError(`${label}.scale.type must be band.`);
+    }
+  }
+  return { ...omitUndefinedOptions(category), fieldType,
+    ...(category.scale === undefined ? {} : { scale: omitUndefinedOptions(category.scale) }) };
+}
+
+export function normalizeCategoryAggregate(args, operation) {
+  const aggregate = args.aggregate === undefined ? "count" : args.aggregate;
+  if (!["count", "sum"].includes(aggregate) || (aggregate === "sum") !== (args.value !== undefined)) {
+    throw new Error(`${operation} requires count without value or explicit sum with value.`);
+  }
+  if (args.value !== undefined) validateNonEmptyString(args.value, `${operation} value`);
+  return aggregate;
 }

package/src/actions/composition/actions.js

@@ -20,6 +20,9 @@ const LAYOUT_EDIT_OPTIONS = Object.freeze([
   "columns", "gap", "align", "padding"
 ]);
 const REPLACEMENT_OPTIONS = Object.freeze(["target", "program"]);
+const INSERTION_OPTIONS = Object.freeze(["id", "program", "before", "after"]);
+const REMOVAL_OPTIONS = Object.freeze(["target"]);
+const REORDER_OPTIONS = Object.freeze(["order"]);
 
 function option(args, name, fallback) {
   return Object.hasOwn(args, name) ? args[name] : fallback;
@@ -180,10 +183,17 @@ const editCompositionLayout = action(
       : current.padding;
     let layout;
     if (current.type === "facet") {
+      const gridCells = new Map(
+        (current.facet.grid?.cells ?? []).map(cell => [cell.id, cell])
+      );
       layout = resolveFacetLayout({
         children: current.children.map((id, index) => ({
           ...childDescriptor({ id, program: this.children[id] }),
-          value: current.facet.values[index]
+          value: current.facet.values[index],
+          ...(gridCells.has(id) ? {
+            row: gridCells.get(id).row,
+            column: gridCells.get(id).column
+          } : {})
         })),
         columns: option(args, "columns", current.columns),
         gap: option(args, "gap", current.gap),
@@ -224,6 +234,7 @@ const replaceCompositionChild = action(
   },
   function (args = {}) {
     validateOptionObject(args, REPLACEMENT_OPTIONS, "replaceCompositionChild");
+    this._assertCompositionProgram("replaceCompositionChild");
     if (this.compositionSpec.type === "facet") {
       throw new Error("replaceCompositionChild is not available on a facet composition.");
     }
@@ -246,9 +257,115 @@ const replaceCompositionChild = action(
   }
 );
 
+function requireConcat(program, operation) {
+  program._assertCompositionProgram(operation);
+  if (program.compositionSpec.type === "facet") {
+    throw new Error(`${operation} is not available on a facet composition.`);
+  }
+}
+
+const insertCompositionChild = action(
+  {
+    op: "insertCompositionChild",
+    description: "Insert one named child into a concat composition.",
+    scope: "composition"
+  },
+  function (args = {}) {
+    validateOptionObject(args, INSERTION_OPTIONS, "insertCompositionChild");
+    requireConcat(this, "insertCompositionChild");
+    const id = validateUserId(args.id, "Composition child ID");
+    if (Object.hasOwn(this.children, id)) {
+      throw new Error(`Composition child "${id}" already exists.`);
+    }
+    if (!(args.program instanceof CoreChartProgram)) {
+      throw new TypeError("insertCompositionChild program must be a ChartProgram.");
+    }
+    if (args.before !== undefined && args.after !== undefined) {
+      throw new Error("insertCompositionChild before and after are mutually exclusive.");
+    }
+    childDescriptor({ id, program: args.program });
+    const order = [...this.compositionSpec.children];
+    if (args.before !== undefined || args.after !== undefined) {
+      const property = args.before !== undefined ? "before" : "after";
+      const anchor = validateUserId(args[property], `Composition child ${property}`);
+      const index = order.indexOf(anchor);
+      if (index < 0) throw new Error(`Unknown composition child "${anchor}".`);
+      order.splice(index + (property === "after" ? 1 : 0), 0, id);
+    } else {
+      order.push(id);
+    }
+    return applyCompositionState(this, {
+      children: freezeOwned({ ...this.children, [id]: args.program }),
+      compositionSpec: { ...this.compositionSpec, children: order }
+    }, [id]);
+  }
+);
+
+const removeCompositionChild = action(
+  {
+    op: "removeCompositionChild",
+    description: "Remove one named child from a concat composition.",
+    scope: "composition"
+  },
+  function (args = {}) {
+    validateOptionObject(args, REMOVAL_OPTIONS, "removeCompositionChild");
+    requireConcat(this, "removeCompositionChild");
+    const target = validateUserId(args.target, "Composition child target");
+    if (!Object.hasOwn(this.children, target)) {
+      throw new Error(`Unknown composition child "${target}".`);
+    }
+    if (this.compositionSpec.children.length === 1) {
+      throw new Error("removeCompositionChild must leave at least one child.");
+    }
+    const { [target]: _removed, ...remaining } = this.children;
+    void _removed;
+    return applyCompositionState(this, {
+      children: freezeOwned(remaining),
+      compositionSpec: {
+        ...this.compositionSpec,
+        children: this.compositionSpec.children.filter(id => id !== target)
+      }
+    });
+  }
+);
+
+const reorderCompositionChildren = action(
+  {
+    op: "reorderCompositionChildren",
+    description: "Reorder every named child in a concat composition.",
+    scope: "composition"
+  },
+  function (args = {}) {
+    validateOptionObject(args, REORDER_OPTIONS, "reorderCompositionChildren");
+    requireConcat(this, "reorderCompositionChildren");
+    if (!Array.isArray(args.order) || args.order.length === 0 ||
+        args.order.some(id => typeof id !== "string" || id.length === 0)) {
+      throw new TypeError("reorderCompositionChildren order must be a non-empty child ID array.");
+    }
+    if (new Set(args.order).size !== args.order.length) {
+      throw new Error("reorderCompositionChildren order must not contain duplicates.");
+    }
+    const current = this.compositionSpec.children;
+    if (args.order.length !== current.length ||
+        args.order.some(id => !Object.hasOwn(this.children, id))) {
+      throw new Error("reorderCompositionChildren order must contain every current child exactly once.");
+    }
+    if (args.order.every((id, index) => id === current[index])) {
+      throw new Error("reorderCompositionChildren requires an actual order change.");
+    }
+    return applyCompositionState(this, {
+      children: this.children,
+      compositionSpec: { ...this.compositionSpec, children: [...args.order] }
+    });
+  }
+);
+
 export function registerCompositionActions(ProgramClass) {
   ProgramClass.prototype.useProgram = useProgram;
   ProgramClass.prototype.materializeComposition = materializeComposition;
   ProgramClass.prototype.editCompositionLayout = editCompositionLayout;
   ProgramClass.prototype.replaceCompositionChild = replaceCompositionChild;
+  ProgramClass.prototype.insertCompositionChild = insertCompositionChild;
+  ProgramClass.prototype.removeCompositionChild = removeCompositionChild;
+  ProgramClass.prototype.reorderCompositionChildren = reorderCompositionChildren;
 }

package/src/actions/data/bin.js

@@ -0,0 +1,29 @@
+import {
+  deriveBinRows,
+  normalizeBinTransform,
+  resolveBinTransform
+} from "../../grammar/bin.js";
+import { derivedCreator, derivedMaterializer } from "./shared.js";
+
+const OPTIONS = Object.freeze([
+  "id", "source", "field", "maxBins", "step", "boundaries", "extent",
+  "nice", "zero", "includeEmpty", "members", "as"
+]);
+
+export const materializeBinData = derivedMaterializer(
+  "materializeBinData",
+  "Materialize one immutable one-dimensional bin dataset.",
+  "bin",
+  deriveBinRows,
+  resolveBinTransform
+);
+
+export const createBinData = derivedCreator(
+  "createBinData",
+  "Create reusable one-dimensional bin bounds, counts, and members.",
+  OPTIONS,
+  "Bin dataset id",
+  "Bin source dataset id",
+  normalizeBinTransform,
+  "materializeBinData"
+);

package/src/actions/data/computed.js

@@ -0,0 +1,24 @@
+import {
+  deriveComputedRows,
+  normalizeComputedTransform
+} from "../../grammar/computed.js";
+import { derivedCreator, derivedMaterializer } from "./shared.js";
+
+const OPTIONS = Object.freeze(["id", "source", "as", "expression"]);
+
+export const materializeComputedData = derivedMaterializer(
+  "materializeComputedData",
+  "Materialize one immutable row-level arithmetic dataset.",
+  "computed",
+  deriveComputedRows
+);
+
+export const createComputedData = derivedCreator(
+  "createComputedData",
+  "Create a finite computed field from a closed arithmetic expression.",
+  OPTIONS,
+  "Computed dataset id",
+  "Computed source dataset id",
+  normalizeComputedTransform,
+  "materializeComputedData"
+);