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 additionalData 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.additionalData = {
  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 additionalData.cellMerge: Reads legacy merge configuration from additionalData.cellMerge.

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

---

dataChange

Creates a proxy for the cell merge data to track changes

export function dataChange(
  cellMerge: MergeData[],
  notifyChange: (
    operation: 'add' | 'update' | 'delete',
    property: string | symbol,
    value: any,
    target: MergeData[]
  ) => void
);

---

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