ggaction 0.0.1

package/src/renderers/canvas/rect.js

@@ -0,0 +1,57 @@
+import { requireFiniteProperty } from "./validation.js";
+import { validateConcreteGraphicProperties } from
+  "../../grammar/schemas/concreteGraphic.js";
+
+function drawRect(context, child, collectionId) {
+  const properties = child.properties ?? {};
+  const graphicId = child.id ?? collectionId;
+  validateConcreteGraphicProperties("rect", properties);
+  const x = requireFiniteProperty(properties, "x", graphicId);
+  const y = requireFiniteProperty(properties, "y", graphicId);
+  const width = requireFiniteProperty(properties, "width", graphicId);
+  const height = requireFiniteProperty(properties, "height", graphicId);
+  const strokeWidth = requireFiniteProperty(
+    properties,
+    "strokeWidth",
+    graphicId
+  );
+
+  if (width < 0 || height < 0 || strokeWidth < 0) {
+    throw new Error(
+      `Graphic "${graphicId}" requires non-negative rect dimensions and strokeWidth.`
+    );
+  }
+  if (typeof properties.fill !== "string") {
+    throw new Error(`Graphic "${graphicId}" requires a string fill property.`);
+  }
+  if (typeof properties.stroke !== "string") {
+    throw new Error(`Graphic "${graphicId}" requires a string stroke property.`);
+  }
+
+  const opacity = properties.opacity ?? 1;
+  if (!Number.isFinite(opacity) || opacity < 0 || opacity > 1) {
+    throw new Error(`Graphic "${graphicId}" requires opacity from 0 to 1.`);
+  }
+
+  context.globalAlpha = opacity;
+  context.fillStyle = properties.fill;
+  context.fillRect(x, y, width, height);
+  context.strokeStyle = properties.stroke;
+  context.lineWidth = strokeWidth;
+  context.setLineDash([]);
+  context.beginPath();
+  context.moveTo(x, y);
+  context.lineTo(x + width, y);
+  context.lineTo(x + width, y + height);
+  context.lineTo(x, y + height);
+  context.lineTo(x, y);
+  context.stroke();
+}
+
+export function drawRectGraphic(context, id, graphic) {
+  if (graphic.items) {
+    for (const item of graphic.items) drawRect(context, item, id);
+    return;
+  }
+  drawRect(context, { id, properties: graphic.properties }, id);
+}

package/src/renderers/canvas/text.js

@@ -0,0 +1,96 @@
+import { requireFiniteProperty, requireStringProperty } from "./validation.js";
+import { validateConcreteGraphicProperties } from
+  "../../grammar/schemas/concreteGraphic.js";
+
+function drawText(context, child, collectionId) {
+  const properties = child.properties ?? {};
+  const graphicId = child.id ?? collectionId;
+  validateConcreteGraphicProperties("text", properties);
+  const x = requireFiniteProperty(properties, "x", graphicId);
+  const y = requireFiniteProperty(properties, "y", graphicId);
+  const fontSize = requireFiniteProperty(properties, "fontSize", graphicId);
+  const rotation = properties.rotation ?? 0;
+  const opacity = properties.opacity ?? 1;
+  const text = requireStringProperty(properties, "text", graphicId);
+  const fill = requireStringProperty(properties, "fill", graphicId);
+  const fontFamily = requireStringProperty(
+    properties,
+    "fontFamily",
+    graphicId
+  );
+  const textAlign = requireStringProperty(
+    properties,
+    "textAlign",
+    graphicId
+  );
+  const textBaseline = requireStringProperty(
+    properties,
+    "textBaseline",
+    graphicId
+  );
+  const fontWeight = properties.fontWeight ?? "normal";
+
+  if (fontSize <= 0) {
+    throw new Error(`Graphic "${graphicId}" requires a positive fontSize.`);
+  }
+
+  if (!Number.isFinite(rotation)) {
+    throw new Error(`Graphic "${graphicId}" requires a finite rotation.`);
+  }
+
+  if (!Number.isFinite(opacity) || opacity < 0 || opacity > 1) {
+    throw new Error(`Graphic "${graphicId}" requires opacity from 0 to 1.`);
+  }
+
+  if (
+    !(
+      (typeof fontWeight === "string" && fontWeight.length > 0) ||
+      Number.isFinite(fontWeight)
+    )
+  ) {
+    throw new Error(`Graphic "${graphicId}" requires a valid fontWeight.`);
+  }
+
+  if (!["left", "right", "center", "start", "end"].includes(textAlign)) {
+    throw new Error(`Graphic "${graphicId}" has invalid textAlign.`);
+  }
+
+  if (
+    ![
+      "top",
+      "hanging",
+      "middle",
+      "alphabetic",
+      "ideographic",
+      "bottom"
+    ].includes(textBaseline)
+  ) {
+    throw new Error(`Graphic "${graphicId}" has invalid textBaseline.`);
+  }
+
+  context.save();
+
+  try {
+    context.fillStyle = fill;
+    context.globalAlpha = opacity;
+    context.font = `${fontWeight} ${fontSize}px ${fontFamily}`;
+    context.textAlign = textAlign;
+    context.textBaseline = textBaseline;
+    context.translate(x, y);
+    context.rotate(rotation);
+    context.fillText(text, 0, 0);
+  } finally {
+    context.restore();
+  }
+}
+
+export function drawTextGraphic(context, id, graphic) {
+  if (graphic.items) {
+    for (const item of graphic.items) {
+      drawText(context, item, id);
+    }
+    return;
+  }
+
+  drawText(context, { id, properties: graphic.properties }, id);
+}

package/src/renderers/canvas/validation.js

@@ -0,0 +1,23 @@
+export function requireFiniteProperty(properties, property, graphicId) {
+  const value = properties[property];
+
+  if (!Number.isFinite(value)) {
+    throw new Error(
+      `Graphic "${graphicId}" requires a finite ${property} property.`
+    );
+  }
+
+  return value;
+}
+
+export function requireStringProperty(properties, property, graphicId) {
+  const value = properties[property];
+
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(
+      `Graphic "${graphicId}" requires a non-empty ${property} property.`
+    );
+  }
+
+  return value;
+}

package/src/renderers/png.js

@@ -0,0 +1,29 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+
+import { createCanvas } from "@napi-rs/canvas";
+
+import { render } from "./canvas/index.js";
+
+export async function renderToPNG(program, { output, pixelRatio = 1 } = {}) {
+  if (typeof output !== "string" || output.length === 0) {
+    throw new TypeError("renderToPNG requires a non-empty output path.");
+  }
+
+  const canvas = createCanvas(1, 1);
+  const context = canvas.getContext("2d");
+  render(program, context, { pixelRatio });
+
+  const path = resolve(output);
+  const buffer = canvas.toBuffer("image/png");
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, buffer);
+
+  return Object.freeze({
+    output: path,
+    width: canvas.width,
+    height: canvas.height,
+    pixelRatio,
+    bytes: buffer.length
+  });
+}

package/src/selectors/coordinates.js

@@ -0,0 +1,13 @@
+export function findCoordinate(program, id) {
+  return program.semanticSpec.coordinates.find(coordinate => coordinate.id === id);
+}
+
+export function hasCoordinate(program, id) {
+  return findCoordinate(program, id) !== undefined;
+}
+
+export function requireCoordinate(program, id) {
+  const coordinate = findCoordinate(program, id);
+  if (coordinate === undefined) throw new Error(`Unknown coordinate "${id}".`);
+  return coordinate;
+}

package/src/selectors/datasets.js

@@ -0,0 +1,13 @@
+export function findDataset(program, id) {
+  return program.semanticSpec.datasets.find(dataset => dataset.id === id);
+}
+
+export function hasDataset(program, id) {
+  return findDataset(program, id) !== undefined;
+}
+
+export function requireDataset(program, id, label = `Dataset "${id}"`) {
+  const dataset = findDataset(program, id);
+  if (dataset === undefined) throw new Error(`${label} does not exist.`);
+  return dataset;
+}

package/src/selectors/index.js

@@ -0,0 +1,4 @@
+export * from "./coordinates.js";
+export * from "./datasets.js";
+export * from "./layers.js";
+export * from "./scales.js";

package/src/selectors/layers.js

@@ -0,0 +1,32 @@
+export function findLayer(program, id) {
+  return program.semanticSpec.layers.find(layer => layer.id === id);
+}
+
+export function hasLayer(program, id) {
+  return findLayer(program, id) !== undefined;
+}
+
+export function requireLayer(program, id, label = `Layer "${id}"`) {
+  const layer = findLayer(program, id);
+  if (layer === undefined) throw new Error(`${label} does not exist.`);
+  return layer;
+}
+
+export function resolveEligibleLayer(program, {
+  target,
+  predicate,
+  label,
+  current = program.context.currentMark
+}) {
+  const candidates = program.semanticSpec.layers.filter(predicate);
+  if (target !== undefined) {
+    const selected = candidates.find(layer => layer.id === target);
+    if (selected === undefined) throw new Error(`Unknown ${label} target "${target}".`);
+    return selected;
+  }
+  const selected = candidates.find(layer => layer.id === current);
+  if (selected !== undefined) return selected;
+  if (candidates.length === 1) return candidates[0];
+  if (candidates.length === 0) throw new Error(`${label} requires an eligible layer.`);
+  throw new Error(`${label} target is ambiguous; provide target.`);
+}

package/src/selectors/scales.js

@@ -0,0 +1,21 @@
+export function findSemanticScale(program, id) {
+  return program.semanticSpec.scales.find(scale => scale.id === id);
+}
+
+export function requireSemanticScale(program, id) {
+  const scale = findSemanticScale(program, id);
+  if (scale === undefined) throw new Error(`Unknown scale "${id}".`);
+  return scale;
+}
+
+export function requireResolvedScale(program, id, type) {
+  const scale = program.resolvedScales[id];
+  if (scale === undefined || (type !== undefined && scale.type !== type)) {
+    throw new Error(
+      type === undefined
+        ? `Unknown resolved scale "${id}".`
+        : `Expected resolved ${type} scale "${id}".`
+    );
+  }
+  return scale;
+}

package/src/theme/defaults.js

@@ -0,0 +1,13 @@
+export const DEFAULT_FONT_FAMILY = "sans-serif";
+
+export const DEFAULT_COLORS = Object.freeze({
+  mark: "#4c78a8",
+  text: "#334155",
+  strongText: "#0f172a",
+  mutedText: "#64748b",
+  grid: "#e2e8f0",
+  border: "#cbd5e1",
+  sizeSymbol: "#94a3b8",
+  regressionBand: "#111111",
+  highlight: "#dc2626"
+});

package/types/extension.d.ts

@@ -0,0 +1,14 @@
+import type { ActionOptions } from "./program.js";
+import { ChartProgram } from "./program.js";
+
+export { ChartProgram };
+
+export interface ActionMetadata {
+  op: string;
+  description: string;
+}
+
+export function action<TOptions extends ActionOptions = ActionOptions>(
+  metadata: ActionMetadata,
+  implementation: (this: ChartProgram, options: TOptions) => ChartProgram
+): (this: ChartProgram, options?: TOptions) => ChartProgram;

package/types/index.d.ts

@@ -0,0 +1,81 @@
+import type { ChartProgram } from "./program.js";
+
+export type {
+  ActionOptions,
+  AxisFormat,
+  AxisFormatString,
+  AxisLabelOptions,
+  AxisLabelStyleOptions,
+  AxisLineStyleOptions,
+  AxisTickOptions,
+  AxisTicksAndLabelsOptions,
+  AxisTickStyleOptions,
+  AxisTitleOptions,
+  AxisValue,
+  BarWidthOptions,
+  CanvasOptions,
+  CategoricalEncodingOptions,
+  ColorLayout,
+  ColorEncodingOptions,
+  CompleteAxisOptions,
+  ChartProgram,
+  ConcretePathCommand,
+  CurveInterpolation,
+  CreateAxesOptions,
+  CreateGridOptions,
+  DashPattern,
+  DashScaleOptions,
+  DashStyle,
+  EditGraphicsOptions,
+  EditGridOptions,
+  EditScaleOptions,
+  EditSemanticOptions,
+  FieldType,
+  GraphicObject,
+  GraphicSpec,
+  GraphicType,
+  GridDirectionOptions,
+  HistogramEncodingOptions,
+  HighlightMarksOptions,
+  LegendOptions,
+  EditLegendOptions,
+  ContinuousColorInterpolation,
+  ContinuousColorScaleOptions,
+  OpacityEncodingOptions,
+  OpacityScaleOptions,
+  OffsetScaleOptions,
+  PointShape,
+  MarkSelector,
+  MarkGraphicProperty,
+  Palette,
+  PaletteName,
+  PositionEncodingOptions,
+  RulePositionEncodingOptions,
+  SecondaryPositionEncodingOptions,
+  RegressionBandOptions,
+  RegressionDataOptions,
+  RegressionInterval,
+  RegressionMethod,
+  RegressionOptions,
+  ScaleRange,
+  ScaleOptions,
+  ScaleType,
+  StackMode,
+  SemanticSpec,
+  SelectMarksOptions,
+  StrokeDashEncodingOptions,
+  TraceNode,
+  TitleOptions,
+  EditTitleOptions,
+  TitleTextStyleOptions,
+  XAxisPosition,
+  YAxisPosition,
+  XOffsetEncodingOptions
+} from "./program.js";
+
+export function chart(): ChartProgram;
+export function render(
+  program: Pick<ChartProgram, "graphicSpec">,
+  context: CanvasRenderingContext2D,
+  options?: { pixelRatio?: number }
+): void;

package/types/png.d.ts

@@ -0,0 +1,14 @@
+import type { ChartProgram } from "./program.js";
+
+export interface PNGRenderResult {
+  readonly output: string;
+  readonly width: number;
+  readonly height: number;
+  readonly pixelRatio: number;
+  readonly bytes: number;
+}
+
+export function renderToPNG(
+  program: Pick<ChartProgram, "graphicSpec">,
+  options: { output: string; pixelRatio?: number }
+): Promise<PNGRenderResult>;