documentation-hub 5.7.2

package/src/services/document/blanklines/rules/indentationRules.ts

@@ -0,0 +1,317 @@
+/**
+ * Indentation Rules - Fix indentation on lines after list items.
+ *
+ * These rules adjust paragraph indentation for continuation text
+ * that follows list items, ensuring visual alignment.
+ *
+ * Also includes removeSmallIndents which strips indentation < 0.25"
+ * from non-list paragraphs before blank line and indentation rules run.
+ */
+
+import { Document, Paragraph, Table, TableCell } from "docxmlater";
+import { isParagraphBlank } from "../helpers/paragraphChecks";
+import { detectTypedPrefix } from "@/services/document/list";
+import type { BlankLineProcessingOptions } from "./ruleTypes";
+import { logger } from "@/utils/logger";
+
+const log = logger.namespace("IndentationRules");
+
+/** Conversion: 1 inch = 1440 twips */
+const TWIPS_PER_INCH = 1440;
+
+/** Threshold below which indentation is removed for non-list paragraphs (0.25 inch) */
+const SMALL_INDENT_THRESHOLD_TWIPS = 360; // 0.25 * 1440
+
+function inchesToTwips(inches: number): number {
+  return Math.round(inches * TWIPS_PER_INCH);
+}
+
+/**
+ * Check whether a paragraph is a list element (Word list or typed prefix).
+ */
+function isListElement(para: Paragraph): boolean {
+  // Real Word list item
+  const numbering = para.getNumbering();
+  if (numbering && numbering.numId !== undefined && numbering.numId !== 0) {
+    return true;
+  }
+
+  // Typed list prefix in text (e.g. "1. ", "a) ", "• ")
+  const text = para.getText()?.trim() || "";
+  if (text.length > 0) {
+    const typed = detectTypedPrefix(text);
+    if (typed.prefix) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Remove small indentation (< 0.25") from non-list paragraphs.
+ *
+ * This runs BEFORE blank line rules and indentation rules to ensure
+ * that trivially-indented body text and table cell text is normalized
+ * to zero indent. This prevents downstream rules from misinterpreting
+ * small indents as intentional formatting and incorrectly adding or
+ * removing blank lines.
+ *
+ * Handles both body-level paragraphs and paragraphs inside table cells
+ * (including multi-column rows).
+ */
+export function removeSmallIndents(doc: Document): number {
+  let fixed = 0;
+
+  // Process body-level paragraphs
+  for (let i = 0; i < doc.getBodyElementCount(); i++) {
+    const element = doc.getBodyElementAt(i);
+    if (!(element instanceof Paragraph)) continue;
+    if (isParagraphBlank(element)) continue;
+
+    const indent = element.getFormatting()?.indentation?.left;
+    if (!indent || indent <= 0) continue;
+    if (indent >= SMALL_INDENT_THRESHOLD_TWIPS) continue;
+
+    // Skip list elements - their indentation is intentional
+    if (isListElement(element)) continue;
+
+    log.debug(
+      `Removing small indent (${indent} twips / ${(indent / TWIPS_PER_INCH).toFixed(2)}") ` +
+      `from body paragraph: "${element.getText()?.substring(0, 40)}..."`
+    );
+    element.setLeftIndent(0);
+    fixed++;
+  }
+
+  // Process table cell paragraphs (all columns in all rows)
+  for (const table of doc.getAllTables()) {
+    for (const row of table.getRows()) {
+      for (const cell of row.getCells()) {
+        const paras = cell.getParagraphs();
+
+        for (let ci = 0; ci < paras.length; ci++) {
+          const para = paras[ci];
+          if (!para) continue;
+          if (isParagraphBlank(para)) continue;
+
+          const indent = para.getFormatting()?.indentation?.left;
+          if (!indent || indent <= 0) continue;
+          if (indent >= SMALL_INDENT_THRESHOLD_TWIPS) continue;
+
+          // Skip list elements
+          if (isListElement(para)) continue;
+
+          log.debug(
+            `Removing small indent (${indent} twips / ${(indent / TWIPS_PER_INCH).toFixed(2)}") ` +
+            `from table cell paragraph: "${para.getText()?.substring(0, 40)}..."`
+          );
+          para.setLeftIndent(0);
+          fixed++;
+        }
+      }
+    }
+  }
+
+  if (fixed > 0) {
+    log.info(`Removed small indentation (< 0.25") from ${fixed} non-list paragraphs`);
+  }
+
+  return fixed;
+}
+
+/**
+ * Find the nearest preceding list item and return its level.
+ * Scans backwards from the given index in the body.
+ */
+function findPrecedingListItem(
+  doc: Document,
+  bodyIndex: number
+): { level: number; paragraph: Paragraph } | null {
+  for (let i = bodyIndex - 1; i >= 0; i--) {
+    const el = doc.getBodyElementAt(i);
+    if (el instanceof Table) return null; // Stop at table boundaries
+    if (!(el instanceof Paragraph)) continue;
+    if (isParagraphBlank(el)) continue;
+
+    const numbering = el.getNumbering();
+    if (numbering) {
+      return { level: numbering.level ?? 0, paragraph: el };
+    }
+
+    // If we hit non-indented, non-list text, stop looking
+    const indent = el.getFormatting()?.indentation?.left;
+    if (!indent || indent <= 0) return null;
+  }
+  return null;
+}
+
+/**
+ * Find the nearest preceding list item in a cell.
+ */
+function findPrecedingListItemInCell(
+  paragraphs: Paragraph[],
+  paraIndex: number
+): { level: number; paragraph: Paragraph } | null {
+  for (let i = paraIndex - 1; i >= 0; i--) {
+    const para = paragraphs[i];
+    if (!para) continue;
+    if (isParagraphBlank(para)) continue;
+
+    const numbering = para.getNumbering();
+    if (numbering) {
+      return { level: numbering.level ?? 0, paragraph: para };
+    }
+
+    // If we hit non-indented text, stop
+    const indent = para.getFormatting()?.indentation?.left;
+    if (!indent || indent <= 0) return null;
+  }
+  return null;
+}
+
+/**
+ * Get the text indentation in twips for a given list level.
+ */
+function getTextIndentForLevel(
+  options: BlankLineProcessingOptions,
+  level: number
+): number | null {
+  if (!options.listBulletSettings?.indentationLevels) return null;
+
+  const levels = options.listBulletSettings.indentationLevels;
+  const levelConfig = levels.find((l) => l.level === level);
+
+  if (levelConfig) {
+    return inchesToTwips(levelConfig.textIndent);
+  }
+
+  // If no exact level match, use the last configured level
+  if (levels.length > 0) {
+    const lastLevel = levels[levels.length - 1];
+    return inchesToTwips(lastLevel.textIndent);
+  }
+
+  return null;
+}
+
+/**
+ * Get the level-0 text indentation in twips.
+ */
+function getLevel0TextIndent(options: BlankLineProcessingOptions): number | null {
+  return getTextIndentForLevel(options, 0);
+}
+
+/**
+ * Applies indentation rules to the document body.
+ *
+ * Rule 1: Indented text after a list item should match the text indentation
+ *         of the list item's level.
+ *
+ * Rule 2: If consecutive indented lines exist and the line above is a list item,
+ *         match the list item's text indentation. If not a list item, match
+ *         the level-0 bullet text indentation.
+ */
+export function applyIndentationRules(
+  doc: Document,
+  options: BlankLineProcessingOptions
+): number {
+  if (!options.listBulletSettings?.indentationLevels) {
+    return 0;
+  }
+
+  let fixed = 0;
+
+  // Process body-level paragraphs
+  for (let i = 0; i < doc.getBodyElementCount(); i++) {
+    const element = doc.getBodyElementAt(i);
+    if (!(element instanceof Paragraph)) continue;
+    if (isParagraphBlank(element)) continue;
+    if (element.getNumbering()) continue; // Skip list items themselves
+
+    const indent = element.getFormatting()?.indentation?.left;
+    if (!indent || indent <= 0) continue; // Only process indented paragraphs
+
+    // Find preceding list item
+    const listItem = findPrecedingListItem(doc, i);
+
+    if (listItem) {
+      // Rule 1: Match the list item's text indentation level
+      const targetIndent = getTextIndentForLevel(options, listItem.level);
+      if (targetIndent !== null && indent !== targetIndent) {
+        element.setLeftIndent(targetIndent);
+        fixed++;
+      }
+    } else {
+      // Rule 2: No preceding list item - check if previous line is indented
+      const prevElement = doc.getBodyElementAt(i - 1);
+      if (
+        prevElement instanceof Paragraph &&
+        !isParagraphBlank(prevElement) &&
+        !prevElement.getNumbering()
+      ) {
+        const prevIndent = prevElement.getFormatting()?.indentation?.left;
+        if (prevIndent && prevIndent > 0) {
+          // Consecutive indented lines - match level-0 text indent
+          const level0Indent = getLevel0TextIndent(options);
+          if (level0Indent !== null && indent !== level0Indent) {
+            element.setLeftIndent(level0Indent);
+            fixed++;
+          }
+        }
+      }
+    }
+  }
+
+  // Process table cell paragraphs
+  for (const table of doc.getAllTables()) {
+    for (const row of table.getRows()) {
+      for (const cell of row.getCells()) {
+        const paras = cell.getParagraphs();
+
+        for (let ci = 0; ci < paras.length; ci++) {
+          const para = paras[ci];
+          if (!para) continue;
+          if (isParagraphBlank(para)) continue;
+          if (para.getNumbering()) continue;
+
+          const indent = para.getFormatting()?.indentation?.left;
+          if (!indent || indent <= 0) continue;
+
+          const listItem = findPrecedingListItemInCell(paras, ci);
+
+          if (listItem) {
+            const targetIndent = getTextIndentForLevel(options, listItem.level);
+            if (targetIndent !== null && indent !== targetIndent) {
+              para.setLeftIndent(targetIndent);
+              fixed++;
+            }
+          } else {
+            // Consecutive indented lines without a list item
+            const prevPara = paras[ci - 1];
+            if (
+              prevPara &&
+              !isParagraphBlank(prevPara) &&
+              !prevPara.getNumbering()
+            ) {
+              const prevIndent = prevPara.getFormatting()?.indentation?.left;
+              if (prevIndent && prevIndent > 0) {
+                const level0Indent = getLevel0TextIndent(options);
+                if (level0Indent !== null && indent !== level0Indent) {
+                  para.setLeftIndent(level0Indent);
+                  fixed++;
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+
+  if (fixed > 0) {
+    log.info(`Fixed indentation on ${fixed} paragraphs`);
+  }
+
+  return fixed;
+}

package/src/services/document/blanklines/rules/removalRules.ts

@@ -0,0 +1,362 @@
+/**
+ * Removal Rules - Define when blank lines must be REMOVED.
+ *
+ * If any removal rule matches a blank paragraph, it is removed regardless
+ * of addition rules or preservation fallback.
+ */
+
+import { Paragraph, Table } from "docxmlater";
+import type { BlankLineRule, RuleContext } from "./ruleTypes";
+import { isParagraphBlank, getEffectiveLeftIndent, hasNavigationHyperlink } from "../helpers/paragraphChecks";
+import { isSmallImageParagraph, getImageRunFromParagraph, isImageSmall } from "../helpers/imageChecks";
+import { tableHasNestedContent } from "../helpers/tableGuards";
+
+/**
+ * Remove blank line above Heading 1 style text.
+ */
+export const aboveHeading1Rule: BlankLineRule = {
+  id: "remove-above-heading1",
+  action: "remove",
+  scope: "body",
+  matches(ctx: RuleContext): boolean {
+    if (ctx.scope !== "body") return false;
+    if (!(ctx.currentElement instanceof Paragraph)) return false;
+    if (!isParagraphBlank(ctx.currentElement)) return false;
+
+    // Check if the element after this blank is Heading 1
+    if (ctx.nextElement instanceof Paragraph) {
+      const style = ctx.nextElement.getStyle();
+      if (style === "Heading1" && ctx.nextElement.getText().trim() !== "") {
+        return true;
+      }
+    }
+    return false;
+  },
+};
+
+/**
+ * Remove blank line if it's the first line of a multi-row cell.
+ * Only applies if the cell has more than one row in its parent table.
+ */
+export const firstLineOfMultiRowCellRule: BlankLineRule = {
+  id: "remove-first-line-multi-row-cell",
+  action: "remove",
+  scope: "cell",
+  matches(ctx: RuleContext): boolean {
+    if (ctx.scope !== "cell") return false;
+    if (ctx.cellParaIndex !== 0) return false;
+    if (!ctx.cellParagraphs || ctx.cellParagraphs.length === 0) return false;
+    if (!(ctx.currentElement instanceof Paragraph)) return false;
+    if (!isParagraphBlank(ctx.currentElement)) return false;
+
+    // Only remove if this table has more than one row
+    if (ctx.parentTable) {
+      const rowCount = ctx.parentTable.getRowCount();
+      if (rowCount > 1) {
+        return true;
+      }
+    }
+    return false;
+  },
+};
+
+/**
+ * Remove blank line above tables larger than 1x1.
+ */
+export const aboveLargeTableRule: BlankLineRule = {
+  id: "remove-above-large-table",
+  action: "remove",
+  scope: "body",
+  matches(ctx: RuleContext): boolean {
+    if (ctx.scope !== "body") return false;
+    if (!(ctx.currentElement instanceof Paragraph)) return false;
+    if (!isParagraphBlank(ctx.currentElement)) return false;
+
+    if (ctx.nextElement instanceof Table) {
+      const rowCount = ctx.nextElement.getRowCount();
+      const colCount = ctx.nextElement.getColumnCount();
+      if (rowCount > 1 || colCount > 1) {
+        return true;
+      }
+    }
+    return false;
+  },
+};
+
+/**
+ * Remove blank line between list items, even if they are different level
+ * bullet lists or numbered list items.
+ */
+export const betweenListItemsRule: BlankLineRule = {
+  id: "remove-between-list-items",
+  action: "remove",
+  scope: "both",
+  matches(ctx: RuleContext): boolean {
+    if (!(ctx.currentElement instanceof Paragraph)) return false;
+    if (!isParagraphBlank(ctx.currentElement)) return false;
+
+    const prevIsListItem =
+      ctx.prevElement instanceof Paragraph && !!ctx.prevElement.getNumbering();
+    const nextIsListItem =
+      ctx.nextElement instanceof Paragraph && !!ctx.nextElement.getNumbering();
+
+    return prevIsListItem && nextIsListItem;
+  },
+};
+
+/**
+ * Remove blank line between a list item and the next line if that next line is:
+ * - indented text
+ * - a list item
+ * - indented text with a small image (<100x100) followed by text
+ */
+export const listItemToIndentedContentRule: BlankLineRule = {
+  id: "remove-list-to-indented",
+  action: "remove",
+  scope: "both",
+  matches(ctx: RuleContext): boolean {
+    if (!(ctx.currentElement instanceof Paragraph)) return false;
+    if (!isParagraphBlank(ctx.currentElement)) return false;
+
+    const prevIsListItem =
+      ctx.prevElement instanceof Paragraph && !!ctx.prevElement.getNumbering();
+    if (!prevIsListItem) return false;
+
+    if (ctx.nextElement instanceof Paragraph) {
+      // Next is a list item
+      if (ctx.nextElement.getNumbering()) return true;
+
+      // Don't remove blank before centered images
+      if (ctx.nextElement.getAlignment() === "center") {
+        const imageRun = getImageRunFromParagraph(ctx.nextElement);
+        if (imageRun) return false;
+      }
+
+      // Next is indented text (check both direct and style-inherited indentation)
+      const nextIndent = getEffectiveLeftIndent(ctx.nextElement, ctx.doc);
+      if (nextIndent > 0) return true;
+
+      // Next is a small image followed by text (check if small image with indentation)
+      if (isSmallImageParagraph(ctx.nextElement)) {
+        const nextIndentImg = getEffectiveLeftIndent(ctx.nextElement, ctx.doc);
+        if (nextIndentImg > 0) return true;
+      }
+    }
+    return false;
+  },
+};
+
+/**
+ * Before the very first list item in a sequence, if the preceding line is
+ * non-indented text, do not have a blank line between them.
+ */
+export const beforeFirstListItemRule: BlankLineRule = {
+  id: "remove-before-first-list-item",
+  action: "remove",
+  scope: "both",
+  matches(ctx: RuleContext): boolean {
+    if (!(ctx.currentElement instanceof Paragraph)) return false;
+    if (!isParagraphBlank(ctx.currentElement)) return false;
+
+    // Next element must be a list item
+    if (!(ctx.nextElement instanceof Paragraph) || !ctx.nextElement.getNumbering()) {
+      return false;
+    }
+
+    // Previous element must be non-indented text (not a list item)
+    if (!(ctx.prevElement instanceof Paragraph)) return false;
+    if (ctx.prevElement.getNumbering()) return false;
+    if (isParagraphBlank(ctx.prevElement)) return false;
+
+    const prevIndent = ctx.prevElement.getFormatting()?.indentation?.left;
+    if (prevIndent && prevIndent > 0) return false;
+
+    // Check that the next element IS the first list item (prev is not a list item)
+    return true;
+  },
+};
+
+/**
+ * If current line has bold text with a colon, no indentation, and the next
+ * line is indented or a list item, never have a blank line between them.
+ *
+ * This rule checks for a blank line between bold+colon and indented/list content.
+ */
+export const boldColonToIndentedRule: BlankLineRule = {
+  id: "remove-bold-colon-to-indented",
+  action: "remove",
+  scope: "both",
+  matches(ctx: RuleContext): boolean {
+    if (!(ctx.currentElement instanceof Paragraph)) return false;
+    if (!isParagraphBlank(ctx.currentElement)) return false;
+
+    // Previous must be bold+colon with no indentation
+    if (!(ctx.prevElement instanceof Paragraph)) return false;
+
+    const prevContent = ctx.prevElement.getContent();
+    if (!prevContent || prevContent.length === 0) return false;
+
+    // Check for bold first run with colon
+    const { Run } = require("docxmlater");
+    const firstRun = prevContent.find((item: any) => item instanceof Run) as any;
+    if (!firstRun) return false;
+    const formatting = firstRun.getFormatting() as any;
+    if (!formatting.bold) return false;
+    const fullText = ctx.prevElement.getText();
+    if (!fullText || !fullText.substring(0, 55).includes(":")) return false;
+
+    // Must have no indentation
+    const prevIndent = ctx.prevElement.getFormatting()?.indentation?.left;
+    if (prevIndent && prevIndent > 0) return false;
+
+    // Next must be indented or a list item
+    if (!(ctx.nextElement instanceof Paragraph)) return false;
+
+    if (ctx.nextElement.getNumbering()) return true;
+
+    const nextIndent = ctx.nextElement.getFormatting()?.indentation?.left;
+    if (nextIndent && nextIndent > 0) return true;
+
+    return false;
+  },
+};
+
+/**
+ * Remove blank line BELOW navigation hyperlinks (text starts with "Top of" or "Return to").
+ */
+export const afterTopOfDocHyperlinkRule: BlankLineRule = {
+  id: "remove-after-top-of-doc-hyperlink",
+  action: "remove",
+  scope: "body",
+  matches(ctx: RuleContext): boolean {
+    if (ctx.scope !== "body") return false;
+    if (!(ctx.currentElement instanceof Paragraph)) return false;
+    if (!isParagraphBlank(ctx.currentElement)) return false;
+    if (!(ctx.prevElement instanceof Paragraph)) return false;
+    return hasNavigationHyperlink(ctx.prevElement);
+  },
+};
+
+/**
+ * Never have a blank line between the last line in a cell and the element before it,
+ * unless the element before is a nested or floating table.
+ */
+export const lastLineInCellRule: BlankLineRule = {
+  id: "remove-last-line-in-cell",
+  action: "remove",
+  scope: "cell",
+  matches(ctx: RuleContext): boolean {
+    if (ctx.scope !== "cell") return false;
+    if (!ctx.cellParagraphs || !ctx.cell) return false;
+    if (!(ctx.currentElement instanceof Paragraph)) return false;
+    if (!isParagraphBlank(ctx.currentElement)) return false;
+
+    const paraIndex = ctx.cellParaIndex ?? -1;
+    const isLastBlankBeforeEnd =
+      paraIndex >= 0 && paraIndex === ctx.cellParagraphs.length - 1;
+
+    // If this blank is the last paragraph, remove it (unless preceded by nested table)
+    if (isLastBlankBeforeEnd && ctx.cellParagraphs.length > 1) {
+      // Check if the cell has nested tables that the blank might be separating
+      if (ctx.cell.hasNestedTables()) {
+        return false; // Don't remove - might be needed for nested table spacing
+      }
+      return true;
+    }
+
+    // Also check for blanks that are second-to-last where last is blank
+    // (trailing blanks in cells)
+    if (
+      paraIndex >= 1 &&
+      paraIndex === ctx.cellParagraphs.length - 2 &&
+      isParagraphBlank(ctx.cellParagraphs[ctx.cellParagraphs.length - 1])
+    ) {
+      if (ctx.cell.hasNestedTables()) return false;
+      return true;
+    }
+
+    return false;
+  },
+};
+
+/**
+ * Remove blank line after images >100x100 if the image is the last element in a table cell.
+ */
+export const largeImageLastInCellRule: BlankLineRule = {
+  id: "remove-large-image-last-in-cell",
+  action: "remove",
+  scope: "cell",
+  matches(ctx: RuleContext): boolean {
+    if (ctx.scope !== "cell") return false;
+    if (!ctx.cellParagraphs || !ctx.cell) return false;
+    if (!(ctx.currentElement instanceof Paragraph)) return false;
+    if (!isParagraphBlank(ctx.currentElement)) return false;
+
+    const paraIndex = ctx.cellParaIndex ?? -1;
+    if (paraIndex < 1) return false;
+
+    // Check if previous paragraph is a large image
+    const prevPara = ctx.cellParagraphs[paraIndex - 1];
+    if (!prevPara) return false;
+
+    const imageRun = getImageRunFromParagraph(prevPara);
+    if (!imageRun) return false;
+
+    const image = imageRun.getImageElement();
+    if (isImageSmall(image)) return false; // Small image, rule doesn't apply
+
+    // Large image - check if it's effectively the last content in the cell
+    // (current blank is after the image and is the last or near-last element)
+    const isNearEnd = paraIndex >= ctx.cellParagraphs.length - 1;
+    if (isNearEnd) return true;
+
+    // Also if all remaining paragraphs after this are blank
+    for (let i = paraIndex + 1; i < ctx.cellParagraphs.length; i++) {
+      if (!isParagraphBlank(ctx.cellParagraphs[i])) return false;
+    }
+    return true;
+  },
+};
+
+/**
+ * Remove blank line between centered text and a following image paragraph.
+ * e.g., "AETNA:" (centered) → blank → image → remove the blank.
+ */
+export const centeredTextToImageRule: BlankLineRule = {
+  id: "remove-centered-text-to-image",
+  action: "remove",
+  scope: "both",
+  matches(ctx: RuleContext): boolean {
+    if (!(ctx.currentElement instanceof Paragraph)) return false;
+    if (!isParagraphBlank(ctx.currentElement)) return false;
+
+    // Previous must be centered text paragraph
+    if (!(ctx.prevElement instanceof Paragraph)) return false;
+    if (ctx.prevElement.getAlignment() !== "center") return false;
+    if (!ctx.prevElement.getText()?.trim()) return false;
+
+    // Next must be a paragraph containing an image
+    if (!(ctx.nextElement instanceof Paragraph)) return false;
+    const imageRun = getImageRunFromParagraph(ctx.nextElement);
+    if (!imageRun) return false;
+
+    return true;
+  },
+};
+
+/**
+ * All removal rules in priority order.
+ */
+export const removalRules: BlankLineRule[] = [
+  aboveHeading1Rule,
+  firstLineOfMultiRowCellRule,
+  aboveLargeTableRule,
+  betweenListItemsRule,
+  listItemToIndentedContentRule,
+  beforeFirstListItemRule,
+  boldColonToIndentedRule,
+  afterTopOfDocHyperlinkRule,
+  lastLineInCellRule,
+  largeImageLastInCellRule,
+  centeredTextToImageRule,
+];