ggaction 0.0.12 → 0.0.15

package/src/grammar/schemas/graphicBounds.js

@@ -3,6 +3,7 @@ import {
   resolveTextBounds
 } from "../../core/textMetrics.js";
 import { interpolateNumber } from "../numeric.js";
+import { resolveStrokeDetails } from "../strokeStyle.js";
 import {
   findGraphic,
   findGraphicParent,
@@ -174,15 +175,101 @@ function endpointDirection(start, command, end, reverse = false) {
   return undefined;
 }
 
-function includeMiter(bounds, point, incoming, outgoing, strokeExtent) {
+function includeCircle(bounds, point, radius) {
+  return includeExtent(
+    bounds,
+    point.x - radius,
+    point.x + radius,
+    point.y - radius,
+    point.y + radius
+  );
+}
+
+function includeEndpointCap(
+  bounds,
+  point,
+  direction,
+  strokeExtent,
+  lineCap,
+  atStart
+) {
+  if (lineCap === "butt" || direction === undefined) return bounds;
+  if (lineCap === "round") {
+    return includeCircle(bounds, point, strokeExtent);
+  }
+  const sign = atStart ? -1 : 1;
+  const center = {
+    x: point.x + direction.x * strokeExtent * sign,
+    y: point.y + direction.y * strokeExtent * sign
+  };
+  const normal = { x: -direction.y, y: direction.x };
+  return includeExtent(
+    bounds,
+    center.x - Math.abs(normal.x) * strokeExtent,
+    center.x + Math.abs(normal.x) * strokeExtent,
+    center.y - Math.abs(normal.y) * strokeExtent,
+    center.y + Math.abs(normal.y) * strokeExtent
+  );
+}
+
+function segmentStrokeBounds(start, end, strokeExtent, lineCap = "butt") {
+  const command = { op: "L", x: end.x, y: end.y };
+  const direction = endpointDirection(start, command, end);
+  let bounds = includeExtent(
+    undefined,
+    start.x,
+    start.x,
+    start.y,
+    start.y
+  );
+  bounds = includeExtent(bounds, end.x, end.x, end.y, end.y);
+  if (direction === undefined) {
+    return lineCap === "butt"
+      ? bounds
+      : includeCircle(bounds, start, strokeExtent);
+  }
+  const normal = { x: -direction.y, y: direction.x };
+  for (const point of [start, end]) {
+    bounds = includeExtent(
+      bounds,
+      point.x - Math.abs(normal.x) * strokeExtent,
+      point.x + Math.abs(normal.x) * strokeExtent,
+      point.y - Math.abs(normal.y) * strokeExtent,
+      point.y + Math.abs(normal.y) * strokeExtent
+    );
+  }
+  bounds = includeEndpointCap(
+    bounds, start, direction, strokeExtent, lineCap, true
+  );
+  bounds = includeEndpointCap(
+    bounds, end, direction, strokeExtent, lineCap, false
+  );
+  return bounds;
+}
+
+function includeJoin(
+  bounds,
+  point,
+  incoming,
+  outgoing,
+  strokeExtent,
+  lineJoin,
+  miterLimit
+) {
   if (incoming === undefined || outgoing === undefined) return;
   const cross = incoming.x * outgoing.y - incoming.y * outgoing.x;
   if (Math.abs(cross) <= EPSILON) return;
+  if (lineJoin === "round") {
+    includeCircle(bounds, point, strokeExtent);
+    return;
+  }
+  if (lineJoin === "bevel") return;
   const normalX = -incoming.y - outgoing.y;
   const normalY = incoming.x + outgoing.x;
   const normalLength = Math.hypot(normalX, normalY);
+  if (!(normalLength > EPSILON)) return;
   const ratio = 2 / normalLength;
-  if (ratio > 10 * (1 + EPSILON)) return;
+  if (ratio > miterLimit * (1 + EPSILON)) return;
   const distance = strokeExtent * ratio * (cross > 0 ? -1 : 1) / normalLength;
   includeExtent(
     bounds,
@@ -193,16 +280,11 @@ function includeMiter(bounds, point, incoming, outgoing, strokeExtent) {
   );
 }
 
-function pathStrokeBounds(commands, bounds, strokeExtent) {
-  const expanded = box(
-    bounds.left, bounds.right, bounds.top, bounds.bottom, strokeExtent
-  );
-  if (!(strokeExtent > 0)) return expanded;
+function pathStrokeBounds(commands, bounds, strokeExtent, details) {
+  if (!(strokeExtent > 0)) return bounds;
   const start = { x: commands[0].x, y: commands[0].y };
   let current = start;
-  let firstDirection;
-  let previousDirection;
-  let segmentCount = 0;
+  const segments = [];
   for (const command of commands.slice(1)) {
     const end = command.op === "Z"
       ? start
@@ -210,31 +292,94 @@ function pathStrokeBounds(commands, bounds, strokeExtent) {
     const outgoing = endpointDirection(current, command, end);
     const incoming = endpointDirection(current, command, end, true);
     if (outgoing !== undefined || incoming !== undefined) {
-      if (segmentCount > 0) {
-        includeMiter(expanded, current, previousDirection, outgoing, strokeExtent);
-      } else {
-        firstDirection = outgoing;
-      }
-      previousDirection = incoming;
-      segmentCount += 1;
+      segments.push({
+        start: current,
+        end,
+        command,
+        outgoing,
+        incoming
+      });
     }
     current = end;
     if (command.op === "Z") break;
   }
-  if (commands.at(-1)?.op === "Z" && segmentCount > 1) {
-    includeMiter(
+  let expanded = bounds;
+  for (const segment of segments) {
+    let segmentBounds;
+    if (segment.command.op === "C") {
+      const centerline = resolvePathCommandBounds([
+        { op: "M", ...segment.start },
+        segment.command
+      ]);
+      segmentBounds = box(
+        centerline.left,
+        centerline.right,
+        centerline.top,
+        centerline.bottom,
+        strokeExtent
+      );
+    } else {
+      segmentBounds = segmentStrokeBounds(
+          segment.start,
+          segment.end,
+          strokeExtent,
+          "butt"
+      );
+    }
+    expanded = unionBounds([expanded, segmentBounds]);
+  }
+  for (let index = 1; index < segments.length; index += 1) {
+    includeJoin(
+      expanded,
+      segments[index].start,
+      segments[index - 1].incoming,
+      segments[index].outgoing,
+      strokeExtent,
+      details.lineJoin,
+      details.miterLimit
+    );
+  }
+  const closed = commands.at(-1)?.op === "Z";
+  if (closed && segments.length > 1) {
+    includeJoin(
       expanded,
       start,
-      previousDirection,
-      firstDirection,
-      strokeExtent
+      segments.at(-1).incoming,
+      segments[0].outgoing,
+      strokeExtent,
+      details.lineJoin,
+      details.miterLimit
+    );
+  } else if (!closed && segments.length > 0) {
+    expanded = includeEndpointCap(
+      expanded,
+      segments[0].start,
+      segments[0].outgoing,
+      strokeExtent,
+      details.lineCap,
+      true
+    );
+    expanded = includeEndpointCap(
+      expanded,
+      segments.at(-1).end,
+      segments.at(-1).incoming,
+      strokeExtent,
+      details.lineCap,
+      false
     );
   }
   return expanded;
 }
 
+function hasActiveStroke(properties) {
+  return typeof properties.stroke === "string" &&
+    (properties.strokeWidth ?? 0) > 0;
+}
+
 function primitiveBounds(type, properties = {}) {
-  const strokeExtent = (properties.strokeWidth ?? 0) / 2;
+  const strokeExtent = hasActiveStroke(properties)
+    ? properties.strokeWidth / 2
+    : 0;
   if (type === "circle") {
     if (![properties.x, properties.y, properties.radius].every(Number.isFinite)) {
       return undefined;
@@ -261,12 +406,11 @@ function primitiveBounds(type, properties = {}) {
   if (type === "line") {
     if (![properties.x1, properties.y1, properties.x2, properties.y2]
       .every(Number.isFinite)) return undefined;
-    return box(
-      Math.min(properties.x1, properties.x2),
-      Math.max(properties.x1, properties.x2),
-      Math.min(properties.y1, properties.y2),
-      Math.max(properties.y1, properties.y2),
-      strokeExtent
+    return segmentStrokeBounds(
+      { x: properties.x1, y: properties.y1 },
+      { x: properties.x2, y: properties.y2 },
+      strokeExtent,
+      resolveStrokeDetails(properties).lineCap
     );
   }
   if (type === "text") {
@@ -283,7 +427,12 @@ function primitiveBounds(type, properties = {}) {
     if (!Array.isArray(commands)) return undefined;
     const bounds = resolvePathCommandBounds(commands);
     if (bounds === undefined) return undefined;
-    return pathStrokeBounds(commands, bounds, strokeExtent);
+    return pathStrokeBounds(
+      commands,
+      bounds,
+      strokeExtent,
+      resolveStrokeDetails(properties)
+    );
   }
   return undefined;
 }

package/src/grammar/schemas/semanticPath.js

@@ -18,14 +18,24 @@ const ENCODING_PATHS = Object.freeze([
   "encoding.x.bin.maxBins",
   "encoding.x.bin.step",
   "encoding.x.bin.boundaries",
+  "encoding.x.weight",
   "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 +55,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 +63,8 @@ const ENTITY_PATHS = Object.freeze({
       "coordinate",
       "transform",
       "mark.type",
+      "mark.missing",
+      "layout.mode",
       ...ENCODING_PATHS
     ])
   },
@@ -60,13 +72,13 @@ 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"
     ])
   },
   coordinate: {
     collection: "coordinates",
-    properties: new Set(["type"])
+    properties: new Set(["type", "aspect", "polarFrame"])
   }
 });
 
@@ -86,8 +98,13 @@ 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.stroke.scale",
+  "legend.stroke.title",
+  "legend.stroke.order",
   "legend.size.scale",
   "legend.size.title",
   "legend.strokeWidth.scale",
@@ -97,6 +114,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",
@@ -118,6 +136,7 @@ const GUIDE_REMOVABLE_CONTAINERS = new Set([
   "grid.theta",
   "grid.radial",
   "legend.color",
+  "legend.stroke",
   "legend.size",
   "legend.strokeWidth",
   "legend.opacity",
@@ -137,7 +156,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|coordinate)\\[(${USER_ID_SOURCE})\\]$`)
     );
     if (entityMatch) {
       const [, kind, id] = entityMatch;

package/src/grammar/stack.js

@@ -0,0 +1,170 @@
+import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
+import { layoutSeriesPartition } from "./seriesLayout.js";
+
+const TRANSFORM_KEYS = Object.freeze([
+  "type", "category", "group", "value", "mode", "as"
+]);
+const AS_KEYS = Object.freeze(["start", "end", "value", "share"]);
+const MODES = new Set(["stack", "fill", "center", "diverging"]);
+const MAX_OUTPUT_ROWS = 10_000;
+
+function rejectUnknownKeys(value, supported, label) {
+  const unknown = Object.keys(value).find(key => !supported.includes(key));
+  if (unknown !== undefined) throw new Error(`Unknown ${label} property "${unknown}".`);
+}
+
+function requireField(value, label) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError(`${label} must be a non-empty string.`);
+  }
+  return value;
+}
+
+function normalizeAs(value, field) {
+  const requested = value ?? {};
+  if (!isPlainObject(requested)) return requested;
+  return {
+    ...requested,
+    start: requested.start ?? `${field}_start`,
+    end: requested.end ?? `${field}_end`,
+    value: requested.value ?? `${field}_value`,
+    share: requested.share ?? `${field}_share`
+  };
+}
+
+export function normalizeStackTransform({ category, group, value, mode, as } = {}) {
+  const transform = {
+    type: "stack",
+    category,
+    group,
+    value,
+    mode: mode ?? "stack",
+    as: normalizeAs(as, value)
+  };
+  validateStackTransform(transform);
+  return cloneAndFreeze(transform);
+}
+
+export function validateStackTransform(transform) {
+  if (!isPlainObject(transform)) {
+    throw new TypeError("Stack transform must be a plain object.");
+  }
+  rejectUnknownKeys(transform, TRANSFORM_KEYS, "stack transform");
+  if (transform.type !== "stack") {
+    throw new Error(`Unsupported stack transform "${transform.type}".`);
+  }
+  const roles = [
+    requireField(transform.category, "Stack category"),
+    requireField(transform.group, "Stack group"),
+    requireField(transform.value, "Stack value")
+  ];
+  if (new Set(roles).size !== roles.length) {
+    throw new Error("Stack category, group, and value fields must be unique.");
+  }
+  if (!MODES.has(transform.mode)) {
+    throw new Error(`Unsupported stack mode "${transform.mode}".`);
+  }
+  if (!isPlainObject(transform.as)) {
+    throw new TypeError("Stack as must be a plain object.");
+  }
+  rejectUnknownKeys(transform.as, AS_KEYS, "stack as");
+  const outputs = AS_KEYS.map(key => requireField(transform.as[key], `Stack as.${key}`));
+  if (new Set(outputs).size !== outputs.length) {
+    throw new Error("Stack output fields must be unique.");
+  }
+  return transform;
+}
+
+function scalarKey(value, label) {
+  if (value === null) return "null";
+  if (typeof value === "string") return `string:${value.length}:${value}`;
+  if (typeof value === "boolean") return `boolean:${value}`;
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return `number:${Object.is(value, -0) ? 0 : value}`;
+  }
+  throw new TypeError(`${label} must contain null, strings, booleans, or finite numbers.`);
+}
+
+function resolvedPartition(entries, mode) {
+  const values = entries.map(entry => entry.row.value);
+  const segments = layoutSeriesPartition(values, mode);
+  const byIndex = new Map(segments.map(segment => [segment.index, segment]));
+  const shares = layoutSeriesPartition(values.map(Math.abs), "fill");
+  const shareByIndex = new Map(shares.map(segment => [
+    segment.index,
+    segment.end - segment.start
+  ]));
+  let boundary = mode === "center" ? segments[0]?.start ?? 0 : 0;
+  return entries.map((entry, index) => {
+    const segment = byIndex.get(index);
+    const start = segment?.start ?? (mode === "diverging" ? 0 : boundary);
+    const end = segment?.end ?? start;
+    if (segment !== undefined && mode !== "diverging") boundary = segment.end;
+    return {
+      index: entry.index,
+      value: entry.row.value,
+      start,
+      end,
+      share: shareByIndex.get(index) ?? 0
+    };
+  });
+}
+
+export function deriveStackRows(rows, transform) {
+  validateStackTransform(transform);
+  if (rows.length > MAX_OUTPUT_ROWS) {
+    throw new RangeError(`Stack output cannot exceed ${MAX_OUTPUT_ROWS} rows.`);
+  }
+  const sourceFields = new Set(rows.flatMap(row => Object.keys(row)));
+  for (const output of Object.values(transform.as)) {
+    if (sourceFields.has(output)) {
+      throw new Error(`Stack output field "${output}" already exists.`);
+    }
+  }
+  const partitions = new Map();
+  const groups = new Map();
+  rows.forEach((source, index) => {
+    for (const field of [transform.category, transform.group, transform.value]) {
+      if (!Object.hasOwn(source, field)) {
+        throw new Error(`Stack source does not contain field "${field}" at row ${index}.`);
+      }
+    }
+    const categoryKey = scalarKey(source[transform.category], "Stack category field");
+    const groupKey = scalarKey(source[transform.group], "Stack group field");
+    if (!Number.isFinite(source[transform.value])) {
+      throw new TypeError(
+        `Stack value field "${transform.value}" must contain a finite number at row ${index}.`
+      );
+    }
+    if (!groups.has(groupKey)) groups.set(groupKey, groups.size);
+    let partition = partitions.get(categoryKey);
+    if (partition === undefined) {
+      partition = new Map();
+      partitions.set(categoryKey, partition);
+    }
+    if (partition.has(groupKey)) {
+      throw new Error("Stack source requires one row per category/group cell.");
+    }
+    partition.set(groupKey, {
+      index,
+      row: { groupKey, value: source[transform.value] }
+    });
+  });
+
+  const resolved = new Array(rows.length);
+  for (const partition of partitions.values()) {
+    const entries = [...partition.values()].sort((left, right) =>
+      groups.get(left.row.groupKey) - groups.get(right.row.groupKey)
+    );
+    for (const item of resolvedPartition(entries, transform.mode)) {
+      resolved[item.index] = item;
+    }
+  }
+  return rows.map((row, index) => ({
+    ...row,
+    [transform.as.start]: resolved[index].start,
+    [transform.as.end]: resolved[index].end,
+    [transform.as.value]: resolved[index].value,
+    [transform.as.share]: resolved[index].share
+  }));
+}

package/src/grammar/statisticalReference.js

@@ -0,0 +1,103 @@
+import { aggregateRows } from "./aggregate.js";
+import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
+
+const STATISTIC_KEYS = Object.freeze(["op", "p"]);
+const SIMPLE_STATISTICS = new Set(["mean", "median", "min", "max"]);
+const POPULATIONS = new Set(["boundData", "visibleItems"]);
+const TRANSFORM_KEYS = Object.freeze(["type", "target"]);
+
+function rejectUnknownKeys(value, supported, label) {
+  const unknown = Object.keys(value).find(key => !supported.includes(key));
+  if (unknown !== undefined) {
+    throw new Error(`Unknown ${label} property "${unknown}".`);
+  }
+}
+
+export function normalizeReferenceStatistic(value, label = "Reference statistic") {
+  if (!isPlainObject(value)) {
+    throw new TypeError(`${label} must be a plain object.`);
+  }
+  rejectUnknownKeys(value, STATISTIC_KEYS, label.toLowerCase());
+  if (SIMPLE_STATISTICS.has(value.op)) {
+    if (Object.hasOwn(value, "p")) {
+      throw new Error(`${label} ${value.op} does not accept p.`);
+    }
+    return cloneAndFreeze({ op: value.op });
+  }
+  if (value.op !== "quantile") {
+    throw new Error(`Unsupported ${label.toLowerCase()} "${value.op ?? "unknown"}".`);
+  }
+  if (!Number.isFinite(value.p) || value.p < 0 || value.p > 1) {
+    throw new RangeError(`${label} quantile p must be between 0 and 1.`);
+  }
+  return cloneAndFreeze({ op: "quantile", p: value.p });
+}
+
+export function normalizeReferenceStatistics(value, count, label) {
+  if (!Array.isArray(value) || value.length !== count) {
+    throw new TypeError(`${label} requires exactly ${count} statistic${count === 1 ? "" : "s"}.`);
+  }
+  return Object.freeze(value.map((statistic, index) =>
+    normalizeReferenceStatistic(statistic, `${label} statistic ${index + 1}`)
+  ));
+}
+
+export function normalizeReferencePopulation(value, label = "Reference population") {
+  const population = value ?? "boundData";
+  if (!POPULATIONS.has(population)) {
+    throw new Error(`${label} must be boundData or visibleItems.`);
+  }
+  return population;
+}
+
+export function normalizeReferenceField(value, label = "Reference field") {
+  if (value === undefined) return cloneAndFreeze({ kind: "axis" });
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError(`${label} must be a non-empty string.`);
+  }
+  return cloneAndFreeze({ kind: "explicit", field: value });
+}
+
+export function normalizeStatisticalReferenceTransform({ target } = {}) {
+  const transform = { type: "statisticalReference", target };
+  validateStatisticalReferenceTransform(transform);
+  return cloneAndFreeze(transform);
+}
+
+export function validateStatisticalReferenceTransform(transform) {
+  if (!isPlainObject(transform)) {
+    throw new TypeError("Statistical reference transform must be a plain object.");
+  }
+  rejectUnknownKeys(
+    transform,
+    TRANSFORM_KEYS,
+    "statistical reference transform"
+  );
+  if (transform.type !== "statisticalReference") {
+    throw new Error(`Unsupported statistical reference transform "${transform.type}".`);
+  }
+  if (typeof transform.target !== "string" || transform.target.length === 0) {
+    throw new TypeError("Statistical reference transform target must be a non-empty string.");
+  }
+  return transform;
+}
+
+export function deriveStatisticalReferenceValues(values, statistics, label) {
+  if (!Array.isArray(values) || values.length === 0) {
+    throw new Error(`${label} population must contain at least one value.`);
+  }
+  values.forEach((value, index) => {
+    if (!Number.isFinite(value)) {
+      throw new TypeError(
+        `${label} population value ${index} must be a finite number.`
+      );
+    }
+  });
+  return statistics.map(statistic => aggregateRows(
+    values.map(value => ({ value })),
+    "value",
+    statistic.op === "quantile"
+      ? { op: "quantile", probability: statistic.p }
+      : statistic.op
+  ));
+}