documentation-hub 5.7.2

package/src/services/document/blanklines/helpers/clearCustom.ts

@@ -0,0 +1,121 @@
+/**
+ * Clears Structured Document Tags (SDTs) from a document, unwrapping their content.
+ * Ported from Document.ts clearCustom(), clearCustomInTable(),
+ * unwrapNestedStructuredDocumentTags(), and sanitizeTableRowExceptions().
+ *
+ * SDTs are wrappers added by tools like Google Docs that can interfere with
+ * document processing. This function removes them while preserving content.
+ */
+
+import {
+  Document,
+  Paragraph,
+  Table,
+  TableCell,
+  StructuredDocumentTag,
+} from "docxmlater";
+
+// Use any[] for unwrapped body since getBodyElements() may return
+// types beyond Paragraph | Table | StructuredDocumentTag (e.g., TableOfContentsElement)
+type BodyElement = any;
+
+/**
+ * Removes all SDT wrappers from the document, unwrapping their content
+ * into the body elements array. Also sanitizes table row exceptions
+ * that would otherwise cause formatting leakage outside the SDT context.
+ *
+ * Ported from Document.ts clearCustom() (lines 15119-15154)
+ */
+export function clearCustom(doc: Document): void {
+  const bodyElements = doc.getBodyElements();
+  const unwrappedBody: BodyElement[] = [];
+
+  for (const element of bodyElements) {
+    if (element instanceof StructuredDocumentTag) {
+      // Unwrap SDT: add its content directly to the body
+      const sdtContent = element.getContent();
+      for (const item of sdtContent) {
+        if (item instanceof Table) {
+          // Sanitize tblPrEx from table rows when coming out of SDT
+          sanitizeTableRowExceptions(item);
+          unwrappedBody.push(item);
+        } else if (item instanceof Paragraph) {
+          unwrappedBody.push(item);
+        } else if (item instanceof StructuredDocumentTag) {
+          // Recursively handle nested SDTs
+          unwrapNestedSDTs(item, unwrappedBody);
+        }
+      }
+    } else if (element instanceof Table) {
+      // Process table: unwrap SDTs inside cells
+      clearCustomInTable(element);
+      unwrappedBody.push(element);
+    } else {
+      unwrappedBody.push(element);
+    }
+  }
+
+  // Replace body elements with unwrapped content
+  doc.setBodyElements(unwrappedBody);
+}
+
+/**
+ * Sanitizes table property exceptions from all rows in a table.
+ * Clears tblPrEx (row-level table property overrides) to prevent formatting
+ * from leaking when tables are relocated outside SDT context.
+ *
+ * Ported from Document.ts sanitizeTableRowExceptions() (lines 15169-15182)
+ */
+function sanitizeTableRowExceptions(table: Table): void {
+  const rows = table.getRows();
+
+  for (const row of rows) {
+    const exceptions = row.getTablePropertyExceptions();
+
+    if (exceptions && Object.keys(exceptions).length > 0) {
+      row.setTablePropertyExceptions(undefined as any);
+    }
+  }
+}
+
+/**
+ * Recursively unwraps nested SDTs, adding their content to the target array.
+ *
+ * Ported from Document.ts unwrapNestedStructuredDocumentTags() (lines 15188-15202)
+ */
+function unwrapNestedSDTs(
+  sdt: StructuredDocumentTag,
+  targetArray: BodyElement[]
+): void {
+  const content = sdt.getContent();
+
+  for (const item of content) {
+    if (item instanceof Paragraph || item instanceof Table) {
+      targetArray.push(item);
+    } else if (item instanceof StructuredDocumentTag) {
+      unwrapNestedSDTs(item, targetArray);
+    }
+  }
+}
+
+/**
+ * Processes a table's cells to clear SDTs inside them.
+ *
+ * Ported from Document.ts clearCustomInTable() (lines 15209-15233)
+ * Note: The original implementation's inner loop body was empty.
+ */
+function clearCustomInTable(table: Table): void {
+  const rows = table.getRows();
+
+  for (const row of rows) {
+    const cells = row.getCells();
+
+    for (const cell of cells) {
+      if (!(cell instanceof TableCell)) {
+        continue;
+      }
+      // Original implementation iterates cell paragraphs but doesn't modify them.
+      // Nested tables in cells are handled separately via getAllTables().
+    }
+  }
+}

package/src/services/document/blanklines/helpers/contextChecks.ts

@@ -0,0 +1,117 @@
+/**
+ * Functions for checking paragraph context (list context, etc.).
+ * These need access to body elements via the Document public API.
+ * Ported from docxmlater Document.ts private methods.
+ */
+
+import { Document, Paragraph, Table, TableCell } from "docxmlater";
+
+/**
+ * Checks if a non-list paragraph is "within" a list context.
+ * A paragraph is within a list context if it has no numbering,
+ * and the previous and next list items share the same numId.
+ * Ported from Document.ts:8302-8348
+ */
+export function isWithinListContext(doc: Document, index: number): boolean {
+  const current = doc.getBodyElementAt(index);
+  if (!(current instanceof Paragraph)) {
+    return false;
+  }
+
+  // If current is a list item, it's not "within" - it IS the list
+  const currentNum = current.getNumbering();
+  if (currentNum) {
+    return false;
+  }
+
+  // Find previous list item (scanning backwards)
+  let prevNumId: number | undefined;
+  for (let i = index - 1; i >= 0; i--) {
+    const el = doc.getBodyElementAt(i);
+    if (el instanceof Paragraph) {
+      const num = el.getNumbering();
+      if (num) {
+        prevNumId = num.numId;
+        break;
+      }
+    } else if (el instanceof Table) {
+      // Stop at table boundaries
+      break;
+    }
+  }
+
+  // Find next list item (scanning forwards)
+  let nextNumId: number | undefined;
+  const count = doc.getBodyElementCount();
+  for (let i = index + 1; i < count; i++) {
+    const el = doc.getBodyElementAt(i);
+    if (el instanceof Paragraph) {
+      const num = el.getNumbering();
+      if (num) {
+        nextNumId = num.numId;
+        break;
+      }
+    } else if (el instanceof Table) {
+      // Stop at table boundaries
+      break;
+    }
+  }
+
+  // Within list context only if both prev and next are same list
+  return (
+    prevNumId !== undefined &&
+    nextNumId !== undefined &&
+    prevNumId === nextNumId
+  );
+}
+
+/**
+ * Checks if a paragraph is within a list context inside a table cell.
+ * Ported from Document.ts:8359-8389
+ */
+export function isWithinListContextInCell(
+  cell: TableCell,
+  paraIndex: number
+): boolean {
+  const cellParas = cell.getParagraphs();
+  const current = cellParas[paraIndex];
+  if (!current) return false;
+
+  // If current is a list item, it's not "within" - it IS the list
+  const currentNum = current.getNumbering();
+  if (currentNum) {
+    return false;
+  }
+
+  // Find previous list item in cell
+  let prevNumId: number | undefined;
+  for (let i = paraIndex - 1; i >= 0; i--) {
+    const para = cellParas[i];
+    if (para) {
+      const num = para.getNumbering();
+      if (num) {
+        prevNumId = num.numId;
+        break;
+      }
+    }
+  }
+
+  // Find next list item in cell
+  let nextNumId: number | undefined;
+  for (let i = paraIndex + 1; i < cellParas.length; i++) {
+    const para = cellParas[i];
+    if (para) {
+      const num = para.getNumbering();
+      if (num) {
+        nextNumId = num.numId;
+        break;
+      }
+    }
+  }
+
+  return (
+    prevNumId !== undefined &&
+    nextNumId !== undefined &&
+    prevNumId === nextNumId
+  );
+}

package/src/services/document/blanklines/helpers/imageChecks.ts

@@ -0,0 +1,51 @@
+/**
+ * Pure functions for checking image-related paragraph characteristics.
+ * Ported from docxmlater Document.ts public/private methods.
+ */
+
+import { Paragraph, ImageRun, Image, Revision } from "docxmlater";
+
+const EMU_PER_PIXEL = 9525; // At 96 DPI
+
+/**
+ * Checks if an image is "small" (both dimensions < 100 pixels).
+ * Ported from Document.ts:8423-8428
+ */
+export function isImageSmall(image: Image): boolean {
+  const widthPx = image.getWidth() / EMU_PER_PIXEL;
+  const heightPx = image.getHeight() / EMU_PER_PIXEL;
+  return widthPx < 100 && heightPx < 100;
+}
+
+/**
+ * Checks if a paragraph contains a small image (< 100x100 pixels).
+ * Ported from Document.ts:8448-8453
+ */
+export function isSmallImageParagraph(para: Paragraph): boolean {
+  const imageRun = getImageRunFromParagraph(para);
+  if (!imageRun) return false;
+  const image = imageRun.getImageElement();
+  return isImageSmall(image);
+}
+
+/**
+ * Extracts the first ImageRun from a paragraph, including from Revision elements.
+ * Ported from Document.ts:8474-8491
+ */
+export function getImageRunFromParagraph(para: Paragraph): ImageRun | null {
+  const content = para.getContent();
+  for (const item of content) {
+    if (item instanceof ImageRun) {
+      return item;
+    }
+    // Also check inside Revision objects (tracked changes)
+    if (item instanceof Revision) {
+      for (const revContent of item.getContent()) {
+        if (revContent instanceof ImageRun) {
+          return revContent;
+        }
+      }
+    }
+  }
+  return null;
+}

package/src/services/document/blanklines/helpers/paragraphChecks.ts

@@ -0,0 +1,236 @@
+/**
+ * Pure functions for checking paragraph content characteristics.
+ * Ported from docxmlater Document.ts private methods.
+ * Most operate only on Paragraph/Run/etc. instances with no Document dependency.
+ * Exception: getEffectiveLeftIndent() requires Document to resolve style-inherited indentation.
+ */
+
+import {
+  Document,
+  Paragraph,
+  Run,
+  Hyperlink,
+  ImageRun,
+  Shape,
+  TextBox,
+  Field,
+  Revision,
+} from "docxmlater";
+
+/**
+ * Checks if a paragraph is blank (no meaningful content).
+ * Ported from Document.ts:8146-8215
+ */
+export function isParagraphBlank(para: Paragraph): boolean {
+  const content = para.getContent();
+
+  // No content at all
+  if (!content || content.length === 0) {
+    return true;
+  }
+
+  // Check all content items
+  for (const item of content) {
+    // Hyperlinks count as content
+    if (item instanceof Hyperlink) {
+      return false;
+    }
+
+    // ImageRun (images embedded in runs) count as content
+    // IMPORTANT: Check ImageRun BEFORE Run since ImageRun extends Run
+    if (item instanceof ImageRun) {
+      return false;
+    }
+
+    // Shapes count as content
+    if (item instanceof Shape) {
+      return false;
+    }
+
+    // TextBox count as content
+    if (item instanceof TextBox) {
+      return false;
+    }
+
+    // Fields count as content
+    if (item instanceof Field) {
+      return false;
+    }
+
+    // Revisions (track changes) - check nested content for text and hyperlinks
+    if (item instanceof Revision) {
+      const revisionText = item.getText().trim();
+      if (revisionText !== "") {
+        return false;
+      }
+      // Also check if revision contains hyperlinks (may have empty display text)
+      for (const revContent of item.getContent()) {
+        if (revContent instanceof Hyperlink) {
+          return false;
+        }
+      }
+      continue; // Already checked, move to next item
+    }
+
+    // Check runs for non-whitespace text
+    if ((item as any).getText) {
+      const text = (item as any).getText().trim();
+      if (text !== "") {
+        return false;
+      }
+    }
+  }
+
+  // Check for bookmarks
+  if (
+    para.getBookmarksStart().length > 0 ||
+    para.getBookmarksEnd().length > 0
+  ) {
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Checks if a paragraph starts with bold text and has a colon within the first 55 characters.
+ * Examples: "Note:", "Warning:", "Note: This can include the following:"
+ * Ported from Document.ts:8267-8287
+ */
+export function startsWithBoldColon(para: Paragraph): boolean {
+  const content = para.getContent();
+  if (!content || content.length === 0) return false;
+
+  // Get first content item that is a Run (skip any non-Run items at start)
+  const firstRun = content.find((item) => item instanceof Run) as
+    | Run
+    | undefined;
+  if (!firstRun) return false;
+
+  // Check if first run is bold
+  const formatting = firstRun.getFormatting();
+  if (!formatting.bold) return false;
+
+  // Check if colon exists within first 55 characters of paragraph text
+  const fullText = para.getText();
+  if (!fullText) return false;
+
+  const first55 = fullText.substring(0, 55);
+  return first55.includes(":");
+}
+
+/**
+ * Checks if a paragraph is centered bold text (all text runs are bold and centered).
+ * Ported from Document.ts:8499-8523
+ */
+export function isCenteredBoldText(para: Paragraph): boolean {
+  if (para.getAlignment() !== "center") return false;
+
+  const content = para.getContent();
+  if (!content || content.length === 0) return false;
+
+  let hasTextRun = false;
+
+  for (const item of content) {
+    if (item instanceof Run) {
+      const text = item.getText();
+      if (text && text.trim() !== "") {
+        hasTextRun = true;
+        const formatting = item.getFormatting();
+        if (!formatting.bold) return false;
+      }
+    }
+  }
+
+  return hasTextRun;
+}
+
+/**
+ * Checks if a paragraph contains text but no media elements (images, shapes, textboxes).
+ * Ported from Document.ts:8531-8548
+ */
+export function isTextOnlyParagraph(para: Paragraph): boolean {
+  if (isParagraphBlank(para)) return false;
+
+  const content = para.getContent();
+  for (const item of content) {
+    if (item instanceof ImageRun) return false;
+    if (item instanceof Shape) return false;
+    if (item instanceof TextBox) return false;
+  }
+
+  const text = para.getText();
+  return !!text && text.trim() !== "";
+}
+
+/**
+ * Detects Table of Contents paragraphs by style.
+ * Ported from Document.ts:8397-8401
+ */
+export function isTocParagraph(para: Paragraph): boolean {
+  const styleId = para.getStyle();
+  if (!styleId) return false;
+  const lower = styleId.toLowerCase();
+  return /^toc\s?\d$/i.test(lower) || lower.startsWith("toc");
+}
+
+/**
+ * Checks if a paragraph contains a navigation hyperlink
+ * (display text starts with "Top of" or "Return to", case insensitive).
+ */
+export function hasNavigationHyperlink(para: Paragraph): boolean {
+  const content = para.getContent();
+  if (!content) return false;
+
+  for (const item of content) {
+    if (item instanceof Hyperlink) {
+      const text = item.getText().toLowerCase().trim();
+      if (text.startsWith("top of") || text.startsWith("return to")) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+/**
+ * Get the effective left indentation of a paragraph, resolving style-inherited
+ * indentation when the paragraph has no direct indentation set.
+ *
+ * In OOXML, a paragraph's visual indentation can come from:
+ * 1. Direct paragraph properties (<w:pPr><w:ind w:left="..."/>)
+ * 2. The paragraph's style definition (e.g., ListParagraph defines w:left="720")
+ *
+ * Paragraph.getFormatting()?.indentation?.left only returns (1).
+ * This helper also checks (2) via the Document's style definitions.
+ *
+ * NOTE: docxmlater currently parses style-level indentation as an empty object
+ * (keys exist but values are undefined), so we also check for known indented
+ * styles like ListParagraph which defines w:ind w:left="720" in its XML.
+ */
+export function getEffectiveLeftIndent(para: Paragraph, doc: Document): number {
+  // 1. Check direct paragraph indentation
+  const directIndent = para.getFormatting()?.indentation?.left;
+  if (directIndent && directIndent > 0) return directIndent;
+
+  // 2. Check style-inherited indentation
+  const styleId = para.getStyle();
+  if (styleId) {
+    const style = doc.getStyle(styleId);
+    if (style) {
+      const stylePf = style.getParagraphFormatting();
+      const styleIndent = stylePf?.indentation?.left;
+      if (styleIndent && styleIndent > 0) return styleIndent;
+
+      // Fallback: docxmlater may create an indentation object with undefined values
+      // for styles that DO have w:ind in their XML (e.g., ListParagraph w:left="720").
+      // If the style has an indentation object at all, it likely defines indentation.
+      // ListParagraph is the most common case: Word's built-in style with w:left="720".
+      if (stylePf?.indentation && styleId === "ListParagraph") {
+        return 720; // Standard ListParagraph indentation
+      }
+    }
+  }
+
+  return 0;
+}

package/src/services/document/blanklines/helpers/removeBlanksBetweenListItems.ts

@@ -0,0 +1,91 @@
+/**
+ * Removes blank paragraphs between consecutive list items.
+ * Ported from Document.ts removeBlanksBetweenListItems() (lines 7159-7216)
+ */
+
+import { Document, Paragraph, Table } from "docxmlater";
+import { isParagraphBlank } from "./paragraphChecks";
+import { tableHasNestedContent } from "./tableGuards";
+
+/**
+ * Removes blank paragraphs between consecutive list items in both
+ * body elements and table cells.
+ *
+ * This should be called AFTER list normalization (e.g., after converting
+ * typed list prefixes like "1.", "a." to proper Word numbering) to clean up
+ * blanks that were missed because items didn't have Word numbering yet.
+ *
+ * @param doc - The document to process
+ * @returns Number of blank paragraphs removed
+ */
+export function removeBlanksBetweenListItems(doc: Document): number {
+  let removed = 0;
+
+  // Process table cells
+  // Skip tables with nested content to avoid violating ECMA-376 cell structure
+  for (const table of doc.getAllTables()) {
+    if (tableHasNestedContent(table)) continue;
+    for (const row of table.getRows()) {
+      for (const cell of row.getCells()) {
+        let cellParas = cell.getParagraphs();
+        for (let ci = 1; ci < cellParas.length - 1; ci++) {
+          const prev = cellParas[ci - 1];
+          const current = cellParas[ci];
+          const next = cellParas[ci + 1];
+
+          if (!current || !isParagraphBlank(current)) continue;
+
+          const prevNumbering = prev?.getNumbering();
+          const nextNumbering = next?.getNumbering();
+
+          if (prevNumbering && nextNumbering) {
+            cell.removeParagraph(ci);
+            ci--;
+            removed++;
+            cellParas = cell.getParagraphs();
+          } else if (prevNumbering && !nextNumbering) {
+            // Also remove blank between list item and indented continuation
+            const nextIndent = next?.getFormatting()?.indentation?.left || 0;
+            if (nextIndent > 0) {
+              cell.removeParagraph(ci);
+              ci--;
+              removed++;
+              cellParas = cell.getParagraphs();
+            }
+          }
+        }
+      }
+    }
+  }
+
+  // Process body-level list items
+  for (let bi = 1; bi < doc.getBodyElementCount() - 1; bi++) {
+    const prev = doc.getBodyElementAt(bi - 1);
+    const current = doc.getBodyElementAt(bi);
+    const next = doc.getBodyElementAt(bi + 1);
+
+    if (!(current instanceof Paragraph) || !isParagraphBlank(current)) continue;
+    if (prev instanceof Table || next instanceof Table) continue;
+
+    if (prev instanceof Paragraph && next instanceof Paragraph) {
+      const prevNumbering = prev.getNumbering();
+      const nextNumbering = next.getNumbering();
+
+      if (prevNumbering && nextNumbering) {
+        doc.removeBodyElementAt(bi);
+        bi--;
+        removed++;
+      } else if (prevNumbering && !nextNumbering) {
+        // Also remove blank between list item and indented continuation
+        const nextIndent = next.getFormatting()?.indentation?.left || 0;
+        if (nextIndent > 0) {
+          doc.removeBodyElementAt(bi);
+          bi--;
+          removed++;
+        }
+      }
+    }
+  }
+
+  return removed;
+}

package/src/services/document/blanklines/helpers/removeTrailingBlanks.ts

@@ -0,0 +1,35 @@
+/**
+ * Removes trailing blank paragraphs from all table cells in the document.
+ * Ported from Document.ts removeTrailingBlanksInTableCells() (lines 5485-5502)
+ */
+
+import { Document } from "docxmlater";
+
+/**
+ * Removes trailing blank paragraphs from all table cells.
+ * A trailing blank is a blank paragraph at the END of a cell, after all content.
+ * Respects the ECMA-376 requirement that each cell must have at least one paragraph.
+ *
+ * @param doc - The document to process
+ * @param options.ignorePreserveFlag - If true, removes trailing blanks even if marked preserved (default: true)
+ * @returns Total number of paragraphs removed across all cells
+ */
+export function removeTrailingBlanksInTableCells(
+  doc: Document,
+  options?: { ignorePreserveFlag?: boolean }
+): number {
+  let totalRemoved = 0;
+  const ignorePreserve = options?.ignorePreserveFlag ?? true;
+
+  for (const table of doc.getAllTables()) {
+    for (const row of table.getRows()) {
+      for (const cell of row.getCells()) {
+        totalRemoved += cell.removeTrailingBlankParagraphs({
+          ignorePreserveFlag: ignorePreserve,
+        });
+      }
+    }
+  }
+
+  return totalRemoved;
+}

package/src/services/document/blanklines/helpers/tableGuards.ts

@@ -0,0 +1,21 @@
+/**
+ * Guard functions for skipping tables with nested content during blank line processing.
+ * Cells containing nested tables have rawNestedContent that must be preserved —
+ * removing paragraphs from these cells can violate ECMA-376 (every w:tc must end with w:p).
+ */
+
+import { Table } from "docxmlater";
+
+/**
+ * Returns true if the table contains any cells with nested tables.
+ * Tables with nested content should be skipped during blank line
+ * removal to avoid corrupting the cell structure.
+ */
+export function tableHasNestedContent(table: Table): boolean {
+  for (const row of table.getRows()) {
+    for (const cell of row.getCells()) {
+      if (cell.hasNestedTables()) return true;
+    }
+  }
+  return false;
+}