ggaction 0.0.2 → 0.0.4

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/index.js

@@ -0,0 +1,130 @@
+import { action } from "../../../core/action.js";
+import {
+  getPositionEncodingMaterializationSteps
+} from "../../../materialization/marks/index.js";
+import { resolvePositionEncoding } from "./resolve.js";
+import { findLayer } from "../../../selectors/layers.js";
+import { applyPositionSemantics } from "./apply.js";
+import {
+  applyEncodingScale,
+  rebindPositionGuides
+} from "../shared.js";
+
+function encodePosition(program, channel, args, operation) {
+  const {
+    target,
+    layer,
+    previous,
+    requestedScale,
+    field,
+    datum,
+    hasField,
+    fieldType,
+    scale,
+    coordinate,
+    bin,
+    aggregate,
+    stack
+  } = resolvePositionEncoding(program, channel, args, operation);
+
+  let next = program
+    .createCoordinate({
+      id: coordinate.id,
+      type: coordinate.type,
+      layers: [target]
+    });
+  next = applyPositionSemantics(next, {
+    target,
+    channel,
+    previous,
+    field,
+    datum,
+    hasField,
+    fieldType,
+    bin,
+    aggregate,
+    stack
+  });
+
+  next = next.editSemantic({
+      property: `layer[${target}].encoding.${channel}.scale`,
+      value: scale.id
+    });
+  next = applyEncodingScale(next, scale, requestedScale, {
+    reassignment: previous?.scale === scale.id
+  });
+  next = rebindPositionGuides(
+    next,
+    channel,
+    previous?.scale,
+    scale.id,
+    target
+  );
+
+  if (layer.mark.type === "bar") {
+    const updated = findLayer(next, target);
+    const pendingBox = next.markConfigs[target]?.boxPlot;
+    if (pendingBox !== undefined && !pendingBox.materialized) {
+      return updated.encoding?.x !== undefined && updated.encoding?.y !== undefined
+        ? next.materializeBoxPlot({ id: target })
+        : next;
+    }
+  }
+
+  const updated = findLayer(next, target);
+  for (const step of getPositionEncodingMaterializationSteps(
+    next,
+    updated,
+    scale.id
+  )) {
+    next = next[step.op](step.args);
+  }
+  return next;
+}
+
+const encodeX = action(
+  {
+    op: "encodeX",
+    description: "Encode a field as horizontal position."
+  },
+  function (args = {}) {
+    return encodePosition(this, "x", args, "encodeX");
+  }
+);
+
+const encodeY = action(
+  {
+    op: "encodeY",
+    description: "Encode a field as vertical position."
+  },
+  function (args = {}) {
+    return encodePosition(this, "y", args, "encodeY");
+  }
+);
+
+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;
+}

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

@@ -7,7 +7,7 @@ import {
   readTemporalField,
   validateFieldType,
   validatePositionChannel
-} from "../../../grammar/scales.js";
+} from "../../../grammar/scales/index.js";
 import { resolvePositionScaleDefinition } from "../../scales/definitions.js";
 import { findCoordinate } from "../../../selectors/coordinates.js";
 import {
@@ -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/ranged.js

@@ -4,14 +4,15 @@ import { isPlainObject } from "../../core/immutable.js";
 import {
   readNominalField,
   readQuantitativeField,
+  readScaleField,
   readTemporalField,
   validateSemanticFieldType
-} from "../../grammar/scales.js";
+} from "../../grammar/scales/index.js";
 import { normalizeRuleDatum } from "../../grammar/rules.js";
 import {
   canMaterializeArea,
   canMaterializeLine
-} from "../../materialization/marks.js";
+} from "../../materialization/marks/index.js";
 import { findLayer } from "../../selectors/layers.js";
 import {
   resolveTarget,
@@ -85,16 +86,35 @@ function encodeSecondaryPosition(program, channel, args, operation, types) {
   }
   const fieldType = rule
     ? validateSemanticFieldType(args.fieldType)
-    : args.fieldType ?? "quantitative";
-  if (!rule && fieldType !== "quantitative") {
+    : layer.mark.type === "rect"
+      ? args.fieldType ?? primary.fieldType
+      : args.fieldType ?? "quantitative";
+  if (
+    !rule &&
+    layer.mark.type !== "rect" &&
+    fieldType !== "quantitative"
+  ) {
     throw new Error(`${operation} requires a quantitative field.`);
   }
+  if (
+    layer.mark.type === "rect" &&
+    !["quantitative", "temporal"].includes(fieldType)
+  ) {
+    throw new Error(`${operation} requires a quantitative or temporal rect field.`);
+  }
+  if (layer.mark.type === "rect" && fieldType !== primary.fieldType) {
+    throw new Error(
+      `${operation} fieldType must match the primary ${primaryChannel} fieldType.`
+    );
+  }
   if (rule && fieldType !== primary.fieldType) {
     throw new Error(
       `${operation} fieldType must match the primary ${primaryChannel} fieldType.`
     );
   }
-  if (hasField) validateSecondaryField(dataset, args.field, fieldType);
+  if (hasField && layer.mark.type === "rect") {
+    readScaleField(dataset.values, args.field, fieldType, { allowUnknown: true });
+  } else if (hasField) validateSecondaryField(dataset, args.field, fieldType);
   else normalizeRuleDatum(args.datum, fieldType, channel);
 
   const previous = layer.encoding?.[channel];
@@ -135,7 +155,9 @@ function encodeSecondaryPosition(program, channel, args, operation, types) {
   if (rule) return next.rematerializeRuleMark({ id: target });
   return layer.mark.type === "bar"
     ? next.rematerializeBarMark({ id: target })
-    : next.rematerializeAreaMark({ id: target });
+    : layer.mark.type === "rect"
+      ? next.rematerializeRectMark({ id: target })
+      : next.rematerializeAreaMark({ id: target });
 }
 
 const encodeX2 = action(
@@ -149,7 +171,7 @@ const encodeX2 = action(
       "x2",
       args,
       "encodeX2",
-      ["area", "rule", "bar"]
+      ["area", "rule", "bar", "rect"]
     );
   }
 );
@@ -165,7 +187,7 @@ const encodeY2 = action(
       "y2",
       args,
       "encodeY2",
-      ["area", "rule", "bar"]
+      ["area", "rule", "bar", "rect"]
     );
   }
 );

package/src/actions/encodings/shared.js

@@ -3,10 +3,14 @@ import { findDataset } from "../../selectors/datasets.js";
 import { resolveEligibleLayer } from "../../selectors/layers.js";
 import { hasMaterializedLegend } from "../../materialization/legends.js";
 import { findSemanticScale } from "../../selectors/scales.js";
-import { validateKeys } from "../../core/validation.js";
+import { validateOptionObject } from "../../core/validation.js";
+import {
+  getMarkGraphicTypes,
+  getPositionChannelDefinition
+} from "../../core/vocabulary.js";
 
 export function validateOptions(args, supported, operation) {
-  validateKeys(args, supported, operation);
+  validateOptionObject(args, supported, operation);
 }
 
 export function validateLineSeriesCompatibility(layer, channel, field) {
@@ -65,10 +69,12 @@ export function rebindPositionGuides(
   nextScale,
   target
 ) {
+  const definition = getPositionChannelDefinition(channel);
+  if (definition?.guideChannel === undefined) return program;
   if (previousScale === undefined || previousScale === nextScale) return program;
 
-  const axis = program.semanticSpec.guides.axis?.[channel];
-  const direction = channel === "x" ? "vertical" : "horizontal";
+  const axis = program.semanticSpec.guides.axis?.[definition.guideChannel];
+  const direction = definition.gridDirection;
   const grid = program.semanticSpec.guides.grid?.[direction];
   const ownsAxis = axis?.scale === previousScale;
   const ownsGrid = grid?.scale === previousScale;
@@ -86,13 +92,13 @@ export function rebindPositionGuides(
   let next = program;
   if (ownsAxis) {
     next = next.editSemantic({
-      property: `guide.axis.${channel}.scale`,
+      property: `guide.axis.${definition.guideChannel}.scale`,
       value: nextScale
     });
-    for (const component of ["ticks", "labels", "title"]) {
-      const config = next.guideConfigs.axis?.[channel]?.[component];
+    for (const component of ["line", "ticks", "labels", "title"]) {
+      const config = next.guideConfigs.axis?.[definition.guideChannel]?.[component];
       if (config?.scale === previousScale) {
-        next = next._withGuideConfig(channel, component, {
+        next = next._withGuideConfig(definition.guideChannel, component, {
           ...config,
           scale: nextScale
         });
@@ -141,22 +147,12 @@ export function resolveTarget(
     throw new Error(`Mark "${id}" requires an existing dataset.`);
   }
 
-  const expectedGraphic = {
-    point: ["circle", "rect", "collection"],
-    line: "path",
-    bar: "rect",
-    area: "path",
-    rule: "line"
-  }[layer.mark.type];
+  const expectedGraphic = getMarkGraphicTypes(layer.mark.type);
 
   const graphicType = program.graphicSpec.objects[id]?.type;
-  const matches = Array.isArray(expectedGraphic)
-    ? expectedGraphic.includes(graphicType)
-    : graphicType === expectedGraphic;
+  const matches = expectedGraphic?.includes(graphicType) === true;
   if (!matches) {
-    const label = Array.isArray(expectedGraphic)
-      ? expectedGraphic.join(" or ")
-      : expectedGraphic;
+    const label = expectedGraphic?.join(" or ") ?? "supported";
     throw new Error(`Mark "${id}" requires ${label} graphics.`);
   }
 

package/src/actions/encodings/strokeDash.js

@@ -3,7 +3,7 @@ import {
   normalizeStrokeDashPattern,
   readNominalField,
   validateNominalFieldType
-} from "../../grammar/scales.js";
+} from "../../grammar/scales/index.js";
 import { resolveStrokeDashScaleDefinition } from "../scales/definitions.js";
 import { applyMaterializationPlan } from "../../materialization/dependencies.js";
 import { planEncodingRematerialization } from "../../materialization/encodings.js";