Cell Merging Specification

Cell Merging Specification

Contents

1. Overview
2. User Stories
3. Functionality
4. Test Scenarios
5. Accessibility
6. Assumptions and Limitations
7. References

Owned by

Team Name: Grinders

Developer Name: Maya K.

Designer Name: Yordanka Petkova-Radoeva

Requires approval from

• Stamen Stoychev | Date: 21.07.2025
• Svilen Dimchevski | Date: 28.07.2025

Signed off by

• Product Owner Name | Date:
• Platform Architect Name | Date:

Revision History

Version	Users	Date	Notes
1	Maya K.	04/07/2025	Initial draft.

1. Overview

Cell merging is a feature that combines two or more cells into a single, larger cell. Cell can be merged vertically, based on same data in adjacent cells in the same column.

Objectives

The feature includes the following:

• Ability to configure and merge cells in a column based on same data or other custom condition, into a single cell.

2. User Stories

Developer stories:

• Story 1: As a developer, I want to be able to enable/disable cell merging for all columns or for particular columns (when sorted or unsorted) so that data is visually merged.

• Story 2: As a developer, I want to be able to apply a custom condition bases on which to merge the cells.

• Story 3: As a developer, I want to configure how the text in the merged cell is displayed.

End-user stories:

• Story 1: As an end-user, I want to see repeating data as a single physical cell that spans multiple records.

• Story 2: As an end-user, I want to be able to interact with the cell in a meaningful way (select, update, navigate through etc.).

3. Functionality

Cells that have same data will be merged in a single cell that spans down. Design specification here.

3.1. End-User Experience

Integration scenarios:

• Virtualization

  Merged cells should not be lost on scroll when their original row goes outside the virtualization frame. The scrolling should feel natural, as if there's no virtualization.

• Expand/Collapse

  If a feature (like master-detail, grouping etc.) generates a non-data row, then the cell merging is interrupted and group will be split in two.

• Paging

  Only data on the current page will be merged.

• Excel export

  Merged cells should remain merged when exported in excel.

• Column pinning

  Cells should also merge when column is pinned and displayed in the pinned area.

• Row pinning

  Rows will merge only within their containing area - pinned rows will merge only with other pinned that have same value and unpinned with other unpinned respectively. Ghost rows should merge with other ghost rows in the main area if adjаcent and with same value. They will NOT merge with other row types even if they have the same value.

• Navigation/Activation

  When cell is activated, all merged cells in the row will become single cells (will break the merge sequence). This includes when activation is moved with navigation. If a merged cell is clicked, the closest cell from the merge sequence will become active.

• Updating

  Since activation breaks the merge sequence, only a single cell will be in edit mode.

• Row Selection

  If selected rows intersects merged cells, all related merged cells should be marked as part of the selection.

3.2. Developer Experience

The merge mode for the grid can be set via a cellMergeMode property with enum values:

export const GridCellMergeMode = {
    always: 'always',
    onSort: 'onSort'
} as const;

Always will merge any cells that match the merging condition and are adjacent. OnSort will merge cells only if the column is sorted.

Merging can be enabled/disabled via a boolean merge property on the column.

    <igx-column merge="true">
    </igx-column>

A custom condition by which to merge cells can be set via a mergeStrategy on the grid with the following signature:

export interface IGridMergeStrategy {
    merge: (
        data: any[],
        field: string,
        comparer: (prevRecord: any, currentRecord: any, field: string) => boolean,
        result: any[],
        activeRowIndex? : number,
        grid?: GridType
    ) => any[];
    comparer: (prevRecord: any, record: any, field: string) => boolean;
}

It can extend the DefaultMergeStrategy if you want to override only part of the implementation. For example, only the comparer function:

export class MyCustomStrategy extends DefaultMergeStrategy {
    public override comparer(prevRecord: any, record: any, field: string): boolean {
      //your implementation here
    }

3.3. Keyboard Navigation

As activation breaks up the merge sequence, navigation will work like in the base grid.

3.4. API

Options

• Grid:

  Name	Description	Type	Default value	Valid values
  cellMergeMode	Determines the mode for when to merging cells.	GridCellMergeMode	onSort	always, onSort
  mergeStrategy	Allows setting a custom merge strategy to customize the conditions by which to merge cells.	IGridMergeStrategy	DefaultMergeStrategy	new MyMergeStrategy() that extends base DefaultMergeStrategy.

• Column:

  Name	Description	Type	Default value	Valid values
  merge	Whether or not to merge cells for this column.	boolean	false	true/false
  mergingComparer	Sets a custom function to compare values for merging.	(prevRecord: any, record: any, field: string) => boolean	undefined	function

4. Test Scenarios

Automation

Basic

• Configuration

  • should show allow enabling/disabling merging per column.
  • should always merge columns if mergeMode is always.
  • should merge only sorted columns if mergeMode is onSort.
  • should allow setting a custom merge strategy via mergeStrategy on grid.
  • should allow setting a custom comparer for merging on particular column via mergingComparer.

• UI

  • should properly align merged cells with their spanned rows.
  • should mark merged cell as hovered when hovering any row that intersects that cell.
  • should set correct size to merged cell that spans multiple rows that have different sizes.

Integration

• Virtualization

  • should retain rows with merged cells that span multiple rows in DOM as long as merged cell is still in view.
  • should remove row from DOM when merged cell is no longer in view.
  • horizontal virtualization should not be affected by vertically merged cells.

• Group By

  • cells should merge only within their respective groups.

• Master-Detail

  • should interrupt merge sequence if a master-detail row is expanded.

• Paging

  • should merge cells only on current page of data.

• Column Pinning

  • should merge cells in pinned columns.

• Row pinning

  • should merge adjacent pinned rows in pinned row area.
  • should merge adjacent ghost rows in unpinned area.
  • should not merge ghost and data rows together.

• Activation

  • should interrupt merge sequence so that active row has no merging.

• Updating

  • should edit the individual row/cell values for the active record.

• Row Selection

  • should mark all merged cells that intersect with a selected row as selected.

• Cell Selection

  • should interrupt merge sequence so that selected cell has no merging.

• Column selection

  • should mark merged cells in selected column as selected.
  • selected data API should return all associated data fields as selected.

• Filtering

  • should merge cells in filtered data.

• Searching

  • findNext \ findPrev should count merged cells as 1 result and navigate once through them.

• Multi-row layout

  • should throw warning and disallow merging with mrl.

• Hierarchical grid

  • should allow configuring and merging cells on each level of hierarchy.
  • should merge cells within their respective grids only.
  • should interrupt merge sequence if row is expanded and a child grid is shown between same value cells.

• Tree grid

  • should merge all cells with same values, even if on different levels by default.
  • should allow setting the ByLevelTreeGridMergeStrategy as the mergeStrategy to merge only data on the same hierarchy level.

5. Accessibility

6. Assumptions and Limitations

Assumptions	Limitation Notes
Pivot grid does not allow cell merging.	You cannot configure columns as they are generated based on data aggregations. Also merging of data does not make sense in a pivot grid scenario.
Cell merging is not supported in combination with MRL	Both span complex layouts that don't make sense when combined. A warning will be thrown if such invalid configuration is detected.

7. References

Specify all referenced external sources