# Spreadsheet Data Flow (App Layer)

## What It Does
- Summary: `Spreadsheet` is the application-facing component that extends `Workbook` with UI orchestration, modules registration, user-facing properties/events, viewport and rendering coordination, and higher-level APIs (selection, editing, printing, formula bar). See `src/spreadsheet/base/spreadsheet.ts`.

## Entry Points (UI / Core)
- UI (Public API & Events):
  - Public properties: `allowScrolling`, `allowResizing`, `selectionSettings`, `scrollSettings`, `showCommentsPane`, `allowUndoRedo`, `enableClipboard`, etc.
  - Events for host apps: `beforeCellRender`, `beforeSelect`, `select`, `dataBound`, `beforeDataBound`, `actionBegin`, `actionComplete`, many more (cell edit lifecycle, file menu, context menu).
  - High-level methods: `renderModule.render()`, `refresh()`, `refreshSheet()`, `getData()`, `print()`, `setRowHeight()`, `setColWidth()`, `updateCell()`, `undo()`, `redo()`.
- Core (Orchestration / Modules):
  - Modules instantiated and used by `Spreadsheet`: `renderModule` (`Render`), `scrollModule` (`Scroll`), `printModule` (`Print`), `workbookFormulaModule`, `autofillModule`, `selectionModule`, `sheetModule` (`SheetRender`), plus `serviceLocator`.
  - `viewport` state: `rowCount`, `colCount`, `height`, `width`, `topIndex`, `leftIndex`, `bottomIndex`, `rightIndex`, `scaleX/Y`, `beforeFreezeWidth/Height`.

## Core Logic Flow (ASCII)
Component `appendTo()` / initial render
         ↓
`Spreadsheet.render()` bootstraps modules, creates sheet panel, calls `renderModule.render()`
         ↓
`renderModule.checkTopLeftCell()` computes top-left + frozen offsets then `refreshUI()` requests `getData()`
         ↓
`getData()` resolves cell map → `sheetModule.renderTable()` or incremental updates → DOM updated
         ↓
User interactions (scroll/resize/edit/rowHeight/colWidth/print)
         ↓
Emit events (`beforeCellUpdate`, `cellEdit`, `actionBegin`) → delegate to specific modules (selection, edit, print) → update model and call targeted renderer refresh (row/column/All)

## Operations Handled (functions & implementation notes)
- Render coordination:
  - `renderModule` computes viewport, thresholds for virtualization, resolves start/end indexes, and routes fetch results to `sheetModule`.
  - `checkTopLeftCell` aligns `topLeftCell` and `paneTopLeftCell` for frozen panes; computes `viewport.beforeFreeze*` pixel offsets.
- Editing and cell lifecycle:
  - `startEdit` / `endEdit` / `updateCell` / `updateCellInfo` manage editing state and notify formula or dependent recalculation when needed.
  - `queryCellInfo` and `beforeCellUpdate` events allow external code to inspect/modify cell behavior.
- Layout and resizing:
  - `setSheetPanelSize` measures container and sets `viewport.scaleX/Y` and counts used by renderer.
  - `setColWidth`, `setRowHeight`, `setRowsHeight`, `setColumnsWidth`, `autoFit` mutate model and call targeted renders (`rowHeightChanged`, `colWidthChanged`) to minimize redraw.
- Selection, clipboard, and context:
  - `selectionModule` and clipboard APIs coordinate user selection state and copy/paste operations; `enableContextMenu` exposes context menu hooks.
- Printing and export:
  - `print()` delegates to `printModule` to rasterize pages; `isPrintingProcessing` guards UI while printing.

## Validation & Safety
- Event gating: `beforeCellUpdate` and `actionBegin` offer cancellation points to prevent unintended changes.
- Virtualization safety: `skipHidden`, `skipHiddenIdx`, and `decreaseHidden` helpers ensure hidden rows/cols don't corrupt viewport calculations.
- Model/DOM synchronization: many operations compute and set `viewport` indices and pixel offsets before issuing render updates to avoid layout jumps.
- Protected sheets and read-only mode: checks on `isProtected`, `isReadOnly` (row/cell) prevent edits where disallowed.

## Desired Outputs
- User-Facing:
  - Responsive spreadsheet UI: virtualization-backed scrolling, frozen panes, editable cells, selection, and accessible headers.
  - Rich features: formula bar, ribbon, comments pane, contextual menus, print preview, image/chart insertion.
- System-Level:
  - `Spreadsheet` object hosts modules via `serviceLocator` and exposes `viewport` and module references for coordination.
  - Events: rich set of lifecycle and operation events for host integration and plugin modules.
  - Model-level guarantees: `sheets[]` normalized via `initSheet`/`processIdx`, `usedRange` maintained by `setUsedRange`, and merge/span placeholders handled during data reads.