@syncfusion/ej2-spreadsheet/docs/skills/action/merge.md

Feature-rich JavaScript Spreadsheet (Excel) control with built-in support for selection, editing, formatting, importing and exporting to Excel

# Merge Module data flow

## What It Does
Merge module handles all cell merge/unmerge operations at the workbook model level and the spreadsheet UI. It computes merged ranges, applies rowSpan/colSpan values, updates cell values/formats, refreshes conditional formats, and coordinates rendering/hide logic for merged cells across frozen panes and hidden rows/columns.

## Entry Points

**WorkbookMerge (Core)**
- `merge(args: MergeArgs)` - Primary core routine that validates ranges, splits horizontal/vertical/all merges, and applies merge logic to model cells. Handles undo/redo via `isAction` and notifies refresh/selection updates.
- `mergeAll(args, startRow?, startCol?)` - Low-level routine that writes span metadata (`rowSpan`/`colSpan`) and clears partial cells inside the merged region.
- `mergedRange`, `activeCellRange`, `insertHandler` - helpers to compute merged extents, adjust ranges when inserts happen, and update persisted mergedCells on import.

**Merge (Spreadsheet / UI)**
- `merge(args)` - UI renderer entry that refreshes DOM cells for merged regions using the cell renderer service.
- `hideHandler`, `checkPrevMerge`, `checkMerge` - UI handlers that control display/hide logic for merged cells when rows/columns are hidden, when rendering viewport rows, and when neighboring merges affect visible cells.

## Core Logic Flow

1. Callers request merge via `setMerge` / `setMerge`-equivalent notification, providing `MergeArgs` (range, type, isAction, model backup when undoable).
2. `WorkbookMerge.merge` normalizes the range (`getRangeIndexes`, `getSwapRange`) and optionally calls `mergedRange` to expand the range considering existing spans.
3. Based on `args.type` it dispatches to `mergeAll` for all/vertical/horizontal variants. `mergeAll`:
   - Iterates target cells; records existing cell content/format into `args.model` when `isAction` for undo.
   - Removes `rowSpan`/`colSpan` from cells inside the merge and sets negative spans on covered cells to mark them as merged placeholders.
   - For the top-left cell of the merge, sets positive `rowSpan`/`colSpan` on the update object to reflect merged dimensions and writes the leading cell value/format.
   - Calls `updateCell(...)` for cell writes and sets `usedRange` appropriately.
4. After mutation, core refreshes conditional formats (`refreshCF`) and notifies `applyMerge` when appropriate.
5. If `insertMerge` notifications come from insert operations, `insertHandler` adapts existing merges to new indices and re-applies merge layout.
6. `WorkbookMerge` emits `actionBegin`/`actionComplete` notifications for actionable merges and triggers `selectRange` and `refreshChart` for the active sheet when necessary.

## UI Logic Flow

1. UI listens to `applyMerge` and `hiddenMerge` events to update DOM.
2. `Merge.merge` uses the cell renderer service to refresh the merged cell DOM (colSpan/rowSpan), and ensures correct content and display settings across frozen panes.
3. When rows/columns are hidden or visibility changes, `hideHandler` determines whether merged cells should be shown/hidden or re-rendered with adjusted spans, using `skipHiddenIdx` to map visible indices.
4. During content rendering, `checkPrevMerge` and `checkMerge` inspect adjacent/past merges to avoid duplicate spans in the viewport, clearing or restoring display attributes as needed.

## Operations Handled

- Merge (All / Horizontally / Vertically)
  - Compute merged range, record undo model, set positive spans on anchor cell and negative placeholders on covered cells.
  - Preserve leading cell value/format; clear other cell content or store it in undo model.

- Unmerge
  - Remove span metadata and restore per-cell values/formats from `args.model` when provided.

- Hidden rows/columns
  - Adjust visible `rowSpan`/`colSpan` based on hidden counts, and avoid rendering merged placeholders in collapsed areas.

- Insert adjustments
  - `insertHandler` adapts merge ranges and reapplies merges when rows/columns are inserted inside merged regions.

- Import/update
  - `updateMergedCellsFromSheet` normalizes mergedCells metadata after import to fit current sheet dimensions and converts stored mergedCells into runtime span metadata.

## Validation & Safety

- Range normalization: accepts string or index input and uses `getRangeIndexes` / `getSwapRange`.
- Skip-checks: `skipChecking` short-circuits expensive range recalculation when callers already know the extent.
- Protection: merges respect workbook action lifecycle (`actionBegin` / `actionComplete`) and use `isAction` to record undo payloads.
- Boundary checks: `updateMergedCellsFromSheet` enforces sheet row/column limits (max rows/cols) and trims spans that would exceed sheet dimensions.

## Desired Outputs (Post-Merge)

- Model: `rowSpan` / `colSpan` set on anchor cell; negative spans on covered cells; optional `mergedCells` list updated on sheet model.
- UI: Table cells updated with `rowSpan`/`colSpan` attributes; merged placeholders hidden; correct display across frozen panes and when rows/cols are hidden.
- Notifications: `applyMerge`, `refreshChart`, `selectRange`, `actionBegin`/`actionComplete` for undo support.

## System-Level

- Important types & events:
  - `MergeArgs`, `CellModel`, `SheetModel`, `MergedCellModel`, `applyMerge`, `setMerge`, `mergedRange`, `activeCellMergedRange`, `insertMerge`, `importModelUpdate`, `refreshChart`, `selectRange`.

- Modules:
  - Core: `src/workbook/actions/merge.ts` (`WorkbookMerge`)
  - UI: `src/spreadsheet/actions/merge.ts` (`Merge`)

## Test / Verification Actions

- Merge a rectangular range and verify anchor cell carries value/format and covered cells are placeholders (hidden or negative spans).
- Merge horizontally and vertically edge cases (single-row, single-column) and verify resulting spans are correct.
- Unmerge with `isAction` and verify undo model restores original cell contents.
- Hide rows/columns inside a merge and verify UI shows/hides merged cells correctly and recalculates visible spans.
- Insert rows/columns inside a merged range and verify `insertMerge` handler adjusts merge ranges and visual spans.

---