sheetnext 0.2.2 → 0.2.4

package/docs/json-format.md

@@ -1,426 +1,426 @@
-# SheetNext JSON Format
-
-> Manual supplemental document. This file is not generated by `scripts/doc-scanner.js`.
-
-## Purpose
-
-`SN.IO.getData()` exports the current workbook into a JSON object.
-
-`SN.IO.setData(data)` restores a workbook from the same structure.
-
-This document describes the transport format used by those two APIs.
-
-## Versioning
-
-- Current version: `2.0`
-- `setData` requires:
-  - `data.version === "2.0"`
-  - `data.sheets` to be a non-empty array
-
-If either check fails, `setData` returns `false`.
-
-## Top-Level Shape
-
-```json
-{
-  "version": "2.0",
-  "workbookName": "Book1",
-  "activeSheet": "Sheet1",
-  "calcMode": "auto",
-  "readOnly": false,
-  "properties": {},
-  "definedNames": {},
-  "styleTable": {
-    "fonts": [],
-    "fills": [],
-    "borders": [],
-    "aligns": [],
-    "styles": []
-  },
-  "sizeTable": {
-    "rowHeights": [],
-    "colWidths": []
-  },
-  "sheets": []
-}
-```
-
-## Top-Level Fields
-
-| Field | Type | Required | Notes |
-| --- | --- | --- | --- |
-| `version` | string | Yes | Must currently be `"2.0"` |
-| `workbookName` | string | No | Workbook display name |
-| `activeSheet` | string \| null | No | Active sheet name to restore |
-| `calcMode` | `"auto"` \| `"manual"` | No | Defaults to `auto` on import |
-| `readOnly` | boolean | No | Workbook read-only state |
-| `properties` | object | No | Workbook custom properties |
-| `definedNames` | object | No | Workbook-level defined names |
-| `styleTable` | object | Yes | Deduplicated shared style pools |
-| `sizeTable` | object | Yes | Deduplicated row/column size pools |
-| `sheets` | array | Yes | Workbook sheet list |
-| `pivotCaches` | array | No | Pivot cache payloads |
-| `slicerCaches` | array | No | Slicer cache payloads |
-| `_snTrace` | any | No | Internal/export trace marker |
-
-## Shared Tables
-
-`styleTable` and `sizeTable` are shared lookup tables.
-
-Instead of storing the same style or size object repeatedly on every cell/row/column, SheetNext stores the object once in a table and references it by index.
-
-### `styleTable`
-
-| Field | Type | Used By |
-| --- | --- | --- |
-| `fonts` | array | cell `fo` |
-| `fills` | array | cell `fi` |
-| `borders` | array | cell `b` |
-| `aligns` | array | cell `a` |
-| `styles` | array | row `s`, column `s`, cell `s` |
-
-### `sizeTable`
-
-| Field | Type | Used By |
-| --- | --- | --- |
-| `rowHeights` | array<number> | row `h` |
-| `colWidths` | array<number> | column `w` |
-
-## Sheet Shape
-
-Each item in `sheets` looks like this:
-
-```json
-{
-  "name": "Sheet1",
-  "hidden": false,
-  "showGridLines": true,
-  "showRowColHeaders": true,
-  "showPageBreaks": false,
-  "outlinePr": {},
-  "frozenCols": 0,
-  "frozenRows": 0,
-  "freezeStartRow": 0,
-  "freezeStartCol": 0,
-  "defaultColWidth": 72,
-  "defaultRowHeight": 21,
-  "zoom": 1,
-  "activeCell": { "r": 0, "c": 0 },
-  "viewStart": { "r": 0, "c": 0 },
-  "printSettings": null,
-  "rowCount": 200,
-  "colCount": 32,
-  "cols": [],
-  "rows": [],
-  "merges": [],
-  "drawings": []
-}
-```
-
-### Common Sheet Fields
-
-| Field | Type | Notes |
-| --- | --- | --- |
-| `name` | string | Sheet name |
-| `hidden` | boolean | Hidden sheet state |
-| `showGridLines` | boolean | Gridline visibility |
-| `showRowColHeaders` | boolean | Row/column header visibility |
-| `showPageBreaks` | boolean | Page break visibility |
-| `outlinePr` | object | Outline options |
-| `frozenCols` | number | Frozen column count |
-| `frozenRows` | number | Frozen row count |
-| `freezeStartRow` | number | Freeze split start row |
-| `freezeStartCol` | number | Freeze split start column |
-| `defaultColWidth` | number | Default width in px |
-| `defaultRowHeight` | number | Default height in px |
-| `zoom` | number | Import is clamped to `0.1` to `4` |
-| `activeCell` | `{r,c}` | Active cell |
-| `viewStart` | `{r,c}` | View origin |
-| `printSettings` | object \| null | Print config |
-| `rowCount` | number | Sheet size hint |
-| `colCount` | number | Sheet size hint |
-| `sheetProtection` | object | Optional sheet protection config |
-
-### Optional Sheet Sections
-
-These sections are included only when data exists:
-
-- `cols`
-- `rows`
-- `merges`
-- `drawings`
-- `sparklines`
-- `comments`
-- `tables`
-- `autoFilters`
-- `cfRules`
-- `pivotTables`
-- `slicers`
-
-## Column Records
-
-```json
-{
-  "cIndex": 0,
-  "w": 3,
-  "hidden": false,
-  "ol": 1,
-  "cl": false,
-  "s": 2
-}
-```
-
-| Field | Type | Notes |
-| --- | --- | --- |
-| `cIndex` | number | Zero-based column index |
-| `w` | number | Index into `sizeTable.colWidths` |
-| `hidden` | boolean | Hidden column |
-| `ol` | number | Outline level |
-| `cl` | boolean | Collapsed state |
-| `s` | number | Index into `styleTable.styles` |
-
-## Row Records
-
-```json
-{
-  "rIndex": 0,
-  "h": 4,
-  "hidden": false,
-  "ol": 1,
-  "cl": false,
-  "s": 5,
-  "cells": []
-}
-```
-
-| Field | Type | Notes |
-| --- | --- | --- |
-| `rIndex` | number | Zero-based row index |
-| `h` | number | Index into `sizeTable.rowHeights` |
-| `hidden` | boolean | Hidden row |
-| `ol` | number | Outline level |
-| `cl` | boolean | Collapsed state |
-| `s` | number | Index into `styleTable.styles` |
-| `cells` | array | Cell payload list |
-
-## Cell Records
-
-Cell payloads are stored inside `row.cells`.
-
-```json
-{
-  "c": 0,
-  "v": "Hello",
-  "vt": "string",
-  "s": 1
-}
-```
-
-### Cell Position Fields
-
-| Field | Type | Notes |
-| --- | --- | --- |
-| `c` | number | Start column index |
-| `e` | number | Optional end column index for repeated identical cells |
-
-If `e` is present, the same decoded cell template is applied from `c` through `e` inclusive.
-
-### Cell Value Fields
-
-| Field | Type | Notes |
-| --- | --- | --- |
-| `v` | any | Raw cell value |
-| `vt` | string \| null | Value type marker |
-| `f` | string | Formula string; importer ensures a leading `=` |
-| `cv` | any | Cached formula result |
-| `cvt` | string \| null | Cached result type marker |
-
-Supported type markers:
-
-- `date`
-- `time`
-- `dateTime`
-- `nan`
-- `inf`
-- `-inf`
-
-### Cell Style Fields
-
-| Field | Type | Notes |
-| --- | --- | --- |
-| `s` | number | Index into `styleTable.styles` |
-| `fo` | number | Index into `styleTable.fonts` |
-| `fi` | number | Index into `styleTable.fills` |
-| `b` | number | Index into `styleTable.borders` |
-| `a` | number | Index into `styleTable.aligns` |
-| `fmt` | string | Number format |
-| `p` | object | Protection overrides |
-
-### Cell Feature Fields
-
-| Field | Type | Notes |
-| --- | --- | --- |
-| `link` | object | Hyperlink payload |
-| `dv` | object | Data validation payload |
-| `rt` | array | Rich text runs |
-
-Hyperlink shape:
-
-```json
-{
-  "t": "https://example.com",
-  "l": null,
-  "tt": "Open link"
-}
-```
-
-## Merge Records
-
-Each merge item is a normalized range object:
-
-```json
-{
-  "s": { "r": 0, "c": 0 },
-  "e": { "r": 1, "c": 2 }
-}
-```
-
-## Drawing Records
-
-Basic drawing shape:
-
-```json
-{
-  "type": "image",
-  "startCell": { "r": 1, "c": 1 },
-  "offsetX": 0,
-  "offsetY": 0,
-  "width": 240,
-  "height": 120,
-  "anchorType": "twoCell",
-  "rotation": 0
-}
-```
-
-Additional drawing fields depend on `type`:
-
-- `chart`: `chartOption`
-- `image`: `imageBase64`
-- `shape` / `connector`: `shapeType`, `shapeStyle`, `shapeText`, `isTextBox`
-
-## Other Optional Sections
-
-Sheet-level optional payloads:
-
-- `sparklines`
-- `comments`
-- `tables`
-- `autoFilters`
-- `cfRules`
-- `pivotTables`
-- `slicers`
-
-Workbook-level optional payloads:
-
-- `pivotCaches`
-- `slicerCaches`
-
-These sections are round-tripped by `getData` / `setData`, but many of them are larger feature-specific payloads and are best produced by exporting an existing workbook first.
-
-## Dynamic Value Wrapper
-
-Some advanced cache payloads use a typed wrapper so special values survive JSON serialization:
-
-```json
-{
-  "__sn_json_type": "date",
-  "__sn_json_value": "2026-03-17T00:00:00.000Z"
-}
-```
-
-Possible wrapper types:
-
-- `date`
-- `nan`
-- `inf`
-- `-inf`
-
-## Minimal Example
-
-```json
-{
-  "version": "2.0",
-  "workbookName": "Demo",
-  "activeSheet": "Sheet1",
-  "calcMode": "auto",
-  "readOnly": false,
-  "properties": {},
-  "definedNames": {},
-  "styleTable": {
-    "fonts": [],
-    "fills": [],
-    "borders": [],
-    "aligns": [],
-    "styles": []
-  },
-  "sizeTable": {
-    "rowHeights": [],
-    "colWidths": []
-  },
-  "sheets": [
-    {
-      "name": "Sheet1",
-      "hidden": false,
-      "showGridLines": true,
-      "showRowColHeaders": true,
-      "showPageBreaks": false,
-      "outlinePr": {},
-      "frozenCols": 0,
-      "frozenRows": 0,
-      "freezeStartRow": 0,
-      "freezeStartCol": 0,
-      "defaultColWidth": 72,
-      "defaultRowHeight": 21,
-      "zoom": 1,
-      "activeCell": { "r": 0, "c": 0 },
-      "viewStart": { "r": 0, "c": 0 },
-      "printSettings": null,
-      "rowCount": 10,
-      "colCount": 10,
-      "cols": [],
-      "rows": [
-        {
-          "rIndex": 0,
-          "h": 0,
-          "cells": [
-            { "c": 0, "v": "Name" },
-            { "c": 1, "v": "Score" }
-          ]
-        },
-        {
-          "rIndex": 1,
-          "h": 0,
-          "cells": [
-            { "c": 0, "v": "Alice" },
-            { "c": 1, "v": 95 }
-          ]
-        }
-      ],
-      "merges": [],
-      "drawings": []
-    }
-  ]
-}
-```
-
-## Recommended Workflow
-
-If you need to generate JSON externally:
-
-1. create a workbook in SheetNext
-2. export it with `SN.IO.getData()`
-3. treat that JSON as the baseline contract
-4. modify only the sections you need
-5. import it back with `SN.IO.setData(data)`
-
-This is the safest way to stay aligned with future feature additions.
+# SheetNext JSON Format
+
+> Manual supplemental document. This file is not generated by `scripts/doc-scanner.js`.
+
+## Purpose
+
+`SN.IO.getData()` exports the current workbook into a JSON object.
+
+`SN.IO.setData(data)` restores a workbook from the same structure.
+
+This document describes the transport format used by those two APIs.
+
+## Versioning
+
+- Current version: `2.0`
+- `setData` requires:
+  - `data.version === "2.0"`
+  - `data.sheets` to be a non-empty array
+
+If either check fails, `setData` returns `false`.
+
+## Top-Level Shape
+
+```json
+{
+  "version": "2.0",
+  "workbookName": "Book1",
+  "activeSheet": "Sheet1",
+  "calcMode": "auto",
+  "readOnly": false,
+  "properties": {},
+  "definedNames": {},
+  "styleTable": {
+    "fonts": [],
+    "fills": [],
+    "borders": [],
+    "aligns": [],
+    "styles": []
+  },
+  "sizeTable": {
+    "rowHeights": [],
+    "colWidths": []
+  },
+  "sheets": []
+}
+```
+
+## Top-Level Fields
+
+| Field | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `version` | string | Yes | Must currently be `"2.0"` |
+| `workbookName` | string | No | Workbook display name |
+| `activeSheet` | string \| null | No | Active sheet name to restore |
+| `calcMode` | `"auto"` \| `"manual"` | No | Defaults to `auto` on import |
+| `readOnly` | boolean | No | Workbook read-only state |
+| `properties` | object | No | Workbook custom properties |
+| `definedNames` | object | No | Workbook-level defined names |
+| `styleTable` | object | Yes | Deduplicated shared style pools |
+| `sizeTable` | object | Yes | Deduplicated row/column size pools |
+| `sheets` | array | Yes | Workbook sheet list |
+| `pivotCaches` | array | No | Pivot cache payloads |
+| `slicerCaches` | array | No | Slicer cache payloads |
+| `_snTrace` | any | No | Internal/export trace marker |
+
+## Shared Tables
+
+`styleTable` and `sizeTable` are shared lookup tables.
+
+Instead of storing the same style or size object repeatedly on every cell/row/column, SheetNext stores the object once in a table and references it by index.
+
+### `styleTable`
+
+| Field | Type | Used By |
+| --- | --- | --- |
+| `fonts` | array | cell `fo` |
+| `fills` | array | cell `fi` |
+| `borders` | array | cell `b` |
+| `aligns` | array | cell `a` |
+| `styles` | array | row `s`, column `s`, cell `s` |
+
+### `sizeTable`
+
+| Field | Type | Used By |
+| --- | --- | --- |
+| `rowHeights` | array<number> | row `h` |
+| `colWidths` | array<number> | column `w` |
+
+## Sheet Shape
+
+Each item in `sheets` looks like this:
+
+```json
+{
+  "name": "Sheet1",
+  "hidden": false,
+  "showGridLines": true,
+  "showRowColHeaders": true,
+  "showPageBreaks": false,
+  "outlinePr": {},
+  "frozenCols": 0,
+  "frozenRows": 0,
+  "freezeStartRow": 0,
+  "freezeStartCol": 0,
+  "defaultColWidth": 72,
+  "defaultRowHeight": 21,
+  "zoom": 1,
+  "activeCell": { "r": 0, "c": 0 },
+  "viewStart": { "r": 0, "c": 0 },
+  "printSettings": null,
+  "rowCount": 200,
+  "colCount": 32,
+  "cols": [],
+  "rows": [],
+  "merges": [],
+  "drawings": []
+}
+```
+
+### Common Sheet Fields
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `name` | string | Sheet name |
+| `hidden` | boolean | Hidden sheet state |
+| `showGridLines` | boolean | Gridline visibility |
+| `showRowColHeaders` | boolean | Row/column header visibility |
+| `showPageBreaks` | boolean | Page break visibility |
+| `outlinePr` | object | Outline options |
+| `frozenCols` | number | Frozen column count |
+| `frozenRows` | number | Frozen row count |
+| `freezeStartRow` | number | Freeze split start row |
+| `freezeStartCol` | number | Freeze split start column |
+| `defaultColWidth` | number | Default width in px |
+| `defaultRowHeight` | number | Default height in px |
+| `zoom` | number | Import is clamped to `0.1` to `4` |
+| `activeCell` | `{r,c}` | Active cell |
+| `viewStart` | `{r,c}` | View origin |
+| `printSettings` | object \| null | Print config |
+| `rowCount` | number | Sheet size hint |
+| `colCount` | number | Sheet size hint |
+| `sheetProtection` | object | Optional sheet protection config |
+
+### Optional Sheet Sections
+
+These sections are included only when data exists:
+
+- `cols`
+- `rows`
+- `merges`
+- `drawings`
+- `sparklines`
+- `comments`
+- `tables`
+- `autoFilters`
+- `cfRules`
+- `pivotTables`
+- `slicers`
+
+## Column Records
+
+```json
+{
+  "cIndex": 0,
+  "w": 3,
+  "hidden": false,
+  "ol": 1,
+  "cl": false,
+  "s": 2
+}
+```
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `cIndex` | number | Zero-based column index |
+| `w` | number | Index into `sizeTable.colWidths` |
+| `hidden` | boolean | Hidden column |
+| `ol` | number | Outline level |
+| `cl` | boolean | Collapsed state |
+| `s` | number | Index into `styleTable.styles` |
+
+## Row Records
+
+```json
+{
+  "rIndex": 0,
+  "h": 4,
+  "hidden": false,
+  "ol": 1,
+  "cl": false,
+  "s": 5,
+  "cells": []
+}
+```
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `rIndex` | number | Zero-based row index |
+| `h` | number | Index into `sizeTable.rowHeights` |
+| `hidden` | boolean | Hidden row |
+| `ol` | number | Outline level |
+| `cl` | boolean | Collapsed state |
+| `s` | number | Index into `styleTable.styles` |
+| `cells` | array | Cell payload list |
+
+## Cell Records
+
+Cell payloads are stored inside `row.cells`.
+
+```json
+{
+  "c": 0,
+  "v": "Hello",
+  "vt": "string",
+  "s": 1
+}
+```
+
+### Cell Position Fields
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `c` | number | Start column index |
+| `e` | number | Optional end column index for repeated identical cells |
+
+If `e` is present, the same decoded cell template is applied from `c` through `e` inclusive.
+
+### Cell Value Fields
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `v` | any | Raw cell value |
+| `vt` | string \| null | Value type marker |
+| `f` | string | Formula string; importer ensures a leading `=` |
+| `cv` | any | Cached formula result |
+| `cvt` | string \| null | Cached result type marker |
+
+Supported type markers:
+
+- `date`
+- `time`
+- `dateTime`
+- `nan`
+- `inf`
+- `-inf`
+
+### Cell Style Fields
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `s` | number | Index into `styleTable.styles` |
+| `fo` | number | Index into `styleTable.fonts` |
+| `fi` | number | Index into `styleTable.fills` |
+| `b` | number | Index into `styleTable.borders` |
+| `a` | number | Index into `styleTable.aligns` |
+| `fmt` | string | Number format |
+| `p` | object | Protection overrides |
+
+### Cell Feature Fields
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `link` | object | Hyperlink payload |
+| `dv` | object | Data validation payload |
+| `rt` | array | Rich text runs |
+
+Hyperlink shape:
+
+```json
+{
+  "t": "https://example.com",
+  "l": null,
+  "tt": "Open link"
+}
+```
+
+## Merge Records
+
+Each merge item is a normalized range object:
+
+```json
+{
+  "s": { "r": 0, "c": 0 },
+  "e": { "r": 1, "c": 2 }
+}
+```
+
+## Drawing Records
+
+Basic drawing shape:
+
+```json
+{
+  "type": "image",
+  "startCell": { "r": 1, "c": 1 },
+  "offsetX": 0,
+  "offsetY": 0,
+  "width": 240,
+  "height": 120,
+  "anchorType": "twoCell",
+  "rotation": 0
+}
+```
+
+Additional drawing fields depend on `type`:
+
+- `chart`: `chartOption`
+- `image`: `imageBase64`
+- `shape` / `connector`: `shapeType`, `shapeStyle`, `shapeText`, `isTextBox`
+
+## Other Optional Sections
+
+Sheet-level optional payloads:
+
+- `sparklines`
+- `comments`
+- `tables`
+- `autoFilters`
+- `cfRules`
+- `pivotTables`
+- `slicers`
+
+Workbook-level optional payloads:
+
+- `pivotCaches`
+- `slicerCaches`
+
+These sections are round-tripped by `getData` / `setData`, but many of them are larger feature-specific payloads and are best produced by exporting an existing workbook first.
+
+## Dynamic Value Wrapper
+
+Some advanced cache payloads use a typed wrapper so special values survive JSON serialization:
+
+```json
+{
+  "__sn_json_type": "date",
+  "__sn_json_value": "2026-03-17T00:00:00.000Z"
+}
+```
+
+Possible wrapper types:
+
+- `date`
+- `nan`
+- `inf`
+- `-inf`
+
+## Minimal Example
+
+```json
+{
+  "version": "2.0",
+  "workbookName": "Demo",
+  "activeSheet": "Sheet1",
+  "calcMode": "auto",
+  "readOnly": false,
+  "properties": {},
+  "definedNames": {},
+  "styleTable": {
+    "fonts": [],
+    "fills": [],
+    "borders": [],
+    "aligns": [],
+    "styles": []
+  },
+  "sizeTable": {
+    "rowHeights": [],
+    "colWidths": []
+  },
+  "sheets": [
+    {
+      "name": "Sheet1",
+      "hidden": false,
+      "showGridLines": true,
+      "showRowColHeaders": true,
+      "showPageBreaks": false,
+      "outlinePr": {},
+      "frozenCols": 0,
+      "frozenRows": 0,
+      "freezeStartRow": 0,
+      "freezeStartCol": 0,
+      "defaultColWidth": 72,
+      "defaultRowHeight": 21,
+      "zoom": 1,
+      "activeCell": { "r": 0, "c": 0 },
+      "viewStart": { "r": 0, "c": 0 },
+      "printSettings": null,
+      "rowCount": 10,
+      "colCount": 10,
+      "cols": [],
+      "rows": [
+        {
+          "rIndex": 0,
+          "h": 0,
+          "cells": [
+            { "c": 0, "v": "Name" },
+            { "c": 1, "v": "Score" }
+          ]
+        },
+        {
+          "rIndex": 1,
+          "h": 0,
+          "cells": [
+            { "c": 0, "v": "Alice" },
+            { "c": 1, "v": 95 }
+          ]
+        }
+      ],
+      "merges": [],
+      "drawings": []
+    }
+  ]
+}
+```
+
+## Recommended Workflow
+
+If you need to generate JSON externally:
+
+1. create a workbook in SheetNext
+2. export it with `SN.IO.getData()`
+3. treat that JSON as the baseline contract
+4. modify only the sections you need
+5. import it back with `SN.IO.setData(data)`
+
+This is the safest way to stay aligned with future feature additions.