ggaction 0.0.6 → 0.0.7

package/src/actions/guides/legends/categorical/index.js

@@ -25,9 +25,8 @@ import {
 } from "./symbols.js";
 import { editLegend } from "../edit.js";
 
-export function registerCategoricalLegendActions(ProgramClass) {
+export function registerBasicCategoricalLegendActions(ProgramClass) {
   ProgramClass.prototype.createLegend = createLegend;
-  ProgramClass.prototype.editLegend = editLegend;
   ProgramClass.prototype.createCategoricalLegend = createCategoricalLegend;
   ProgramClass.prototype.removeCategoricalLegend = removeCategoricalLegend;
   ProgramClass.prototype.createLegendBackground = createLegendBackground;
@@ -47,3 +46,8 @@ export function registerCategoricalLegendActions(ProgramClass) {
   ProgramClass.prototype.rematerializeLegendTitle = rematerializeLegendTitle;
   ProgramClass.prototype.rematerializeLegend = rematerializeLegend;
 }
+
+export function registerCategoricalLegendActions(ProgramClass) {
+  registerBasicCategoricalLegendActions(ProgramClass);
+  ProgramClass.prototype.editLegend = editLegend;
+}

package/src/actions/guides/legends/continuous/index.js

@@ -15,11 +15,15 @@ export {
 export { createIntervalLegend, rematerializeIntervalLegend } from "./interval.js";
 
 export function registerContinuousLegendActions(ProgramClass) {
-  ProgramClass.prototype.createGradientLegend = createGradientLegend;
-  ProgramClass.prototype.rematerializeGradientLegend = rematerializeGradientLegend;
+  registerGradientLegendActions(ProgramClass);
   ProgramClass.prototype.createOpacityLegend = createOpacityLegend;
   ProgramClass.prototype.rematerializeOpacityLegend = rematerializeOpacityLegend;
   ProgramClass.prototype.removeOpacityLegend = removeOpacityLegend;
   ProgramClass.prototype.createIntervalLegend = createIntervalLegend;
   ProgramClass.prototype.rematerializeIntervalLegend = rematerializeIntervalLegend;
 }
+
+export function registerGradientLegendActions(ProgramClass) {
+  ProgramClass.prototype.createGradientLegend = createGradientLegend;
+  ProgramClass.prototype.rematerializeGradientLegend = rematerializeGradientLegend;
+}

package/src/actions/marks/bar/index.js

@@ -3,7 +3,11 @@ import { editBarMark } from "./edit.js";
 import { rematerializeBarMark } from "./materialize.js";
 
 export function registerBarMarkActions(ProgramClass) {
-  ProgramClass.prototype.createBarMark = createBarMark;
   ProgramClass.prototype.editBarMark = editBarMark;
+  registerBasicBarMarkActions(ProgramClass);
+}
+
+export function registerBasicBarMarkActions(ProgramClass) {
+  ProgramClass.prototype.createBarMark = createBarMark;
   ProgramClass.prototype.rematerializeBarMark = rematerializeBarMark;
 }

package/src/actions/marks/basic.js

@@ -0,0 +1,11 @@
+import { registerBarMarkActions } from "./bar/index.js";
+import { registerLineMarkActions } from "./line/index.js";
+import { registerPointMarkActions } from "./point/index.js";
+import { registerRectMarkActions } from "./rect/index.js";
+
+export function registerBasicMarkActions(ProgramClass) {
+  registerPointMarkActions(ProgramClass);
+  registerLineMarkActions(ProgramClass);
+  registerBarMarkActions(ProgramClass);
+  registerRectMarkActions(ProgramClass);
+}

package/src/actions/marks/line/actions.js

@@ -386,7 +386,11 @@ const editLineMark = action(
 );
 
 export function registerLineMarkActions(ProgramClass) {
-  ProgramClass.prototype.createLineMark = createLineMark;
   ProgramClass.prototype.editLineMark = editLineMark;
+  registerBasicLineMarkActions(ProgramClass);
+}
+
+export function registerBasicLineMarkActions(ProgramClass) {
+  ProgramClass.prototype.createLineMark = createLineMark;
   ProgramClass.prototype.rematerializeLineMark = rematerializeLineMark;
 }

package/src/actions/marks/line/index.js

@@ -1 +1,4 @@
-export { registerLineMarkActions } from "./actions.js";
+export {
+  registerBasicLineMarkActions,
+  registerLineMarkActions
+} from "./actions.js";

package/src/actions/marks/point/index.js

@@ -5,7 +5,11 @@ import { rematerializePointMark } from "./materialize.js";
 export { registerPointJitterActions } from "./jitter.js";
 
 export function registerPointMarkActions(ProgramClass) {
-  ProgramClass.prototype.createPointMark = createPointMark;
   ProgramClass.prototype.editPointMark = editPointMark;
+  registerBasicPointMarkActions(ProgramClass);
+}
+
+export function registerBasicPointMarkActions(ProgramClass) {
+  ProgramClass.prototype.createPointMark = createPointMark;
   ProgramClass.prototype.rematerializePointMark = rematerializePointMark;
 }

package/src/actions/marks/rect/actions.js

@@ -162,7 +162,11 @@ const editRectMark = action(
 );
 
 export function registerRectMarkActions(ProgramClass) {
-  ProgramClass.prototype.createRectMark = createRectMark;
   ProgramClass.prototype.editRectMark = editRectMark;
+  registerBasicRectMarkActions(ProgramClass);
+}
+
+export function registerBasicRectMarkActions(ProgramClass) {
+  ProgramClass.prototype.createRectMark = createRectMark;
   ProgramClass.prototype.rematerializeRectMark = rematerializeRectMark;
 }

package/src/actions/marks/rect/index.js

@@ -1 +1,4 @@
-export { registerRectMarkActions } from "./actions.js";
+export {
+  registerBasicRectMarkActions,
+  registerRectMarkActions
+} from "./actions.js";

package/src/actions/scales/index.js

@@ -4,8 +4,12 @@ import { rematerializeScale } from "./materialize.js";
 import { setQuantitativeColorScale } from "./quantitativeColor.js";
 
 export function registerScaleActions(ProgramClass) {
-  ProgramClass.prototype.createScale = createScale;
   ProgramClass.prototype.editScale = editScale;
+  registerBasicScaleActions(ProgramClass);
+}
+
+export function registerBasicScaleActions(ProgramClass) {
+  ProgramClass.prototype.createScale = createScale;
   ProgramClass.prototype.rematerializeScale = rematerializeScale;
   ProgramClass.prototype.setQuantitativeColorScale = setQuantitativeColorScale;
 }

package/src/basic.js

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

package/src/renderers/canvas/index.js

@@ -17,32 +17,43 @@ const DRAWERS = Object.freeze({
   path: drawPathGraphic
 });
 
-function requireCanvasContext(context) {
-  const methods = [
-    "save",
-    "restore",
-    "clearRect",
-    "fillRect",
-    "beginPath",
-    "closePath",
-    "arc",
-    "fill",
-    "moveTo",
-    "lineTo",
-    "bezierCurveTo",
-    "setLineDash",
-    "stroke",
-    "translate",
-    "rotate",
-    "fillText",
-    "scale"
-  ];
+const DRAWING_CONTEXT_METHODS = Object.freeze([
+  "save",
+  "restore",
+  "fillRect",
+  "beginPath",
+  "closePath",
+  "arc",
+  "fill",
+  "moveTo",
+  "lineTo",
+  "bezierCurveTo",
+  "setLineDash",
+  "stroke",
+  "translate",
+  "rotate",
+  "fillText"
+]);
+
+function requireDrawingContext(context) {
+  if (context === null || typeof context !== "object") {
+    throw new TypeError("Canvas drawing requires a 2D context.");
+  }
+
+  for (const method of DRAWING_CONTEXT_METHODS) {
+    if (typeof context[method] !== "function") {
+      throw new TypeError(`Canvas context is missing ${method}().`);
+    }
+  }
+}
 
+function requireCanvasContext(context) {
   if (context === null || typeof context !== "object" || !context.canvas) {
     throw new TypeError("render requires a Canvas 2D context.");
   }
 
-  for (const method of methods) {
+  requireDrawingContext(context);
+  for (const method of ["clearRect", "scale"]) {
     if (typeof context[method] !== "function") {
       throw new TypeError(`Canvas context is missing ${method}().`);
     }
@@ -86,7 +97,7 @@ function enterNestedCanvas(context, id, canvas) {
   fillCanvasBackground(context, id, canvas, width, height);
 }
 
-export function render(program, context, { pixelRatio = 1 } = {}) {
+export function requireProgramGraphicSpec(program) {
   const graphicSpec = program?.graphicSpec;
 
   if (
@@ -99,12 +110,10 @@ export function render(program, context, { pixelRatio = 1 } = {}) {
     throw new TypeError("render requires a program with a graphicSpec.");
   }
 
-  requireCanvasContext(context);
-
-  if (!Number.isFinite(pixelRatio) || pixelRatio <= 0) {
-    throw new RangeError("render pixelRatio must be a positive finite number.");
-  }
+  return graphicSpec;
+}
 
+export function resolveGraphicRenderTarget(graphicSpec) {
   const { id: canvasId, object: canvas } =
     requireSingleOrderedGraphicByType(graphicSpec, "canvas");
   const width = requireFiniteProperty(canvas.properties ?? {}, "width", canvasId);
@@ -118,6 +127,65 @@ export function render(program, context, { pixelRatio = 1 } = {}) {
     throw new Error("Canvas width and height must not be negative.");
   }
 
+  return Object.freeze({
+    graphicSpec,
+    canvasId,
+    canvas,
+    width,
+    height
+  });
+}
+
+export function drawResolvedGraphicSpec(target, context) {
+  requireDrawingContext(context);
+  const { graphicSpec, canvasId, canvas, width, height } = target;
+
+  fillCanvasBackground(context, canvasId, canvas, width, height);
+
+  walkGraphicTreeEvents(graphicSpec, {
+    enter({ id, object }) {
+      if (id === canvasId) return;
+      if (object.type === "canvas") {
+        enterNestedCanvas(context, id, object);
+        return;
+      }
+      if (object.type === "collection") {
+        context.save();
+        return;
+      }
+      if (!Array.isArray(object.items)) {
+        drawConcreteGraphic(context, id, object);
+      }
+    },
+    item({ id, object, owner }) {
+      drawConcreteGraphic(context, id, {
+        ...object,
+        type: object.type ?? owner.type
+      });
+    },
+    exit({ id, object }) {
+      if (
+        id !== canvasId &&
+        (object.type === "collection" || object.type === "canvas")
+      ) {
+        context.restore();
+      }
+    }
+  });
+}
+
+export function render(program, context, { pixelRatio = 1 } = {}) {
+  const graphicSpec = requireProgramGraphicSpec(program);
+
+  requireCanvasContext(context);
+
+  if (!Number.isFinite(pixelRatio) || pixelRatio <= 0) {
+    throw new RangeError("render pixelRatio must be a positive finite number.");
+  }
+
+  const target = resolveGraphicRenderTarget(graphicSpec);
+  const { width, height } = target;
+
   context.canvas.width = Math.round(width * pixelRatio);
   context.canvas.height = Math.round(height * pixelRatio);
   if (
@@ -132,39 +200,7 @@ export function render(program, context, { pixelRatio = 1 } = {}) {
   try {
     context.scale(pixelRatio, pixelRatio);
     context.clearRect(0, 0, width, height);
-
-    fillCanvasBackground(context, canvasId, canvas, width, height);
-
-    walkGraphicTreeEvents(graphicSpec, {
-      enter({ id, object }) {
-        if (id === canvasId) return;
-        if (object.type === "canvas") {
-          enterNestedCanvas(context, id, object);
-          return;
-        }
-        if (object.type === "collection") {
-          context.save();
-          return;
-        }
-        if (!Array.isArray(object.items)) {
-          drawConcreteGraphic(context, id, object);
-        }
-      },
-      item({ id, object, owner }) {
-        drawConcreteGraphic(context, id, {
-          ...object,
-          type: object.type ?? owner.type
-        });
-      },
-      exit({ id, object }) {
-        if (
-          id !== canvasId &&
-          (object.type === "collection" || object.type === "canvas")
-        ) {
-          context.restore();
-        }
-      }
-    });
+    drawResolvedGraphicSpec(target, context);
   } finally {
     context.restore();
   }

package/src/renderers/canvas/text.js

@@ -1,18 +1,7 @@
 import { requireFiniteProperty, requireStringProperty } from "./validation.js";
 import { validateConcreteGraphicProperties } from
   "../../grammar/schemas/concreteGraphic.js";
-
-const MIN_CANVAS_NUMERIC_FONT_WEIGHT = 100;
-const MAX_CANVAS_NUMERIC_FONT_WEIGHT = 900;
-
-export function normalizeCanvasFontWeight(fontWeight) {
-  if (typeof fontWeight !== "number") return fontWeight;
-  const rounded = Math.round(fontWeight / 100) * 100;
-  return Math.min(
-    MAX_CANVAS_NUMERIC_FONT_WEIGHT,
-    Math.max(MIN_CANVAS_NUMERIC_FONT_WEIGHT, rounded)
-  );
-}
+import { normalizeRendererFontWeight } from "../text.js";
 
 function drawText(context, child, collectionId) {
   const properties = child.properties ?? {};
@@ -85,8 +74,8 @@ function drawText(context, child, collectionId) {
   try {
     context.fillStyle = fill;
     context.globalAlpha = opacity;
-    const canvasFontWeight = normalizeCanvasFontWeight(fontWeight);
-    context.font = `${canvasFontWeight} ${fontSize}px ${fontFamily}`;
+    const rendererFontWeight = normalizeRendererFontWeight(fontWeight);
+    context.font = `${rendererFontWeight} ${fontSize}px ${fontFamily}`;
     context.textAlign = textAlign;
     context.textBaseline = textBaseline;
     context.translate(x, y);

package/src/renderers/pdf.js

@@ -0,0 +1,112 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+
+import { PDFDocument } from "@napi-rs/canvas";
+
+import {
+  drawResolvedGraphicSpec,
+  requireProgramGraphicSpec,
+  resolveGraphicRenderTarget
+} from "./canvas/index.js";
+
+const PDF_OPTIONS = new Set(["output", "metadata"]);
+const PDF_METADATA = new Set([
+  "title",
+  "author",
+  "subject",
+  "keywords"
+]);
+
+function requirePlainObject(value, label) {
+  if (
+    value === null ||
+    typeof value !== "object" ||
+    Array.isArray(value) ||
+    Object.getPrototypeOf(value) !== Object.prototype
+  ) {
+    throw new TypeError(`${label} must be a plain object.`);
+  }
+  return value;
+}
+
+function requireClosedKeys(value, allowed, label) {
+  for (const key of Object.keys(value)) {
+    if (!allowed.has(key)) {
+      throw new TypeError(`${label} does not support option "${key}".`);
+    }
+  }
+}
+
+function requireMetadata(metadata) {
+  if (metadata === undefined) return undefined;
+  requirePlainObject(metadata, "renderToPDF metadata");
+  requireClosedKeys(metadata, PDF_METADATA, "renderToPDF metadata");
+
+  const resolved = {};
+  for (const key of ["title", "author", "subject"]) {
+    const value = metadata[key];
+    if (
+      value !== undefined &&
+      (typeof value !== "string" || value.length === 0)
+    ) {
+      throw new TypeError(
+        `renderToPDF metadata ${key} must be a non-empty string.`
+      );
+    }
+    if (value !== undefined) resolved[key] = value;
+  }
+
+  if (metadata.keywords !== undefined) {
+    if (
+      !Array.isArray(metadata.keywords) ||
+      !metadata.keywords.every(keyword =>
+        typeof keyword === "string" && keyword.length > 0
+      )
+    ) {
+      throw new TypeError(
+        "renderToPDF metadata keywords must be an array of non-empty strings."
+      );
+    }
+    resolved.keywords = metadata.keywords.join(", ");
+  }
+
+  return resolved;
+}
+
+function requirePDFOptions(options) {
+  requirePlainObject(options, "renderToPDF options");
+  requireClosedKeys(options, PDF_OPTIONS, "renderToPDF");
+  if (typeof options.output !== "string" || options.output.length === 0) {
+    throw new TypeError("renderToPDF requires a non-empty output path.");
+  }
+  return {
+    output: resolve(options.output),
+    metadata: requireMetadata(options.metadata)
+  };
+}
+
+function renderPDFBuffer(target, metadata) {
+  const document = new PDFDocument(metadata);
+  const context = document.beginPage(target.width, target.height);
+  drawResolvedGraphicSpec(target, context);
+  document.endPage();
+  return document.close();
+}
+
+export async function renderToPDF(program, options = {}) {
+  const { output, metadata } = requirePDFOptions(options);
+  const graphicSpec = requireProgramGraphicSpec(program);
+  const target = resolveGraphicRenderTarget(graphicSpec);
+  const buffer = renderPDFBuffer(target, metadata);
+
+  await mkdir(dirname(output), { recursive: true });
+  await writeFile(output, buffer);
+
+  return Object.freeze({
+    output,
+    width: target.width,
+    height: target.height,
+    pages: 1,
+    bytes: buffer.length
+  });
+}