ggaction 0.0.4 → 0.0.6

package/src/actions/encodings/density/resolve.js

@@ -0,0 +1,109 @@
+import { isPlainObject } from "../../../core/immutable.js";
+import { findSemanticScale } from "../../../selectors/scales.js";
+
+export function requireDensityField(value, label) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError(`${label} must be a non-empty string.`);
+  }
+  return value;
+}
+
+export function resolveDensityScaleOptions(value, defaults, label) {
+  if (value !== undefined && !isPlainObject(value)) {
+    throw new TypeError(`${label} must be a plain object.`);
+  }
+  return { ...defaults, ...(value ?? {}) };
+}
+
+export function resolveDensityCategoryScaleOptions(value, fallbackId) {
+  const scale = resolveDensityScaleOptions(
+    value,
+    { type: "band" },
+    "Density placement scale"
+  );
+  if ((scale.type ?? "band") !== "band") {
+    throw new Error('Density category placement requires scale type "band".');
+  }
+  return {
+    ...(fallbackId === undefined ? {} : { id: fallbackId }),
+    ...scale,
+    type: "band"
+  };
+}
+
+function valueScaleForTransition(program, layer, transform) {
+  const densityChannel = transform.placement?.channel ?? (
+    layer.encoding.x.field === transform.as[1] ? "x" : "y"
+  );
+  const valueChannel = densityChannel === "x" ? "y" : "x";
+  return findSemanticScale(program, layer.encoding[valueChannel].scale);
+}
+
+export function resolveDensityTransitionScaleDefinitions(
+  program,
+  layer,
+  transform,
+  placement,
+  rawPlacement
+) {
+  const valueScale = valueScaleForTransition(program, layer, transform);
+  if (valueScale === undefined) {
+    throw new Error(`Density area "${layer.id}" requires its value scale.`);
+  }
+  const { id: _valueId, range: _valueRange, ...valueDefinition } = valueScale;
+  void _valueId;
+  void _valueRange;
+  const valueChannel = placement?.channel === "x" ? "y" : "x";
+  const companionChannel = valueChannel === "x" ? "y" : "x";
+  const companionDefinition = placement === undefined
+    ? { type: "linear", domain: "auto", range: "auto", nice: true, zero: true }
+    : resolveDensityCategoryScaleOptions(rawPlacement.scale);
+  return {
+    [valueChannel]: { ...valueDefinition, range: "auto" },
+    [companionChannel]: companionDefinition
+  };
+}
+
+export function resolveDensityPositionDefinition({
+  layer,
+  output,
+  groupBy,
+  placement,
+  coordinate,
+  valueScale,
+  densityScale,
+  placementScale
+}) {
+  if (placement === undefined) {
+    const xIsDensity = layer.densityChannel === "x";
+    return {
+      x: {
+        field: output[xIsDensity ? 1 : 0],
+        fieldType: "quantitative",
+        scale: xIsDensity ? densityScale : valueScale,
+        coordinate
+      },
+      y: {
+        field: output[xIsDensity ? 0 : 1],
+        fieldType: "quantitative",
+        scale: xIsDensity ? valueScale : densityScale,
+        coordinate
+      }
+    };
+  }
+  const category = {
+    field: placement.categoryField,
+    fieldType: "nominal",
+    scale: placementScale,
+    coordinate
+  };
+  const value = {
+    field: output[0],
+    fieldType: "quantitative",
+    scale: valueScale,
+    coordinate
+  };
+  return placement.channel === "x"
+    ? { x: category, y: value }
+    : { x: value, y: category };
+}

package/src/actions/encodings/density.js

@@ -1,6 +1,5 @@
 import { action } from "../../core/action.js";
 import { validateUserId } from "../../core/identifiers.js";
-import { isPlainObject } from "../../core/immutable.js";
 import {
   findDataset,
   findLayer,
@@ -11,15 +10,28 @@ import { applyMaterializationPlan } from
   "../../materialization/dependencies.js";
 import { planDensityRematerialization } from
   "../../materialization/density.js";
+import { planDerivedDataRevision } from
+  "../../materialization/dataProvenance.js";
 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,
+  resolveDensityPositionDefinition,
+  resolveDensityScaleOptions,
+  resolveDensityTransitionScaleDefinitions
+} from "./density/resolve.js";
 
 const OPTIONS = Object.freeze([
   "field", "target", "source", "groupBy", "bandwidth", "extent", "steps",
   "kernel", "normalization", "as", "densityChannel", "coordinate",
-  "valueScale", "densityScale"
+  "valueScale", "densityScale", "placement"
 ]);
 const EDIT_OPTIONS = Object.freeze([
-  "target", "bandwidth", "extent", "steps", "kernel", "normalization"
+  "target", "source", "field", "groupBy", "bandwidth", "extent", "steps",
+  "kernel", "normalization", "placement"
 ]);
 const EDITABLE = Object.freeze(EDIT_OPTIONS.filter(option => option !== "target"));
 
@@ -42,32 +54,35 @@ function findArea(program, requested) {
   throw new Error("encodeDensity target is ambiguous; provide target.");
 }
 
-function requireField(value, label) {
-  if (typeof value !== "string" || value.length === 0) {
-    throw new TypeError(`${label} must be a non-empty string.`);
-  }
-  return value;
-}
-
-function scaleOptions(value, defaults, label) {
-  if (value !== undefined && !isPlainObject(value)) {
-    throw new TypeError(`${label} must be a plain object.`);
+function applyDensityPosition(program, layerId, definition, groupBy) {
+  const withCoordinate = value => ({
+    target: layerId,
+    field: value.field,
+    fieldType: value.fieldType,
+    scale: value.scale,
+    ...(value.coordinate === undefined ? {} : { coordinate: value.coordinate })
+  });
+  let next = program
+    .encodeX(withCoordinate(definition.x))
+    .encodeY(withCoordinate(definition.y));
+  if (groupBy !== undefined) {
+    next = next.encodeGroup({ target: layerId, field: groupBy });
   }
-  return { ...defaults, ...(value ?? {}) };
+  return next;
 }
 
 const encodeDensity = action(
   {
     op: "encodeDensity",
-    description: "Derive and encode a baseline-oriented kernel density area."
+    description: "Derive and encode a baseline or categorical kernel-density area."
   },
   function (args = {}) {
     validateOptions(args, OPTIONS, "encodeDensity");
     const layer = findArea(this, args.target);
-    const field = requireField(args.field, "Density field");
+    const field = requireDensityField(args.field, "Density field");
     const groupBy = args.groupBy === undefined
       ? undefined
-      : requireField(args.groupBy, "Density groupBy");
+      : requireDensityField(args.groupBy, "Density groupBy");
     const source = validateUserId(
       args.source ?? layer.data,
       "Density source dataset id"
@@ -82,7 +97,8 @@ const encodeDensity = action(
         `Density area target "${layer.id}" already has positional or group encodings.`
       );
     }
-    const densityChannel = args.densityChannel ?? "y";
+    const categoryPlacement = args.placement?.type === "category";
+    const densityChannel = args.densityChannel ?? (categoryPlacement ? "x" : "y");
     if (!["x", "y"].includes(densityChannel)) {
       throw new Error(`Unsupported densityChannel "${densityChannel}".`);
     }
@@ -94,56 +110,67 @@ const encodeDensity = action(
     if (hasDataset(this, derivedId)) {
       throw new Error(`Dataset "${derivedId}" already exists.`);
     }
-    const valueScale = scaleOptions(
+    const valueScale = resolveDensityScaleOptions(
       args.valueScale,
       { nice: false, zero: false },
       "Density valueScale"
     );
-    const densityScale = scaleOptions(
-      args.densityScale,
-      { nice: true, zero: true },
-      "Density densityScale"
-    );
-    const xIsDensity = densityChannel === "x";
-    const xField = output[xIsDensity ? 1 : 0];
-    const yField = output[xIsDensity ? 0 : 1];
-    const xScale = xIsDensity ? densityScale : valueScale;
-    const yScale = xIsDensity ? valueScale : densityScale;
+    const placement = args.placement === undefined
+      ? undefined
+      : normalizeDensityPlacement(args.placement, {
+          densityChannel,
+          groupBy,
+          categoryField: groupBy ?? `${layer.id}DensityCategory`
+        });
+    if (placement !== undefined && args.densityScale !== undefined) {
+      throw new Error(
+        "Density category placement cannot be combined with densityScale."
+      );
+    }
+    const densityScale = placement === undefined
+      ? resolveDensityScaleOptions(
+          args.densityScale,
+          { nice: true, zero: true },
+          "Density densityScale"
+        )
+      : undefined;
+    const placementScale = placement === undefined
+      ? undefined
+      : resolveDensityCategoryScaleOptions(args.placement.scale);
 
-    let next = this
-      .createDensityData({
-        id: derivedId,
-        source,
-        field,
-        ...(groupBy === undefined ? {} : { groupBy }),
-        ...(args.bandwidth === undefined ? {} : { bandwidth: args.bandwidth }),
-        ...(args.extent === undefined ? {} : { extent: args.extent }),
-        ...(args.steps === undefined ? {} : { steps: args.steps }),
-        ...(args.kernel === undefined ? {} : { kernel: args.kernel }),
-        ...(args.normalization === undefined
-          ? {}
-          : { normalization: args.normalization }),
-        ...(args.as === undefined ? {} : { as: args.as })
-      })
+    const dataArgs = {
+      id: derivedId,
+      source,
+      field,
+      ...(groupBy === undefined ? {} : { groupBy }),
+      ...(args.bandwidth === undefined ? {} : { bandwidth: args.bandwidth }),
+      ...(args.extent === undefined ? {} : { extent: args.extent }),
+      ...(args.steps === undefined ? {} : { steps: args.steps }),
+      ...(args.kernel === undefined ? {} : { kernel: args.kernel }),
+      ...(args.normalization === undefined
+        ? {}
+        : { normalization: args.normalization }),
+      ...(args.as === undefined ? {} : { as: args.as }),
+      ...(placement === undefined ? {} : { placement })
+    };
+    let next = placement === undefined
+      ? this.createDensityData(dataArgs)
+      : this.createCategoricalDensityData(dataArgs);
+    next = next
       .editSemantic({
         property: `layer[${layer.id}].data`,
         value: derivedId
-      })
-      .encodeX({
-        target: layer.id,
-        field: xField,
-        ...(args.coordinate === undefined ? {} : { coordinate: args.coordinate }),
-        scale: xScale
-      })
-      .encodeY({
-        target: layer.id,
-        field: yField,
-        ...(args.coordinate === undefined ? {} : { coordinate: args.coordinate }),
-        scale: yScale
       });
-    if (groupBy !== undefined) {
-      next = next.encodeGroup({ target: layer.id, field: groupBy });
-    }
+    next = applyDensityPosition(next, layer.id, resolveDensityPositionDefinition({
+      layer: { densityChannel },
+      output,
+      groupBy,
+      placement,
+      coordinate: args.coordinate,
+      valueScale,
+      densityScale,
+      placementScale
+    }), groupBy);
     return next.rematerializeAreaMark({ id: layer.id });
   }
 );
@@ -164,12 +191,41 @@ function findDensityArea(program, requested) {
   });
 }
 
-function nextDensityRevisionId(program, target) {
-  let revision = 1;
-  while (hasDataset(program, `${target}DensityDataRevision${revision}`)) {
-    revision += 1;
+function densityCategoryField(layer, transform, groupBy) {
+  if (transform.placement === undefined) return undefined;
+  if (transform.placement.categoryField !== transform.groupBy) {
+    return transform.placement.categoryField;
   }
-  return `${target}DensityDataRevision${revision}`;
+  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(
@@ -185,37 +241,221 @@ const editDensity = action(
     const layer = findDensityArea(this, args.target);
     const previous = findDataset(this, layer.data);
     const transform = previous.transform[0];
-    const revisionId = nextDensityRevisionId(this, layer.id);
+    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,
+          categoryField: categoryField ?? groupBy ??
+            `${layer.id}DensityCategory`
+        })
+      : 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 = [
+      groupBy,
+      requestedPlacement?.split?.field
+    ].filter(Boolean);
+    if (
+      colorField !== undefined &&
+      !colorFollowsGroup &&
+      !availableColorFields.includes(colorField)
+    ) {
+      throw new Error(
+        `editDensity placement would remove color field "${colorField}" from the density series.`
+      );
+    }
+    const revision = planDerivedDataRevision(this, {
+      owner: layer.id,
+      role: "DensityData",
+      previous: previous.id,
+      consumers: [layer.id]
+    });
     const option = property => Object.hasOwn(args, property)
       ? args[property]
       : transform[property];
 
-    let next = this
-      .createDensityData({
-        id: revisionId,
-        source: previous.source,
-        field: transform.field,
-        ...(transform.groupBy === undefined
-          ? {}
-          : { groupBy: transform.groupBy }),
-        bandwidth: option("bandwidth"),
-        extent: option("extent"),
-        steps: option("steps"),
-        kernel: option("kernel") ?? "gaussian",
-        normalization: option("normalization") ?? "unit",
-        as: transform.as
-      })
-      .editSemantic({
-        property: `layer[${layer.id}].data`,
-        value: revisionId
-      })
-      .releaseDerivedData({ id: previous.id });
+    const dataArgs = {
+      id: revision.id,
+      source,
+      field,
+      ...(groupBy === undefined
+        ? {}
+        : { groupBy }),
+      bandwidth: option("bandwidth"),
+      extent: option("extent"),
+      steps: option("steps"),
+      kernel: option("kernel") ?? "gaussian",
+      normalization: option("normalization") ?? "unit",
+      as: transform.as,
+      ...(requestedPlacement === undefined
+        ? {}
+        : { placement: requestedPlacement })
+    };
+    const changesPlacementMode = Object.hasOwn(args, "placement") &&
+      (transform.placement === undefined) !== (requestedPlacement === undefined);
+    const applyEdit = program => {
+      let next = requestedPlacement === undefined
+        ? program.createDensityData(dataArgs)
+        : program.createCategoricalDensityData(dataArgs);
+      next = next.rebindLayerData(revision.rebinds[0])
+        .releaseDerivedData(revision.release);
 
-    next = applyMaterializationPlan(
-      next,
-      planDensityRematerialization(next, layer.id)
-    );
-    return next;
+      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
+          });
+        }
+      }
+
+      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);
   }
 );