@beyondwork/docx-react-component 1.0.0

package/docs/reference/word-review-editor-frontend-architecture.md

@@ -0,0 +1,479 @@
+# Word Review Editor — Frontend Architecture
+
+This document is the canonical reference for the frontend implementation architecture of the React Word Editor. It governs how the design principles in `DESIGN.md` are realized in code.
+
+It remains a docx-specific implementation reference inside the broader `react-ooxml-office` repo. It is not the umbrella architecture for future xlsx or pdf work.
+
+Use this together with:
+
+- `DESIGN.md` for visual design, interaction style, and layout principles
+- `docs/reference/word-review-editor-ux-guide.md` for UX patterns and review workflow
+- `src/api/public-types.ts` for the runtime data contracts
+
+---
+
+## 1. Rendering Stack
+
+| Layer | Technology | Purpose |
+|-------|-----------|---------|
+| Layout and styling | Tailwind CSS v4 | Utility-first classes referencing CSS custom properties |
+| Primitives | Radix UI | Accessible, unstyled building blocks (tabs, selects, tooltips, toggles, scroll areas) |
+| Icons | Lucide React | Consistent, tree-shakable icon library |
+| Theme | CSS custom properties | Portable `@theme` block in `editor-theme.css` — consumers override variables for custom themes |
+| Dark mode | `.dark` class | Scoped to the editor root element, not `document.documentElement` |
+| Reduced motion | `data-reduced-motion` attribute | CSS rule disables all transitions and animations within editor scope |
+
+**No inline `CSSProperties` objects.** All styling uses Tailwind utility classes. Colors reference CSS variables (`text-primary`, `bg-canvas`, `border-border`, etc.) which resolve through the `@theme` block.
+
+---
+
+## 2. Directory Structure
+
+```
+src/
+  ui/
+    headless/                          # Pure logic — no rendering, no framework deps
+      use-editor-keyboard.ts           # Keyboard event handler factory
+      comment-decoration-model.ts      # Comment anchor → highlight computation
+      revision-decoration-model.ts     # Revision anchor → highlight computation
+      selection-helpers.ts             # Selection snapshot utilities
+    shared/                            # Shared presentational utilities
+      revision-filters.ts             # selectVisibleRevisions, describeEmptyRevisionState
+      summary-chip.tsx                 # Shared summary chip used by the review rail
+
+  ui-tailwind/                         # Styled components — Tailwind + Radix + Lucide
+    theme/
+      editor-theme.css                 # Portable CSS: @theme block, .dark overrides, animations
+    editor-surface/
+      tw-prosemirror-surface.tsx       # Default mounted ProseMirror contentEditable surface
+      pm-schema.ts                     # ProseMirror schema for the owned editor slice
+      pm-state-from-snapshot.ts        # Runtime snapshot -> ProseMirror state
+      pm-command-bridge.ts             # ProseMirror input -> runtime commands/selection
+      pm-decorations.ts                # Comment/revision decorations and clean-mode hiding
+      pm-position-map.ts               # Runtime <-> ProseMirror position mapping
+      tw-inline-token.tsx              # Tab, break, image, opaque inline tokens
+      tw-paragraph-block.tsx           # Paragraph block with heading detection
+      tw-opaque-block.tsx              # Locked region rendering
+      tw-segment-view.tsx              # Legacy segment renderer (not the default mounted path)
+      tw-caret.tsx                     # Legacy caret renderer for the older surface path
+      tw-editor-surface.tsx            # Legacy non-default surface retained during migration
+    review/
+      tw-comment-sidebar.tsx           # Comment thread cards
+      tw-revision-sidebar.tsx          # Tracked change cards with accept/reject
+      tw-health-panel.tsx              # Compatibility and warning entries
+      tw-review-rail.tsx               # Tabbed rail container (comments/changes)
+    toolbar/
+      tw-toolbar.tsx                   # Main toolbar
+      tw-toolbar-icon-button.tsx       # Reusable icon button with tooltip
+    status/
+      tw-status-bar.tsx                # Bottom status strip
+    chrome/
+      tw-alert-banner.tsx              # Fatal/blocked/warning banners
+      tw-selection-toolbar.tsx         # Floating contextual toolbar on text selection
+    tw-review-workspace.tsx            # Main workspace shell composing all chrome
+    index.ts                           # Barrel export
+```
+
+---
+
+## 3. Component Hierarchy
+
+```
+WordReviewEditor
+└── TwReviewWorkspace
+    ├── TwToolbar
+    │   ├── TwToolbarIconButton (undo, redo)
+    │   ├── TwToolbarIconButton (comment)
+    │   ├── Radix Toggle (show/hide tracked changes — display only)
+    │   ├── Radix ToggleGroup (view mode: canvas/document)
+    │   ├── Health indicator (Radix Popover with TwHealthPanel)
+    │   └── TwToolbarIconButton (export)
+    ├── TwAlertBanner (conditional: fatal, blocked, warning)
+    ├── Document Column
+    │   ├── TwSelectionToolbar (conditional: comment button + preview)
+    │   ├── TwProseMirrorSurface (ProseMirror contentEditable)
+    │   │   ├── pm-schema.ts (document schema)
+    │   │   ├── pm-state-from-snapshot.ts (snapshot → PM state)
+    │   │   ├── pm-command-bridge.ts (input → runtime commands)
+    │   │   ├── pm-decorations.ts (comment/revision highlights)
+    │   │   └── pm-position-map.ts (runtime ↔ PM positions)
+    │   └── TwStatusBar
+    └── TwReviewRail
+        ├── Radix Tabs (comments / changes)
+        ├── TwCommentSidebar (comments tab)
+        └── TwRevisionSidebar (changes tab)
+```
+
+---
+
+## 4. Data Flow
+
+```
+                    ┌──────────────────────┐
+                    │  DocumentRuntime     │
+                    │  (src/runtime/)      │
+                    └──────┬───────────────┘
+                           │ subscribe()
+                           ▼
+                    RuntimeRenderSnapshot
+                           │
+                           ▼
+              WordReviewEditor
+              (useSyncExternalStore)
+                           │
+              ┌────────────┼────────────┐
+              ▼            ▼            ▼
+        TwToolbar  TwProseMirrorSurface TwReviewRail
+        (reads       (reads surface,  (reads comments,
+         commandState) selection)      trackedChanges,
+                                       compatibility)
+```
+
+**Rules:**
+- UI components receive `RuntimeRenderSnapshot` (or slices of it) as props
+- UI components NEVER hold a second copy of canonical document state
+- All mutations flow through `DocumentRuntime` via callbacks (`onUndo`, `onAddComment`, `onAcceptRevision`, etc.)
+- UI-local state is limited to: focus, hover, panel openness, active tab, markup display mode, view mode, dark mode toggle
+
+### Planned AI action flow
+
+Future AI integration is reserved as a runtime-mediated flow, not a second editing
+stack:
+
+```text
+Host AI adapter / action executor
+            |
+            v
+    WordReviewEditor entry point
+            |
+            v
+      DocumentRuntime
+  (selection/context packaging,
+   capability checks, validation)
+            |
+            v
+  proposal / confirmation surface
+            |
+            v
+   runtime commands or workflows
+```
+
+Rules for the planned AI surface:
+
+- toolbar buttons, contextual selection tools, or review actions may launch AI requests
+- the runtime remains the sole mutation authority
+- action status and result reporting should come back through runtime-owned events or state, not optimistic local component state
+- AI proposals must be reviewed and confirmed before content-changing application
+- validate/export workflows still pass through the normal runtime compatibility gates
+
+---
+
+## 5. Editing Model
+
+The default mounted surface uses **ProseMirror contentEditable**, not
+button-per-character rendering.
+
+The ownership split is intentional:
+
+| Layer | Owns |
+|------|------|
+| `TwProseMirrorSurface` | DOM editing, native selection, IME/input composition, rendered decorations |
+| `pm-state-from-snapshot.ts` | snapshot -> ProseMirror document/state projection |
+| `pm-command-bridge.ts` | translating ProseMirror edits and selections into runtime commands/callbacks |
+| `DocumentRuntime` | canonical state, command semantics, review logic, history, validation, import/export |
+
+Editing rules:
+
+- ProseMirror is a rendering and input surface, not the source of truth
+- runtime commands remain authoritative for canonical mutations
+- selection changes are projected back into `SelectionSnapshot` shape for the rest of the app
+- `pm-position-map.ts` is the contract layer between runtime coordinates and ProseMirror positions
+- legacy segment-based renderer files may remain in the tree during migration, but the mounted default path is `TwProseMirrorSurface`
+
+---
+
+## 6. Decoration Model
+
+Comment and revision highlights are computed in the ProseMirror layer from
+runtime-owned anchor projections. The editor does not pre-bake highlight state
+into the canonical document model.
+
+Current rules:
+
+- `pm-decorations.ts` builds comment and revision decorations from runtime projections
+- clean mode always hides deletions; the tracked-changes visibility toggle only suppresses styling, not the clean-mode deletion elision
+- interactive decoration wrappers carry comment/revision ids so clicks can activate the matching sidebar item
+- active-comment and active-revision emphasis comes from runtime truth, not local DOM bookkeeping
+
+Markup-display intent still follows the same UI contract:
+
+| Mode | Comment treatment | Revision treatment |
+|------|-------------------|-------------------|
+| `clean` | hide most comment chrome, keep active context discoverable | hide deleted text and suppress markup-heavy chrome |
+| `simple` | lightweight review emphasis | lightweight insertion/deletion emphasis |
+| `all` | strongest inline review visibility | strongest inline review visibility |
+
+---
+
+## 7. Theme Contract
+
+### CSS custom properties
+
+All visual values are defined as CSS custom properties in `editor-theme.css`:
+
+```css
+@theme {
+  /* Backgrounds */
+  --color-surface: #f7f7f5;
+  --color-canvas: #ffffff;
+  --color-card: #faf8f2;
+  --color-shell-bg: #f3efe7;
+  --color-editor-frame: #f6f3ee;
+
+  /* Text */
+  --color-primary: #1f1f1f;
+  --color-secondary: #6b6b6b;
+  --color-tertiary: #616161;
+
+  /* Accent */
+  --color-accent: #1660a8;
+
+  /* Review */
+  --color-comment: #7a4f00;
+  --color-insert: #1a7f37;
+  --color-delete: #cf222e;
+
+  /* Semantic */
+  --color-warning: #7a4f00;
+  --color-danger: #cf222e;
+  --color-success: #1a7f37;
+
+  /* Borders & shadows */
+  --color-border: rgba(0, 0, 0, 0.06);
+  --color-shadow: rgba(16, 24, 40, 0.08);
+
+  /* Typography */
+  --font-legal-serif: "Source Serif 4", Georgia, serif;
+  --font-legal-sans: "Inter", system-ui, sans-serif;
+  --font-legal-mono: "JetBrains Mono", monospace;
+}
+```
+
+### Dark mode
+
+Override variables under `.dark`:
+
+```css
+.dark {
+  --color-surface: #1e1e1e;
+  --color-canvas: #191919;
+  --color-primary: #e4e4e4;
+  --color-accent: #4ca6f0;
+  --color-comment: #d4a020;
+  --color-insert: #3fb950;
+  --color-delete: #f85149;
+  /* ... full palette inversion */
+}
+```
+
+Applied via scoped class on the editor root:
+
+```tsx
+<div className={darkMode ? "dark" : undefined}>
+  <TwReviewWorkspace ... />
+</div>
+```
+
+### Custom themes
+
+Consumers override CSS variables in their own stylesheet:
+
+```css
+.my-brand-theme {
+  --color-accent: #8b5cf6;
+  --color-surface: #fafaf9;
+  --font-legal-sans: "My Brand Font", sans-serif;
+}
+```
+
+Then wrap the editor:
+
+```tsx
+<div className="my-brand-theme">
+  <WordReviewEditor ... />
+</div>
+```
+
+---
+
+## 8. Markup Display Modes
+
+| Mode | Purpose | Document font | Comment decorations | Revision decorations | Margin indicators |
+|------|---------|---------------|--------------------|--------------------|-------------------|
+| **clean** | Undistracted reading | Sans-serif | Hidden (active only: subtle bg) | Hidden (deletions removed) | Comment dots only |
+| **simple** | Subtle review chrome | Serif | Underline decorations | Underline (insert) / strikethrough (delete) | Colored left border |
+| **all** | Full markup visibility | Serif | Background wash | Colored backgrounds + text | Not needed (inline sufficient) |
+
+---
+
+## 9. Radix UI Component Usage
+
+| Radix Primitive | Usage | Component |
+|----------------|-------|-----------|
+| `Tabs` | Review rail navigation (comments/changes) | `TwReviewRail` |
+| `Toggle` | Show/hide tracked changes (display only) | `TwToolbar` |
+| `ToggleGroup` | View mode (canvas/document) | `TwToolbar` |
+| `Popover` | Health indicator with TwHealthPanel | `TwToolbar` |
+| `Tooltip` | All icon buttons, interactive elements | `TwToolbarIconButton` |
+| `ScrollArea` | Review rail scrollable content | `TwReviewRail` |
+
+---
+
+## 10. Accessibility
+
+- **Focus ring**: `focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-2 focus-visible:ring-offset-canvas` on all interactive elements
+- **Tab order**: Toolbar → document surface → review rail tabs → rail content
+- **Document surface**: ProseMirror root with `role="textbox"` and `aria-multiline="true"` on the mounted editable surface
+- **Inline review affordances**: pointer-activatable in the document, with accessible companion actions in the rail and toolbar
+- **Rail tabs**: `role="tablist"` with `aria-selected`, arrow key navigation
+- **Landmark regions**: `aria-label` on `<section>`, `<aside>`, `<header>`
+- **Reduced motion**: `data-reduced-motion="true"` disables all animations and transitions
+
+---
+
+## 11. Responsive Behavior
+
+- **Below 1024px**: Review rail collapses (hidden, accessible via toggle)
+- **Toolbar**: `flex-wrap` allows natural wrapping on narrow viewports
+- **Document canvas**: `max-w-[780px] mx-auto` for readability
+- **Page view mode**: Additional `rounded-xl ring-1 ring-border shadow-sm` frame
+
+---
+
+## 12. Public API Surface
+
+The shipped `WordReviewEditor` component exposes the Tailwind workspace by default while keeping the existing public API contract:
+
+```typescript
+// Props (input)
+interface WordReviewEditorProps {
+  documentId: string;
+  currentUser: EditorUser;
+  initialDocx?: Uint8Array | ArrayBuffer;
+  initialSnapshot?: PersistedEditorSnapshot;
+  externalDocumentRevision?: string;
+  externalDocSource?: ExternalDocumentSource;
+  reviewMode?: "editing" | "review";
+  markupDisplay?: "clean" | "simple" | "all";
+  readOnly?: boolean;
+  datastore?: EditorDatastoreAdapter;
+  autosave?: AutosaveConfig;
+  onEvent?: (event: WordReviewEditorEvent) => void;
+  onWarning?: (warning: EditorWarning) => void;
+  onError?: (error: EditorError) => void;
+}
+
+// Ref (imperative handle)
+interface WordReviewEditorRef {
+  focus(): void;
+  blur(): void;
+  undo(): void;
+  redo(): void;
+  addComment(params): string;
+  openComment(commentId): void;
+  resolveComment(commentId): void;
+  reopenComment(commentId): void;
+  addCommentReply(commentId, body): void;
+  editCommentBody(commentId, body): void;
+  acceptChange(changeId): void;
+  rejectChange(changeId): void;
+  acceptAllChanges(): void;
+  rejectAllChanges(): void;
+  exportDocx(options?): Promise<ExportResult>;
+  getSnapshot(): PersistedEditorSnapshot;
+  getCompatibilityReport(): CompatibilityReport;
+  getWarnings(): EditorWarning[];
+}
+```
+
+`viewMode` is internal workspace state, not a public prop on
+`WordReviewEditorProps`. See `docs/reference/public-api.md` for the
+authoritative public contract, including the planned post-v1 AI extension.
+
+---
+
+## 13. Migration Status
+
+1. **Tailwind shell is the default**: `src/ui/WordReviewEditor` renders the `TwReviewWorkspace` path by default.
+2. **Harness and mounted routes are aligned**: Demo and editor routes use the same shared workspace architecture.
+3. **Legacy inline-CSS surfaces are removed**: New UI work should land in `src/ui-tailwind/` plus `src/ui/headless/`.
+4. **Future expansion stays on one shell**: Wave 10+ UX, certification, and post-v1 capability work should extend the current mounted workspace rather than introduce a parallel renderer.
+
+---
+
+## 14. What This Architecture Replaces
+
+The legacy `src/ui/` implementation used:
+- 200+ inline `CSSProperties` style constants
+- `uiColors` / `uiFonts` design token objects referencing CSS variables
+- Per-component `palette` objects for semantic color mapping
+- No external CSS framework — all styling in TypeScript
+
+This architecture replaces it with:
+- Tailwind utility classes (no style constants)
+- CSS custom properties in a portable `@theme` block
+- Radix UI for accessible primitives
+- Lucide React for consistent icons
+- Headless logic hooks shared between implementations
+
+---
+
+## 15. Session Capabilities Model
+
+All UI control states are derived from `RuntimeRenderSnapshot` via `deriveCapabilities()` in `src/runtime/session-capabilities.ts`.
+
+### SessionCapabilities interface
+
+```typescript
+interface SessionCapabilities {
+  phase: "loading" | "ready" | "diagnostics" | "error";
+  mode: "editing" | "review" | "read-only-diagnostics";
+  canUndo: boolean;
+  canRedo: boolean;
+  canEdit: boolean;
+  canAddComment: boolean;
+  canExport: boolean;
+  canAcceptChange: boolean;
+  canRejectChange: boolean;
+  canAcceptAll: boolean;
+  canRejectAll: boolean;
+  reviewRailVisible: boolean;
+  trackChangesSupported: boolean;
+  exportBlocked: boolean;
+  preserveOnlyCount: number;
+  unsupportedFatalCount: number;
+  isDirty: boolean;
+  isReady: boolean;
+  hasFatalError: boolean;
+}
+```
+
+### Derivation rules
+
+- `phase` derived from `isReady` and `fatalError`
+- `mode` overrides requested `reviewMode` when diagnostics are active
+- `canEdit` requires `isReady && !readOnly && !fatalError`
+- `canAddComment` requires `canEdit && !selection.isCollapsed`
+- `canExport` requires `isReady && !blockExport && !fatalError`
+- `reviewRailVisible` is true in `review` and `read-only-diagnostics` modes, false in `editing`
+- `trackChangesSupported` is true when `trackedChanges.totalCount > 0`
+
+### reviewMode behavior
+
+- `"editing"`: Review rail hidden by default, editing controls primary
+- `"review"`: Review rail visible, comments/changes accessible, and health/trust surfaces remain reachable from toolbar chrome
+- Both modes: health/trust info always reachable, fatal errors always visible
+
+### Track changes display toggle
+
+The toolbar "Show/Hide tracked changes" toggle controls decoration visibility, not runtime mutation recording. The runtime always tracks changes internally. This is an honest display toggle, not a fake mode switch.