ggaction 0.0.12 → 0.0.15

package/src/grammar/facets/dependencies.js

@@ -1,6 +1,137 @@
 import { cloneAndFreeze, isPlainObject } from "../../core/immutable.js";
 import { validateUserId } from "../../core/identifiers.js";
 import { findTransformPolicy } from "../transforms.js";
+import { BAR_GRAINS, resolveBarGrain } from "../bars/policy.js";
+import { resolveRectMode } from "../rects.js";
+import { resolveRuleMode } from "../rules.js";
+
+const CARTESIAN_MARKS = new Set([
+  "point", "line", "area", "bar", "rule", "tick", "rect"
+]);
+const FACET_BAR_GRAINS = new Set([
+  BAR_GRAINS.histogram,
+  BAR_GRAINS.aggregate,
+  BAR_GRAINS.ranged
+]);
+const ORDINARY_SCALE_CHANNELS = Object.freeze([
+  ["x", "x"], ["y", "y"], ["xOffset", "xOffset"], ["yOffset", "yOffset"],
+  ["theta", "theta"], ["r", "radius"], ["color", "color"],
+  ["stroke", "stroke"], ["size", "size"], ["shape", "shape"],
+  ["opacity", "opacity"], ["strokeDash", "strokeDash"]
+]);
+
+function coordinateType(semanticSpec, layer) {
+  if (layer.coordinate === undefined) return undefined;
+  return semanticSpec.coordinates?.find(value => value.id === layer.coordinate)?.type;
+}
+
+function classifyPrimaryLayer(semanticSpec, layer) {
+  const type = layer.mark?.type;
+  const parallel = layer.encoding?.parallel;
+  if (parallel !== undefined || coordinateType(semanticSpec, layer) === "parallel") {
+    const complete = type === "line" && Array.isArray(parallel?.dimensions) &&
+      parallel.dimensions.length >= 2 &&
+      parallel.dimensions.every(dimension =>
+        typeof dimension?.scale === "string" && dimension.scale.length > 0
+      );
+    if (!complete) {
+      throw new Error(
+        `Facet layer "${layer.id}" must be a complete materializable Parallel mark.`
+      );
+    }
+    return "parallel";
+  }
+  const polar = layer.encoding?.theta !== undefined ||
+    layer.encoding?.radius !== undefined || coordinateType(semanticSpec, layer) === "polar";
+  if (polar) {
+    const theta = layer.encoding?.theta?.scale !== undefined;
+    const radius = layer.encoding?.radius?.scale !== undefined;
+    const complete = (type === "point" || type === "line")
+      ? theta && radius
+      : type === "arc" && theta;
+    if (!complete) {
+      throw new Error(
+        `Facet layer "${layer.id}" must be a complete materializable Polar mark.`
+      );
+    }
+    return "polar";
+  }
+  if (!CARTESIAN_MARKS.has(type)) {
+    throw new Error(
+      `facet does not support mark "${layer.id}" of type ${type ?? "incomplete"}.`
+    );
+  }
+  if (type === "bar" && !FACET_BAR_GRAINS.has(resolveBarGrain(layer))) {
+    throw new Error(
+      `facet requires bar mark "${layer.id}" to be a complete histogram, aggregate, or ranged bar.`
+    );
+  }
+  const complete = (
+    layer.encoding?.x?.scale !== undefined &&
+    layer.encoding?.y?.scale !== undefined
+  ) || (type === "rule" && resolveRuleMode(layer) !== undefined) ||
+    (type === "rect" && resolveRectMode(layer) !== undefined);
+  if (!complete) {
+    throw new Error(
+      `Facet layer "${layer.id}" must be a complete materializable Cartesian mark.`
+    );
+  }
+  return "cartesian";
+}
+
+export function collectFacetScaleBindings(semanticSpec) {
+  if (!isPlainObject(semanticSpec) || !Array.isArray(semanticSpec.layers)) {
+    throw new TypeError("Facet scale bindings require a semantic spec with layers.");
+  }
+  const bindings = [];
+  for (const layer of semanticSpec.layers) {
+    for (const [policyKey, semanticChannel] of ORDINARY_SCALE_CHANNELS) {
+      const scaleId = layer.encoding?.[semanticChannel]?.scale;
+      if (scaleId === undefined) continue;
+      bindings.push({ layerId: layer.id, scaleId, policyKey, semanticChannel });
+    }
+    for (const [dimensionIndex, dimension] of
+      (layer.encoding?.parallel?.dimensions ?? []).entries()) {
+      if (dimension?.scale === undefined) continue;
+      bindings.push({
+        layerId: layer.id,
+        scaleId: dimension.scale,
+        policyKey: "parallelDimensions",
+        semanticChannel: "parallel",
+        dimensionField: dimension.field,
+        dimensionIndex
+      });
+    }
+  }
+  return cloneAndFreeze(bindings);
+}
+
+export function resolveFacetFamily(semanticSpec) {
+  if (!isPlainObject(semanticSpec) || !Array.isArray(semanticSpec.layers) ||
+      semanticSpec.layers.length === 0) {
+    throw new Error("facet requires at least one materializable layer.");
+  }
+  const primary = semanticSpec.layers.filter(layer =>
+    !(layer.mark?.type === "text" && layer.source !== undefined)
+  );
+  if (primary.length === 0) {
+    throw new Error("facet requires at least one primary materializable layer.");
+  }
+  const families = primary.map(layer => classifyPrimaryLayer(semanticSpec, layer));
+  if (new Set(families).size !== 1) {
+    throw new Error("facet requires every primary layer to use one coordinate family.");
+  }
+  const family = families[0];
+  return cloneAndFreeze({
+    family,
+    primaryLayers: primary.map(layer => layer.id),
+    dependentLayers: semanticSpec.layers
+      .filter(layer => !primary.includes(layer))
+      .map(layer => layer.id),
+    scaleBindings: collectFacetScaleBindings(semanticSpec),
+    coordinates: [...new Set(primary.map(layer => layer.coordinate).filter(Boolean))]
+  });
+}
 
 function requireCollection(value, label) {
   if (!Array.isArray(value) || value.length === 0) {
@@ -172,6 +303,7 @@ export function planFacetDependencies(semanticSpec, options = {}) {
     field,
     anchor,
     replay,
-    layers: layerPaths.map(({ layerId, data }) => ({ id: layerId, data }))
+    layers: layerPaths.map(({ layerId, data }) => ({ id: layerId, data })),
+    ...(options.family === undefined ? {} : options.family)
   });
 }

package/src/grammar/facets/guides.js

@@ -3,8 +3,11 @@ import { cloneAndFreeze, isPlainObject } from "../../core/immutable.js";
 const LEGEND_FAMILIES = Object.freeze({
   series: "categorical",
   color: "categorical",
+  stroke: "categorical",
   gradient: "gradient",
   interval: "discretized",
+  strokeGradient: "gradient",
+  strokeInterval: "discretized",
   size: "size",
   opacity: "opacity"
 });

package/src/grammar/facets/index.js

@@ -4,61 +4,17 @@ import {
   validateGeneratedItemLimit,
   validateWorkLimit
 } from "../../core/validation.js";
-import { BAR_GRAINS, resolveBarGrain } from "../bars/policy.js";
-import { planFacetDependencies } from "./dependencies.js";
+import { planFacetDependencies, resolveFacetFamily } from "./dependencies.js";
 import { readNominalField } from "../scales/index.js";
-
-const SUPPORTED_MARKS = new Set([
-  "point", "line", "area", "bar", "rule", "tick", "rect"
-]);
-const SUPPORTED_BAR_GRAINS = new Set([
-  BAR_GRAINS.histogram,
-  BAR_GRAINS.aggregate,
-  BAR_GRAINS.ranged
-]);
 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;
 }
 
-function requireSupportedLayer(layer) {
-  if (!SUPPORTED_MARKS.has(layer.mark?.type)) {
-    throw new Error(
-      `facet does not support mark "${layer.id}" of type ${layer.mark?.type ?? "incomplete"}.`
-    );
-  }
-  if (
-    layer.mark.type === "bar" &&
-    !SUPPORTED_BAR_GRAINS.has(resolveBarGrain(layer))
-  ) {
-    throw new Error(
-      `facet requires bar mark "${layer.id}" to be a complete histogram, aggregate, or ranged bar.`
-    );
-  }
-  if (
-    layer.encoding?.x?.scale === undefined ||
-    layer.encoding?.y?.scale === undefined
-  ) {
-    throw new Error(
-      `Facet layer "${layer.id}" must be a complete materializable Cartesian mark.`
-    );
-  }
-  if (typeof layer.data !== "string" || layer.data.length === 0) {
-    throw new Error(`Facet layer "${layer.id}" requires a dataset.`);
-  }
-}
-
-function requireSupportedLayers(semanticSpec) {
-  if (!Array.isArray(semanticSpec.layers) || semanticSpec.layers.length === 0) {
-    throw new Error("facet requires at least one materializable layer.");
-  }
-  for (const layer of semanticSpec.layers) requireSupportedLayer(layer);
-}
-
 function requirePartitionDataset(semanticSpec, id) {
   const dataset = semanticSpec.datasets?.find(candidate => candidate.id === id);
   if (dataset === undefined) {
@@ -74,25 +30,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.");
@@ -102,9 +85,10 @@ export function resolveFacetDefinition(semanticSpec, options = {}) {
   }
   const field = requireFacetField(options.field);
   const id = validateUserId(options.id ?? "facet", "Facet id");
-  requireSupportedLayers(semanticSpec);
+  const family = resolveFacetFamily(semanticSpec);
   const dependencies = planFacetDependencies(semanticSpec, {
     field,
+    family,
     ...(options.data === undefined ? {} : { data: options.data })
   });
   const data = dependencies.anchor;
@@ -125,6 +109,7 @@ export function resolveFacetDefinition(semanticSpec, options = {}) {
   );
   return cloneAndFreeze({
     id,
+    family: family.family,
     data,
     field,
     values,
@@ -136,3 +121,89 @@ 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");
+  const family = resolveFacetFamily(semanticSpec);
+  const dependencies = planFacetDependencies(semanticSpec, {
+    field: rows.field,
+    family,
+    ...(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,
+    family: family.family,
+    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/facets/scales.js

@@ -3,6 +3,7 @@ import {
   FACET_SCALE_CHANNELS,
   FACET_SCALE_RESOLUTIONS
 } from "../../core/vocabulary.js";
+import { collectFacetScaleBindings } from "./dependencies.js";
 import { resolveHistogramBins } from "../histogram.js";
 import {
   hasOrdinalDomain,
@@ -63,30 +64,25 @@ function normalizeRequestedPolicies(requested) {
 
 function usedScaleChannels(semanticSpec, scales) {
   const used = new Map();
-  for (const layer of semanticSpec.layers) {
-    for (const channel of FACET_SCALE_CHANNELS) {
-      const id = layer.encoding?.[channel]?.scale;
-      if (id === undefined) continue;
-      if (!scales.has(id)) {
-        throw new Error(
-          `Facet layer "${layer.id}" references missing scale "${id}".`
-        );
-      }
-      if (!used.has(id)) used.set(id, new Set());
-      used.get(id).add(channel);
+  const bindings = collectFacetScaleBindings(semanticSpec);
+  for (const binding of bindings) {
+    if (!scales.has(binding.scaleId)) {
+      throw new Error(
+        `Facet layer "${binding.layerId}" references missing scale "${binding.scaleId}".`
+      );
     }
+    if (!used.has(binding.scaleId)) used.set(binding.scaleId, new Set());
+    used.get(binding.scaleId).add(binding.policyKey);
   }
-  return used;
+  return { used, bindings };
 }
 
 export function normalizeFacetScalePolicies(semanticSpec, requested = {}) {
   const scales = requireScaleDefinitions(semanticSpec);
   const channels = normalizeRequestedPolicies(requested);
-  const used = usedScaleChannels(semanticSpec, scales);
+  const { used, bindings } = usedScaleChannels(semanticSpec, scales);
   for (const channel of Object.keys(requested)) {
-    const applicable = semanticSpec.layers.some(
-      layer => layer.encoding?.[channel]?.scale !== undefined
-    );
+    const applicable = bindings.some(binding => binding.policyKey === channel);
     if (!applicable) {
       throw new Error(
         `Facet scale channel "${channel}" is not used by an affected layer.`
@@ -107,7 +103,7 @@ export function normalizeFacetScalePolicies(semanticSpec, requested = {}) {
       channels: attached
     };
   }
-  return cloneAndFreeze({ channels, scales: scalePolicies });
+  return cloneAndFreeze({ channels, scales: scalePolicies, bindings });
 }
 
 function requireChildDomains(resolvedByChild, scaleId) {
@@ -210,7 +206,8 @@ export function resolveFacetScaleDomains(
   }
   return cloneAndFreeze({
     channels: normalized.channels,
-    scales: resolved
+    scales: resolved,
+    bindings: normalized.bindings
   });
 }
 

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(