Skip to content

feat(docx): tables and paragraphs split across pages, header rows repeated, keep rules - #42

Open
pierreneter wants to merge 9 commits into
mainfrom
feat/docx-split-blocks
Open

pierreneter wants to merge 9 commits into
mainfrom
feat/docx-split-blocks

Conversation

@pierreneter

Copy link
Copy Markdown
Member

Part of #30: plan items 1 to 3, in the current (browser) layout.

The DOCX view now splits blocks across pages instead of moving them whole:

  • tables split between rows, with their header rows repeated;
  • paragraphs split between lines;
  • keep rules apply: widow and orphan control, keepNext and keepLines.

Editing works across the page cut. Pages grow taller than the paper only for a single line or row that is taller than the page. Rendering stays DOM, and the browser still breaks lines. The pageLayout option and the exact mode are later work. Item 4, fonts, is in #39.

What changed

  • Parser (types.ts, styles.ts):
    • keepLines and widowControl are read from the paragraph, its style chain and the document defaults.
    • When widowControl is absent it counts as on, as Word reads it.
    • The writer already keeps both through edit and save; tests cover this.
    • The Word 97 and RTF converters now set widow control off in their document defaults, because their paragraphs have it only where the file says so.
  • paginate.ts (pure):
    • It takes line and row positions, a table's header rows, and the row boundaries a merged cell forbids.
    • Each page slice gets from / to (where its first block starts and its last block stops) and cols.
    • Keep rules:
      • widow and orphan control;
      • keepLines, which is ignored for a paragraph taller than a page;
      • keepNext chains, which include the first part of the next block. A chain taller than a page is let go, so nothing is pushed forever.
    • At the top of a page the keep rules give way.
    • Blocks that fit whole take a fast path that does not look at their lines.
  • measure.ts (new):
    • row tops, header rows and merged-cell boundaries of tables;
    • line boundaries of paragraphs, read from text-box rects through one shared Range. One Range per paragraph made DOM removals very slow in Chrome.
    • Line start offsets are read only for edited paragraphs and paragraphs cut on a page in view.
  • render.tsx:
    • Tables: a table part renders rows [from, to). A later part starts with copies of the header rows: no data-pa, not editable, not found twice by find. A merged cell is clipped at the cut and continues as an empty cell.
    • Paragraphs: a paragraph part renders characters [from, to).
      • A later part has no first-line indent, space before or top border.
      • An earlier part has no space after or bottom border.
      • A justified earlier part keeps its last line justified.
      • The list marker is drawn on the first part only.
  • DocxView.tsx:
    • Measuring: edited blocks and cut paragraphs on pages in view are measured before paint, so typing does not flicker or move the caret. Pages are frozen during an IME composition.
    • Navigation: page lookups (pageOfPos) know offsets and rows. Scroll-to-caret, find, comment reveal and the outline use them.
    • Text columns are now explicit column boxes instead of CSS multicol, so blocks split across columns too.
    • Print waits until every cut paragraph is measured.
  • input.ts, the one place where DOM and offsets meet:
    • paraEl() picks the part that shows an offset, with an upstream bias at the cut.
    • posFromDom and domFromPos work across parts; paraRanges() gives one range per part.
    • Arrow keys step over the cut.
    • reflow() restores the caret after a re-layout.
  • DocxEditor.ts: an edited block keeps its old height and lines, with line starts shifted by the edit, until it is measured again.
  • collab/docx.ts: a collaborator's selection is drawn part by part.
  • Docs: docs/features.md, README.md, and a new "DOCX pages" section in docs/development.md.

e2e/docx-page.spec.ts checked CSS column-count. It now checks for the column boxes.

Tests

  • test/docx-builder.ts (new): a minimal DOCX builder.
  • test/docx-keep.test.ts:
    • keepLines and widowControl read from the paragraph, its style (including basedOn) and the document defaults;
    • both kept through an edit, and through save and reopen;
    • RTF and Word 97 files without widow control. This test fails without the converter fix.
  • test/docx-paginate.test.ts (19 tests):
    • line and row splits, repeated header rows, headers too tall to repeat;
    • oversized lines and rows, merged-cell boundaries, space before and after;
    • forced page breaks, sections, columns;
    • widow and orphan control, keepLines, keepNext (a chain, before a table, a page break after it), and a chain taller than a page.
  • e2e/docx-split.spec.ts (18 tests in Chromium):
    • Long paragraph: no gap, no lost or duplicated text, and the same line breaks as the whole paragraph. Also with justify, a first-line indent, spacing, \n line breaks and a hanging indent.
    • Long table:
      • header copies, and every row shown once;
      • typing in a cell on page 2;
      • the copy is not editable, and an edit to the header shows in the copy;
      • a merged cell across the cut.
    • Editing across the cut:
      • typing in the second part;
      • a click at the end of the first part;
      • typing until the cut moves, with the caret page checked on each of 40 keystrokes;
      • Backspace across the cut;
      • a selection across the cut deleted and undone;
      • arrows and Shift+arrows, ↓ and ↑;
      • find of a phrase over the cut;
      • an IME composition at the cut;
      • save and reopen.
    • Keep rules: widow and orphan on and off, keepLines, keepNext chains, and a caption kept with its table.
    • Also: text columns, a comment over the cut, a Word 97 .doc, and print.

On main, all 18 e2e tests and both earlier keep tests fail.

Results

In the Linux test VM with Bun 1.4.4:

Check Result
typecheck clean
bun test 1214 pass, 0 fail
build ok
15 e2e specs (docx, docx-qa2, docx-hf, docx-track, docx-table, docx-page, docx-split, comments, comments-collab, collab, legacy, viewer, file-menu, security, permissions) 154 pass, 0 fail

After the converter fix and the rebase onto af19290, I re-ran typecheck, the whole unit suite, the legacy and docx-split e2e specs, and the build.

docx-track "typing is underlined" can flake, as it does on main: tracked-change dates have one-second resolution. #38 says more about this.

Performance

Measured with large-doc.docx in the shared VM, on the Vite dev server with the React development build.

main this branch
until pagination is complete about 7.2–8.6 s about 9.0–9.6 s (about 20% slower)
pages 2072 2009
main-thread time while typing 40 characters mid-document 1576 ms 1651 ms (about +2 ms per keystroke)

The extra load time comes from about 20% more measure batches, because reading lines makes each batch slower, plus paginate at about 0.5 s in total. Two README / features rows (2073 pages in about 2 s; 7 ms per keystroke) were measured on a Mac and should be measured again there, since the page count changes.

Not done

  • Paragraphs in table cells are not split; rows are the unit there.
  • Rows are never split, so cantSplit has no effect and is not parsed.
  • Line boundaries are estimated halfway between text boxes. This is exact for uniform lines and about 1 px off with mixed sizes or pictures. A part that reflows differently spills into the bottom margin; no text is lost.
  • Fields: PAGE and NUMPAGES fields in body text are measured as "1", so their line could break differently.
  • Soft hyphen: a soft hyphen at the cut is not shown.
  • Simplifications:
    • a long keepNext paragraph is moved whole;
    • space before is kept at the top of a page;
    • a drag selection cannot start on a header copy.
  • Not tested: collaborators' cursors drawn across parts have no e2e test.

Merging

🤖 Generated with Claude Code

pierreneter and others added 9 commits November 20, 2026 12:44
…its style and the document defaults

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…en rows, header rows repeated

The pure page cutter, given where each block's lines or rows are: what does not fit a page goes on on the next
one, one line or row taller than a page makes its page grow, text columns are filled the same way.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…t one, its header rows repeated

The measure pass reads where the rows of a table are; pages cut it between rows. The pages after the first
start with a copy of the header rows (shown, not editable). A merged cell cut by a page end keeps its text on
its first page and goes on below as an empty cell; one whose text would not fit above the cut keeps those rows
together. Text columns are laid out as columns of their own, filled like pages.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… next one, split between two lines

The measure pass reads where each line of a paragraph is, and for the paragraphs a page in view cuts, the
offset each line starts at; the page shows the lines that fit, the next page the rest, with the same line
breaks (no first-line indent or space before on the second part, the first part's last line justified when
the paragraph is). Keep rules choose the cut: widow / orphan control, keep lines together, keep with next.

A split paragraph is edited as one: its parts carry the offsets they hold, and the DOM <-> offset mapping
goes across them (caret, selection, find highlights, comment drafts, collaborators' cursors). Arrow keys
step over the page end one character; typing that moves the page end keeps the caret on the side it was
typed on; edited paragraphs are measured again before the page is painted; the pages stay as they are while
an input method composes. Printing waits until every cut paragraph is read.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ed without looking at their lines, typing cuts the pages once

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…mment over the page end, a Word 97 file

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ss the page end

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Widow control absent from a DOCX now means on, as Word reads it. The Word 97
and RTF converters write it only where a paragraph or style has it, so the
paragraphs of those files without it came out with it on. Their document
defaults now say it is off.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant