ggaction 0.0.8 → 0.0.9

package/src/actions/primitives/semanticAction.js

@@ -0,0 +1,188 @@
+import { action } from "../../core/action.js";
+import {
+  cloneAndFreeze,
+  freezeOwned,
+  isPlainObject,
+  removeOwnedPath
+} from "../../core/immutable.js";
+import { parseSemanticPath } from "../../grammar/schemas/semanticPath.js";
+
+const CONTEXT_KEYS = Object.freeze({
+  dataset: "currentData",
+  layer: "currentMark",
+  scale: "currentScale",
+  coordinate: "currentCoordinate",
+  guide: "currentGuide"
+});
+
+function setNestedProperty(source, path, value) {
+  const [key, ...rest] = path;
+
+  if (rest.length === 0) {
+    return freezeOwned({ ...source, [key]: cloneAndFreeze(value) });
+  }
+
+  const child = isPlainObject(source[key]) ? source[key] : {};
+  return freezeOwned({
+    ...source,
+    [key]: setNestedProperty(child, rest, value)
+  });
+}
+
+function updateEntity(spec, parsed, value) {
+  const collection = spec[parsed.collection];
+  const index = collection.findIndex(item => item.id === parsed.id);
+
+  if (
+    parsed.kind === "dataset" &&
+    index !== -1 &&
+    Object.hasOwn(collection[index], "values")
+  ) {
+    throw new Error(`Dataset "${parsed.id}" is immutable after creation.`);
+  }
+
+  const current = index === -1 ? { id: parsed.id } : collection[index];
+  const updated = setNestedProperty(current, parsed.path, value);
+  const nextCollection = [...collection];
+
+  if (index === -1) {
+    nextCollection.push(updated);
+  } else {
+    nextCollection[index] = updated;
+  }
+
+  return freezeOwned({
+    ...spec,
+    [parsed.collection]: freezeOwned(nextCollection)
+  });
+}
+
+function updateGuides(spec, parsed, value) {
+  return freezeOwned({
+    ...spec,
+    guides: setNestedProperty(spec.guides, parsed.path, value)
+  });
+}
+
+function updateTitle(spec, parsed, value) {
+  return freezeOwned({
+    ...spec,
+    title: setNestedProperty(spec.title, parsed.path, value)
+  });
+}
+
+function removeEntity(spec, parsed) {
+  const collection = spec[parsed.collection];
+  const index = collection.findIndex(item => item.id === parsed.id);
+  if (index === -1) return spec;
+  if (parsed.kind === "layer" && parsed.path.length === 0) {
+    const nextCollection = collection.filter((_, itemIndex) => itemIndex !== index);
+    return freezeOwned({
+      ...spec,
+      [parsed.collection]: freezeOwned(nextCollection)
+    });
+  }
+  if (parsed.kind === "dataset" && parsed.path.length === 0) {
+    const dataset = collection[index];
+    if (dataset.source === undefined) {
+      throw new Error(`Source dataset "${parsed.id}" is immutable after creation.`);
+    }
+    const referenced = spec.layers.some(layer => layer.data === parsed.id) ||
+      spec.datasets.some(candidate => candidate.source === parsed.id);
+    if (referenced) {
+      throw new Error(`Derived dataset "${parsed.id}" is still referenced.`);
+    }
+    const nextCollection = collection.filter((_, itemIndex) => itemIndex !== index);
+    return freezeOwned({
+      ...spec,
+      [parsed.collection]: freezeOwned(nextCollection)
+    });
+  }
+  if (parsed.kind === "dataset") {
+    throw new Error(`Dataset "${parsed.id}" is immutable after creation.`);
+  }
+  const removed = removeOwnedPath(collection[index], parsed.path);
+  if (!removed.removed) return spec;
+  const nextCollection = [...collection];
+  nextCollection[index] = removed.value;
+  return freezeOwned({
+    ...spec,
+    [parsed.collection]: freezeOwned(nextCollection)
+  });
+}
+
+function removeRootProperty(spec, root, path) {
+  const removed = removeOwnedPath(spec[root], path);
+  return removed.removed
+    ? freezeOwned({ ...spec, [root]: removed.value })
+    : spec;
+}
+
+export function createSemanticPrimitiveAction(validateSemanticValue) {
+  return action(
+    {
+      op: "editSemantic",
+      description: "Create, replace, or remove one semantic property.",
+      scope: "any"
+    },
+    function ({ property, value, remove = false } = {}) {
+      if (typeof remove !== "boolean") {
+        throw new TypeError("editSemantic remove must be a boolean.");
+      }
+      if (remove && value !== undefined) {
+        throw new Error("editSemantic cannot combine value and remove.");
+      }
+      if (!remove && value === undefined) {
+        throw new TypeError("editSemantic requires a value.");
+      }
+
+      const parsed = parseSemanticPath(property, { allowContainer: remove });
+      if (this.compositionSpec !== undefined && !(
+        this.compositionSpec.type === "facet" && parsed.kind === "title"
+      )) {
+        throw new Error(
+          "editSemantic on a composition parent currently supports only facet title state."
+        );
+      }
+      if (remove) {
+        const semanticSpec = parsed.kind === "guide"
+          ? removeRootProperty(this.semanticSpec, "guides", parsed.path)
+          : parsed.kind === "title"
+            ? removeRootProperty(this.semanticSpec, "title", parsed.path)
+            : removeEntity(this.semanticSpec, parsed);
+        if (semanticSpec === this.semanticSpec) return this;
+        const clearsCurrentData =
+          parsed.kind === "dataset" &&
+          parsed.path.length === 0 &&
+          this.context.currentData === parsed.id;
+        const clearsCurrentMark =
+          parsed.kind === "layer" &&
+          parsed.path.length === 0 &&
+          this.context.currentMark === parsed.id;
+        return this._clone({
+          semanticSpec,
+          ...(clearsCurrentData || clearsCurrentMark
+            ? { context: freezeOwned({
+                ...this.context,
+                ...(clearsCurrentData ? { currentData: undefined } : {}),
+                ...(clearsCurrentMark ? { currentMark: undefined } : {})
+              }) }
+            : {})
+        });
+      }
+      validateSemanticValue(this, parsed, value);
+
+      const semanticSpec = parsed.kind === "guide"
+        ? updateGuides(this.semanticSpec, parsed, value)
+        : parsed.kind === "title"
+          ? updateTitle(this.semanticSpec, parsed, value)
+          : updateEntity(this.semanticSpec, parsed, value);
+      const contextKey = CONTEXT_KEYS[parsed.kind];
+      const context = contextKey === undefined
+        ? this.context
+        : freezeOwned({ ...this.context, [contextKey]: parsed.id });
+
+      return this._clone({ semanticSpec, context });
+    }
+  );
+}

package/src/actions/primitives/semanticValidation/dataset.js

@@ -1,9 +1,13 @@
 import { validateUserId } from "../../../core/identifiers.js";
 import { isPlainObject } from "../../../core/immutable.js";
-import { validateDatasetTransforms } from "../../../grammar/transforms.js";
 import { hasDataset } from "../../../selectors/datasets.js";
 
-export function validateDatasetSemanticValue(program, parsed, value) {
+export function validateDatasetSemanticValue(
+  program,
+  parsed,
+  value,
+  validateTransforms
+) {
   const property = parsed.path[0];
   if (property === "values") {
     if (!Array.isArray(value) || !value.every(isPlainObject)) {
@@ -18,5 +22,5 @@ export function validateDatasetSemanticValue(program, parsed, value) {
     }
     return;
   }
-  if (property === "transform") validateDatasetTransforms(value);
+  if (property === "transform") validateTransforms(value);
 }

package/src/actions/primitives/semanticValidation/index.js

@@ -5,19 +5,32 @@ import { validateLayerSemanticValue } from "./layer.js";
 import { validateScaleSemanticValue } from "./scale.js";
 import { validateNonEmptySemanticString } from "./shared.js";
 
-const VALIDATORS = Object.freeze({
-  dataset: validateDatasetSemanticValue,
-  layer: validateLayerSemanticValue,
-  scale: validateScaleSemanticValue,
-  coordinate(_program, parsed, value) {
-    if (parsed.path[0] === "type") validateCoordinateType(value);
-  },
-  guide: validateGuideSemanticValue,
-  title(_program, parsed, value) {
-    validateNonEmptySemanticString(value, `Chart title ${parsed.path[0]}`);
-  }
-});
-
-export function validateSemanticValue(program, parsed, value) {
-  VALIDATORS[parsed.kind]?.(program, parsed, value);
+export function createSemanticValueValidator({
+  validateDatasetTransforms,
+  validateParallel,
+  sourceMarkTypes
+}) {
+  return function validateSemanticValue(program, parsed, value) {
+    if (parsed.kind === "dataset") {
+      validateDatasetSemanticValue(
+        program,
+        parsed,
+        value,
+        validateDatasetTransforms
+      );
+    } else if (parsed.kind === "layer") {
+      validateLayerSemanticValue(program, parsed, value, {
+        sourceMarkTypes,
+        validateParallel
+      });
+    } else if (parsed.kind === "scale") {
+      validateScaleSemanticValue(program, parsed, value);
+    } else if (parsed.kind === "coordinate" && parsed.path[0] === "type") {
+      validateCoordinateType(value);
+    } else if (parsed.kind === "guide") {
+      validateGuideSemanticValue(program, parsed, value);
+    } else if (parsed.kind === "title") {
+      validateNonEmptySemanticString(value, `Chart title ${parsed.path[0]}`);
+    }
+  };
 }

package/src/actions/primitives/semanticValidation/layer.js

@@ -10,18 +10,13 @@ import {
   validateHistogramBinBoundaries,
   validateHistogramBinStep
 } from "../../../grammar/histogram.js";
-import {
-  validateParallelDimensions,
-  validateParallelKeyField,
-  validateParallelMissingPolicy
-} from "../../../grammar/parallelCoordinates.js";
 import { validatePathOrderDirection } from "../../../grammar/pathOrder.js";
 import { normalizeCategoryOrder } from "../../../grammar/categoryOrder.js";
 import { validateSemanticFieldType } from "../../../grammar/scales/index.js";
 import { findLayer } from "../../../selectors/layers.js";
 import { validateNonEmptySemanticString } from "./shared.js";
 
-function validateLayerSource(program, parsed, value) {
+function validateLayerSource(program, parsed, value, sourceMarkTypes) {
   validateUserId(value, "Layer source id");
   if (value === parsed.id) {
     throw new Error("A layer cannot use itself as its source.");
@@ -30,19 +25,32 @@ function validateLayerSource(program, parsed, value) {
   if (source === undefined) {
     throw new Error(`Unknown source layer "${value}".`);
   }
-  if (!["point", "bar", "rule", "rect"].includes(source.mark?.type)) {
+  if (!sourceMarkTypes.includes(source.mark?.type)) {
+    const sourceLabel = sourceMarkTypes.length === 1
+      ? sourceMarkTypes[0]
+      : `${sourceMarkTypes.slice(0, -1).join(", ")}, or ${sourceMarkTypes.at(-1)}`;
     throw new Error(
-      `Layer source "${value}" must be a point, bar, rule, or rect mark.`
+      `Layer source "${value}" must be a ${sourceLabel} mark.`
     );
   }
 }
 
-export function validateLayerSemanticValue(program, parsed, value) {
+export function validateLayerSemanticValue(
+  program,
+  parsed,
+  value,
+  {
+    sourceMarkTypes = ["point", "bar", "rule", "rect"],
+    validateParallel
+  } = {}
+) {
   const property = parsed.path.join(".");
   if (property === "mark.type" && !MARK_TYPES.includes(value)) {
     throw new Error(`Unknown mark type "${value}".`);
   }
-  if (property === "source") validateLayerSource(program, parsed, value);
+  if (property === "source") {
+    validateLayerSource(program, parsed, value, sourceMarkTypes);
+  }
   if (property.endsWith(".title")) {
     validateNonEmptySemanticString(value, "Encoding title");
   }
@@ -52,12 +60,8 @@ export function validateLayerSemanticValue(program, parsed, value) {
   if (property.endsWith(".fieldType")) validateSemanticFieldType(value);
   if (property === "encoding.pathOrder.order") validatePathOrderDirection(value);
   if (property.endsWith(".categoryOrder")) normalizeCategoryOrder(value);
-  if (property === "encoding.parallel.dimensions") {
-    validateParallelDimensions(value, { normalized: true });
-  }
-  if (property === "encoding.parallel.key") validateParallelKeyField(value);
-  if (property === "encoding.parallel.missing") {
-    validateParallelMissingPolicy(value);
+  if (property.startsWith("encoding.parallel.")) {
+    validateParallel?.(property, value);
   }
   if (property.endsWith(".aggregate")) validateAggregate(value);
   if (property.endsWith(".bin.maxBins")) normalizeHistogramBin({ maxBins: value });

package/src/grammar/transformTopology.js

@@ -0,0 +1,18 @@
+const TRANSFORM_TOPOLOGY = Object.freeze({
+  bin2d: Object.freeze({ facetTopology: "statistical" }),
+  boxOutlier: Object.freeze({ facetTopology: "statistical" }),
+  boxSummary: Object.freeze({ facetTopology: "statistical" }),
+  density: Object.freeze({ facetTopology: "statistical" }),
+  filter: Object.freeze({ facetTopology: "rowPreserving" }),
+  gradientProfile: Object.freeze({ facetTopology: "statistical" }),
+  horizon: Object.freeze({ facetTopology: "statistical" }),
+  interval: Object.freeze({ facetTopology: "statistical" }),
+  markFilter: Object.freeze({ provenanceTransparent: true }),
+  regression: Object.freeze({ facetTopology: "statistical" }),
+  timeUnit: Object.freeze({ facetTopology: "rowPreserving" }),
+  window: Object.freeze({ facetTopology: "statistical" })
+});
+
+export function findTransformTopology(type) {
+  return TRANSFORM_TOPOLOGY[type];
+}

package/src/grammar/transforms.js

@@ -19,6 +19,7 @@ import { validateMarkFilterTransform } from "./markFilter.js";
 import { validateRegressionTransform } from "./regression/index.js";
 import { validateWindowTransform } from "./window.js";
 import { validateTimeUnitTransform } from "./timeUnit.js";
+import { findTransformTopology } from "./transformTopology.js";
 
 function requestedDensityTransform(transform) {
   const { resolved: _resolved, ...requested } = transform;
@@ -41,69 +42,69 @@ function facetHorizonTransform(transform, { scales = {} } = {}) {
 
 const TRANSFORM_POLICIES = Object.freeze({
   bin2d: Object.freeze({
+    ...findTransformTopology("bin2d"),
     validate: validateBin2DTransform,
     materializeOp: "materializeBin2DData",
-    facetTopology: "statistical",
     replayTransform: requestedBin2DTransform
   }),
   boxOutlier: Object.freeze({
+    ...findTransformTopology("boxOutlier"),
     validate: validateBoxTransform,
-    materializeOp: "materializeBoxOutlierData",
-    facetTopology: "statistical"
+    materializeOp: "materializeBoxOutlierData"
   }),
   boxSummary: Object.freeze({
+    ...findTransformTopology("boxSummary"),
     validate: validateBoxTransform,
-    materializeOp: "materializeBoxSummaryData",
-    facetTopology: "statistical"
+    materializeOp: "materializeBoxSummaryData"
   }),
   density: Object.freeze({
+    ...findTransformTopology("density"),
     validate: validateDensityTransform,
     materializeOp: "materializeDensityData",
-    facetTopology: "statistical",
     replayTransform: requestedDensityTransform
   }),
   filter: Object.freeze({
+    ...findTransformTopology("filter"),
     validate: validateFilterTransform,
-    materializeOp: "materializeFilteredData",
-    facetTopology: "rowPreserving"
+    materializeOp: "materializeFilteredData"
   }),
   gradientProfile: Object.freeze({
+    ...findTransformTopology("gradientProfile"),
     validate: validateGradientProfileTransform,
     materializeOp: "materializeGradientProfileData",
-    facetTopology: "statistical",
     replayTransform: requestedGradientProfileTransform
   }),
   horizon: Object.freeze({
+    ...findTransformTopology("horizon"),
     validate: validateHorizonTransform,
     materializeOp: "materializeHorizonData",
-    facetTopology: "statistical",
     replayTransform: requestedHorizonTransform,
     facetReplayTransform: facetHorizonTransform
   }),
   interval: Object.freeze({
+    ...findTransformTopology("interval"),
     validate: validateIntervalTransform,
-    materializeOp: "materializeIntervalData",
-    facetTopology: "statistical"
+    materializeOp: "materializeIntervalData"
   }),
   markFilter: Object.freeze({
+    ...findTransformTopology("markFilter"),
     validate: validateMarkFilterTransform,
-    materializeOp: "materializeMarkFilteredData",
-    provenanceTransparent: true
+    materializeOp: "materializeMarkFilteredData"
   }),
   regression: Object.freeze({
+    ...findTransformTopology("regression"),
     validate: validateRegressionTransform,
-    materializeOp: "materializeRegressionData",
-    facetTopology: "statistical"
+    materializeOp: "materializeRegressionData"
   }),
   timeUnit: Object.freeze({
+    ...findTransformTopology("timeUnit"),
     validate: validateTimeUnitTransform,
-    materializeOp: "materializeTimeUnitData",
-    facetTopology: "rowPreserving"
+    materializeOp: "materializeTimeUnitData"
   }),
   window: Object.freeze({
+    ...findTransformTopology("window"),
     validate: validateWindowTransform,
-    materializeOp: "materializeWindowData",
-    facetTopology: "statistical"
+    materializeOp: "materializeWindowData"
   })
 });
 

package/src/materialization/dataProvenance.js

@@ -1,6 +1,6 @@
 import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
 import { validateUserId } from "../core/identifiers.js";
-import { findTransformPolicy } from "../grammar/transforms.js";
+import { findTransformTopology } from "../grammar/transformTopology.js";
 import { findDataset, hasDataset } from "../selectors/datasets.js";
 import { requireLayer } from "../selectors/layers.js";
 
@@ -60,7 +60,7 @@ export function findUpstreamTransform(program, dataset, type) {
     if (current.transform?.length !== 1) return undefined;
     const transform = current.transform[0];
     if (transform.type === type) return transform;
-    if (findTransformPolicy(transform.type)?.provenanceTransparent !== true) {
+    if (findTransformTopology(transform.type)?.provenanceTransparent !== true) {
       return undefined;
     }
     current = findDataset(program, current.source);

package/src/materialization/marks/pathOrder.js

@@ -1,5 +1,5 @@
 import { isAggregate } from "../../grammar/aggregate.js";
-import { findTransformPolicy } from "../../grammar/transforms.js";
+import { findTransformTopology } from "../../grammar/transformTopology.js";
 import { findDataset } from "../../selectors/datasets.js";
 
 function hasRowPreservingProvenance(program, dataset) {
@@ -8,7 +8,7 @@ function hasRowPreservingProvenance(program, dataset) {
   while (current?.source !== undefined) {
     if (visited.has(current.id) || current.transform?.length !== 1) return false;
     visited.add(current.id);
-    const policy = findTransformPolicy(current.transform[0].type);
+    const policy = findTransformTopology(current.transform[0].type);
     if (
       policy?.facetTopology !== "rowPreserving" &&
       policy?.provenanceTransparent !== true