ggaction 0.0.3 → 0.0.5

package/src/grammar/interval.js

@@ -1,5 +1,6 @@
 import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
 import { aggregateScalarValues } from "./aggregate.js";
+import { studentTCriticalValue } from "./statistics/studentT.js";
 
 const CENTER_VALUES = Object.freeze(["mean", "median"]);
 const EXTENT_VALUES = Object.freeze(["stderr", "stdev", "ci", "iqr"]);
@@ -133,92 +134,6 @@ export function normalizeIntervalParameters({
   });
 }
 
-const LANCZOS = Object.freeze([
-  676.5203681218851,
-  -1259.1392167224028,
-  771.3234287776531,
-  -176.6150291621406,
-  12.507343278686905,
-  -0.13857109526572012,
-  9.984369578019572e-6,
-  1.5056327351493116e-7
-]);
-
-function logGamma(value) {
-  if (value < 0.5) {
-    return Math.log(Math.PI) - Math.log(Math.sin(Math.PI * value)) -
-      logGamma(1 - value);
-  }
-  const shifted = value - 1;
-  let sum = 0.9999999999998099;
-  for (const [index, coefficient] of LANCZOS.entries()) {
-    sum += coefficient / (shifted + index + 1);
-  }
-  const t = shifted + LANCZOS.length - 0.5;
-  return 0.5 * Math.log(2 * Math.PI) +
-    (shifted + 0.5) * Math.log(t) - t + Math.log(sum);
-}
-
-function betaFraction(a, b, x) {
-  const maximumIterations = 200;
-  const epsilon = 3e-14;
-  const floor = 1e-300;
-  const sum = a + b;
-  let c = 1;
-  let d = 1 - sum * x / (a + 1);
-  if (Math.abs(d) < floor) d = floor;
-  d = 1 / d;
-  let result = d;
-
-  for (let iteration = 1; iteration <= maximumIterations; iteration += 1) {
-    const even = 2 * iteration;
-    let coefficient = iteration * (b - iteration) * x /
-      ((a + even - 1) * (a + even));
-    d = 1 + coefficient * d;
-    if (Math.abs(d) < floor) d = floor;
-    c = 1 + coefficient / c;
-    if (Math.abs(c) < floor) c = floor;
-    d = 1 / d;
-    result *= d * c;
-
-    coefficient = -(a + iteration) * (sum + iteration) * x /
-      ((a + even) * (a + even + 1));
-    d = 1 + coefficient * d;
-    if (Math.abs(d) < floor) d = floor;
-    c = 1 + coefficient / c;
-    if (Math.abs(c) < floor) c = floor;
-    d = 1 / d;
-    const delta = d * c;
-    result *= delta;
-    if (Math.abs(delta - 1) <= epsilon) return result;
-  }
-  throw new Error("Student-t calculation did not converge.");
-}
-
-function regularizedBeta(x, a, b) {
-  if (x <= 0) return 0;
-  if (x >= 1) return 1;
-  const front = Math.exp(
-    logGamma(a + b) - logGamma(a) - logGamma(b) +
-    a * Math.log(x) + b * Math.log1p(-x)
-  );
-  return x < (a + 1) / (a + b + 2)
-    ? front * betaFraction(a, b, x) / a
-    : 1 - front * betaFraction(b, a, 1 - x) / b;
-}
-
-function studentTCdf(value, degreesOfFreedom) {
-  if (value === 0) return 0.5;
-  const x = degreesOfFreedom /
-    (degreesOfFreedom + value * value);
-  const tail = 0.5 * regularizedBeta(
-    x,
-    degreesOfFreedom / 2,
-    0.5
-  );
-  return value > 0 ? 1 - tail : tail;
-}
-
 export function studentTCritical(degreesOfFreedom, level) {
   if (!Number.isInteger(degreesOfFreedom) || degreesOfFreedom < 1) {
     throw new RangeError("Student-t degreesOfFreedom must be a positive integer.");
@@ -226,16 +141,7 @@ export function studentTCritical(degreesOfFreedom, level) {
   if (!Number.isFinite(level) || level <= 0 || level >= 1) {
     throw new RangeError("Student-t level must be between 0 and 1.");
   }
-  const target = 0.5 + level / 2;
-  let low = 0;
-  let high = 1;
-  while (studentTCdf(high, degreesOfFreedom) < target) high *= 2;
-  for (let iteration = 0; iteration < 100; iteration += 1) {
-    const midpoint = (low + high) / 2;
-    if (studentTCdf(midpoint, degreesOfFreedom) < target) low = midpoint;
-    else high = midpoint;
-  }
-  return (low + high) / 2;
+  return studentTCriticalValue(level, degreesOfFreedom);
 }
 
 function isMissing(value) {

package/src/grammar/jitter.js

@@ -0,0 +1,197 @@
+import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
+import { validateNonEmptyString } from "../core/validation.js";
+
+const UINT32_RANGE = 0x1_0000_0000;
+const CATEGORICAL_SCALE_TYPES = new Set(["band", "point", "ordinal"]);
+
+export const JITTER_ALGORITHM = "jitter-uniform-v1";
+
+export function canonicalJitterScalar(value, label = "Jitter identity") {
+  if (typeof value === "string") {
+    return `string:${new TextEncoder().encode(value).length}:${value}`;
+  }
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return `number:${Object.is(value, -0) ? "0" : String(value)}`;
+  }
+  if (typeof value === "boolean") return `boolean:${value}`;
+  throw new TypeError(`${label} must be a string, finite number, or boolean.`);
+}
+
+export function stableUint32HashV1(value) {
+  const bytes = new TextEncoder().encode(value);
+  let hash = 0x811c9dc5;
+  for (const byte of bytes) {
+    hash ^= byte;
+    hash = Math.imul(hash, 0x01000193) >>> 0;
+  }
+  return hash;
+}
+
+function jitterIdentity({ target, channel, seed, identity }) {
+  return [
+    canonicalJitterScalar(target, "Jitter target"),
+    canonicalJitterScalar(channel, "Jitter channel"),
+    canonicalJitterScalar(seed, "Jitter seed"),
+    canonicalJitterScalar(identity, "Jitter key")
+  ].join("\0");
+}
+
+function requestedOffset(options, maximum) {
+  const hash = stableUint32HashV1(jitterIdentity(options));
+  return (2 * (hash / UINT32_RANGE) - 1) * maximum;
+}
+
+export function normalizePointJitterPolicy(options = {}) {
+  if (!isPlainObject(options)) {
+    throw new TypeError("Point jitter options must be a plain object.");
+  }
+  if (!["x", "y"].includes(options.channel)) {
+    throw new Error('Point jitter channel must be "x" or "y".');
+  }
+  const maxOffset = options.maxOffset;
+  if (!isPlainObject(maxOffset)) {
+    throw new TypeError("Point jitter maxOffset must be a plain object.");
+  }
+  const keys = Object.keys(maxOffset);
+  if (
+    keys.length !== 1 ||
+    !["pixels", "band"].includes(keys[0])
+  ) {
+    throw new Error("Point jitter maxOffset requires exactly one of pixels or band.");
+  }
+  const kind = keys[0];
+  const value = maxOffset[kind];
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new RangeError(`Point jitter ${kind} must be positive and finite.`);
+  }
+  if (kind === "band" && value > 0.5) {
+    throw new RangeError("Point jitter band must be at most 0.5.");
+  }
+  const seed = options.seed ?? 0;
+  if (!(
+    typeof seed === "string" ||
+    (typeof seed === "number" && Number.isFinite(seed))
+  )) {
+    throw new TypeError("Point jitter seed must be a string or finite number.");
+  }
+  const key = options.key === undefined
+    ? undefined
+    : validateNonEmptyString(options.key, "Point jitter key");
+  return cloneAndFreeze({
+    algorithm: JITTER_ALGORITHM,
+    channel: options.channel,
+    maxOffset: { [kind]: value },
+    seed,
+    ...(key === undefined ? {} : { key })
+  });
+}
+
+export function resolveJitterSlotWidth(scale) {
+  if (!CATEGORICAL_SCALE_TYPES.has(scale?.type)) return undefined;
+  const width = scale.bandwidth > 0
+    ? scale.bandwidth
+    : Math.abs(scale.step);
+  return Number.isFinite(width) && width > 0 ? width : undefined;
+}
+
+export function resolveJitterMaximum(policy, scale) {
+  if (policy.maxOffset.pixels !== undefined) {
+    return policy.maxOffset.pixels;
+  }
+  const slotWidth = resolveJitterSlotWidth(scale);
+  if (slotWidth === undefined) {
+    throw new Error(
+      "Band point jitter requires a categorical position scale with a positive slot."
+    );
+  }
+  return slotWidth * policy.maxOffset.band;
+}
+
+function containOffset({
+  base,
+  requested,
+  plotMinimum,
+  plotMaximum,
+  halfExtent,
+  slotWidth
+}) {
+  let minimum = plotMinimum + halfExtent;
+  let maximum = plotMaximum - halfExtent;
+  if (slotWidth !== undefined) {
+    minimum = Math.max(minimum, base - slotWidth / 2 + halfExtent);
+    maximum = Math.min(maximum, base + slotWidth / 2 - halfExtent);
+  }
+  if (minimum > maximum) {
+    return { offset: 0, clamped: true, available: false };
+  }
+  const final = Math.max(minimum, Math.min(maximum, base + requested));
+  return {
+    offset: final - base,
+    clamped: final !== base + requested,
+    available: true
+  };
+}
+
+export function resolvePointJitter({
+  target,
+  policy,
+  scale,
+  entries,
+  plotMinimum,
+  plotMaximum
+}) {
+  validateNonEmptyString(target, "Point jitter target");
+  if (!Array.isArray(entries)) {
+    throw new TypeError("Point jitter entries must be an array.");
+  }
+  if (
+    !Number.isFinite(plotMinimum) ||
+    !Number.isFinite(plotMaximum) ||
+    plotMaximum < plotMinimum
+  ) {
+    throw new RangeError("Point jitter plot bounds are invalid.");
+  }
+  const maximum = resolveJitterMaximum(policy, scale);
+  const slotWidth = resolveJitterSlotWidth(scale);
+  const items = entries.map((entry, itemIndex) => {
+    if (!Number.isInteger(entry.index) || entry.index < 0) {
+      throw new TypeError(`Point jitter entry ${itemIndex} index must be non-negative.`);
+    }
+    if (!Number.isFinite(entry.base) || !Number.isFinite(entry.halfExtent)) {
+      throw new TypeError(`Point jitter entry ${itemIndex} geometry must be finite.`);
+    }
+    if (entry.halfExtent < 0) {
+      throw new RangeError(`Point jitter entry ${itemIndex} extent must not be negative.`);
+    }
+    const requested = requestedOffset({
+      target,
+      channel: policy.channel,
+      seed: policy.seed,
+      identity: entry.identity
+    }, maximum);
+    const contained = containOffset({
+      base: entry.base,
+      requested,
+      plotMinimum,
+      plotMaximum,
+      halfExtent: entry.halfExtent,
+      slotWidth
+    });
+    return {
+      index: entry.index,
+      identity: entry.identity,
+      requestedOffset: requested,
+      finalOffset: contained.offset,
+      clamped: contained.clamped,
+      available: contained.available
+    };
+  });
+  return cloneAndFreeze({
+    algorithm: JITTER_ALGORITHM,
+    maximum,
+    itemCount: items.length,
+    clampedItemCount: items.filter(item => item.clamped).length,
+    unavailableItemCount: items.filter(item => !item.available).length,
+    items
+  });
+}

package/src/grammar/lineSeries.js

@@ -3,13 +3,14 @@ import {
   readNominalField,
   readQuantitativeField,
   readTemporalField
-} from "./scales.js";
+} from "./scales/index.js";
 import {
   aggregateRows,
   isAggregate,
   validateAggregateFieldType,
   validateAggregateFieldValues,
 } from "./aggregate.js";
+import { stableOrderPathValues } from "./pathOrder.js";
 
 const SERIES_CHANNELS = Object.freeze(["group", "color", "strokeDash"]);
 
@@ -101,6 +102,51 @@ function deriveCartesianLineSeries(rows, layer) {
       : readQuantitativeField(rows, y.field);
   const seriesFields = readSeriesFields(rows, layer);
 
+  const pathOrder = layer.encoding?.pathOrder;
+  if (pathOrder !== undefined) {
+    if (isAggregate) {
+      throw new Error(
+        `Line mark "${layer.id}" cannot combine aggregate y and path order.`
+      );
+    }
+    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 key = groupKey(dimensions);
+      const series = groups.get(key) ?? {
+        key: Object.fromEntries(
+          seriesFields.fields.map((field, item) => [field, dimensions[item]])
+        ),
+        values: [],
+        orderValues: []
+      };
+      series.values.push({ x: xValues[index], y: yValues[index] });
+      series.orderValues.push(orderValues[index]);
+      groups.set(key, series);
+    }
+    const series = [...groups.values()].flatMap(item => {
+      const values = stableOrderPathValues(
+        item.values,
+        item.orderValues,
+        pathOrder.order
+      );
+      return values.length < 2 ? [] : [{ key: item.key, values }];
+    });
+    if (series.length === 0) {
+      throw new Error(
+        `Line series on mark "${layer.id}" requires at least two ordered points.`
+      );
+    }
+    return cloneAndFreeze({
+      xValues: series.flatMap(item => item.values.map(value => value.x)),
+      yValues: series.flatMap(item => item.values.map(value => value.y)),
+      series
+    });
+  }
+
   if (directTemporal) {
     const groups = new Map();
     for (let index = 0; index < rows.length; index += 1) {
@@ -249,6 +295,11 @@ function thetaOrder(values, fieldType, domain) {
 }
 
 export function derivePolarLineSeries(rows, layer, { thetaDomain } = {}) {
+  if (layer.encoding?.pathOrder !== undefined) {
+    throw new Error(
+      `Polar line mark "${layer.id}" does not support path order.`
+    );
+  }
   const { theta, radius } = requirePolarLineEncoding(layer);
   const thetaValues = readThetaValues(rows, theta);
   const radiusValues = readQuantitativeField(rows, radius.field);
@@ -303,3 +354,21 @@ export function deriveLineSeries(rows, layer, options) {
     ? derivePolarLineSeries(rows, layer, options)
     : deriveCartesianLineSeries(rows, layer);
 }
+
+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/paint.js

@@ -0,0 +1,88 @@
+import { isPlainObject } from "../core/immutable.js";
+
+const PAINT_KEYS = Object.freeze(["type", "from", "to", "stops"]);
+const POINT_KEYS = Object.freeze(["x", "y"]);
+const STOP_KEYS = Object.freeze(["offset", "color"]);
+
+function hasExactKeys(value, keys) {
+  const actual = Object.keys(value);
+  return actual.length === keys.length && keys.every(key => Object.hasOwn(value, key));
+}
+
+function validateUnitPoint(value, label) {
+  if (!isPlainObject(value) || !hasExactKeys(value, POINT_KEYS)) {
+    throw new TypeError(`${label} must be a plain { x, y } object.`);
+  }
+  for (const key of POINT_KEYS) {
+    if (!Number.isFinite(value[key]) || value[key] < 0 || value[key] > 1) {
+      throw new RangeError(`${label}.${key} must be a finite number from 0 to 1.`);
+    }
+  }
+}
+
+function validateStop(stop, index) {
+  const label = `Linear gradient stops[${index}]`;
+  if (!isPlainObject(stop) || !hasExactKeys(stop, STOP_KEYS)) {
+    throw new TypeError(`${label} must be a plain { offset, color } object.`);
+  }
+  if (!Number.isFinite(stop.offset) || stop.offset < 0 || stop.offset > 1) {
+    throw new RangeError(`${label}.offset must be a finite number from 0 to 1.`);
+  }
+  if (typeof stop.color !== "string" || stop.color.length === 0) {
+    throw new TypeError(`${label}.color must be a non-empty string.`);
+  }
+}
+
+export function isLinearGradientPaint(value) {
+  return isPlainObject(value) && value.type === "linear-gradient";
+}
+
+export function validateFillPaint(value, label = "fill") {
+  if (typeof value === "string") {
+    if (value.length === 0) throw new TypeError(`${label} must be a non-empty string or linear gradient.`);
+    return value;
+  }
+  if (!isPlainObject(value) || !hasExactKeys(value, PAINT_KEYS)) {
+    throw new TypeError(`${label} must be a non-empty string or linear gradient.`);
+  }
+  if (value.type !== "linear-gradient") {
+    throw new Error(`Unsupported fill paint type "${value.type}".`);
+  }
+  validateUnitPoint(value.from, "Linear gradient from");
+  validateUnitPoint(value.to, "Linear gradient to");
+  if (value.from.x === value.to.x && value.from.y === value.to.y) {
+    throw new Error("Linear gradient from and to must differ.");
+  }
+  if (!Array.isArray(value.stops) || value.stops.length < 2) {
+    throw new TypeError("Linear gradient stops must contain at least two entries.");
+  }
+  value.stops.forEach(validateStop);
+  for (let index = 1; index < value.stops.length; index += 1) {
+    if (value.stops[index].offset < value.stops[index - 1].offset) {
+      throw new Error("Linear gradient stop offsets must be nondecreasing.");
+    }
+  }
+  return value;
+}
+
+export function resolveLinearGradientCoordinates(paint, bounds) {
+  validateFillPaint(paint, "Linear gradient paint");
+  if (!isLinearGradientPaint(paint)) {
+    throw new TypeError("Linear gradient coordinates require a structured paint.");
+  }
+  if (
+    !isPlainObject(bounds) ||
+    ![bounds.left, bounds.right, bounds.top, bounds.bottom].every(Number.isFinite) ||
+    bounds.left > bounds.right ||
+    bounds.top > bounds.bottom
+  ) {
+    throw new TypeError("Linear gradient bounds must be finite and ordered.");
+  }
+  const width = bounds.right - bounds.left;
+  const height = bounds.bottom - bounds.top;
+  const point = value => Object.freeze({
+    x: bounds.left + width * value.x,
+    y: bounds.top + height * value.y
+  });
+  return Object.freeze({ from: point(paint.from), to: point(paint.to) });
+}

package/src/grammar/palettes.js

@@ -190,16 +190,14 @@ export function resolvePalette(value, domainCount) {
 }
 
 export function resolveContinuousPalette(value, count = 31) {
-  if (!Number.isInteger(count) || count < 2) {
-    throw new RangeError("Continuous palette count must be an integer of at least 2.");
-  }
   const palette = normalizePalette(value);
-  if (palette.count !== undefined) {
-    throw new Error("Continuous palette does not accept count.");
+  const resolvedCount = palette.count ?? count;
+  if (!Number.isInteger(resolvedCount) || resolvedCount < 2) {
+    throw new RangeError("Continuous palette count must be an integer of at least 2.");
   }
   const discrete = DISCRETE[palette.name];
-  if (discrete !== undefined) return discrete;
-  return resolvePalette({ ...palette, count }, count);
+  if (discrete !== undefined && palette.count === undefined) return discrete;
+  return resolvePalette({ ...palette, count: resolvedCount }, resolvedCount);
 }
 
 export function paletteFamily(name) {