Skip to content

fix(docx): avoid private numbering APIs and simplify layout mappings - #3225

Merged
nperez0111 merged 1 commit into
mainfrom
fix/ci-run-39560995707
Oct 22, 2026
Merged

nperez0111 merged 1 commit into
mainfrom
fix/ci-run-39560995707

Conversation

@nperez0111

@nperez0111 nperez0111 commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Fix the DOCX exporter failure in Fresh Install Tests run 39560995707 and simplify brittle mapping boundaries.

Rationale

The locked docx 9.9.0 passes, but fresh resolution to 9.13.0 removes the private Paragraph.properties.numberingReferences field. Seven exporter tests then crash while indenting nested content. This fix tracks the indentation behavior we own instead of inspecting docx internals.

Changes

  • Add createDOCXParagraph, returning a normal docx Paragraph with WeakSet-backed numbering metadata. Built-in list mappings use it; custom child-placement mappings continue receiving real paragraphs, not wrappers.
  • Replace column mappings' TableCell casts and options inspection with explicit { type: "column", width, children } objects, constructing cells only at the column-list boundary. Reject misplaced columns with contextual errors.
  • Keep all full XML snapshots. Normalize only empty optional image descr/title attributes, which newer docx versions omit; update that single snapshot line.
  • Add nesting, custom mapping compatibility/indentation, and malformed layout regression coverage.

Impact

No dependency, lockfile, or CI changes. Custom numbered/bulleted mappings must use createDOCXParagraph instead of new Paragraph to avoid extra nesting tabs; raw paragraphs remain accepted, but their private numbering settings are no longer inspected. This distinction is documented in the helper and covered by tests.

Testing

  • 14 exporter tests, including all full snapshots, pass with both locked docx 9.9.0 and freshly resolved 9.13.0. Dependency changes used for reproduction were restored.
  • Math (2) and diagram (7) DOCX integration tests pass.
  • Type-aware lint, formatting, and whitespace checks pass.
  • New regression tests were verified failing before their fixes, including the custom child-placement compatibility regression found during review.
  • The earlier core run passed 103 files / 1,359 tests. The complete repository suite remains blocked locally by the missing generated @blocknote/xl-typst-compiler/pkg WASM artifact; it is not claimed green.
  • Independent review completed; recommendations implemented and follow-up review found no remaining blockers.

Additional Notes

Related prior DOCX upgrade fixes: #3139 and #3170. This avoids another private-API repair while retaining the fresh-dependency CI coverage and full snapshots.

Summary by CodeRabbit

  • Bug Fixes
    • Improved indentation in exported Word documents: nested paragraphs are indented while numbered and bulleted list items retain their intended alignment.
    • Column layouts now preserve column proportions, and invalid layouts are rejected instead of producing malformed output.
  • New Features
    • Added support for custom paragraph formatting and placement in DOCX exports.

@vercel

vercel Bot commented Oct 22, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
blocknote Ready Ready Preview Oct 22, 2026 2:11am UTC
blocknote-website Ready Ready Preview Oct 22, 2026 2:11am UTC

Request Review

@coderabbitai

coderabbitai Bot commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

Review in Change Stack →

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration
  • Configuration used: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 603268e1-524f-42ad-9c39-e887612ab2d5
📥 Commits

Reviewing files that changed from the base of the PR and between a7c9538 and 1acb4a9.

⛔ Files ignored due to path filters: 1
  • packages/xl-docx-exporter/src/docx/__snapshots__/basic/document.xml is excluded by !**/__snapshots__/**
📒 Files selected for processing: 5
  • packages/xl-docx-exporter/src/docx/defaultSchema/blocks.ts
  • packages/xl-docx-exporter/src/docx/docxExporter.test.ts
  • packages/xl-docx-exporter/src/docx/docxExporter.ts
  • packages/xl-docx-exporter/src/docx/index.ts
  • packages/xl-docx-exporter/src/docx/mapping.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 7 remain after this review.

📝 Walkthrough

The DOCX exporter now uses shared block result types, tracks paragraph indentation separately from list numbering, and represents columns with intermediate descriptors. Column lists validate their children and build table cells from the validated descriptors.

Changes: DOCX export behavior

Layer / File(s) Summary
Mapping contracts and paragraph processing
packages/xl-docx-exporter/src/docx/mapping.ts, packages/xl-docx-exporter/src/docx/docxExporter.ts, packages/xl-docx-exporter/src/docx/defaultSchema/blocks.ts, packages/xl-docx-exporter/src/docx/index.ts, packages/xl-docx-exporter/src/docx/docxExporter.test.ts
DOCX mappings use shared result types. Paragraphs created with numbering or bullet options are tracked separately, and the exporter applies indentation tabs to paragraphs accepted by isTabIndentedParagraph. Tests cover nested indentation, list behavior, custom mappings, and XML snapshot normalization.
Column descriptor layout
packages/xl-docx-exporter/src/docx/mapping.ts, packages/xl-docx-exporter/src/docx/defaultSchema/blocks.ts, packages/xl-docx-exporter/src/docx/docxExporter.test.ts
Column blocks return descriptors with widths and flattened content. Column lists validate their children and build table cells with calculated widths. Tests cover invalid column placement and layouts.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Bug fix

Suggested reviewers: yousefed, areknawo

Merge Risk: ⚪ Minimal · up to 1acb4

No identified issue currently blocks merging after normal checks.

Pre-merge checks: Passed 4 · Failed 1

Failed Failed checks: 1 warning

Check name Status Explanation Resolution
Docstring Coverage Warning Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 4 functions across 5 files. Write docstrings for the functions missing them to satisfy the coverage threshold.
Passed Passed checks: 4 passed
Check name Status Explanation
Title check Passed The title clearly identifies the DOCX numbering API fix and the mapping simplification, which are the main changes in the pull request.
Description check Passed The description covers the summary, rationale, changes, impact, testing, and additional notes with specific technical context. The Screenshots/Video and Checklist sections are omitted, but the descrip…
Linked Issues check Passed No active directly linked issue remains. Issue #3139 is closed and supplies historical context only. Its coding requirements do not apply to this pull request.
Out of Scope Changes check Passed The reported changes stay within the pull request scope: DOCX paragraph metadata, column-boundary handling, contextual validation, snapshot normalization, and regression tests address the stated DOCX …
Full details: Description check

Explanation

The description covers the summary, rationale, changes, impact, testing, and additional notes with specific technical context. The Screenshots/Video and Checklist sections are omitted, but the description is otherwise complete and sufficiently detailed.

Full details: Out of Scope Changes check

Explanation

The reported changes stay within the pull request scope: DOCX paragraph metadata, column-boundary handling, contextual validation, snapshot normalization, and regression tests address the stated DOCX exporter failure and mapping-boundary objectives. No unrelated dependency, lockfile, or CI changes are reported.

✨ Finishing Touches: 💡 1
📝 Generate docstrings: 💡
  • Commit to this branch
  • Create a new PR
🧪 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.

❤️ Share

A rabbit checks each paragraph’s place
And keeps list numbers in their space
Columns line up, their widths made clear
The DOCX pages hop without a fear
One final nibble: snapshots agree

Comment @coderabbitai help to get the list of available commands.

@pkg-pr-new

pkg-pr-new Bot commented Oct 22, 2026 •

Copy link
Copy Markdown

Open in StackBlitz

@blocknote/ariakit

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/ariakit@3225

@blocknote/code-block

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/code-block@3225

@blocknote/core

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/core@3225

@blocknote/diagram-block

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/diagram-block@3225

@blocknote/mantine

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/mantine@3225

@blocknote/math-block

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/math-block@3225

@blocknote/react

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/react@3225

@blocknote/server-util

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/server-util@3225

@blocknote/shadcn

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/shadcn@3225

@blocknote/xl-ai

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/xl-ai@3225

@blocknote/xl-docx-exporter

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/xl-docx-exporter@3225

@blocknote/xl-email-exporter

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/xl-email-exporter@3225

@blocknote/xl-multi-column

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/xl-multi-column@3225

@blocknote/xl-odt-exporter

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/xl-odt-exporter@3225

@blocknote/xl-pdf-exporter

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/xl-pdf-exporter@3225

@blocknote/xl-typst-exporter

npm i https://pkg.pr.new/TypeCellOS/BlockNote/@blocknote/xl-typst-exporter@3225

commit: 1acb4a9

@github-actions

github-actions Bot commented Oct 22, 2026 •

Copy link
Copy Markdown
PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-10-22 02:25 UTC

@nperez0111
nperez0111 merged commit eeee854 into main Oct 22, 2026
37 checks passed
@nperez0111
nperez0111 deleted the fix/ci-run-39560995707 branch October 22, 2026 02:24

This branch was successfully deployed

2 active deployments
Preview – blocknote-website — 1acb4a9d Deployed Oct 22, 2026 by vercel[bot]
Preview – blocknote — 1acb4a9d Deployed Oct 22, 2026 by vercel[bot]
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