ggaction 0.0.11 → 0.0.13

package/src/actions/titles/actions.js

@@ -1,3 +1,4 @@
+import { withGuideLayoutValidation } from "../../materialization/guides/layout.js";
 import { action } from "../../core/action.js";
 import { noOptions } from "../../core/validation.js";
 import {
@@ -92,7 +93,7 @@ function titleTextAction(kind, create) {
   return action({
     op,
     description: `${create ? "Create" : "Rematerialize"} chart ${kind} text.`
-  }, function (args = {}) {
+  }, withGuideLayoutValidation(function (args = {}) {
     noOptions(args, op);
     const config = requireTitleConfig(this);
     if (create && this.graphicSpec.objects[id] !== undefined) {
@@ -111,7 +112,7 @@ function titleTextAction(kind, create) {
       ...(component.lines.length > 1 ? { length: component.lines.length } : {}),
       ...resolveCanvasGraphicPlacement(this)
     })[`edit${suffix}`]();
-  });
+  }));
 }
 
 export const editTitleText = titleTextAction("title", false);
@@ -121,7 +122,7 @@ export const createSubtitleText = titleTextAction("subtitle", true);
 
 export const rematerializeTitle = action(
   { op: "rematerializeTitle", description: "Rematerialize chart title graphics." },
-  function (args = {}) {
+  withGuideLayoutValidation(function (args = {}) {
     noOptions(args, "rematerializeTitle");
     requireTitleConfig(this);
     if (this.graphicSpec.objects.chartTitle?.type !== "text") {
@@ -138,7 +139,7 @@ export const rematerializeTitle = action(
       next = next.editGraphics({ target: "chartSubtitle", remove: true });
     }
     return next;
-  }
+  })
 );
 
 export const createTitle = action(
@@ -147,7 +148,7 @@ export const createTitle = action(
     description: "Create a chart title and optional subtitle.",
     scope: "any"
   },
-  function (args = {}) {
+  withGuideLayoutValidation(function (args = {}) {
     assertTitleScope(this, "createTitle");
     const options = normalizeTitleOptions(args);
     if (Object.keys(this.semanticSpec.title).length > 0) {
@@ -172,7 +173,7 @@ export const createTitle = action(
     next = next.createTitleText();
     if (subtitle !== undefined) next = next.createSubtitleText();
     return next;
-  }
+  })
 );
 
 export const editTitle = action(
@@ -181,7 +182,7 @@ export const editTitle = action(
     description: "Edit one stable chart title resource.",
     scope: "any"
   },
-  function (args = {}) {
+  withGuideLayoutValidation(function (args = {}) {
     assertTitleScope(this, "editTitle");
     if (this.semanticSpec.title.text === undefined) {
       throw new Error("editTitle requires an existing chart title.");
@@ -210,7 +211,7 @@ export const editTitle = action(
     }
     resolveTitleLayout(next, normalized.config);
     return next.rematerializeTitle();
-  }
+  })
 );
 
 export const removeTitle = action(
@@ -219,7 +220,7 @@ export const removeTitle = action(
     description: "Remove the complete chart title resource.",
     scope: "any"
   },
-  function (args = {}) {
+  withGuideLayoutValidation(function (args = {}) {
     assertTitleScope(this, "removeTitle");
     noOptions(args, "removeTitle");
     if (
@@ -246,5 +247,5 @@ export const removeTitle = action(
     return next.compositionSpec?.type === "facet"
       ? next.materializeComposition()
       : next;
-  }
+  })
 );

package/src/actions/titles/resolve.js

@@ -7,12 +7,10 @@ import {
   validatePositiveFinite
 } from "../../core/validation.js";
 import { resolveGraphicBounds } from "../../layout/canvas.js";
-import { resolveConcreteGraphicBounds } from "../../grammar/schemas/graphicBounds.js";
 import {
   alignedTextAnchor,
   alignedTitleAnchor,
   buildTitleReadingBlock,
-  layoutBoundsIntersect,
   resolveTitleComponentBounds,
   unionTitleBounds
 } from "../../layout/title.js";
@@ -176,35 +174,7 @@ export function requireTitleConfig(program) {
   return program.titleConfig;
 }
 
-function reservedGraphicIds(program, position) {
-  const ids = [];
-  const axisChannel = ["top", "bottom"].includes(position) ? "x" : "y";
-  const axis = program.guideConfigs.axis?.[axisChannel];
-  if (axis && Object.values(axis).some(config => config?.position === position)) {
-    const prefix = axisChannel === "x" ? "xAxis" : "yAxis";
-    ids.push(`${prefix}Line`, `${prefix}Ticks`, `${prefix}Labels`, `${prefix}Title`);
-  }
-  const prefixes = {
-    series: "seriesLegend",
-    color: "colorLegend",
-    gradient: "colorGradient",
-    opacity: "opacityLegend"
-  };
-  for (const [kind, config] of Object.entries(program.guideConfigs.legend ?? {})) {
-    if (config?.position !== position || prefixes[kind] === undefined) continue;
-    ids.push(...Object.keys(program.graphicSpec.objects).filter(
-      id => id.startsWith(prefixes[kind])
-    ));
-    if (kind === "series" && program.guideConfigs.legend?.size !== undefined) {
-      ids.push(...Object.keys(program.graphicSpec.objects).filter(
-        id => id.startsWith("sizeLegend")
-      ));
-    }
-  }
-  return [...new Set(ids)];
-}
-
-function validateLayout(program, position, titleBounds, plot, canvas) {
+function validateLayout(position, titleBounds, plot, canvas) {
   if (
     titleBounds.left < 0 || titleBounds.top < 0 ||
     titleBounds.right > canvas.width || titleBounds.bottom > canvas.height
@@ -220,14 +190,6 @@ function validateLayout(program, position, titleBounds, plot, canvas) {
   if (!outsidePlot) {
     throw new Error(`Chart title requires more ${position}-margin space.`);
   }
-  for (const id of reservedGraphicIds(program, position)) {
-    const bounds = program.graphicSpec.objects[id] === undefined
-      ? undefined
-      : resolveConcreteGraphicBounds(program.graphicSpec, id);
-    if (bounds !== undefined && layoutBoundsIntersect(titleBounds, bounds)) {
-      throw new Error(`Chart title and ${position} guides require more margin space.`);
-    }
-  }
 }
 
 export function resolveTitleLayout(program, config) {
@@ -293,7 +255,6 @@ export function resolveTitleLayout(program, config) {
       : [resolveTitleComponentBounds(subtitle, config.subtitleStyle)])
   ]);
   validateLayout(
-    program,
     config.position,
     titleBounds,
     plot,

package/src/actions/violinPlots/create.js

@@ -1,6 +1,7 @@
 import { action } from "../../core/action.js";
 import { validateOptionObject } from "../../core/validation.js";
 import { findDataset } from "../../selectors/datasets.js";
+import { findLayer } from "../../selectors/layers.js";
 import {
   applyFacadeGuides,
   normalizeAppearance,
@@ -19,7 +20,7 @@ const OPTIONS = Object.freeze([
 ]);
 const POSITION_OPTIONS = Object.freeze(["field", "fieldType", "scale"]);
 const DENSITY_OPTIONS = Object.freeze([
-  "bandwidth", "extent", "steps", "kernel", "normalization", "width"
+  "bandwidth", "extent", "steps", "kernel", "normalization", "width", "side"
 ]);
 const WIDTH_OPTIONS = Object.freeze(["band", "resolve"]);
 const SPLIT_OPTIONS = Object.freeze(["field", "domain"]);
@@ -28,7 +29,6 @@ const AREA_OPTIONS = Object.freeze([
 ]);
 const CATEGORICAL_TYPES = Object.freeze(["nominal", "ordinal"]);
 const OPERATION = "createViolinPlot";
-const ROLE_ERROR = `${OPERATION} requires one categorical axis and one quantitative axis.`;
 
 function inferFieldType(dataset, encoding, label) {
   if (encoding.fieldType !== undefined) return encoding.fieldType;
@@ -44,7 +44,7 @@ function inferFieldType(dataset, encoding, label) {
   return values.every(Number.isFinite) ? "quantitative" : "nominal";
 }
 
-function normalizePosition(dataset, value, label) {
+export function normalizeViolinPosition(dataset, value, label) {
   const encoding = normalizeFieldEncoding(value, label);
   validateOptionObject(encoding, POSITION_OPTIONS, label);
   return {
@@ -53,6 +53,54 @@ function normalizePosition(dataset, value, label) {
   };
 }
 
+export function resolveViolinRoles(dataset, xValue, yValue, operation) {
+  const x = normalizeViolinPosition(dataset, xValue, `${operation} x`);
+  const y = normalizeViolinPosition(dataset, yValue, `${operation} y`);
+  const xCategorical = CATEGORICAL_TYPES.includes(x.fieldType);
+  const yCategorical = CATEGORICAL_TYPES.includes(y.fieldType);
+  const roleError = `${operation} requires one categorical axis and one quantitative axis.`;
+  if (xCategorical === yCategorical || (
+    x.fieldType !== "quantitative" && y.fieldType !== "quantitative"
+  )) {
+    throw new Error(roleError);
+  }
+  const category = xCategorical ? x : y;
+  const value = xCategorical ? y : x;
+  if (value.fieldType !== "quantitative") throw new Error(roleError);
+  return {
+    x,
+    y,
+    category,
+    value,
+    orientation: xCategorical ? "vertical" : "horizontal",
+    densityChannel: xCategorical ? "x" : "y"
+  };
+}
+
+export function resolveViolinSplit(value, category, operation, { removable = false } = {}) {
+  if (removable && value === false) return undefined;
+  if (value === undefined) return undefined;
+  validateOptionObject(value, SPLIT_OPTIONS, `${operation} split`);
+  if (typeof value.field !== "string" || value.field.length === 0) {
+    throw new TypeError(`${operation} split.field must be a non-empty string.`);
+  }
+  const split = { ...value };
+  if (split.field === category.field) {
+    throw new Error(`${operation} split field must differ from its category field.`);
+  }
+  return split;
+}
+
+export function resolveViolinDensity(value, current = {}, operation = OPERATION) {
+  if (value !== undefined) {
+    validateOptionObject(value, DENSITY_OPTIONS, `${operation} density`);
+    if (value.width !== undefined) {
+      validateOptionObject(value.width, WIDTH_OPTIONS, `${operation} density.width`);
+    }
+  }
+  return { ...current, ...(value ?? {}) };
+}
+
 function axisGuideOptions(value, field) {
   if (value === false) return false;
   return {
@@ -95,31 +143,9 @@ export const createViolinPlot = action(
     });
     const data = resolveFacadeData(this, args.data, OPERATION);
     const dataset = findDataset(this, data);
-    const x = normalizePosition(dataset, args.x, `${OPERATION} x`);
-    const y = normalizePosition(dataset, args.y, `${OPERATION} y`);
-    const xCategorical = CATEGORICAL_TYPES.includes(x.fieldType);
-    const yCategorical = CATEGORICAL_TYPES.includes(y.fieldType);
-    if (xCategorical === yCategorical || (
-      x.fieldType !== "quantitative" && y.fieldType !== "quantitative"
-    )) {
-      throw new Error(ROLE_ERROR);
-    }
-    const category = xCategorical ? x : y;
-    const value = xCategorical ? y : x;
-    if (value.fieldType !== "quantitative") {
-      throw new Error(ROLE_ERROR);
-    }
-    let split = args.split;
-    if (split !== undefined) {
-      validateOptionObject(split, SPLIT_OPTIONS, `${OPERATION} split`);
-      if (typeof split.field !== "string" || split.field.length === 0) {
-        throw new TypeError(`${OPERATION} split.field must be a non-empty string.`);
-      }
-      split = { ...split };
-    }
-    if (split?.field === category.field) {
-      throw new Error(`${OPERATION} split field must differ from its category field.`);
-    }
+    const roles = resolveViolinRoles(dataset, args.x, args.y, OPERATION);
+    const { x, y, category, value } = roles;
+    const split = resolveViolinSplit(args.split, category, OPERATION);
     const color = normalizeEncoding(args.color, `${OPERATION} color`);
     if (
       color !== undefined &&
@@ -129,18 +155,8 @@ export const createViolinPlot = action(
         `${OPERATION} color must encode its category or split field.`
       );
     }
-    const density = args.density === undefined ? {} : args.density;
-    if (args.density !== undefined) {
-      validateOptionObject(density, DENSITY_OPTIONS, `${OPERATION} density`);
-      if (density.width !== undefined) {
-        validateOptionObject(
-          density.width,
-          WIDTH_OPTIONS,
-          `${OPERATION} density.width`
-        );
-      }
-    }
-    const { width: densityWidth, ...densityOptions } = density;
+    const density = resolveViolinDensity(args.density);
+    const { width: densityWidth, side: densitySide, ...densityOptions } = density;
     const area = normalizeAppearance(
       args.area,
       AREA_OPTIONS,
@@ -174,18 +190,46 @@ export const createViolinPlot = action(
       source: data,
       field: value.field,
       groupBy: category.field,
-      densityChannel: xCategorical ? "x" : "y",
+      densityChannel: roles.densityChannel,
       ...(args.coordinate === undefined ? {} : { coordinate: args.coordinate }),
       ...(value.scale === undefined ? {} : { valueScale: value.scale }),
       ...densityOptions,
       placement: {
         type: "category",
+        ...(densitySide === undefined ? {} : { side: densitySide }),
         ...(densityWidth === undefined ? {} : { width: densityWidth }),
         ...(split === undefined ? {} : { split }),
         ...(category.scale === undefined ? {} : { scale: category.scale })
       }
     });
     if (color !== undefined) next = next.encodeColor(targetArgs(color, id));
-    return applyFacadeGuides(next, guides);
+    next = applyFacadeGuides(next, guides, id, args.guides ?? {});
+    const transform = findDataset(next, findLayer(next, id).data).transform[0];
+    return next._withMarkConfig(id, {
+      ...next.markConfigs[id],
+      violinPlot: {
+        materialized: true,
+        source: data,
+        orientation: roles.orientation,
+        category: category.field,
+        categoryType: category.fieldType,
+        value: value.field,
+        split: transform.placement.split,
+        density: {
+          bandwidth: transform.bandwidth,
+          extent: transform.extent,
+          steps: transform.steps,
+          kernel: transform.kernel,
+          normalization: transform.normalization,
+          width: transform.placement.width,
+          side: transform.placement.side
+        },
+        colorRole: color === undefined
+          ? undefined
+          : color.field === category.field
+            ? "category"
+            : color.field === split?.field ? "split" : undefined
+      }
+    });
   }
 );

package/src/actions/violinPlots/edit.js

@@ -0,0 +1,191 @@
+import { action } from "../../core/action.js";
+import { validateUserId } from "../../core/identifiers.js";
+import { validateKeys } from "../../core/validation.js";
+import { findDataset } from "../../selectors/datasets.js";
+import { findLayer } from "../../selectors/layers.js";
+import { rebindDistributionGuides } from "../distributions/revision.js";
+import {
+  resolveViolinDensity,
+  resolveViolinRoles,
+  resolveViolinSplit
+} from "./create.js";
+
+const OPERATION = "editViolinPlot";
+const OPTIONS = Object.freeze([
+  "target", "data", "x", "y", "split", "density"
+]);
+
+function resolveOwner(program, requested) {
+  const eligible = program.semanticSpec.layers.filter(
+    layer => program.markConfigs[layer.id]?.violinPlot?.materialized === true
+  );
+  if (requested !== undefined) {
+    const id = validateUserId(requested, "Violin-plot owner id");
+    const layer = findLayer(program, id);
+    if (layer === undefined || !eligible.includes(layer)) {
+      throw new Error(`Unknown violin-plot owner "${id}".`);
+    }
+    return layer;
+  }
+  const current = findLayer(program, program.context.currentMark);
+  if (current !== undefined && eligible.includes(current)) return current;
+  if (eligible.length === 1) return eligible[0];
+  if (eligible.length === 0) throw new Error(`${OPERATION} requires a violin plot.`);
+  throw new Error(`${OPERATION} target is ambiguous; provide target.`);
+}
+
+function currentPosition(owner, current, channel) {
+  const categorical = current.orientation === "vertical"
+    ? channel === "x"
+    : channel === "y";
+  return {
+    field: categorical ? current.category : current.value,
+    fieldType: categorical ? current.categoryType : "quantitative",
+    scale: { id: owner.encoding[channel].scale }
+  };
+}
+
+function requestedScale(args, channel, expectedId) {
+  if (!Object.hasOwn(args, channel) || typeof args[channel] !== "object") {
+    return undefined;
+  }
+  const scale = args[channel].scale;
+  if (scale === undefined) return undefined;
+  if (scale.id !== undefined && scale.id !== expectedId) {
+    throw new Error(`${OPERATION} ${channel} scale cannot change its id.`);
+  }
+  const { id: _id, ...definition } = scale;
+  void _id;
+  return definition;
+}
+
+function assertSplitSelectionCompatibility(program, owner, changesSplit) {
+  if (!changesSplit) return;
+  const referenced = Object.entries(
+    program.materializationConfigs.selections ?? {}
+  ).find(([, selection]) =>
+    selection.target === owner.id && selection.selector?.channel === "color"
+  );
+  if (referenced !== undefined) {
+    throw new Error(
+      `${OPERATION} cannot change split while selection "${referenced[0]}" ` +
+      "references color."
+    );
+  }
+}
+
+export const editViolinPlot = action(
+  {
+    op: OPERATION,
+    description: "Revise one violin plot's data and statistical roles."
+  },
+  function (args = {}) {
+    validateKeys(args, OPTIONS, OPERATION);
+    if (!OPTIONS.slice(1).some(key => Object.hasOwn(args, key))) {
+      throw new Error(`${OPERATION} requires at least one violin-plot option.`);
+    }
+    const owner = resolveOwner(this, args.target);
+    const current = this.markConfigs[owner.id].violinPlot;
+    const source = Object.hasOwn(args, "data")
+      ? validateUserId(args.data, "Violin-plot data id")
+      : current.source;
+    const dataset = findDataset(this, source);
+    if (dataset === undefined) {
+      throw new Error(`Unknown violin-plot data "${source}".`);
+    }
+    const roles = resolveViolinRoles(
+      dataset,
+      Object.hasOwn(args, "x") ? args.x : currentPosition(owner, current, "x"),
+      Object.hasOwn(args, "y") ? args.y : currentPosition(owner, current, "y"),
+      OPERATION
+    );
+    const split = Object.hasOwn(args, "split")
+      ? resolveViolinSplit(args.split, roles.category, OPERATION, {
+          removable: true
+        })
+      : current.split;
+    if (split?.field === roles.category.field) {
+      throw new Error(
+        `${OPERATION} split field must differ from its category field.`
+      );
+    }
+    const density = resolveViolinDensity(args.density, current.density, OPERATION);
+    const changesSplit = split?.field !== current.split?.field;
+    assertSplitSelectionCompatibility(this, owner, changesSplit);
+    if (current.colorRole === "split" && split === undefined) {
+      throw new Error(
+        `${OPERATION} cannot remove split while color encodes the split field.`
+      );
+    }
+
+    const categoryChannel = roles.orientation === "vertical" ? "x" : "y";
+    const valueChannel = roles.orientation === "vertical" ? "y" : "x";
+    const categoryScale = requestedScale(
+      args, categoryChannel, owner.encoding[categoryChannel].scale
+    );
+    const valueScale = requestedScale(
+      args, valueChannel, owner.encoding[valueChannel].scale
+    );
+    const { width, side, ...densityOptions } = density;
+    let next = this;
+    if (current.colorRole === "split" && changesSplit) {
+      next = next.editSemantic({
+        property: `layer[${owner.id}].encoding.color.field`,
+        value: split.field
+      });
+    }
+    next = next.editDensity({
+      target: owner.id,
+      source,
+      field: roles.value.field,
+      groupBy: roles.category.field,
+      densityChannel: roles.densityChannel,
+      ...densityOptions,
+      ...(valueScale === undefined ? {} : { valueScale }),
+      placement: {
+        type: "category",
+        ...(side === undefined ? {} : { side }),
+        width,
+        ...(split === undefined ? {} : { split }),
+        ...(categoryScale === undefined ? {} : { scale: categoryScale })
+      }
+    });
+    next = rebindDistributionGuides(next, {
+      oldXScale: owner.encoding.x.scale,
+      oldYScale: owner.encoding.y.scale,
+      newXScale: owner.encoding.x.scale,
+      newYScale: owner.encoding.y.scale,
+      oldXTitle: current.orientation === "vertical" ? current.category : current.value,
+      oldYTitle: current.orientation === "vertical" ? current.value : current.category,
+      newXTitle: roles.x.field,
+      newYTitle: roles.y.field,
+      oldMeasureChannel: current.orientation === "vertical" ? "y" : "x",
+      newMeasureChannel: valueChannel
+    });
+    const revisedLayer = findLayer(next, owner.id);
+    const transform = findDataset(next, revisedLayer.data).transform[0];
+    next = next._withMarkConfig(owner.id, {
+      ...next.markConfigs[owner.id],
+      violinPlot: {
+        ...current,
+        materialized: true,
+        source,
+        orientation: roles.orientation,
+        category: roles.category.field,
+        categoryType: roles.category.fieldType,
+        value: roles.value.field,
+        split: transform.placement.split,
+        density: {
+          bandwidth: transform.bandwidth,
+          extent: transform.extent,
+          steps: transform.steps,
+          kernel: transform.kernel,
+          normalization: transform.normalization,
+          width: transform.placement.width,
+          side: transform.placement.side
+        }
+      }
+    });
+    return next._withContext({ currentMark: owner.id, currentData: source });
+  }
+);

package/src/actions/violinPlots/index.js

@@ -1,5 +1,7 @@
 import { createViolinPlot } from "./create.js";
+import { editViolinPlot } from "./edit.js";
 
 export function registerViolinPlotActions(ProgramClass) {
   ProgramClass.prototype.createViolinPlot = createViolinPlot;
+  ProgramClass.prototype.editViolinPlot = editViolinPlot;
 }

package/src/core/ChartProgram.js

@@ -173,6 +173,13 @@ export class ChartProgram {
     });
   }
 
+  _withoutResolvedScale(id) {
+    if (!Object.hasOwn(this.resolvedScales, id)) return this;
+    const { [id]: unused, ...remaining } = this.resolvedScales;
+    void unused;
+    return this._clone({ resolvedScales: freezeOwned(remaining) });
+  }
+
   _withMarkConfig(id, config) {
     if (typeof id !== "string" || id.length === 0) {
       throw new TypeError("Mark config id must be a non-empty string.");

package/src/core/action.js

@@ -1,6 +1,14 @@
 import { cloneAndFreeze, freezeOwned, isPlainObject } from "./immutable.js";
 
 const metadataByWrappedAction = new WeakMap();
+let actionCompletionHook;
+
+export function setActionCompletionHook(hook) {
+  if (hook !== undefined && typeof hook !== "function") {
+    throw new TypeError("Action completion hook must be a function.");
+  }
+  actionCompletionHook = hook;
+}
 
 export function getWrappedActionMetadata(value) {
   return metadataByWrappedAction.get(value);
@@ -127,16 +135,28 @@ export function action(metadata, implementation) {
     if (scope === "unit") this._assertUnitProgram(ownedMetadata.op);
     if (scope === "composition") this._assertCompositionProgram(ownedMetadata.op);
 
+    const summarizedArgs = summarizeArgs(args);
     const entered = this._enterAction({
       ...ownedMetadata,
-      args: summarizeArgs(args)
+      args: summarizedArgs
     });
-    const result = implementation.call(entered, args);
+    let result = implementation.call(entered, args);
 
     if (!(result instanceof this.constructor)) {
       throw new TypeError(`${ownedMetadata.op} must return a ChartProgram.`);
     }
 
+    if (this.actionStack.length === 0 && actionCompletionHook !== undefined) {
+      result = actionCompletionHook(result, {
+        source: this,
+        metadata: ownedMetadata,
+        args: summarizedArgs
+      });
+      if (!(result instanceof this.constructor)) {
+        throw new TypeError("Action completion hook must return a ChartProgram.");
+      }
+    }
+
     return result._exitAction();
   };