ggaction 0.0.2 → 0.0.3

package/src/actions/encodings/offset.js

@@ -1,7 +1,7 @@
 import { action } from "../../core/action.js";
 import {
   readNominalField,
-  validateNominalFieldType
+  validateCategoricalFieldType
 } from "../../grammar/scales.js";
 import { resolveOffsetScaleDefinition } from "../scales/definitions.js";
 import {
@@ -12,6 +12,7 @@ import {
 } from "./shared.js";
 import {
   resolveBarColorLayout,
+  resolveBarChannels,
   resolveBarGrain
 } from "../../grammar/bars/policy.js";
 import { normalizeOffsetPadding } from "../../grammar/bars/geometry.js";
@@ -21,84 +22,101 @@ import { planEncodingRematerialization } from "../../materialization/encodings.j
 const ENCODING_OPTIONS = Object.freeze([
   "field", "target", "fieldType", "scale", "paddingInner", "paddingOuter"
 ]);
-const encodeXOffset = action(
-  {
-    op: "encodeXOffset",
-    description: "Encode a nominal field within each ordinal x band."
-  },
-  function (args = {}) {
-    validateOptions(args, ENCODING_OPTIONS, "encodeXOffset");
-    const fieldType = validateNominalFieldType(args.fieldType ?? "nominal");
-    const { id: target, dataset, layer } = resolveTarget(
-      this,
-      args.target,
-      ["bar"],
-      "bar mark"
-    );
+function createOffsetEncoding(channel) {
+  const operation = channel === "xOffset" ? "encodeXOffset" : "encodeYOffset";
+  const parentChannel = channel === "xOffset" ? "x" : "y";
+  return action(
+    {
+      op: operation,
+      description: `Encode a categorical field within each ${parentChannel} category band.`
+    },
+    function (args = {}) {
+      validateOptions(args, ENCODING_OPTIONS, operation);
+      const fieldType = validateCategoricalFieldType(args.fieldType ?? "nominal");
+      const { id: target, dataset, layer } = resolveTarget(
+        this,
+        args.target,
+        ["bar"],
+        "bar mark"
+      );
+
+      const channels = resolveBarChannels(layer);
+      if (
+        resolveBarGrain(layer) === undefined ||
+        channels?.category !== parentChannel
+      ) {
+        throw new Error(
+          `${operation} requires a complete bar with a ${parentChannel} category encoding.`
+        );
+      }
+      if (
+        layer.encoding?.color !== undefined &&
+        (resolveBarColorLayout(layer) !== "group" ||
+          layer.encoding.color.field !== args.field)
+      ) {
+        throw new Error(
+          `${operation} field must match a grouped bar color field.`
+        );
+      }
 
-    if (
-      resolveBarGrain(layer) === undefined ||
-      layer.encoding.x.scale === undefined
-    ) {
-      throw new Error(
-        "encodeXOffset requires a complete bar x/y encoding."
+      readNominalField(dataset.values, args.field);
+      const requestedScale = resolveReassignmentScaleOptions(
+        layer.encoding?.[channel],
+        args.scale ?? {}
       );
-    }
-    if (
-      layer.encoding?.color !== undefined &&
-      (resolveBarColorLayout(layer) !== "group" ||
-        layer.encoding.color.field !== args.field)
-    ) {
-      throw new Error(
-        "encodeXOffset field must match a grouped bar color field."
+      const scale = resolveOffsetScaleDefinition(this, requestedScale, channel);
+      if (Object.hasOwn(scale, "unknown")) {
+        throw new Error(
+          `${channel} scale unknown is not supported for grouped bars.`
+        );
+      }
+      const padding = normalizeOffsetPadding(
+        args,
+        this.markConfigs[target]?.[channel],
+        channel
       );
-    }
 
-    readNominalField(dataset.values, args.field);
-    const requestedScale = resolveReassignmentScaleOptions(
-      layer.encoding?.xOffset,
-      args.scale ?? {}
-    );
-    const scale = resolveOffsetScaleDefinition(this, requestedScale);
-    if (Object.hasOwn(scale, "unknown")) {
-      throw new Error("xOffset scale unknown is not supported for grouped bars.");
+      let next = this
+        .editSemantic({
+          property: `layer[${target}].encoding.${channel}.field`,
+          value: args.field
+        })
+        .editSemantic({
+          property: `layer[${target}].encoding.${channel}.fieldType`,
+          value: fieldType
+        })
+        .editSemantic({
+          property: `layer[${target}].encoding.${channel}.scale`,
+          value: scale.id
+        })
+        ._withMarkConfig(target, {
+          ...this.markConfigs[target],
+          [channel]: padding
+        });
+      next = applyEncodingScale(next, scale, requestedScale, {
+        reassignment: layer.encoding?.[channel]?.scale === scale.id
+      });
+      if (layer.encoding?.color === undefined) {
+        return next
+          .rematerializeScale({ id: scale.id })
+          .editGraphics({ target, property: "length", value: 0 });
+      }
+      return applyMaterializationPlan(
+        next,
+        planEncodingRematerialization(next, {
+          target,
+          channel,
+          scale: scale.id
+        })
+      );
     }
-    const padding = normalizeOffsetPadding(
-      args,
-      this.markConfigs[target]?.xOffset
-    );
+  );
+}
 
-    let next = this
-      .editSemantic({
-        property: `layer[${target}].encoding.xOffset.field`,
-        value: args.field
-      })
-      .editSemantic({
-        property: `layer[${target}].encoding.xOffset.fieldType`,
-        value: fieldType
-      })
-      .editSemantic({
-        property: `layer[${target}].encoding.xOffset.scale`,
-        value: scale.id
-      })
-      ._withMarkConfig(target, {
-        ...this.markConfigs[target],
-        xOffset: padding
-      });
-    next = applyEncodingScale(next, scale, requestedScale, {
-      reassignment: layer.encoding?.xOffset?.scale === scale.id
-    });
-    return applyMaterializationPlan(
-      next,
-      planEncodingRematerialization(next, {
-        target,
-        channel: "xOffset",
-        scale: scale.id
-      })
-    );
-  }
-);
+const encodeXOffset = createOffsetEncoding("xOffset");
+const encodeYOffset = createOffsetEncoding("yOffset");
 
 export function registerOffsetEncodingAction(ProgramClass) {
   ProgramClass.prototype.encodeXOffset = encodeXOffset;
+  ProgramClass.prototype.encodeYOffset = encodeYOffset;
 }

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

@@ -0,0 +1,66 @@
+function replaceAlternateBinding(program, target, channel, previous, usesField) {
+  if (previous === undefined) return program;
+  const alternate = usesField ? "datum" : "field";
+  return Object.hasOwn(previous, alternate)
+    ? program.editSemantic({
+        property: `layer[${target}].encoding.${channel}.${alternate}`,
+        remove: true
+      })
+    : program;
+}
+
+function applyBin(program, target, channel, previous, bin) {
+  if (bin === undefined) return program;
+  const [mode] = Object.keys(bin);
+  let next = program;
+  for (const previousMode of Object.keys(previous?.bin ?? {})) {
+    if (previousMode === mode) continue;
+    next = next.editSemantic({
+      property: `layer[${target}].encoding.${channel}.bin.${previousMode}`,
+      remove: true
+    });
+  }
+  return next.editSemantic({
+    property: `layer[${target}].encoding.${channel}.bin.${mode}`,
+    value: bin[mode]
+  });
+}
+
+export function applyPositionSemantics(program, {
+  target,
+  channel,
+  previous,
+  field,
+  datum,
+  hasField,
+  fieldType,
+  bin,
+  aggregate,
+  stack
+}) {
+  let next = replaceAlternateBinding(
+    program,
+    target,
+    channel,
+    previous,
+    hasField
+  )
+    .editSemantic({
+      property: `layer[${target}].encoding.${channel}.${hasField ? "field" : "datum"}`,
+      value: hasField ? field : datum
+    })
+    .editSemantic({
+      property: `layer[${target}].encoding.${channel}.fieldType`,
+      value: fieldType
+    });
+
+  next = applyBin(next, target, channel, previous, bin);
+  for (const [property, value] of Object.entries({ aggregate, stack })) {
+    if (value === undefined) continue;
+    next = next.editSemantic({
+      property: `layer[${target}].encoding.${channel}.${property}`,
+      value
+    });
+  }
+  return next;
+}

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

@@ -0,0 +1,26 @@
+import { validateAggregate } from "../../../../grammar/aggregate.js";
+import { emptyPositionPolicy } from "./common.js";
+
+export function resolveArcPositionPolicy({ channel, args, fieldType }) {
+  if (args.bin !== undefined) {
+    throw new Error(`Arc ${channel} encoding does not support bin.`);
+  }
+  if (args.stack !== undefined) {
+    throw new Error(`Arc ${channel} encoding does not support stack.`);
+  }
+  if (channel === "radius") {
+    if (args.aggregate !== undefined) {
+      throw new Error("Arc radius encoding does not support aggregate.");
+    }
+    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();
+  const aggregate = validateAggregate(args.aggregate);
+  if (aggregate !== "count") {
+    throw new Error('Arc theta aggregate currently supports only "count".');
+  }
+  return { bin: undefined, aggregate, stack: undefined };
+}

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

@@ -4,6 +4,7 @@ import {
 } from "../../../../grammar/aggregate.js";
 import {
   BAR_ORIENTATIONS,
+  resolveBarOffsetChannel,
   resolveBarOrientation
 } from "../../../../grammar/bars/policy.js";
 import { resolveBin, validateStack } from "./common.js";
@@ -98,12 +99,15 @@ export function resolveBarPositionPolicy({
       `Bar ${channel} encoding requires a quantitative field opposite a categorical position.`
     );
   }
-  if (
-    orientation === BAR_ORIENTATIONS.horizontal &&
-    candidate.encoding?.xOffset !== undefined
-  ) {
+  const expectedOffset = resolveBarOffsetChannel(candidate);
+  const incompatibleOffset = orientation === BAR_ORIENTATIONS.horizontal
+    ? "xOffset"
+    : orientation === BAR_ORIENTATIONS.vertical
+      ? "yOffset"
+      : undefined;
+  if (incompatibleOffset !== undefined && candidate.encoding?.[incompatibleOffset] !== undefined) {
     throw new Error(
-      "Horizontal grouped bars require yOffset support, which is not available yet."
+      `${orientation} bars require ${expectedOffset}; remove the incompatible ${incompatibleOffset} encoding.`
     );
   }
   return { bin, aggregate, stack };

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

@@ -1,6 +1,7 @@
 import { validatePositionFieldCompatibility } from
   "../../../../grammar/positionCompatibility.js";
 import { resolveAreaPositionPolicy } from "./area.js";
+import { resolveArcPositionPolicy } from "./arc.js";
 import { resolveBarPositionPolicy } from "./bar.js";
 import { resolveLinePositionPolicy } from "./line.js";
 import { resolvePointPositionPolicy } from "./point.js";
@@ -8,10 +9,13 @@ import { resolveRulePositionPolicy } from "./rule.js";
 
 const POSITION_POLICIES = Object.freeze({
   area: resolveAreaPositionPolicy,
+  arc: resolveArcPositionPolicy,
   bar: resolveBarPositionPolicy,
   line: resolveLinePositionPolicy,
   point: resolvePointPositionPolicy,
-  rule: resolveRulePositionPolicy
+  rule: resolveRulePositionPolicy,
+  text: resolvePointPositionPolicy,
+  rect: resolvePointPositionPolicy
 });
 
 export function resolveMarkPositionPolicy(context) {

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

@@ -14,22 +14,39 @@ function rejectSharedOptions(args, channel) {
 }
 
 export function resolveLinePositionPolicy({
+  program,
   layer,
   dataset,
   channel,
   args,
   fieldType
 }) {
+  const polar = ["theta", "radius"].includes(channel);
+  const config = program.markConfigs[layer.id] ?? {};
+  if (polar) {
+    if (config.curve !== undefined && config.curve !== "linear") {
+      throw new Error("Polar line position currently requires curve \"linear\".");
+    }
+    rejectSharedOptions(args, channel);
+    if (args.aggregate !== undefined) {
+      throw new Error(`Line ${channel} encoding does not support aggregate.`);
+    }
+    return emptyPositionPolicy();
+  }
+  if (config.closed === true) {
+    throw new Error("Line closed requires theta/radius Polar position encodings.");
+  }
   const regression = dataset.transform?.some(item => item.type === "regression");
   const interval = dataset.transform?.some(item => item.type === "interval");
 
   if (channel === "x") {
-    const horizontalDirect =
-      layer.encoding?.y?.fieldType === "temporal" &&
+    const directPair =
+      layer.encoding?.y?.aggregate === undefined &&
+      ["quantitative", "temporal"].includes(layer.encoding?.y?.fieldType) &&
       fieldType === "quantitative";
     if (
       fieldType !== "temporal" &&
-      !((regression || interval || horizontalDirect) && fieldType === "quantitative")
+      !((regression || interval || directPair) && fieldType === "quantitative")
     ) {
       throw new Error(
         "Line x encoding requires a temporal field or a compatible derived quantitative field."

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

@@ -22,12 +22,29 @@ import {
 } from "../../../grammar/aggregate.js";
 import { normalizeRuleDatum } from "../../../grammar/rules.js";
 import { resolveMarkPositionPolicy } from "./policies/index.js";
+import {
+  getPositionChannelDefinition,
+  positionChannelsForFamily
+} from "../../../core/vocabulary.js";
 
 const POSITION_ENCODING_OPTIONS = Object.freeze([
   "field", "datum", "target", "fieldType", "scale", "coordinate",
   "aggregate", "bin", "stack"
 ]);
 
+function validateCoordinateFamily(layer, channel, operation) {
+  const family = getPositionChannelDefinition(channel).family;
+  const incompatible = positionChannelsForFamily(
+    family === "polar" ? "cartesian" : "polar"
+  );
+  const existing = incompatible.filter(name => layer.encoding?.[name] !== undefined);
+  if (existing.length > 0) {
+    throw new Error(
+      `${operation} cannot mix ${channel} with ${existing.join("/")} position encodings on layer "${layer.id}".`
+    );
+  }
+}
+
 function resolveCoordinate(program, channel, layer, requestedId) {
   const defaults = getPositionCoordinateDefaults(channel);
   const existingId = layer.coordinate;
@@ -35,7 +52,19 @@ function resolveCoordinate(program, channel, layer, requestedId) {
   if (existingId !== undefined && requestedId !== undefined && existingId !== requestedId) {
     throw new Error(`Layer "${layer.id}" already uses coordinate "${existingId}".`);
   }
-  const id = existingId ?? requestedId ?? defaults.id;
+  const compatible = program.semanticSpec.coordinates.filter(
+    coordinate => coordinate.type === defaults.type
+  );
+  if (
+    existingId === undefined &&
+    requestedId === undefined &&
+    compatible.length > 1
+  ) {
+    throw new Error(
+      `${channel} encoding requires coordinate when multiple ${defaults.type} coordinates are available.`
+    );
+  }
+  const id = existingId ?? requestedId ?? compatible[0]?.id ?? defaults.id;
   const coordinate = findCoordinate(program, id);
   if (coordinate !== undefined && coordinate.type !== defaults.type) {
     throw new Error(
@@ -51,8 +80,9 @@ export function resolvePositionEncoding(program, channel, args, operation) {
   const { id: target, dataset, layer } = resolveTarget(
     program,
     args.target,
-    ["point", "line", "bar", "area", "rule"]
+    getPositionChannelDefinition(channel).markTypes
   );
+  validateCoordinateFamily(layer, channel, operation);
   const hasField = Object.hasOwn(args, "field");
   const hasDatum = Object.hasOwn(args, "datum");
   if (layer.mark.type === "rule") {
@@ -66,8 +96,11 @@ export function resolvePositionEncoding(program, channel, args, operation) {
     throw new Error(`${operation} does not support datum for a ${layer.mark.type} mark.`);
   }
   const previous = layer.encoding?.[channel];
-  const requestedFieldType =
-    args.fieldType ?? previous?.fieldType ?? "quantitative";
+  const requestedFieldType = args.fieldType ?? previous?.fieldType ?? (
+    layer.mark.type === "arc" && channel === "theta" && args.aggregate === "count"
+      ? "nominal"
+      : "quantitative"
+  );
   const fieldType = requestedFieldType === "nominal"
     ? "nominal"
     : validateFieldType(requestedFieldType);
@@ -98,7 +131,9 @@ export function resolvePositionEncoding(program, channel, args, operation) {
     throw new TypeError(`${operation} field must be a non-empty string.`);
   }
 
-  const aggregateOutput = isAggregate(policy.aggregate);
+  const aggregateOutput = isAggregate(policy.aggregate) && !(
+    layer.mark.type === "arc" && channel === "theta"
+  );
   const requestedScale = resolveReassignmentScaleOptions(
     previous,
     Object.hasOwn(args, "scale") ? args.scale : {}
@@ -119,9 +154,21 @@ export function resolvePositionEncoding(program, channel, args, operation) {
           ? { nice: true }
           : { discreteType: "band" }
       : ["ordinal", "nominal"].includes(fieldType)
-        ? { discreteType: "point" }
+        ? {
+            discreteType: ["arc", "rect"].includes(layer.mark.type)
+              ? "band"
+              : "point"
+          }
         : {}
   );
+  if (
+    layer.mark.type === "arc" &&
+    channel === "theta" &&
+    ["ordinal", "nominal"].includes(fieldType) &&
+    scale.type !== "band"
+  ) {
+    throw new Error("Categorical arc theta position requires a band scale.");
+  }
   if (Object.hasOwn(scale, "unknown") && layer.mark.type !== "point") {
     throw new Error(
       "Position scale unknown currently requires a row-owned point mark."
@@ -140,6 +187,8 @@ export function resolvePositionEncoding(program, channel, args, operation) {
         throw new TypeError(`Field "${field}" must contain a finite number at row ${index}.`);
       }
     }
+  } else if (layer.mark.type === "rect") {
+    readScaleField(dataset.values, field, fieldType, { allowUnknown: true });
   } else if (Object.hasOwn(scale, "unknown")) {
     readScaleField(dataset.values, field, fieldType, { allowUnknown: true });
   } else if (fieldType === "temporal") readTemporalField(dataset.values, field);
@@ -148,11 +197,11 @@ export function resolvePositionEncoding(program, channel, args, operation) {
   } else readQuantitativeField(dataset.values, field);
 
   if (
-    layer.mark.type === "bar" &&
+    ["bar", "rect"].includes(layer.mark.type) &&
     ["ordinal", "nominal"].includes(fieldType) &&
     scale.type === "point"
   ) {
-    throw new Error("Categorical bar positions require a band scale.");
+    throw new Error(`Categorical ${layer.mark.type} positions require a band scale.`);
   }
   return {
     target,

package/src/actions/encodings/position.js

@@ -1,11 +1,10 @@
 import { action } from "../../core/action.js";
 import {
-  canMaterializeArea,
-  canMaterializeLine,
+  getPositionEncodingMaterializationSteps
 } from "../../materialization/marks.js";
-import { resolveBarGrain } from "../../grammar/bars/policy.js";
 import { resolvePositionEncoding } from "./position/resolve.js";
 import { findLayer } from "../../selectors/layers.js";
+import { applyPositionSemantics } from "./position/apply.js";
 import {
   applyEncodingScale,
   rebindPositionGuides
@@ -34,69 +33,18 @@ function encodePosition(program, channel, args, operation) {
       type: coordinate.type,
       layers: [target]
     });
-  if (previous !== undefined) {
-    const alternate = hasField ? "datum" : "field";
-    if (Object.hasOwn(previous, alternate)) {
-      next = next.editSemantic({
-        property: `layer[${target}].encoding.${channel}.${alternate}`,
-        remove: true
-      });
-    }
-  }
-  next = next
-    .editSemantic({
-      property: `layer[${target}].encoding.${channel}.${hasField ? "field" : "datum"}`,
-      value: hasField ? field : datum
-    })
-    .editSemantic({
-      property: `layer[${target}].encoding.${channel}.fieldType`,
-      value: fieldType
-    });
-
-  if (layer.mark.type === "line" && channel === "y" && args.aggregate !== undefined) {
-    next = next.editSemantic({
-      property: `layer[${target}].encoding.y.aggregate`,
-      value: aggregate
-    });
-  }
-
-  if (layer.mark.type === "bar" && channel === "x" && bin !== undefined) {
-    const [mode] = Object.keys(bin);
-    const previousModes = Object.keys(layer.encoding?.x?.bin ?? {});
-    for (const previousMode of previousModes) {
-      if (previousMode === mode) continue;
-      next = next.editSemantic({
-        property: `layer[${target}].encoding.x.bin.${previousMode}`,
-        remove: true
-      });
-    }
-    next = next.editSemantic({
-      property: `layer[${target}].encoding.x.bin.${mode}`,
-      value: bin[mode]
-    });
-  }
-
-  if (layer.mark.type === "bar") {
-    if (aggregate !== undefined) {
-      next = next.editSemantic({
-        property: `layer[${target}].encoding.${channel}.aggregate`,
-        value: aggregate
-      });
-    }
-    if (stack !== undefined) {
-      next = next.editSemantic({
-        property: `layer[${target}].encoding.${channel}.stack`,
-        value: stack
-      });
-    }
-  }
-
-  if (layer.mark.type === "area" && channel === "y" && stack !== undefined) {
-    next = next.editSemantic({
-      property: `layer[${target}].encoding.y.stack`,
-      value: stack
-    });
-  }
+  next = applyPositionSemantics(next, {
+    target,
+    channel,
+    previous,
+    field,
+    datum,
+    hasField,
+    fieldType,
+    bin,
+    aggregate,
+    stack
+  });
 
   next = next.editSemantic({
       property: `layer[${target}].encoding.${channel}.scale`,
@@ -113,17 +61,6 @@ function encodePosition(program, channel, args, operation) {
     target
   );
 
-  if (layer.mark.type === "line") {
-    const updated = findLayer(next, target);
-    return canMaterializeLine(next, updated)
-      ? next.rematerializeLineMark({ id: target })
-      : next.rematerializeScale({ id: scale.id });
-  }
-
-  if (layer.mark.type === "rule") {
-    return next.rematerializeRuleMark({ id: target });
-  }
-
   if (layer.mark.type === "bar") {
     const updated = findLayer(next, target);
     const pendingBox = next.markConfigs[target]?.boxPlot;
@@ -132,22 +69,17 @@ function encodePosition(program, channel, args, operation) {
         ? next.materializeBoxPlot({ id: target })
         : next;
     }
-    const materialized = resolveBarGrain(updated) !== undefined
-      ? next.rematerializeBarMark({ id: target })
-      : next.rematerializeScale({ id: scale.id });
-    return materialized;
   }
 
-  next = next.rematerializeScale({ id: scale.id });
-  if (layer.mark.type === "area") {
-    const updated = findLayer(next, target);
-    return canMaterializeArea(next, updated)
-      ? next.rematerializeAreaMark({ id: target })
-      : next;
+  const updated = findLayer(next, target);
+  for (const step of getPositionEncodingMaterializationSteps(
+    next,
+    updated,
+    scale.id
+  )) {
+    next = next[step.op](step.args);
   }
-  return layer.mark.type === "point"
-    ? next.rematerializePointMark({ id: target })
-    : next;
+  return next;
 }
 
 const encodeX = action(
@@ -170,7 +102,29 @@ const encodeY = action(
   }
 );
 
+const encodeTheta = action(
+  {
+    op: "encodeTheta",
+    description: "Encode a field as Polar angle in clockwise degrees."
+  },
+  function (args = {}) {
+    return encodePosition(this, "theta", args, "encodeTheta");
+  }
+);
+
+const encodeR = action(
+  {
+    op: "encodeR",
+    description: "Encode a quantitative field as Polar radius."
+  },
+  function (args = {}) {
+    return encodePosition(this, "radius", args, "encodeR");
+  }
+);
+
 export function registerPositionEncodingActions(ProgramClass) {
   ProgramClass.prototype.encodeX = encodeX;
   ProgramClass.prototype.encodeY = encodeY;
+  ProgramClass.prototype.encodeTheta = encodeTheta;
+  ProgramClass.prototype.encodeR = encodeR;
 }