@syncfusion/ej2-spreadsheet

# EJ2 Spreadsheet Component Architecture ## Scope & Goals This document describes the architecture of the **EJ2 Spreadsheet Component** library as organized under the repository root: ```text ej2-spreadsheet-component/ ``` It covers: - High level layers and data flows for **Spreadsheet** (UI) and **Workbook** (data). - Key responsibilities of the `src`' folder. - Module injection, initialization paths, action system, rendering, and data binding architecture. - Integration with **Ribbon**, **Calculate** engine, and feature modules. ## High Level Architecture ### Layered View ```text Application (Angular/React/Vue/TS/JS) - Instantiates Spreadsheet - Binds data (local/remote), configures sheets, sets options - Mounts to DOM | v Spreadsheet Public API (UI Tier 1) [src/spreadsheet/base/spreadsheet.ts] - Main facade and lifecycle orchestrator - Manages UI state: selection, edit mode, clipboard, keyboard interactions - Routes user actions to model operations - Injects all Spreadsheet UI/action modules | v Spreadsheet UI Shell & Base Runtime [src/spreadsheet/base/*, src/spreadsheet/common/*] - Rendering coordination, DOM and layout management - Cell/row/column measurement and sizing - Selection, keyboard navigation, scroll handling - Ribbon, context menu, dialogs, overlays - Virtual scrolling for large datasets | +--> Feature Action Modules (UI Feature Modules) | [src/spreadsheet/actions/*] | - Auto-fill | - Cell formatting | - Clipboard | - Comment & Note | - Conditional formatting | - Data validation | - Edit, Insert, Delete | - Find & Replace | - Hyperlink | - Keyboard navigation & shortcuts | - Merge, Resize, Show/Hide | - Protect sheet | - Scroll, Selection | - Undo/Redo | - Virtual scroll | - Wrap | v Spreadsheet Integrations (Component-Level Integrations) [src/spreadsheet/integrations/*] - Chart integration - Color picker - Context menu integration - Filter UI - Formula bar UI - Formula helpers - Image integration - Number formatting UI bridge - File Open (via server endpoint) - File Save/Export (via server endpoint) - Ribbon integration - Sheet tab management - Sorting UI | v Spreadsheet Renderer (UI Rendering Layer) [src/spreadsheet/renderer/*] - Cell renderer - Row renderer - Sheet renderer - Print renderer - Frozen row/column rendering - Hyperlink overlays - Virtual viewport renderer | v Workbook Model (Data Tier 2) [src/workbook/*] - Central data model: workbook, sheets, rows, columns, cells - Range operations: insert/delete, merge, wrap, copy, clear - Data binding (local & remote) - Formatting rules storage - Hyperlinks, notes, comments (model persistence) - Validation rules, protection state - Undo/redo action recording - Import/export JSON model (bridge to server) | +--> Workbook Action Modules | [src/workbook/actions/*] | - Auto-fill | - Cell formatting | - Conditional formatting | - Data validation | - Delete, Insert | - Edit, Merge | - Hyperlink | - Find & Replace | - Protect sheet | +--> Workbook Integrations | [src/workbook/integrations/*] | - Chart data model | - Image anchors | - Open/import (Excel→JSON) | - Save/export (JSON→Excel/PDF/CSV) | - Formula helpers | - Data-binding logic | +--> Workbook Services | [src/workbook/services/*] | - Service locator | - Shared helpers | v Calculate Engine (Tier 3 — Shared Calculation Engine) [src/calculate/*] - Formula parser - 150+ Excel-compatible formulas - Dependency graph & recalculation pipeline - Cross-sheet reference resolution - Named ranges - Custom (user-defined) function support - Error propagation (#DIV/0, #REF, #VALUE, circular refs) ``` ## Source Layout (relative to repo root) ```text ej2-spreadsheet-component/ ├── package.json └── src/ ├── index.ts ├── calculate/ # Formula engine (shared) │ ├── base/ │ │ ├── calculate.ts │ │ ├── parser.ts │ │ └── index.ts │ ├── common/ │ │ ├── enum.ts │ │ ├── interface.ts │ │ └── common.ts │ │ └── index.ts │ ├── formulas/ # 150+ Excel-compatible functions │ │ ├── basic.ts │ │ └── index.ts │ └── index.ts │ ├── ribbon/ # Ribbon control (Rendering) │ ├── ribbon.ts │ └── index.ts │ ├── spreadsheet/ # UI (Tier 1) │ ├── base/ │ │ ├── spreadsheet.ts # Main facade & orchestrator │ │ └── index.ts │ │ │ ├── common/ │ │ ├── class.ts │ │ ├── constant.ts │ │ ├── enum.ts │ │ ├── event.ts │ │ ├── interface.ts │ │ ├── module.ts │ │ ├── util.ts # Utility function │ │ └── index.ts │ │ │ ├── actions/ # Feature action modules │ │ ├── auto-fill.ts │ │ ├── cell-format.ts │ │ ├── clipboard.ts │ │ ├── comment.ts │ │ ├── conditional-formatting.ts │ │ ├── data-validation.ts │ │ ├── delete.ts │ │ ├── edit.ts │ │ ├── find-and-replace.ts │ │ ├── hyperlink.ts │ │ ├── insert.ts │ │ ├── keyboard-navigation.ts │ │ ├── keyboard-shortcut.ts │ │ ├── merge.ts │ │ ├── note.ts │ │ ├── protect-sheet.ts │ │ ├── resize.ts │ │ ├── scroll.ts │ │ ├── selection.ts │ │ ├── show-hide.ts │ │ ├── undo-redo.ts │ │ ├── virtual-scroll.ts │ │ ├── wrap.ts │ │ └── index.ts │ │ │ ├── integrations/ # Dependent component feature integrations │ │ ├── chart.ts │ │ ├── color-picker.ts │ │ ├── context-menu.ts │ │ ├── filter.ts │ │ ├── formula-bar.ts │ │ ├── formula.ts │ │ ├── image.ts │ │ ├── number-format.ts │ │ ├── open.ts │ │ ├── ribbon.ts │ │ ├── save.ts │ │ ├── sheet-tabs.ts │ │ ├── sort.ts │ │ └── index.ts │ │ │ ├── renderer/ # Rendering │ │ ├── cell.ts │ │ ├── row.ts │ │ ├── sheet.ts │ │ ├── render.ts │ │ ├── print.ts │ │ └── index.ts │ │ │ ├── services/ # Service layer (singleton per component) │ │ ├── action-events.ts │ │ ├── dialog.ts │ │ ├── overlay.ts │ │ ├── index.ts │ └── index.ts │ ├── workbook/ # Data (Tier 2) │ ├── base/ │ │ ├── workbook.ts │ │ ├── cell.ts │ │ ├── column.ts │ │ ├── data.ts │ │ ├── row.ts │ │ ├── sheet.ts │ │ └── index.ts │ │ │ ├── common/ │ │ ├── address.ts │ │ ├── class.ts │ │ ├── constant.ts │ │ ├── enum.ts │ │ ├── event.ts │ │ ├── interface.ts │ │ ├── internalization.ts │ │ ├── math.ts │ │ ├── module.ts │ │ ├── util.ts │ │ ├── worker.ts │ │ └── index.ts │ │ │ ├── actions/ # Workbook action modules (mirrors spreadsheet/) │ │ ├── auto-fill.ts │ │ ├── cell-format.ts │ │ ├── conditional-formatting.ts │ │ ├── data-validation.ts │ │ ├── delete.ts │ │ ├── edit.ts │ │ ├── find-and-replace.ts │ │ ├── hyperlink.ts │ │ ├── insert.ts │ │ ├── merge.ts │ │ ├── protect-sheet.ts │ │ └── index.ts │ │ │ ├── integrations/ # Workbook integration modules │ │ ├── chart.ts │ │ ├── image.ts │ │ ├── open.ts │ │ ├── save.ts │ │ ├── formula.ts │ │ ├── number-format.ts │ │ ├── filter.ts │ │ ├── sort.ts │ │ ├── image.ts │ │ ├── data-bind.ts │ │ └── index.ts │ │ │ ├── services/ # Workbook services │ │ ├── service-locator.ts │ │ ├── index.ts │ │ │ ├── workers/ # Web Workers (optional) │ │ ├── save-worker.ts │ │ └── index.ts │ │ │ └── index.ts │ └── index.ts # Top-level re-export ``` ## Specs Layout (relative to repo root) This file documents the structure of the repository `spec/` folder. It is a mirror of the test organization present in the codebase and is intended to help contributors quickly find tests for features and subsystems. Project-level layout: ```text spec/ ├── calculate/ │ ├── basicformulas.spec.ts │ ├── calculate.spec.ts | ├── manual-calculate.spec.ts │ ├── common/ │ ├── common.spec.ts │ ├── helper.spec.ts │ └── cldr-data/ │ └── main/ # CLDR data fixtures or helper files │ ├── ribbon/ │ ├── ribbon.spec.ts │ └── spreadsheet/ ├── actions/ │ ├── auto-fill.spec.ts │ ├── cell-format.spec.ts │ ├── clipboard.spec.ts │ ├── collaborative-editing.spec.ts │ ├── comment.spec.ts │ ├── conditional-formatting.spec.ts │ ├── data-validation.spec.ts │ ├── edit.spec.ts │ ├── find-and-replace.spec.ts │ ├── freeze-pane.spec.ts │ ├── hide-show.spec.ts │ ├── hyperlink.spec.ts │ ├── insert.spec.ts │ ├── keyboard-navigation.spec.ts │ ├── keyboard-shortcuts.spec.ts │ ├── merge.spec.ts │ ├── note.spec.ts │ ├── print.spec.ts │ ├── protect-sheet.spec.ts │ ├── resize.spec.ts │ ├── selection.spec.ts │ ├── undo-redo.spec.ts │ ├── wrap.spec.ts │ ├── base/ │ ├── spreadsheet.spec.ts │ ├── integrations/ │ ├── chart.spec.ts │ ├── context-menu.spec.ts │ ├── dynamic-data.spec.ts │ ├── filter.spec.ts │ ├── formula-bar.spec.ts │ ├── formula.spec.ts │ ├── image.spec.ts │ ├── number-format.spec.ts │ ├── open.spec.ts │ ├── ribbon.spec.ts │ ├── sheet-tab.spec.ts │ ├── sort.spec.ts │ ├── util/ │ ├── datasource.spec.ts │ ├── spreadsheethelper.spec.ts │ └── spreadsheet.css # test CSS used by UI tests │ └── workbook/ └── util/ ├── workbookhelper.spec.ts ``` Notes: - Many test files have both TypeScript source (`.spec.ts`) and a compiled JavaScript artifact (`.spec.js`). Use the `.spec.ts` file when reading or editing test logic. - Feature-level tests are arranged under `spec/spreadsheet/actions/` and `spec/spreadsheet/integrations/` to match the feature modules in `src/spreadsheet/`. - The `calculate/` and `spec/spreadsheet/integrations/formula` folder contains formula engine tests for the formula/calc subsystem. Use this layout for quick navigation and to decide where to add new tests.