From df36a616a967d9e204f0efbeda1434303b57992b Mon Sep 17 00:00:00 2001
From: SheetJS <dev@sheetjs.com>
Date: Mon, 15 Jul 2024 21:40:51 -0400
Subject: [PATCH] Merged Cells docs

---
 .../02-examples/04-import.md                  |   2 +-
 .../02-examples/06-loader.md                  |  12 +-
 docz/docs/03-demos/02-frontend/01-kaioken.md  |   3 +-
 docz/docs/03-demos/02-frontend/02-react.md    |   7 +-
 docz/docs/03-demos/02-frontend/03-angular.md  |   7 +-
 docz/docs/03-demos/02-frontend/04-vue.md      |   7 +-
 docz/docs/03-demos/02-frontend/05-svelte.md   |   4 +-
 .../docs/03-demos/02-frontend/07-angularjs.md |   7 +-
 docz/docs/06-solutions/03-processing.md       |  23 +-
 docz/docs/06-solutions/05-output.md           |   5 +-
 docz/docs/07-csf/03-sheet.md                  |   6 +-
 docz/docs/07-csf/07-features/11-merges.md     | 268 ++++++++++++++++++
 docz/static/files/merges.png                  | Bin 0 -> 29922 bytes
 13 files changed, 307 insertions(+), 44 deletions(-)
 create mode 100644 docz/docs/07-csf/07-features/11-merges.md
 create mode 100644 docz/static/files/merges.png

diff --git a/docz/docs/02-getting-started/02-examples/04-import.md b/docz/docs/02-getting-started/02-examples/04-import.md
index 13d4e18..09c6ccb 100644
--- a/docz/docs/02-getting-started/02-examples/04-import.md
+++ b/docz/docs/02-getting-started/02-examples/04-import.md
@@ -1089,7 +1089,7 @@ When the app is loaded, the data will be displayed in rows.
 [^7]: See [`sheet_to_html` in "Utilities"](/docs/api/utilities/html#html-table-output)
 [^8]: See [`sheet_to_json` in "Utilities"](/docs/api/utilities/array#array-output)
 [^9]: See [`sheet_to_json` in "Utilities"](/docs/api/utilities/array#array-output)
-[^10]: See [`!merges` in "Sheet Objects"](/docs/csf/sheet#worksheet-object)
+[^10]: See ["Merged Cells" in "SheetJS Data Model"](/docs/csf/features/merges)
 [^11]: See ["Column Names" in "Addresses and Ranges"](/docs/csf/general#column-names)
 [^12]: See ["Array of Objects" in "ReactJS"](/docs/demos/frontend/react#array-of-objects)
 [^13]: See ["Running on Device"](https://reactnative.dev/docs/running-on-device) in the React Native documentation for more details.
\ No newline at end of file
diff --git a/docz/docs/02-getting-started/02-examples/06-loader.md b/docz/docs/02-getting-started/02-examples/06-loader.md
index d931b70..5ec8071 100644
--- a/docz/docs/02-getting-started/02-examples/06-loader.md
+++ b/docz/docs/02-getting-started/02-examples/06-loader.md
@@ -35,7 +35,7 @@ This demo was tested in the following configurations:
 
 | Date       | Platform                                                      |
 |:-----------|:--------------------------------------------------------------|
-| 2024-06-19 | Apple M2 Max 12-Core CPU + 30-Core GPU (32 GB unified memory) |
+| 2024-07-15 | Apple M2 Max 12-Core CPU + 30-Core GPU (32 GB unified memory) |
 | 2024-07-14 | NVIDIA RTX 4090 (24 GB VRAM) + i9-10910 (128 GB RAM)          |
 | 2024-07-14 | NVIDIA RTX 4080 SUPER (16 GB VRAM) + i9-10910 (128 GB RAM)    |
 
@@ -819,6 +819,16 @@ The filtered results should match the following screenshot:
 
 ![Expected Results](pathname:///loadofsheet/expected.png)
 
+:::tip pass
+
+The [SheetJS model](/docs/csf) exposes [formulae](/docs/csf/features/formulae)
+and other features.
+
+[SheetJS Pro](https://sheetjs.com/pro) builds expose cell styling, images,
+charts, tables, and other features.
+
+:::
+
 [^1]: See ["How to load CSV data"](https://js.langchain.com/v0.2/docs/how_to/document_loader_csv) in the LangChain documentation
 [^2]: See [`readFile` in "Reading Files"](/docs/api/parse-options)
 [^3]: See ["SheetJS Data Model"](/docs/csf/)
diff --git a/docz/docs/03-demos/02-frontend/01-kaioken.md b/docz/docs/03-demos/02-frontend/01-kaioken.md
index 3e7de30..15ad90a 100644
--- a/docz/docs/03-demos/02-frontend/01-kaioken.md
+++ b/docz/docs/03-demos/02-frontend/01-kaioken.md
@@ -537,7 +537,7 @@ will generate a workbook that can be opened in a spreadsheet editor.
 
 The main disadvantage of the Array of Objects approach is the specific nature
 of the columns.  For more general use, passing around an Array of Arrays works.
-However, this does not handle merge cells well!
+However, this does not handle merge cells[^6] well!
 
 The [`sheet_to_html`](/docs/api/utilities/html#html-table-output) function
 generates HTML that is aware of merges and other worksheet features. To add the
@@ -685,3 +685,4 @@ will generate a workbook that can be opened in a spreadsheet editor.
 [^3]: See [`useEffect`](https://kaioken.dev/docs/hooks/useEffect) in the Kaioken documentation.
 [^4]: See [`useCallback`](https://kaioken.dev/docs/hooks/useCallback) in the Kaioken documentation.
 [^5]: See [`useCallback`](https://kaioken.dev/docs/hooks/useCallback) in the Kaioken documentation.
+[^6]: See ["Merged Cells" in "SheetJS Data Model"](/docs/csf/features/merges) for more details.
diff --git a/docz/docs/03-demos/02-frontend/02-react.md b/docz/docs/03-demos/02-frontend/02-react.md
index bde3d9b..47e1f59 100644
--- a/docz/docs/03-demos/02-frontend/02-react.md
+++ b/docz/docs/03-demos/02-frontend/02-react.md
@@ -554,11 +554,11 @@ will generate a workbook that can be opened in a spreadsheet editor.
 
 The main disadvantage of the Array of Objects approach is the specific nature
 of the columns.  For more general use, passing around an Array of Arrays works.
-However, this does not handle merge cells well!
+However, this does not handle merge cells[^5] well!
 
 The [`sheet_to_html`](/docs/api/utilities/html#html-table-output) function
 generates HTML that is aware of merges and other worksheet features.  ReactJS
-`dangerouslySetInnerHTML`[^5] prop allows code to set the `innerHTML` attribute,
+`dangerouslySetInnerHTML`[^6] prop allows code to set the `innerHTML` attribute,
 effectively inserting the code into the page.
 
 In this example, the component attaches a `ref` to the `DIV` container. During
@@ -761,4 +761,5 @@ transpiled in the browser using Babel standalone library.
 [^2]: See [`useEffect`](https://react.dev/reference/react/useEffect) in the ReactJS documentation.
 [^3]: See [`useCallback`](https://react.dev/reference/react/useCallback) in the ReactJS documentation.
 [^4]: See [`useCallback`](https://react.dev/reference/react/useCallback) in the ReactJS documentation.
-[^5]: [`dangerouslySetInnerHTML`](https://react.dev/reference/react-dom/components/common#common-props) is a ReactJS prop supported for all built-in components.
\ No newline at end of file
+[^5]: See ["Merged Cells" in "SheetJS Data Model"](/docs/csf/features/merges) for more details.
+[^6]: [`dangerouslySetInnerHTML`](https://react.dev/reference/react-dom/components/common#common-props) is a ReactJS prop supported for all built-in components.
diff --git a/docz/docs/03-demos/02-frontend/03-angular.md b/docz/docs/03-demos/02-frontend/03-angular.md
index 00d04fa..c613a20 100644
--- a/docz/docs/03-demos/02-frontend/03-angular.md
+++ b/docz/docs/03-demos/02-frontend/03-angular.md
@@ -507,12 +507,12 @@ to test the bundled site.
 
 The main disadvantage of the Array of Objects approach is the specific nature
 of the columns.  For more general use, passing around an Array of Arrays works.
-However, this does not handle merge cells well!
+However, this does not handle merge cells[^5] well!
 
 The `sheet_to_html` function generates HTML that is aware of merges and other
 worksheet features.  The generated HTML does not contain any `<script>` tags,
 and should therefore be safe to pass to an `innerHTML`-bound variable, but the
-`DomSanitizer` approach[^5] is strongly recommended:
+`DomSanitizer` approach[^6] is strongly recommended:
 
 <Tabs groupId="ngVer">
   <TabItem value="2" label="Angular 2-16">
@@ -1042,4 +1042,5 @@ npm run build
 [^2]: See `OnInit` in the [Angular 2-16 docs](https://angular.io/api/core/OnInit) or [Angular 17 docs](https://angular.dev/guide/components/lifecycle#ngoninit)
 [^3]: See [`ngFor`](https://angular.io/api/common/NgFor) in the Angular 2-16 docs.
 [^4]: See [`@for`](https://angular.dev/api/core/@for) in the Angular 17 docs.
-[^5]: See `DomSanitizer` in the [Angular 2-16 docs](https://angular.io/api/platform-browser/DomSanitizer) or [Angular 17 docs](https://angular.dev/api/platform-browser/DomSanitizer)
\ No newline at end of file
+[^5]: See ["Merged Cells" in "SheetJS Data Model"](/docs/csf/features/merges) for more details.
+[^6]: See `DomSanitizer` in the [Angular 2-16 docs](https://angular.io/api/platform-browser/DomSanitizer) or [Angular 17 docs](https://angular.dev/api/platform-browser/DomSanitizer)
diff --git a/docz/docs/03-demos/02-frontend/04-vue.md b/docz/docs/03-demos/02-frontend/04-vue.md
index 3e20f00..96dc624 100644
--- a/docz/docs/03-demos/02-frontend/04-vue.md
+++ b/docz/docs/03-demos/02-frontend/04-vue.md
@@ -464,11 +464,11 @@ and test the page.
 
 The main disadvantage of the Array of Objects approach is the specific nature
 of the columns.  For more general use, passing around an Array of Arrays works.
-However, this does not handle merge cells well!
+However, this does not handle merge cells[^5] well!
 
 The [`sheet_to_html`](/docs/api/utilities/html#html-table-output) function
 generates HTML that is aware of merges and other worksheet features.  VueJS
-`v-html`[^5] attribute allows code to set the `innerHTML` attribute, effectively
+`v-html`[^6] attribute allows code to set the `innerHTML` attribute, effectively
 inserting the code into the page.
 
 In this example, the component attaches a `ref` to the `DIV` container. During
@@ -672,4 +672,5 @@ modern design patterns.
 [^2]: See [`onMounted()`](https://vuejs.org/api/composition-api-lifecycle.html#onmounted) in the VueJS documentation.
 [^3]: See [`v-for`](https://vuejs.org/api/built-in-directives.html#v-for) in the VueJS documentation.
 [^4]: See [`v-on`](https://vuejs.org/api/built-in-directives.html#v-on) in the VueJS documentation.
-[^5]: See [`v-html`](https://vuejs.org/api/built-in-directives.html#v-html) in the VueJS documentation.
\ No newline at end of file
+[^5]: See ["Merged Cells" in "SheetJS Data Model"](/docs/csf/features/merges) for more details.
+[^6]: See [`v-html`](https://vuejs.org/api/built-in-directives.html#v-html) in the VueJS documentation.
diff --git a/docz/docs/03-demos/02-frontend/05-svelte.md b/docz/docs/03-demos/02-frontend/05-svelte.md
index 57c7539..95e438f 100644
--- a/docz/docs/03-demos/02-frontend/05-svelte.md
+++ b/docz/docs/03-demos/02-frontend/05-svelte.md
@@ -193,7 +193,7 @@ and test the page.
 
 The main disadvantage of the Array of Objects approach is the specific nature
 of the columns.  For more general use, passing around an Array of Arrays works.
-However, this does not handle merge cells well!
+However, this does not handle merge cells[^1] well!
 
 The `sheet_to_html` function generates HTML that is aware of merges and other
 worksheet features.  Svelte `@html` tag allows raw HTML strings:
@@ -288,3 +288,5 @@ Access the displayed URL (typically `http://localhost:8080`) with a web browser
 and test the page.
 
 </details>
+
+[^1]: See ["Merged Cells" in "SheetJS Data Model"](/docs/csf/features/merges) for more details.
diff --git a/docz/docs/03-demos/02-frontend/07-angularjs.md b/docz/docs/03-demos/02-frontend/07-angularjs.md
index 6bd4503..9ff8beb 100644
--- a/docz/docs/03-demos/02-frontend/07-angularjs.md
+++ b/docz/docs/03-demos/02-frontend/07-angularjs.md
@@ -301,12 +301,12 @@ a worksheet is created and exported to XLSX.
 
 The main disadvantage of the Array of Objects approach is the specific nature
 of the columns.  For more general use, passing around an Array of Arrays works.
-However, this does not handle merge cells well!
+However, this does not handle merge cells[^4] well!
 
 The `sheet_to_html` function generates HTML that is aware of merges and other
 worksheet features.  The generated HTML does not contain any `<script>` tags,
 and should therefore be safe to pass to an `ng-bind-html` binding. This approach
-requires the `ngSanitize` plugin[^4].
+requires the `ngSanitize` plugin[^5].
 
 ```html
 <div ng-controller="sheetjs">
@@ -399,4 +399,5 @@ worksheet is created and exported to XLSX.
 [^1]: See [`$http`](https://docs.angularjs.org/api/ng/service/$http) in the AngularJS documentation.
 [^2]: See ["Workbook Object"](/docs/csf/book)
 [^3]: See ["Creating Directives"](https://docs.angularjs.org/guide/directive#creating-a-directive-that-manipulates-the-dom) in the AngularJS documentation.
-[^4]: See [`ngSanitize`](https://docs.angularjs.org/api/ngSanitize) in the AngularJS documentation.
\ No newline at end of file
+[^4]: See ["Merged Cells" in "SheetJS Data Model"](/docs/csf/features/merges) for more details.
+[^5]: See [`ngSanitize`](https://docs.angularjs.org/api/ngSanitize) in the AngularJS documentation.
diff --git a/docz/docs/06-solutions/03-processing.md b/docz/docs/06-solutions/03-processing.md
index 6b885bd..0ac64b4 100644
--- a/docz/docs/06-solutions/03-processing.md
+++ b/docz/docs/06-solutions/03-processing.md
@@ -173,25 +173,4 @@ XLSX.utils.sheet_add_aoa(worksheet, [
 
 _Merge a group of cells_
 
-```js
-if(!worksheet["!merges"]) worksheet["!merges"] = [];
-worksheet["!merges"].push(XLSX.utils.decode_range("A1:E1"));
-```
-
-The `!merges` property of a worksheet object is a list of [Cell Ranges](/docs/csf/general#cell-ranges).
-The data for the cell will be taken from the top-left cell.
-
-A range can be created with `decode_range` or specified manually:
-
-```js
-worksheet["!merges"].push({
-  s: { r: 2, c: 1 }, // s ("start"): c = 1 r = 2 -> "B3"
-  e: { r: 3, c: 4 }  // e ("end"):   c = 4 r = 3 -> "E4"
-});
-```
-
-:::caution pass
-
-This approach does not verify if two merged ranges intersect.
-
-:::
+**[The exposition has been moved to a separate page.](/docs/csf/features/merges)**
diff --git a/docz/docs/06-solutions/05-output.md b/docz/docs/06-solutions/05-output.md
index 01edb90..7eb1b57 100644
--- a/docz/docs/06-solutions/05-output.md
+++ b/docz/docs/06-solutions/05-output.md
@@ -688,8 +688,9 @@ var html = XLSX.utils.sheet_to_html(worksheet);
 ```
 
 The `sheet_to_html` utility function generates HTML code based on the worksheet
-data.  Each cell in the worksheet is mapped to a `<TD>` element.  Merged cells
-in the worksheet are serialized by setting `colspan` and `rowspan` attributes.
+data.  Each cell in the worksheet is mapped to a `<TD>` element.
+[Merged cells](/docs/csf/features/merges) are serialized using the TR and TH
+`colspan` and `rowspan` attributes.
 
 #### Examples
 
diff --git a/docz/docs/07-csf/03-sheet.md b/docz/docs/07-csf/03-sheet.md
index 599917b..1052ec0 100644
--- a/docz/docs/07-csf/03-sheet.md
+++ b/docz/docs/07-csf/03-sheet.md
@@ -199,10 +199,8 @@ In addition to the aforementioned sheet keys, worksheets also add:
 - `ws['!rows']`: [array of row objects](/docs/csf/features/rowprops).
   Each row object encodes properties including level, height and visibility.
 
-- `ws['!merges']`: array of range objects corresponding to the merged cells in
-  the worksheet.  Plain text formats do not support merge cells.  CSV export
-  will write all cells in the merge range if they exist, so be sure that only
-  the first cell (upper-left) in the range is set.
+- `ws['!merges']`: [array of merge ranges](/docs/csf/features/merges). Each
+  merge object is a range object that represents the covered range.
 
 - `ws['!outline']`: configure how outlines should behave.  Options default to
   the default settings in Excel 2019:
diff --git a/docz/docs/07-csf/07-features/11-merges.md b/docz/docs/07-csf/07-features/11-merges.md
new file mode 100644
index 0000000..01d7030
--- /dev/null
+++ b/docz/docs/07-csf/07-features/11-merges.md
@@ -0,0 +1,268 @@
+---
+title: Merged Cells
+sidebar_position: 11
+---
+
+<details>
+  <summary><b>File Format Support</b> (click to show)</summary>
+
+By default, no cells are merged. Merge metadata is ignored when exporting to a
+file format that does not support merge cells.
+
+Formats store the actual contents of a merged cell in the "top-left" corner
+(first row and first column of the merge range). Some formats can hold data for
+cells that are covered by the merge range.
+
+| Formats   | Merge | Covered |
+|:----------|:-----:|:-------:|
+| XLSX/XLSM |   ✔   |    ✔    |
+| XLSB      |   ✔   |    ✔    |
+| XLML      |   ✔   |    ✔    |
+| BIFF8 XLS |   ✔   |    ✔    |
+| ODS/FODS  |   ✔   |    ✔    |
+| NUMBERS   |   ✔   |    ✔    |
+| HTML      |   ✔   |         |
+
+There are multiple representations of merge cells in the NUMBERS file format.
+Writers use the simplified `.TST.MergeRegionMapArchive` representation. Parsers
+understand the classic form and the modern `.TST.MergeOwnerArchive` form.
+
+</details>
+
+Modern spreadsheet software typically allow users to combine blocks of cells
+into a single unit. This unit can span multiple columns and rows. As shown in
+the following table, HTML TH and TD elements use `colspan` and `rowspan`
+attributes to effectuate merging:
+
+<table><tbody>
+  <tr><td colSpan="4"><center>This title spans four columns</center></td></tr>
+  <tr><td>SheetJS</td><td>supports</td><td>merge</td><td>cells</td></tr>
+</tbody></table>
+
+:::tip pass
+
+This feature was expanded in version `0.20.3`. It is strongly recommended to
+[upgrade to the latest version](/docs/getting-started/installation/).
+
+:::
+
+## Storage
+
+The `!merges` property of the worksheet object is expected to be an array of
+[SheetJS range objects](/docs/csf/general#sheetjs-range). Each range object
+corresponds to a merged range in the worksheet.
+
+The following snippet creates a merge range spanning `A1:B2` :
+
+```js title="Merge the range A1:B2 in a worksheet"
+ws["!merges"] = [
+  { s: { c: 0, r: 0 }, e: { c: 1, r: 1 } }  // A1:B2
+];
+```
+
+:::caution pass
+
+**Overlapping merges are not automatically detected!**
+
+:::
+
+### Range
+
+The [`decode_range`](/docs/csf/general#cell-ranges-1) method creates range
+objects from A1-style range strings.
+
+The following snippet creates a merge range spanning `A1:B2` :
+
+```js title="Merge the range A1:B2 in a worksheet"
+ws["!merges"] = [
+  XLSX.utils.decode_range("A1:B2")
+];
+```
+
+### Overlap
+
+When adding merges to an existing workbook, it is strongly recommended to scan
+the merges array and test for collisions:
+
+```js title="Add a merged range to a worksheet"
+function sheet_add_merge(ws, range) {
+  /* if `range` is a string, parse into a range object */
+  var merge = typeof range == "string" ? XLSX.utils.decode_range(range) : range;
+
+  /* create array merge if it does not exist */
+  if(!ws["!merges"]) ws["!merges"] = [];
+
+  /* check if the new merge collides with any existing merge */
+  ws["!merges"].forEach(function(range) {
+    if(merge.e.r < range.s.r) return;
+    if(range.e.r < merge.s.r) return;
+    if(merge.e.c < range.s.c) return;
+    if(range.e.c < merge.s.c) return;
+    throw new Error(XLSX.utils.encode_range(merge)+" overlaps "+XLSX.utils.encode_range(range));
+  });
+
+  /* add merge */
+  ws["!merges"].push(merge);
+}
+```
+
+### Cells
+
+Spreadsheet tools will store and use the top-left cell of a merge range. For
+example, if the range `B2:C5` is merged, the cell corresponding to the range
+will be stored in the worksheet in cell `B2`.
+
+#### Covered Cells
+
+Spreadsheet tools can store cells that are covered by a merged cell.
+
+The [SheetJS worksheet object](/docs/csf/sheet) can store covered cells.
+[API Functions](#functions) may omit or include covered cells.
+
+## Live Demo
+
+This example generates a worksheet that matches the following screenshot:
+
+![screenshot](pathname:///files/merges.png)
+
+The merge ranges are `A1:B2`, `C1:C2`, `A3:B3`, `D1:D2`, and `A4:B4`.
+
+```jsx live
+function SheetJSMergeCellsExport() { return (<button onClick={() => {
+  /* write data to the top-left corner of each range */
+  var ws = XLSX.utils.aoa_to_sheet([
+    ["A1:B2",  /* B1 */, "C1:C2",  "Separate blocks"], // row 1
+    [],                                                // row 2
+    ["A3:B3",  /* B3 */, "C3"],                        // row 3
+    ["... are merged separately"],                     // row 4
+  ]);
+  /* add merges */
+  ws["!merges"] = [
+    { s: { c: 0, r: 0 }, e: { c: 1, r: 1 } },  // A1:B2
+    { s: { c: 2, r: 0 }, e: { c: 2, r: 1 } },  // C1:C2
+    { s: { c: 0, r: 2 }, e: { c: 1, r: 2 } },  // A3:B3
+    { s: { c: 3, r: 0 }, e: { c: 3, r: 1 } },  // D1:D2
+    { s: { c: 0, r: 3 }, e: { c: 1, r: 3 } }   // A4:B4
+  ];
+  /* export to XLSX */
+  var wb = XLSX.utils.book_new(ws, "Merges");
+  XLSX.writeFile(wb, "SheetJSMergeCells.xlsx");
+}}><b>Click here to Export</b></button>); }
+```
+
+## Functions
+
+#### HTML
+
+[`table_to_sheet` and `table_to_book`](/docs/api/utilities/html#html-table-input)
+will generate worksheets that include merged ranges:
+
+<details>
+  <summary><b>Live Demo</b> (click to show)</summary>
+
+```jsx live
+function SheetJSDOMMergedCells() {
+  const ref = React.useRef(null);
+  const [ merges, setMerges ] = React.useState([]);
+
+  React.useEffect(() => {
+    if(ref.current) {
+      const tbl = ref.current.getElementsByTagName("TABLE");
+      if(!tbl || !tbl[0]) return;
+      const ws = XLSX.utils.table_to_sheet(tbl[0]);
+      console.log(ws["!merges"])
+      setMerges(ws["!merges"] || []);
+    }
+  }, [ref])
+  const ws = XLSX.utils.aoa_to_sheet([
+    ["A1:B1 is merged", "This cell is covered" ],
+    ["A2 is not merged", "B2 is not merged"]
+  ]);
+  ws["!merges"] = [XLSX.utils.decode_range("A1:B1")];
+  const __html = XLSX.utils.sheet_to_html(ws);
+
+  return ( <>
+    <b>Table:</b>
+    <div ref={ref} dangerouslySetInnerHTML={{__html}}/>
+    <b>Merges:</b>
+    <pre>{merges ? merges.map(m =>  XLSX.utils.encode_range(m)).join("\n") : ""}</pre>
+  </>
+  );
+}
+```
+
+</details>
+
+[`sheet_to_html`](/docs/api/utilities/html#html-table-output) will generate HTML
+strings that use `colspan` and `rowspan` for merged ranges:
+
+<details>
+  <summary><b>Live Demo</b> (click to show)</summary>
+
+```jsx live
+function SheetJSHTMLMergedCells() {
+  const ws = XLSX.utils.aoa_to_sheet([
+    ["A1:B1 is merged", "This cell is covered" ],
+    ["A2 is not merged", "B2 is not merged"]
+  ]);
+  ws["!merges"] = [XLSX.utils.decode_range("A1:B1")];
+  const __html = XLSX.utils.sheet_to_html(ws);
+  return ( <div dangerouslySetInnerHTML={{__html}}/> );
+}
+```
+
+</details>
+
+#### Reading Files
+
+[`read` and `readFile`](/docs/api/parse-options) will extract merge metadata
+from supported files.
+
+#### Writing Files
+
+[`write` and `writeFile`](/docs/api/write-options) will attempt to write merge
+metadata when exporting to file formats that support merged ranges.
+
+When writing to CSV and other formats that do not support merged ranges, every
+cell in the range will be exported. This includes covered cells!
+
+<details>
+  <summary><b>Live Demo</b> (click to show)</summary>
+
+```jsx live
+function SheetJSCSVMergedCells() {
+  const ws = XLSX.utils.aoa_to_sheet([
+    ["A1:B1 is merged", "This cell is covered" ],
+    ["A2 is not merged", "B2 is not merged"]
+  ]);
+  ws["!merges"] = [XLSX.utils.decode_range("A1:B1")];
+  const wb = XLSX.utils.book_new(ws, "Sheet1");
+  const csv = XLSX.write(wb, { type: "string", bookType: "csv"});
+  return ( <pre>{csv}</pre> );
+}
+```
+
+</details>
+
+#### Exporting Data
+
+[`sheet_to_csv`](/docs/api/utilities/csv#delimiter-separated-output) and
+[`sheet_to_json`](/docs/api/utilities/array#array-output) do not support merged
+ranges. The exports will include covered cells:
+
+<details>
+  <summary><b>Live Demo</b> (click to show)</summary>
+
+```jsx live
+function SheetJSAOAMergedCells() {
+  const ws = XLSX.utils.aoa_to_sheet([
+    ["A1:B1 is merged", "This cell is covered" ],
+    ["A2 is not merged", "B2 is not merged"]
+  ]);
+  ws["!merges"] = [XLSX.utils.decode_range("A1:B1")];
+  const aoa = XLSX.utils.sheet_to_json(ws, {header:1});
+  return ( <pre>{JSON.stringify(aoa,2,2)}</pre> );
+}
+```
+
+</details>
diff --git a/docz/static/files/merges.png b/docz/static/files/merges.png
new file mode 100644
index 0000000000000000000000000000000000000000..9c991cad5e78bf3a0823ed5ccf6402b170c6b206
GIT binary patch
literal 29922
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
H<{|$NBi$+s

literal 0
HcmV?d00001