From 66e3bc6758eae16cbb5fb14a988660635fcb01dd Mon Sep 17 00:00:00 2001 From: Afzal Ahmad Date: Mon, 16 Nov 2026 13:08:53 +0100 Subject: [PATCH 1/3] RDE-1.12: migration guide from 0.6 to 1.0 docs/migration.md shows every 0.x pattern next to its 1.0 code (ExcelFile + ExcelSheet + ExcelColumn, dataSet, xSteps/ySteps, hideElement, element, fileExtension, xlsx-style styles with a converter) and lists the intentional behaviour differences, checked against the v0.6.0 source. Every 1.0 snippet is a type-checked file in examples/migration; docs:check keeps the Markdown blocks identical to the files. README gains a Migrating from 0.x section. --- .github/workflows/ci.yml | 6 +- README.md | 48 +- docs/migration.md | 670 ++++++++++++++++++++++ examples/migration/auto-download.tsx | 25 + examples/migration/custom-trigger.tsx | 27 + examples/migration/file-formats.ts | 30 + examples/migration/legacy-style.ts | 106 ++++ examples/migration/like-0x.ts | 23 + examples/migration/readme.tsx | 20 + examples/migration/sheets-and-columns.tsx | 54 ++ examples/migration/stacked-blocks.tsx | 39 ++ examples/migration/styled-dataset.tsx | 31 + examples/migration/tsconfig.json | 12 + package.json | 3 +- packages/react-data-export/README.md | 2 +- scripts/check-doc-snippets.mjs | 52 ++ 16 files changed, 1144 insertions(+), 4 deletions(-) create mode 100644 docs/migration.md create mode 100644 examples/migration/auto-download.tsx create mode 100644 examples/migration/custom-trigger.tsx create mode 100644 examples/migration/file-formats.ts create mode 100644 examples/migration/legacy-style.ts create mode 100644 examples/migration/like-0x.ts create mode 100644 examples/migration/readme.tsx create mode 100644 examples/migration/sheets-and-columns.tsx create mode 100644 examples/migration/stacked-blocks.tsx create mode 100644 examples/migration/styled-dataset.tsx create mode 100644 examples/migration/tsconfig.json create mode 100644 scripts/check-doc-snippets.mjs diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 364098e..e961510 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -46,10 +46,14 @@ jobs: - name: Resolved versions run: node scripts/print-versions.mjs - - name: Typecheck (library + playground) + - name: Typecheck (library + playground + docs examples) if: matrix.react == 19 run: npm run typecheck + - name: Code in the README and docs matches examples/ + if: matrix.react == 19 + run: npm run docs:check + - name: Typecheck (library) if: matrix.react != 19 run: npm run typecheck -w react-data-export diff --git a/README.md b/README.md index a9cc82e..fbb1166 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ Export data from React to `.xlsx` and `.csv`. ## Status: 1.0 is a from-scratch rewrite, in progress -- **1.0 is a clean break.** It is being rebuilt on [javascript-excel](https://github.com/securedeveloper/javascript-excel) 2.0 and will not ship the 0.x `` / `` / `` API. A migration guide will come with the first beta. +- **1.0 is a clean break.** It is being rebuilt on [javascript-excel](https://github.com/securedeveloper/javascript-excel) 2.0 and will not ship the 0.x `` / `` / `` API. See [Migrating from 0.x](#migrating-from-0x). - **The dataset module is on `main`, not yet on npm:** `exportDataset`, `exportWorkbook`, `useExcelExport` and ``, as specified in [docs/api.md](docs/api.md). They are built on javascript-excel 2.0's `fromDataset`, writer and download. Table export comes later, and the first 1.0 prerelease will be announced in this README. ```tsx @@ -22,6 +22,52 @@ Export data from React to `.xlsx` and `.csv`. - **0.6.x stays on npm unchanged.** `npm install react-data-export@0.6` keeps working; nothing is unpublished or deprecated. - **Legacy code and docs** (0.x README, examples, Babel/Jest setup) live at the [`v0.6.0` tag](https://github.com/securedeveloper/react-data-export/tree/v0.6.0). +## Migrating from 0.x + +The [migration guide](docs/migration.md) shows every 0.x pattern next to its 1.0 code: `ExcelFile` + `ExcelSheet` + `ExcelColumn`, `dataSet` with `xSteps`/`ySteps`, `hideElement`, `element`, `fileExtension`, and the xlsx-style cell styles (with a converter). It also lists every intentional behaviour difference. The most common change: + +```jsx +// 0.x +Download}> + + + col.is_married ? "Married" : "Single"}/> + + +``` + + +```tsx +// 1.0 +import { ExcelExport } from 'react-data-export'; + +const employees = [{ name: 'Monika', is_married: false }]; + +export const Download = () => ( + (row.is_married ? 'Married' : 'Single') }, + ], + data: employees, + }} + > + Download + +); +``` + +Things to know before you switch: +- `` headers are now bold, and 0.x's 80 px default column width is gone. +- Dates are written in local time; 0.x converted them as UTC. +- `fileExtension` is replaced by `format: 'xlsx' | 'csv'`. 0.6 saved an xlsx package even for `csv`, `txt`, `xls` and `html`. +- Styles use javascript-excel's keys (`font.size`, `fill: 'FF0000'`, …), and invalid values throw `INVALID_STYLE`. + +0.6.x stays on npm unchanged (`npm install react-data-export@0.6`) if you're not ready to move. + ## TypeScript support Types ship with the package (`.d.ts` for `import`, `.d.cts` for `require`). CI type-checks a consumer project against the packed tarball, in strict mode with `skipLibCheck: false`. diff --git a/docs/migration.md b/docs/migration.md new file mode 100644 index 0000000..09652c3 --- /dev/null +++ b/docs/migration.md @@ -0,0 +1,670 @@ +# Migrating from 0.6 to 1.0 + +react-data-export 1.0 is a rewrite on [javascript-excel](https://github.com/securedeveloper/javascript-excel) 2.0, and a clean break: the 0.x components ``, `` and `` are gone. This guide shows every 0.x pattern next to its 1.0 code, then lists the behaviour that changed on purpose. + +**You don't have to move now.** 0.6.x stays on npm unchanged: `npm install react-data-export@0.6` keeps working, and nothing is unpublished or deprecated. Its docs are at the [`v0.6.0` tag](https://github.com/securedeveloper/react-data-export/tree/v0.6.0). + +Every 1.0 snippet below is a file in [`examples/migration/`](../examples/migration), type-checked in CI against the library. The 0.x snippets are taken from the 0.6 README and examples. The exact 1.0 API is in [api.md](api.md). + +## Contents + +1. [Install and imports](#1-install-and-imports) +2. [Quick reference](#2-quick-reference) +3. [Side by side](#3-side-by-side) + - [3.1 `ExcelFile` + `ExcelSheet` + `ExcelColumn`](#31-excelfile--excelsheet--excelcolumn) + - [3.2 `dataSet`: array rows, styled cells, widths](#32-dataset-array-rows-styled-cells-widths) + - [3.3 `xSteps` / `ySteps`](#33-xsteps--ysteps) + - [3.4 `hideElement`](#34-hideelement) + - [3.5 `element`](#35-element) + - [3.6 `fileExtension` and `filename`](#36-fileextension-and-filename) + - [3.7 Cell styles](#37-cell-styles) +4. [Behaviour differences](#4-behaviour-differences) +5. [Not carried over](#5-not-carried-over) + +## 1. Install and imports + +```sh +npm uninstall file-saver tempa-xlsx # only if you added them for 0.x +npm install react-data-export@next # 1.0 prereleases go to the `next` tag; none is out yet +``` + +- **No peer libraries, no bundler setup.** 0.x needed `file-saver` and `tempa-xlsx`, and webpack settings for them (`node: { fs: 'empty' }`, `externals` for `./cptable` and `./jszip`). Delete those. 1.0's only dependency is javascript-excel, which has no dependencies of its own. +- **Named exports.** 0.x had a default export (`ReactExport.ExcelFile`, `ReactExport.ExcelFile.ExcelSheet`, …). 1.0 has named exports only: + + ```ts + import { ExcelExport, useExcelExport, exportDataset, exportWorkbook } from 'react-data-export'; + import type { Dataset, Style } from 'react-data-export'; + ``` +- **Types ship with the package**, generated from the source, so they match the code. The hand-written 0.x `types/index.d.ts` is gone. +- React 17, 18 and 19 are supported. Importing the package is safe during server rendering, and the entry is marked `"use client"`. + +## 2. Quick reference + +| 0.x | 1.0 | section | +|---|---|---| +| `` with `` children | ``, or `dataset={...}` for one sheet | [3.1](#31-excelfile--excelsheet--excelcolumn) | +| `` | a sheet: `{ name, columns, data }` | [3.1](#31-excelfile--excelsheet--excelcolumn) | +| `` | `{ title, key }` (`path` for nested properties) | [3.1](#31-excelfile--excelsheet--excelcolumn) | +| ` …}>` | `{ title, value: (row) => … }` | [3.1](#31-excelfile--excelsheet--excelcolumn) | +| `dataSet={[{ columns, data }]}` | `{ columns: [{ title }, …], data }`; array rows are read by position | [3.2](#32-dataset-array-rows-styled-cells-widths) | +| `columns: ['Name']` (strings) | `columns: [{ title: 'Name' }]` | [3.2](#32-dataset-array-rows-styled-cells-widths) | +| column `width: { wpx }` / `{ wch }` | the same, plus `'auto'` | [3.2](#32-dataset-array-rows-styled-cells-widths) | +| column `style` (header cell) | column `headerStyle`, or sheet `headerStyle` | [4](#4-behaviour-differences) | +| several `dataSet` entries, `xSteps`, `ySteps` | sheet `blocks`, `offset: { cols, rows }`, `gap: 0` | [3.3](#33-xsteps--ysteps) | +| `hideElement` | `useExcelExport` in a `useEffect` | [3.4](#34-hideelement) | +| `element={}` | children as the label, or a render prop | [3.5](#35-element) | +| `filename` (default `Download`) | `filename` (default `export`) | [3.6](#36-fileextension-and-filename) | +| `fileExtension="xlsx"` / `"csv"` | `format="xlsx"` / `"csv"` | [3.6](#36-fileextension-and-filename) | +| `fileExtension="txt"` / `"xls"` / `"html"` | CSV with a tab delimiter / `xlsx` / none | [3.6](#36-fileextension-and-filename) | +| cell `{ value, style }` | the same, with javascript-excel style keys | [3.7](#37-cell-styles) | +| `font.sz`, `fill.patternType`/`fgColor`, `alignment.textRotation` | `font.size`, `fill: 'RRGGBB'` or `{ pattern, fgColor }`, `alignment.rotation` | [3.7](#37-cell-styles) | + +## 3. Side by side + +### 3.1 `ExcelFile` + `ExcelSheet` + `ExcelColumn` + +**0.x** + +```jsx +import ReactExport from "react-data-export"; + +const ExcelFile = ReactExport.ExcelFile; +const ExcelSheet = ReactExport.ExcelFile.ExcelSheet; +const ExcelColumn = ReactExport.ExcelFile.ExcelColumn; + + + + + + + col.is_married ? "Married" : "Single"}/> + + + + + + + +``` + +**1.0** + + +```tsx +import { ExcelExport, type Dataset } from 'react-data-export'; + +interface Employee { + name: string; + amount: number; + sex: 'M' | 'F'; + is_married: boolean; +} +interface Leave { + name: string; + total: number; + remaining: number; +} + +const employees: Employee[] = [ + { name: 'Johnson', amount: 30000, sex: 'M', is_married: true }, + { name: 'Monika', amount: 355000, sex: 'F', is_married: false }, +]; +const leaves: Leave[] = [{ name: 'Johnson', total: 25, remaining: 16 }]; + +// → { title, key }; a value function → { title, value }. +const employeeSheet: Dataset = { + columns: [ + { title: 'Name', key: 'name' }, + { title: 'Wallet Money', key: 'amount' }, + { title: 'Gender', key: 'sex' }, + { title: 'Marital Status', value: (row) => (row.is_married ? 'Married' : 'Single') }, + ], + data: employees, +}; +const leaveSheet: Dataset = { + columns: [ + { title: 'Name', key: 'name' }, + { title: 'Total Leaves', key: 'total' }, + { title: 'Remaining Leaves', key: 'remaining' }, + ], + data: leaves, +}; + +export function Download() { + return ( + + Download + + ); +} +``` + +- Each `` becomes one entry in `workbook.sheets`: its `name`, plus a dataset (`columns` and `data`). For a single sheet, `` is shorter. +- `label` becomes `title`. A string `value` becomes `key` (an own property, read literally) or `path` (`'address.city'`, `'items[0].name'`). A function `value` stays `value`, and it also gets `{ rowIndex }`. +- `data={() => rows}` (a function) is gone: pass the array. To build the rows only when the user clicks, call `exportWorkbook`/`exportDataset` from your own handler (see [3.5](#35-element)). +- Sheets can be conditional: `sheets: [summary, isAdmin && salaries]`. Falsy entries are skipped. Columns work the same way. +- New per-sheet options: `freezeHeader`, `autoFilter`, `autoWidth`, `rightToLeft`, `totals`, `rowStyle`, header groups (`children` on a column), and per-column `type` and `numFmt`. See [api.md §3](api.md#3-the-dataset-shape). + +### 3.2 `dataSet`: array rows, styled cells, widths + +**0.x** + +```jsx +const multiDataSet = [ + { + columns: [ + {title: "Headings", width: {wpx: 80}},//pixels width + {title: "Text Style", width: {wch: 40}},//char width + {title: "Colors", width: {wpx: 90}}, + ], + data: [ + [ + {value: "H1", style: {font: {sz: "24", bold: true}}}, + {value: "Bold", style: {font: {bold: true}}}, + {value: "Red", style: {fill: {patternType: "solid", fgColor: {rgb: "FFFF0000"}}}}, + ], + [ + {value: "H2", style: {font: {sz: "18", bold: true}}}, + {value: "underline", style: {font: {underline: true}}}, + {value: "Blue", style: {fill: {patternType: "solid", fgColor: {rgb: "FF0000FF"}}}}, + ], + ] + } +]; + +Download Data With Styles}> + + +``` + +**1.0** + + +```tsx +import { ExcelExport, type Dataset } from 'react-data-export'; + +// Rows are arrays, so each column takes the value at its position. +// A cell is a bare value or { value, style }; style keys are javascript-excel's. +const styles: Dataset = { + columns: [ + { title: 'Headings', width: { wpx: 80 } }, // pixels + { title: 'Text Style', width: { wch: 40 } }, // characters + { title: 'Colors', width: { wpx: 90 } }, + ], + data: [ + [ + { value: 'H1', style: { font: { size: 24, bold: true } } }, + { value: 'Bold', style: { font: { bold: true } } }, + { value: 'Red', style: { fill: 'FF0000' } }, + ], + [ + { value: 'H2', style: { font: { size: 18, bold: true } } }, + { value: 'underline', style: { font: { underline: true } } }, + { value: 'Blue', style: { fill: { pattern: 'solid', fgColor: { rgb: 'FF0000FF' } } } }, + ], + ], +}; + +export function DownloadStyled() { + return ( + + Download Data With Styles + + ); +} +``` + +- **Array rows stay array rows.** A column without `key`, `path` or `value` takes the cell at its own position; `index` picks another position. +- **Columns must be objects.** A plain string throws `INVALID_COLUMN`. (In 0.6.0 a string column also misbehaved: the header code reads `col.title`, so the header cell came out empty.) +- **Cells** are a bare value or `{ value, style }`, as before. They can also carry `formula`, `hyperlink` and `type`. +- **Widths** keep `{ wpx }` and `{ wch }`, and add a bare number (characters) and `'auto'`. +- The style keys changed. See [3.7](#37-cell-styles) for the table, and a converter for existing style objects. + +### 3.3 `xSteps` / `ySteps` + +**0.x** + +```jsx +const multiDataSet = [ + { + columns: ["Name", "Salary", "Sex"], + data: [["Johnson", 30000, "Male"], ["Monika", 355000, "Female"]] + }, + { + xSteps: 1, // Will start putting cell with 1 empty cell on left most + ySteps: 5, //will put space of 5 rows, + columns: ["Name", "Department"], + data: [["Johnson", "Finance"], ["Monika", "IT"]] + } +]; + + + + +``` + +**1.0** + + +```tsx +import { ExcelExport } from 'react-data-export'; + +// Several blocks on one sheet. 0.x `xSteps` → offset.cols (from column A); +// 0.x `ySteps` → offset.rows (empty rows above the block). `gap: 0` matches 0.x, +// which put a block right under the previous one unless ySteps said otherwise. +export function DownloadOrganization() { + return ( + + Download + + ); +} +``` + +- `xSteps` → `offset.cols` and `ySteps` → `offset.rows`, with the same meaning. Columns count from column A for every block. Rows count from the end of the previous block, or from row 1 for the first block. +- 1.0's default is one empty row between blocks (`gap: 1`). 0.x put each block straight under the previous one. With `gap: 0` and the same `offset` values, every cell lands where 0.x put it: in the example the second block starts at B9 in both versions. +- `freezeHeader` and `autoFilter` apply to the first block that has a header row. + +### 3.4 `hideElement` + +**0.x** + +```jsx + + + + + + +``` + +**1.0** + + +```tsx +import { useEffect } from 'react'; +import { useExcelExport, type Dataset } from 'react-data-export'; + +interface Row { + name: string; + amount: number; +} + +// 0.x `hideElement`: download as soon as the component mounts, render nothing. +export function AutoDownload({ rows }: { rows: Row[] }) { + const { exportDataset } = useExcelExport(); + useEffect(() => { + const dataset: Dataset = { + columns: [ + { title: 'Name', key: 'name' }, + { title: 'Amount', key: 'amount' }, + ], + data: rows, + }; + // Rejected with an AbortError if the component unmounts first + // (StrictMode does that once in development, then runs the effect again). + exportDataset(dataset, { filename: 'report' }).catch(() => {}); + }, [exportDataset, rows]); + return null; +} +``` + +- 0.x started the download in the `ExcelFile` constructor, so it ran on every construction. In development, React's StrictMode constructs class components twice, which gave two files. 1.0 starts it in an effect, and the hook aborts it when the component unmounts. StrictMode's simulated unmount aborts the first run and the remount starts a new one, so an xlsx export saves one file. + - **CSV caveat:** a CSV export finishes synchronously inside the first call, before the simulated unmount can abort it. Until that is fixed, this recipe saves the CSV twice under StrictMode in development. Production builds, which run effects once, are not affected. +- Browsers may block a download that doesn't follow a click or a key press. That was true in 0.x too. Prefer a button where you can. +- The hook also gives `status`, `progress`, `error`, `result` and `abort()`. See [api.md §5](api.md#5-useexcelexport). + +### 3.5 `element` + +**0.x** + +```jsx +Download Data}> + + + + +``` + +**1.0** + + +```tsx +import type { ReactElement } from 'react'; +import { ExcelExport, type Dataset } from 'react-data-export'; + +declare function MyButton(props: { onClick: () => void; disabled: boolean; children: string }): ReactElement; + +const people: Dataset<{ name: string }> = { + columns: [{ title: 'Name', key: 'name' }], + data: [{ name: 'Ada' }], +}; + +// 0.x `element={}` → the default button's label… +export function WithLabel() { + return Download Data; +} + +// …or any element, through the render prop. +export function WithOwnButton() { + return ( + + {({ run, status }) => ( + void run()} disabled={status === 'exporting'}> + Download Data + + )} + + ); +} +``` + +- 0.x wrapped `element` in a ``. 1.0 adds no wrapper element. +- Without children, `` renders ``, disabled while the export runs. A string or element child becomes that button's label. +- For anything else (a design-system button, a menu item, a link), use the render prop: you get `run`, `status` and `progress`. `run()` never rejects. Errors go to `onError`, or to `console.error` if there is no `onError`. `onExported` fires once the file has been handed to the browser. +- Not using a component at all? Call `exportDataset` / `exportWorkbook` from any handler. They return a promise with `{ blob, filename, format, warnings }`. + +### 3.6 `fileExtension` and `filename` + +**0.x** + +```jsx +… +``` + +**1.0** + + +```ts +import { exportDataset, type Dataset } from 'react-data-export'; + +const people: Dataset<{ name: string; city: string }> = { + columns: [ + { title: 'Name', key: 'name' }, + { title: 'City', key: 'city' }, + ], + data: [{ name: 'Ada', city: 'London' }], +}; + +// fileExtension="xlsx" (the default) → format: 'xlsx' (the default). 'report' → report.xlsx. +export async function asXlsx(): Promise { + await exportDataset(people, { filename: 'report' }); +} + +// fileExtension="csv" → format: 'csv'. Real CSV text: UTF-8 with a BOM, formula-injection guard on. +export async function asCsv(): Promise { + await exportDataset(people, { filename: 'report', format: 'csv' }); +} + +// fileExtension="txt" has no format of its own: build tab-separated text, then save it under any name. +export async function asTabSeparatedTxt(): Promise { + const { blob } = await exportDataset(people, { format: 'csv', csv: { delimiter: '\t' }, download: false }); + const url = URL.createObjectURL(blob); + const a = document.createElement('a'); + a.href = url; + a.download = 'report.txt'; + a.click(); + setTimeout(() => URL.revokeObjectURL(url), 40_000); +} +``` + +| 0.x `fileExtension` | what 0.6.0 actually saved | 1.0 | +|---|---|---| +| `xlsx` (default) | an `.xlsx` workbook | `format: 'xlsx'` (default) | +| `csv` | the xlsx zip package, under a `.csv` name | `format: 'csv'`: real CSV text | +| `txt` | the xlsx zip package, under a `.txt` name | `format: 'csv'` with `csv: { delimiter: '\t' }`, saved under your own name (example above) | +| `xls` | the xlsx zip package, under a `.xls` name | `format: 'xlsx'`. Legacy `.xls` (BIFF8) output isn't planned for 1.0 | +| `html` | the xlsx zip package, under an `.html` name | none. Render an HTML table in your app | +| anything else | an `.xlsx` workbook | a `TypeError` | + +0.6.0 handed every extension to tempa-xlsx, whose write function only special-cases `'xml'`. Every other book type went through its zip writer. So any CSV, TXT, XLS or HTML file from 0.6 was really an xlsx package with another name. + +- **Filename:** 1.0 appends the extension only when the name doesn't already end with it: `'report'` → `report.xlsx`, `'report.xlsx'` → `report.xlsx`. 0.x always appended it, so `filename="report.xlsx"` gave `report.xlsx.xlsx`. The default name changes from `Download` to `export`, and an empty name falls back to `export`. +- **CSV holds one sheet.** `exportWorkbook` with `format: 'csv'` and several sheets throws a `TypeError`. Export each sheet as its own file (`Promise.all` over several `exportDataset` calls). +- **CSV defaults:** + - UTF-8 with a byte-order mark, so Excel detects the encoding. + - CRLF line endings. + - A formula-injection guard: a text field starting with `=`, `+`, `-`, `@`, tab or CR gets a leading `'`. + + All of these can be changed in `csv` (`bom`, `newline`, `delimiter`, `quote`, `escapeFormulas`, `dates`). Only turn the guard off for data you trust. + +### 3.7 Cell styles + +1.0 uses javascript-excel's style model. It has the same five groups (`font`, `fill`, `border`, `alignment`, `numFmt`), with these changes: + +| 0.x (xlsx-style) | 1.0 | +|---|---| +| `font.sz: "24"` | `font.size: 24` (a number) | +| `font.color: { rgb: 'FFFF0000' }` | `font.color: 'FF0000'`, or `{ rgb: 'FFFF0000' }` | +| `fill: { patternType: 'solid', fgColor: { rgb: 'FFFFFF00' } }` | `fill: 'FFFF00'`, or `{ pattern: 'solid', fgColor: { rgb: 'FFFFFF00' } }` | +| `fill: { patternType: 'none' }` | leave `fill` out | +| colour `{ theme: '1', tint: '-0.25' }` | `{ theme: 1, tint: -0.25 }` (numbers) | +| colour `{ auto: 1 }` | `{ auto: true }` | +| `alignment.textRotation: 0`–`90` | `alignment.rotation`: the same value | +| `alignment.textRotation: 91`–`180` (135 = 45° down) | `alignment.rotation: 90 - value` (135 → `-45`) | +| `alignment.textRotation: 255` (stacked) | `alignment.rotation: 'vertical'` | +| `alignment.readingOrder: 2` | `alignment.readingOrder: 'rtl'` (`1` → `'ltr'`) | +| `alignment.horizontal`/`vertical` | the same keys. `horizontal` takes `left`, `center`, `right`, `justify`, …; `vertical` takes `top`, `center`, `bottom`, … | +| `font.vertAlign: true` | `font.vertAlign: 'superscript'` or `'subscript'` | +| `border.top: { style, color }` (and `bottom`, `left`, `right`, `diagonal`) | the same; `'double'` is also accepted | +| `numFmt: '0.00%'` | the same. A string is always a format code; a number is a built-in format id | + +Invalid styles now fail loudly, with some exceptions. A 0.x fill (`patternType` but no `pattern`), a string theme index, `auto: 1`, a boolean `vertAlign` or `horizontal: 'bottom'` throws `INVALID_STYLE`, naming the cell. But keys that 1.0 doesn't know, such as `font.sz` and `alignment.textRotation`, are ignored without an error. Convert them; don't rely on an error to find them. + +If your app has many 0.x style objects, convert them in one place. This helper is type-checked with the rest of the examples. Copy it into your project: + + +```ts +import type { Style } from 'react-data-export'; + +/** A 0.x (xlsx-style) style object, as documented in the 0.6 README. */ +export interface LegacyColor { + auto?: number; + rgb?: string; + theme?: string | number; + tint?: string | number; + indexed?: number; +} +export interface LegacyBorderSide { + style: string; + color?: LegacyColor; +} +export interface LegacyStyle { + fill?: { patternType?: string; fgColor?: LegacyColor; bgColor?: LegacyColor }; + font?: { + name?: string; + sz?: string | number; + color?: LegacyColor; + bold?: boolean; + underline?: boolean; + italic?: boolean; + strike?: boolean; + outline?: boolean; + shadow?: boolean; + }; + numFmt?: string; + alignment?: { vertical?: string; horizontal?: string; wrapText?: boolean; readingOrder?: number; textRotation?: number }; + border?: { top?: LegacyBorderSide; bottom?: LegacyBorderSide; left?: LegacyBorderSide; right?: LegacyBorderSide; diagonal?: LegacyBorderSide; diagonalUp?: boolean; diagonalDown?: boolean }; +} + +type Font = NonNullable; +type Color = NonNullable; +type Alignment = NonNullable; +type Border = NonNullable; +type BorderSide = NonNullable; + +function color(c: LegacyColor | undefined): Color | undefined { + if (!c) return undefined; + if (c.rgb !== undefined) return { rgb: c.rgb }; + if (c.theme !== undefined) return { theme: Number(c.theme), ...(c.tint !== undefined ? { tint: Number(c.tint) } : {}) }; + if (c.indexed !== undefined) return { indexed: c.indexed }; + if (c.auto) return { auto: true }; + return undefined; +} + +// 0.x: 0–90 up, 91–180 down (135 = 45° down), 255 = stacked. 1.0: -90..90, or 'vertical'. +function rotation(r: number | undefined): Alignment['rotation'] { + if (r === undefined) return undefined; + if (r === 255) return 'vertical'; + return r > 90 ? 90 - r : r; +} + +const HORIZONTAL = ['general', 'left', 'center', 'right', 'fill', 'justify', 'centerContinuous', 'distributed'] as const; +const VERTICAL = ['top', 'center', 'bottom', 'justify', 'distributed'] as const; +const pick = (allowed: readonly T[], v: string | undefined): T | undefined => + allowed.find((a) => a === v); + +function side(s: LegacyBorderSide | undefined): BorderSide | undefined { + if (!s) return undefined; + const c = color(s.color); + return { style: s.style as BorderSide['style'], ...(c ? { color: c } : {}) }; +} + +/** Converts a 0.x cell style to a react-data-export 1.0 (javascript-excel) style. */ +export function convertLegacyStyle(old: LegacyStyle): Style { + const style: Style = {}; + if (old.font) { + const { sz, color: c, name, bold, italic, underline, strike, outline, shadow } = old.font; + const font: Font = { name, bold, italic, underline, strike, outline, shadow }; + if (sz !== undefined) font.size = Number(sz); + if (c) font.color = color(c); + style.font = font; + } + // A fill with a colour becomes a solid fill; 'none' or no colour means no fill. + if (old.fill && old.fill.patternType !== 'none' && old.fill.fgColor) { + const fg = color(old.fill.fgColor); + const bg = color(old.fill.bgColor); + style.fill = { pattern: 'solid', ...(fg ? { fgColor: fg } : {}), ...(bg ? { bgColor: bg } : {}) }; + } + if (old.numFmt !== undefined) style.numFmt = old.numFmt; + if (old.alignment) { + const a = old.alignment; + style.alignment = { + horizontal: pick(HORIZONTAL, a.horizontal), + vertical: pick(VERTICAL, a.vertical), + wrapText: a.wrapText, + rotation: rotation(a.textRotation), + readingOrder: a.readingOrder === 2 ? 'rtl' : a.readingOrder === 1 ? 'ltr' : undefined, + }; + } + if (old.border) { + const b = old.border; + style.border = { + top: side(b.top), + bottom: side(b.bottom), + left: side(b.left), + right: side(b.right), + diagonal: side(b.diagonal), + diagonalUp: b.diagonalUp, + diagonalDown: b.diagonalDown, + }; + } + return style; +} +``` + +```ts +import { convertLegacyStyle } from './legacy-style'; + +const cell = { value: 'Red', style: convertLegacyStyle({ fill: { patternType: 'solid', fgColor: { rgb: 'FFFF0000' } } }) }; +``` + +Styles also cascade in 1.0: a column's `style` applies to every data cell in the column, a `rowStyle` function styles whole rows, and a cell's own `style` is merged on top. + +## 4. Behaviour differences + +Intentional changes, found by comparing the 0.6.0 source with 1.0. Where you might want the old behaviour back, the last column says how. + +| | 0.6.0 | 1.0 | to get the 0.6 output | +|---|---|---|---| +| **Header style, ``** | plain text, not bold | bold (`{ font: { bold: true } }`) | `headerStyle: {}` | +| **Header style, `dataSet`** | bold; a column's `style` replaced the bold | bold. The sheet's `headerStyle` replaces the bold; a column's `headerStyle` is merged over the sheet's | put the full style in `headerStyle` | +| **Column widths** | `dataSet` columns written as objects: `{ wpx: 80 }` unless set. ``: none. Several blocks on one sheet: the last block's widths won | no width unless set, so Excel's default (about 64 px) applies | `width: { wpx: 80 }` on each column | +| **Dates** | converted as UTC: midnight local time in Berlin became 23:00 UTC the day before, so a date-only format showed the previous day | the local time zone of the browser (javascript-excel's default) | `write: { dateZone: 'utc' }` | +| **Date format** | built-in format 14 (short date) | the same, unless the column or cell sets `numFmt` | — | +| **`hideElement` / auto-download** | downloads in the constructor: twice under StrictMode in development | xlsx: once under StrictMode (CSV: see [3.4](#34-hideelement)); aborted on unmount | — | +| **`fileExtension` other than xlsx** | an xlsx package under that name ([3.6](#36-fileextension-and-filename)) | real CSV for `'csv'`; any other format is a `TypeError` | — | +| **File name** | extension always appended; default `Download` | appended unless already there; default `export` | `filename: 'Download'` | +| **Trigger markup** | `` around `element`; default `` | no wrapper; default ``, disabled while exporting | `Download` | +| **Timing and errors** | synchronous; errors thrown inside the click handler | a promise; errors go to `onError` or `console.error`; `onExported` on success | — | +| **Empty `columns: []`** | an empty header row, then the data | no columns, so no cells | `columns: [{}, {}], header: false` (one `{}` per column) | +| **Empty values (``)** | `undefined`, `''` and `NaN` → an empty text cell; `null` → no cell | `null`/`undefined` → no cell; `NaN`/`Infinity` → no cell plus a `NON_FINITE_NUMBER` warning | — | +| **Invalid styles** | passed to tempa-xlsx | `INVALID_STYLE` for invalid values; unknown keys ignored ([3.7](#37-cell-styles)) | convert with `convertLegacyStyle` | +| **Sheet names** | passed through | validated: an invalid name throws `INVALID_SHEET_NAME` | `sanitizeSheetName(name)` | +| **CSV** | not available (see above) | UTF-8 BOM, CRLF, formula-injection guard on | `csv: { bom: false, escapeFormulas: false }` | +| **`dataSet` and `data` on one sheet** | `dataSet` won when it wasn't empty | one shape per sheet | — | + +Together, for a sheet that should look like a 0.6 export: + + +```ts +import { exportDataset, type Dataset } from 'react-data-export'; + +interface Row { + name: string; + joined: Date; +} + +// Options that bring 1.0's output closer to what 0.x wrote, where it differs. +export async function exportLike0x(rows: Row[]): Promise { + const dataset: Dataset = { + columns: [ + // dataSet columns given as objects got 80 px unless they had a width + { title: 'Name', key: 'name', width: { wpx: 80 } }, + { title: 'Joined', key: 'joined', width: { wpx: 80 } }, + ], + data: rows, + }; + await exportDataset(dataset, { + filename: 'Download', // the 0.x default name + headerStyle: {}, // headers were not bold (dataSet headers were: leave this out) + write: { dateZone: 'utc' }, // 0.x wrote dates as UTC times + }); +} +``` + +## 5. Not carried over + +- **`.xls`, `.html` and `.txt` output**, and `fileExtension` itself. See the table in [3.6](#36-fileextension-and-filename). +- **`element` cloning.** Injecting `onClick` into an arbitrary element breaks with components that don't forward it, and with fragments. The render prop replaces it ([api.md §12 Q5](api.md#12-design-decisions)). +- **A `hideElement` prop.** It is a three-line effect instead ([3.4](#34-hideelement)). +- **`data` as a function** on a sheet. Pass the rows, or build them in your own handler. +- **The default export and `ExcelFile.ExcelSheet` / `ExcelFile.ExcelColumn`**, and PropTypes. 1.0 has named exports and TypeScript types. + +Found a 0.x pattern this guide doesn't cover? Please open an issue with the snippet. diff --git a/examples/migration/auto-download.tsx b/examples/migration/auto-download.tsx new file mode 100644 index 0000000..ceabf1a --- /dev/null +++ b/examples/migration/auto-download.tsx @@ -0,0 +1,25 @@ +import { useEffect } from 'react'; +import { useExcelExport, type Dataset } from 'react-data-export'; + +interface Row { + name: string; + amount: number; +} + +// 0.x `hideElement`: download as soon as the component mounts, render nothing. +export function AutoDownload({ rows }: { rows: Row[] }) { + const { exportDataset } = useExcelExport(); + useEffect(() => { + const dataset: Dataset = { + columns: [ + { title: 'Name', key: 'name' }, + { title: 'Amount', key: 'amount' }, + ], + data: rows, + }; + // Rejected with an AbortError if the component unmounts first + // (StrictMode does that once in development, then runs the effect again). + exportDataset(dataset, { filename: 'report' }).catch(() => {}); + }, [exportDataset, rows]); + return null; +} diff --git a/examples/migration/custom-trigger.tsx b/examples/migration/custom-trigger.tsx new file mode 100644 index 0000000..c457df6 --- /dev/null +++ b/examples/migration/custom-trigger.tsx @@ -0,0 +1,27 @@ +import type { ReactElement } from 'react'; +import { ExcelExport, type Dataset } from 'react-data-export'; + +declare function MyButton(props: { onClick: () => void; disabled: boolean; children: string }): ReactElement; + +const people: Dataset<{ name: string }> = { + columns: [{ title: 'Name', key: 'name' }], + data: [{ name: 'Ada' }], +}; + +// 0.x `element={}` → the default button's label… +export function WithLabel() { + return Download Data; +} + +// …or any element, through the render prop. +export function WithOwnButton() { + return ( + + {({ run, status }) => ( + void run()} disabled={status === 'exporting'}> + Download Data + + )} + + ); +} diff --git a/examples/migration/file-formats.ts b/examples/migration/file-formats.ts new file mode 100644 index 0000000..7d7e0e8 --- /dev/null +++ b/examples/migration/file-formats.ts @@ -0,0 +1,30 @@ +import { exportDataset, type Dataset } from 'react-data-export'; + +const people: Dataset<{ name: string; city: string }> = { + columns: [ + { title: 'Name', key: 'name' }, + { title: 'City', key: 'city' }, + ], + data: [{ name: 'Ada', city: 'London' }], +}; + +// fileExtension="xlsx" (the default) → format: 'xlsx' (the default). 'report' → report.xlsx. +export async function asXlsx(): Promise { + await exportDataset(people, { filename: 'report' }); +} + +// fileExtension="csv" → format: 'csv'. Real CSV text: UTF-8 with a BOM, formula-injection guard on. +export async function asCsv(): Promise { + await exportDataset(people, { filename: 'report', format: 'csv' }); +} + +// fileExtension="txt" has no format of its own: build tab-separated text, then save it under any name. +export async function asTabSeparatedTxt(): Promise { + const { blob } = await exportDataset(people, { format: 'csv', csv: { delimiter: '\t' }, download: false }); + const url = URL.createObjectURL(blob); + const a = document.createElement('a'); + a.href = url; + a.download = 'report.txt'; + a.click(); + setTimeout(() => URL.revokeObjectURL(url), 40_000); +} diff --git a/examples/migration/legacy-style.ts b/examples/migration/legacy-style.ts new file mode 100644 index 0000000..b97988f --- /dev/null +++ b/examples/migration/legacy-style.ts @@ -0,0 +1,106 @@ +import type { Style } from 'react-data-export'; + +/** A 0.x (xlsx-style) style object, as documented in the 0.6 README. */ +export interface LegacyColor { + auto?: number; + rgb?: string; + theme?: string | number; + tint?: string | number; + indexed?: number; +} +export interface LegacyBorderSide { + style: string; + color?: LegacyColor; +} +export interface LegacyStyle { + fill?: { patternType?: string; fgColor?: LegacyColor; bgColor?: LegacyColor }; + font?: { + name?: string; + sz?: string | number; + color?: LegacyColor; + bold?: boolean; + underline?: boolean; + italic?: boolean; + strike?: boolean; + outline?: boolean; + shadow?: boolean; + }; + numFmt?: string; + alignment?: { vertical?: string; horizontal?: string; wrapText?: boolean; readingOrder?: number; textRotation?: number }; + border?: { top?: LegacyBorderSide; bottom?: LegacyBorderSide; left?: LegacyBorderSide; right?: LegacyBorderSide; diagonal?: LegacyBorderSide; diagonalUp?: boolean; diagonalDown?: boolean }; +} + +type Font = NonNullable; +type Color = NonNullable; +type Alignment = NonNullable; +type Border = NonNullable; +type BorderSide = NonNullable; + +function color(c: LegacyColor | undefined): Color | undefined { + if (!c) return undefined; + if (c.rgb !== undefined) return { rgb: c.rgb }; + if (c.theme !== undefined) return { theme: Number(c.theme), ...(c.tint !== undefined ? { tint: Number(c.tint) } : {}) }; + if (c.indexed !== undefined) return { indexed: c.indexed }; + if (c.auto) return { auto: true }; + return undefined; +} + +// 0.x: 0–90 up, 91–180 down (135 = 45° down), 255 = stacked. 1.0: -90..90, or 'vertical'. +function rotation(r: number | undefined): Alignment['rotation'] { + if (r === undefined) return undefined; + if (r === 255) return 'vertical'; + return r > 90 ? 90 - r : r; +} + +const HORIZONTAL = ['general', 'left', 'center', 'right', 'fill', 'justify', 'centerContinuous', 'distributed'] as const; +const VERTICAL = ['top', 'center', 'bottom', 'justify', 'distributed'] as const; +const pick = (allowed: readonly T[], v: string | undefined): T | undefined => + allowed.find((a) => a === v); + +function side(s: LegacyBorderSide | undefined): BorderSide | undefined { + if (!s) return undefined; + const c = color(s.color); + return { style: s.style as BorderSide['style'], ...(c ? { color: c } : {}) }; +} + +/** Converts a 0.x cell style to a react-data-export 1.0 (javascript-excel) style. */ +export function convertLegacyStyle(old: LegacyStyle): Style { + const style: Style = {}; + if (old.font) { + const { sz, color: c, name, bold, italic, underline, strike, outline, shadow } = old.font; + const font: Font = { name, bold, italic, underline, strike, outline, shadow }; + if (sz !== undefined) font.size = Number(sz); + if (c) font.color = color(c); + style.font = font; + } + // A fill with a colour becomes a solid fill; 'none' or no colour means no fill. + if (old.fill && old.fill.patternType !== 'none' && old.fill.fgColor) { + const fg = color(old.fill.fgColor); + const bg = color(old.fill.bgColor); + style.fill = { pattern: 'solid', ...(fg ? { fgColor: fg } : {}), ...(bg ? { bgColor: bg } : {}) }; + } + if (old.numFmt !== undefined) style.numFmt = old.numFmt; + if (old.alignment) { + const a = old.alignment; + style.alignment = { + horizontal: pick(HORIZONTAL, a.horizontal), + vertical: pick(VERTICAL, a.vertical), + wrapText: a.wrapText, + rotation: rotation(a.textRotation), + readingOrder: a.readingOrder === 2 ? 'rtl' : a.readingOrder === 1 ? 'ltr' : undefined, + }; + } + if (old.border) { + const b = old.border; + style.border = { + top: side(b.top), + bottom: side(b.bottom), + left: side(b.left), + right: side(b.right), + diagonal: side(b.diagonal), + diagonalUp: b.diagonalUp, + diagonalDown: b.diagonalDown, + }; + } + return style; +} diff --git a/examples/migration/like-0x.ts b/examples/migration/like-0x.ts new file mode 100644 index 0000000..0c00b3f --- /dev/null +++ b/examples/migration/like-0x.ts @@ -0,0 +1,23 @@ +import { exportDataset, type Dataset } from 'react-data-export'; + +interface Row { + name: string; + joined: Date; +} + +// Options that bring 1.0's output closer to what 0.x wrote, where it differs. +export async function exportLike0x(rows: Row[]): Promise { + const dataset: Dataset = { + columns: [ + // dataSet columns given as objects got 80 px unless they had a width + { title: 'Name', key: 'name', width: { wpx: 80 } }, + { title: 'Joined', key: 'joined', width: { wpx: 80 } }, + ], + data: rows, + }; + await exportDataset(dataset, { + filename: 'Download', // the 0.x default name + headerStyle: {}, // headers were not bold (dataSet headers were: leave this out) + write: { dateZone: 'utc' }, // 0.x wrote dates as UTC times + }); +} diff --git a/examples/migration/readme.tsx b/examples/migration/readme.tsx new file mode 100644 index 0000000..cf3f258 --- /dev/null +++ b/examples/migration/readme.tsx @@ -0,0 +1,20 @@ +// 1.0 +import { ExcelExport } from 'react-data-export'; + +const employees = [{ name: 'Monika', is_married: false }]; + +export const Download = () => ( + (row.is_married ? 'Married' : 'Single') }, + ], + data: employees, + }} + > + Download + +); diff --git a/examples/migration/sheets-and-columns.tsx b/examples/migration/sheets-and-columns.tsx new file mode 100644 index 0000000..e98e277 --- /dev/null +++ b/examples/migration/sheets-and-columns.tsx @@ -0,0 +1,54 @@ +import { ExcelExport, type Dataset } from 'react-data-export'; + +interface Employee { + name: string; + amount: number; + sex: 'M' | 'F'; + is_married: boolean; +} +interface Leave { + name: string; + total: number; + remaining: number; +} + +const employees: Employee[] = [ + { name: 'Johnson', amount: 30000, sex: 'M', is_married: true }, + { name: 'Monika', amount: 355000, sex: 'F', is_married: false }, +]; +const leaves: Leave[] = [{ name: 'Johnson', total: 25, remaining: 16 }]; + +// → { title, key }; a value function → { title, value }. +const employeeSheet: Dataset = { + columns: [ + { title: 'Name', key: 'name' }, + { title: 'Wallet Money', key: 'amount' }, + { title: 'Gender', key: 'sex' }, + { title: 'Marital Status', value: (row) => (row.is_married ? 'Married' : 'Single') }, + ], + data: employees, +}; +const leaveSheet: Dataset = { + columns: [ + { title: 'Name', key: 'name' }, + { title: 'Total Leaves', key: 'total' }, + { title: 'Remaining Leaves', key: 'remaining' }, + ], + data: leaves, +}; + +export function Download() { + return ( + + Download + + ); +} diff --git a/examples/migration/stacked-blocks.tsx b/examples/migration/stacked-blocks.tsx new file mode 100644 index 0000000..fe97442 --- /dev/null +++ b/examples/migration/stacked-blocks.tsx @@ -0,0 +1,39 @@ +import { ExcelExport } from 'react-data-export'; + +// Several blocks on one sheet. 0.x `xSteps` → offset.cols (from column A); +// 0.x `ySteps` → offset.rows (empty rows above the block). `gap: 0` matches 0.x, +// which put a block right under the previous one unless ySteps said otherwise. +export function DownloadOrganization() { + return ( + + Download + + ); +} diff --git a/examples/migration/styled-dataset.tsx b/examples/migration/styled-dataset.tsx new file mode 100644 index 0000000..7c556ce --- /dev/null +++ b/examples/migration/styled-dataset.tsx @@ -0,0 +1,31 @@ +import { ExcelExport, type Dataset } from 'react-data-export'; + +// Rows are arrays, so each column takes the value at its position. +// A cell is a bare value or { value, style }; style keys are javascript-excel's. +const styles: Dataset = { + columns: [ + { title: 'Headings', width: { wpx: 80 } }, // pixels + { title: 'Text Style', width: { wch: 40 } }, // characters + { title: 'Colors', width: { wpx: 90 } }, + ], + data: [ + [ + { value: 'H1', style: { font: { size: 24, bold: true } } }, + { value: 'Bold', style: { font: { bold: true } } }, + { value: 'Red', style: { fill: 'FF0000' } }, + ], + [ + { value: 'H2', style: { font: { size: 18, bold: true } } }, + { value: 'underline', style: { font: { underline: true } } }, + { value: 'Blue', style: { fill: { pattern: 'solid', fgColor: { rgb: 'FF0000FF' } } } }, + ], + ], +}; + +export function DownloadStyled() { + return ( + + Download Data With Styles + + ); +} diff --git a/examples/migration/tsconfig.json b/examples/migration/tsconfig.json new file mode 100644 index 0000000..1452362 --- /dev/null +++ b/examples/migration/tsconfig.json @@ -0,0 +1,12 @@ +{ + "extends": "../../tsconfig.base.json", + "compilerOptions": { + "declaration": false, + "isolatedDeclarations": false, + "types": ["node"], + "paths": { + "react-data-export": ["../../packages/react-data-export/src/index.ts"] + } + }, + "include": ["*.ts", "*.tsx"] +} diff --git a/package.json b/package.json index 604c088..a13c0a5 100644 --- a/package.json +++ b/package.json @@ -12,7 +12,8 @@ }, "scripts": { "build": "npm run build -w react-data-export && npm run build -w playground", - "typecheck": "npm run typecheck --workspaces --if-present", + "typecheck": "npm run typecheck --workspaces --if-present && tsc -p examples/migration", + "docs:check": "node scripts/check-doc-snippets.mjs", "test": "npm test -w react-data-export", "lint:pkg": "npm run lint:pkg -w react-data-export", "smoke": "node scripts/smoke.mjs", diff --git a/packages/react-data-export/README.md b/packages/react-data-export/README.md index 6239c5a..585f487 100644 --- a/packages/react-data-export/README.md +++ b/packages/react-data-export/README.md @@ -2,6 +2,6 @@ Export data from React to `.xlsx` and `.csv`. -> **1.0 is a from-scratch rewrite in progress.** The dataset module (`exportDataset`, `exportWorkbook`, `useExcelExport`, ``) is implemented but not yet released as a 1.0 prerelease. See the [repository README](https://github.com/securedeveloper/react-data-export#readme) for status and the [API design](https://github.com/securedeveloper/react-data-export/blob/main/docs/api.md). The current stable release is **0.6.x**; its docs are at the [`v0.6.0` tag](https://github.com/securedeveloper/react-data-export/tree/v0.6.0). +> **1.0 is a from-scratch rewrite in progress.** The dataset module (`exportDataset`, `exportWorkbook`, `useExcelExport`, ``) is implemented but not yet released as a 1.0 prerelease. See the [repository README](https://github.com/securedeveloper/react-data-export#readme) for status and the [API design](https://github.com/securedeveloper/react-data-export/blob/main/docs/api.md). The current stable release is **0.6.x**; its docs are at the [`v0.6.0` tag](https://github.com/securedeveloper/react-data-export/tree/v0.6.0). Moving from 0.x: see the [migration guide](https://github.com/securedeveloper/react-data-export/blob/main/docs/migration.md). MIT licensed. diff --git a/scripts/check-doc-snippets.mjs b/scripts/check-doc-snippets.mjs new file mode 100644 index 0000000..7154f13 --- /dev/null +++ b/scripts/check-doc-snippets.mjs @@ -0,0 +1,52 @@ +// Keeps the code in docs/ and the READMEs identical to the type-checked +// examples in examples/ (same convention as javascript-excel's docs:check). +// +// A Markdown file includes an example file with a marker line followed by a +// fenced code block: +// +// +// ```tsx +// ...the file's exact content... +// ``` +// +// node scripts/check-doc-snippets.mjs fail if any block differs from its file +// node scripts/check-doc-snippets.mjs --fix rewrite the blocks from the files +import { readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'; +import { join, relative, resolve } from 'node:path'; +import { fileURLToPath } from 'node:url'; + +const root = resolve(fileURLToPath(new URL('.', import.meta.url)), '..'); +const fix = process.argv.includes('--fix'); +const MARKER = /^\n(`{3,})(\w*)\n(?:\2$|([\s\S]*?)\n\2$)/gm; + +const files = ['README.md', 'packages/react-data-export/README.md']; +(function walk(dir) { + for (const name of readdirSync(dir)) { + const p = join(dir, name); + if (statSync(p).isDirectory()) walk(p); + else if (name.endsWith('.md')) files.push(relative(root, p)); + } +})(join(root, 'docs')); + +let problems = 0; +let blocks = 0; +for (const file of files) { + const path = join(root, file); + const text = readFileSync(path, 'utf8'); + const out = text.replace(MARKER, (whole, src, fence, lang, body) => { + blocks++; + const want = readFileSync(join(root, src), 'utf8').replace(/\n$/, ''); + if ((body ?? '') === want) return whole; + if (!fix) { + problems++; + console.error(`${file}: the block for ${src} differs from the file`); + } + return `\n${fence}${lang}\n${want}\n${fence}`; + }); + if (fix && out !== text) writeFileSync(path, out); +} +if (problems) { + console.error(`${problems} snippet(s) out of date; run: node scripts/check-doc-snippets.mjs --fix`); + process.exit(1); +} +console.log(`ok ${blocks} example blocks match their files`); From 9bf3b85406a4a946223ca3eceb317baee297e2fd Mon Sep 17 00:00:00 2001 From: Afzal Ahmad Date: Mon, 16 Nov 2026 13:11:23 +0100 Subject: [PATCH 2/3] Migration guide: export a table that is already on the page (RDE-1.17) --- docs/migration.md | 55 +++++++++++++++++++++++++++++ examples/migration/table-export.tsx | 41 +++++++++++++++++++++ 2 files changed, 96 insertions(+) create mode 100644 examples/migration/table-export.tsx diff --git a/docs/migration.md b/docs/migration.md index 09652c3..95a0624 100644 --- a/docs/migration.md +++ b/docs/migration.md @@ -18,6 +18,7 @@ Every 1.0 snippet below is a file in [`examples/migration/`](../examples/migrati - [3.5 `element`](#35-element) - [3.6 `fileExtension` and `filename`](#36-fileextension-and-filename) - [3.7 Cell styles](#37-cell-styles) + - [3.8 New: export a table that is already on the page](#38-new-export-a-table-that-is-already-on-the-page) 4. [Behaviour differences](#4-behaviour-differences) 5. [Not carried over](#5-not-carried-over) @@ -57,6 +58,7 @@ npm install react-data-export@next # 1.0 prereleases go to the `next` tag; n | `fileExtension="xlsx"` / `"csv"` | `format="xlsx"` / `"csv"` | [3.6](#36-fileextension-and-filename) | | `fileExtension="txt"` / `"xls"` / `"html"` | CSV with a tab delimiter / `xlsx` / none | [3.6](#36-fileextension-and-filename) | | cell `{ value, style }` | the same, with javascript-excel style keys | [3.7](#37-cell-styles) | +| a `` on the page plus the same rows in `` | ``, which exports the table itself | [3.8](#38-new-export-a-table-that-is-already-on-the-page) | | `font.sz`, `fill.patternType`/`fgColor`, `alignment.textRotation` | `font.size`, `fill: 'RRGGBB'` or `{ pattern, fgColor }`, `alignment.rotation` | [3.7](#37-cell-styles) | ## 3. Side by side @@ -607,6 +609,59 @@ const cell = { value: 'Red', style: convertLegacyStyle({ fill: { patternType: 's Styles also cascade in 1.0: a column's `style` applies to every data cell in the column, a `rowStyle` function styles whole rows, and a cell's own `style` is merged on top. +### 3.8 New: export a table that is already on the page + +0.x had no table export, so apps that showed a `
` also passed the same rows to ``. In 1.0 you can export the rendered table directly. Its header rows, `colspan`/`rowspan` merges and links are kept, and hidden rows and `[data-export-ignore]` cells are skipped: + + +```tsx +import { useRef } from 'react'; +import { ExportTableButton } from 'react-data-export'; + +interface Order { + id: string; + customer: string; + total: number; +} + +// 0.x apps often rendered a
and passed the same rows to again. +// In 1.0 the rendered table can be exported as it is. +export function Orders({ orders }: { orders: Order[] }) { + const ref = useRef(null); + return ( + <> +
+ + + + + + + + + {orders.map((o) => ( + + + + + + ))} + +
OrderCustomerTotal
{o.id}{o.customer} + {o.total.toFixed(2)} +
+ + Download orders.xlsx + + + ); +} +``` + +- `data-type`, `data-value` and `data-numfmt` on a cell give it a real type and number format, so a total is exported as a number, not as text. `styles: 'computed'` carries the table's CSS (colours, bold, alignment) into the file. +- `useTableExport(ref)` and `exportTable(element)` are the hook and the plain function, with the same options. See [api.md §13](api.md#13-table-export). +- Exporting a dataset is still the better fit when the file needs columns the page doesn't show, or when the table is paginated or virtualised (only the rendered rows are in the DOM). + ## 4. Behaviour differences Intentional changes, found by comparing the 0.6.0 source with 1.0. Where you might want the old behaviour back, the last column says how. diff --git a/examples/migration/table-export.tsx b/examples/migration/table-export.tsx new file mode 100644 index 0000000..49b0ff7 --- /dev/null +++ b/examples/migration/table-export.tsx @@ -0,0 +1,41 @@ +import { useRef } from 'react'; +import { ExportTableButton } from 'react-data-export'; + +interface Order { + id: string; + customer: string; + total: number; +} + +// 0.x apps often rendered a and passed the same rows to again. +// In 1.0 the rendered table can be exported as it is. +export function Orders({ orders }: { orders: Order[] }) { + const ref = useRef(null); + return ( + <> +
+ + + + + + + + + {orders.map((o) => ( + + + + + + ))} + +
OrderCustomerTotal
{o.id}{o.customer} + {o.total.toFixed(2)} +
+ + Download orders.xlsx + + + ); +} From fd08c2f411ae294f87859d6585c526dd77c2082a Mon Sep 17 00:00:00 2001 From: Afzal Ahmad Date: Mon, 16 Nov 2026 13:14:09 +0100 Subject: [PATCH 3/3] Migration guide: one download under StrictMode for xlsx and CSV (#198) --- docs/migration.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/migration.md b/docs/migration.md index 95a0624..8f7bd78 100644 --- a/docs/migration.md +++ b/docs/migration.md @@ -347,8 +347,7 @@ export function AutoDownload({ rows }: { rows: Row[] }) { } ``` -- 0.x started the download in the `ExcelFile` constructor, so it ran on every construction. In development, React's StrictMode constructs class components twice, which gave two files. 1.0 starts it in an effect, and the hook aborts it when the component unmounts. StrictMode's simulated unmount aborts the first run and the remount starts a new one, so an xlsx export saves one file. - - **CSV caveat:** a CSV export finishes synchronously inside the first call, before the simulated unmount can abort it. Until that is fixed, this recipe saves the CSV twice under StrictMode in development. Production builds, which run effects once, are not affected. +- 0.x started the download in the `ExcelFile` constructor, so it ran on every construction. In development, React's StrictMode constructs class components twice, which gave two files. 1.0 starts it in an effect, and the hook aborts it when the component unmounts. StrictMode's simulated unmount aborts the first run and the remount starts a new one, so there is one download under StrictMode, for xlsx and CSV. - Browsers may block a download that doesn't follow a click or a key press. That was true in 0.x too. Prefer a button where you can. - The hook also gives `status`, `progress`, `error`, `result` and `abort()`. See [api.md §5](api.md#5-useexcelexport). @@ -673,7 +672,7 @@ Intentional changes, found by comparing the 0.6.0 source with 1.0. Where you mig | **Column widths** | `dataSet` columns written as objects: `{ wpx: 80 }` unless set. ``: none. Several blocks on one sheet: the last block's widths won | no width unless set, so Excel's default (about 64 px) applies | `width: { wpx: 80 }` on each column | | **Dates** | converted as UTC: midnight local time in Berlin became 23:00 UTC the day before, so a date-only format showed the previous day | the local time zone of the browser (javascript-excel's default) | `write: { dateZone: 'utc' }` | | **Date format** | built-in format 14 (short date) | the same, unless the column or cell sets `numFmt` | — | -| **`hideElement` / auto-download** | downloads in the constructor: twice under StrictMode in development | xlsx: once under StrictMode (CSV: see [3.4](#34-hideelement)); aborted on unmount | — | +| **`hideElement` / auto-download** | downloads in the constructor: twice under StrictMode in development | one download under StrictMode, xlsx and CSV; aborted on unmount | — | | **`fileExtension` other than xlsx** | an xlsx package under that name ([3.6](#36-fileextension-and-filename)) | real CSV for `'csv'`; any other format is a `TypeError` | — | | **File name** | extension always appended; default `Download` | appended unless already there; default `export` | `filename: 'Download'` | | **Trigger markup** | `` around `element`; default `` | no wrapper; default ``, disabled while exporting | `Download` |