ggaction 0.0.12 → 0.0.15

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

package/src/grammar/bars/aggregate.js

@@ -1,15 +1,9 @@
+import { readSeriesIdentity } from "../pathSeries.js";
 import { cloneAndFreeze } from "../../core/immutable.js";
 import { readNominalField, readTemporalField } from "../scales/index.js";
-import {
-  aggregateRows,
-  validateAggregateFieldType,
-  validateAggregateFieldValues,
-} from "../aggregate.js";
-import {
-  BAR_GRAINS,
-  resolveBarChannels,
-  resolveBarGrain
-} from "./policy.js";
+import { aggregateRows, validateAggregateFieldType, validateAggregateFieldValues } from "../aggregate.js";
+import { BAR_GRAINS, resolveBarChannels, resolveBarGrain, resolveBarColorLayout } from "./policy.js";
+import { layoutSeriesPartition } from "../seriesLayout.js";
 
 function requireAggregateBarEncoding(layer) {
   if (layer?.mark?.type !== "bar") {
@@ -33,7 +27,7 @@ export function deriveBarAggregates(rows, layer) {
   const { channels, category, measure } = requireAggregateBarEncoding(layer);
   validateAggregateFieldValues(rows, measure.field, measure.fieldType);
   const categoryValues = category.fieldType === "temporal"
-    ? readTemporalField(rows, category.field)
+    ? readTemporalField(rows, category.field, category.temporalUnit)
     : readNominalField(rows, category.field);
   const color = layer.encoding?.color;
   let colorValues;
@@ -52,18 +46,26 @@ export function deriveBarAggregates(rows, layer) {
       );
     }
   }
+  const identity = layer.encoding?.group === undefined ? undefined : readSeriesIdentity(rows, layer);
   const groups = new Map();
 
   for (let index = 0; index < rows.length; index += 1) {
     const categoryValue = categoryValues[index];
     const colorValue = colorValues?.[index];
-    const key = JSON.stringify([categoryValue, colorValue]);
+    const seriesValue = identity?.values[index];
+    const key = JSON.stringify([categoryValue, identity === undefined ? colorValue : seriesValue]);
     const group = groups.get(key) ?? {
       category: categoryValue,
+      ...(identity === undefined ? {} : { series: seriesValue }),
       ...(colorValues === undefined ? {} : { color: colorValue }),
-      rows: []
+      rows: [],
+      sourceIndices: []
     };
+    if (identity !== undefined && colorValues !== undefined && group.color !== colorValue) {
+      throw new Error("Bar color requires one categorical value within each aggregate cell.");
+    }
     group.rows.push(rows[index]);
+    group.sourceIndices.push(index);
     groups.set(key, group);
   }
 
@@ -82,6 +84,8 @@ export function deriveBarAggregates(rows, layer) {
       x: channels.category === "x" ? group.category : value,
       y: channels.category === "y" ? group.category : value,
       ...(color === undefined ? {} : { color: aggregateColor }),
+      ...(identity === undefined ? {} : { series: group.series }),
+      sourceIndices: group.sourceIndices,
       count: group.rows.length
     }];
   });
@@ -96,3 +100,23 @@ export function deriveBarAggregates(rows, layer) {
     values
   });
 }
+
+export function deriveSeriesBarCells(rows, layer, categoryDomain, seriesDomain) {
+  const channels = resolveBarChannels(layer);
+  const values = deriveBarAggregates(rows, layer).values;
+  const identity = readSeriesIdentity(rows, layer);
+  const categories = categoryDomain ?? [...new Set(values.map(cell => cell[channels.category]))].sort((a, b) => a - b);
+  const seriesKey = cell => layer.encoding.group !== undefined ? cell.series : layer.encoding.color?.fieldType === "quantitative" ? undefined : cell.color;
+  const series = seriesDomain ?? (layer.encoding.group !== undefined ? identity.domain : [...new Set(values.map(seriesKey))]);
+  const cells = new Map(values.map(cell => [JSON.stringify([cell[channels.category], seriesKey(cell)]), cell]));
+  const layout = resolveBarColorLayout(layer);
+  return categories.flatMap(category => {
+    const partition = series.map(key => cells.get(JSON.stringify([category, key])));
+    const segments = layout === "group"
+      ? partition.flatMap((cell, index) => cell === undefined ? [] : [{ index, start: 0, end: cell[channels.measure] }])
+      : layoutSeriesPartition(partition.map(cell => cell?.[channels.measure] ?? 0), layout);
+    return segments.flatMap(segment => partition[segment.index] === undefined ? [] : [{
+      cell: partition[segment.index], start: segment.start, end: segment.end, seriesIndex: segment.index
+    }]);
+  });
+}

package/src/grammar/bars/geometry.js

@@ -45,6 +45,50 @@ export function normalizeOffsetPadding(options = {}, existing, channel = "xOffse
   return cloneAndFreeze({ paddingInner, paddingOuter });
 }
 
+export function normalizeOffsetScalePolicy(
+  options = {},
+  existing,
+  channel = "xOffset"
+) {
+  const hasPadding = Object.hasOwn(options, "padding");
+  const hasInner = Object.hasOwn(options, "paddingInner");
+  const hasOuter = Object.hasOwn(options, "paddingOuter");
+  if (hasPadding && (hasInner || hasOuter)) {
+    throw new Error(
+      `${channel} padding cannot be combined with paddingInner or paddingOuter.`
+    );
+  }
+  const padding = hasPadding ? options.padding : undefined;
+  if (hasPadding && (!Number.isFinite(padding) || padding < 0 || padding >= 1)) {
+    throw new RangeError(
+      `${channel} padding must be from 0 (inclusive) to 1 (exclusive).`
+    );
+  }
+  const paddingInner = hasPadding
+    ? padding
+    : hasInner ? options.paddingInner : existing?.paddingInner ?? 0;
+  const paddingOuter = hasPadding
+    ? padding
+    : hasOuter ? options.paddingOuter : existing?.paddingOuter ?? 0;
+  const align = Object.hasOwn(options, "align")
+    ? options.align
+    : existing?.align ?? 0.5;
+  if (!Number.isFinite(paddingInner) || paddingInner < 0 || paddingInner >= 1) {
+    throw new RangeError(
+      `${channel} paddingInner must be from 0 (inclusive) to 1 (exclusive).`
+    );
+  }
+  if (!Number.isFinite(paddingOuter) || paddingOuter < 0) {
+    throw new RangeError(
+      `${channel} paddingOuter must be a non-negative finite number.`
+    );
+  }
+  if (!Number.isFinite(align) || align < 0 || align > 1) {
+    throw new RangeError(`${channel} align must be between 0 and 1.`);
+  }
+  return cloneAndFreeze({ paddingInner, paddingOuter, align });
+}
+
 export function resolveBarWidth(config, slotBandwidth) {
   if (!Number.isFinite(slotBandwidth) || slotBandwidth <= 0) {
     throw new Error("Bar width requires a positive resolved slot bandwidth.");

package/src/grammar/bars/policy.js

@@ -11,7 +11,7 @@ export const BAR_ORIENTATIONS = Object.freeze({
   horizontal: "horizontal"
 });
 
-function isCategory(encoding) {
+export function isBarCategoryEncoding(encoding) {
   return ["nominal", "ordinal", "temporal"].includes(encoding?.fieldType);
 }
 
@@ -27,14 +27,14 @@ export function resolveBarOrientation(layer) {
   if (x?.bin !== undefined && y?.aggregate === "count") {
     return BAR_ORIENTATIONS.vertical;
   }
-  if (isCategory(x) && y?.fieldType === "quantitative" && layer.encoding?.y2?.fieldType === "quantitative") {
+  if (isBarCategoryEncoding(x) && y?.fieldType === "quantitative" && layer.encoding?.y2?.fieldType === "quantitative") {
     return BAR_ORIENTATIONS.vertical;
   }
-  if (isCategory(y) && x?.fieldType === "quantitative" && layer.encoding?.x2?.fieldType === "quantitative") {
+  if (isBarCategoryEncoding(y) && x?.fieldType === "quantitative" && layer.encoding?.x2?.fieldType === "quantitative") {
     return BAR_ORIENTATIONS.horizontal;
   }
-  if (isCategory(x) && isMeasure(y)) return BAR_ORIENTATIONS.vertical;
-  if (isMeasure(x) && isCategory(y)) return BAR_ORIENTATIONS.horizontal;
+  if (isBarCategoryEncoding(x) && isMeasure(y)) return BAR_ORIENTATIONS.vertical;
+  if (isMeasure(x) && isBarCategoryEncoding(y)) return BAR_ORIENTATIONS.horizontal;
   return undefined;
 }
 
@@ -63,8 +63,8 @@ export function resolveBarGrain(layer) {
     return BAR_GRAINS.histogram;
   }
   if (
-    (isCategory(x) && y?.fieldType === "quantitative" && layer.encoding?.y2?.fieldType === "quantitative") ||
-    (isCategory(y) && x?.fieldType === "quantitative" && layer.encoding?.x2?.fieldType === "quantitative")
+    (isBarCategoryEncoding(x) && y?.fieldType === "quantitative" && layer.encoding?.y2?.fieldType === "quantitative") ||
+    (isBarCategoryEncoding(y) && x?.fieldType === "quantitative" && layer.encoding?.x2?.fieldType === "quantitative")
   ) return BAR_GRAINS.ranged;
   if (resolveBarOrientation(layer) !== undefined) {
     return BAR_GRAINS.aggregate;
@@ -73,6 +73,7 @@ export function resolveBarGrain(layer) {
 }
 
 export function inferBarColorLayout(layer) {
+  if (layer?.layout?.mode !== undefined) return layer.layout.mode;
   if (layer?.encoding?.color?.layout !== undefined) {
     return layer.encoding.color.layout;
   }
@@ -84,6 +85,7 @@ export function inferBarColorLayout(layer) {
 }
 
 export function resolveBarColorLayout(layer) {
+  if (layer?.layout?.mode !== undefined) return layer.layout.mode;
   if (layer?.encoding?.color?.layout !== undefined) {
     return layer.encoding.color.layout;
   }

package/src/grammar/bin.js

@@ -0,0 +1,226 @@
+import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
+import {
+  findHistogramBinIndex,
+  normalizeHistogramBin,
+  resolveHistogramBins
+} from "./histogram.js";
+import {
+  normalizeStatisticalWeight,
+  readStatisticalWeights,
+  sumEntryWeights,
+  summarizeStatisticalWeights,
+  validateWeightedNumericFields,
+  weightedRows
+} from "./weightedStatistics.js";
+
+const TRANSFORM_KEYS = Object.freeze([
+  "type", "field", "bin", "extent", "nice", "zero", "includeEmpty",
+  "members", "as", "weight", "resolved"
+]);
+const AS_KEYS = Object.freeze(["lower", "upper", "count", "members"]);
+const RESOLVED_KEYS = Object.freeze(["domain", "step", "boundaries"]);
+
+function rejectUnknownKeys(value, supported, label) {
+  const unknown = Object.keys(value).find(key => !supported.includes(key));
+  if (unknown !== undefined) {
+    throw new Error(`Unknown ${label} property "${unknown}".`);
+  }
+}
+
+function requireField(value, label) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError(`${label} must be a non-empty string.`);
+  }
+  return value;
+}
+
+function normalizeAs(field, value, members) {
+  const requested = value ?? {};
+  if (!isPlainObject(requested)) return requested;
+  const result = {
+    ...requested,
+    lower: requested.lower ?? `${field}_start`,
+    upper: requested.upper ?? `${field}_end`,
+    count: requested.count ?? "count"
+  };
+  if (members) result.members = requested.members ?? "members";
+  else if (Object.hasOwn(requested, "members")) result.members = requested.members;
+  return result;
+}
+
+export function normalizeBinTransform({
+  field,
+  maxBins,
+  step,
+  boundaries,
+  extent,
+  nice,
+  zero,
+  includeEmpty,
+  members,
+  as,
+  weight
+} = {}) {
+  const selected = [maxBins, step, boundaries].filter(value => value !== undefined);
+  if (selected.length > 1) {
+    throw new Error("Bin data accepts only one of maxBins, step, or boundaries.");
+  }
+  const bin = normalizeHistogramBin(
+    boundaries !== undefined ? { boundaries }
+      : step !== undefined ? { step }
+        : { maxBins: maxBins ?? 10 }
+  );
+  const resolvedMembers = members ?? false;
+  const transform = {
+    type: "bin",
+    field,
+    bin,
+    extent: extent ?? "auto",
+    nice: nice ?? true,
+    zero: zero ?? false,
+    includeEmpty: includeEmpty ?? true,
+    members: resolvedMembers,
+    as: normalizeAs(field, as, resolvedMembers),
+    ...(weight === undefined
+      ? {}
+      : { weight: normalizeStatisticalWeight(weight, "Bin weight") })
+  };
+  validateBinTransform(transform);
+  return cloneAndFreeze(transform);
+}
+
+export function validateBinTransform(transform) {
+  if (!isPlainObject(transform)) {
+    throw new TypeError("Bin transform must be a plain object.");
+  }
+  rejectUnknownKeys(transform, TRANSFORM_KEYS, "bin transform");
+  if (transform.type !== "bin") {
+    throw new Error(`Unsupported bin transform "${transform.type}".`);
+  }
+  requireField(transform.field, "Bin field");
+  if (transform.weight !== undefined) {
+    normalizeStatisticalWeight(transform.weight, "Bin weight");
+  }
+  normalizeHistogramBin(transform.bin);
+  if (
+    transform.extent !== "auto" &&
+    (!Array.isArray(transform.extent) || transform.extent.length !== 2 ||
+      !transform.extent.every(Number.isFinite) || transform.extent[0] >= transform.extent[1])
+  ) {
+    throw new TypeError("Bin extent must be auto or two ascending finite numbers.");
+  }
+  for (const property of ["nice", "zero", "includeEmpty", "members"]) {
+    if (typeof transform[property] !== "boolean") {
+      throw new TypeError(`Bin ${property} must be a boolean.`);
+    }
+  }
+  if (!isPlainObject(transform.as)) {
+    throw new TypeError("Bin as must be a plain object.");
+  }
+  rejectUnknownKeys(transform.as, AS_KEYS, "bin as");
+  const required = ["lower", "upper", "count", ...(transform.members ? ["members"] : [])];
+  if (!transform.members && Object.hasOwn(transform.as, "members")) {
+    throw new Error("Bin as.members requires members: true.");
+  }
+  const outputs = required.map(key => requireField(transform.as[key], `Bin as.${key}`));
+  if (new Set(outputs).size !== outputs.length) {
+    throw new Error("Bin output fields must be unique.");
+  }
+  if (transform.resolved !== undefined) {
+    if (!isPlainObject(transform.resolved)) {
+      throw new TypeError("Bin resolved must be a plain object.");
+    }
+    rejectUnknownKeys(transform.resolved, RESOLVED_KEYS, "bin resolved");
+    resolveHistogramBins({
+      values: transform.resolved.boundaries ?? [],
+      bin: { boundaries: transform.resolved.boundaries },
+      domain: transform.resolved.domain,
+      nice: transform.nice,
+      zero: transform.zero
+    });
+  }
+  return transform;
+}
+
+function readValues(rows, field) {
+  return rows.map((row, index) => {
+    const value = row[field];
+    if (!Number.isFinite(value)) {
+      throw new TypeError(`Bin field "${field}" must contain a finite number at row ${index}.`);
+    }
+    return value;
+  });
+}
+
+export function deriveBinRows(rows, transform) {
+  validateBinTransform(transform);
+  const values = readValues(rows, transform.field);
+  const weights = transform.weight === undefined
+    ? undefined
+    : readStatisticalWeights(rows, transform.weight, "Bin");
+  if (weights !== undefined) {
+    validateWeightedNumericFields(weights.entries, [transform.field], "Bin");
+  }
+  const weightSummary = weights === undefined
+    ? undefined
+    : summarizeStatisticalWeights(
+        weights.entries,
+        weights.definition.kind,
+        "Bin data"
+      );
+  const contributingValues = weightSummary === undefined
+    ? values
+    : weightSummary.positive.map(entry => entry.row[transform.field]);
+  if (
+    transform.extent !== "auto" &&
+    contributingValues.some(value =>
+      value < transform.extent[0] || value > transform.extent[1]
+    )
+  ) {
+    throw new RangeError("Bin extent must contain the histogram data extent.");
+  }
+  const resolved = resolveHistogramBins({
+    values: contributingValues,
+    bin: transform.bin,
+    domain: transform.extent,
+    nice: transform.nice,
+    zero: transform.zero
+  });
+  const members = resolved.boundaries.slice(0, -1).map(() => []);
+  const entries = weightSummary === undefined
+    ? rows.map((row, index) => ({ row, index }))
+    : weightSummary.positive;
+  entries.forEach(entry => {
+    const value = entry.row[transform.field];
+    const bin = findHistogramBinIndex(value, resolved.boundaries);
+    if (bin !== -1) members[bin].push(entry);
+  });
+  const output = members.flatMap((group, index) =>
+    !transform.includeEmpty && group.length === 0 ? [] : [{
+      [transform.as.lower]: resolved.boundaries[index],
+      [transform.as.upper]: resolved.boundaries[index + 1],
+      [transform.as.count]: weightSummary === undefined
+        ? group.length
+        : sumEntryWeights(group, weightSummary, "Bin mass"),
+      ...(transform.members
+        ? {
+            [transform.as.members]: weightSummary === undefined
+              ? group.map(entry => entry.row)
+              : weightedRows({ positive: group })
+          }
+        : {})
+    }]
+  );
+  return {
+    values: output,
+    resolved: {
+      domain: resolved.domain,
+      ...(resolved.step === undefined ? {} : { step: resolved.step }),
+      boundaries: resolved.boundaries
+    }
+  };
+}
+
+export function resolveBinTransform(result, transform) {
+  return cloneAndFreeze([{ ...transform, resolved: result.resolved }]);
+}

package/src/grammar/categoryOrder.js

@@ -2,6 +2,8 @@ import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
 import { isNominalValue, readNominalField } from "./scales/fields.js";
 import { aggregateScalarValues } from "./aggregate.js";
 
+export const CATEGORY_ORDER_CHANNELS = Object.freeze(["x", "y", "theta"]);
+
 const DIRECTIONS = ["ascending", "descending"];
 const AGGREGATES = ["sum", "mean", "min", "max"];
 
@@ -130,3 +132,35 @@ export function resolveCategoryOrder(rows, categoryField, order) {
     return direction * comparison || first.get(left) - first.get(right);
   }));
 }
+
+
+export function normalizeLegendOrder(order) {
+  if (order === "scale") return order;
+  if (!isPlainObject(order)) {
+    throw new TypeError('Legend order must be "scale", { values }, or { channel }.');
+  }
+  const keys = Object.keys(order);
+  if (keys.length !== 1 || !["values", "channel"].includes(keys[0])) {
+    throw new Error("Legend order requires exactly one of values or channel.");
+  }
+  if (keys[0] === "values") return normalizeCategoryOrder({ values: order.values });
+  if (!CATEGORY_ORDER_CHANNELS.includes(order.channel)) {
+    throw new Error("Legend order channel must be x, y, or theta.");
+  }
+  return cloneAndFreeze({ channel: order.channel });
+}
+
+export function resolveLegendOrderDomain(domain, order, linked, observed = domain) {
+  if (order === undefined || order === "scale") return domain;
+  const normalized = normalizeLegendOrder(order);
+  if (normalized.values !== undefined) {
+    const seen = [...new Set(observed)].filter(value => domain.some(item => Object.is(item, value)));
+    const available = [...seen, ...domain.filter(value => !seen.some(item => Object.is(item, value)))];
+    return resolveCategoryOrder(available.map(value => ({ value })), "value", normalized);
+  }
+  if (!Array.isArray(linked) || linked.length !== domain.length ||
+    !domain.every(value => linked.some(other => Object.is(value, other)))) {
+    throw new Error("Linked legend order requires the same categorical domain.");
+  }
+  return cloneAndFreeze(linked);
+}