Cell Merge

Module Extensions

AdditionalData (Extended from @revolist/revogrid)

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)

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

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.

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.

/**
 * 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

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

---

MergeCache

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

---

getCellMergeExcelRanges

export function getCellMergeExcelRanges(
  context: CellMergeExcelExportContext =;

---

getCellMergeExcelProviderOptions

export function getCellMergeExcelProviderOptions(
  context: CellMergeExcelExportContext =;

---

applyCellMergeWriteExcelFileSpans

export function applyCellMergeWriteExcelFileSpans<TCell extends CellMergeWriteExcelFileCell>(;

---

CellMergeExcelSegment

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

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

---

CellMergeExcelExportContext

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

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

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

---

CellMergeWriteExcelFileCell

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

---

ApplyCellMergeWriteExcelFileSpansOptions (Extended from index.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.

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);
}