ggaction 0.0.12 → 0.0.15

package/src/actions/violinPlots/edit.js

@@ -0,0 +1,192 @@
+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,
+          ...(transform.weight === undefined ? {} : { weight: transform.weight }),
+          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,11 +1,28 @@
 import { cloneAndFreeze, freezeOwned, isPlainObject } from "./immutable.js";
 
 const metadataByWrappedAction = new WeakMap();
+const implementationByWrappedAction = 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);
 }
 
+export function invokeWrappedActionImplementation(value, program, args = {}) {
+  const implementation = implementationByWrappedAction.get(value);
+  if (implementation === undefined) {
+    throw new TypeError("Expected an action created by action().");
+  }
+  return implementation.call(program, args);
+}
+
 function summarizeObject(value, ancestors = new WeakSet()) {
   if (ancestors.has(value)) {
     throw new TypeError("Action arguments must not contain circular references.");
@@ -127,19 +144,32 @@ 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();
   };
 
   metadataByWrappedAction.set(wrappedAction, ownedMetadata);
+  implementationByWrappedAction.set(wrappedAction, implementation);
   return wrappedAction;
 }

package/src/core/compositionState.js

@@ -11,24 +11,23 @@ function validateFacetSpec(compositionSpec) {
   }
   if (
     !Number.isInteger(compositionSpec.columns) ||
-    compositionSpec.columns <= 0 ||
-    compositionSpec.columns > compositionSpec.children.length
+    compositionSpec.columns <= 0
   ) {
     throw new RangeError(
-      "Facet compositionSpec.columns must be a positive integer no larger than its children."
+      "Facet compositionSpec.columns must be a positive integer."
     );
   }
   if (!isPlainObject(compositionSpec.facet)) {
     throw new TypeError("Facet compositionSpec.facet must be a plain object.");
   }
-  const facetKeys = ["data", "field", "values", "scales", "guides"];
+  const facetKeys = ["data", "field", "values", "grid", "repeat", "scales", "guides"];
   const unknownFacet = Object.keys(compositionSpec.facet).find(
     key => !facetKeys.includes(key)
   );
   if (unknownFacet !== undefined) {
     throw new Error(`Unknown compositionSpec.facet property "${unknownFacet}".`);
   }
-  for (const property of ["data", "field"]) {
+  for (const property of ["data"]) {
     if (
       typeof compositionSpec.facet[property] !== "string" ||
       compositionSpec.facet[property].length === 0
@@ -36,6 +35,134 @@ function validateFacetSpec(compositionSpec) {
       throw new TypeError(`compositionSpec.facet.${property} must be a non-empty string.`);
     }
   }
+  const grid = compositionSpec.facet.grid;
+  const repeat = compositionSpec.facet.repeat;
+  if (grid !== undefined && repeat !== undefined) {
+    throw new Error("Facet compositionSpec cannot combine grid and repeat recipes.");
+  }
+  if (grid === undefined && repeat === undefined) {
+    if (compositionSpec.columns > compositionSpec.children.length) {
+      throw new RangeError(
+        "Facet compositionSpec.columns must be no larger than its children."
+      );
+    }
+    if (
+      typeof compositionSpec.facet.field !== "string" ||
+      compositionSpec.facet.field.length === 0
+    ) {
+      throw new TypeError("compositionSpec.facet.field must be a non-empty string.");
+    }
+  } else if (grid !== undefined) {
+    if (compositionSpec.columns !== grid.columns?.values?.length) {
+      throw new RangeError(
+        "Grid facet compositionSpec.columns must match its column domain."
+      );
+    }
+    if (compositionSpec.facet.field !== undefined) {
+      throw new Error("Grid facet compositionSpec does not use facet.field.");
+    }
+    if (!isPlainObject(grid)) {
+      throw new TypeError("compositionSpec.facet.grid must be a plain object.");
+    }
+    const gridKeys = ["rows", "columns", "combinations", "cells"];
+    const unknownGrid = Object.keys(grid).find(key => !gridKeys.includes(key));
+    if (unknownGrid !== undefined) {
+      throw new Error(`Unknown compositionSpec.facet.grid property "${unknownGrid}".`);
+    }
+    for (const role of ["rows", "columns"]) {
+      const value = grid[role];
+      if (!isPlainObject(value) || Object.keys(value).some(
+        key => !["field", "values"].includes(key)
+      )) {
+        throw new TypeError(
+          `compositionSpec.facet.grid.${role} requires field and values.`
+        );
+      }
+      if (typeof value.field !== "string" || value.field.length === 0) {
+        throw new TypeError(
+          `compositionSpec.facet.grid.${role}.field must be a non-empty string.`
+        );
+      }
+      if (
+        !Array.isArray(value.values) || value.values.length === 0 ||
+        value.values.some(item => !(
+          typeof item === "string" || typeof item === "boolean" ||
+          (typeof item === "number" && Number.isFinite(item))
+        )) || new Set(value.values).size !== value.values.length
+      ) {
+        throw new TypeError(
+          `compositionSpec.facet.grid.${role}.values must contain unique scalars.`
+        );
+      }
+    }
+    if (grid.rows.field === grid.columns.field) {
+      throw new Error("compositionSpec.facet.grid fields must be different.");
+    }
+    if (!["observed", "full"].includes(grid.combinations)) {
+      throw new Error(
+        'compositionSpec.facet.grid.combinations must be "observed" or "full".'
+      );
+    }
+    if (!Array.isArray(grid.cells) || grid.cells.length !== compositionSpec.children.length) {
+      throw new TypeError(
+        "compositionSpec.facet.grid.cells must contain one descriptor per child."
+      );
+    }
+    const cellKeys = ["id", "row", "column", "rowValue", "columnValue", "empty"];
+    const coordinates = new Set();
+    for (const cell of grid.cells) {
+      if (!isPlainObject(cell) || Object.keys(cell).some(key => !cellKeys.includes(key))) {
+        throw new TypeError("compositionSpec.facet.grid cells must be canonical objects.");
+      }
+      if (!compositionSpec.children.includes(cell.id)) {
+        throw new Error(`Unknown grid facet child "${cell.id}".`);
+      }
+      if (!Number.isInteger(cell.row) || cell.row < 0 || cell.row >= grid.rows.values.length ||
+          !Number.isInteger(cell.column) || cell.column < 0 || cell.column >= grid.columns.values.length) {
+        throw new RangeError("Grid facet cell coordinates must be inside their domains.");
+      }
+      if (cell.rowValue !== grid.rows.values[cell.row] ||
+          cell.columnValue !== grid.columns.values[cell.column]) {
+        throw new Error("Grid facet cell values must match their row and column coordinates.");
+      }
+      if (typeof cell.empty !== "boolean") {
+        throw new TypeError("Grid facet cell empty must be a boolean.");
+      }
+      const key = `${cell.row}:${cell.column}`;
+      if (coordinates.has(key)) {
+        throw new Error("Grid facet cells must occupy unique coordinates.");
+      }
+      coordinates.add(key);
+    }
+  } else {
+    if (compositionSpec.facet.field !== undefined) {
+      throw new Error("Repeat compositionSpec does not use facet.field.");
+    }
+    if (compositionSpec.columns > compositionSpec.children.length) {
+      throw new RangeError(
+        "Repeat compositionSpec.columns must be no larger than its children."
+      );
+    }
+    if (!isPlainObject(repeat) || Object.keys(repeat).some(
+      key => !["target", "channel", "fields"].includes(key)
+    )) {
+      throw new TypeError(
+        "compositionSpec.facet.repeat requires target, channel, and fields."
+      );
+    }
+    const repeatChannel = ["x", "y", "theta", "r"].includes(repeat.channel) ||
+      (isPlainObject(repeat.channel) &&
+        Object.keys(repeat.channel).length === 1 &&
+        typeof repeat.channel.parallelDimension === "string" &&
+        repeat.channel.parallelDimension.length > 0);
+    if (typeof repeat.target !== "string" || repeat.target.length === 0 ||
+        !repeatChannel ||
+        !Array.isArray(repeat.fields) || repeat.fields.length === 0 ||
+        repeat.fields.some(field => typeof field !== "string" || field.length === 0) ||
+        new Set(repeat.fields).size !== repeat.fields.length) {
+      throw new TypeError("compositionSpec.facet.repeat is not canonical.");
+    }
+  }
   const values = compositionSpec.facet.values;
   if (
     !Array.isArray(values) ||
@@ -45,12 +172,18 @@ function validateFacetSpec(compositionSpec) {
       typeof value === "boolean" ||
       (typeof value === "number" && Number.isFinite(value))
     )) ||
-    new Set(values).size !== values.length
+    (grid === undefined && new Set(values).size !== values.length)
   ) {
     throw new TypeError(
       "compositionSpec.facet.values must contain one unique scalar per child."
     );
   }
+  if (repeat !== undefined && (
+    values.length !== repeat.fields.length ||
+    values.some((value, index) => value !== repeat.fields[index])
+  )) {
+    throw new Error("compositionSpec.facet.values must match repeat fields.");
+  }
   const scales = compositionSpec.facet.scales;
   if (
     !isPlainObject(scales) ||
@@ -80,13 +213,13 @@ function validateFacetSpec(compositionSpec) {
 function validateCompositionChildren(compositionSpec, childIds, facet) {
   if (
     !Array.isArray(compositionSpec.children) ||
-    compositionSpec.children.length < (facet ? 1 : 2) ||
+    compositionSpec.children.length < 1 ||
     !compositionSpec.children.every(id => typeof id === "string" && id.length > 0)
   ) {
     throw new TypeError(
       facet
         ? "Facet compositionSpec.children requires at least one child ID."
-        : "compositionSpec.children requires at least two child IDs."
+        : "compositionSpec.children requires at least one child ID."
     );
   }
   if (new Set(compositionSpec.children).size !== compositionSpec.children.length) {

package/src/core/programState.js

@@ -4,6 +4,7 @@ import {
   isOwned,
   isPlainObject
 } from "./immutable.js";
+import { removeMaterializationConfig } from "./materializationState.js";
 
 export function ownProgramState(value) {
   return isOwned(value) ? value : cloneAndFreeze(value);
@@ -26,3 +27,22 @@ export function ownChildPrograms(children, ProgramClass) {
   }
   return freezeOwned(owned);
 }
+
+// Semantic entries, resolved scale caches, and physical current-resource IDs
+// are removed by editSemantic. A logical data owner also retains its own ID
+// and replay configuration; release those non-semantic references after the
+// domain's dependency validation and before the primitive deletion.
+export function releaseNamedResourceOwnership(program, { kind, id, dataOwner }) {
+  if (kind !== "data") return program;
+  const materializationConfigs = dataOwner === undefined
+    ? program.materializationConfigs
+    : removeMaterializationConfig(
+        program.materializationConfigs,
+        ["data", dataOwner.family, dataOwner.owner]
+      ).value;
+  const context = program.context.currentData === id
+    ? freezeOwned({ ...program.context, currentData: undefined })
+    : program.context;
+  if (context === program.context && materializationConfigs === program.materializationConfigs) return program;
+  return program._clone({ context, materializationConfigs });
+}