ggaction 0.0.1

package/src/actions/primitives/editGraphics.js

@@ -0,0 +1,208 @@
+import { action } from "../../core/action.js";
+import { cloneAndFreeze, freezeOwned, isPlainObject } from "../../core/immutable.js";
+import {
+  isPrimitiveDrawableGraphicType,
+  isStructuralGraphicType,
+  validateGraphicProperty,
+  validateGraphicType
+} from "../../grammar/schemas/graphic.js";
+import { validateConcreteGraphicValue } from
+  "../../grammar/schemas/concreteGraphic.js";
+import {
+  collectGraphicSubtreeIds,
+  findGraphicParent,
+  requireGraphic
+} from "../../grammar/schemas/graphicTree.js";
+
+function setGraphicProperty(properties, property, value) {
+  return freezeOwned({ ...properties, [property]: cloneAndFreeze(value) });
+}
+
+function validateCollectionItem(item, ownerId, index) {
+  if (!isPlainObject(item)) {
+    throw new TypeError(`collection.items[${index}] must be a plain object.`);
+  }
+  const unknown = Object.keys(item).find(key => !["type", "properties"].includes(key));
+  if (unknown !== undefined) throw new Error(`Unknown collection item property "${unknown}".`);
+  const type = validateGraphicType(item.type);
+  if (!isPrimitiveDrawableGraphicType(type)) {
+    throw new Error(`Collection item "${ownerId}:${index}" requires a primitive drawable type.`);
+  }
+  if (!isPlainObject(item.properties)) {
+    throw new TypeError(`Collection item "${ownerId}:${index}" requires plain properties.`);
+  }
+  for (const [property, value] of Object.entries(item.properties)) {
+    validateGraphicProperty(type, property);
+    validateConcreteGraphicValue(type, property, value);
+  }
+  return freezeOwned({
+    id: `${ownerId}:${index}`,
+    type,
+    properties: cloneAndFreeze(item.properties)
+  });
+}
+
+function replaceCollectionItems(value, id) {
+  if (!Array.isArray(value)) throw new TypeError("collection.items must be an array.");
+  return freezeOwned(value.map((item, index) => validateCollectionItem(item, id, index)));
+}
+
+function replaceDrawableItems(value, id, type) {
+  const items = replaceCollectionItems(value, id);
+  if (!items.every(item => item.type === type)) {
+    return freezeOwned({ type: "collection", items });
+  }
+  return freezeOwned({
+    type,
+    items: freezeOwned(items.map(item => freezeOwned({
+      id: item.id,
+      properties: item.properties
+    })))
+  });
+}
+
+function editGeneratedItem(owner, itemIndex, property, value) {
+  const items = [...owner.items];
+  const item = items[itemIndex];
+  const type = item.type ?? owner.type;
+  validateGraphicProperty(type, property);
+  validateConcreteGraphicValue(type, property, value);
+  items[itemIndex] = freezeOwned({
+    ...item,
+    properties: setGraphicProperty(item.properties, property, value)
+  });
+  return freezeOwned({ ...owner, items: freezeOwned(items) });
+}
+
+function editItems(owner, property, value, id) {
+  if (owner.type === "collection" && property === "items") {
+    return freezeOwned({ ...owner, items: replaceCollectionItems(value, id) });
+  }
+  if (property === "length") {
+    if (!Number.isInteger(value) || value < 0) {
+      throw new TypeError("Graphic collection length must be a non-negative integer.");
+    }
+    const items = owner.items.slice(0, value);
+    for (let index = items.length; index < value; index += 1) {
+      if (owner.type === "collection") {
+        throw new Error("A heterogeneous collection can only grow by replacing its items.");
+      }
+      items.push(freezeOwned({ id: `${id}:${index}`, properties: freezeOwned({}) }));
+    }
+    return freezeOwned({ ...owner, items: freezeOwned(items) });
+  }
+  if (Array.isArray(value) && value.length !== owner.items.length) {
+    throw new Error(
+      `${owner.type}.${property} requires ${owner.items.length} values, received ${value.length}.`
+    );
+  }
+  const items = owner.items.map((item, index) => {
+    const itemValue = Array.isArray(value) ? value[index] : value;
+    const type = item.type ?? owner.type;
+    validateGraphicProperty(type, property);
+    validateConcreteGraphicValue(type, property, itemValue);
+    return freezeOwned({
+      ...item,
+      properties: setGraphicProperty(item.properties, property, itemValue)
+    });
+  });
+  return freezeOwned({ ...owner, items: freezeOwned(items) });
+}
+
+function removeGraphicTree(graphicSpec, id) {
+  if (graphicSpec.objects[id].type === "canvas") {
+    throw new Error("The canvas root cannot be removed.");
+  }
+  const removedIds = new Set(collectGraphicSubtreeIds(graphicSpec, id));
+  const objects = Object.fromEntries(
+    Object.entries(graphicSpec.objects).filter(([objectId]) => !removedIds.has(objectId))
+  );
+  const parent = findGraphicParent(graphicSpec, id);
+  let order = graphicSpec.order;
+  if (parent?.kind === "parent") {
+    objects[parent.id] = freezeOwned({
+      ...objects[parent.id],
+      children: freezeOwned(parent.object.children.filter(childId => childId !== id))
+    });
+  } else {
+    order = freezeOwned(order.filter(objectId => objectId !== id));
+  }
+  return freezeOwned({ objects: freezeOwned(objects), order });
+}
+
+const editGraphics = action(
+  { op: "editGraphics", description: "Replace or remove concrete graphic state." },
+  function ({ target, property, value, remove = false } = {}) {
+    if (typeof target !== "string" || target.length === 0) {
+      throw new TypeError("editGraphics requires a non-empty target string.");
+    }
+    if (typeof remove !== "boolean") throw new TypeError("editGraphics remove must be a boolean.");
+    if (remove && (property !== undefined || value !== undefined)) {
+      throw new Error("editGraphics target removal cannot include property or value.");
+    }
+    if (!remove && value === undefined) throw new TypeError("editGraphics requires a value.");
+
+    const found = requireGraphic(this.graphicSpec, target);
+    if (remove) {
+      if (found.kind === "item") {
+        throw new Error("editGraphics cannot remove a generated item independently.");
+      }
+      return this._clone({ graphicSpec: removeGraphicTree(this.graphicSpec, found.id) });
+    }
+
+    const ownerId = found.kind === "item" ? found.ownerId : found.id;
+    const owner = found.kind === "item" ? found.owner : found.object;
+    const replacesDrawableItems =
+      found.kind === "object" && property === "items" &&
+      owner.items !== undefined && owner.type !== "collection";
+    const validatedProperty = replacesDrawableItems
+      ? "items"
+      : validateGraphicProperty(found.kind === "item"
+          ? (found.object.type ?? owner.type)
+          : owner.type, property);
+    let updated;
+    if (replacesDrawableItems) {
+      updated = replaceDrawableItems(value, ownerId, owner.type);
+    } else if (found.kind === "item") {
+      if (validatedProperty === "length" || validatedProperty === "items") {
+        throw new Error(`${validatedProperty} can only target an owning graphic.`);
+      }
+      updated = editGeneratedItem(owner, found.itemIndex, validatedProperty, value);
+    } else if (isStructuralGraphicType(owner.type)) {
+      validateConcreteGraphicValue(owner.type, validatedProperty, value);
+      updated = freezeOwned({
+        ...owner,
+        properties: setGraphicProperty(owner.properties, validatedProperty, value)
+      });
+    } else if (owner.items !== undefined) {
+      updated = editItems(owner, validatedProperty, value, ownerId);
+    } else if (validatedProperty === "length") {
+      if (!Number.isInteger(value) || value < 0) {
+        throw new TypeError("Graphic collection length must be a non-negative integer.");
+      }
+      updated = freezeOwned({
+        type: owner.type,
+        items: freezeOwned(Array.from({ length: value }, (_, index) => freezeOwned({
+          id: `${ownerId}:${index}`,
+          properties: index === 0 ? owner.properties : freezeOwned({})
+        })))
+      });
+    } else {
+      validateConcreteGraphicValue(owner.type, validatedProperty, value);
+      updated = freezeOwned({
+        ...owner,
+        properties: setGraphicProperty(owner.properties, validatedProperty, value)
+      });
+    }
+    return this._clone({
+      graphicSpec: freezeOwned({
+        ...this.graphicSpec,
+        objects: freezeOwned({ ...this.graphicSpec.objects, [ownerId]: updated })
+      })
+    });
+  }
+);
+
+export function registerEditGraphicsAction(ProgramClass) {
+  ProgramClass.prototype.editGraphics = editGraphics;
+}

package/src/actions/primitives/index.js

@@ -0,0 +1,9 @@
+import { registerCreateGraphicsAction } from "./createGraphics.js";
+import { registerEditGraphicsAction } from "./editGraphics.js";
+import { registerSemanticPrimitiveAction } from "./semantic.js";
+
+export function registerPrimitiveActions(ProgramClass) {
+  registerSemanticPrimitiveAction(ProgramClass);
+  registerCreateGraphicsAction(ProgramClass);
+  registerEditGraphicsAction(ProgramClass);
+}

package/src/actions/primitives/semantic.js

@@ -0,0 +1,168 @@
+import { action } from "../../core/action.js";
+import {
+  cloneAndFreeze,
+  freezeOwned,
+  isPlainObject,
+  removeOwnedPath
+} from "../../core/immutable.js";
+import { parseSemanticPath } from "../../grammar/schemas/semanticPath.js";
+import { validateSemanticValue } from "./semanticValue.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 === "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;
+}
+
+const editSemantic = action(
+  {
+    op: "editSemantic",
+    description: "Create, replace, or remove one semantic property."
+  },
+  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 (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;
+      return this._clone({
+        semanticSpec,
+        ...(clearsCurrentData
+          ? { context: freezeOwned({ ...this.context, currentData: 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 });
+  }
+);
+
+export function registerSemanticPrimitiveAction(ProgramClass) {
+  ProgramClass.prototype.editSemantic = editSemantic;
+}

package/src/actions/primitives/semanticValue.js

@@ -0,0 +1,182 @@
+import { validateUserId } from "../../core/identifiers.js";
+import { isPlainObject } from "../../core/immutable.js";
+import {
+  COLOR_LAYOUTS,
+  STACK_MODES,
+  CATEGORICAL_LEGEND_CHANNELS,
+  MARK_TYPES
+} from "../../core/vocabulary.js";
+import { validateAggregate } from "../../grammar/aggregate.js";
+import { findSemanticScale, hasDataset } from "../../selectors/index.js";
+import { validateCoordinateType } from "../../grammar/coordinates.js";
+import {
+  normalizeHistogramBin,
+  validateHistogramBinBoundaries,
+  validateHistogramBinStep
+} from "../../grammar/histogram.js";
+import { validateDatasetTransforms } from "../../grammar/transforms.js";
+import {
+  validateSemanticFieldType,
+  validateContinuousColorInterpolation,
+  validateScalePropertyForType,
+  validateSemanticScaleDomain,
+  validateSemanticScaleRange,
+  validateSemanticScaleType
+} from "../../grammar/scales.js";
+
+function nonEmptyString(value, label) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError(`${label} must be a non-empty string.`);
+  }
+}
+
+function validateLegend(property, value) {
+  if (property === "title") {
+    nonEmptyString(value, "Legend title");
+    return;
+  }
+  if (!Array.isArray(value) || value.length === 0) {
+    throw new TypeError(`Legend ${property} must be a non-empty array.`);
+  }
+  if (new Set(value).size !== value.length) {
+    throw new Error(`Legend ${property} must not contain duplicates.`);
+  }
+  if (property === "channels") {
+    if (!value.every(channel => CATEGORICAL_LEGEND_CHANNELS.includes(channel))) {
+      throw new Error("Legend channels support only color, strokeDash, and shape.");
+    }
+    return;
+  }
+  for (const id of value) validateUserId(id, "Legend scale id");
+}
+
+export function validateSemanticValue(program, parsed, value) {
+  if (parsed.kind === "dataset" && parsed.path[0] === "values") {
+    if (!Array.isArray(value) || !value.every(isPlainObject)) {
+      throw new TypeError("Dataset values must be an array of plain row objects.");
+    }
+  }
+  if (parsed.kind === "dataset" && parsed.path[0] === "source") {
+    validateUserId(value, "Dataset source id");
+    if (!hasDataset(program, value)) {
+      throw new Error(`Unknown source dataset "${value}".`);
+    }
+  }
+  if (parsed.kind === "dataset" && parsed.path[0] === "transform") {
+    validateDatasetTransforms(value);
+  }
+  if (
+    parsed.kind === "layer" &&
+    parsed.path.join(".") === "mark.type" &&
+    !MARK_TYPES.includes(value)
+  ) {
+    throw new Error(`Unknown mark type "${value}".`);
+  }
+  if (parsed.kind === "layer") {
+    const property = parsed.path.join(".");
+    if (property.endsWith(".title")) {
+      nonEmptyString(value, "Encoding title");
+    }
+    if (property.endsWith(".fieldType")) validateSemanticFieldType(value);
+    if (property.endsWith(".aggregate")) validateAggregate(value);
+    if (property.endsWith(".bin.maxBins")) normalizeHistogramBin({ maxBins: value });
+    if (property.endsWith(".bin.step")) validateHistogramBinStep(value);
+    if (property.endsWith(".bin.boundaries")) {
+      validateHistogramBinBoundaries(value);
+    }
+    if (
+      property.endsWith(".stack") &&
+      value !== null &&
+      !STACK_MODES.includes(value)
+    ) {
+      throw new Error(`Unsupported stack "${value}".`);
+    }
+    if (
+      property === "encoding.color.layout" &&
+      !COLOR_LAYOUTS.includes(value)
+    ) {
+      throw new Error(`Unsupported color layout "${value}".`);
+    }
+  }
+  if (parsed.kind === "scale") {
+    const property = parsed.path.join(".");
+    const existing = findSemanticScale(program, parsed.id);
+    if (property === "type") {
+      validateSemanticScaleType(value);
+      for (const owned of [
+        "nice", "zero", "clamp", "base", "exponent", "constant",
+        "paddingInner", "paddingOuter", "padding", "align"
+      ]) {
+        if (existing?.[owned] !== undefined) {
+          validateScalePropertyForType(value, owned);
+        }
+      }
+    } else if (property === "domain") validateSemanticScaleDomain(value);
+    else if (property === "range") validateSemanticScaleRange(value);
+    else if (property === "nice") {
+      if (typeof value !== "boolean") throw new TypeError("Scale nice must be a boolean.");
+      if (existing?.type !== undefined) {
+        validateScalePropertyForType(existing.type, "nice");
+      }
+    } else if (property === "zero") {
+      if (typeof value !== "boolean") throw new TypeError("Scale zero must be a boolean.");
+      if (existing?.type !== undefined) {
+        validateScalePropertyForType(existing.type, "zero");
+      }
+    } else if (property === "clamp") {
+      if (typeof value !== "boolean") throw new TypeError("Scale clamp must be a boolean.");
+      if (existing?.type !== undefined) {
+        validateScalePropertyForType(existing.type, "clamp");
+      }
+    } else if (property === "reverse") {
+      if (typeof value !== "boolean") throw new TypeError("Scale reverse must be a boolean.");
+    } else if (["base", "exponent", "constant"].includes(property)) {
+      if (!Number.isFinite(value) || value <= 0) {
+        throw new RangeError(`Scale ${property} must be a positive finite number.`);
+      }
+      if (property === "base" && value === 1) {
+        throw new RangeError("Scale base must not equal 1.");
+      }
+      if (existing?.type !== undefined) {
+        validateScalePropertyForType(existing.type, property);
+      }
+    } else if (property === "interpolate") {
+      validateContinuousColorInterpolation(value);
+    } else if (property === "paddingInner") {
+      if (!Number.isFinite(value) || value < 0 || value >= 1) {
+        throw new RangeError(
+          "Scale paddingInner must be from 0 (inclusive) to 1 (exclusive)."
+        );
+      }
+      if (existing?.type !== undefined) {
+        validateScalePropertyForType(existing.type, property);
+      }
+    } else if (property === "paddingOuter" || property === "padding") {
+      if (!Number.isFinite(value) || value < 0) {
+        throw new RangeError(`Scale ${property} must be a non-negative finite number.`);
+      }
+      if (existing?.type !== undefined) {
+        validateScalePropertyForType(existing.type, property);
+      }
+    } else if (property === "align") {
+      if (!Number.isFinite(value) || value < 0 || value > 1) {
+        throw new RangeError("Scale align must be between 0 and 1.");
+      }
+      if (existing?.type !== undefined) {
+        validateScalePropertyForType(existing.type, property);
+      }
+    }
+  }
+  if (parsed.kind === "coordinate" && parsed.path[0] === "type") {
+    validateCoordinateType(value);
+  }
+  if (parsed.kind === "guide" && parsed.id === "legend.series") {
+    validateLegend(parsed.path.at(-1), value);
+  }
+  if (parsed.kind === "guide" && parsed.id.startsWith("grid.")) {
+    validateUserId(value, `Grid ${parsed.path.at(-1)} id`);
+  }
+  if (parsed.kind === "title") {
+    nonEmptyString(value, `Chart title ${parsed.path[0]}`);
+  }
+}