ggaction 0.0.12 → 0.0.13

package/src/actions/errorBands/edit.js

@@ -11,12 +11,22 @@ import {
 import { validateCurveInterpolation } from "../../grammar/curveCommands.js";
 import { normalizeStrokeDashPattern } from "../../grammar/scales/index.js";
 import { findLayer } from "../../selectors/layers.js";
+import { findSemanticScale } from "../../selectors/scales.js";
 import { removeOwnedMark } from "../marks/remove.js";
 import { DEFAULT_COLORS } from "../../theme/defaults.js";
+import { resolveIntervalComposite } from "../intervals/resolve.js";
+import {
+  resolveDistributionScalePlan,
+  setCartesianPosition,
+  updateDistributionPositions
+} from "../distributions/revision.js";
 import {
   applyIntervalRevision,
+  collectIntervalConsumers,
+  findIntervalTransform,
   ownOptions,
   planIntervalEdit,
+  planIntervalRoleData,
   releaseIntervalRevision,
   resolveIntervalOwner
 } from "../data/intervalEdit.js";
@@ -43,8 +53,26 @@ export function resolveBoundaryAppearance(value, { defaults, operation }) {
 }
 
 const EDIT_OPTIONS = Object.freeze([
-  "target", "fill", "opacity", "curve", "statistics", "boundaries"
+  "target", "data", "x", "y", "groupBy", "fill", "opacity", "curve",
+  "statistics", "boundaries"
 ]);
+const STATISTICS_OPTIONS = Object.freeze(["center", "extent", "method", "level"]);
+const EDIT_POLICY = Object.freeze({
+  operation: "editErrorBand",
+  resourceLabel: "error-band",
+  defaultId: "errorBand",
+  ownerLabel: "Error-band id",
+  positionTypes: Object.freeze(["quantitative", "temporal"]),
+  defaultPositionType: "quantitative",
+  defaultIntervalChannel: "y",
+  scaleDefaults: fieldType => fieldType === "temporal"
+    ? { nice: true }
+    : { nice: true, zero: false },
+  intervalScaleDefaults: Object.freeze({ nice: true, zero: false }),
+  allowExplicitGrouping: true,
+  ambiguousMessage:
+    "editErrorBand cannot infer the interval axis when both positions are quantitative; provide an interval option."
+});
 const BOUNDARY_EDIT_OPTIONS = Object.freeze([
   "target", "boundary", ...ERROR_BAND_BOUNDARY_OPTIONS
 ]);
@@ -76,6 +104,223 @@ function resolveOwner(program, requested) {
   });
 }
 
+function currentRoleArgs(program, owner, current) {
+  const transform = findIntervalTransform(program, current.data);
+  const intervalChannel = current.orientation === "vertical" ? "y" : "x";
+  const positionChannel = intervalChannel === "x" ? "y" : "x";
+  const position = {
+    field: current.position.field,
+    fieldType: current.position.fieldType,
+    ...(current.position.temporalUnit === undefined
+      ? {}
+      : { temporalUnit: current.position.temporalUnit }),
+    scale: { id: current.positionScale }
+  };
+  const interval = transform === undefined
+    ? {
+        center: current.centerField ?? owner.encoding[intervalChannel].title,
+        lower: current.lowerField,
+        upper: current.upperField,
+        scale: { id: current.intervalScale }
+      }
+    : {
+        field: transform.field,
+        center: transform.center,
+        extent: transform.extent,
+        ...(transform.method === undefined ? {} : { method: transform.method }),
+        ...(transform.level === undefined ? {} : { level: transform.level }),
+        scale: { id: current.intervalScale }
+      };
+  return {
+    source: current.source ?? transform?.source ?? current.data,
+    x: positionChannel === "x" ? position : interval,
+    y: positionChannel === "y" ? position : interval,
+    groupBy: current.groupBy
+  };
+}
+
+function channelArgs(requested, fallback) {
+  if (requested === undefined) return fallback;
+  return requested;
+}
+
+function resolveRoleCandidate(program, owner, current, args) {
+  const previous = currentRoleArgs(program, owner, current);
+  const full = {
+    data: Object.hasOwn(args, "data") ? args.data : previous.source,
+    x: channelArgs(args.x, previous.x),
+    y: channelArgs(args.y, previous.y),
+    ...(Object.hasOwn(args, "groupBy")
+      ? { groupBy: args.groupBy }
+      : previous.groupBy === undefined ? {} : { groupBy: previous.groupBy }),
+    coordinate: current.coordinate
+  };
+  const policy = {
+    ...EDIT_POLICY,
+    existingId: owner.id,
+    coordinate: current.coordinate,
+    generatedFields: findIntervalTransform(program, current.data)?.as
+  };
+  let resolved = resolveIntervalComposite(program, full, policy);
+  if (resolved.groupField === resolved.position.field) {
+    throw new Error(
+      "editErrorBand groupBy must differ from the independent position field."
+    );
+  }
+  if (Object.hasOwn(args, "statistics")) {
+    if (!isPlainObject(args.statistics)) {
+      throw new TypeError("editErrorBand statistics must be a plain object.");
+    }
+    validateKeys(args.statistics, STATISTICS_OPTIONS, "editErrorBand statistics");
+    if (!STATISTICS_OPTIONS.some(key => Object.hasOwn(args.statistics, key))) {
+      throw new Error(
+        "editErrorBand statistics requires center, extent, method, or level."
+      );
+    }
+    full[resolved.interval.channel] = {
+      ...full[resolved.interval.channel],
+      ...args.statistics
+    };
+    resolved = resolveIntervalComposite(program, full, policy);
+  }
+  const positionRole = {
+    field: resolved.position.field,
+    fieldType: resolved.position.fieldType,
+    scale: resolved.position.scale
+  };
+  const intervalTitle = resolved.interval.mode === "statistical"
+    ? resolved.interval.field
+    : resolved.interval.title;
+  const intervalRole = {
+    field: intervalTitle,
+    fieldType: "quantitative",
+    scale: resolved.interval.scale
+  };
+  const x = resolved.position.channel === "x" ? positionRole : intervalRole;
+  const y = resolved.position.channel === "y" ? positionRole : intervalRole;
+  const plan = (channel, role) => {
+    const fallback = role === intervalRole
+      ? current.intervalScale
+      : current.positionScale;
+    const stored = findSemanticScale(program, fallback);
+    const compatible = role.fieldType === "temporal"
+      ? stored?.type === "time"
+      : ["linear", "log", "pow", "sqrt", "symlog"].includes(stored?.type);
+    const requested = role.scale.type !== undefined || compatible
+      ? role.scale
+      : { ...role.scale, type: role.fieldType === "temporal" ? "time" : "linear" };
+    return resolveDistributionScalePlan(program, {
+      channel,
+      fieldType: role.fieldType,
+      requested,
+      fallback,
+      defaults: role === intervalRole
+        ? EDIT_POLICY.intervalScaleDefaults
+        : EDIT_POLICY.scaleDefaults(role.fieldType)
+    });
+  };
+  const xScale = plan("x", x);
+  const yScale = plan("y", y);
+  return {
+    ...resolved,
+    x: { ...x, scale: xScale.id },
+    y: { ...y, scale: yScale.id },
+    xScale,
+    yScale,
+    category: resolved.position.field,
+    categoryType: resolved.position.fieldType,
+    measure: intervalTitle,
+    previous: {
+      x: { field: previous.x.center ?? previous.x.field,
+        fieldType: owner.encoding.x.fieldType, scale: owner.encoding.x.scale },
+      y: { field: previous.y.center ?? previous.y.field,
+        fieldType: owner.encoding.y.fieldType, scale: owner.encoding.y.scale }
+    }
+  };
+}
+
+function updateGrouping(program, ids, previous, nextField) {
+  let next = program;
+  for (const id of ids) {
+    const layer = findLayer(next, id);
+    if (layer === undefined) continue;
+    if (nextField === undefined) {
+      if (layer.encoding?.group !== undefined) {
+        next = next.editSemantic({
+          property: `layer[${id}].encoding.group`, remove: true
+        });
+      }
+    } else if (layer.encoding?.group === undefined) {
+      next = next.encodeGroup({ target: id, field: nextField, fieldType: "nominal" });
+    } else if (layer.encoding.group.field !== nextField) {
+      next = next.editSemantic({
+        property: `layer[${id}].encoding.group.field`, value: nextField
+      });
+    }
+  }
+  return next;
+}
+
+function updateErrorBandRoles(program, owner, current, candidate, dataId, boundaryIds) {
+  const owned = [owner.id, ...boundaryIds];
+  let next = updateDistributionPositions(program, owner, current, candidate, {
+    owned,
+    lower: candidate.fields.lower,
+    upper: candidate.fields.upper,
+    title: candidate.measure,
+    update(value, { category, measure, categoryChannel, measureChannel }) {
+      let updated = value;
+      for (const [id, field] of [
+        [current.lowerBoundaryId, candidate.fields.lower],
+        [current.upperBoundaryId, candidate.fields.upper]
+      ]) {
+        if (findLayer(updated, id) === undefined) continue;
+        updated = setCartesianPosition(updated, id, categoryChannel, {
+          field: candidate.position.field,
+          fieldType: candidate.position.fieldType,
+          scale: category.scale
+        });
+        updated = setCartesianPosition(updated, id, measureChannel, {
+          field,
+          fieldType: "quantitative",
+          scale: measure.scale
+        });
+      }
+      return updated;
+    }
+  });
+  next = updateGrouping(next, owned, current.groupBy, candidate.groupField);
+  const revisedConfig = {
+    ...current,
+    source: candidate.source,
+    data: dataId,
+    intervalMode: candidate.interval.mode,
+    orientation: candidate.orientation,
+    position: candidate.position,
+    positionScale: candidate.position.channel === "x"
+      ? candidate.xScale.id : candidate.yScale.id,
+    intervalScale: candidate.interval.channel === "x"
+      ? candidate.xScale.id : candidate.yScale.id,
+    groupBy: candidate.groupField,
+    transformGroupBy: candidate.groupBy,
+    lowerField: candidate.fields.lower,
+    upperField: candidate.fields.upper
+  };
+  delete revisedConfig.intervalField;
+  delete revisedConfig.centerField;
+  if (candidate.interval.mode === "statistical") {
+    revisedConfig.intervalField = candidate.interval.field;
+  } else {
+    revisedConfig.centerField = candidate.fields.center;
+  }
+  next = next._withMarkConfig(owner.id, {
+    ...next.markConfigs[owner.id],
+    errorBand: revisedConfig
+  }).rematerializeAreaMark({ id: owner.id });
+  for (const id of boundaryIds) next = next.rematerializeLineMark({ id });
+  return next;
+}
+
 function currentBoundaryAppearance(program, id) {
   const config = program.markConfigs[id];
   if (findLayer(program, id)?.mark?.type !== "line" || config === undefined) {
@@ -166,11 +411,12 @@ export const rematerializeErrorBandBoundary = action(
 export const editErrorBand = action(
   {
     op: "editErrorBand",
-    description: "Edit one error-band body appearance."
+    description: "Revise one error band's roles, statistics, body, and boundaries."
   },
   function (args = {}) {
     validateOptionObject(args, EDIT_OPTIONS, "editErrorBand");
-    if (!["fill", "opacity", "curve", "statistics", "boundaries"]
+    if (!["data", "x", "y", "groupBy", "fill", "opacity", "curve",
+      "statistics", "boundaries"]
       .some(key => Object.hasOwn(args, key))) {
       throw new Error("editErrorBand requires at least one change.");
     }
@@ -178,7 +424,16 @@ export const editErrorBand = action(
     const config = { ...this.markConfigs[owner.id] };
     const errorBand = { ...config.errorBand };
     if (Object.hasOwn(args, "fill")) {
-      errorBand.fill = validateNonEmptyString(args.fill, "Error-band fill");
+      if (args.fill === false) {
+        delete errorBand.fill;
+        config.fill = DEFAULT_COLORS.mark;
+      } else {
+        if (owner.encoding?.color !== undefined) {
+          throw new Error("editErrorBand fill conflicts with a color encoding; remove the color encoding first.");
+        }
+        errorBand.fill = validateNonEmptyString(args.fill, "Error-band fill");
+        config.fill = errorBand.fill;
+      }
     }
     if (Object.hasOwn(args, "opacity")) {
       config.opacity = validateUnitInterval(args.opacity, "Error-band opacity");
@@ -186,16 +441,30 @@ export const editErrorBand = action(
     if (Object.hasOwn(args, "curve")) {
       config.curve = validateCurveInterpolation(args.curve);
     }
-    const interval = Object.hasOwn(args, "statistics")
+    const roleRequested = ["data", "x", "y", "groupBy"].some(
+      key => Object.hasOwn(args, key)
+    );
+    const candidate = roleRequested
+      ? resolveRoleCandidate(this, owner, errorBand, args)
+      : undefined;
+    const existingBoundaryIds = errorBandBoundaries(errorBand)
+      .map(([id]) => id)
+      .filter(id => findLayer(this, id) !== undefined);
+    const consumers = collectIntervalConsumers(
+      this, [owner.id, ...existingBoundaryIds]
+    );
+    const interval = roleRequested
+      ? planIntervalRoleData(this, {
+          owner: owner.id,
+          currentData: errorBand.data,
+          candidate,
+          consumers
+        })
+      : Object.hasOwn(args, "statistics")
       ? planIntervalEdit(this, {
           owner: owner.id,
           data: errorBand.data,
-          consumers: [
-            owner.id,
-            ...errorBandBoundaries(errorBand)
-              .map(([id]) => id)
-              .filter(id => findLayer(this, id) !== undefined)
-          ],
+          consumers,
           statistics: args.statistics,
           operation: "editErrorBand"
         })
@@ -210,17 +479,68 @@ export const editErrorBand = action(
       );
     }
 
-    let next = applyIntervalRevision(this, interval);
-    if (interval.changed) errorBand.data = interval.revision.id;
-    next = next
-      ._withMarkConfig(owner.id, { ...config, errorBand })
-      .rematerializeAreaMark({ id: owner.id });
+    let base = this;
+    if (roleRequested && owner.encoding?.color?.field !== undefined) {
+      const colorField = owner.encoding.color.field;
+      const followsGroup = colorField === this.markConfigs[owner.id].errorBand.groupBy;
+      if (followsGroup && candidate.groupField !== undefined) {
+        const referenced = Object.entries(
+          this.materializationConfigs.selections ?? {}
+        ).find(([, selection]) =>
+          selection.target === owner.id &&
+          ["group", "color"].includes(selection.selector?.channel)
+        );
+        if (referenced !== undefined && candidate.groupField !== colorField) {
+          throw new Error(
+            `editErrorBand cannot change groupBy while selection "${referenced[0]}" ` +
+            `references ${referenced[1].selector.channel}.`
+          );
+        }
+        base = base.editSemantic({
+          property: `layer[${owner.id}].encoding.color.field`,
+          value: candidate.groupField
+        });
+      } else if (
+        candidate.interval.mode === "statistical" &&
+        !candidate.groupBy.includes(colorField)
+      ) {
+        throw new Error(
+          `editErrorBand roles would remove color field "${colorField}" from the interval data.`
+        );
+      }
+    }
+    if (roleRequested && candidate.groupField !== undefined) {
+      for (const id of [owner.id, ...existingBoundaryIds]) {
+        const layer = findLayer(base, id);
+        if (
+          layer?.encoding?.group !== undefined &&
+          layer.encoding.group.field !== candidate.groupField
+        ) {
+          base = base.editSemantic({
+            property: `layer[${id}].encoding.group.field`,
+            value: candidate.groupField
+          });
+        }
+      }
+    }
+    let next = applyIntervalRevision(base, interval);
+    if (interval.changed) {
+      errorBand.data = interval.dataId ?? interval.revision.id;
+    }
+    next = next._withMarkConfig(owner.id, { ...config, errorBand });
+    next = roleRequested
+      ? updateErrorBandRoles(
+          next, owner, this.markConfigs[owner.id].errorBand,
+          candidate, interval.dataId, existingBoundaryIds
+        )
+      : next.rematerializeAreaMark({ id: owner.id });
+    const revisedErrorBand = next.markConfigs[owner.id].errorBand;
     if (Object.hasOwn(args, "boundaries")) {
       if (args.boundaries === false) {
-        next = removeBoundary(next, errorBand.lowerBoundaryId);
-        next = removeBoundary(next, errorBand.upperBoundaryId);
+        next = removeBoundary(next, revisedErrorBand.lowerBoundaryId);
+        next = removeBoundary(next, revisedErrorBand.upperBoundaryId);
       } else if (Object.keys(args.boundaries).length === 0) {
-        for (const [id, bound] of errorBandBoundaries(errorBand)) {
+        for (const [id, bound] of errorBandBoundaries(revisedErrorBand)) {
           next = findLayer(next, id) === undefined
             ? createBoundary(
                 next,
@@ -239,8 +559,8 @@ export const editErrorBand = action(
           ...args.boundaries
         });
       }
-    } else if (interval.changed) {
-      for (const [id] of errorBandBoundaries(errorBand)) {
+    } else if (interval.changed && !roleRequested) {
+      for (const [id] of errorBandBoundaries(revisedErrorBand)) {
         if (findLayer(next, id) !== undefined) {
           next = next.rematerializeLineMark({ id });
         }

package/src/actions/errorBars/create.js

@@ -38,7 +38,7 @@ const OFFSET_OPTIONS = Object.freeze([
   "field", "fieldType", "scale", "paddingInner", "paddingOuter"
 ]);
 
-const ERROR_BAR_POLICY = Object.freeze({
+export const ERROR_BAR_POLICY = Object.freeze({
   operation: "createErrorBar",
   resourceLabel: "error-bar",
   defaultId: "errorBar",
@@ -55,9 +55,9 @@ const ERROR_BAR_POLICY = Object.freeze({
     "createErrorBar requires one quantitative interval axis and one compatible position axis; use interval options to disambiguate two quantitative channels."
 });
 
-function resolveErrorBar(program, args) {
-  const resolved = resolveIntervalComposite(program, args, ERROR_BAR_POLICY);
-  const offset = resolveErrorBarOffset(program, args, resolved);
+export function resolveErrorBar(program, args, policy = ERROR_BAR_POLICY) {
+  const resolved = resolveIntervalComposite(program, args, policy);
+  const offset = resolveErrorBarOffset(program, args, resolved, policy.operation);
   const groupBy = resolved.interval.mode === "statistical" && offset !== undefined
     ? [...new Set([...resolved.groupBy, offset.field])]
     : resolved.groupBy;
@@ -70,27 +70,27 @@ function resolveErrorBar(program, args) {
   };
 }
 
-function resolveErrorBarOffset(program, args, resolved) {
+function resolveErrorBarOffset(program, args, resolved, operation) {
   const channel = `${resolved.position.channel}Offset`;
   const incompatible = channel === "xOffset" ? "yOffset" : "xOffset";
   if (args[incompatible] !== undefined) {
     throw new Error(
-      `createErrorBar ${incompatible} does not match the ${resolved.orientation} interval orientation.`
+      `${operation} ${incompatible} does not match the ${resolved.orientation} interval orientation.`
     );
   }
   const explicit = args[channel] === undefined
     ? undefined
-    : validateOptionObject(args[channel], OFFSET_OPTIONS, `createErrorBar ${channel}`);
+    : validateOptionObject(args[channel], OFFSET_OPTIONS, `${operation} ${channel}`);
   const inferred = resolved.sourceLayer?.encoding?.[channel];
   if (explicit === undefined && inferred === undefined) return undefined;
   if (!["nominal", "ordinal"].includes(resolved.position.fieldType)) {
     throw new Error(
-      `createErrorBar ${channel} requires a categorical ${resolved.position.channel} position.`
+      `${operation} ${channel} requires a categorical ${resolved.position.channel} position.`
     );
   }
   const field = explicit?.field ?? inferred?.field;
   if (typeof field !== "string" || field.length === 0) {
-    throw new TypeError(`createErrorBar ${channel} field must be a non-empty string.`);
+    throw new TypeError(`${operation} ${channel} field must be a non-empty string.`);
   }
   const fieldType = validateCategoricalFieldType(
     explicit?.fieldType ?? inferred?.fieldType ?? "nominal"
@@ -140,7 +140,7 @@ export const createErrorBarCap = action(
   function (args = {}) {
     validateKeys(args, [
       "id", "data", "orientation", "positionField", "positionFieldType",
-      "intervalField", "coordinate", "positionScale", "intervalScale",
+      "intervalField", "coordinate", "positionScale", "intervalScale", "positionTemporalUnit",
       "offsetChannel", "offsetField", "offsetFieldType", "offsetScale",
       "offsetPaddingInner", "offsetPaddingOuter",
       "capSize", "stroke", "strokeWidth", "strokeDash", "opacity"
@@ -166,6 +166,7 @@ export const createErrorBarCap = action(
         target: args.id,
         field: args.positionField,
         fieldType: args.positionFieldType,
+        ...(args.positionTemporalUnit === undefined ? {} : { temporalUnit: args.positionTemporalUnit }),
         coordinate: args.coordinate,
         scale: { id: args.positionScale }
       })
@@ -207,6 +208,7 @@ function positionArgs(resolved) {
     target: resolved.id,
     field: resolved.position.field,
     fieldType: resolved.position.fieldType,
+    ...(resolved.position.temporalUnit === undefined ? {} : { temporalUnit: resolved.position.temporalUnit }),
     coordinate: resolved.coordinate,
     scale: resolved.position.scale
   };
@@ -282,6 +284,7 @@ export const createErrorBar = action(
           orientation: resolved.orientation,
           positionField: resolved.position.field,
           positionFieldType: resolved.position.fieldType,
+        ...(resolved.position.temporalUnit === undefined ? {} : { positionTemporalUnit: resolved.position.temporalUnit }),
           intervalField: field,
           coordinate: resolved.coordinate,
           positionScale: intervalLayer.encoding[resolved.position.channel].scale,
@@ -307,10 +310,18 @@ export const createErrorBar = action(
     return next._withMarkConfig(resolved.id, {
       ...next.markConfigs[resolved.id],
       errorBar: {
+        source: resolved.source,
+        intervalMode: resolved.interval.mode,
+        ...(resolved.interval.mode === "statistical"
+          ? { intervalField: resolved.interval.field }
+          : { centerField: resolved.fields.center }),
+        groupField: resolved.groupField,
+        groupBy: resolved.groupBy,
         data: resolved.dataId,
         orientation: resolved.orientation,
         positionField: resolved.position.field,
         positionFieldType: resolved.position.fieldType,
+        ...(resolved.position.temporalUnit === undefined ? {} : { positionTemporalUnit: resolved.position.temporalUnit }),
         lowerField: resolved.fields.lower,
         upperField: resolved.fields.upper,
         coordinate: resolved.coordinate,