ggaction 0.0.11 → 0.0.12

package/src/grammar/arcs.js

@@ -17,12 +17,30 @@ function requireArcLayer(layer) {
     throw new Error("Arc derivation requires a semantic arc mark.");
   }
   const theta = layer.encoding?.theta;
-  if (theta === undefined || !["nominal", "ordinal"].includes(theta.fieldType)) {
-    throw new Error(`Arc mark "${layer.id}" requires categorical theta.`);
+  if (
+    theta === undefined ||
+    !["quantitative", "nominal", "ordinal"].includes(theta.fieldType)
+  ) {
+    throw new Error(
+      `Arc mark "${layer.id}" requires quantitative or categorical theta.`
+    );
   }
   return theta;
 }
 
+function requireContinuousThetaScale(scale, label) {
+  if (
+    scale?.type !== "linear" ||
+    !Array.isArray(scale.range) ||
+    scale.range.length !== 2 ||
+    !scale.range.every(Number.isFinite) ||
+    scale.range[0] === scale.range[1]
+  ) {
+    throw new Error(`${label} requires a resolved linear scale.`);
+  }
+  return scale;
+}
+
 function requireBandScale(scale, label) {
   if (
     scale?.type !== "band" ||
@@ -45,24 +63,90 @@ function colorValues(rows, encoding) {
     : readNominalField(rows, encoding.field);
 }
 
-export function readArcThetaWeights(rows, field, layerId = "arc") {
-  if (!Array.isArray(rows)) throw new TypeError("Arc theta weights require rows.");
+function readNonNegativeArcThetaValues(rows, field, layerId, role) {
+  if (!Array.isArray(rows)) throw new TypeError(`Arc theta ${role}s require rows.`);
   if (typeof field !== "string" || field.length === 0) {
-    throw new TypeError("Arc theta weight must be a non-empty string.");
+    throw new TypeError(`Arc theta ${role} must be a non-empty string.`);
   }
-  const weights = rows.map((row, index) => {
+  const values = rows.map((row, index) => {
     const value = row?.[field];
     if (!Number.isFinite(value) || value < 0) {
       throw new TypeError(
-        `Arc theta weight field "${field}" must contain non-negative finite numbers at row ${index}.`
+        `Arc theta ${role} field "${field}" must contain non-negative finite numbers at row ${index}.`
       );
     }
     return value;
   });
-  if (weights.every(value => value === 0)) {
-    throw new Error(`Arc mark "${layerId}" theta weights must have a positive total.`);
+  if (values.every(value => value === 0)) {
+    throw new Error(`Arc mark "${layerId}" theta ${role}s must have a positive total.`);
+  }
+  return cloneAndFreeze(values);
+}
+
+export function readArcThetaWeights(rows, field, layerId = "arc") {
+  return readNonNegativeArcThetaValues(rows, field, layerId, "weight");
+}
+
+export function readArcThetaValues(rows, field, layerId = "arc") {
+  return readNonNegativeArcThetaValues(rows, field, layerId, "value");
+}
+
+function resolveProportionalRanges(values, range, labelAt) {
+  const total = values.reduce((sum, value) => sum + value, 0);
+  const normalizedTotal = Number.isFinite(total)
+    ? undefined
+    : normalizedFiniteSum(values, "Arc theta values");
+  if (total === 0 || normalizedTotal?.total <= 0) {
+    throw new Error("Arc theta values must have a positive total.");
+  }
+  const span = range[1] - range[0];
+  let cursor = range[0];
+  let cumulative = 0;
+  let cumulativeCorrection = 0;
+  return values.map((value, index) => {
+    const normalizedValue = normalizedTotal === undefined
+      ? value
+      : value / normalizedTotal.scale;
+    const next = cumulative + normalizedValue;
+    if (normalizedTotal !== undefined) {
+      cumulativeCorrection += Math.abs(cumulative) >= Math.abs(normalizedValue)
+        ? cumulative - next + normalizedValue
+        : normalizedValue - next + cumulative;
+    }
+    cumulative = next;
+    const directEnd = cursor + value / total * span;
+    const endTheta = index === values.length - 1
+      ? range[1]
+      : normalizedTotal === undefined && Number.isFinite(directEnd)
+        ? directEnd
+        : interpolateNumber(
+            range[0],
+            range[1],
+            (cumulative + cumulativeCorrection) /
+              (normalizedTotal?.total ?? total)
+          );
+    if (!Number.isFinite(endTheta) || endTheta === cursor) {
+      throw new RangeError(
+        `Arc theta ${labelAt(index)} cannot resolve a distinct finite sector.`
+      );
+    }
+    const result = { startTheta: cursor, endTheta };
+    cursor = endTheta;
+    return result;
+  });
+}
+
+function resolveProportionalRadii(layer, frame, innerRadiusRatio) {
+  if (!Number.isFinite(frame?.availableRadius) || frame.availableRadius < 0) {
+    throw new RangeError(`Arc mark "${layer.id}" requires a finite available radius.`);
   }
-  return cloneAndFreeze(weights);
+  return {
+    innerRadius: requireFiniteResult(
+      frame.availableRadius * innerRadiusRatio,
+      `Arc mark "${layer.id}" inner radius`
+    ),
+    outerRadius: frame.availableRadius
+  };
 }
 
 function proportionalSectors(rows, layer, thetaScale, frame, innerRadiusRatio) {
@@ -87,14 +171,7 @@ function proportionalSectors(rows, layer, thetaScale, frame, innerRadiusRatio) {
       weight: weights[index]
     });
   }
-  if (!Number.isFinite(frame?.availableRadius) || frame.availableRadius < 0) {
-    throw new RangeError(`Arc mark "${layer.id}" requires a finite available radius.`);
-  }
-  const innerRadius = requireFiniteResult(
-    frame.availableRadius * innerRadiusRatio,
-    `Arc mark "${layer.id}" inner radius`
-  );
-  let cursor = thetaScale.range[0];
+  const radii = resolveProportionalRadii(layer, frame, innerRadiusRatio);
   const sectors = [];
   const positiveValues = thetaScale.domain.filter(value =>
     groups.get(value).some(item => item.weight > 0)
@@ -103,48 +180,15 @@ function proportionalSectors(rows, layer, thetaScale, frame, innerRadiusRatio) {
     groups.get(value).map(item => item.weight),
     `Arc theta group "${String(value)}" aggregate`
   ));
-  const total = aggregateValues.reduce((sum, value) => sum + value, 0);
-  const normalizedTotal = Number.isFinite(total)
-    ? undefined
-    : normalizedFiniteSum(
-        aggregateValues,
-        `Arc mark "${layer.id}" theta aggregates`
-      );
-  if (total === 0 || normalizedTotal?.total <= 0) {
-    throw new Error(`Arc mark "${layer.id}" has no positive theta weight.`);
-  }
-  const span = thetaScale.range[1] - thetaScale.range[0];
-  let cumulative = 0;
-  let cumulativeCorrection = 0;
+  const ranges = resolveProportionalRanges(
+    aggregateValues,
+    thetaScale.range,
+    index => `group "${String(positiveValues[index])}"`
+  );
   for (const [positiveIndex, value] of positiveValues.entries()) {
     const group = groups.get(value);
     const aggregateValue = aggregateValues[positiveIndex];
-    const normalizedValue = normalizedTotal === undefined
-      ? aggregateValue
-      : aggregateValue / normalizedTotal.scale;
-    const next = cumulative + normalizedValue;
-    if (normalizedTotal !== undefined) {
-      cumulativeCorrection += Math.abs(cumulative) >= Math.abs(normalizedValue)
-        ? cumulative - next + normalizedValue
-        : normalizedValue - next + cumulative;
-    }
-    cumulative = next;
-    const directEnd = cursor + aggregateValue / total * span;
-    const endTheta = positiveIndex === positiveValues.length - 1
-      ? thetaScale.range[1]
-      : normalizedTotal === undefined && Number.isFinite(directEnd)
-        ? directEnd
-        : interpolateNumber(
-            thetaScale.range[0],
-            thetaScale.range[1],
-            (cumulative + cumulativeCorrection) /
-              (normalizedTotal?.total ?? total)
-          );
-    if (!Number.isFinite(endTheta) || endTheta === cursor) {
-      throw new RangeError(
-        `Arc theta group "${String(value)}" cannot resolve a distinct finite sector.`
-      );
-    }
+    const { startTheta, endTheta } = ranges[positiveIndex];
     const distinctColors = [...new Set(group.map(item => item.color))];
     if (distinctColors.length > 1) {
       throw new Error(
@@ -157,17 +201,46 @@ function proportionalSectors(rows, layer, thetaScale, frame, innerRadiusRatio) {
       count: group.length,
       aggregateValue,
       color: distinctColors[0],
-      startTheta: cursor,
+      startTheta,
       endTheta,
-      innerRadius,
-      outerRadius: frame.availableRadius,
+      ...radii,
       sourceIndices: group.map(item => item.sourceIndex)
     });
-    cursor = endTheta;
   }
   return sectors;
 }
 
+function quantitativeSectors(rows, layer, thetaScale, frame, innerRadiusRatio) {
+  const theta = layer.encoding.theta;
+  if (layer.encoding?.radius !== undefined) {
+    throw new Error(
+      `Arc mark "${layer.id}" cannot combine quantitative theta with radius.`
+    );
+  }
+  const values = readArcThetaValues(rows, theta.field, layer.id);
+  const colors = colorValues(rows, layer.encoding?.color);
+  const positiveIndices = values
+    .map((value, index) => value > 0 ? index : undefined)
+    .filter(index => index !== undefined);
+  const positiveValues = positiveIndices.map(index => values[index]);
+  const ranges = resolveProportionalRanges(
+    positiveValues,
+    thetaScale.range,
+    index => `row ${positiveIndices[index]}`
+  );
+  const radii = resolveProportionalRadii(layer, frame, innerRadiusRatio);
+  return positiveIndices.map((sourceIndex, index) => ({
+    key: `${String(values[sourceIndex])}:${sourceIndex}`,
+    theta: values[sourceIndex],
+    count: 1,
+    aggregateValue: values[sourceIndex],
+    color: colors[sourceIndex],
+    ...ranges[index],
+    ...radii,
+    sourceIndices: [sourceIndex]
+  }));
+}
+
 function radialSectors(rows, layer, thetaScale, radiusScale) {
   const theta = layer.encoding.theta;
   const radius = layer.encoding?.radius;
@@ -223,7 +296,6 @@ export function deriveArcSectors(rows, layer, {
 } = {}) {
   if (!Array.isArray(rows)) throw new TypeError("Arc derivation requires rows.");
   const theta = requireArcLayer(layer);
-  requireBandScale(thetaScale, `Arc mark "${layer.id}" theta`);
   if (
     !Number.isFinite(innerRadiusRatio) ||
     innerRadiusRatio < 0 ||
@@ -231,8 +303,27 @@ export function deriveArcSectors(rows, layer, {
   ) {
     throw new RangeError("Arc innerRadius must be from 0 (inclusive) to 1 (exclusive).");
   }
-  const sectors = ["count", "sum"].includes(theta.aggregate)
-    ? proportionalSectors(rows, layer, thetaScale, frame, innerRadiusRatio)
-    : radialSectors(rows, layer, thetaScale, radiusScale);
+  const sectors = theta.fieldType === "quantitative"
+    ? quantitativeSectors(
+        rows,
+        layer,
+        requireContinuousThetaScale(thetaScale, `Arc mark "${layer.id}" theta`),
+        frame,
+        innerRadiusRatio
+      )
+    : ["count", "sum"].includes(theta.aggregate)
+      ? proportionalSectors(
+          rows,
+          layer,
+          requireBandScale(thetaScale, `Arc mark "${layer.id}" theta`),
+          frame,
+          innerRadiusRatio
+        )
+      : radialSectors(
+          rows,
+          layer,
+          requireBandScale(thetaScale, `Arc mark "${layer.id}" theta`),
+          radiusScale
+        );
   return cloneAndFreeze({ sectors });
 }

package/src/grammar/positionCompatibility.js

@@ -16,7 +16,7 @@ export const POSITION_FIELD_COMPATIBILITY = Object.freeze({
     y: Object.freeze(["quantitative", "temporal"])
   }),
   arc: Object.freeze({
-    theta: Object.freeze(["ordinal", "nominal"]),
+    theta: Object.freeze(["quantitative", "ordinal", "nominal"]),
     radius: Object.freeze(["quantitative"])
   }),
   rule: Object.freeze({

package/src/grammar/rules.js

@@ -11,6 +11,8 @@ import {
 const ENDPOINT_CHANNELS = Object.freeze(["x", "y", "x2", "y2"]);
 const VALUE_CHANNELS = Object.freeze([
   ...ENDPOINT_CHANNELS,
+  "xOffset",
+  "yOffset",
   "strokeDash",
   "strokeWidth",
   "opacity"

package/src/grammar/scales/ordinal.js

@@ -278,3 +278,26 @@ export function mapOrdinalPositionValues(values, scale) {
     );
   }));
 }
+
+export function mapOrdinalOffsetValues(values, scale) {
+  const indices = new Map(scale.domain.map((value, index) => [value, index]));
+  const direction = Math.sign(scale.step) || 1;
+  const denominator = Math.max(
+    1,
+    scale.domain.length - scale.paddingInner + scale.paddingOuter * 2
+  );
+  return cloneAndFreeze(values.map(value => {
+    const index = indices.get(value);
+    if (index === undefined) {
+      throw new Error(`Value "${value}" is outside the ordinal domain.`);
+    }
+    const direct = scale.start + index * scale.step +
+      direction * scale.bandwidth / 2;
+    return finitePosition(
+      direct,
+      scale,
+      (scale.paddingOuter + index + (1 - scale.paddingInner) / 2) /
+        denominator
+    );
+  }));
+}

package/src/layout/facets.js

@@ -9,6 +9,11 @@ import {
 
 export const DEFAULT_FACET_LEGEND_GAP = 18;
 export const DEFAULT_FACET_LEGEND_WIDTH = 132;
+export const DEFAULT_FACET_LEGEND_HEIGHT = 0;
+
+const FACET_LEGEND_POSITIONS = Object.freeze([
+  "right", "left", "top", "bottom"
+]);
 
 function resolveColumns(columns, count) {
   const value = columns ?? count;
@@ -33,7 +38,9 @@ export function resolveFacetLayout({
   titleHeight = 0,
   sharedLegend = false,
   sharedLegendGap = DEFAULT_FACET_LEGEND_GAP,
-  sharedLegendWidth = DEFAULT_FACET_LEGEND_WIDTH
+  sharedLegendWidth = DEFAULT_FACET_LEGEND_WIDTH,
+  sharedLegendHeight = DEFAULT_FACET_LEGEND_HEIGHT,
+  sharedLegendPosition = "right"
 } = {}) {
   const values = children?.map(child => child?.value);
   const resolvedChildren = normalizeCompositionChildren(children?.map(
@@ -58,6 +65,20 @@ export function resolveFacetLayout({
     sharedLegendWidth,
     "Facet shared legend width"
   );
+  const legendHeight = validateCompositionSpacing(
+    sharedLegendHeight,
+    "Facet shared legend height"
+  );
+  if (!FACET_LEGEND_POSITIONS.includes(sharedLegendPosition)) {
+    throw new Error(
+      `Unknown facet shared legend position "${sharedLegendPosition}".`
+    );
+  }
+  const sideLegend = ["right", "left"].includes(sharedLegendPosition);
+  const beforeGrid = ["left", "top"].includes(sharedLegendPosition);
+  const legendLane = sharedLegend
+    ? legendGap + (sideLegend ? legendWidth : legendHeight)
+    : 0;
   const rowCount = Math.ceil(resolvedChildren.length / resolvedColumns);
   const columnWidths = Array(resolvedColumns).fill(-Infinity);
   const rowHeights = Array(rowCount).fill(-Infinity);
@@ -83,14 +104,16 @@ export function resolveFacetLayout({
       value: values[index],
       column,
       row,
-      x: columnStarts[column] + alignedOffset(
-        columnWidths[column] - child.width,
-        resolvedAlign
-      ),
-      y: rowStarts[row] + alignedOffset(
-        rowHeights[row] - child.height,
-        resolvedAlign
-      ),
+      x: columnStarts[column] + (beforeGrid && sideLegend ? legendLane : 0) +
+        alignedOffset(
+          columnWidths[column] - child.width,
+          resolvedAlign
+        ),
+      y: rowStarts[row] + (beforeGrid && !sideLegend ? legendLane : 0) +
+        alignedOffset(
+          rowHeights[row] - child.height,
+          resolvedAlign
+        ),
       width: child.width,
       height: child.height
     };
@@ -111,16 +134,22 @@ export function resolveFacetLayout({
     padding: resolvedPadding,
     titleHeight: resolvedTitleHeight,
     gridWidth,
-    width: gridWidth + (sharedLegend
-      ? legendGap + legendWidth
-      : 0),
-    height: gridHeight,
+    width: gridWidth + (sideLegend ? legendLane : 0),
+    height: gridHeight + (sideLegend ? 0 : legendLane),
     children: placements,
     ...(sharedLegend ? {
       legend: {
-        x: gridWidth + legendGap,
-        y: resolvedTitleHeight + resolvedPadding.top + 30,
-        width: legendWidth
+        position: sharedLegendPosition,
+        x: sharedLegendPosition === "right"
+          ? gridWidth + legendGap
+          : 0,
+        y: sharedLegendPosition === "bottom"
+          ? gridHeight + legendGap
+          : sharedLegendPosition === "top"
+            ? resolvedTitleHeight
+            : resolvedTitleHeight + resolvedPadding.top + 30,
+        width: legendWidth,
+        height: legendHeight
       }
     } : {})
   });

package/src/materialization/facetGuides/legacyCategorical.js

@@ -69,7 +69,13 @@ export function resolveLegacyCategoricalLegend(program) {
   return {
     mode: "legacyCategorical",
     compatibility,
-    reservation: { gap: 18, width: 132 },
+    reservation: {
+      position: "right",
+      align: "center",
+      gap: 18,
+      width: 132,
+      height: 0
+    },
     legend: {
       field: config.field,
       mark: encodings[0].layer.mark.type,

package/src/materialization/facetGuides/placement.js

@@ -33,12 +33,27 @@ function removeNamespacedGraphics(program, namespace, ids) {
 }
 
 function legendTranslation(prepared, plot, layout) {
+  const position = prepared.reservation.position;
+  if (["top", "bottom"].includes(position)) {
+    const width = prepared.bounds.right - prepared.bounds.left;
+    const left = prepared.reservation.align === "left"
+      ? plot.x
+      : prepared.reservation.align === "right"
+        ? plot.x + plot.width - width
+        : plot.x + (plot.width - width) / 2;
+    return {
+      x: left - prepared.bounds.left,
+      y: layout.legend.y - prepared.bounds.top
+    };
+  }
   const strips = prepared.source.graphicSpec.objects.colorGradientStrips;
   if (strips?.items?.[0] !== undefined) {
     const properties = strips.items[0].properties;
     const length = prepared.source.guideConfigs.legend.gradient.gradient.length;
     return {
-      x: layout.legend.x - properties.x,
+      x: layout.legend.x - (position === "left"
+        ? prepared.bounds.left
+        : properties.x),
       y: plot.y + (plot.height - length) / 2 - properties.y
     };
   }

package/src/materialization/facetGuides/preparation.js

@@ -149,6 +149,27 @@ function compatibleLegendChildren(program, source, inferred) {
   });
 }
 
+function promotedLegendPlacement(source, kinds) {
+  const positioned = kinds.map(kind => source.guideConfigs.legend[kind])
+    .filter(config => config.position !== undefined);
+  const positions = new Set(positioned.map(config => config.position));
+  if (positions.size > 1) {
+    throw new Error(
+      "Shared facet legends must use one common edge position."
+    );
+  }
+  const aligns = new Set(positioned.map(config => config.align ?? "center"));
+  if (aligns.size > 1) {
+    throw new Error(
+      "Shared facet legends must use one common alignment."
+    );
+  }
+  return {
+    position: positioned[0]?.position ?? "right",
+    align: positioned[0]?.align ?? "center"
+  };
+}
+
 export function prepareSharedFacetLegend(program) {
   if (program.compositionSpec.facet.guides.legend !== "shared") {
     return undefined;
@@ -176,6 +197,8 @@ export function prepareSharedFacetLegend(program) {
     throw new Error("Shared facet legend has no measurable concrete bounds.");
   }
   const gradient = kinds.includes("gradient");
+  const placement = promotedLegendPlacement(source, kinds);
+  const width = Math.ceil(bounds.right - bounds.left);
   return {
     mode: "promoted",
     source,
@@ -185,8 +208,10 @@ export function prepareSharedFacetLegend(program) {
     bounds,
     compatibility,
     reservation: {
+      ...placement,
       gap: gradient ? 24 : 18,
-      width: gradient ? 112 : Math.max(132, Math.ceil(bounds.right - bounds.left))
+      width: Math.max(gradient ? 112 : 132, width),
+      height: Math.ceil(bounds.bottom - bounds.top)
     }
   };
 }

package/src/materialization/facets.js

@@ -175,7 +175,9 @@ export function resolveFacetProgramLayout(program, preparedLegend) {
     sharedLegend: spec.facet.guides.legend === "shared",
     ...(preparedLegend === undefined ? {} : {
       sharedLegendGap: preparedLegend.reservation.gap,
-      sharedLegendWidth: preparedLegend.reservation.width
+      sharedLegendWidth: preparedLegend.reservation.width,
+      sharedLegendHeight: preparedLegend.reservation.height,
+      sharedLegendPosition: preparedLegend.reservation.position
     })
   });
   const plots = spec.children.map(id => ({

package/src/materialization/marks/capabilities.js

@@ -108,11 +108,19 @@ export function isIntentionallyEmptyArea(program, layer) {
 export function canMaterializeArc(_program, layer) {
   if (
     layer.mark?.type !== "arc" ||
-    layer.encoding?.theta?.scale === undefined ||
-    !["nominal", "ordinal"].includes(layer.encoding.theta.fieldType)
+    layer.encoding?.theta?.scale === undefined
   ) {
     return false;
   }
+  if (layer.encoding.theta.fieldType === "quantitative") {
+    return (
+      layer.encoding.theta.aggregate === undefined &&
+      layer.encoding?.radius === undefined
+    );
+  }
+  if (!["nominal", "ordinal"].includes(layer.encoding.theta.fieldType)) {
+    return false;
+  }
   if (["count", "sum"].includes(layer.encoding.theta.aggregate)) {
     return layer.encoding?.radius === undefined;
   }

package/src/materialization/marks/index.js

@@ -1,4 +1,7 @@
-import { POSITION_CHANNELS } from "../../core/vocabulary.js";
+import {
+  POSITION_CHANNELS,
+  POSITION_ENCODING_CHANNELS
+} from "../../core/vocabulary.js";
 import { getMarkMaterializationPolicy } from "./policies.js";
 
 export {
@@ -75,7 +78,7 @@ export function getPositionEncodingMaterializationSteps(program, layer, scaleId)
 export function getScaleConsumerMaterializationMode(layer, channel) {
   const policy = getMarkMaterializationPolicy(layer);
   if (policy === undefined) return "direct";
-  if (POSITION_CHANNELS.includes(channel)) {
+  if (POSITION_ENCODING_CHANNELS.includes(channel)) {
     return policy.scaleApplication.position ?? policy.scaleApplication.default;
   }
   if (policy.scaleApplication.deferredChannels?.includes(channel)) {

package/src/materialization/rowEncoding.js

@@ -1,11 +1,19 @@
-import { POSITION_CHANNELS } from "../core/vocabulary.js";
 import {
+  OFFSET_POSITION_CHANNELS,
+  POSITION_CHANNELS
+} from "../core/vocabulary.js";
+import {
+  mapOrdinalOffsetValues,
   mapOrdinalPositionValues,
   readNominalField,
   readQuantitativeField,
   readScaleField,
   readTemporalField
 } from "../grammar/scales/index.js";
+import {
+  finiteMidpoint,
+  requireFiniteResult
+} from "../grammar/numeric.js";
 import { mapScaleConsumerValues } from "./scales/map.js";
 
 export function resolveRowEncodingValues(program, layer, dataset, channel) {
@@ -27,7 +35,55 @@ export function resolveRowEncodingValues(program, layer, dataset, channel) {
       : encoding.fieldType === "temporal"
         ? readTemporalField(dataset.values, encoding.field)
         : readQuantitativeField(dataset.values, encoding.field);
+  if (categorical && OFFSET_POSITION_CHANNELS.includes(channel)) {
+    return mapOrdinalOffsetValues(values, scale);
+  }
   return categorical && POSITION_CHANNELS.includes(channel)
     ? mapOrdinalPositionValues(values, scale)
     : mapScaleConsumerValues(values, scale, channel);
 }
+
+export function applyOffsetPositionValues({
+  base,
+  offset,
+  parentScale,
+  offsetScale,
+  channel
+}) {
+  if (base.length !== offset.length) {
+    throw new Error(`${channel} offset values must match the base position grain.`);
+  }
+  const midpoint = finiteMidpoint(offsetScale.range[0], offsetScale.range[1]);
+  const direction = Math.sign(parentScale.step) ||
+    Math.sign(parentScale.range[1] - parentScale.range[0]) || 1;
+  return Object.freeze(base.map((value, index) => {
+    if (!Number.isFinite(value) || !Number.isFinite(offset[index])) {
+      return undefined;
+    }
+    return requireFiniteResult(
+      value + direction * (offset[index] - midpoint),
+      `${channel} offset position`
+    );
+  }));
+}
+
+export function resolveRowPositionValues(program, layer, dataset, channel) {
+  const base = resolveRowEncodingValues(program, layer, dataset, channel);
+  if (base === undefined) return undefined;
+  const offsetChannel = channel === "x" ? "xOffset" : "yOffset";
+  const offsetEncoding = layer.encoding?.[offsetChannel];
+  if (offsetEncoding === undefined) return base;
+  const offset = resolveRowEncodingValues(
+    program,
+    layer,
+    dataset,
+    offsetChannel
+  );
+  return applyOffsetPositionValues({
+    base,
+    offset,
+    parentScale: program.resolvedScales[layer.encoding[channel].scale],
+    offsetScale: program.resolvedScales[offsetEncoding.scale],
+    channel
+  });
+}