# Cell Format Module data flow

## What It Does
Cell Format manages persistent model-level styling (workbook) and immediate DOM rendering/row-height adjustments (spreadsheet). This combined dataflow explains how formatting requests traverse from UI entry points to model updates, border adjacency logic, merge handling, and renderer coordination.

## Entry Points
- UI / Spreadsheet layer:
  - `applyCellFormat(args: CellFormatArgs)` — in-place DOM style application and height checks.
  - `textDecorationActionUpdate(args)` — toggle text decoration and trigger model update.
  - `clearViewer` — clear visible formats in the viewer.
- Core / Workbook layer:
  - `setCellFormat(args: SetCellFormatArgs)` — model-level apply/clear of styles, undo/redo aware.
  - `clear` — clear model objects (formats/contents/hyperlinks) across ranges.

## Core Logic Flow

```
User action (ribbon/toolbar/shortcut) or programmatic call
    ↓
Spreadsheet.applyCellFormat()  (fast-path DOM)  ←─  Workbook.setCellFormat() (model change)
    ↓                                          ↘
update DOM styles, row height recalculation         validate ranges → beforeCellFormat → iterate cells
    ↓                                               ↓
update merged-border bookkeeping ←── setCellStyle/updateCell on model per-cell
    ↓                                               ↓
update renderer (refreshRange) and emit actionComplete → applyCF / activeCellChanged
```

## Operations Handled
- Inline style application: merge incoming `style` with per-cell current style and apply to TD (spreadsheet) or model (workbook).
- Border decomposition: convert `border` to side props (`borderTop/Bottom/Left/Right`), resolve adjacent-cell conflicts, and enforce border priority rules.
- Merge-aware updates: ensure styles on merged regions are applied to anchor cells and merge bookkeeping (`mergeBorderRows`) is updated.
- Row-height handling: recalc row height for wrapped text or thick borders and update DOM/model accordingly.
- Clear operations: remove formats/contents/hyperlinks and refresh renderer ranges.

## Data Transformations
- Range parsing: `getRangeIndexes` ↔ `getRangeAddress` and `getSwapRange` for normalized index order.
- Style normalization: clone event-level `style` into eventArgs, then tailor per cell (remove or override side props when adjacent cells require different borders).
- Border handling: unified `border` → side properties; neighbors get cleared or adjusted via adjacency helpers.

## Validation & Safety
- Read-only checks: skip cells/rows/columns flagged as read-only or locked; abort action for fully read-only ranges.
- Cancelable hook: `beforeCellFormat` allows consumers to cancel or change the requested style/range before model mutation.
- Undo/Redo: commit operations emit `actionBegin`/`actionComplete` and respect `isUndoRedo` flags.

## Side Effects & Notifications
- Events emitted: `beforeCellFormat`, `actionBegin`, `actionComplete`, `activeCellChanged`.
- Notifications to subsystems: `applyCF` (conditional formats), renderer `refreshRange`, `clear` for clearing flows.
- Model writes: `setCellStyle()` updates `sheet.rows[].cells[].style`; `setUsedRange()` updates used ranges.

## Edge Cases
- Merged cells: apply to anchor cell, update merge-border bookkeeping to avoid double borders.
- Hidden rows/columns: skip or adjust computations when applying heights or borders.
- Virtualization: DOM path may not find a TD — fallback to model-only height/style updates.

## Simplified Sequence (apply formatting)
1. Receive `applyCellFormat` or `setCellFormat` with `style` and `range`.
2. Validate read-only status; return if prohibited.
3. Fire `beforeCellFormat` (cancelable). If changed range/style, normalize accordingly.
4. For every target cell index:
   - Compose final style (split borders if needed).
   - Update model via `setCellStyle()` (workbook path) or set `td.style` (spreadsheet path).
   - Update merge/border bookkeeping and `usedRange`.
5. If necessary, recalc row heights and call `refreshRange` for renderer.
6. Emit `actionComplete` and notify conditional formatting (`applyCF`) if present.

## Desired Outputs
- User-facing: immediate visual style changes with correct border rendering, right row heights, and consistent merged-cell appearance.
- System-level: consistent `sheet.rows[].cells[].style` model, undo/redo entries, and conditional-format refresh.