ggaction 0.0.2 → 0.0.4

package/src/actions/boxPlots/options.js

@@ -27,12 +27,12 @@ const DEFAULT_OUTLIER = Object.freeze({
   opacity: 0.75
 });
 
-function plainOptions(value, keys, label) {
+function plainOptions(value, keys, label, operation = "createBoxPlot") {
   if (value === undefined) return {};
   if (!isPlainObject(value)) {
-    throw new TypeError(`createBoxPlot ${label} must be a plain object.`);
+    throw new TypeError(`${operation} ${label} must be a plain object.`);
   }
-  validateKeys(value, keys, `createBoxPlot ${label}`);
+  validateKeys(value, keys, `${operation} ${label}`);
   return value;
 }
 
@@ -52,12 +52,12 @@ export function boxEncodingArgs(value) {
   };
 }
 
-export function resolveBoxWhisker(value) {
+export function resolveBoxWhisker(value, operation = "createBoxPlot") {
   if (value === undefined) return Object.freeze({ type: "tukey", factor: 1.5 });
   if (!isPlainObject(value)) {
-    throw new TypeError("createBoxPlot whisker must be a plain object.");
+    throw new TypeError(`${operation} whisker must be a plain object.`);
   }
-  validateKeys(value, ["type", "factor"], "createBoxPlot whisker");
+  validateKeys(value, ["type", "factor"], `${operation} whisker`);
   const type = value.type ?? "tukey";
   if (!["tukey", "minmax"].includes(type)) {
     throw new Error(`Unsupported createBoxPlot whisker type "${type}".`);
@@ -77,8 +77,8 @@ export function resolveBoxWhisker(value) {
   return Object.freeze({ type, factor });
 }
 
-export function resolveBoxWidth(value) {
-  const options = plainOptions(value, ["band"], "width");
+export function resolveBoxWidth(value, operation = "createBoxPlot") {
+  const options = plainOptions(value, ["band"], "width", operation);
   const band = options.band ?? 0.7;
   if (!Number.isFinite(band) || band <= 0 || band >= 1) {
     throw new RangeError(
@@ -88,11 +88,12 @@ export function resolveBoxWidth(value) {
   return band;
 }
 
-export function resolveBoxAppearance(value) {
+export function resolveBoxAppearance(value, operation = "createBoxPlot") {
   const options = plainOptions(
     value,
     ["fill", "opacity", "stroke", "strokeWidth"],
-    "box"
+    "box",
+    operation
   );
   return Object.freeze({
     fill: options.fill === undefined
@@ -113,8 +114,13 @@ export function resolveBoxAppearance(value) {
   });
 }
 
-export function resolveBoxMedianAppearance(value) {
-  const options = plainOptions(value, ["stroke", "strokeWidth"], "median");
+export function resolveBoxMedianAppearance(value, operation = "createBoxPlot") {
+  const options = plainOptions(
+    value,
+    ["stroke", "strokeWidth"],
+    "median",
+    operation
+  );
   return Object.freeze({
     stroke: options.stroke === undefined
       ? DEFAULT_MEDIAN.stroke
@@ -128,8 +134,13 @@ export function resolveBoxMedianAppearance(value) {
   });
 }
 
-export function resolveBoxOutlierAppearance(value) {
-  const options = plainOptions(value, ["shape", "radius", "opacity"], "outlier");
+export function resolveBoxOutlierAppearance(value, operation = "createBoxPlot") {
+  const options = plainOptions(
+    value,
+    ["shape", "radius", "opacity"],
+    "outlier",
+    operation
+  );
   return Object.freeze({
     shape: options.shape === undefined
       ? DEFAULT_OUTLIER.shape

package/src/actions/canvas/actions.js

@@ -6,6 +6,7 @@ import {
   validateCanvasState
 } from "../../layout/canvas.js";
 import { cloneAndFreeze } from "../../core/immutable.js";
+import { validateOptionObject } from "../../core/validation.js";
 import {
   applyMaterializationPlan,
   planCanvasRematerialization
@@ -13,6 +14,7 @@ import {
 import {
   assertCanvasHierarchyAvailable,
   CANVAS_GRAPHIC_ID,
+  findCanvasGraphic,
   PLOT_GRAPHIC_ID
 } from "../../materialization/graphicHierarchy.js";
 
@@ -24,21 +26,11 @@ const CANVAS_OPTIONS = Object.freeze([
 ]);
 
 function validateOptions(args, operation, { allowEmpty = false } = {}) {
-  const keys = Object.keys(args);
-
-  if (!allowEmpty && keys.length === 0) {
-    throw new TypeError(`${operation} requires at least one option.`);
-  }
-
-  for (const key of keys) {
-    if (!CANVAS_OPTIONS.includes(key)) {
-      throw new Error(`Unknown ${operation} option "${key}".`);
-    }
-  }
+  validateOptionObject(args, CANVAS_OPTIONS, operation, { allowEmpty });
 }
 
 function requireCanvas(program) {
-  const canvas = program.graphicSpec.objects.canvas;
+  const canvas = findCanvasGraphic(program);
 
   if (canvas?.type !== "canvas") {
     throw new Error("editCanvas requires an existing canvas.");
@@ -49,8 +41,9 @@ function requireCanvas(program) {
 
 function resolveCanvasState(program, args) {
   const canvas = requireCanvas(program);
-  const baseMargin =
-    program.materializationConfigs.canvas?.margin ?? DEFAULT_MARGIN;
+  const canvasConfig = program.materializationConfigs.canvas;
+  const baseMargin = canvasConfig?.margin ?? DEFAULT_MARGIN;
+  const baseSize = canvasConfig?.size ?? { width: "explicit", height: "explicit" };
   const state = {
     width: Object.hasOwn(args, "width")
       ? args.width
@@ -63,7 +56,11 @@ function resolveCanvasState(program, args) {
       : canvas.properties.background,
     margin: Object.hasOwn(args, "margin")
       ? normalizeMargin(args.margin, baseMargin)
-      : baseMargin
+      : baseMargin,
+    size: {
+      width: Object.hasOwn(args, "width") ? "explicit" : baseSize.width,
+      height: Object.hasOwn(args, "height") ? "explicit" : baseSize.height
+    }
   };
 
   validateCanvasState(state);
@@ -90,7 +87,7 @@ export const editCanvas = action(
       }
     }
 
-    next = next._withCanvasConfig({ margin: state.margin });
+    next = next._withCanvasConfig({ margin: state.margin, size: state.size });
 
     if (
       Object.hasOwn(args, "width") ||
@@ -132,7 +129,7 @@ export const createCanvas = action(
         : DEFAULT_CANVAS.margin
     };
 
-    return this
+    const next = this
       .createGraphics({ id: CANVAS_GRAPHIC_ID, type: "canvas" })
       .createGraphics({
         id: PLOT_GRAPHIC_ID,
@@ -140,5 +137,12 @@ export const createCanvas = action(
         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"
+      }
+    });
   }
 );

package/src/actions/composition/actions.js

@@ -0,0 +1,247 @@
+import { action } from "../../core/action.js";
+import { ChartProgram as CoreChartProgram } from "../../core/ChartProgram.js";
+import { freezeOwned, isPlainObject } from "../../core/immutable.js";
+import { validateUserId } from "../../core/identifiers.js";
+import { validateOptionObject } from "../../core/validation.js";
+import {
+  normalizeCompositionPadding,
+  resolveCompositionLayout
+} from "../../layout/composition.js";
+import { resolveFacetLayout } from "../../layout/facets.js";
+import { namespaceGraphicSnapshot } from "../../materialization/compositionSnapshot.js";
+import { materializeCompositionGraphics } from
+  "../../materialization/composition.js";
+import { materializeFacetGraphics } from "../../materialization/facets.js";
+
+const CONCAT_OPTIONS = Object.freeze([
+  "id", "programs", "gap", "align", "padding"
+]);
+const LAYOUT_EDIT_OPTIONS = Object.freeze(["gap", "align", "padding"]);
+const REPLACEMENT_OPTIONS = Object.freeze(["target", "program"]);
+
+function normalizeChildEntry(entry, index) {
+  const fallbackId = `view-${index + 1}`;
+  if (entry instanceof CoreChartProgram) {
+    return { id: fallbackId, program: entry };
+  }
+  if (!isPlainObject(entry)) {
+    throw new TypeError(`Composition program ${index} must be a ChartProgram or wrapper.`);
+  }
+  validateOptionObject(entry, ["id", "program"], `Composition program ${index}`);
+  if (!(entry.program instanceof CoreChartProgram)) {
+    throw new TypeError(`Composition program ${index}.program must be a ChartProgram.`);
+  }
+  return {
+    id: entry.id === undefined
+      ? fallbackId
+      : validateUserId(entry.id, "Composition child ID"),
+    program: entry.program
+  };
+}
+
+function childDescriptor({ id, program }) {
+  if (program.actionStack.length !== 0) {
+    throw new Error(`Composition child "${id}" has an unfinished action stack.`);
+  }
+  namespaceGraphicSnapshot(program.graphicSpec, { namespace: id });
+  const canvasId = program.graphicSpec.order.find(
+    graphicId => program.graphicSpec.objects[graphicId]?.type === "canvas"
+  );
+  const canvas = program.graphicSpec.objects[canvasId];
+  const size = program.materializationConfigs.canvas?.size ?? {
+    width: "explicit",
+    height: "explicit"
+  };
+  return {
+    id,
+    width: canvas.properties.width,
+    height: canvas.properties.height,
+    widthMode: size.width,
+    heightMode: size.height
+  };
+}
+
+function normalizeCompositionInput(args, direction) {
+  validateOptionObject(args, CONCAT_OPTIONS, direction === "horizontal" ? "hconcat" : "vconcat");
+  if (!Array.isArray(args.programs) || args.programs.length < 2) {
+    throw new TypeError("Composition requires at least two programs.");
+  }
+  const entries = args.programs.map(normalizeChildEntry);
+  const ids = entries.map(entry => entry.id);
+  if (new Set(ids).size !== ids.length) {
+    throw new Error("Composition child IDs must be unique.");
+  }
+  const id = args.id === undefined
+    ? "composition"
+    : validateUserId(args.id, "Composition ID");
+  const layout = resolveCompositionLayout({
+    direction,
+    children: entries.map(childDescriptor),
+    ...(Object.hasOwn(args, "gap") ? { gap: args.gap } : {}),
+    ...(Object.hasOwn(args, "align") ? { align: args.align } : {}),
+    ...(Object.hasOwn(args, "padding") ? { padding: args.padding } : {})
+  });
+  return {
+    children: freezeOwned(Object.fromEntries(
+      entries.map(entry => [entry.id, entry.program])
+    )),
+    compositionSpec: {
+      id,
+      direction,
+      children: ids,
+      gap: layout.gap,
+      align: layout.align,
+      padding: layout.padding
+    }
+  };
+}
+
+const useProgram = action(
+  {
+    op: "useProgram",
+    description: "Retain one named child program in a composition.",
+    scope: "composition"
+  },
+  function ({ id } = {}) {
+    validateUserId(id, "Composition child ID");
+    if (!Object.hasOwn(this.children, id)) {
+      throw new Error(`Unknown composition child "${id}".`);
+    }
+    return this;
+  }
+);
+
+const materializeComposition = action(
+  {
+    op: "materializeComposition",
+    description: "Materialize retained child programs into one graphic tree.",
+    scope: "composition"
+  },
+  function () {
+    return this.compositionSpec.type === "facet"
+      ? materializeFacetGraphics(this)
+      : materializeCompositionGraphics(this);
+  }
+);
+
+function concatAction(direction, op) {
+  return action(
+    {
+      op,
+      description: direction === "horizontal"
+        ? "Compose complete programs horizontally."
+        : "Compose complete programs vertically."
+    },
+    function (args = {}) {
+      const state = normalizeCompositionInput(args, direction);
+      let next = this._withCompositionState(state);
+      for (const id of state.compositionSpec.children) {
+        next = next.useProgram({ id });
+      }
+      return next.materializeComposition();
+    }
+  );
+}
+
+export const hconcatAction = concatAction("horizontal", "hconcat");
+export const vconcatAction = concatAction("vertical", "vconcat");
+
+const editCompositionLayout = action(
+  {
+    op: "editCompositionLayout",
+    description: "Edit composition spacing and alignment.",
+    scope: "composition"
+  },
+  function (args = {}) {
+    validateOptionObject(args, LAYOUT_EDIT_OPTIONS, "editCompositionLayout");
+    if (!LAYOUT_EDIT_OPTIONS.some(option => Object.hasOwn(args, option))) {
+      throw new TypeError("editCompositionLayout requires at least one layout option.");
+    }
+    const current = this.compositionSpec;
+    if (current.type === "facet") {
+      const layout = resolveFacetLayout({
+        children: current.children.map((id, index) => ({
+          ...childDescriptor({ id, program: this.children[id] }),
+          value: current.facet.values[index]
+        })),
+        columns: current.columns,
+        gap: Object.hasOwn(args, "gap") ? args.gap : current.gap,
+        align: Object.hasOwn(args, "align") ? args.align : current.align,
+        padding: Object.hasOwn(args, "padding")
+          ? normalizeCompositionPadding(args.padding, current.padding)
+          : current.padding,
+        sharedLegend: current.facet.guides.legend === "shared"
+      });
+      return this._withCompositionState({
+        children: this.children,
+        compositionSpec: {
+          ...current,
+          gap: layout.gap,
+          align: layout.align,
+          padding: layout.padding
+        }
+      }).materializeComposition();
+    }
+    const padding = Object.hasOwn(args, "padding")
+      ? normalizeCompositionPadding(args.padding, current.padding)
+      : current.padding;
+    const layout = resolveCompositionLayout({
+      direction: current.direction,
+      children: current.children.map(id => childDescriptor({
+        id,
+        program: this.children[id]
+      })),
+      gap: Object.hasOwn(args, "gap") ? args.gap : current.gap,
+      align: Object.hasOwn(args, "align") ? args.align : current.align,
+      padding
+    });
+    return this._withCompositionState({
+      children: this.children,
+      compositionSpec: {
+        ...current,
+        gap: layout.gap,
+        align: layout.align,
+        padding: layout.padding
+      }
+    }).materializeComposition();
+  }
+);
+
+const replaceCompositionChild = action(
+  {
+    op: "replaceCompositionChild",
+    description: "Replace one composition child without changing its slot.",
+    scope: "composition"
+  },
+  function (args = {}) {
+    validateOptionObject(args, REPLACEMENT_OPTIONS, "replaceCompositionChild");
+    if (this.compositionSpec.type === "facet") {
+      throw new Error("replaceCompositionChild is not available on a facet composition.");
+    }
+    const target = validateUserId(args.target, "Composition child target");
+    if (!Object.hasOwn(this.children, target)) {
+      throw new Error(`Unknown composition child "${target}".`);
+    }
+    if (!(args.program instanceof CoreChartProgram)) {
+      throw new TypeError("replaceCompositionChild program must be a ChartProgram.");
+    }
+    childDescriptor({ id: target, program: args.program });
+    const children = freezeOwned({
+      ...this.children,
+      [target]: args.program
+    });
+    return this._withCompositionState({
+      children,
+      compositionSpec: this.compositionSpec
+    })
+      .useProgram({ id: target })
+      .materializeComposition();
+  }
+);
+
+export function registerCompositionActions(ProgramClass) {
+  ProgramClass.prototype.useProgram = useProgram;
+  ProgramClass.prototype.materializeComposition = materializeComposition;
+  ProgramClass.prototype.editCompositionLayout = editCompositionLayout;
+  ProgramClass.prototype.replaceCompositionChild = replaceCompositionChild;
+}

package/src/actions/composition/index.js

@@ -0,0 +1 @@
+export { registerCompositionActions } from "./actions.js";

package/src/actions/coordinates/actions.js

@@ -3,15 +3,12 @@ import { validateCoordinateType } from "../../grammar/coordinates.js";
 import { validateUserId } from "../../core/identifiers.js";
 import { findCoordinate } from "../../selectors/coordinates.js";
 import { findLayer, hasLayer } from "../../selectors/layers.js";
+import { validateOptionObject } from "../../core/validation.js";
 
 const COORDINATE_OPTIONS = Object.freeze(["id", "type", "layers"]);
 
 function validateOptions(args) {
-  for (const key of Object.keys(args)) {
-    if (!COORDINATE_OPTIONS.includes(key)) {
-      throw new Error(`Unknown createCoordinate option "${key}".`);
-    }
-  }
+  validateOptionObject(args, COORDINATE_OPTIONS, "createCoordinate");
 }
 
 function validateLayers(program, layers) {

package/src/actions/data/density.js

@@ -22,7 +22,13 @@ export const materializeDensityData = action(
     return this
       .editSemantic({
         property: `dataset[${id}].transform`,
-        value: [{ ...transform, bandwidth: result.bandwidth }]
+        value: [{
+          ...transform,
+          resolved: {
+            bandwidth: result.bandwidth,
+            extent: result.extent
+          }
+        }]
       })
       .editSemantic({
         property: `dataset[${id}].values`,

package/src/actions/data/filter.js

@@ -10,6 +10,8 @@ import {
   normalizeMarkFilterTransform
 } from "../../grammar/markFilter.js";
 import { resolveMarkFilterSelection } from "../../materialization/selection/filter.js";
+import { findSelectionPolicy } from
+  "../../materialization/selection/policies/index.js";
 import {
   applyLayerDataRematerialization
 } from "../../materialization/dependencies.js";
@@ -121,7 +123,7 @@ export const filterMarks = action(
       label: "filter mark",
       predicate: candidate =>
         candidate.data !== undefined &&
-        ["point", "bar", "line", "area", "rule"].includes(candidate.mark?.type)
+        findSelectionPolicy(candidate.mark?.type) !== undefined
     });
     const derivedId = `${layer.id}FilteredData`;
     if (hasDataset(this, derivedId)) {

package/src/actions/data/regression.js

@@ -4,7 +4,7 @@ import { validateKeys } from "../../core/validation.js";
 import {
   deriveRegression,
   normalizeRegressionParameters
-} from "../../grammar/regression.js";
+} from "../../grammar/regression/index.js";
 import { MATERIALIZE_OPTIONS, requireDerivedDataset } from "./shared.js";
 
 const OPTIONS = Object.freeze([

package/src/actions/encodings/appearance.js

@@ -4,7 +4,7 @@ import {
   readQuantitativeField,
   readScaleField,
   validateOpacityValue
-} from "../../grammar/scales.js";
+} from "../../grammar/scales/index.js";
 import {
   resolveAppearanceScaleDefinition,
   resolveOpacityScaleDefinition
@@ -119,6 +119,16 @@ const encodeRadius = action(
   }
 );
 
+const encodePointRadius = action(
+  {
+    op: "encodePointRadius",
+    description: "Set a constant graphical radius on a point mark."
+  },
+  function (args = {}) {
+    return this.encodeRadius(args);
+  }
+);
+
 const encodeSize = action(
   {
     op: "encodeSize",
@@ -236,6 +246,7 @@ const encodeOpacity = action(
 
 export function registerAppearanceEncodingAction(ProgramClass) {
   ProgramClass.prototype.encodeRadius = encodeRadius;
+  ProgramClass.prototype.encodePointRadius = encodePointRadius;
   ProgramClass.prototype.encodeSize = encodeSize;
   ProgramClass.prototype.encodeShape = encodeShape;
   ProgramClass.prototype.encodeOpacity = encodeOpacity;

package/src/actions/encodings/barWidth.js

@@ -3,6 +3,7 @@ import { resolveTarget, validateOptions } from "./shared.js";
 import {
   BAR_GRAINS,
   resolveBarColorLayout,
+  resolveBarOffsetChannel,
   resolveBarGrain
 } from "../../grammar/bars/policy.js";
 import { normalizeBarWidth } from "../../grammar/bars/geometry.js";
@@ -12,7 +13,7 @@ const OPTIONS = Object.freeze(["band", "pixels", "target"]);
 const encodeBarWidth = action(
   {
     op: "encodeBarWidth",
-    description: "Set aggregate bar width within each x band or xOffset slot."
+    description: "Override aggregate or ranged bar width within its category slot."
   },
   function (args = {}) {
     validateOptions(args, OPTIONS, "encodeBarWidth");
@@ -28,6 +29,7 @@ const encodeBarWidth = action(
       this.markConfigs[target]?.barWidth
     );
     const grouped = layout === "group";
+    const offsetChannel = resolveBarOffsetChannel(layer);
     const grain = resolveBarGrain(layer);
     if (grain === BAR_GRAINS.ranged) {
       return this._withMarkConfig(target, { ...this.markConfigs[target], barWidth: width })
@@ -37,11 +39,11 @@ const encodeBarWidth = action(
       grain !== BAR_GRAINS.aggregate ||
       (grouped &&
         layer.encoding?.color?.field !== undefined &&
-        layer.encoding?.xOffset?.field !== layer.encoding.color.field)
+        layer.encoding?.[offsetChannel]?.field !== layer.encoding.color.field)
     ) {
       throw new Error(
         grouped
-          ? "encodeBarWidth requires complete grouped bar x, y, color, and xOffset encodings."
+          ? `encodeBarWidth requires complete grouped bar x, y, color, and ${offsetChannel} encodings.`
           : "encodeBarWidth requires complete aggregate bar x and y encodings."
       );
     }