ggaction 0.0.2 → 0.0.3

package/src/grammar/positionCompatibility.js

@@ -1,16 +1,24 @@
 export const POSITION_FIELD_COMPATIBILITY = Object.freeze({
   point: Object.freeze({
     x: Object.freeze(["quantitative", "temporal", "ordinal", "nominal"]),
-    y: Object.freeze(["quantitative", "temporal", "ordinal", "nominal"])
+    y: Object.freeze(["quantitative", "temporal", "ordinal", "nominal"]),
+    theta: Object.freeze(["quantitative", "temporal", "ordinal", "nominal"]),
+    radius: Object.freeze(["quantitative"])
   }),
   line: Object.freeze({
     x: Object.freeze(["quantitative", "temporal"]),
-    y: Object.freeze(["quantitative", "temporal", "ordinal", "nominal"])
+    y: Object.freeze(["quantitative", "temporal", "ordinal", "nominal"]),
+    theta: Object.freeze(["quantitative", "temporal", "ordinal", "nominal"]),
+    radius: Object.freeze(["quantitative"])
   }),
   area: Object.freeze({
     x: Object.freeze(["quantitative", "temporal"]),
     y: Object.freeze(["quantitative", "temporal"])
   }),
+  arc: Object.freeze({
+    theta: Object.freeze(["ordinal", "nominal"]),
+    radius: Object.freeze(["quantitative"])
+  }),
   rule: Object.freeze({
     x: Object.freeze(["quantitative", "temporal", "ordinal", "nominal"]),
     y: Object.freeze(["quantitative", "temporal", "ordinal", "nominal"])
@@ -18,6 +26,14 @@ export const POSITION_FIELD_COMPATIBILITY = Object.freeze({
   bar: Object.freeze({
     x: Object.freeze(["quantitative", "temporal", "ordinal", "nominal"]),
     y: Object.freeze(["quantitative", "temporal", "ordinal", "nominal"])
+  }),
+  text: Object.freeze({
+    x: Object.freeze(["quantitative", "temporal", "ordinal", "nominal"]),
+    y: Object.freeze(["quantitative", "temporal", "ordinal", "nominal"])
+  }),
+  rect: Object.freeze({
+    x: Object.freeze(["quantitative", "temporal", "ordinal", "nominal"]),
+    y: Object.freeze(["quantitative", "temporal", "ordinal", "nominal"])
   })
 });
 

package/src/grammar/rects.js

@@ -0,0 +1,26 @@
+export const RECT_MODES = Object.freeze({
+  discrete: "discrete",
+  ranged: "ranged"
+});
+
+function categorical(encoding) {
+  return ["nominal", "ordinal"].includes(encoding?.fieldType) &&
+    encoding.scale !== undefined;
+}
+
+function ranged(primary, secondary) {
+  return primary?.scale !== undefined &&
+    secondary?.scale === primary.scale &&
+    ["quantitative", "temporal"].includes(primary.fieldType) &&
+    secondary.fieldType === primary.fieldType;
+}
+
+export function resolveRectMode(layer) {
+  if (layer?.mark?.type !== "rect") return undefined;
+  const { x, y, x2, y2 } = layer.encoding ?? {};
+  if (x2 === undefined && y2 === undefined && categorical(x) && categorical(y)) {
+    return RECT_MODES.discrete;
+  }
+  if (ranged(x, x2) && ranged(y, y2)) return RECT_MODES.ranged;
+  return undefined;
+}

package/src/grammar/scales/continuous.js

@@ -1,4 +1,6 @@
 import { cloneAndFreeze, isPlainObject } from "../../core/immutable.js";
+import { POLAR_POSITION_CHANNELS } from "../../core/vocabulary.js";
+import { resolvePolarScaleRange } from "../polar.js";
 import { niceTimeDomain } from "./temporal.js";
 import {
   validatePair,
@@ -66,8 +68,11 @@ export function resolveContinuousDomain({ domain, values, type, nice, zero }) {
 }
 
 export function resolveScaleRange(range, channel, bounds) {
-  const validated = validateScaleRange(range);
   validatePositionChannel(channel);
+  if (POLAR_POSITION_CHANNELS.includes(channel)) {
+    return resolvePolarScaleRange(range, channel, bounds);
+  }
+  const validated = validateScaleRange(range);
   if (validated !== "auto") return validated;
   if (
     !isPlainObject(bounds) ||

package/src/grammar/scales/fields.js

@@ -22,6 +22,13 @@ export function validateNominalFieldType(fieldType) {
   return fieldType;
 }
 
+export function validateCategoricalFieldType(fieldType) {
+  if (!["nominal", "ordinal"].includes(fieldType)) {
+    throw new Error(`Unsupported categorical field type "${fieldType}".`);
+  }
+  return fieldType;
+}
+
 export function validateSemanticFieldType(fieldType) {
   if (!["quantitative", "nominal", "ordinal", "temporal"].includes(fieldType)) {
     throw new Error(`Unsupported semantic field type "${fieldType}".`);

package/src/grammar/scales/ordinal.js

@@ -151,11 +151,14 @@ export function resolveOrdinalOffsetScale({
   range,
   parentBandwidth,
   paddingInner = 0,
-  paddingOuter = 0
+  paddingOuter = 0,
+  channel = "xOffset"
 }) {
   const resolvedDomain = resolveOrdinalDomain(domain, values);
   if (!Number.isFinite(parentBandwidth) || parentBandwidth <= 0) {
-    throw new Error("Automatic xOffset range requires a positive x bandwidth.");
+    throw new Error(
+      `Automatic ${channel} range requires a positive ${channel[0]} bandwidth.`
+    );
   }
   const resolvedRange = range === "auto"
     ? validatePair([0, parentBandwidth], "Offset scale range")

package/src/grammar/scales/policies.js

@@ -3,7 +3,7 @@ import { POINT_SHAPES } from "../pointShapes.js";
 import { normalizeStrokeDashPattern } from "./appearance.js";
 
 export function validateScaleUnknown(channel, value) {
-  if (["x", "y", "xOffset"].includes(channel)) {
+  if (["x", "y", "xOffset", "yOffset"].includes(channel)) {
     if (!Number.isFinite(value)) {
       throw new TypeError(`Scale unknown for ${channel} must be a finite number.`);
     }

package/src/grammar/schemas/graphic.js

@@ -11,7 +11,7 @@ const DRAWABLE_TYPES = new Set([
 ]);
 const STRUCTURAL_TYPES = new Set(["canvas"]);
 const GRAPHIC_PROPERTIES = Object.freeze({
-  canvas: new Set(["width", "height", "background"]),
+  canvas: new Set(["x", "y", "width", "height", "background"]),
   collection: new Set([
     "items",
     "x",

package/src/grammar/schemas/graphicBounds.js

@@ -11,6 +11,69 @@ function unionBounds(bounds) {
   };
 }
 
+function cubicValue(start, control1, control2, end, t) {
+  const remaining = 1 - t;
+  return remaining ** 3 * start +
+    3 * remaining ** 2 * t * control1 +
+    3 * remaining * t ** 2 * control2 +
+    t ** 3 * end;
+}
+
+function cubicExtrema(start, control1, control2, end) {
+  const quadratic = 3 * (-start + 3 * control1 - 3 * control2 + end);
+  const linear = 2 * (3 * start - 6 * control1 + 3 * control2);
+  const constant = 3 * (control1 - start);
+  const epsilon = Number.EPSILON * 64 * Math.max(
+    1,
+    Math.abs(quadratic),
+    Math.abs(linear),
+    Math.abs(constant)
+  );
+  if (Math.abs(quadratic) <= epsilon) {
+    if (Math.abs(linear) <= epsilon) return [];
+    const root = -constant / linear;
+    return root > 0 && root < 1 ? [root] : [];
+  }
+  const discriminant = linear ** 2 - 4 * quadratic * constant;
+  if (discriminant < -epsilon) return [];
+  const root = Math.sqrt(Math.max(0, discriminant));
+  return [
+    (-linear - root) / (2 * quadratic),
+    (-linear + root) / (2 * quadratic)
+  ].filter(value => value > 0 && value < 1);
+}
+
+function pathPoints(commands) {
+  const points = [];
+  let current;
+  for (const command of commands) {
+    if (command.op === "M" || command.op === "L") {
+      if ([command.x, command.y].every(Number.isFinite)) {
+        current = { x: command.x, y: command.y };
+        points.push(current);
+      }
+      continue;
+    }
+    if (command.op !== "C" || current === undefined) continue;
+    if (![command.x1, command.y1, command.x2, command.y2, command.x, command.y]
+      .every(Number.isFinite)) continue;
+    const roots = new Set([
+      0,
+      1,
+      ...cubicExtrema(current.x, command.x1, command.x2, command.x),
+      ...cubicExtrema(current.y, command.y1, command.y2, command.y)
+    ]);
+    for (const t of roots) {
+      points.push({
+        x: cubicValue(current.x, command.x1, command.x2, command.x, t),
+        y: cubicValue(current.y, command.y1, command.y2, command.y, t)
+      });
+    }
+    current = { x: command.x, y: command.y };
+  }
+  return points;
+}
+
 function primitiveBounds(type, properties = {}) {
   const strokeExtent = (properties.strokeWidth ?? 0) / 2;
   if (type === "circle") {
@@ -86,15 +149,7 @@ function primitiveBounds(type, properties = {}) {
   if (type === "path") {
     const commands = properties.commands;
     if (!Array.isArray(commands)) return undefined;
-    const points = commands.flatMap(command => {
-      if (command.op === "M" || command.op === "L") return [{ x: command.x, y: command.y }];
-      if (command.op === "C") return [
-        { x: command.x1, y: command.y1 },
-        { x: command.x2, y: command.y2 },
-        { x: command.x, y: command.y }
-      ];
-      return [];
-    }).filter(point => Number.isFinite(point.x) && Number.isFinite(point.y));
+    const points = pathPoints(commands);
     if (points.length === 0) return undefined;
     return {
       left: Math.min(...points.map(point => point.x)) - strokeExtent,

package/src/grammar/schemas/graphicTree.js

@@ -70,7 +70,7 @@ export function graphicSiblings(graphicSpec, target) {
   return graphicSpec.order;
 }
 
-function visitNamed(graphicSpec, id, visitor, path, visited) {
+function visitNamed(graphicSpec, id, visitors, path, visited) {
   if (path.includes(id)) {
     throw new Error(`Graphic attachment cycle includes "${id}".`);
   }
@@ -82,29 +82,37 @@ function visitNamed(graphicSpec, id, visitor, path, visited) {
     throw new Error(`Graphic "${id}" is attached more than once.`);
   }
   visited.add(id);
-  visitor({ id, object, kind: "object", depth: path.length });
+  const entry = { id, object, kind: "object", depth: path.length };
+  visitors.enter?.(entry);
   for (const item of object.items ?? []) {
-    visitor({
+    visitors.item?.({
       id: item.id,
       object: item,
       kind: "item",
       ownerId: id,
+      owner: object,
       depth: path.length + 1
     });
   }
   for (const childId of object.children ?? []) {
-    visitNamed(graphicSpec, childId, visitor, [...path, id], visited);
+    visitNamed(graphicSpec, childId, visitors, [...path, id], visited);
   }
+  visitors.exit?.(entry);
 }
 
-export function walkGraphicTree(graphicSpec, visitor) {
+export function walkGraphicTreeEvents(graphicSpec, visitors) {
   requireGraphicSpec(graphicSpec);
-  if (typeof visitor !== "function") {
-    throw new TypeError("walkGraphicTree requires a visitor function.");
+  if (!isPlainObject(visitors)) {
+    throw new TypeError("walkGraphicTreeEvents requires visitor callbacks.");
+  }
+  for (const name of ["enter", "item", "exit"]) {
+    if (visitors[name] !== undefined && typeof visitors[name] !== "function") {
+      throw new TypeError(`walkGraphicTreeEvents ${name} must be a function.`);
+    }
   }
   const visited = new Set();
   for (const id of graphicSpec.order) {
-    visitNamed(graphicSpec, id, visitor, [], visited);
+    visitNamed(graphicSpec, id, visitors, [], visited);
   }
   const orphan = Object.keys(graphicSpec.objects).find(id => !visited.has(id));
   if (orphan !== undefined) {
@@ -112,12 +120,38 @@ export function walkGraphicTree(graphicSpec, visitor) {
   }
 }
 
+export function walkGraphicTree(graphicSpec, visitor) {
+  if (typeof visitor !== "function") {
+    throw new TypeError("walkGraphicTree requires a visitor function.");
+  }
+  walkGraphicTreeEvents(graphicSpec, {
+    enter: visitor,
+    item: visitor
+  });
+}
+
 export function walkGraphicDrawOrder(graphicSpec, visitor) {
-  walkGraphicTree(graphicSpec, entry => {
-    if (entry.kind === "object") visitor(entry);
+  walkGraphicTreeEvents(graphicSpec, { enter: visitor });
+}
+
+export function findOrderedGraphicsByType(graphicSpec, type) {
+  requireGraphicSpec(graphicSpec);
+  return graphicSpec.order.flatMap(id => {
+    const object = graphicSpec.objects[id];
+    return object?.type === type ? [{ id, object }] : [];
   });
 }
 
+export function requireSingleOrderedGraphicByType(graphicSpec, type) {
+  const matches = findOrderedGraphicsByType(graphicSpec, type);
+  if (matches.length !== 1) {
+    throw new Error(
+      `graphicSpec must contain exactly one ordered ${type}.`
+    );
+  }
+  return matches[0];
+}
+
 export function collectGraphicSubtreeIds(graphicSpec, target) {
   const found = requireGraphic(graphicSpec, target);
   if (found.kind === "item") {

package/src/grammar/schemas/semanticPath.js

@@ -1,7 +1,7 @@
 import { USER_ID_SOURCE } from "../../core/identifiers.js";
 import {
+  CARTESIAN_POSITION_CHANNELS,
   ENCODING_CHANNELS,
-  POSITION_CHANNELS,
   SCALED_ENCODING_CHANNELS
 } from "../../core/vocabulary.js";
 
@@ -20,7 +20,9 @@ const ENCODING_PATHS = Object.freeze([
   "encoding.x.bin.boundaries",
   "encoding.color.layout",
   "encoding.color.aggregate",
-  ...POSITION_CHANNELS.flatMap(channel => [
+  "encoding.theta.aggregate",
+  "encoding.text.format",
+  ...CARTESIAN_POSITION_CHANNELS.flatMap(channel => [
     `encoding.${channel}.aggregate`,
     `encoding.${channel}.stack`
   ])
@@ -38,6 +40,7 @@ const ENTITY_PATHS = Object.freeze({
     ),
     properties: new Set([
       "data",
+      "source",
       "coordinate",
       "transform",
       "mark.type",
@@ -65,6 +68,12 @@ const GUIDE_PATHS = new Set([
   "axis.y.scale",
   "axis.y.coordinate",
   "axis.y.title",
+  "axis.theta.scale",
+  "axis.theta.coordinate",
+  "axis.theta.title",
+  "axis.radius.scale",
+  "axis.radius.coordinate",
+  "axis.radius.title",
   "legend.color.scale",
   "legend.color.title",
   "legend.size.scale",
@@ -77,10 +86,22 @@ const GUIDE_PATHS = new Set([
   "grid.horizontal.scale",
   "grid.horizontal.coordinate",
   "grid.vertical.scale",
-  "grid.vertical.coordinate"
+  "grid.vertical.coordinate",
+  "grid.theta.scale",
+  "grid.theta.coordinate",
+  "grid.radial.scale",
+  "grid.radial.coordinate"
 ]);
 
 const GUIDE_REMOVABLE_CONTAINERS = new Set([
+  "axis.x",
+  "axis.y",
+  "axis.theta",
+  "axis.radius",
+  "grid.horizontal",
+  "grid.vertical",
+  "grid.theta",
+  "grid.radial",
   "legend.color",
   "legend.size",
   "legend.opacity",
@@ -99,14 +120,15 @@ export function parseSemanticPath(property, { allowContainer = false } = {}) {
   }
 
   if (allowContainer) {
-    const datasetMatch = property.match(
-      new RegExp(`^dataset\\[(${USER_ID_SOURCE})\\]$`)
+    const entityMatch = property.match(
+      new RegExp(`^(dataset|layer)\\[(${USER_ID_SOURCE})\\]$`)
     );
-    if (datasetMatch) {
+    if (entityMatch) {
+      const [, kind, id] = entityMatch;
       return Object.freeze({
-        kind: "dataset",
-        id: datasetMatch[1],
-        collection: "datasets",
+        kind,
+        id,
+        collection: ENTITY_PATHS[kind].collection,
         path: Object.freeze([])
       });
     }

package/src/grammar/seriesLayout.js

@@ -1,6 +1,8 @@
 import { cloneAndFreeze } from "../core/immutable.js";
 import { COLOR_LAYOUTS } from "../core/vocabulary.js";
 
+export const DEFAULT_SERIES_BASELINE = 0;
+
 export function validateColorLayout(layout) {
   if (!COLOR_LAYOUTS.includes(layout)) {
     throw new Error(`Unsupported color layout "${layout}".`);
@@ -14,7 +16,11 @@ function validateValues(values) {
   }
 }
 
-export function layoutSeriesPartition(values, layout, { baseline = 0 } = {}) {
+export function layoutSeriesPartition(
+  values,
+  layout,
+  { baseline = DEFAULT_SERIES_BASELINE } = {}
+) {
   validateValues(values);
   validateColorLayout(layout);
   if (!Number.isFinite(baseline)) {
@@ -66,7 +72,12 @@ export function resolveSeriesLayoutDomainValues(partitions, layout) {
   for (const partition of partitions) validateValues(partition);
 
   if (layout === "fill") return [0, 1];
-  if (layout === "group" || layout === "overlay") return partitions.flat();
+  if (layout === "group" || layout === "overlay") {
+    return partitions.flatMap(partition => [
+      DEFAULT_SERIES_BASELINE,
+      ...partition
+    ]);
+  }
   return partitions.flatMap(partition =>
     layoutSeriesPartition(partition, layout).flatMap(segment => [
       segment.start,

package/src/grammar/text.js

@@ -0,0 +1,71 @@
+import { cloneAndFreeze } from "../core/immutable.js";
+import { validateConcreteGraphicValue } from "./schemas/concreteGraphic.js";
+
+export const DEFAULT_TEXT_MARK = cloneAndFreeze({
+  fill: "#334155",
+  opacity: 1,
+  fontSize: 12,
+  fontFamily: "sans-serif",
+  fontWeight: "normal",
+  align: "left",
+  baseline: "alphabetic",
+  rotation: 0,
+  dx: 0,
+  dy: 0
+});
+
+const FIXED_FORMAT = /^\.(\d{1,2})f$/;
+
+export function validateTextFormat(format) {
+  if (format === undefined || format === "auto") return format ?? "auto";
+  if (typeof format !== "string" || !FIXED_FORMAT.test(format)) {
+    throw new Error(
+      'Text format must be "auto" or a fixed-decimal token such as ".1f".'
+    );
+  }
+  const decimals = Number(format.match(FIXED_FORMAT)[1]);
+  if (decimals > 12) {
+    throw new RangeError("Text fixed-decimal format supports at most 12 decimals.");
+  }
+  return format;
+}
+
+export function formatTextValue(value, format = "auto") {
+  const resolved = validateTextFormat(format);
+  if (value === undefined || value === null) return undefined;
+  if (resolved === "auto") {
+    const text = String(value);
+    return text.length === 0 ? undefined : text;
+  }
+  if (!Number.isFinite(value)) {
+    throw new TypeError(`Text format "${resolved}" requires a finite number.`);
+  }
+  return value.toFixed(Number(resolved.match(FIXED_FORMAT)[1]));
+}
+
+export function normalizeTextMarkConfig(options, base = DEFAULT_TEXT_MARK) {
+  const config = { ...base };
+  const mapping = {
+    fill: "fill",
+    opacity: "opacity",
+    fontSize: "fontSize",
+    fontFamily: "fontFamily",
+    fontWeight: "fontWeight",
+    align: "textAlign",
+    baseline: "textBaseline",
+    rotation: "rotation"
+  };
+  for (const [option, property] of Object.entries(mapping)) {
+    if (!Object.hasOwn(options, option)) continue;
+    validateConcreteGraphicValue("text", property, options[option]);
+    config[option] = options[option];
+  }
+  for (const property of ["dx", "dy"]) {
+    if (!Object.hasOwn(options, property)) continue;
+    if (!Number.isFinite(options[property])) {
+      throw new TypeError(`Text ${property} must be a finite number.`);
+    }
+    config[property] = options[property];
+  }
+  return cloneAndFreeze(config);
+}

package/src/grammar/ticks.js

@@ -125,13 +125,7 @@ function pad(value) {
   return String(value).padStart(2, "0");
 }
 
-export function formatTimeTick(value, domain) {
-  if (!Number.isFinite(value)) {
-    throw new TypeError("Time tick value must be a finite timestamp.");
-  }
-
-  const [low, high] = validateTimeDomain(domain);
-  const span = high - low;
+function formatTimePrecision(value, precision) {
   const date = new Date(value);
   const year = String(date.getUTCFullYear()).padStart(4, "0");
   const month = pad(date.getUTCMonth() + 1);
@@ -139,11 +133,54 @@ export function formatTimeTick(value, domain) {
   const hour = pad(date.getUTCHours());
   const minute = pad(date.getUTCMinutes());
   const second = pad(date.getUTCSeconds());
+  const millisecond = String(date.getUTCMilliseconds()).padStart(3, "0");
+
+  if (precision === 0) return year;
+  if (precision === 1) return `${year}-${month}`;
+  if (precision === 2) return `${year}-${month}-${day}`;
+  if (precision === 3) return `${year}-${month}-${day} ${hour}:${minute}`;
+  if (precision === 4) return `${hour}:${minute}`;
+  if (precision === 5) return `${hour}:${minute}:${second}`;
+  return `${hour}:${minute}:${second}.${millisecond}`;
+}
+
+function timePrecision(domain) {
+  const [low, high] = validateTimeDomain(domain);
+  const span = high - low;
+
+  if (span >= 2 * YEAR) return 0;
+  if (span >= 60 * DAY) return 1;
+  if (span >= 2 * DAY) return 2;
+  if (span >= 2 * HOUR) return 3;
+  if (span >= 2 * MINUTE) return 4;
+  return 5;
+}
+
+export function formatTimeTick(value, domain) {
+  if (!Number.isFinite(value)) {
+    throw new TypeError("Time tick value must be a finite timestamp.");
+  }
+  return formatTimePrecision(value, timePrecision(domain));
+}
+
+function distinguishesTicks(values, labels) {
+  const timestamps = new Map();
+  for (let index = 0; index < values.length; index += 1) {
+    const previous = timestamps.get(labels[index]);
+    if (previous !== undefined && previous !== values[index]) return false;
+    timestamps.set(labels[index], values[index]);
+  }
+  return true;
+}
 
-  if (span >= 2 * YEAR) return year;
-  if (span >= 60 * DAY) return `${year}-${month}`;
-  if (span >= 2 * DAY) return `${year}-${month}-${day}`;
-  if (span >= 2 * HOUR) return `${year}-${month}-${day} ${hour}:00`;
-  if (span >= 2 * MINUTE) return `${hour}:${minute}`;
-  return `${hour}:${minute}:${second}`;
+export function formatTimeTicks(values, domain) {
+  if (!Array.isArray(values) || !values.every(Number.isFinite)) {
+    throw new TypeError("Time tick values must be finite timestamps.");
+  }
+  const initial = timePrecision(domain);
+  for (let precision = initial; precision <= 6; precision += 1) {
+    const labels = values.map(value => formatTimePrecision(value, precision));
+    if (distinguishesTicks(values, labels)) return cloneAndFreeze(labels);
+  }
+  return cloneAndFreeze(values.map(value => String(value)));
 }

package/src/index.js

@@ -1,2 +1,3 @@
 export { chart } from "./ChartProgram.js";
+export { hconcat, vconcat } from "./composition.js";
 export { render } from "./renderers/canvas/index.js";