diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 90145f0..ea890ad 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -91,6 +91,32 @@ jobs: if: matrix.react == 19 && matrix.node == 24 run: npm pack --dry-run -w react-data-export + # RDE-1.10: javascript-excel's conformance corpus through the public API + # (packages/react-data-export/test/conformance, docs/conformance.md), with + # openpyxl. The test matrix above runs the same tests without openpyxl. + conformance: + name: Conformance + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + - uses: actions/setup-node@v7 + with: + node-version: 26 + cache: npm + - run: npm ci + - name: The corpus copy matches the installed javascript-excel's tag + run: node scripts/sync-jse-corpus.mjs --check + # Same openpyxl as javascript-excel's CI; installed in a virtualenv, not a project dependency. + - name: Python tools (openpyxl) + run: | + python3 -m venv "$RUNNER_TEMP/py" + "$RUNNER_TEMP/py/bin/pip" install --quiet openpyxl==3.1.5 + echo "RDE_PYTHON=$RUNNER_TEMP/py/bin/python" >> "$GITHUB_ENV" + - name: Conformance tests (openpyxl required) + env: + RDE_REQUIRE_OPENPYXL: '1' + run: npm test -w react-data-export -- test/conformance + # Consumer TypeScript matrix: one tarball, type-checked by a consumer project # on several TypeScript versions, @types/react majors and moduleResolution modes. pack: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6fc3c1a..92ac0ea 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -23,6 +23,7 @@ npm run smoke - Library code lives in `packages/react-data-export/src`, tests in `packages/react-data-export/test` (Vitest + React Testing Library). - Everything is TypeScript with `strict` on. +- `packages/react-data-export/test/conformance` runs javascript-excel's conformance corpus through the public API ([docs/conformance.md](docs/conformance.md)). The corpus is copied from javascript-excel's tag for the installed version: after a javascript-excel upgrade, run `npm run conformance:sync` and commit the result (CI checks it). If the corpus changed, `npm run conformance:doc -w react-data-export` updates the doc. With openpyxl installed (`pip install openpyxl==3.1.5`; set `RDE_PYTHON` for a virtualenv's python), the tests also open every file in openpyxl. - New dependencies need a reason in the PR description. The library itself should stay free of runtime dependencies other than the spreadsheet engine. Bug reports and PRs against 0.6.x are welcome as issues; the 0.x code is at the [`v0.6.0` tag](https://github.com/securedeveloper/react-data-export/tree/v0.6.0). diff --git a/docs/conformance.md b/docs/conformance.md new file mode 100644 index 0000000..243fead --- /dev/null +++ b/docs/conformance.md @@ -0,0 +1,70 @@ +# Conformance: javascript-excel’s corpus through the React API + + + +javascript-excel keeps a conformance corpus: one workbook per feature area, plus a kitchen sink, each checked in LibreOffice, openpyxl and javascript-excel’s own reader. `packages/react-data-export/test/conformance` runs the same workbooks through react-data-export’s public API (`exportWorkbook`, `exportDataset`, the hooks and the components) and compares the result with the file javascript-excel writes for the same workbook. + +## How it is checked + +- **The corpus** is copied from javascript-excel’s git tag for the installed version (`npm run conformance:sync`; CI fails when the copy is out of date). +- **Each workbook** becomes `exportWorkbook` input: a sheet frozen below a row of titles is a dataset with that row as its header and `freezeHeader`; any other sheet is headerless blocks of array rows (`header: false`, columns picked by `index`). Column widths, hidden columns, right-to-left, the active sheet, document properties and write options carry over. +- **Byte-identical** to javascript-excel’s file when the API can express every feature of the file. +- **Otherwise** the features it cannot express are exactly the ones listed for the file below, and the file is byte-identical to javascript-excel’s file for the same workbook without them. (A column style stays on the column’s cells, as javascript-excel’s writer applies it to them.) +- **Read back** with `javascript-excel/read`: no warnings, and the same sheets, values, merges and defined names as that workbook. +- **openpyxl** opens it and sees the same sheets and cell values as in javascript-excel’s file of the full corpus workbook (except where the 1904 date system or a merge changes them). This runs in CI’s Conformance job. +- **exportDataset** writes the same bytes as `exportWorkbook` for every single-sheet file, and `format: 'csv'` writes what javascript-excel’s `toCsvBlob` writes. +- **The builders file** (`19-builders`) is built with `fromDataset`/`fromDatasets`; its Dataset and Stacked sheets are also built from the same dataset input through `exportWorkbook`, `useExcelExport` and ``, byte-identical to javascript-excel’s file. +- **Table export:** javascript-excel’s table golden case (`fromTable`) through `exportTable`, `useTableExport` and `` is byte-identical to `fromTable` + `toUint8Array`. + +## Files + +| File | Covers | Through the React API | +|---|---|---| +| `01-values.xlsx` | Cell values | byte-identical without `colProps.style`. | +| `02-text.xlsx` | Text edge cases and rich text | byte-identical without `colProps.style`. | +| `03-dates.xlsx` | Dates (1900 date system) | byte-identical without `colProps.style`. | +| `04-dates-1904.xlsx` | Dates (1904 date system) | byte-identical without `colProps.style`, `date1904`. | +| `05-formulas.xlsx` | Formulas and cached values | byte-identical. | +| `06-fonts.xlsx` | Fonts | byte-identical without `colProps.style`. | +| `07-fills.xlsx` | Fills | byte-identical without `colProps.style`. | +| `08-borders.xlsx` | Borders | byte-identical without `colProps.style`. | +| `09-alignment.xlsx` | Alignment and protection | byte-identical without `colProps.style`, `rowProps.height`. | +| `10-number-formats.xlsx` | Built-in and custom number formats | byte-identical without `colProps.style`. | +| `11-number-formats-locale.xlsx` | Locale-dependent built-in number formats | byte-identical. | +| `12-colours.xlsx` | Colours: theme order, tints, indexed palette | byte-identical. | +| `13-columns-rows.xlsx` | Column widths, row heights, hidden and outline | byte-identical without `colProps.outlineLevel`, `colProps.style`, `colProps.width: 'auto' (bestFit)`, `defaultRowHeight`, `rowProps.height`, `rowProps.hidden`, `rowProps.outlineLevel`, `rowProps.style`. | +| `14-merges-views.xlsx` | Merges, freeze panes, views and tab colours | byte-identical without `merges`, `state`, `tabColor`, `view.activeCell`, `view.freeze`, `view.showGridLines`, `view.showRowColHeaders`, `view.zoom`. | +| `15-hyperlinks-names.xlsx` | Hyperlinks and defined names | byte-identical without `colProps.style`, `definedNames`. | +| `16-print.xlsx` | Print setup | byte-identical without `print`. | +| `17-workbook.xlsx` | Workbook properties, default font and sheet names | byte-identical without `defaultFont`, `print`. | +| `18-limits.xlsx` | Format limits | byte-identical. | +| `19-builders.xlsx` | Dataset builders (fromDataset, fromDatasets) | byte-identical without `autoFilter`, `colProps.style`, `merges`, `view.freeze`. Its Dataset and Stacked sheets are made by `fromDataset`/`fromDatasets`; built from that same dataset input, they are byte-identical (see above). Converting the finished sheet cannot recover the header groups, hence the list. | +| `99-kitchen-sink.xlsx` | Kitchen sink | byte-identical without `autoFilter`, `colProps.outlineLevel`, `colProps.style`, `colProps.width: 'auto' (bestFit)`, `defaultRowHeight`, `definedNames`, `merges`, `print`, `rowProps.height`, `rowProps.hidden`, `rowProps.outlineLevel`, `rowProps.style`, `state`, `tabColor`, `view.activeCell`, `view.freeze`, `view.showGridLines`, `view.showRowColHeaders`, `view.zoom`. | + +## Not expressible through the React API + +react-data-export builds every sheet with javascript-excel’s dataset builders, so a sheet is what a dataset and its options describe. These features of the corpus are outside that. A file that needs them is written with javascript-excel directly (`toBlob`, then `download` from `javascript-excel/dom`). + +| Feature | Why | +|---|---| +| `autoFilter` | An autofilter on a range other than the header and data rows: `autoFilter: true` always covers exactly those. | +| `colProps.width: 'auto' (bestFit)` | `width: 'auto'` is measured by `fromDataset`, which writes the measured width. javascript-excel’s writer, given `'auto'`, writes the same width and also marks the column best-fit. | +| `colProps.outlineLevel` | Column outline levels (grouped columns). | +| `colProps.style` | Column styles. The column’s cells get the style (the dataset column’s `style` and `headerStyle`), but the column itself, and so its empty cells, does not. | +| `date1904` | The 1904 date system: a workbook setting that neither `WorkbookSpec` nor `ExportOptions` carries. | +| `defaultFont` | The workbook’s default font. | +| `defaultRowHeight` | A sheet’s default row height. | +| `definedNames` | Defined names (workbook and sheet scope). | +| `merges` | Merged cells other than the header-group merges `fromDataset` makes. | +| `print` | Print setup (orientation, paper, margins, print area and titles, headers and footers). | +| `rowProps.height` | Row heights: a dataset has no row properties. | +| `rowProps.hidden` | Hidden rows. | +| `rowProps.outlineLevel` | Row outline levels (grouped rows). | +| `rowProps.style` | Row styles. `rowStyle` styles the cells of a data row, empty ones included, which is not the same file. | +| `state` | Hidden and very hidden sheets. | +| `tabColor` | Sheet tab colours. | +| `view.activeCell` | The active cell of a sheet view. | +| `view.freeze` | Frozen columns, or frozen rows other than the header rows (`freezeHeader`). | +| `view.showGridLines` | Hiding gridlines. | +| `view.showRowColHeaders` | Hiding row and column headings. | +| `view.zoom` | Sheet zoom. | diff --git a/package.json b/package.json index a13c0a5..09abd70 100644 --- a/package.json +++ b/package.json @@ -20,7 +20,8 @@ "consumer-ts": "node scripts/consumer-ts.mjs", "version-packages": "changeset version && node scripts/sync-version.mjs --package packages/react-data-export --file packages/react-data-export/src/index.ts && npm install --package-lock-only --no-audit --no-fund", "test:release": "node --test \"scripts/*.test.mjs\"", - "bundlers": "node scripts/bundlers.mjs" + "bundlers": "node scripts/bundlers.mjs", + "conformance:sync": "node scripts/sync-jse-corpus.mjs" }, "devDependencies": { "@changesets/cli": "3.0.3", diff --git a/packages/react-data-export/package.json b/packages/react-data-export/package.json index 0b4b0c7..b6722d5 100644 --- a/packages/react-data-export/package.json +++ b/packages/react-data-export/package.json @@ -63,6 +63,7 @@ "typecheck": "tsc -p tsconfig.json", "test": "vitest run", "test:watch": "vitest", + "conformance:doc": "UPDATE_CONFORMANCE_DOC=1 vitest run test/conformance/conformance.test.ts -t \"docs/conformance.md\"", "lint:pkg": "publint --strict && attw --pack . --profile node16" }, "devDependencies": { diff --git a/packages/react-data-export/test/conformance/conformance.test.ts b/packages/react-data-export/test/conformance/conformance.test.ts new file mode 100644 index 0000000..6fedca4 --- /dev/null +++ b/packages/react-data-export/test/conformance/conformance.test.ts @@ -0,0 +1,159 @@ +/// +// RDE-1.10: javascript-excel's conformance corpus (JSE-9) through +// react-data-export's public API. +// +// Every corpus workbook is turned into a WorkbookSpec (to-spec.ts) and +// exported with exportWorkbook. The result is compared with what +// javascript-excel writes for the same workbook: +// +// - when the API can express the whole workbook, the two files are +// byte-identical; +// - otherwise the features it cannot express are exactly the ones listed in +// expressible.ts (and docs/conformance.md), and once those are removed from +// javascript-excel's file, both files read back (javascript-excel/read) to +// the same model. +// +// Both files are also opened with openpyxl when it is installed (required in +// CI's Conformance job), as javascript-excel's own conformance test does. +import { execFileSync, spawnSync } from 'node:child_process'; +import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { cellText, dateToSerial, toUint8Array, type Cell, type CellInput, type Workbook } from 'javascript-excel'; +import { toCsvBlob } from 'javascript-excel/csv'; +import { read } from 'javascript-excel/read'; +import { exportDataset, exportWorkbook, type SheetSpec } from '../../src/index'; +import { renderConformanceDoc, NOT_EXPRESSIBLE } from './expressible'; +import { ALL, type CorpusEntry } from './jse/corpus'; +import { toSpec, withoutLost } from './to-spec'; + +const PY = process.env['RDE_PYTHON'] ?? 'python3'; +const dump = join(process.cwd(), 'test', 'conformance', 'jse', 'xlsx_dump.py'); +const hasOpenpyxl = spawnSync(PY, ['-I', '-c', 'import openpyxl'], { stdio: 'ignore' }).status === 0; +if (process.env['RDE_REQUIRE_OPENPYXL'] && !hasOpenpyxl) throw new Error(`openpyxl is required (python: ${PY})`); +const dir = mkdtempSync(join(tmpdir(), 'rde-conformance-')); +afterAll(() => rmSync(dir, { recursive: true, force: true })); + +const bytesOf = async (blob: unknown): Promise => new Uint8Array(await (blob as Blob).arrayBuffer()); + +/** + * Every non-empty cell as [sheet, ref, text], numbers and dates as serials + * (as in javascript-excel's own conformance test: the number format decides + * whether the reader returns a number or a Date). + */ +function texts(wb: Workbook): Array<[string, string, string]> { + const out: Array<[string, string, string]> = []; + const date1904 = wb.date1904 === true; + const norm = (c: CellInput): string => { + const v = c !== null && typeof c === 'object' && !(c instanceof Date) && !('error' in c) && !('richText' in c) ? (c as Cell).value : c; + if (v instanceof Date) return `#${dateToSerial(v, { date1904 }).toFixed(6)}`; + if (typeof v === 'number') return `#${v.toFixed(6)}`; + return cellText(c); + }; + for (const s of wb.sheets) { + s.rows.forEach((row, r) => + row?.forEach((c, col) => { + if (c === undefined || c === null) return; + out.push([s.name, `${r}:${col}`, norm(c)]); + }), + ); + } + return out; +} + +interface Pair { + /** The React API's file. */ + rde: Uint8Array; + /** javascript-excel's file for the corpus workbook. */ + jse: Uint8Array; + /** javascript-excel's file for the corpus workbook without the features the API cannot express. */ + reduced: Uint8Array; +} +const pairs = new Map>(); +function pair(entry: CorpusEntry): Promise { + let p = pairs.get(entry.id); + if (!p) { + p = (async () => { + const converted = toSpec(entry.workbook(), entry.options); + const { spec, options, lost } = converted; + const result = await exportWorkbook(spec, options); + const jse = await toUint8Array(entry.workbook(), entry.options); + return { rde: await bytesOf(result.blob), jse, reduced: lost.length ? await toUint8Array(withoutLost(entry.workbook(), converted), entry.options) : jse }; + })(); + pairs.set(entry.id, p); + } + return p; +} + +describe('the conformance corpus through react-data-export', () => { + it('lists every corpus file in expressible.ts, and docs/conformance.md is up to date', () => { + expect(Object.keys(NOT_EXPRESSIBLE).sort()).toEqual(ALL.map((e) => e.id).sort()); + const path = join(process.cwd(), '..', '..', 'docs', 'conformance.md'); + if (process.env['UPDATE_CONFORMANCE_DOC']) writeFileSync(path, renderConformanceDoc(ALL)); + expect(readFileSync(path, 'utf8')).toBe(renderConformanceDoc(ALL)); + }); + + describe.each(ALL)('$id', (entry) => { + const converted = toSpec(entry.workbook(), entry.options); + const { lost } = converted; + + it('leaves out exactly the features listed as not expressible', () => { + expect(lost).toEqual(NOT_EXPRESSIBLE[entry.id]); + }); + + it(lost.length === 0 ? 'is byte-identical to javascript-excel’s file' : 'is byte-identical to javascript-excel’s file for the workbook without those features', { timeout: 120_000 }, async () => { + const { rde, reduced } = await pair(entry); + expect(rde.length).toBe(reduced.length); + expect(Buffer.from(rde).equals(Buffer.from(reduced))).toBe(true); + }); + + it('reads back with javascript-excel’s reader: no warnings, same sheets, values, merges and names', { timeout: 120_000 }, async () => { + const { rde } = await pair(entry); + const input = withoutLost(entry.workbook(), converted); + const { workbook, warnings } = await read(rde); + expect(warnings).toEqual([]); + expect(workbook.sheets.map((s) => [s.name, s.state ?? 'visible'])).toEqual(input.sheets.map((s) => [s.name, s.state ?? 'visible'])); + expect(texts(workbook)).toEqual(texts(input)); + workbook.sheets.forEach((s, i) => expect(s.merges ?? [], s.name).toEqual(input.sheets[i]!.merges ?? [])); + expect((workbook.definedNames ?? []).map((d) => d.name).sort()).toEqual((input.definedNames ?? []).map((d) => d.name).sort()); + }); + + it.skipIf(!hasOpenpyxl || entry.heavy === true)('opens in openpyxl with the same sheets and cell values as javascript-excel’s file', { timeout: 120_000 }, async () => { + const { rde, jse, reduced } = await pair(entry); + const load = (bytes: Uint8Array, name: string): { sheets: Array<{ title: string }>; cells: unknown } => { + const file = join(dir, `${entry.id}-${name}.xlsx`); + writeFileSync(file, bytes); + // Values only: styles and sheet states may be among the features left out. (A value + // openpyxl has no JSON form for is printed with its repr, which holds a memory address.) + const text = execFileSync(PY, ['-I', dump, file, 'values'], { encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 }); + return JSON.parse(text.replace(/ at 0x[0-9a-f]+>/g, '>')) as { sheets: Array<{ title: string }>; cells: unknown }; + }; + const got = load(rde, 'rde'); + // Values do not depend on the features left out, except a date's serial under the + // 1904 date system, and the covered cells of a merge (openpyxl lists them, empty). + const want = load(lost.includes('date1904') || lost.includes('merges') ? reduced : jse, 'jse'); + expect(got.sheets.map((s) => s.title)).toEqual(want.sheets.map((s) => s.title)); + expect(got.cells).toEqual(want.cells); + }); + }); + + // exportDataset (one sheet) and CSV: every single-sheet corpus file. + const single = ALL.filter((e) => e.workbook().sheets.length === 1 && e.heavy !== true); + describe.each(single)('$id as one dataset', (entry) => { + it('exportDataset writes the same file as exportWorkbook', { timeout: 60_000 }, async () => { + const { spec, options } = toSpec(entry.workbook(), entry.options); + const sheet = spec.sheets[0] as SheetSpec; + if ('blocks' in sheet) return; // several blocks need exportWorkbook (fromDatasets) + const { rde } = await pair(entry); + const result = await exportDataset({ columns: sheet.columns, data: sheet.data }, { ...sheet, ...options }); + expect(Buffer.from(await bytesOf(result.blob)).equals(Buffer.from(rde))).toBe(true); + }); + + it('format: csv is what javascript-excel writes for the sheet', async () => { + const { spec, options } = toSpec(entry.workbook(), entry.options); + const result = await exportWorkbook(spec, { ...options, format: 'csv' }); + const want = toCsvBlob(entry.workbook().sheets[0]!) as Blob; + expect(Buffer.from(await bytesOf(result.blob)).equals(Buffer.from(await bytesOf(want)))).toBe(true); + }); + }); +}); diff --git a/packages/react-data-export/test/conformance/expressible.ts b/packages/react-data-export/test/conformance/expressible.ts new file mode 100644 index 0000000..ced2f57 --- /dev/null +++ b/packages/react-data-export/test/conformance/expressible.ts @@ -0,0 +1,128 @@ +// What of javascript-excel's conformance corpus react-data-export's API can +// express. conformance.test.ts checks this list against to-spec.ts, and +// docs/conformance.md is rendered from it (npm run conformance:doc). +import type { CorpusEntry } from './jse/corpus'; +import type { Lost } from './to-spec'; + +/** Why the API cannot express a feature. Keyed by the names to-spec.ts reports. */ +export const REASONS: Record = { + autoFilter: 'An autofilter on a range other than the header and data rows: `autoFilter: true` always covers exactly those.', + "colProps.width: 'auto' (bestFit)": "`width: 'auto'` is measured by `fromDataset`, which writes the measured width. javascript-excel’s writer, given `'auto'`, writes the same width and also marks the column best-fit.", + 'colProps.outlineLevel': 'Column outline levels (grouped columns).', + 'colProps.style': 'Column styles. The column’s cells get the style (the dataset column’s `style` and `headerStyle`), but the column itself, and so its empty cells, does not.', + date1904: 'The 1904 date system: a workbook setting that neither `WorkbookSpec` nor `ExportOptions` carries.', + defaultFont: 'The workbook’s default font.', + defaultRowHeight: 'A sheet’s default row height.', + definedNames: 'Defined names (workbook and sheet scope).', + merges: 'Merged cells other than the header-group merges `fromDataset` makes.', + print: 'Print setup (orientation, paper, margins, print area and titles, headers and footers).', + 'rowProps.height': 'Row heights: a dataset has no row properties.', + 'rowProps.hidden': 'Hidden rows.', + 'rowProps.outlineLevel': 'Row outline levels (grouped rows).', + 'rowProps.style': 'Row styles. `rowStyle` styles the cells of a data row, empty ones included, which is not the same file.', + state: 'Hidden and very hidden sheets.', + tabColor: 'Sheet tab colours.', + 'view.activeCell': 'The active cell of a sheet view.', + 'view.freeze': 'Frozen columns, or frozen rows other than the header rows (`freezeHeader`).', + 'view.showGridLines': 'Hiding gridlines.', + 'view.showRowColHeaders': 'Hiding row and column headings.', + 'view.zoom': 'Sheet zoom.', +}; + +/** Per corpus file: the features the React API leaves out. Empty means the file is byte-identical. */ +export const NOT_EXPRESSIBLE: Record = { + '01-values': ['colProps.style'], + '02-text': ['colProps.style'], + '03-dates': ['colProps.style'], + '04-dates-1904': ['colProps.style', 'date1904'], + '05-formulas': [], + '06-fonts': ['colProps.style'], + '07-fills': ['colProps.style'], + '08-borders': ['colProps.style'], + '09-alignment': ['colProps.style', 'rowProps.height'], + '10-number-formats': ['colProps.style'], + '11-number-formats-locale': [], + '12-colours': [], + '13-columns-rows': ['colProps.outlineLevel', 'colProps.style', "colProps.width: 'auto' (bestFit)", 'defaultRowHeight', 'rowProps.height', 'rowProps.hidden', 'rowProps.outlineLevel', 'rowProps.style'], + '14-merges-views': ['merges', 'state', 'tabColor', 'view.activeCell', 'view.freeze', 'view.showGridLines', 'view.showRowColHeaders', 'view.zoom'], + '15-hyperlinks-names': ['colProps.style', 'definedNames'], + '16-print': ['print'], + '17-workbook': ['defaultFont', 'print'], + '18-limits': [], + '19-builders': ['autoFilter', 'colProps.style', 'merges', 'view.freeze'], + '99-kitchen-sink': [ + 'autoFilter', + 'colProps.outlineLevel', + 'colProps.style', + "colProps.width: 'auto' (bestFit)", + 'defaultRowHeight', + 'definedNames', + 'merges', + 'print', + 'rowProps.height', + 'rowProps.hidden', + 'rowProps.outlineLevel', + 'rowProps.style', + 'state', + 'tabColor', + 'view.activeCell', + 'view.freeze', + 'view.showGridLines', + 'view.showRowColHeaders', + 'view.zoom', + ], +}; + +/** Notes for the files table. */ +const NOTES: Record = { + '19-builders': 'Its Dataset and Stacked sheets are made by `fromDataset`/`fromDatasets`; built from that same dataset input, they are byte-identical (see above). Converting the finished sheet cannot recover the header groups, hence the list.', +}; + +const code = (s: string): string => `\`${s}\``; + +/** docs/conformance.md. */ +export function renderConformanceDoc(corpus: readonly CorpusEntry[]): string { + const used = new Set(Object.values(NOT_EXPRESSIBLE).flat()); + const lines = [ + '# Conformance: javascript-excel’s corpus through the React API', + '', + '', + '', + 'javascript-excel keeps a conformance corpus: one workbook per feature area, plus a kitchen sink, each checked in LibreOffice, openpyxl and javascript-excel’s own reader. `packages/react-data-export/test/conformance` runs the same workbooks through react-data-export’s public API (`exportWorkbook`, `exportDataset`, the hooks and the components) and compares the result with the file javascript-excel writes for the same workbook.', + '', + '## How it is checked', + '', + '- **The corpus** is copied from javascript-excel’s git tag for the installed version (`npm run conformance:sync`; CI fails when the copy is out of date).', + '- **Each workbook** becomes `exportWorkbook` input: a sheet frozen below a row of titles is a dataset with that row as its header and `freezeHeader`; any other sheet is headerless blocks of array rows (`header: false`, columns picked by `index`). Column widths, hidden columns, right-to-left, the active sheet, document properties and write options carry over.', + '- **Byte-identical** to javascript-excel’s file when the API can express every feature of the file.', + '- **Otherwise** the features it cannot express are exactly the ones listed for the file below, and the file is byte-identical to javascript-excel’s file for the same workbook without them. (A column style stays on the column’s cells, as javascript-excel’s writer applies it to them.)', + '- **Read back** with `javascript-excel/read`: no warnings, and the same sheets, values, merges and defined names as that workbook.', + '- **openpyxl** opens it and sees the same sheets and cell values as in javascript-excel’s file of the full corpus workbook (except where the 1904 date system or a merge changes them). This runs in CI’s Conformance job.', + '- **exportDataset** writes the same bytes as `exportWorkbook` for every single-sheet file, and `format: \'csv\'` writes what javascript-excel’s `toCsvBlob` writes.', + '- **The builders file** (`19-builders`) is built with `fromDataset`/`fromDatasets`; its Dataset and Stacked sheets are also built from the same dataset input through `exportWorkbook`, `useExcelExport` and ``, byte-identical to javascript-excel’s file.', + '- **Table export:** javascript-excel’s table golden case (`fromTable`) through `exportTable`, `useTableExport` and `` is byte-identical to `fromTable` + `toUint8Array`.', + '', + '## Files', + '', + '| File | Covers | Through the React API |', + '|---|---|---|', + ...corpus.map((e) => { + const lost = NOT_EXPRESSIBLE[e.id] ?? []; + const how = lost.length === 0 ? 'byte-identical' : `byte-identical without ${lost.map(code).join(', ')}`; + const note = NOTES[e.id] ? ` ${NOTES[e.id]}` : ''; + return `| \`${e.id}.xlsx\` | ${e.title} | ${how}.${note} |`; + }), + '', + '## Not expressible through the React API', + '', + 'react-data-export builds every sheet with javascript-excel’s dataset builders, so a sheet is what a dataset and its options describe. These features of the corpus are outside that. A file that needs them is written with javascript-excel directly (`toBlob`, then `download` from `javascript-excel/dom`).', + '', + '| Feature | Why |', + '|---|---|', + ...Object.entries(REASONS) + .filter(([k]) => used.has(k)) + .map(([k, why]) => `| ${code(k)} | ${why} |`), + '', + ]; + return lines.join('\n'); +} diff --git a/packages/react-data-export/test/conformance/golden.test.tsx b/packages/react-data-export/test/conformance/golden.test.tsx new file mode 100644 index 0000000..356e4a6 --- /dev/null +++ b/packages/react-data-export/test/conformance/golden.test.tsx @@ -0,0 +1,207 @@ +// RDE-1.10: the corpus files javascript-excel builds with its dataset and +// table builders, through every react-data-export entry point: the export +// functions, the hooks and the components. Each one is byte-identical to +// javascript-excel's builder + toUint8Array for the same input. +// +// Only APIs that exist in Testing Library 12 (React 17) are used. +import { fireEvent, render, screen, waitFor } from '@testing-library/react'; +import { useRef } from 'react'; +import { fromDataset, fromDatasets, toUint8Array, type Dataset, type DatasetBlock, type DatasetOptions, type Style } from 'javascript-excel'; +import { fromTable, type FromTableOptions } from 'javascript-excel/dom'; +import { + ExcelExport, + ExportTableButton, + exportDataset, + exportTable, + exportWorkbook, + useExcelExport, + useTableExport, + type ExportResult, + type UseExcelExport, + type UseTableExport, + type WorkbookSpec, +} from '../../src/index'; +import { ALL } from './jse/corpus'; + +const bytesOf = async (blob: unknown): Promise => Buffer.from(await (blob as Blob).arrayBuffer()); + +// ------------------------------------------------- 19-builders (fromDataset, fromDatasets) + +// The input of the corpus file's Dataset and Stacked sheets, as in +// javascript-excel's corpus.ts. The first test checks that it still builds +// exactly those sheets, so a change to the corpus cannot go unnoticed. +interface Person { + name: string; + team: string; + joined: string; + sales: { q1: number; q2: number }; +} +const HEAD: Style = { font: { bold: true }, fill: 'D9E1F2', border: { bottom: { style: 'thin' } } }; +const people: Person[] = [ + { name: 'Ada', team: 'Core', joined: '2024-01-15', sales: { q1: 1200.5, q2: 980 } }, + { name: 'Grace 漢字', team: 'Core', joined: '2023-06-01', sales: { q1: 860, q2: 1430.25 } }, + { name: 'Linus', team: 'Tools', joined: '2022-11-30', sales: { q1: 0, q2: 75.5 } }, + { name: 'Margaret', team: 'Tools', joined: '2021-03-09', sales: { q1: 2210, q2: 2000 } }, +]; +const band: Style = { fill: 'F2F2F2' }; +const showInternal = false as boolean; +const dataset: Dataset = { + columns: [ + { title: 'Name', key: 'name', width: 'auto' }, + showInternal && { title: 'Internal id', key: 'id' }, + { title: 'Team', key: 'team' }, + { title: 'Joined', key: 'joined', type: 'date', numFmt: 'yyyy-mm-dd' }, + { + title: 'Sales', + headerStyle: { alignment: { horizontal: 'center' } }, + children: [ + { title: 'Q1', path: 'sales.q1', numFmt: '#,##0.00', total: 'sum' }, + { title: 'Q2', path: 'sales.q2', numFmt: '#,##0.00', total: 'average' }, + ], + }, + { title: 'Rows', value: () => 1, total: 'count' }, + ], + data: people, +}; +const datasetOptions: DatasetOptions = { + name: 'Dataset', + freezeHeader: true, + autoFilter: true, + autoWidth: true, + headerStyle: HEAD, + rowStyle: (_r, i) => (i % 2 ? band : undefined), + totals: { label: 'Total', style: { font: { bold: true }, border: { top: { style: 'thin' } } } }, +}; +const blocks: Array> = [ + { columns: [{ title: 'Block 1: products', key: 'p' }, { title: 'Price', key: 'price', numFmt: '#,##0.00' }], data: [{ p: 'Pens', price: 1.5 }, { p: 'Pads', price: 3.25 }] }, + { columns: [{ title: 'Block 2: offset 1 column right', key: 'x' }], data: [{ x: 'one empty row above (gap 1)' }], offset: { cols: 1 } }, +]; +const stackedOptions = { name: 'Stacked', headerStyle: HEAD }; + +const builders = ALL.find((e) => e.id === '19-builders')!; +const corpusSheets = builders.workbook().sheets; +const properties = builders.workbook().properties; +const spec: WorkbookSpec = { sheets: [{ ...dataset, ...datasetOptions }, { blocks, ...stackedOptions }] }; + +/** javascript-excel's file of the corpus's Dataset and Stacked sheets. */ +const jseBuilders = (): Promise => toUint8Array({ properties, sheets: corpusSheets.slice(0, 2) }); + +function HookProbe({ api }: { api: { current: UseExcelExport | null } }) { + api.current = useExcelExport({ download: false, properties }); + return null; +} + +describe('19-builders through react-data-export', () => { + it('the input here builds exactly the corpus sheets', () => { + expect(fromDataset(dataset, datasetOptions)).toEqual(corpusSheets[0]); + expect(fromDatasets(blocks, stackedOptions)).toEqual(corpusSheets[1]); + }); + + it('exportWorkbook is byte-identical', async () => { + const result = await exportWorkbook(spec, { download: false, properties }); + expect((await bytesOf(result.blob)).equals(Buffer.from(await jseBuilders()))).toBe(true); + }); + + it('exportDataset is byte-identical (the Dataset sheet)', async () => { + const result = await exportDataset(dataset, { ...datasetOptions, download: false, properties }); + const want = await toUint8Array({ properties, sheets: [corpusSheets[0]!] }); + expect((await bytesOf(result.blob)).equals(Buffer.from(want))).toBe(true); + }); + + it('useExcelExport is byte-identical', async () => { + const api: { current: UseExcelExport | null } = { current: null }; + render(); + const result = await api.current!.exportWorkbook(spec); + expect((await bytesOf(result.blob)).equals(Buffer.from(await jseBuilders()))).toBe(true); + }); + + it(' is byte-identical', async () => { + const onExported = vi.fn<(r: ExportResult) => void>(); + render( + + Export + , + ); + fireEvent.click(screen.getByRole('button')); + await waitFor(() => expect(onExported).toHaveBeenCalledTimes(1)); + expect((await bytesOf(onExported.mock.calls[0]![0].blob)).equals(Buffer.from(await jseBuilders()))).toBe(true); + }); +}); + +// ------------------------------------------------------------ table (fromTable) + +// javascript-excel's table golden case (its test/dom/golden.test.ts). +const STYLE = `.num { text-align: right } .total td { font-weight: 700; background-color: #ddebf7 } .warn { color: rgb(192, 0, 0); font-style: italic }`; +const INNER = ` + + ProductSales + Q1Q2 + + + Pens1,200.50980 + Pads
(new)8602024-01-15 + secret + internal + + Total4,040.50 +`; +const TABLE = `${INNER}
`; +const tableOptions: FromTableOptions = { name: 'Sales', styles: 'computed', freezeHeader: true, autoFilter: true, autoWidth: true }; + +beforeEach(() => { + document.head.innerHTML = ``; + document.body.innerHTML = ''; // exactly one table in the document +}); +afterEach(() => { + document.head.innerHTML = ''; +}); + +/** javascript-excel's file for the table currently in the document. */ +const jseTable = async (): Promise => Buffer.from(await toUint8Array({ sheets: [fromTable(document.querySelector('table')!, tableOptions)] })); + +/** The golden table, rendered by React, with an object ref. */ +function GoldenTable({ tableRef }: { tableRef: { current: HTMLTableElement | null } }) { + return ; +} + +function TableHookProbe({ api }: { api: { current: UseTableExport | null } }) { + const ref = useRef(null); + api.current = useTableExport(ref, { ...tableOptions, download: false }); + return ; +} + +function TableButton({ onExported }: { onExported: (r: ExportResult) => void }) { + const ref = useRef(null); + return ( + <> + + + Export + + + ); +} + +describe('the table golden case through react-data-export', () => { + it('exportTable is byte-identical to fromTable + toUint8Array', async () => { + document.body.innerHTML = TABLE; + const result = await exportTable(document.querySelector('table')!, { ...tableOptions, download: false }); + expect((await bytesOf(result.blob)).equals(await jseTable())).toBe(true); + expect(result.warnings).toEqual([]); + }); + + it('useTableExport is byte-identical', async () => { + const api: { current: UseTableExport | null } = { current: null }; + render(); + const result = await api.current!.exportTable(); + expect((await bytesOf(result.blob)).equals(await jseTable())).toBe(true); + }); + + it(' is byte-identical', async () => { + const onExported = vi.fn<(r: ExportResult) => void>(); + render(); + fireEvent.click(screen.getByRole('button')); + await waitFor(() => expect(onExported).toHaveBeenCalledTimes(1)); + expect((await bytesOf(onExported.mock.calls[0]![0].blob)).equals(await jseTable())).toBe(true); + }); +}); diff --git a/packages/react-data-export/test/conformance/jse/corpus.ts b/packages/react-data-export/test/conformance/jse/corpus.ts new file mode 100644 index 0000000..52988e8 --- /dev/null +++ b/packages/react-data-export/test/conformance/jse/corpus.ts @@ -0,0 +1,771 @@ +// Generated by scripts/sync-jse-corpus.mjs from javascript-excel's tag for the +// installed version (packages/javascript-excel/test/conformance/corpus.ts). Do not edit. +// The conformance corpus (JSE-9): one workbook per feature area, plus a +// kitchen sink. Each sheet is self-describing: column A says what a row +// tests, column B holds the sample, and column C says what Excel should show. +// +// The same list drives the automated checks (test/conformance/*), the manual +// checklist (docs/conformance.md, generated by scripts/conformance.mjs) and +// the downloadable corpus artifact. +import { fromDataset, fromDatasets, type BorderStyle, type CellInput, type PatternType, type Sheet, type Style, type Workbook, type WriteOptions } from "javascript-excel"; + +/** One thing to look at in Excel or Numbers. */ +export interface Check { + /** Sheet and cells, e.g. "Fills!B2:B20". */ + where: string; + /** What to do or look at. */ + look: string; + /** What you should see. */ + expect: string; + /** The docs/api.md `[to verify]` item this check resolves, if any. */ + verifies?: string; +} + +export interface CorpusEntry { + /** File name without extension. */ + id: string; + title: string; + /** What the file covers. */ + covers: string; + workbook: () => Workbook; + options?: WriteOptions; + /** Large files are skipped by the openpyxl/LibreOffice round trips and noted in the checklist. */ + heavy?: boolean; + checks: Check[]; +} + +/** Fixed timestamps, so the corpus is byte-for-byte reproducible. */ +const FIXED = new Date(Date.UTC(2026, 10, 16, 9, 0, 0)); +const props = (title: string): Workbook["properties"] => ({ title, creator: "javascript-excel conformance corpus", created: FIXED, modified: FIXED }); +const HEAD: Style = { font: { bold: true }, fill: "D9E1F2", border: { bottom: { style: "thin" } } }; + +/** A self-describing sheet: [what, sample, expected] rows under a header. */ +function labelled(name: string, rows: Array<[string, CellInput, string]>, extra: Partial = {}): Sheet { + return { + name, + rows: [ + [ + { value: "What", style: HEAD }, + { value: "Sample", style: HEAD }, + { value: "Expected", style: HEAD }, + ], + ...rows.map(([what, sample, expected]) => [what, sample, expected]), + ], + colProps: [{ width: 34 }, { width: 26 }, { width: 60, style: { alignment: { wrapText: true } } }], + view: { freeze: { rows: 1 } }, + ...extra, + }; +} + +const PATTERNS: PatternType[] = [ + "solid", "mediumGray", "darkGray", "lightGray", "darkHorizontal", "darkVertical", "darkDown", "darkUp", "darkGrid", + "darkTrellis", "lightHorizontal", "lightVertical", "lightDown", "lightUp", "lightGrid", "lightTrellis", "gray125", "gray0625", +]; +const BORDERS: BorderStyle[] = ["thin", "medium", "thick", "double", "hair", "dotted", "dashed", "dashDot", "dashDotDot", "mediumDashed", "mediumDashDot", "mediumDashDotDot", "slantDashDot"]; +const THEME_NAMES = [ + "Background 1 (lt1): white", + "Text 1 (dk1): black", + "Background 2 (lt2): light grey E7E6E6", + "Text 2 (dk2): dark blue-grey 44546A", + "Accent 1: blue 4472C4", + "Accent 2: orange ED7D31", + "Accent 3: grey A5A5A5", + "Accent 4: gold FFC000", + "Accent 5: light blue 5B9BD5", + "Accent 6: green 70AD47", + "Hyperlink: blue 0563C1", + "Followed hyperlink: purple 954F72", +]; +const BUILTIN: Array<[number, string, number | Date]> = [ + [0, "General", 1234.5678], [1, "0", 1234.5678], [2, "0.00", 1234.5678], [3, "#,##0", 1234.5678], [4, "#,##0.00", 1234.5678], + [9, "0%", 0.256], [10, "0.00%", 0.256], [11, "0.00E+00", 1234.5678], [12, "# ?/?", 1.25], [13, "# ??/??", 1.3125], + [14, "short date (mm-dd-yy; locale)", new Date(2024, 0, 15)], [15, "d-mmm-yy", new Date(2024, 0, 15)], [16, "d-mmm", new Date(2024, 0, 15)], + [17, "mmm-yy", new Date(2024, 0, 15)], [18, "h:mm AM/PM", 0.6458333], [19, "h:mm:ss AM/PM", 0.6458333], [20, "h:mm", 0.6458333], + [21, "h:mm:ss", 0.6458333], [22, "m/d/yy h:mm (locale)", new Date(2024, 0, 15, 15, 30)], [37, "#,##0 ;(#,##0)", -1234], [38, "#,##0 ;[Red](#,##0)", -1234], + [39, "#,##0.00;(#,##0.00)", -1234.5], [40, "#,##0.00;[Red](#,##0.00)", -1234.5], [45, "mm:ss", 0.0215278], [46, "[h]:mm:ss", 1.5215278], + [47, "mmss.0", 0.0215278], [48, "##0.0E+0", 12345.678], [49, "@ (text)", 1234.5678], +]; + +export const CORPUS: CorpusEntry[] = [ + { + id: "01-values", + title: "Cell values", + covers: "strings, numbers, booleans, error values, empty styled cells, shared and inline strings", + workbook: () => ({ + properties: props("Cell values"), + sheets: [ + labelled("Values", [ + ["Plain text", "Hello", "Hello"], + ["Unicode", "été 漢字 😀 ✓", "été 漢字 😀 ✓ (all characters visible)"], + ["Text that looks like a formula", "=1+1", "the text =1+1, not 2"], + ["Leading and trailing spaces", " padded ", "two spaces before and after 'padded'"], + ["Integer", 42, "42, right-aligned (a number)"], + ["Negative decimal", -3.5, "-3.5"], + ["Floating point", 0.1 + 0.2, "0.3"], + ["Large number", 1e21, "1E+21"], + ["Tiny number", 1e-7, "1E-07"], + ["Max safe integer", Number.MAX_SAFE_INTEGER, "9.0072E+15 (or 9007199254740991 when widened)"], + ["TRUE", true, "TRUE, centred (a boolean)"], + ["FALSE", false, "FALSE"], + ["#N/A", { error: "#N/A" }, "#N/A (an error value; error checking may flag it)"], + ["#DIV/0!", { error: "#DIV/0!" }, "#DIV/0!"], + ["#VALUE!", { error: "#VALUE!" }, "#VALUE!"], + ["#REF!", { error: "#REF!" }, "#REF!"], + ["#NAME?", { error: "#NAME?" }, "#NAME?"], + ["#NUM!", { error: "#NUM!" }, "#NUM!"], + ["#NULL!", { error: "#NULL!" }, "#NULL!"], + ["Empty cell with a yellow fill", { value: null, style: { fill: "FFFF00" } }, "an empty yellow cell"], + ]), + ], + }), + checks: [ + { where: "Values!B2:B21", look: "Compare column B with column C, row by row.", expect: "Every sample matches its description; no repair prompt when opening." }, + { where: "Values!B4", look: "Select the cell and look at the formula bar.", expect: "The formula bar shows =1+1 as text (the cell is not a formula)." }, + ], + }, + { + id: "02-text", + title: "Text edge cases and rich text", + covers: "ST_Xstring escapes (CR, control characters, literal _xHHHH_), line breaks, 32,767-character text, rich-text runs, inline strings", + options: { sharedStrings: false }, + workbook: () => ({ + properties: props("Text edge cases"), + sheets: [ + labelled("Text", [ + ["Line break (LF), wrapped", { value: "line 1\nline 2", style: { alignment: { wrapText: true } } }, "two lines in one cell"], + ["CR LF line break, wrapped", { value: "line 1\r\nline 2", style: { alignment: { wrapText: true } } }, "two lines; no stray character"], + ["Control character U+0001", "a\u0001b", "a and b with an invisible character between (no _x0001_ text)"], + ["Literal _x0041_ text", "_x0041_", "the literal text _x0041_ (not 'A')"], + ["Literal _x005F_x0041_ text", "_x005F_x0041_", "the literal text _x005F_x0041_"], + ["Tab character", "a\tb", "a and b separated by a tab or space"], + ["Characters < > & \" '", `< > & " '`, `< > & " '`], + ["32,767 characters (the maximum)", "x".repeat(32_767), "a very long run of x; the cell is not truncated (check LEN in the next row)"], + ["LEN of the cell above", { formula: "LEN(B9)", value: 32_767 }, "32767"], + [ + "Rich text", + { richText: [{ text: "bold ", font: { bold: true } }, { text: "red italic ", font: { italic: true, color: "C00000" } }, { text: "plain" }] }, + "'bold' in bold, 'red italic' in red italics, 'plain' plain", + ], + ["Rich text: underline, strike, superscript", { richText: [{ text: "u", font: { underline: true } }, { text: " s", font: { strike: true } }, { text: " x" }, { text: "2", font: { vertAlign: "superscript" } }] }, "u underlined, s struck through, x with a superscript 2"], + ]), + ], + }), + checks: [ + { where: "Text!B2:B12", look: "Compare column B with column C. Strings in this file are inline strings (sharedStrings: false).", expect: "Every sample matches; no _x000D_ or _x0001_ text appears anywhere." }, + { where: "Text!B10", look: "Check the formula result.", expect: "32767." }, + ], + }, + { + id: "03-dates", + title: "Dates (1900 date system)", + covers: "Date cells, default date format, times, the 1900 leap-year quirk, time-only values, the date range", + workbook: () => ({ + properties: props("Dates 1900"), + sheets: [ + labelled("Dates", [ + ["Date, default format (id 14)", new Date(2024, 0, 15), "15 January 2024 in your short-date format"], + ["Date with time", { value: new Date(2024, 0, 15, 10, 30, 15), style: { numFmt: "yyyy-mm-dd hh:mm:ss" } }, "2024-01-15 10:30:15"], + ["1900-01-01 (serial 1)", { value: new Date(1900, 0, 1), style: { numFmt: "yyyy-mm-dd" } }, "1900-01-01"], + ["1900-02-28 (serial 59)", { value: new Date(1900, 1, 28), style: { numFmt: "yyyy-mm-dd" } }, "1900-02-28"], + ["1900-03-01 (serial 61)", { value: new Date(1900, 2, 1), style: { numFmt: "yyyy-mm-dd" } }, "1900-03-01"], + ["9999-12-31 (the maximum)", { value: new Date(9999, 11, 31), style: { numFmt: "yyyy-mm-dd" } }, "9999-12-31"], + ["Serial of 1900-03-01", { value: new Date(1900, 2, 1), style: { numFmt: "0" } }, "61"], + ["Time only (0.5)", { value: 0.5, style: { numFmt: "h:mm" } }, "12:00"], + ["Elapsed time 1.5 days", { value: 1.5, style: { numFmt: "[h]:mm" } }, "36:00"], + ["Date via formula with cached value", { formula: "DATE(2024,1,15)", value: new Date(2024, 0, 15), style: { numFmt: "yyyy-mm-dd" } }, "2024-01-15"], + ]), + ], + }), + checks: [{ where: "Dates!B2:B11", look: "Compare column B with column C.", expect: "All dates and times match. 1900-01-01 and 1900-02-28 show exactly those dates (Excel's 1900 system)." }], + }, + { + id: "04-dates-1904", + title: "Dates (1904 date system)", + covers: "workbookPr/@date1904", + workbook: () => ({ + properties: props("Dates 1904"), + date1904: true, + sheets: [ + labelled("Dates 1904", [ + ["1904-01-01 (serial 0)", { value: new Date(1904, 0, 1), style: { numFmt: "yyyy-mm-dd" } }, "1904-01-01"], + ["2024-01-15", { value: new Date(2024, 0, 15), style: { numFmt: "yyyy-mm-dd" } }, "2024-01-15"], + ["Serial of 2024-01-15", { value: new Date(2024, 0, 15), style: { numFmt: "0" } }, "43844 (1462 less than in the 1900 system)"], + ]), + ], + }), + checks: [ + { where: "Dates 1904!B2:B4", look: "Compare column B with column C.", expect: "Dates match." }, + { where: "File > Options > Advanced (Excel for Mac: Preferences > Calculation)", look: "Look at 'Use 1904 date system'.", expect: "It is ticked for this workbook." }, + ], + }, + { + id: "05-formulas", + title: "Formulas and cached values", + covers: "formulas with cached number/string/boolean/error/date results, array formulas, fullCalcOnLoad for formulas without a cached value", + workbook: () => ({ + properties: props("Formulas"), + sheets: [ + { + name: "Formulas", + rows: [ + [{ value: "What", style: HEAD }, { value: "Sample", style: HEAD }, { value: "Expected", style: HEAD }, { value: "Input", style: HEAD }], + ["Number result", { formula: "D2*2", value: 20 }, "20", 10], + ["String result", { formula: 'D3&"!"', value: "hi!" }, "hi!", "hi"], + ["Boolean result", { formula: "D4>5", value: true }, "TRUE", 10], + ["Error result", { formula: "1/0", value: { error: "#DIV/0!" } }, "#DIV/0!"], + ["No cached value (recalculated on open)", { formula: "SUM(D2,D4)" }, "20, calculated by Excel when the file opens"], + ["Array formula over D2:D4 (B7:B9)", { formula: "D2:D4*10", arrayRef: "B7:B9", value: 100 }, "100, then #VALUE! for the text row, then 100; {braces} in the formula bar"], + ["(array continued)", undefined, ""], + ["(array continued)", undefined, ""], + ["Leading = in the model", { formula: "=1+2", value: 3 }, "3"], + ], + colProps: [{ width: 34 }, { width: 20 }, { width: 60 }, { width: 10 }], + }, + ], + }), + checks: [ + { where: "Formulas!B2:B10", look: "Compare column B with column C; select cells to see each formula in the formula bar.", expect: "Results match. B6 shows 20 after Excel recalculated it. B7 shows {=D2:D4*10} as an array formula." }, + { where: "Close the workbook", look: "Close it without changes.", expect: "Excel may ask to save (it recalculated); that is expected for generated files." }, + ], + }, + { + id: "06-fonts", + title: "Fonts", + covers: "every font property and all four colour forms", + workbook: () => ({ + properties: props("Fonts"), + sheets: [ + labelled("Fonts", [ + ["Arial 14", { value: "Sample", style: { font: { name: "Arial", size: 14 } } }, "Arial, 14 pt"], + ["Bold", { value: "Sample", style: { font: { bold: true } } }, "bold"], + ["Italic", { value: "Sample", style: { font: { italic: true } } }, "italic"], + ["Underline single", { value: "Sample", style: { font: { underline: "single" } } }, "single underline"], + ["Underline double", { value: "Sample", style: { font: { underline: "double" } } }, "double underline"], + ["Underline single accounting", { value: "Sample", style: { font: { underline: "singleAccounting" } } }, "single accounting underline (full cell width)"], + ["Underline double accounting", { value: "Sample", style: { font: { underline: "doubleAccounting" } } }, "double accounting underline"], + ["Strikethrough", { value: "Sample", style: { font: { strike: true } } }, "struck through"], + ["Superscript", { value: "Sample", style: { font: { vertAlign: "superscript" } } }, "superscript (raised, smaller)"], + ["Subscript", { value: "Sample", style: { font: { vertAlign: "subscript" } } }, "subscript (lowered, smaller)"], + ["RGB colour C00000", { value: "Sample", style: { font: { color: "C00000" } } }, "dark red"], + ["Theme colour accent 1", { value: "Sample", style: { font: { color: { theme: 4 } } } }, "blue (Accent 1)"], + ["Theme colour accent 1, tint -0.5", { value: "Sample", style: { font: { color: { theme: 4, tint: -0.5 } } } }, "darker blue (Accent 1, darker 50%)"], + ["Indexed colour 10", { value: "Sample", style: { font: { color: { indexed: 10 } } } }, "red (legacy palette index 10)"], + ["Automatic colour", { value: "Sample", style: { font: { color: { auto: true } } } }, "black (automatic)"], + ["Major scheme font", { value: "Sample", style: { font: { name: "Calibri Light", scheme: "major", size: 14 } } }, "Calibri Light (Headings font), 14 pt"], + ["Size 6 and size 36", { richText: [{ text: "small ", font: { size: 6 } }, { text: "big", font: { size: 36 } }] }, "'small' tiny, 'big' large"], + ]), + ], + }), + checks: [{ where: "Fonts!B2:B18", look: "Compare column B with column C; use Format Cells > Font for details.", expect: "Every font matches its description." }], + }, + { + id: "07-fills", + title: "Fills", + covers: "all 18 non-empty pattern types, the solid shorthand, linear and path gradients", + workbook: () => ({ + properties: props("Fills"), + sheets: [ + labelled("Fills", [ + ...PATTERNS.map((pattern): [string, CellInput, string] => [`Pattern ${pattern}`, { value: "", style: { fill: { pattern, fgColor: "C00000", bgColor: "FFFF00" } } }, `${pattern}: red pattern on yellow (Format Cells > Fill > Pattern Style)`]), + ["Solid shorthand fill: 'DDEBF7'", { value: "", style: { fill: "DDEBF7" } }, "light blue"], + ["Linear gradient, 90°", { value: "", style: { fill: { type: "gradient", gradient: "linear", degree: 90, stops: [{ position: 0, color: "FFFFFF" }, { position: 1, color: "4472C4" }] } } }, "white at the top fading to blue at the bottom"], + ["Path gradient, from the centre", { value: "", style: { fill: { type: "gradient", gradient: "path", left: 0.5, right: 0.5, top: 0.5, bottom: 0.5, stops: [{ position: 0, color: "FFFFFF" }, { position: 1, color: "70AD47" }] } } }, "white centre fading to green edges"], + ]), + ], + }), + checks: [{ where: "Fills!B2:B22", look: "Compare each cell with Format Cells > Fill; the pattern name is in column A.", expect: "Every pattern style matches its name, red on yellow. Gradients as described." }], + }, + { + id: "08-borders", + title: "Borders", + covers: "all 13 visible border styles, a colour per side, diagonals", + workbook: () => ({ + properties: props("Borders"), + sheets: [ + labelled("Borders", [ + ...BORDERS.map((style): [string, CellInput, string] => [`All sides ${style}`, { value: style, style: { border: { left: { style }, right: { style }, top: { style }, bottom: { style } } } }, `${style} border on all four sides`]), + [ + "A colour per side", + { value: "sides", style: { border: { left: { style: "thick", color: "FF0000" }, right: { style: "thick", color: "00B050" }, top: { style: "thick", color: "0070C0" }, bottom: { style: "thick", color: "7030A0" } } } }, + "thick: left red, right green, top blue, bottom purple", + ], + ["Diagonal up and down", { value: "X", style: { border: { diagonal: { style: "thin", color: "FF0000" }, diagonalUp: true, diagonalDown: true } } }, "a red X through the cell"], + ]), + ], + // Leave room between rows so borders do not touch. + }), + checks: [{ where: "Borders!B2:B16", look: "Compare with Format Cells > Border; the style name is in column A and in the cell.", expect: "Each style matches its name (thin, medium, thick, double, hair, dotted, dashed, dash-dot, dash-dot-dot, medium dashed, medium dash-dot, medium dash-dot-dot, slanted dash-dot)." }], + }, + { + id: "09-alignment", + title: "Alignment and protection", + covers: "horizontal and vertical alignment, rotation, vertical text, indent (including the 250 maximum), reading order, wrap, shrink, protection flags", + workbook: () => { + const h = ["general", "left", "center", "right", "fill", "justify", "centerContinuous", "distributed"] as const; + const v = ["top", "center", "bottom", "justify", "distributed"] as const; + return { + properties: props("Alignment"), + sheets: [ + labelled( + "Alignment", + [ + ...h.map((horizontal): [string, CellInput, string] => [`Horizontal ${horizontal}`, { value: horizontal === "fill" ? "ab" : "text", style: { alignment: { horizontal } } }, `horizontal: ${horizontal}`]), + ...v.map((vertical): [string, CellInput, string] => [`Vertical ${vertical}`, { value: "text", style: { alignment: { vertical } } }, `vertical: ${vertical} (row is tall)`]), + ["Rotation +45°", { value: "up", style: { alignment: { rotation: 45 } } }, "text rotated 45° counter-clockwise"], + ["Rotation -45°", { value: "down", style: { alignment: { rotation: -45 } } }, "text rotated 45° clockwise (Format Cells shows -45)"], + ["Rotation 90°", { value: "up", style: { alignment: { rotation: 90 } } }, "text reading upwards"], + ["Vertical (stacked) text", { value: "abc", style: { alignment: { rotation: "vertical" } } }, "letters stacked top to bottom"], + ["Indent 2", { value: "indented", style: { alignment: { horizontal: "left", indent: 2 } } }, "indent 2"], + ["Indent 250 (the documented maximum)", { value: "x", style: { alignment: { horizontal: "left", indent: 250 } } }, "Format Cells > Alignment shows indent 250"], + ["Reading order right-to-left", { value: "abc", style: { alignment: { readingOrder: "rtl" } } }, "Text direction: Right-to-Left"], + ["Wrap text", { value: "a long sentence that wraps inside the cell", style: { alignment: { wrapText: true } } }, "wrapped onto several lines"], + ["Shrink to fit", { value: "a long sentence that shrinks to fit", style: { alignment: { shrinkToFit: true } } }, "smaller font so it fits"], + ["Unlocked cell", { value: "unlocked", style: { protection: { locked: false } } }, "Format Cells > Protection: Locked unticked"], + ["Hidden formula", { formula: "1+1", value: 2, style: { protection: { hidden: true } } }, "Format Cells > Protection: Hidden ticked"], + ], + { rowProps: [undefined, ...h.map(() => undefined), ...v.map(() => ({ height: 45 }))] }, + ), + ], + }; + }, + checks: [ + { where: "Alignment!B2:B26", look: "Compare with Format Cells > Alignment and Protection.", expect: "Everything matches column C." }, + { where: "Alignment!B20", look: "Open Format Cells > Alignment and try to set Indent to 251.", expect: "Excel shows 250 for this cell and refuses 251.", verifies: "indent maximum 250 (§3.5.4)" }, + ], + }, + { + id: "10-number-formats", + title: "Built-in and custom number formats", + covers: "every built-in id the spec defines (0–4, 9–22, 37–40, 45–49) and custom codes", + workbook: () => ({ + properties: props("Number formats"), + sheets: [ + { + name: "Built-in", + rows: [ + [{ value: "Id", style: HEAD }, { value: "Spec code", style: HEAD }, { value: "Sample", style: HEAD }], + ...BUILTIN.map(([id, code, value]) => [id, code, { value, style: { numFmt: id } }]), + ], + colProps: [{ width: 8 }, { width: 34 }, { width: 24 }], + view: { freeze: { rows: 1 } }, + }, + labelled("Custom", [ + ["0.000", { value: 1234.5678, style: { numFmt: "0.000" } }, "1234.568"], + ["#,##0.00 €", { value: 1234.5, style: { numFmt: '#,##0.00 "€"' } }, "1,234.50 €"], + ["Sections with colours", { value: -12.5, style: { numFmt: "[Blue]0.0;[Red]-0.0;0" } }, "-12.5 in red"], + ["yyyy-mm-dd\"T\"hh:mm", { value: new Date(2024, 0, 15, 9, 5), style: { numFmt: 'yyyy-mm-dd"T"hh:mm' } }, "2024-01-15T09:05"], + ["Text placeholder", { value: "abc", style: { numFmt: '"<"@">"' } }, ""], + ["'General' as a string", { value: 1234.5, style: { numFmt: "General" } }, "1234.5 (built-in General)"], + ]), + // How javascript-excel/format (docs/api.md §5.7.4) expects Excel to display these; LibreOffice differs on most. + labelled("Display", [ + ["Day 0 (serial 0.5)", { value: 0.5, style: { numFmt: "yyyy-mm-dd hh:mm" } }, "1900-01-00 12:00"], + ["Serial 1 weekday", { value: 1, style: { numFmt: "dddd" } }, "Sunday"], + ["Seconds round (0.6458333)", { value: 0.6458333, style: { numFmt: "h:mm:ss" } }, "15:30:00"], + ["Rounds into the next day", { value: 45306.99999999, style: { numFmt: "yyyy-mm-dd hh:mm:ss" } }, "2024-01-16 00:00:00"], + ["Date only, same value", { value: 45306.99999999, style: { numFmt: "yyyy-mm-dd" } }, "2024-01-16"], + ["General 1/3 (default width)", { value: 1 / 3, style: { numFmt: "General" } }, "0.333333333"], + ["General 123456789012", { value: 123456789012, style: { numFmt: "General" } }, "1.23457E+11"], + ["General 0.00001", { value: 0.00001, style: { numFmt: "General" } }, "1E-05"], + ["Dangling decimal point", { value: 7, style: { numFmt: "#,##0.###" } }, "7."], + ["Lower-case am/pm", { value: 0.5, style: { numFmt: "h am/pm" } }, "12 pm"], + ["A/P", { value: 0.75, style: { numFmt: "h:mm A/P" } }, "6:00 P"], + ["Negative in a [<0] section", { value: -1, style: { numFmt: '[>100]"big";[<0]"neg";"small"' } }, "neg"], + ["Negative in [<1000]", { value: -5, style: { numFmt: "[<1000]0;[>=1000]#,##0" } }, "-5"], + ["-0.001 as 0.00", { value: -0.001, style: { numFmt: "0.00" } }, "0.00 (no minus sign)"], + ["Built-in id 32", { value: 0.6458333, style: { numFmt: 32 } }, "15:30:00, or your locale's time format"], + ["Buddhist year (bbbb)", { value: 45306, style: { numFmt: "bbbb" } }, "2567"], + ]), + ], + }), + checks: [ + { where: "Built-in!C2:C29", look: "For each row, open Format Cells > Number > Custom and read the selected code.", expect: "The code matches column B (ids 14 and 22 may show your locale's date format). Write down the exact code Excel shows for ids 37, 38, 39, 40 and 47, including spaces.", verifies: "codes and spacing of built-in formats 37–40 and 47 (§11.2)" }, + { where: "Custom!B2:B7", look: "Compare column B with column C.", expect: "Everything matches." }, + { where: "Display!B2:B17", look: "Compare column B with column C. Widen column B if a value shows ####.", expect: "Everything matches. Write down every row that differs.", verifies: "how Excel displays day 0, rounded times, General, a dangling decimal point, am/pm case, conditional sections, built-in id 32 and bbbb (§5.7.4)" }, + ], + }, + { + id: "11-number-formats-locale", + title: "Locale-dependent built-in number formats", + covers: "built-in ids the spec does not list: 5–8, 23–36, 41–44, 50–58", + workbook: () => { + const ids = [5, 6, 7, 8, ...Array.from({ length: 14 }, (_, i) => 23 + i), 41, 42, 43, 44, ...Array.from({ length: 9 }, (_, i) => 50 + i)]; + return { + properties: props("Locale number formats"), + sheets: [ + { + name: "Locale ids", + rows: [ + [{ value: "Id", style: HEAD }, { value: "Date sample (2024-01-15)", style: HEAD }, { value: "Number sample (1234.5)", style: HEAD }, { value: "What you see (write it down)", style: HEAD }], + ...ids.map((id) => [id, { value: new Date(2024, 0, 15), style: { numFmt: id } }, { value: 1234.5, style: { numFmt: id } }]), + ], + colProps: [{ width: 8 }, { width: 28 }, { width: 28 }, { width: 40 }], + view: { freeze: { rows: 1 } }, + }, + ], + }; + }, + checks: [ + { + where: "Locale ids!B2:C32", + look: "Note what each row shows, in your Excel locale. If you can, switch Excel or Windows to Japanese or Chinese and look again at ids 27–36 and 50–58.", + expect: "No repair prompt. In an East Asian locale, ids 27–36 and 50–58 show dates; elsewhere they may show General. Record the result for each id.", + verifies: "ids 27–36 and 50–58 are date formats (§3.4.1)", + }, + ], + }, + { + id: "12-colours", + title: "Colours: theme order, tints, indexed palette", + covers: "theme indices 0–11, tints, indexed colours 0–65 (including 64/65), automatic colour, ARGB alpha", + workbook: () => ({ + properties: props("Colours"), + sheets: [ + { + name: "Theme", + rows: [ + [{ value: "Theme index", style: HEAD }, { value: "Fill", style: HEAD }, { value: "Expected (Office theme)", style: HEAD }, { value: "Tint +0.6", style: HEAD }, { value: "Tint -0.25", style: HEAD }], + ...THEME_NAMES.map((expected, theme) => [ + theme, + { value: "", style: { fill: { pattern: "solid" as const, fgColor: { theme } } } }, + expected, + { value: "", style: { fill: { pattern: "solid" as const, fgColor: { theme, tint: 0.6 } } } }, + { value: "", style: { fill: { pattern: "solid" as const, fgColor: { theme, tint: -0.25 } } } }, + ]), + ], + colProps: [{ width: 12 }, { width: 12 }, { width: 40 }, { width: 12 }, { width: 12 }], + }, + { + name: "Indexed", + rows: [ + [{ value: "Index", style: HEAD }, { value: "Fill", style: HEAD }, { value: "Text in this colour", style: HEAD }, { value: "Expected", style: HEAD }], + ...Array.from({ length: 64 }, (_, i) => [i, { value: "", style: { fill: { pattern: "solid" as const, fgColor: { indexed: i } } } }, { value: "Aa", style: { font: { color: { indexed: i } } } }, i < 8 ? "same as index " + (i + 8) : "legacy palette colour"]), + [64, "", { value: "Aa", style: { font: { color: { indexed: 64 } } } }, "system foreground: black text"], + [65, "", { value: "Aa", style: { font: { color: { indexed: 65 } } } }, "system background: white text (invisible on white)"], + ["auto", "", { value: "Aa", style: { font: { color: { auto: true } } } }, "automatic: black text"], + ["alpha 80", { value: "", style: { fill: "80C00000" } }, "", "dark red (Excel ignores the alpha byte)"], + ], + colProps: [{ width: 10 }, { width: 10 }, { width: 22 }, { width: 44 }], + }, + ], + }), + checks: [ + { + where: "Theme!B2:B13", + look: "Select each fill and open Fill Color > Theme Colors; note which swatch is highlighted.", + expect: "Row 0 is Background 1 (white), 1 is Text 1 (black), 2 is Background 2, 3 is Text 2, 4–9 are Accent 1–6, 10 Hyperlink, 11 Followed Hyperlink. Columns D and E are lighter and darker versions.", + verifies: "theme index order: 0 = lt1, 1 = dk1, 2 = lt2, 3 = dk2 (§3.5.6)", + }, + { where: "Indexed!C66:C67", look: "Look at the text colour of 'Aa' for indexed 64 and 65.", expect: "64 is black (system foreground), 65 is white (system background).", verifies: "indexed 64 = system foreground, 65 = system background (§3.5.6)" }, + ], + }, + { + id: "13-columns-rows", + title: "Column widths, row heights, hidden and outline", + covers: "widths in characters, {wch}, {wpx}, 'auto', width 0; row heights; hidden rows and columns; outline levels; column and row styles; default sizes", + workbook: () => ({ + properties: props("Columns and rows"), + sheets: [ + { + name: "Widths", + defaultRowHeight: 18, + rows: [ + ["8.43 (default)", "10", "20", "{wch: 12}", "{wpx: 64}", "{wpx: 100}", "auto", "hidden", "width 0", "default"], + ["xxxxxxxx", "xxxxxxxxxx", "xxxxxxxxxxxxxxxxxxxx", "xxxxxxxxxxxx", "", "", "auto-sized to this longer text", "", "", ""], + [{ value: "Row 3: height 30", style: { font: { bold: true } } }], + ["Row 4 is hidden"], + ["hidden row"], + ["Rows 6–7: outline level 1"], + ["grouped 1"], + ["grouped 2"], + ["Row 9 has a row style (green fill) but no cells beyond A9", undefined], + ], + colProps: [ + { width: 8.43 }, + { width: 10 }, + { width: 20 }, + { width: { wch: 12 } }, + { width: { wpx: 64 } }, + { width: { wpx: 100 } }, + { width: "auto" }, + { hidden: true }, + { width: 0 }, + undefined, + { outlineLevel: 1, style: { fill: "FCE4D6" } }, + { outlineLevel: 1, style: { fill: "FCE4D6" } }, + ], + rowProps: [undefined, undefined, { height: 30 }, undefined, { hidden: true }, undefined, { outlineLevel: 1 }, { outlineLevel: 1 }, { style: { fill: "E2EFDA" } }], + }, + ], + }), + checks: [ + { + where: "Widths!A:F", + look: "Hover over the right edge of each column header (or Format > Column Width) and note the width Excel shows.", + expect: "A 8.43 (64 px), B 10 (75 px), C 20 (145 px), D 12 (89 px), E 8.43 (64 px), F 13.57 (100 px). On a Mac the pixel values may differ; the character widths must match.", + verifies: "maximum digit width 7 px for Calibri 11 (§3.3)", + }, + { where: "Widths!G:J", look: "Look at columns G to J.", expect: "G is wide enough for its text; H and I are hidden (no header visible); J has the default width." }, + { where: "Widths!rows 3–9, columns K:L", look: "Look at the rows and the outline buttons.", expect: "Row 3 is tall (30 pt), row 5 is hidden, rows 7–8 and columns K–L have outline (group) buttons, row 9 is green across the whole row, columns K–L are light orange." }, + ], + }, + { + id: "14-merges-views", + title: "Merges, freeze panes, views and tab colours", + covers: "merged ranges, frozen rows/columns/both, right-to-left, zoom, gridlines and headings off, selection, tab colours, hidden and very hidden sheets, the active sheet", + workbook: () => ({ + properties: props("Merges and views"), + activeSheet: 1, + sheets: [ + { + name: "Merges", + tabColor: "C00000", + rows: [ + [{ value: "A1:C1 merged, centred", style: { alignment: { horizontal: "center" }, fill: "DDEBF7" } }], + [{ value: "A2:A4 merged vertically", style: { alignment: { vertical: "center" }, fill: "E2EFDA" } }, "B2"], + [undefined, { value: "B3:C4 merged", style: { fill: "FFF2CC" } }], + ], + merges: ["A1:C1", "A2:A4", "B3:C4"], + colProps: [{ width: 24 }, { width: 16 }, { width: 16 }], + }, + { name: "Frozen both (active)", tabColor: { theme: 4 }, rows: Array.from({ length: 40 }, (_, r) => Array.from({ length: 10 }, (_, c) => (r === 0 ? `Col ${c + 1}` : c === 0 ? `Row ${r + 1}` : r * c))), view: { freeze: { rows: 1, cols: 1 }, activeCell: "C5" } }, + { name: "Frozen rows", rows: Array.from({ length: 40 }, (_, r) => [r < 2 ? `header ${r + 1}` : r]), view: { freeze: { rows: 2 } } }, + { name: "RTL zoom 150", rows: [["A1 is on the right"], ["Gridlines and headings are off"]], view: { rightToLeft: true, zoom: 150, showGridLines: false, showRowColHeaders: false } }, + { name: "Hidden", state: "hidden", rows: [["This sheet is hidden"]] }, + { name: "Very hidden", state: "veryHidden", rows: [["This sheet is very hidden"]] }, + ], + }), + checks: [ + { where: "Opening the file", look: "Look at which sheet is shown.", expect: "'Frozen both (active)' is active, with C5 selected." }, + { where: "Merges!A1:C4", look: "Look at the merged cells.", expect: "A1:C1, A2:A4 and B3:C4 are merged; the Merges tab is red, the active sheet's tab is blue." }, + { where: "Frozen both (active), Frozen rows", look: "Scroll down and right.", expect: "Row 1 and column A stay put on the first; rows 1–2 stay put on the second." }, + { where: "RTL zoom 150", look: "Look at the sheet.", expect: "Column A is on the right, zoom 150%, no gridlines, no row/column headings." }, + { where: "Sheet tabs (right-click > Unhide)", look: "List the hidden sheets.", expect: "'Hidden' can be unhidden; 'Very hidden' is not listed." }, + ], + }, + { + id: "15-hyperlinks-names", + title: "Hyperlinks and defined names", + covers: "external, mailto and internal hyperlinks with tooltips; workbook and sheet-scoped defined names", + workbook: () => ({ + properties: props("Hyperlinks and names"), + definedNames: [ + { name: "TaxRate", ref: "'Links & names'!$B$8" }, + { name: "LocalTotal", ref: "'Second sheet'!$A$1", sheet: 1, comment: "scoped to Second sheet" }, + ], + sheets: [ + labelled("Links & names", [ + ["External link", { value: "example.com", hyperlink: "https://example.com/?a=1&b=2" }, "opens https://example.com/?a=1&b=2 (Ctrl/Cmd-click)"], + ["Link with tooltip", { value: "hover me", hyperlink: { target: "https://example.com/docs", tooltip: "Read the docs" } }, "the tooltip 'Read the docs' on hover"], + ["mailto link", { value: "email us", hyperlink: "mailto:someone@example.com?subject=Hello" }, "opens a new mail to someone@example.com"], + ["Internal link", { value: "go to Second sheet", hyperlink: { location: "'Second sheet'!A1" } }, "jumps to Second sheet!A1"], + ["Internal link to a name", { value: "go to TaxRate", hyperlink: { location: "TaxRate" } }, "selects B8 on this sheet"], + ["TaxRate (named cell)", 0.2, "this cell is named TaxRate"], + ["Formula using the name", { formula: "100*TaxRate", value: 20 }, "20"], + ]), + { name: "Second sheet", rows: [["LocalTotal is a sheet-scoped name for this cell"]] }, + ], + }), + checks: [ + { where: "Links & names!B2:B6", look: "Hover and Ctrl/Cmd-click each link.", expect: "Each link does what column C says." }, + { where: "Formulas > Name Manager", look: "List the names.", expect: "TaxRate (Workbook scope, refers to B8) and LocalTotal (scope: Second sheet, comment 'scoped to Second sheet')." }, + ], + }, + { + id: "16-print", + title: "Print setup", + covers: "orientation, paper size, fit to width, margins, centring, gridlines, headings, print area, print titles, headers and footers", + workbook: () => ({ + properties: props("Print setup"), + sheets: [ + { + name: "Print", + rows: Array.from({ length: 80 }, (_, r) => Array.from({ length: 14 }, (_, c) => (r === 0 ? `Heading ${c + 1}` : c === 0 ? `Row ${r + 1}` : r * c))), + print: { + orientation: "landscape", + paperSize: 9, + fitTo: { width: 1 }, + margins: { left: 0.5, right: 0.5, top: 1, bottom: 1, header: 0.4, footer: 0.4 }, + center: { horizontal: true }, + gridLines: true, + headings: true, + printArea: "A1:N80", + printTitles: { rows: "1:1", cols: "A:A" }, + header: { odd: "&LConformance&CPrint setup&R&D" }, + footer: { odd: "&CPage &P of &N", first: "&CFirst page" }, + }, + }, + ], + }), + checks: [ + { + where: "Print!File > Print (preview) and Page Layout > Page Setup", + look: "Look at the preview and the Page Setup dialog.", + expect: + "Landscape, A4, Fit to 1 page wide by automatic tall, margins 0.5/0.5/1/1 in (header/footer 0.4), centred horizontally, gridlines and row/column headings printed, print area A1:N80, row 1 and column A repeat on every page. Header: 'Conformance' left, 'Print setup' centre, the date right. Footer 'Page n of m'; the first page has 'First page' instead.", + }, + ], + }, + { + id: "17-workbook", + title: "Workbook properties, default font and sheet names", + covers: "document properties (core, app, custom), a non-default workbook font, sheet names at the 31-character limit, quoting in references", + workbook: () => ({ + defaultFont: { name: "Arial", size: 10 }, + properties: { + title: "Conformance: workbook", + subject: "javascript-excel", + creator: "Conformance corpus", + keywords: "excel, conformance", + description: "Document properties check", + lastModifiedBy: "javascript-excel", + category: "Tests", + company: "Example Co", + manager: "Team lead", + created: FIXED, + modified: FIXED, + custom: [ + { name: "Project", value: "javascript-excel" }, + { name: "Build", value: 42 }, + { name: "Ratio", value: 0.25 }, + { name: "Released", value: false }, + { name: "Checked on", value: FIXED }, + ], + }, + sheets: [ + { name: "Properties", rows: [["This text is Arial 10 (the workbook default font)."], ["See File > Info > Properties."]] }, + { name: "x".repeat(31), rows: [["This sheet's name is exactly 31 characters."]] }, + { name: "It's quoted", rows: [[{ formula: "'It''s quoted'!A2*2", value: 4 }], [2]], print: { printArea: "A1:A2" } }, + { name: `${"y".repeat(29)}😀`, rows: [["29 y's and an emoji: 31 UTF-16 code units, 30 characters."]] }, + ], + }), + checks: [ + { where: "File > Info > Properties (Advanced Properties > Summary and Custom)", look: "Read the properties.", expect: "Title 'Conformance: workbook', subject, author 'Conformance corpus', keywords, comments, category, company 'Example Co', manager. Custom: Project, Build 42, Ratio 0.25, Released No, Checked on 2026-11-16." }, + { where: "Properties!A1", look: "Look at the font.", expect: "Arial 10; Home > Cell Styles > Normal is Arial 10." }, + { + where: "Any sheet tab", + look: "Rename a sheet to History. Then rename one to 31 characters made of 30 x's and one emoji (😀).", + expect: "Record whether Excel refuses 'History' and whether it accepts the 31-character emoji name (if it does, Excel counts characters, not UTF-16 code units).", + verifies: "'History' is reserved; how the 31-character limit counts astral characters (§3.3)", + }, + ], + }, + { + id: "18-limits", + title: "Format limits", + covers: "the last cell (XFD1048576), 32,767-character text, 64,000 distinct cell formats", + heavy: true, + workbook: () => { + const rows: CellInput[][] = [["Last cell: XFD1048576. 64,000 distinct cell formats in B2:B64001 (different fill colours)."]]; + for (let i = 0; i < 63_999; i++) { + const rgb = (0x100000 + i * 97).toString(16).toUpperCase().slice(-6).padStart(6, "0"); + rows.push([undefined, { value: i, style: { fill: rgb, numFmt: i % 2 ? "0" : "0.0" } }]); + } + const last: CellInput[] = []; + last[16_383] = "XFD1048576"; + rows[1_048_575] = last; + return { properties: props("Limits"), sheets: [{ name: "Limits", rows }] }; + }, + checks: [ + { + where: "Opening the file", + look: "Open it and wait (it is large).", + expect: "No repair prompt. Ctrl/Cmd+End jumps to XFD1048576. The writer emits 64,000 cell formats (the default one plus 63,999), the most it allows; Excel's documented limit is 64,000.", + verifies: "64,000 unique cell formats (§7.2, §11.1)", + }, + ], + }, + { + id: "19-builders", + title: "Dataset builders (fromDataset, fromDatasets)", + covers: "header groups as merged cells, conditional columns, typed and formatted columns, banded rows, auto widths, freeze and filter on the header, SUBTOTAL totals with cached values, stacked datasets", + workbook: () => { + const people = [ + { name: "Ada", team: "Core", joined: "2024-01-15", sales: { q1: 1200.5, q2: 980 } }, + { name: "Grace 漢字", team: "Core", joined: "2023-06-01", sales: { q1: 860, q2: 1430.25 } }, + { name: "Linus", team: "Tools", joined: "2022-11-30", sales: { q1: 0, q2: 75.5 } }, + { name: "Margaret", team: "Tools", joined: "2021-03-09", sales: { q1: 2210, q2: 2000 } }, + ]; + const band: Style = { fill: "F2F2F2" }; + const showInternal = false; + const dataset = fromDataset( + { + columns: [ + { title: "Name", key: "name", width: "auto" }, + showInternal && { title: "Internal id", key: "id" }, + { title: "Team", key: "team" }, + { title: "Joined", key: "joined", type: "date", numFmt: "yyyy-mm-dd" }, + { + title: "Sales", + headerStyle: { alignment: { horizontal: "center" } }, + children: [ + { title: "Q1", path: "sales.q1", numFmt: "#,##0.00", total: "sum" }, + { title: "Q2", path: "sales.q2", numFmt: "#,##0.00", total: "average" }, + ], + }, + { title: "Rows", value: () => 1, total: "count" }, + ], + data: people, + }, + { name: "Dataset", freezeHeader: true, autoFilter: true, autoWidth: true, headerStyle: HEAD, rowStyle: (_r, i) => (i % 2 ? band : undefined), totals: { label: "Total", style: { font: { bold: true }, border: { top: { style: "thin" } } } } }, + ); + const stacked = fromDatasets( + [ + { columns: [{ title: "Block 1: products", key: "p" }, { title: "Price", key: "price", numFmt: "#,##0.00" }], data: [{ p: "Pens", price: 1.5 }, { p: "Pads", price: 3.25 }] }, + { columns: [{ title: "Block 2: offset 1 column right", key: "x" }], data: [{ x: "one empty row above (gap 1)" }], offset: { cols: 1 } }, + ], + { name: "Stacked", headerStyle: HEAD }, + ); + return { + properties: props("Dataset builders"), + sheets: [ + dataset, + stacked, + labelled("Builders guide", [ + ["Dataset!A1:A2", "", "'Name' merged down two rows (it is shallower than the Sales group)"], + ["Dataset!D1:E1", "", "'Sales' merged across Q1 and Q2, centred; A1:A2, B1:B2, C1:C2 and F1:F2 merged down"], + ["Dataset!B:B", "", "Team, not 'Internal id' (that column is conditional and switched off)"], + ["Dataset rows 3, 5", "", "light grey band on every second data row"], + ["Dataset row 7", "", "Total; Q1 =SUBTOTAL(109,D3:D6) shows 4,270.50; Q2 =SUBTOTAL(101,E3:E6) shows 1,121.44; Rows =SUBTOTAL(103,F3:F6) shows 4"], + ["Dataset filter", "", "filter buttons on row 2 (Q1/Q2 row), not on the totals row; filtering hides rows and the totals follow"], + ["Stacked", "", "block 2 starts after one empty row and one column to the right"], + ["Dataset column widths", "", "every column wide enough for its text (auto width); Joined shows full dates, no ###"], + ]), + ], + }; + }, + checks: [ + { where: "Dataset!A1:F7", look: "Compare with the Builders guide sheet.", expect: "Merged header cells, the banding, the totals row values and the date format all as the guide says; rows 1–2 stay frozen." }, + { where: "Dataset, filter on Team", look: "Filter Team to 'Core'.", expect: "Only Ada and Grace remain, and the Q1 total becomes 2,060.50 (SUBTOTAL ignores filtered rows)." }, + { where: "Stacked", look: "Look at the two blocks.", expect: "Block 2 is one row below block 1 and one column to the right, with its own bold header." }, + ], + }, +]; + +/** The kitchen sink: every area's sheets in one workbook. */ +export const KITCHEN_SINK: CorpusEntry = { + id: "99-kitchen-sink", + title: "Kitchen sink", + covers: "every sheet of every non-heavy corpus file in one workbook, with all defined names and properties", + workbook: () => { + const sheets: Sheet[] = []; + const definedNames: NonNullable = []; + const used = new Set(); + for (const entry of CORPUS) { + if (entry.heavy || entry.id === "04-dates-1904" || entry.id === "17-workbook") continue; + const wb = entry.workbook(); + const offset = sheets.length; + for (const s of wb.sheets) { + if (used.has(s.name.toLowerCase())) continue; + used.add(s.name.toLowerCase()); + // The active sheet of the merges file is a view setting; the kitchen sink opens on its first sheet. + sheets.push(s); + } + for (const d of wb.definedNames ?? []) definedNames.push({ ...d, ...(d.sheet !== undefined ? { sheet: d.sheet + offset } : {}) }); + } + return { properties: props("Kitchen sink"), definedNames, sheets }; + }, + checks: [{ where: "Every sheet", look: "Page through every sheet and repeat the checks of the individual files where you like.", expect: "No repair prompt; every sheet looks as in its own file." }], +}; + +export const ALL: CorpusEntry[] = [...CORPUS, KITCHEN_SINK]; diff --git a/packages/react-data-export/test/conformance/jse/xlsx_dump.py b/packages/react-data-export/test/conformance/jse/xlsx_dump.py new file mode 100644 index 0000000..e8dd700 --- /dev/null +++ b/packages/react-data-export/test/conformance/jse/xlsx_dump.py @@ -0,0 +1,243 @@ +# Generated by scripts/sync-jse-corpus.mjs from javascript-excel's tag for the +# installed version (packages/javascript-excel/test/interop/xlsx_dump.py). Do not edit. +"""Dump an .xlsx file as JSON with openpyxl, for test/write/golden.test.ts. + + python3 xlsx_dump.py [values] + +With "values", cells carry only their value (for very large sheets). + +Prints workbook structure, document properties and, for every cell, its +value (formula text and cached value), number format and full style. +""" + +import datetime +import json +import sys + +import openpyxl +from openpyxl.cell.rich_text import CellRichText, TextBlock + + +def color(c): + if c is None: + return None + t = c.type + if t == "rgb": + return {"rgb": c.rgb} + if t == "theme": + return {"theme": c.theme, "tint": c.tint} + if t == "indexed": + return {"indexed": c.indexed} + if t == "auto": + return {"auto": True} + return {"type": t} + + +def plain(v): + """Unwraps openpyxl's nested descriptor values (used by rich-text InlineFont).""" + return getattr(v, "val", v) + + +def font(f): + if f is None: + return None + # InlineFont (rich-text runs) stores the typeface in rFont. + name = getattr(f, "rFont", None) if hasattr(f, "rFont") else f.name + return { + "name": plain(name), + "size": plain(f.sz), + "bold": bool(f.b), + "italic": bool(f.i), + "underline": plain(f.u), + "strike": bool(f.strike), + "vertAlign": plain(f.vertAlign), + "color": color(f.color), + "family": plain(f.family), + "charset": plain(f.charset), + "scheme": plain(f.scheme), + "outline": bool(f.outline), + "shadow": bool(f.shadow), + "condense": bool(f.condense), + "extend": bool(f.extend), + } + + +def fill(f): + if f.tagname == "gradientFill": + return { + "gradient": f.type, + "degree": f.degree, + "left": f.left, + "right": f.right, + "top": f.top, + "bottom": f.bottom, + "stops": [{"position": s.position, "color": color(s.color)} for s in f.stop], + } + return {"pattern": f.patternType, "fgColor": color(f.fgColor), "bgColor": color(f.bgColor)} + + +def side(s): + return {"style": s.style, "color": color(s.color)} if s is not None and s.style else None + + +def border(b): + return { + "left": side(b.left), + "right": side(b.right), + "top": side(b.top), + "bottom": side(b.bottom), + "diagonal": side(b.diagonal), + "diagonalUp": bool(b.diagonalUp), + "diagonalDown": bool(b.diagonalDown), + } + + +def alignment(a): + return { + "horizontal": a.horizontal, + "vertical": a.vertical, + "textRotation": a.textRotation, + "wrapText": bool(a.wrapText), + "shrinkToFit": bool(a.shrinkToFit), + "indent": a.indent, + "readingOrder": a.readingOrder, + "justifyLastLine": bool(a.justifyLastLine), + } + + +def value(v): + if isinstance(v, (datetime.datetime, datetime.date, datetime.time)): + return {"datetime": v.isoformat()} + if isinstance(v, CellRichText): + return { + "richText": [ + {"text": b.text, "font": font(b.font)} if isinstance(b, TextBlock) else {"text": b} + for b in v + ] + } + if v is None or isinstance(v, (bool, int, float, str)): + return v + return {"repr": repr(v)} + + +def dim_style(d): + return {"bold": bool(d.font.b), "fill": color(d.fill.fgColor) if d.fill.patternType else None} if d.has_style else None + + +def hf_part(part): + return {k: getattr(part, k).text for k in ("left", "center", "right") if getattr(part, k).text} + + +def sheet_info(ws): + sv = ws.sheet_view + pane = sv.pane + props = ws.sheet_properties + fmt = ws.sheet_format + ps = ws.page_setup + po = ws.print_options + pm = ws.page_margins + hf = ws.HeaderFooter + return { + "cols": { + k: { + "min": d.min, "max": d.max, "width": d.width, "customWidth": bool(d.customWidth), "bestFit": bool(d.bestFit), + "hidden": bool(d.hidden), "outlineLevel": d.outlineLevel, "collapsed": bool(d.collapsed), "style": dim_style(d), + } + for k, d in ws.column_dimensions.items() + }, + "rows": { + str(k): { + "height": d.height, "customHeight": bool(d.customHeight), "hidden": bool(d.hidden), + "outlineLevel": d.outlineLevel, "collapsed": bool(d.collapsed), "style": dim_style(d), + } + for k, d in ws.row_dimensions.items() + }, + "merges": sorted(str(r) for r in ws.merged_cells.ranges), + "autoFilter": ws.auto_filter.ref, + "freeze": ws.freeze_panes, + "view": { + "tabSelected": bool(sv.tabSelected), "rightToLeft": bool(sv.rightToLeft), "zoomScale": sv.zoomScale, + "showGridLines": sv.showGridLines, "showRowColHeaders": sv.showRowColHeaders, + "pane": {"xSplit": pane.xSplit, "ySplit": pane.ySplit, "topLeftCell": pane.topLeftCell, "activePane": pane.activePane, "state": pane.state} if pane else None, + "selection": [{"pane": x.pane, "activeCell": x.activeCell, "sqref": str(x.sqref)} for x in sv.selection], + }, + "tabColor": color(props.tabColor), + "fitToPage": bool(props.pageSetUpPr.fitToPage) if props.pageSetUpPr else False, + "format": { + "defaultColWidth": fmt.defaultColWidth, "defaultRowHeight": fmt.defaultRowHeight, "customHeight": bool(fmt.customHeight), + "outlineLevelRow": fmt.outlineLevelRow, "outlineLevelCol": fmt.outlineLevelCol, + }, + "hyperlinks": { + c.coordinate: {"target": c.hyperlink.target, "location": c.hyperlink.location, "tooltip": c.hyperlink.tooltip} + for row in ws.iter_rows() for c in row if c.hyperlink is not None + }, + "pageSetup": {"orientation": ps.orientation, "paperSize": ps.paperSize, "scale": ps.scale, "fitToWidth": ps.fitToWidth, "fitToHeight": ps.fitToHeight}, + "printOptions": {"horizontalCentered": bool(po.horizontalCentered), "verticalCentered": bool(po.verticalCentered), "headings": bool(po.headings), "gridLines": bool(po.gridLines)}, + "margins": {k: getattr(pm, k) for k in ("left", "right", "top", "bottom", "header", "footer")}, + "headerFooter": { + "oddHeader": hf_part(hf.oddHeader), "oddFooter": hf_part(hf.oddFooter), "evenHeader": hf_part(hf.evenHeader), + "firstFooter": hf_part(hf.firstFooter), "differentOddEven": bool(hf.differentOddEven), "differentFirst": bool(hf.differentFirst), + }, + "printArea": ws.print_area, + "printTitleRows": ws.print_title_rows, + "printTitleCols": ws.print_title_cols, + "definedNames": {n: {"ref": d.attr_text, "hidden": bool(d.hidden)} for n, d in ws.defined_names.items()}, + } + + +def iso(d): + return d.isoformat() if d else None + + +def main(path, values_only=False): + wb = openpyxl.load_workbook(path, rich_text=True) + cached = openpyxl.load_workbook(path, data_only=True) + props = wb.properties + out = { + "sheets": [{"title": ws.title, "state": ws.sheet_state} for ws in wb.worksheets], + "active": wb.index(wb.active), + "epoch1904": wb.epoch == openpyxl.utils.datetime.MAC_EPOCH, + "properties": { + "title": props.title, + "subject": props.subject, + "creator": props.creator, + "keywords": props.keywords, + "description": props.description, + "lastModifiedBy": props.lastModifiedBy, + "category": props.category, + "created": iso(props.created), + "modified": iso(props.modified), + }, + "custom": [{"name": p.name, "value": value(p.value)} for p in wb.custom_doc_props.props], + "cellXfCount": len(wb._cell_styles), + "definedNames": {n: {"ref": d.attr_text, "hidden": bool(d.hidden), "comment": d.comment} for n, d in wb.defined_names.items()}, + "sheetInfo": {ws.title: sheet_info(ws) for ws in wb.worksheets}, + "cells": {}, + } + for ws in wb.worksheets: + cws = cached[ws.title] + cells = {} + for row in ws.iter_rows(): + for c in row: + if c.value is None and not c.has_style: + continue + if values_only: + cells[c.coordinate] = {"value": value(c.value)} + continue + cells[c.coordinate] = { + "value": value(c.value), + "cached": value(cws[c.coordinate].value), + "dataType": c.data_type, + "numFmt": c.number_format, + "font": font(c.font), + "fill": fill(c.fill), + "border": border(c.border), + "alignment": alignment(c.alignment), + "protection": {"locked": c.protection.locked, "hidden": c.protection.hidden}, + } + out["cells"][ws.title] = cells + print(json.dumps(out)) + + +if __name__ == "__main__": + main(sys.argv[1], len(sys.argv) > 2 and sys.argv[2] == "values") diff --git a/packages/react-data-export/test/conformance/to-spec.ts b/packages/react-data-export/test/conformance/to-spec.ts new file mode 100644 index 0000000..9430278 --- /dev/null +++ b/packages/react-data-export/test/conformance/to-spec.ts @@ -0,0 +1,227 @@ +// Turns a javascript-excel Workbook (a conformance corpus entry) into the +// input of react-data-export's public API: a WorkbookSpec of datasets plus +// ExportOptions. Whatever the API has no way to say is reported, not +// approximated, so the conformance test can check that everything else comes +// out exactly as javascript-excel writes it. +import { fromDataset, fromDatasets, mergeStyles, type CellInput, type ColumnProps, type Dataset, type LeafColumn, type Sheet, type Style, type Workbook, type WriteOptions } from 'javascript-excel'; +import type { ExportOptions, SheetSpec, WorkbookSpec } from '../../src/index'; + +/** A model feature the React API cannot express, e.g. 'merges' or 'colProps.style'. */ +export type Lost = string; + +export interface Converted { + spec: WorkbookSpec; + options: ExportOptions; + /** Features of the input the spec leaves out (sorted, unique). */ + lost: Lost[]; + /** The same, for the workbook itself and for each sheet. */ + workbookLost: Lost[]; + sheetLost: Lost[][]; +} + +type Row = Array | undefined; + +/** + * `width: 'auto'` is measured by fromDataset, which writes the measured width. + * javascript-excel's writer, given 'auto', writes the same width and also + * marks the column bestFit. + */ +export const AUTO: Lost = "colProps.width: 'auto' (bestFit)"; + +const isEmpty = (row: Row): boolean => !row || !row.some((c) => c !== undefined); + +/** Defined, and a string or a plain cell object: usable as a column title. */ +function isTitle(c: CellInput | undefined): boolean { + if (typeof c === 'string') return true; + return typeof c === 'object' && c !== null && !(c instanceof Date) && !('error' in c) && !('richText' in c) && typeof c.value === 'string'; +} + +/** + * A column picked by `index`. A column style becomes the dataset column's + * `style` (and `headerStyle`), which is how javascript-excel's writer applies + * it to the column's cells: the column style, then the cell's own style. + */ +function leaf(index: number, colProps: ColumnProps | undefined, header?: { title: CellInput }): LeafColumn { + const col: LeafColumn = { index }; + if (colProps?.width !== undefined) col.width = colProps.width; + if (colProps?.hidden) col.hidden = true; + if (colProps?.style) col.style = colProps.style; + if (header) { + col.title = header.title as LeafColumn['title']; + if (colProps?.style) col.headerStyle = colProps.style; + } + return col; +} + +/** + * One sheet. Two shapes, both through fromDataset/fromDatasets: + * + * - **Header + freeze.** A sheet frozen below row 1 whose first row holds a + * title (text) in every column is a dataset with that row as its header + * (`headerStyle: {}`, so the titles keep exactly their own style) and + * `freezeHeader`. + * - **Blocks.** Otherwise each run of non-empty rows becomes one headerless + * block (`header: false`, array rows picked by `index`), placed with + * `offset`. A sheet with one cell at XFD1048576 then needs no 16,384 + * columns over every row. + */ +function sheetSpec(sheet: Sheet, lost: Set): SheetSpec { + const { name, rows, colProps, rowProps, view, autoFilter, ...rest } = sheet; + for (const [k, v] of Object.entries(rest)) if (v !== undefined) lost.add(k); + // A column style goes onto the column's cells (see leaf), but the column itself is lost. + // Row styles are not used at all: `rowStyle` would also style the row's empty cells. + colProps?.forEach((p) => { + for (const [k, v] of Object.entries(p ?? {})) if (v !== undefined && k !== 'width' && k !== 'hidden') lost.add(`colProps.${k}`); + if (p?.width === 'auto') lost.add(AUTO); + }); + rowProps?.forEach((p) => { + for (const [k, v] of Object.entries(p ?? {})) if (v !== undefined) lost.add(`rowProps.${k}`); + }); + + const { freeze, rightToLeft, ...viewRest } = view ?? {}; + for (const [k, v] of Object.entries(viewRest)) if (v !== undefined) lost.add(`view.${k}`); + + const width = rows.reduce((m, r) => Math.max(m, r?.length ?? 0), 0); + const first = rows[0]; + const headerFreeze = + freeze !== undefined && freeze.rows === 1 && !freeze.cols && first !== undefined && first.length === width && Array.from(first).every(isTitle); + if (freeze !== undefined && !headerFreeze) lost.add('view.freeze'); + const common = { name, ...(rightToLeft ? { rightToLeft: true } : {}) }; + + if (headerFreeze) { + const columns = Array.from({ length: width }, (_, i) => leaf(i, colProps?.[i], { title: first[i] })); + const data = rows.slice(1); + const spec: SheetSpec = { ...common, columns, data, headerStyle: {}, freezeHeader: true }; + // fromDataset's filter covers the header row and the data rows. + if (autoFilter !== undefined) { + if (autoFilter === `A1:${columnName(width - 1)}${rows.length}`) spec.autoFilter = true; + else lost.add('autoFilter'); + } + return spec; + } + if (autoFilter !== undefined) lost.add('autoFilter'); + + // Runs of non-empty rows, each with its first and last used column. + const runs: Array<{ top: number; rows: Row[]; left: number; right: number }> = []; + let run: (typeof runs)[number] | undefined; + for (let r = 0; r < rows.length; r++) { + const row = rows[r]; + if (isEmpty(row)) { + run = undefined; + continue; + } + const used = (row as Array).flatMap((c, i) => (c === undefined ? [] : [i])); + if (!run) runs.push((run = { top: r, rows: [], left: Infinity, right: -1 })); + run.rows.push(row); + run.left = Math.min(run.left, used[0]!); + run.right = Math.max(run.right, used[used.length - 1]!); + } + // Column widths and hidden flags are properties of a block's columns, so the + // first block spans every column that has one (extra columns stay empty). + const propCols = (colProps ?? []).flatMap((p, c) => (p?.width !== undefined || p?.hidden ? [c] : [])); + if (runs[0] && propCols.length) { + runs[0].left = Math.min(runs[0].left, propCols[0]!); + runs[0].right = Math.max(runs[0].right, propCols[propCols.length - 1]!); + } + const placed = new Set(); + let bottom = -1; + const blocks = runs.map((b) => { + const columns = Array.from({ length: b.right - b.left + 1 }, (_, i) => { + const c = b.left + i; + const props = placed.has(c) ? undefined : colProps?.[c]; + placed.add(c); + return leaf(c, props); + }); + const block: Dataset & { offset: { rows: number; cols: number } } = { + columns, + data: b.rows, + offset: { rows: b.top - bottom - 1, cols: b.left }, + }; + bottom = b.top + b.rows.length - 1; + return block; + }); + colProps?.forEach((p, c) => { + if (!placed.has(c) && (p?.width !== undefined || p?.hidden)) lost.add('colProps (column outside the data)'); + }); + if (blocks.length === 0) return { ...common, columns: [], data: [], header: false }; + return { ...common, blocks, header: false }; +} + +function columnName(c: number): string { + let s = ''; + for (let n = c + 1; n > 0; n = Math.floor((n - 1) / 26)) s = String.fromCharCode(65 + ((n - 1) % 26)) + s; + return s; +} + +/** The React API's input for `workbook`, written with `write`. */ +export function toSpec(workbook: Workbook, write?: WriteOptions): Converted { + const workbookLost = new Set(); + const { sheets, activeSheet, properties, ...rest } = workbook; + for (const [k, v] of Object.entries(rest)) if (v !== undefined) workbookLost.add(k); + const sheetLost = sheets.map(() => new Set()); + const spec: WorkbookSpec = { sheets: sheets.map((s, i) => sheetSpec(s, sheetLost[i]!)) }; + if (activeSheet !== undefined) spec.activeSheet = activeSheet; + const options: ExportOptions = { download: false }; + if (properties !== undefined) options.properties = properties; + if (write !== undefined) options.write = write; + const lost = new Set([...workbookLost, ...sheetLost.flatMap((l) => [...l])]); + return { spec, options, lost: [...lost].sort(), workbookLost: [...workbookLost], sheetLost: sheetLost.map((l) => [...l]) }; +} + +const isCell = (c: CellInput): c is Exclude & { value?: unknown; style?: Style } => + typeof c === 'object' && c !== null && !(c instanceof Date) && !('error' in c) && !('richText' in c); + +/** + * The same workbook without the features in `lost`: what the React API's file + * is compared with. A column style is not dropped from the cells: the writer + * applies it to every cell of the column (before the cell's own style), and so + * does the spec (see leaf), so here it moves onto the cells. Only the empty + * cells lose it. + */ +export function withoutLost(workbook: Workbook, converted: Converted): Workbook { + const wb: Record = { ...workbook }; + for (const k of converted.workbookLost) delete wb[k]; + wb['sheets'] = workbook.sheets.map((s, i) => { + const drop = new Set(converted.sheetLost[i]); + const sheet: Record = { ...s }; + if (drop.has(AUTO)) { + // The width fromDataset measured for the spec's sheet. + drop.delete(AUTO); + const spec = converted.spec.sheets[i] as SheetSpec; + const built = 'blocks' in spec ? fromDatasets(spec.blocks, spec) : fromDataset(spec, spec); + sheet['colProps'] = s.colProps?.map((p, c) => (p?.width === 'auto' ? { ...p, width: built.colProps?.[c]?.width } : p)); + } + for (const k of drop) if (!k.includes('.')) delete sheet[k]; + // A row style is dropped with the cells' share of it; a column style stays on the cells. + if (drop.has('colProps.style')) { + sheet['rows'] = s.rows.map((row) => + row?.map((c, col) => { + if (c === undefined || c === null) return c; + const style = mergeStyles(s.colProps?.[col]?.style, isCell(c) ? c.style : undefined); + if (!Object.keys(style).length) return c; + return isCell(c) ? { ...c, style } : { value: c, style }; + }), + ); + } + for (const list of ['colProps', 'rowProps'] as const) { + const fields = [...drop].filter((k) => k.startsWith(`${list}.`)).map((k) => k.slice(list.length + 1)); + const current = sheet[list] as Array | undefined; + if (!fields.length || !current) continue; + const kept = current.map((p) => { + if (!p) return p; + const q: Record = { ...p }; + for (const f of fields) delete q[f]; + return Object.keys(q).length ? q : undefined; + }); + sheet[list] = kept.some((p) => p !== undefined) ? kept : undefined; + } + const viewFields = [...drop].filter((k) => k.startsWith('view.')).map((k) => k.slice(5)); + if (viewFields.length && s.view) { + const view: Record = { ...s.view }; + for (const f of viewFields) delete view[f]; + sheet['view'] = Object.keys(view).length ? view : undefined; + } + return sheet; + }); + return wb as unknown as Workbook; +} diff --git a/scripts/sync-jse-corpus.mjs b/scripts/sync-jse-corpus.mjs new file mode 100644 index 0000000..3499b07 --- /dev/null +++ b/scripts/sync-jse-corpus.mjs @@ -0,0 +1,71 @@ +// Copies javascript-excel's conformance corpus (JSE-9) into this repository, +// so react-data-export's conformance tests run the same workbooks through its +// public API (packages/react-data-export/test/conformance/). +// +// The corpus is not part of the javascript-excel npm package, so it is taken +// from the git tag of the installed version: the files always describe the +// engine the tests run against. The files don't name the version, so an +// upgrade that leaves the corpus unchanged needs no new copy. +// +// node scripts/sync-jse-corpus.mjs write the files for the installed version +// node scripts/sync-jse-corpus.mjs --check fail if they differ from that version's files +// +// Only Node built-ins (fetch needs network access to raw.githubusercontent.com). +import { readFileSync, writeFileSync } from 'node:fs'; +import { createRequire } from 'node:module'; +import { join, resolve } from 'node:path'; +import { fileURLToPath } from 'node:url'; + +const root = resolve(fileURLToPath(new URL('.', import.meta.url)), '..'); +const out = join(root, 'packages/react-data-export/test/conformance/jse'); +const check = process.argv.includes('--check'); + +const require = createRequire(join(root, 'packages/react-data-export/package.json')); +const { version } = JSON.parse(readFileSync(require.resolve('javascript-excel/package.json'), 'utf8')); +const tag = `v${version}`; +const base = `https://raw.githubusercontent.com/securedeveloper/javascript-excel/${tag}/packages/javascript-excel/test`; + +const FILES = [ + { + from: 'conformance/corpus.ts', + to: 'corpus.ts', + // The corpus imports the engine's sources; here it uses the installed package. + transform: (text) => { + const replaced = text.replace(/from "\.\.\/\.\.\/src\/index";/g, 'from "javascript-excel";'); + if (replaced === text) throw new Error('corpus.ts: the import of ../../src/index was not found; update this script'); + return `// Generated by scripts/sync-jse-corpus.mjs from javascript-excel's tag for the\n// installed version (packages/javascript-excel/test/conformance/corpus.ts). Do not edit.\n${replaced}`; + }, + }, + { + from: 'interop/xlsx_dump.py', + to: 'xlsx_dump.py', + transform: (text) => `# Generated by scripts/sync-jse-corpus.mjs from javascript-excel's tag for the\n# installed version (packages/javascript-excel/test/interop/xlsx_dump.py). Do not edit.\n${text}`, + }, +]; + +let stale = 0; +for (const f of FILES) { + const res = await fetch(`${base}/${f.from}`); + if (!res.ok) throw new Error(`${base}/${f.from}: HTTP ${res.status}`); + const want = f.transform(await res.text()); + const path = join(out, f.to); + let have; + try { + have = readFileSync(path, 'utf8'); + } catch { + have = undefined; + } + if (have === want) continue; + if (check) { + stale++; + console.error(`${f.to} differs from javascript-excel ${tag}`); + } else { + writeFileSync(path, want); + console.log(`wrote ${f.to} (javascript-excel ${tag})`); + } +} +if (stale) { + console.error(`run: npm run conformance:sync`); + process.exit(1); +} +if (check) console.log(`ok the conformance corpus matches javascript-excel ${tag}`);