# Workbook Data Flow (Base)

## What It Does
- Summary: Core data model and operations for the entire workbook: sheet collection management, persistence, high-level APIs (create/remove/move/duplicate sheets), undo/redo scaffolding, and coordination points used by the Spreadsheet UI. See `src/workbook/base/workbook.ts`.

## Entry Points (UI / Core)
- UI (Consumers / Extensions):
  - `Workbook` properties accessed by UI layers: `sheets[]`, `activeSheetIndex`, `height`, `width`, `showSheetTabs`, `allowEditing`, `allowPrint`, etc.
  - Event hooks exposed to host applications: `beforeOpen`, `openFailure`, `beforeSave`, `saveComplete`, `beforeCellUpdate`, `queryCellInfo`, `actionBegin`, `actionComplete`.
- Core (Model / Utilities):
  - `createSheet(index, sheets)` / `removeSheet(idx)` / `moveSheet` / `duplicateSheet` — high-level sheet operations that mutate `sheets[]` and emit action events.
  - `getData(address)` / `getCell(row, col)` / `setUsedRange(rowIdx, colIdx)` — data access and range maintenance used by render and API methods.
  - Undo/Redo integration: `undo()`, `redo()`, `updateUndoRedoCollection()` called by mutating operations.
  - Persistence and file IO: `save()`, `open()`, `openFromJson()`, `saveAsJson()` (entry points for serialization and import/export).

## Core Logic Flow (ASCII)
API call (create/move/duplicate sheet / update cell / save / open)
         ↓
Workbook mutates model (`sheets[]`, `activeSheetIndex`, sheet properties)
         ↓
Emit action events (`actionBegin`) → perform mutation → emit `actionComplete`
         ↓
If mutation affects view: notify renderer/services (via `serviceLocator` and `notify`) to refresh viewport or re-render
         ↓
If persistence requested: call serialization/export routines and trigger file IO events

## Operations Handled (functions & implementation notes)
- Sheet lifecycle:
  - `createSheet`: inserts one or more sheet models at given index; ensures `id` and `name` defaults; triggers module registration and formula recalculation hooks.
  - `removeSheet`: removes sheet at index and updates active index and UI via notifications.
  - `moveSheet` / `duplicateSheet`: reorder or duplicate sheet models; update internal references (charts/images ids) and call `workbookFormulaOperation` when structure changes.
- Data & ranges:
  - `getData(address)`: proxy to `src/workbook/base/data.ts` `getData` to fetch cells for addresses (used by `Render.refreshUI`).
  - `setUsedRange(rowIdx, colIdx)`: updates `sheet.usedRange` and optionally notifies UI to resize view.
- Undo/Redo & actions:
  - Mutating operations wrap changes with `actionBegin` and `actionComplete`; they should push undo records via `updateUndoRedoCollection`.
  - `undo()` / `redo()` call into the undo manager (not shown here) to revert/apply recorded operations.
- Utilities & helpers:
  - `getAddressInfo`, `getCell`, `getValueRowCol`, `setValueRowCol` provide small, frequently used helpers for other modules.

## Validation & Safety
- Action events: call sites get `actionBegin` handlers, allowing cancellation before destructive changes.
- Index normalization: `processIdx` and `getModel` (used across base modules) ensure gaps in sparse models do not cause undefined access.
- Sheet visibility checks: operations that change active sheet use `skipHiddenSheets` to land on a visible sheet.
- Protected sheets: mutating functions check sheet `isProtected` and `protectSettings` before applying changes when enforcement is required.

## Desired Outputs
- User-Facing:
  - Stable workbook operations: create/move/duplicate sheets, save/open, and consistent active-sheet behavior.
  - Predictable undo/redo experience for user-initiated changes.
- System-Level:
  - Model: `Workbook` instance with `sheets[]` each a `SheetModel` containing `rows`, `columns`, `usedRange`, `ranges`.
  - Events: `actionBegin`/`actionComplete` surrounding model mutations, plus file-level events (`beforeOpen`, `saveComplete`).
  - Integration: `serviceLocator` used by other modules (render, formula, print, etc.) to access workbook services and reflect model changes into UI.