Cell Merging Specification
- Overview
- User Stories
- Functionality
- Test Scenarios
- Accessibility
- Assumptions and Limitations
- References
Team Name: Grinders
Developer Name: Maya K.
Designer Name: Yordanka Petkova-Radoeva
- Peer Developer Name | Date:
- Design Manager Name | Date:
- Product Owner Name | Date:
- Platform Architect Name | Date:
| Version | Users | Date | Notes |
|---|---|---|---|
| 1 | Maya K. | 04/07/2025 | Initial draft. |
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.
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.
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.).
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.
Note S.S. -> that's fine but there is this row pinned chip in the first column of a pinned row which will look weird if repeated in a merged cell... maybe something for UX to decide but I have the feeling we should probably not merge ghost row cells
-
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:
Note S.S. please add the signature of the strategy function or the example default function .
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
-
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
| Name | Description | Cancelable | Parameters |
|---|---|---|---|
Automation
- Scenario 1:
- scenario 2:
| Assumptions | Limitation Notes |
|---|---|
| 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. |
Note S.S. make sure to throw a console warn too if this configuration is detected
Specify all referenced external sources