documentation-hub 5.7.2

package/src/services/document/list/index.ts

@@ -0,0 +1,45 @@
+/**
+ * List normalization module
+ *
+ * Moved from docxmlater to dochub-app for processing-level customization.
+ * Provides typed list prefix detection and normalization to proper Word formatting.
+ */
+
+// Types
+export type {
+  ListCategory,
+  NumberFormat,
+  BulletFormat,
+  ListDetectionResult,
+  ListAnalysis,
+  IndentationLevel,
+  ListNormalizationOptions,
+  ListNormalizationReport,
+} from "./list-types";
+
+// Detection utilities
+export {
+  TYPED_LIST_PATTERNS,
+  PATTERN_TO_CATEGORY,
+  FORMAT_TO_LEVEL,
+  getLevelFromFormat,
+  inferLevelFromIndentation,
+  inferLevelFromRelativeIndentation,
+  detectTypedPrefix,
+  getParagraphIndentation,
+  detectListType,
+  validateListSequence,
+  getListCategoryFromFormat,
+} from "./list-detection";
+
+// Normalization
+export {
+  ListNormalizer,
+  analyzeCellLists,
+  analyzeTableLists,
+  normalizeListsInCell,
+  normalizeListsInTable,
+  normalizeOrphanListLevelsInCell,
+  normalizeOrphanListLevelsInTable,
+  stripTypedPrefix,
+} from "./ListNormalizer";

package/src/services/document/list/list-detection.ts

@@ -0,0 +1,275 @@
+/**
+ * List Detection Utilities
+ *
+ * Moved from docxmlater to dochub-app for processing-level customization.
+ * Provides functions to detect typed list prefixes and analyze
+ * paragraph list properties.
+ */
+
+import type { Paragraph } from "docxmlater";
+import type {
+  ListCategory,
+  ListDetectionResult,
+  NumberFormat,
+  BulletFormat,
+} from "./list-types";
+
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+
+/**
+ * Regex patterns for typed list prefixes.
+ * Order matters: more specific patterns first.
+ */
+export const TYPED_LIST_PATTERNS: Record<string, RegExp> = {
+  // Numbered patterns (capture the marker for validation)
+  decimal: /^(\d+)[.)]\s+/,
+  lowerLetter: /^([a-z])[.)]\s+/,
+  upperLetter: /^([A-Z])[.)]\s+/,
+  lowerRoman: /^((?:i{1,3}|iv|vi{0,3}|ix|x{1,3}))[.)]\s+/i,
+
+  // Bullet patterns
+  bullet: /^[•●○◦▪■□]\s+/,
+  dash: /^[-–—]\s+/,
+  arrow: /^[►▸▶→]\s+/,
+};
+
+/** Map pattern names to categories */
+export const PATTERN_TO_CATEGORY: Record<string, ListCategory> = {
+  decimal: "numbered",
+  lowerLetter: "numbered",
+  upperLetter: "numbered",
+  lowerRoman: "numbered",
+  bullet: "bullet",
+  dash: "bullet",
+  arrow: "bullet",
+};
+
+/**
+ * Map typed prefix format to Word numbering level.
+ * Word's default multilevel list uses:
+ *   Level 0: 1., 2., 3. (decimal)
+ *   Level 1: a., b., c. (lowerLetter)
+ *   Level 2: i., ii., iii. (lowerRoman)
+ */
+export const FORMAT_TO_LEVEL: Record<string, number> = {
+  decimal: 0,      // 1., 2., 3.
+  lowerLetter: 1,  // a., b., c.
+  upperLetter: 0,  // A., B., C. — top-level alternative to decimal in business docs
+  lowerRoman: 2,   // i., ii., iii.
+  upperRoman: 2,   // I., II., III.
+  bullet: 0,       // Top-level bullet (filled circle)
+  dash: 0,         // Top-level dash marker
+  arrow: 0,        // Top-level arrow marker
+};
+
+/**
+ * Get the Word numbering level for a given format.
+ * Returns 0 (top level) for decimal or unknown formats.
+ */
+export function getLevelFromFormat(format: string | null): number {
+  if (!format) return 0;
+  return FORMAT_TO_LEVEL[format] ?? 0;
+}
+
+/**
+ * Word standard indentation values in twips.
+ * Level 0: 720 twips (0.5 inch) left indent
+ * Level 1: 1080 twips (0.75 inch) left indent
+ * Level 2: 1440 twips (1 inch) left indent
+ * Each subsequent level adds 360 twips.
+ */
+const WORD_BASE_INDENT = 720;
+const INDENT_PER_LEVEL = 360;
+
+// =============================================================================
+// CORE DETECTION FUNCTIONS
+// =============================================================================
+
+/**
+ * Infer list level from indentation.
+ * Uses standard Word indentation: 720 twips for level 0, +360 per level.
+ */
+export function inferLevelFromIndentation(indentTwips: number): number {
+  if (indentTwips < WORD_BASE_INDENT) return 0;
+  return Math.floor((indentTwips - WORD_BASE_INDENT) / INDENT_PER_LEVEL);
+}
+
+/**
+ * Infer list level from relative indentation (baseline already subtracted).
+ * Used when normalizing lists within a table cell where the baseline
+ * indentation varies per cell.
+ */
+export function inferLevelFromRelativeIndentation(relativeIndentTwips: number): number {
+  if (relativeIndentTwips <= 0) return 0;
+  return Math.min(8, Math.floor(relativeIndentTwips / INDENT_PER_LEVEL));
+}
+
+/**
+ * Detect typed list prefix in text.
+ * Returns the matched prefix and format type.
+ *
+ * Special handling for abbreviations:
+ * - Single letter prefixes (A., B., P.) are NOT treated as list markers
+ *   if the remaining text also starts with a letter+period pattern,
+ *   indicating an abbreviation like "P.O. Box", "U.S. Army", etc.
+ */
+export function detectTypedPrefix(text: string): {
+  prefix: string | null;
+  format: NumberFormat | BulletFormat | null;
+  category: ListCategory;
+} {
+  for (const [format, regex] of Object.entries(TYPED_LIST_PATTERNS)) {
+    const match = text.match(regex);
+    if (match) {
+      // Special check for single-letter patterns (lowerLetter, upperLetter)
+      // to avoid false positives on abbreviations like "P.O. Box", "U.S.", "A.M."
+      if (format === "lowerLetter" || format === "upperLetter") {
+        const remaining = text.substring(match[0].length);
+        // If remaining text starts with another letter followed by period,
+        // this is likely an abbreviation, not a list marker
+        if (/^[A-Za-z]\./.test(remaining)) {
+          continue; // Skip this pattern, try others
+        }
+      }
+
+      return {
+        prefix: match[0],
+        format: format as NumberFormat | BulletFormat,
+        category: PATTERN_TO_CATEGORY[format] ?? "none",
+      };
+    }
+  }
+
+  return { prefix: null, format: null, category: "none" };
+}
+
+/**
+ * Get the left indentation from a paragraph in twips.
+ */
+export function getParagraphIndentation(paragraph: Paragraph): number {
+  const formatting = paragraph.getFormatting();
+  return formatting?.indentation?.left ?? 0;
+}
+
+/**
+ * Main detection function: analyze a single paragraph for list properties.
+ */
+export function detectListType(paragraph: Paragraph): ListDetectionResult {
+  const text = paragraph.getText();
+  const indentation = getParagraphIndentation(paragraph);
+  const numbering = paragraph.getNumbering();
+
+  // Priority 1: Real Word list with <w:numPr>
+  if (numbering && numbering.numId !== undefined && numbering.numId !== 0) {
+    return {
+      category: "numbered", // Default, caller can refine with NumberingManager lookup
+      isWordList: true,
+      typedPrefix: null,
+      inferredLevel: numbering.level ?? 0,
+      format: null, // Would need numbering.xml lookup
+      numId: numbering.numId,
+      ilvl: numbering.level ?? 0,
+      indentationTwips: indentation,
+    };
+  }
+
+  // Priority 2: Typed prefix detection
+  const typed = detectTypedPrefix(text);
+  if (typed.prefix) {
+    return {
+      category: typed.category,
+      isWordList: false,
+      typedPrefix: typed.prefix,
+      // Use FORMAT to determine level, not indentation!
+      // decimal=0, lowerLetter=1, lowerRoman=2
+      inferredLevel: getLevelFromFormat(typed.format),
+      format: typed.format,
+      numId: null,
+      ilvl: null,
+      indentationTwips: indentation,
+    };
+  }
+
+  // Priority 3: Not a list
+  return {
+    category: "none",
+    isWordList: false,
+    typedPrefix: null,
+    inferredLevel: 0,
+    format: null,
+    numId: null,
+    ilvl: null,
+    indentationTwips: indentation,
+  };
+}
+
+/**
+ * Validate that a typed prefix sequence is reasonable.
+ * E.g., "1. 2. 3." is valid, "1. 5. 2." is suspicious.
+ */
+export function validateListSequence(
+  paragraphs: Array<{ detection: ListDetectionResult; text: string }>
+): { valid: boolean; warnings: string[] } {
+  const warnings: string[] = [];
+  let lastDecimal = 0;
+  let lastLetter = "";
+
+  for (const { detection } of paragraphs) {
+    if (!detection.typedPrefix || detection.category !== "numbered") continue;
+
+    const match = detection.typedPrefix.match(/^(\d+|[a-zA-Z]+)/);
+    if (!match || !match[1]) continue;
+
+    const marker = match[1];
+
+    // Check decimal sequence
+    if (/^\d+$/.test(marker)) {
+      const num = parseInt(marker, 10);
+      if (lastDecimal > 0 && num !== lastDecimal + 1 && num !== 1) {
+        warnings.push(`Unexpected number sequence: ${lastDecimal} → ${num}`);
+      }
+      lastDecimal = num;
+    }
+
+    // Check letter sequence
+    if (/^[a-z]$/i.test(marker)) {
+      const letter = marker.toLowerCase();
+      if (
+        lastLetter &&
+        letter.charCodeAt(0) !== lastLetter.charCodeAt(0) + 1 &&
+        letter !== "a"
+      ) {
+        warnings.push(`Unexpected letter sequence: ${lastLetter} → ${letter}`);
+      }
+      lastLetter = letter;
+    }
+  }
+
+  return { valid: warnings.length === 0, warnings };
+}
+
+/**
+ * Determine the list category for a given numId by checking the abstractNum.
+ * This requires access to the NumberingManager.
+ */
+export function getListCategoryFromFormat(
+  format: string | undefined
+): ListCategory {
+  if (!format) return "none";
+
+  if (["bullet", "dash", "arrow"].includes(format)) {
+    return "bullet";
+  }
+
+  if (
+    ["decimal", "lowerLetter", "upperLetter", "lowerRoman", "upperRoman"].includes(
+      format
+    )
+  ) {
+    return "numbered";
+  }
+
+  return "none";
+}

package/src/services/document/list/list-types.ts

@@ -0,0 +1,162 @@
+/**
+ * List Normalization Types
+ *
+ * Moved from docxmlater to dochub-app for processing-level customization.
+ * These types support detection and normalization of typed list prefixes
+ * to proper Word list formatting.
+ */
+
+/** High-level list category */
+export type ListCategory = "numbered" | "bullet" | "none";
+
+/** Specific number format patterns */
+export type NumberFormat =
+  | "decimal" // 1. 2. 3.
+  | "lowerLetter" // a. b. c.
+  | "upperLetter" // A. B. C.
+  | "lowerRoman" // i. ii. iii.
+  | "upperRoman"; // I. II. III.
+
+/** Specific bullet format patterns */
+export type BulletFormat =
+  | "bullet" // • ● ○
+  | "dash" // - – —
+  | "arrow"; // ► ▸
+
+/**
+ * Result of detecting list type for a single paragraph
+ */
+export interface ListDetectionResult {
+  /** High-level category */
+  category: ListCategory;
+
+  /** True if paragraph has <w:numPr> (real Word list) */
+  isWordList: boolean;
+
+  /** The typed prefix found, e.g., "1. ", "a) ", "• " */
+  typedPrefix: string | null;
+
+  /** Inferred nesting level based on indentation */
+  inferredLevel: number;
+
+  /** Specific format detected */
+  format: NumberFormat | BulletFormat | null;
+
+  /** If Word list, the numId from <w:numPr> */
+  numId: number | null;
+
+  /** If Word list, the ilvl from <w:numPr> */
+  ilvl: number | null;
+
+  /** Raw indentation in twips for debugging */
+  indentationTwips: number;
+}
+
+/**
+ * Analysis of all lists within a scope (cell, table, document)
+ */
+export interface ListAnalysis {
+  /** All analyzed paragraphs with their detection results */
+  paragraphs: Array<{
+    paragraph: unknown; // Paragraph instance - using unknown to avoid circular dep
+    text: string;
+    detection: ListDetectionResult;
+  }>;
+
+  /** True if any typed (non-Word) lists found */
+  hasTypedLists: boolean;
+
+  /** True if any real Word lists found */
+  hasWordLists: boolean;
+
+  /** True if both numbered AND bullet lists present */
+  hasMixedCategories: boolean;
+
+  /** The dominant list type in this scope */
+  majorityCategory: ListCategory;
+
+  /** Count by category */
+  counts: {
+    numbered: number;
+    bullet: number;
+    none: number;
+  };
+
+  /** Recommended action */
+  recommendedAction: "normalize" | "none";
+}
+
+/**
+ * User-defined indentation level configuration for list normalization
+ */
+export interface IndentationLevel {
+  level: number;
+  textIndent: number;      // in inches
+  symbolIndent: number;    // in inches
+  bulletChar?: string;
+  numberedFormat?: NumberFormat | string;
+}
+
+/**
+ * Options for list normalization
+ */
+export interface ListNormalizationOptions {
+  /** numId to use for numbered lists (from numbering.xml) */
+  numberedStyleNumId?: number;
+
+  /** numId to use for bullet lists (from numbering.xml) */
+  bulletStyleNumId?: number;
+
+  /** Processing scope */
+  scope?: "cell" | "table" | "document";
+
+  /**
+   * If true, convert ALL list items to majority type.
+   * If false, only convert typed lists (preserve existing Word lists).
+   */
+  forceMajority?: boolean;
+
+  /**
+   * If true, preserve original indentation instead of using level defaults.
+   */
+  preserveIndentation?: boolean;
+
+  /**
+   * User-defined indentation settings per list level.
+   * Used to configure symbol indent, text indent, and bullet characters.
+   */
+  indentationLevels?: IndentationLevel[];
+
+  /**
+   * Extra twips to add to hanging indent for documents with 10+ numbered items.
+   * When a numbered list has double-digit items (10+), the wider number text
+   * needs more space. This value is added to textIndent (leftIndent) before
+   * computing hangingIndent, widening the gap between number and text.
+   * Typically 72 twips (0.05 inches) to go from 0.25" to 0.30" hanging indent.
+   */
+  extraHangingIndentTwips?: number;
+}
+
+/**
+ * Report returned after normalization
+ */
+export interface ListNormalizationReport {
+  /** Number of paragraphs successfully normalized */
+  normalized: number;
+
+  /** Number of paragraphs skipped (already correct or non-list) */
+  skipped: number;
+
+  /** Any errors encountered */
+  errors: string[];
+
+  /** The majority category that was applied */
+  appliedCategory: ListCategory;
+
+  /** Detailed per-paragraph results */
+  details: Array<{
+    originalText: string;
+    action: "normalized" | "skipped" | "error";
+    reason?: string;
+  }>;
+}