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

package/lib/recipe/font.js

@@ -1,23 +1,44 @@
 const fs = require("fs");
 const path = require("path");
+const { FontStyle } = require("../recipe-constants");
+
+// Keys of the per-style font files stored for each family in this.fonts.
+const FontSlot = Object.freeze({
+  REGULAR: "r",
+  BOLD: "b",
+  ITALIC: "i",
+  BOLD_ITALIC: "bi",
+});
+
 /**
  * Register a custom font
  * @name registerFont
  * @function
  * @memberof Recipe#
- * @param {string} [fontName=''] - The font name used in text.
+ * @param {string} [fontName=''] - The font name used in text, matched case-insensitively.
  * @param {string} [fontSrcPath=''] - The path to the font file.
- * @param {string} [type='regular'] - The font type, one of 'bold', 'bold-italic', 'italic'
+ * @param {Recipe.FontStyle} [type='regular'] - The style this file provides,
+ *   one of the `Recipe.FontStyle` values or its short form r, b, i or bi.
+ *   Any other value registers the regular style.
  * @returns {Recipe} The recipe instance.
  */
 exports.registerFont = function registerFont(
   fontName = "",
   fontSrcPath = "",
-  type = "regular",
+  type = FontStyle.REGULAR,
 ) {
   return this._registerFont(fontName, fontSrcPath, type);
 };
 
+/**
+ * Register every .ttf, .ttc and .otf file in the given directories, deriving
+ * the family and style from the file name (for example "Roboto-BoldItalic").
+ * Missing directories are skipped.
+ * @private
+ * @param {string|string[]} fontSrcPath - The font directory or directories.
+ * @returns {void}
+ * @throws {Error} If an existing directory cannot be read.
+ */
 exports._loadFonts = function _loadFonts(fontSrcPath) {
   const fontTypes = [".ttf", ".ttc", ".otf"];
   const fontPaths =
@@ -33,19 +54,19 @@ exports._loadFonts = function _loadFonts(fontSrcPath) {
         .forEach((file) => {
           let fontName = path.basename(file, path.extname(file)).toLowerCase();
           // simple heuristics to make sure library fonts behave as expected
-          const hasBold = fontName.indexOf("bold") !== -1;
-          const hasItalic = fontName.indexOf("italic") !== -1;
-          let type = "r";
+          const hasBold = fontName.indexOf(FontStyle.BOLD) !== -1;
+          const hasItalic = fontName.indexOf(FontStyle.ITALIC) !== -1;
+          let type = FontSlot.REGULAR;
           if (hasBold && hasItalic) {
             fontName = fontName.replace(/-*bold/, "");
             fontName = fontName.replace(/-*italic/, "");
-            type = "bi";
+            type = FontSlot.BOLD_ITALIC;
           } else if (hasBold) {
             fontName = fontName.replace(/-*bold/, "");
-            type = "b";
+            type = FontSlot.BOLD;
           } else if (hasItalic) {
             fontName = fontName.replace(/-*italic/, "");
-            type = "i";
+            type = FontSlot.ITALIC;
           }
           return this._registerFont(fontName, path.join(fpath, file), type);
         });
@@ -53,10 +74,19 @@ exports._loadFonts = function _loadFonts(fontSrcPath) {
   }
 };
 
+/**
+ * Record a font file for a family and style.
+ * @private
+ * @param {string} fontName - The family name, stored lower-cased.
+ * @param {string} fontSrcPath - The font file path.
+ * @param {Recipe.FontStyle|string} [type='regular'] - A `Recipe.FontStyle`
+ *   value or its short form; anything else is stored as regular.
+ * @returns {Recipe} The recipe instance.
+ */
 exports._registerFont = function _registerFont(
   fontName,
   fontSrcPath,
-  type = "regular",
+  type = FontStyle.REGULAR,
 ) {
   this.fonts = this.fonts || {};
   let family = fontName.toLowerCase();
@@ -64,19 +94,19 @@ exports._registerFont = function _registerFont(
 
   switch (type) {
     default:
-      font.r = fontSrcPath;
+      font[FontSlot.REGULAR] = fontSrcPath;
       break;
-    case "bold":
-    case "b":
-      font.b = fontSrcPath;
+    case FontStyle.BOLD:
+    case FontSlot.BOLD:
+      font[FontSlot.BOLD] = fontSrcPath;
       break;
-    case "italic":
-    case "i":
-      font.i = fontSrcPath;
+    case FontStyle.ITALIC:
+    case FontSlot.ITALIC:
+      font[FontSlot.ITALIC] = fontSrcPath;
       break;
-    case "bold-italic":
-    case "bi":
-      font.bi = fontSrcPath;
+    case FontStyle.BOLD_ITALIC:
+    case FontSlot.BOLD_ITALIC:
+      font[FontSlot.BOLD_ITALIC] = fontSrcPath;
       break;
   }
   this.fonts[family] = font;
@@ -84,18 +114,26 @@ exports._registerFont = function _registerFont(
   return this;
 };
 
+/**
+ * Pick the registered font file for the family and bold/italic options,
+ * falling back to Helvetica when the family, style or file is unavailable.
+ * @private
+ * @param {Recipe} self - The recipe instance.
+ * @param {Object} [options] - Text options: font, and bold/isBold, italic/isItalic.
+ * @returns {string} The font file path.
+ */
 function _getFontFile(self, options = {}) {
   let fontFile;
   // Need to choose appropriate file based on bold/italic considerations
   // Note, if this is not done explicitly, the font dimensions will be incorrect.
   let type =
     (options.bold || options.isBold) && (options.italic || options.isItalic)
-      ? "bi"
+      ? FontSlot.BOLD_ITALIC
       : options.italic || options.isItalic
-        ? "i"
+        ? FontSlot.ITALIC
         : options.bold || options.isBold
-          ? "b"
-          : "r";
+          ? FontSlot.BOLD
+          : FontSlot.REGULAR;
 
   if (options.font) {
     const fontFamily = self.fonts[options.font.toLowerCase()];
@@ -110,12 +148,19 @@ function _getFontFile(self, options = {}) {
   }
 
   if (!fontFile) {
-    fontFile = self.fonts["helvetica"]["r"]; // use default font when otherwise unavailable.
+    fontFile = self.fonts["helvetica"][FontSlot.REGULAR]; // use default font when otherwise unavailable.
   }
 
   return fontFile;
 }
 
+/**
+ * Load the writer font for text options once per font file.
+ * @private
+ * @param {Object} [options] - Text options: font, and bold/isBold, italic/isItalic.
+ * @returns {Object} The writer's used font.
+ * @throws {Error} If the font file cannot be loaded.
+ */
 exports._getFont = function _getFont(options) {
   this.current = this.current || {};
 

package/lib/recipe/graphics-state.js

@@ -4,9 +4,10 @@
  * @function
  * @memberof Recipe#
  * @param {number} degrees - Clockwise rotation in degrees.
- * @param {number} [x=0] - Rotation origin x coordinate.
- * @param {number} [y=0] - Rotation origin y coordinate.
+ * @param {number|"center"} [x=0] - Rotation origin x coordinate.
+ * @param {number|"center"} [y=0] - Rotation origin y coordinate.
  * @returns {Recipe} The recipe instance.
+ * @throws {TypeError} If no page is active.
  */
 exports.rotateContent = function rotateContent(degrees, x = 0, y = 0) {
   const radians = (degrees * Math.PI) / 180;

package/lib/recipe/htmlToTextObjects.js

@@ -1,13 +1,52 @@
 const DOMParser = require("@xmldom/xmldom").DOMParser;
 
+// HTML attribute and inline style names the parser reads.
+const HtmlAttribute = Object.freeze({
+  STYLE: "style",
+  HREF: "href",
+});
+const CssProperty = Object.freeze({
+  COLOR: "color",
+  OPACITY: "opacity",
+});
+
+// CSS color functions whose components the parser reads.
+const CssColorFunction = Object.freeze({
+  RGB: "rgb",
+});
+
+// Lower-case names of the HTML elements the parser handles.
+const HtmlTag = Object.freeze({
+  HTML: "html",
+  P: "p",
+  LI: "li",
+  UL: "ul",
+  OL: "ol",
+  H1: "h1",
+  H2: "h2",
+  H3: "h3",
+  SMALL: "small",
+  BR: "br",
+  B: "b",
+  STRONG: "strong",
+  I: "i",
+  EM: "em",
+  U: "u",
+  DEL: "del",
+  A: "a",
+});
+
 /**
  * Convert HTML into Recipe text layout objects.
  * @name htmlToTextObjects
  * @function
  * @memberof Recipe#
- * @param {string} htmlCodes - The HTML source.
+ * @param {string} htmlCodes - The HTML source. Tag names are matched case-insensitively.
  * @param {Object} [options] - Text options used to initialize the objects.
- * @returns {Object[]} The parsed text layout objects.
+ * @param {string} [options.font] - The font of every object.
+ * @param {number} [options.size] - The base font size of every object.
+ * @returns {Object[]} The parsed text layout objects: one per child node,
+ *   each with its value, tag, style flags, link, font size ratio and childs.
  */
 exports.htmlToTextObjects = function (htmlCodes, options = {}) {
   const nodes = new DOMParser().parseFromString(
@@ -18,13 +57,19 @@ exports.htmlToTextObjects = function (htmlCodes, options = {}) {
   return textObjects;
 };
 
+/**
+ * The font size multiplier of an element.
+ * @private
+ * @param {string} [tagName=''] - The element name, matched case-insensitively.
+ * @returns {number} The multiplier; 1 for elements without one.
+ */
 function getFontSizeRatio(tagName = "") {
   const fontSizeRatio = {
-    p: 1, // 14px
-    h1: 2.57, // 36px
-    h2: 2.14, // 30px
-    h3: 1.71, // 24px
-    small: 0.7,
+    [HtmlTag.P]: 1, // 14px
+    [HtmlTag.H1]: 2.57, // 36px
+    [HtmlTag.H2]: 2.14, // 30px
+    [HtmlTag.H3]: 1.71, // 24px
+    [HtmlTag.SMALL]: 0.7,
     // h4: 1.12,
     // h5: 0.83,
     // h6: 0.75
@@ -33,9 +78,21 @@ function getFontSizeRatio(tagName = "") {
   return matched ? matched : 1;
 }
 
+/**
+ * Whether an element starts its content on a new line.
+ * @private
+ * @param {string} [tagName=''] - The element name, matched case-insensitively.
+ * @returns {boolean} True for p, li and h1 to h3.
+ */
 function needsLineBreaker(tagName = "") {
-  const lineBreakers = ["p", "li", "h1", "h2", "h3"];
-  return lineBreakers.includes(tagName);
+  const lineBreakers = [
+    HtmlTag.P,
+    HtmlTag.LI,
+    HtmlTag.H1,
+    HtmlTag.H2,
+    HtmlTag.H3,
+  ];
+  return lineBreakers.includes(String(tagName).toLowerCase());
 }
 
 /**
@@ -43,12 +100,18 @@ function needsLineBreaker(tagName = "") {
  * block element, or at the start of a block. Only such text drops its
  * leading whitespace; text that follows inline content keeps one space.
  * @private
+ * @param {Object} node - The DOM text node.
+ * @returns {boolean} True when the text begins a visual line.
  */
 function startsLine(node) {
   const previous = node.previousSibling;
   if (previous) {
     const tag = (previous.tagName || "").toLowerCase();
-    return tag === "br" || needsLineBreaker(tag) || ["ul", "ol"].includes(tag);
+    return (
+      tag === HtmlTag.BR ||
+      needsLineBreaker(tag) ||
+      [HtmlTag.UL, HtmlTag.OL].includes(tag)
+    );
   }
   const parent = node.parentNode;
   const parentTag = (
@@ -57,7 +120,7 @@ function startsLine(node) {
   if (
     !parent ||
     !parentTag ||
-    parentTag === "html" ||
+    parentTag === HtmlTag.HTML ||
     needsLineBreaker(parentTag)
   ) {
     return true;
@@ -65,17 +128,37 @@ function startsLine(node) {
   return startsLine(parent);
 }
 
+/**
+ * Whether an element makes its text bold.
+ * @private
+ * @param {string} [tagName=''] - The element name, matched case-insensitively.
+ * @returns {boolean} True for b and strong.
+ */
 function isBoldTag(tagName = "") {
-  const boldTags = ["b", "strong"];
-  return boldTags.includes(tagName);
+  const boldTags = [HtmlTag.B, HtmlTag.STRONG];
+  return boldTags.includes(String(tagName).toLowerCase());
 }
 
+/**
+ * Whether an element makes its text italic.
+ * @private
+ * @param {string} [tagName=''] - The element name, matched case-insensitively.
+ * @returns {boolean} True for i and em.
+ */
 function isItalicTag(tagName = "") {
-  const italicTags = ["i", "em"];
-  return italicTags.includes(tagName);
+  const italicTags = [HtmlTag.I, HtmlTag.EM];
+  return italicTags.includes(String(tagName).toLowerCase());
 }
 
+/**
+ * Convert a DOM node and its children into a text layout object.
+ * @private
+ * @param {Object} node - The DOM node.
+ * @param {Object} options - The htmlToTextObjects() options.
+ * @returns {Object} The text layout object with its parsed childs.
+ */
 function parseNode(node, options) {
+  const tag = (node.tagName || "").toLowerCase();
   const attributes = [];
   const styles = {};
   for (let i in node.attributes) {
@@ -84,22 +167,22 @@ function parseNode(node, options) {
         name: node.attributes[i].nodeName,
         value: node.attributes[i].nodeValue,
       });
-      if (node.attributes[i].nodeName == "style") {
+      if (node.attributes[i].nodeName === HtmlAttribute.STYLE) {
         const styleValues = node.attributes[i].nodeValue.split(";");
         styleValues.forEach((element) => {
           if (element && element != "") {
             element = element.split(":");
             const key = element[0];
             let value = element[1].replace(/ /g, "");
-            if (key == "color") {
-              if (value.search("rgb") > -1) {
+            if (key === CssProperty.COLOR) {
+              if (value.search(CssColorFunction.RGB) > -1) {
                 value = value
                   .replace(/rgba?\(/, "")
                   .replace(/\)/, "")
                   .split(",")
                   .map((item) => parseFloat(item));
                 if (value.length > 3) {
-                  styles["opacity"] = value.pop();
+                  styles[CssProperty.OPACITY] = value.pop();
                 }
               }
             }
@@ -115,7 +198,11 @@ function parseNode(node, options) {
   }
   // Whitespace before a line break would only pad the end of the line.
   const next = node.nextSibling;
-  if (value !== null && next && /^br$/i.test(next.tagName || "")) {
+  if (
+    value !== null &&
+    next &&
+    (next.tagName || "").toLowerCase() === HtmlTag.BR
+  ) {
     value = value.replace(/\s+$/, "");
   }
   if (value && value.charCodeAt(0) == 8203) {
@@ -128,17 +215,24 @@ function parseNode(node, options) {
     font: options.font,
     isBold: isBoldTag(node.tagName),
     isItalic: isItalicTag(node.tagName),
-    underline: node.tagName == "u",
-    strikeOut: node.tagName == "del",
+    underline: tag === HtmlTag.U,
+    strikeOut: tag === HtmlTag.DEL,
     attributes,
     styles,
     needsLineBreaker: needsLineBreaker(node.tagName),
     // An explicit line break; text layout ends the current line here.
-    lineBreak: /^br$/i.test(node.tagName || ""),
+    lineBreak: tag === HtmlTag.BR,
     size: options.size,
     sizeRatio: getFontSizeRatio(node.tagName),
     sizeRatios: [getFontSizeRatio(node.tagName)],
-    link: node.tagName == "a" ? node.attributes[0].value : null,
+    link:
+      tag === HtmlTag.A
+        ? (
+            attributes.find(
+              (attribute) => attribute.name === HtmlAttribute.HREF,
+            ) || {}
+          ).value || null
+        : null,
     childs: [],
   };
   for (let num in node.childNodes) {
@@ -153,3 +247,6 @@ function parseNode(node, options) {
   });
   return parsedData;
 }
+
+// Shared with text layout; non-enumerable so it is not a Recipe method.
+Object.defineProperty(exports, "HtmlTag", { value: HtmlTag });

package/lib/recipe/image.js

@@ -1,11 +1,14 @@
+const muhammara = require("../muhammara");
+const { HorizontalAlign, VerticalAlign } = require("../recipe-constants");
+
 /**
  * Place images to pdf
  * @name image
  * @function
  * @memberof Recipe#
- * @param {string} imgSrc - The path for the image. [JPEG, PNG, TIFF]
- * @param {number} x - The coordinate x
- * @param {number} y - The coordinate y
+ * @param {string} imgSrc - The path for the image. [JPEG, PNG, TIFF, PDF]
+ * @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 {Object} [options] - The options
  * @returns {Recipe} The recipe instance.
  * @param {number} [options.width] - The new width
@@ -13,7 +16,14 @@
  * @param {number} [options.scale] - Scale the image from the original width and height.
  * @param {boolean} [options.keepAspectRatio=true] - Keep the aspect ratio.
  * @param {number} [options.opacity] - The opacity.
- * @param {string} [options.align] - 'center center'...
+ * @param {string} [options.align] - A `Recipe.HorizontalAlign` value, optionally
+ *   followed by a space and a `Recipe.VerticalAlign` value, for example
+ *   "center center". Horizontal center moves the image left by half its width
+ *   and right moves it right by half; vertical center moves it up by half its
+ *   height and bottom moves it down by half from its top-left placement.
+ * @param {string} [options.link] - Make the image open this URL.
+ * @throws {TypeError} If no page is active.
+ * @throws {Error} If the image cannot be read.
  */
 exports.image = function image(imgSrc, x, y, options = {}) {
   const { width, height, offsetX, offsetY } = this._getImgOffset(
@@ -22,7 +32,7 @@ exports.image = function image(imgSrc, x, y, options = {}) {
   );
   const imgOptions = {
     transformation: {
-      fit: "always",
+      fit: muhammara.ImageFit.ALWAYS,
       // proportional: true,
       width,
       height,
@@ -65,11 +75,26 @@ exports.image = function image(imgSrc, x, y, options = {}) {
   return this;
 };
 
+/**
+ * Compute the drawn size of an image and the offset its alignment applies.
+ * Sets `options.keepAspectRatio` to true when it is not given.
+ * @private
+ * @param {string} [imgSrc=''] - The image path.
+ * @param {Object} [options] - The image() options.
+ * @returns {{width: number, height: number, offsetX: number, offsetY: number}}
+ *   The drawn size and the PDF offset from the placement point.
+ * @throws {Error} If the image cannot be read.
+ */
 exports._getImgOffset = function _getImgOffset(imgSrc = "", options = {}) {
   // set default to true
   options.keepAspectRatio =
     options.keepAspectRatio == void 0 ? true : options.keepAspectRatio;
   const dimensions = this.writer.getImageDimensions(imgSrc);
+  // An unreadable image measures 0 by 0. Drawing it would leave an image
+  // object that is never written, so endPDF() could not finish the PDF.
+  if (!(dimensions.width > 0 && dimensions.height > 0)) {
+    throw new Error(`Unknown image: ${imgSrc}`);
+  }
   const ratio = dimensions.width / dimensions.height;
 
   let width = dimensions.width;
@@ -105,10 +130,10 @@ exports._getImgOffset = function _getImgOffset(imgSrc = "", options = {}) {
     const alignments = options.align.split(" ");
     if (alignments[0]) {
       switch (alignments[0]) {
-        case "center":
+        case HorizontalAlign.CENTER:
           offsetX = (-1 * width) / 2;
           break;
-        case "right":
+        case HorizontalAlign.RIGHT:
           offsetX = width / 2;
           break;
         default:
@@ -116,10 +141,10 @@ exports._getImgOffset = function _getImgOffset(imgSrc = "", options = {}) {
     }
     if (alignments[1]) {
       switch (alignments[1]) {
-        case "center":
+        case VerticalAlign.CENTER:
           offsetY = (-1 * height) / 2;
           break;
-        case "bottom":
+        case VerticalAlign.BOTTOM:
           offsetY = height / 2;
           break;
         default: