feat: Option to prevent table rows from splitting across pages (table-row-break: avoid)

[defurl]

Type

• Feature
• Other

Description

Problem Description

When rendering DOCX documents with tables containing tall cells (e.g., cells with multiple paragraphs or long text), SuperDoc's layout engine splits individual table rows across multiple page fragments. This causes several visual issues:

1. Text overlapping - Content from different fragments bleeds into each other
2. Misaligned borders - Cell borders don't align across page boundaries
3. Per-fragment text reflow - Each fragment independently reflows text, causing inconsistent line breaks between columns

Visual Example

When a single table row is too tall to fit on one page:

Page 1:                          Page 2:
┌────┬────┬────┐                 (continuation)
│ A  │ B  │ C  │                 ┌────┬────┬────┐
│    │    │ Lo │ ← row split →   │    │    │ng  │  ← text wraps differently
│    │    │ ng │                 │    │    │con │
└────┴────┴────┘                 └────┴────┴────┘
     borders don't                    tent
     align visually

Reproduction

1. Create a DOCX with a table where one cell contains very long content (multiple paragraphs)
2. Load in SuperDoc with layout engine
3. Observe that the row is split across up to 7+ page fragments
4. Text overlaps and borders misalign at fragment boundaries

Diagnostic Output

Using custom diagnostic tooling, we found:

• Fragment 0-6 all contain the SAME logical row (split across 7 pages)
• Fragment heights vary wildly (17px to 725px)
• continuation=true for fragments 1-6, but no cross-fragment height coordination

Fragment 0: 8 cells, 2 rows, height=102.3px, continuation=false
Fragment 1: 4 cells, 1 rows, height=51.8px, continuation=true
Fragment 2: 4 cells, 1 rows, height=397.1px, continuation=true
Fragment 3: 4 cells, 1 rows, height=69.1px, continuation=true
Fragment 4: 4 cells, 1 rows, height=86.3px, continuation=true
Fragment 5: 4 cells, 1 rows, height=725.2px, continuation=true
Fragment 6: 2 cells, 1 rows, height=25.3px, continuation=true

Current Behavior / Limitation

Current Behavior / Limitation

When a table row is taller than the remaining page space, SuperDoc:

1. Splits the row across multiple page fragments (we observed 1 row spanning 7 pages)
2. Reflows text independently in each fragment, causing inconsistent line breaks
3. Creates visual artifacts including text overlap and border misalignment

Diagnostic output:

Fragment 0: 8 cells, 2 rows, height=102.3px, continuation=false
Fragment 1: 4 cells, 1 rows, height=51.8px, continuation=true
Fragment 2: 4 cells, 1 rows, height=397.1px, continuation=true
Fragment 3: 4 cells, 1 rows, height=69.1px, continuation=true
Fragment 4: 4 cells, 1 rows, height=86.3px, continuation=true
Fragment 5: 4 cells, 1 rows, height=725.2px, continuation=true
Fragment 6: 2 cells, 1 rows, height=25.3px, continuation=true

Workarounds attempted (none fully work):

• synchronizeTableRowHeights() - only aligns within fragments
• CSS overflow: visible - causes text bleeding
• Hiding continuation borders - partial improvement only

---

Expected Behavior

Expected Behavior

Layout engine options to control table row splitting:

new SuperDoc({
  layoutEngineOptions: {
    // Option 1: Prevent row splitting (like CSS break-inside: avoid)
    tableRowBreak: 'avoid',
    
    // Option 2: Coordinate heights across fragments
    tableRowFragmentSync: true,
    
    // Option 3: Limit row height before forcing split
    maxTableRowHeight: 800, // pixels
  }
});

Ideally, if a row won't fit, move the entire row to the next page rather than splitting it mid-content.

---

Example Use Case

Example Use Case

We're building a contract management system displaying legal documents with complex tables. These tables contain:

• Multiple paragraphs per cell (terms, conditions, scope descriptions)
• Rows that naturally exceed page height

Current rendering makes these tables unreadable due to text overlap and border issues.

Environment:

• SuperDoc versions tested: 0.37.0, 1.0.3, 2.0.0-next.6
• Browser: Chrome 120+
• Framework: React 19

Related issues: #1435, #1353, #1380

---

SuperDoc Version

0.37.0, 1.0.3, 2.0.0-next.6

Additional Context

Provided here is a sample image of 2 engines, to the right is the document opened in Microsoft Word, and to the left is the rendered document on the web page using SuperDoc.
https://github.com/user-attachments/assets/72adf7cd-ed7c-4ee1-afb3-73a1763d2692

Checklist

• Checked for duplicates
• Added relevant labels

[linear]

IT-157