@beyondwork/docx-react-component 1.0.1 → 1.0.3

package/README.md

@@ -2,121 +2,74 @@
 
 [![CI](https://github.com/bwllaming/React-OOXML-Office/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/bwllaming/React-OOXML-Office/actions/workflows/ci.yml)
 
-React OOXML Office is a repo for embeddable office-document runtimes, shared OOXML platform work, and host-facing review or editing surfaces.
+`docx-react-component` is now configured as an npm-ready package for the shipped product in this repository: `WordReviewEditor`, a fidelity-first React editor for legal-review-safe `docx` workflows.
 
-This repository is evolving from the original docx-first `React Word Editor` codebase into a broader layered story:
+The broader repository is still evolving toward a layered `react-ooxml-office` platform, but the source reality is unchanged:
 
-- a shared OOXML platform for package, preservation, diagnostics, and validation concerns
-- format-specific runtimes with honest capability boundaries
-- host-facing editor surfaces for each supported format
+- `docx` is the only implemented and shipped runtime contract
+- `xlsx` is the next planned OOXML sibling
+- `pdf` is future work and outside the first shared OOXML platform contract
 
-## Current Status
+## Install
 
-The code in source today is still centered on one shipped editor:
+```bash
+pnpm add docx-react-component react react-dom \
+  prosemirror-commands prosemirror-keymap prosemirror-model \
+  prosemirror-state prosemirror-tables prosemirror-transform prosemirror-view
+```
+
+Current packaging truth:
+
+- the package is ESM-only
+- exports point at shipped TypeScript source entry points
+- consumers need a bundler or runtime that can resolve `.ts` and `.tsx` ESM imports
+- package and source identifiers remain docx-first until a deliberate rename lands
+
+## Shipped Product
+
+The primary shipped surface is:
 
 ```tsx
+import { WordReviewEditor } from "docx-react-component";
+
 <WordReviewEditor />
 ```
 
-That means:
-
-- `docx` is the only implemented and shipped runtime contract in this repo today
-- `xlsx` is now documented as the next planned OOXML sibling
-- `pdf` is acknowledged as a future vertical, but it is not part of the first shared OOXML platform contract
+`WordReviewEditor` remains uncontrolled by default:
 
-The repo path, many source folders, and the internal harness are still docx-first. The docs now distinguish clearly between:
+- host passes `initialDocx` or `initialSnapshot`
+- runtime owns the live working session
+- host receives events, warnings, errors, snapshots, and exported artifacts
 
-- what is already landed
-- what is the target shared architecture
-- what is still research or future planning
+The current public ESM exports are:
 
-The `react-ooxml-office` name is currently a documentation and architecture umbrella. Package, workspace, and many source identifiers remain docx-first until a later rename is intentionally landed.
+- `docx-react-component` -> `WordReviewEditor`
+- `docx-react-component/public-types` -> public TypeScript contracts
+- `docx-react-component/ui-tailwind` -> current Tailwind UI primitives
 
-## Core Goal
+## Product Contract
 
 For every format the repo eventually ships, the standard is:
 
 > Open -> edit -> save -> reopen in the host application without damage.
 
-For the current shipped `docx` implementation, that still specifically means:
+For the current shipped `docx` implementation, that specifically means:
 
 - open in recent Microsoft Word without repair prompts
 - preserve supported content and review structures
 - preserve unsupported but preservable OOXML
 - remain editable in Word after export
 
-## Repo Principles
-
-- Compatibility first: host-format fidelity outranks convenience.
-- Structured editing over DOM editing: runtime-owned canonical state is the source of truth.
-- Preserve, do not destroy: unsupported but preservable OOXML must survive round trips.
-- Explicit capability classes: features are `supported-roundtrip`, `preserve-only`, or `unsupported-fatal`.
-- Clean UX over suite chrome: contextual, low-noise UI beats ribbon-style sprawl.
-- Separate platform, runtime, validation, preservation, and UI concerns.
-- Main-thread only for shipped runtimes unless the architecture explicitly changes.
-
-## Architecture Layers
-
-All landed and planned editor work follows the same high-level mutation path:
-
-```text
-UI -> Command -> Transaction -> State Update -> Render
-```
-
-The broader architecture is layered like this:
+## Repository Direction
 
-```text
-shared platform
-  package io, preservation, diagnostics, validation, host doctrine
+This repo is broadening from the original docx-first editor into a layered shared-OOXML story:
 
-format runtimes
-  docx runtime today
-  xlsx runtime next
-  pdf future, outside the first OOXML platform contract
-
-host surfaces
-  embeddable components, internal harnesses, certification views
-```
+- shared platform concerns for package IO, preservation, diagnostics, and validation
+- format-specific runtimes with explicit capability boundaries
+- host-facing review and editing surfaces for each supported format
 
 The canonical shared-platform overview lives in `docs/architecture/platform/shared-openxml-editor-platform.md`.
 
-## Current Landed Source Layout
-
-The truthful current source layout remains docx-first:
-
-```text
-src/
-  api/
-  model/
-  core/
-  review/
-  io/
-  preservation/
-  validation/
-  runtime/
-  ui/
-services/
-  react-word-editor/
-  openxml-validator/
-test/
-  fixtures/
-docs/
-```
-
-The target future source layout is broader, but it is still only a planning direction:
-
-```text
-src/
-  platform/
-  formats/
-    docx/
-    xlsx/
-    pdf/
-services/
-  office-harness/
-  openxml-validator/
-```
-
 ## Documentation Map
 
 Start here:
@@ -144,25 +97,12 @@ Shared platform and planned xlsx docs:
 - `docs/plans/xlsx/xlsx-fixture-corpus-and-certification-plan.md`
 - `docs/xlsx-react/README.md`
 
-## Docx Surface Today
-
-`WordReviewEditor` remains uncontrolled by default:
-
-- host passes `initialDocx` or `initialSnapshot`
-- runtime owns the live working session
-- host receives events, warnings, errors, snapshots, and exported artifacts
-
-The current shipped scope is still the legal-review-safe docx slice documented in the docx reference set. Tables, shell structures, and later legal-fidelity work remain governed by the existing wave sequence.
-
-## Validation Strategy
-
-The runtime editor does not ship the Microsoft Open XML SDK.
-
-Instead:
+## Packaging And Release
 
-- runtime and test code produce structural compatibility data in TypeScript
-- the internal validator service uses the Open XML SDK in CI and service workflows
-- Word or, later, Excel reopen behavior remains the final certification bar for supported flows
+- `.github/workflows/publish.yml` publishes on `v*` tags
+- `pnpm pack --dry-run` is the baseline package proof for this wave
+- npm provenance is enabled in `publishConfig`
+- the Microsoft Open XML SDK remains CI/internal-service only, never part of the shipped browser runtime
 
 ## Contribution Rules
 

package/package.json

@@ -1,27 +1,37 @@
 {
   "name": "@beyondwork/docx-react-component",
-  "version": "1.0.1",
+  "publisher": "beyondwork",
+  "version": "1.0.3",
   "description": "Embeddable React Word (docx) editor with review, comments, tracked changes, and round-trip OOXML fidelity.",
   "type": "module",
+  "files": [
+    "README.md",
+    "LICENSE.md",
+    "src"
+  ],
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    },
+    "./public-types": {
+      "types": "./src/api/public-types.ts",
+      "import": "./src/api/public-types.ts"
+    },
+    "./ui-tailwind": {
+      "types": "./src/ui-tailwind/index.ts",
+      "import": "./src/ui-tailwind/index.ts"
     },
     "./tailwind": {
-      "types": "./dist/tailwind.d.ts",
-      "import": "./dist/tailwind.js",
-      "require": "./dist/tailwind.cjs"
-    }
+      "types": "./src/ui-tailwind/index.ts",
+      "import": "./src/ui-tailwind/index.ts"
+    },
+    "./io/docx-session": "./src/io/docx-session.ts",
+    "./runtime/document-runtime": "./src/runtime/document-runtime.ts",
+    "./api/public-types": "./src/api/public-types.ts",
+    "./package.json": "./package.json"
   },
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "files": [
-    "dist",
-    "LICENSE.md"
-  ],
+  "types": "./src/index.ts",
   "keywords": [
     "docx",
     "word",
@@ -29,16 +39,13 @@
     "editor",
     "react",
     "comments",
-    "tracked-changes"
+    "tracked-changes",
+    "word-review",
+    "prosemirror"
   ],
   "author": "",
   "license": "SEE LICENSE IN LICENSE.md",
-  "peerDependencies": {
-    "react": ">=18",
-    "react-dom": ">=18"
-  },
-  "devDependencies": {
-    "@chllming/wave-orchestration": "^0.9.8",
+  "dependencies": {
     "@radix-ui/react-popover": "^1.1.15",
     "@radix-ui/react-scroll-area": "^1.2.10",
     "@radix-ui/react-select": "^2.2.6",
@@ -46,23 +53,36 @@
     "@radix-ui/react-toggle": "^1.1.10",
     "@radix-ui/react-toggle-group": "^1.1.11",
     "@radix-ui/react-tooltip": "^1.2.8",
+    "fflate": "^0.8.2",
+    "lucide-react": "^1.7.0"
+  },
+  "peerDependencies": {
+    "prosemirror-commands": "^1.7.1",
+    "prosemirror-keymap": "^1.2.3",
+    "prosemirror-model": "^1.25.4",
+    "prosemirror-state": "^1.4.4",
+    "prosemirror-tables": "^1.8.5",
+    "prosemirror-transform": "^1.11.0",
+    "prosemirror-view": "^1.41.7",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0"
+  },
+  "devDependencies": {
+    "@chllming/wave-orchestration": "^0.9.8",
     "@types/react": "19.2.14",
     "@types/react-dom": "19.2.3",
     "jsdom": "^29.0.1",
-    "lucide-react": "^1.7.0",
-    "react": "19.2.4",
-    "react-dom": "19.2.4",
-    "tsup": "^8.3.0",
-    "tsx": "^4.21.0"
-  },
-  "dependencies": {
     "prosemirror-commands": "^1.7.1",
     "prosemirror-keymap": "^1.2.3",
     "prosemirror-model": "^1.25.4",
     "prosemirror-state": "^1.4.4",
     "prosemirror-tables": "^1.8.5",
     "prosemirror-transform": "^1.11.0",
-    "prosemirror-view": "^1.41.7"
+    "prosemirror-view": "^1.41.7",
+    "react": "19.2.4",
+    "react-dom": "19.2.4",
+    "tsup": "^8.3.0",
+    "tsx": "^4.21.0"
   },
   "scripts": {
     "build": "tsup",

package/src/README.md

@@ -0,0 +1,85 @@
+# Source Layout
+
+The landed source tree is still organized around the active docx implementation, not around the future target office-wide layout.
+
+## Current Landed Layout
+
+```text
+src/
+  api/
+  model/
+  core/
+    schema/
+    state/
+    commands/
+    selection/
+  review/
+    store/
+  io/
+    opc/
+    ooxml/
+    normalize/
+    export/
+  preservation/
+  validation/
+  runtime/
+  ui/
+    headless/            # Shared pure logic (framework-free)
+    shared/              # Shared utilities (revision-filters)
+    WordReviewEditor.tsx  # Entry point
+  ui-tailwind/           # Default rendering (Tailwind + Radix + Lucide)
+    editor-surface/
+    toolbar/
+    review/
+    status/
+    chrome/
+    theme/
+```
+
+This is the truthful current layout for implementation work today.
+
+## Target Broader Layout
+
+The broader repo story now targets a future layout like this:
+
+```text
+src/
+  platform/
+  formats/
+    docx/
+    xlsx/
+    pdf/
+```
+
+That layout is not landed yet. Use it as a planning direction, not as evidence that the current code has already been reorganized.
+
+## UI Layer Strategy
+
+- `ui/headless/` — Pure logic: keyboard handling, decoration models, selection utilities. No React dependencies.
+- `ui-tailwind/` — Default rendering: Tailwind CSS, Radix UI primitives, Lucide icons. All styling via CSS custom properties.
+- `ui/WordReviewEditor.tsx` — Public entry point that bridges the runtime to the Tailwind layer.
+
+Legacy inline-CSSProperties components have been removed. See `docs/reference/word-review-editor-frontend-architecture.md` for the canonical frontend architecture.
+
+Keep business rules close to the subsystem that owns them. Do not centralize unrelated logic into generic utility layers.
+
+Ownership rules:
+
+- `api` exposes public contracts only.
+- `model`, `core`, `review`, `io`, `preservation`, and `validation` should remain React-free when possible.
+- `runtime` is the only mutation boundary the UI calls into.
+- `ui` consumes runtime contracts and design tokens; it does not own canonical document truth.
+
+## Broader Repo Direction
+
+As the repo broadens:
+
+- shared package and preservation concerns should move toward `src/platform/`
+- current docx runtime code remains the active implementation track until a deliberate source move lands
+- future xlsx work should gain its own source area rather than widening docx-specific modules by implication
+- future pdf work should remain separate from the first OOXML platform layer unless architecture decisions intentionally broaden it
+
+Wave 0 inventory references:
+
+- `component-inventory.md`
+  Wave-owned inventory for the major editor subsystems, their boundaries, and the promotion target for this scaffold phase.

package/src/api/README.md

@@ -0,0 +1,22 @@
+# API
+
+Public TypeScript contracts for `WordReviewEditor` belong here.
+
+This layer should expose:
+
+- component props and ref types
+- datastore adapter interfaces
+- runtime-derived position and selection projection types used by the public API
+- discriminated event unions
+- warning and error payloads
+- persisted snapshot contracts
+- export and compatibility report types
+
+Do not place runtime logic here.
+
+Frozen naming and boundary rules:
+
+- the shipped component name is `WordReviewEditor`
+- `DocumentRuntime` is an internal runtime contract, not a public React component name
+- public range references are canonical-position projections, not DOM-path handles
+- render snapshots stay in `src/runtime`; `src/api` only exposes persisted host-facing snapshot types