ggaction 0.0.3 → 0.0.5

package/src/actions/charts/bar.js

@@ -0,0 +1,50 @@
+import { action } from "../../core/action.js";
+import {
+  applyFacadeGuides,
+  normalizeAppearance,
+  normalizeEncoding,
+  normalizeFieldEncoding,
+  normalizeGuides,
+  normalizeTargetOptions,
+  positionArgs,
+  resolveFacadeData,
+  resolveFacadeId,
+  targetArgs,
+  validateFacadeOptions
+} from "./shared.js";
+
+const OPTIONS = Object.freeze([
+  "id", "data", "coordinate", "x", "y", "color", "width", "bar", "guides"
+]);
+const BAR_OPTIONS = Object.freeze([
+  "fill", "opacity", "stroke", "strokeWidth"
+]);
+
+export const createBarPlot = action(
+  {
+    op: "createBarPlot",
+    description: "Create a Cartesian bar plot from existing chart data."
+  },
+  function (args = {}) {
+    validateFacadeOptions(args, OPTIONS, "createBarPlot");
+    const id = resolveFacadeId(this, args.id, {
+      defaultId: "barPlot",
+      operation: "createBarPlot"
+    });
+    const data = resolveFacadeData(this, args.data, "createBarPlot");
+    const bar = normalizeAppearance(args.bar, BAR_OPTIONS, "createBarPlot bar");
+    const x = normalizeFieldEncoding(args.x, "createBarPlot x");
+    const y = normalizeFieldEncoding(args.y, "createBarPlot y");
+    const color = normalizeEncoding(args.color, "createBarPlot color");
+    const width = normalizeTargetOptions(args.width, "createBarPlot width");
+    const guides = normalizeGuides(args.guides, "createBarPlot");
+
+    let next = this
+      .createBarMark({ id, data, ...bar })
+      .encodeX(positionArgs(x, { target: id, coordinate: args.coordinate }))
+      .encodeY(positionArgs(y, { target: id, coordinate: args.coordinate }));
+    if (color !== undefined) next = next.encodeColor(targetArgs(color, id));
+    if (width !== undefined) next = next.encodeBarWidth(targetArgs(width, id));
+    return applyFacadeGuides(next, guides);
+  }
+);

package/src/actions/charts/heatmap.js

@@ -0,0 +1,205 @@
+import { action } from "../../core/action.js";
+import { isPlainObject } from "../../core/immutable.js";
+import {
+  validateNonEmptyString,
+  validateOptionObject
+} from "../../core/validation.js";
+import { requireDataset } from "../../selectors/datasets.js";
+import {
+  applyFacadeGuides,
+  normalizeAppearance,
+  normalizeFieldEncoding,
+  normalizeGuides,
+  positionArgs,
+  resolveFacadeData,
+  resolveFacadeId,
+  targetArgs,
+  validateFacadeOptions
+} from "./shared.js";
+
+const OPTIONS = Object.freeze([
+  "id", "data", "coordinate", "x", "y", "bin", "color", "rect", "guides"
+]);
+const RECT_OPTIONS = Object.freeze([
+  "opacity", "stroke", "strokeWidth"
+]);
+const BIN_OPTIONS = Object.freeze([
+  "bins", "extent", "includeEmpty"
+]);
+const BINNED_POSITION_OPTIONS = Object.freeze([
+  "field", "fieldType", "scale"
+]);
+const BINNED_COLOR_OPTIONS = Object.freeze([
+  "scale", "palette"
+]);
+
+function normalizeBin(value) {
+  if (!isPlainObject(value)) {
+    throw new TypeError("createHeatmap bin must be a plain object.");
+  }
+  validateOptionObject(value, BIN_OPTIONS, "createHeatmap bin");
+  return {
+    ...value,
+    includeEmpty: value.includeEmpty ?? true
+  };
+}
+
+function normalizeBinnedPosition(value, channel) {
+  const label = `createHeatmap ${channel}`;
+  const encoding = normalizeFieldEncoding(value, label);
+  validateOptionObject(encoding, BINNED_POSITION_OPTIONS, label);
+  const field = validateNonEmptyString(encoding.field, `${label} field`);
+  const fieldType = encoding.fieldType ?? "quantitative";
+  if (fieldType !== "quantitative") {
+    throw new Error(`${label} requires a quantitative field.`);
+  }
+  if (encoding.scale !== undefined && !isPlainObject(encoding.scale)) {
+    throw new TypeError(`${label} scale must be a plain object.`);
+  }
+  return { ...encoding, field, fieldType };
+}
+
+function normalizeBinnedColor(value) {
+  if (value === undefined) return {};
+  if (!isPlainObject(value)) {
+    throw new TypeError("createHeatmap binned color must be a plain object.");
+  }
+  validateOptionObject(value, BINNED_COLOR_OPTIONS, "createHeatmap binned color");
+  return { ...value };
+}
+
+function resolvedPosition(encoding, field, extent) {
+  const scale = encoding.scale ?? {};
+  return {
+    field,
+    fieldType: "quantitative",
+    scale: {
+      type: "linear",
+      nice: false,
+      zero: false,
+      ...scale,
+      domain: scale.domain === undefined || scale.domain === "auto"
+        ? extent
+        : scale.domain
+    }
+  };
+}
+
+function axisWithTitle(value, text) {
+  if (value === false) return false;
+  if (value !== undefined && !isPlainObject(value)) {
+    throw new TypeError("createHeatmap binned axis must be false or a plain object.");
+  }
+  if (value?.title !== undefined && !isPlainObject(value.title)) {
+    throw new TypeError("createHeatmap binned axis title must be a plain object.");
+  }
+  return {
+    ...value,
+    title: {
+      text,
+      ...value?.title
+    }
+  };
+}
+
+function binnedGuides(guides, xTitle, yTitle) {
+  if (guides === false) return false;
+  for (const key of ["axes", "legend"]) {
+    if (
+      guides[key] !== undefined &&
+      guides[key] !== false &&
+      !isPlainObject(guides[key])
+    ) {
+      throw new TypeError(
+        `createHeatmap guides ${key} must be false or a plain object.`
+      );
+    }
+  }
+  const axes = guides.axes === false
+    ? false
+    : {
+        ...guides.axes,
+        x: axisWithTitle(guides.axes?.x, xTitle),
+        y: axisWithTitle(guides.axes?.y, yTitle)
+      };
+  const legend = guides.legend === false
+    ? false
+    : { title: "Count", ...guides.legend };
+  return {
+    ...guides,
+    axes,
+    grid: guides.grid ?? false,
+    legend
+  };
+}
+
+function createPreGriddedHeatmap(program, args, { id, data, rect, guides }) {
+  const x = normalizeFieldEncoding(args.x, "createHeatmap x");
+  const y = normalizeFieldEncoding(args.y, "createHeatmap y");
+  const color = normalizeFieldEncoding(args.color, "createHeatmap color");
+  const next = program
+    .createRectMark({ id, data, ...rect })
+    .encodeX(positionArgs(x, { target: id, coordinate: args.coordinate }))
+    .encodeY(positionArgs(y, { target: id, coordinate: args.coordinate }))
+    .encodeColor(targetArgs(color, id));
+  return applyFacadeGuides(next, guides);
+}
+
+function createBinnedHeatmap(program, args, { id, data, rect, guides }) {
+  const x = normalizeBinnedPosition(args.x, "x");
+  const y = normalizeBinnedPosition(args.y, "y");
+  const bin = normalizeBin(args.bin);
+  const color = normalizeBinnedColor(args.color);
+  const resolvedGuides = binnedGuides(guides, x.field, y.field);
+  const generatedData = `${id}Bin2DData`;
+  const binned = program.createBin2DData({
+    id: generatedData,
+    source: data,
+    x: x.field,
+    y: y.field,
+    ...bin
+  });
+  const dataset = requireDataset(binned, generatedData);
+  const transform = dataset.transform[0];
+  const resolved = transform.resolved;
+  const xEncoding = resolvedPosition(x, transform.as.x0, resolved.extent.x);
+  const yEncoding = resolvedPosition(y, transform.as.y0, resolved.extent.y);
+
+  const next = binned
+    .createRectMark({ id, data: generatedData, ...rect })
+    .encodeX(positionArgs(xEncoding, { target: id, coordinate: args.coordinate }))
+    .encodeX2({ target: id, field: transform.as.x1, fieldType: "quantitative" })
+    .encodeY(positionArgs(yEncoding, { target: id, coordinate: args.coordinate }))
+    .encodeY2({ target: id, field: transform.as.y1, fieldType: "quantitative" })
+    .encodeColor({
+      target: id,
+      field: transform.as.count,
+      fieldType: "quantitative",
+      ...color
+    });
+  return applyFacadeGuides(
+    next,
+    resolvedGuides
+  );
+}
+
+export const createHeatmap = action(
+  {
+    op: "createHeatmap",
+    description: "Create a pre-gridded or rectangularly binned heatmap."
+  },
+  function (args = {}) {
+    validateFacadeOptions(args, OPTIONS, "createHeatmap");
+    const id = resolveFacadeId(this, args.id, {
+      defaultId: "heatmap",
+      operation: "createHeatmap"
+    });
+    const data = resolveFacadeData(this, args.data, "createHeatmap");
+    const rect = normalizeAppearance(args.rect, RECT_OPTIONS, "createHeatmap rect");
+    const guides = normalizeGuides(args.guides, "createHeatmap");
+    const shared = { id, data, rect, guides };
+    return args.bin === undefined
+      ? createPreGriddedHeatmap(this, args, shared)
+      : createBinnedHeatmap(this, args, shared);
+  }
+);

package/src/actions/charts/histogram.js

@@ -0,0 +1,58 @@
+import { action } from "../../core/action.js";
+import { validateNonEmptyString } from "../../core/validation.js";
+import {
+  applyFacadeGuides,
+  normalizeAppearance,
+  normalizeEncoding,
+  normalizeGuides,
+  resolveFacadeData,
+  resolveFacadeId,
+  targetArgs,
+  validateFacadeOptions
+} from "./shared.js";
+
+const OPTIONS = Object.freeze([
+  "id", "data", "coordinate", "field", "maxBins", "binStep",
+  "binBoundaries", "stack", "xScale", "yScale", "color", "bar", "guides"
+]);
+const BAR_OPTIONS = Object.freeze([
+  "fill", "opacity", "stroke", "strokeWidth"
+]);
+const HISTOGRAM_OPTIONS = Object.freeze([
+  "maxBins", "binStep", "binBoundaries", "stack", "xScale", "yScale"
+]);
+
+export const createHistogram = action(
+  {
+    op: "createHistogram",
+    description: "Create a binned count histogram from existing chart data."
+  },
+  function (args = {}) {
+    validateFacadeOptions(args, OPTIONS, "createHistogram");
+    const id = resolveFacadeId(this, args.id, {
+      defaultId: "histogram",
+      operation: "createHistogram"
+    });
+    const data = resolveFacadeData(this, args.data, "createHistogram");
+    const field = validateNonEmptyString(args.field, "createHistogram field");
+    const bar = normalizeAppearance(args.bar, BAR_OPTIONS, "createHistogram bar");
+    const color = normalizeEncoding(args.color, "createHistogram color");
+    const guides = normalizeGuides(args.guides, "createHistogram");
+    const histogram = Object.fromEntries(
+      HISTOGRAM_OPTIONS
+        .filter(key => Object.hasOwn(args, key))
+        .map(key => [key, args[key]])
+    );
+
+    let next = this
+      .createBarMark({ id, data, ...bar })
+      .encodeHistogram({
+        field,
+        target: id,
+        ...(args.coordinate === undefined ? {} : { coordinate: args.coordinate }),
+        ...histogram
+      });
+    if (color !== undefined) next = next.encodeColor(targetArgs(color, id));
+    return applyFacadeGuides(next, guides);
+  }
+);

package/src/actions/charts/index.js

@@ -0,0 +1,15 @@
+import { createBarPlot } from "./bar.js";
+import { createHeatmap } from "./heatmap.js";
+import { createHistogram } from "./histogram.js";
+import { createLinePlot } from "./line.js";
+import { createScatterPlot } from "./scatter.js";
+import { createParallelCoordinates } from "./parallel.js";
+
+export function registerChartActions(ProgramClass) {
+  ProgramClass.prototype.createBarPlot = createBarPlot;
+  ProgramClass.prototype.createHeatmap = createHeatmap;
+  ProgramClass.prototype.createHistogram = createHistogram;
+  ProgramClass.prototype.createScatterPlot = createScatterPlot;
+  ProgramClass.prototype.createLinePlot = createLinePlot;
+  ProgramClass.prototype.createParallelCoordinates = createParallelCoordinates;
+}

package/src/actions/charts/line.js

@@ -0,0 +1,69 @@
+import { action } from "../../core/action.js";
+import { validateNonEmptyString } from "../../core/validation.js";
+import {
+  applyFacadeGuides,
+  normalizeAppearance,
+  normalizeEncoding,
+  normalizeFieldEncoding,
+  normalizeGuides,
+  normalizeStrokeDashEncoding,
+  positionArgs,
+  resolveFacadeData,
+  resolveFacadeId,
+  targetArgs,
+  validateFacadeOptions
+} from "./shared.js";
+
+const OPTIONS = Object.freeze([
+  "id", "data", "coordinate", "x", "y", "color", "groupBy",
+  "strokeDash", "line", "guides"
+]);
+const LINE_OPTIONS = Object.freeze([
+  "strokeWidth", "curve", "stroke", "opacity", "closed"
+]);
+
+export const createLinePlot = action(
+  {
+    op: "createLinePlot",
+    description: "Create a Cartesian line plot from existing chart data."
+  },
+  function (args = {}) {
+    validateFacadeOptions(args, OPTIONS, "createLinePlot");
+    const id = resolveFacadeId(this, args.id, {
+      defaultId: "linePlot",
+      operation: "createLinePlot"
+    });
+    const data = resolveFacadeData(this, args.data, "createLinePlot");
+    const line = normalizeAppearance(
+      args.line,
+      LINE_OPTIONS,
+      "createLinePlot line"
+    );
+    if (line.closed === true) {
+      throw new Error(
+        "createLinePlot is Cartesian; closed lines require Polar line authoring."
+      );
+    }
+    const x = normalizeFieldEncoding(args.x, "createLinePlot x");
+    const y = normalizeFieldEncoding(args.y, "createLinePlot y");
+    const color = normalizeEncoding(args.color, "createLinePlot color");
+    const strokeDash = normalizeStrokeDashEncoding(args.strokeDash);
+    const groupBy = args.groupBy === undefined
+      ? undefined
+      : validateNonEmptyString(args.groupBy, "createLinePlot groupBy");
+    const guides = normalizeGuides(args.guides, "createLinePlot");
+
+    let next = this
+      .createLineMark({ id, data, ...line })
+      .encodeX(positionArgs(x, { target: id, coordinate: args.coordinate }))
+      .encodeY(positionArgs(y, { target: id, coordinate: args.coordinate }));
+    if (color !== undefined) next = next.encodeColor(targetArgs(color, id));
+    if (groupBy !== undefined) {
+      next = next.encodeGroup({ field: groupBy, target: id });
+    }
+    if (strokeDash !== undefined) {
+      next = next.encodeStrokeDash(targetArgs(strokeDash, id));
+    }
+    return applyFacadeGuides(next, guides);
+  }
+);

package/src/actions/charts/parallel.js

@@ -0,0 +1,76 @@
+import { action } from "../../core/action.js";
+import { resolveParallelCoordinate } from "../coordinates/parallel.js";
+import {
+  applyFacadeGuides,
+  normalizeAppearance,
+  normalizeEncoding,
+  normalizeGuides,
+  normalizeStrokeDashEncoding,
+  resolveFacadeData,
+  resolveFacadeId,
+  targetArgs,
+  validateFacadeOptions
+} from "./shared.js";
+
+const OPTIONS = Object.freeze([
+  "id", "data", "coordinate", "dimensions", "key", "missing",
+  "color", "strokeDash", "line", "guides"
+]);
+const LINE_OPTIONS = Object.freeze([
+  "strokeWidth", "stroke", "opacity", "curve", "closed"
+]);
+
+export const createParallelCoordinates = action(
+  {
+    op: "createParallelCoordinates",
+    description: "Create a complete Parallel-coordinates chart."
+  },
+  function (args = {}) {
+    validateFacadeOptions(args, OPTIONS, "createParallelCoordinates");
+    const id = resolveFacadeId(this, args.id, {
+      defaultId: "parallelCoordinates",
+      operation: "createParallelCoordinates"
+    });
+    const data = resolveFacadeData(this, args.data, "createParallelCoordinates");
+    const coordinate = resolveParallelCoordinate(this, {
+      requested: args.coordinate,
+      operation: "createParallelCoordinates",
+      useCurrent: true
+    }).id;
+    const line = normalizeAppearance(
+      args.line,
+      LINE_OPTIONS,
+      "createParallelCoordinates line"
+    );
+    if (line.closed === true || (line.curve !== undefined && line.curve !== "linear")) {
+      throw new Error(
+        "createParallelCoordinates requires a linear open line."
+      );
+    }
+    const color = normalizeEncoding(
+      args.color,
+      "createParallelCoordinates color"
+    );
+    const strokeDash = normalizeStrokeDashEncoding(
+      args.strokeDash,
+      "createParallelCoordinates strokeDash"
+    );
+    const guides = normalizeGuides(args.guides, "createParallelCoordinates");
+
+    let next = this
+      .createCoordinate({ id: coordinate, type: "parallel" })
+      .createLineMark({ id, data, ...line })
+      .encodeParallelCoordinates({
+        target: id,
+        coordinate,
+        dimensions: args.dimensions,
+        ...(args.key === undefined ? {} : { key: args.key }),
+        ...(args.missing === undefined ? {} : { missing: args.missing })
+      });
+    if (color !== undefined) next = next.encodeColor(targetArgs(color, id));
+    if (strokeDash !== undefined) {
+      next = next.encodeStrokeDash(targetArgs(strokeDash, id));
+    }
+    return applyFacadeGuides(next, guides);
+  }
+);

package/src/actions/charts/scatter.js

@@ -0,0 +1,56 @@
+import { action } from "../../core/action.js";
+import {
+  applyFacadeGuides,
+  normalizeAppearance,
+  normalizeEncoding,
+  normalizeFieldEncoding,
+  normalizeGuides,
+  positionArgs,
+  resolveFacadeData,
+  resolveFacadeId,
+  targetArgs,
+  validateFacadeOptions
+} from "./shared.js";
+
+const OPTIONS = Object.freeze([
+  "id", "data", "coordinate", "x", "y", "color", "size", "shape",
+  "point", "guides"
+]);
+const POINT_OPTIONS = Object.freeze([
+  "shape", "fill", "opacity", "stroke", "strokeWidth"
+]);
+
+export const createScatterPlot = action(
+  {
+    op: "createScatterPlot",
+    description: "Create a Cartesian scatter plot from existing chart data."
+  },
+  function (args = {}) {
+    validateFacadeOptions(args, OPTIONS, "createScatterPlot");
+    const id = resolveFacadeId(this, args.id, {
+      defaultId: "scatterPlot",
+      operation: "createScatterPlot"
+    });
+    const data = resolveFacadeData(this, args.data, "createScatterPlot");
+    const point = normalizeAppearance(
+      args.point,
+      POINT_OPTIONS,
+      "createScatterPlot point"
+    );
+    const x = normalizeFieldEncoding(args.x, "createScatterPlot x");
+    const y = normalizeFieldEncoding(args.y, "createScatterPlot y");
+    const color = normalizeEncoding(args.color, "createScatterPlot color");
+    const size = normalizeEncoding(args.size, "createScatterPlot size");
+    const shape = normalizeEncoding(args.shape, "createScatterPlot shape");
+    const guides = normalizeGuides(args.guides, "createScatterPlot");
+
+    let next = this
+      .createPointMark({ id, data, ...point })
+      .encodeX(positionArgs(x, { target: id, coordinate: args.coordinate }))
+      .encodeY(positionArgs(y, { target: id, coordinate: args.coordinate }));
+    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);
+  }
+);

package/src/actions/charts/shared.js

@@ -0,0 +1,121 @@
+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 { hasLayer } from "../../selectors/layers.js";
+
+export function validateFacadeOptions(args, supported, operation) {
+  return validateOptionObject(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;
+  }
+
+  const current = program.context.currentData;
+  if (current !== undefined && findDataset(program, current) !== undefined) {
+    return current;
+  }
+  const datasets = program.semanticSpec.datasets;
+  if (datasets.length === 1) return datasets[0].id;
+  if (datasets.length > 1) {
+    throw new Error(
+      `${operation} requires data when multiple datasets are available.`
+    );
+  }
+  throw new Error(`${operation} requires data or one inferable dataset.`);
+}
+
+export function resolveFacadeId(program, requested, {
+  defaultId,
+  operation
+}) {
+  return resolveOptionalUserId(requested, {
+    defaultId,
+    label: `${operation} id`,
+    operation,
+    ambiguous: hasLayer(program, defaultId) ||
+      program.graphicSpec.objects[defaultId] !== undefined
+  });
+}
+
+export function normalizeFieldEncoding(value, label) {
+  if (typeof value === "string") return { field: value };
+  if (!isPlainObject(value)) {
+    throw new TypeError(`${label} must be a field string or a plain object.`);
+  }
+  if (Object.hasOwn(value, "target") || Object.hasOwn(value, "coordinate")) {
+    throw new Error(
+      `${label} target and coordinate are owned by the chart facade.`
+    );
+  }
+  return { ...value };
+}
+
+export function normalizeEncoding(value, label) {
+  if (value === undefined) return undefined;
+  return normalizeFieldEncoding(value, label);
+}
+
+export function normalizeStrokeDashEncoding(
+  value,
+  label = "createLinePlot strokeDash"
+) {
+  if (value === undefined) return undefined;
+  if (!isPlainObject(value)) {
+    throw new TypeError(
+      `${label} must be an encodeStrokeDash option object.`
+    );
+  }
+  if (Object.hasOwn(value, "target")) {
+    throw new Error(`${label} target is owned by the chart facade.`);
+  }
+  return { ...value };
+}
+
+export function normalizeAppearance(value, supported, label) {
+  if (value === undefined) return {};
+  validateOptionObject(value, supported, label);
+  return { ...value };
+}
+
+export function normalizeTargetOptions(value, label) {
+  if (value === undefined) return undefined;
+  if (!isPlainObject(value)) {
+    throw new TypeError(`${label} must be a plain object.`);
+  }
+  if (Object.hasOwn(value, "target")) {
+    throw new Error(`${label} target is owned by the chart facade.`);
+  }
+  return { ...value };
+}
+
+export function normalizeGuides(value, operation) {
+  if (value === false) return false;
+  if (value === undefined) return {};
+  if (!isPlainObject(value)) {
+    throw new TypeError(`${operation} guides must be false or a plain object.`);
+  }
+  return { ...value };
+}
+
+export function positionArgs(encoding, { target, coordinate }) {
+  return {
+    ...encoding,
+    target,
+    ...(coordinate === undefined ? {} : { coordinate })
+  };
+}
+
+export function targetArgs(encoding, target) {
+  return { ...encoding, target };
+}
+
+export function applyFacadeGuides(program, guides) {
+  return guides === false ? program : program.createGuides(guides);
+}