ggaction 0.0.1

package/src/grammar/scales/definition.js

@@ -0,0 +1,153 @@
+import { validateContinuousColorInterpolation } from "./color.js";
+import { isTransformedScaleType } from "./mapping.js";
+import {
+  normalizeTransformParameters,
+  validateTransformedDomain
+} from "./transformed.js";
+import {
+  isContinuousColorScaleType,
+  validateScalePropertyForType
+} from "./types.js";
+
+const BOOLEAN_PROPERTIES = Object.freeze([
+  "nice", "zero", "clamp", "reverse"
+]);
+const TYPE_PARAMETERS = Object.freeze(["base", "exponent", "constant"]);
+
+function retainedValue(previous, patch, defaults, property, typeChanged) {
+  if (Object.hasOwn(patch, property)) return patch[property];
+  if (!typeChanged && Object.hasOwn(previous, property)) {
+    return previous[property];
+  }
+  return defaults[property];
+}
+
+function validateBandParameters(definition, previous, patch, defaults, typeChanged) {
+  const paddingInner = retainedValue(
+    previous, patch, defaults, "paddingInner", typeChanged
+  ) ?? 0;
+  const paddingOuter = retainedValue(
+    previous, patch, defaults, "paddingOuter", typeChanged
+  ) ?? 0;
+  const align = retainedValue(previous, patch, defaults, "align", typeChanged) ?? 0.5;
+  if (!Number.isFinite(paddingInner) || paddingInner < 0 || paddingInner >= 1) {
+    throw new RangeError(
+      "Scale paddingInner must be from 0 (inclusive) to 1 (exclusive)."
+    );
+  }
+  if (!Number.isFinite(paddingOuter) || paddingOuter < 0) {
+    throw new RangeError("Scale paddingOuter must be non-negative and finite.");
+  }
+  if (!Number.isFinite(align) || align < 0 || align > 1) {
+    throw new RangeError("Scale align must be between 0 and 1.");
+  }
+  Object.assign(definition, { paddingInner, paddingOuter, align });
+}
+
+function validatePointParameters(definition, previous, patch, defaults, typeChanged) {
+  const padding = retainedValue(
+    previous, patch, defaults, "padding", typeChanged
+  ) ?? 0.5;
+  const align = retainedValue(previous, patch, defaults, "align", typeChanged) ?? 0.5;
+  if (!Number.isFinite(padding) || padding < 0) {
+    throw new RangeError("Scale padding must be non-negative and finite.");
+  }
+  if (!Number.isFinite(align) || align < 0 || align > 1) {
+    throw new RangeError("Scale align must be between 0 and 1.");
+  }
+  Object.assign(definition, { padding, align });
+}
+
+export function normalizeScaleDefinition({
+  type,
+  previous = {},
+  patch = {},
+  defaults = {},
+  retainCoreOnTypeChange = false,
+  retainCompatibleOnTypeChange = false,
+  validateDomain,
+  validateRange
+}) {
+  const typeChanged = previous.type !== undefined && previous.type !== type;
+  const rawDomain = Object.hasOwn(patch, "domain")
+    ? patch.domain
+    : (!typeChanged || retainCoreOnTypeChange) && Object.hasOwn(previous, "domain")
+      ? previous.domain
+      : defaults.domain ?? "auto";
+  const rawRange = Object.hasOwn(patch, "range")
+    ? patch.range
+    : (!typeChanged || retainCoreOnTypeChange) && Object.hasOwn(previous, "range")
+      ? previous.range
+      : defaults.range ?? "auto";
+  const definition = {
+    type,
+    domain: validateDomain(type, rawDomain),
+    range: validateRange(type, rawRange)
+  };
+
+  for (const property of BOOLEAN_PROPERTIES) {
+    let value = retainedValue(previous, patch, defaults, property, typeChanged);
+    if (
+      value === undefined &&
+      typeChanged &&
+      retainCompatibleOnTypeChange &&
+      Object.hasOwn(previous, property)
+    ) {
+      try {
+        validateScalePropertyForType(type, property);
+        value = previous[property];
+      } catch {
+        value = undefined;
+      }
+    }
+    if (value === undefined) continue;
+    if (typeof value !== "boolean") {
+      throw new TypeError(`Scale ${property} must be a boolean.`);
+    }
+    validateScalePropertyForType(type, property);
+    definition[property] = value;
+  }
+
+  const requested = Object.fromEntries(TYPE_PARAMETERS.flatMap(property => {
+    const value = retainedValue(previous, patch, defaults, property, typeChanged);
+    return value === undefined ? [] : [[property, value]];
+  }));
+  if (isTransformedScaleType(type)) {
+    const parameters = normalizeTransformParameters(type, requested);
+    if (type === "log") definition.base = parameters.base;
+    if (type === "pow") definition.exponent = parameters.exponent;
+    if (type === "symlog") definition.constant = parameters.constant;
+    if (definition.domain !== "auto") {
+      validateTransformedDomain(type, definition.domain, parameters);
+    }
+  } else {
+    for (const property of Object.keys(requested)) {
+      validateScalePropertyForType(type, property);
+    }
+  }
+
+  const interpolate = retainedValue(
+    previous, patch, defaults, "interpolate", typeChanged
+  );
+  if (isContinuousColorScaleType(type)) {
+    definition.interpolate = validateContinuousColorInterpolation(
+      interpolate ?? "rgb"
+    );
+  } else if (interpolate !== undefined) {
+    throw new Error(`Scale type "${type}" does not support interpolate.`);
+  }
+
+  if (type === "band") {
+    validateBandParameters(definition, previous, patch, defaults, typeChanged);
+  } else if (type === "point") {
+    validatePointParameters(definition, previous, patch, defaults, typeChanged);
+  } else {
+    for (const property of ["paddingInner", "paddingOuter", "padding", "align"]) {
+      if (Object.hasOwn(patch, property)) {
+        validateScalePropertyForType(type, property);
+      }
+    }
+  }
+
+  return definition;
+}

package/src/grammar/scales/discretized.js

@@ -0,0 +1,159 @@
+import { cloneAndFreeze } from "../../core/immutable.js";
+import { resolveColorRange, validateColorRange } from "./appearance.js";
+import { SCALE_ROLES, validateScaleTypeForRole } from "./types.js";
+
+export const DISCRETIZED_COLOR_SCALE_TYPES = cloneAndFreeze([
+  "quantize",
+  "quantile",
+  "threshold"
+]);
+
+function finiteValues(values, label) {
+  if (!Array.isArray(values) || values.length === 0 || !values.every(Number.isFinite)) {
+    throw new TypeError(`${label} must contain finite numbers.`);
+  }
+  return values;
+}
+
+function ascending(values, label) {
+  finiteValues(values, label);
+  if (values.some((value, index) => index > 0 && value <= values[index - 1])) {
+    throw new RangeError(`${label} must be strictly increasing.`);
+  }
+  return values;
+}
+
+function nondecreasing(values, label) {
+  finiteValues(values, label);
+  if (values.some((value, index) => index > 0 && value < values[index - 1])) {
+    throw new RangeError(`${label} must be nondecreasing.`);
+  }
+  return values;
+}
+
+function quantile(sorted, probability) {
+  const position = (sorted.length - 1) * probability;
+  const lower = Math.floor(position);
+  const upper = Math.ceil(position);
+  return sorted[lower] + (sorted[upper] - sorted[lower]) * (position - lower);
+}
+
+export function validateDiscretizedColorDomain(type, domain) {
+  validateScaleTypeForRole(type, SCALE_ROLES.discretizedColor);
+  if (domain === "auto") {
+    if (type === "threshold") {
+      throw new Error("Threshold color scale requires an explicit domain.");
+    }
+    return domain;
+  }
+  if (!Array.isArray(domain)) {
+    throw new TypeError("Discretized color domain must be an array or auto.");
+  }
+  if (type === "quantize") {
+    if (domain.length !== 2 || !domain.every(Number.isFinite) || domain[0] >= domain[1]) {
+      throw new RangeError("Quantize color domain must be an increasing pair.");
+    }
+  } else if (type === "quantile") {
+    finiteValues(domain, "Quantile color domain");
+  } else {
+    ascending(domain, "Threshold color domain");
+  }
+  return cloneAndFreeze(domain);
+}
+
+export function validateDiscretizedColorRange(range) {
+  const validated = validateColorRange(range);
+  if (validated === "auto") return validated;
+  if (Array.isArray(validated) && validated.length < 2) {
+    throw new RangeError("Discretized color range requires at least two colors.");
+  }
+  return validated;
+}
+
+export function resolveDiscretizedColorScale({ type, domain, range, values }) {
+  validateScaleTypeForRole(type, SCALE_ROLES.discretizedColor);
+  finiteValues(values, "Discretized color values");
+  const requestedDomain = validateDiscretizedColorDomain(type, domain);
+  const sample = [...values].sort((left, right) => left - right);
+  const validatedRange = validateDiscretizedColorRange(range);
+  const colorCount = type === "threshold" && requestedDomain !== "auto"
+    ? requestedDomain.length + 1
+    : Array.isArray(range) ? range.length : 5;
+  const colors = resolveColorRange(
+    validatedRange === "auto" ? { palette: "viridis" } : validatedRange,
+    colorCount
+  );
+  if (colors.length < 2) {
+    throw new RangeError("Discretized color range requires at least two colors.");
+  }
+  let resolvedDomain;
+  let thresholds;
+  if (type === "quantize") {
+    resolvedDomain = requestedDomain === "auto"
+      ? [sample[0], sample.at(-1)]
+      : [...requestedDomain];
+    if (resolvedDomain[0] === resolvedDomain[1]) {
+      throw new RangeError("Quantize color scale requires a non-zero domain span.");
+    }
+    thresholds = Array.from(
+      { length: colors.length - 1 },
+      (_, index) => resolvedDomain[0] + (index + 1) / colors.length *
+        (resolvedDomain[1] - resolvedDomain[0])
+    );
+  } else if (type === "quantile") {
+    const source = requestedDomain === "auto"
+      ? sample
+      : [...requestedDomain].sort((left, right) => left - right);
+    resolvedDomain = source;
+    thresholds = Array.from(
+      { length: colors.length - 1 },
+      (_, index) => quantile(source, (index + 1) / colors.length)
+    );
+  } else {
+    resolvedDomain = [...requestedDomain];
+    thresholds = [...requestedDomain];
+    if (colors.length !== thresholds.length + 1) {
+      throw new RangeError(
+        "Threshold color range must contain exactly one more color than its domain."
+      );
+    }
+  }
+  return cloneAndFreeze({
+    type,
+    domain: resolvedDomain,
+    thresholds,
+    range: colors
+  });
+}
+
+export function discretizedColorIndex(value, thresholds) {
+  if (!Number.isFinite(value)) {
+    throw new TypeError("Discretized color values must be finite numbers.");
+  }
+  let index = 0;
+  while (index < thresholds.length && value >= thresholds[index]) index += 1;
+  return index;
+}
+
+export function mapDiscretizedColors(values, scale) {
+  const hasUnknown = Object.hasOwn(scale, "unknown");
+  return cloneAndFreeze(values.map(value => {
+    if (!Number.isFinite(value) && hasUnknown) return scale.unknown;
+    return scale.range[discretizedColorIndex(value, scale.thresholds)];
+  }));
+}
+
+function formatBoundary(value) {
+  return Number.isInteger(value) ? String(value) : value.toFixed(1);
+}
+
+export function formatDiscretizedIntervals(thresholds) {
+  nondecreasing(thresholds, "Discretized color thresholds");
+  return cloneAndFreeze([
+    `< ${formatBoundary(thresholds[0])}`,
+    ...thresholds.slice(0, -1).map((value, index) =>
+      `${formatBoundary(value)}–${formatBoundary(thresholds[index + 1])}`
+    ),
+    `≥ ${formatBoundary(thresholds.at(-1))}`
+  ]);
+}

package/src/grammar/scales/fields.js

@@ -0,0 +1,133 @@
+import { cloneAndFreeze } from "../../core/immutable.js";
+
+export function isNominalValue(value) {
+  return (
+    typeof value === "string" ||
+    typeof value === "boolean" ||
+    (typeof value === "number" && Number.isFinite(value))
+  );
+}
+
+export function validateFieldType(fieldType) {
+  if (!["quantitative", "ordinal", "temporal"].includes(fieldType)) {
+    throw new Error(`Unsupported field type "${fieldType}".`);
+  }
+  return fieldType;
+}
+
+export function validateNominalFieldType(fieldType) {
+  if (fieldType !== "nominal") {
+    throw new Error(`Unsupported color field type "${fieldType}".`);
+  }
+  return fieldType;
+}
+
+export function validateSemanticFieldType(fieldType) {
+  if (!["quantitative", "nominal", "ordinal", "temporal"].includes(fieldType)) {
+    throw new Error(`Unsupported semantic field type "${fieldType}".`);
+  }
+  return fieldType;
+}
+
+function validateField(field) {
+  if (typeof field !== "string" || field.length === 0) {
+    throw new TypeError("Encoding field must be a non-empty string.");
+  }
+}
+
+export function readQuantitativeField(rows, field) {
+  validateField(field);
+  return cloneAndFreeze(rows.map((row, index) => {
+    if (!Object.hasOwn(row, field) || !Number.isFinite(row[field])) {
+      throw new TypeError(
+        `Field "${field}" must contain a finite number at row ${index}.`
+      );
+    }
+    return row[field];
+  }));
+}
+
+function utcDate(year, month = 1, day = 1) {
+  const timestamp = Date.UTC(year, month - 1, day);
+  const date = new Date(timestamp);
+  return date.getUTCFullYear() === year &&
+    date.getUTCMonth() === month - 1 &&
+    date.getUTCDate() === day
+    ? timestamp
+    : undefined;
+}
+
+export function normalizeTemporalValue(value, field = "value", index = 0) {
+  let timestamp;
+  if (typeof value === "number") {
+    timestamp = Number.isInteger(value) && value >= 1000 && value <= 9999
+      ? utcDate(value)
+      : value;
+  } else if (typeof value === "string") {
+    const year = /^(\d{4})$/.exec(value);
+    const date = /^(\d{4})[-/](\d{2})[-/](\d{2})$/.exec(value);
+    timestamp = year !== null
+      ? utcDate(Number(year[1]))
+      : date !== null
+        ? utcDate(Number(date[1]), Number(date[2]), Number(date[3]))
+        : Date.parse(value);
+  }
+  if (!Number.isFinite(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}.`
+    );
+  }
+  return timestamp;
+}
+
+export function readTemporalField(rows, field) {
+  validateField(field);
+  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);
+  }));
+}
+
+export function readNominalField(rows, field) {
+  validateField(field);
+  return cloneAndFreeze(rows.map((row, index) => {
+    if (!Object.hasOwn(row, field) || !isNominalValue(row[field])) {
+      throw new TypeError(
+        `Field "${field}" must contain a nominal value at row ${index}.`
+      );
+    }
+    return row[field];
+  }));
+}
+
+export function readScaleField(rows, field, fieldType, { allowUnknown = false } = {}) {
+  validateSemanticFieldType(fieldType);
+  if (!allowUnknown) {
+    if (fieldType === "temporal") return readTemporalField(rows, field);
+    if (["nominal", "ordinal"].includes(fieldType)) {
+      return readNominalField(rows, field);
+    }
+    return readQuantitativeField(rows, field);
+  }
+  validateField(field);
+  return cloneAndFreeze(rows.map((row, index) => {
+    if (!Object.hasOwn(row, field)) return undefined;
+    const value = row[field];
+    if (fieldType === "quantitative") {
+      return Number.isFinite(value) ? value : undefined;
+    }
+    if (["nominal", "ordinal"].includes(fieldType)) {
+      return isNominalValue(value) ? value : undefined;
+    }
+    try {
+      return normalizeTemporalValue(value, field, index);
+    } catch {
+      return undefined;
+    }
+  }));
+}

package/src/grammar/scales/index.js

@@ -0,0 +1,12 @@
+export * from "./appearance.js";
+export * from "./color.js";
+export * from "./continuous.js";
+export * from "./discretized.js";
+export * from "./definition.js";
+export * from "./fields.js";
+export * from "./mapping.js";
+export * from "./ordinal.js";
+export * from "./policies.js";
+export * from "./transformed.js";
+export * from "./types.js";
+export * from "./validation.js";

package/src/grammar/scales/mapping.js

@@ -0,0 +1,27 @@
+import { mapLinearValues } from "./continuous.js";
+import { mapTransformedValues } from "./transformed.js";
+import { SCALE_ROLES, validateScaleTypeForRole } from "./types.js";
+
+const TRANSFORMED_TYPES = new Set(["log", "pow", "sqrt", "symlog"]);
+
+export function isTransformedScaleType(type) {
+  return TRANSFORMED_TYPES.has(type);
+}
+
+export function mapContinuousScaleValues(values, scale) {
+  if (isTransformedScaleType(scale?.type)) {
+    validateScaleTypeForRole(scale.type, SCALE_ROLES.quantitativePosition);
+    return mapTransformedValues(values, scale.domain, scale.range, {
+      type: scale.type,
+      clamp: scale.clamp ?? false,
+      ...(Object.hasOwn(scale, "unknown") ? { unknown: scale.unknown } : {}),
+      ...(scale.type === "log" ? { base: scale.base } : {}),
+      ...(scale.type === "pow" ? { exponent: scale.exponent } : {}),
+      ...(scale.type === "symlog" ? { constant: scale.constant } : {})
+    });
+  }
+  return mapLinearValues(values, scale.domain, scale.range, {
+    clamp: scale.clamp ?? false,
+    ...(Object.hasOwn(scale, "unknown") ? { unknown: scale.unknown } : {})
+  });
+}