feat(docx-io): add docXMLater adapter layer for DOCX export #4830
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add comprehensive support for exporting Plate editor suggestions and comments to Word's native tracked changes and comments format: ## New Features ### Tracked Changes Export - Support for insertion tokens (`[[DOCX_INS_START:...]]`) → `<w:ins>` elements - Support for deletion tokens (`[[DOCX_DEL_START:...]]`) → `<w:del>` elements - Proper `<w:delText>` element usage for deleted content - Author and date metadata preservation in revision elements - Sequential revision ID tracking for Word compatibility ### Comments Export - Support for comment tokens (`[[DOCX_CMT_START:...]]`) → Word comments - Comment range markers (`<w:commentRangeStart>`, `<w:commentRangeEnd>`) - Comment reference runs (`<w:commentReference>`) - Automatic `comments.xml` file generation - Content type registration for comments part - Multi-line comment text support with paragraph splitting - Author name, initials, and date preservation ## Technical Implementation ### New Files - `tracking.ts`: Core token parsing, XML builders, and type definitions - `tracking.spec.ts`: Comprehensive test suite (397 lines) ### Modified Files - `docx-document.ts`: Added comment storage and generation methods - `xml-builder.ts`: Integrated token processing in text run building - `html-to-docx.ts`: Added comments.xml to DOCX package - `index.ts`: Exported tracking types and utilities ## API Additions ### Token Building Functions - `buildSuggestionStartToken(payload, type)` - Build insertion/deletion start - `buildSuggestionEndToken(id, type)` - Build insertion/deletion end - `buildCommentStartToken(payload)` - Build comment start with metadata - `buildCommentEndToken(id)` - Build comment end ### Tracking Utilities - `hasTrackingTokens(text)` - Check if text contains tracking tokens - `splitDocxTrackingTokens(text)` - Parse text into token segments ### DocxDocument Methods - `ensureComment(data)` - Register comment and return numeric ID - `getCommentId(id)` - Get numeric ID for string comment ID - `getRevisionId(id)` - Get numeric ID for suggestion ID - `generateCommentsXML()` - Generate comments.xml content Generated with [Claude Code](https://claude.ai/code) via [Happy](https://happy.engineering) Co-Authored-By: Claude <noreply@anthropic.com> Co-Authored-By: Happy <yesreply@happy.engineering>
- Fix hasTrackingTokens regex state issue by using non-global regex - Add bun:test imports to tracking tests - Update comments XML test to handle namespace variations Generated with [Claude Code](https://claude.ai/code) via [Happy](https://happy.engineering) Co-Authored-By: Claude <noreply@anthropic.com> Co-Authored-By: Happy <yesreply@happy.engineering>
…omments - Add parseDocxTracking.ts with utilities for parsing tracking tokens from HTML - Add comprehensive types for tracked changes (DocxTrackedChange, DocxTrackedComment) - Add parseDocxTrackedChanges() for extracting insertions/deletions - Add parseDocxComments() for extracting comments with full metadata - Add hasDocxTrackingTokens() for fast presence check - Add stripDocxTrackingTokens() for removing tokens from HTML - Export all token constants from tracking module - Add 39 tests with 98%+ coverage This enables applications using mammoth.js forks that emit tracking tokens to parse and apply tracked changes and comments to their editors. Generated with [Claude Code](https://claude.ai/code) via [Happy](https://happy.engineering) Co-Authored-By: Claude <noreply@anthropic.com> Co-Authored-By: Happy <yesreply@happy.engineering>
…mments - Add applyDocxTracking.ts: utilities for applying tracked changes and comments from parsed DOCX tokens to a Plate editor (suggestions and discussions) - Add injectDocxTrackingTokens.ts: utilities for injecting DOCX tracking tokens into editor values for export (tokens are processed by html-to-docx) - Add comprehensive tests for both modules (82+ new tests, 90%+ coverage) - Export new modules from index.ts This completes the bidirectional tracked changes support: - Import: parseDocxTracking → applyDocxTracking - Export: injectDocxTrackingTokens → html-to-docx Generated with [Claude Code](https://claude.ai/code) via [Happy](https://happy.engineering) Co-Authored-By: Claude <noreply@anthropic.com> Co-Authored-By: Happy <yesreply@happy.engineering>
- Add searchRange.ts: text search utility for locating tracking tokens in the editor after HTML deserialization - Export searchRange, searchRanges, createSearchRangeFn, and helper utilities - Add 43 comprehensive tests for search functionality - Improve applyDocxTracking tests to cover edge cases (28 tests total) Coverage results (all modules >95%): - applyDocxTracking.ts: 99.19% - parseDocxTracking.ts: 98.62% - searchRange.ts: 96.15% - injectDocxTrackingTokens.ts: 95.19% Total: 136 tests passing Generated with [Claude Code](https://claude.ai/code) via [Happy](https://happy.engineering) Co-Authored-By: Claude <noreply@anthropic.com> Co-Authored-By: Happy <yesreply@happy.engineering>
Wire up the tracking token injection into the main export plugin:
- Add DocxTrackingExportOptions type for tracking configuration
- Update DocxExportOperationOptions with optional tracking property
- Modify exportToDocxInternal to inject tokens when tracking is enabled
- Re-export tracking types and utilities from the plugin
Usage:
```typescript
// Export with tracked changes
const blob = await editor.api.docxExport.exportToBlob({
tracking: {
discussions: myDiscussions, // Comment threads
// Optional custom extractors:
// getSuggestions, getCommentIds, nodeToString
},
});
```
The tracking option enables:
- Suggestion marks → Word tracked changes (insertions/deletions)
- Comment marks → Word comments with author/date metadata
Generated with [Claude Code](https://claude.ai/code)
via [Happy](https://happy.engineering)
Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Happy <yesreply@happy.engineering>
…ation of comments is corrupted. Need to add build step for custom mammoth into plugin.
…still strike-throughing and swallowing comment.
…tilities - Add custom mammoth build as direct dependency with tracking support - Refactor import-toolbar-button.tsx to use applyTrackedCommentsLocal utility - Add convertToTDiscussion helper for discussion format conversion - Update export-toolbar-button.tsx to include discussions and nodeToString in tracking config - Remove inline applyDocxComments implementation in favor of shared utility - Add tmp/ to .gitignore - Update package.json dependencies
Replace html-to-docx with embedded docXMLater (v9.5.1) library and a comprehensive adapter layer that maps Plate editor content to OOXML. The adapter layer includes: element handlers (headings, lists, tables, code blocks, callouts, toggles, media, links, mentions, math, emoji, etc.), style mappers (CSS to DOCX), tracking bridge (comments, suggestions, diffs, revisions), document options (page size, margins, headers/footers, font defaults), sanitization (UTF-8, XML), and validation (pre-save checks, warning collection).
Review or Edit in CodeSandboxOpen the branch in Web Editor • VS Code • Insiders |
|
|
The latest updates on your projects. Learn more about Vercel for GitHub. |
dosubot
bot
added
size:XXL
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
packages/docx-io/src/lib/adapters/) with 40+ modules mapping Plate editor content to OOXMLpackages/docx-io/src/lib/index.tsTest plan
bun typecheckpasses with zero new errorsbun lint:fixpasses with zero new errors in adapter files