# Data Validation Module data flow

## What It Does
Data Validation enforces input constraints at model level and provides UI affordances (in-cell dropdowns, validation dialog, and highlights). Workbook code manages validation models and range-level updates; spreadsheet code evaluates rules on edits and manages UI (dropdowns, error dialogs, highlights).

## Entry Points
- Workbook layer:
  - `cellValidation` — add/remove validation rules for a range (model mutation).
  - `addHighlight` / `removeHighlight` — request highlight invalid data across ranges.
  - `beforeInsert` / `beforeDelete` / `refreshInsertDelete` — update validation models when structure changes.
  - `importModelUpdate` — re-evaluate imported validations.
- Spreadsheet / UI layer:
  - `initiateDataValidation` — open validation dialog to create/update rules.
  - `isValidation` / `checkValidationHandler` — evaluate cell validity on edits.
  - `addListValidationDropdown` / `listValueChange` — create and handle in-cell dropdowns for `List` validation.

## Core Logic Flow

```
User edits or opens validation dialog → Spreadsheet UI checks or creates rule
    ↓
cellValidation (workbook) updates `cell.validation` or `column.validation` across ranges
    ↓
If list-type: workbook notifies addListValidationDropdown → spreadsheet creates dropdown
    ↓
On edit: spreadsheet.validate value via checkValidationHandler → if invalid, notify addHighlight
    ↓
Workbook invalidDataHandler updates model `validation.highlight` and notifies UI to paint highlights
```

## Operations Handled
- Add/Remove validation: map ranges to index bounds, support full-column rules, store `ValidationModel` on cells or columns.
- Highlighting: mark `validation.highlight` in model and notify UI to show invalid-data markers or remove them.
- List dropdowns: resolve data source (`=range` or named ranges), construct `DropDownList`, and commit selection via `listValueChange`.
- Structural updates: on insert/delete, shift or remove validation rules and update any formula references contained in `value1`/`value2`.

## Data Transformations
- Range normalization: `getRangeWhenColumnSelected`, `getRangeIndexes`, `getSwapRange`.
- Validation values: detect formulas (`checkIsFormula`) and store raw formulas; parse values for numeric/date checks respecting locale.
- List sources: `getListDataSource` converts `=A1:A10` or named ranges into choice arrays.

## Validation & Safety
- Read-only/protected checks: skip committing dropdown selections or edits when the cell is protected/locked.
- Separate flows: removing a validation rule vs removing highlights are distinct and handled by different flags.
- Import/update: `updataSheetValidation()` migrates and re-evaluates validations after import, preserving formulas and adjusting sheet references when necessary.

## Side Effects & Notifications
- Workbook notifies `addListValidationDropdown` to prompt spreadsheet UI to open dropdowns.
- UI triggers `addHighlight` / `removeHighlight`; workbook responds with `invalidDataHandler` to compute highlights across affected ranges.
- Validation checking can result in dialogs (error) and prevent value commits when `showErrorDialog` is configured.

## Edge Cases
- Full-column validation: ranges without row numbers apply to entire column and require virtualization-aware iteration.
- Formula-based validation: values referencing ranges or named ranges need updates when sheets/rows/cols change.
- Virtualized viewport / missing TD: UI dropdown positioning and height use viewport offsets; if TD absent, model commits still occur.

## Simplified Sequence (add validation)
1. User configures validation via dialog → spreadsheet issues `cellValidation` with `range` and `rules`.
2. Workbook resolves sheet/range and iterates target cells/columns to set `validation` model.
3. If `List` type: workbook notifies `addListValidationDropdown` and spreadsheet creates the in-cell dropdown.
4. On edit, spreadsheet runs `checkValidationHandler`; invalid cells trigger `addHighlight`.
5. Workbook `invalidDataHandler` applies model flags and notifies UI to paint/unpaint highlights.

## Desired Outputs
- User-facing: validation dialog UX, in-cell list dropdowns, invalid-data highlights, and error dialogs.
- System-level: `cell.validation` or `column.validation` stored per model, correct handling across structural edits and imports.