ggaction 0.0.4 → 0.0.6

package/src/actions/encodings/parallel.js

@@ -0,0 +1,115 @@
+import { action } from "../../core/action.js";
+import { validateOptionObject } from "../../core/validation.js";
+import {
+  normalizeParallelDimensions,
+  validateParallelKeyField,
+  validateParallelMissingPolicy,
+  validateParallelRows
+} from "../../grammar/parallelCoordinates.js";
+import { resolvePositionScaleDefinition } from "../scales/definitions.js";
+import { applyEncodingScale, resolveTarget } from "./shared.js";
+import { resolveParallelCoordinate } from "../coordinates/parallel.js";
+
+const OPTIONS = Object.freeze([
+  "target", "coordinate", "dimensions", "key", "missing"
+]);
+
+export const encodeParallelCoordinates = action(
+  {
+    op: "encodeParallelCoordinates",
+    description: "Atomically encode ordered Parallel-coordinate dimensions."
+  },
+  function (args = {}) {
+    validateOptionObject(args, OPTIONS, "encodeParallelCoordinates");
+    const { id: target, dataset, layer } = resolveTarget(
+      this,
+      args.target,
+      ["line"],
+      "line mark"
+    );
+    if (
+      ["x", "y", "theta", "radius"].some(
+        channel => layer.encoding?.[channel] !== undefined
+      )
+    ) {
+      throw new Error(
+        `Parallel encoding cannot mix with existing position encodings on layer "${target}".`
+      );
+    }
+    const coordinate = resolveParallelCoordinate(this, {
+      requested: args.coordinate,
+      layer,
+      operation: "encodeParallelCoordinates"
+    });
+    const dimensions = normalizeParallelDimensions(
+      dataset.values,
+      args.dimensions,
+      target
+    );
+    const key = args.key === undefined
+      ? undefined
+      : validateParallelKeyField(args.key);
+    const missing = validateParallelMissingPolicy(args.missing ?? "break");
+    validateParallelRows(dataset.values, dimensions, { key, missing });
+
+    const definitions = dimensions.map(dimension =>
+      resolvePositionScaleDefinition(
+        this,
+        "y",
+        dimension.fieldType,
+        { ...dimension.scaleOptions, id: dimension.scale },
+        dimension.fieldType === "ordinal" ? { discreteType: "point" } : {}
+      )
+    );
+    const storedDimensions = dimensions.map(({ scaleOptions, ...dimension }) => {
+      void scaleOptions;
+      return dimension;
+    });
+
+    let next = this;
+    if (coordinate.create) {
+      next = next.createCoordinate({ id: coordinate.id, type: "parallel" });
+    }
+    if (layer.coordinate === undefined) {
+      next = next.editSemantic({
+        property: `layer[${target}].coordinate`,
+        value: coordinate.id
+      });
+    }
+    next = next
+      .editSemantic({
+        property: `layer[${target}].encoding.parallel.dimensions`,
+        value: storedDimensions
+      })
+      .editSemantic({
+        property: `layer[${target}].encoding.parallel.missing`,
+        value: missing
+      });
+    if (key === undefined && layer.encoding?.parallel?.key !== undefined) {
+      next = next.editSemantic({
+        property: `layer[${target}].encoding.parallel.key`,
+        remove: true
+      });
+    } else if (key !== undefined) {
+      next = next.editSemantic({
+        property: `layer[${target}].encoding.parallel.key`,
+        value: key
+      });
+    }
+    for (let index = 0; index < definitions.length; index += 1) {
+      next = applyEncodingScale(next, definitions[index], dimensions[index].scaleOptions);
+    }
+    for (const definition of definitions) {
+      next = next.rematerializeScale({
+        id: definition.id,
+        guides: false,
+        marks: false
+      });
+    }
+    return next.rematerializeLineMark({ id: target, scales: false });
+  }
+);
+
+export function registerParallelEncodingAction(ProgramClass) {
+  ProgramClass.prototype.encodeParallelCoordinates = encodeParallelCoordinates;
+}

package/src/actions/encodings/pathOrder.js

@@ -0,0 +1,131 @@
+import { action } from "../../core/action.js";
+import { validateUserId } from "../../core/identifiers.js";
+import {
+  validateNonEmptyString,
+  validateOptionObject
+} from "../../core/validation.js";
+import { readQuantitativeField } from "../../grammar/scales/index.js";
+import { validatePathOrderDirection } from "../../grammar/pathOrder.js";
+import {
+  assertPathOrderCompatible,
+  pathOrderCompatibility
+} from "../../materialization/marks/pathOrder.js";
+import {
+  canMaterializeArea,
+  canMaterializeLine
+} from "../../materialization/marks/index.js";
+import { findLayer } from "../../selectors/layers.js";
+
+const ENCODE_OPTIONS = Object.freeze([
+  "target", "field", "fieldType", "order"
+]);
+const REMOVE_OPTIONS = Object.freeze(["target"]);
+
+function resolvePathOrderLayer(program, target, { active = false } = {}) {
+  const requested = target === undefined
+    ? undefined
+    : validateUserId(target, "Path order target");
+  if (requested !== undefined) {
+    const layer = findLayer(program, requested);
+    if (layer === undefined) {
+      throw new Error(`Unknown path order target "${requested}".`);
+    }
+    if (active && layer.encoding?.pathOrder === undefined) {
+      throw new Error(`Mark "${requested}" has no path order encoding.`);
+    }
+    assertPathOrderCompatible(
+      program,
+      layer,
+      active ? "removePathOrder" : "encodePathOrder"
+    );
+    return layer;
+  }
+  const pathLayers = program.semanticSpec.layers.filter(layer =>
+    ["line", "area"].includes(layer.mark?.type)
+  );
+  const candidates = pathLayers.filter(layer =>
+    pathOrderCompatibility(program, layer).compatible &&
+    (!active || layer.encoding?.pathOrder !== undefined)
+  );
+  const current = candidates.find(
+    layer => layer.id === program.context.currentMark
+  );
+  if (current !== undefined) return current;
+  if (candidates.length === 1) return candidates[0];
+  if (candidates.length > 1) {
+    throw new Error("path order target is ambiguous; provide target.");
+  }
+  if (!active && pathLayers.length === 1) {
+    assertPathOrderCompatible(program, pathLayers[0], "encodePathOrder");
+  }
+  if (active && pathLayers.length === 1) {
+    throw new Error(`Mark "${pathLayers[0].id}" has no path order encoding.`);
+  }
+  throw new Error("path order requires an eligible layer.");
+}
+
+function rematerializePath(program, layer) {
+  if (layer.mark.type === "line") {
+    return canMaterializeLine(program, layer)
+      ? program.rematerializeLineMark({ id: layer.id })
+      : program;
+  }
+  return canMaterializeArea(program, layer)
+    ? program.rematerializeAreaMark({ id: layer.id })
+    : program;
+}
+
+const encodePathOrder = action(
+  {
+    op: "encodePathOrder",
+    description: "Order vertices within each Cartesian path series."
+  },
+  function (args = {}) {
+    validateOptionObject(args, ENCODE_OPTIONS, "encodePathOrder");
+    const field = validateNonEmptyString(args.field, "Path order field");
+    const fieldType = args.fieldType ?? "quantitative";
+    if (fieldType !== "quantitative") {
+      throw new Error("encodePathOrder requires a quantitative field.");
+    }
+    const order = validatePathOrderDirection(args.order ?? "ascending");
+    const layer = resolvePathOrderLayer(this, args.target);
+    const dataset = assertPathOrderCompatible(this, layer, "encodePathOrder");
+    readQuantitativeField(dataset.values, field);
+
+    const next = this
+      .editSemantic({
+        property: `layer[${layer.id}].encoding.pathOrder.field`,
+        value: field
+      })
+      .editSemantic({
+        property: `layer[${layer.id}].encoding.pathOrder.fieldType`,
+        value: fieldType
+      })
+      .editSemantic({
+        property: `layer[${layer.id}].encoding.pathOrder.order`,
+        value: order
+      });
+    return rematerializePath(next, findLayer(next, layer.id));
+  }
+);
+
+const removePathOrder = action(
+  {
+    op: "removePathOrder",
+    description: "Remove explicit path order and restore automatic ordering."
+  },
+  function (args = {}) {
+    validateOptionObject(args, REMOVE_OPTIONS, "removePathOrder");
+    const layer = resolvePathOrderLayer(this, args.target, { active: true });
+    const next = this.editSemantic({
+      property: `layer[${layer.id}].encoding.pathOrder`,
+      remove: true
+    });
+    return rematerializePath(next, findLayer(next, layer.id));
+  }
+);
+
+export function registerPathOrderEncodingActions(ProgramClass) {
+  ProgramClass.prototype.encodePathOrder = encodePathOrder;
+  ProgramClass.prototype.removePathOrder = removePathOrder;
+}

package/src/actions/encodings/position/apply.js

@@ -9,6 +9,44 @@ function replaceAlternateBinding(program, target, channel, previous, usesField)
     : program;
 }
 
+function reconcileInheritedRulePosition(program, {
+  target,
+  channel,
+  layer,
+  hasField
+}) {
+  const config = program.markConfigs[target] ?? {};
+  const inherited = config.inheritedPosition;
+  if (layer.mark.type !== "rule" || inherited === undefined) return program;
+
+  let channels = inherited.channels.filter(candidate => candidate !== channel);
+  let next = program;
+  if (
+    !hasField &&
+    ["x", "y"].includes(channel) &&
+    layer.encoding?.x2 === undefined &&
+    layer.encoding?.y2 === undefined
+  ) {
+    const opposite = channel === "x" ? "y" : "x";
+    if (channels.includes(opposite) && layer.encoding?.[opposite] !== undefined) {
+      next = next.editSemantic({
+        property: `layer[${target}].encoding.${opposite}`,
+        remove: true
+      });
+      channels = channels.filter(candidate => candidate !== opposite);
+    }
+  }
+
+  const { inheritedPosition, ...rest } = config;
+  void inheritedPosition;
+  return next._withMarkConfig(target, channels.length === 0
+    ? rest
+    : {
+        ...rest,
+        inheritedPosition: { ...inherited, channels }
+      });
+}
+
 function applyBin(program, target, channel, previous, bin) {
   if (bin === undefined) return program;
   const [mode] = Object.keys(bin);
@@ -26,9 +64,26 @@ function applyBin(program, target, channel, previous, bin) {
   });
 }
 
+function applyArcThetaWeight(program, target, channel, previous, aggregate, weight) {
+  if (channel !== "theta") return program;
+  if (aggregate !== "sum") {
+    return previous?.weight === undefined
+      ? program
+      : program.editSemantic({
+          property: `layer[${target}].encoding.theta.weight`,
+          remove: true
+        });
+  }
+  return program.editSemantic({
+    property: `layer[${target}].encoding.theta.weight`,
+    value: weight
+  });
+}
+
 export function applyPositionSemantics(program, {
   target,
   channel,
+  layer,
   previous,
   field,
   datum,
@@ -36,10 +91,17 @@ export function applyPositionSemantics(program, {
   fieldType,
   bin,
   aggregate,
-  stack
+  stack,
+  weight
 }) {
-  let next = replaceAlternateBinding(
-    program,
+  let next = reconcileInheritedRulePosition(program, {
+    target,
+    channel,
+    layer,
+    hasField
+  });
+  next = replaceAlternateBinding(
+    next,
     target,
     channel,
     previous,
@@ -62,5 +124,12 @@ export function applyPositionSemantics(program, {
       value
     });
   }
-  return next;
+  return applyArcThetaWeight(
+    next,
+    target,
+    channel,
+    previous,
+    aggregate,
+    weight
+  );
 }

package/src/actions/encodings/position/index.js

@@ -24,7 +24,8 @@ function encodePosition(program, channel, args, operation) {
     coordinate,
     bin,
     aggregate,
-    stack
+    stack,
+    weight
   } = resolvePositionEncoding(program, channel, args, operation);
 
   let next = program
@@ -36,6 +37,7 @@ function encodePosition(program, channel, args, operation) {
   next = applyPositionSemantics(next, {
     target,
     channel,
+    layer,
     previous,
     field,
     datum,
@@ -43,7 +45,8 @@ function encodePosition(program, channel, args, operation) {
     fieldType,
     bin,
     aggregate,
-    stack
+    stack,
+    weight
   });
 
   next = next.editSemantic({
@@ -71,6 +74,16 @@ function encodePosition(program, channel, args, operation) {
     }
   }
 
+  if (layer.mark.type === "rect") {
+    const updated = findLayer(next, target);
+    const pendingGradient = next.markConfigs[target]?.gradientPlot;
+    if (pendingGradient !== undefined && !pendingGradient.materialized) {
+      return updated.encoding?.x !== undefined && updated.encoding?.y !== undefined
+        ? next.materializeGradientPlot({ id: target })
+        : next;
+    }
+  }
+
   const updated = findLayer(next, target);
   for (const step of getPositionEncodingMaterializationSteps(
     next,

package/src/actions/encodings/position/policies/arc.js

@@ -1,4 +1,5 @@
 import { validateAggregate } from "../../../../grammar/aggregate.js";
+import { validateNonEmptyString } from "../../../../core/validation.js";
 import { emptyPositionPolicy } from "./common.js";
 
 export function resolveArcPositionPolicy({ channel, args, fieldType }) {
@@ -12,15 +13,37 @@ export function resolveArcPositionPolicy({ channel, args, fieldType }) {
     if (args.aggregate !== undefined) {
       throw new Error("Arc radius encoding does not support aggregate.");
     }
+    if (args.weight !== undefined) {
+      throw new Error("Arc radius encoding does not support weight.");
+    }
     return emptyPositionPolicy();
   }
   if (!["ordinal", "nominal"].includes(fieldType)) {
     throw new Error("Arc theta encoding requires an ordinal or nominal field.");
   }
-  if (args.aggregate === undefined) return emptyPositionPolicy();
+  if (args.aggregate === undefined) {
+    if (args.weight !== undefined) {
+      throw new Error('Arc theta weight requires aggregate: "sum".');
+    }
+    return emptyPositionPolicy();
+  }
   const aggregate = validateAggregate(args.aggregate);
-  if (aggregate !== "count") {
-    throw new Error('Arc theta aggregate currently supports only "count".');
+  if (!["count", "sum"].includes(aggregate)) {
+    throw new Error('Arc theta aggregate supports only "count" or "sum".');
+  }
+  if (aggregate === "count") {
+    if (args.weight !== undefined) {
+      throw new Error('Arc theta weight requires aggregate: "sum".');
+    }
+    return { bin: undefined, aggregate, stack: undefined, weight: undefined };
+  }
+  if (args.weight === undefined) {
+    throw new Error('Arc theta aggregate "sum" requires weight.');
   }
-  return { bin: undefined, aggregate, stack: undefined };
+  return {
+    bin: undefined,
+    aggregate,
+    stack: undefined,
+    weight: validateNonEmptyString(args.weight, "Arc theta weight")
+  };
 }

package/src/actions/encodings/position/policies/area.js

@@ -1,6 +1,37 @@
 import { validateStack, emptyPositionPolicy } from "./common.js";
 
-export function resolveAreaPositionPolicy({ dataset, channel, args, fieldType }) {
+export function isCategoricalDensityPosition({
+  layer,
+  dataset,
+  channel,
+  fieldType,
+  field
+}) {
+  const density = dataset.transform?.find(transform => transform.type === "density");
+  return layer.mark?.type === "area" &&
+    ["nominal", "ordinal"].includes(fieldType) &&
+    density?.placement?.type === "category" &&
+    density.placement.channel === channel &&
+    density.placement.categoryField === field;
+}
+
+export function resolveAreaPositionPolicy({ dataset, channel, args, fieldType, field }) {
+  const density = dataset.transform?.find(transform => transform.type === "density");
+  if (["nominal", "ordinal"].includes(fieldType)) {
+    if (
+      density?.placement?.type !== "category" ||
+      density.placement.channel !== channel ||
+      density.placement.categoryField !== field
+    ) {
+      throw new Error(
+        "Categorical area position requires a matching category density placement."
+      );
+    }
+    if (args.aggregate !== undefined || args.bin !== undefined || args.stack !== undefined) {
+      throw new Error("Categorical density position does not support aggregate, bin, or stack.");
+    }
+    return emptyPositionPolicy();
+  }
   if (!["quantitative", "temporal"].includes(fieldType)) {
     throw new Error(
       "Area position encoding requires quantitative or temporal fields."
@@ -12,7 +43,7 @@ export function resolveAreaPositionPolicy({ dataset, channel, args, fieldType })
   if (args.stack === undefined) return emptyPositionPolicy();
   if (
     channel !== "y" ||
-    !dataset.transform?.some(transform => transform.type === "density")
+    density === undefined
   ) {
     throw new Error("Area stack currently requires a density y encoding.");
   }

package/src/actions/encodings/position/policies/index.js

@@ -1,6 +1,9 @@
 import { validatePositionFieldCompatibility } from
   "../../../../grammar/positionCompatibility.js";
-import { resolveAreaPositionPolicy } from "./area.js";
+import {
+  isCategoricalDensityPosition,
+  resolveAreaPositionPolicy
+} from "./area.js";
 import { resolveArcPositionPolicy } from "./arc.js";
 import { resolveBarPositionPolicy } from "./bar.js";
 import { resolveLinePositionPolicy } from "./line.js";
@@ -20,7 +23,9 @@ const POSITION_POLICIES = Object.freeze({
 
 export function resolveMarkPositionPolicy(context) {
   const { layer, channel, fieldType } = context;
-  validatePositionFieldCompatibility(layer.mark.type, channel, fieldType);
+  if (!isCategoricalDensityPosition(context)) {
+    validatePositionFieldCompatibility(layer.mark.type, channel, fieldType);
+  }
   const policy = POSITION_POLICIES[layer.mark.type];
   if (policy === undefined) {
     throw new Error(`Unsupported position policy for mark "${layer.mark.type}".`);

package/src/actions/encodings/position/policies/line.js

@@ -44,9 +44,14 @@ export function resolveLinePositionPolicy({
       layer.encoding?.y?.aggregate === undefined &&
       ["quantitative", "temporal"].includes(layer.encoding?.y?.fieldType) &&
       fieldType === "quantitative";
+    const pendingQuantitativePair =
+      layer.encoding?.y === undefined && fieldType === "quantitative";
     if (
       fieldType !== "temporal" &&
-      !((regression || interval || directPair) && fieldType === "quantitative")
+      !(
+        (regression || interval || directPair || pendingQuantitativePair) &&
+        fieldType === "quantitative"
+      )
     ) {
       throw new Error(
         "Line x encoding requires a temporal field or a compatible derived quantitative field."
@@ -60,10 +65,14 @@ export function resolveLinePositionPolicy({
   }
 
   rejectSharedOptions(args, "y");
+  const quantitativePair =
+    fieldType === "quantitative" &&
+    layer.encoding?.x?.fieldType === "quantitative";
   const prospectiveDirect =
     args.aggregate === undefined &&
     (fieldType === "temporal" ||
-      (fieldType === "quantitative" && layer.encoding?.x === undefined));
+      (fieldType === "quantitative" &&
+        (layer.encoding?.x === undefined || quantitativePair)));
   if (interval || prospectiveDirect) {
     if (!["quantitative", "temporal"].includes(fieldType)) {
       throw new Error(
@@ -85,6 +94,13 @@ export function resolveLinePositionPolicy({
     return emptyPositionPolicy();
   }
 
+  if (
+    layer.encoding?.x !== undefined &&
+    layer.encoding.x.fieldType !== "temporal"
+  ) {
+    throw new Error("Aggregate line y encoding requires a temporal x encoding.");
+  }
+
   const aggregate = validateAggregate(args.aggregate);
   validateAggregateFieldType(aggregate, fieldType);
   return { bin: undefined, aggregate, stack: undefined };

package/src/actions/encodings/position/resolve.js

@@ -21,6 +21,7 @@ import {
   validateAggregateFieldValues,
 } from "../../../grammar/aggregate.js";
 import { normalizeRuleDatum } from "../../../grammar/rules.js";
+import { readArcThetaWeights } from "../../../grammar/arcs.js";
 import { resolveMarkPositionPolicy } from "./policies/index.js";
 import {
   getPositionChannelDefinition,
@@ -29,7 +30,7 @@ import {
 
 const POSITION_ENCODING_OPTIONS = Object.freeze([
   "field", "datum", "target", "fieldType", "scale", "coordinate",
-  "aggregate", "bin", "stack"
+  "aggregate", "bin", "stack", "weight"
 ]);
 
 function validateCoordinateFamily(layer, channel, operation) {
@@ -82,6 +83,12 @@ export function resolvePositionEncoding(program, channel, args, operation) {
     args.target,
     getPositionChannelDefinition(channel).markTypes
   );
+  if (
+    Object.hasOwn(args, "weight") &&
+    !(layer.mark.type === "arc" && channel === "theta")
+  ) {
+    throw new Error(`${operation} weight is supported only for arc theta encoding.`);
+  }
   validateCoordinateFamily(layer, channel, operation);
   const hasField = Object.hasOwn(args, "field");
   const hasDatum = Object.hasOwn(args, "datum");
@@ -97,7 +104,8 @@ export function resolvePositionEncoding(program, channel, args, operation) {
   }
   const previous = layer.encoding?.[channel];
   const requestedFieldType = args.fieldType ?? previous?.fieldType ?? (
-    layer.mark.type === "arc" && channel === "theta" && args.aggregate === "count"
+    layer.mark.type === "arc" && channel === "theta" &&
+      ["count", "sum"].includes(args.aggregate)
       ? "nominal"
       : "quantitative"
   );
@@ -117,6 +125,14 @@ export function resolvePositionEncoding(program, channel, args, operation) {
       effectiveArgs[property] = previous[property];
     }
   }
+  if (
+    !Object.hasOwn(effectiveArgs, "weight") &&
+    effectiveArgs.aggregate === "sum" &&
+    previous !== undefined &&
+    Object.hasOwn(previous, "weight")
+  ) {
+    effectiveArgs.weight = previous.weight;
+  }
   const policy = resolveMarkPositionPolicy({
     program,
     layer,
@@ -179,6 +195,12 @@ export function resolvePositionEncoding(program, channel, args, operation) {
   } else if (aggregateOutput) {
     validateAggregateFieldType(policy.aggregate, fieldType);
     validateAggregateFieldValues(dataset.values, field, fieldType);
+  } else if (
+    layer.mark.type === "arc" &&
+    channel === "theta" &&
+    policy.aggregate === "sum"
+  ) {
+    readArcThetaWeights(dataset.values, policy.weight, layer.id);
   } else if (program.markConfigs[target]?.boxPlot !== undefined) {
     for (const [index, row] of dataset.values.entries()) {
       const value = row[field];

package/src/actions/encodings/ranged.js

@@ -157,7 +157,9 @@ function encodeSecondaryPosition(program, channel, args, operation, types) {
     ? next.rematerializeBarMark({ id: target })
     : layer.mark.type === "rect"
       ? next.rematerializeRectMark({ id: target })
-      : next.rematerializeAreaMark({ id: target });
+      : canMaterializeArea(next, findLayer(next, target))
+        ? next.rematerializeAreaMark({ id: target })
+        : next;
 }
 
 const encodeX2 = action(