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

package/lib/recipe/utils.js

@@ -12,6 +12,8 @@ const PAGE_CONTEXT_STATE = Object.freeze({
 /**
  * Copies nested option objects and arrays without discarding callback values.
  * @private
+ * @param {*} value - The options or value to copy.
+ * @returns {*} The copy; functions and primitives are returned as they are.
  */
 function cloneOptions(value) {
   if (Array.isArray(value)) return value.map(cloneOptions);
@@ -27,9 +29,11 @@ function cloneOptions(value) {
  * Append PDF Page with annotations.
  *
  * @param {any} pdfWriter - Hummus writer.
- * @param {string|any} sourcePDFPath - The path for the output pdfs or Reader stream.
- * @param {number} pageNumber - page number.
+ * @param {string|any} sourcePDFPath - The source PDF path or read stream.
+ * @param {number} pageNumber - The zero-based page index.
  * @private
+ * @returns {void}
+ * @throws {Error} If the source cannot be read or the page does not exist.
  */
 function appendPDFPageFromPDFWithAnnotations(
   pdfWriter,
@@ -67,8 +71,13 @@ function appendPDFPageFromPDFWithAnnotations(
  * Append PDF Pages with annotations.
  *
  * @param {any} pdfWriter - Hummus writer.
- * @param {string|any} sourcePDFPath - The path for the output pdfs or Reader stream.
+ * @param {string|any} sourcePDFPath - The source PDF path or read stream.
+ * @param {Object} [options] - The options.
+ * @param {number[][]} [options.specificRanges] - Zero-based inclusive
+ *   [start, end] page ranges; all pages when omitted.
  * @private
+ * @returns {void}
+ * @throws {Error} If the source cannot be read or a page does not exist.
  */
 function appendPDFPagesFromPDFWithAnnotations(
   pdfWriter,
@@ -97,7 +106,8 @@ function appendPDFPagesFromPDFWithAnnotations(
 
 /**
  * Resolves a text font size from `size`, its `fontSize` alias, or a fallback,
- * rejecting a size that is not greater than zero. Zero and negative sizes have
+ * rejecting a size that is not a finite number greater than zero. Zero,
+ * negative, and infinite sizes have
  * no usable meaning: they draw nothing readable and measure to nonsensical font
  * metrics, so they are reported as invalid input naming the option and the
  * value. Omitting both options, or passing `null` or `undefined`, selects the
@@ -105,7 +115,8 @@ function appendPDFPagesFromPDFWithAnnotations(
  * @param {Object} [options] - Options holding `size` or `fontSize`.
  * @param {number} [fallback] - Size used when neither option is given.
  * @returns {number} The resolved font size in PDF points.
- * @throws {RangeError} If the given size is not greater than zero.
+ * @throws {RangeError} If the given size is not a finite number greater than
+ *   zero.
  */
 function resolveFontSize(options = {}, fallback) {
   const name = options.size == null ? "fontSize" : "size";
@@ -113,7 +124,7 @@ function resolveFontSize(options = {}, fallback) {
   if (size == null) {
     return fallback;
   }
-  if (!(size > 0)) {
+  if (!(size > 0) || size === Infinity) {
     throw new RangeError(
       `Text ${name} must be a number greater than zero, received ${size}`,
     );

package/lib/recipe/vector-line.js

@@ -1,11 +1,15 @@
+const muhammara = require("../muhammara");
+const { Colorspace } = require("../recipe-constants");
+
 /**
  * move the current position to target position
  * @name moveTo
  * @function
  * @memberof Recipe#
- * @param {number} x - The coordinate x
- * @param {number} y - The coordinate y
+ * @param {number|"center"} x - The coordinate x
+ * @param {number|"center"} y - The coordinate y
  * @returns {Recipe} The recipe instance.
+ * @throws {TypeError} If no page is active.
  */
 exports.moveTo = function moveTo(x, y) {
   const { nx, ny } = this._calibrateCoordinate(x, y);
@@ -21,53 +25,95 @@ exports.moveTo = function moveTo(x, y) {
  * @name lineTo
  * @function
  * @memberof Recipe#
- * @param {number} x - The coordinate x
- * @param {number} y - The coordinate y
+ * @param {number|"center"} x - The coordinate x
+ * @param {number|"center"} y - The coordinate y
  * @param {Object} [options] - The options
  * @returns {Recipe} The recipe instance.
+ * @throws {TypeError} If no page is active.
  * @param {string|number[]} [options.color] - HexColor, PercentColor or DecimalColor
  * @param {string|number[]} [options.stroke] - HexColor, PercentColor or DecimalColor
  * @param {number} [options.lineWidth] - The line width
  * @param {number} [options.opacity] - how transparent should line be, from 0: invisible to 1: opaque
  * @param {number[]} [options.dash] - The dash pattern [dashSize, gapSize] or [dashAndGapSize]
  * @param {number} [options.dashPhase] - distance into dash pattern at which to start dash (default: 0, immediately)
- * @param {string} [options.lineCap] -  open line end style, 'butt', 'round', or 'square' (default: 'round')
- * @param {string} [options.lineJoin] - joined line end style, 'miter', 'round', or 'bevel' (default: 'round')
+ * @param {Recipe.LineCap} [options.lineCap] -  open line end style, a `Recipe.LineCap` value (default: 'round')
+ * @param {Recipe.LineJoin} [options.lineJoin] - joined line end style, a `Recipe.LineJoin` value (default: 'round')
  * @param {number} [options.miterLimit] - limit at which 'miter' joins are forced to 'bevel' (default: 1.414)
- *
  */
 exports.lineTo = function lineTo(x, y, options = {}) {
-  const fromX = this._position.x;
-  const fromY = this._position.y;
+  const from = [this._position.x, this._position.y];
   const { nx, ny } = this._calibrateCoordinate(x, y);
-  const context = this.pageContext;
+  this._strokePolyline([from, [nx, ny]], options);
+  this.moveTo(x, y);
+  return this;
+};
+
+/**
+ * Stroke one path through PDF points, so segments meet at the line join
+ * instead of overlapping, and a Separation line writes one form.
+ * @private
+ * @param {number[][]} points - Two or more [x, y] points in PDF coordinates.
+ * @param {Object} options - The line options of `lineTo()` and `line()`.
+ * @returns {void}
+ * @throws {TypeError} If no page is active.
+ */
+exports._strokePolyline = function _strokePolyline(points, options) {
+  // _getPathOptions() may pause the page to write graphics states, and an
+  // edited page resumes into a new context, so read the context afterwards.
   const pathOptions = this._getPathOptions(options);
-  pathOptions.type = "stroke";
+  const context = this.pageContext;
+  pathOptions.type = muhammara.DrawingPathType.STROKE;
 
   if (pathOptions.stroke !== undefined) {
     pathOptions.color = pathOptions.stroke;
     pathOptions.colorspace = pathOptions.strokeModel.colorspace;
   }
 
-  context
-    .q()
-    .J(pathOptions.lineCap)
-    .j(pathOptions.lineJoin)
-    .d(pathOptions.dash, pathOptions.dashPhase)
-    .M(pathOptions.miterLimit)
-    .drawPath(fromX, fromY, nx, ny, pathOptions)
-    .Q();
-  this.moveTo(x, y);
-  return this;
+  const colorModel = pathOptions.strokeModel || pathOptions.colorModel;
+  const drawLine = (ctx, originX, originY) =>
+    ctx
+      .J(pathOptions.lineCap)
+      .j(pathOptions.lineJoin)
+      .d(pathOptions.dash, pathOptions.dashPhase)
+      .M(pathOptions.miterLimit)
+      .drawPath(
+        ...points.flatMap(([px, py]) => [px - originX, py - originY]),
+        this._devicePathOptions(pathOptions),
+      );
+
+  if (colorModel.colorspace === Colorspace.SEPARATION) {
+    // A Separation color space is a resource, so draw through a form XObject
+    // as the other shapes do; the padding keeps caps and miter joins inside.
+    const padding = pathOptions.width * Math.max(1, pathOptions.miterLimit);
+    const xs = points.map((point) => point[0]);
+    const ys = points.map((point) => point[1]);
+    const left = Math.min(...xs) - padding;
+    const bottom = Math.min(...ys) - padding;
+    this._drawObject(
+      this,
+      left,
+      bottom,
+      Math.max(...xs) - Math.min(...xs) + padding * 2,
+      Math.max(...ys) - Math.min(...ys) + padding * 2,
+      {},
+      (ctx, xObject) => {
+        this._setSeparationColor(xObject, colorModel, true);
+        drawLine(ctx, left, bottom);
+      },
+    );
+  } else {
+    drawLine(context.q(), 0, 0).Q();
+  }
 };
 
 /**
- * Draw a line
+ * Draw a line through coordinate pairs, or from (startX, startY) to
+ * (endX, endY) when called as `line(startX, startY, endX, endY, options?)`.
  * @name line
  * @function
  * @memberof Recipe#
- * @param {number[]} coordinates - The array of coordinate [[x,y], [m,n]]
- * @param {Object} [options] - The options
+ * @param {number[][]|number} coordinates - The array of coordinate [[x,y], [m,n]], or the start x
+ * @param {Object} [options] - The options, or the start y in the four-number form
  * @returns {Recipe} The recipe instance.
  * @param {string|number[]} [options.color] - HexColor, PercentColor or DecimalColor
  * @param {string|number[]} [options.stroke] - HexColor, PercentColor or DecimalColor
@@ -75,20 +121,36 @@ exports.lineTo = function lineTo(x, y, options = {}) {
  * @param {number} [options.opacity] - how transparent should line be, from 0: invisible to 1: opaque
  * @param {number[]} [options.dash] - The dash pattern [dashSize, gapSize] or [dashAndGapSize]
  * @param {number} [options.dashPhase] - distance into dash pattern at which to start dash (default: 0, immediately)
- * @param {string} [options.lineCap] -  open line end style, 'butt', 'round', or 'square' (default: 'round')
- * @param {string} [options.lineJoin] - joined line end style, 'miter', 'round', or 'bevel' (default: 'round')
- * @param {number} [options.miterLimit] - limit at which 'miter' joins are forced to 'bevel' (default: 1.414)*/
+ * @param {Recipe.LineCap} [options.lineCap] -  open line end style, a `Recipe.LineCap` value (default: 'round')
+ * @param {Recipe.LineJoin} [options.lineJoin] - joined line end style, a `Recipe.LineJoin` value (default: 'round')
+ * @param {number} [options.miterLimit] - limit at which 'miter' joins are forced to 'bevel' (default: 1.414)
+ * @throws {TypeError} If no page is active.
+ */
 exports.line = function line(coordinates = [], options = {}) {
-  coordinates.forEach((coordinate, index) => {
-    if (index === 0) {
-      this.moveTo(coordinate[0], coordinate[1]);
-      if (this.editingPage) {
-        // hack to force out first line when editing page
-        this.lineTo(coordinate[0], coordinate[1], options);
-      }
-    } else {
-      this.lineTo(coordinate[0], coordinate[1], options);
-    }
-  });
-  return this;
+  // null arguments act like omitted ones.
+  if (coordinates === null) coordinates = [];
+  if (options === null) options = {};
+  if (typeof coordinates === "number") {
+    // line(startX, startY, endX, endY, options?), as in Wasm.
+    const [startX, startY, endX, endY, lineOptions = {}] = arguments;
+    coordinates = [
+      [startX, startY],
+      [endX, endY],
+    ];
+    options = lineOptions;
+  }
+  if (coordinates.length < 2) {
+    if (coordinates.length) this.moveTo(coordinates[0][0], coordinates[0][1]);
+    return this;
+  }
+  // Stroke every segment as one path, as Wasm does.
+  this._strokePolyline(
+    coordinates.map(([x, y]) => {
+      const { nx, ny } = this._calibrateCoordinate(x, y);
+      return [nx, ny];
+    }),
+    options,
+  );
+  const [lastX, lastY] = coordinates[coordinates.length - 1];
+  return this.moveTo(lastX, lastY);
 };

package/lib/recipe/vector-polygon.js

@@ -29,10 +29,20 @@
  * @param {number} [options.dashPhase] - distance into dash pattern at which to start dash (default: 0, immediately)
  * @param {number} [options.rotation] - Accept: +/- 0 through 360. Default: 0
  * @param {number[]} [options.rotationOrigin] - [originX, originY] Default: x, y
- * @param {string} [options.lineCap] -  open line end style, 'butt', 'round', or 'square' (default: 'round')
- * @param {string} [options.lineJoin] - joined line end style, 'miter', 'round', or 'bevel' (default: 'round')
- * @param {number} [options.miterLimit] - limit at which 'miter' joins are forced to 'bevel' (default: 1.414) */
+ * @param {Recipe.LineCap} [options.lineCap] -  open line end style, a `Recipe.LineCap` value (default: 'round')
+ * @param {Recipe.LineJoin} [options.lineJoin] - joined line end style, a `Recipe.LineJoin` value (default: 'round')
+ * @param {number} [options.miterLimit] - limit at which 'miter' joins are forced to 'bevel' (default: 1.414)
+ * @param {string} [options.link] - Make the polygon's bounding box open this URL.
+ * @throws {TypeError} If no page is active or there are no coordinates.
+ */
 exports.polygon = function polygon(coordinates = [], options = {}) {
+  // null options act like omitted options.
+  if (options === null) options = {};
+  if (!Array.isArray(coordinates) || coordinates.length === 0) {
+    throw new TypeError("A polygon needs at least one coordinate pair");
+  }
+  // Work on a copy so closing the path leaves the caller's array unchanged.
+  coordinates = coordinates.slice();
   // close polygon
   if (
     this._getDistance(coordinates[0], coordinates[coordinates.length - 1]) != 0
@@ -110,9 +120,11 @@ exports.polygon = function polygon(coordinates = [], 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;
 
     this._drawObject(
       this,

package/lib/recipe/vector.helper.js

@@ -1,6 +1,19 @@
 const { xObjectForm } = require("./xObjectForm");
 const { resolveFontSize } = require("./utils");
-
+const { Colorspace, LineCap, LineJoin } = require("../recipe-constants");
+
+/**
+ * Resolve drawing and text options into path options: font, size, colors
+ * and color models, line style, opacity graphics states, rotation, skew and
+ * dash. Clamps `options.opacity` to 0..1 in place.
+ * @private
+ * @param {Object} [options] - The drawing or text options.
+ * @param {number} originX - The PDF x of the default rotation origin.
+ * @param {number} originY - The PDF y of the default rotation origin.
+ * @returns {Object} The resolved path options.
+ * @throws {RangeError} If a given font size is not greater than zero.
+ * @throws {Error} If the font cannot be loaded.
+ */
 exports._getPathOptions = function _getPathOptions(
   options = {},
   originX,
@@ -47,8 +60,9 @@ exports._getPathOptions = function _getPathOptions(
   if (options.opacity == void 0 || isNaN(options.opacity)) {
     options.opacity = this.current.opacity ?? 1;
   } else {
-    options.opacity =
-      options.opacity < 0 ? 0 : options.opacity > 1 ? 1 : options.opacity;
+    // A numeric string such as "0.5" passes the isNaN check; write it as a
+    // number, as Wasm does.
+    options.opacity = Math.max(0, Math.min(1, Number(options.opacity)));
   }
   pathOptions.opacity = options.opacity;
   const extGStates = this._createExtGStates(options.opacity);
@@ -78,9 +92,13 @@ exports._getPathOptions = function _getPathOptions(
     pathOptions.fill = pathOptions.fillModel.color;
   }
 
+  // A fill or stroke replaces the default color. Resolving that default under
+  // colorName would write an unused Separation color space for the ink.
+  const paintsColor =
+    options.color || options.colour || (!options.fill && !options.stroke);
   pathOptions.colorModel = this._transformColor(
     options.color || options.colour,
-    colorOpts,
+    paintsColor ? colorOpts : { ...colorOpts, colorName: undefined },
   );
   pathOptions.color = pathOptions.colorModel.color;
   pathOptions.colorspace = pathOptions.colorModel.colorspace;
@@ -126,6 +144,13 @@ exports._getPathOptions = function _getPathOptions(
   return pathOptions;
 };
 
+/**
+ * The distance between two points.
+ * @private
+ * @param {number[]} coordA - The first [x, y] point.
+ * @param {number[]} coordB - The second [x, y] point.
+ * @returns {number} The distance.
+ */
 exports._getDistance = function _getDistance(coordA, coordB) {
   const disX = Math.abs(coordB[0] - coordA[0]);
   const disY = Math.abs(coordB[1] - coordA[1]);
@@ -136,6 +161,16 @@ exports._getDistance = function _getDistance(coordA, coordB) {
 
 exports._getTransformParams = getTransformParams;
 
+/**
+ * The transformation matrix that rotates content around an origin.
+ * @private
+ * @param {number} inAngle - The rotation in degrees.
+ * @param {number} x - The origin x.
+ * @param {number} y - The origin y.
+ * @param {number} offsetX - The content x relative to the origin.
+ * @param {number} offsetY - The content y relative to the origin.
+ * @returns {number[]} The [a, b, c, d, e, f] matrix.
+ */
 function getTransformParams(inAngle, x, y, offsetX, offsetY) {
   const theta = toRadians(inAngle);
   const cosTheta = Math.cos(theta);
@@ -145,6 +180,17 @@ function getTransformParams(inAngle, x, y, offsetX, offsetY) {
   return [cosTheta, -sinTheta, sinTheta, cosTheta, x - nx, y - ny];
 }
 
+/**
+ * Translate a content context to a point and apply the rotation options.
+ * @private
+ * @param {Object} context - The content context.
+ * @param {number} x - The PDF x.
+ * @param {number} y - The PDF y.
+ * @param {Object} options - The path options: rotation, rotationOrigin,
+ *   useGivenCoords, originX, originY and deltaY.
+ * @returns {void}
+ * @throws {TypeError} If a Recipe rotation origin is converted without an active page.
+ */
 exports._setRotationContext = function _setRotationTransform(
   context,
   x,
@@ -185,6 +231,12 @@ exports._setRotationContext = function _setRotationTransform(
   }
 };
 
+/**
+ * Whether the options carry an explicit [x, y] rotation origin.
+ * @private
+ * @param {Object} options - The path options.
+ * @returns {boolean} True for a two-element rotationOrigin array.
+ */
 function hasRotation(options) {
   return (
     options.rotationOrigin &&
@@ -193,10 +245,23 @@ function hasRotation(options) {
   );
 }
 
+/**
+ * Convert degrees to radians, wrapping at 360.
+ * @private
+ * @param {number} angle - The angle in degrees.
+ * @returns {number} The angle in radians.
+ */
 function toRadians(angle) {
   return 2 * Math.PI * ((angle % 360) / 360);
 }
 
+/**
+ * The transformation matrix for skew angles.
+ * @private
+ * @param {number} [skewXAngle=0] - The skew off the x axis, in degrees.
+ * @param {number} [skewYAngle=0] - The skew off the y axis, in degrees.
+ * @returns {number[]} The [a, b, c, d, e, f] matrix.
+ */
 function getSkewTransform(skewXAngle = 0, skewYAngle = 0) {
   const alpha = toRadians(skewXAngle);
   const beta = toRadians(skewYAngle);
@@ -206,6 +271,13 @@ function getSkewTransform(skewXAngle = 0, skewYAngle = 0) {
   return [1, tanAlpha, tanBeta, 1, 0, 0];
 }
 
+/**
+ * Apply the skew options to a content context.
+ * @private
+ * @param {Object} context - The content context.
+ * @param {Object} options - The path options: skewX and skewY.
+ * @returns {void}
+ */
 exports._setSkewContext = function _setSkewTransform(context, options) {
   if (options.skewX || options.skewY) {
     const sm = getSkewTransform(options.skewX, options.skewY);
@@ -214,12 +286,68 @@ exports._setSkewContext = function _setSkewTransform(context, options) {
   }
 };
 
+/**
+ * Apply a [scaleX, scaleY] ratio to a content context.
+ * @private
+ * @param {Object} context - The content context.
+ * @param {Object} options - The path options: ratio.
+ * @returns {void}
+ */
 exports._setScalingTransform = function _setScalingTransform(context, options) {
   if (options.ratio) {
     context.cm(options.ratio[0], 0, 0, options.ratio[1], 0, 0);
   }
 };
 
+/**
+ * Options for a low-level drawing call. A separation color is not a device
+ * color: the caller sets it on the form XObject, so the low-level call gets
+ * neither its color nor its colorspace.
+ * @private
+ * @param {Object} pathOptions - The path options.
+ * @returns {Object} The path options, or a copy without color and colorspace
+ *   for a separation color.
+ */
+exports._devicePathOptions = function _devicePathOptions(pathOptions) {
+  if (pathOptions.colorspace !== Colorspace.SEPARATION) return pathOptions;
+  const { color, colorspace, ...deviceOptions } = pathOptions;
+  return deviceOptions;
+};
+
+/**
+ * Select a Separation color in a form XObject. Device colors are left to the
+ * low-level drawing call, so their output is unchanged.
+ * @private
+ * @param {Object} xObject - The form the color is selected in.
+ * @param {Object} [colorModel] - The color model from _transformColor().
+ * @param {boolean} stroke - Select the stroking instead of the fill color.
+ * @returns {void}
+ */
+exports._setSeparationColor = function _setSeparationColor(
+  xObject,
+  colorModel,
+  stroke,
+) {
+  if (!colorModel || colorModel.colorspace !== Colorspace.SEPARATION) return;
+  if (stroke) xObject.stroke(colorModel);
+  else xObject.fill(colorModel);
+};
+
+/**
+ * Draw content through a form XObject, creating it with the callback unless
+ * `options.xObject` supplies one, then place it with rotation, skew and
+ * scaling.
+ * @private
+ * @param {Recipe} self - The recipe instance.
+ * @param {number} x - The PDF x.
+ * @param {number} y - The PDF y.
+ * @param {number} width - The form width.
+ * @param {number} height - The form height.
+ * @param {Object} options - The path options.
+ * @param {function(Object, xObjectForm): void} callback - Draws into a new form.
+ * @returns {void}
+ * @throws {Error} If no page content context is active.
+ */
 exports._drawObject = function _drawObject(
   self,
   x,
@@ -253,12 +381,19 @@ exports._drawObject = function _drawObject(
   context.doXObject(xObject).Q();
 };
 
+/**
+ * The PDF line cap number of a `Recipe.LineCap` value.
+ * @private
+ * @param {Recipe.LineCap} [type] - The cap style; round when omitted or unknown.
+ * @returns {number} 0 for butt, 1 for round, 2 for square.
+ */
 exports._lineCap = function _lineCap(type) {
   const round = 1;
   let cap = round;
 
   if (type) {
-    const capStyle = ["butt", "round", "square"];
+    // In PDF line cap order.
+    const capStyle = [LineCap.BUTT, LineCap.ROUND, LineCap.SQUARE];
     const capType = capStyle.indexOf(type);
     cap = capType !== -1 ? capType : round;
   }
@@ -266,12 +401,19 @@ exports._lineCap = function _lineCap(type) {
   return cap;
 };
 
+/**
+ * The PDF line join number of a `Recipe.LineJoin` value.
+ * @private
+ * @param {Recipe.LineJoin} [type] - The join style; round when omitted or unknown.
+ * @returns {number} 0 for miter, 1 for round, 2 for bevel.
+ */
 exports._lineJoin = function _lineJoin(type) {
   const round = 1;
   let join = round;
 
   if (type) {
-    const joinStyle = ["miter", "round", "bevel"];
+    // In PDF line join order.
+    const joinStyle = [LineJoin.MITER, LineJoin.ROUND, LineJoin.BEVEL];
     const joinType = joinStyle.indexOf(type);
     join = joinType !== -1 ? joinType : round;
   }