ggaction 0.0.11 → 0.0.13

package/src/grammar/rotation.js

@@ -0,0 +1,29 @@
+const UNITS = new Set(["radians", "degrees"]);
+
+function toRadians(value, unit) {
+  return unit === "degrees" ? value * Math.PI / 180 : value;
+}
+
+export function resolveRotation(value, label = "Rotation", {
+  legacyUnit = "radians"
+} = {}) {
+  if (!UNITS.has(legacyUnit)) {
+    throw new TypeError(`${label} legacy unit must be radians or degrees.`);
+  }
+  if (Number.isFinite(value)) return toRadians(value, legacyUnit);
+  if (
+    value !== null &&
+    typeof value === "object" &&
+    Object.getPrototypeOf(value) === Object.prototype &&
+    Object.keys(value).length === 2 &&
+    Object.hasOwn(value, "value") &&
+    Object.hasOwn(value, "unit") &&
+    Number.isFinite(value.value) &&
+    UNITS.has(value.unit)
+  ) {
+    return toRadians(value.value, value.unit);
+  }
+  throw new TypeError(
+    `${label} must be a finite legacy number or { value, unit: "radians" | "degrees" }.`
+  );
+}

package/src/grammar/rules.js

@@ -1,16 +1,16 @@
+import { normalizePositionDatum } from "./positionDatum.js";
 import { cloneAndFreeze } from "../core/immutable.js";
 import {
-  isNominalValue,
-  normalizeTemporalValue,
   readNominalField,
   readQuantitativeField,
-  readTemporalField,
-  validateSemanticFieldType
+  readTemporalField
 } from "./scales/index.js";
 
 const ENDPOINT_CHANNELS = Object.freeze(["x", "y", "x2", "y2"]);
 const VALUE_CHANNELS = Object.freeze([
   ...ENDPOINT_CHANNELS,
+  "xOffset",
+  "yOffset",
   "strokeDash",
   "strokeWidth",
   "opacity"
@@ -37,26 +37,13 @@ function readField(rows, encoding) {
     return readNominalField(rows, encoding.field);
   }
   if (encoding.fieldType === "temporal") {
-    return readTemporalField(rows, encoding.field);
+    return readTemporalField(rows, encoding.field, encoding.temporalUnit);
   }
   return readQuantitativeField(rows, encoding.field);
 }
 
-export function normalizeRuleDatum(value, fieldType, channel) {
-  validateSemanticFieldType(fieldType);
-  if (fieldType === "quantitative") {
-    if (!Number.isFinite(value)) {
-      throw new TypeError(`Rule ${channel} datum must be a finite number.`);
-    }
-    return value;
-  }
-  if (fieldType === "temporal") {
-    return normalizeTemporalValue(value, `${channel} datum`, 0);
-  }
-  if (!isNominalValue(value)) {
-    throw new TypeError(`Rule ${channel} datum must be a nominal value.`);
-  }
-  return value;
+export function normalizeRuleDatum(value, fieldType, channel, temporalUnit) {
+  return normalizePositionDatum(value, fieldType, channel, temporalUnit, "Rule");
 }
 
 export function deriveRuleValues(rows, layer) {
@@ -81,7 +68,8 @@ export function deriveRuleValues(rows, layer) {
       const datum = normalizeRuleDatum(
         encoding.datum,
         encoding.fieldType,
-        channel
+        channel,
+        encoding.temporalUnit
       );
       values[channel] = Array.from({ length }, () => datum);
     }

package/src/grammar/scales/color.js

@@ -325,6 +325,23 @@ export function interpolateColorStops(stops, position, interpolation = "rgb") {
   return interpolateColors(colors, position, method, true);
 }
 
+export function validateSequentialMidpoint(value, type, domain = "auto") {
+  if (value === undefined || value === "auto") return undefined;
+  if (type !== "sequential") {
+    throw new Error(`Scale type "${type}" does not support midpoint.`);
+  }
+  if (!Number.isFinite(value)) {
+    throw new TypeError("Scale midpoint must be finite or auto.");
+  }
+  if (domain !== "auto" && (
+    !Array.isArray(domain) || domain.length !== 2 || !domain.every(Number.isFinite) ||
+    !(value > Math.min(...domain) && value < Math.max(...domain))
+  )) {
+    throw new RangeError("Scale midpoint must lie strictly inside its resolved domain.");
+  }
+  return value;
+}
+
 export function mapSequentialColors(
   values,
   domain,
@@ -342,6 +359,7 @@ export function mapSequentialColors(
   if (typeof shouldClamp !== "boolean") {
     throw new TypeError("Sequential color clamp must be a boolean.");
   }
+  const midpoint = validateSequentialMidpoint(options.midpoint, "sequential", domain);
   const [start, end] = domain;
   const constant = start === end;
   const method = validateContinuousColorInterpolation(interpolation);
@@ -354,7 +372,11 @@ export function mapSequentialColors(
       if (hasUnknown) return options.unknown;
       throw new TypeError("Sequential color values must be finite numbers.");
     }
-    const raw = constant ? 0.5 : inverseLerp(value, start, end);
+    const raw = midpoint === undefined
+      ? constant ? 0.5 : inverseLerp(value, start, end)
+      : (end > start ? value <= midpoint : value >= midpoint)
+        ? inverseLerp(value, start, midpoint) / 2
+        : 0.5 + inverseLerp(value, midpoint, end) / 2;
     return interpolateColors(colors, raw, method, shouldClamp);
   }));
 }

package/src/grammar/scales/colorConsumers.js

@@ -0,0 +1,38 @@
+import { BAR_GRAINS, resolveBarChannels, resolveBarGrain } from "../bars/policy.js";
+import { validateAggregate, validateAggregateFieldType } from "../aggregate.js";
+import { isDiscretizedColorScaleType } from "./types.js";
+
+export function validateContinuousColorConsumer(layer, encoding, scale, { inferAggregate = false } = {}) {
+  const kind = layer.mark?.type;
+  if (!["point", "bar", "rect"].includes(kind)) {
+    throw new Error("Continuous color requires a Point, aggregate Bar, or Rect consumer.");
+  }
+  if (!["quantitative", "temporal"].includes(encoding.fieldType) ||
+    (isDiscretizedColorScaleType(scale.type) && encoding.fieldType !== "quantitative")) {
+    throw new Error(`Scale type "${scale.type}" has an incompatible color field type.`);
+  }
+  if (Object.hasOwn(scale, "unknown") && kind !== "point") {
+    throw new Error("Continuous color scale unknown currently requires a row-owned point mark.");
+  }
+  if (kind !== "bar") {
+    if (encoding.aggregate !== undefined) throw new Error(`${kind} continuous color does not support aggregate.`);
+    return undefined;
+  }
+  if (["nominal", "ordinal"].includes(layer.encoding?.color?.fieldType)) {
+    throw new Error("Continuous bar color cannot replace an existing nominal color layout.");
+  }
+  if (encoding.fieldType !== "quantitative") {
+    throw new Error("Aggregate bar color currently requires a quantitative field.");
+  }
+  if (resolveBarGrain(layer) !== BAR_GRAINS.aggregate) {
+    throw new Error("Continuous bar color requires a complete categorical aggregate bar.");
+  }
+  const measure = layer.encoding?.[resolveBarChannels(layer).measure];
+  const aggregate = encoding.aggregate ?? (inferAggregate && measure?.field === encoding.field ? measure.aggregate : undefined);
+  if (aggregate === undefined) {
+    throw new Error("Continuous bar color requires aggregate when its field differs from the measure field.");
+  }
+  validateAggregate(aggregate);
+  validateAggregateFieldType(aggregate, encoding.fieldType);
+  return aggregate;
+}

package/src/grammar/scales/definition.js

@@ -1,4 +1,5 @@
-import { validateContinuousColorInterpolation } from "./color.js";
+import { validateMeasuredRadiusScale } from "./radial.js";
+import { validateContinuousColorInterpolation, validateSequentialMidpoint } from "./color.js";
 import { isTransformedScaleType } from "./mapping.js";
 import {
   normalizeTransformParameters,
@@ -137,6 +138,11 @@ export function normalizeScaleDefinition({
     throw new Error(`Scale type "${type}" does not support interpolate.`);
   }
 
+  const midpoint = validateSequentialMidpoint(
+    retainedValue(previous, patch, defaults, "midpoint", typeChanged), type, definition.domain
+  );
+  if (midpoint !== undefined) definition.midpoint = midpoint;
+
   if (type === "band") {
     validateBandParameters(definition, previous, patch, defaults, typeChanged);
   } else if (type === "point") {
@@ -149,5 +155,13 @@ export function normalizeScaleDefinition({
     }
   }
 
+  const radialMapping = Object.hasOwn(patch, "radialMapping") ? patch.radialMapping : previous.radialMapping;
+  if (radialMapping !== undefined) {
+    definition.radialMapping = radialMapping;
+    validateMeasuredRadiusScale({ ...definition,
+      ...(Object.hasOwn(patch, "unknown") || Object.hasOwn(previous, "unknown")
+        ? { unknown: patch.unknown ?? previous.unknown } : {})
+    }, { allowAuto: true });
+  }
   return definition;
 }

package/src/grammar/scales/discretized.js

@@ -1,6 +1,7 @@
 import { cloneAndFreeze } from "../../core/immutable.js";
 import { validateGeneratedItemLimit } from "../../core/validation.js";
 import { interpolateNumber } from "../numeric.js";
+import { formatValue, validateValueFormat } from "../valueFormat.js";
 import { resolveColorRange, validateColorRange } from "./appearance.js";
 import { SCALE_ROLES, validateScaleTypeForRole } from "./types.js";
 
@@ -162,17 +163,22 @@ export function mapDiscretizedColors(values, scale) {
   }));
 }
 
-export function formatDiscretizedIntervals(thresholds) {
+export function formatDiscretizedIntervals(thresholds, format = "auto") {
   nondecreasing(thresholds, "Discretized color thresholds");
+  const resolvedFormat = validateValueFormat(format, "Legend label format");
   let resolution = Infinity;
   for (let index = 1; index < thresholds.length; index += 1) {
     const gap = thresholds[index] - thresholds[index - 1];
     if (Number.isFinite(gap) && gap > 0) resolution = Math.min(resolution, gap);
   }
-  let labels = thresholds.map(value =>
-    Number.isInteger(value) ? String(value) : value.toFixed(1)
-  );
-  if (thresholds.some((value, index) => {
+  let labels = resolvedFormat === "auto"
+    ? thresholds.map(value => Number.isInteger(value) ? String(value) : value.toFixed(1))
+    : thresholds.map(value => formatValue(value, {
+        format: resolvedFormat,
+        valueType: "quantitative",
+        label: "Legend label format"
+      }));
+  if (resolvedFormat === "auto" && thresholds.some((value, index) => {
     const rounded = Number(labels[index]);
     return value !== 0 && rounded === 0 ||
       index > 0 && value !== thresholds[index - 1] &&

package/src/grammar/scales/fields.js

@@ -81,9 +81,37 @@ function validTimestamp(value) {
   return Number.isFinite(value) && Number.isFinite(new Date(value).getTime());
 }
 
-export function normalizeTemporalValue(value, field = "value", index = 0) {
+export function validateTemporalUnit(unit) {
+  if (unit !== undefined && !["auto", "year", "timestamp"].includes(unit)) {
+    throw new Error(`Unsupported temporalUnit "${unit}"; use auto, year, or timestamp.`);
+  }
+  return unit;
+}
+
+export function resolveTemporalUnit(options, fieldType, previous) {
+  if (fieldType !== "temporal") {
+    if (Object.hasOwn(options, "temporalUnit")) {
+      throw new Error("temporalUnit requires a temporal fieldType.");
+    }
+    return undefined;
+  }
+  validateTemporalUnit(options.temporalUnit);
+  const sameBinding = ["field", "datum"].some(key =>
+    Object.hasOwn(options, key) && Object.hasOwn(previous ?? {}, key) &&
+    options[key] === previous[key]);
+  return options.temporalUnit ?? (sameBinding && previous?.fieldType === "temporal"
+    ? previous.temporalUnit : undefined);
+}
+
+export function normalizeTemporalValue(value, field = "value", index = 0, temporalUnit = "auto") {
+  validateTemporalUnit(temporalUnit);
   let timestamp;
-  if (typeof value === "number") {
+  if (temporalUnit === "year") {
+    const year = typeof value === "string" && /^\d{4}$/.test(value) ? Number(value) : value;
+    if (Number.isInteger(year) && year >= 0 && year <= 9999) timestamp = utcDate(year);
+  } else if (temporalUnit === "timestamp") {
+    if (typeof value === "number") timestamp = value;
+  } else if (typeof value === "number") {
     timestamp = Number.isInteger(value) && value >= 1000 && value <= 9999
       ? utcDate(value)
       : value;
@@ -99,21 +127,22 @@ export function normalizeTemporalValue(value, field = "value", index = 0) {
   if (!validTimestamp(timestamp)) {
     throw new TypeError(
       `Field "${field}" must contain a temporal string or finite timestamp ` +
-      `(including a valid date or four-digit year) at row ${index}.`
+      `(including a valid date or four-digit year) at row ${index}; temporalUnit is ${temporalUnit}.`
     );
   }
   return timestamp;
 }
 
-export function readTemporalField(rows, field) {
+export function readTemporalField(rows, field, temporalUnit) {
   validateField(field);
+  validateTemporalUnit(temporalUnit);
   return cloneAndFreeze(rows.map((row, index) => {
     if (!Object.hasOwn(row, field)) {
       throw new TypeError(
         `Field "${field}" must contain a temporal string or finite timestamp at row ${index}.`
       );
     }
-    return normalizeTemporalValue(row[field], field, index);
+    return normalizeTemporalValue(row[field], field, index, temporalUnit);
   }));
 }
 
@@ -129,10 +158,11 @@ export function readNominalField(rows, field) {
   }));
 }
 
-export function readScaleField(rows, field, fieldType, { allowUnknown = false } = {}) {
+export function readScaleField(rows, field, fieldType, { allowUnknown = false, temporalUnit } = {}) {
   validateSemanticFieldType(fieldType);
+  validateTemporalUnit(temporalUnit);
   if (!allowUnknown) {
-    if (fieldType === "temporal") return readTemporalField(rows, field);
+    if (fieldType === "temporal") return readTemporalField(rows, field, temporalUnit);
     if (["nominal", "ordinal"].includes(fieldType)) {
       return readNominalField(rows, field);
     }
@@ -149,7 +179,7 @@ export function readScaleField(rows, field, fieldType, { allowUnknown = false }
       return isNominalValue(value) ? value : undefined;
     }
     try {
-      return normalizeTemporalValue(value, field, index);
+      return normalizeTemporalValue(value, field, index, temporalUnit);
     } catch {
       return undefined;
     }

package/src/grammar/scales/mapping.js

@@ -1,3 +1,4 @@
+import { mapMeasuredRadiusValues } from "./radial.js";
 import { mapLinearValues } from "./continuous.js";
 import { mapTransformedValues } from "./transformed.js";
 import { SCALE_ROLES, validateScaleTypeForRole } from "./types.js";
@@ -9,6 +10,7 @@ export function isTransformedScaleType(type) {
 }
 
 export function mapContinuousScaleValues(values, scale) {
+  if (scale?.radialMapping !== undefined) return mapMeasuredRadiusValues(values, scale);
   if (isTransformedScaleType(scale?.type)) {
     validateScaleTypeForRole(scale.type, SCALE_ROLES.quantitativePosition);
     return mapTransformedValues(values, scale.domain, scale.range, {

package/src/grammar/scales/ordinal.js

@@ -278,3 +278,26 @@ export function mapOrdinalPositionValues(values, scale) {
     );
   }));
 }
+
+export function mapOrdinalOffsetValues(values, scale) {
+  const indices = new Map(scale.domain.map((value, index) => [value, index]));
+  const direction = Math.sign(scale.step) || 1;
+  const denominator = Math.max(
+    1,
+    scale.domain.length - scale.paddingInner + scale.paddingOuter * 2
+  );
+  return cloneAndFreeze(values.map(value => {
+    const index = indices.get(value);
+    if (index === undefined) {
+      throw new Error(`Value "${value}" is outside the ordinal domain.`);
+    }
+    const direct = scale.start + index * scale.step +
+      direction * scale.bandwidth / 2;
+    return finitePosition(
+      direct,
+      scale,
+      (scale.paddingOuter + index + (1 - scale.paddingInner) / 2) /
+        denominator
+    );
+  }));
+}

package/src/grammar/scales/radial.js

@@ -0,0 +1,55 @@
+import { cloneAndFreeze } from "../../core/immutable.js";
+import { interpolateNumber } from "../numeric.js";
+
+export function validateRadialMapping(mapping) {
+  if (!["area", "radius-length"].includes(mapping)) {
+    throw new Error('Radial mapping must be "area" or "radius-length".');
+  }
+  return mapping;
+}
+
+export function validateMeasuredRadiusScale(scale, { allowAuto = false } = {}) {
+  validateRadialMapping(scale.radialMapping);
+  if (scale.type !== "linear" || (scale.nice !== undefined && scale.nice !== false) ||
+    (scale.zero !== undefined && scale.zero !== true) ||
+    (scale.reverse !== undefined && scale.reverse !== false) || Object.hasOwn(scale, "unknown")) {
+    throw new Error("Measured radius requires a linear, zero-based, non-reversed scale without nice or unknown.");
+  }
+  if (!(allowAuto && scale.domain === "auto") && (!Array.isArray(scale.domain) || scale.domain.length !== 2 ||
+    scale.domain[0] !== 0 || !Number.isFinite(scale.domain[1]) || scale.domain[1] <= 0)) {
+    throw new RangeError("Measured radius domain must be [0, positive finite maximum].");
+  }
+  if (!(allowAuto && scale.range === "auto") && (!Array.isArray(scale.range) || scale.range.length !== 2 ||
+    !scale.range.every(Number.isFinite) || scale.range[0] < 0 || scale.range[0] >= scale.range[1])) {
+    throw new RangeError("Measured radius range must satisfy 0 <= inner < outer with finite radii.");
+  }
+  if (scale.clamp !== undefined && typeof scale.clamp !== "boolean") {
+    throw new TypeError("Measured radius clamp must be a boolean.");
+  }
+  return scale;
+}
+
+export function mapMeasuredRadiusValues(values, scale) {
+  validateMeasuredRadiusScale(scale);
+  const [inner, outer] = scale.range;
+  const ratio = inner / outer;
+  // Normalize before squaring so finite large radii do not overflow.
+  const annulus = (1 - ratio) * (1 + ratio);
+  return cloneAndFreeze(values.map(value => {
+    if (!Number.isFinite(value)) throw new TypeError("Measured radius values must be finite.");
+    const proportion = value / scale.domain[1];
+    const t = scale.clamp ? Math.max(0, Math.min(1, proportion)) : proportion;
+    if (!Number.isFinite(t) || t < 0 || t > 1) {
+      throw new RangeError("Measured radius value must lie inside its zero-based domain.");
+    }
+    if (t === 0 && value <= 0) return inner;
+    if (t === 1) return outer;
+    const radius = scale.radialMapping === "area"
+      ? outer * Math.sqrt(Math.min(1, ratio * ratio + t * annulus))
+      : interpolateNumber(inner, outer, t);
+    if (radius <= inner) {
+      throw new RangeError("Positive measured radius cannot be represented distinctly from the inner radius at this numeric precision.");
+    }
+    return Math.min(outer, radius);
+  }));
+}

package/src/grammar/scales/types.js

@@ -27,6 +27,7 @@ export const COMPLETE_SCALE_TYPES = Object.freeze([
 ]);
 
 const SCALE_PROPERTY_TYPES = Object.freeze({
+  midpoint: Object.freeze(["sequential"]),
   nice: Object.freeze(["linear", "log", "pow", "sqrt", "symlog", "time"]),
   zero: Object.freeze(["linear", "pow", "sqrt", "symlog"]),
   clamp: Object.freeze([

package/src/grammar/schemas/semanticPath.js

@@ -20,12 +20,21 @@ const ENCODING_PATHS = Object.freeze([
   "encoding.x.bin.boundaries",
   "encoding.color.layout",
   "encoding.color.aggregate",
+  "encoding.group.fields",
+  "encoding.group.inferredFrom",
+  ...["x", "y", "x2", "y2", "theta", "color"].map(channel =>
+    `encoding.${channel}.temporalUnit`
+  ),
   "encoding.pathOrder.field",
   "encoding.pathOrder.fieldType",
   "encoding.pathOrder.order",
   "encoding.theta.aggregate",
   "encoding.theta.weight",
+  "encoding.radius.aggregate",
+  "encoding.theta.categoryOrder",
   "encoding.text.format",
+  "encoding.text.content",
+  "encoding.text.normalizeBy",
   "encoding.parallel.dimensions",
   "encoding.parallel.key",
   "encoding.parallel.missing",
@@ -45,7 +54,7 @@ const ENTITY_PATHS = Object.freeze({
     collection: "layers",
     removableContainers: new Set(
       [...ENCODING_CHANNELS.map(channel => `encoding.${channel}`),
-        "encoding.parallel"]
+        "encoding.parallel", "layout"]
     ),
     properties: new Set([
       "data",
@@ -53,6 +62,8 @@ const ENTITY_PATHS = Object.freeze({
       "coordinate",
       "transform",
       "mark.type",
+      "mark.missing",
+      "layout.mode",
       ...ENCODING_PATHS
     ])
   },
@@ -60,7 +71,7 @@ const ENTITY_PATHS = Object.freeze({
     collection: "scales",
     properties: new Set([
       "type", "domain", "range", "nice", "zero", "clamp", "reverse",
-      "unknown", "base", "exponent", "constant", "interpolate",
+      "unknown", "base", "exponent", "constant", "interpolate", "radialMapping", "midpoint",
       "paddingInner", "paddingOuter", "padding", "align"
     ])
   },
@@ -86,8 +97,10 @@ const GUIDE_PATHS = new Set([
   "axis.parallel.target",
   "axis.parallel.coordinate",
   "axis.parallel.scales",
+  "axis.parallel.titles",
   "legend.color.scale",
   "legend.color.title",
+  "legend.color.order",
   "legend.size.scale",
   "legend.size.title",
   "legend.strokeWidth.scale",
@@ -97,6 +110,7 @@ const GUIDE_PATHS = new Set([
   "legend.series.channels",
   "legend.series.scales",
   "legend.series.title",
+  "legend.series.order",
   "grid.horizontal.scale",
   "grid.horizontal.coordinate",
   "grid.vertical.scale",
@@ -137,7 +151,7 @@ export function parseSemanticPath(property, { allowContainer = false } = {}) {
 
   if (allowContainer) {
     const entityMatch = property.match(
-      new RegExp(`^(dataset|layer)\\[(${USER_ID_SOURCE})\\]$`)
+      new RegExp(`^(dataset|layer|scale)\\[(${USER_ID_SOURCE})\\]$`)
     );
     if (entityMatch) {
       const [, kind, id] = entityMatch;