From 138b790bab1f4e6480a10cc13a7f6b652c8756a8 Mon Sep 17 00:00:00 2001 From: Afzal Ahmad Date: Thu, 19 Nov 2026 22:49:34 +0100 Subject: [PATCH 1/2] Require javascript-excel ^2.0.0 javascript-excel 2.0.0 is on latest; move the dependency range off the prerelease line and relock. --- .changeset/engine-2-0-0.md | 5 +++++ README.md | 2 +- apps/playground/package.json | 2 +- docs/api.md | 8 ++++---- docs/triage-1.0.md | 2 +- package-lock.json | 10 +++++----- packages/react-data-export/package.json | 2 +- 7 files changed, 18 insertions(+), 13 deletions(-) create mode 100644 .changeset/engine-2-0-0.md diff --git a/.changeset/engine-2-0-0.md b/.changeset/engine-2-0-0.md new file mode 100644 index 0000000..9e56c39 --- /dev/null +++ b/.changeset/engine-2-0-0.md @@ -0,0 +1,5 @@ +--- +"react-data-export": patch +--- + +Require javascript-excel `^2.0.0`, the stable release (was a 2.0.0 prerelease range). diff --git a/README.md b/README.md index 2a4b41e..f4570ba 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ Export data from React to `.xlsx` and `.csv`. - **1.0 has a new API.** It is rebuilt on [javascript-excel](https://github.com/securedeveloper/javascript-excel) 2.0, and its main entry has no `` / `` / ``. The 0.6 API ships only as the deprecated `react-data-export/legacy` entry: supported for all of 1.x, removed in 2.0. See [Migrating from 0.x](#migrating-from-0x). - **1.0 prereleases are on npm's `next` tag:** `npm install react-data-export@next`. They have dataset export (`exportDataset`, `exportWorkbook`, `useExcelExport`, ``) and table export for an HTML `` (`exportTable`, `useTableExport`, ``), as specified in [docs/api.md](docs/api.md), built on javascript-excel 2.0's `fromDataset`, `fromTable`, writer and download. The 1.0 feature set is complete: until 1.0.0, changes are limited to fixes found in testing. Coming from 0.x: the [migration guide](docs/migration.md). -- **Big exports stay responsive.** Exports run on the main thread. Since javascript-excel 2.0.0-alpha.7 (react-data-export requires 2.0.0-beta.0 or later), the `.xlsx` writer returns to the event loop about every 16 ms, so the page keeps rendering and handling input during a large export, and `abort()` works while it runs. A `worker` option, which writes the file in a Web Worker on top of `javascript-excel/worker`, comes in a 1.x release after 1.0.0, not in 1.0 ([docs/api.md §7](docs/api.md#7-errors-abort-and-progress)). +- **Big exports stay responsive.** Exports run on the main thread. Since javascript-excel 2.0.0-alpha.7 (react-data-export requires 2.0.0 or later), the `.xlsx` writer returns to the event loop about every 16 ms, so the page keeps rendering and handling input during a large export, and `abort()` works while it runs. A `worker` option, which writes the file in a Web Worker on top of `javascript-excel/worker`, comes in a 1.x release after 1.0.0, not in 1.0 ([docs/api.md §7](docs/api.md#7-errors-abort-and-progress)). ```tsx import { ExcelExport } from 'react-data-export'; diff --git a/apps/playground/package.json b/apps/playground/package.json index 737d072..212c9e4 100644 --- a/apps/playground/package.json +++ b/apps/playground/package.json @@ -10,7 +10,7 @@ "test": "vitest run" }, "dependencies": { - "javascript-excel": "^2.0.0-beta.0", + "javascript-excel": "^2.0.0", "react": "^19.3.1", "react-data-export": "1.0.0-beta.0", "react-dom": "^19.3.1" diff --git a/docs/api.md b/docs/api.md index ebbcb3d..f3c652e 100644 --- a/docs/api.md +++ b/docs/api.md @@ -1,6 +1,6 @@ # react-data-export 1.0: API design (dataset module) -Status: **design decided (2026-11-16); the dataset module is implemented** (RDE-1.9) on **javascript-excel ≥ 2.0.0-beta.0** (see [§9](#9-dependencies-and-order)), and ships in the 1.0 prereleases on npm's `next` tag. The 1.0 feature set is complete: until 1.0.0, changes are limited to fixes found in testing. Table export (module B, [§13](#13-table-export)) is designed and implemented in RDE-1.17. +Status: **design decided (2026-11-16); the dataset module is implemented** (RDE-1.9) on **javascript-excel ≥ 2.0.0** (see [§9](#9-dependencies-and-order)), and ships in the 1.0 prereleases on npm's `next` tag. The 1.0 feature set is complete: until 1.0.0, changes are limited to fixes found in testing. Table export (module B, [§13](#13-table-export)) is designed and implemented in RDE-1.17. This document covers module A, **dataset export** (`exportDataset`, `exportWorkbook`, `useExcelExport`, ``), and module B, **table export** (`exportTable`, `useTableExport`, ``, [§13](#13-table-export)). @@ -263,7 +263,7 @@ export function ExcelExport(props: ExcelExportProps): ReactElement; - react-data-export's own misuse errors (CSV with several sheets, `dataset` and `workbook` both or neither, an unknown `format`) are `TypeError`s. That's how javascript-excel treats invalid options too. - **Abort.** `signal` reaches `toBlob`, which checks it between sheet chunks. It is also checked before building and before the download starts. Every export starts by yielding once (one microtask) and re-checking the signal before it builds anything. `toCsvBlob` is synchronous, so without that yield a CSV export started in an effect would finish, download included, before React 18/19 StrictMode's simulated unmount could abort it, and the documented auto-export recipe would save the file twice in development. An abort rejects with `signal.reason` (a `DOMException` `AbortError` by default). `toCsvBlob` is synchronous, so a CSV export can only be aborted before it starts. - **Progress.** `onProgress` receives javascript-excel's `Progress` (`phase`, `sheet`, `ratio` from 0 to 1, non-decreasing) from `toBlob`. The building phase (`fromDataset`) is synchronous and reports nothing, so the first progress event comes from the writer. CSV reports no progress. -- **Big data: the main thread stays responsive.** In 1.0, exports run on the main thread. From javascript-excel 2.0.0-alpha.7 (react-data-export depends on 2.0.0-beta.0 or later, §9), `toBlob` returns to the event loop about every 16 ms while it writes. So a large `.xlsx` export doesn't freeze the page: frames render, input is handled, and `abort()` or an aborted `signal` takes effect while the file is being written. The output bytes are the same as without the pauses. Building the sheet (`fromDataset`, `fromTable`) and writing CSV (`toCsvBlob`) are still synchronous. +- **Big data: the main thread stays responsive.** In 1.0, exports run on the main thread. From javascript-excel 2.0.0-alpha.7 (react-data-export depends on 2.0.0 or later, §9), `toBlob` returns to the event loop about every 16 ms while it writes. So a large `.xlsx` export doesn't freeze the page: frames render, input is handled, and `abort()` or an aborted `signal` takes effect while the file is being written. The output bytes are the same as without the pauses. Building the sheet (`fromDataset`, `fromTable`) and writing CSV (`toCsvBlob`) are still synchronous. - **Worker: 1.x, not 1.0** (decided 2026-11-17). javascript-excel's worker entry, `javascript-excel/worker` (its §5.5), has existed since 2.0.0-alpha.1. react-data-export adds it after 1.0.0, in a 1.x minor release: - `fromDataset` and `fromTable` have to run on the main thread: accessors are functions and can't be sent to a worker, and the table is in the page. - The resulting sheet is plain data, and can be written in a worker. @@ -291,7 +291,7 @@ export function ExcelExport(props: ExcelExportProps): ReactElement; | `toBlob` returning to the event loop while it writes (§7) | core entry, §5.1 | 2.0.0-alpha.7 | | `WorkerClient` (1.x only, §7) | `javascript-excel/worker`, §5.5 | 2.0.0-alpha.1 (JSE-8) | -So react-data-export depends on `"javascript-excel": "^2.0.0-beta.0"` ([Q6](#12-design-decisions)), the first 2.0.0 beta. 2.0.0-alpha.2 was the first prerelease with `fromDataset`/`fromDatasets`, and 2.0.0-alpha.7 the first whose writer yields to the browser. Nothing in react-data-export reimplements them. +So react-data-export depends on `"javascript-excel": "^2.0.0"` ([Q6](#12-design-decisions)), the stable 2.0 release. 2.0.0-alpha.2 was the first prerelease with `fromDataset`/`fromDatasets`, and 2.0.0-alpha.7 the first whose writer yields to the browser. Nothing in react-data-export reimplements them. ## 10. Feature coverage @@ -341,7 +341,7 @@ These were the open questions of the review. Each one is decided, and the sectio **Q5. `` triggers.** Decided (2026-11-16): a default button or a render prop, with no `cloneElement` (§6). The 0.x-style `element` with an injected `onClick` is not carried over, because it breaks with components that don't forward `onClick` and with fragments. -**Q6. javascript-excel range during the 2.0 prereleases.** Decided (2026-11-16): a caret range on a prerelease, `"javascript-excel": "^2.0.0-alpha.2"` at the time and `^2.0.0-beta.0` now (§9). A caret on a prerelease matches only later 2.0.0 prereleases and 2.0.0 itself. An exact pin bumped with each alpha was not taken. +**Q6. javascript-excel range during the 2.0 prereleases.** Decided (2026-11-16): a caret range on a prerelease, `"javascript-excel": "^2.0.0-alpha.2"` at the time, then `^2.0.0-beta.0`, and `^2.0.0` since javascript-excel 2.0.0 shipped on 2026-11-19 (§9). A caret on a prerelease matches only later 2.0.0 prereleases and 2.0.0 itself. An exact pin bumped with each alpha was not taken. **Q7. Accessor fields.** Decided (2026-11-16): javascript-excel's `key` / `path` / `value` / `index` pass through unchanged (§3). That gives one documented shape for every framework and no ambiguity about `'a.b'`. A combined react-data-export field mapped to `key` or `path`, which javascript-excel's Q18 would allow, was not taken. diff --git a/docs/triage-1.0.md b/docs/triage-1.0.md index abd9523..4c93e39 100644 --- a/docs/triage-1.0.md +++ b/docs/triage-1.0.md @@ -218,7 +218,7 @@ Thanks to the community pull requests whose ideas shaped 1.0: | # | title | disposition | how / reason | |---|---|---|---| | #154 | The maximum you can export to excel is 1299 rows, how to increase the number of exported rows? | Fixed in 1.0.0-alpha.1 | Measured on alpha.1 (Node 24): 1,300 / 10,000 / 100,000 rows × 3 columns export and read back complete (100k rows: 318 ms, 2.1 MB). | -| #170 | Browser window stops responding | Still open, tracked | From javascript-excel 2.0.0-alpha.7 (react-data-export requires 2.0.0-beta.0 or later), the writer returns to the event loop about every 16 ms, so a large export on the main thread no longer freezes the page. The `worker` option (`javascript-excel/worker`) lands in react-data-export 1.x, not 1.0 (decided 2026-11-17). Keep open until the worker option ships. | +| #170 | Browser window stops responding | Still open, tracked | From javascript-excel 2.0.0-alpha.7 (react-data-export requires 2.0.0 or later), the writer returns to the event loop about every 16 ms, so a large export on the main thread no longer freezes the page. The `worker` option (`javascript-excel/worker`) lands in react-data-export 1.x, not 1.0 (decided 2026-11-17). Keep open until the worker option ships. | ### Out of scope for 1.0 diff --git a/package-lock.json b/package-lock.json index 34b8a86..6f956fb 100644 --- a/package-lock.json +++ b/package-lock.json @@ -21,7 +21,7 @@ }, "apps/playground": { "dependencies": { - "javascript-excel": "^2.0.0-beta.0", + "javascript-excel": "^2.0.0", "react": "^19.3.1", "react-data-export": "1.0.0-beta.0", "react-dom": "^19.3.1" @@ -2188,9 +2188,9 @@ "license": "MIT" }, "node_modules/javascript-excel": { - "version": "2.0.0-beta.0", - "resolved": "https://registry.npmjs.org/javascript-excel/-/javascript-excel-2.0.0-beta.0.tgz", - "integrity": "sha512-TYYjCNaG/qWaUV6TS3yDMWn/awxxH722sX6Hr67XmFrJaasf2w/VQO/2BsBvwfG0KXuGTal0dUdg2hN/UqSezg==", + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/javascript-excel/-/javascript-excel-2.0.0.tgz", + "integrity": "sha512-17pEDs03BnndbmC3Buj7LEd/xu4LwJMkTtzgDmeWKhDlhdmyBJSNw4h0vx2fk8en5AhXSy3Ue29dGlezIiOSbQ==", "license": "MIT", "engines": { "node": ">=22" @@ -4156,7 +4156,7 @@ "version": "1.0.0-beta.0", "license": "MIT", "dependencies": { - "javascript-excel": "^2.0.0-beta.0" + "javascript-excel": "^2.0.0" }, "devDependencies": { "@arethetypeswrong/cli": "^0.18.5", diff --git a/packages/react-data-export/package.json b/packages/react-data-export/package.json index 3f13c25..3f25473 100644 --- a/packages/react-data-export/package.json +++ b/packages/react-data-export/package.json @@ -80,6 +80,6 @@ "vitest": "^5.1.0" }, "dependencies": { - "javascript-excel": "^2.0.0-beta.0" + "javascript-excel": "^2.0.0" } } From 3f51bea1b1b7d2c20e9a2c12e741a68ab9e3a60d Mon Sep 17 00:00:00 2001 From: Afzal Ahmad Date: Thu, 19 Nov 2026 22:52:41 +0100 Subject: [PATCH 2/2] Sync the conformance corpus to javascript-excel v2.0.0 --- .../test/conformance/jse/corpus.ts | 28 ++++++++++++++----- 1 file changed, 21 insertions(+), 7 deletions(-) diff --git a/packages/react-data-export/test/conformance/jse/corpus.ts b/packages/react-data-export/test/conformance/jse/corpus.ts index 52988e8..db921d9 100644 --- a/packages/react-data-export/test/conformance/jse/corpus.ts +++ b/packages/react-data-export/test/conformance/jse/corpus.ts @@ -19,8 +19,17 @@ export interface Check { expect: string; /** The docs/api.md `[to verify]` item this check resolves, if any. */ verifies?: string; + /** For an open item: what the manual check found (see MANUAL_CHECK). */ + result?: string; } +/** The manual check that was done: who, where and when. */ +export const MANUAL_CHECK = { + date: "2026-11-17", + checked: ["Excel for Mac"], + notChecked: ["Excel for Windows", "Apple Numbers"], +} as const; + export interface CorpusEntry { /** File name without extension. */ id: string; @@ -81,9 +90,9 @@ const BUILTIN: Array<[number, string, number | Date]> = [ [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], + [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, "mm:ss.0", 0.0215278], [48, "##0.0E+0", 12345.678], [49, "@ (text)", 1234.5678], ]; export const CORPUS: CorpusEntry[] = [ @@ -330,7 +339,7 @@ export const CORPUS: CorpusEntry[] = [ }, 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)" }, + { 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)", result: "Confirmed: the cell shows indent 250 and Excel refuses 251." }, ], }, { @@ -379,9 +388,9 @@ export const CORPUS: CorpusEntry[] = [ ], }), 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: "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)", result: "Confirmed, with Excel's own codes: 37 `#,##0_);(#,##0)`, 38 `#,##0_);[Red](#,##0)`, 39 `#,##0.00_);(#,##0.00)`, 40 `#,##0.00_);[Red](#,##0.00)`, 47 `mm:ss.0`. These are the codes copied from Format Cells, and they are the record. Column B then held the ECMA-376 codes (`#,##0 ;(#,##0)`, `#,##0 ;[Red](#,##0)`, `#,##0.00;(#,##0.00)`, `#,##0.00;[Red](#,##0.00)`, `mmss.0`), so the separate answer that the codes matched column B is not relied on. Column B, `BUILTIN_NUM_FMTS` and docs/api.md §11.2 now use Excel's codes." }, { 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)" }, + { 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)", result: "Not verified: no result was reported for the Display sheet." }, ], }, { @@ -411,6 +420,7 @@ export const CORPUS: CorpusEntry[] = [ 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)", + result: "Confirmed in de-DE: ids 27–36 and 50–58 display as dates, not General. Columns B and C showed different values with the same pattern, as expected in de-DE (locale separators and date order). Not verified: an East Asian locale (Japanese, Chinese) was not tried.", }, ], }, @@ -455,8 +465,9 @@ export const CORPUS: CorpusEntry[] = [ 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)", + result: "Confirmed: 0 Background 1, 1 Text 1, 2 Background 2, 3 Text 2, 4–9 Accent 1–6, 10 Hyperlink, 11 Followed Hyperlink.", }, - { 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)" }, + { 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)", result: "Confirmed: 64 is black, 65 is white." }, ], }, { @@ -504,6 +515,7 @@ export const CORPUS: CorpusEntry[] = [ 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)", + result: "Confirmed in characters: A 8.43, B 10, C 20, D 12, E 8.43, F 13.57. Pixel widths are Windows values and were not checked.", }, { 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." }, @@ -647,6 +659,7 @@ export const CORPUS: CorpusEntry[] = [ 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)", + result: "Confirmed: Excel accepts a name of 30 x's and 😀, 31 code points (32 UTF-16 units), so the limit counts code points. Excel refuses to rename a sheet to History (\"History is a reserve word\").", }, ], }, @@ -672,6 +685,7 @@ export const CORPUS: CorpusEntry[] = [ 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)", + result: "Confirmed: the file with 64,000 cell formats opens with no repair prompt, and Cmd+End goes to XFD1048576. A file over the limit was not tried.", }, ], },