ggaction 0.0.12 → 0.0.15

package/src/core/resourceReferences.js

@@ -0,0 +1,332 @@
+import { freezeOwned, isPlainObject } from "./immutable.js";
+import { validateUserId } from "./identifiers.js";
+
+export const RESOURCE_KINDS = Object.freeze([
+  "data", "scale", "coordinate", "mark", "selection"
+]);
+
+const DATA_VALUE_KEYS = new Set([
+  "data", "dataset", "dataId", "filteredData", "originalData",
+  "outlierDataId", "profileId", "summaryId"
+]);
+const DATA_SOURCE_CONFIGS = new Set([
+  "boxPlot", "density", "ecdfPlot", "endpointPlot", "errorBand", "errorBar",
+  "gradientPlot", "horizon", "intervalPlot", "markFilter", "raincloudPlot",
+  "regression", "violinPlot"
+]);
+const MARK_ID_KEYS = new Set([
+  "bandId", "bodyId", "centerId", "connectorId", "intervalId", "lineId",
+  "lowerBoundaryId", "lowerCapId", "medianId", "outlierId", "startId",
+  "stemId", "upperBoundaryId", "upperCapId", "whiskerId"
+]);
+
+function ownedPath(path) {
+  return freezeOwned([...path]);
+}
+
+function reference(kind, id, ownerKind, ownerId, path, strength = "live") {
+  if (typeof id !== "string" || id.length === 0) return undefined;
+  return freezeOwned({
+    kind,
+    id,
+    ownerKind,
+    ownerId,
+    path: ownedPath(path),
+    strength
+  });
+}
+
+function append(references, value) {
+  if (value !== undefined) references.push(value);
+}
+
+function collectKnownKeys(value, path, visit) {
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => collectKnownKeys(item, [...path, index], visit));
+    return;
+  }
+  if (!isPlainObject(value)) return;
+  for (const [key, child] of Object.entries(value)) {
+    visit(key, child, [...path, key], path);
+    collectKnownKeys(child, [...path, key], visit);
+  }
+}
+
+export function canonicalResourcePath(path) {
+  if (!Array.isArray(path)) {
+    throw new TypeError("Resource reference path must be an array.");
+  }
+  return path.map(part => {
+    if (Number.isInteger(part) && part >= 0) return `[${part}]`;
+    if (typeof part !== "string" || part.length === 0) {
+      throw new TypeError("Resource reference path parts must be names or indexes.");
+    }
+    return `.${part}`;
+  }).join("");
+}
+
+export function collectSemanticDataReferences(program) {
+  const references = [];
+  for (const layer of program.semanticSpec.layers) {
+    append(references, reference("data", layer.data, "layer", layer.id, ["data"]));
+  }
+  for (const dataset of program.semanticSpec.datasets) {
+    append(references, reference(
+      "data", dataset.source, "dataset", dataset.id, ["source"]
+    ));
+  }
+  return freezeOwned(references);
+}
+
+export function collectSemanticScaleReferences(program) {
+  const references = [];
+  for (const layer of program.semanticSpec.layers) {
+    for (const [channel, encoding] of Object.entries(layer.encoding ?? {})) {
+      append(references, reference(
+        "scale", encoding?.scale, "layer", layer.id,
+        ["encoding", channel, "scale"]
+      ));
+      if (channel === "parallel") {
+        for (const [index, dimension] of (encoding?.dimensions ?? []).entries()) {
+          append(references, reference(
+            "scale", dimension.scale, "layer", layer.id,
+            ["encoding", "parallel", "dimensions", index, "scale"]
+          ));
+        }
+      }
+    }
+  }
+  collectKnownKeys(program.semanticSpec.guides, [], (key, value, path) => {
+    if (key === "scale") {
+      append(references, reference(
+        "scale", value, "semanticGuide", "guides", path
+      ));
+    } else if (key === "scales" && Array.isArray(value)) {
+      value.forEach((id, index) => append(references, reference(
+        "scale", id, "semanticGuide", "guides", [...path, index]
+      )));
+    }
+  });
+  return freezeOwned(references);
+}
+
+export function collectSemanticCoordinateReferences(program) {
+  const references = [];
+  for (const layer of program.semanticSpec.layers) {
+    append(references, reference(
+      "coordinate", layer.coordinate, "layer", layer.id, ["coordinate"]
+    ));
+  }
+  collectKnownKeys(program.semanticSpec.guides, [], (key, value, path) => {
+    if (key === "coordinate") {
+      append(references, reference(
+        "coordinate", value, "semanticGuide", "guides", path
+      ));
+    }
+  });
+  return freezeOwned(references);
+}
+
+export function collectMarkConfigReferences(program) {
+  const references = [];
+  for (const layer of program.semanticSpec.layers) {
+    append(references, reference(
+      "mark", layer.source, "layer", layer.id, ["source"]
+    ));
+  }
+  for (const [ownerId, config] of Object.entries(program.markConfigs)) {
+    collectKnownKeys(config, [], (key, value, path, parentPath) => {
+      if (DATA_VALUE_KEYS.has(key)) {
+        append(references, reference("data", value, "markConfig", ownerId, path));
+      }
+      const root = parentPath[0];
+      if (key === "source" && DATA_SOURCE_CONFIGS.has(root)) {
+        append(references, reference("data", value, "markConfig", ownerId, path));
+      }
+      if (key === "coordinate") {
+        append(references, reference(
+          "coordinate", value, "markConfig", ownerId, path
+        ));
+      }
+      if ((key === "scale" || key.endsWith("Scale")) && typeof value === "string") {
+        append(references, reference("scale", value, "markConfig", ownerId, path));
+      } else if (key === "scale" && isPlainObject(value)) {
+        append(references, reference(
+          "scale", value.id, "markConfig", ownerId, [...path, "id"]
+        ));
+      }
+      if (MARK_ID_KEYS.has(key)) {
+        append(references, reference("mark", value, "markConfig", ownerId, path));
+      }
+      if (
+        (root === "errorBandBoundary" && key === "owner") ||
+        (parentPath.length === 0 && key === "boxSpanOwner") ||
+        (root === "raincloudPlot" && (
+          key === "ownerId" || parentPath[1] === "childIds" ||
+          parentPath[1] === "ownedChildIds"
+        ))
+      ) {
+        append(references, reference("mark", value, "markConfig", ownerId, path));
+      }
+    });
+    append(references, reference(
+      "mark", config.statisticalReference?.source,
+      "markConfig", ownerId, ["statisticalReference", "source"]
+    ));
+    for (const [index, id] of (
+      config.raincloudPlot?.ownedChildIds ?? []
+    ).entries()) {
+      append(references, reference(
+        "mark", id, "markConfig", ownerId,
+        ["raincloudPlot", "ownedChildIds", index]
+      ));
+    }
+    const selection = config.labelAuthoring?.selection;
+    if (selection?.kind === "named") {
+      append(references, reference(
+        "selection", selection.id, "markConfig", ownerId,
+        ["labelAuthoring", "selection", "id"]
+      ));
+    }
+  }
+  return freezeOwned(references);
+}
+
+export function collectGuideConfigReferences(program) {
+  const references = [];
+  for (const [family, configs] of Object.entries(program.guideConfigs ?? {})) {
+    collectKnownKeys(configs, [], (key, value, path, parentPath) => {
+      const ownerId = parentPath.length === 0 ? family : parentPath.join(".");
+      const relativePath = parentPath.length === 0
+        ? path
+        : path.slice(parentPath.length);
+      if (key === "scale") {
+        append(references, reference(
+          "scale", value, family, ownerId, relativePath
+        ));
+      } else if (key === "scales" && Array.isArray(value)) {
+        value.forEach((id, index) => append(references, reference(
+          "scale", id, family, ownerId, [...relativePath, index]
+        )));
+      } else if (key === "coordinate") {
+        append(references, reference(
+          "coordinate", value, family, ownerId, relativePath
+        ));
+      } else if (key === "target") {
+        append(references, reference(
+          "mark", value, family, ownerId, relativePath
+        ));
+      }
+    });
+  }
+  return freezeOwned(references);
+}
+
+export function collectSelectionReferences(program) {
+  const references = [];
+  for (const [id, config] of Object.entries(
+    program.materializationConfigs.selections ?? {}
+  )) {
+    append(references, reference(
+      "mark", config.target, "selection", id, ["target"]
+    ));
+  }
+  for (const [id, config] of Object.entries(
+    program.materializationConfigs.highlights ?? {}
+  )) {
+    append(references, reference(
+      "mark", config.target, "highlight", id, ["target"]
+    ));
+    append(references, reference(
+      "selection", config.selection, "highlight", id, ["selection"]
+    ));
+  }
+  return freezeOwned(references);
+}
+
+export function collectDataOwnerReferences(program) {
+  const references = [];
+  for (const [family, owners] of Object.entries(
+    program.materializationConfigs.data ?? {}
+  )) {
+    for (const [owner, config] of Object.entries(owners ?? {})) {
+      for (const key of ["current", "source", "previous"]) {
+        append(references, reference(
+          "data", config?.[key], "dataOwner", owner,
+          ["data", family, owner, key]
+        ));
+      }
+    }
+  }
+  return freezeOwned(references);
+}
+
+export function collectCompositionReferences(program) {
+  const references = [];
+  const composition = program.compositionSpec;
+  if (composition?.type !== "facet") return freezeOwned(references);
+  append(references, reference(
+    "data", composition.facet.data, "composition", composition.id,
+    ["facet", "data"]
+  ));
+  append(references, reference(
+    "mark", composition.facet.repeat?.target, "composition", composition.id,
+    ["facet", "repeat", "target"]
+  ));
+  return freezeOwned(references);
+}
+
+export function collectContextReferences(program) {
+  const references = [];
+  for (const [key, kind] of Object.entries({
+    currentData: "data",
+    currentScale: "scale",
+    currentCoordinate: "coordinate",
+    currentMark: "mark",
+    currentSelection: "selection"
+  })) {
+    append(references, reference(
+      kind, program.context[key], "context", "program", [key], "context"
+    ));
+  }
+  return freezeOwned(references);
+}
+
+function referenceKey(value) {
+  return [
+    value.kind, value.id, value.ownerKind, value.ownerId,
+    canonicalResourcePath(value.path), value.strength
+  ].join("\u0000");
+}
+
+function compareReferences(left, right) {
+  const leftKey = [
+    left.ownerKind, left.ownerId, canonicalResourcePath(left.path),
+    left.kind, left.id, left.strength
+  ].join("\u0000");
+  const rightKey = [
+    right.ownerKind, right.ownerId, canonicalResourcePath(right.path),
+    right.kind, right.id, right.strength
+  ].join("\u0000");
+  return leftKey < rightKey ? -1 : leftKey > rightKey ? 1 : 0;
+}
+
+export function collectResourceReferences(program, { kind, id }) {
+  if (!RESOURCE_KINDS.includes(kind)) {
+    throw new Error(`Unknown resource kind "${kind}".`);
+  }
+  const target = validateUserId(id, "Resource id");
+  const combined = [
+    ...collectSemanticDataReferences(program),
+    ...collectSemanticScaleReferences(program),
+    ...collectSemanticCoordinateReferences(program),
+    ...collectMarkConfigReferences(program),
+    ...collectGuideConfigReferences(program),
+    ...collectSelectionReferences(program),
+    ...collectDataOwnerReferences(program),
+    ...collectCompositionReferences(program),
+    ...collectContextReferences(program)
+  ].filter(value => value.kind === kind && value.id === target);
+  const unique = new Map(combined.map(value => [referenceKey(value), value]));
+  return freezeOwned([...unique.values()].sort(compareReferences));
+}

package/src/core/vocabulary.js

@@ -13,13 +13,13 @@ export const MARK_TYPES = Object.freeze([
 export const MARK_GRAPHIC_TYPES = Object.freeze({
   point: Object.freeze(["circle", "rect", "path", "collection"]),
   line: Object.freeze(["path"]),
-  bar: Object.freeze(["rect"]),
+  bar: Object.freeze(["rect", "collection"]),
   area: Object.freeze(["path"]),
   arc: Object.freeze(["path"]),
   rule: Object.freeze(["line"]),
   tick: Object.freeze(["line"]),
   text: Object.freeze(["text"]),
-  rect: Object.freeze(["rect"])
+  rect: Object.freeze(["rect", "collection"])
 });
 
 export const ENCODING_CHANNELS = Object.freeze([
@@ -32,6 +32,7 @@ export const ENCODING_CHANNELS = Object.freeze([
   "theta",
   "radius",
   "color",
+  "stroke",
   "strokeDash",
   "strokeWidth",
   "size",
@@ -155,13 +156,21 @@ export const FACET_SCALE_CHANNELS = Object.freeze([
   "y",
   "xOffset",
   "yOffset",
+  "theta",
+  "r",
   "color",
+  "stroke",
   "size",
   "shape",
   "opacity",
-  "strokeDash"
+  "strokeDash",
+  "parallelDimensions"
 ]);
 
+export function facetSemanticChannel(channel) {
+  return channel === "r" ? "radius" : channel;
+}
+
 export const FACET_SCALE_RESOLUTIONS = Object.freeze([
   "shared",
   "independent"
@@ -198,6 +207,7 @@ export const STACK_MODES = Object.freeze(["zero", "normalize", "center"]);
 
 export const CATEGORICAL_LEGEND_CHANNELS = Object.freeze([
   "color",
+  "stroke",
   "strokeDash",
   "shape"
 ]);
@@ -212,9 +222,12 @@ export const LEGEND_CHANNELS = Object.freeze([
 export const LEGEND_CONFIG_KINDS = Object.freeze([
   "series",
   "color",
+  "stroke",
   "size",
   "gradient",
   "interval",
+  "strokeGradient",
+  "strokeInterval",
   "opacity",
   "strokeWidth"
 ]);

package/src/grammar/aggregate.js

@@ -7,6 +7,10 @@ import {
   stableFiniteMean,
   stableFiniteSum
 } from "./numeric.js";
+import {
+  confidenceCriticalValue,
+  normalizeConfidenceInterval
+} from "./statistics/confidenceInterval.js";
 
 export const SCALAR_AGGREGATE_OPERATIONS = Object.freeze([
   "count", "sum", "mean", "median", "min", "max",
@@ -17,7 +21,9 @@ export const SCALAR_AGGREGATE_OPERATIONS = Object.freeze([
 
 const SCALAR_OPERATIONS = new Set(SCALAR_AGGREGATE_OPERATIONS);
 const NOMINAL_OPERATIONS = ["count", "distinct", "valid", "missing"];
-const PARAMETERIZED_OPERATIONS = ["quantile", "first", "last"];
+const PARAMETERIZED_OPERATIONS = [
+  "quantile", "first", "last", "ciLower", "ciUpper"
+];
 
 function nonEmptyString(value, label) {
   if (typeof value !== "string" || value.length === 0) {
@@ -83,6 +89,21 @@ export function validateAggregate(value) {
       order: value.order ?? "ascending"
     };
   }
+  if (value.op === "ciLower" || value.op === "ciUpper") {
+    const unknown = Object.keys(value).find(
+      key => !["op", "method", "level"].includes(key)
+    );
+    if (unknown !== undefined) {
+      throw new Error(`Unknown confidence aggregate property "${unknown}".`);
+    }
+    return {
+      op: value.op,
+      ...normalizeConfidenceInterval(value, {
+        defaultMethod: "normal",
+        label: "Aggregate confidence interval"
+      })
+    };
+  }
   throw new Error(`Unsupported aggregate "${value.op}".`);
 }
 
@@ -194,39 +215,44 @@ export function aggregateScalarValues(values, operation) {
   if (!Array.isArray(values)) {
     throw new TypeError("Aggregate values must be an array.");
   }
-  validateAggregate(operation);
-  if (!isScalarAggregate(operation)) {
+  const aggregate = validateAggregate(operation);
+  const scalarOperation = isScalarAggregate(aggregate)
+    ? aggregate
+    : ["ciLower", "ciUpper"].includes(aggregate.op)
+      ? aggregate.op
+      : undefined;
+  if (scalarOperation === undefined) {
     throw new Error("Scalar aggregate calculation requires a scalar operation.");
   }
 
-  if (operation === "count") return values.length;
+  if (scalarOperation === "count") return values.length;
   const valid = values.filter(value => !isMissing(value));
-  if (operation === "valid") return valid.length;
-  if (operation === "missing") return values.length - valid.length;
-  if (operation === "distinct") return new Set(valid).size;
+  if (scalarOperation === "valid") return valid.length;
+  if (scalarOperation === "missing") return values.length - valid.length;
+  if (scalarOperation === "distinct") return new Set(valid).size;
 
   const finite = finiteValues(values);
   if (finite.length === 0) return undefined;
-  if (operation === "sum") {
+  if (scalarOperation === "sum") {
     return stableFiniteSum(finite, "Aggregate sum");
   }
-  if (operation === "min") return numericExtent(finite)[0];
-  if (operation === "max") return numericExtent(finite)[1];
-  if (operation === "median") return quantile(finite, 0.5);
-  if (operation === "q1") return quantile(finite, 0.25);
-  if (operation === "q3") return quantile(finite, 0.75);
+  if (scalarOperation === "min") return numericExtent(finite)[0];
+  if (scalarOperation === "max") return numericExtent(finite)[1];
+  if (scalarOperation === "median") return quantile(finite, 0.5);
+  if (scalarOperation === "q1") return quantile(finite, 0.25);
+  if (scalarOperation === "q3") return quantile(finite, 0.75);
 
   const mean = stableFiniteMean(finite, "Aggregate mean");
-  if (operation === "mean") return mean;
-  if (["variance", "varianceP", "stdev", "stdevP"].includes(operation)) {
-    const population = operation.endsWith("P");
+  if (scalarOperation === "mean") return mean;
+  if (["variance", "varianceP", "stdev", "stdevP"].includes(scalarOperation)) {
+    const population = scalarOperation.endsWith("P");
     if (!population && finite.length < 2) return undefined;
     const kind = population ? "population" : "sample";
     const deviation = stableFiniteDeviation(finite, {
       sample: !population,
       label: `Aggregate ${kind} deviation`
     });
-    if (operation.startsWith("stdev")) return deviation.deviation;
+    if (scalarOperation.startsWith("stdev")) return deviation.deviation;
     return deviation.squared === undefined
       ? requireFiniteResult(
           deviation.deviation ** 2,
@@ -240,14 +266,25 @@ export function aggregateScalarValues(values, operation) {
     divisor: Math.sqrt(finite.length),
     label: "Aggregate standard error"
   }).deviation;
-  if (operation === "stderr") return stderr;
-  if (operation === "ciLower") {
-    return requireFiniteResult(mean - 1.96 * stderr, "Aggregate lower CI");
+  if (scalarOperation === "stderr") return stderr;
+  const confidence = isScalarAggregate(aggregate)
+    ? normalizeConfidenceInterval({}, {
+        defaultMethod: "normal",
+        label: "Aggregate confidence interval"
+      })
+    : aggregate;
+  const critical = confidenceCriticalValue({
+    method: confidence.method,
+    level: confidence.level,
+    degreesOfFreedom: finite.length - 1
+  });
+  if (scalarOperation === "ciLower") {
+    return requireFiniteResult(mean - critical * stderr, "Aggregate lower CI");
   }
-  if (operation === "ciUpper") {
-    return requireFiniteResult(mean + 1.96 * stderr, "Aggregate upper CI");
+  if (scalarOperation === "ciUpper") {
+    return requireFiniteResult(mean + critical * stderr, "Aggregate upper CI");
   }
-  throw new Error(`Unsupported scalar aggregate "${operation}".`);
+  throw new Error(`Unsupported scalar aggregate "${scalarOperation}".`);
 }
 
 export function aggregateRows(rows, field, operation) {
@@ -265,6 +302,9 @@ export function aggregateRows(rows, field, operation) {
       ? undefined
       : quantile(values, aggregate.probability);
   }
+  if (aggregate.op === "ciLower" || aggregate.op === "ciUpper") {
+    return aggregateScalarValues(rows.map(row => row[field]), aggregate);
+  }
   return aggregateOrderedRows(rows, field, aggregate);
 }
 
@@ -275,5 +315,8 @@ export function formatAggregateTitle(operation, field) {
   if (aggregate.op === "quantile") {
     return `quantile(${field}, ${aggregate.probability})`;
   }
+  if (aggregate.op === "ciLower" || aggregate.op === "ciUpper") {
+    return `${aggregate.op}(${field}, ${aggregate.method}, ${aggregate.level})`;
+  }
   return `${aggregate.op}(${field}, ${aggregate.orderBy} ${aggregate.order})`;
 }

package/src/grammar/arcs.js

@@ -241,6 +241,61 @@ function quantitativeSectors(rows, layer, thetaScale, frame, innerRadiusRatio) {
   }));
 }
 
+export function deriveMeasuredArcValues(rows, layer) {
+  const theta = requireArcLayer(layer);
+  const radius = layer.encoding?.radius;
+  if (!["nominal", "ordinal"].includes(theta.fieldType) || theta.aggregate !== undefined ||
+    !["count", "sum"].includes(radius?.aggregate) || radius.fieldType !== "quantitative") {
+    throw new Error("Measured Arc requires equal-angle categorical theta and count or sum radius.");
+  }
+  if (radius.aggregate === "count" && Object.hasOwn(radius, "field")) {
+    throw new Error("Measured count radius does not accept a field.");
+  }
+  const categories = readNominalField(rows, theta.field);
+  const measures = radius.aggregate === "count" ? rows.map(() => 1)
+    : readQuantitativeField(rows, radius.field);
+  if (measures.some(value => value < 0)) {
+    throw new RangeError("Measured Arc radius inputs must be non-negative.");
+  }
+  const colors = colorValues(rows, layer.encoding?.color);
+  const groups = new Map();
+  for (const [index, category] of categories.entries()) {
+    const group = groups.get(category) ?? { key: category, sourceIndices: [], values: [], colors: [] };
+    group.sourceIndices.push(index);
+    group.values.push(measures[index]);
+    group.colors.push(colors[index]);
+    groups.set(category, group);
+  }
+  const result = [...groups.values()].map(group => {
+    const distinctColors = [...new Set(group.colors)];
+    if (distinctColors.length > 1) {
+      throw new Error(`Measured Arc category "${group.key}" must resolve to one color value.`);
+    }
+    return { key: group.key, theta: group.key, count: group.sourceIndices.length,
+      radius: stableFiniteSum(group.values, "Measured Arc radius aggregate"),
+      color: distinctColors[0], sourceIndices: group.sourceIndices };
+  });
+  if (!result.some(group => group.radius > 0)) {
+    throw new Error("Measured Arc radius requires at least one positive category aggregate.");
+  }
+  return cloneAndFreeze(result);
+}
+
+function measuredRadialSectors(rows, layer, thetaScale, radiusScale) {
+  const items = deriveMeasuredArcValues(rows, layer);
+  const centers = mapOrdinalPositionValues(items.map(item => item.theta), thetaScale);
+  const radii = mapContinuousScaleValues(items.map(item => item.radius), radiusScale);
+  const halfBand = (Math.sign(thetaScale.step) || 1) * thetaScale.bandwidth / 2;
+  const byCategory = new Map(items.map((item, index) => [item.theta, {
+    ...item, startTheta: centers[index] - halfBand, endTheta: centers[index] + halfBand,
+    innerRadius: radiusScale.range[0], outerRadius: radii[index]
+  }]));
+  return thetaScale.domain.flatMap(category => {
+    const item = byCategory.get(category);
+    return item === undefined || item.radius === 0 ? [] : [item];
+  });
+}
+
 function radialSectors(rows, layer, thetaScale, radiusScale) {
   const theta = layer.encoding.theta;
   const radius = layer.encoding?.radius;
@@ -303,7 +358,9 @@ export function deriveArcSectors(rows, layer, {
   ) {
     throw new RangeError("Arc innerRadius must be from 0 (inclusive) to 1 (exclusive).");
   }
-  const sectors = theta.fieldType === "quantitative"
+  const sectors = radiusScale?.radialMapping !== undefined
+    ? measuredRadialSectors(rows, layer, requireBandScale(thetaScale, `Arc mark "${layer.id}" theta`), radiusScale)
+    : theta.fieldType === "quantitative"
     ? quantitativeSectors(
         rows,
         layer,

package/src/grammar/areaEndpoints.js

@@ -0,0 +1,46 @@
+import { validateKeys, validateNonEmptyString } from "../core/validation.js";
+import { isPlainObject } from "../core/immutable.js";
+import { readQuantitativeField } from "./scales/fields.js";
+
+export function validateAreaMissing(value = "error") {
+  if (!["error", "break"].includes(value)) {
+    throw new Error('Area missing must be "error" or "break".');
+  }
+  return value;
+}
+
+export function normalizeAreaBound(bound) {
+  if (typeof bound === "string") return { field: validateNonEmptyString(bound, "Area endpoint field") };
+  if (!isPlainObject(bound)) throw new TypeError("Area bound must be a field or datum object.");
+  validateKeys(bound, ["datum"], "Area bound");
+  if (!Number.isFinite(bound.datum)) throw new TypeError("Area datum must be finite.");
+  return { datum: bound.datum };
+}
+
+export function readAreaEndpoint(rows, encoding, missing = "error") {
+  if (Object.hasOwn(encoding, "datum")) {
+    if (Object.hasOwn(encoding, "field") || !Number.isFinite(encoding.datum) || encoding.fieldType !== "quantitative") {
+      throw new TypeError("Area endpoint requires exactly one finite quantitative datum or field.");
+    }
+    return rows.map(() => encoding.datum);
+  }
+  if (missing !== "break") return readQuantitativeField(rows, encoding.field);
+  validateNonEmptyString(encoding.field, "Area endpoint field");
+  if (rows.length > 0 && !rows.some(row => Object.hasOwn(row, encoding.field))) {
+    throw new Error(`Area endpoint field "${encoding.field}" does not exist.`);
+  }
+  return rows.map((row, index) => {
+    const value = row[encoding.field];
+    if (value == null) return null;
+    if (!Number.isFinite(value)) {
+      throw new TypeError(`Field "${encoding.field}" must contain a finite number at row ${index}.`);
+    }
+    return value;
+  });
+}
+
+export function validateAreaEndpointPair(primary, secondary) {
+  if (primary?.datum !== undefined && secondary?.datum !== undefined) {
+    throw new Error("Area range requires at least one field endpoint.");
+  }
+}