ggaction 0.0.1

package/src/grammar/schemas/semanticPath.js

@@ -0,0 +1,174 @@
+import { USER_ID_SOURCE } from "../../core/identifiers.js";
+import {
+  ENCODING_CHANNELS,
+  POSITION_CHANNELS,
+  SCALED_ENCODING_CHANNELS
+} from "../../core/vocabulary.js";
+
+const ENCODING_PATHS = Object.freeze([
+  ...ENCODING_CHANNELS.flatMap(channel => [
+    `encoding.${channel}.field`,
+    `encoding.${channel}.datum`,
+    `encoding.${channel}.fieldType`,
+    `encoding.${channel}.title`
+  ]),
+  ...SCALED_ENCODING_CHANNELS.map(channel =>
+    `encoding.${channel}.scale`
+  ),
+  "encoding.x.bin.maxBins",
+  "encoding.x.bin.step",
+  "encoding.x.bin.boundaries",
+  "encoding.color.layout",
+  "encoding.color.aggregate",
+  ...POSITION_CHANNELS.flatMap(channel => [
+    `encoding.${channel}.aggregate`,
+    `encoding.${channel}.stack`
+  ])
+]);
+
+const ENTITY_PATHS = Object.freeze({
+  dataset: {
+    collection: "datasets",
+    properties: new Set(["source", "transform", "values"])
+  },
+  layer: {
+    collection: "layers",
+    removableContainers: new Set(
+      ENCODING_CHANNELS.map(channel => `encoding.${channel}`)
+    ),
+    properties: new Set([
+      "data",
+      "coordinate",
+      "transform",
+      "mark.type",
+      ...ENCODING_PATHS
+    ])
+  },
+  scale: {
+    collection: "scales",
+    properties: new Set([
+      "type", "domain", "range", "nice", "zero", "clamp", "reverse",
+      "unknown", "base", "exponent", "constant", "interpolate",
+      "paddingInner", "paddingOuter", "padding", "align"
+    ])
+  },
+  coordinate: {
+    collection: "coordinates",
+    properties: new Set(["type"])
+  }
+});
+
+const GUIDE_PATHS = new Set([
+  "axis.x.scale",
+  "axis.x.coordinate",
+  "axis.x.title",
+  "axis.y.scale",
+  "axis.y.coordinate",
+  "axis.y.title",
+  "legend.color.scale",
+  "legend.color.title",
+  "legend.size.scale",
+  "legend.size.title",
+  "legend.opacity.scale",
+  "legend.opacity.title",
+  "legend.series.channels",
+  "legend.series.scales",
+  "legend.series.title",
+  "grid.horizontal.scale",
+  "grid.horizontal.coordinate",
+  "grid.vertical.scale",
+  "grid.vertical.coordinate"
+]);
+
+const GUIDE_REMOVABLE_CONTAINERS = new Set([
+  "legend.color",
+  "legend.size",
+  "legend.opacity",
+  "legend.series"
+]);
+
+const TITLE_PATHS = new Set(["text", "subtitle"]);
+
+function splitPropertyPath(property) {
+  return property.split(".");
+}
+
+export function parseSemanticPath(property, { allowContainer = false } = {}) {
+  if (typeof property !== "string" || property.length === 0) {
+    throw new TypeError("editSemantic requires a non-empty property string.");
+  }
+
+  if (allowContainer) {
+    const datasetMatch = property.match(
+      new RegExp(`^dataset\\[(${USER_ID_SOURCE})\\]$`)
+    );
+    if (datasetMatch) {
+      return Object.freeze({
+        kind: "dataset",
+        id: datasetMatch[1],
+        collection: "datasets",
+        path: Object.freeze([])
+      });
+    }
+  }
+
+  const entityMatch = property.match(
+    new RegExp(
+      `^(${Object.keys(ENTITY_PATHS).join("|")})\\[(${USER_ID_SOURCE})\\]\\.(.+)$`
+    )
+  );
+
+  if (entityMatch) {
+    const [, kind, id, propertyPath] = entityMatch;
+    const definition = ENTITY_PATHS[kind];
+
+    if (
+      !definition.properties.has(propertyPath) &&
+      !(allowContainer && definition.removableContainers?.has(propertyPath))
+    ) {
+      throw new Error(`Unknown semantic property "${property}".`);
+    }
+
+    return Object.freeze({
+      kind,
+      id,
+      collection: definition.collection,
+      path: Object.freeze(splitPropertyPath(propertyPath))
+    });
+  }
+
+  if (property.startsWith("guide.")) {
+    const propertyPath = property.slice("guide.".length);
+
+    if (
+      !GUIDE_PATHS.has(propertyPath) &&
+      !(allowContainer && GUIDE_REMOVABLE_CONTAINERS.has(propertyPath))
+    ) {
+      throw new Error(`Unknown semantic property "${property}".`);
+    }
+
+    return Object.freeze({
+      kind: "guide",
+      id: propertyPath.split(".").slice(0, 2).join("."),
+      collection: "guides",
+      path: Object.freeze(splitPropertyPath(propertyPath))
+    });
+  }
+
+  if (property.startsWith("title.")) {
+    const propertyPath = property.slice("title.".length);
+
+    if (!TITLE_PATHS.has(propertyPath)) {
+      throw new Error(`Unknown semantic property "${property}".`);
+    }
+
+    return Object.freeze({
+      kind: "title",
+      id: "title",
+      collection: "title",
+      path: Object.freeze(splitPropertyPath(propertyPath))
+    });
+  }
+
+  throw new Error(`Unknown semantic property "${property}".`);
+}

package/src/grammar/seriesLayout.js

@@ -0,0 +1,76 @@
+import { cloneAndFreeze } from "../core/immutable.js";
+import { COLOR_LAYOUTS } from "../core/vocabulary.js";
+
+export function validateColorLayout(layout) {
+  if (!COLOR_LAYOUTS.includes(layout)) {
+    throw new Error(`Unsupported color layout "${layout}".`);
+  }
+  return layout;
+}
+
+function validateValues(values) {
+  if (!Array.isArray(values) || !values.every(Number.isFinite)) {
+    throw new TypeError("Series layout values must be finite numbers.");
+  }
+}
+
+export function layoutSeriesPartition(values, layout, { baseline = 0 } = {}) {
+  validateValues(values);
+  validateColorLayout(layout);
+  if (!Number.isFinite(baseline)) {
+    throw new TypeError("Series layout baseline must be finite.");
+  }
+
+  if (layout === "group" || layout === "overlay") {
+    return cloneAndFreeze(values.flatMap((value, index) =>
+      value === baseline
+        ? []
+        : [{ index, value, start: baseline, end: value }]
+    ));
+  }
+
+  if (layout === "stack" || layout === "fill") {
+    if (values.some(value => value < 0)) {
+      throw new RangeError(`${layout} layout requires non-negative values.`);
+    }
+    const total = values.reduce((sum, value) => sum + value, 0);
+    if (layout === "fill" && total === 0) return cloneAndFreeze([]);
+    let offset = 0;
+    return cloneAndFreeze(values.flatMap((value, index) => {
+      if (value === 0) return [];
+      const resolvedValue = layout === "fill" ? value / total : value;
+      const start = offset;
+      const end = start + resolvedValue;
+      offset = end;
+      return [{ index, value, start, end }];
+    }));
+  }
+
+  let positive = 0;
+  let negative = 0;
+  return cloneAndFreeze(values.flatMap((value, index) => {
+    if (value === 0) return [];
+    const start = value > 0 ? positive : negative;
+    const end = start + value;
+    if (value > 0) positive = end;
+    else negative = end;
+    return [{ index, value, start, end }];
+  }));
+}
+
+export function resolveSeriesLayoutDomainValues(partitions, layout) {
+  if (!Array.isArray(partitions)) {
+    throw new TypeError("Series layout partitions must be an array.");
+  }
+  validateColorLayout(layout);
+  for (const partition of partitions) validateValues(partition);
+
+  if (layout === "fill") return [0, 1];
+  if (layout === "group" || layout === "overlay") return partitions.flat();
+  return partitions.flatMap(partition =>
+    layoutSeriesPartition(partition, layout).flatMap(segment => [
+      segment.start,
+      segment.end
+    ])
+  );
+}

package/src/grammar/ticks.js

@@ -0,0 +1,149 @@
+import { cloneAndFreeze } from "../core/immutable.js";
+
+const LINEAR_FACTORS = Object.freeze([1, 2, 3, 5]);
+
+export function niceTicks(domain, count) {
+  if (!Number.isInteger(count) || count <= 0) throw new RangeError("Tick count must be a positive integer.");
+  const low = Math.min(...domain);
+  const high = Math.max(...domain);
+  if (low === high) return cloneAndFreeze([low]);
+  const rough = (high - low) / count;
+  const power = 10 ** Math.floor(Math.log10(rough));
+  const error = rough / power;
+  const factor = LINEAR_FACTORS.find(candidate => candidate >= error) ?? 10;
+  const step = factor * power;
+  const tolerance = step * 1e-10;
+  const start = Math.ceil((low - tolerance) / step) * step;
+  const end = Math.floor((high + tolerance) / step) * step;
+  const values = [];
+  for (let value = start; value <= end + step * 1e-10; value += step) values.push(+value.toPrecision(12));
+  return cloneAndFreeze(values);
+}
+
+const SECOND = 1000;
+const MINUTE = 60 * SECOND;
+const HOUR = 60 * MINUTE;
+const DAY = 24 * HOUR;
+const YEAR = 365.2425 * DAY;
+
+const TIME_INTERVALS = Object.freeze([
+  ...[1, 2, 5, 10].map(step => ({ unit: "year", step, duration: step * YEAR })),
+  ...[1, 2, 3, 6].map(step => ({ unit: "month", step, duration: step * YEAR / 12 })),
+  ...[1, 2, 7, 14].map(step => ({ unit: "day", step, duration: step * DAY })),
+  ...[1, 3, 6, 12].map(step => ({ unit: "hour", step, duration: step * HOUR })),
+  ...[1, 5, 15, 30].map(step => ({ unit: "minute", step, duration: step * MINUTE })),
+  ...[1, 5, 15, 30].map(step => ({ unit: "second", step, duration: step * SECOND }))
+]);
+
+function validateTimeDomain(domain) {
+  if (
+    !Array.isArray(domain) ||
+    domain.length !== 2 ||
+    !domain.every(Number.isFinite)
+  ) {
+    throw new TypeError("Time tick domain must contain two finite timestamps.");
+  }
+
+  return [Math.min(...domain), Math.max(...domain)];
+}
+
+function selectTimeInterval(span, count) {
+  return TIME_INTERVALS.reduce((best, candidate) => {
+    const error = Math.abs(span / candidate.duration - count);
+    return error < best.error ? { ...candidate, error } : best;
+  }, { ...TIME_INTERVALS[0], error: Infinity });
+}
+
+function floorCalendar(timestamp, { unit, step }) {
+  const date = new Date(timestamp);
+
+  if (unit === "year") {
+    const year = Math.floor(date.getUTCFullYear() / step) * step;
+    return Date.UTC(year, 0, 1);
+  }
+
+  if (unit === "month") {
+    const month = date.getUTCFullYear() * 12 + date.getUTCMonth();
+    const aligned = Math.floor(month / step) * step;
+    return Date.UTC(Math.floor(aligned / 12), aligned % 12, 1);
+  }
+
+  const duration = unit === "day"
+    ? step * DAY
+    : unit === "hour"
+      ? step * HOUR
+      : unit === "minute"
+        ? step * MINUTE
+        : step * SECOND;
+
+  return Math.floor(timestamp / duration) * duration;
+}
+
+function addCalendar(timestamp, { unit, step }) {
+  const date = new Date(timestamp);
+
+  if (unit === "year") {
+    return Date.UTC(date.getUTCFullYear() + step, 0, 1);
+  }
+
+  if (unit === "month") {
+    return Date.UTC(date.getUTCFullYear(), date.getUTCMonth() + step, 1);
+  }
+
+  const duration = unit === "day"
+    ? step * DAY
+    : unit === "hour"
+      ? step * HOUR
+      : unit === "minute"
+        ? step * MINUTE
+        : step * SECOND;
+
+  return timestamp + duration;
+}
+
+export function timeTicks(domain, count) {
+  if (!Number.isInteger(count) || count <= 0) {
+    throw new RangeError("Time tick count must be a positive integer.");
+  }
+
+  const [low, high] = validateTimeDomain(domain);
+  if (low === high) return cloneAndFreeze([low]);
+  const interval = selectTimeInterval(high - low, count);
+  let value = floorCalendar(low, interval);
+  if (value < low) value = addCalendar(value, interval);
+  const values = [];
+
+  while (value <= high) {
+    values.push(value);
+    value = addCalendar(value, interval);
+  }
+
+  return cloneAndFreeze(values.length === 0 ? [low, high] : values);
+}
+
+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;
+  const date = new Date(value);
+  const year = String(date.getUTCFullYear()).padStart(4, "0");
+  const month = pad(date.getUTCMonth() + 1);
+  const day = pad(date.getUTCDate());
+  const hour = pad(date.getUTCHours());
+  const minute = pad(date.getUTCMinutes());
+  const second = pad(date.getUTCSeconds());
+
+  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}`;
+}

package/src/grammar/transforms.js

@@ -0,0 +1,37 @@
+import { isPlainObject } from "../core/immutable.js";
+import { validateBoxTransform } from "./boxPlot.js";
+import { validateDensityTransform } from "./density.js";
+import { validateFilterTransform } from "./filter.js";
+import { validateIntervalTransform } from "./interval.js";
+import { validateMarkFilterTransform } from "./markFilter.js";
+import { validateRegressionTransform } from "./regression.js";
+
+const TRANSFORM_VALIDATORS = Object.freeze({
+  boxOutlier: validateBoxTransform,
+  boxSummary: validateBoxTransform,
+  density: validateDensityTransform,
+  filter: validateFilterTransform,
+  interval: validateIntervalTransform,
+  markFilter: validateMarkFilterTransform,
+  regression: validateRegressionTransform
+});
+
+export function findTransformValidator(type) {
+  return TRANSFORM_VALIDATORS[type];
+}
+
+export function validateDatasetTransforms(value) {
+  if (!Array.isArray(value) || value.length === 0 || !value.every(isPlainObject)) {
+    throw new TypeError(
+      "Dataset transform must be a non-empty array of plain objects."
+    );
+  }
+  for (const transform of value) {
+    const validate = findTransformValidator(transform.type);
+    if (validate === undefined) {
+      throw new Error(`Unsupported dataset transform "${transform.type}".`);
+    }
+    validate(transform);
+  }
+  return value;
+}

package/src/index.js

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

package/src/layout/canvas.js

@@ -0,0 +1,114 @@
+import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
+import {
+  validateNonEmptyString,
+  validateNonNegativeFinite
+} from "../core/validation.js";
+
+const MARGIN_KEYS = Object.freeze(["top", "right", "bottom", "left"]);
+
+export const DEFAULT_MARGIN = cloneAndFreeze({
+  top: 30,
+  right: 30,
+  bottom: 60,
+  left: 70
+});
+
+export const DEFAULT_CANVAS = cloneAndFreeze({
+  width: 640,
+  height: 400,
+  background: "white",
+  margin: DEFAULT_MARGIN
+});
+
+function validateMarginValue(value, key) {
+  validateNonNegativeFinite(value, `Canvas margin.${key}`);
+}
+
+export function normalizeMargin(margin, base = DEFAULT_MARGIN) {
+  if (Number.isFinite(margin)) {
+    if (margin < 0) {
+      throw new RangeError("Canvas margin must not be negative.");
+    }
+
+    return cloneAndFreeze({
+      top: margin,
+      right: margin,
+      bottom: margin,
+      left: margin
+    });
+  }
+
+  if (!isPlainObject(margin)) {
+    throw new TypeError("Canvas margin must be a number or a plain object.");
+  }
+
+  const keys = Object.keys(margin);
+
+  if (keys.length === 0) {
+    throw new TypeError("Canvas margin object must contain at least one side.");
+  }
+
+  for (const key of keys) {
+    if (!MARGIN_KEYS.includes(key)) {
+      throw new Error(`Unknown canvas margin option "${key}".`);
+    }
+
+    validateMarginValue(margin[key], key);
+  }
+
+  return cloneAndFreeze({
+    ...base,
+    ...margin
+  });
+}
+
+export function validateCanvasState({ width, height, background, margin }) {
+  if (!Number.isInteger(width) || width <= 0) {
+    throw new RangeError("Canvas width must be a positive integer.");
+  }
+
+  if (!Number.isInteger(height) || height <= 0) {
+    throw new RangeError("Canvas height must be a positive integer.");
+  }
+
+  validateNonEmptyString(background, "Canvas background");
+
+  for (const key of MARGIN_KEYS) {
+    validateMarginValue(margin[key], key);
+  }
+
+  if (margin.left + margin.right >= width) {
+    throw new RangeError("Canvas horizontal margins must be smaller than width.");
+  }
+
+  if (margin.top + margin.bottom >= height) {
+    throw new RangeError("Canvas vertical margins must be smaller than height.");
+  }
+}
+
+export function createGraphicBounds({ width, height, margin }) {
+  return cloneAndFreeze({
+    x: margin.left,
+    y: margin.top,
+    width: width - margin.left - margin.right,
+    height: height - margin.top - margin.bottom
+  });
+}
+
+export function resolveGraphicBounds(program) {
+  const canvas = program.graphicSpec.objects.canvas;
+  const margin = program.materializationConfigs.canvas?.margin;
+  if (
+    canvas?.type !== "canvas" ||
+    !Number.isFinite(canvas.properties.width) ||
+    !Number.isFinite(canvas.properties.height) ||
+    margin === undefined
+  ) {
+    throw new Error("Graphical layout requires Canvas dimensions and margin.");
+  }
+  return createGraphicBounds({
+    width: canvas.properties.width,
+    height: canvas.properties.height,
+    margin
+  });
+}

package/src/layout/grid.js

@@ -0,0 +1,17 @@
+export function resolveGridLineGeometry({ direction, values, positions, bounds }) {
+  return direction === "horizontal"
+    ? {
+        values,
+        x1: bounds.x,
+        y1: positions,
+        x2: bounds.x + bounds.width,
+        y2: positions
+      }
+    : {
+        values,
+        x1: positions,
+        y1: bounds.y,
+        x2: positions,
+        y2: bounds.y + bounds.height
+      };
+}

package/src/layout/legend.js

@@ -0,0 +1,51 @@
+export function measureLegendSymbolHeight(config) {
+  return Math.max(...config.symbol.layers.map(layer => {
+    if (layer.type === "swatch") return layer.height;
+    if (layer.type === "point") return layer.size * 2;
+    return layer.lineWidth;
+  }));
+}
+
+export function measureLegendTextWidth(value) {
+  return String(value).length * 7;
+}
+
+export function resolveLegendGrid(config, width, count) {
+  const labels = config.domain.map(String);
+  const itemWidths = labels.map(
+    label => width + config.labels.offset + label.length * 7
+  );
+  const columnCount = Math.min(config.columns ?? count, count);
+  const rowCount = Math.ceil(count / columnCount);
+  const cells = Array.from({ length: count }, (_, index) => {
+    if (config.direction === "horizontal") {
+      return { column: index % columnCount, row: Math.floor(index / columnCount) };
+    }
+    return {
+      column: Math.floor(index / rowCount),
+      row: index % rowCount
+    };
+  });
+  const actualColumns = Math.max(...cells.map(cell => cell.column)) + 1;
+  const actualRows = Math.max(...cells.map(cell => cell.row)) + 1;
+  const columnWidths = Array.from({ length: actualColumns }, (_, column) =>
+    Math.max(...cells.map((cell, index) =>
+      cell.column === column ? itemWidths[index] : 0
+    ))
+  );
+  const gridWidth = columnWidths.reduce((sum, value) => sum + value, 0) +
+    config.itemGap * Math.max(0, actualColumns - 1);
+  const rowHeight = Math.max(
+    config.labels.fontSize,
+    measureLegendSymbolHeight(config)
+  );
+  const gridHeight = rowHeight * actualRows +
+    config.itemGap * Math.max(0, actualRows - 1);
+  return { cells, columnWidths, gridWidth, gridHeight, rowHeight };
+}
+
+export function alignLegendStart(bounds, width, align) {
+  if (align === "left") return bounds.x;
+  if (align === "right") return bounds.x + bounds.width - width;
+  return bounds.x + (bounds.width - width) / 2;
+}

package/src/layout/text.js

@@ -0,0 +1,62 @@
+import { measureTextWidth } from "../core/textMetrics.js";
+
+export { measureTextWidth } from "../core/textMetrics.js";
+
+function wrapCodePoints(text, maxWidth, style) {
+  const lines = [];
+  let line = "";
+  for (const codePoint of [...text]) {
+    const candidate = line + codePoint;
+    if (line !== "" && measureTextWidth(candidate, style) > maxWidth) {
+      lines.push(line);
+      line = codePoint;
+    } else {
+      line = candidate;
+    }
+  }
+  if (line !== "") lines.push(line);
+  return lines;
+}
+
+function wrapWords(text, maxWidth, style) {
+  const lines = [];
+  let line = "";
+  for (const word of text.trim().split(/\s+/u)) {
+    if (measureTextWidth(word, style) > maxWidth) {
+      if (line !== "") {
+        lines.push(line);
+        line = "";
+      }
+      const fragments = wrapCodePoints(word, maxWidth, style);
+      lines.push(...fragments.slice(0, -1));
+      line = fragments.at(-1);
+      continue;
+    }
+    const candidate = line === "" ? word : `${line} ${word}`;
+    if (line !== "" && measureTextWidth(candidate, style) > maxWidth) {
+      lines.push(line);
+      line = word;
+    } else {
+      line = candidate;
+    }
+  }
+  if (line !== "") lines.push(line);
+  return lines;
+}
+
+export function wrapText(text, {
+  maxWidth,
+  mode = "word",
+  style
+} = {}) {
+  if (maxWidth === undefined) return [text];
+  if (!Number.isFinite(maxWidth) || maxWidth <= 0) {
+    throw new RangeError("Text maxWidth must be positive.");
+  }
+  if (!["word", "character"].includes(mode)) {
+    throw new Error(`Unsupported text wrap mode "${mode}".`);
+  }
+  return mode === "word"
+    ? wrapWords(text, maxWidth, style)
+    : wrapCodePoints(text, maxWidth, style);
+}