Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 26 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
1 change: 1 addition & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
70 changes: 70 additions & 0 deletions docs/conformance.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
# Conformance: javascript-excel’s corpus through the React API

<!-- Generated from packages/react-data-export/test/conformance/expressible.ts by `npm run conformance:doc`. Do not edit by hand. -->

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 `<ExcelExport>`, byte-identical to javascript-excel’s file.
- **Table export:** javascript-excel’s table golden case (`fromTable`) through `exportTable`, `useTableExport` and `<ExportTableButton>` 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. |
3 changes: 2 additions & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
1 change: 1 addition & 0 deletions packages/react-data-export/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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": {
Expand Down
159 changes: 159 additions & 0 deletions packages/react-data-export/test/conformance/conformance.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,159 @@
/// <reference types="node" />
// 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<Uint8Array> => 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<string, Promise<Pair>>();
function pair(entry: CorpusEntry): Promise<Pair> {
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<unknown>;
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);
});
});
});
Loading
Loading