Cell Merge

Module Extensions

AdditionalData (Extended from @revolist/revogrid)

interface AdditionalData {
  /**
      * Additional data property for cell merge configuration
      * @example
      * grid.additionalData = {
      *   cellMerge: [
      *     {
      *       row: 0,
      *       column: 0,
      *       rowSpan: 2,
      *       colSpan: 2,
      *       rowType: 'rgRow',
      *       colType: 'rgCol',
      *     }
      *   ]
      * }
      */
      cellMerge?: 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 ADDITIONAL_DATA_EVENT, APPLY_RANGE_EVENT, etc., to handle merge configurations and rendering.

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

---

mergeDataChange

This module provides utility functions for managing cell merge operations in RevoGrid. It includes functionality to dynamically track and respond to changes in merge configurations.

Functions:

• mergeDataChange: Wraps an array of MergeData objects with a Proxy to monitor and notify changes such as additions, updates, and deletions. This is useful for plugins that need to react to changes in cell merge setups.

Parameters:

• cellMerge: An array of MergeData objects representing the current state of cell merges.
• notifyChange: A callback function that is triggered on modifications to the cellMerge array, receiving details of the operation, the affected property, its new value, and the target array.

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