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

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,9 +1,17 @@
-function clone(object) {
-  return JSON.parse(JSON.stringify(object));
-}
+var { htmlToTextObjects } = require("./htmlToTextObjects");
+var { cloneOptions: clone } = require("./utils");
+var { LineCap, TableRowNth } = require("../recipe-constants");
 
+/**
+ * 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") {
-  const cellOptions = clone(options);
+  var cellOptions = clone(options);
 
   if (cellOptions[cell]) {
     // convert cell options to textBox options
@@ -13,65 +21,141 @@ function getCellOptions(options, cell = "cell") {
   return cellOptions;
 }
 
+/**
+ * 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) {
-  let colOptions = self._merge(options, { textBox: { width: column.width } });
-  const originCoord = self._calibrateCoordinate(
+  var colOptions = self._merge(options, { textBox: { width: column.width } });
+  var originCoord = self._calibrateCoordinate(
     column.x,
     column.y,
     0,
     0,
     self.pageNumber,
   );
-  const pathOptions = self._getPathOptions(
+  var pathOptions = self._getPathOptions(
     colOptions,
     originCoord.nx,
     originCoord.ny,
   );
-  const textObjects = self._makeTextObject(text, pathOptions.size, colOptions);
-  const textBox = self._makeTextBox(colOptions);
-  const { textHeight } = self._layoutText(textObjects, textBox, pathOptions);
-
-  return textHeight;
+  pathOptions.html = colOptions.html;
+  var textObjects = colOptions.html
+    ? htmlToTextObjects(text, colOptions)
+    : self._makeTextObject(text, pathOptions.size, colOptions);
+  var textBox = self._makeTextBox(colOptions);
+  var { textHeight } = self._layoutText(textObjects, textBox, pathOptions);
+
+  return (
+    textBox.height ||
+    Math.max(
+      textBox.minHeight,
+      textHeight + textBox.paddingTop + textBox.paddingBottom,
+    )
+  );
 }
 
+/**
+ * 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) {
-  if (options.border) {
-    let borderOptions = options.border === true ? {} : options.border;
+  // A segment without rows has nothing to enclose.
+  if (!options.border || height <= 0) {
+    return;
+  }
+  var borderOptions = Object.assign(
+    {},
+    options.border === true ? {} : options.border,
+    // Keep borders from extending outside of the enclosing box.
+    { lineCap: LineCap.BUTT },
+  );
+  if (!borderOptions.width) {
+    borderOptions.width = 0.5;
+  }
 
-    if (!borderOptions.width) {
-      borderOptions = Object.assign({}, borderOptions, { width: 0.5 });
-    }
+  self.rectangle(x, y, width, height, borderOptions);
+  var columns = self._layouts["_table_"];
+
+  // Draw verticals
+  for (var index = 0; index < columns.length - 1; index++) {
+    var column = columns[index];
+    self.line(
+      [
+        [column.x + column.width, y],
+        [column.x + column.width, y + height],
+      ],
+      borderOptions,
+    );
+  }
+  // Draw horizontals; the last row line is the rectangle's bottom edge.
+  for (var index = 0; index < rowLines.length - 1; index++) {
+    var yPos = rowLines[index];
+    self.line(
+      [
+        [x, yPos],
+        [x + width, yPos],
+      ],
+      borderOptions,
+    );
+  }
+}
 
-    self.rectangle(x, y, width, height, borderOptions);
-    const columns = self._layouts["_table_"];
-
-    // Draw verticles
-    for (let index = 0; index < columns.length - 1; index++) {
-      const column = columns[index];
-      self.line(
-        [
-          [column.x + column.width, y],
-          [column.x + column.width, y + height],
-        ],
-        borderOptions,
-      );
-    }
-    // Draw horizontals
-    for (let index = 0; index < rowLines.length - 1; index++) {
-      const yPos = rowLines[index];
-      self.line(
-        [
-          [x, yPos],
-          [x + width, yPos],
-        ],
-        borderOptions,
-      );
+/**
+ * Resolves the table's data fields: `order` when given, otherwise the names
+ * 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) {
+    return typeof options.order === "string"
+      ? options.order
+          .split(",")
+          .map((field) => field.trim())
+          .filter(Boolean)
+      : options.order.slice();
+  }
+  if (options.columns && options.columns.length) {
+    return options.columns.map((column) => column.name);
+  }
+  var fields = [];
+  for (var record of contents) {
+    for (var field of Object.keys(record || {})) {
+      if (!fields.includes(field)) {
+        fields.push(field);
+      }
     }
   }
+  return fields;
 }
 
 /**
  * Display text data in tabular form
+ * Rows and headers use their rendered text-box heights, including padding,
+ * minimum heights, fixed heights, and HTML layout. Empty contents or no selected
+ * columns leave the Recipe unchanged. Array-form order preserves exact keys.
+ * Header text styles are independent of body styles: column header options
+ * (or defaults) are overridden by table header options, then alignToData
+ * and column hcell box overrides are applied.
  * @name table
  * @function
  * @memberof Recipe#
@@ -108,107 +192,101 @@ function drawTableBorder(self, x, y, width, height, rowLines, options) {
  * @param {function} [options.overflow] - Called when the next table entry is going to expand the table
  * beyond the given height or page boundary. Its parameters are (self, row) where 'self' is the recipe handle so
  * that other recipe interfaces can be called, and the row number of the data which caused the data overflow.
+ * The callback's `this` is also the Recipe instance.
  * The return value can be 'true' which indicates that data processing should stop, or 'false' which indicates that
  * the data should continue being processed with the original [x,y] coordinates, or it can be an object containing
  * 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.
+ * @throws {Error} If the overflow callback continues after ending the page
+ * without starting another one.
  */
 exports.table = function table(x, y, contents, options = {}) {
-  let tableBottom = options.height ? y + options.height : 0;
-  let fields = Object.keys(contents[0]);
-  let order = options.order || [];
-  let columns = [];
-
-  if (order.length !== 0) {
-    if (typeof options.order === "string") {
-      order = options.order.split(",");
-    }
-  } else {
-    if (!options.columns || options.columns.length > fields.length) {
-      order = fields; // all fields emitted, columns in order of first record
-    } else {
-      // columns in order found in options
-      for (const column of options.columns) {
-        order.push(column.name);
-      }
-    }
+  if (!Array.isArray(contents) || contents.length === 0) {
+    return this;
   }
-
-  for (const field of order) {
-    if (fields.includes(field)) {
-      let found = false;
-      if (options.columns) {
-        for (const column of options.columns) {
-          if (column.name && column.name === field) {
-            columns.push(column);
-            found = true;
-            break;
-          }
-        }
-      }
-
-      if (!found) {
-        columns.push({ text: field, name: field });
-      }
-    }
+  var columns = tableFields(contents, options).map((field) => {
+    var column =
+      options.columns &&
+      options.columns.find((definition) => definition.name === field);
+    return column || { text: field, name: field };
+  });
+  if (columns.length === 0) {
+    return this;
   }
   this.layout("_table_", x, y, 0, 0, { columns: columns, reset: true });
 
-  const tableWidth = this._layouts["_table_"].reduce((width, column) => {
+  var tableWidth = this._layouts["_table_"].reduce((width, column) => {
     width += column.width;
     return width;
   }, 0);
 
-  let tableHeight = 0;
-  let headerHeight = 0;
-  let rowLines = [];
-  let currentY = y;
   this._previousTextObjects = [];
-  let nth;
-  let rowOptions = {};
+  var nth;
+  var rowOptions = {};
+
+  /** Resolves header styles identically for measurement and drawing. */
+  var headerOptions = (column) => {
+    var colOptions = clone(column.options.header);
+    if (typeof options.header === "object") {
+      colOptions = this._merge(colOptions, getCellOptions(options.header));
+    }
+    // Have header alignment match data alignment?
+    if (options.header.alignToData && column.options.textBox.textAlign) {
+      colOptions.textBox.textAlign = column.options.textBox.textAlign;
+    }
+    // Is there a specific header cell override in this column?
+    if (column.options.hcell) {
+      var cellOptions = getCellOptions(column.options, "hcell");
+      colOptions.textBox = this._merge(
+        colOptions.textBox,
+        clone(cellOptions.textBox),
+      );
+    }
+    return colOptions;
+  };
 
+  var headerHeight = 0;
   if (options.header) {
-    // Wade through columns to determine minimum header height
-    for (const column of this._layouts["_table_"]) {
-      let colOptions = clone(column.options.header);
-      if (typeof options.header === "object") {
-        const cellOptions = getCellOptions(options.header);
-        colOptions = this._merge(colOptions, cellOptions);
-      }
-
-      const cellHeight = getCellHeight(this, column.text, column, colOptions);
+    for (var column of this._layouts["_table_"]) {
+      var cellHeight = getCellHeight(
+        this,
+        column.text,
+        column,
+        headerOptions(column),
+      );
       headerHeight = Math.max(headerHeight, cellHeight);
     }
   }
 
-  if (options.overflow) {
-    this._tableFullNotifier = options.overflow;
-
-    const pageBottom =
+  /** Recomputes bounds for each continuation position and page. */
+  var segmentBottom = (top) => {
+    var bottom = options.height ? top + options.height : 0;
+    var pageBottom =
       this.pageInfo(this.pageNumber).height - this._margin.bottom;
-    if (tableBottom === 0 || tableBottom > pageBottom) {
-      tableBottom = pageBottom;
+    if (bottom === 0 || bottom > pageBottom) {
+      bottom = pageBottom;
     }
-  }
-
-  if (options.border) {
-    options.border.lineCap = "butt"; // keep borders from extending outside of enclosing box.
-  }
+    return bottom;
+  };
 
   if (options.row) {
     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;
         };
@@ -221,46 +299,78 @@ exports.table = function table(x, y, contents, options = {}) {
     }
   }
 
-  let firstTime = true;
-  let row = 0;
+  var tableBottom = options.overflow ? segmentBottom(y) : 0;
+  var tableHeight = 0;
+  var rowLines = [];
+  var currentY = y;
+  var firstTime = true;
+  var row = 0;
 
-  for (const record of contents) {
-    let rowHeight = 0;
+  for (var record of contents) {
     row++;
 
-    // Wade through row data to determine row height
-    for (const column of this._layouts["_table_"]) {
-      const field = column.field;
-      const text = record[field];
-      if (text !== undefined) {
-        let colOptions = clone(options);
-        colOptions = this._merge(colOptions, clone(column.options));
-        if (nth && nth(row)) {
-          colOptions = this._merge(colOptions, clone(rowOptions));
+    // Resolve every cell once: the renderer runs once per cell, and its
+    // options size the row as well as style the drawn text.
+    var cells = this._layouts["_table_"].map((column) => {
+      var field = column.field;
+      var value = Object.prototype.hasOwnProperty.call(record, field)
+        ? record[field]
+        : undefined;
+      var text = value === undefined || value === null ? "" : value;
+      var colOptions = clone(options);
+      // The table callback is not a text-flow overflow callback.
+      delete colOptions.overflow;
+      colOptions = this._merge(colOptions, clone(column.options));
+      if (nth && nth(row)) {
+        colOptions = this._merge(colOptions, clone(rowOptions));
+      }
+      if (column.options.renderer) {
+        var renderOptions = column.options.renderer(text, record, field, row);
+        if (renderOptions) {
+          colOptions = this._merge(colOptions, renderOptions);
         }
-        const cellHeight = getCellHeight(this, text, column, colOptions);
-        rowHeight = Math.max(rowHeight, cellHeight);
       }
+      return { column, text: String(text), options: colOptions };
+    });
+
+    var rowHeight = 0;
+    for (var cell of cells) {
+      var cellHeight = getCellHeight(
+        this,
+        cell.text,
+        cell.column,
+        cell.options,
+      );
+      rowHeight = Math.max(rowHeight, cellHeight);
     }
 
     // When table gets 'full', let user know when overflow callback provided.
     // They can choose to bail out of table filling loop, or keep on going with
     // appropriate variables reset to initial values. This gives the user the
     // opportunity to change to a new page to continue table production with
-    // remaining rows of data.
-    if (currentY + rowHeight > tableBottom && this._tableFullNotifier) {
+    // remaining rows of data. A continuation reserves room for its repeated
+    // header as well as the row.
+    var needed = rowHeight + (firstTime && options.header ? headerHeight : 0);
+    if (options.overflow && currentY + needed > tableBottom) {
       drawTableBorder(this, x, y, tableWidth, tableHeight, rowLines, options);
 
-      const orders = this._tableFullNotifier(this, row);
+      var orders = options.overflow.call(this, this, row);
 
       if (orders === true) {
-        return this;
-      } // stop processing table data
-      if (orders.position) {
+        // stop processing table data
+        tableHeight = 0;
+        break;
+      }
+      if (!this.page) {
+        throw new Error(
+          "Recipe.table: the overflow callback must leave an active page to continue on.",
+        );
+      }
+      if (orders && orders.position) {
         [x, y] = orders.position;
-        let xx = x;
+        var xx = x;
         // Make sure x position adjusted in all columns
-        for (const column of this._layouts["_table_"]) {
+        for (var column of this._layouts["_table_"]) {
           column.x = xx;
           xx += column.width;
         }
@@ -270,32 +380,18 @@ exports.table = function table(x, y, contents, options = {}) {
       currentY = y;
       tableHeight = 0;
       rowLines = [];
+      tableBottom = segmentBottom(y);
+      if (currentY + rowHeight + headerHeight > tableBottom) {
+        throw new RangeError(
+          `Recipe.table: row ${row} and its header do not fit in the continuation area.`,
+        );
+      }
     }
 
     if (firstTime && options.header) {
       // Display table header
-      for (const column of this._layouts["_table_"]) {
-        let colOptions = clone(column.options.header);
-        if (typeof options.header === "object") {
-          const cellOptions = getCellOptions(options.header);
-          colOptions = this._merge(colOptions, clone(cellOptions));
-        }
-
-        // Have header alignment match data alignment?
-        if (options.header.alignToData && column.options.textBox.textAlign) {
-          colOptions.textBox.textAlign = column.options.textBox.textAlign;
-        }
-
-        // Is there a specific header cell override in this column?
-        if (column.options.hcell) {
-          const cellOptions = getCellOptions(column.options, "hcell");
-          colOptions.textBox = this._merge(
-            colOptions.textBox,
-            clone(cellOptions.textBox),
-          );
-        }
-
-        colOptions = this._merge(colOptions, {
+      for (var column of this._layouts["_table_"]) {
+        var colOptions = this._merge(headerOptions(column), {
           textBox: { minHeight: headerHeight, width: column.width },
         });
         this.text(column.text, column.x, currentY, colOptions);
@@ -309,27 +405,11 @@ exports.table = function table(x, y, contents, options = {}) {
     firstTime = false;
 
     // Now write out table cells for current record
-    for (const column of this._layouts["_table_"]) {
-      const field = column.field;
-      let text = record[field];
-      if (text === undefined) {
-        text = "";
-      }
-      let colOptions = clone(options);
-      colOptions = this._merge(colOptions, clone(column.options));
-      if (nth && nth(row)) {
-        colOptions = this._merge(colOptions, clone(rowOptions));
-      }
-      if (column.options.renderer) {
-        let renderOptions = column.options.renderer(text, record, field, row);
-        if (renderOptions) {
-          colOptions = this._merge(colOptions, renderOptions);
-        }
-      }
-      colOptions = this._merge(colOptions, {
-        textBox: { minHeight: rowHeight, width: column.width },
+    for (var cell of cells) {
+      var colOptions = this._merge(cell.options, {
+        textBox: { minHeight: rowHeight, width: cell.column.width },
       });
-      this.text(text, column.x, currentY, colOptions);
+      this.text(cell.text, cell.column.x, currentY, colOptions);
     }
 
     currentY += rowHeight;
@@ -339,5 +419,12 @@ exports.table = function table(x, y, contents, options = {}) {
 
   drawTableBorder(this, x, y, tableWidth, tableHeight, rowLines, options);
 
+  // Leave the text cursor at the table's left edge, below its last segment.
+  this.x = x;
+  this.y = currentY;
+  this.box = { x, y: currentY };
+  this._flow = false;
+  this._previousTextObjects = [];
+
   return this;
 };