From f9cfa7c5bdee0905e0d286c6c2cda835fcdfe066 Mon Sep 17 00:00:00 2001
From: ghiscoding <gbeaulac@gmail.com>
Date: Tue, 21 Jan 2025 19:12:07 -0500
Subject: [PATCH] docs: add missing colspan/rowspan documentation

---
 docs/TOC.md                                   |  1 +
 .../column-row-spanning.md                    | 64 +++++++++++++++++++
 2 files changed, 65 insertions(+)
 create mode 100644 docs/grid-functionalities/column-row-spanning.md

diff --git a/docs/TOC.md b/docs/TOC.md
index e9cb8c6a0..042f25ace 100644
--- a/docs/TOC.md
+++ b/docs/TOC.md
@@ -49,6 +49,7 @@
 * [Custom Tooltip](grid-functionalities/custom-tooltip.md)
 * [Add, Update or Highlight a Datagrid Item](grid-functionalities/add-update-highlight.md)
 * [Dynamically Add CSS Classes to Item Rows](grid-functionalities/dynamic-item-metadata.md)
+* [Column & Row Spanning](grid-functionalities/column-row-spanning.md)
 * [Context Menu](grid-functionalities/context-menu.md)
 * [Custom Footer](grid-functionalities/custom-footer.md)
 * [Excel Copy Buffer Plugin](grid-functionalities/excel-copy-buffer.md)
diff --git a/docs/grid-functionalities/column-row-spanning.md b/docs/grid-functionalities/column-row-spanning.md
new file mode 100644
index 000000000..09e72095b
--- /dev/null
+++ b/docs/grid-functionalities/column-row-spanning.md
@@ -0,0 +1,64 @@
+### Description
+You can use Colspan and/or Rowspan by using the DataView Item Metadata Provider, however please note that row spanning is under a flag because of its small perf hit (`rowspan` requires an initial loop through of all row item metadata to map all row span).
+
+> [!NOTE]
+> Please note that `colspan` and `rowspan` have multiple constraints that you must be aware,
+> any side effects will **not** keep anything in sync since metadata are based on grid row index based...
+> for example: Filtering/Sorting/Paging/ColumnReorder/ColumnHidding
+> These side effect will require user's own logic to deal with such things!
+
+### Demo
+
+#### Colspan / Rowspan
+[Employee Timesheets](https://ghiscoding.github.io/aurelia-slickgrid/#/example43) / [Demo Component](https://github.com/ghiscoding/aurelia-slickgrid/blob/master/packages/demo/src/examples/slickgrid/example43.ts)
+
+[Large Dataset](https://ghiscoding.github.io/aurelia-slickgrid/#/example44) / [Demo Component](https://github.com/ghiscoding/aurelia-slickgrid/blob/master/packages/demo/src/examples/slickgrid/example44.ts)
+
+### Basic Usage
+
+You can see a basic example below where we set static `metadata`, however you will must often use it with dynamic `metadata`, and it works in both cases. From the example below, the first object key is a number, `0` in our case, which represents the row index (again this can be dynamic). Then if we continue drilling down, we get a `columns` property which holds another object containing all the column indexes that will have a span (which can be individual `colspan`, `rowspan` or both of them at the same time).
+
+What if we have a side effect that kicks in, for example a Sorting, Filtering, ...?
+Well, that is where you the developer will have to add your own logic to update this `metadata` with the expected code logic of what and how it's supposed to behave. Because as mentioned in the note above, the library is pretty dumb and does not know what is the expected behavior for any side effects and it **will not change any** of the `metadata` spans, you have to implement such logic yourself (for example, if we drag a column to another position then the `rowspan` will stay at the same exact column index which is most probably not what you want, you could subscribe to the `onColumnsChanged` to deal with this one). You can see the full list of Events that you can listen for changes and implement necessary callback to update your `metadata` accordingly (see [List of Available Events](https://ghiscoding.gitbook.io/aurelia-slickgrid/events/available-events) docs).
+
+##### Component
+
+```ts
+import type { Column, GridOption, ItemMetadata } from 'aurelia-slickgrid';
+
+example class MyExample {
+  gridOptions: GridOption;
+  columnDefinitions: Column[];
+  dataset: any[];
+
+  // metadata can be dynamic too, it doesn't have to be preset
+  metadata: ItemMetadata | Record<number, ItemMetadata> = {
+    0: {
+      columns: {
+        1: { rowspan: 2 },
+        2: { colspan: 2 },
+        10: { colspan: 3, rowspan: 10 },
+        13: { colspan: 2 },
+        17: { colspan: 2, rowspan: 2 },
+      },
+    }
+  };
+
+  defineGrid() {
+    this.columnDefinitions = [ /*...*/ ];
+
+    this.gridOptions.value = {
+      enableCellNavigation: true,
+      enableCellRowSpan: true, // required for rowspan to work
+      dataView: {
+        globalItemMetadataProvider: {
+          getRowMetadata: (_item, row) => {
+            return this.metadata[row];
+          },
+        },
+      },
+      rowTopOffsetRenderType: 'top', // rowspan doesn't render well with 'transform', default is 'top'
+    };
+  }
+}
+```