ggaction 0.0.13 → 0.0.16

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 primitiveBounds(type, properties = {}) {
-  const strokeExtent = (properties.strokeWidth ?? 0) / 2;
+function hasActiveStroke(properties) {
+  return typeof properties.stroke === "string" &&
+    (properties.strokeWidth ?? 0) > 0;
+}
+
+function primitiveBounds(type, properties = {}, profile) {
+  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") {
@@ -276,14 +420,19 @@ function primitiveBounds(type, properties = {}) {
       !Number.isFinite(properties.fontSize) ||
       typeof properties.text !== "string"
     ) return undefined;
-    return resolveTextBounds(properties);
+    return resolveTextBounds(properties, profile);
   }
   if (type === "path") {
     const commands = properties.commands;
     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;
 }
@@ -320,15 +469,15 @@ function ancestorOffset(graphicSpec, target) {
   }
 }
 
-function objectBounds(graphicSpec, id, object, ancestors, x, y) {
+function objectBounds(graphicSpec, id, object, ancestors, x, y, profile) {
   if (ancestors.has(id)) {
     throw new Error(`Graphic attachment cycle includes "${id}".`);
   }
   ancestors.add(id);
   let result = object.items === undefined
-    ? translateBounds(primitiveBounds(object.type, object.properties), x, y)
+    ? translateBounds(primitiveBounds(object.type, object.properties, profile), x, y)
     : unionBounds(object.items.map(item => translateBounds(
-        primitiveBounds(item.type ?? object.type, item.properties),
+        primitiveBounds(item.type ?? object.type, item.properties, profile),
         x,
         y
       )));
@@ -340,7 +489,7 @@ function objectBounds(graphicSpec, id, object, ancestors, x, y) {
       throw new Error(`Unknown attached graphic "${childId}".`);
     }
     const bounds = objectBounds(
-      graphicSpec, childId, child.object, ancestors, childX, childY
+      graphicSpec, childId, child.object, ancestors, childX, childY, profile
     );
     if (bounds !== undefined) {
       result = includeExtent(
@@ -352,23 +501,23 @@ function objectBounds(graphicSpec, id, object, ancestors, x, y) {
   return result;
 }
 
-export function resolveConcreteGraphicBounds(graphicSpec, target) {
+export function resolveConcreteGraphicBounds(graphicSpec, target, profile) {
   const found = requireGraphic(graphicSpec, target);
   const [x, y] = ancestorOffset(graphicSpec, target);
   return requireFiniteBounds(found.kind === "item"
     ? translateBounds(
-      primitiveBounds(found.object.type ?? found.owner.type, found.object.properties),
+      primitiveBounds(found.object.type ?? found.owner.type, found.object.properties, profile),
       x,
       y
     )
-    : objectBounds(graphicSpec, found.id, found.object, new Set(), x, y));
+    : objectBounds(graphicSpec, found.id, found.object, new Set(), x, y, profile));
 }
 
-export function unionConcreteGraphicBounds(graphicSpec, targets) {
+export function unionConcreteGraphicBounds(graphicSpec, targets, profile) {
   if (!Array.isArray(targets)) {
     throw new TypeError("Graphic bounds targets must be an array.");
   }
   return unionBounds(targets.map(target =>
-    resolveConcreteGraphicBounds(graphicSpec, target)
+    resolveConcreteGraphicBounds(graphicSpec, target, profile)
   ));
 }

package/src/grammar/schemas/semanticPath.js

@@ -18,6 +18,7 @@ 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",
@@ -77,7 +78,7 @@ const ENTITY_PATHS = Object.freeze({
   },
   coordinate: {
     collection: "coordinates",
-    properties: new Set(["type"])
+    properties: new Set(["type", "aspect", "polarFrame"])
   }
 });
 
@@ -101,6 +102,9 @@ const GUIDE_PATHS = new Set([
   "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",
@@ -132,6 +136,7 @@ const GUIDE_REMOVABLE_CONTAINERS = new Set([
   "grid.theta",
   "grid.radial",
   "legend.color",
+  "legend.stroke",
   "legend.size",
   "legend.strokeWidth",
   "legend.opacity",
@@ -151,7 +156,7 @@ export function parseSemanticPath(property, { allowContainer = false } = {}) {
 
   if (allowContainer) {
     const entityMatch = property.match(
-      new RegExp(`^(dataset|layer|scale)\\[(${USER_ID_SOURCE})\\]$`)
+      new RegExp(`^(dataset|layer|scale|coordinate)\\[(${USER_ID_SOURCE})\\]$`)
     );
     if (entityMatch) {
       const [, kind, id] = entityMatch;

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

package/src/grammar/strokeStyle.js

@@ -0,0 +1,77 @@
+import { freezeOwned, isPlainObject } from "../core/immutable.js";
+
+export const DEFAULT_LINE_CAP = "butt";
+export const DEFAULT_LINE_JOIN = "miter";
+export const DEFAULT_MITER_LIMIT = 10;
+
+export const LINE_CAPS = Object.freeze(["butt", "round", "square"]);
+export const LINE_JOINS = Object.freeze(["miter", "round", "bevel"]);
+export const STROKE_STYLE_PROPERTIES = Object.freeze([
+  "lineCap",
+  "lineJoin",
+  "miterLimit"
+]);
+
+function validateEnum(value, values, property, label) {
+  if (typeof value !== "string") {
+    throw new TypeError(`${label} ${property} must be a string.`);
+  }
+  if (!values.includes(value)) {
+    throw new Error(
+      `${label} ${property} must be one of ${values.join(", ")}.`
+    );
+  }
+  return value;
+}
+
+export function validateLineCap(value, label = "Stroke style") {
+  return validateEnum(value, LINE_CAPS, "lineCap", label);
+}
+
+export function validateLineJoin(value, label = "Stroke style") {
+  return validateEnum(value, LINE_JOINS, "lineJoin", label);
+}
+
+export function validateMiterLimit(value, label = "Stroke style") {
+  if (!Number.isFinite(value)) {
+    throw new TypeError(`${label} miterLimit must be a finite number.`);
+  }
+  if (!(value > 0)) {
+    throw new RangeError(`${label} miterLimit must be positive.`);
+  }
+  return value;
+}
+
+export function resolveStrokeDetails(request = {}) {
+  if (!isPlainObject(request)) {
+    throw new TypeError("Stroke style details must be a plain object.");
+  }
+  return freezeOwned({
+    lineCap: request.lineCap === undefined
+      ? DEFAULT_LINE_CAP
+      : validateLineCap(request.lineCap),
+    lineJoin: request.lineJoin === undefined
+      ? DEFAULT_LINE_JOIN
+      : validateLineJoin(request.lineJoin),
+    miterLimit: request.miterLimit === undefined
+      ? DEFAULT_MITER_LIMIT
+      : validateMiterLimit(request.miterLimit)
+  });
+}
+
+export function requestedStrokeDetails(request = {}, label = "Stroke style") {
+  if (!isPlainObject(request)) {
+    throw new TypeError(`${label} details must be a plain object.`);
+  }
+  const result = {};
+  if (Object.hasOwn(request, "lineCap")) {
+    result.lineCap = validateLineCap(request.lineCap, label);
+  }
+  if (Object.hasOwn(request, "lineJoin")) {
+    result.lineJoin = validateLineJoin(request.lineJoin, label);
+  }
+  if (Object.hasOwn(request, "miterLimit")) {
+    result.miterLimit = validateMiterLimit(request.miterLimit, label);
+  }
+  return freezeOwned(result);
+}