Skip to content

RDE-1.12: migration guide from 0.6 to 1.0 - #197

Merged
securedeveloper merged 5 commits into
mainfrom
rde-1.12-migration
Nov 16, 2026
Merged

securedeveloper merged 5 commits into
mainfrom
rde-1.12-migration

Conversation

@securedeveloper

@securedeveloper securedeveloper commented Nov 16, 2026 •

Copy link
Copy Markdown
Owner

RDE-1.12: the 0.6 → 1.0 migration guide, as docs/migration.md, plus a "Migrating from 0.x" section in the README.

What's in the guide

  • Side by side for every 0.x pattern: 0.x code (taken from the 0.6 README and examples) next to 1.0 code.
    • ExcelFile + ExcelSheet + ExcelColumn, including value functions
    • dataSet with array rows, styled cells and widths
    • several blocks with xSteps/ySteps → blocks + offset + gap: 0. The second block of the 0.6 example lands at B9 in both versions (checked with fromDatasets).
    • hideElement → useExcelExport + useEffect
    • element → label or render prop
    • fileExtension/filename, including xls/txt/html
    • xlsx-style cell styles
  • A style table (font.sz → font.size, fill.patternType/fgColor → fill, textRotation → rotation, readingOrder, string theme indexes, auto: 1, vertAlign, …). It comes with a convertLegacyStyle() helper users can copy. All 13 style variants from the 0.6 docs convert and write without INVALID_STYLE.
  • Behaviour differences, each checked against the v0.6.0 source (ExcelFile.js, DataUtil.js) and against the tempa-xlsx 0.0.1 source it pinned. Each entry says how to get the old output back where that makes sense:
    • <ExcelColumn> headers weren't bold. dataSet headers were, and a column style replaced that.
    • The { wpx: 80 } default width applied only to object columns in dataSet, and the last block's widths won.
    • Dates were converted as UTC; 1.0 uses local time, and write: { dateZone: 'utc' } restores the old behaviour.
    • hideElement downloaded in the constructor, so twice under StrictMode.
    • The extension was always appended (report.xlsx.xlsx), and the default name was Download.
    • element was wrapped in a <span onClick>.
    • columns: [] gave an empty header row. In 0.6.0, string columns gave empty header cells (the header code reads col.title).
    • undefined, '' and NaN became empty text cells.
    • fileExtension csv/txt/xls/html never produced those formats. tempa-xlsx 0.0.1's writeSync only special-cases 'xml', so every other book type went through its zip writer: 0.6 saved an xlsx package under a .csv/.txt/.xls/.html name. I found this by reading the source; I didn't run the package. 1.0's format: 'csv' is the first real CSV output, and the guide says so.
  • A "Not carried over" list: .xls, .html and .txt formats, element cloning, the hideElement prop, data as a function, the default export, PropTypes.

Type-checked snippets (like javascript-excel's docs:check)

  • Every 1.0 snippet in the guide and the README is a file in examples/migration/ (10 files). They're type-checked against the library source through paths, so no build is needed.
  • scripts/check-doc-snippets.mjs (same convention as javascript-excel's: <!-- example: path --> + fence; --fix rewrites the blocks) fails when a Markdown block differs from its file. I checked that a drifted block fails the step.
  • CI: in the React 19 job (the only one that runs the full typecheck), npm run typecheck now also runs tsc -p examples/migration, and a new step runs npm run docs:check. I didn't add examples/* as a workspace: its own React dependency would fight scripts/use-react.mjs in the React 17/18 jobs. No job was renamed. No changeset, because nothing in the published code changes.

Scope

Only docs/migration.md, examples/migration/, scripts/check-doc-snippets.mjs, the two READMEs, the root package.json scripts and the CI step. Nothing in docs/api.md or src changes, since infra-rde is working there for RDE-1.17.

StrictMode

The hideElement recipe gives one download under StrictMode, for xlsx and CSV. The CSV double download found while writing this guide was fixed in #198, which is merged into this branch. The guide records the 0.6 behaviour: it downloaded twice under StrictMode, because the download started in the constructor.

Table export (RDE-1.17)

RDE-1.17 merged while this was open. After merging main, §3.8 "New: export a table that is already on the page" shows <ExportTableButton tableRef> with data-type/data-numfmt hints (examples/migration/table-export.tsx), and there's a row for it in the quick reference. It's aimed at 0.x apps that rendered a <table> and passed the same rows to <ExcelFile>. 0.x had no table API, so this is a pointer rather than a migration. The merge itself only resolves the two README status lines: main's text, plus the migration link.

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.
# Conflicts:
#	README.md
#	packages/react-data-export/README.md
@securedeveloper
securedeveloper merged commit 1a36f27 into main Nov 16, 2026
34 checks passed
@securedeveloper
securedeveloper deleted the rde-1.12-migration branch November 16, 2026 12:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant