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

package/lib/recipe/text.js

@@ -379,7 +379,6 @@ exports.text = function text(text = "", x, y, options = {}) {
     let columnIndex = 1;
 
     toWriteTextObjects.some((toWriteTextObject, index) => {
-      const isHTML = toWriteTextObject.writeOptions.html;
       const { text, lineHeight, lineWidth, lineID, spaceWidth } =
         toWriteTextObject;
 
@@ -484,6 +483,9 @@ exports.text = function text(text = "", x, y, options = {}) {
           // nothing to write, so simply escape.
           return next_x;
         }
+        // The opacity and rotation path below resets x to the text box edge;
+        // text-markup annotations need the line's own start.
+        const lineX = x;
 
         if (options.underline || options.strikeOut) {
           options.lineWidth = lineWidth;
@@ -607,18 +609,38 @@ exports.text = function text(text = "", x, y, options = {}) {
 
         const { textHeight } = options;
 
+        var markupLeft = lineX;
+        var markupBottom = y - textHeight * 0.2;
+        var markupWidth = _justify ? next_x - lineX : currentLineWidth;
+        var markupHeight = textHeight * 1.4;
+        if (textBox.wrap === "clip") {
+          // Clipped runs retain the first overflowing word, so measure the
+          // drawn text instead of using the preceding fitting line's width.
+          var markupRight = Math.min(
+            lineX + new Word(text, options).dimensions.xMax,
+            nx + textBox.width,
+          );
+          var markupTop = Math.min(markupBottom + markupHeight, y + lineHeight);
+          markupLeft = Math.max(markupLeft, nx);
+          markupBottom = Math.max(markupBottom, y);
+          markupWidth = markupRight - markupLeft;
+          markupHeight = markupTop - markupBottom;
+          if (markupWidth <= 0 || markupHeight <= 0) return next_x;
+        }
+
         for (let key in targetAnnotations) {
           const subtype = this._getTextMarkupAnnotationSubtype(key);
-          if (subtype) {
+          if (subtype && targetAnnotations[key]) {
+            // Copy so the caller's markup options are not modified.
             const markupOption =
               typeof targetAnnotations[key] != "object"
                 ? {}
-                : targetAnnotations[key];
+                : { ...targetAnnotations[key] };
             const { title, open, richText, flag, icon, date, subject } =
               targetAnnotations;
             Object.assign(markupOption, {
-              height: textHeight * 1.4,
-              width: currentLineWidth,
+              height: markupHeight,
+              width: markupWidth,
               text: markupOption.text || "",
               _textHeight: textHeight,
               // add options to annotation
@@ -630,7 +652,10 @@ exports.text = function text(text = "", x, y, options = {}) {
               date: date || "",
               subject: subject || "",
             });
-            const { ox, oy } = this._reverseCoordinate(x, y - textHeight * 0.2);
+            const { ox, oy } = this._reverseCoordinate(
+              markupLeft,
+              markupBottom,
+            );
 
             this.annot(ox, oy, subtype, markupOption);
           }
@@ -639,6 +664,29 @@ exports.text = function text(text = "", x, y, options = {}) {
         return next_x;
       };
 
+      /** Queues a text link limited to the run's visible clipping region. */
+      var queueTextLink = function (content, x, y, nextX) {
+        if (!content.writeOptions.link) return;
+        var left = x;
+        var width = nextX ? nextX - x : content.lineWidth;
+        if (textBox.wrap === "clip") {
+          var right = Math.min(
+            x + new Word(content.text, content.writeOptions).dimensions.xMax,
+            nx + textBox.width,
+          );
+          left = Math.max(left, nx);
+          width = right - left;
+          if (width <= 0) return;
+        }
+        linkAnnotations.push({
+          url: content.writeOptions.link,
+          left,
+          bottom: y,
+          width,
+          height: content.lineHeight,
+        });
+      };
+
       if (!isContinued) {
         // flush out current line before processing next one
         let next_x = 0;
@@ -646,15 +694,7 @@ exports.text = function text(text = "", x, y, options = {}) {
           const x = next_x || getStartX(content.startX, content);
           const y = currentY;
           next_x = writeText(context, x, y, content);
-          if (content.writeOptions.link) {
-            linkAnnotations.push({
-              url: content.writeOptions.link,
-              left: x,
-              bottom: y,
-              width: next_x ? next_x - x : content.lineWidth,
-              height: content.lineHeight,
-            });
-          }
+          queueTextLink(content, x, y, next_x);
         });
         // The line offset from the last line in the
         // group determines Y positioning for next line.
@@ -683,6 +723,7 @@ exports.text = function text(text = "", x, y, options = {}) {
         }
 
         if (overflow && this._overflowNotifier) {
+          flushTextLinks(this, linkAnnotations);
           let orders = this._overflowNotifier(this);
           if (orders === true) {
             return true; // stop processing remaining text.
@@ -723,18 +764,16 @@ exports.text = function text(text = "", x, y, options = {}) {
 
       const startX = nx + currentLineWidth;
 
-      // This text will only ever have this strange tag when the
-      // HTML option is being used and an explicit linebreak encountered.
-      if (text != "[@@DONOT_RENDER_THIS@@]") {
-        toWriteTextObject.startX = toWriteTextObject.startX || startX;
-        toWriteContents.push(toWriteTextObject);
-      }
+      toWriteTextObject.startX = toWriteTextObject.startX || startX;
+      toWriteContents.push(toWriteTextObject);
 
       // To handle text that has been split in middle of word,
-      // need to decide if current text ends with a space.
+      // need to decide if current text ends with a space. HTML segments carry
+      // their own separating space, so adding one unconditionally in HTML mode
+      // measured every line a space wider than it is drawn and pushed aligned
+      // lines left.
       currentLineWidth +=
-        lineWidth +
-        (isHTML || toWriteTextObject.text.endsWith(" ") ? spaceWidth : 0);
+        lineWidth + (toWriteTextObject.text.endsWith(" ") ? spaceWidth : 0);
 
       // Processing last text object?
       if (index === toWriteTextObjects.length - 1) {
@@ -753,15 +792,7 @@ exports.text = function text(text = "", x, y, options = {}) {
           const x = next_x || getStartX(content.startX, content);
           const y = currentY;
           next_x = writeText(context, x, y, content);
-          if (content.writeOptions.link) {
-            linkAnnotations.push({
-              url: content.writeOptions.link,
-              left: x,
-              bottom: y,
-              width: next_x ? next_x - x : content.lineWidth,
-              height: content.lineHeight,
-            });
-          }
+          queueTextLink(content, x, y, next_x);
         }
 
         // Flush any left over text objects.
@@ -772,23 +803,29 @@ exports.text = function text(text = "", x, y, options = {}) {
     });
 
     if (clipResult && typeof textBox.onClip === "function") {
-      // The active text operation owns the page context until it returns.
+      // The callback may finish the page or start drawing on another one.
+      flushTextLinks(this, linkAnnotations);
       textBox.onClip(this, clipResult);
     }
   }
 
-  linkAnnotations.forEach((annotation) => {
+  flushTextLinks(this, linkAnnotations);
+  return this;
+};
+
+/** Writes pending text links before a callback can change the active page. @private */
+function flushTextLinks(recipe, annotations) {
+  for (var annotation of annotations.splice(0)) {
     linkPdf(
-      this,
+      recipe,
       annotation.url,
       annotation.left,
       annotation.bottom,
       annotation.width,
       annotation.height,
     );
-  });
-  return this;
-};
+  }
+}
 
 exports._layoutText = function _layoutText(textObjects, textBox, pathOptions) {
   let totalHeight = 0;
@@ -831,19 +868,52 @@ exports._layoutText = function _layoutText(textObjects, textBox, pathOptions) {
 
   let firstLineHeight;
   let toWriteTextObjects = [];
-  /** Reports whether a layout node contains content other than the break sentinel. */
+  /** Reports whether a layout node contains text, not only line breaks. */
   const hasRenderableContent = (textObject) =>
     (textObject.value !== undefined &&
       textObject.value !== null &&
-      textObject.value !== "" &&
-      textObject.value !== "[@@DONOT_RENDER_THIS@@]") ||
+      textObject.value !== "") ||
     textObject.childs?.some(hasRenderableContent);
 
+  /** Adds laid-out objects, recording the first line height. */
+  const addLaidOutObjects = (newToWriteObjects, paragraphHeight) => {
+    toWriteTextObjects = [...toWriteTextObjects, ...newToWriteObjects];
+
+    if (!firstLineHeight) {
+      this._lineHeight = firstLineHeight = toWriteTextObjects[0].lineHeight;
+      if (!this._firstLineHeight) {
+        this._firstLineHeight = this._lineHeight; // used in textbox coordinate computation
+      }
+    }
+    totalHeight += paragraphHeight;
+  };
+
   const writeValue = (textObject) => {
     textObject.lineID = textObject.lineID || Date.now() * Math.random();
-    textObject.lineID = textObject.needsLineBreaker
-      ? Date.now() * Math.random()
-      : textObject.lineID;
+    textObject.lineID =
+      textObject.needsLineBreaker || textObject.lineBreak
+        ? Date.now() * Math.random()
+        : textObject.lineID;
+    if (textObject.lineBreak) {
+      // A line break lays out as one empty line sized like its text; the
+      // normalization below turns it into line state, never into text.
+      const { toWriteTextObjects: newToWriteObjects, paragraphHeight } =
+        makeTextObjects(
+          this,
+          Object.assign({}, textObject, { value: "" }),
+          pathOptions,
+          textBox,
+        );
+      const lineBreak = newToWriteObjects[newToWriteObjects.length - 1];
+      lineBreak.lineBreak = true;
+      // Flowed text marks the last word of the previous line, so an empty
+      // break line still carries one empty word.
+      if (!lineBreak.wordsInLine.length) {
+        lineBreak.wordsInLine.push(new Word("", pathOptions));
+      }
+      addLaidOutObjects(newToWriteObjects, paragraphHeight);
+      return;
+    }
     // Want to allow empty string to pass through. Undefined and null elements, stay out!
     if (textObject.value !== undefined && textObject.value !== null) {
       textObject.styles.color = textObject.styles.color
@@ -851,16 +921,7 @@ exports._layoutText = function _layoutText(textObjects, textBox, pathOptions) {
         : pathOptions.color;
       const { toWriteTextObjects: newToWriteObjects, paragraphHeight } =
         makeTextObjects(this, textObject, pathOptions, textBox);
-
-      toWriteTextObjects = [...toWriteTextObjects, ...newToWriteObjects];
-
-      if (!firstLineHeight) {
-        this._lineHeight = firstLineHeight = toWriteTextObjects[0].lineHeight;
-        if (!this._firstLineHeight) {
-          this._firstLineHeight = this._lineHeight; // used in textbox coordinate computation
-        }
-      }
-      totalHeight += paragraphHeight;
+      addLaidOutObjects(newToWriteObjects, paragraphHeight);
     }
     if (textObject.tag && textObject.childs.length) {
       // console.log(textObject);
@@ -931,14 +992,18 @@ exports._layoutText = function _layoutText(textObjects, textBox, pathOptions) {
       });
     }
   };
+  // Top-level nodes share a line, as children of a block element do, so
+  // inline runs outside any element are not split onto separate lines.
+  const topLevelLineID = Date.now() * Math.random();
   textObjects.forEach((textObject) => {
+    textObject.lineID = textObject.lineID || topLevelLineID;
     writeValue(textObject);
   });
 
   const normalizedTextObjects = [];
   let pendingBreaks = [];
   const replacementLineIDs = new Map();
-  /** Converts pending break sentinels into line state without rendering their text. */
+  /** Converts pending line breaks into line state: blank lines and line IDs. */
   const appendPendingBreaks = (nextTextObject) => {
     const previous = normalizedTextObjects[normalizedTextObjects.length - 1];
     if (previous) previous.lineComplete = true;
@@ -963,12 +1028,13 @@ exports._layoutText = function _layoutText(textObjects, textBox, pathOptions) {
     pendingBreaks = [];
   };
   toWriteTextObjects.forEach((textObject, index, objects) => {
-    const sentinel = textObject.text.trim() == "[@@DONOT_RENDER_THIS@@]";
-    const beforeSentinel =
+    // Whitespace that only precedes a line break would start a blank line.
+    const beforeLineBreak =
+      !textObject.lineBreak &&
       textObject.text.trim() == "" &&
-      objects[index + 1]?.text.trim() == "[@@DONOT_RENDER_THIS@@]";
-    if (beforeSentinel) return;
-    if (sentinel) {
+      objects[index + 1]?.lineBreak;
+    if (beforeLineBreak) return;
+    if (textObject.lineBreak) {
       pendingBreaks.push(textObject);
       return;
     }
@@ -1297,7 +1363,8 @@ function makeTextObjects(self, textObject = {}, pathOptions, textBox = {}) {
     opacity: parseFloat(textObject.styles.opacity || pathOptions.opacity || 1),
     underline: textObject.underline || pathOptions.underline,
     strikeOut: textObject.strikeOut || pathOptions.strikeOut,
-    size: textObject.size,
+    // Text outside any HTML element has no inherited size of its own.
+    size: size,
     alignHorizontal: alignHorizontal,
     alignVertical: alignVertical,
     font: self._getFont(textObject),
@@ -1339,7 +1406,7 @@ function makeTextObjects(self, textObject = {}, pathOptions, textBox = {}) {
     const previousLine = toWriteTextObjects[end];
     let lineComplete, fini;
 
-    if (text === "" && !self._flow) {
+    if (text === "" && !self._flow && !textObject.lineBreak) {
       // turning off flow with empty text so
       previousLine.lastLine = true; // need to make previous line, the last.
     }

package/lib/recipe/utils.js

@@ -1,5 +1,28 @@
 const ANNOTATION_PREFIX = "Annots";
 
+/** Recipe page content-stream lifecycle states. */
+const PAGE_CONTEXT_STATE = Object.freeze({
+  IDLE: "idle",
+  ACTIVE_NEW: "active-new",
+  ACTIVE_EDIT: "active-edit",
+  PAUSED_NEW: "paused-new",
+  PAUSED_EDIT: "paused-edit",
+});
+
+/**
+ * Copies nested option objects and arrays without discarding callback values.
+ * @private
+ */
+function cloneOptions(value) {
+  if (Array.isArray(value)) return value.map(cloneOptions);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, item]) => [key, cloneOptions(item)]),
+    );
+  }
+  return value;
+}
+
 /**
  * Append PDF Page with annotations.
  *
@@ -72,7 +95,36 @@ 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
+ * 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
+ * fallback.
+ * @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.
+ */
+function resolveFontSize(options = {}, fallback) {
+  const name = options.size == null ? "fontSize" : "size";
+  const size = options[name];
+  if (size == null) {
+    return fallback;
+  }
+  if (!(size > 0)) {
+    throw new RangeError(
+      `Text ${name} must be a number greater than zero, received ${size}`,
+    );
+  }
+  return size;
+}
+
 exports.ANNOTATION_PREFIX = ANNOTATION_PREFIX;
+exports.PAGE_CONTEXT_STATE = PAGE_CONTEXT_STATE;
+exports.cloneOptions = cloneOptions;
+exports.resolveFontSize = resolveFontSize;
 exports.appendPDFPageFromPDFWithAnnotations =
   appendPDFPageFromPDFWithAnnotations;
 exports.appendPDFPagesFromPDFWithAnnotations =

package/lib/recipe/vector.helper.js

@@ -1,4 +1,5 @@
 const { xObjectForm } = require("./xObjectForm");
+const { resolveFontSize } = require("./utils");
 
 exports._getPathOptions = function _getPathOptions(
   options = {},
@@ -13,7 +14,7 @@ exports._getPathOptions = function _getPathOptions(
     originX,
     originY,
     font: this._getFont(options),
-    size: options.size || this.current.defaultFontSize,
+    size: resolveFontSize(options, this.current.defaultFontSize),
     charSpace: options.charSpace || 0,
     underline: false,
     strikeOut: false,
@@ -54,12 +55,6 @@ exports._getPathOptions = function _getPathOptions(
   pathOptions.strokeGsId = extGStates.stroke;
   pathOptions.fillGsId = extGStates.fill;
 
-  if (options.size || options.fontSize) {
-    const size = options.size || options.fontSize;
-    if (!isNaN(size)) {
-      pathOptions.size = size <= 0 ? 1 : size;
-    }
-  }
   if (options.width || options.lineWidth) {
     const width = options.width || options.lineWidth;
     if (!isNaN(width)) {

package/lib/recipe/vector.js

@@ -668,7 +668,6 @@ exports.opacity = function opacity(value) {
  * @name fill
  * @function
  * @memberof Recipe#
- * @param {string|number[]} [color] - The requested fill color.
  * @returns {Recipe} The recipe instance.
  */
 exports.fill = function fill() {
@@ -682,7 +681,6 @@ exports.fill = function fill() {
  * @name stroke
  * @function
  * @memberof Recipe#
- * @param {string|number[]} [color] - The requested stroke color.
  * @returns {Recipe} The recipe instance.
  */
 exports.stroke = function stroke() {

package/muhammara.d.ts

@@ -109,6 +109,7 @@ declare namespace muhammara {
   }
 
   export interface GraphicOptions extends ColorOptions {
+    /** "clip" intersects the clipping region without painting; scope with q()/Q(). */
     type?: "stroke" | "fill" | "clip";
     width?: number;
     close?: boolean;
@@ -215,11 +216,15 @@ declare namespace muhammara {
     ): this;
     TJ(value: string | Glyph, options?: TextRenderOptions): this;
     writeFreeCode(freeCode: string): this;
+    /** Require at least two complete finite coordinate pairs; invalid input emits no operators. */
     drawPath(...parameters: any[]): this; // This can't be materialized in TypeScript
     ////drawPath(...xyPairs: number[], options: GraphicOptions): this;
     drawPath(xyPairs: Array<[number, number]>, options: GraphicOptions): this;
+    /** Coordinates, radius, and calculated circle geometry must remain finite. */
     drawCircle(x: PosX, y: PosY, r: number, options?: GraphicOptions): this;
+    /** Coordinates and edge length must be finite. */
     drawSquare(x: PosX, y: PosY, l: number, options?: GraphicOptions): this;
+    /** Coordinates and dimensions must be finite. */
     drawRectangle(
       x: PosX,
       y: PosY,
@@ -227,6 +232,7 @@ declare namespace muhammara {
       h: number,
       options?: GraphicOptions,
     ): this;
+    /** Coordinates, font size, and calculated underline geometry must remain finite. */
     writeText(text: string, x: PosX, y: PosY, options?: WriteTextOptions): this;
     drawImage(
       x: PosX,
@@ -287,7 +293,8 @@ declare namespace muhammara {
   export interface PDFWriterToContinueOptions {
     modifiedFilePath?: string;
     modifiedStream?: PDFRStreamForFile; // TODO
-    log?: string;
+    /** Log file path or synchronous byte writer returning the number of bytes written. */
+    log?: string | ByteWriter;
   }
 
   export interface PDFRecryptOptions extends PDFWriterOptions {
@@ -863,6 +870,7 @@ declare namespace muhammara {
       source: FilePath | ReadStream,
       options?: AppendOptions,
     ): number[];
+    /** Calls the optional callback with no arguments and globalThis as its receiver. */
     mergePDFPagesToPage(
       page: PDFPage,
       file: FilePath | PDFRStreamForFile,
@@ -1226,6 +1234,7 @@ declare namespace muhammara {
       /** Make the rendered text open this URL. */
       link?: string;
       charSpace?: number;
+      /** Text fill color: `#gg`, `#rrggbb`, `#ccmmyykk`, `%r,g,b` percentages, a 0-255 component array, or a name registered with `chroma()`. Missing or unknown colors use `#1777d1`. */
       color?: Color;
       colorspace?: Colorspace;
       flow?: boolean;
@@ -1235,9 +1244,9 @@ declare namespace muhammara {
       rotation?: number;
       rotationOrigin?: readonly [number, number];
       font?: string;
-      /** Font size in points for text() and textDimensions(); defaults to 14 when both fontSize and size are omitted. */
+      /** Font size in points for text() and textDimensions(); defaults to 14 when both fontSize and size are omitted. A size that is not greater than zero throws RangeError. */
       fontSize?: number;
-      /** Font size in points for text() and textDimensions(); defaults to 14. */
+      /** Font size in points for text() and textDimensions(); defaults to 14. A size that is not greater than zero throws RangeError. */
       size?: number;
       bold?: boolean;
       italic?: boolean;
@@ -1301,14 +1310,20 @@ declare namespace muhammara {
       name: Field;
       text?: string;
       width?: number;
+      /** Cell text-box options, including onClip callbacks preserved during table layout. */
       cell?: TextBox;
+      /** Header text styles, independent of body styles; booleans use the default header style. Table-level header options take precedence. */
       header?: boolean | TextOptions;
+      /** Final header text-box overrides, applied after header styles and alignToData. */
       hcell?: TextBox;
       renderer?: (
         this: void,
+        /** The own cell value; missing, inherited, and nullish values arrive as `""`. */
         text: undefined extends TableFieldValue<RecordType, Field>
-          ? Exclude<TableFieldValue<RecordType, Field>, undefined> | ""
-          : TableFieldValue<RecordType, Field>,
+          ? Exclude<TableFieldValue<RecordType, Field>, null | undefined> | ""
+          : null extends TableFieldValue<RecordType, Field>
+            ? Exclude<TableFieldValue<RecordType, Field>, null | undefined> | ""
+            : TableFieldValue<RecordType, Field>,
         record: RecordType,
         field: Field,
         row: number,
@@ -1335,16 +1350,20 @@ declare namespace muhammara {
     interface TableOptions<
       RecordType extends object = Record<string, unknown>,
     > extends Omit<TextOptions, "overflow"> {
+      /** Per-segment height, also bounded by the current page's bottom margin. */
       height?: number;
+      /** Comma-separated names are trimmed; array entries preserve exact keys. */
       order?:
         | string
         | TableField<RecordType>[]
         | readonly [TableField<RecordType>, ...TableField<RecordType>[]];
       columns?: readonly TableColumnOptions<RecordType>[];
+      /** Enables headers and overrides column header styles; body text styles are not inherited. */
       header?:
         boolean | (TextOptions & { alignToData?: boolean; cell?: TextBox });
       border?: boolean | PolygonOptions;
       row?: TextOptions & { nth?: "even" | "odd"; cell?: TextBox };
+      /** Called once per overflow. A continuing destination must fit the row and repeated header or table() throws RangeError; ending the page without starting another throws Error. */
       overflow?: (
         this: Recipe,
         recipe: Recipe,
@@ -1363,6 +1382,8 @@ declare namespace muhammara {
       attributes: Array<{ name: string; value: string | null }>;
       styles: Record<string, string | number | number[]>;
       needsLineBreaker: boolean;
+      /** True for a `<br>` element, which ends the current line. */
+      lineBreak: boolean;
       size: number | undefined;
       sizeRatio: number;
       sizeRatios: number[];
@@ -1697,9 +1718,9 @@ declare namespace muhammara {
     lineWidth(width: number): Recipe;
     /** Set fill and stroke opacity from 0 (transparent) to 1 (opaque). */
     opacity(opacity: number): Recipe;
-    fill(color?: Recipe.Color): Recipe;
-    stroke(color?: Recipe.Color): Recipe;
-    fillAndStroke(fill?: Recipe.Color, stroke?: Recipe.Color): Recipe;
+    fill(): Recipe;
+    stroke(): Recipe;
+    fillAndStroke(): Recipe;
     n_gon(
       cx: number,
       cy: number,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@muhammara/native-core",
-  "version": "7.0.0-beta.2",
+  "version": "7.0.0-beta.4",
   "description": "Shared JavaScript API for MuhammaraJS native packages",
   "homepage": "https://muhammarajs.readthedocs.io/",
   "license": "Apache-2.0",