ggaction 0.0.12 → 0.0.13

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

@@ -1,12 +1,16 @@
+import { stackLayoutMode } from "../seriesLayout.js";
+import { resolveBarGrain } from "../../../grammar/bars/policy.js";
 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 { findSemanticScale } from "../../../selectors/scales.js";
 import { applyPositionSemantics } from "./apply.js";
 import {
   applyEncodingScale,
+  applyDetachedScaleRematerialization,
   rebindPositionGuides
 } from "../shared.js";
 
@@ -20,12 +24,14 @@ function encodePosition(program, channel, args, operation) {
     datum,
     hasField,
     fieldType,
+    temporalUnit,
     scale,
     coordinate,
     bin,
     aggregate,
     stack,
-    weight
+    weight,
+    companion
   } = resolvePositionEncoding(program, channel, args, operation);
 
   let next = program
@@ -43,6 +49,7 @@ function encodePosition(program, channel, args, operation) {
     datum,
     hasField,
     fieldType,
+    temporalUnit,
     bin,
     aggregate,
     stack,
@@ -54,8 +61,12 @@ function encodePosition(program, channel, args, operation) {
       value: scale.id
     });
   next = applyEncodingScale(next, scale, requestedScale, {
-    reassignment: previous?.scale === scale.id
+    reassignment: previous?.scale === scale.id,
+    allowTypeChange: layer.mark.type === "area"
   });
+  if (["bar", "area"].includes(layer.mark.type) && Object.hasOwn(args, "stack") && args.stack !== undefined) {
+    next = next.editSemantic({ property: `layer[${target}].layout.mode`, value: stackLayoutMode(args.stack) });
+  }
   next = rebindPositionGuides(
     next,
     channel,
@@ -64,13 +75,30 @@ function encodePosition(program, channel, args, operation) {
     target
   );
 
+  if (companion !== undefined) {
+    const encoding = companion.encoding;
+    const storedScale = findSemanticScale(next, encoding.scale);
+    next = next[companion.channel === "x" ? "encodeX" : "encodeY"]({
+      target,
+      field: encoding.field,
+      fieldType: encoding.fieldType,
+      aggregate: encoding.aggregate,
+      ...(layer.layout?.mode === undefined ? {} : { stack: encoding.stack }),
+      scale: {
+        id: encoding.scale,
+        ...(storedScale?.zero === undefined ? { zero: encoding.stack !== null } : {})
+      }
+    });
+  }
+
   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
+      const materialized = updated.encoding?.x !== undefined && updated.encoding?.y !== undefined
         ? next.materializeBoxPlot({ id: target })
         : next;
+      return applyDetachedScaleRematerialization(materialized, [layer]);
     }
   }
 
@@ -78,13 +106,23 @@ function encodePosition(program, channel, args, operation) {
     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
+      const materialized = updated.encoding?.x !== undefined && updated.encoding?.y !== undefined
         ? next.materializeGradientPlot({ id: target })
         : next;
+      return applyDetachedScaleRematerialization(materialized, [layer]);
     }
   }
 
   const updated = findLayer(next, target);
+  if (["bar", "area"].includes(layer.mark.type) && next.markConfigs[target]?.boxPlot === undefined &&
+      updated.encoding?.x?.scale !== undefined && updated.encoding?.y?.scale !== undefined) {
+    const requested = Object.hasOwn(args, "stack") ? args.stack : undefined;
+    const mode = requested !== undefined ? stackLayoutMode(requested) : updated.layout?.mode ??
+      (layer.mark.type === "bar" && resolveBarGrain(updated) === "histogram" ? stackLayoutMode(updated.encoding.y.stack) : undefined);
+    if (mode !== undefined && (layer.mark.type === "area" || resolveBarGrain(updated) !== undefined)) {
+      return applyDetachedScaleRematerialization(next.layoutSeries({ target, mode }), [layer]);
+    }
+  }
   for (const step of getPositionEncodingMaterializationSteps(
     next,
     updated,
@@ -92,7 +130,7 @@ function encodePosition(program, channel, args, operation) {
   )) {
     next = next[step.op](step.args);
   }
-  return next;
+  return applyDetachedScaleRematerialization(next, [layer]);
 }
 
 const encodeX = action(

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

@@ -1,3 +1,4 @@
+import { validateRadialMapping } from "../../../../grammar/scales/radial.js";
 import { validateAggregate } from "../../../../grammar/aggregate.js";
 import { validateNonEmptyString } from "../../../../core/validation.js";
 import { emptyPositionPolicy } from "./common.js";
@@ -15,6 +16,19 @@ export function resolveArcPositionPolicy({ channel, args, fieldType, layer }) {
         "Arc radius encoding cannot be combined with quantitative theta."
       );
     }
+    if (args.mapping !== undefined) {
+      validateRadialMapping(args.mapping);
+      if (fieldType !== "quantitative" || !["count", "sum"].includes(args.aggregate)) {
+        throw new Error("Measured radius requires quantitative count or sum aggregation.");
+      }
+      if (args.aggregate === "count" && Object.hasOwn(args, "field")) {
+        throw new Error("Measured radius count does not accept a field.");
+      }
+      if (layer.encoding?.theta?.aggregate !== undefined) {
+        throw new Error("Measured radius requires equal-angle theta without aggregation.");
+      }
+      return { ...emptyPositionPolicy(), aggregate: args.aggregate };
+    }
     if (args.aggregate !== undefined) {
       throw new Error("Arc radius encoding does not support aggregate.");
     }

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

@@ -1,6 +1,4 @@
 import { validateStack, emptyPositionPolicy } from "./common.js";
-import { deriveCenteredAreaSeries } from "../../../../grammar/areaSeries.js";
-import { readQuantitativeField } from "../../../../grammar/scales/index.js";
 
 export function isCategoricalDensityPosition({
   layer,
@@ -50,44 +48,8 @@ export function resolveAreaPositionPolicy({
     throw new Error("Area position encoding does not support aggregate or bin.");
   }
   if (args.stack === undefined) return emptyPositionPolicy();
-  const stack = validateStack(args.stack, "Area y encoding");
-  if (stack === "center") {
-    if (channel !== "y") {
-      throw new Error("Area center stack requires a y encoding.");
-    }
-    if (layer.encoding?.group?.fieldType !== "nominal") {
-      throw new Error("Area center stack requires a nominal group encoding.");
-    }
-    if (
-      layer.encoding?.color?.layout !== undefined &&
-      layer.encoding.color.layout !== "center"
-    ) {
-      throw new Error("Area center stack requires a matching center color layout.");
-    }
-    const values = readQuantitativeField(dataset.values, field);
-    if (values.some(value => value < 0)) {
-      throw new RangeError("Area center stack requires non-negative values.");
-    }
-    if (layer.encoding?.x !== undefined) {
-      deriveCenteredAreaSeries(dataset.values, {
-        ...layer,
-        encoding: {
-          ...layer.encoding,
-          y: { field, fieldType, stack: "center" }
-        }
-      });
-    }
-    return { bin: undefined, aggregate: undefined, stack };
-  }
-  if (
-    channel !== "y" ||
-    density === undefined
-  ) {
-    throw new Error("Area stack currently requires a density y encoding.");
-  }
-  return {
-    bin: undefined,
-    aggregate: undefined,
-    stack
-  };
+  const stack = validateStack(args.stack, "Area position encoding");
+  if (fieldType !== "quantitative") throw new Error("Area stack requires a quantitative measure.");
+  if (stack === "center" && channel !== "y") throw new Error("Area center stack requires a y encoding.");
+  return { bin: undefined, aggregate: undefined, stack };
 }

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

@@ -4,12 +4,14 @@ import {
 } from "../../../../grammar/aggregate.js";
 import {
   BAR_ORIENTATIONS,
+  BAR_GRAINS,
+  resolveBarGrain,
   resolveBarOffsetChannel,
   resolveBarOrientation
 } from "../../../../grammar/bars/policy.js";
 import { resolveBin, validateStack } from "./common.js";
 
-export function resolveBarPositionPolicy({
+function resolveBarChannelPolicy({
   program,
   layer,
   channel,
@@ -72,17 +74,12 @@ export function resolveBarPositionPolicy({
     if (pendingBoxRange && args.aggregate === undefined) {
       return { bin, aggregate, stack };
     }
-    if (aggregate === undefined) {
-      throw new Error(
-        channel === "x"
-          ? "Quantitative bar x encoding requires bin or aggregate."
-          : "Bar y encoding requires a binned quantitative or ordinal x category, temporal x category, or aggregate."
-      );
+    stack = Object.hasOwn(args, "stack") ? args.stack : opposite === undefined ? undefined : null;
+    if (aggregate !== undefined) {
+      aggregate = validateAggregate(aggregate);
+      validateAggregateFieldType(aggregate, fieldType);
     }
-    stack = Object.hasOwn(args, "stack") ? args.stack : null;
-    aggregate = validateAggregate(aggregate);
-    validateAggregateFieldType(aggregate, fieldType);
-    stack = validateStack(stack, `Bar ${channel} encoding`);
+    if (stack !== undefined) stack = validateStack(stack, `Bar ${channel} encoding`);
     if (stack === "center") {
       throw new Error("Centered bars are not supported.");
     }
@@ -92,13 +89,45 @@ export function resolveBarPositionPolicy({
     );
   }
 
+  return { bin, aggregate, stack };
+}
+
+export function resolveBarPositionPolicy(context) {
+  const { program, layer, channel, field, fieldType } = context;
+  const policy = resolveBarChannelPolicy(context);
+  const oppositeChannel = channel === "x" ? "y" : "x";
+  const opposite = layer.encoding?.[oppositeChannel];
+  const pendingBoxRange = program.markConfigs[layer.id]?.boxPlot !== undefined;
   const candidate = {
     ...layer,
     encoding: {
       ...layer.encoding,
-      [channel]: { field, fieldType, bin, aggregate, stack }
+      [channel]: { field, fieldType, ...policy }
     }
   };
+  // The same channel policy owns a measure whether it is authored first or last.
+  // Absence of an aggregate/stack is sufficient to represent an unresolved role.
+  let companion;
+  if (
+    !pendingBoxRange && resolveBarGrain(layer) === undefined &&
+    opposite?.fieldType === "quantitative" && opposite.bin === undefined
+  ) {
+    const resolved = resolveBarChannelPolicy({
+      ...context,
+      layer: candidate,
+      channel: oppositeChannel,
+      field: opposite.field,
+      fieldType: opposite.fieldType,
+      args: opposite
+    });
+    candidate.encoding[oppositeChannel] = { ...opposite, ...resolved };
+    if (
+      (opposite.aggregate === undefined && resolved.aggregate !== undefined) ||
+      opposite.stack !== resolved.stack
+    ) {
+      companion = { channel: oppositeChannel, encoding: candidate.encoding[oppositeChannel] };
+    }
+  }
   const orientation = resolveBarOrientation(candidate);
   if (opposite !== undefined && orientation === undefined && !pendingBoxRange) {
     throw new Error(
@@ -116,5 +145,11 @@ export function resolveBarPositionPolicy({
       `${orientation} bars require ${expectedOffset}; remove the incompatible ${incompatibleOffset} encoding.`
     );
   }
-  return { bin, aggregate, stack };
+  if (
+    program.markConfigs[layer.id]?.barWidth !== undefined &&
+    resolveBarGrain(candidate) === BAR_GRAINS.histogram
+  ) {
+    throw new Error("A saved Bar width requires an aggregate or ranged category slot and cannot be applied to histogram bins.");
+  }
+  return companion === undefined ? policy : { ...policy, companion };
 }

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

@@ -1,3 +1,6 @@
+import { isSourceOwnedText } from "../../../grammar/text.js";
+import { findSemanticScale } from "../../../selectors/scales.js";
+import { readAreaEndpoint } from "../../../grammar/areaEndpoints.js";
 import { validateUserId } from "../../../core/identifiers.js";
 import { getPositionCoordinateDefaults } from "../../../grammar/coordinates.js";
 import {
@@ -6,6 +9,7 @@ import {
   readQuantitativeField,
   readScaleField,
   readTemporalField,
+  resolveTemporalUnit,
   validateFieldType,
   validatePositionChannel
 } from "../../../grammar/scales/index.js";
@@ -21,7 +25,7 @@ import {
   validateAggregateFieldType,
   validateAggregateFieldValues,
 } from "../../../grammar/aggregate.js";
-import { normalizeRuleDatum } from "../../../grammar/rules.js";
+import { normalizePositionDatum } from "../../../grammar/positionDatum.js";
 import {
   readArcThetaValues,
   readArcThetaWeights
@@ -34,10 +38,10 @@ import {
 
 const POSITION_ENCODING_OPTIONS = Object.freeze([
   "field", "datum", "target", "fieldType", "scale", "coordinate",
-  "aggregate", "bin", "stack", "weight"
+  "aggregate", "bin", "stack", "weight", "temporalUnit", "mapping"
 ]);
 
-function inferRuleDatumFieldType(datum, operation) {
+function inferDatumFieldType(datum, operation) {
   if (Number.isFinite(datum)) return "quantitative";
   if (isNominalValue(datum)) return "nominal";
   throw new Error(`${operation} datum requires an explicit fieldType.`);
@@ -93,29 +97,45 @@ export function resolvePositionEncoding(program, channel, args, operation) {
     args.target,
     getPositionChannelDefinition(channel).markTypes
   );
+  if (isSourceOwnedText(layer)) {
+    throw new Error(`${operation} cannot replace source-owned Text positions; edit the source, use dx/dy, or create independent Text with data.`);
+  }
   if (
     Object.hasOwn(args, "weight") &&
     !(layer.mark.type === "arc" && channel === "theta")
   ) {
     throw new Error(`${operation} weight is supported only for arc theta encoding.`);
   }
+  if (Object.hasOwn(args, "mapping") && (layer.mark.type !== "arc" || channel !== "radius")) {
+    throw new Error(`${operation} mapping requires Arc radius.`);
+  }
   validateCoordinateFamily(layer, channel, operation);
   const hasField = Object.hasOwn(args, "field");
   const hasDatum = Object.hasOwn(args, "datum");
-  if (layer.mark.type === "rule") {
+  if (["rule", "rect", "text", "point", "tick"].includes(layer.mark.type)) {
     if (hasField === hasDatum) {
-      throw new Error(`${operation} requires exactly one of field or datum for a rule mark.`);
+      throw new Error(`${operation} requires exactly one of field or datum for a ${layer.mark.type} mark.`);
     }
-    if (hasField && args.fieldType === undefined) {
+    if (layer.mark.type === "rule" && hasField && args.fieldType === undefined) {
       throw new Error(`${operation} requires fieldType for a rule mark.`);
     }
+  } else if (layer.mark.type === "area") {
+    if (hasField === hasDatum) throw new Error(`${operation} requires exactly one of field or datum for an area mark.`);
+    if (hasDatum && (!Number.isFinite(args.datum) || (args.fieldType ?? "quantitative") !== "quantitative" ||
+      ["aggregate", "bin", "stack", "temporalUnit"].some(key => Object.hasOwn(args, key)))) {
+      throw new Error("Area datum requires a finite quantitative constant without aggregate, bin, stack, or temporalUnit.");
+    }
   } else if (hasDatum) {
     throw new Error(`${operation} does not support datum for a ${layer.mark.type} mark.`);
   }
   const previous = layer.encoding?.[channel];
+  const mapping = channel === "radius" && layer.mark.type === "arc"
+    ? args.mapping ?? findSemanticScale(program, previous?.scale)?.radialMapping
+    : undefined;
+  const countRadius = mapping !== undefined && (args.aggregate ?? previous?.aggregate) === "count";
   const requestedFieldType = args.fieldType ?? previous?.fieldType ?? (
-    layer.mark.type === "rule" && hasDatum
-      ? inferRuleDatumFieldType(args.datum, operation)
+    ["rule", "rect", "text", "point", "tick"].includes(layer.mark.type) && hasDatum
+      ? inferDatumFieldType(args.datum, operation)
       : layer.mark.type === "arc" && channel === "theta" &&
           ["count", "sum"].includes(args.aggregate)
         ? "nominal"
@@ -130,7 +150,22 @@ export function resolvePositionEncoding(program, channel, args, operation) {
     ? xEncoding.field
     : args.field;
   const datum = args.datum;
-  const effectiveArgs = { ...args };
+  const temporalUnit = resolveTemporalUnit({ ...args, ...(hasDatum ? {} : { field }) }, fieldType, previous);
+  const usesField = !countRadius && (!["rule", "area", "rect", "text", "point", "tick"].includes(layer.mark.type) || hasField);
+  if (usesField && (typeof field !== "string" || field.length === 0)) {
+    throw new TypeError(`${operation} field must be a non-empty string.`);
+  }
+  // A missing field is invalid even before the Bar's measure/category role is known.
+  if (layer.mark.type === "bar" && program.markConfigs[target]?.boxPlot === undefined) {
+    if (fieldType === "quantitative" && dataset.values.length > 0 &&
+      !dataset.values.some(row => Object.hasOwn(row, field))) {
+      throw new Error(`${operation} field "${field}" does not exist in the dataset.`);
+    }
+    if (fieldType === "quantitative") {
+      validateAggregateFieldValues(dataset.values, field, fieldType);
+    } else readScaleField(dataset.values, field, fieldType, { temporalUnit });
+  }
+  const effectiveArgs = { ...args, ...(mapping === undefined ? {} : { mapping }) };
   const directQuantitativeArcTheta =
     layer.mark.type === "arc" &&
     channel === "theta" &&
@@ -159,11 +194,6 @@ export function resolvePositionEncoding(program, channel, args, operation) {
     fieldType,
     field
   });
-  const usesField = layer.mark.type !== "rule" || hasField;
-  if (usesField && (typeof field !== "string" || field.length === 0)) {
-    throw new TypeError(`${operation} field must be a non-empty string.`);
-  }
-
   const aggregateOutput = isAggregate(policy.aggregate) && !(
     layer.mark.type === "arc" && channel === "theta"
   );
@@ -176,11 +206,14 @@ export function resolvePositionEncoding(program, channel, args, operation) {
     channel,
     aggregateOutput ? "quantitative" : fieldType,
     requestedScale,
-    layer.mark.type === "bar"
+    mapping !== undefined ? { radialMapping: mapping, zero: true, nice: false }
+      : layer.mark.type === "bar"
       ? program.markConfigs[target]?.boxPlot !== undefined && fieldType === "quantitative"
         ? { nice: true, zero: false }
         : fieldType === "quantitative"
-        ? policy.bin !== undefined || policy.stack === null
+        ? policy.bin === undefined && policy.stack === undefined
+          ? { nice: true }
+          : policy.bin !== undefined || policy.stack === null
           ? { nice: true, zero: false }
           : { nice: true, zero: true }
         : fieldType === "temporal"
@@ -217,8 +250,13 @@ export function resolvePositionEncoding(program, channel, args, operation) {
       "Position scale unknown currently requires a row-owned point mark."
     );
   }
-  if (layer.mark.type === "rule" && hasDatum) {
-    normalizeRuleDatum(datum, fieldType, channel);
+  if (layer.mark.type === "area" && fieldType === "quantitative") {
+    readAreaEndpoint(dataset.values, { ...(hasDatum ? { datum } : { field }), fieldType }, layer.mark.missing);
+  } else if (["rule", "rect", "text", "point", "tick"].includes(layer.mark.type) && hasDatum) {
+    const mark = layer.mark.type[0].toUpperCase() + layer.mark.type.slice(1);
+    normalizePositionDatum(datum, fieldType, channel, temporalUnit, mark);
+  } else if (countRadius) {
+    // Count has no source measure field. Category-grain validation runs once theta exists.
   } else if (aggregateOutput) {
     validateAggregateFieldType(policy.aggregate, fieldType);
     validateAggregateFieldValues(dataset.values, field, fieldType);
@@ -239,14 +277,20 @@ export function resolvePositionEncoding(program, channel, args, operation) {
       }
     }
   } else if (layer.mark.type === "rect") {
-    readScaleField(dataset.values, field, fieldType, { allowUnknown: true });
+    readScaleField(dataset.values, field, fieldType, { allowUnknown: true, temporalUnit });
   } else if (Object.hasOwn(scale, "unknown")) {
-    readScaleField(dataset.values, field, fieldType, { allowUnknown: true });
-  } else if (fieldType === "temporal") readTemporalField(dataset.values, field);
+    readScaleField(dataset.values, field, fieldType, { allowUnknown: true, temporalUnit });
+  } else if (fieldType === "temporal") readTemporalField(dataset.values, field, temporalUnit);
   else if (["ordinal", "nominal"].includes(fieldType)) {
     readNominalField(dataset.values, field);
   } else readQuantitativeField(dataset.values, field);
 
+  if (mapping !== undefined) {
+    const values = countRadius ? dataset.values.map(() => 1) : readQuantitativeField(dataset.values, field);
+    if (values.length === 0 || values.some(value => value < 0) || !values.some(value => value > 0)) {
+      throw new Error("Measured radius requires non-negative values and a positive aggregate.");
+    }
+  }
   if (
     ["bar", "rect"].includes(layer.mark.type) &&
     ["ordinal", "nominal"].includes(fieldType) &&
@@ -258,11 +302,12 @@ export function resolvePositionEncoding(program, channel, args, operation) {
     target,
     layer,
     previous,
-    requestedScale,
+    requestedScale: mapping === undefined ? requestedScale : { ...requestedScale, radialMapping: mapping },
     field,
     datum,
     hasField: usesField,
     fieldType,
+    temporalUnit,
     scale,
     coordinate: resolveCoordinate(program, channel, layer, args.coordinate),
     ...policy