feat: support rendering of column line separators by JoaaoVerona · Pull Request #2088 · superdoc-dev/superdoc

JoaaoVerona · 2026-02-18T01:39:29Z

Summary

Adds support for rendering "line between" separators between page columns in DOM Painter, extracting their presence by looking up the w:sep tag in the layout engine and ProseMirror adapter. Closes #2067.

Changes

layout-engine, pm-adapter: Extracts w:sep tag according to OOXML spec [1] [2]
painters: Renders one separator for each page column (w:num)
contracts, layout-bridge, super-editor: pass down withSeparator property
New tests

Questions & Additional details

There were multiple occurrences (within the existing code) of copying the columns data (i.e. y.columns = { count: x.count, gap: x.gap }) that needed to be updated also to copy withSeparator; I could have used spread operator to shallow clone the data, but I went with a more conservative approach to avoid, potentially, copying unnecessary/unintended properties that could be declared in these objects at runtime;
withSeparator will be true when w:sep="true", w:sep="1" or w:sep="on", according to the spec;
Separator color hard-coded as #b3b3b3, as I'm not sure if we could infer this somehow;
I'm not sure about the retrocompatibility of this change; I marked withSeparator as optional to make sure we don't break userland, but a second look from someone more experienced with the packaging/release of superdoc would be great.

Showcase

GDocs - Two-column layout (docx here)	SuperDoc - Imported from GDocs

GDocs - Three-column layout (docx here)	SuperDoc - Imported from GDocs

MSWord - Two-column layout (docx here)	SuperDoc - Imported from MSWord

chatgpt-codex-connector · 2026-02-18T01:39:33Z

Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits.
Credits must be used to enable repository wide code reviews.

JoaaoVerona · 2026-02-18T01:45:05Z

@caio-pizzol I could not find, in ECMA-376, a definition for w:sectPr > lineBetween as specified on #2067. Should we add support for that attribute too? Are programs out there exporting docx files with it?

caio-pizzol

Hey @JoaaoVerona, this is a great start! The withSeparator flag is threaded cleanly through the whole pipeline - extraction, layout, rendering — nice work.

Tests: would be great to add a visual rendering test with a sample .docx that has w:sep="1" on <w:cols>. The test infra auto-discovers .docx files so it's mostly just dropping one in tests/visual/. This is the best way to catch regressions in separator positioning and styling down the road.

On your lineBetween question: lineBetween isn't part of the ECMA-376 spec - the actual XML attribute for column separators is w:sep on <w:cols> (§17.6.4), which is exactly what this PR implements. The name lineBetween probably comes from the Open XML SDK's property naming, not from the XML itself. Word and LibreOffice both use w:sep, so no need to support lineBetween.

left some inline comments on a few things worth tweaking before merging.

packages/layout-engine/painters/dom/src/renderer.ts

packages/layout-engine/layout-engine/src/index.ts

packages/layout-engine/painters/dom/src/renderer.ts

packages/layout-engine/layout-engine/src/paginator.ts

packages/layout-engine/layout-bridge/src/incrementalLayout.ts

caio-pizzol · 2026-02-18T13:18:26Z

@JoaaoVerona btw we've created our own OOXML MCP server (https://ooxml.dev/mcp) :)

caio-pizzol · 2026-02-23T14:45:31Z

@JoaaoVerona, let us know if you have any questions on this one

JoaaoVerona · 2026-02-24T03:00:04Z

hey @caio-pizzol, thanks for the info!

also, great work with the mcp -- been using it already with CC!

additionally to the inline comments:

I simply added a test .docx directly to tests/visual/ directory as instructed; I'm guessing there's no way right now for external contributors to run the visual tests (given that the docs:download script requires auth)?
I'm not sure yet why this doc test.docx has "misleading" w:cols entries and the actual columns in each page. it is a two-page doc; each page has a different column layout. SuperDoc itself seems to render the content correctly, but it seems the w:cols I'm extracting is misleading (perhaps I should not be looking at them and should infer columns another way? or maybe it could be related to the continuous section break you mentioned?).

Google Docs	SuperDoc

by looking at document.xml, I can see there are 3 w:cols entries (although there are only 2 pages). will need to investigate that further whenever I have additional time to work on this again, but please let me know if you have any insights!

caio-pizzol · 2026-02-27T15:06:32Z

I simply added a test .docx directly to tests/visual/ directory as instructed; I'm guessing there's no way right now for external contributors to run the visual tests (given that the docs:download script requires auth)?

correct — the visual test infra isn't set up for external contributors to run locally yet. we'll upload the baseline on our end. we're looking into better ways to support this for the community going forward.

I'm not sure yet why this doc test.docx has "misleading" w:cols entries [...] by looking at document.xml, I can see there are 3 w:cols entries (although there are only 2 pages).

i looked at your document.xml — OOXML sections are end-tagged, meaning the sectPr on a paragraph defines the section that ends at that paragraph, not the one that starts there. your doc has 3 sections:

Section	`w:cols`	`w:type`	What it controls
1 (paragraph `sectPr`, line 7)	`num="3"`	(default = nextPage)	just "Start line." — a single-paragraph section
2 (paragraph `sectPr`, line 895)	`num="2"`	`continuous`	"Start first column." through "End." — page 1's 2-column layout
3 (body `sectPr`, line 2195)	`num="3"`	`continuous`	"Start line page 2." through "End." — page 2's 3-column layout

the confusing part is that the first w:cols says num="3", but it only applies to a throwaway single-paragraph section that Google Docs emits before the actual column content begins. the num="2" in section 2 is what drives page 1's layout, and the num="3" in the body sectPr drives page 2.

so the extraction is correct — the values just read counterintuitively because of end-tagged semantics. nothing to fix here.

caio-pizzol

@JoaaoVerona the round 1 feedback is all addressed — the separator color, the columnWidth <= 1 guard, the ColumnLayout type usage, and the SINGLE_COLUMN_DEFAULT constant are all looking good. left a few inline comments on some remaining rough edges before this is ready to merge.

packages/layout-engine/pm-adapter/src/sections/extraction.ts

packages/layout-engine/pm-adapter/src/sections/types.ts

packages/layout-engine/layout-engine/src/section-breaks.d.ts

packages/layout-engine/layout-engine/src/index.ts

- Extracts 'w:sep' tag according to OOXML spec - Renders one separator for each page column ('w:col' / 'w:num') in DOM painter Closes superdoc-dev#2067

JoaaoVerona · 2026-03-15T04:15:52Z

hey @caio-pizzol, thanks for the context! inline comments should be solved now. rebased it with main too.

caio-pizzol

@JoaaoVerona all the feedback from previous rounds is addressed — looking good.

two small things:

the column snapshot in section-props.ts copies fields by hand and misses equalWidth and widths. there's already a helper (getColumnConfig) that copies everything — reusing it would avoid this.
normalizeColumnsForFootnotes in incrementalLayout.ts is a copy of normalizeColumns in index.ts. worth consolidating so the next person doesn't update one and forget the other.

on tests: renderColumnSeparators doesn't have a unit test for its positioning math and guard clauses. also, tests/visual/columns-with-line-separator.docx won't get picked up by the layout regression suite — it needs to go through pnpm corpus:upload to land in the R2 corpus where rendering.spec.ts auto-discovers test files.

left a couple inline comments.

caio-pizzol · 2026-03-23T23:09:52Z

packages/layout-engine/layout-engine/src/section-props.ts

  if (block.columns) {
    hasProps = true;
-    props.columns = { count: block.columns.count, gap: block.columns.gap };
+    props.columns = { count: block.columns.count, gap: block.columns.gap, withSeparator: block.columns.withSeparator };


the manual { count, gap, withSeparator } copy here and at line 138 drops equalWidth and widths — so documents with different-sized columns lose that info in the snapshot. getColumnConfig() in section-breaks.ts already copies everything correctly. worth reusing it here?

caio-pizzol · 2026-03-23T23:09:52Z

packages/layout-engine/layout-bridge/src/incrementalLayout.ts

  const gap = Math.max(0, input?.gap ?? 0);
  const totalGap = gap * (count - 1);
  const width = (contentWidth - totalGap) / count;
+  const withSeparator = input?.withSeparator ?? false;


this does the same thing as normalizeColumns in layout-engine/src/index.ts:2633 — both are one-liners wrapping normalizeColumnLayout. not blocking, but if one changes and the other doesn't, things will break quietly.

caio-pizzol reviewed Feb 18, 2026

View reviewed changes

caio-pizzol assigned JoaaoVerona Feb 23, 2026

JoaaoVerona force-pushed the feat/support-column-line-separator branch from fefdd96 to 9a732ac Compare February 24, 2026 02:44

caio-pizzol added the community label Feb 27, 2026

caio-pizzol reviewed Feb 27, 2026

View reviewed changes

JoaaoVerona added 6 commits March 15, 2026 00:51

feat: support column line separators

bdb30d5

- Extracts 'w:sep' tag according to OOXML spec - Renders one separator for each page column ('w:col' / 'w:num') in DOM painter Closes superdoc-dev#2067

test: add docx file with line separator between columns enabled

580710c

fix: rendering color of separators

7c6b27a

fix: reuse ColumnLayout and SINGLE_COLUMN_DEFAULT

a54e4a9

fix: ensure column width larger than separator width

031b42a

chore: lint

32753c9

JoaaoVerona force-pushed the feat/support-column-line-separator branch from 9a732ac to 32753c9 Compare March 15, 2026 03:53

chore: fix imports and missing SINGLE_COLUMN_DEFAULT usage

e2117fa

chore: reuse type

8d1ddcc

caio-pizzol approved these changes Mar 23, 2026

View reviewed changes

Conversation

JoaaoVerona commented Feb 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Questions & Additional details

Showcase

Uh oh!

chatgpt-codex-connector bot commented Feb 18, 2026

Uh oh!

JoaaoVerona commented Feb 18, 2026

Uh oh!

caio-pizzol left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

caio-pizzol commented Feb 18, 2026

Uh oh!

caio-pizzol commented Feb 23, 2026

Uh oh!

JoaaoVerona commented Feb 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

caio-pizzol commented Feb 27, 2026

Uh oh!

caio-pizzol left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

JoaaoVerona commented Mar 15, 2026

Uh oh!

caio-pizzol left a comment

Choose a reason for hiding this comment

Uh oh!

caio-pizzol Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

caio-pizzol Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

JoaaoVerona commented Feb 18, 2026 •

edited

Loading

JoaaoVerona commented Feb 24, 2026 •

edited

Loading