Repository navigation
docs: say a table goes next to paragraphs, never in a paragraph's children - #3859
Conversation
…ldren #2711's HTML converter put each table in `new Paragraph({ children: [table] })`, which writes a w:tbl inside a w:p that Word can't open. TypeScript has rejected it since 9.13.0 (#3790), but plain JavaScript still writes it, and the docs never said where a table can go. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01X5zGDL3sgGVBMXPfny376c
|
No actionable comments were generated in the recent review.
 |
| Layer / File(s) | Summary |
|---|---|
Table placement constraints docs/usage/tables.md |
The intro directs readers to place tables in container children, not paragraph children. It also notes Word’s document-opening limitation and a TypeScript error reported since version 9.13.0. |
Priority:
Estimated code review effort: 1 (Trivial) | ~3 minutes
Change: Other · Severity of issue fixed: Low
Merge Risk: 
182be
-
The documentation clarifies where tables belong without changing runtime behavior. No merge-blocking issue was identified.
Pre-merge checks: 
-
Check name Status Explanation Resolution Linked Issues check Issue #2711reports a document-opening failure caused by placing a table inside paragraph children. The reviewed change updates onlydocs/usage/tables.md, as shown by the commit history and supplied…Implement the converter change described in the PR. Add an automated regression test that verifies a generated document places the table as a section child and passes the relevant document validation. -
Check name Status Explanation Description Check Check skipped - CodeRabbit’s high-level summary is enabled. Title check The title clearly and concisely describes the main documentation change: tables must be placed next to paragraphs, not inside paragraph children. Out of Scope Changes check The changed file documents the valid table placement for sections, headers, footers, cells, and text boxes. This change directly addresses the table-placement problem in issue #2711. No unrelated chan…Docstring Coverage No eligible functions found in the changed files. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentat… Full details: Out of Scope Changes check
-
Explanation
The changed file documents the valid table placement for sections, headers, footers, cells, and text boxes. This change directly addresses the table-placement problem in issue
#2711. No unrelated change is shown.
Full details: Docstring Coverage
-
Explanation
No eligible functions found in the changed files. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 0 functions across 0 files. (1 skipped: 1 unsupported.)
-
Full details: Linked Issues check
-
Explanation
Issue
#2711reports a document-opening failure caused by placing a table inside paragraph children. The reviewed change updates onlydocs/usage/tables.md, as shown by the commit history and supplied change summary. It does not implement the stated converter change to return(Paragraph | Table)[]and place the table directly in section children. No automated regression test proves valid document output.Resolution
Implement the converter change described in the PR. Add an automated regression test that verifies a generated document places the table as a section child and passes the relevant document validation.
-
Finishing Touches
-
🧪 Generate unit tests (beta)
-
- Commit to this branch
- Create a new PR
-
- Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.
Comment @coderabbitai help to get the list of available commands.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #3859 +/- ##
=========================================
Coverage 100.00% 100.00%
=========================================
Files 576 576
Lines 27809 27809
Branches 10186 10186
=========================================
Hits 27809 27809 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
Closes #2711
Problem
#2711's attached code converts a rich text editor's HTML to docx, and puts each table in a paragraph:
That writes a
w:tblinside aw:p, which Word can't open. The Open XML SDK validator reports it asThe element has invalid child element 'w:tbl'at/w:body/w:p[2].Since 9.13.0 (#3790, for #2395) TypeScript rejects that line. Type-checking the attached code gives
Type 'Table' is not assignable to type 'ParagraphChild'with 9.15.0, and nothing with 9.12.0. Plain JavaScript still writes the broken file, though, and the docs never said where a table can go: tables.md only says to add it to the section.Change
tables.md's intro now says a table goes next to paragraphs, in a section's, header's, footer's, cell's or text box's
children, never in a paragraph's, and gives the TypeScript error.The fix for the converter is to return
(Paragraph | Table)[]and push the table itself. With the table in the section'schildren, the same document passes the validator.Not in this PR
There's no runtime check in
Paragraph, as #3790 also left out.Summary by CodeRabbit