ggaction 0.0.12 → 0.0.13

package/src/core/compositionState.js

@@ -11,24 +11,23 @@ function validateFacetSpec(compositionSpec) {
   }
   if (
     !Number.isInteger(compositionSpec.columns) ||
-    compositionSpec.columns <= 0 ||
-    compositionSpec.columns > compositionSpec.children.length
+    compositionSpec.columns <= 0
   ) {
     throw new RangeError(
-      "Facet compositionSpec.columns must be a positive integer no larger than its children."
+      "Facet compositionSpec.columns must be a positive integer."
     );
   }
   if (!isPlainObject(compositionSpec.facet)) {
     throw new TypeError("Facet compositionSpec.facet must be a plain object.");
   }
-  const facetKeys = ["data", "field", "values", "scales", "guides"];
+  const facetKeys = ["data", "field", "values", "grid", "repeat", "scales", "guides"];
   const unknownFacet = Object.keys(compositionSpec.facet).find(
     key => !facetKeys.includes(key)
   );
   if (unknownFacet !== undefined) {
     throw new Error(`Unknown compositionSpec.facet property "${unknownFacet}".`);
   }
-  for (const property of ["data", "field"]) {
+  for (const property of ["data"]) {
     if (
       typeof compositionSpec.facet[property] !== "string" ||
       compositionSpec.facet[property].length === 0
@@ -36,6 +35,129 @@ function validateFacetSpec(compositionSpec) {
       throw new TypeError(`compositionSpec.facet.${property} must be a non-empty string.`);
     }
   }
+  const grid = compositionSpec.facet.grid;
+  const repeat = compositionSpec.facet.repeat;
+  if (grid !== undefined && repeat !== undefined) {
+    throw new Error("Facet compositionSpec cannot combine grid and repeat recipes.");
+  }
+  if (grid === undefined && repeat === undefined) {
+    if (compositionSpec.columns > compositionSpec.children.length) {
+      throw new RangeError(
+        "Facet compositionSpec.columns must be no larger than its children."
+      );
+    }
+    if (
+      typeof compositionSpec.facet.field !== "string" ||
+      compositionSpec.facet.field.length === 0
+    ) {
+      throw new TypeError("compositionSpec.facet.field must be a non-empty string.");
+    }
+  } else if (grid !== undefined) {
+    if (compositionSpec.columns !== grid.columns?.values?.length) {
+      throw new RangeError(
+        "Grid facet compositionSpec.columns must match its column domain."
+      );
+    }
+    if (compositionSpec.facet.field !== undefined) {
+      throw new Error("Grid facet compositionSpec does not use facet.field.");
+    }
+    if (!isPlainObject(grid)) {
+      throw new TypeError("compositionSpec.facet.grid must be a plain object.");
+    }
+    const gridKeys = ["rows", "columns", "combinations", "cells"];
+    const unknownGrid = Object.keys(grid).find(key => !gridKeys.includes(key));
+    if (unknownGrid !== undefined) {
+      throw new Error(`Unknown compositionSpec.facet.grid property "${unknownGrid}".`);
+    }
+    for (const role of ["rows", "columns"]) {
+      const value = grid[role];
+      if (!isPlainObject(value) || Object.keys(value).some(
+        key => !["field", "values"].includes(key)
+      )) {
+        throw new TypeError(
+          `compositionSpec.facet.grid.${role} requires field and values.`
+        );
+      }
+      if (typeof value.field !== "string" || value.field.length === 0) {
+        throw new TypeError(
+          `compositionSpec.facet.grid.${role}.field must be a non-empty string.`
+        );
+      }
+      if (
+        !Array.isArray(value.values) || value.values.length === 0 ||
+        value.values.some(item => !(
+          typeof item === "string" || typeof item === "boolean" ||
+          (typeof item === "number" && Number.isFinite(item))
+        )) || new Set(value.values).size !== value.values.length
+      ) {
+        throw new TypeError(
+          `compositionSpec.facet.grid.${role}.values must contain unique scalars.`
+        );
+      }
+    }
+    if (grid.rows.field === grid.columns.field) {
+      throw new Error("compositionSpec.facet.grid fields must be different.");
+    }
+    if (!["observed", "full"].includes(grid.combinations)) {
+      throw new Error(
+        'compositionSpec.facet.grid.combinations must be "observed" or "full".'
+      );
+    }
+    if (!Array.isArray(grid.cells) || grid.cells.length !== compositionSpec.children.length) {
+      throw new TypeError(
+        "compositionSpec.facet.grid.cells must contain one descriptor per child."
+      );
+    }
+    const cellKeys = ["id", "row", "column", "rowValue", "columnValue", "empty"];
+    const coordinates = new Set();
+    for (const cell of grid.cells) {
+      if (!isPlainObject(cell) || Object.keys(cell).some(key => !cellKeys.includes(key))) {
+        throw new TypeError("compositionSpec.facet.grid cells must be canonical objects.");
+      }
+      if (!compositionSpec.children.includes(cell.id)) {
+        throw new Error(`Unknown grid facet child "${cell.id}".`);
+      }
+      if (!Number.isInteger(cell.row) || cell.row < 0 || cell.row >= grid.rows.values.length ||
+          !Number.isInteger(cell.column) || cell.column < 0 || cell.column >= grid.columns.values.length) {
+        throw new RangeError("Grid facet cell coordinates must be inside their domains.");
+      }
+      if (cell.rowValue !== grid.rows.values[cell.row] ||
+          cell.columnValue !== grid.columns.values[cell.column]) {
+        throw new Error("Grid facet cell values must match their row and column coordinates.");
+      }
+      if (typeof cell.empty !== "boolean") {
+        throw new TypeError("Grid facet cell empty must be a boolean.");
+      }
+      const key = `${cell.row}:${cell.column}`;
+      if (coordinates.has(key)) {
+        throw new Error("Grid facet cells must occupy unique coordinates.");
+      }
+      coordinates.add(key);
+    }
+  } else {
+    if (compositionSpec.facet.field !== undefined) {
+      throw new Error("Repeat compositionSpec does not use facet.field.");
+    }
+    if (compositionSpec.columns > compositionSpec.children.length) {
+      throw new RangeError(
+        "Repeat compositionSpec.columns must be no larger than its children."
+      );
+    }
+    if (!isPlainObject(repeat) || Object.keys(repeat).some(
+      key => !["target", "channel", "fields"].includes(key)
+    )) {
+      throw new TypeError(
+        "compositionSpec.facet.repeat requires target, channel, and fields."
+      );
+    }
+    if (typeof repeat.target !== "string" || repeat.target.length === 0 ||
+        !["x", "y"].includes(repeat.channel) ||
+        !Array.isArray(repeat.fields) || repeat.fields.length === 0 ||
+        repeat.fields.some(field => typeof field !== "string" || field.length === 0) ||
+        new Set(repeat.fields).size !== repeat.fields.length) {
+      throw new TypeError("compositionSpec.facet.repeat is not canonical.");
+    }
+  }
   const values = compositionSpec.facet.values;
   if (
     !Array.isArray(values) ||
@@ -45,12 +167,18 @@ function validateFacetSpec(compositionSpec) {
       typeof value === "boolean" ||
       (typeof value === "number" && Number.isFinite(value))
     )) ||
-    new Set(values).size !== values.length
+    (grid === undefined && new Set(values).size !== values.length)
   ) {
     throw new TypeError(
       "compositionSpec.facet.values must contain one unique scalar per child."
     );
   }
+  if (repeat !== undefined && (
+    values.length !== repeat.fields.length ||
+    values.some((value, index) => value !== repeat.fields[index])
+  )) {
+    throw new Error("compositionSpec.facet.values must match repeat fields.");
+  }
   const scales = compositionSpec.facet.scales;
   if (
     !isPlainObject(scales) ||
@@ -80,13 +208,13 @@ function validateFacetSpec(compositionSpec) {
 function validateCompositionChildren(compositionSpec, childIds, facet) {
   if (
     !Array.isArray(compositionSpec.children) ||
-    compositionSpec.children.length < (facet ? 1 : 2) ||
+    compositionSpec.children.length < 1 ||
     !compositionSpec.children.every(id => typeof id === "string" && id.length > 0)
   ) {
     throw new TypeError(
       facet
         ? "Facet compositionSpec.children requires at least one child ID."
-        : "compositionSpec.children requires at least two child IDs."
+        : "compositionSpec.children requires at least one child ID."
     );
   }
   if (new Set(compositionSpec.children).size !== compositionSpec.children.length) {

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.");
+  }
+}

package/src/grammar/areaSeries.js

@@ -1,15 +1,11 @@
 import { cloneAndFreeze } from "../core/immutable.js";
-import {
-  readNominalField,
-  readQuantitativeField,
-  readTemporalField
-} from "./scales/index.js";
-import {
-  layoutSeriesPartition,
-  validateColorLayout
-} from "./seriesLayout.js";
+import { readNominalField, readQuantitativeField, readTemporalField } from "./scales/index.js";
+import { layoutSeriesPartition, validateColorLayout } from "./seriesLayout.js";
 import { stableOrderPathValues } from "./pathOrder.js";
 import { deriveCategoricalDensitySeries } from "./categoricalDensity.js";
+import { validatePathSeriesAppearance } from "./pathSeries.js";
+import { readAreaEndpoint, validateAreaEndpointPair } from "./areaEndpoints.js";
+import { validateGeneratedItemLimit } from "../core/validation.js";
 
 function indexSegments(segments) {
   const indexed = [];
@@ -21,7 +17,7 @@ export function deriveAreaSeries(rows, layer) {
   if (layer?.mark?.type !== "area") {
     throw new Error("Area series derivation requires a semantic area mark.");
   }
-  const { x, y, x2, y2, group, color } = layer.encoding ?? {};
+  const { x, y, x2, y2 } = layer.encoding ?? {};
   const vertical =
     ["quantitative", "temporal"].includes(x?.fieldType) &&
     y?.fieldType === "quantitative" &&
@@ -37,26 +33,19 @@ export function deriveAreaSeries(rows, layer) {
       `Area mark "${layer.id}" requires exactly one quantitative x/x2 or y/y2 range and one quantitative or temporal independent position.`
     );
   }
-  if (group !== undefined && group.fieldType !== "nominal") {
-    throw new Error(`Area group encoding on mark "${layer.id}" must be nominal.`);
-  }
+  const grouping = validatePathSeriesAppearance(rows, layer);
   const orientation = vertical ? "vertical" : "horizontal";
   const independent = vertical ? x : y;
   const independentValues = independent.fieldType === "temporal"
-    ? readTemporalField(rows, independent.field)
+    ? readTemporalField(rows, independent.field, independent.temporalUnit)
     : readQuantitativeField(rows, independent.field);
-  const lower = vertical
-    ? readQuantitativeField(rows, y.field)
-    : readQuantitativeField(rows, x.field);
-  const upper = vertical
-    ? readQuantitativeField(rows, y2.field)
-    : readQuantitativeField(rows, x2.field);
-  const groupValues = group === undefined
-    ? rows.map(() => undefined)
-    : readNominalField(rows, group.field);
-  const colorValues = color === undefined
-    ? rows.map(() => undefined)
-    : readNominalField(rows, color.field);
+  if (Object.hasOwn(independent, "datum")) throw new Error("Area independent position requires a field.");
+  const primary = vertical ? y : x;
+  const secondary = vertical ? y2 : x2;
+  validateAreaEndpointPair(primary, secondary);
+  const missing = layer.mark.missing ?? "error";
+  const lower = readAreaEndpoint(rows, primary, missing);
+  const upper = readAreaEndpoint(rows, secondary, missing);
   const pathOrder = layer.encoding?.pathOrder;
   const orderValues = pathOrder === undefined
     ? undefined
@@ -64,32 +53,24 @@ export function deriveAreaSeries(rows, layer) {
   const groups = new Map();
 
   for (let index = 0; index < rows.length; index += 1) {
-    const key = groupValues[index];
+    const tuple = grouping.map(field => rows[index][field]);
+    const key = JSON.stringify(tuple);
     const series = groups.get(key) ?? {
-      key: {
-        ...(group === undefined ? {} : { [group.field]: key }),
-        ...(color === undefined ? {} : { [color.field]: colorValues[index] })
-      },
+      key: Object.fromEntries(grouping.map((field, i) => [field, tuple[i]])),
       values: []
     };
-    if (
-      color !== undefined &&
-      !Object.is(series.key[color.field], colorValues[index])
-    ) {
-      throw new Error(
-        `Area series "${String(key)}" must have one color value.`
-      );
-    }
     series.values.push(vertical
       ? {
           x: independentValues[index],
           y: lower[index],
           y2: upper[index],
+          ...(missing === "break" ? { sourceIndex: index } : {}),
           ...(orderValues === undefined ? {} : { pathOrder: orderValues[index] })
         }
       : {
           x: lower[index],
           x2: upper[index],
+          ...(missing === "break" ? { sourceIndex: index } : {}),
           y: independentValues[index],
           ...(orderValues === undefined ? {} : { pathOrder: orderValues[index] })
         });
@@ -98,7 +79,8 @@ export function deriveAreaSeries(rows, layer) {
   if (groups.size === 0) {
     throw new Error(`Area mark "${layer.id}" has no values.`);
   }
-  const series = [...groups.values()].map(item => {
+  layoutRawAreaGroups(groups, { layer, vertical, primary, secondary });
+  const series = [...groups.values()].flatMap(item => {
     const key = vertical ? "x" : "y";
     const values = pathOrder === undefined
       ? item.values.sort((left, right) => left[key] - right[key])
@@ -107,6 +89,22 @@ export function deriveAreaSeries(rows, layer) {
           item.values.map(value => value.pathOrder),
           pathOrder.order
         );
+    if (missing === "break") {
+      const segments = [];
+      let segment = [];
+      const emit = () => {
+        if (segment.length >= 2) segments.push({ key: item.key,
+          sourceIndices: segment.map(value => value.sourceIndex),
+          values: segment.map(({ sourceIndex, ...value }) => value) });
+        segment = [];
+      };
+      for (const value of values) {
+        if ((vertical ? value.y == null || value.y2 == null : value.x == null || value.x2 == null)) emit();
+        else segment.push(value);
+      }
+      emit();
+      return segments;
+    }
     if (values.length < 2) {
       throw new Error(
         `Area series on mark "${layer.id}" requires at least two points.`
@@ -114,6 +112,7 @@ export function deriveAreaSeries(rows, layer) {
     }
     return { key: item.key, values };
   });
+  if (series.length === 0) throw new Error(`Area mark "${layer.id}" has no valid segment with at least two points.`);
   return cloneAndFreeze({
     orientation,
     xValues: series.flatMap(item => item.values.flatMap(value =>
@@ -151,7 +150,7 @@ export function deriveCenteredAreaSeries(rows, layer) {
     );
   }
   const xValues = x.fieldType === "temporal"
-    ? readTemporalField(rows, x.field)
+    ? readTemporalField(rows, x.field, x.temporalUnit)
     : readQuantitativeField(rows, x.field);
   const yValues = readQuantitativeField(rows, y.field);
   const groups = readNominalField(rows, group.field);
@@ -359,3 +358,50 @@ export function layoutDensityAreaSeries(derived, layout = "overlay") {
     }))
   });
 }
+
+export function layoutRawAreaGroups(groups, { layer, vertical, primary, secondary }) {
+  const mode = layer.layout?.mode ?? "overlay";
+  validateColorLayout(mode);
+  if (mode === "overlay") return;
+  if (mode === "group" || (mode === "center" && !vertical)) {
+    throw new Error(`Area layout "${mode}" is incompatible with this orientation.`);
+  }
+  const primaryDatum = Object.hasOwn(primary, "datum");
+  const secondaryDatum = Object.hasOwn(secondary, "datum");
+  if (primaryDatum === secondaryDatum || (primaryDatum ? primary.datum : secondary.datum) !== 0) {
+    throw new Error("Stacked area requires one value field and one zero datum endpoint.");
+  }
+  const position = vertical ? "x" : "y";
+  const lower = vertical ? "y" : "x", upper = `${lower}2`;
+  const measure = primaryDatum ? upper : lower;
+  const series = [...groups.values()];
+  const indices = series.map(item => {
+    const index = new Map();
+    for (const value of item.values) {
+      if (index.has(value[position])) throw new Error("Area layout requires unique group/position rows.");
+      index.set(value[position], value);
+    }
+    return index;
+  });
+  const positions = [...new Set(series.flatMap(item => item.values.map(value => value[position])))].sort((a, b) => a - b);
+  validateGeneratedItemLimit(positions.length * series.length, "Area layout cell count");
+  if (indices.some(index => index.size !== positions.length || positions.some(value => !index.has(value)))) {
+    throw new Error("Area layout requires an aligned row for every group and position.");
+  }
+  for (const position of positions) {
+    const points = indices.map(index => index.get(position));
+    if (points.some(point => point[measure] == null)) {
+      for (const point of points) { point[lower] = null; point[upper] = null; }
+      continue;
+    }
+    const segments = layoutSeriesPartition(points.map(point => point[measure]), mode);
+    const byIndex = new Map(segments.map(segment => [segment.index, segment]));
+    let endpoint = mode === "center" ? segments[0]?.start ?? 0 : 0;
+    points.forEach((point, index) => {
+      const segment = byIndex.get(index);
+      point[lower] = segment?.start ?? (mode === "diverging" ? 0 : endpoint);
+      point[upper] = segment?.end ?? (mode === "diverging" ? 0 : endpoint);
+      if (segment !== undefined && mode !== "diverging") endpoint = segment.end;
+    });
+  }
+}