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

package/lib/recipe/text.helper.js

@@ -1,11 +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;
@@ -14,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;
@@ -30,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;
@@ -73,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;
@@ -83,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)
@@ -125,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);
@@ -134,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;
@@ -150,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)
@@ -157,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;
@@ -164,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;
@@ -185,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;
@@ -194,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:
@@ -206,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:
@@ -235,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;
@@ -246,7 +364,7 @@ exports.textDimensions = function textDimensions(text, options = {}) {
     if (options.charSpace) {
       charSpaces = charSpacing(text, options.charSpace);
     }
-    const fontSize = options.size || this.current.defaultFontSize;
+    const fontSize = resolveFontSize(options, this.current.defaultFontSize);
     dimensions = font.calculateTextDimensions(text, fontSize);
     dimensions.xMax += charSpaces;
   }
@@ -268,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;
@@ -276,7 +403,7 @@ exports.Column = class Column {
     this._field = field; // associated data field
     this._text = text || field; // for column title
     this._gap = 0;
-    this._options = JSON.parse(JSON.stringify(options)); // cloning
+    this._options = cloneOptions(options);
 
     this._options.textBox = this._options.cell;
 
@@ -292,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}`,
+        },
       };
     }
 
@@ -301,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;
   }