ggaction 0.0.2 → 0.0.3

package/src/grammar/lineSeries.js

@@ -64,8 +64,13 @@ function readSeriesFields(rows, layer) {
     const encoding = layer.encoding?.[channel];
 
     if (encoding?.field === undefined) continue;
-    if (encoding.fieldType !== "nominal") {
-      throw new Error(`Line ${channel} encoding on mark "${layer.id}" must be nominal.`);
+    const categorical = channel === "color"
+      ? ["nominal", "ordinal"].includes(encoding.fieldType)
+      : encoding.fieldType === "nominal";
+    if (!categorical) {
+      throw new Error(
+        `Line ${channel} encoding on mark "${layer.id}" must be categorical.`
+      );
     }
 
     if (!values.has(encoding.field)) {
@@ -81,7 +86,7 @@ function groupKey(values) {
   return JSON.stringify(values);
 }
 
-export function deriveLineSeries(rows, layer) {
+function deriveCartesianLineSeries(rows, layer) {
   const { x, y, isAggregate, directTemporal } = requireLineEncoding(layer);
   if (isAggregate) {
     validateAggregateFieldValues(rows, y.field, y.fieldType);
@@ -195,3 +200,106 @@ export function deriveLineSeries(rows, layer) {
     series
   });
 }
+
+function requirePolarLineEncoding(layer) {
+  if (layer?.mark?.type !== "line") {
+    throw new Error("Polar line series derivation requires a semantic line mark.");
+  }
+  const theta = layer.encoding?.theta;
+  const radius = layer.encoding?.radius;
+  if (theta === undefined || radius === undefined) {
+    throw new Error(
+      `Polar line mark "${layer.id}" requires theta and radius encodings.`
+    );
+  }
+  if (!["quantitative", "temporal", "ordinal", "nominal"].includes(
+    theta.fieldType
+  )) {
+    throw new Error(
+      `Polar line mark "${layer.id}" has unsupported theta field type.`
+    );
+  }
+  if (radius.fieldType !== "quantitative") {
+    throw new Error(
+      `Polar line mark "${layer.id}" requires a quantitative radius encoding.`
+    );
+  }
+  return { theta, radius };
+}
+
+function readThetaValues(rows, encoding) {
+  if (["nominal", "ordinal"].includes(encoding.fieldType)) {
+    return readNominalField(rows, encoding.field);
+  }
+  return encoding.fieldType === "temporal"
+    ? readTemporalField(rows, encoding.field)
+    : readQuantitativeField(rows, encoding.field);
+}
+
+function thetaOrder(values, fieldType, domain) {
+  if (!["nominal", "ordinal"].includes(fieldType)) return values;
+  const order = domain ?? [...new Set(values)];
+  const indices = new Map(order.map((value, index) => [value, index]));
+  for (const value of values) {
+    if (!indices.has(value)) {
+      throw new Error(`Polar line theta domain does not contain "${value}".`);
+    }
+  }
+  return values.map(value => indices.get(value));
+}
+
+export function derivePolarLineSeries(rows, layer, { thetaDomain } = {}) {
+  const { theta, radius } = requirePolarLineEncoding(layer);
+  const thetaValues = readThetaValues(rows, theta);
+  const radiusValues = readQuantitativeField(rows, radius.field);
+  const sortValues = thetaOrder(thetaValues, theta.fieldType, thetaDomain);
+  const seriesFields = readSeriesFields(rows, layer);
+  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: []
+    };
+    series.values.push({
+      theta: thetaValues[index],
+      radius: radiusValues[index],
+      order: sortValues[index],
+      sourceIndex: index
+    });
+    groups.set(key, series);
+  }
+
+  const series = [...groups.values()].flatMap(item => {
+    const values = item.values.sort(
+      (left, right) => left.order - right.order ||
+        left.sourceIndex - right.sourceIndex
+    );
+    return values.length < 2 ? [] : [{ key: item.key, values }];
+  });
+  if (series.length === 0) {
+    throw new Error(
+      `Polar line series on mark "${layer.id}" requires at least two points.`
+    );
+  }
+  return cloneAndFreeze({
+    thetaFieldType: theta.fieldType,
+    thetaValues: series.flatMap(item => item.values.map(value => value.theta)),
+    radiusValues: series.flatMap(item => item.values.map(value => value.radius)),
+    series
+  });
+}
+
+export function deriveLineSeries(rows, layer, options) {
+  const polar = layer?.encoding?.theta !== undefined ||
+    layer?.encoding?.radius !== undefined;
+  return polar
+    ? derivePolarLineSeries(rows, layer, options)
+    : deriveCartesianLineSeries(rows, layer);
+}

package/src/grammar/polar.js

@@ -0,0 +1,102 @@
+import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
+import { validatePair } from "./scales/validation.js";
+
+function validateBounds(bounds) {
+  if (
+    !isPlainObject(bounds) ||
+    ![bounds.x, bounds.y, bounds.width, bounds.height].every(Number.isFinite) ||
+    bounds.width < 0 ||
+    bounds.height < 0
+  ) {
+    throw new TypeError(
+      "Polar geometry requires finite, non-negative graphical bounds."
+    );
+  }
+  return bounds;
+}
+
+export function resolvePolarFrame(bounds) {
+  validateBounds(bounds);
+  return cloneAndFreeze({
+    centerX: bounds.x + bounds.width / 2,
+    centerY: bounds.y + bounds.height / 2,
+    availableRadius: Math.min(bounds.width, bounds.height) / 2
+  });
+}
+
+export function validateThetaRange(range) {
+  if (range === "auto") return range;
+  const validated = validatePair(range, "Theta scale range");
+  if (Math.abs(validated[1] - validated[0]) > 360) {
+    throw new RangeError("Theta scale range span must not exceed 360 degrees.");
+  }
+  return validated;
+}
+
+export function validateRadialRange(range, availableRadius) {
+  if (range === "auto") return range;
+  const validated = validatePair(range, "Radius scale range");
+  if (validated.some(value => value < 0)) {
+    throw new RangeError("Radius scale range values must be non-negative.");
+  }
+  if (
+    availableRadius !== undefined &&
+    validated.some(value => value > availableRadius)
+  ) {
+    throw new RangeError(
+      `Radius scale range must fit within the available radius ${availableRadius}.`
+    );
+  }
+  return validated;
+}
+
+export function resolvePolarScaleRange(range, channel, bounds) {
+  if (channel === "theta") {
+    return range === "auto"
+      ? cloneAndFreeze([0, 360])
+      : validateThetaRange(range);
+  }
+  if (channel !== "radius") {
+    throw new Error(`Unknown Polar position channel "${channel}".`);
+  }
+  const frame = resolvePolarFrame(bounds);
+  return range === "auto"
+    ? cloneAndFreeze([0, frame.availableRadius])
+    : validateRadialRange(range, frame.availableRadius);
+}
+
+export function polarDirection(theta) {
+  if (!Number.isFinite(theta)) {
+    throw new TypeError("Polar theta must be a finite number of degrees.");
+  }
+  const angle = theta * Math.PI / 180;
+  return cloneAndFreeze({
+    x: Math.sin(angle),
+    y: -Math.cos(angle)
+  });
+}
+
+export function polarToCartesian({ theta, radius, frame }) {
+  const direction = polarDirection(theta);
+  if (!Number.isFinite(radius) || radius < 0) {
+    throw new TypeError("Polar radius must be a non-negative finite number.");
+  }
+  const resolvedFrame = frame?.availableRadius === undefined
+    ? resolvePolarFrame(frame)
+    : frame;
+  if (
+    ![resolvedFrame.centerX, resolvedFrame.centerY,
+      resolvedFrame.availableRadius].every(Number.isFinite)
+  ) {
+    throw new TypeError("Polar frame must contain finite geometry.");
+  }
+  if (radius > resolvedFrame.availableRadius) {
+    throw new RangeError(
+      `Polar radius ${radius} exceeds the available radius ${resolvedFrame.availableRadius}.`
+    );
+  }
+  return cloneAndFreeze({
+    x: resolvedFrame.centerX + radius * direction.x,
+    y: resolvedFrame.centerY + radius * direction.y
+  });
+}

package/src/grammar/polarGuides.js

@@ -0,0 +1,243 @@
+import { freezeOwned } from "../core/immutable.js";
+import { polarDirection } from "./polar.js";
+import { buildPolarCircleCommands } from "./polarPaths.js";
+
+export { buildPolarCircleCommands } from "./polarPaths.js";
+
+function validateFrame(frame) {
+  if (
+    frame === null ||
+    typeof frame !== "object" ||
+    ![frame.centerX, frame.centerY, frame.availableRadius].every(Number.isFinite) ||
+    frame.availableRadius < 0
+  ) {
+    throw new TypeError(
+      "Polar guide frame requires finite centerX, centerY, and non-negative availableRadius."
+    );
+  }
+  return frame;
+}
+
+function validateFiniteValues(values, label) {
+  if (!Array.isArray(values) || !values.every(Number.isFinite)) {
+    throw new TypeError(`${label} must be an array of finite numbers.`);
+  }
+  return values;
+}
+
+function validateNonNegative(value, label) {
+  if (!Number.isFinite(value) || value < 0) {
+    throw new RangeError(`${label} must be a non-negative finite number.`);
+  }
+  return value;
+}
+
+function own(value) {
+  return freezeOwned(value);
+}
+
+function pointAt(frame, theta, radius) {
+  validateNonNegative(radius, "Polar guide radius");
+  const direction = polarDirection(theta);
+  return {
+    x: frame.centerX + direction.x * radius,
+    y: frame.centerY + direction.y * radius
+  };
+}
+
+export function resolveThetaSpokes({ frame, angles }) {
+  validateFrame(frame);
+  validateFiniteValues(angles, "Polar spoke angles");
+  const end = angles.map(theta => pointAt(frame, theta, frame.availableRadius));
+  return own({
+    x1: angles.map(() => frame.centerX),
+    y1: angles.map(() => frame.centerY),
+    x2: end.map(point => point.x),
+    y2: end.map(point => point.y)
+  });
+}
+
+export function resolveRadialCircles({ frame, radii }) {
+  validateFrame(frame);
+  validateFiniteValues(radii, "Polar grid radii");
+  if (radii.some(radius => radius < 0 || radius > frame.availableRadius)) {
+    throw new RangeError("Polar grid radii must be inside the Polar frame.");
+  }
+  const visibleRadii = radii.filter(radius => radius > 0);
+  return own({
+    radii: visibleRadii,
+    commands: visibleRadii.map(radius => buildPolarCircleCommands(frame, radius))
+  });
+}
+
+export function resolveThetaAxisTicks({ frame, angles, length }) {
+  validateFrame(frame);
+  validateFiniteValues(angles, "Theta-axis angles");
+  validateNonNegative(length, "Theta-axis tick length");
+  const start = angles.map(theta => pointAt(frame, theta, frame.availableRadius));
+  const end = angles.map(theta => pointAt(
+    frame,
+    theta,
+    frame.availableRadius + length
+  ));
+  return own({
+    x1: start.map(point => point.x),
+    y1: start.map(point => point.y),
+    x2: end.map(point => point.x),
+    y2: end.map(point => point.y)
+  });
+}
+
+function perimeterAlignment(theta) {
+  const radians = theta * Math.PI / 180;
+  const horizontal = Math.sin(radians);
+  const vertical = Math.cos(radians);
+  return {
+    textAlign: horizontal > 0.25
+      ? "left"
+      : horizontal < -0.25
+        ? "right"
+        : "center",
+    textBaseline: vertical > 0.25
+      ? "bottom"
+      : vertical < -0.25
+        ? "top"
+        : "middle"
+  };
+}
+
+export function resolveThetaAxisLabels({ frame, angles, offset }) {
+  validateFrame(frame);
+  validateFiniteValues(angles, "Theta-axis label angles");
+  validateNonNegative(offset, "Theta-axis label offset");
+  const points = angles.map(theta => pointAt(
+    frame,
+    theta,
+    frame.availableRadius + offset
+  ));
+  const alignment = angles.map(perimeterAlignment);
+  return own({
+    x: points.map(point => point.x),
+    y: points.map(point => point.y),
+    textAlign: alignment.map(value => value.textAlign),
+    textBaseline: alignment.map(value => value.textBaseline)
+  });
+}
+
+function radialVectors(angle) {
+  let direction;
+  try {
+    direction = polarDirection(angle);
+  } catch {
+    throw new TypeError("Radial-axis angle must be finite degrees.");
+  }
+  return {
+    direction,
+    normal: { x: -direction.y, y: direction.x }
+  };
+}
+
+export function resolveRadialAxisLine({ frame, angle, startRadius = 0 }) {
+  validateFrame(frame);
+  validateNonNegative(startRadius, "Radial-axis start radius");
+  if (startRadius > frame.availableRadius) {
+    throw new RangeError("Radial-axis start radius must be inside the Polar frame.");
+  }
+  const { direction } = radialVectors(angle);
+  return own({
+    x1: frame.centerX + direction.x * startRadius,
+    y1: frame.centerY + direction.y * startRadius,
+    x2: frame.centerX + direction.x * frame.availableRadius,
+    y2: frame.centerY + direction.y * frame.availableRadius
+  });
+}
+
+export function resolveRadialAxisTicks({ frame, angle, radii, length }) {
+  validateFrame(frame);
+  validateFiniteValues(radii, "Radial-axis tick radii");
+  validateNonNegative(length, "Radial-axis tick length");
+  if (radii.some(radius => radius < 0 || radius > frame.availableRadius)) {
+    throw new RangeError("Radial-axis tick radii must be inside the Polar frame.");
+  }
+  const { direction, normal } = radialVectors(angle);
+  const half = length / 2;
+  const centers = radii.map(radius => ({
+    x: frame.centerX + direction.x * radius,
+    y: frame.centerY + direction.y * radius
+  }));
+  return own({
+    x1: centers.map(point => point.x - normal.x * half),
+    y1: centers.map(point => point.y - normal.y * half),
+    x2: centers.map(point => point.x + normal.x * half),
+    y2: centers.map(point => point.y + normal.y * half)
+  });
+}
+
+export function resolveRadialAxisLabels({ frame, angle, radii, offset }) {
+  validateFrame(frame);
+  validateFiniteValues(radii, "Radial-axis label radii");
+  validateNonNegative(offset, "Radial-axis label offset");
+  if (radii.some(radius => radius < 0 || radius > frame.availableRadius)) {
+    throw new RangeError("Radial-axis label radii must be inside the Polar frame.");
+  }
+  const { direction, normal } = radialVectors(angle);
+  return own({
+    x: radii.map(radius =>
+      frame.centerX + direction.x * radius - normal.x * offset
+    ),
+    y: radii.map(radius =>
+      frame.centerY + direction.y * radius - normal.y * offset
+    ),
+    textAlign: radii.map(() => "center"),
+    textBaseline: radii.map(() => "bottom")
+  });
+}
+
+export function resolveRadialAxisTitle({
+  frame,
+  angle,
+  radius = frame.availableRadius / 2,
+  offset,
+  position = "inside"
+}) {
+  validateFrame(frame);
+  validateNonNegative(offset, "Radial-axis title offset");
+  if (!["inside", "outside"].includes(position)) {
+    throw new Error(`Unknown radial-axis title position "${position}".`);
+  }
+  if (position === "outside") {
+    const { direction } = radialVectors(angle);
+    return own({
+      x: frame.centerX + direction.x * (frame.availableRadius + offset),
+      y: frame.centerY + direction.y * (frame.availableRadius + offset),
+      textAlign: direction.x > 0.25
+        ? "left"
+        : direction.x < -0.25 ? "right" : "center",
+      textBaseline: direction.y > 0.25
+        ? "top"
+        : direction.y < -0.25 ? "bottom" : "middle"
+    });
+  }
+  validateNonNegative(radius, "Radial-axis title radius");
+  if (radius > frame.availableRadius) {
+    throw new RangeError("Radial-axis title radius must be inside the Polar frame.");
+  }
+  const { direction, normal } = radialVectors(angle);
+  return own({
+    x: frame.centerX + direction.x * radius + normal.x * offset,
+    y: frame.centerY + direction.y * radius + normal.y * offset,
+    textAlign: "center",
+    textBaseline: "top"
+  });
+}
+
+export function resolveThetaAxisTitle({ frame, offset }) {
+  validateFrame(frame);
+  validateNonNegative(offset, "Theta-axis title offset");
+  return own({
+    x: frame.centerX,
+    y: frame.centerY + frame.availableRadius + offset,
+    textAlign: "center",
+    textBaseline: "middle"
+  });
+}

package/src/grammar/polarLineCommands.js

@@ -0,0 +1,43 @@
+import { buildLinearPathCommands } from "./pathCommands.js";
+import { polarToCartesian } from "./polar.js";
+import {
+  mapContinuousScaleValues,
+  mapOrdinalPositionValues
+} from "./scales.js";
+
+function mappedTheta(values, fieldType, scale) {
+  return ["nominal", "ordinal"].includes(fieldType)
+    ? mapOrdinalPositionValues(values, scale)
+    : mapContinuousScaleValues(values, scale);
+}
+
+export function buildPolarLinePathCommands({
+  series,
+  thetaFieldType,
+  thetaScale,
+  radiusScale,
+  frame,
+  closed = false
+}) {
+  if (!Array.isArray(series) || series.length < 2) {
+    throw new TypeError("Polar line commands require at least two series values.");
+  }
+  if (typeof closed !== "boolean") {
+    throw new TypeError("Polar line closed must be a boolean.");
+  }
+  const theta = mappedTheta(
+    series.map(value => value.theta),
+    thetaFieldType,
+    thetaScale
+  );
+  const radius = mapContinuousScaleValues(
+    series.map(value => value.radius),
+    radiusScale
+  );
+  const points = series.map((_, index) => polarToCartesian({
+    theta: theta[index],
+    radius: radius[index],
+    frame
+  }));
+  return buildLinearPathCommands(points, { close: closed });
+}

package/src/grammar/polarPaths.js

@@ -0,0 +1,161 @@
+import { freezeOwned } from "../core/immutable.js";
+
+const KAPPA = 0.5522847498307936;
+const MAX_ARC_SEGMENT = 90;
+
+function validateFrame(frame) {
+  if (
+    frame === null ||
+    typeof frame !== "object" ||
+    ![frame.centerX, frame.centerY, frame.availableRadius].every(Number.isFinite) ||
+    frame.availableRadius < 0
+  ) {
+    throw new TypeError(
+      "Polar path frame requires finite centerX, centerY, and non-negative availableRadius."
+    );
+  }
+  return frame;
+}
+
+function validateRadius(value, label, frame) {
+  if (!Number.isFinite(value) || value < 0) {
+    throw new RangeError(`${label} must be a non-negative finite number.`);
+  }
+  if (value > frame.availableRadius) {
+    throw new RangeError(`${label} must fit inside the Polar frame.`);
+  }
+  return value;
+}
+
+function pointAt(frame, theta, radius) {
+  const radians = theta * Math.PI / 180;
+  return {
+    x: frame.centerX + radius * Math.sin(radians),
+    y: frame.centerY - radius * Math.cos(radians)
+  };
+}
+
+function arcCommands(frame, radius, startTheta, endTheta) {
+  const sweep = endTheta - startTheta;
+  const segments = Math.ceil(Math.abs(sweep) / MAX_ARC_SEGMENT);
+  const delta = sweep / segments;
+  const commands = [];
+  for (let index = 0; index < segments; index += 1) {
+    const start = startTheta + delta * index;
+    const end = start + delta;
+    const startRadians = start * Math.PI / 180;
+    const endRadians = end * Math.PI / 180;
+    const deltaRadians = endRadians - startRadians;
+    const control = 4 / 3 * Math.tan(deltaRadians / 4);
+    const from = pointAt(frame, start, radius);
+    const to = pointAt(frame, end, radius);
+    const fromDerivative = {
+      x: radius * Math.cos(startRadians),
+      y: radius * Math.sin(startRadians)
+    };
+    const toDerivative = {
+      x: radius * Math.cos(endRadians),
+      y: radius * Math.sin(endRadians)
+    };
+    commands.push({
+      op: "C",
+      x1: from.x + control * fromDerivative.x,
+      y1: from.y + control * fromDerivative.y,
+      x2: to.x - control * toDerivative.x,
+      y2: to.y - control * toDerivative.y,
+      x: to.x,
+      y: to.y
+    });
+  }
+  return commands;
+}
+
+export function buildPolarCircleCommands(frame, radius) {
+  validateFrame(frame);
+  validateRadius(radius, "Polar circle radius", frame);
+  const control = radius * KAPPA;
+  const { centerX: cx, centerY: cy } = frame;
+  return freezeOwned([
+    { op: "M", x: cx, y: cy - radius },
+    {
+      op: "C",
+      x1: cx + control,
+      y1: cy - radius,
+      x2: cx + radius,
+      y2: cy - control,
+      x: cx + radius,
+      y: cy
+    },
+    {
+      op: "C",
+      x1: cx + radius,
+      y1: cy + control,
+      x2: cx + control,
+      y2: cy + radius,
+      x: cx,
+      y: cy + radius
+    },
+    {
+      op: "C",
+      x1: cx - control,
+      y1: cy + radius,
+      x2: cx - radius,
+      y2: cy + control,
+      x: cx - radius,
+      y: cy
+    },
+    {
+      op: "C",
+      x1: cx - radius,
+      y1: cy - control,
+      x2: cx - control,
+      y2: cy - radius,
+      x: cx,
+      y: cy - radius
+    },
+    { op: "Z" }
+  ]);
+}
+
+export function buildAnnularSectorCommands({
+  frame,
+  startTheta,
+  endTheta,
+  innerRadius = 0,
+  outerRadius,
+  padAngle = 0
+}) {
+  validateFrame(frame);
+  if (![startTheta, endTheta].every(Number.isFinite)) {
+    throw new TypeError("Polar sector angles must be finite numbers.");
+  }
+  validateRadius(innerRadius, "Polar sector innerRadius", frame);
+  validateRadius(outerRadius, "Polar sector outerRadius", frame);
+  if (outerRadius <= innerRadius) {
+    throw new RangeError("Polar sector outerRadius must be greater than innerRadius.");
+  }
+  const sweep = endTheta - startTheta;
+  if (sweep === 0 || Math.abs(sweep) > 360) {
+    throw new RangeError("Polar sector sweep must be non-zero and at most 360 degrees.");
+  }
+  if (!Number.isFinite(padAngle) || padAngle < 0 || padAngle >= Math.abs(sweep)) {
+    throw new RangeError(
+      "Polar sector padAngle must be non-negative and smaller than its sweep."
+    );
+  }
+  const direction = Math.sign(sweep);
+  const start = startTheta + direction * padAngle / 2;
+  const end = endTheta - direction * padAngle / 2;
+  const commands = [
+    { op: "M", ...pointAt(frame, start, outerRadius) },
+    ...arcCommands(frame, outerRadius, start, end)
+  ];
+  if (innerRadius === 0) {
+    commands.push({ op: "L", x: frame.centerX, y: frame.centerY });
+  } else {
+    commands.push({ op: "L", ...pointAt(frame, end, innerRadius) });
+    commands.push(...arcCommands(frame, innerRadius, end, start));
+  }
+  commands.push({ op: "Z" });
+  return freezeOwned(commands);
+}