@beyondwork/docx-react-component 1.0.0

package/docs/architecture/xlsx/canonical-workbook-model-and-commands.md

@@ -0,0 +1,187 @@
+# Canonical Workbook Model And Commands
+
+## Status
+
+- Planned canonical model for the future `xlsx` runtime.
+- Not implemented in source today.
+- Intended to align the xlsx planning work with the current repo's runtime-first, command-driven architecture.
+
+## Purpose
+
+This document defines what should remain canonical in a spreadsheet runtime and what should remain derived.
+
+The goal is to keep the workbook model:
+
+- sparse and serializable
+- safe for import and export
+- compatible with command and transaction boundaries
+- honest about preserve-only content
+
+## Core Rules
+
+- The workbook runtime owns the only canonical state.
+- React renders runtime projections and never mutates canonical workbook state directly.
+- Commands produce transactions, mappings, effects, and history boundaries.
+- Structural edits must remap anchors, ranges, comments, merges, and references.
+- Unsupported but preservable workbook content must stay in preservation state, not be flattened into "best effort" workbook data.
+
+## Canonical Stores
+
+The planned xlsx runtime should keep the same broad separation of concerns as the current docx runtime:
+
+- content model
+- review or annotation model
+- preservation model
+- diagnostics and compatibility state
+
+### Content Model
+
+The content model should own:
+
+- workbook metadata
+- sheet registry and ordering
+- sparse cell storage
+- formulas and cached values
+- row and column properties
+- merges
+- workbook-level named items
+- style references and workbook-wide style registries
+
+### Annotation Model
+
+The annotation model should own:
+
+- notes or legacy comments if supported
+- future threaded comment preservation data
+- cell or range anchors for annotations
+
+### Preservation Model
+
+The preservation model should own:
+
+- unknown parts and relationships
+- preserve-only workbook features
+- extension markup and compatibility payloads
+- locked-region metadata required to explain blocked edits
+
+## Sparse Workbook Shape
+
+The canonical workbook should be sparse by default.
+
+That means:
+
+- empty cells are omitted from canonical storage
+- non-default row and column metadata is stored sparsely
+- merges, notes, hyperlinks, and other anchored objects are stored as separate collections
+
+This avoids pretending a spreadsheet is a dense DOM-shaped tree.
+
+## Cell Value Strategy
+
+Canonical cell state should preserve semantic type without coercing everything into a single JavaScript value shape.
+
+Minimum value families:
+
+- empty
+- text
+- number
+- boolean
+- error
+- formula
+- rich or formatted text if supported later, otherwise preserve-only
+
+The runtime may maintain derived caches for display or performance, but canonical state must remain export-safe.
+
+## Formula Strategy
+
+Formulas should be first-class runtime entities even if the editor does not ship a full Excel-compatible calculation engine.
+
+The canonical model should retain:
+
+- formula text
+- reference tokens needed for remapping
+- cached value when present
+- enough structure to support safe row, column, and range edits
+
+If a formula family cannot be remapped safely, the relevant structural edit should warn, block, or remain preserve-only.
+
+## Selection And Anchor Strategy
+
+Selection should be grid-native, not text-editor-shaped.
+
+Minimum runtime selection surfaces:
+
+- active sheet
+- active cell
+- primary range
+- optional multi-range support
+- selection mode for cells, rows, columns, or full-sheet operations
+
+Mapped anchors should also support:
+
+- notes or comments
+- hyperlinks
+- preserve-only object references
+- future named ranges and table surfaces
+
+## Command And Transaction Model
+
+Every mutation should flow through typed spreadsheet commands.
+
+Representative command families:
+
+- set cell value
+- set formula
+- apply styles
+- insert or delete rows
+- insert or delete columns
+- merge or unmerge cells
+- add, rename, reorder, or delete sheets
+- freeze or clear panes
+- add or edit supported note surfaces
+
+Each transaction should produce:
+
+- next workbook state
+- mapping data for remapping selections and anchored objects
+- effects for UI or host notifications
+- history boundary metadata
+
+## Preserve-Only Boundary
+
+The canonical model must not over-claim ownership.
+
+Examples of likely preserve-only workbook surfaces in early xlsx work:
+
+- threaded comments
+- pivot caches and pivot tables
+- charts and complex drawing graphs
+- advanced extension lists
+- rich value families
+- features that require rewriting unknown extension parts
+
+Those surfaces should stay in preservation state until they have package-backed proof and Excel reopen evidence.
+
+## Relationship To The Shared Platform
+
+This doc intentionally stops at workbook semantics.
+
+The following concerns belong to the shared platform instead:
+
+- OPC package reading and writing
+- preserved part reattachment
+- compatibility taxonomy and export blockers
+- validator service integration
+- snapshot and persistence doctrine
+
+See `docs/architecture/platform/shared-openxml-editor-platform.md` for that shared layer.
+
+## Source Research Mapping
+
+This canonical doc is derived from research in:
+
+- `docs/xlsx-react/canonical-workbook-model-and-commands.md`
+- `docs/xlsx-react/spreadsheet-editor-component-architecture.md`
+- `docs/xlsx-react/spreadsheet-editor-frontend-architecture.md`
+
+The research sources remain useful design rationale, but this file is the repo-aligned planned canonical model reference.

package/docs/architecture/xlsx/spreadsheet-editor-frontend-architecture.md

@@ -0,0 +1,150 @@
+# Spreadsheet Editor Frontend Architecture
+
+## Status
+
+- Planned canonical architecture for the future `xlsx` runtime.
+- No `SpreadsheetEditor` implementation is shipped in this repo today.
+- This doc translates the strongest `docs/xlsx-react` research into a repo-aligned architecture that matches the current runtime-first philosophy without pretending the source already exists.
+
+## Role In The Repo
+
+This document is the `xlsx` sibling to the current docx frontend architecture.
+
+Use it together with:
+
+- `docs/architecture/platform/shared-openxml-editor-platform.md`
+- `docs/architecture/xlsx/canonical-workbook-model-and-commands.md`
+- `docs/reference/xlsx/xlsx-ooxml-compliance.md`
+- `docs/plans/xlsx/xlsx-fixture-corpus-and-certification-plan.md`
+
+## Frontend Doctrine
+
+- The workbook runtime owns canonical truth.
+- React renders runtime projections and dispatches commands.
+- The grid surface is spreadsheet-native and performance-driven.
+- UI state remains presentation-only: tabs, panel visibility, theme, and transient edit buffers.
+- Export safety and preserve-only states are visible in the UI instead of being hidden behind implicit behavior.
+
+## Editor Shape
+
+The target public surface is a single embeddable component:
+
+```tsx
+<SpreadsheetEditor />
+```
+
+That component should remain uncontrolled by default, matching the current `WordReviewEditor` philosophy:
+
+- host provides initial source or snapshot
+- runtime owns the live session
+- host receives typed events, warnings, errors, snapshots, and exports
+
+## Rendering Stack
+
+The spreadsheet editor should keep the same broad discipline as the docx runtime while using spreadsheet-appropriate rendering:
+
+- React shell for layout, panels, and tool surfaces
+- imperative or headless grid surface controller for scrolling, hit-testing, and keyboard flow
+- runtime-owned render snapshot consumed through `useSyncExternalStore`
+- token-driven theme system rather than one-off inline styling
+
+## High-Level Component Hierarchy
+
+```text
+SpreadsheetEditor
+└── SpreadsheetWorkspace
+    ├── TopBar
+    │   ├── NameBox
+    │   ├── FormulaBar
+    │   └── Toolbar
+    ├── GridViewport
+    │   ├── GridSurfaceHost
+    │   └── GridOverlays
+    ├── RightRail
+    │   ├── CommentsOrNotes
+    │   └── HealthPanel
+    ├── SheetTabs
+    └── StatusBar
+```
+
+## Runtime And UI Boundary
+
+The boundary should match the current repo's strongest invariant:
+
+```text
+UI -> Command -> Transaction -> State Update -> Render
+```
+
+Rules:
+
+- React never owns workbook truth.
+- The grid surface never bypasses the runtime.
+- Formula edits, range edits, merge edits, and structural sheet edits all flow through typed commands.
+- Render snapshots may be denormalized for visible regions, but persisted snapshots stay separate.
+
+## Module Boundaries
+
+Target source ownership for the `xlsx` frontend should stay explicit:
+
+```text
+src/formats/xlsx/
+  api/
+  model/
+  core/
+    commands/
+    selection/
+    formulas/
+    grid-math/
+  io/
+  preservation/
+  validation/
+  runtime/
+  ui/
+    headless/
+    grid-surface/
+    react/
+```
+
+This is a target-state layout, not a claim that these directories already exist.
+
+## Capability Model
+
+The editor should derive session capabilities from runtime state rather than local UI guesses.
+
+Minimum capability surfaces:
+
+- `canEdit`
+- `canUndo`
+- `canRedo`
+- `canExport`
+- `exportBlocked`
+- `preserveOnlyCount`
+- `unsupportedFatalCount`
+- `canEditFormulas`
+
+## UX Honesty Rules
+
+- Spreadsheet features are either `supported-roundtrip`, `preserve-only`, or `unsupported-fatal`.
+- Preserve-only content must remain visible and explainable.
+- Locked or blocked regions must surface through the health rail and status bar.
+- Unsupported structures must not be rewritten optimistically.
+
+## Current Scope Boundary
+
+This architecture is intentionally for the future `xlsx` runtime only.
+
+It does not change:
+
+- the current `WordReviewEditor` public API
+- the docx-specific ProseMirror editing surface
+- the current docx wave maturity line
+
+## Source Research Mapping
+
+This canonical doc is derived from research in:
+
+- `docs/xlsx-react/spreadsheet-editor-frontend-architecture.md`
+- `docs/xlsx-react/spreadsheet-editor-component-architecture.md`
+- `docs/xlsx-react/canonical-workbook-model-and-commands.md`
+
+The research papers remain useful source material, but this file is the repo-aligned planned architecture reference.