@muhammara/native-core 7.0.0-beta.4 → 7.0.0-rc.1

package/lib/recipe/vector.js

@@ -13,31 +13,37 @@
 //   PercentColor component values range from 1 to 100.
 
 const { linkPdf } = require("./annotation");
+const muhammara = require("../muhammara");
 
 /**
  * Draw a circle
  * @name circle
  * @function
  * @memberof Recipe#
- * @param {number} x - The coordinate x
- * @param {number} y - The coordinate y
+ * @param {number|"center"} x - The coordinate x of the center
+ * @param {number|"center"} y - The coordinate y of the center
  * @param {number} radius - The radius
  * @param {Object} [options] - The options
  * @param {string|number[]} [options.color] - HexColor, PercentColor or DecimalColor
  * @param {string|number[]} [options.stroke] - HexColor, PercentColor or DecimalColor
- * @param {string|number[]}[ options.fill] - HexColor, PercentColor or DecimalColor
+ * @param {string|number[]} [options.fill] - HexColor, PercentColor or DecimalColor
  * @param {number} [options.lineWidth] - The line width
  * @param {number} [options.opacity] - The opacity
  * @param {number[]} [options.dash] - The dash style [number, number]
+ * @param {string} [options.link] - Make the circle's bounding square open this URL.
  * @returns {Recipe} The recipe instance.
+ * @throws {TypeError} If no page is active.
  */
 exports.circle = function circle(x, y, radius, options = {}) {
+  // null options act like omitted options.
+  if (options === null) options = {};
+  [x, y] = this._centrify(x, y);
   const { nx, ny } = this._calibrateCoordinate(x, y);
   const diameter = radius * 2;
 
   if (options.fill) {
     const pathOptions = this._getPathOptions(options, nx, ny);
-    pathOptions.type = "fill";
+    pathOptions.type = muhammara.DrawingPathType.FILL;
 
     if (pathOptions.fill !== undefined) {
       pathOptions.color = pathOptions.fill;
@@ -52,15 +58,20 @@ exports.circle = function circle(x, y, radius, options = {}) {
       diameter,
       pathOptions,
       (ctx, xObject) => {
-        ctx
-          .gs(xObject.getGsName(pathOptions.fillGsId))
-          .drawCircle(radius, radius, radius, pathOptions);
+        ctx.gs(xObject.getGsName(pathOptions.fillGsId));
+        this._setSeparationColor(xObject, pathOptions.fillModel, false);
+        ctx.drawCircle(
+          radius,
+          radius,
+          radius,
+          this._devicePathOptions(pathOptions),
+        );
       },
     );
   }
   if (options.stroke || options.color || !options.fill) {
     const pathOptions = this._getPathOptions(options);
-    pathOptions.type = "stroke";
+    pathOptions.type = muhammara.DrawingPathType.STROKE;
 
     if (pathOptions.stroke !== undefined) {
       pathOptions.color = pathOptions.stroke;
@@ -78,13 +89,18 @@ exports.circle = function circle(x, y, radius, options = {}) {
       pathOptions,
       (ctx, xObject) => {
         ctx.gs(xObject.getGsName(pathOptions.strokeGsId));
+        this._setSeparationColor(
+          xObject,
+          pathOptions.strokeModel || pathOptions.colorModel,
+          true,
+        );
         ctx
           .d(pathOptions.dash, pathOptions.dashPhase)
           .drawCircle(
             radius,
             radius,
-            radius - pathOptions.width / 2,
-            pathOptions,
+            Math.max(0, radius - pathOptions.width / 2),
+            this._devicePathOptions(pathOptions),
           );
 
         // ... requires adjusting the internal drawing to accomodate line thickness.
@@ -101,8 +117,8 @@ exports.circle = function circle(x, y, radius, options = {}) {
  * @name rectangle
  * @function
  * @memberof Recipe#
- * @param {number} x - The coordinate x
- * @param {number} y - The coordinate y
+ * @param {number|"center"} x - The coordinate x of the top-left corner
+ * @param {number|"center"} y - The coordinate y of the top-left corner
  * @param {number} width - The width
  * @param {number} height - The height
  * @param {Object} [options] - The options
@@ -118,9 +134,14 @@ exports.circle = function circle(x, y, radius, options = {}) {
  * When a one to four number array can be used to give specific sizees to each corner.
  * The numbering starts from the top, left corner, and goes clockwise around the text box.
  * Missing values in the array are filled in by opposite corner values.
+ * @param {string} [options.link] - Make the rectangle open this URL.
+ * @param {boolean} [options.useGivenCoords] - Take x and y as PDF coordinates of the bottom-left corner.
  * @returns {Recipe} The recipe instance.
+ * @throws {TypeError} If no page is active.
  */
 exports.rectangle = function rectangle(x, y, width, height, options = {}) {
+  // null options act like omitted options.
+  if (options === null) options = {};
   const { nx, ny } = options.useGivenCoords
     ? { nx: x, ny: y }
     : this._calibrateCoordinate(x, y, 0, -height);
@@ -130,7 +151,7 @@ exports.rectangle = function rectangle(x, y, width, height, options = {}) {
   pathOptions.useGivenCoords = options.useGivenCoords;
 
   if (options.fill) {
-    pathOptions.type = "fill";
+    pathOptions.type = muhammara.DrawingPathType.FILL;
 
     if (pathOptions.fill !== undefined) {
       pathOptions.color = pathOptions.fill;
@@ -153,20 +174,28 @@ exports.rectangle = function rectangle(x, y, width, height, options = {}) {
           drawRoundedRectangle(ctx, 0, 0, width, height, options.borderRadius);
           ctx.f();
         } else {
-          ctx.drawRectangle(0, 0, width, height, pathOptions);
+          ctx.drawRectangle(
+            0,
+            0,
+            width,
+            height,
+            this._devicePathOptions(pathOptions),
+          );
         }
       },
     );
   }
 
   if (options.stroke || options.color || !options.fill) {
-    pathOptions.type = "stroke";
+    pathOptions.type = muhammara.DrawingPathType.STROKE;
 
-    if (pathOptions.stroke !== undefined) {
-      pathOptions.color = pathOptions.stroke;
-      pathOptions.colorspace = pathOptions.strokeModel.colorspace;
-      colorModel = pathOptions.strokeModel;
-    }
+    // The fill above may have replaced the color; stroke with `color`.
+    colorModel =
+      pathOptions.stroke !== undefined
+        ? pathOptions.strokeModel
+        : pathOptions.colorModel;
+    pathOptions.color = colorModel.color;
+    pathOptions.colorspace = colorModel.colorspace;
 
     // To honor the given width and height of the rectangle ...
 
@@ -186,24 +215,26 @@ exports.rectangle = function rectangle(x, y, width, height, options = {}) {
         if (options.borderRadius) {
           ctx.w(pathOptions.width).d(pathOptions.dash, pathOptions.dashPhase);
 
+          const inset = Math.min(margin / 2, width / 2, height / 2);
           drawRoundedRectangle(
             ctx,
-            margin / 2,
-            margin / 2,
-            width - margin,
-            height - margin,
+            inset,
+            inset,
+            width - inset * 2,
+            height - inset * 2,
             options.borderRadius,
+            inset,
           );
           ctx.S();
         } else {
           ctx
             .d(pathOptions.dash, pathOptions.dashPhase)
             .drawRectangle(
-              margin / 2,
-              margin / 2,
-              width - margin,
-              height - margin,
-              pathOptions,
+              Math.min(margin / 2, width / 2),
+              Math.min(margin / 2, height / 2),
+              Math.max(0, width - margin),
+              Math.max(0, height - margin),
+              this._devicePathOptions(pathOptions),
             );
         }
       },
@@ -218,7 +249,28 @@ exports.rectangle = function rectangle(x, y, width, height, options = {}) {
   return this;
 };
 
-function drawRoundedRectangle(ctx, left, bottom, width, height, radii) {
+/**
+ * Append a rectangle path with rounded corners.
+ * @private
+ * @param {Object} ctx - The content context.
+ * @param {number} left - The left edge.
+ * @param {number} bottom - The bottom edge.
+ * @param {number} width - The width.
+ * @param {number} height - The height.
+ * @param {number|number[]} radii - One radius, or up to four clockwise from
+ *   the top-left corner; missing ones come from the opposite corner.
+ * @param {number} [inset=0] - How far to move the path inside the rectangle.
+ * @returns {void}
+ */
+function drawRoundedRectangle(
+  ctx,
+  left,
+  bottom,
+  width,
+  height,
+  radii,
+  inset = 0,
+) {
   let radius = [];
 
   // populate radius array accordingly.
@@ -244,6 +296,8 @@ function drawRoundedRectangle(ctx, left, bottom, width, height, radii) {
         break;
     }
   }
+  // Keep inset corners concentric with the nominal corners.
+  radius = radius.map((value) => Math.max(0, value - inset));
   const K = 0.551784;
   const right = left + width;
   const top = bottom + height;
@@ -296,8 +350,8 @@ function drawRoundedRectangle(ctx, left, bottom, width, height, radii) {
  * @name ellipse
  * @function
  * @memberof Recipe#
- * @param {number} cx x-coordinate of center point of ellipse
- * @param {number} cy y-coordinate of center point of ellipse
+ * @param {number|"center"} cx x-coordinate of center point of ellipse
+ * @param {number|"center"} cy y-coordinate of center point of ellipse
  * @param {number} rx radius length from the center point along x-axis
  * @param {number} ry radius length from the center point along y-axis
  * @param {Object} [options]
@@ -310,8 +364,12 @@ function drawRoundedRectangle(ctx, left, bottom, width, height, radii) {
  * @param {number} [options.rotation] - Accept: +/- 0 through 360. Default: 0
  * @param {number[]} [options.rotationOrigin] - [originX, originY] Default: x, y
  * @returns {Recipe} The recipe instance.
+ * @throws {TypeError} If no page is active.
  */
 exports.ellipse = function ellipse(cx, cy, rx, ry, options = {}) {
+  // null options act like omitted options.
+  if (options === null) options = {};
+  [cx, cy] = this._centrify(cx, cy);
   const { nx, ny } = this._calibrateCoordinate(cx, cy);
 
   const pathOptions = this._getPathOptions(options, nx, ny);
@@ -322,8 +380,8 @@ exports.ellipse = function ellipse(cx, cy, rx, ry, options = {}) {
 
   const drawEllipse = (ctx, x, y, w, h) => {
     const magic = 0.551784; // from https://www.tinaja.com/glib/ellipse4.pdf
-    const ox = rx * magic; // control point offset horizontal
-    const oy = ry * magic; // control point offset horizontal
+    const ox = (w / 2) * magic; // control point offset horizontal
+    const oy = (h / 2) * magic; // control point offset vertical
     const xe = x + w; // x-end, opposite corner from origin
     const ye = y + h; // y-end, opposite corner from origin
     const xm = rx; // x-middle of enclosing rectangle
@@ -359,9 +417,11 @@ exports.ellipse = function ellipse(cx, cy, rx, ry, options = {}) {
   }
 
   if (options.stroke || options.color || !options.fill) {
-    if (pathOptions.stroke !== undefined) {
-      colorModel = pathOptions.strokeModel;
-    }
+    // The fill above may have replaced colorModel; stroke with `color`.
+    colorModel =
+      pathOptions.stroke !== undefined
+        ? pathOptions.strokeModel
+        : pathOptions.colorModel;
 
     // To honor the given width and height of the enclosing rectangle ...
 
@@ -381,10 +441,10 @@ exports.ellipse = function ellipse(cx, cy, rx, ry, options = {}) {
         // ... requires adjusting the internal drawing to accomodate line thickness.
         drawEllipse(
           ctx,
-          margin,
-          margin,
-          width - pathOptions.width,
-          height - pathOptions.width,
+          Math.min(margin, rx),
+          Math.min(margin, ry),
+          Math.max(0, width - pathOptions.width),
+          Math.max(0, height - pathOptions.width),
         );
         ctx.S();
       },
@@ -394,6 +454,18 @@ exports.ellipse = function ellipse(cx, cy, rx, ry, options = {}) {
   return this;
 };
 
+/**
+ * Append a circular arc path built from Bézier segments.
+ * @private
+ * @param {Object} ctx - The content context.
+ * @param {number} x - The center x.
+ * @param {number} y - The center y.
+ * @param {number} radius - The radius.
+ * @param {number} startAngle - The start angle in degrees.
+ * @param {number} endAngle - The end angle in degrees.
+ * @param {boolean} [fromCenter=false] - Start the path at the center, for a sector.
+ * @returns {void}
+ */
 function drawArc(ctx, x, y, radius, startAngle, endAngle, fromCenter = false) {
   const TWO_PI = 2.0 * Math.PI;
   const HALF_PI = 0.5 * Math.PI;
@@ -459,8 +531,8 @@ function drawArc(ctx, x, y, radius, startAngle, endAngle, fromCenter = false) {
  * @name arc
  * @function
  * @memberof Recipe#
- * @param {number} x - the x coordinate of the arc center point
- * @param {number} y - the y coordinate of the arc center point
+ * @param {number|"center"} x - the x coordinate of the arc center point
+ * @param {number|"center"} y - the y coordinate of the arc center point
  * @param {number} radius - the distance from the given x,y coordinates from which to produce the arc
  * @param {number} [startAngle=0] - the start of the arc in degree units +/- 0 through 360. Positive values go clockwise, Negative values, counterclockwise.
  * @param {number} [endAngle=360] - the end of the arc in degree units +/- 0 through 360. Positive values go clockwise, Negative values, counterclockwise.
@@ -474,6 +546,7 @@ function drawArc(ctx, x, y, radius, startAngle, endAngle, fromCenter = false) {
  * @param {number} [options.rotation=0] - Accept: +/- 0 through 360.
  * @param {number[]} [options.rotationOrigin] - [originX, originY] Default: x, y
  * @returns {Recipe} The recipe instance.
+ * @throws {TypeError} If no page is active.
  */
 exports.arc = function arc(
   x,
@@ -483,6 +556,9 @@ exports.arc = function arc(
   endAngle = 360,
   options = {},
 ) {
+  // null options act like omitted options.
+  if (options === null) options = {};
+  [x, y] = this._centrify(x, y);
   const { nx, ny } = this._calibrateCoordinate(x, y);
   const diameter = radius * 2;
   const pathOptions = this._getPathOptions(options, nx, ny);
@@ -517,9 +593,11 @@ exports.arc = function arc(
   }
 
   if (options.stroke || options.color || !options.fill) {
-    if (pathOptions.stroke !== undefined) {
-      colorModel = pathOptions.strokeModel;
-    }
+    // The fill above may have replaced colorModel; stroke with `color`.
+    colorModel =
+      pathOptions.stroke !== undefined
+        ? pathOptions.strokeModel
+        : pathOptions.colorModel;
 
     // To honor the given width and height of the enclosing rectangle ...
 
@@ -537,7 +615,15 @@ exports.arc = function arc(
         ctx.w(pathOptions.width).d(pathOptions.dash, pathOptions.dashPhase);
 
         // ... requires adjusting the internal drawing to accomodate line thickness.
-        drawArc(ctx, radius, radius, radius - margin, sAng, eAng, sector);
+        drawArc(
+          ctx,
+          radius,
+          radius,
+          Math.max(0, radius - margin),
+          sAng,
+          eAng,
+          sector,
+        );
         if (sector) {
           ctx.h();
         } // close off path to create a circle sector.
@@ -556,13 +642,14 @@ exports.arc = function arc(
  * @name pie
  * @function
  * @memberof Recipe#
- * @param {number} x - the x coordinate of the pie center point
- * @param {number} y - the y coordinate of the pie center point
+ * @param {number|"center"} x - the x coordinate of the pie center point
+ * @param {number|"center"} y - the y coordinate of the pie center point
  * @param {number} radius - the distance from the center point to the arc
  * @param {number} [startAngle=0] - the start of the arc in degree units
  * @param {number} [endAngle=360] - the end of the arc in degree units
  * @param {Object} [options] - The path options.
  * @returns {Recipe} The recipe instance.
+ * @throws {TypeError} If no page is active.
  */
 exports.pie = function pie(x, y, radius, startAngle, endAngle, options = {}) {
   return this.arc(x, y, radius, startAngle, endAngle, {
@@ -579,14 +666,17 @@ exports.pie = function pie(x, y, radius, startAngle, endAngle, options = {}) {
  * @param {Recipe.LineStyleOptions} [options] - The line style options.
  * @param {number} [options.width] - The line width.
  * @param {number} [options.lineWidth] - Alias for width.
- * @param {number} [options.cap] - The PDF line cap style.
- * @param {number} [options.join] - The PDF line join style.
+ * @param {number} [options.cap] - The PDF line cap style, a `LineCapStyle` value.
+ * @param {number} [options.join] - The PDF line join style: 0 miter, 1 round, 2 bevel.
  * @param {number} [options.miterLimit] - The miter limit.
  * @param {number[]} [options.dash] - The dash pattern.
  * @param {number} [options.dashPhase] - The dash pattern phase.
  * @returns {Recipe} The recipe instance.
+ * @throws {TypeError} If no page is active.
  */
 exports.lineStyle = function lineStyle(options = {}) {
+  // null options act like omitted options.
+  if (options === null) options = {};
   this.current = this.current || {};
   this.current.lineStyle = this.current.lineStyle || {};
 
@@ -617,6 +707,13 @@ exports.lineStyle = function lineStyle(options = {}) {
   return this._setLineStyle(options);
 };
 
+/**
+ * Write the given line style options to the page content context.
+ * @private
+ * @param {Object} [options] - The lineStyle() options.
+ * @returns {Recipe} The recipe instance.
+ * @throws {TypeError} If no page is active.
+ */
 exports._setLineStyle = function _setLineStyle(options = {}) {
   if (options.width !== undefined || options.lineWidth !== undefined)
     this.pageContext.w(options.width ?? options.lineWidth);
@@ -639,6 +736,7 @@ exports._setLineStyle = function _setLineStyle(options = {}) {
  * @memberof Recipe#
  * @param {number} width - The line width.
  * @returns {Recipe} The recipe instance.
+ * @throws {TypeError} If no page is active.
  */
 exports.lineWidth = function lineWidth(width) {
   return this.lineStyle({ width });
@@ -652,6 +750,7 @@ exports.lineWidth = function lineWidth(width) {
  * @memberof Recipe#
  * @param {number} value - The requested opacity from 0 (transparent) to 1 (opaque).
  * @returns {Recipe} The recipe instance.
+ * @throws {RangeError} If the value is not a finite number from 0 to 1.
  */
 exports.opacity = function opacity(value) {
   if (!Number.isFinite(value) || value < 0 || value > 1) {

package/lib/recipe/xObjectForm.js

@@ -1,33 +1,52 @@
+const { Colorspace } = require("../recipe-constants");
+
+/**
+ * Writes device color operators for a color model.
+ * @private
+ */
 const Color = class Color {
+  /** Not meant to be instantiated; use the static methods. */
   constructor() {}
 
+  /**
+   * Set the fill color.
+   * @param {Object} ctx - The content context.
+   * @param {Object} colorModel - The color model from _transformColor().
+   * @returns {void}
+   */
   static fill(ctx, colorModel) {
     switch (colorModel.colorspace) {
-      case "rgb":
+      case Colorspace.RGB:
         ctx.rg(colorModel.r, colorModel.g, colorModel.b);
         break;
 
-      case "cmyk":
+      case Colorspace.CMYK:
         ctx.k(colorModel.c, colorModel.m, colorModel.y, colorModel.k);
         break;
 
-      case "gray":
+      case Colorspace.GRAY:
         ctx.g(colorModel.gray);
         break;
     }
   }
 
+  /**
+   * Set the stroke color.
+   * @param {Object} ctx - The content context.
+   * @param {Object} colorModel - The color model from _transformColor().
+   * @returns {void}
+   */
   static stroke(ctx, colorModel) {
     switch (colorModel.colorspace) {
-      case "rgb":
+      case Colorspace.RGB:
         ctx.RG(colorModel.r, colorModel.g, colorModel.b);
         break;
 
-      case "cmyk":
+      case Colorspace.CMYK:
         ctx.K(colorModel.c, colorModel.m, colorModel.y, colorModel.k);
         break;
 
-      case "gray":
+      case Colorspace.GRAY:
         ctx.G(colorModel.gray);
         break;
     }
@@ -36,7 +55,17 @@ const Color = class Color {
 
 exports.Color = Color;
 
+/**
+ * Creates a writer form XObject extended with Recipe helpers; the
+ * constructor returns the form itself.
+ * @private
+ */
 exports.xObjectForm = class xObjectForm {
+  /**
+   * @param {Object} pdfWriter - The PDF writer.
+   * @param {number} [width=100] - The form width.
+   * @param {number} [height=100] - The form height.
+   */
   constructor(pdfWriter, width = 100, height = 100) {
     const xObject = pdfWriter.createFormXObject(0, 0, width, height);
     xObject.pdfWriter = pdfWriter;
@@ -50,32 +79,61 @@ exports.xObjectForm = class xObjectForm {
     return xObject;
   }
 
+  /**
+   * Store a value on the form, such as its Recipe cache key.
+   * @param {string} key - The key.
+   * @param {*} value - The value.
+   * @returns {void}
+   */
   set(key, value) {
     this._values = this._values || {};
     this._values[key] = value;
   }
 
+  /**
+   * @param {string} key - The key.
+   * @returns {*} The stored value, or undefined.
+   */
   get(key) {
     this._values = this._values || {};
     return this._values[key];
   }
 
+  /**
+   * Map a graphics state into the form resources.
+   * @param {number} gsId - The ExtGState object ID.
+   * @returns {string} The resource name.
+   */
   getGsName(gsId) {
-    const resourcesDict = this.getResourcesDictinary();
+    const resourcesDict = this.getResourcesDictionary();
     const gsName = resourcesDict.addExtGStateMapping(gsId);
     return gsName;
   }
 
+  /**
+   * Map a color space into the form resources.
+   * @param {number} csId - The color space object ID.
+   * @returns {string} The resource name.
+   */
   getCsName(csId) {
-    const resourcesDict = this.getResourcesDictinary();
+    const resourcesDict = this.getResourcesDictionary();
     const csName = resourcesDict.addColorSpaceMapping(csId);
     return csName;
   }
 
+  /**
+   * End the form so it can be placed.
+   * @returns {void}
+   */
   end() {
     this.pdfWriter.endFormXObject(this);
   }
 
+  /**
+   * Set the fill color in the form, including separation colors.
+   * @param {Object} colorModel - The color model from _transformColor().
+   * @returns {Object} The form.
+   */
   fill(colorModel) {
     const ctx = this.getContentContext();
     switch (colorModel.colorspace) {
@@ -83,7 +141,7 @@ exports.xObjectForm = class xObjectForm {
         Color.fill(ctx, colorModel);
         break;
 
-      case "separation":
+      case Colorspace.SEPARATION:
         ctx.cs(this.getCsName(colorModel.colorspaceId));
         ctx.scn(1);
         break;
@@ -91,6 +149,11 @@ exports.xObjectForm = class xObjectForm {
     return this;
   }
 
+  /**
+   * Set the stroke color in the form, including separation colors.
+   * @param {Object} colorModel - The color model from _transformColor().
+   * @returns {Object} The form.
+   */
   stroke(colorModel) {
     const ctx = this.getContentContext();
     switch (colorModel.colorspace) {
@@ -98,7 +161,7 @@ exports.xObjectForm = class xObjectForm {
         Color.stroke(ctx, colorModel);
         break;
 
-      case "separation":
+      case Colorspace.SEPARATION:
         ctx.CS(this.getCsName(colorModel.colorspaceId));
         ctx.SCN(1);
         break;