ggaction 0.0.1

package/src/actions/boxPlots/materialize.js

@@ -0,0 +1,183 @@
+import { action } from "../../core/action.js";
+import { validateUserId } from "../../core/identifiers.js";
+import {
+  BOX_FIELDS,
+  deriveBoxData,
+  normalizeBoxTransform
+} from "../../grammar/boxPlot.js";
+import { findDataset } from "../../selectors/datasets.js";
+import { findLayer } from "../../selectors/layers.js";
+import { resolveBoxOrientation } from "./resolve.js";
+import { resolvePlotGraphicPlacement } from
+  "../../materialization/graphicHierarchy.js";
+
+export const materializeBoxPlot = action(
+  {
+    op: "materializeBoxPlot",
+    description: "Materialize a complete box-plot composite."
+  },
+  function ({ id } = {}) {
+    const ownerId = validateUserId(id, "Box-plot id");
+    const config = this.markConfigs[ownerId]?.boxPlot;
+    const layer = findLayer(this, ownerId);
+    if (config === undefined || layer?.mark?.type !== "bar") {
+      throw new Error(`Unknown box plot "${ownerId}".`);
+    }
+    if (config.materialized) return this;
+    const x = layer.encoding?.x;
+    const y = layer.encoding?.y;
+    if (x?.field === undefined || y?.field === undefined) return this;
+    const orientation = resolveBoxOrientation(x, y);
+    if (orientation === undefined) {
+      throw new Error(
+        "createBoxPlot requires one categorical axis and one quantitative axis."
+      );
+    }
+    const category = orientation === "vertical" ? x : y;
+    const measure = orientation === "vertical" ? y : x;
+    const measureChannel = orientation === "vertical" ? "y" : "x";
+    const source = layer.data;
+    const summaryId = `${ownerId}SummaryData`;
+    const outlierDataId = `${ownerId}OutlierData`;
+    const whiskerId = `${ownerId}Whisker`;
+    const medianId = `${ownerId}Median`;
+    const outlierId = `${ownerId}Outliers`;
+    let next = this._withMarkConfig(ownerId, {
+      ...this.markConfigs[ownerId],
+      boxPlot: {
+        ...config,
+        materialized: true,
+        source,
+        orientation,
+        category: category.field,
+        measure: measure.field
+      },
+      barWidth: { band: config.width },
+      fill: config.box.fill,
+      opacity: config.box.opacity,
+      stroke: config.box.stroke,
+      strokeWidth: config.box.strokeWidth
+    }).createBoxSummaryData({
+      id: summaryId,
+      source,
+      category: category.field,
+      field: measure.field,
+      whisker: config.whisker.type,
+      ...(config.whisker.factor === undefined
+        ? {}
+        : { factor: config.whisker.factor })
+    });
+    const sourceRows = findDataset(next, source).values;
+    const hasOutliers = config.outliers &&
+      config.whisker.type === "tukey" &&
+      deriveBoxData(sourceRows, normalizeBoxTransform({
+        type: "boxOutlier",
+        category: category.field,
+        field: measure.field,
+        whisker: config.whisker.type,
+        factor: config.whisker.factor
+      })).outliers.length > 0;
+    if (hasOutliers) {
+      next = next.createBoxOutlierData({
+        id: outlierDataId,
+        source,
+        category: category.field,
+        field: measure.field,
+        whisker: config.whisker.type,
+        factor: config.whisker.factor
+      });
+    }
+    next = next.editSemantic({
+      property: `layer[${ownerId}].data`,
+      value: summaryId
+    });
+    const rangeAction = orientation === "vertical" ? "encodeYRange" : "encodeXRange";
+    next = next[rangeAction]({
+      target: ownerId,
+      lower: BOX_FIELDS.q1,
+      upper: BOX_FIELDS.q3,
+      scale: { id: measure.scale }
+    }).editSemantic({
+      property: `layer[${ownerId}].encoding.${measureChannel}.title`,
+      value: measure.field
+    });
+    next = next.createErrorBar({
+      id: whiskerId,
+      data: summaryId,
+      ...(orientation === "vertical"
+        ? {
+            x: {
+              field: category.field,
+              fieldType: category.fieldType,
+              scale: { id: category.scale }
+            },
+            y: {
+              center: BOX_FIELDS.median,
+              lower: BOX_FIELDS.lowerWhisker,
+              upper: BOX_FIELDS.upperWhisker,
+              scale: { id: measure.scale }
+            }
+          }
+        : {
+            x: {
+              center: BOX_FIELDS.median,
+              lower: BOX_FIELDS.lowerWhisker,
+              upper: BOX_FIELDS.upperWhisker,
+              scale: { id: measure.scale }
+            },
+            y: {
+              field: category.field,
+              fieldType: category.fieldType,
+              scale: { id: category.scale }
+            }
+          }),
+      coordinate: layer.coordinate,
+      stroke: "#111111",
+      strokeWidth: 1.5
+    });
+    next = next
+      .editSemantic({
+        property: `layer[${whiskerId}].encoding.${measureChannel}.title`,
+        value: measure.field
+      })
+      .editGraphics({ target: ownerId, remove: true })
+      .createGraphics({
+        id: ownerId,
+        type: "rect",
+        length: 0,
+        ...resolvePlotGraphicPlacement(next)
+      })
+      .rematerializeBarMark({ id: ownerId })
+      .createBoxMedian({
+        id: medianId,
+        owner: ownerId,
+        data: summaryId,
+        category: category.field,
+        categoryType: category.fieldType,
+        measure: BOX_FIELDS.median,
+        orientation,
+        coordinate: layer.coordinate,
+        categoryScale: category.scale,
+        measureScale: measure.scale,
+        stroke: config.median.stroke,
+        strokeWidth: config.median.strokeWidth
+      });
+    if (hasOutliers) {
+      next = next.createBoxOutliers({
+        id: outlierId,
+        data: outlierDataId,
+        category: category.field,
+        categoryType: category.fieldType,
+        measure: measure.field,
+        orientation,
+        coordinate: layer.coordinate,
+        categoryScale: category.scale,
+        measureScale: measure.scale,
+        shape: config.outlier.shape,
+        radius: config.outlier.radius,
+        opacity: config.outlier.opacity
+      });
+    }
+    return next._withContext({ currentMark: ownerId, currentData: source });
+  }
+);

package/src/actions/boxPlots/options.js

@@ -0,0 +1,147 @@
+import { isPlainObject } from "../../core/immutable.js";
+import {
+  validateKeys,
+  validateNonEmptyString,
+  validateNonNegativeFinite,
+  validatePositiveFinite,
+  validateUnitInterval
+} from "../../core/validation.js";
+import { validatePointShape } from "../../grammar/pointShapes.js";
+import { DEFAULT_COLORS } from "../../theme/defaults.js";
+
+export const BOX_PLOT_OPTIONS = Object.freeze([
+  "id", "target", "data", "x", "y", "coordinate", "whisker",
+  "width", "outliers", "box", "median", "outlier"
+]);
+
+const DEFAULT_BOX = Object.freeze({
+  fill: DEFAULT_COLORS.mark,
+  opacity: 1,
+  stroke: DEFAULT_COLORS.mark,
+  strokeWidth: 1.5
+});
+const DEFAULT_MEDIAN = Object.freeze({ stroke: "#1f2937", strokeWidth: 1.5 });
+const DEFAULT_OUTLIER = Object.freeze({
+  shape: "diamond",
+  radius: 3,
+  opacity: 0.75
+});
+
+function plainOptions(value, keys, label) {
+  if (value === undefined) return {};
+  if (!isPlainObject(value)) {
+    throw new TypeError(`createBoxPlot ${label} must be a plain object.`);
+  }
+  validateKeys(value, keys, `createBoxPlot ${label}`);
+  return value;
+}
+
+export function resolveBoxPosition(value, label) {
+  if (value === undefined) return undefined;
+  if (!isPlainObject(value)) {
+    throw new TypeError(`createBoxPlot ${label} must be a plain object.`);
+  }
+  validateKeys(value, ["field", "fieldType", "scale"], `createBoxPlot ${label}`);
+  return value;
+}
+
+export function boxEncodingArgs(value) {
+  return {
+    ...value,
+    ...(typeof value.scale === "string" ? { scale: { id: value.scale } } : {})
+  };
+}
+
+export function resolveBoxWhisker(value) {
+  if (value === undefined) return Object.freeze({ type: "tukey", factor: 1.5 });
+  if (!isPlainObject(value)) {
+    throw new TypeError("createBoxPlot whisker must be a plain object.");
+  }
+  validateKeys(value, ["type", "factor"], "createBoxPlot whisker");
+  const type = value.type ?? "tukey";
+  if (!["tukey", "minmax"].includes(type)) {
+    throw new Error(`Unsupported createBoxPlot whisker type "${type}".`);
+  }
+  if (type === "minmax") {
+    if (value.factor !== undefined) {
+      throw new Error("createBoxPlot minmax whiskers do not accept factor.");
+    }
+    return Object.freeze({ type });
+  }
+  const factor = value.factor ?? 1.5;
+  if (!Number.isFinite(factor) || factor <= 0) {
+    throw new RangeError(
+      "createBoxPlot whisker factor must be positive and finite."
+    );
+  }
+  return Object.freeze({ type, factor });
+}
+
+export function resolveBoxWidth(value) {
+  const options = plainOptions(value, ["band"], "width");
+  const band = options.band ?? 0.7;
+  if (!Number.isFinite(band) || band <= 0 || band >= 1) {
+    throw new RangeError(
+      "createBoxPlot width.band must be greater than 0 and less than 1."
+    );
+  }
+  return band;
+}
+
+export function resolveBoxAppearance(value) {
+  const options = plainOptions(
+    value,
+    ["fill", "opacity", "stroke", "strokeWidth"],
+    "box"
+  );
+  return Object.freeze({
+    fill: options.fill === undefined
+      ? DEFAULT_BOX.fill
+      : validateNonEmptyString(options.fill, "createBoxPlot box.fill"),
+    opacity: options.opacity === undefined
+      ? DEFAULT_BOX.opacity
+      : validateUnitInterval(options.opacity, "createBoxPlot box.opacity"),
+    stroke: options.stroke === undefined
+      ? DEFAULT_BOX.stroke
+      : validateNonEmptyString(options.stroke, "createBoxPlot box.stroke"),
+    strokeWidth: options.strokeWidth === undefined
+      ? DEFAULT_BOX.strokeWidth
+      : validateNonNegativeFinite(
+          options.strokeWidth,
+          "createBoxPlot box.strokeWidth"
+        )
+  });
+}
+
+export function resolveBoxMedianAppearance(value) {
+  const options = plainOptions(value, ["stroke", "strokeWidth"], "median");
+  return Object.freeze({
+    stroke: options.stroke === undefined
+      ? DEFAULT_MEDIAN.stroke
+      : validateNonEmptyString(options.stroke, "createBoxPlot median.stroke"),
+    strokeWidth: options.strokeWidth === undefined
+      ? DEFAULT_MEDIAN.strokeWidth
+      : validateNonNegativeFinite(
+          options.strokeWidth,
+          "createBoxPlot median.strokeWidth"
+        )
+  });
+}
+
+export function resolveBoxOutlierAppearance(value) {
+  const options = plainOptions(value, ["shape", "radius", "opacity"], "outlier");
+  return Object.freeze({
+    shape: options.shape === undefined
+      ? DEFAULT_OUTLIER.shape
+      : validatePointShape(options.shape),
+    radius: options.radius === undefined
+      ? DEFAULT_OUTLIER.radius
+      : validatePositiveFinite(options.radius, "createBoxPlot outlier.radius"),
+    opacity: options.opacity === undefined
+      ? DEFAULT_OUTLIER.opacity
+      : validateUnitInterval(
+          options.opacity,
+          "createBoxPlot outlier.opacity"
+        )
+  });
+}

package/src/actions/boxPlots/resolve.js

@@ -0,0 +1,38 @@
+import { resolveOptionalUserId, validateUserId } from "../../core/identifiers.js";
+import { findLayer, hasLayer } from "../../selectors/layers.js";
+
+const CATEGORY_TYPES = Object.freeze(["nominal", "ordinal", "temporal"]);
+
+export function resolveBoxOrientation(x, y) {
+  const xType = x?.fieldType ?? "quantitative";
+  const yType = y?.fieldType ?? "quantitative";
+  if (CATEGORY_TYPES.includes(xType) && yType === "quantitative") return "vertical";
+  if (xType === "quantitative" && CATEGORY_TYPES.includes(yType)) return "horizontal";
+  return undefined;
+}
+
+export function resolveBoxSourceLayer(program, target) {
+  if (target !== undefined) {
+    const layer = findLayer(program, validateUserId(target, "Box source layer id"));
+    if (layer === undefined) throw new Error(`Unknown box source layer "${target}".`);
+    return layer;
+  }
+  const current = findLayer(program, program.context.currentMark);
+  if (current?.encoding?.x !== undefined || current?.encoding?.y !== undefined) {
+    return current;
+  }
+  const eligible = program.semanticSpec.layers.filter(
+    layer => layer.encoding?.x !== undefined && layer.encoding?.y !== undefined
+  );
+  return eligible.length === 1 ? eligible[0] : undefined;
+}
+
+export function resolveBoxPlotId(program, requested) {
+  return resolveOptionalUserId(requested, {
+    defaultId: "boxPlot",
+    label: "Box-plot id",
+    operation: "createBoxPlot",
+    ambiguous: hasLayer(program, "boxPlot") ||
+      program.graphicSpec.objects.boxPlot !== undefined
+  });
+}

package/src/actions/canvas/actions.js

@@ -0,0 +1,144 @@
+import { action } from "../../core/action.js";
+import {
+  DEFAULT_CANVAS,
+  DEFAULT_MARGIN,
+  normalizeMargin,
+  validateCanvasState
+} from "../../layout/canvas.js";
+import { cloneAndFreeze } from "../../core/immutable.js";
+import {
+  applyMaterializationPlan,
+  planCanvasRematerialization
+} from "../../materialization/dependencies.js";
+import {
+  assertCanvasHierarchyAvailable,
+  CANVAS_GRAPHIC_ID,
+  PLOT_GRAPHIC_ID
+} from "../../materialization/graphicHierarchy.js";
+
+const CANVAS_OPTIONS = Object.freeze([
+  "width",
+  "height",
+  "background",
+  "margin"
+]);
+
+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}".`);
+    }
+  }
+}
+
+function requireCanvas(program) {
+  const canvas = program.graphicSpec.objects.canvas;
+
+  if (canvas?.type !== "canvas") {
+    throw new Error("editCanvas requires an existing canvas.");
+  }
+
+  return canvas;
+}
+
+function resolveCanvasState(program, args) {
+  const canvas = requireCanvas(program);
+  const baseMargin =
+    program.materializationConfigs.canvas?.margin ?? DEFAULT_MARGIN;
+  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
+  };
+
+  validateCanvasState(state);
+  return cloneAndFreeze(state);
+}
+
+export const editCanvas = action(
+  {
+    op: "editCanvas",
+    description: "Edit canvas properties and authoring bounds."
+  },
+  function (args = {}) {
+    validateOptions(args, "editCanvas");
+    const state = resolveCanvasState(this, args);
+    let next = this;
+
+    for (const property of ["width", "height", "background"]) {
+      if (Object.hasOwn(args, property)) {
+        next = next.editGraphics({
+          target: "canvas",
+          property,
+          value: state[property]
+        });
+      }
+    }
+
+    next = next._withCanvasConfig({ margin: state.margin });
+
+    if (
+      Object.hasOwn(args, "width") ||
+      Object.hasOwn(args, "height") ||
+      Object.hasOwn(args, "margin")
+    ) {
+      next = applyMaterializationPlan(
+        next,
+        planCanvasRematerialization(next)
+      );
+    }
+
+    return next;
+  }
+);
+
+export const createCanvas = action(
+  {
+    op: "createCanvas",
+    description: "Create and configure the chart canvas."
+  },
+  function (args = {}) {
+    validateOptions(args, "createCanvas", { allowEmpty: true });
+
+    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
+    };
+
+    return this
+      .createGraphics({ id: CANVAS_GRAPHIC_ID, type: "canvas" })
+      .createGraphics({
+        id: PLOT_GRAPHIC_ID,
+        type: "collection",
+        parent: CANVAS_GRAPHIC_ID
+      })
+      .editCanvas(options);
+  }
+);

package/src/actions/canvas/index.js

@@ -0,0 +1,6 @@
+import { createCanvas, editCanvas } from "./actions.js";
+
+export function registerCanvasActions(ProgramClass) {
+  ProgramClass.prototype.editCanvas = editCanvas;
+  ProgramClass.prototype.createCanvas = createCanvas;
+}

package/src/actions/coordinates/actions.js

@@ -0,0 +1,85 @@
+import { action } from "../../core/action.js";
+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";
+
+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}".`);
+    }
+  }
+}
+
+function validateLayers(program, layers) {
+  if (!Array.isArray(layers)) {
+    throw new TypeError("createCoordinate layers must be an array.");
+  }
+
+  const ids = layers.map(layer => validateUserId(layer, "Layer id"));
+
+  if (new Set(ids).size !== ids.length) {
+    throw new Error("createCoordinate layers must not contain duplicates.");
+  }
+
+  for (const id of ids) {
+    if (!hasLayer(program, id)) {
+      throw new Error(`Unknown layer "${id}".`);
+    }
+  }
+
+  return ids;
+}
+
+export const createCoordinate = action(
+  {
+    op: "createCoordinate",
+    description: "Create a semantic coordinate and attach layers to it."
+  },
+  function (args = {}) {
+    validateOptions(args);
+    const id = validateUserId(args.id ?? "main", "Coordinate id");
+    const type = validateCoordinateType(args.type ?? "cartesian");
+    const layers = validateLayers(this, args.layers ?? []);
+    const existing = findCoordinate(this, id);
+
+    if (existing !== undefined && existing.type !== type) {
+      throw new Error(
+        `Coordinate "${id}" already exists with type "${existing.type}".`
+      );
+    }
+
+    for (const layerId of layers) {
+      const layer = findLayer(this, layerId);
+
+      if (layer.coordinate !== undefined && layer.coordinate !== id) {
+        throw new Error(
+          `Layer "${layerId}" already uses coordinate "${layer.coordinate}".`
+        );
+      }
+    }
+
+    let program = existing === undefined
+      ? this.editSemantic({
+          property: `coordinate[${id}].type`,
+          value: type
+        })
+      : this;
+
+    for (const layerId of layers) {
+      const layer = findLayer(program, layerId);
+
+      if (layer.coordinate === undefined) {
+        program = program.editSemantic({
+          property: `layer[${layerId}].coordinate`,
+          value: id
+        });
+      }
+    }
+
+    return program;
+  }
+);

package/src/actions/coordinates/index.js

@@ -0,0 +1,5 @@
+import { createCoordinate } from "./actions.js";
+
+export function registerCoordinateActions(ProgramClass) {
+  ProgramClass.prototype.createCoordinate = createCoordinate;
+}

package/src/actions/data/box.js

@@ -0,0 +1,40 @@
+import { action } from "../../core/action.js";
+import { validateUserId } from "../../core/identifiers.js";
+import { validateKeys } from "../../core/validation.js";
+import { BOX_FIELDS, deriveBoxData, normalizeBoxTransform } from "../../grammar/boxPlot.js";
+import { MATERIALIZE_OPTIONS, requireDerivedDataset } from "./shared.js";
+
+const OPTIONS = Object.freeze([
+  "id", "source", "category", "field", "whisker", "factor", "as"
+]);
+
+function materializer(type, op, select) {
+  return action({ op, description: `Materialize ${type} box-plot data.` }, function (args = {}) {
+    validateKeys(args, MATERIALIZE_OPTIONS, op);
+    const { id, source, transform } = requireDerivedDataset(this, args.id, type);
+    return this.editSemantic({ property: `dataset[${id}].values`, value: select(deriveBoxData(source.values, transform)) });
+  });
+}
+
+export const materializeBoxSummaryData = materializer("boxSummary", "materializeBoxSummaryData", value => value.summaries);
+export const materializeBoxOutlierData = materializer("boxOutlier", "materializeBoxOutlierData", value => value.outliers);
+
+function creator(type, op, materialize) {
+  return action({ op, description: `Create immutable ${type} box-plot data.` }, function (args = {}) {
+    validateKeys(args, OPTIONS, op);
+    const id = validateUserId(args.id, "Box dataset id");
+    const source = validateUserId(args.source ?? this.context.currentData, "Box source dataset id");
+    const transform = normalizeBoxTransform({
+      type,
+      category: args.category,
+      field: args.field,
+      ...(args.whisker === undefined ? {} : { whisker: args.whisker }),
+      ...(args.factor === undefined ? {} : { factor: args.factor }),
+      as: args.as ?? BOX_FIELDS
+    });
+    return this.createDerivedData({ id, source, transform: [transform] })[materialize]({ id });
+  });
+}
+
+export const createBoxSummaryData = creator("boxSummary", "createBoxSummaryData", "materializeBoxSummaryData");
+export const createBoxOutlierData = creator("boxOutlier", "createBoxOutlierData", "materializeBoxOutlierData");

package/src/actions/data/create.js

@@ -0,0 +1,33 @@
+import { action } from "../../core/action.js";
+import { resolveOptionalUserId } from "../../core/identifiers.js";
+import { isPlainObject } from "../../core/immutable.js";
+import { validateKeys } from "../../core/validation.js";
+import { hasDataset } from "../../selectors/index.js";
+
+const OPTIONS = Object.freeze(["id", "values"]);
+
+export const createData = action(
+  { op: "createData", description: "Create an immutable named dataset." },
+  function (args = {}) {
+    validateKeys(args, OPTIONS, "createData");
+    const id = resolveOptionalUserId(args.id, {
+      defaultId: "data",
+      label: "Dataset id",
+      operation: "createData",
+      ambiguous: this.semanticSpec.datasets.length > 0
+    });
+    if (!Array.isArray(args.values)) {
+      throw new TypeError("createData requires values to be an array.");
+    }
+    if (!args.values.every(isPlainObject)) {
+      throw new TypeError("createData requires every row to be a plain object.");
+    }
+    if (hasDataset(this, id)) {
+      throw new Error(`Dataset "${id}" already exists.`);
+    }
+    return this.editSemantic({
+      property: `dataset[${id}].values`,
+      value: args.values
+    });
+  }
+);