Skip to content

Mail merge: use Excel and OpenDocument spreadsheets as recipient lists - #341

Merged
echelon merged 2 commits into
storytold:mainfrom
vangel76:feat/334-spreadsheet-recipients
Oct 11, 2026
Merged

echelon merged 2 commits into
storytold:mainfrom
vangel76:feat/334-spreadsheet-recipients

Conversation

@vangel76

Copy link
Copy Markdown
Contributor

What changed

Select Recipients › Use an Existing List… now opens Excel (.xlsx, .xlsm) and OpenDocument (.ods) spreadsheets as well as CSV/TSV.

  • Parser (crates/formats/src/sheet.rs, new, L2): a read-only reader written from ECMA-376 Part 1 §18 (SpreadsheetML) and OASIS ODF 1.3. It reuses the zip and quick-xml crates the workspace already has. It lists a workbook's sheets (workbook.xml + rels, or the names of the table:table elements in content.xml; chart sheets are skipped) and reads one sheet into rows of strings:
    • xlsx: shared strings (rich-text runs joined, phonetic runs skipped), inline strings, numbers, booleans (TRUE/FALSE), errors, cached formula results (<v>), sparse cells (r="C5" gaps), out-of-order rows. Merged cells keep only the top-left value.
    • Dates: when a cell's number format is a date or time, its value is written as ISO 8601: yyyy-mm-dd, yyyy-mm-dd hh:mm[:ss] or hh:mm[:ss]. This covers built-in formats 14–22, 27–36, 45–47 and 50–58, and custom formats with d/y/h/s outside quotes and brackets. I chose ISO because it is locale-neutral and can't be misread. Both the 1900 and the 1904 date systems are handled. Other numbers keep up to 15 significant digits.
    • ods: office:value-type float/date/time/boolean/string (percentages and currencies use the cell's displayed text), table:number-columns-repeated / number-rows-repeated, covered cells, text:s/tab/line-break. Annotations are skipped.
    • Blank rows are dropped. The first non-blank row gives the field names: blank names become Column N and repeated names are numbered (Name, Name 2).
  • Engine: mailings.recipients accepts {"path"|"data" (base64), "sheet"?: name | number (1 = first), "headers"?: bool}. Files are recognised by extension or by what is inside the zip. If a workbook has several sheets and no sheet is given, the command returns {"sheets": [...], "chooseSheet": true} and loads nothing. CSV loaded from a file also gets the blank/duplicate header clean-up, and headers: false works for every source.
  • UI:
    • A new Select Table dialog lists the sheets (click to select, double-click to load) and has a First row of data contains column headers checkbox.
    • The desktop picker's "Recipient lists" filter now includes xlsx/xlsm/ods.
    • The web inbox and desktop drag-and-drop send spreadsheets to the recipient list instead of trying to open them as documents.
    • New strings are translated in every catalog.
  • Docs: gaps.md macOS DMG: branded window background and icon layout #21, target-app-parity.md (Mailings), file-format-parity.md (new row), ROADMAP progress log.

Limits (never-crash)

  • Zip entries: 64 MiB each when inflated, 160 MiB per workbook. Both the header size and the actual inflated size are checked.
  • Up to 4,096 sheets, 100,000 non-blank rows, 1,000 columns and 2 M cells. A cell holds at most 32,767 characters.
  • Repeat counts are clamped to whatever room is left. Trailing blank cells and blank rows are never materialised, so LibreOffice's number-rows-repeated="1048553" costs nothing.
  • Elements nested deeper than 256 are skipped, and nothing recurses.

Not done yet: number formats other than dates (currency, percent, thousands separators) in .xlsx show the plain value. No .xls, Access or Outlook sources.

Testing

  • wordcraft-formats: xlsx with shared and rich strings, built-in and custom date formats, a number with float noise, a gap and duplicate/blank headers; ods with repeated rows/columns, covered cells and every value type; hostile files (4 billion repeat counts, a small zip that inflates past the cap, giant cell references, long strings, junk bytes). All are rejected or capped without a panic.
  • wordcraft-engine: a two-sheet workbook as data returns the sheet list, then loads by name or number, with and without headers; bad sheet numbers and bad base64 are errors. hostile_params_never_panic passes.
  • wordcraft-ui-egui: picking a two-sheet workbook opens Select Table, and its answer loads the chosen sheet. The i18n catalog tests pass.
  • cargo fmt, clippy -D warnings (formats, engine, ui-egui, wordcraft) and tests for the touched crates pass. cargo xtask layers, assets and wasm pass.

Fixes #334

🤖 Generated with Claude Code

@vangel76
vangel76 force-pushed the feat/334-spreadsheet-recipients branch 3 times, most recently from eb9666c to 62fca27 Compare October 10, 2026 23:24
@vangel76

Copy link
Copy Markdown
Contributor Author

Rebased onto main (after #315/#308/#294/#370). Conflicts were only in revision tables and the ROADMAP progress log (now its own row). Main's new Estonian catalog got the 2 new strings.

…told#334)

Select Recipients › Use an Existing List… now reads .xlsx, .xlsm and .ods
workbooks besides CSV. A new read-only SpreadsheetML / ODF spreadsheet
reader in wordcraft-formats lists the sheets and turns one sheet into rows
of display strings: shared, inline and rich strings, numbers, booleans,
cached formula results, dates and times as ISO 8601 from the cell's number
format, sparse cells, ODS value types, repeated rows/columns and covered
cells. Zip entries, rows, columns, cells, string lengths and repeat counts
are capped, and nothing recurses.

mailings.recipients takes "data" (base64) and "sheet" and "headers"; a
workbook with several sheets and no sheet answers with the sheet names, and
the app shows a Select Table dialog with "First row of data contains column
headers". The desktop picker, dropped files and the web inbox route
spreadsheets to the recipient list.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@vangel76
vangel76 force-pushed the feat/334-spreadsheet-recipients branch from d286442 to bcb960d Compare October 11, 2026 16:57
# Conflicts:
#	ROADMAP.md
#	crates/ui-egui/src/i18n/ru.tsv
#	crates/ui-egui/src/i18n/tr.tsv
#	docs/gaps.md
#	docs/target-app-parity.md
@echelon
echelon merged commit 589e82e into storytold:main Oct 11, 2026
@echelon

echelon commented Oct 11, 2026

Copy link
Copy Markdown
Member

Thanks for the contribution, @vangel76! This is now merged into main. If you haven't already, please come join us on Discord: https://discord.gg/artcraft

daghantektepe added a commit to daghantektepe/wordcraft that referenced this pull request Nov 6, 2026
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.

Mail merge: use an Excel workbook (.xlsx) or OpenDocument spreadsheet (.ods) as the recipient list

2 participants