# Conditional Formatting Module data flow

## What It Does
Conditional Formatting (CF) allows rules to be attached to ranges that compute style/results dynamically. The workbook side manages CF models and range updates; the spreadsheet side evaluates rules and applies visual results to cells.

## Entry Points
- Workbook layer:
  - `setCFRule(e: CFArgs)` — add a CF model to a sheet and trigger apply.
  - `clearCFRule(args: CFArgs)` — remove or carve CF ranges when clearing areas or undoing.
- Spreadsheet/UI layer:
  - `applyCF` — request to compute and apply CF results to visible cells.
  - `clearCF` — remove applied CF styles from viewport.

## Core Logic Flow

```
User adds/clears CF → Workbook.setCFRule / clearCFRule
    ↓
Workbook updates sheet.conditionalFormats[] (append / modify / remove ranges)
    ↓
If active sheet: notify applyCF → Spreadsheet evaluates rules cell-by-cell → renderer updates DOM
    ↓
ActionComplete / undo stack entries
```

## Operations Handled
- Add CF: normalize range, emit cancellable `beginAction`, push CF model onto `sheet.conditionalFormats`, call `applyCF` for active sheet.
- Clear CF: for each CF entry, split comma-separated ranges, test overlap with clear area, carve new ranges (top/bottom/left/right splits), remove empty CF entries, and collect `oldCFModel` / `updatedCFModel` for action logging.
- CF application: evaluate each CF rule over its range, compute `result` for cells, and update `sheet` result cache and DOM via renderer.

## Data Transformations
- Range parsing: split multi-range strings, `getRangeIndexes` → `getSwapRange` → `getRangeAddress`.
- CF model mutation: when splitting ranges, transform one CF entry into zero-to-many new range strings and update model properties.

## Validation & Safety
- Undo/Redo: clear/add operations respect `isUndo`, `isUndoRedo`, and preserve `oldCFModel` to revert or reapply rules.
- Action completion gating: `actionComplete` may be suppressed for special CF actions (e.g., `autofillWithCF`) per-last-action checks.

## Side Effects & Notifications
- Workbook notifies `applyCF` or `goto` (sheet navigation) depending on active sheet and undo/redo flows.
- Spreadsheet responds to `applyCF` by evaluating rules and updating visible cells; `clearCF` removes applied styles from viewport.
- `actionComplete` includes `oldRange` and `previousConditionalFormats` for telemetry and undo stacks.

## Edge Cases
- Multi-range CF entries: comma-separated ranges are independently tested and surgically modified when overlaps occur.
- Partial overlaps: CF ranges are carved into up to four remainders (top/bottom/left/right) as needed.
- Cross-sheet operations: clearing or undoing CF on a non-active sheet may trigger `goto` to apply changes when appropriate.

## Simplified Sequence (clear CF)
1. Receive `clearCFRule` with target range and sheet index.
2. For each CF entry on that sheet, split ranges and compute overlap with clear area.
3. If fully covered: remove CF entry; if partially covered: compute remainder ranges and update CF entry.
4. Notify `clearCF` to remove applied visuals; call `applyCF` for updated CF entries if needed.
5. Emit `actionComplete` with `oldCFModel` and `updatedCFModel`.

## Desired Outputs
- User-facing: CF rules reflect the user's add/clear actions, visible cells update accordingly, and undo/redo restores previous rule sets.
- System-level: `sheet.conditionalFormats` accurately represent active rules; evaluation results cached for renderer performance.