# Cell Merge
URL: https://pro.rv-grid.com/api/cell-merge/
Source: src/content/docs/api/cell-merge.md
## Module Extensions

### `AdditionalData` (Extended from `@revolist/revogrid`)

```ts
interface AdditionalData {
  /**
      * Additional data property for cell merge configuration.
      *
      * @deprecated Use `grid.cellMerge` instead.
      * @example
      * grid.additionalData = {
      *   cellMerge: [
      *     {
      *       row: 0,
      *       column: 0,
      *       rowSpan: 2,
      *       colSpan: 2,
      *       rowType: 'rgRow',
      *       colType: 'rgCol',
      *     }
      *   ]
      * }
      */
      cellMerge?: MergeData[]
}
```

---

### `HTMLRevoGridElement` (Extended from `global`)

```ts
interface HTMLRevoGridElement {
  cellMerge?: MergeData[];
  'cell-merge'?: MergeData[]
}
```

## Plugin API

### `CellMergePlugin`

The `CellMergePlugin` is a RevoGrid plugin designed to manage and render merged cells within a grid.
It allows users to visually and functionally combine multiple adjacent cells into a single larger cell,
offering a more cohesive data presentation within the grid interface.

**Key Features**:
- Merging Logic: Extends the size of specified cells and hides cells covered by the merged area.
- Event Management: Overrides grid events and focus behavior to accommodate hidden cells due to merging.
- Dynamic Updates: Listens for data changes and adjusts merged configurations accordingly.
- UI Rendering: Adjusts cell sizes and parameters for merged cells during rendering.

**Usage**:
- This plugin should be included in the grid's plugin array to enable cell merging functionality.
- Configure the merge data through the grid's `cellMerge` property to define which cells should be merged.

### Example
```typescript
import { CellMergePlugin } from './cell-merge-plugin';

const grid = document.createElement('revo-grid');
grid.plugins = [CellMergePlugin]; // Add merge plugin
grid.cellMerge = [
  { row: 1, column: 1, rowSpan: 2, colSpan: 2 },
];
```

Events:
- Listens to a variety of events like `APPLY_RANGE_EVENT`, `FOCUS_APPLY_EVENT`, etc., to handle merge configurations and rendering.

#### Dependencies

- **Event integration** `APPLY_RANGE_EVENT`, `FOCUS_APPLY_EVENT`, `EDIT_RENDER_EVENT`: Integrates with range, focus, and edit overlay events to preserve merged-cell behavior.
- **Config integration** `grid.cellMerge`: Reads merge configuration from the grid cellMerge DOM property.

```ts
class CellMergePlugin {
  destroy(): void;
}
```

---

### `MergeData`

Represents a range of cells that should be merged.
The coordinates are relative to the top-left cell of the range.

```ts
/**
 * Represents a range of cells that should be merged.
 * The coordinates are relative to the top-left cell of the range.
 */
export type MergeData = {
  /**
   * The row index of the top-left cell of the range.
   */
  row: number;

  /**
   * The column index of the top-left cell of the range.
   */
  column: number;

  /**
   * The number of rows to span. If not specified, the range will span only one row.
   */
  rowSpan?: number;

  /**
   * The type of the row dimension. If not specified, it will default to 'rgRow'.
   */
  rowType?: DimensionRows;

  /**
   * The number of columns to span. If not specified, the range will span only one column.
   */
  colSpan?: number;

  /**
   * The type of the column dimension. If not specified, it will default to 'rgCol'.
   */
  colType?: DimensionCols;
};
```

---

### `MergeRowCache`

```ts
export type MergeRowCache = Partial<Record<MultiDimensionType, CellCache>>;
```

---

### `MergeCache`

```ts
export type MergeCache = Partial<Record<MultiDimensionType, { [key: number]: MergeRowCache }>>;
```

---

### `getCellMergeExcelRanges`

```ts
export function getCellMergeExcelRanges(
  context: CellMergeExcelExportContext =;
```

---

### `getCellMergeExcelProviderOptions`

```ts
export function getCellMergeExcelProviderOptions(
  context: CellMergeExcelExportContext =;
```

---

### `applyCellMergeWriteExcelFileSpans`

```ts
export function applyCellMergeWriteExcelFileSpans<TCell extends CellMergeWriteExcelFileCell>(;
```

---

### `CellMergeExcelSegment`

```ts
export type CellMergeExcelSegment = {
  /**
   * Segment start in the export matrix before the generated header offset is
   * applied. Omit when segment lengths are supplied in grid order.
   */
  start?: number;
  /** Number of rows or columns in the segment. */
  length?: number;
};
```

---

### `CellMergeExcelSegments`

```ts
export type CellMergeExcelSegments<T extends string> = Partial<Record<T, number | CellMergeExcelSegment>>;
```

---

### `CellMergeExcelExportContext`

```ts
export type CellMergeExcelExportContext = {
  /** Explicit merge data. Wins over merge data read from `revogrid`. */
  cellMerge?: MergeData[];
  /** Optional grid element source for `cellMerge` or legacy `cell-merge`. */
  revogrid?: Pick<HTMLRevoGridElement, 'cellMerge'> & Partial<Record<'cell-merge', MergeData[]>>;
  /**
   * Generated header rows before data rows. ExportExcel currently generates one
   * header row, so this defaults to 1.
   */
  headerRows?: number;
  /**
   * Row segment lengths or starts in export data-row order. Starts are counted
   * after generated header rows; the helper adds `headerRows`.
   */
  rowSegments?: CellMergeExcelSegments<DimensionRows>;
  /**
   * Column segment lengths or starts in export column order.
   */
  columnSegments?: CellMergeExcelSegments<DimensionCols>;
};
```

---

### `CellMergeExcelRange`

```ts
export type CellMergeExcelRange = {
  /** Zero-based start row in the provider matrix, including generated headers. */
  startRow: number;
  /** Zero-based start column in the provider matrix. */
  startColumn: number;
  /** Zero-based end row in the provider matrix, including generated headers. */
  endRow: number;
  /** Zero-based end column in the provider matrix. */
  endColumn: number;
  rowSpan: number;
  columnSpan: number;
  rowType: DimensionRows;
  colType: DimensionCols;
  source: MergeData;
};
```

---

### `CellMergeExcelProviderOptions`

```ts
export type CellMergeExcelProviderOptions = {
  /** Generic provider merge ranges in zero-based export matrix coordinates. */
  mergeRanges: CellMergeExcelRange[];
};
```

---

### `CellMergeWriteExcelFileCell`

```ts
export type CellMergeWriteExcelFileCell = Record<string, unknown> | null | undefined;
```

---

### `ApplyCellMergeWriteExcelFileSpansOptions` (Extended from `index.ts`)

```ts
export type ApplyCellMergeWriteExcelFileSpansOptions<TCell extends CellMergeWriteExcelFileCell> =
  CellMergeExcelExportContext & {
    cellRows: TCell[][];
    /** Mutate the supplied `cellRows` matrix instead of returning a patched copy. */
    inPlace?: boolean;
  };
```

---

### `MergeCacheService`

Service responsible for managing the cell merge cache.
This service handles all operations related to storing, retrieving, and manipulating
the cache of merged cells, separating these concerns from the main plugin logic.

```ts
class MergeCacheService {
  /**
     * Clears the entire merge cache
     */
  public clearCache(): void;

  /**
     * Gets the current merge cache
     */
  public getCache(): MergeCache;

  /**
     * Check cache for merged cells and return spans
     */
  public getSpans(types: AllDimensionType, startX: number, startY: number);

  /**
     * High level mapping start
     */
  public setMerge(data: MergeData[] | undefined);
}
```
