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

package/lib/recipe/split.js

@@ -8,8 +8,12 @@ const utils = require("./utils");
  * @function
  * @memberof Recipe#
  * @param {string} [outputDir=''] - The path for the output PDFs.
- * @param {string} [prefix] - The output filename prefix. Defaults to the source filename.
- * @returns {Recipe} The recipe instance.
+ * @param {string} [prefix] - The output filename prefix. Defaults to the
+ *   source filename; pass one for a Buffer source, which has no filename.
+ * @returns {Recipe} The recipe instance. Each page is written to
+ *   `<outputDir>/<prefix>-<pageNumber>.pdf`.
+ * @throws {Error} If the source reader was released by endPDF(), or an output
+ *   file cannot be written.
  */
 exports.split = function split(outputDir = "", prefix) {
   prefix = prefix || this.filename;

package/lib/recipe/table.js

@@ -1,7 +1,15 @@
 var { htmlToTextObjects } = require("./htmlToTextObjects");
 var { cloneOptions: clone } = require("./utils");
+var { LineCap, TableRowNth } = require("../recipe-constants");
 
-/** Converts a table cell style into text options. */
+/**
+ * Convert a table cell style into text options: a copy of the options with
+ * the cell entry moved to `textBox`.
+ * @private
+ * @param {Object} options - The table, header, row or column options.
+ * @param {string} [cell='cell'] - The key holding the cell style, "cell" or "hcell".
+ * @returns {Object} The text options.
+ */
 function getCellOptions(options, cell = "cell") {
   var cellOptions = clone(options);
 
@@ -13,7 +21,16 @@ function getCellOptions(options, cell = "cell") {
   return cellOptions;
 }
 
-/** Measures the same text and outer box height that text() will draw. */
+/**
+ * Measure the outer box height text() will draw for a cell.
+ * @private
+ * @param {Recipe} self - The recipe instance.
+ * @param {string} text - The cell text or HTML.
+ * @param {Object} column - The table layout column: x, y and width.
+ * @param {Object} options - The cell text options.
+ * @returns {number} The box height, including padding and minimum height.
+ * @throws {TypeError} If no page is active.
+ */
 function getCellHeight(self, text, column, options) {
   var colOptions = self._merge(options, { textBox: { width: column.width } });
   var originCoord = self._calibrateCoordinate(
@@ -44,7 +61,19 @@ function getCellHeight(self, text, column, options) {
   );
 }
 
-/** Draws a completed table segment without duplicating its bottom edge. */
+/**
+ * Draw the border of a completed table segment without duplicating its
+ * bottom edge.
+ * @private
+ * @param {Recipe} self - The recipe instance.
+ * @param {number} x - The segment left.
+ * @param {number} y - The segment top.
+ * @param {number} width - The segment width.
+ * @param {number} height - The segment height; nothing is drawn when 0.
+ * @param {number[]} rowLines - The y of every row bottom.
+ * @param {Object} options - The table options; `border` enables drawing.
+ * @returns {void}
+ */
 function drawTableBorder(self, x, y, width, height, rowLines, options) {
   // A segment without rows has nothing to enclose.
   if (!options.border || height <= 0) {
@@ -54,7 +83,7 @@ function drawTableBorder(self, x, y, width, height, rowLines, options) {
     {},
     options.border === true ? {} : options.border,
     // Keep borders from extending outside of the enclosing box.
-    { lineCap: "butt" },
+    { lineCap: LineCap.BUTT },
   );
   if (!borderOptions.width) {
     borderOptions.width = 0.5;
@@ -92,6 +121,9 @@ function drawTableBorder(self, x, y, width, height, rowLines, options) {
  * of the configured `columns`, otherwise every field found in any record, in
  * first-seen order.
  * @private
+ * @param {Object[]} contents - The table records.
+ * @param {Object} options - The table options.
+ * @returns {string[]} The field names, in column order.
  */
 function tableFields(contents, options) {
   if (options.order && options.order.length) {
@@ -166,9 +198,10 @@ function tableFields(contents, options) {
  * a 'position' property indicating the [x,y] coordinates where the next table for the remaining data should start.
  * @param {object} [options.row] - text properties to be applied to all cells in a table row.
  * @param {object} [options.row.cell] - All textBox options from the 'text' interface can be used here.
- * @param {string} [options.row.nth] - 'even|odd', indicating that the properties should be applied only to
- * 'even' or 'odd' rows.
+ * @param {Recipe.TableRowNth} [options.row.nth] - A `Recipe.TableRowNth` value, indicating that the
+ * properties should be applied only to 'even' or 'odd' rows.
  * @returns {Recipe} The recipe instance.
+ * @throws {TypeError} If no page is active.
  * @throws {RangeError} If the overflow callback continues into an area too small
  * for the pending row and its repeated header. Return true to stop, or provide
  * enough space; rows are not split and the callback is called once per overflow.
@@ -248,12 +281,12 @@ exports.table = function table(x, y, contents, options = {}) {
     rowOptions = getCellOptions(options.row);
 
     switch (options.row.nth) {
-      case "even":
+      case TableRowNth.EVEN:
         nth = (row) => {
           return row % 2 === 0;
         };
         break;
-      case "odd":
+      case TableRowNth.ODD:
         nth = (row) => {
           return row % 2 !== 0;
         };

package/lib/recipe/text.helper.js

@@ -1,13 +1,29 @@
 var { cloneOptions, resolveFontSize } = require("./utils");
+var { HorizontalAlign, VerticalAlign } = require("../recipe-constants");
 
+/**
+ * The width character spacing adds between the characters of a text.
+ * @private
+ * @param {string} text - The text.
+ * @param {number} charSpace - The spacing added after each character but the last.
+ * @returns {number} The added width.
+ */
 const charSpacing = function charSpacing(text, charSpace) {
-  let txt = text.replace(/^(?:(?!\u00a0)\s)+|(?:(?!\u00a0)\s)+$/g, "");
-  return txt.length ? (txt.length - 1) * charSpace : 0;
+  var characterCount = Array.from(String(text)).length;
+  return characterCount ? (characterCount - 1) * charSpace : 0;
 };
 
 // Have to set up word as a constant, then export it below
 // so that Line can see it. Otherwise, an error is thrown.
 
+/**
+ * A word used by Recipe text layout.
+ * @name Word
+ * @class
+ * @memberof Recipe#
+ * @param {string} word - The word, a single space measured as "o".
+ * @param {Object} pathOptions - The resolved text options: font, size and charSpace.
+ */
 const Word = class Word {
   constructor(word, pathOptions) {
     this._value = word;
@@ -16,10 +32,17 @@ const Word = class Word {
     this._text = word === " " ? "o" : word; // allows space to get an actual dimension
   }
 
+  /**
+   * @returns {string} The word text.
+   */
   get value() {
     return this._value;
   }
 
+  /**
+   * The measured text box, including character spacing; cached.
+   * @returns {Object} xMin, yMin, xMax, yMax, width and height.
+   */
   get dimensions() {
     if (this._dimensions) {
       return this._dimensions;
@@ -32,14 +55,26 @@ const Word = class Word {
     return this._dimensions;
   }
 
+  /**
+   * @returns {boolean} Whether this is the last word of its line.
+   */
   get last() {
     return this._last;
   }
 
+  /**
+   * @returns {number} The width character spacing adds to the word.
+   */
   get charSpacing() {
     return charSpacing(this._text, this._pathOptions.charSpace);
   }
 
+  /**
+   * Mark the word as the last of its line, trimming trailing space and
+   * measuring it again.
+   * @param {boolean} [value=true] - Whether the word is last.
+   * @returns {void}
+   */
   lastWord(value = true) {
     // indicate last word in line (for justification)
     this._last = value;
@@ -75,9 +110,19 @@ exports.Word = Word; // ... now export Word to the rest of the library.
  * @param {number} size - The font size.
  * @param {Object} pathOptions - The resolved text options.
  */
+// The width of a line without a text box. No text reaches it, so such a line
+// accepts every word without measuring.
+const UNBOUNDED_LINE_WIDTH = 999999999;
+
 exports.Line = class Line {
+  /**
+   * @param {number} [width] - The available width; unlimited when omitted.
+   * @param {number} [height] - A fixed line height.
+   * @param {number} [size] - The font size; defaults to the text options size.
+   * @param {Object} pathOptions - The resolved text options.
+   */
   constructor(width, height, size, pathOptions) {
-    this._width = width || 999999999;
+    this._width = width || UNBOUNDED_LINE_WIDTH;
     this._height = height;
     this._pathOptions = pathOptions;
     this.size = size || pathOptions.size;
@@ -85,41 +130,75 @@ exports.Line = class Line {
     this.wordObjects = [];
   }
 
+  /**
+   * Replace the line ID; falsy values are ignored.
+   * @param {number} id - The new ID.
+   */
   set lineID(id) {
     if (id) {
       this._lineID = id;
     }
   }
 
+  /**
+   * @returns {number} The line ID, grouping objects laid out on one line.
+   */
   get lineID() {
     return this._lineID;
   }
 
+  /**
+   * @param {Word} wordObject - The word to append.
+   * @returns {void}
+   */
   addWord(wordObject) {
     this.wordObjects.push(wordObject);
   }
 
+  /**
+   * Append leading spaces.
+   * @param {number} amount - The number of spaces.
+   * @returns {void}
+   */
   indent(amount) {
     for (let i = 0; i < amount; i++) {
       this.addWord(new Word(" ", this._pathOptions));
     }
   }
 
+  /**
+   * Mark the final word as the last of the line.
+   * @returns {void}
+   */
   markLastWord() {
     if (this.wordObjects.length > 0) {
       this.wordObjects[this.wordObjects.length - 1].lastWord();
     }
   }
 
+  /**
+   * @returns {Word|undefined} The final word, or undefined for an empty line.
+   */
   get lastWord() {
     return this.wordObjects[this.wordObjects.length - 1];
   }
 
+  /**
+   * @param {string} text - The text.
+   * @returns {number} The width character spacing adds to the text.
+   */
   charSpacing(text) {
     return charSpacing(text, this._pathOptions.charSpace);
   }
 
+  /**
+   * @param {Word} wordObject - The word to test.
+   * @returns {boolean} Whether the line still fits its width with the word appended.
+   */
   canFit(wordObject) {
+    // Measuring the whole line for every word is quadratic in its length, and
+    // a line without a text box never wraps.
+    if (this._width >= UNBOUNDED_LINE_WIDTH) return true;
     const tempValue = this.value + wordObject.value;
     const toWidth =
       this._pathOptions.font.calculateTextDimensions(tempValue, this.size)
@@ -127,6 +206,11 @@ exports.Line = class Line {
     return toWidth <= this.width;
   }
 
+  /**
+   * Replace the final word and mark the new one as last.
+   * @param {Word|string} wordObject - The replacement word.
+   * @returns {void}
+   */
   replaceLastWord(wordObject) {
     if (typeof wordObject === "string") {
       wordObject = new Word(wordObject, this._pathOptions);
@@ -136,14 +220,23 @@ exports.Line = class Line {
     wordObject.lastWord();
   }
 
+  /**
+   * @returns {Word[]} The words of the line.
+   */
   get words() {
     return this.wordObjects;
   }
 
+  /**
+   * @returns {number} The width of one space, measured as "o".
+   */
   get spaceWidth() {
     return this._pathOptions.font.calculateTextDimensions("o", this.size).width;
   }
 
+  /**
+   * @returns {string} The text of the line.
+   */
   get value() {
     const value = this.wordObjects.reduce((string, word) => {
       string += word.value;
@@ -152,6 +245,9 @@ exports.Line = class Line {
     return value;
   }
 
+  /**
+   * @returns {number} The measured width of the line text.
+   */
   get currentWidth() {
     return (
       this._pathOptions.font.calculateTextDimensions(this.value, this.size)
@@ -159,6 +255,9 @@ exports.Line = class Line {
     );
   }
 
+  /**
+   * @returns {number} The sum of the measured word widths.
+   */
   get textWidth() {
     return this.wordObjects.reduce((width, word) => {
       width += word.dimensions.xMax;
@@ -166,11 +265,17 @@ exports.Line = class Line {
     }, 0);
   }
 
+  /**
+   * @returns {number} The available width.
+   */
   get width() {
     return this._width;
   }
 
   // dynamic adjust height based on word height?
+  /**
+   * @returns {number} The fixed height, or the measured text height plus 20.
+   */
   get height() {
     if (this._height) {
       return this._height;
@@ -187,6 +292,12 @@ exports.Line = class Line {
  * Get the offset for a text box.
  * @private
  * @todo handle page margin and padding
+ * @param {Object} textBox - The laid-out text box: width, height, textHeight,
+ *   firstLineHeight and isSimpleText.
+ * @param {Object} [options] - The text options.
+ * @param {string} [options.align] - A `Recipe.HorizontalAlign` value,
+ *   optionally followed by a space and a `Recipe.VerticalAlign` value.
+ * @returns {{offsetX: number, offsetY: number}} The offset from the placement point.
  */
 exports._getTextBoxOffset = function _getTextBoxOffset(textBox, options = {}) {
   let offsetX = 0;
@@ -196,10 +307,10 @@ exports._getTextBoxOffset = function _getTextBoxOffset(textBox, 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;
           break;
         default:
@@ -208,12 +319,12 @@ exports._getTextBoxOffset = function _getTextBoxOffset(textBox, options = {}) {
     if (alignments[1]) {
       height = height || textHeight;
       switch (alignments[1]) {
-        case "center":
+        case VerticalAlign.CENTER:
           offsetY = textBox.isSimpleText
             ? -textBox.firstLineHeight / 2
             : height / 2 + offsetY;
           break;
-        case "bottom":
+        case VerticalAlign.BOTTOM:
           offsetY = height + offsetY;
           break;
         default:
@@ -237,9 +348,14 @@ exports._getTextBoxOffset = function _getTextBoxOffset(textBox, options = {}) {
  * @param {string} [options.font='helvetica'] - name of font from which measurements are to be taken
  * @param {number} [options.size=14] - size of font to be used in taking measurements
  * @param {number} [options.charSpace=0] - character spacing being applied to the given text.
+ * @param {boolean} [options.bold] - Measure with the bold style of the font.
+ * @param {boolean} [options.italic] - Measure with the italic style of the font.
  * @returns {Object} measurement components of given text: width, height, xMin, xMax, yMin, yMax
+ * @throws {Error} If the font file cannot be loaded.
  */
 exports.textDimensions = function textDimensions(text, options = {}) {
+  // null options act like omitted options.
+  if (options === null) options = {};
   const font = this._getFont(options);
   let dimensions = {};
   let charSpaces = 0;
@@ -270,6 +386,15 @@ exports.textDimensions = function textDimensions(text, options = {}) {
  * @param {Object} [options] - The column options.
  */
 exports.Column = class Column {
+  /**
+   * @param {number} x - The x coordinate.
+   * @param {number} y - The y coordinate.
+   * @param {number} width - The column width.
+   * @param {number} [height] - The column height; unlimited when omitted.
+   * @param {string} [text=''] - The column heading; defaults to the field.
+   * @param {string} [field=''] - The associated data field.
+   * @param {Object} [options] - The column options; `cell` becomes the text box.
+   */
   constructor(x, y, width, height, text = "", field = "", options = {}) {
     this._x = x;
     this._y = y;
@@ -294,7 +419,10 @@ exports.Column = class Column {
     if (!this._options.header || typeof this._options.header === "boolean") {
       this._options.header = {
         bold: true,
-        textBox: { padding: 2, textAlign: "center center" },
+        textBox: {
+          padding: 2,
+          textAlign: `${HorizontalAlign.CENTER} ${VerticalAlign.CENTER}`,
+        },
       };
     }
 
@@ -303,39 +431,75 @@ exports.Column = class Column {
     }
   }
 
+  /**
+   * @returns {number} The column width.
+   */
   get width() {
     return this._width;
   }
+  /**
+   * @returns {number} The column height.
+   */
   get height() {
     return this._height;
   }
+  /**
+   * @returns {number} The column x coordinate.
+   */
   get x() {
     return this._x;
   }
+  /**
+   * @param {number} x - The new x coordinate.
+   */
   set x(x) {
     this._x = x;
   }
+  /**
+   * @returns {number} The column y coordinate.
+   */
   get y() {
     return this._y;
   }
+  /**
+   * @returns {number[]} The column [x, y] position.
+   */
   get position() {
     return [this._x, this._y];
   }
+  /**
+   * @param {number[]} pos - The new [x, y] position.
+   */
   set position(pos) {
     [this._x, this._y] = pos;
   }
+  /**
+   * @returns {number} The gap after the column.
+   */
   get gap() {
     return this._gap;
   }
+  /**
+   * @param {number} gap - The new gap after the column.
+   */
   set gap(gap) {
     this._gap = gap;
   }
+  /**
+   * @returns {string} The associated data field.
+   */
   get field() {
     return this._field;
   }
+  /**
+   * @returns {string} The column heading.
+   */
   get text() {
     return this._text;
   }
+  /**
+   * @returns {Object} The column text options.
+   */
   get options() {
     return this._options;
   }