ggaction 0.0.5 → 0.0.6

package/src/actions/encodings/density.js

@@ -15,6 +15,7 @@ import { planDerivedDataRevision } from
 import { validateOptions } from "./shared.js";
 import { normalizeDensityPlacement } from "../../grammar/density.js";
 import { scaleEditPatch } from "../scales/patch.js";
+import { removeLegendKinds } from "../guides/legends/remove.js";
 import {
   requireDensityField,
   resolveDensityCategoryScaleOptions,
@@ -29,8 +30,8 @@ const OPTIONS = Object.freeze([
   "valueScale", "densityScale", "placement"
 ]);
 const EDIT_OPTIONS = Object.freeze([
-  "target", "bandwidth", "extent", "steps", "kernel", "normalization",
-  "placement"
+  "target", "source", "field", "groupBy", "bandwidth", "extent", "steps",
+  "kernel", "normalization", "placement"
 ]);
 const EDITABLE = Object.freeze(EDIT_OPTIONS.filter(option => option !== "target"));
 
@@ -190,6 +191,43 @@ function findDensityArea(program, requested) {
   });
 }
 
+function densityCategoryField(layer, transform, groupBy) {
+  if (transform.placement === undefined) return undefined;
+  if (transform.placement.categoryField !== transform.groupBy) {
+    return transform.placement.categoryField;
+  }
+  return groupBy ?? `${layer.id}DensityCategory`;
+}
+
+function assertGroupingSelectionCompatibility(program, layer, changesGroup) {
+  if (!changesGroup) return;
+  const referenced = Object.entries(
+    program.materializationConfigs.selections ?? {}
+  ).find(([, selection]) =>
+    selection.target === layer.id &&
+    ["group", "color"].includes(selection.selector?.channel)
+  );
+  if (referenced !== undefined) {
+    throw new Error(
+      `editDensity cannot change groupBy while selection "${referenced[0]}" ` +
+      `references ${referenced[1].selector.channel}.`
+    );
+  }
+}
+
+function removeOwnedColorLegends(program, target) {
+  const kinds = Object.entries(program.guideConfigs.legend ?? {})
+    .filter(([kind, config]) =>
+      config?.target === target &&
+      (
+        config.channels?.includes("color") ||
+        ["gradient", "interval"].includes(kind)
+      )
+    )
+    .map(([kind]) => kind);
+  return kinds.length === 0 ? program : removeLegendKinds(program, kinds);
+}
+
 const editDensity = action(
   {
     op: "editDensity",
@@ -203,21 +241,55 @@ const editDensity = action(
     const layer = findDensityArea(this, args.target);
     const previous = findDataset(this, layer.data);
     const transform = previous.transform[0];
+    const source = Object.hasOwn(args, "source")
+      ? validateUserId(args.source, "Density source dataset id")
+      : previous.source;
+    const field = Object.hasOwn(args, "field")
+      ? requireDensityField(args.field, "Density field")
+      : transform.field;
+    const groupBy = Object.hasOwn(args, "groupBy")
+      ? args.groupBy === false
+        ? undefined
+        : requireDensityField(args.groupBy, "Density groupBy")
+      : transform.groupBy;
+    const changesGroup = groupBy !== transform.groupBy;
+    assertGroupingSelectionCompatibility(this, layer, changesGroup);
+    const categoryField = densityCategoryField(layer, transform, groupBy);
     const requestedPlacement = Object.hasOwn(args, "placement")
       ? normalizeDensityPlacement(args.placement, {
           densityChannel: transform.placement?.channel ?? "x",
-          groupBy: transform.groupBy,
-          categoryField: transform.groupBy ??
-            transform.placement?.categoryField ??
+          groupBy,
+          categoryField: categoryField ?? groupBy ??
             `${layer.id}DensityCategory`
         })
-      : transform.placement;
+      : transform.placement === undefined || !changesGroup
+        ? transform.placement
+        : normalizeDensityPlacement({
+            type: "category",
+            ...(transform.placement.side === undefined
+              ? {}
+              : { side: transform.placement.side }),
+            width: transform.placement.width,
+            ...(transform.placement.split === undefined
+              ? {}
+              : { split: transform.placement.split })
+          }, {
+            densityChannel: transform.placement.channel,
+            groupBy,
+            categoryField
+          });
     const colorField = layer.encoding?.color?.field;
+    const colorFollowsGroup = transform.groupBy !== undefined &&
+      colorField === transform.groupBy;
     const availableColorFields = [
-      transform.groupBy,
+      groupBy,
       requestedPlacement?.split?.field
     ].filter(Boolean);
-    if (colorField !== undefined && !availableColorFields.includes(colorField)) {
+    if (
+      colorField !== undefined &&
+      !colorFollowsGroup &&
+      !availableColorFields.includes(colorField)
+    ) {
       throw new Error(
         `editDensity placement would remove color field "${colorField}" from the density series.`
       );
@@ -234,11 +306,11 @@ const editDensity = action(
 
     const dataArgs = {
       id: revision.id,
-      source: previous.source,
-      field: transform.field,
-      ...(transform.groupBy === undefined
+      source,
+      field,
+      ...(groupBy === undefined
         ? {}
-        : { groupBy: transform.groupBy }),
+        : { groupBy }),
       bandwidth: option("bandwidth"),
       extent: option("extent"),
       steps: option("steps"),
@@ -249,78 +321,141 @@ const editDensity = action(
         ? {}
         : { placement: requestedPlacement })
     };
-    let next = requestedPlacement === undefined
-      ? this.createDensityData(dataArgs)
-      : this.createCategoricalDensityData(dataArgs);
-    next = next.rebindLayerData(revision.rebinds[0])
-      .releaseDerivedData(revision.release);
-
     const changesPlacementMode = Object.hasOwn(args, "placement") &&
       (transform.placement === undefined) !== (requestedPlacement === undefined);
-    if (changesPlacementMode) {
-      const xScaleId = layer.encoding?.x?.scale;
-      const yScaleId = layer.encoding?.y?.scale;
-      const scaleDefinitions = resolveDensityTransitionScaleDefinitions(
-        this,
-        layer,
-        transform,
-        requestedPlacement,
-        args.placement
-      );
-      next = next
-        .editSemantic({ property: `layer[${layer.id}].encoding.x`, remove: true })
-        .editSemantic({ property: `layer[${layer.id}].encoding.y`, remove: true });
-      next = next
-        .editScale(scaleEditPatch(xScaleId, scaleDefinitions.x))
-        .editScale(scaleEditPatch(yScaleId, scaleDefinitions.y));
-      const densityChannel = requestedPlacement?.channel ?? (
-        layer.encoding.x.field === transform.as[1] ? "x" : "y"
-      );
-      const definition = resolveDensityPositionDefinition({
-        layer: { densityChannel },
-        output: transform.as,
-        groupBy: transform.groupBy,
-        placement: requestedPlacement,
-        coordinate: layer.coordinate,
-        valueScale: {
-          id: requestedPlacement?.channel === "x" ? yScaleId : xScaleId,
-          ...scaleDefinitions[requestedPlacement?.channel === "x" ? "y" : "x"]
-        },
-        densityScale: requestedPlacement === undefined
-          ? {
-              id: densityChannel === "x" ? xScaleId : yScaleId,
-              ...scaleDefinitions[densityChannel]
-            }
-          : undefined,
-        placementScale: requestedPlacement === undefined
-          ? undefined
-          : {
-              id: requestedPlacement.channel === "x" ? xScaleId : yScaleId,
-              ...scaleDefinitions[requestedPlacement.channel]
-            }
-      });
-      next = applyDensityPosition(next, layer.id, definition);
-    } else if (
-      requestedPlacement !== undefined &&
-      Object.hasOwn(args.placement ?? {}, "scale")
-    ) {
-      const channel = requestedPlacement.channel;
-      const scaleId = layer.encoding[channel].scale;
-      const requestedScale = resolveDensityCategoryScaleOptions(
-        args.placement.scale,
-        scaleId
-      );
-      if (requestedScale.id !== scaleId) {
-        throw new Error("editDensity placement scale cannot change its id.");
+    const applyEdit = program => {
+      let next = requestedPlacement === undefined
+        ? program.createDensityData(dataArgs)
+        : program.createCategoricalDensityData(dataArgs);
+      next = next.rebindLayerData(revision.rebinds[0])
+        .releaseDerivedData(revision.release);
+
+      if (changesGroup) {
+        if (groupBy === undefined) {
+          if (findLayer(next, layer.id).encoding?.group !== undefined) {
+            next = next.editSemantic({
+              property: `layer[${layer.id}].encoding.group`,
+              remove: true
+            });
+          }
+          if (colorFollowsGroup) {
+            next = next.editSemantic({
+              property: `layer[${layer.id}].encoding.color`,
+              remove: true
+            });
+            next = removeOwnedColorLegends(next, layer.id);
+          }
+        } else {
+          next = next
+            .editSemantic({
+              property: `layer[${layer.id}].encoding.group.field`,
+              value: groupBy
+            })
+            .editSemantic({
+              property: `layer[${layer.id}].encoding.group.fieldType`,
+              value: "nominal"
+            });
+          if (colorFollowsGroup) {
+            next = next.editSemantic({
+              property: `layer[${layer.id}].encoding.color.field`,
+              value: groupBy
+            });
+          }
+        }
+        if (
+          requestedPlacement !== undefined &&
+          transform.placement?.categoryField !== requestedPlacement.categoryField
+        ) {
+          next = next.editSemantic({
+            property: `layer[${layer.id}].encoding.${requestedPlacement.channel}.field`,
+            value: requestedPlacement.categoryField
+          });
+        }
       }
-      next = next.editScale(scaleEditPatch(scaleId, requestedScale));
-    }
 
-    next = applyMaterializationPlan(
-      next,
-      planDensityRematerialization(next, layer.id)
-    );
-    return next;
+      if (changesPlacementMode) {
+        const xScaleId = layer.encoding?.x?.scale;
+        const yScaleId = layer.encoding?.y?.scale;
+        const scaleDefinitions = resolveDensityTransitionScaleDefinitions(
+          program,
+          layer,
+          transform,
+          requestedPlacement,
+          args.placement
+        );
+        next = next
+          .editSemantic({
+            property: `layer[${layer.id}].encoding.x`,
+            remove: true
+          })
+          .editSemantic({
+            property: `layer[${layer.id}].encoding.y`,
+            remove: true
+          });
+        next = next
+          .editScale(scaleEditPatch(xScaleId, scaleDefinitions.x))
+          .editScale(scaleEditPatch(yScaleId, scaleDefinitions.y));
+        const densityChannel = requestedPlacement?.channel ?? (
+          layer.encoding.x.field === transform.as[1] ? "x" : "y"
+        );
+        const valueChannel = requestedPlacement?.channel === "x" ? "y" : "x";
+        const definition = resolveDensityPositionDefinition({
+          layer: { densityChannel },
+          output: transform.as,
+          groupBy,
+          placement: requestedPlacement,
+          coordinate: layer.coordinate,
+          valueScale: {
+            id: valueChannel === "y" ? yScaleId : xScaleId,
+            ...scaleDefinitions[valueChannel]
+          },
+          densityScale: requestedPlacement === undefined
+            ? {
+                id: densityChannel === "x" ? xScaleId : yScaleId,
+                ...scaleDefinitions[densityChannel]
+              }
+            : undefined,
+          placementScale: requestedPlacement === undefined
+            ? undefined
+            : {
+                id: requestedPlacement.channel === "x" ? xScaleId : yScaleId,
+                ...scaleDefinitions[requestedPlacement.channel]
+              }
+        });
+        next = applyDensityPosition(next, layer.id, definition, groupBy);
+      } else if (
+        requestedPlacement !== undefined &&
+        Object.hasOwn(args.placement ?? {}, "scale")
+      ) {
+        const channel = requestedPlacement.channel;
+        const scaleId = layer.encoding[channel].scale;
+        const requestedScale = resolveDensityCategoryScaleOptions(
+          args.placement.scale,
+          scaleId
+        );
+        if (requestedScale.id !== scaleId) {
+          throw new Error("editDensity placement scale cannot change its id.");
+        }
+        next = next.editScale(scaleEditPatch(scaleId, requestedScale));
+      }
+
+      next = applyMaterializationPlan(
+        next,
+        planDensityRematerialization(next, layer.id)
+      );
+      if (
+        changesGroup &&
+        colorFollowsGroup &&
+        groupBy !== undefined &&
+        Object.values(next.guideConfigs.legend ?? {})
+          .some(config => config?.target === layer.id)
+      ) {
+        next = next.rematerializeLegend();
+      }
+      return next;
+    };
+    applyEdit(this);
+    return applyEdit(this);
   }
 );
 

package/src/actions/encodings/index.js

@@ -12,6 +12,7 @@ import { registerStrokeDashEncodingActions } from "./strokeDash.js";
 import { registerRuleAppearanceEncodingActions } from "./ruleAppearance.js";
 import { registerTextEncodingAction } from "./text.js";
 import { registerParallelEncodingAction } from "./parallel.js";
+import { registerEncodingRemovalAction } from "./remove.js";
 
 export function registerEncodingActions(ProgramClass) {
   registerPositionEncodingActions(ProgramClass);
@@ -28,4 +29,5 @@ export function registerEncodingActions(ProgramClass) {
   registerRuleAppearanceEncodingActions(ProgramClass);
   registerTextEncodingAction(ProgramClass);
   registerParallelEncodingAction(ProgramClass);
+  registerEncodingRemovalAction(ProgramClass);
 }

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;
+}