@beyondwork/docx-react-component 1.0.0 → 1.0.2

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

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