@beyondwork/docx-react-component 1.0.0 → 1.0.2

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

@@ -1,13 +0,0 @@
-# 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

@@ -1,174 +0,0 @@
-# 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