@beyondwork/docx-react-component 1.0.0

package/docs/research/xlsx/raw/README.md

@@ -0,0 +1,13 @@
+# Raw XLSX Research
+
+This directory is reserved for raw imported xlsx research reports that have not yet been cleaned, classified, or promoted.
+
+Current xlsx research intake still lives under:
+
+- `docs/xlsx-react/`
+
+Policy:
+
+- keep cleaned research papers in `docs/xlsx-react/`
+- promote repo-aligned planned docs into `docs/architecture/xlsx/`, `docs/reference/xlsx/`, and `docs/plans/xlsx/`
+- remove raw duplicate reports when an equivalent cleaned paper already exists

package/docs/roadmap.md

@@ -0,0 +1,174 @@
+# Roadmap
+
+Ship `WordReviewEditor` as a finished, usable docx component.
+
+Everything in this roadmap is scoped to what the README promises: a fidelity-first React component that opens, edits, and exports `.docx` files without damage. Multi-format work (xlsx, pdf) starts after this ships.
+
+## What Works Today
+
+- OOXML import/export with Word round-trip fidelity (F01–F21 fixtures)
+- Track changes: insert/delete/formatting revisions, accept/reject
+- Comments: anchored, threaded, resolve/reopen
+- Paragraphs, headings, numbered clauses, lists
+- Hyperlinks, inline images
+- Preservation system: unsupported OOXML survives round-trip
+- ProseMirror-based editing surface with prosemirror-tables integration
+- Compatibility report and export gating
+- Rich formatting marks: font family, font size, text color, highlight, superscript, subscript, small caps, all caps, paragraph alignment
+- Image insertion (`insertImage` command)
+- Search/highlight plugin (case-sensitive, regex, highlight color)
+- `useDocxEditor()` imperative hook exposing full editor API
+- Headless CLI: `docx info`, `docx convert`, `docx validate`
+- Complete paragraph properties: spacing (before/after/line), indentation (left/right/firstLine/hanging), tab stops, keepNext, keepLines, outlineLevel, pageBreakBefore
+- Complete run properties: doubleStrikethrough, vanish, lang, backgroundColor
+- Complete table properties: per-side borders, cell margins, shading, width, alignment, row height, header row flag
+- Field codes (`w:fldSimple` and complex fields), bookmarks, section breaks
+- Extended paragraph properties: widowControl, paragraph borders (pBdr), paragraph shading, bidi, suppressLineNumbers, cnfStyle
+- Extended run properties: charSpacing, kerning, emboss, imprint, shadow, vertical position, textFill (w14:textFill preserved)
+- Table model: tblLook (firstRow/lastRow/firstColumn/lastColumn/banding flags)
+- Inline types: column breaks, symbol characters
+- Latent style catalog support
+- Headers and footers: default, first-page, even/odd variants; `w:headerReference` / `w:footerReference` linked from section properties
+- Footnotes and endnotes: `FootnoteCollection` type, `FootnoteRefNode` inline, superscript numbering
+- Theme parsing: theme colors and fonts from `theme1.xml` captured in `subParts.theme` for future resolution work
+- Structural block types: SDT blocks, custom XML wrappers, altChunk relationship preservation, nested tables, and floating-image anchor metadata with inline editor fallback
+- Track change extensions: property change revisions for pPrChange (preserve-only with metadata), sectPrChange and tblPrChange (actionable accept/reject), rPrChange (preserve-only with metadata); move tracking via moveFrom/moveTo with linked move IDs
+- Complex content rendering: charts (ChartPreviewNode), SmartArt (SmartArtPreviewNode), wps shapes (ShapeNode), WordArt (WordArtNode), VML elements (VmlShapeNode) — read-only labeled preview with rawXml round-trip preservation
+
+## What's Missing to Ship
+
+1. **npm package** — `private: true`, no published artifact.
+2. **API docs** — no reference for consumers to integrate against.
+3. **Validation in CI** — OpenXML SDK validator service exists but is not wired into PR validation yet.
+4. **Remaining OOXML fidelity gaps** — theme values are parsed and preserved from `theme1.xml`, but not yet resolved into style inheritance or exposed as authored theme edits/export.
+5. **Production hardening** — accessibility, large-document performance, and long-session memory still need closure.
+
+---
+
+## Phase 1: Tests Run (complete)
+
+**Goal:** `pnpm test` passes reliably. CI catches regressions.
+
+- [x] `pnpm test:repo` passes from clean install
+- [x] GitHub Actions CI: lint + type-check + test on PR/push to main
+- [x] All test files pass, including fixture round-trip coverage
+- [ ] CI badge in README
+
+**Exit:** `pnpm test:repo` green on main. PR merges blocked on red CI.
+
+---
+
+## Phase 2: Editing & OOXML Fidelity (advancing)
+
+**Goal:** Close the biggest docx editing and fidelity gaps before package/publish work.
+
+- [x] Wave 20 landed first-class table editing at `baseline-proved`
+- [x] Wave 28 landed editor feature parity: rich formatting marks, image insertion, search/highlight, `useDocxEditor`, headless CLI
+- [x] Wave 29 landed OOXML parsing fidelity for paragraphs, runs, tables, fields, bookmarks, and section breaks
+- [x] Wave 32 landed remaining OOXML property completeness for paragraphs, runs, tables, and inline types
+- [x] Wave 33 landed headers, footers, footnotes, and endnotes under `document-sub-parts`
+- [x] Wave 34 landed structural block type support under `structural-block-types`: SDT, custom XML wrappers, altChunk preservation, nested tables, floating-image metadata
+- [x] Wave 35 landed track change extensions under `track-change-extensions`: property change revisions (sectPrChange, tblPrChange actionable; pPrChange, rPrChange preserve-only with metadata) and move tracking (moveFrom/moveTo with linked move IDs)
+- [x] Wave 36 landed complex content rendering under `complex-rendering`: charts, SmartArt, wps shapes, WordArt, and VML as read-only labeled previews with rawXml round-trip preservation; 5 new canonical inline types; dedicated PM atoms
+- [ ] Resolve theme colors/fonts from `theme1.xml` into style inheritance
+- [ ] If theme editing becomes in-scope, add authored theme export and proof
+
+**Exit:** Remaining Phase 2 fidelity claims have durable proof and no shared-plan overclaim remains.
+
+---
+
+## Phase 3: API Reference & npm Package
+
+**Goal:** Ship the component so others can actually use it.
+
+### Documentation
+- [ ] `docs/reference/api-reference.md` — every prop, ref method, event, and exported type
+- [ ] `docs/reference/quick-start.md` — install, import, render, load a .docx, export
+- [ ] `docs/reference/integration-guide.md` — datastore adapter, autosave, persistence, controlled reload
+
+### Package
+- [ ] Remove `"private": true` from package.json
+- [ ] Configure npm publish workflow (GitHub Actions on release tag)
+- [ ] Set ESM entry points and type declarations
+- [ ] Declare peer dependencies (React, ProseMirror)
+- [ ] Published to npm as scoped package
+
+### README
+- [ ] Rewrite README: what it does, install command, working code example, link to API docs
+- [ ] Remove architecture-umbrella language (multi-format, shared platform, pdf track)
+- [ ] Lead with the shipped product, not the vision
+
+**Exit:** `npm install <package>` works. README has a working code example. API reference covers every public surface.
+
+---
+
+## Phase 4: OpenXML Validator in CI
+
+**Goal:** Every PR is validated against the Microsoft Open XML SDK.
+
+- [ ] Validator service containerized for CI
+- [ ] CI step: export all fixtures → run through SDK validator → fail on errors
+- [ ] Validation results visible in PR checks
+- [ ] Word reopen smoke test documented as manual release gate
+
+**Exit:** PR CI includes "OpenXML SDK validation: 0 errors" for all fixture exports.
+
+---
+
+## Phase 5: Legal Workflow Features
+
+**Goal:** Version compare and legal semantics — the features that make this a legal tool.
+
+### Version Compare
+- [ ] Snapshot versioning: save named document versions
+- [ ] Diff engine: compare two canonical documents, produce changeset
+- [ ] Compare view: side-by-side or inline diff rendering
+- [ ] Export compared document with changes tracked
+
+### Legal Semantics
+- [ ] Cross-references: parse, render, navigate
+- [ ] Defined terms: highlight and navigate
+- [ ] Bookmarks/anchors: preserve and navigate
+
+**Exit:** Load v1 and v2 of a contract → see tracked differences → export with redlines. Cross-refs and defined terms navigable.
+
+---
+
+## Phase 6: Production Hardening
+
+**Goal:** Performant, accessible, resilient for real-world use.
+
+- [ ] Large document handling (100+ page contracts, < 3s load)
+- [ ] WCAG 2.1 AA compliance, keyboard navigation, screen reader support
+- [ ] Graceful handling of malformed .docx files
+- [ ] No memory leaks on long editing sessions
+- [ ] Browser compatibility: Chrome, Firefox, Safari, Edge
+
+**Exit:** Lighthouse accessibility ≥ 90. 100-page doc loads in < 3s. No memory growth over 1-hour session.
+
+---
+
+## Priority Order
+
+| # | Phase | Why |
+|---|-------|-----|
+| 1 | Tests in CI | Complete and now the baseline for all follow-on waves |
+| 2 | Editing & OOXML fidelity | Still the active docx capability track before packaging |
+| 3 | API docs + npm | Makes it usable by others |
+| 4 | Validator in CI | Prevents regressions |
+| 5 | Legal features | High-value workflow features |
+| 6 | Hardening | Production readiness |
+
+## What's Deferred
+
+- **xlsx shipping** — the xlsx foundation (Wave 25: canonical workbook model + SpreadsheetML import) has started as a parallel track, but a shipped `SpreadsheetEditor` surface is after docx ships. Separate maturity line, separate fixtures, separate Excel certification bar.
+- **pdf** — future exploration. Not part of this roadmap.
+- **Shared OOXML platform extraction** — do it in code when xlsx needs it, not before.
+- **Source tree restructuring** — the `src/formats/xlsx/` layout is in use for Wave 25 work; full `src/platform/` extraction deferred until after docx ships.
+
+## What's Cut
+
+- Wave 10 "qa-proved certification" ceremony — replaced by Phase 1 (real CI)
+- Wave 11 "fleet-ready packaging" ceremony — replaced by Phase 3 (real npm publish)
+- Waves 12–17 architecture exploration docs — absorbed into focused feature phases
+- Multi-format public API planning — premature until docx ships