ggaction 0.0.11 → 0.0.13

package/src/grammar/facets/index.js

@@ -18,9 +18,9 @@ const SUPPORTED_BAR_GRAINS = new Set([
 ]);
 const MAX_FACET_CHILDREN = 100;
 
-function requireFacetField(field) {
+function requireFacetField(field, label = "facet") {
   if (typeof field !== "string" || field.length === 0) {
-    throw new TypeError("facet requires a non-empty field.");
+    throw new TypeError(`${label} requires a non-empty field.`);
   }
   return field;
 }
@@ -74,25 +74,52 @@ function uniqueInOrder(values) {
   return [...new Set(values)];
 }
 
-function resolveValues(observed, requested) {
+function resolveValues(observed, requested, label = "facet values") {
   if (requested === undefined) return observed;
   if (!Array.isArray(requested) || requested.length === 0) {
-    throw new TypeError("facet values must be a non-empty array when provided.");
+    throw new TypeError(`${label} must be a non-empty array when provided.`);
   }
   const normalized = readNominalField(
     requested.map(value => ({ value })),
     "value"
   );
   if (new Set(normalized).size !== normalized.length) {
-    throw new Error("facet values must be unique.");
+    throw new Error(`${label} must be unique.`);
   }
   const missing = normalized.find(value => !observed.includes(value));
   if (missing !== undefined) {
-    throw new Error(`facet value ${JSON.stringify(missing)} is not present in the source field.`);
+    throw new Error(
+      `${label} value ${JSON.stringify(missing)} is not present in the source field.`
+    );
   }
   return normalized;
 }
 
+function requireGridRole(value, label) {
+  if (!isPlainObject(value)) {
+    throw new TypeError(`facetGrid ${label} must be a plain object.`);
+  }
+  const unknown = Object.keys(value).find(key => !["field", "values"].includes(key));
+  if (unknown !== undefined) {
+    throw new Error(`Unknown facetGrid ${label} option "${unknown}".`);
+  }
+  return {
+    field: requireFacetField(value.field, `facetGrid ${label}`),
+    ...(value.values === undefined ? {} : { values: value.values })
+  };
+}
+
+function pairKey(row, column) {
+  return JSON.stringify([
+    [typeof row, row],
+    [typeof column, column]
+  ]);
+}
+
+function displayValue(value) {
+  return value === "" ? "(empty)" : String(value);
+}
+
 export function resolveFacetDefinition(semanticSpec, options = {}) {
   if (!isPlainObject(semanticSpec)) {
     throw new TypeError("resolveFacetDefinition requires a semantic spec.");
@@ -136,3 +163,87 @@ export function resolveFacetDefinition(semanticSpec, options = {}) {
     }))
   });
 }
+
+export function resolveFacetGridDefinition(semanticSpec, options = {}) {
+  if (!isPlainObject(semanticSpec)) {
+    throw new TypeError("resolveFacetGridDefinition requires a semantic spec.");
+  }
+  if (!isPlainObject(options)) {
+    throw new TypeError("facetGrid options must be a plain object.");
+  }
+  const rows = requireGridRole(options.rows, "rows");
+  const columns = requireGridRole(options.columns, "columns");
+  if (rows.field === columns.field) {
+    throw new Error("facetGrid rows.field and columns.field must be different.");
+  }
+  const combinations = options.combinations ?? "observed";
+  if (!["observed", "full"].includes(combinations)) {
+    throw new Error('facetGrid combinations must be "observed" or "full".');
+  }
+  const id = validateUserId(options.id ?? "facetGrid", "Facet grid id");
+  requireSupportedLayers(semanticSpec);
+  const dependencies = planFacetDependencies(semanticSpec, {
+    field: rows.field,
+    ...(options.data === undefined ? {} : { data: options.data })
+  });
+  const data = dependencies.anchor;
+  const dataset = requirePartitionDataset(semanticSpec, data);
+  const observedRows = readNominalField(dataset.values, rows.field);
+  const observedColumns = readNominalField(dataset.values, columns.field);
+  const rowValues = resolveValues(
+    uniqueInOrder(observedRows), rows.values, "facetGrid rows.values"
+  );
+  const columnValues = resolveValues(
+    uniqueInOrder(observedColumns), columns.values, "facetGrid columns.values"
+  );
+  const observedPairs = new Set(dataset.values.map((_, index) =>
+    pairKey(observedRows[index], observedColumns[index])
+  ));
+  const candidates = rowValues.flatMap((rowValue, row) =>
+    columnValues.map((columnValue, column) => ({
+      row,
+      column,
+      rowValue,
+      columnValue,
+      empty: !observedPairs.has(pairKey(rowValue, columnValue))
+    }))
+  );
+  const selected = combinations === "full"
+    ? candidates
+    : candidates.filter(cell => !cell.empty);
+  if (selected.length === 0) {
+    throw new Error("facetGrid has no observed row and column combinations.");
+  }
+  validateGeneratedItemLimit(
+    selected.length,
+    "Facet grid child count",
+    MAX_FACET_CHILDREN
+  );
+  validateWorkLimit(
+    dataset.values.length * selected.length,
+    "Facet grid partition work"
+  );
+  return cloneAndFreeze({
+    id,
+    data,
+    dependencies,
+    grid: {
+      rows: { field: rows.field, values: rowValues },
+      columns: { field: columns.field, values: columnValues },
+      combinations
+    },
+    cells: selected.map(cell => {
+      const cellId = `${id}-row-${cell.row + 1}-column-${cell.column + 1}`;
+      return {
+        ...cell,
+        id: cellId,
+        data: `${cellId}-data`,
+        value: `${displayValue(cell.rowValue)} · ${displayValue(cell.columnValue)}`,
+        filters: [
+          { field: rows.field, value: cell.rowValue },
+          { field: columns.field, value: cell.columnValue }
+        ]
+      };
+    })
+  });
+}

package/src/grammar/fold.js

@@ -0,0 +1,123 @@
+import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
+
+const TRANSFORM_KEYS = Object.freeze(["type", "fields", "as"]);
+const AS_KEYS = Object.freeze(["key", "value"]);
+const MAX_FIELDS = 64;
+const MAX_OUTPUT_ROWS = 10_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 normalizeAs(value) {
+  const requested = value ?? {};
+  if (!isPlainObject(requested)) return requested;
+  return {
+    ...requested,
+    key: requested.key ?? "key",
+    value: requested.value ?? "value"
+  };
+}
+
+export function normalizeFoldTransform({ fields, as } = {}) {
+  const transform = {
+    type: "fold",
+    fields: Array.isArray(fields) ? [...fields] : fields,
+    as: normalizeAs(as)
+  };
+  validateFoldTransform(transform);
+  return cloneAndFreeze(transform);
+}
+
+export function validateFoldTransform(transform) {
+  if (!isPlainObject(transform)) {
+    throw new TypeError("Fold transform must be a plain object.");
+  }
+  rejectUnknownKeys(transform, TRANSFORM_KEYS, "fold transform");
+  if (transform.type !== "fold") {
+    throw new Error(`Unsupported fold transform "${transform.type}".`);
+  }
+  if (!Array.isArray(transform.fields) || transform.fields.length === 0) {
+    throw new TypeError("Fold fields must be a non-empty array.");
+  }
+  if (transform.fields.length > MAX_FIELDS) {
+    throw new RangeError(`Fold fields cannot contain more than ${MAX_FIELDS} entries.`);
+  }
+  transform.fields.forEach((field, index) => {
+    requireField(field, `Fold fields[${index}]`);
+  });
+  if (new Set(transform.fields).size !== transform.fields.length) {
+    throw new Error("Fold fields must be unique.");
+  }
+  if (!isPlainObject(transform.as)) {
+    throw new TypeError("Fold as must be a plain object.");
+  }
+  rejectUnknownKeys(transform.as, AS_KEYS, "fold as");
+  const key = requireField(transform.as.key, "Fold as.key");
+  const value = requireField(transform.as.value, "Fold as.value");
+  if (key === value) {
+    throw new Error("Fold output fields must be unique.");
+  }
+  return transform;
+}
+
+function valueType(value, field, row) {
+  if (value === null || value === undefined) {
+    throw new TypeError(`Fold field "${field}" is missing at row ${row}.`);
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new TypeError(`Fold field "${field}" must contain finite numbers.`);
+    }
+    return "number";
+  }
+  if (typeof value === "string" || typeof value === "boolean") {
+    return typeof value;
+  }
+  throw new TypeError(
+    `Fold field "${field}" must contain finite numbers, strings, or booleans.`
+  );
+}
+
+export function deriveFoldRows(rows, transform) {
+  validateFoldTransform(transform);
+  if (rows.length * transform.fields.length > MAX_OUTPUT_ROWS) {
+    throw new RangeError(`Fold output cannot exceed ${MAX_OUTPUT_ROWS} rows.`);
+  }
+  const sourceFields = new Set(rows.flatMap(row => Object.keys(row)));
+  for (const output of [transform.as.key, transform.as.value]) {
+    if (sourceFields.has(output)) {
+      throw new Error(`Fold output field "${output}" already exists.`);
+    }
+  }
+  let expectedType;
+  const output = [];
+  rows.forEach((row, rowIndex) => {
+    for (const field of transform.fields) {
+      if (!Object.hasOwn(row, field)) {
+        throw new Error(`Fold source does not contain field "${field}" at row ${rowIndex}.`);
+      }
+      const type = valueType(row[field], field, rowIndex);
+      if (expectedType === undefined) expectedType = type;
+      else if (type !== expectedType) {
+        throw new TypeError("Fold fields must contain one common primitive type.");
+      }
+      output.push({
+        ...row,
+        [transform.as.key]: field,
+        [transform.as.value]: row[field]
+      });
+    }
+  });
+  return output;
+}

package/src/grammar/horizon.js

@@ -8,14 +8,15 @@ import { interpolateNumber, inverseLerp } from "./numeric.js";
 import { requireFiniteResult } from "./numeric.js";
 import {
   isNominalValue,
-  normalizeTemporalValue
+  normalizeTemporalValue,
+  resolveTemporalUnit
 } from "./scales/index.js";
 
 export const HORIZON_RESOLUTIONS = Object.freeze(["shared", "independent"]);
 export const HORIZON_MISSING_POLICIES = Object.freeze(["break", "error"]);
 export const HORIZON_OVERFLOW_POLICIES = Object.freeze(["clip", "error"]);
 
-const ENCODING_PROPERTIES = Object.freeze(["field", "fieldType"]);
+const ENCODING_PROPERTIES = Object.freeze(["field", "fieldType", "temporalUnit"]);
 const OUTPUT_PROPERTIES = Object.freeze([
   "x", "lower", "upper", "group", "color", "sign", "band", "segment"
 ]);
@@ -41,7 +42,8 @@ function validateEncoding(value, role) {
       `Horizon ${role} fieldType must be quantitative${supportsTemporal ? " or temporal" : ""}.`
     );
   }
-  return { field, fieldType };
+  const temporalUnit = resolveTemporalUnit(value, fieldType);
+  return { field, fieldType, ...(temporalUnit === undefined ? {} : { temporalUnit }) };
 }
 
 function validateOutputFields(value) {
@@ -183,7 +185,7 @@ export function validateHorizonTransform(transform) {
 
 function orderedX(value, encoding, rowIndex) {
   if (encoding.fieldType === "temporal") {
-    return normalizeTemporalValue(value, encoding.field, rowIndex);
+    return normalizeTemporalValue(value, encoding.field, rowIndex, encoding.temporalUnit);
   }
   if (!Number.isFinite(value)) {
     throw new TypeError(

package/src/grammar/interval.js

@@ -1,7 +1,10 @@
 import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
 import { aggregateScalarValues } from "./aggregate.js";
 import { requireFiniteResult, stableDecimal } from "./numeric.js";
-import { studentTCriticalValue } from "./statistics/studentT.js";
+import {
+  confidenceCriticalValue,
+  normalizeConfidenceInterval
+} from "./statistics/confidenceInterval.js";
 
 const CENTER_VALUES = ["mean", "median"];
 const EXTENT_VALUES = ["stderr", "stdev", "ci", "iqr"];
@@ -11,6 +14,7 @@ const TRANSFORM_KEYS = [
   "groupBy",
   "center",
   "extent",
+  "method",
   "level",
   "as"
 ];
@@ -84,13 +88,12 @@ export function validateIntervalTransform(transform) {
     throw new Error("Median intervals require iqr, and iqr requires median.");
   }
   if (transform.extent === "ci") {
-    if (
-      !Number.isFinite(transform.level) ||
-      transform.level <= 0 ||
-      transform.level >= 1
-    ) {
-      throw new RangeError("Interval CI level must be between 0 and 1.");
-    }
+    normalizeConfidenceInterval(transform, {
+      defaultMethod: "student-t",
+      label: "Interval CI"
+    });
+  } else if (transform.method !== undefined) {
+    throw new Error("Interval method is supported only for ci extent.");
   } else if (transform.level !== undefined) {
     throw new Error("Interval level is supported only for ci extent.");
   }
@@ -111,16 +114,27 @@ function normalizeGrouping(groupBy) {
 export function normalizeIntervalParameters({
   center = "mean",
   extent = "ci",
+  method,
   level
 } = {}) {
-  const resolvedLevel = extent === "ci" ? level ?? 0.95 : level;
+  const confidence = extent === "ci"
+    ? normalizeConfidenceInterval({ method, level }, {
+        defaultMethod: "student-t",
+        label: "Interval CI"
+      })
+    : undefined;
   const candidate = {
     type: "interval",
     field: "__interval_input",
     groupBy: [],
     center,
     extent,
-    ...(resolvedLevel === undefined ? {} : { level: resolvedLevel }),
+    ...(confidence === undefined
+      ? {
+          ...(method === undefined ? {} : { method }),
+          ...(level === undefined ? {} : { level })
+        }
+      : confidence),
     as: {
       center: "__interval_center",
       lower: "__interval_lower",
@@ -131,18 +145,16 @@ export function normalizeIntervalParameters({
   return cloneAndFreeze({
     center,
     extent,
-    ...(resolvedLevel === undefined ? {} : { level: resolvedLevel })
+    ...(confidence === undefined ? {} : confidence)
   });
 }
 
 export function studentTCritical(degreesOfFreedom, level) {
-  if (!Number.isInteger(degreesOfFreedom) || degreesOfFreedom < 1) {
-    throw new RangeError("Student-t degreesOfFreedom must be a positive integer.");
-  }
-  if (!Number.isFinite(level) || level <= 0 || level >= 1) {
-    throw new RangeError("Student-t level must be between 0 and 1.");
-  }
-  return studentTCriticalValue(level, degreesOfFreedom);
+  return confidenceCriticalValue({
+    method: "student-t",
+    level,
+    degreesOfFreedom
+  });
 }
 
 function isMissing(value) {
@@ -170,7 +182,11 @@ function deriveGroup(values, transform) {
     ? aggregateScalarValues(values, "stdev")
     : transform.extent === "stderr"
       ? aggregateScalarValues(values, "stderr")
-      : studentTCritical(values.length - 1, transform.level) *
+      : confidenceCriticalValue({
+          method: transform.method,
+          level: transform.level,
+          degreesOfFreedom: values.length - 1
+        }) *
         aggregateScalarValues(values, "stderr");
   return {
     center,
@@ -232,12 +248,13 @@ export function normalizeIntervalTransform({
   groupBy,
   center,
   extent,
+  method,
   level,
   as
 }) {
   nonEmptyString(field, "Interval field");
   const grouping = normalizeGrouping(groupBy);
-  const parameters = normalizeIntervalParameters({ center, extent, level });
+  const parameters = normalizeIntervalParameters({ center, extent, method, level });
   const transform = {
     type: "interval",
     field,

package/src/grammar/lineSeries.js

@@ -16,8 +16,9 @@ import {
   findHistogramBinIndex,
   resolveHistogramBins
 } from "./histogram.js";
-
-const SERIES_CHANNELS = ["group", "color", "strokeDash"];
+import {
+  validatePathSeriesAppearance
+} from "./pathSeries.js";
 
 function requireLineEncoding(layer) {
   if (layer?.mark?.type !== "line") {
@@ -70,32 +71,6 @@ function requireLineEncoding(layer) {
   };
 }
 
-function readSeriesFields(rows, layer) {
-  const fields = [];
-  const values = new Map();
-
-  for (const channel of SERIES_CHANNELS) {
-    const encoding = layer.encoding?.[channel];
-
-    if (encoding?.field === undefined) continue;
-    const categorical = channel === "color"
-      ? ["nominal", "ordinal"].includes(encoding.fieldType)
-      : encoding.fieldType === "nominal";
-    if (!categorical) {
-      throw new Error(
-        `Line ${channel} encoding on mark "${layer.id}" must be categorical.`
-      );
-    }
-
-    if (!values.has(encoding.field)) {
-      fields.push(encoding.field);
-      values.set(encoding.field, readNominalField(rows, encoding.field));
-    }
-  }
-
-  return { fields, values };
-}
-
 function groupKey(values) {
   return JSON.stringify(values);
 }
@@ -148,14 +123,14 @@ function deriveCartesianLineSeries(rows, layer, options = {}) {
     validateAggregateFieldValues(rows, y.field, y.fieldType);
   }
   const xValues = x.fieldType === "temporal"
-    ? readTemporalField(rows, x.field)
+    ? readTemporalField(rows, x.field, x.temporalUnit)
     : readQuantitativeField(rows, x.field);
   const yValues = isAggregate
     ? undefined
     : y.fieldType === "temporal"
-      ? readTemporalField(rows, y.field)
+      ? readTemporalField(rows, y.field, y.temporalUnit)
       : readQuantitativeField(rows, y.field);
-  const seriesFields = readSeriesFields(rows, layer);
+  const seriesFields = validatePathSeriesAppearance(rows, layer);
   const binBoundaries = binnedAggregate
     ? options.xBinBoundaries ?? resolveLineBins(rows, layer).boundaries
     : undefined;
@@ -170,10 +145,10 @@ function deriveCartesianLineSeries(rows, layer, options = {}) {
     const orderValues = readQuantitativeField(rows, pathOrder.field);
     const groups = new Map();
     for (let index = 0; index < rows.length; index += 1) {
-      const dimensions = seriesFields.fields.map(
-        field => seriesFields.values.get(field)[index]
+      const dimensions = seriesFields.map(
+        field => rows[index][field]
       );
-      const series = groupedSeries(groups, seriesFields.fields, dimensions);
+      const series = groupedSeries(groups, seriesFields, dimensions);
       series.values.push({ x: xValues[index], y: yValues[index] });
       series.orderValues ??= [];
       series.orderValues.push(orderValues[index]);
@@ -197,10 +172,10 @@ function deriveCartesianLineSeries(rows, layer, options = {}) {
   if (directRows) {
     const groups = new Map();
     for (let index = 0; index < rows.length; index += 1) {
-      const dimensions = seriesFields.fields.map(
-        field => seriesFields.values.get(field)[index]
+      const dimensions = seriesFields.map(
+        field => rows[index][field]
       );
-      const series = groupedSeries(groups, seriesFields.fields, dimensions);
+      const series = groupedSeries(groups, seriesFields, dimensions);
       series.values.push({ x: xValues[index], y: yValues[index] });
     }
     const orderBy = directTemporal && y.fieldType === "temporal" ? "y" : "x";
@@ -220,8 +195,8 @@ function deriveCartesianLineSeries(rows, layer, options = {}) {
   const aggregateGroups = new Map();
 
   for (let index = 0; index < rows.length; index += 1) {
-    const dimensions = seriesFields.fields.map(
-      field => seriesFields.values.get(field)[index]
+    const dimensions = seriesFields.map(
+      field => rows[index][field]
     );
     const binIndex = binnedAggregate
       ? findHistogramBinIndex(xValues[index], binBoundaries)
@@ -255,7 +230,7 @@ function deriveCartesianLineSeries(rows, layer, options = {}) {
     if (value === undefined) continue;
     const series = groupedSeries(
       seriesGroups,
-      seriesFields.fields,
+      seriesFields,
       group.dimensions
     );
 
@@ -315,7 +290,7 @@ function readThetaValues(rows, encoding) {
     return readNominalField(rows, encoding.field);
   }
   return encoding.fieldType === "temporal"
-    ? readTemporalField(rows, encoding.field)
+    ? readTemporalField(rows, encoding.field, encoding.temporalUnit)
     : readQuantitativeField(rows, encoding.field);
 }
 
@@ -341,14 +316,14 @@ export function derivePolarLineSeries(rows, layer, { thetaDomain } = {}) {
   const thetaValues = readThetaValues(rows, theta);
   const radiusValues = readQuantitativeField(rows, radius.field);
   const sortValues = thetaOrder(thetaValues, theta.fieldType, thetaDomain);
-  const seriesFields = readSeriesFields(rows, layer);
+  const seriesFields = validatePathSeriesAppearance(rows, layer);
   const groups = new Map();
 
   for (let index = 0; index < rows.length; index += 1) {
-    const dimensions = seriesFields.fields.map(
-      field => seriesFields.values.get(field)[index]
+    const dimensions = seriesFields.map(
+      field => rows[index][field]
     );
-    const series = groupedSeries(groups, seriesFields.fields, dimensions);
+    const series = groupedSeries(groups, seriesFields, dimensions);
     series.values.push({
       theta: thetaValues[index],
       radius: radiusValues[index],
@@ -384,21 +359,3 @@ export function deriveLineSeries(rows, layer, options) {
     ? derivePolarLineSeries(rows, layer, options)
     : deriveCartesianLineSeries(rows, layer, options);
 }
-
-export function deriveLineSeriesFieldValues(rows, layer, derived, field) {
-  const values = readQuantitativeField(rows, field);
-  if (values.some(value => value < 0)) {
-    throw new RangeError(`Line strokeWidth field "${field}" cannot contain negative values.`);
-  }
-  return cloneAndFreeze(derived.series.map(series => {
-    const matching = values.filter((_, index) => Object.entries(series.key)
-      .every(([key, value]) => rows[index]?.[key] === value));
-    const unique = [...new Set(matching)];
-    if (unique.length !== 1) {
-      throw new Error(
-        `Line strokeWidth field "${field}" must have one value within each series.`
-      );
-    }
-    return unique[0];
-  }));
-}

package/src/grammar/markFilter.js

@@ -1,7 +1,24 @@
 import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
 import { normalizeMarkSelector } from "./markSelection.js";
 
-const TRANSFORM_KEYS = Object.freeze(["type", "target", "selector"]);
+const TRANSFORM_KEYS = Object.freeze([
+  "type", "target", "selector", "selectors"
+]);
+
+export function markFilterSelectors(transform) {
+  const hasSelector = Object.hasOwn(transform, "selector");
+  const hasSelectors = Object.hasOwn(transform, "selectors");
+  if (hasSelector === hasSelectors) {
+    throw new Error(
+      "Mark filter transform requires exactly one of selector or selectors."
+    );
+  }
+  const selectors = hasSelector ? [transform.selector] : transform.selectors;
+  if (!Array.isArray(selectors) || selectors.length === 0) {
+    throw new TypeError("Mark filter selectors must be a non-empty array.");
+  }
+  return cloneAndFreeze(selectors.map(normalizeMarkSelector));
+}
 
 export function validateMarkFilterTransform(transform) {
   if (!isPlainObject(transform)) {
@@ -19,14 +36,15 @@ export function validateMarkFilterTransform(transform) {
   if (typeof transform.target !== "string" || transform.target.length === 0) {
     throw new TypeError("Mark filter target must be a non-empty string.");
   }
-  normalizeMarkSelector(transform.selector);
+  markFilterSelectors(transform);
 }
 
-export function normalizeMarkFilterTransform(target, selector) {
+export function normalizeMarkFilterTransform(target, selectors) {
   const transform = {
     type: "markFilter",
     target,
-    selector: normalizeMarkSelector(selector)
+    selectors: (Array.isArray(selectors) ? selectors : [selectors])
+      .map(normalizeMarkSelector)
   };
   validateMarkFilterTransform(transform);
   return cloneAndFreeze(transform);