ggaction 0.0.12 → 0.0.15

package/src/actions/charts/interval-regression.js

@@ -0,0 +1,172 @@
+import { action } from "../../core/action.js";
+import { validateNonNegativeFinite } from "../../core/validation.js";
+import { findDataset } from "../../selectors/datasets.js";
+import { STROKE_STYLE_PROPERTIES } from "../../grammar/strokeStyle.js";
+import {
+  applyFacadeGuides,
+  normalizeAppearance,
+  normalizeEncoding,
+  normalizeFieldEncoding,
+  normalizeGuides,
+  resolveFacadeData,
+  resolveFacadeId,
+  targetArgs,
+  validateFacadeOptions
+} from "./shared.js";
+
+const INTERVAL_OPTIONS = Object.freeze([
+  "id", "data", "coordinate", "x", "y", "xOffset", "yOffset", "groupBy",
+  "color", "point", "errorBar", "guides"
+]);
+const POINT_OPTIONS = Object.freeze([
+  "shape", "fill", "opacity", "stroke", "strokeWidth", "radius",
+  ...STROKE_STYLE_PROPERTIES
+]);
+const ERROR_BAR_OPTIONS = Object.freeze([
+  "caps", "capSize", "stroke", "strokeWidth", "strokeDash", "opacity",
+  ...STROKE_STYLE_PROPERTIES
+]);
+
+function intervalChannel(value, operation, channel, id) {
+  const encoding = normalizeFieldEncoding(value, `${operation} ${channel}`);
+  return {
+    ...encoding,
+    scale: {
+      ...(encoding.scale ?? {}),
+      id: encoding.scale?.id ?? `${id}${channel.toUpperCase()}`
+    }
+  };
+}
+
+function centerField(program, config) {
+  if (config.intervalMode === "explicit") return config.centerField;
+  const dataset = findDataset(program, config.data);
+  const transform = dataset?.transform?.[0];
+  if (transform?.type !== "interval") {
+    throw new Error(`Interval plot requires interval provenance for dataset "${config.data}".`);
+  }
+  return transform.as.center;
+}
+
+function applyIntervalPointPositions(program, id, config) {
+  const vertical = config.orientation === "vertical";
+  const positionChannel = vertical ? "x" : "y";
+  const intervalChannelName = vertical ? "y" : "x";
+  let next = program[positionChannel === "x" ? "encodeX" : "encodeY"]({
+    target: id,
+    field: config.positionField,
+    fieldType: config.positionFieldType,
+    ...(config.positionTemporalUnit === undefined
+      ? {}
+      : { temporalUnit: config.positionTemporalUnit }),
+    coordinate: config.coordinate,
+    scale: { id: config.positionScale }
+  });
+  next = next[intervalChannelName === "x" ? "encodeX" : "encodeY"]({
+    target: id,
+    field: centerField(next, config),
+    fieldType: "quantitative",
+    coordinate: config.coordinate,
+    scale: { id: config.intervalScale }
+  });
+  if (config.offset !== undefined) {
+    next = next[config.offset.channel === "xOffset" ? "encodeXOffset" : "encodeYOffset"]({
+      target: id,
+      field: config.offset.field,
+      fieldType: config.offset.fieldType,
+      scale: { id: config.offset.scale },
+      paddingInner: config.offset.paddingInner,
+      paddingOuter: config.offset.paddingOuter
+    });
+  }
+  return next;
+}
+
+export const createIntervalPlot = action(
+  {
+    op: "createIntervalPlot",
+    description: "Create a center point and matching statistical or explicit interval."
+  },
+  function (args = {}) {
+    const operation = "createIntervalPlot";
+    validateFacadeOptions(args, INTERVAL_OPTIONS, operation);
+    const id = resolveFacadeId(this, args.id, { defaultId: "intervalPlot", operation });
+    const data = resolveFacadeData(this, args.data, operation);
+    const x = intervalChannel(args.x, operation, "x", id);
+    const y = intervalChannel(args.y, operation, "y", id);
+    const point = normalizeAppearance(args.point, POINT_OPTIONS, `${operation} point`);
+    const { radius, ...pointAppearance } = point;
+    if (radius !== undefined) validateNonNegativeFinite(radius, `${operation} point radius`);
+    const errorBar = normalizeAppearance(
+      args.errorBar,
+      ERROR_BAR_OPTIONS,
+      `${operation} errorBar`
+    );
+    const color = normalizeEncoding(args.color, `${operation} color`);
+    const guides = normalizeGuides(args.guides, operation);
+    const intervalId = `${id}Interval`;
+
+    let next = this.createErrorBar({
+      id: intervalId,
+      data,
+      x,
+      y,
+      ...(args.xOffset === undefined ? {} : { xOffset: args.xOffset }),
+      ...(args.yOffset === undefined ? {} : { yOffset: args.yOffset }),
+      ...(Object.hasOwn(args, "groupBy") ? { groupBy: args.groupBy } : {}),
+      ...(args.coordinate === undefined ? {} : { coordinate: args.coordinate }),
+      ...errorBar
+    });
+    const config = next.markConfigs[intervalId]?.errorBar;
+    if (config === undefined) {
+      throw new Error(`Interval plot child "${intervalId}" has no interval owner configuration.`);
+    }
+    next = next.createPointMark({ id, data: config.data, ...pointAppearance });
+    next = applyIntervalPointPositions(next, id, config);
+    if (radius !== undefined) next = next.encodePointRadius({ target: id, value: radius });
+    if (color !== undefined) next = next.encodeColor(targetArgs(color, id));
+    next = next._withMarkConfig(id, {
+      ...next.markConfigs[id],
+      intervalPlot: { intervalId, materialized: true }
+    });
+    return applyFacadeGuides(next, guides, id, guides);
+  }
+);
+
+const REGRESSION_OPTIONS = Object.freeze([
+  "id", "data", "coordinate", "x", "y", "color", "size", "shape", "point",
+  "groupBy", "method", "degree", "span", "confidenceMethod", "level", "confidence",
+  "interval", "band", "line", "guides"
+]);
+
+export const createRegressionPlot = action(
+  {
+    op: "createRegressionPlot",
+    description: "Create a scatter plot with a fitted regression line and optional interval band."
+  },
+  function (args = {}) {
+    const operation = "createRegressionPlot";
+    validateFacadeOptions(args, REGRESSION_OPTIONS, operation);
+    const id = resolveFacadeId(this, args.id, { defaultId: "regressionPlot", operation });
+    const data = resolveFacadeData(this, args.data, operation);
+    const guides = normalizeGuides(args.guides, operation);
+    let next = this.createScatterPlot({
+      id,
+      data,
+      x: args.x,
+      y: args.y,
+      ...(args.coordinate === undefined ? {} : { coordinate: args.coordinate }),
+      ...(args.color === undefined ? {} : { color: args.color }),
+      ...(args.size === undefined ? {} : { size: args.size }),
+      ...(args.shape === undefined ? {} : { shape: args.shape }),
+      ...(args.point === undefined ? {} : { point: args.point }),
+      guides: false
+    });
+    const regression = Object.fromEntries([
+      "groupBy", "method", "degree", "span", "confidenceMethod", "level",
+      "confidence", "interval", "band", "line"
+    ].filter(key => Object.hasOwn(args, key)).map(key => [key, args[key]]));
+    next = next.createRegression({ target: id, ...regression });
+    return applyFacadeGuides(next, guides, id, guides);
+  }
+);

package/src/actions/charts/line.js

@@ -1,5 +1,6 @@
 import { action } from "../../core/action.js";
-import { validateNonEmptyString } from "../../core/validation.js";
+import { normalizeGroupFields } from "../../grammar/pathSeries.js";
+import { STROKE_STYLE_PROPERTIES } from "../../grammar/strokeStyle.js";
 import {
   applyFacadeGuides,
   normalizeAppearance,
@@ -19,7 +20,8 @@ const OPTIONS = Object.freeze([
   "strokeDash", "line", "guides"
 ]);
 const LINE_OPTIONS = Object.freeze([
-  "strokeWidth", "curve", "stroke", "opacity", "closed"
+  "strokeWidth", "curve", "stroke", "opacity", "closed",
+  ...STROKE_STYLE_PROPERTIES
 ]);
 
 export const createLinePlot = action(
@@ -50,20 +52,20 @@ export const createLinePlot = action(
     const strokeDash = normalizeStrokeDashEncoding(args.strokeDash);
     const groupBy = args.groupBy === undefined
       ? undefined
-      : validateNonEmptyString(args.groupBy, "createLinePlot groupBy");
+      : normalizeGroupFields(args.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 });
+      next = next.encodeGroup({ fields: groupBy, target: id });
     }
+    if (color !== undefined) next = next.encodeColor(targetArgs(color, id));
     if (strokeDash !== undefined) {
       next = next.encodeStrokeDash(targetArgs(strokeDash, id));
     }
-    return applyFacadeGuides(next, guides);
+    return applyFacadeGuides(next, guides, id);
   }
 );

package/src/actions/charts/parallel.js

@@ -1,5 +1,6 @@
 import { action } from "../../core/action.js";
 import { resolveParallelCoordinate } from "../coordinates/parallel.js";
+import { STROKE_STYLE_PROPERTIES } from "../../grammar/strokeStyle.js";
 import {
   applyFacadeGuides,
   normalizeAppearance,
@@ -17,7 +18,8 @@ const OPTIONS = Object.freeze([
   "color", "strokeDash", "line", "guides"
 ]);
 const LINE_OPTIONS = Object.freeze([
-  "strokeWidth", "stroke", "opacity", "curve", "closed"
+  "strokeWidth", "stroke", "opacity", "curve", "closed",
+  ...STROKE_STYLE_PROPERTIES
 ]);
 
 function scopeParallelGuides(guides, coordinate) {
@@ -105,6 +107,10 @@ export const createParallelCoordinates = action(
     if (strokeDash !== undefined) {
       next = next.encodeStrokeDash(targetArgs(strokeDash, id));
     }
-    return applyFacadeGuides(next, guides);
+    next = applyFacadeGuides(next, guides, id);
+    return next._withMarkConfig(id, {
+      ...next.markConfigs[id],
+      compositionRole: "parallel"
+    });
   }
 );

package/src/actions/charts/pie.js

@@ -0,0 +1,52 @@
+import { action } from "../../core/action.js";
+import { STROKE_STYLE_PROPERTIES } from "../../grammar/strokeStyle.js";
+import {
+  applyFacadeGuides, normalizeAppearance, normalizeCategoricalColor, normalizeCategoricalGuides,
+  normalizeArcCategory, normalizeCategoryAggregate, omitUndefinedOptions,
+  resolveFacadeData, resolveFacadeId, validateFacadeOptions
+} from "./shared.js";
+
+const OPERATION = "createPiePlot";
+const OPTIONS = ["id", "data", "coordinate", "category", "value", "aggregate", "color", "arc", "guides"];
+const ARC_OPTIONS = [
+  "innerRadius", "padAngle", "fill", "opacity", "stroke", "strokeWidth",
+  ...STROKE_STYLE_PROPERTIES
+];
+function guideOptions(value, color) {
+  const guides = normalizeCategoricalGuides(value, OPERATION, color);
+  if (guides === false) return false;
+  for (const key of ["axes", "grid"]) {
+    if (guides[key] !== undefined && guides[key] !== false) {
+      throw new TypeError(`${OPERATION} guides.${key} only accepts false.`);
+    }
+  }
+  return { ...guides, axes: false, grid: false };
+}
+
+export const createPiePlot = action({
+  op: OPERATION, description: "Create a categorical count or weighted-sum pie or donut plot."
+}, function (args = {}) {
+  validateFacadeOptions(args, OPTIONS, OPERATION);
+  const id = resolveFacadeId(this, args.id, { defaultId: "piePlot", operation: OPERATION });
+  const data = resolveFacadeData(this, args.data, OPERATION);
+  const category = normalizeArcCategory(args.category, OPERATION);
+  const aggregate = normalizeCategoryAggregate(args, OPERATION);
+  const arc = omitUndefinedOptions(normalizeAppearance(args.arc, ARC_OPTIONS, `${OPERATION} arc`));
+  const color = args.color === false ? undefined
+    : normalizeCategoricalColor(args.color === undefined ? category.field : args.color, `${OPERATION} color`);
+  if (color !== undefined && arc.fill !== undefined) {
+    throw new Error(`${OPERATION} arc.fill cannot be combined with color; use color:false.`);
+  }
+  const guides = guideOptions(args.guides, color);
+  let next = this.createArcMark({ id, data, ...arc }).encodeTheta({
+    ...category, target: id, aggregate,
+    ...(args.coordinate === undefined ? {} : { coordinate: args.coordinate }),
+    ...(aggregate === "sum" ? { weight: args.value } : {})
+  });
+  if (color !== undefined) next = next.encodeColor({ ...color, target: id });
+  next = applyFacadeGuides(next, guides, id, args.guides ?? {});
+  return next._withMarkConfig(id, {
+    ...next.markConfigs[id],
+    compositionRole: "pie"
+  });
+});

package/src/actions/charts/polar.js

@@ -0,0 +1,134 @@
+import { action } from "../../core/action.js";
+import { validateNonNegativeFinite, validateOptionObject } from
+  "../../core/validation.js";
+import { normalizeGroupFields } from "../../grammar/pathSeries.js";
+import { STROKE_STYLE_PROPERTIES } from "../../grammar/strokeStyle.js";
+import {
+  applyFacadeGuides,
+  normalizeAppearance,
+  normalizeEncoding,
+  normalizeFieldEncoding,
+  normalizeGuides,
+  normalizeStrokeDashEncoding,
+  positionArgs,
+  resolveFacadeData,
+  resolveFacadeId,
+  targetArgs,
+  validateFacadeOptions
+} from "./shared.js";
+
+const POSITION_OPTIONS = Object.freeze([
+  "field", "fieldType", "temporalUnit", "scale"
+]);
+const POINT_OPTIONS = Object.freeze([
+  "shape", "fill", "opacity", "stroke", "strokeWidth", "radius",
+  ...STROKE_STYLE_PROPERTIES
+]);
+const LINE_OPTIONS = Object.freeze([
+  "strokeWidth", "curve", "stroke", "opacity", "closed",
+  ...STROKE_STYLE_PROPERTIES
+]);
+
+function position(value, operation, channel) {
+  const resolved = normalizeFieldEncoding(value, `${operation} ${channel}`);
+  validateOptionObject(
+    resolved,
+    channel === "theta" ? POSITION_OPTIONS : ["field", "fieldType", "scale"],
+    `${operation} ${channel}`
+  );
+  return resolved;
+}
+
+export const createPolarScatterPlot = action(
+  {
+    op: "createPolarScatterPlot",
+    description: "Create a Polar scatter plot with distinct radial position and glyph size."
+  },
+  function (args = {}) {
+    const operation = "createPolarScatterPlot";
+    validateFacadeOptions(args, [
+      "id", "data", "coordinate", "theta", "radius", "color", "size",
+      "shape", "point", "guides"
+    ], operation);
+    const id = resolveFacadeId(this, args.id, {
+      defaultId: "polarScatterPlot",
+      operation
+    });
+    const data = resolveFacadeData(this, args.data, operation);
+    const theta = position(args.theta, operation, "theta");
+    const radiusPosition = position(args.radius, operation, "radius");
+    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`
+    );
+    const guides = normalizeGuides(args.guides, operation);
+    if (radius !== undefined) {
+      validateNonNegativeFinite(radius, `${operation} point radius`);
+      if (size !== undefined) {
+        throw new Error(`${operation} point radius conflicts with size.`);
+      }
+    }
+
+    let next = this
+      .createPointMark({ id, data, ...point })
+      .encodeTheta(positionArgs(theta, { target: id, coordinate: args.coordinate }))
+      .encodeR(positionArgs(radiusPosition, { 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));
+    next = applyFacadeGuides(next, guides, id);
+    return next._withMarkConfig(id, {
+      ...next.markConfigs[id],
+      compositionRole: "polar-point"
+    });
+  }
+);
+
+export const createPolarLinePlot = action(
+  {
+    op: "createPolarLinePlot",
+    description: "Create an open or explicitly closed Polar line plot."
+  },
+  function (args = {}) {
+    const operation = "createPolarLinePlot";
+    validateFacadeOptions(args, [
+      "id", "data", "coordinate", "theta", "radius", "color", "groupBy",
+      "strokeDash", "line", "guides"
+    ], operation);
+    const id = resolveFacadeId(this, args.id, {
+      defaultId: "polarLinePlot",
+      operation
+    });
+    const data = resolveFacadeData(this, args.data, operation);
+    const theta = position(args.theta, operation, "theta");
+    const radius = position(args.radius, operation, "radius");
+    const color = normalizeEncoding(args.color, `${operation} color`);
+    const strokeDash = normalizeStrokeDashEncoding(
+      args.strokeDash,
+      `${operation} strokeDash`
+    );
+    const groupBy = args.groupBy === undefined
+      ? undefined
+      : normalizeGroupFields(args.groupBy);
+    const line = normalizeAppearance(args.line, LINE_OPTIONS, `${operation} line`);
+    const guides = normalizeGuides(args.guides, operation);
+
+    let next = this
+      .createLineMark({ id, data, ...line })
+      .encodeTheta(positionArgs(theta, { target: id, coordinate: args.coordinate }))
+      .encodeR(positionArgs(radius, { target: id, coordinate: args.coordinate }));
+    if (groupBy !== undefined) next = next.encodeGroup({ target: id, fields: groupBy });
+    if (color !== undefined) next = next.encodeColor(targetArgs(color, id));
+    if (strokeDash !== undefined) next = next.encodeStrokeDash(targetArgs(strokeDash, id));
+    next = applyFacadeGuides(next, guides, id);
+    return next._withMarkConfig(id, {
+      ...next.markConfigs[id],
+      compositionRole: "polar-line"
+    });
+  }
+);