ggaction 0.0.1

package/src/grammar/areaSeries.js

@@ -0,0 +1,217 @@
+import { cloneAndFreeze } from "../core/immutable.js";
+import {
+  readNominalField,
+  readQuantitativeField,
+  readTemporalField
+} from "./scales.js";
+import {
+  layoutSeriesPartition,
+  validateColorLayout
+} from "./seriesLayout.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 vertical =
+    ["quantitative", "temporal"].includes(x?.fieldType) &&
+    y?.fieldType === "quantitative" &&
+    y2?.fieldType === "quantitative" &&
+    x2 === undefined;
+  const horizontal =
+    ["quantitative", "temporal"].includes(y?.fieldType) &&
+    x?.fieldType === "quantitative" &&
+    x2?.fieldType === "quantitative" &&
+    y2 === undefined;
+  if (vertical === horizontal) {
+    throw new Error(
+      `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 orientation = vertical ? "vertical" : "horizontal";
+  const independent = vertical ? x : y;
+  const independentValues = independent.fieldType === "temporal"
+    ? readTemporalField(rows, independent.field)
+    : 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 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 },
+      values: []
+    };
+    series.values.push(vertical
+      ? {
+          x: independentValues[index],
+          y: lower[index],
+          y2: upper[index]
+        }
+      : {
+          x: lower[index],
+          x2: upper[index],
+          y: independentValues[index]
+        });
+    groups.set(key, series);
+  }
+  if (groups.size === 0) {
+    throw new Error(`Area mark "${layer.id}" has no values.`);
+  }
+  const series = [...groups.values()].map(item => {
+    const key = vertical ? "x" : "y";
+    const values = item.values.sort((left, right) => left[key] - right[key]);
+    if (values.length < 2) {
+      throw new Error(
+        `Area series on mark "${layer.id}" requires at least two points.`
+      );
+    }
+    return { key: item.key, values };
+  });
+  return cloneAndFreeze({
+    orientation,
+    xValues: series.flatMap(item => item.values.flatMap(value =>
+      vertical ? [value.x] : [value.x, value.x2]
+    )),
+    yValues: series.flatMap(item => item.values.flatMap(value =>
+      vertical ? [value.y, value.y2] : [value.y]
+    )),
+    series
+  });
+}
+
+export function deriveDensityAreaSeries(rows, layer, transform) {
+  if (layer?.mark?.type !== "area") {
+    throw new Error("Density area derivation requires a semantic area mark.");
+  }
+  if (transform?.type !== "density" || !Array.isArray(transform.as)) {
+    throw new Error(`Area mark "${layer.id}" requires density provenance.`);
+  }
+  const { x, y, group } = layer.encoding ?? {};
+  if (
+    x?.fieldType !== "quantitative" ||
+    y?.fieldType !== "quantitative"
+  ) {
+    throw new Error(
+      `Density area mark "${layer.id}" requires quantitative x and y encodings.`
+    );
+  }
+  const [valueField, densityField] = transform.as;
+  const mode = x.field === valueField && y.field === densityField
+    ? "y-density"
+    : x.field === densityField && y.field === valueField
+      ? "x-density"
+      : undefined;
+  if (mode === undefined) {
+    throw new Error(
+      `Density area mark "${layer.id}" must encode its value and density fields.`
+    );
+  }
+  if (transform.groupBy === undefined) {
+    if (group !== undefined) {
+      throw new Error(`Ungrouped density area mark "${layer.id}" cannot encode group.`);
+    }
+  } else if (
+    group?.field !== transform.groupBy ||
+    group.fieldType !== "nominal"
+  ) {
+    throw new Error(
+      `Density area mark "${layer.id}" must group by "${transform.groupBy}".`
+    );
+  }
+
+  const xValues = readQuantitativeField(rows, x.field);
+  const yValues = readQuantitativeField(rows, y.field);
+  const groupValues = transform.groupBy === undefined
+    ? rows.map(() => undefined)
+    : readNominalField(rows, transform.groupBy);
+  const groups = new Map();
+  for (let index = 0; index < rows.length; index += 1) {
+    const key = groupValues[index];
+    const series = groups.get(key) ?? {
+      key: transform.groupBy === undefined ? {} : { [transform.groupBy]: key },
+      values: []
+    };
+    series.values.push({ x: xValues[index], y: yValues[index] });
+    groups.set(key, series);
+  }
+  if (groups.size === 0) {
+    throw new Error(`Density area mark "${layer.id}" has no values.`);
+  }
+  const valueKey = mode === "y-density" ? "x" : "y";
+  const series = [...groups.values()].map(item => {
+    const values = item.values.sort((left, right) => left[valueKey] - right[valueKey]);
+    if (values.length < 2) {
+      throw new Error(
+        `Density area series on mark "${layer.id}" requires at least two points.`
+      );
+    }
+    return { key: item.key, values };
+  });
+  return cloneAndFreeze({ mode, series });
+}
+
+export function layoutDensityAreaSeries(derived, layout = "overlay") {
+  validateColorLayout(layout);
+  if (layout === "group") {
+    throw new Error('Density area series do not support "group" layout.');
+  }
+  if (derived?.mode !== "y-density") {
+    if (layout === "overlay") return derived;
+    throw new Error(
+      `Area layout "${layout}" currently requires vertical density series.`
+    );
+  }
+  const sampleCount = derived.series[0]?.values.length ?? 0;
+  if (
+    sampleCount === 0 ||
+    derived.series.some(series => series.values.length !== sampleCount)
+  ) {
+    throw new Error("Density area layout requires aligned non-empty samples.");
+  }
+
+  const valuesBySeries = derived.series.map(() => []);
+  for (let sample = 0; sample < sampleCount; sample += 1) {
+    const x = derived.series[0].values[sample].x;
+    const densities = derived.series.map(series => {
+      if (series.values[sample].x !== x) {
+        throw new Error("Density area layout requires one shared sample grid.");
+      }
+      return series.values[sample].y;
+    });
+    const segments = new Map(
+      layoutSeriesPartition(densities, layout).map(segment => [
+        segment.index,
+        segment
+      ])
+    );
+    for (let index = 0; index < derived.series.length; index += 1) {
+      const segment = segments.get(index);
+      valuesBySeries[index].push({
+        x,
+        lower: segment?.start ?? 0,
+        upper: segment?.end ?? 0
+      });
+    }
+  }
+
+  return cloneAndFreeze({
+    mode: derived.mode,
+    series: derived.series.map((series, index) => ({
+      key: series.key,
+      values: valuesBySeries[index]
+    }))
+  });
+}

package/src/grammar/bars/aggregate.js

@@ -0,0 +1,98 @@
+import { cloneAndFreeze } from "../../core/immutable.js";
+import { readNominalField, readTemporalField } from "../scales.js";
+import {
+  aggregateRows,
+  validateAggregateFieldType,
+  validateAggregateFieldValues,
+} from "../aggregate.js";
+import {
+  BAR_GRAINS,
+  resolveBarChannels,
+  resolveBarGrain
+} from "./policy.js";
+
+function requireAggregateBarEncoding(layer) {
+  if (layer?.mark?.type !== "bar") {
+    throw new Error("Bar aggregate derivation requires a semantic bar mark.");
+  }
+
+  const channels = resolveBarChannels(layer);
+  if (resolveBarGrain(layer) !== BAR_GRAINS.aggregate) {
+    throw new Error(
+      `Bar mark "${layer.id}" requires a categorical position and quantitative aggregate measure.`
+    );
+  }
+  const category = layer.encoding[channels.category];
+  const measure = layer.encoding[channels.measure];
+  validateAggregateFieldType(measure.aggregate, measure.fieldType);
+
+  return { channels, category, measure };
+}
+
+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)
+    : readNominalField(rows, category.field);
+  const color = layer.encoding?.color;
+  let colorValues;
+  let colorAggregate;
+
+  if (color !== undefined) {
+    if (color.fieldType === "nominal") {
+      colorValues = readNominalField(rows, color.field);
+    } else if (color.fieldType === "quantitative") {
+      colorAggregate = color.aggregate;
+      validateAggregateFieldType(colorAggregate, color.fieldType);
+      validateAggregateFieldValues(rows, color.field, color.fieldType);
+    } else {
+      throw new Error(
+        `Bar color encoding on mark "${layer.id}" must be nominal or aggregate quantitative.`
+      );
+    }
+  }
+  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 group = groups.get(key) ?? {
+      category: categoryValue,
+      ...(colorValues === undefined ? {} : { color: colorValue }),
+      rows: []
+    };
+    group.rows.push(rows[index]);
+    groups.set(key, group);
+  }
+
+  if (groups.size === 0) {
+    throw new Error(`Bar mark "${layer.id}" has no values to aggregate.`);
+  }
+
+  const values = [...groups.values()].flatMap(group => {
+    const value = aggregateRows(group.rows, measure.field, measure.aggregate);
+    const aggregateColor = colorAggregate === undefined
+      ? group.color
+      : aggregateRows(group.rows, color.field, colorAggregate);
+    return value === undefined || (
+      colorAggregate !== undefined && aggregateColor === undefined
+    ) ? [] : [{
+      x: channels.category === "x" ? group.category : value,
+      y: channels.category === "y" ? group.category : value,
+      ...(color === undefined ? {} : { color: aggregateColor }),
+      count: group.rows.length
+    }];
+  });
+
+  if (values.length === 0) {
+    throw new Error(`Bar mark "${layer.id}" has no complete aggregate values.`);
+  }
+
+  return cloneAndFreeze({
+    xValues: values.map(value => value.x),
+    yValues: values.map(value => value.y),
+    values
+  });
+}

package/src/grammar/bars/geometry.js

@@ -0,0 +1,54 @@
+import { cloneAndFreeze } from "../../core/immutable.js";
+
+export const DEFAULT_BAR_WIDTH = Object.freeze({ band: 0.72 });
+export const DEFAULT_OFFSET_PADDING = Object.freeze({
+  paddingInner: 0,
+  paddingOuter: 0
+});
+
+export function normalizeBarWidth(options = {}, existing) {
+  const hasBand = options.band !== undefined;
+  const hasPixels = options.pixels !== undefined;
+  if (hasBand && hasPixels) {
+    throw new Error("encodeBarWidth band and pixels are mutually exclusive.");
+  }
+  if (!hasBand && !hasPixels) {
+    return cloneAndFreeze(existing ?? DEFAULT_BAR_WIDTH);
+  }
+  if (hasBand) {
+    if (!Number.isFinite(options.band) || options.band <= 0 || options.band > 1) {
+      throw new RangeError("Bar width band must be greater than 0 and at most 1.");
+    }
+    return cloneAndFreeze({ band: options.band });
+  }
+  if (!Number.isFinite(options.pixels) || options.pixels <= 0) {
+    throw new RangeError("Bar width pixels must be a positive finite number.");
+  }
+  return cloneAndFreeze({ pixels: options.pixels });
+}
+
+export function normalizeOffsetPadding(options = {}, existing) {
+  const paddingInner = options.paddingInner ??
+    existing?.paddingInner ?? DEFAULT_OFFSET_PADDING.paddingInner;
+  const paddingOuter = options.paddingOuter ??
+    existing?.paddingOuter ?? DEFAULT_OFFSET_PADDING.paddingOuter;
+  if (!Number.isFinite(paddingInner) || paddingInner < 0 || paddingInner >= 1) {
+    throw new RangeError(
+      "xOffset paddingInner must be from 0 (inclusive) to 1 (exclusive)."
+    );
+  }
+  if (!Number.isFinite(paddingOuter) || paddingOuter < 0) {
+    throw new RangeError(
+      "xOffset paddingOuter must be a non-negative finite number."
+    );
+  }
+  return cloneAndFreeze({ paddingInner, paddingOuter });
+}
+
+export function resolveBarWidth(config, slotBandwidth) {
+  if (!Number.isFinite(slotBandwidth) || slotBandwidth <= 0) {
+    throw new Error("Bar width requires a positive resolved slot bandwidth.");
+  }
+  const normalized = normalizeBarWidth(config);
+  return normalized.pixels ?? slotBandwidth * normalized.band;
+}

package/src/grammar/bars/policy.js

@@ -0,0 +1,90 @@
+import { isAggregate } from "../aggregate.js";
+
+export const BAR_GRAINS = Object.freeze({
+  histogram: "histogram",
+  aggregate: "aggregate",
+  ranged: "ranged"
+});
+
+export const BAR_ORIENTATIONS = Object.freeze({
+  vertical: "vertical",
+  horizontal: "horizontal"
+});
+
+function isCategory(encoding) {
+  return ["nominal", "ordinal", "temporal"].includes(encoding?.fieldType);
+}
+
+function isMeasure(encoding) {
+  return encoding?.fieldType === "quantitative" &&
+    isAggregate(encoding.aggregate);
+}
+
+export function resolveBarOrientation(layer) {
+  if (layer?.mark?.type !== "bar") return undefined;
+  const x = layer.encoding?.x;
+  const y = layer.encoding?.y;
+  if (x?.bin !== undefined && y?.aggregate === "count") {
+    return BAR_ORIENTATIONS.vertical;
+  }
+  if (isCategory(x) && y?.fieldType === "quantitative" && layer.encoding?.y2?.fieldType === "quantitative") {
+    return BAR_ORIENTATIONS.vertical;
+  }
+  if (isCategory(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;
+  return undefined;
+}
+
+export function resolveBarChannels(layer) {
+  const orientation = resolveBarOrientation(layer);
+  if (orientation === undefined) return undefined;
+  return orientation === BAR_ORIENTATIONS.vertical
+    ? { orientation, category: "x", measure: "y" }
+    : { orientation, category: "y", measure: "x" };
+}
+
+export function resolveBarGrain(layer) {
+  if (layer?.mark?.type !== "bar") return undefined;
+  const x = layer.encoding?.x;
+  const y = layer.encoding?.y;
+
+  if (
+    x?.bin !== undefined &&
+    y?.aggregate === "count"
+  ) {
+    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")
+  ) return BAR_GRAINS.ranged;
+  if (resolveBarOrientation(layer) !== undefined) {
+    return BAR_GRAINS.aggregate;
+  }
+  return undefined;
+}
+
+export function inferBarColorLayout(layer) {
+  if (layer?.encoding?.color?.layout !== undefined) {
+    return layer.encoding.color.layout;
+  }
+  const grain = resolveBarGrain(layer);
+  if (grain === BAR_GRAINS.histogram) return "stack";
+  if (grain === BAR_GRAINS.aggregate) return "group";
+  if (grain === BAR_GRAINS.ranged) return "overlay";
+  return undefined;
+}
+
+export function resolveBarColorLayout(layer) {
+  if (layer?.encoding?.color?.layout !== undefined) {
+    return layer.encoding.color.layout;
+  }
+  const channels = resolveBarChannels(layer);
+  if (layer?.encoding?.[channels?.measure]?.stack === "normalize") return "fill";
+  if (layer?.encoding?.xOffset !== undefined) return "group";
+  if (layer?.encoding?.[channels?.measure]?.stack === null) return "overlay";
+  return "stack";
+}

package/src/grammar/boxPlot.js

@@ -0,0 +1,140 @@
+import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
+
+export const BOX_FIELDS = Object.freeze({
+  q1: "__boxPlot_q1", median: "__boxPlot_median", q3: "__boxPlot_q3",
+  lowerWhisker: "__boxPlot_lowerWhisker", upperWhisker: "__boxPlot_upperWhisker",
+  lowerFence: "__boxPlot_lowerFence", upperFence: "__boxPlot_upperFence",
+  count: "__boxPlot_count"
+});
+
+const TRANSFORM_KEYS = Object.freeze([
+  "type", "category", "field", "method", "whisker", "factor", "as"
+]);
+const OUTPUT_KEYS = Object.freeze(Object.keys(BOX_FIELDS));
+
+function field(value, label) {
+  if (typeof value !== "string" || value.length === 0) throw new TypeError(`${label} must be a non-empty string.`);
+  return value;
+}
+
+function validateOutputs(as, occupied) {
+  if (!isPlainObject(as)) throw new TypeError("Box as must be a plain object.");
+  const keys = Object.keys(as);
+  if (keys.length !== OUTPUT_KEYS.length || !OUTPUT_KEYS.every(key => Object.hasOwn(as, key))) {
+    throw new Error(`Box as requires exactly ${OUTPUT_KEYS.join(", ")}.`);
+  }
+  const values = OUTPUT_KEYS.map(key => field(as[key], `Box as.${key}`));
+  if (new Set(values).size !== values.length) throw new Error("Box output fields must be distinct.");
+  if (values.some(value => occupied.has(value))) {
+    throw new Error("Box output fields must not collide with input fields.");
+  }
+}
+
+export function validateBoxTransform(value) {
+  if (!isPlainObject(value)) throw new TypeError("Box transform must be a plain object.");
+  const unknown = Object.keys(value).find(key => !TRANSFORM_KEYS.includes(key));
+  if (unknown) throw new Error(`Unknown box transform property "${unknown}".`);
+  if (!["boxSummary", "boxOutlier"].includes(value.type)) {
+    throw new Error(`Unsupported box transform "${value.type}".`);
+  }
+  field(value.category, "Box category field");
+  field(value.field, "Box measure field");
+  if (value.method !== "linear") throw new Error(`Unsupported box quantile method "${value.method}".`);
+  const whisker = value.whisker ?? "tukey";
+  if (!["tukey", "minmax"].includes(whisker)) {
+    throw new Error(`Unsupported box whisker policy "${whisker}".`);
+  }
+  if (whisker === "tukey" && (!Number.isFinite(value.factor) || value.factor <= 0)) {
+    throw new RangeError("Box factor must be positive and finite.");
+  }
+  if (whisker === "minmax" && value.factor !== undefined) {
+    throw new Error("Box minmax whiskers do not accept factor.");
+  }
+  validateOutputs(value.as, new Set([value.category, value.field]));
+  return value;
+}
+
+export function normalizeBoxTransform(options = {}) {
+  const {
+    type = "boxSummary",
+    category,
+    field: measure,
+    whisker = "tukey",
+    factor = 1.5,
+    as = BOX_FIELDS
+  } = options;
+  if (whisker === "minmax" && Object.hasOwn(options, "factor")) {
+    throw new Error("Box minmax whiskers do not accept factor.");
+  }
+  const normalized = {
+    type,
+    category,
+    field: measure,
+    method: "linear",
+    ...(whisker === "tukey" ? { factor } : { whisker }),
+    as
+  };
+  validateBoxTransform(normalized);
+  return cloneAndFreeze(normalized);
+}
+
+function quantile(sorted, p) {
+  const position = (sorted.length - 1) * p;
+  const lower = Math.floor(position);
+  const upper = Math.ceil(position);
+  return sorted[lower] + (sorted[upper] - sorted[lower]) * (position - lower);
+}
+
+function stableNumber(value) {
+  return Number(value.toFixed(12));
+}
+
+export function deriveBoxData(rows, transform) {
+  if (!Array.isArray(rows)) throw new TypeError("Box rows must be an array.");
+  validateBoxTransform(transform);
+  const { category, field: measure, factor, as } = transform;
+  const whisker = transform.whisker ?? "tukey";
+  const groups = [];
+  const byCategory = new Map();
+  for (const row of rows) {
+    const key = row[category];
+    const value = row[measure];
+    if (key === undefined || key === null || key === "" || value === undefined || value === null) continue;
+    if (!Number.isFinite(value)) throw new TypeError(`Box field "${measure}" must contain finite numbers.`);
+    if (!byCategory.has(key)) {
+      const group = { key, rows: [] };
+      byCategory.set(key, group);
+      groups.push(group);
+    }
+    byCategory.get(key).rows.push(row);
+  }
+  if (groups.length === 0) throw new Error("Box transform requires at least one valid row.");
+  const summaries = [];
+  const outlierSet = new Set();
+  for (const group of groups) {
+    const sorted = group.rows.map(row => row[measure]).sort((a, b) => a - b);
+    const q1 = stableNumber(quantile(sorted, 0.25));
+    const median = stableNumber(quantile(sorted, 0.5));
+    const q3 = stableNumber(quantile(sorted, 0.75));
+    const lowerFence = whisker === "minmax"
+      ? sorted[0]
+      : stableNumber(q1 - factor * (q3 - q1));
+    const upperFence = whisker === "minmax"
+      ? sorted.at(-1)
+      : stableNumber(q3 + factor * (q3 - q1));
+    const inliers = sorted.filter(value => value >= lowerFence && value <= upperFence);
+    const lowerWhisker = inliers[0];
+    const upperWhisker = inliers.at(-1);
+    summaries.push({
+      [category]: group.key, [as.q1]: q1, [as.median]: median, [as.q3]: q3,
+      [as.lowerWhisker]: lowerWhisker, [as.upperWhisker]: upperWhisker,
+      [as.lowerFence]: lowerFence, [as.upperFence]: upperFence, [as.count]: sorted.length
+    });
+    if (whisker === "tukey") {
+      for (const row of group.rows) {
+        if (row[measure] < lowerWhisker || row[measure] > upperWhisker) outlierSet.add(row);
+      }
+    }
+  }
+  return cloneAndFreeze({ summaries, outliers: rows.filter(row => outlierSet.has(row)).map(row => ({ ...row })) });
+}

package/src/grammar/coordinates.js

@@ -0,0 +1,25 @@
+const COORDINATE_TYPES = new Set(["cartesian", "polar"]);
+const POSITION_COORDINATES = Object.freeze({
+  x: Object.freeze({ id: "main", type: "cartesian" }),
+  y: Object.freeze({ id: "main", type: "cartesian" }),
+  theta: Object.freeze({ id: "polar", type: "polar" }),
+  radius: Object.freeze({ id: "polar", type: "polar" })
+});
+
+export function validateCoordinateType(value) {
+  if (!COORDINATE_TYPES.has(value)) {
+    throw new Error(`Unknown coordinate type "${value}".`);
+  }
+
+  return value;
+}
+
+export function getPositionCoordinateDefaults(channel) {
+  const coordinate = POSITION_COORDINATES[channel];
+
+  if (coordinate === undefined) {
+    throw new Error(`Unknown positional channel "${channel}".`);
+  }
+
+  return coordinate;
+}