ggaction 0.0.12 → 0.0.13

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,17 +46,23 @@ 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: []
     };
+    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]);
     groups.set(key, group);
   }
@@ -82,6 +82,7 @@ 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 }),
       count: group.rows.length
     }];
   });
@@ -96,3 +97,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/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,181 @@
+import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
+import {
+  findHistogramBinIndex,
+  normalizeHistogramBin,
+  resolveHistogramBins
+} from "./histogram.js";
+
+const TRANSFORM_KEYS = Object.freeze([
+  "type", "field", "bin", "extent", "nice", "zero", "includeEmpty",
+  "members", "as", "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
+} = {}) {
+  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)
+  };
+  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");
+  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);
+  if (
+    transform.extent !== "auto" &&
+    values.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,
+    bin: transform.bin,
+    domain: transform.extent,
+    nice: transform.nice,
+    zero: transform.zero
+  });
+  const members = resolved.boundaries.slice(0, -1).map(() => []);
+  values.forEach((value, index) => {
+    const bin = findHistogramBinIndex(value, resolved.boundaries);
+    if (bin !== -1) members[bin].push(rows[index]);
+  });
+  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]: group.length,
+      ...(transform.members ? { [transform.as.members]: 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);
+}

package/src/grammar/computed.js

@@ -0,0 +1,150 @@
+import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
+
+const TRANSFORM_KEYS = Object.freeze(["type", "as", "expression"]);
+const BINARY_OPERATIONS = new Set(["add", "subtract", "multiply", "divide"]);
+const UNARY_OPERATIONS = new Set(["negate", "absolute"]);
+const MAX_DEPTH = 16;
+const MAX_NODES = 128;
+const MAX_WORK = 10_000_000;
+
+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 validateExpression(expression, depth = 1, state = { nodes: 0 }) {
+  if (!isPlainObject(expression)) {
+    throw new TypeError("Computed expression nodes must be plain objects.");
+  }
+  state.nodes += 1;
+  if (state.nodes > MAX_NODES) {
+    throw new RangeError(`Computed expression cannot exceed ${MAX_NODES} nodes.`);
+  }
+  if (depth > MAX_DEPTH) {
+    throw new RangeError(`Computed expression cannot exceed depth ${MAX_DEPTH}.`);
+  }
+  const kinds = ["field", "constant", "op"].filter(key => Object.hasOwn(expression, key));
+  if (kinds.length !== 1) {
+    throw new Error("Computed expression requires exactly one of field, constant, or op.");
+  }
+  if (kinds[0] === "field") {
+    rejectUnknownKeys(expression, ["field"], "computed field expression");
+    requireField(expression.field, "Computed expression field");
+  } else if (kinds[0] === "constant") {
+    rejectUnknownKeys(expression, ["constant"], "computed constant expression");
+    if (!Number.isFinite(expression.constant)) {
+      throw new TypeError("Computed expression constant must be a finite number.");
+    }
+  } else if (BINARY_OPERATIONS.has(expression.op)) {
+    rejectUnknownKeys(expression, ["op", "left", "right"], "computed binary expression");
+    if (!Object.hasOwn(expression, "left") || !Object.hasOwn(expression, "right")) {
+      throw new TypeError(`Computed ${expression.op} requires left and right expressions.`);
+    }
+    validateExpression(expression.left, depth + 1, state);
+    validateExpression(expression.right, depth + 1, state);
+  } else if (UNARY_OPERATIONS.has(expression.op)) {
+    rejectUnknownKeys(expression, ["op", "operand"], "computed unary expression");
+    if (!Object.hasOwn(expression, "operand")) {
+      throw new TypeError(`Computed ${expression.op} requires an operand expression.`);
+    }
+    validateExpression(expression.operand, depth + 1, state);
+  } else {
+    throw new Error(`Unsupported computed operation "${expression.op}".`);
+  }
+  return state.nodes;
+}
+
+function normalizeExpression(expression) {
+  if (!isPlainObject(expression)) return expression;
+  if (Object.hasOwn(expression, "left") || Object.hasOwn(expression, "right")) {
+    return {
+      ...expression,
+      left: normalizeExpression(expression.left),
+      right: normalizeExpression(expression.right)
+    };
+  }
+  if (Object.hasOwn(expression, "operand")) {
+    return { ...expression, operand: normalizeExpression(expression.operand) };
+  }
+  return { ...expression };
+}
+
+export function normalizeComputedTransform({ as, expression } = {}) {
+  const transform = {
+    type: "computed",
+    as,
+    expression: normalizeExpression(expression)
+  };
+  validateComputedTransform(transform);
+  return cloneAndFreeze(transform);
+}
+
+export function validateComputedTransform(transform) {
+  if (!isPlainObject(transform)) {
+    throw new TypeError("Computed transform must be a plain object.");
+  }
+  rejectUnknownKeys(transform, TRANSFORM_KEYS, "computed transform");
+  if (transform.type !== "computed") {
+    throw new Error(`Unsupported computed transform "${transform.type}".`);
+  }
+  requireField(transform.as, "Computed output field");
+  return validateExpression(transform.expression);
+}
+
+function evaluate(expression, row, rowIndex) {
+  if (Object.hasOwn(expression, "field")) {
+    if (!Object.hasOwn(row, expression.field)) {
+      throw new Error(
+        `Computed source does not contain field "${expression.field}" at row ${rowIndex}.`
+      );
+    }
+    const value = row[expression.field];
+    if (!Number.isFinite(value)) {
+      throw new TypeError(
+        `Computed field "${expression.field}" must contain a finite number at row ${rowIndex}.`
+      );
+    }
+    return value;
+  }
+  if (Object.hasOwn(expression, "constant")) return expression.constant;
+  if (UNARY_OPERATIONS.has(expression.op)) {
+    const value = evaluate(expression.operand, row, rowIndex);
+    return expression.op === "negate" ? -value : Math.abs(value);
+  }
+  const left = evaluate(expression.left, row, rowIndex);
+  const right = evaluate(expression.right, row, rowIndex);
+  if (expression.op === "divide" && right === 0) {
+    throw new RangeError(`Computed divide by zero at row ${rowIndex}.`);
+  }
+  const result = expression.op === "add" ? left + right
+    : expression.op === "subtract" ? left - right
+      : expression.op === "multiply" ? left * right
+        : left / right;
+  if (!Number.isFinite(result)) {
+    throw new RangeError(`Computed ${expression.op} result is not finite at row ${rowIndex}.`);
+  }
+  return result;
+}
+
+export function deriveComputedRows(rows, transform) {
+  const nodes = validateComputedTransform(transform);
+  if (rows.length * nodes > MAX_WORK) {
+    throw new RangeError(`Computed work cannot exceed ${MAX_WORK} row-nodes.`);
+  }
+  if (rows.some(row => Object.hasOwn(row, transform.as))) {
+    throw new Error(`Computed output field "${transform.as}" already exists.`);
+  }
+  return rows.map((row, index) => ({
+    ...row,
+    [transform.as]: evaluate(transform.expression, row, index)
+  }));
+}