ggaction 0.0.4 → 0.0.6

package/src/grammar/areaSeries.js

@@ -8,12 +8,14 @@ import {
   layoutSeriesPartition,
   validateColorLayout
 } from "./seriesLayout.js";
+import { stableOrderPathValues } from "./pathOrder.js";
+import { deriveCategoricalDensitySeries } from "./categoricalDensity.js";
 
 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 } = layer.encoding ?? {};
+  const { x, y, x2, y2, group, color } = layer.encoding ?? {};
   const vertical =
     ["quantitative", "temporal"].includes(x?.fieldType) &&
     y?.fieldType === "quantitative" &&
@@ -46,24 +48,44 @@ export function deriveAreaSeries(rows, layer) {
   const groupValues = group === undefined
     ? rows.map(() => undefined)
     : readNominalField(rows, group.field);
+  const colorValues = color === undefined
+    ? rows.map(() => undefined)
+    : readNominalField(rows, color.field);
+  const pathOrder = layer.encoding?.pathOrder;
+  const orderValues = pathOrder === undefined
+    ? undefined
+    : readQuantitativeField(rows, pathOrder.field);
   const groups = new Map();
 
   for (let index = 0; index < rows.length; index += 1) {
     const key = groupValues[index];
     const series = groups.get(key) ?? {
-      key: group === undefined ? {} : { [group.field]: key },
+      key: {
+        ...(group === undefined ? {} : { [group.field]: key }),
+        ...(color === undefined ? {} : { [color.field]: colorValues[index] })
+      },
       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]
+          y2: upper[index],
+          ...(orderValues === undefined ? {} : { pathOrder: orderValues[index] })
         }
       : {
           x: lower[index],
           x2: upper[index],
-          y: independentValues[index]
+          y: independentValues[index],
+          ...(orderValues === undefined ? {} : { pathOrder: orderValues[index] })
         });
     groups.set(key, series);
   }
@@ -72,7 +94,13 @@ export function deriveAreaSeries(rows, layer) {
   }
   const series = [...groups.values()].map(item => {
     const key = vertical ? "x" : "y";
-    const values = item.values.sort((left, right) => left[key] - right[key]);
+    const values = pathOrder === undefined
+      ? item.values.sort((left, right) => left[key] - right[key])
+      : stableOrderPathValues(
+          item.values.map(({ pathOrder: _pathOrder, ...value }) => value),
+          item.values.map(value => value.pathOrder),
+          pathOrder.order
+        );
     if (values.length < 2) {
       throw new Error(
         `Area series on mark "${layer.id}" requires at least two points.`
@@ -96,9 +124,17 @@ export function deriveDensityAreaSeries(rows, layer, transform) {
   if (layer?.mark?.type !== "area") {
     throw new Error("Density area derivation requires a semantic area mark.");
   }
+  if (layer.encoding?.pathOrder !== undefined) {
+    throw new Error(
+      `Density area mark "${layer.id}" does not support path order.`
+    );
+  }
   if (transform?.type !== "density" || !Array.isArray(transform.as)) {
     throw new Error(`Area mark "${layer.id}" requires density provenance.`);
   }
+  if (transform.placement?.type === "category") {
+    return deriveCategoricalDensitySeries(rows, layer, transform);
+  }
   const { x, y, group } = layer.encoding ?? {};
   if (
     x?.fieldType !== "quantitative" ||

package/src/grammar/bin2d.js

@@ -0,0 +1,333 @@
+import {
+  cloneAndFreeze,
+  isPlainObject
+} from "../core/immutable.js";
+
+const TRANSFORM_KEYS = Object.freeze([
+  "type", "x", "y", "bins", "extent", "includeEmpty", "members", "as",
+  "resolved"
+]);
+const BIN_KEYS = Object.freeze(["x", "y"]);
+const EXTENT_KEYS = Object.freeze(["x", "y"]);
+const FIELD_KEYS = Object.freeze(["x0", "x1", "y0", "y1", "count", "members"]);
+const RESOLVED_KEYS = Object.freeze([
+  "extent", "edges", "eligibleCount", "occupiedCount"
+]);
+
+function requireField(value, label) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError(`${label} must be a non-empty string.`);
+  }
+  return value;
+}
+
+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 requirePositiveInteger(value, label) {
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new RangeError(`${label} must be a positive integer.`);
+  }
+  return value;
+}
+
+function normalizeBins(value) {
+  if (value === undefined) return { x: 10, y: 10 };
+  if (Number.isInteger(value)) return { x: value, y: value };
+  if (!isPlainObject(value)) {
+    throw new TypeError(
+      "2D bin bins must be a positive integer or an object with x and y."
+    );
+  }
+  rejectUnknownKeys(value, BIN_KEYS, "2D bin bins");
+  return { x: value.x, y: value.y };
+}
+
+function validateBins(value) {
+  if (!isPlainObject(value)) {
+    throw new TypeError("2D bin bins must be an object.");
+  }
+  rejectUnknownKeys(value, BIN_KEYS, "2D bin bins");
+  requirePositiveInteger(value.x, "2D bin x bins");
+  requirePositiveInteger(value.y, "2D bin y bins");
+}
+
+function normalizeRequestedExtent(value) {
+  if (value === undefined) return { x: "auto", y: "auto" };
+  if (!isPlainObject(value)) {
+    throw new TypeError("2D bin extent must be an object.");
+  }
+  rejectUnknownKeys(value, EXTENT_KEYS, "2D bin extent");
+  return {
+    x: value.x ?? "auto",
+    y: value.y ?? "auto"
+  };
+}
+
+function validateExtentValue(value, label, { allowAuto = true } = {}) {
+  if (allowAuto && value === "auto") return;
+  if (
+    !Array.isArray(value) ||
+    value.length !== 2 ||
+    !value.every(Number.isFinite) ||
+    value[0] >= value[1]
+  ) {
+    throw new RangeError(`${label} must be two increasing finite numbers.`);
+  }
+}
+
+function validateRequestedExtent(value) {
+  if (!isPlainObject(value)) {
+    throw new TypeError("2D bin extent must be an object.");
+  }
+  rejectUnknownKeys(value, EXTENT_KEYS, "2D bin extent");
+  validateExtentValue(value.x, "2D bin x extent");
+  validateExtentValue(value.y, "2D bin y extent");
+}
+
+function normalizeOutputFields(id, value, members) {
+  if (value !== undefined && !isPlainObject(value)) {
+    throw new TypeError("2D bin as must be an object.");
+  }
+  if (value !== undefined) rejectUnknownKeys(value, FIELD_KEYS, "2D bin as");
+  if (!members && value?.members !== undefined) {
+    throw new Error("2D bin as.members requires members: true.");
+  }
+  return {
+    x0: value?.x0 ?? `__${id}_x0`,
+    x1: value?.x1 ?? `__${id}_x1`,
+    y0: value?.y0 ?? `__${id}_y0`,
+    y1: value?.y1 ?? `__${id}_y1`,
+    count: value?.count ?? `__${id}_count`,
+    ...(members ? { members: value?.members ?? `__${id}_members` } : {})
+  };
+}
+
+function validateOutputFields(value, members) {
+  if (!isPlainObject(value)) {
+    throw new TypeError("2D bin as must be an object.");
+  }
+  rejectUnknownKeys(value, FIELD_KEYS, "2D bin as");
+  const required = ["x0", "x1", "y0", "y1", "count"];
+  if (members) required.push("members");
+  if (!members && value.members !== undefined) {
+    throw new Error("2D bin as.members requires members: true.");
+  }
+  const fields = required.map(role => requireField(
+    value[role],
+    `2D bin ${role} output field`
+  ));
+  if (new Set(fields).size !== fields.length) {
+    throw new Error("2D bin output fields must be unique.");
+  }
+}
+
+function validateEdges(value, extent, count, axis) {
+  if (
+    !Array.isArray(value) ||
+    value.length !== count + 1 ||
+    !value.every(Number.isFinite)
+  ) {
+    throw new TypeError(`Resolved 2D bin ${axis} edges are invalid.`);
+  }
+  if (value[0] !== extent[0] || value.at(-1) !== extent[1]) {
+    throw new Error(`Resolved 2D bin ${axis} edges must match its extent.`);
+  }
+  for (let index = 1; index < value.length; index += 1) {
+    if (value[index] <= value[index - 1]) {
+      throw new Error(`Resolved 2D bin ${axis} edges must be increasing.`);
+    }
+  }
+}
+
+function validateResolved(value, bins) {
+  if (!isPlainObject(value)) {
+    throw new TypeError("Resolved 2D bin state must be a plain object.");
+  }
+  rejectUnknownKeys(value, RESOLVED_KEYS, "resolved 2D bin");
+  if (!isPlainObject(value.extent) || !isPlainObject(value.edges)) {
+    throw new TypeError("Resolved 2D bin extent and edges must be objects.");
+  }
+  rejectUnknownKeys(value.extent, EXTENT_KEYS, "resolved 2D bin extent");
+  rejectUnknownKeys(value.edges, EXTENT_KEYS, "resolved 2D bin edges");
+  for (const axis of ["x", "y"]) {
+    validateExtentValue(
+      value.extent[axis],
+      `Resolved 2D bin ${axis} extent`,
+      { allowAuto: false }
+    );
+    validateEdges(value.edges[axis], value.extent[axis], bins[axis], axis);
+  }
+  for (const property of ["eligibleCount", "occupiedCount"]) {
+    if (!Number.isInteger(value[property]) || value[property] < 0) {
+      throw new RangeError(`Resolved 2D bin ${property} must be a non-negative integer.`);
+    }
+  }
+  if (value.occupiedCount > bins.x * bins.y) {
+    throw new RangeError("Resolved 2D bin occupiedCount exceeds the grid size.");
+  }
+}
+
+export function validateBin2DTransform(transform) {
+  if (!isPlainObject(transform)) {
+    throw new TypeError("2D bin transform must be a plain object.");
+  }
+  rejectUnknownKeys(transform, TRANSFORM_KEYS, "2D bin transform");
+  if (transform.type !== "bin2d") {
+    throw new Error(`Unsupported 2D bin transform "${transform.type}".`);
+  }
+  requireField(transform.x, "2D bin x field");
+  requireField(transform.y, "2D bin y field");
+  validateBins(transform.bins);
+  validateRequestedExtent(transform.extent);
+  if (typeof transform.includeEmpty !== "boolean") {
+    throw new TypeError("2D bin includeEmpty must be a boolean.");
+  }
+  if (typeof transform.members !== "boolean") {
+    throw new TypeError("2D bin members must be a boolean.");
+  }
+  validateOutputFields(transform.as, transform.members);
+  if (transform.resolved !== undefined) {
+    validateResolved(transform.resolved, transform.bins);
+  }
+  return transform;
+}
+
+export function normalizeBin2DTransform({
+  id,
+  x,
+  y,
+  bins,
+  extent,
+  includeEmpty = false,
+  members = false,
+  as
+} = {}) {
+  const normalizedBins = normalizeBins(bins);
+  const transform = {
+    type: "bin2d",
+    x,
+    y,
+    bins: normalizedBins,
+    extent: normalizeRequestedExtent(extent),
+    includeEmpty,
+    members,
+    as: normalizeOutputFields(id, as, members)
+  };
+  validateBin2DTransform(transform);
+  return cloneAndFreeze(transform);
+}
+
+function resolveExtent(values, requested, axis) {
+  const minimum = Math.min(...values);
+  const maximum = Math.max(...values);
+  const extent = requested === "auto" ? [minimum, maximum] : requested;
+  if (extent[0] > minimum || extent[1] < maximum) {
+    throw new RangeError(
+      `2D bin ${axis} extent must contain every eligible value.`
+    );
+  }
+  if (extent[0] === extent[1]) {
+    throw new RangeError(`2D bin ${axis} extent must have positive span.`);
+  }
+  return [...extent];
+}
+
+function createEdges(extent, count) {
+  const [minimum, maximum] = extent;
+  const step = (maximum - minimum) / count;
+  return Array.from({ length: count + 1 }, (_, index) =>
+    index === count ? maximum : minimum + step * index
+  );
+}
+
+function findBinIndex(value, edges) {
+  if (value === edges.at(-1)) return edges.length - 2;
+  let low = 0;
+  let high = edges.length - 1;
+  while (low + 1 < high) {
+    const middle = Math.floor((low + high) / 2);
+    if (value < edges[middle]) high = middle;
+    else low = middle;
+  }
+  return low;
+}
+
+export function deriveBin2DRows(rows, transform) {
+  if (!Array.isArray(rows)) {
+    throw new TypeError("2D bin source rows must be an array.");
+  }
+  validateBin2DTransform(transform);
+  const eligible = rows.flatMap((row, index) =>
+    isPlainObject(row) &&
+    Number.isFinite(row[transform.x]) &&
+    Number.isFinite(row[transform.y])
+      ? [{ index, row }]
+      : []
+  );
+  if (eligible.length === 0) {
+    throw new Error(
+      "2D bin requires at least one row with finite x and y values."
+    );
+  }
+  const extent = {
+    x: resolveExtent(
+      eligible.map(item => item.row[transform.x]),
+      transform.extent.x,
+      "x"
+    ),
+    y: resolveExtent(
+      eligible.map(item => item.row[transform.y]),
+      transform.extent.y,
+      "y"
+    )
+  };
+  const edges = {
+    x: createEdges(extent.x, transform.bins.x),
+    y: createEdges(extent.y, transform.bins.y)
+  };
+  const buckets = Array.from(
+    { length: transform.bins.x * transform.bins.y },
+    () => []
+  );
+  for (const item of eligible) {
+    const xIndex = findBinIndex(item.row[transform.x], edges.x);
+    const yIndex = findBinIndex(item.row[transform.y], edges.y);
+    buckets[yIndex * transform.bins.x + xIndex].push(item.index);
+  }
+  const values = [];
+  for (let yIndex = 0; yIndex < transform.bins.y; yIndex += 1) {
+    for (let xIndex = 0; xIndex < transform.bins.x; xIndex += 1) {
+      const memberIndexes = buckets[yIndex * transform.bins.x + xIndex];
+      if (!transform.includeEmpty && memberIndexes.length === 0) continue;
+      values.push({
+        [transform.as.x0]: edges.x[xIndex],
+        [transform.as.x1]: edges.x[xIndex + 1],
+        [transform.as.y0]: edges.y[yIndex],
+        [transform.as.y1]: edges.y[yIndex + 1],
+        [transform.as.count]: memberIndexes.length,
+        ...(transform.members
+          ? { [transform.as.members]: [...memberIndexes] }
+          : {})
+      });
+    }
+  }
+  return cloneAndFreeze({
+    values,
+    resolved: {
+      extent,
+      edges,
+      eligibleCount: eligible.length,
+      occupiedCount: buckets.filter(bucket => bucket.length > 0).length
+    }
+  });
+}
+
+export function requestedBin2DTransform(transform) {
+  const { resolved: _resolved, ...requested } = transform;
+  return cloneAndFreeze(requested);
+}

package/src/grammar/categoricalDensity.js

@@ -0,0 +1,192 @@
+import { cloneAndFreeze } from "../core/immutable.js";
+import {
+  mapContinuousScaleValues,
+  mapOrdinalPositionValues,
+  readNominalField,
+  readQuantitativeField
+} from "./scales/index.js";
+import { buildAreaCurvePathCommands } from "./curveCommands.js";
+import { buildLinearPathCommands } from "./pathCommands.js";
+
+function sameKey(left, right) {
+  const leftEntries = Object.entries(left);
+  const rightEntries = Object.entries(right);
+  return leftEntries.length === rightEntries.length && leftEntries.every(
+    ([field, value]) => Object.hasOwn(right, field) && Object.is(right[field], value)
+  );
+}
+
+function seriesSide(placement, splitValue) {
+  if (placement.split === undefined) return placement.side;
+  const domain = placement.split.domain ?? placement.resolvedSplitDomain;
+  const index = domain.findIndex(value => Object.is(value, splitValue));
+  if (index < 0) {
+    throw new Error(`Density split value "${splitValue}" is outside its domain.`);
+  }
+  if (placement.channel === "x") return index === 0 ? "left" : "right";
+  return index === 0 ? "top" : "bottom";
+}
+
+export function deriveCategoricalDensitySeries(rows, layer, transform) {
+  const placement = transform?.placement;
+  if (layer?.mark?.type !== "area" || placement?.type !== "category") {
+    throw new Error("Categorical density series require a category-placed area.");
+  }
+  const categoryEncoding = layer.encoding?.[placement.channel];
+  const valueChannel = placement.channel === "x" ? "y" : "x";
+  const valueEncoding = layer.encoding?.[valueChannel];
+  if (
+    categoryEncoding?.field !== placement.categoryField ||
+    !["nominal", "ordinal"].includes(categoryEncoding.fieldType) ||
+    valueEncoding?.field !== transform.as?.[0] ||
+    valueEncoding.fieldType !== "quantitative"
+  ) {
+    throw new Error(
+      `Categorical density area mark "${layer.id}" requires its category and value encodings.`
+    );
+  }
+  const categories = readNominalField(rows, placement.categoryField);
+  const values = readQuantitativeField(rows, transform.as[0]);
+  const densities = readQuantitativeField(rows, transform.as[1]);
+  const splits = placement.split === undefined
+    ? rows.map(() => undefined)
+    : readNominalField(rows, placement.split.field);
+  const series = [];
+  for (let index = 0; index < rows.length; index += 1) {
+    const key = {
+      ...(transform.groupBy === undefined
+        ? {}
+        : { [transform.groupBy]: categories[index] }),
+      ...(placement.split === undefined
+        ? {}
+        : { [placement.split.field]: splits[index] })
+    };
+    let current = series.find(item => sameKey(item.key, key));
+    if (current === undefined) {
+      current = {
+        category: categories[index],
+        split: splits[index],
+        key,
+        values: []
+      };
+      series.push(current);
+    }
+    current.values.push({
+      value: values[index],
+      density: densities[index]
+    });
+  }
+  if (series.length === 0) {
+    throw new Error(`Categorical density area mark "${layer.id}" has no values.`);
+  }
+  const resolvedSplitDomain = placement.split === undefined
+    ? undefined
+    : transform.resolved?.splitDomain ?? placement.split.domain;
+  if (placement.split !== undefined && resolvedSplitDomain === undefined) {
+    throw new Error("Categorical density split requires a resolved two-value domain.");
+  }
+  return cloneAndFreeze({
+    mode: placement.channel === "x" ? "category-x" : "category-y",
+    placement: {
+      ...placement,
+      ...(resolvedSplitDomain === undefined ? {} : { resolvedSplitDomain })
+    },
+    series: series.map(item => ({
+      ...item,
+      side: seriesSide({
+        ...placement,
+        ...(resolvedSplitDomain === undefined ? {} : { resolvedSplitDomain })
+      }, item.split),
+      values: item.values.sort((left, right) => left.value - right.value)
+    }))
+  });
+}
+
+function maximumFor(derived, series) {
+  const candidates = derived.placement.width.resolve === "shared"
+    ? derived.series
+    : derived.series.filter(candidate => Object.is(
+        candidate.category,
+        series.category
+      ));
+  const maximum = Math.max(...candidates.flatMap(candidate =>
+    candidate.values.map(value => value.density)
+  ));
+  if (!Number.isFinite(maximum) || maximum <= 0) {
+    throw new Error("Categorical density width requires a positive maximum.");
+  }
+  return maximum;
+}
+
+function pathBoundaries(series, center, halfWidth, maximum, valueScale, channel) {
+  const valuePositions = mapContinuousScaleValues(
+    series.values.map(value => value.value),
+    valueScale
+  );
+  const widths = series.values.map(value => halfWidth * value.density / maximum);
+  const horizontal = channel === "x";
+  const direction = {
+    left: -1,
+    right: 1,
+    top: -1,
+    bottom: 1
+  }[series.side];
+  const point = (valuePosition, width) => horizontal
+    ? { x: center + width, y: valuePosition }
+    : { x: valuePosition, y: center + width };
+  if (series.side === "both") {
+    return {
+      lower: valuePositions.map((value, index) => point(value, -widths[index])),
+      upper: valuePositions.map((value, index) => point(value, widths[index]))
+    };
+  }
+  const baseline = valuePositions.map(value => point(value, 0));
+  const outer = valuePositions.map((value, index) =>
+    point(value, direction * widths[index])
+  );
+  return {
+    lower: baseline,
+    upper: outer,
+    outline: [baseline[0], ...outer, baseline.at(-1)]
+  };
+}
+
+export function buildCategoricalDensityPaths(
+  derived,
+  { categoryScale, valueScale, curve = "linear" } = {}
+) {
+  if (!Number.isFinite(categoryScale?.bandwidth) || categoryScale.bandwidth <= 0) {
+    throw new Error("Categorical density placement requires a positive band scale.");
+  }
+  const halfWidth = categoryScale.bandwidth * derived.placement.width.band / 2;
+  const centers = mapOrdinalPositionValues(
+    derived.series.map(series => series.category),
+    categoryScale
+  );
+  const commands = derived.series.map((series, index) => {
+    const boundaries = pathBoundaries(
+      series,
+      centers[index],
+      halfWidth,
+      maximumFor(derived, series),
+      valueScale,
+      derived.placement.channel
+    );
+    if (curve !== "linear") {
+      return buildAreaCurvePathCommands(
+        boundaries.lower,
+        boundaries.upper,
+        curve,
+        derived.placement.channel === "x" ? { independentAxis: "y" } : {}
+      );
+    }
+    return buildLinearPathCommands(
+      boundaries.outline ?? [
+        ...boundaries.lower,
+        ...[...boundaries.upper].reverse()
+      ],
+      { close: true }
+    );
+  });
+  return cloneAndFreeze(commands);
+}

package/src/grammar/coordinates.js

@@ -1,6 +1,6 @@
 import { getPositionChannelDefinition } from "../core/vocabulary.js";
 
-const COORDINATE_TYPES = new Set(["cartesian", "polar"]);
+const COORDINATE_TYPES = new Set(["cartesian", "polar", "parallel"]);
 
 export function validateCoordinateType(value) {
   if (!COORDINATE_TYPES.has(value)) {

package/src/grammar/curveCommands.js

@@ -267,7 +267,9 @@ export function buildCurvePathCommands(points, curve = "linear") {
   const validatedPoints = validatePoints(points);
   const validatedCurve = validateCurveInterpolation(curve);
   if (validatedCurve === "linear" ||
-      (SMOOTH_CURVES.has(validatedCurve) && points.length < 3)) {
+      (SMOOTH_CURVES.has(validatedCurve) &&
+        validatedCurve !== "monotone" &&
+        points.length < 3)) {
     return buildLinearPathCommands(validatedPoints);
   }
   if (validatedCurve.startsWith("step")) {