ggaction 0.0.4 → 0.0.6

package/src/actions/boxPlots/edit.js

@@ -4,19 +4,31 @@ import { validateUserId } from "../../core/identifiers.js";
 import { validateKeys } from "../../core/validation.js";
 import { BOX_FIELDS, deriveBoxData, normalizeBoxTransform } from
   "../../grammar/boxPlot.js";
-import { hasDataset } from "../../selectors/index.js";
+import { planDerivedDataRevision } from
+  "../../materialization/dataProvenance.js";
 import { findDataset } from "../../selectors/datasets.js";
 import { findLayer } from "../../selectors/layers.js";
+import {
+  assertDistributionScaleHandoff,
+  clearCartesianPositions,
+  rebindDistributionGuides,
+  resolveDistributionScalePlan,
+  setCartesianPosition,
+  setCartesianRange
+} from "../distributions/revision.js";
 import {
   resolveBoxAppearance,
   resolveBoxMedianAppearance,
   resolveBoxOutlierAppearance,
+  resolveBoxPosition,
   resolveBoxWhisker,
   resolveBoxWidth
 } from "./options.js";
+import { resolveBoxOrientation } from "./resolve.js";
 
 const OPTIONS = Object.freeze([
-  "target", "whisker", "width", "outliers", "box", "median", "outlier"
+  "target", "data", "x", "y", "whisker", "width", "outliers", "box",
+  "median", "outlier"
 ]);
 
 function resolveBoxOwner(program, requested) {
@@ -61,23 +73,288 @@ function resolveEditedWhisker(current, value) {
   return resolveBoxWhisker(candidate, "editBoxPlot");
 }
 
-function nextRevisionId(program, ownerId, kind) {
-  let revision = 1;
-  while (hasDataset(program, `${ownerId}${kind}Revision${revision}`)) {
-    revision += 1;
-  }
-  return `${ownerId}${kind}Revision${revision}`;
-}
-
 function removeOwnedMark(program, id) {
-  return program
+  const selections = 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 || selections.includes(config.selection)) {
+      next = next._withoutMaterializationConfig(["highlights", highlight]);
+    }
+  }
+  for (const selection of selections) {
+    next = next._withoutMaterializationConfig(["selections", selection]);
+  }
+  return next
     .editSemantic({ property: `layer[${id}]`, remove: true })
     .editGraphics({ target: id, remove: true })
-    ._withoutMaterializationConfig(["marks", id]);
+    ._withoutMaterializationConfig(["marks", id])
+    ._withContext({
+      ...(program.context.currentMark === id ? { currentMark: undefined } : {}),
+      ...(selections.includes(program.context.currentSelection)
+        ? { currentSelection: undefined }
+        : {})
+    });
+}
+
+function currentBoxPositions(owner, current) {
+  const categoryChannel = current.orientation === "vertical" ? "x" : "y";
+  const measureChannel = current.orientation === "vertical" ? "y" : "x";
+  const categoryEncoding = owner.encoding[categoryChannel];
+  const measureEncoding = owner.encoding[measureChannel];
+  return {
+    x: current.orientation === "vertical"
+      ? {
+          field: current.category,
+          fieldType: categoryEncoding.fieldType,
+          scale: categoryEncoding.scale
+        }
+      : {
+          field: current.measure,
+          fieldType: "quantitative",
+          scale: measureEncoding.scale
+        },
+    y: current.orientation === "vertical"
+      ? {
+          field: current.measure,
+          fieldType: "quantitative",
+          scale: measureEncoding.scale
+        }
+      : {
+          field: current.category,
+          fieldType: categoryEncoding.fieldType,
+          scale: categoryEncoding.scale
+        },
+    categoryScale: categoryEncoding.scale,
+    measureScale: measureEncoding.scale
+  };
+}
+
+function requirePositionField(position, label) {
+  if (typeof position.field !== "string" || position.field.length === 0) {
+    throw new TypeError(`${label} field must be a non-empty string.`);
+  }
+  return { fieldType: position.fieldType ?? "quantitative", ...position };
+}
+
+function roleCandidate(program, owner, current, args) {
+  const previous = currentBoxPositions(owner, current);
+  const x = requirePositionField(
+    Object.hasOwn(args, "x")
+      ? resolveBoxPosition(args.x, "x", "editBoxPlot")
+      : previous.x,
+    "editBoxPlot x"
+  );
+  const y = requirePositionField(
+    Object.hasOwn(args, "y")
+      ? resolveBoxPosition(args.y, "y", "editBoxPlot")
+      : previous.y,
+    "editBoxPlot y"
+  );
+  const orientation = resolveBoxOrientation(x, y);
+  if (orientation === undefined) {
+    throw new Error(
+      "editBoxPlot requires one categorical axis and one quantitative axis."
+    );
+  }
+  const xRoleScale = orientation === "vertical"
+    ? previous.categoryScale
+    : previous.measureScale;
+  const yRoleScale = orientation === "vertical"
+    ? previous.measureScale
+    : previous.categoryScale;
+  const xScale = resolveDistributionScalePlan(program, {
+    channel: "x",
+    fieldType: x.fieldType,
+    requested: x.scale,
+    fallback: xRoleScale,
+    defaults: ["ordinal", "nominal"].includes(x.fieldType)
+      ? { discreteType: "band" }
+      : { nice: true, zero: false }
+  });
+  const yScale = resolveDistributionScalePlan(program, {
+    channel: "y",
+    fieldType: y.fieldType,
+    requested: y.scale,
+    fallback: yRoleScale,
+    defaults: ["ordinal", "nominal"].includes(y.fieldType)
+      ? { discreteType: "band" }
+      : { nice: true, zero: false }
+  });
+  return {
+    source: Object.hasOwn(args, "data")
+      ? validateUserId(args.data, "Box-plot data id")
+      : current.source,
+    orientation,
+    x: { ...x, scale: xScale.id },
+    y: { ...y, scale: yScale.id },
+    xScale,
+    yScale,
+    category: orientation === "vertical" ? x.field : y.field,
+    categoryType: orientation === "vertical" ? x.fieldType : y.fieldType,
+    measure: orientation === "vertical" ? y.field : x.field,
+    previous
+  };
 }
 
-function rebindRuleData(program, id, data) {
-  return program.editSemantic({ property: `layer[${id}].data`, value: data });
+function sameRoleCandidate(current, candidate) {
+  return candidate.source === current.source &&
+    candidate.orientation === current.orientation &&
+    candidate.category === current.category &&
+    candidate.measure === current.measure &&
+    candidate.x.fieldType === candidate.previous.x.fieldType &&
+    candidate.y.fieldType === candidate.previous.y.fieldType &&
+    candidate.xScale.id === candidate.previous.x.scale &&
+    candidate.yScale.id === candidate.previous.y.scale &&
+    candidate.xScale.edit === undefined &&
+    candidate.yScale.edit === undefined;
+}
+
+function updateBoxPositions(program, owner, current, candidate, {
+  hasOutliers
+}) {
+  const whiskerConfig = program.markConfigs[current.whiskerId];
+  const capIds = [
+    whiskerConfig.errorBar.lowerCapId,
+    whiskerConfig.errorBar.upperCapId
+  ].filter(Boolean);
+  const owned = [owner.id, current.whiskerId, ...capIds, current.medianId,
+    ...(findLayer(program, current.outlierId) ? [current.outlierId] : [])];
+  assertDistributionScaleHandoff(program, {
+    owned,
+    oldXScale: candidate.previous.x.scale,
+    oldYScale: candidate.previous.y.scale,
+    newXScale: candidate.xScale.id,
+    newYScale: candidate.yScale.id
+  });
+  let next = program;
+  for (const id of owned) next = clearCartesianPositions(next, id);
+  for (const scale of [candidate.xScale, candidate.yScale]) {
+    if (scale.create) next = next.createScale(scale.definition);
+  }
+  const category = candidate.orientation === "vertical" ? candidate.x : candidate.y;
+  const measure = candidate.orientation === "vertical" ? candidate.y : candidate.x;
+  const categoryChannel = candidate.orientation === "vertical" ? "x" : "y";
+  const measureChannel = candidate.orientation === "vertical" ? "y" : "x";
+  next = setCartesianPosition(next, owner.id, categoryChannel, {
+    field: category.field,
+    fieldType: category.fieldType,
+    scale: category.scale
+  });
+  next = setCartesianRange(
+    next,
+    owner.id,
+    measureChannel,
+    BOX_FIELDS.q1,
+    BOX_FIELDS.q3,
+    measure.scale,
+    candidate.measure
+  );
+  next = next._withMarkConfig(current.whiskerId, {
+    ...whiskerConfig,
+    errorBar: {
+      ...whiskerConfig.errorBar,
+      data: findLayer(next, current.whiskerId).data,
+      orientation: candidate.orientation,
+      positionField: candidate.category,
+      positionFieldType: candidate.categoryType,
+      coordinate: owner.coordinate,
+      positionScale: category.scale,
+      intervalScale: measure.scale
+    }
+  });
+  next = setCartesianPosition(next, current.whiskerId, categoryChannel, {
+    field: category.field,
+    fieldType: category.fieldType,
+    scale: category.scale
+  });
+  next = setCartesianRange(
+    next,
+    current.whiskerId,
+    measureChannel,
+    BOX_FIELDS.lowerWhisker,
+    BOX_FIELDS.upperWhisker,
+    measure.scale,
+    candidate.measure
+  );
+  for (const [index, capId] of capIds.entries()) {
+    const field = index === 0 ? BOX_FIELDS.lowerWhisker : BOX_FIELDS.upperWhisker;
+    next = setCartesianPosition(next, capId, categoryChannel, {
+      field: category.field,
+      fieldType: category.fieldType,
+      scale: category.scale
+    });
+    next = setCartesianPosition(next, capId, measureChannel, {
+      field,
+      fieldType: "quantitative",
+      scale: measure.scale
+    })._withMarkConfig(capId, {
+      ...next.markConfigs[capId],
+      fixedSpan: {
+        ...next.markConfigs[capId].fixedSpan,
+        orientation: candidate.orientation === "vertical"
+          ? "horizontal"
+          : "vertical"
+      }
+    });
+  }
+  next = setCartesianPosition(next, current.medianId, categoryChannel, {
+    field: category.field,
+    fieldType: category.fieldType,
+    scale: category.scale
+  });
+  next = setCartesianPosition(next, current.medianId, measureChannel, {
+    field: BOX_FIELDS.median,
+    fieldType: "quantitative",
+    scale: measure.scale
+  });
+  if (hasOutliers && findLayer(next, current.outlierId) !== undefined) {
+    next = setCartesianPosition(next, current.outlierId, categoryChannel, {
+      field: category.field,
+      fieldType: category.fieldType,
+      scale: category.scale
+    });
+    next = setCartesianPosition(next, current.outlierId, measureChannel, {
+      field: candidate.measure,
+      fieldType: "quantitative",
+      scale: measure.scale
+    });
+  }
+  for (const id of new Set([candidate.xScale.id, candidate.yScale.id])) {
+    next = next.rematerializeScale({ id, marks: false, guides: false });
+  }
+  next = rebindDistributionGuides(next, {
+    oldXScale: candidate.previous.x.scale,
+    oldYScale: candidate.previous.y.scale,
+    newXScale: candidate.xScale.id,
+    newYScale: candidate.yScale.id,
+    oldXTitle: candidate.previous.x.field,
+    oldYTitle: candidate.previous.y.field,
+    newXTitle: candidate.x.field,
+    newYTitle: candidate.y.field,
+    oldMeasureChannel: current.orientation === "vertical" ? "y" : "x",
+    newMeasureChannel: candidate.orientation === "vertical" ? "y" : "x"
+  });
+  for (const scale of [candidate.xScale, candidate.yScale]) {
+    if (scale.edit !== undefined) next = next.editScale(scale.edit);
+  }
+  next = next.rematerializeBarMark({ id: owner.id })
+    .rematerializeErrorBar({ id: current.whiskerId });
+  for (const capId of capIds) {
+    next = next.materializeRuleSpan({
+      id: capId,
+      orientation: candidate.orientation === "vertical" ? "horizontal" : "vertical",
+      size: whiskerConfig.errorBar.capSize
+    });
+  }
+  next = next.rematerializeRuleMark({ id: current.medianId });
+  if (hasOutliers && findLayer(next, current.outlierId) !== undefined) {
+    next = next.rematerializePointMark({ id: current.outlierId });
+  }
+  return next;
 }
 
 export const editBoxPlot = action(
@@ -127,6 +404,170 @@ export const editBoxPlot = action(
       );
     }
 
+    const candidate = roleCandidate(this, owner, current, args);
+    const sourceDataset = findDataset(this, candidate.source);
+    if (sourceDataset === undefined) {
+      throw new Error(`Unknown box-plot data "${candidate.source}".`);
+    }
+    const roleRequested = ["data", "x", "y"].some(
+      key => Object.hasOwn(args, key)
+    );
+    const changesRoles = !sameRoleCandidate(current, candidate);
+    if (changesRoles) {
+      const derived = deriveBoxData(
+        sourceDataset.values,
+        normalizeBoxTransform({
+          type: "boxSummary",
+          category: candidate.category,
+          field: candidate.measure,
+          whisker: whisker.type,
+          ...(whisker.factor === undefined ? {} : { factor: whisker.factor })
+        })
+      );
+      const hasOutliers = outliers && whisker.type === "tukey" &&
+        derived.outliers.length > 0;
+      const whiskerConfig = this.markConfigs[current.whiskerId];
+      const capIds = [
+        whiskerConfig.errorBar.lowerCapId,
+        whiskerConfig.errorBar.upperCapId
+      ].filter(Boolean);
+      const summaryRevision = planDerivedDataRevision(this, {
+        owner: owner.id,
+        role: "SummaryData",
+        previous: current.summaryId,
+        consumers: [owner.id, current.whiskerId, ...capIds, current.medianId]
+      });
+      const hadOutlierLayer = findLayer(this, current.outlierId) !== undefined;
+      const outlierRevision = hasOutliers
+        ? planDerivedDataRevision(this, {
+            owner: owner.id,
+            role: "OutlierData",
+            ...(current.outlierDataId === undefined
+              ? {}
+              : { previous: current.outlierDataId }),
+            consumers: hadOutlierLayer ? [current.outlierId] : []
+          })
+        : undefined;
+      const applyEdit = program => {
+        let next = program.createBoxSummaryData({
+          id: summaryRevision.id,
+          source: candidate.source,
+          category: candidate.category,
+          field: candidate.measure,
+          whisker: whisker.type,
+          ...(whisker.factor === undefined ? {} : { factor: whisker.factor })
+        });
+        if (outlierRevision !== undefined) {
+          next = next.createBoxOutlierData({
+            id: outlierRevision.id,
+            source: candidate.source,
+            category: candidate.category,
+            field: candidate.measure,
+            whisker: whisker.type,
+            factor: whisker.factor
+          });
+          for (const rebind of outlierRevision.rebinds) {
+            next = next.rebindLayerData(rebind);
+          }
+        }
+        for (const rebind of summaryRevision.rebinds) {
+          next = next.rebindLayerData(rebind);
+        }
+        next = next._withMarkConfig(current.whiskerId, {
+          ...next.markConfigs[current.whiskerId],
+          errorBar: {
+            ...next.markConfigs[current.whiskerId].errorBar,
+            data: summaryRevision.id
+          }
+        });
+        if (hadOutlierLayer && !hasOutliers) {
+          next = removeOwnedMark(next, current.outlierId);
+        }
+        next = next._withMarkConfig(owner.id, {
+          ...next.markConfigs[owner.id],
+          boxPlot: {
+            ...current,
+            whisker,
+            width,
+            outliers,
+            box,
+            median,
+            outlier,
+            source: candidate.source,
+            orientation: candidate.orientation,
+            category: candidate.category,
+            measure: candidate.measure,
+            summaryId: summaryRevision.id,
+            outlierDataId: outlierRevision?.id
+          },
+          barWidth: { band: width },
+          fill: box.fill,
+          opacity: box.opacity,
+          stroke: box.stroke,
+          strokeWidth: box.strokeWidth
+        });
+        next = updateBoxPositions(next, owner, current, candidate, {
+          outlierDataId: outlierRevision?.id,
+          hasOutliers
+        });
+        if (!hadOutlierLayer && hasOutliers) {
+          const category = candidate.orientation === "vertical"
+            ? candidate.x
+            : candidate.y;
+          const measure = candidate.orientation === "vertical"
+            ? candidate.y
+            : candidate.x;
+          next = next.createBoxOutliers({
+            id: current.outlierId,
+            data: outlierRevision.id,
+            category: candidate.category,
+            categoryType: candidate.categoryType,
+            measure: candidate.measure,
+            orientation: candidate.orientation,
+            coordinate: owner.coordinate,
+            categoryScale: category.scale,
+            measureScale: measure.scale,
+            shape: outlier.shape,
+            radius: outlier.radius,
+            opacity: outlier.opacity
+          });
+        }
+        next = next
+          .encodeStroke({ target: current.medianId, value: median.stroke })
+          .encodeStrokeWidth({
+            target: current.medianId,
+            value: median.strokeWidth
+          });
+        if (findLayer(next, current.outlierId) !== undefined) {
+          next = next
+            .editPointMark({
+              target: current.outlierId,
+              shape: outlier.shape,
+              opacity: outlier.opacity
+            })
+            .encodeRadius({ target: current.outlierId, value: outlier.radius });
+        }
+        next = next.releaseDerivedData(summaryRevision.release);
+        if (current.outlierDataId !== undefined) {
+          next = next.releaseDerivedData({ id: current.outlierDataId });
+        }
+        return next._withContext({
+          currentMark: owner.id,
+          currentData: candidate.source
+        });
+      };
+      applyEdit(this);
+      return applyEdit(this);
+    }
+    if (roleRequested && !OPTIONS.slice(4).some(
+      key => Object.hasOwn(args, key)
+    )) {
+      return this._withContext({
+        currentMark: owner.id,
+        currentData: current.source
+      });
+    }
+
     const revisesData = JSON.stringify(whisker) !== JSON.stringify(current.whisker) ||
       outliers !== current.outliers;
     const changesBox = Object.hasOwn(args, "box") ||
@@ -156,7 +597,18 @@ export const editBoxPlot = action(
       derived.outliers.length > 0;
 
     if (revisesData) {
-      summaryId = nextRevisionId(this, owner.id, "SummaryData");
+      const whiskerConfig = next.markConfigs[current.whiskerId];
+      const capIds = [
+        whiskerConfig.errorBar.lowerCapId,
+        whiskerConfig.errorBar.upperCapId
+      ].filter(id => id !== undefined);
+      const summaryRevision = planDerivedDataRevision(this, {
+        owner: owner.id,
+        role: "SummaryData",
+        previous: current.summaryId,
+        consumers: [owner.id, current.whiskerId, ...capIds, current.medianId]
+      });
+      summaryId = summaryRevision.id;
       next = next.createBoxSummaryData({
         id: summaryId,
         source: current.source,
@@ -166,7 +618,16 @@ export const editBoxPlot = action(
         ...(whisker.factor === undefined ? {} : { factor: whisker.factor })
       });
       if (hasOutliers) {
-        outlierDataId = nextRevisionId(this, owner.id, "OutlierData");
+        const hadOutlierLayer = findLayer(next, current.outlierId) !== undefined;
+        const outlierRevision = planDerivedDataRevision(this, {
+          owner: owner.id,
+          role: "OutlierData",
+          ...(current.outlierDataId === undefined
+            ? {}
+            : { previous: current.outlierDataId }),
+          consumers: hadOutlierLayer ? [current.outlierId] : []
+        });
+        outlierDataId = outlierRevision.id;
         next = next.createBoxOutlierData({
           id: outlierDataId,
           source: current.source,
@@ -175,37 +636,24 @@ export const editBoxPlot = action(
           whisker: whisker.type,
           factor: whisker.factor
         });
+        for (const rebind of outlierRevision.rebinds) {
+          next = next.rebindLayerData(rebind);
+        }
       } else {
         outlierDataId = undefined;
       }
 
-      next = next.editSemantic({
-        property: `layer[${owner.id}].data`,
-        value: summaryId
-      });
-      const whiskerConfig = next.markConfigs[current.whiskerId];
-      const capIds = [
-        whiskerConfig.errorBar.lowerCapId,
-        whiskerConfig.errorBar.upperCapId
-      ].filter(id => id !== undefined);
-      next = rebindRuleData(next, current.whiskerId, summaryId)
-        ._withMarkConfig(current.whiskerId, {
+      for (const rebind of summaryRevision.rebinds) {
+        next = next.rebindLayerData(rebind);
+      }
+      next = next._withMarkConfig(current.whiskerId, {
           ...whiskerConfig,
           errorBar: { ...whiskerConfig.errorBar, data: summaryId }
         });
-      for (const capId of capIds) {
-        next = rebindRuleData(next, capId, summaryId);
-      }
-      next = rebindRuleData(next, current.medianId, summaryId);
 
       const hadOutlierLayer = findLayer(next, current.outlierId) !== undefined;
       if (hadOutlierLayer && !hasOutliers) {
         next = removeOwnedMark(next, current.outlierId);
-      } else if (hadOutlierLayer && hasOutliers) {
-        next = next.editSemantic({
-          property: `layer[${current.outlierId}].data`,
-          value: outlierDataId
-        });
       } else if (!hadOutlierLayer && hasOutliers) {
         next = next.createBoxOutliers({
           id: current.outlierId,

package/src/actions/boxPlots/materialize.js

@@ -189,6 +189,9 @@ export const materializeBoxPlot = action(
         outlierDataId: hasOutliers ? outlierDataId : undefined
       }
     });
+    if (config.guides !== false) {
+      next = next.createGuides(config.guides);
+    }
     return next._withContext({ currentMark: ownerId, currentData: source });
   }
 );

package/src/actions/boxPlots/options.js

@@ -8,10 +8,11 @@ import {
 } from "../../core/validation.js";
 import { validatePointShape } from "../../grammar/pointShapes.js";
 import { DEFAULT_COLORS } from "../../theme/defaults.js";
+import { normalizeGuides } from "../charts/shared.js";
 
 export const BOX_PLOT_OPTIONS = Object.freeze([
   "id", "target", "data", "x", "y", "coordinate", "whisker",
-  "width", "outliers", "box", "median", "outlier"
+  "width", "outliers", "box", "median", "outlier", "guides"
 ]);
 
 const DEFAULT_BOX = Object.freeze({
@@ -36,12 +37,12 @@ function plainOptions(value, keys, label, operation = "createBoxPlot") {
   return value;
 }
 
-export function resolveBoxPosition(value, label) {
+export function resolveBoxPosition(value, label, operation = "createBoxPlot") {
   if (value === undefined) return undefined;
   if (!isPlainObject(value)) {
-    throw new TypeError(`createBoxPlot ${label} must be a plain object.`);
+    throw new TypeError(`${operation} ${label} must be a plain object.`);
   }
-  validateKeys(value, ["field", "fieldType", "scale"], `createBoxPlot ${label}`);
+  validateKeys(value, ["field", "fieldType", "scale"], `${operation} ${label}`);
   return value;
 }
 
@@ -52,6 +53,12 @@ export function boxEncodingArgs(value) {
   };
 }
 
+export function resolveBoxGuides(value) {
+  return value === undefined
+    ? false
+    : normalizeGuides(value, "createBoxPlot");
+}
+
 export function resolveBoxWhisker(value, operation = "createBoxPlot") {
   if (value === undefined) return Object.freeze({ type: "tukey", factor: 1.5 });
   if (!isPlainObject(value)) {

package/src/actions/boxPlots/resolve.js

@@ -11,7 +11,9 @@ export function resolveBoxOrientation(x, y) {
   return undefined;
 }
 
-export function resolveBoxSourceLayer(program, target) {
+export function resolveBoxSourceLayer(program, target, {
+  requiresInference = true
+} = {}) {
   if (target !== undefined) {
     const layer = findLayer(program, validateUserId(target, "Box source layer id"));
     if (layer === undefined) throw new Error(`Unknown box source layer "${target}".`);
@@ -24,7 +26,13 @@ export function resolveBoxSourceLayer(program, target) {
   const eligible = program.semanticSpec.layers.filter(
     layer => layer.encoding?.x !== undefined && layer.encoding?.y !== undefined
   );
-  return eligible.length === 1 ? eligible[0] : undefined;
+  if (eligible.length === 1) return eligible[0];
+  if (eligible.length > 1 && requiresInference) {
+    throw new Error(
+      "createBoxPlot target is ambiguous; provide target or explicit x and y."
+    );
+  }
+  return undefined;
 }
 
 export function resolveBoxPlotId(program, requested) {