ggaction 0.0.4 → 0.0.6

package/src/grammar/horizon.js

@@ -0,0 +1,455 @@
+import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
+import { normalizePalette } from "./palettes.js";
+import {
+  isNominalValue,
+  normalizeTemporalValue
+} 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 OUTPUT_PROPERTIES = Object.freeze([
+  "x", "lower", "upper", "group", "color", "sign", "band", "segment"
+]);
+
+function requireField(value, label) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError(`${label} must be a non-empty string.`);
+  }
+  return value;
+}
+
+function validateEncoding(value, role) {
+  if (!isPlainObject(value)) {
+    throw new TypeError(`Horizon ${role} encoding must be a plain object.`);
+  }
+  const unknown = Object.keys(value).find(
+    property => !ENCODING_PROPERTIES.includes(property)
+  );
+  if (unknown !== undefined) {
+    throw new Error(`Unknown Horizon ${role} encoding property "${unknown}".`);
+  }
+  const field = requireField(value.field, `Horizon ${role} field`);
+  const fieldType = value.fieldType ?? (role === "x" ? "quantitative" : "quantitative");
+  const supported = role === "x"
+    ? ["quantitative", "temporal"]
+    : ["quantitative"];
+  if (!supported.includes(fieldType)) {
+    throw new Error(
+      `Horizon ${role} fieldType must be ${supported.join(" or ")}.`
+    );
+  }
+  return { field, fieldType };
+}
+
+function validateOutputFields(value) {
+  if (!isPlainObject(value)) {
+    throw new TypeError("Horizon as must be a plain object.");
+  }
+  const unknown = Object.keys(value).find(
+    property => !OUTPUT_PROPERTIES.includes(property)
+  );
+  if (unknown !== undefined) {
+    throw new Error(`Unknown Horizon output field "${unknown}".`);
+  }
+  const output = Object.fromEntries(OUTPUT_PROPERTIES.map(property => [
+    property,
+    requireField(value[property], `Horizon ${property} output field`)
+  ]));
+  if (new Set(Object.values(output)).size !== OUTPUT_PROPERTIES.length) {
+    throw new Error("Horizon output fields must be distinct.");
+  }
+  return output;
+}
+
+function validatePalette(value = {}) {
+  if (!isPlainObject(value)) {
+    throw new TypeError("Horizon palette must be a plain object.");
+  }
+  const unknown = Object.keys(value).find(
+    property => !["positive", "negative"].includes(property)
+  );
+  if (unknown !== undefined) {
+    throw new Error(`Unknown Horizon palette property "${unknown}".`);
+  }
+  return {
+    positive: normalizePalette(value.positive ?? "blues"),
+    negative: normalizePalette(value.negative ?? "reds")
+  };
+}
+
+function validateResolved(value) {
+  if (!isPlainObject(value) || Object.keys(value).some(key => key !== "extents")) {
+    throw new TypeError("Horizon resolved provenance must contain only extents.");
+  }
+  if (!Array.isArray(value.extents) || value.extents.length === 0) {
+    throw new TypeError("Horizon resolved extents must be a non-empty array.");
+  }
+  for (const [index, entry] of value.extents.entries()) {
+    if (
+      !isPlainObject(entry) ||
+      Object.keys(entry).some(key => !["group", "extent", "bandHeight"].includes(key)) ||
+      !Number.isFinite(entry.extent) ||
+      entry.extent < 0 ||
+      !Number.isFinite(entry.bandHeight) ||
+      entry.bandHeight < 0
+    ) {
+      throw new TypeError(`Horizon resolved extent ${index} is invalid.`);
+    }
+    if (Object.hasOwn(entry, "group") && !isNominalValue(entry.group)) {
+      throw new TypeError(`Horizon resolved group ${index} must be nominal.`);
+    }
+  }
+  return value;
+}
+
+export function requestedHorizonTransform(transform) {
+  const { resolved: _resolved, ...requested } = transform;
+  void _resolved;
+  return requested;
+}
+
+export function validateHorizonTransform(transform) {
+  if (!isPlainObject(transform)) {
+    throw new TypeError("Horizon transform must be a plain object.");
+  }
+  const supported = [
+    "type", "x", "y", "groupBy", "bands", "baseline", "extent",
+    "resolve", "missing", "overflow", "palette", "as", "resolved"
+  ];
+  const unknown = Object.keys(transform).find(key => !supported.includes(key));
+  if (unknown !== undefined) {
+    throw new Error(`Unknown Horizon transform property "${unknown}".`);
+  }
+  if (transform.type !== "horizon") {
+    throw new Error(`Unsupported Horizon transform "${transform.type}".`);
+  }
+  const x = validateEncoding(transform.x, "x");
+  const y = validateEncoding(transform.y, "y");
+  if (x.field === y.field) {
+    throw new Error("Horizon x and y fields must differ.");
+  }
+  if (transform.groupBy !== undefined) {
+    requireField(transform.groupBy, "Horizon groupBy");
+    if ([x.field, y.field].includes(transform.groupBy)) {
+      throw new Error("Horizon groupBy must differ from x and y fields.");
+    }
+  }
+  if (!Number.isInteger(transform.bands) || transform.bands <= 0) {
+    throw new RangeError("Horizon bands must be a positive integer.");
+  }
+  if (!Number.isFinite(transform.baseline)) {
+    throw new TypeError("Horizon baseline must be finite.");
+  }
+  if (
+    transform.extent !== "auto" &&
+    (!Number.isFinite(transform.extent) || transform.extent <= 0)
+  ) {
+    throw new RangeError('Horizon extent must be "auto" or a positive number.');
+  }
+  if (!HORIZON_RESOLUTIONS.includes(transform.resolve)) {
+    throw new Error(`Unknown Horizon resolve "${transform.resolve}".`);
+  }
+  if (!HORIZON_MISSING_POLICIES.includes(transform.missing)) {
+    throw new Error(`Unknown Horizon missing policy "${transform.missing}".`);
+  }
+  if (!HORIZON_OVERFLOW_POLICIES.includes(transform.overflow)) {
+    throw new Error(`Unknown Horizon overflow policy "${transform.overflow}".`);
+  }
+  const palette = validatePalette(transform.palette);
+  for (const [sign, value] of Object.entries(palette)) {
+    if (value.count !== undefined && value.count !== transform.bands) {
+      throw new Error(
+        `Horizon ${sign} palette count must equal bands (${transform.bands}).`
+      );
+    }
+  }
+  const as = validateOutputFields(transform.as);
+  if (transform.groupBy !== undefined && Object.values(as).includes(transform.groupBy)) {
+    throw new Error("Horizon output fields must not collide with groupBy.");
+  }
+  if (transform.resolved !== undefined) validateResolved(transform.resolved);
+  return cloneAndFreeze({
+    ...transform,
+    x,
+    y,
+    palette,
+    as
+  });
+}
+
+function orderedX(value, encoding, rowIndex) {
+  if (encoding.fieldType === "temporal") {
+    return normalizeTemporalValue(value, encoding.field, rowIndex);
+  }
+  if (!Number.isFinite(value)) {
+    throw new TypeError(
+      `Horizon x field "${encoding.field}" must contain finite numbers at row ${rowIndex}.`
+    );
+  }
+  return value;
+}
+
+function groupRows(rows, transform) {
+  const groups = [];
+  const indexed = new Map();
+  for (const [sourceRowIndex, row] of rows.entries()) {
+    if (!isPlainObject(row)) {
+      throw new TypeError(`Horizon row ${sourceRowIndex} must be a plain object.`);
+    }
+    const group = transform.groupBy === undefined ? undefined : row[transform.groupBy];
+    if (transform.groupBy !== undefined && !isNominalValue(group)) {
+      throw new TypeError(
+        `Horizon groupBy field "${transform.groupBy}" must contain nominal values at row ${sourceRowIndex}.`
+      );
+    }
+    const key = transform.groupBy === undefined
+      ? "__horizon_ungrouped__"
+      : `${typeof group}:${String(group)}`;
+    if (!indexed.has(key)) {
+      const entry = { group, groupIndex: groups.length, rows: [] };
+      indexed.set(key, entry);
+      groups.push(entry);
+    }
+    const y = row[transform.y.field];
+    const missing = !Number.isFinite(y);
+    if (missing && transform.missing === "error") {
+      throw new Error(
+        `Horizon y field "${transform.y.field}" is missing at source row ${sourceRowIndex}.`
+      );
+    }
+    indexed.get(key).rows.push({
+      sourceRowIndex,
+      x: orderedX(row[transform.x.field], transform.x, sourceRowIndex),
+      y,
+      missing
+    });
+  }
+  for (const entry of groups) {
+    entry.rows.sort((left, right) =>
+      left.x - right.x || left.sourceRowIndex - right.sourceRowIndex
+    );
+    for (let index = 1; index < entry.rows.length; index += 1) {
+      if (entry.rows[index - 1].x === entry.rows[index].x) {
+        throw new Error(
+          `Horizon group ${JSON.stringify(entry.group ?? null)} has duplicate x value ${entry.rows[index].x}.`
+        );
+      }
+    }
+  }
+  return groups;
+}
+
+function splitSegments(rows, baseline) {
+  const segments = [];
+  let current = [];
+  const flush = () => {
+    if (current.length > 0) segments.push(current);
+    current = [];
+  };
+  for (const row of rows) {
+    if (row.missing) {
+      flush();
+      continue;
+    }
+    current.push({ ...row, signed: row.y - baseline, interpolated: false });
+  }
+  flush();
+  return segments;
+}
+
+function insertCrossings(points, baseline) {
+  if (points.length < 2) return points.map(point => ({ ...point }));
+  const output = [{ ...points[0] }];
+  for (let index = 1; index < points.length; index += 1) {
+    const left = points[index - 1];
+    const right = points[index];
+    if (left.signed * right.signed < 0) {
+      const fraction = (baseline - left.y) / (right.y - left.y);
+      output.push({
+        sourceRowIndex: undefined,
+        x: left.x + (right.x - left.x) * fraction,
+        y: baseline,
+        missing: false,
+        signed: 0,
+        interpolated: true,
+        leftSourceRowIndex: left.sourceRowIndex,
+        rightSourceRowIndex: right.sourceRowIndex,
+        fraction
+      });
+    }
+    output.push({ ...right });
+  }
+  return output;
+}
+
+function pointSign(value) {
+  return value > 0 ? "positive" : value < 0 ? "negative" : "zero";
+}
+
+function runsForSign(points, desired) {
+  const runs = [];
+  let current = [];
+  let pendingZeros = [];
+  const flush = () => {
+    if (current.some(point => pointSign(point.signed) === desired)) {
+      runs.push(current);
+    }
+    current = [];
+  };
+  for (const point of points) {
+    const sign = pointSign(point.signed);
+    if (sign === desired) {
+      if (current.length === 0 && pendingZeros.length > 0) {
+        current.push(...pendingZeros);
+      }
+      current.push(point);
+      pendingZeros = [];
+    } else if (sign === "zero") {
+      if (current.length > 0) {
+        current.push(point);
+        flush();
+      }
+      pendingZeros = [point];
+    } else {
+      flush();
+      pendingZeros = [];
+    }
+  }
+  flush();
+  return runs;
+}
+
+function maximumMagnitude(group) {
+  return Math.max(
+    0,
+    ...group.segments.flatMap(segment =>
+      segment.map(point => Math.abs(point.signed))
+    )
+  );
+}
+
+function resolvedExtents(groups, transform) {
+  if (transform.extent !== "auto") return groups.map(() => transform.extent);
+  if (transform.resolve === "shared") {
+    const shared = Math.max(0, ...groups.map(maximumMagnitude));
+    return groups.map(() => shared);
+  }
+  return groups.map(maximumMagnitude);
+}
+
+function seriesForGroup(group, extent, transform) {
+  if (extent === 0) return [];
+  const bandHeight = extent / transform.bands;
+  const output = [];
+  for (const sign of ["negative", "positive"]) {
+    const runs = [];
+    let segmentIndex = 0;
+    for (const source of group.segments) {
+      for (const points of runsForSign(source, sign)) {
+        runs.push({ points, segmentIndex });
+        segmentIndex += 1;
+      }
+    }
+    for (let bandIndex = 0; bandIndex < transform.bands; bandIndex += 1) {
+      for (const run of runs) {
+        const points = run.points.map(point => {
+          const rawMagnitude = Math.abs(point.signed);
+          if (rawMagnitude > extent && transform.overflow === "error") {
+            throw new RangeError(
+              `Horizon magnitude ${rawMagnitude} exceeds extent ${extent}.`
+            );
+          }
+          const magnitude = Math.min(rawMagnitude, extent);
+          const amplitude = Math.min(
+            bandHeight,
+            Math.max(0, magnitude - bandIndex * bandHeight)
+          );
+          return {
+            ...point,
+            magnitude,
+            rawMagnitude,
+            amplitude,
+            fraction: amplitude / bandHeight,
+            overflowed: rawMagnitude > extent
+          };
+        });
+        if (points.some(point => point.amplitude > 0)) {
+          const groupIdentity = transform.groupBy === undefined
+            ? null
+            : group.group;
+          output.push({
+            group: group.group,
+            groupIndex: group.groupIndex,
+            sign,
+            bandIndex,
+            segmentIndex: run.segmentIndex,
+            seriesKey: JSON.stringify([
+              groupIdentity,
+              sign,
+              bandIndex,
+              run.segmentIndex
+            ]),
+            colorKey: `${sign}:${bandIndex}`,
+            bandHeight,
+            points
+          });
+        }
+      }
+    }
+  }
+  return output;
+}
+
+function generatedRows(series, transform) {
+  return series.flatMap(item => item.points.map(point => ({
+    ...(transform.groupBy === undefined
+      ? {}
+      : { [transform.groupBy]: item.group }),
+    [transform.as.x]: point.x,
+    [transform.as.lower]: 0,
+    [transform.as.upper]: point.fraction,
+    [transform.as.group]: item.seriesKey,
+    [transform.as.color]: item.colorKey,
+    [transform.as.sign]: item.sign,
+    [transform.as.band]: item.bandIndex,
+    [transform.as.segment]: item.segmentIndex
+  })));
+}
+
+export function deriveHorizon(rows, requested) {
+  if (!Array.isArray(rows)) {
+    throw new TypeError("Horizon values must be an array.");
+  }
+  if (rows.length === 0) {
+    throw new Error("Horizon requires at least one source row.");
+  }
+  const transform = validateHorizonTransform(requested);
+  const grouped = groupRows(rows, transform).map(group => ({
+    ...group,
+    segments: splitSegments(group.rows, transform.baseline).map(segment =>
+      insertCrossings(segment, transform.baseline)
+    )
+  }));
+  if (!grouped.some(group => group.rows.some(row => !row.missing))) {
+    throw new Error("Horizon requires at least one finite y value.");
+  }
+  const extents = resolvedExtents(grouped, transform);
+  const groups = grouped.map((group, index) => ({
+    ...(transform.groupBy === undefined ? {} : { group: group.group }),
+    extent: extents[index],
+    bandHeight: extents[index] / transform.bands
+  }));
+  const series = grouped.flatMap((group, index) =>
+    seriesForGroup(group, extents[index], transform)
+  );
+  return cloneAndFreeze({
+    transform: requestedHorizonTransform(transform),
+    resolved: { extents: groups },
+    groups,
+    series,
+    values: generatedRows(series, transform)
+  });
+}

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
+  });
+}