ggaction 0.0.4 → 0.0.6

package/src/actions/encodings/remove.js

@@ -0,0 +1,268 @@
+import { action } from "../../core/action.js";
+import { validateUserId } from "../../core/identifiers.js";
+import { validateOptionObject } from "../../core/validation.js";
+import {
+  getPositionChannelDefinition,
+  POSITION_ENCODING_CHANNELS
+} from "../../core/vocabulary.js";
+import {
+  resolveBarChannels,
+  resolveBarColorLayout,
+  resolveBarOffsetChannel
+} from "../../grammar/bars/policy.js";
+import {
+  getMarkMaterializationStep,
+  getSourceDependentMarkSteps
+} from "../../materialization/marks/index.js";
+import { findLayer } from "../../selectors/layers.js";
+import { removeLegendKinds } from "../guides/legends/remove.js";
+
+const OPTIONS = Object.freeze(["target", "channel"]);
+const REMOVABLE_CHANNELS = Object.freeze([
+  "x", "y", "x2", "y2", "xOffset", "yOffset", "theta", "radius",
+  "color", "strokeDash", "strokeWidth", "size", "shape", "group",
+  "opacity", "text"
+]);
+const REMOVE_AXIS = Object.freeze({
+  x: "removeXAxis",
+  y: "removeYAxis",
+  theta: "removeThetaAxis",
+  radius: "removeRadialAxis"
+});
+const SPECIALIZED_LEGEND_KIND = Object.freeze({
+  color: Object.freeze(["gradient", "interval"]),
+  size: Object.freeze(["size"]),
+  opacity: Object.freeze(["opacity"]),
+  strokeWidth: Object.freeze(["strokeWidth"])
+});
+
+function resolveTarget(program, requested, channel) {
+  const candidates = program.semanticSpec.layers.filter(
+    layer => layer.encoding?.[channel] !== undefined
+  );
+  if (requested !== undefined) {
+    const id = validateUserId(requested, "Encoding target id");
+    const layer = findLayer(program, id);
+    if (layer === undefined) {
+      throw new Error(`Unknown encoding target "${id}".`);
+    }
+    if (layer.encoding?.[channel] === undefined) {
+      throw new Error(`Mark "${id}" has no ${channel} encoding.`);
+    }
+    return layer;
+  }
+  const current = candidates.find(
+    layer => layer.id === program.context.currentMark
+  );
+  if (current !== undefined) return current;
+  if (candidates.length === 1) return candidates[0];
+  if (candidates.length === 0) {
+    throw new Error(`removeEncoding requires an active ${channel} encoding.`);
+  }
+  throw new Error(`removeEncoding ${channel} target is ambiguous; provide target.`);
+}
+
+function activeCascade(layer, channel) {
+  const channels = new Set([channel]);
+  if (channel === "x") {
+    channels.add("x2");
+    channels.add("xOffset");
+  }
+  if (channel === "y") {
+    channels.add("y2");
+    channels.add("yOffset");
+  }
+  if (channel === "color" && layer.mark?.type === "bar") {
+    if (resolveBarColorLayout(layer) === "group") {
+      channels.add(resolveBarOffsetChannel(layer));
+    }
+  }
+  if (
+    channel === "group" &&
+    layer.mark?.type === "area" &&
+    layer.encoding?.color?.field !== undefined &&
+    layer.encoding.color.field === layer.encoding.group?.field
+  ) {
+    channels.add("color");
+  }
+  return [...channels].filter(active => layer.encoding?.[active] !== undefined);
+}
+
+function assertSelectionCompatibility(program, target, channels) {
+  for (const [id, selection] of Object.entries(
+    program.materializationConfigs.selections ?? {}
+  )) {
+    if (
+      selection.target === target &&
+      channels.includes(selection.selector?.channel)
+    ) {
+      throw new Error(
+        `Cannot remove ${selection.selector.channel} encoding while selection "${id}" references that channel.`
+      );
+    }
+  }
+}
+
+function removeChannelConfigs(program, target, channels) {
+  let next = program;
+  for (const channel of channels) {
+    if (["xOffset", "yOffset"].includes(channel)) {
+      next = next._withoutMaterializationConfig(["marks", target, channel]);
+    }
+  }
+  return next;
+}
+
+function restoreBarBaseline(program, layer, channels) {
+  if (layer.mark?.type !== "bar" || !channels.includes("color")) {
+    return program;
+  }
+  const measureChannel = resolveBarChannels(layer)?.measure;
+  if (
+    measureChannel === undefined ||
+    layer.encoding?.[measureChannel]?.stack !== "normalize"
+  ) {
+    return program;
+  }
+  return program.editSemantic({
+    property: `layer[${layer.id}].encoding.${measureChannel}.stack`,
+    value: "zero"
+  });
+}
+
+function hasPrimaryScaleConsumer(program, channel, scale) {
+  return program.semanticSpec.layers.some(
+    layer => layer.encoding?.[channel]?.scale === scale
+  );
+}
+
+function cleanupPositionGuides(program, removed) {
+  let next = program;
+  for (const { channel, scale } of removed) {
+    const definition = getPositionChannelDefinition(channel);
+    if (
+      definition?.guideChannel === undefined ||
+      hasPrimaryScaleConsumer(next, channel, scale)
+    ) {
+      continue;
+    }
+    const axis = next.semanticSpec.guides.axis?.[definition.guideChannel];
+    if (axis?.scale === scale) {
+      next = next[REMOVE_AXIS[definition.guideChannel]]({
+        scale,
+        ...(axis.coordinate === undefined ? {} : { coordinate: axis.coordinate })
+      });
+    }
+    const grid = next.semanticSpec.guides.grid?.[definition.gridDirection];
+    if (grid?.scale === scale) {
+      next = next.removeGrid({ [definition.gridDirection]: true });
+    }
+  }
+  return next;
+}
+
+function reconcileCategoricalLegend(program, target, channels) {
+  const entry = ["series", "color"]
+    .map(kind => [kind, program.guideConfigs.legend?.[kind]])
+    .find(([, config]) =>
+      config?.target === target &&
+      config.channels.some(channel => channels.includes(channel))
+    );
+  if (entry === undefined) return program;
+  const [kind, config] = entry;
+  const layer = findLayer(program, target);
+  const remaining = config.channels.filter(
+    channel => layer.encoding?.[channel]?.scale !== undefined
+  );
+  if (remaining.length === 0) {
+    return removeLegendKinds(program, [kind]);
+  }
+  const next = removeLegendKinds(program, [kind]);
+  return next.createLegend({
+    target,
+    channels: remaining,
+    position: config.position,
+    align: config.align,
+    direction: config.direction,
+    ...(config.columns === undefined ? {} : { columns: config.columns }),
+    offset: config.offset,
+    titlePosition: config.titlePosition,
+    ...(config.inferredTitle ? {} : { title: config.title }),
+    symbol: config.symbol,
+    labels: config.labels,
+    titleStyle: config.titleStyle,
+    itemGap: config.itemGap,
+    border: config.border
+  });
+}
+
+function cleanupLegends(program, target, channels) {
+  let next = reconcileCategoricalLegend(program, target, channels);
+  const kinds = [...new Set(channels.flatMap(
+    channel => SPECIALIZED_LEGEND_KIND[channel] ?? []
+  ))].filter(kind => next.guideConfigs.legend?.[kind]?.target === target);
+  return kinds.length === 0 ? next : removeLegendKinds(next, kinds);
+}
+
+function clearGraphic(program, target) {
+  const graphic = program.graphicSpec.objects[target];
+  if (graphic === undefined) return program;
+  return graphic.type === "collection"
+    ? program.editGraphics({ target, property: "items", value: [] })
+    : program.editGraphics({ target, property: "length", value: 0 });
+}
+
+function rematerializeTarget(program, target) {
+  const layer = findLayer(program, target);
+  const step = getMarkMaterializationStep(program, layer);
+  const baseline = clearGraphic(program, target);
+  let next = step === undefined
+    ? baseline
+    : baseline[step.op](step.args);
+  for (const dependent of getSourceDependentMarkSteps(next, target)) {
+    next = next[dependent.op](dependent.args);
+  }
+  return next;
+}
+
+export const removeEncoding = action(
+  {
+    op: "removeEncoding",
+    description: "Remove one semantic encoding and its owned materialized state."
+  },
+  function (args = {}) {
+    validateOptionObject(args, OPTIONS, "removeEncoding");
+    if (!REMOVABLE_CHANNELS.includes(args.channel)) {
+      throw new Error(
+        `Unsupported removable encoding channel "${args.channel}".`
+      );
+    }
+    const layer = resolveTarget(this, args.target, args.channel);
+    const channels = activeCascade(layer, args.channel);
+    assertSelectionCompatibility(this, layer.id, channels);
+    const removedPositions = channels
+      .filter(channel => POSITION_ENCODING_CHANNELS.includes(channel))
+      .map(channel => ({
+        channel,
+        scale: layer.encoding[channel].scale
+      }))
+      .filter(item => item.scale !== undefined);
+
+    let next = this;
+    for (const channel of channels) {
+      next = next.editSemantic({
+        property: `layer[${layer.id}].encoding.${channel}`,
+        remove: true
+      });
+    }
+    next = removeChannelConfigs(next, layer.id, channels);
+    next = restoreBarBaseline(next, layer, channels);
+    next = cleanupLegends(next, layer.id, channels);
+    next = cleanupPositionGuides(next, removedPositions);
+    return rematerializeTarget(next, layer.id);
+  }
+);
+
+export function registerEncodingRemovalAction(ProgramClass) {
+  ProgramClass.prototype.removeEncoding = removeEncoding;
+}

package/src/actions/encodings/ruleAppearance.js

@@ -3,9 +3,22 @@ import {
   validateRuleStroke,
   validateRuleStrokeWidth
 } from "../../grammar/ruleAppearance.js";
-import { resolveTarget, validateOptions } from "./shared.js";
+import { readQuantitativeField } from "../../grammar/scales/index.js";
+import { resolveStrokeWidthScaleDefinition } from "../scales/definitions.js";
+import {
+  applyEncodingScale,
+  resolveReassignmentScaleOptions,
+  resolveTarget,
+  validateOptions
+} from "./shared.js";
+import { applyMaterializationPlan } from "../../materialization/dependencies.js";
+import { planEncodingRematerialization } from "../../materialization/encodings.js";
+import { findLayer } from "../../selectors/layers.js";
 
-const OPTIONS = Object.freeze(["target", "value"]);
+const STROKE_OPTIONS = Object.freeze(["target", "value"]);
+const WIDTH_OPTIONS = Object.freeze([
+  "target", "value", "field", "fieldType", "scale"
+]);
 
 const encodeStroke = action(
   {
@@ -13,7 +26,7 @@ const encodeStroke = action(
     description: "Set a constant graphical stroke on a rule mark."
   },
   function (args = {}) {
-    validateOptions(args, OPTIONS, "encodeStroke");
+    validateOptions(args, STROKE_OPTIONS, "encodeStroke");
     const { id } = resolveTarget(this, args.target, ["rule"], "rule mark");
     return this
       ._withMarkConfig(id, {
@@ -30,14 +43,79 @@ const encodeStrokeWidth = action(
     description: "Set a constant graphical stroke width on a rule mark."
   },
   function (args = {}) {
-    validateOptions(args, OPTIONS, "encodeStrokeWidth");
-    const { id } = resolveTarget(this, args.target, ["rule"], "rule mark");
-    return this
-      ._withMarkConfig(id, {
-        ...this.markConfigs[id],
-        strokeWidth: validateRuleStrokeWidth(args.value)
+    validateOptions(args, WIDTH_OPTIONS, "encodeStrokeWidth");
+    const hasValue = Object.hasOwn(args, "value");
+    const hasField = Object.hasOwn(args, "field");
+    if (hasValue === hasField) {
+      throw new Error("encodeStrokeWidth requires exactly one of value or field.");
+    }
+    if (hasValue) {
+      const { id } = resolveTarget(this, args.target, ["rule"], "rule mark");
+      let next = this.guideConfigs.legend?.strokeWidth?.target === id
+        ? this.removeLegend({ target: id })
+        : this;
+      if (findLayer(next, id)?.encoding?.strokeWidth !== undefined) {
+        next = next.editSemantic({
+          property: `layer[${id}].encoding.strokeWidth`,
+          remove: true
+        });
+      }
+      return next
+        ._withMarkConfig(id, {
+          ...next.markConfigs[id],
+          strokeWidth: validateRuleStrokeWidth(args.value)
+        })
+        .rematerializeRuleMark({ id });
+    }
+    const { id, dataset, layer } = resolveTarget(
+      this,
+      args.target,
+      ["rule", "line"],
+      "rule or line mark"
+    );
+    const fieldType = args.fieldType ?? "quantitative";
+    if (fieldType !== "quantitative") {
+      throw new Error("encodeStrokeWidth requires a quantitative field.");
+    }
+    const values = readQuantitativeField(dataset.values, args.field);
+    if (values.some(value => value < 0)) {
+      throw new RangeError(
+        `encodeStrokeWidth field "${args.field}" cannot contain negative values.`
+      );
+    }
+    const previous = layer.encoding?.strokeWidth;
+    const requestedScale = resolveReassignmentScaleOptions(
+      previous,
+      args.scale ?? {}
+    );
+    const scale = resolveStrokeWidthScaleDefinition(this, requestedScale);
+    const { strokeWidth, ...config } = this.markConfigs[id] ?? {};
+    void strokeWidth;
+    let next = this
+      ._withMarkConfig(id, config)
+      .editSemantic({
+        property: `layer[${id}].encoding.strokeWidth.field`,
+        value: args.field
       })
-      .rematerializeRuleMark({ id });
+      .editSemantic({
+        property: `layer[${id}].encoding.strokeWidth.fieldType`,
+        value: fieldType
+      })
+      .editSemantic({
+        property: `layer[${id}].encoding.strokeWidth.scale`,
+        value: scale.id
+      });
+    next = applyEncodingScale(next, scale, requestedScale, {
+      reassignment: previous?.scale === scale.id
+    });
+    return applyMaterializationPlan(
+      next,
+      planEncodingRematerialization(next, {
+        target: id,
+        channel: "strokeWidth",
+        scale: scale.id
+      })
+    );
   }
 );
 

package/src/actions/errorBands/edit.js

@@ -1,4 +1,5 @@
 import { action } from "../../core/action.js";
+import { isPlainObject } from "../../core/immutable.js";
 import { validateUserId } from "../../core/identifiers.js";
 import {
   validateOptionObject,
@@ -8,12 +9,15 @@ import {
 import { validateCurveInterpolation } from "../../grammar/curveCommands.js";
 import { findLayer, resolveEligibleLayer } from "../../selectors/layers.js";
 import { DEFAULT_COLORS } from "../../theme/defaults.js";
+import { planIntervalEdit } from "../data/intervalEdit.js";
 import {
   ERROR_BAND_BOUNDARY_OPTIONS,
   resolveBoundaryAppearance
 } from "./options.js";
 
-const EDIT_OPTIONS = Object.freeze(["target", "fill", "opacity", "curve"]);
+const EDIT_OPTIONS = Object.freeze([
+  "target", "fill", "opacity", "curve", "statistics", "boundaries"
+]);
 const BOUNDARY_EDIT_OPTIONS = Object.freeze([
   "target", "boundary", ...ERROR_BAND_BOUNDARY_OPTIONS
 ]);
@@ -49,13 +53,16 @@ function currentBoundaryAppearance(program, id) {
 }
 
 function defaultBoundaryAppearance(program, owner) {
-  return {
-    stroke: DEFAULT_COLORS.mark,
-    strokeWidth: 1,
-    strokeDash: "solid",
-    opacity: 1,
-    curve: program.markConfigs[owner]?.curve ?? "linear"
-  };
+  return resolveBoundaryAppearance({}, {
+    defaults: {
+      stroke: DEFAULT_COLORS.mark,
+      strokeWidth: 1,
+      strokeDash: "solid",
+      opacity: 1,
+      curve: program.markConfigs[owner]?.curve ?? "linear"
+    },
+    operation: "editErrorBand boundaries"
+  });
 }
 
 function createBoundary(program, owner, id, bound, appearance) {
@@ -82,6 +89,34 @@ function createBoundary(program, owner, id, bound, appearance) {
   });
 }
 
+function removeBoundary(program, id) {
+  if (findLayer(program, id) === undefined) return program;
+  const selectionIds = Object.entries(
+    program.materializationConfigs.selections ?? {}
+  ).filter(([, config]) => config.target === id).map(([selection]) => selection);
+  let next = program;
+  for (const [highlight, config] of Object.entries(
+    program.materializationConfigs.highlights ?? {}
+  )) {
+    if (config.target === id || selectionIds.includes(config.selection)) {
+      next = next._withoutMaterializationConfig(["highlights", highlight]);
+    }
+  }
+  for (const selection of selectionIds) {
+    next = next._withoutMaterializationConfig(["selections", selection]);
+  }
+  return next
+    .editSemantic({ property: `layer[${id}]`, remove: true })
+    .editGraphics({ target: id, remove: true })
+    ._withoutMaterializationConfig(["marks", id])
+    ._withContext({
+      ...(program.context.currentMark === id ? { currentMark: undefined } : {}),
+      ...(selectionIds.includes(program.context.currentSelection)
+        ? { currentSelection: undefined }
+        : {})
+    });
+}
+
 export const rematerializeErrorBandBoundary = action(
   {
     op: "rematerializeErrorBandBoundary",
@@ -121,8 +156,9 @@ export const editErrorBand = action(
   },
   function (args = {}) {
     validateOptionObject(args, EDIT_OPTIONS, "editErrorBand");
-    if (!["fill", "opacity", "curve"].some(key => Object.hasOwn(args, key))) {
-      throw new Error("editErrorBand requires fill, opacity, or curve.");
+    if (!["fill", "opacity", "curve", "statistics", "boundaries"]
+      .some(key => Object.hasOwn(args, key))) {
+      throw new Error("editErrorBand requires at least one change.");
     }
     const owner = resolveOwner(this, args.target);
     const config = { ...this.markConfigs[owner.id] };
@@ -136,9 +172,81 @@ export const editErrorBand = action(
     if (Object.hasOwn(args, "curve")) {
       config.curve = validateCurveInterpolation(args.curve);
     }
-    return this
-      ._withMarkConfig(owner.id, { ...config, errorBand })
-      .rematerializeAreaMark({ id: owner.id });
+    const interval = Object.hasOwn(args, "statistics")
+      ? planIntervalEdit(this, {
+          owner: owner.id,
+          data: errorBand.data,
+          consumers: [
+            owner.id,
+            ...[errorBand.lowerBoundaryId, errorBand.upperBoundaryId]
+              .filter(id => findLayer(this, id) !== undefined)
+          ],
+          statistics: args.statistics,
+          operation: "editErrorBand"
+        })
+      : { changed: false };
+    if (
+      Object.hasOwn(args, "boundaries") &&
+      args.boundaries !== false &&
+      !isPlainObject(args.boundaries)
+    ) {
+      throw new TypeError(
+        "editErrorBand boundaries must be false or a plain object."
+      );
+    }
+
+    const applyEdit = program => {
+      let next = program;
+      if (interval.changed) {
+        next = next.createIntervalData(interval.dataArgs);
+        for (const rebind of interval.revision.rebinds) {
+          next = next.rebindLayerData(rebind);
+        }
+        errorBand.data = interval.revision.id;
+      }
+      next = next
+        ._withMarkConfig(owner.id, { ...config, errorBand })
+        .rematerializeAreaMark({ id: owner.id });
+      if (Object.hasOwn(args, "boundaries")) {
+        if (args.boundaries === false) {
+          next = removeBoundary(next, errorBand.lowerBoundaryId);
+          next = removeBoundary(next, errorBand.upperBoundaryId);
+        } else if (Object.keys(args.boundaries).length === 0) {
+          for (const [id, bound] of [
+            [errorBand.lowerBoundaryId, errorBand.lowerField],
+            [errorBand.upperBoundaryId, errorBand.upperField]
+          ]) {
+            next = findLayer(next, id) === undefined
+              ? createBoundary(
+                  next,
+                  owner.id,
+                  id,
+                  bound,
+                  defaultBoundaryAppearance(next, owner.id)
+                )
+              : interval.changed
+                ? next.rematerializeLineMark({ id })
+                : next;
+          }
+        } else {
+          next = next.editErrorBandBoundary({
+            target: owner.id,
+            ...args.boundaries
+          });
+        }
+      } else if (interval.changed) {
+        for (const id of [errorBand.lowerBoundaryId, errorBand.upperBoundaryId]) {
+          if (findLayer(next, id) !== undefined) {
+            next = next.rematerializeLineMark({ id });
+          }
+        }
+      }
+      return interval.changed
+        ? next.releaseDerivedData(interval.revision.release)
+        : next;
+    };
+    if (interval.changed || Object.hasOwn(args, "boundaries")) applyEdit(this);
+    return applyEdit(this);
   }
 );
 

package/src/actions/errorBars/edit.js

@@ -2,7 +2,9 @@ import { action } from "../../core/action.js";
 import { validateUserId } from "../../core/identifiers.js";
 import { validateKeys } from "../../core/validation.js";
 import { findLayer, resolveEligibleLayer } from "../../selectors/layers.js";
+import { planIntervalEdit } from "../data/intervalEdit.js";
 import {
+  ERROR_BAR_APPEARANCE_OPTIONS,
   ERROR_BAR_EDIT_OPTIONS,
   resolveErrorBarAppearance
 } from "./options.js";
@@ -112,19 +114,54 @@ export const editErrorBar = action(
     validateKeys(args, ERROR_BAR_EDIT_OPTIONS, "editErrorBar");
     const editable = ERROR_BAR_EDIT_OPTIONS.filter(option => option !== "target");
     if (!editable.some(option => Object.hasOwn(args, option))) {
-      throw new Error("editErrorBar requires at least one appearance change.");
+      throw new Error("editErrorBar requires at least one change.");
     }
     const owner = resolveOwner(this, args.target);
     const current = this.markConfigs[owner.id].errorBar;
-    const appearance = resolveErrorBarAppearance(args, {
+    const appearanceArgs = Object.fromEntries(
+      ERROR_BAR_APPEARANCE_OPTIONS
+        .filter(key => Object.hasOwn(args, key))
+        .map(key => [key, args[key]])
+    );
+    const appearance = resolveErrorBarAppearance(appearanceArgs, {
       defaults: current,
       operation: "editErrorBar"
     });
-    return this
-      ._withMarkConfig(owner.id, {
-        ...this.markConfigs[owner.id],
-        errorBar: { ...current, ...appearance }
-      })
-      .rematerializeErrorBar({ id: owner.id });
+    const interval = Object.hasOwn(args, "statistics")
+      ? planIntervalEdit(this, {
+          owner: owner.id,
+          data: current.data,
+          consumers: [
+            owner.id,
+            ...[current.lowerCapId, current.upperCapId]
+              .filter(id => findLayer(this, id) !== undefined)
+          ],
+          statistics: args.statistics,
+          operation: "editErrorBar"
+        })
+      : { changed: false };
+
+    const applyEdit = program => {
+      let next = program;
+      if (interval.changed) {
+        next = next.createIntervalData(interval.dataArgs);
+        for (const rebind of interval.revision.rebinds) {
+          next = next.rebindLayerData(rebind);
+        }
+      }
+      next = next._withMarkConfig(owner.id, {
+        ...next.markConfigs[owner.id],
+        errorBar: {
+          ...current,
+          ...appearance,
+          ...(interval.changed ? { data: interval.revision.id } : {})
+        }
+      }).rematerializeErrorBar({ id: owner.id });
+      return interval.changed
+        ? next.releaseDerivedData(interval.revision.release)
+        : next;
+    };
+    if (interval.changed) applyEdit(this);
+    return applyEdit(this);
   }
 );

package/src/actions/errorBars/options.js

@@ -13,9 +13,15 @@ import {
 
 export const ERROR_BAR_EDIT_OPTIONS = Object.freeze([
   "target", "caps", "capSize", "stroke", "strokeWidth",
-  "strokeDash", "opacity"
+  "strokeDash", "opacity", "statistics"
 ]);
 
+export const ERROR_BAR_APPEARANCE_OPTIONS = Object.freeze(
+  ERROR_BAR_EDIT_OPTIONS.filter(option =>
+    option !== "target" && option !== "statistics"
+  )
+);
+
 export function resolveErrorBarAppearance(args, {
   defaults,
   operation