ggaction 0.0.12 → 0.0.15

package/src/actions/charts/area.js

@@ -0,0 +1,51 @@
+import { action } from "../../core/action.js";
+import { STROKE_STYLE_PROPERTIES } from "../../grammar/strokeStyle.js";
+import { normalizeGroupFields } from "../../grammar/pathSeries.js";
+import { normalizeAreaBound, validateAreaEndpointPair } from "../../grammar/areaEndpoints.js";
+import {
+  applyFacadeGuides, normalizeAppearance, normalizeCategoricalColor, normalizeCategoricalGuides,
+  normalizeFieldEncoding, omitUndefinedOptions, positionArgs, resolveFacadeData, resolveFacadeId,
+  validateFacadeOptions
+} from "./shared.js";
+
+const OPERATION = "createAreaPlot";
+const OPTIONS = ["id", "data", "coordinate", "x", "y", "valueChannel", "baseline", "groupBy", "layout", "missing", "color", "area", "guides"];
+
+export const createAreaPlot = action({ op: OPERATION, description: "Create a simple, ranged, or stacked Cartesian area plot." }, function (args = {}) {
+  validateFacadeOptions(args, OPTIONS, OPERATION);
+  for (const [key, value] of Object.entries(args)) if (value === null) throw new TypeError(`${OPERATION} ${key} cannot be null.`);
+  const id = resolveFacadeId(this, args.id, { defaultId: "areaPlot", operation: OPERATION });
+  const data = resolveFacadeData(this, args.data, OPERATION);
+  const valueChannel = args.valueChannel ?? "y";
+  if (!["x", "y"].includes(valueChannel)) throw new Error("createAreaPlot valueChannel must be x or y.");
+  const independentChannel = valueChannel === "y" ? "x" : "y";
+  const independent = omitUndefinedOptions(normalizeFieldEncoding(args[independentChannel], `${OPERATION} ${independentChannel}`));
+  validateFacadeOptions(independent, ["field", "fieldType", "temporalUnit", "scale"], `${OPERATION} independent position`);
+  if (independent.fieldType !== undefined && !["quantitative", "temporal"].includes(independent.fieldType)) {
+    throw new Error("createAreaPlot independent position must be quantitative or temporal.");
+  }
+  const measurement = omitUndefinedOptions(normalizeFieldEncoding(args[valueChannel], `${OPERATION} ${valueChannel}`));
+  const ranged = Object.hasOwn(measurement, "lower") || Object.hasOwn(measurement, "upper");
+  validateFacadeOptions(measurement, ranged ? ["lower", "upper", "scale"] : ["field", "scale"], `${OPERATION} measurement`);
+  if (ranged && args.baseline !== undefined) throw new Error("createAreaPlot baseline cannot be combined with a range.");
+  const lower = ranged ? measurement.lower : measurement.field;
+  const upper = ranged ? measurement.upper : { datum: args.baseline ?? 0 };
+  validateAreaEndpointPair(normalizeAreaBound(lower), normalizeAreaBound(upper));
+  const groupBy = args.groupBy === undefined ? undefined : normalizeGroupFields(args.groupBy);
+  const area = omitUndefinedOptions(normalizeAppearance(args.area, [
+    "fill", "opacity", "stroke", "strokeWidth", "curve",
+    ...STROKE_STYLE_PROPERTIES
+  ], `${OPERATION} area`));
+  const color = args.color === undefined ? undefined : normalizeCategoricalColor(args.color, `${OPERATION} color`);
+  if (color !== undefined && area.fill !== undefined) throw new Error("createAreaPlot area.fill cannot be combined with color.");
+  const guides = normalizeCategoricalGuides(args.guides, OPERATION, color);
+  let next = this.createAreaMark({ id, data, ...area, missing: args.missing ?? "error" });
+  if (groupBy !== undefined) next = next.encodeGroup({ target: id, fields: groupBy });
+  next = next[independentChannel === "x" ? "encodeX" : "encodeY"](positionArgs(independent, { target: id, coordinate: args.coordinate }))
+    [valueChannel === "y" ? "encodeYRange" : "encodeXRange"]({ target: id, lower, upper,
+      ...(measurement.scale === undefined ? {} : { scale: measurement.scale }),
+      ...(args.coordinate === undefined ? {} : { coordinate: args.coordinate }) })
+    .layoutSeries({ target: id, mode: args.layout ?? "overlay" });
+  if (color !== undefined) next = next.encodeColor({ target: id, ...color });
+  return applyFacadeGuides(next, guides, id, args.guides ?? {});
+});

package/src/actions/charts/bar.js

@@ -1,4 +1,6 @@
 import { action } from "../../core/action.js";
+import { isBarCategoryEncoding } from "../../grammar/bars/policy.js";
+import { RECT_STYLE_PROPERTIES } from "../../grammar/roundedRect.js";
 import {
   applyFacadeGuides,
   inferFacadeFieldType,
@@ -18,7 +20,7 @@ const OPTIONS = Object.freeze([
   "id", "data", "coordinate", "x", "y", "color", "width", "bar", "guides"
 ]);
 const BAR_OPTIONS = Object.freeze([
-  "fill", "opacity", "stroke", "strokeWidth"
+  "fill", "opacity", "stroke", "strokeWidth", ...RECT_STYLE_PROPERTIES
 ]);
 
 export const createBarPlot = action(
@@ -42,12 +44,17 @@ export const createBarPlot = action(
     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 }));
+    const positions = isBarCategoryEncoding(y)
+      ? [["encodeY", y], ["encodeX", x]]
+      : [["encodeX", x], ["encodeY", y]];
+    let next = this.createBarMark({ id, data, ...bar });
+    for (const [operation, encoding] of positions) {
+      next = next[operation](positionArgs(encoding, {
+        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);
+    return applyFacadeGuides(next, guides, id);
   }
 );

package/src/actions/charts/beeswarm.js

@@ -0,0 +1,70 @@
+import { action } from "../../core/action.js";
+import { isPlainObject } from "../../core/immutable.js";
+import { validateOptionObject } from "../../core/validation.js";
+import { findLayer } from "../../selectors/layers.js";
+import { resolveFacadeId, validateFacadeOptions } from "./shared.js";
+
+const OPTIONS = Object.freeze([
+  "id", "data", "coordinate", "x", "y", "color", "size", "shape",
+  "point", "packing", "guides"
+]);
+const PACKING_OPTIONS = Object.freeze(["maxOffset", "padding", "key", "overflow"]);
+
+function ownerScale(value, id, label) {
+  if (typeof value === "string") return { field: value, scale: { id } };
+  if (!isPlainObject(value)) return value;
+  if (value.scale !== undefined && !isPlainObject(value.scale)) {
+    throw new TypeError(`${label}.scale must be a plain object.`);
+  }
+  return {
+    ...value,
+    scale: { ...(value.scale ?? {}), id: value.scale?.id ?? id }
+  };
+}
+
+function normalizePacking(value, operation) {
+  if (value === false) return false;
+  const packing = value ?? {};
+  validateOptionObject(packing, PACKING_OPTIONS, `${operation} packing`);
+  return { ...packing };
+}
+
+export const createBeeswarmPlot = action(
+  {
+    op: "createBeeswarmPlot",
+    description: "Create a Point plot packed within categorical slots."
+  },
+  function (args = {}) {
+    const operation = "createBeeswarmPlot";
+    validateFacadeOptions(args, OPTIONS, operation);
+    if (args.x === undefined || args.y === undefined) {
+      throw new Error(`${operation} requires x and y.`);
+    }
+    const id = resolveFacadeId(this, args.id, {
+      defaultId: "beeswarmPlot",
+      operation
+    });
+    const packing = normalizePacking(args.packing, operation);
+    let next = this.createStripPlot({
+      id,
+      ...(args.data === undefined ? {} : { data: args.data }),
+      ...(args.coordinate === undefined ? {} : { coordinate: args.coordinate }),
+      x: ownerScale(args.x, `${id}X`, `${operation} x`),
+      y: ownerScale(args.y, `${id}Y`, `${operation} y`),
+      ...(args.color === undefined ? {} : { color: args.color }),
+      ...(args.size === undefined ? {} : { size: args.size }),
+      ...(args.shape === undefined ? {} : { shape: args.shape }),
+      ...(args.point === undefined ? {} : { point: args.point }),
+      ...(args.guides === undefined ? {} : { guides: args.guides })
+    });
+    if (packing === false) return next;
+    const layer = findLayer(next, id);
+    const categoryChannel = ["x", "y"].find(channel =>
+      ["nominal", "ordinal"].includes(layer?.encoding?.[channel]?.fieldType)
+    );
+    if (categoryChannel === undefined) {
+      throw new Error(`${operation} requires exactly one categorical position.`);
+    }
+    return next.packPoints({ target: id, channel: categoryChannel, ...packing });
+  }
+);

package/src/actions/charts/density.js

@@ -0,0 +1,48 @@
+import { action } from "../../core/action.js";
+import { STROKE_STYLE_PROPERTIES } from "../../grammar/strokeStyle.js";
+import { validateNonEmptyString, validateOptionObject } from "../../core/validation.js";
+import {
+  applyFacadeGuides, normalizeAppearance, normalizeCategoricalColor, normalizeCategoricalGuides,
+  omitUndefinedOptions, resolveFacadeData, resolveFacadeId, validateFacadeOptions
+} from "./shared.js";
+
+const OPERATION = "createDensityPlot";
+const OPTIONS = ["id", "data", "coordinate", "field", "groupBy", "bandwidth", "extent", "steps",
+  "kernel", "normalization", "weight", "as", "densityChannel", "valueScale", "densityScale", "color", "area", "guides"];
+const AREA_OPTIONS = [
+  "fill", "opacity", "stroke", "strokeWidth", "curve",
+  ...STROKE_STYLE_PROPERTIES
+];
+
+export const createDensityPlot = action({
+  op: OPERATION, description: "Create a baseline kernel-density area plot with optional explicit groups."
+}, function (args = {}) {
+  validateFacadeOptions(args, OPTIONS, OPERATION);
+  const id = resolveFacadeId(this, args.id, { defaultId: "densityPlot", operation: OPERATION });
+  const data = resolveFacadeData(this, args.data, OPERATION);
+  validateNonEmptyString(args.field, `${OPERATION} field`);
+  const { id: requestedId, data: requestedData, color: requestedColor, area: requestedArea,
+    guides: requestedGuides, ...density } = omitUndefinedOptions(args);
+  const area = omitUndefinedOptions(normalizeAppearance(requestedArea, AREA_OPTIONS, `${OPERATION} area`));
+  for (const [key, value] of Object.entries({ ...density, ...area })) {
+    if (value === null) throw new TypeError(`${OPERATION} ${key} cannot be null.`);
+  }
+  for (const key of ["valueScale", "densityScale"]) {
+    if (density[key] === undefined) continue;
+    validateOptionObject(density[key], undefined, `${OPERATION} ${key}`);
+    density[key] = omitUndefinedOptions(density[key]);
+  }
+  const color = requestedColor === undefined ? undefined
+    : normalizeCategoricalColor(requestedColor, `${OPERATION} color`, ["field", "fieldType", "scale", "palette", "layout"]);
+  if (color !== undefined && (color.field !== density.groupBy ||
+    color.layout !== undefined && color.layout !== "overlay")) {
+    throw new Error(`${OPERATION} color requires the same explicit groupBy field and overlay layout.`);
+  }
+  if (color !== undefined && area.fill !== undefined) {
+    throw new Error(`${OPERATION} area.fill cannot be combined with color.`);
+  }
+  const guides = normalizeCategoricalGuides(requestedGuides, OPERATION, color);
+  let next = this.createAreaMark({ id, data, ...area }).encodeDensity({ ...density, target: id });
+  if (color !== undefined) next = next.encodeColor({ ...color, target: id });
+  return applyFacadeGuides(next, guides, id, requestedGuides ?? {});
+});

package/src/actions/charts/ecdf.js

@@ -0,0 +1,186 @@
+import { action } from "../../core/action.js";
+import { validateUserId } from "../../core/identifiers.js";
+import { validateNonEmptyString, validateOptionObject } from "../../core/validation.js";
+import { normalizeGroupFields } from "../../grammar/pathSeries.js";
+import { STROKE_STYLE_PROPERTIES } from "../../grammar/strokeStyle.js";
+import {
+  applyFacadeGuides,
+  normalizeAppearance,
+  normalizeCategoricalColor,
+  normalizeGuides,
+  resolveFacadeData,
+  resolveFacadeId,
+  targetArgs,
+  validateFacadeOptions
+} from "./shared.js";
+
+const OPTIONS = Object.freeze([
+  "id", "data", "coordinate", "field", "groupBy", "weight", "missing",
+  "as", "color", "line", "labels", "guides"
+]);
+const EDIT_OPTIONS = Object.freeze([
+  "target", "data", "coordinate", "field", "groupBy", "weight", "missing", "as", "color"
+]);
+const LINE_OPTIONS = Object.freeze([
+  "strokeWidth", "stroke", "opacity", ...STROKE_STYLE_PROPERTIES
+]);
+const LABEL_OPTIONS = Object.freeze([
+  "field", "value", "content", "normalizeBy", "format", "layout", "fill",
+  "opacity", "fontSize", "fontFamily", "fontWeight", "align", "baseline",
+  "rotation", "dx", "dy"
+]);
+
+function normalizeGrouping(value) {
+  return value === undefined ? [] : normalizeGroupFields(value);
+}
+
+function normalizeLabels(value, operation) {
+  if (value === undefined || value === false) return false;
+  validateOptionObject(value, LABEL_OPTIONS, `${operation} labels`);
+  return { ...value };
+}
+
+function normalizeOutputs(value, id, operation) {
+  if (value === undefined) {
+    return {
+      value: `__${id}ECDFData_value`,
+      cumulative: `__${id}ECDFData_cumulative`,
+      probability: `__${id}ECDFData_probability`
+    };
+  }
+  validateOptionObject(value, ["value", "cumulative", "probability"], `${operation} as`);
+  for (const field of ["value", "cumulative", "probability"]) {
+    validateNonEmptyString(value[field], `${operation} as.${field}`);
+  }
+  return { ...value };
+}
+
+function resolveOwner(program, requested) {
+  const eligible = program.semanticSpec.layers.filter(
+    layer => program.markConfigs[layer.id]?.ecdfPlot !== undefined
+  );
+  if (requested !== undefined) {
+    const id = validateUserId(requested, "ECDF-plot owner id");
+    const owner = eligible.find(layer => layer.id === id);
+    if (owner === undefined) throw new Error(`Unknown ECDF-plot owner "${id}".`);
+    return owner;
+  }
+  const current = eligible.find(layer => layer.id === program.context.currentMark);
+  if (current !== undefined) return current;
+  if (eligible.length === 1) return eligible[0];
+  if (eligible.length === 0) throw new Error("editECDFPlot requires an ECDF plot.");
+  throw new Error("editECDFPlot target is ambiguous; provide target.");
+}
+
+export const createECDFPlot = action(
+  {
+    op: "createECDFPlot",
+    description: "Create a right-continuous empirical cumulative distribution plot."
+  },
+  function (args = {}) {
+    const operation = "createECDFPlot";
+    validateFacadeOptions(args, OPTIONS, operation);
+    const id = resolveFacadeId(this, args.id, { defaultId: "ecdfPlot", operation });
+    const source = resolveFacadeData(this, args.data, operation);
+    validateNonEmptyString(args.field, `${operation} field`);
+    if (args.weight !== undefined) validateNonEmptyString(args.weight, `${operation} weight`);
+    const groupBy = normalizeGrouping(args.groupBy);
+    const as = normalizeOutputs(args.as, id, operation);
+    const color = args.color === undefined
+      ? undefined
+      : normalizeCategoricalColor(args.color, `${operation} color`);
+    if (color !== undefined && !groupBy.includes(color.field)) {
+      throw new Error(`${operation} color field must be included in groupBy.`);
+    }
+    const line = normalizeAppearance(args.line, LINE_OPTIONS, `${operation} line`);
+    const labels = normalizeLabels(args.labels, operation);
+    const guides = normalizeGuides(args.guides, operation);
+    const dataId = `${id}ECDFData`;
+
+    let next = this
+      .createECDFData({
+        id: dataId,
+        source,
+        field: args.field,
+        ...(groupBy.length === 0 ? {} : { groupBy }),
+        ...(args.weight === undefined ? {} : { weight: args.weight }),
+        ...(args.missing === undefined ? {} : { missing: args.missing }),
+        as
+      })
+      .createLineMark({ id, data: dataId, curve: "step-after", ...line })
+      .encodeX({
+        target: id,
+        field: as.value,
+        fieldType: "quantitative",
+        scale: { id: `${id}Value`, zero: false, nice: false },
+        ...(args.coordinate === undefined ? {} : { coordinate: args.coordinate })
+      })
+      .encodeY({
+        target: id,
+        field: as.probability,
+        fieldType: "quantitative",
+        scale: { id: `${id}Probability`, domain: [0, 1], zero: true, nice: false },
+        ...(args.coordinate === undefined ? {} : { coordinate: args.coordinate })
+      });
+    if (groupBy.length > 0) next = next.encodeGroup({ target: id, fields: groupBy });
+    if (color !== undefined) next = next.encodeColor(targetArgs(color, id));
+    if (labels !== false) {
+      const hasContent = ["field", "value", "content"].some(key => Object.hasOwn(labels, key));
+      next = next.createMarkLabels({
+        id: `${id}Label`,
+        source: id,
+        ...labels,
+        ...(hasContent ? {} : { field: as.probability })
+      });
+    }
+    next = applyFacadeGuides(next, guides, id, guides);
+    return next._withMarkConfig(id, {
+      ...next.markConfigs[id],
+      ecdfPlot: {
+        source,
+        data: dataId,
+        options: {
+          id,
+          data: source,
+          coordinate: args.coordinate,
+          field: args.field,
+          ...(groupBy.length === 0 ? {} : { groupBy }),
+          ...(args.weight === undefined ? {} : { weight: args.weight }),
+          missing: args.missing ?? "drop",
+          as,
+          ...(color === undefined ? {} : { color }),
+          line,
+          labels,
+          guides
+        }
+      }
+    });
+  }
+);
+
+export const editECDFPlot = action(
+  {
+    op: "editECDFPlot",
+    description: "Atomically revise an ECDF plot's source or statistical roles."
+  },
+  function (args = {}) {
+    validateFacadeOptions(args, EDIT_OPTIONS, "editECDFPlot");
+    const changes = Object.keys(args).filter(key => key !== "target");
+    if (changes.length === 0) {
+      throw new Error("editECDFPlot requires at least one ECDF option.");
+    }
+    const owner = resolveOwner(this, args.target);
+    const current = this.markConfigs[owner.id].ecdfPlot;
+    const revised = { ...current.options };
+    for (const key of changes) {
+      if (key === "groupBy" && args[key] === false) {
+        delete revised.groupBy;
+        if (!Object.hasOwn(args, "color")) delete revised.color;
+      }
+      else if (key === "weight" && args[key] === false) delete revised.weight;
+      else if (key === "color" && args[key] === false) delete revised.color;
+      else revised[key] = args[key];
+    }
+    return this.removeMark({ target: owner.id }).createECDFPlot(revised);
+  }
+);