Commit Graph
28 Commits
Author SHA1 Message Date
kiwi4boy 8b7cdcdbf0 Merge remote-tracking branch 'origin/main' into xlsb-styles 2026-11-15 16:12:50 -05:00
keithcsqueensu 5a0caf286e craft-xlsx: .xlsb cell formulas, shared, array and dynamic arrays (ports of gridcraft#3810, #3818, #3821) (#1166)
craft-xlsx decodes `.xlsb` cell formulas, including shared, array and dynamic-array formulas, into the text an `.xlsx` file holds for them. Until now they were skipped and only their saved values kept. Part of #778.

Ported from storytold/gridcraft#3810, #3818 and #3821 (issue gridcraft#3806), my own series; the commits keep me (kiwi4boy) as their author. The three PRs are one series, each containing the one before.

## Commits

1. **The XLSB function table** (gridcraft#3810): `xlsb/ftab.rs`, [MS-XLSB] 2.5.98.10. It is craft-xls's table up to 379 (0x17B), which matches GridCraft's before the PR, plus the PR's 0x17C–0x1E4 entries (CUBE*, the Analysis ToolPak functions, IFERROR, COUNTIFS, SUMIFS, AVERAGEIF(S)). It is craft-xlsx's own copy, not shared with craft-xls: the formats follow separate specifications and their readers develop separately. They can share one table later once both settle.
2. **Cell formulas** (gridcraft#3818, with its two review fixes): `xlsb/formula.rs` is a BIFF12 decoder, separate from craft-xls's BIFF8 one, because nearly every operand differs. `xlsb/expr.rs` is a copy of craft-xls's expression tree and A1 printer, with `BinOp::precedence` added for grouping. A formula cell's `CellFormula.text` is in the file's spelling (`_xlfn.CONCAT`, `_xlpm.x`, no implicit `@`), and a `BrtCellMeta` before a cell sets `cell_metadata`, as `cm` does. The workbook's sheet links, supporting links and names are read with the workbook part, and `Package` keeps them for its sheets. A new `Limits::binary_formula_text` (128 MiB) bounds decoded text.
3. **Shared, array and dynamic-array formulas** (gridcraft#3821, with its review fixes): `PtgExp` cells, `BrtShrFmla` and `BrtArrFmla`. See the mapping below.
4. **A shared formula stops decoding copies once one is kept as its value**: a fix for CodeRabbit's finding that is still open on gridcraft#3821, so it isn't carried over.
5. **README**: what the decoder gives, what keeps its saved result, and the new limit.
6. **Review fixes**: 468 (0x1D4) is CONVERT. The specification's table has no row for it, but Excel writes CONVERT as `PtgFunc` 0x1D4. A shared formula's tokens are borrowed from the part instead of copied. A formula kept as its value loses its cell metadata.
7. **Review fixes, round 2**: a chain of strings joined with `&` is flattened only up to the decoder's depth bound (256 strings), so a balanced tree of thousands can't become a chain that overflows the stack when printed or dropped. A first cell whose range record never comes loses its cell metadata.
8. **Excel's spelling, from a second Excel round:**
   - Spaces and line breaks typed in a formula (`PtgAttrSpace`) are kept where `.xlsx` keeps them (`1 +  2`, `SUM( A1, B1 )`), and the text is trimmed as the `.xlsx` reader trims it.
   - A number is written out in full when that takes at most 21 characters without the sign, and in scientific notation otherwise (`100000000000000000000`, `1E+21`), as Excel writes it. The decoder switched at 1E+15 and 1E-9.
   - ISO.CEILING, ECMA.CEILING, NETWORKDAYS.INTL and WORKDAY.INTL are called through hidden `_xlfn.` names in `.xlsb`, but `.xlsx` spells them without the prefix.
9. **Macro sheets and spans over chart sheets:** a reference to an XLM macro sheet (`Macro1!$A$1`) is named, since macro sheets have cells. A 3-D span with a chart sheet between its ends is spelled by its ends, as `.xlsx` has it. An end with no cells still keeps the saved result.

## How it maps onto craft-xlsx's model

- A formula's text is what the `.xlsx` reader gives for the same formula. GridCraft's reading of that text stays in GridCraft: `fmla::from_file`, the implicit `@` on legacy formulas, its parser check, and Python-cell adoption.
- **Shared formulas:** every cell of the group gets `FormulaKind::Shared` with the group's `si` (counted per sheet), and the first cell also gets the range. Unlike `.xlsx`, where the other cells have empty text, each cell here gets its own text, decoded from the shared tokens at that cell. [MS-XLSB] defines it that way, with relative offsets that wrap around the grid. Shifting the first cell's text is not exact; the review of the GridCraft PR found that. `CellFormula.text`'s doc says so.
- **Arrays:** the first cell gets `FormulaKind::Array` and its range. The other cells keep their cached values and have no formula, as in `.xlsx`. A dynamic array also has its `cell_metadata`, even across a `BrtValueMeta` written in between. Clearing the other cells, and deciding from `fDynamic` whether to spill, is the consumer's call (gridcraft#3825).
- **Kept as values:** a formula that needs something the reader doesn't read keeps only its saved result, with a warning: user defined names (XLSB names aren't read yet), table references, other workbooks, `PY(index, …)` (code stored elsewhere in the package) and data tables. So do malformed tokens or records, and formulas past the allowance. A workbook whose links can't be read opens with values only, as before.

## Changed from the GridCraft PRs

- craft-xlsx's own function table, tree and printer, instead of GridCraft's formula crate and the table and helpers shared with its `.xls` decoder.
- A single-cell dynamic-array formula is read in commit 2, where #3818 left dynamic arrays to #3821: with `cell_metadata` there is nothing more to decide.
- The test of GridCraft's 8,192-character parser limit is replaced by one showing that a shared copy may be longer than its first cell. Tests that saved to `.xlsx` with GridCraft are dropped. The rest of the PRs' tests come along in `tests/xlsb.rs`, with craft-xlsx's model in the expectations.
- `Limits` gets a new public field, `binary_formula_text`. Code that builds `Limits` with `..Limits::default()` is unaffected.

## Checked against Excel

Excel saved the same workbook (`make_probe.ps1` in the GridCraft work: refs, 3-D refs, names, shared, CSE and dynamic arrays, newer functions, LET, a table, an external link, unions and intersections, array constants) as `.xlsb` and as `.xlsx`. Read through craft-xlsx, all 33 formulas this decodes from the `.xlsb` match the `.xlsx`: same text, kind, range and shared index, with the same cell metadata. The other 5 use tables, an external link or defined names, and keep their values with those warnings.

A second, wider round (commits 8 and 9) saved three more workbooks both ways:
- 487 functions Excel accepts on a worksheet: every name in the function table except 113 macro-sheet-only commands, and about 120 newer `_xlfn.` functions, LET, LAMBDA and its helpers, GROUPBY, the REGEX functions, `TRIMRANGE` and `A1:.A5`, IMAGE, RTD, CUBEVALUE and an add-in function;
- operators and precedence, unary and percent chains, unions, intersections, whole rows and columns, 3-D references and spans, quoted and cell-like sheet names, array constants, edge-magnitude numbers, a 255-character string, unicode, errors and missing arguments, legacy and dynamic-array `@`, references to a deleted sheet, column and row;
- 246 shared-formula cells, including relative references that wrap at the grid's edges, legacy array formulas, spills, spill references and a data table;
- 60 formulas typed with spaces and line breaks, and 62 number literals around Excel's switch to scientific notation.

Before commit 8, 725 formulas matched and 20 differed. Now 744 of the 745 match, with the same text, kind, range and cell metadata, and every non-first shared-formula cell matches Excel's own `Range.Formula`. The other one is a deleted column on a sheet named like a cell (`'S3'!#REF!`). That is #1330's: it prints the sheet before `#REF!`, which this PR doesn't. The spacing and number workbooks match in full. Two inline LAMBDA calls, an add-in call and a data table keep their saved results, as described above.

## Ran locally (own target directory)

- `cargo fmt -p craft-xlsx --check`: clean
- `cargo clippy -p craft-xlsx --all-targets --all-features -- -D warnings`: clean (and `cargo clippy --workspace --all-targets -- -D warnings` after commit 9)
- `cargo test -p craft-xlsx --all-features`: 74 pass, 0 fail (after commit 7); 76 after commit 9. No other workspace crate depends on craft-xlsx.
- The new tests fail without their commit's code: 5 of 6 for commit 3 (the sixth checks that unreadable shared formulas keep their values, which commit 2 already does), and 1 for commit 4. The tests for commits 8 and 9 fail without them.

## For the coordinator

Once this is merged, gridcraft#3810, #3818 and #3821 can be closed, each with a note like "Ported to craft-xlsx in storytold/craft-libs#1166; GridCraft gets it when it switches to craft-xlsx." GridCraft's remainder is the mapping. That means `from_file` and the implicit `@` (as for `.xlsx`), Python cells, clearing array cells, spilling dynamic arrays, the `xlsb-import.md` / `gaps.md` / `file-format-parity.md` notes and the engine's use of `read_xlsb_with`. I'll redo those against the switch.

<!-- This is an auto-generated comment: release notes by coderabbit.ai -->

## Summary by CodeRabbit

* **New Features**
  * Binary Excel workbooks now display decoded formula text in familiar spreadsheet notation, including shared and array formulas.
  * Shared-formula cells show formula text adjusted to their own cell references. Array-formula follower cells do not display separate formula text.
* **Bug Fixes**
  * When formulas cannot be decoded or exceed supported limits, cells retain their saved results; a warning may be provided.
* **Documentation**
  * Clarified formula display behavior and documented limits on formula text, token length, nesting depth, and array constants.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
2026-11-15 12:11:39 +01:00
kiwi4boy aa622a2e20 Merge branch 'xlsb-formulas' into xlsb-styles
# Conflicts:
#	crates/xlsx/tests/xlsb.rs
2026-11-14 13:32:25 -05:00
kiwi4boy 24e6266119 craft-xlsx: review fixes: spaced string chains flatten, module sheets and supporting links are capped
- literal_texts now accepts a spaced operand as literal_text does, and the
  chain flattens with the spacing kept on its strings, so a chain the Python
  check accepts is written flat ("x"& "="&"1", not "x"&( "="&"1")).
- Every BrtBundleSh counts toward the 1,024-sheet cap, a skipped module
  sheet too, since each keeps a place in the sheet links.
- Supporting links are capped at 65,536; past it the links aren't read and
  formulas keep their saved results.
2026-11-14 13:27:25 -05:00
kiwi4boy 88287a6b46 craft-xlsx: review fixes: styles caps are too large, differential format strings are charged
- A styles table past 65,536 entries, or a gradient past 1,024 stops, is past
  a fixed cap: Error::TooLarge, as the error's contract and the other caps
  have it, not a damaged part that is skipped with a warning.
- A differential format's font name and number format are charged to
  binary_text, as the other string-bearing style records are.
2026-11-14 12:40:55 -05:00
kiwi4boy 14e516edf4 Merge branch 'xlsb-formulas' into xlsb-styles 2026-11-14 12:36:13 -05:00
kiwi4boy fa5457bed6 craft-xlsx: review fixes: array constants bounded per formula, a spent allowance skips decoding
- A formula's array constants share one allowance of 65,536 values, each
  array charged before its rows are allocated. Before, the cap was per
  array, so a formula of many arrays could hold gigabytes before the formula
  text allowance was checked.
- Once binary_formula_text is spent, a formula is not decoded only to be
  dropped: it keeps its saved result straight away.
2026-11-14 12:35:54 -05:00
kiwi4boy 259afde541 Merge branch 'xlsb-formulas' into xlsb-styles
# Conflicts:
#	crates/xlsx/README.md
#	crates/xlsx/tests/xlsb.rs
2026-11-14 12:04:49 -05:00
kiwi4boy 5742279729 craft-xlsx: binary formulas name macro sheets and span chart sheets
An Excel probe showed two references the decoder refused that .xlsx spells:

- A reference to an XLM macro sheet (Macro1!$A$1): macro sheets have cells,
  so the sheet links now name them.
- A 3-D span with a chart sheet between its ends ('Data:After Sheet'!$A$1):
  a span is spelled by its ends, as .xlsx has it. An end with no cells is
  still refused.
2026-11-14 12:01:46 -05:00
kiwi4boy abceed3f17 craft-xlsx: binary formulas keep typed spacing and Excel's number spelling
Checked against a wider Excel probe (every worksheet function Excel
accepts, operators, references, constants, spacing, shared and array
formulas), three differences from the .xlsx text are fixed:

- PtgAttrSpace: the spaces and line breaks typed in a formula are kept
  where Excel writes them in .xlsx (before an operand, an operator's
  symbol or a call, after a parenthesis's or call's opening and before its
  closing), and the text is trimmed as the .xlsx reader trims it.
- Numbers are written out in full when that takes at most 21 characters
  (100000000000000000000, 0.0000000000000000001), scientific past that
  (1E+21, 1.5E-19, 1.23456789012345E-06), as Excel spells them.
- ISO.CEILING, ECMA.CEILING, NETWORKDAYS.INTL and WORKDAY.INTL are called
  through hidden _xlfn. names in .xlsb, but .xlsx names them bare.
2026-11-14 11:56:51 -05:00
kiwi4boy d2b6416db9 craft-xlsx: binary styles: legacy number formats, automatic font colours, tinted fills
A broader Excel probe found three differences from the styles.xml Excel
writes for the same workbook:

- A number format with a newer locale tag ([$-ja-JP-x-gannen]) is only in
  alternate content: the newer spelling in a block for later versions, and
  the one .xlsx keeps as formatCode in a block listing version 12 onwards.
  The styles part now reads the alternate content meant for Excel 2007
  (version 12), so the format is no longer lost.
- A font whose colour is automatic has no <color> in .xlsx.
- A pattern fill whose pattern colour has a tint states the system
  background (bgColor indexed 65), as Excel's .xlsx does for any pattern.
2026-11-14 11:32:40 -05:00
kiwi4boy 3e957e0fd1 craft-xlsx: read the styles part of a binary workbook
Package::styles() reads styles.bin into the same Styles the XML part
gives: number formats, fonts, fills, borders, cell and cell style
formats, cell styles, differential formats and indexed colours, spelled
as Excel writes them in styles.xml. A damaged part is a warning and no
styles; each table holds at most 65,536 entries.

Closes #1253.
2026-11-13 23:35:18 -05:00
kiwi4boy fd8a0dcf22 craft-xlsx: review fixes: a long string chain stays within the depth bound; pending array metadata
From the second review round (FredApps):

- Strings joined with `&` are printed as one flat chain, which nests one level per string. A
  balanced tree of 4,096 empty strings fits in 16,383 token bytes and is 13 levels deep, but as a
  chain it was 4,096 levels, and printing and dropping it recurse: on a 256 KiB stack it
  overflowed. The chain is now made only up to MAX_DEPTH strings, the bound push keeps on the
  decoded tree (Excel's 8,192 characters hold at most about 33 full-length constants, so Python
  code split into constants is unaffected). A longer one prints as its tokens nest, with the
  parentheses that needs. GridCraft's tree walks a left-deep chain in a loop; the printer copied
  from craft-xls recurses, which is how the port lost the bound.
- The first cell of a shared or array formula whose BrtShrFmla/BrtArrFmla never comes (another
  cell or the next row follows) loses its cell metadata too, as a formula kept as its value does.

The new unit test overflowed its stack without this commit; the extended metadata test fails
without it. The Excel-saved workbook still reads with all 33 formulas as in its .xlsx.
2026-11-13 19:12:02 -05:00
Dylan M. Taylor 6d0b33c0cd Read conventional XLSX shared strings without a relationship 2026-11-13 22:11:05 +00:00
kiwi4boy 79b4fd0144 craft-xlsx: review fixes: CONVERT, shared formula tokens borrowed, cell metadata with its formula
From the first review round:

- 468 (0x1D4) is CONVERT, with 3 arguments. [MS-XLSB]'s Ftab table has no row for it, though
  its grammar lists convert-params among the fixed-argument functions; Excel writes
  =CONVERT(1,"m","ft") in .xlsb as a PtgFunc calling 0x1D4 (observed in Excel). It was the only
  unassigned number from 0x17C to 0x1E4. The module doc says it isn't the specification's row.
- A BrtShrFmla's tokens and extra data are borrowed from the worksheet part instead of copied: a
  record may claim up to 256 MiB, and each shared formula is kept for the rest of the sheet, so
  the copies could cost as much again as the part. BrtArrFmla's are used at once and borrowed too.
- A formula record's cell metadata goes with its formula: when the formula is kept as its value
  (tokens the reader can't decode, an unreadable BrtArrFmla), the cell loses its `cm`, which
  would otherwise mark a dynamic-array formula that isn't there. A value cell keeps its cell
  metadata, as the file has it.

The CONVERT and cell-metadata tests fail without this commit. The Excel-saved workbook still
reads with all 33 formulas as in its .xlsx.
2026-11-13 00:04:32 -05:00
kiwi4boy 20050077ad craft-xlsx: the README describes formulas in binary workbooks
They were "token streams that are not decoded". The README now says what the decoder gives
(text in the file's spelling, shared and array kinds and ranges, cell metadata, each shared copy's
own text), what keeps its saved result and why, that the function table and printer are this
crate's own, and the binary_formula_text limit with the decoder's fixed bounds.
2026-11-12 23:36:47 -05:00
kiwi4boy 1f5f1f0f51 craft-xlsx: a shared formula stops decoding copies once one is kept as its value
From gridcraft#3821's review (CodeRabbit, still open there): a shared formula's copies are
checked against the formula text allowance with the first cell's length, which a copy can
exceed. A copy that was decoded and printed, then kept as its value because it didn't fit, or
because it couldn't be decoded, charged nothing, so a file with many cells of one long shared
formula could repeat that work for each of them. The PR's case was GridCraft's 8,192-character
rejection, which isn't here; the allowance and decode failures are the same path.

After one such copy the group keeps every later copy as its value without decoding it, so a
group costs at most one wasted decode. A new test shows a later copy that would have fit kept
as its value; it fails without this commit.
2026-11-12 23:36:18 -05:00
kiwi4boy 734ade8cd9 craft-xlsx: read shared, array and dynamic-array formulas from .xlsb files (port of gridcraft#3821)
A cell whose tokens are only PtgExp (row) + PtgExtraCol (column) belongs to the shared or array
formula starting there; its first cell is followed by BrtShrFmla or BrtArrFmla.

- Shared formulas: each cell's copy is decoded from the shared tokens at its own cell, as
  [MS-XLSB] defines it (PtgRefN/PtgAreaN offsets, wrapping around the grid). Every cell of the
  group gets FormulaKind::Shared, its own text and the group's index (`si`, counted per sheet);
  the first also gets the group's range. Its first cell is the first that uses it, anywhere in
  its range. Copies are charged to the formula text allowance before they are decoded, so a long
  formula shared by a million cells stops costing once the allowance is spent.
- Ctrl+Shift+Enter and dynamic arrays: the first cell gets FormulaKind::Array with its range; a
  dynamic one also has its cell metadata (BrtCellMeta, which now also holds across a BrtValueMeta
  written in between), as `cm` marks it in .xlsx. The other cells of an array keep their cached
  values and have no formula, as in .xlsx.
- A record that can't be read leaves its range as values and never fails the file, with a
  warning; so does a first cell with no formula record after it.

Ported from storytold/gridcraft#3821 (issue gridcraft#3806), with its review fixes (each copy
decoded at its own cell; a shared formula may start inside its range). Changed from the
GridCraft PR:
- In .xlsx a shared formula's other cells have empty text. Here they have their own decoded text
  (and CellFormula's doc says so), because that is exact where shifting the first cell's text is
  not, as the PR's review found.
- Clearing an array's other cells for recalculation, marking dynamic arrays to spill, and the
  check against GridCraft's parser's 8,192-character limit are GridCraft's reading, not the
  file's: the cells keep what the file holds. That test becomes one that a copy may be longer
  than its first cell.
The PR's tests come along in tests/xlsb.rs, with craft-xlsx's model in the expectations.

Checked against Excel: in a workbook Excel saved both as .xlsb and as .xlsx, every formula this
reads (33, shared, array and dynamic ones included) has the .xlsx text, kind and range; the other
5 use tables, an external link or defined names.
2026-11-12 23:34:15 -05:00
kiwi4boy 787b3e44f4 craft-xlsx: read cell formulas from .xlsb files (port of gridcraft#3818)
A BIFF12 decoder for cell formulas (xlsb/formula.rs), separate from craft-xls's BIFF8 one because
nearly every operand differs (32-bit rows, 14-bit columns, UTF-16 strings, its own array-constant
codes, newer functions called through hidden names). It reads references, 3-D references,
constants, array constants, functions by number (xlsb/ftab.rs) and newer functions through
Excel's hidden _xlfn. names. A formula cell's CellFormula holds the text as an .xlsx file holds it
(`_xlfn.CONCAT`, `_xlpm.x`, no implicit `@`), and a BrtCellMeta before a cell gives it
cell_metadata, as `cm` does. Reverse-Polish tokens group by order alone, so the decoded tree
gets the parentheses its text needs from operator precedence; Excel's own text is unchanged. A
chain of string constants joined with & prints as one flat chain.

What a formula refers to must be readable too, so shared, array and data-table forms, user
defined names (XLSB names aren't read yet), table references, external links and PY(index, ...)
(code stored elsewhere in the package) keep only their saved results, with a warning saying why.
So does a formula past Limits::binary_formula_text (128 MiB of text over the workbook). The
workbook's links and names are optional: if they can't be read, the file opens with values only,
as before, and a warning says so.

Ported from storytold/gridcraft#3818 (issue gridcraft#3806), with its two review fixes
(grouping by precedence, the flat & chain). Changed from the GridCraft PR:
- The tree and its A1 printer (xlsb/expr.rs) are a copy of craft-xls's expr.rs, with
  BinOp::precedence added; the decoder's stack and depth guards are copies of craft-xls's. The
  PR used GridCraft's formula crate and shared these with GridCraft's .xls decoder.
- No fmla::from_file, implicit `@`, parse check or Python-cell adoption: those are GridCraft's
  reading of the text, not the file's. A single-cell dynamic-array formula is read (with its
  cell metadata) instead of being kept as its value; the PR left dynamic arrays to the next PR.
- The links are read with the workbook part and kept by Package for its sheets.
Its tests come along in tests/xlsb.rs, with the expected text in the file's spelling.

Checked against Excel: of the formulas in a workbook Excel saved both as .xlsb and as .xlsx,
every one this reads (26) has the text of the .xlsx; the other 12 are the kinds above.
2026-11-12 23:29:29 -05:00
kiwi4boy 1bdaa7aff3 craft-xlsx: the XLSB function table, with the numbers 0x17C-0x1E4 (port of gridcraft#3810)
[MS-XLSB]'s Ftab (2.5.98.10) continues the [MS-XLS] table from 0x17C: the cube functions, the old
Analysis ToolPak functions, IFERROR, COUNTIFS, SUMIFS and AVERAGEIF(S). Excel writes these by
number in .xlsb (PtgFunc / PtgFuncVar) where .xls calls them by name, so an XLSB formula decoder
needs them. Generated from the spec with the same argument-count rule as the existing entries.

Ported from storytold/gridcraft#3810 (issue gridcraft#3806). There the entries were appended to
GridCraft's .xls table, which is now craft-xls's. Here the table is craft-xlsx's own
(xlsb/ftab.rs): craft-xls's 0-379, which match GridCraft's table before the PR, then the PR's
entries. The two formats follow separate specifications and develop separately; they can share a
table later if both readers settle on one. The PR's table checks come along. Its decoding checks
(IFERROR, SUMIFS by number) go with the decoder in the next commit, and its check that every new
name is a GridCraft function stays in GridCraft.
2026-11-12 23:23:02 -05:00
Dylan M. Taylor 7dcc9950a1 craft-xlsx: pictures in cells and dynamic-array metadata
craft-xlsx: pictures in cells and dynamic-array metadata

* craft-xlsx: read parts with canonical prefixes so kept trees can be written back

The part layer read every part by local name, so extLst children (x14:, xr:, xm:),
mc:AlternateContent and r:id lost their namespaces and could not be written back.
Parts are now read with one fixed prefix per namespace (the main namespace unprefixed),
mc:Ignorable and mc:Choice/@Requires are rewritten to match, and ns::declare prepares a
kept tree for writing. craft-xml: a namespace listed with the empty prefix reads unprefixed.

* craft-xlsx: write SpreadsheetML workbooks (Document read and write)

Document holds a whole workbook: the workbook part, shared strings, styles, each worksheet's
rows and the rest of its part, and every other part kept as bytes. write regenerates the
workbook part, worksheets, shared strings and styles from the model, keeps unknown children
in place (schema order for regenerated ones), keeps part names and relationship ids, and
writes kept parts unchanged. Writers: Styles::to_xml and to_el for each table entry,
StringItem::to_el (phonetic runs checked as on reading), SheetPart::to_xml with rows
streamed, Workbook::to_el, XlsxKind. Row and DefinedName keep their other attributes;
CellStyle reads iLevel. craft-opc: LazyPackage::canonical gives a part's stored name.

* craft-xlsx: typed worksheet features and comments, written back

SheetPart::features lifts sheet views, print setup, data validation, conditional formats,
hyperlinks and the legacy drawing into types that mirror their elements (optional attributes,
unnamed ones kept) and writes them in schema order. Comments come from the comments part,
note shapes from the VML drawing; a sheet that gains comments without a VML drawing gets one.
A hyperlink to a new URL gets its own relationship. craft-sheet: Range derives Default.

* craft-xlsx: drawings, charts and the theme on craft-drawingml

Drawing reads a sheet's xdr:wsDr into anchors with typed placements and objects kept as
written; Anchor gives the object's kind, properties, chart or image relationship and xfrm.
Package::drawing, Package::chart (c: and cx: parts through craft-drawingml) and
Package::theme. Document worksheets hold their drawing part, regenerated with its
relationships kept by id; add_chart and add_picture add new chart parts (chartEx behind
mc:AlternateContent) and images with their anchors. More drawing namespaces get prefixes
(a16, asvg, aink, am3d, cx1-cx4, dgm).

* craft-xlsx: tables (ListObjects) read and written back

Table mirrors CT_Table: every attribute, columns with calculated and totals formulas, the
style info, autoFilter/sortState/extensions kept as written. Package::tables reads a sheet's
table parts; Document worksheets hold them as TableParts, regenerated with their
relationships and tableParts entries. Part names a document keeps are reserved before new
parts are named, so a new part never takes a name a later sheet keeps.

* craft-xlsx: PivotTables (caches, records, tables) read and written

Typed pivot cache definitions (source, fields, shared items, grouping),
streamed cache records and PivotTable definitions (location, fields and
items, axes, page and data fields, style), with every unmodelled child
and attribute kept. Workbook::pivot_caches lifts pivotCaches. A Document
holds caches and tables and regenerates their parts, relationships and
pivotCaches entries; an OLAP cache or a table on one stays a kept part.
SharedItems::describe gives Excel's shared-item flags and records_xml
writes a records part, after GridCraft's pivot writer.

* craft-xlsx: pictures in cells and dynamic-array metadata

Package::cell_pictures follows a cell's vm through the value and future
metadata to its _localImage rich value and image, bounded and lenient as
GridCraft's richdata.rs reads it. Document::add_cell_metadata writes the
metadata part (XLDAPR for dynamic arrays, XLRICHVALUE for pictures), the
rich-value parts and the images as GridCraft writes them.
2026-11-11 22:44:39 -05:00
Dylan M. Taylor d1f10a9612 craft-xlsx: PivotTables (caches, records, tables) read and written (#1074)
* craft-xlsx: read parts with canonical prefixes so kept trees can be written back

The part layer read every part by local name, so extLst children (x14:, xr:, xm:),
mc:AlternateContent and r:id lost their namespaces and could not be written back.
Parts are now read with one fixed prefix per namespace (the main namespace unprefixed),
mc:Ignorable and mc:Choice/@Requires are rewritten to match, and ns::declare prepares a
kept tree for writing. craft-xml: a namespace listed with the empty prefix reads unprefixed.

* craft-xlsx: write SpreadsheetML workbooks (Document read and write)

Document holds a whole workbook: the workbook part, shared strings, styles, each worksheet's
rows and the rest of its part, and every other part kept as bytes. write regenerates the
workbook part, worksheets, shared strings and styles from the model, keeps unknown children
in place (schema order for regenerated ones), keeps part names and relationship ids, and
writes kept parts unchanged. Writers: Styles::to_xml and to_el for each table entry,
StringItem::to_el (phonetic runs checked as on reading), SheetPart::to_xml with rows
streamed, Workbook::to_el, XlsxKind. Row and DefinedName keep their other attributes;
CellStyle reads iLevel. craft-opc: LazyPackage::canonical gives a part's stored name.

* craft-xlsx: typed worksheet features and comments, written back

SheetPart::features lifts sheet views, print setup, data validation, conditional formats,
hyperlinks and the legacy drawing into types that mirror their elements (optional attributes,
unnamed ones kept) and writes them in schema order. Comments come from the comments part,
note shapes from the VML drawing; a sheet that gains comments without a VML drawing gets one.
A hyperlink to a new URL gets its own relationship. craft-sheet: Range derives Default.

* craft-xlsx: drawings, charts and the theme on craft-drawingml

Drawing reads a sheet's xdr:wsDr into anchors with typed placements and objects kept as
written; Anchor gives the object's kind, properties, chart or image relationship and xfrm.
Package::drawing, Package::chart (c: and cx: parts through craft-drawingml) and
Package::theme. Document worksheets hold their drawing part, regenerated with its
relationships kept by id; add_chart and add_picture add new chart parts (chartEx behind
mc:AlternateContent) and images with their anchors. More drawing namespaces get prefixes
(a16, asvg, aink, am3d, cx1-cx4, dgm).

* craft-xlsx: tables (ListObjects) read and written back

Table mirrors CT_Table: every attribute, columns with calculated and totals formulas, the
style info, autoFilter/sortState/extensions kept as written. Package::tables reads a sheet's
table parts; Document worksheets hold them as TableParts, regenerated with their
relationships and tableParts entries. Part names a document keeps are reserved before new
parts are named, so a new part never takes a name a later sheet keeps.

* craft-xlsx: PivotTables (caches, records, tables) read and written

Typed pivot cache definitions (source, fields, shared items, grouping),
streamed cache records and PivotTable definitions (location, fields and
items, axes, page and data fields, style), with every unmodelled child
and attribute kept. Workbook::pivot_caches lifts pivotCaches. A Document
holds caches and tables and regenerates their parts, relationships and
pivotCaches entries; an OLAP cache or a table on one stays a kept part.
SharedItems::describe gives Excel's shared-item flags and records_xml
writes a records part, after GridCraft's pivot writer.
2026-11-11 22:13:49 -05:00
Dylan M. Taylor a19cf6753b craft-xlsx: tables (ListObjects) read and written back (#1062)
* craft-xlsx: read parts with canonical prefixes so kept trees can be written back

The part layer read every part by local name, so extLst children (x14:, xr:, xm:),
mc:AlternateContent and r:id lost their namespaces and could not be written back.
Parts are now read with one fixed prefix per namespace (the main namespace unprefixed),
mc:Ignorable and mc:Choice/@Requires are rewritten to match, and ns::declare prepares a
kept tree for writing. craft-xml: a namespace listed with the empty prefix reads unprefixed.

* craft-xlsx: write SpreadsheetML workbooks (Document read and write)

Document holds a whole workbook: the workbook part, shared strings, styles, each worksheet's
rows and the rest of its part, and every other part kept as bytes. write regenerates the
workbook part, worksheets, shared strings and styles from the model, keeps unknown children
in place (schema order for regenerated ones), keeps part names and relationship ids, and
writes kept parts unchanged. Writers: Styles::to_xml and to_el for each table entry,
StringItem::to_el (phonetic runs checked as on reading), SheetPart::to_xml with rows
streamed, Workbook::to_el, XlsxKind. Row and DefinedName keep their other attributes;
CellStyle reads iLevel. craft-opc: LazyPackage::canonical gives a part's stored name.

* craft-xlsx: typed worksheet features and comments, written back

SheetPart::features lifts sheet views, print setup, data validation, conditional formats,
hyperlinks and the legacy drawing into types that mirror their elements (optional attributes,
unnamed ones kept) and writes them in schema order. Comments come from the comments part,
note shapes from the VML drawing; a sheet that gains comments without a VML drawing gets one.
A hyperlink to a new URL gets its own relationship. craft-sheet: Range derives Default.

* craft-xlsx: drawings, charts and the theme on craft-drawingml

Drawing reads a sheet's xdr:wsDr into anchors with typed placements and objects kept as
written; Anchor gives the object's kind, properties, chart or image relationship and xfrm.
Package::drawing, Package::chart (c: and cx: parts through craft-drawingml) and
Package::theme. Document worksheets hold their drawing part, regenerated with its
relationships kept by id; add_chart and add_picture add new chart parts (chartEx behind
mc:AlternateContent) and images with their anchors. More drawing namespaces get prefixes
(a16, asvg, aink, am3d, cx1-cx4, dgm).

* craft-xlsx: tables (ListObjects) read and written back

Table mirrors CT_Table: every attribute, columns with calculated and totals formulas, the
style info, autoFilter/sortState/extensions kept as written. Package::tables reads a sheet's
table parts; Document worksheets hold them as TableParts, regenerated with their
relationships and tableParts entries. Part names a document keeps are reserved before new
parts are named, so a new part never takes a name a later sheet keeps.
2026-11-11 22:09:08 -05:00
Dylan M. Taylor 1acdb0dd68 craft-xlsx: drawings, charts and theme on craft-drawingml (#1058)
* craft-xlsx: read parts with canonical prefixes so kept trees can be written back

The part layer read every part by local name, so extLst children (x14:, xr:, xm:),
mc:AlternateContent and r:id lost their namespaces and could not be written back.
Parts are now read with one fixed prefix per namespace (the main namespace unprefixed),
mc:Ignorable and mc:Choice/@Requires are rewritten to match, and ns::declare prepares a
kept tree for writing. craft-xml: a namespace listed with the empty prefix reads unprefixed.

* craft-xlsx: write SpreadsheetML workbooks (Document read and write)

Document holds a whole workbook: the workbook part, shared strings, styles, each worksheet's
rows and the rest of its part, and every other part kept as bytes. write regenerates the
workbook part, worksheets, shared strings and styles from the model, keeps unknown children
in place (schema order for regenerated ones), keeps part names and relationship ids, and
writes kept parts unchanged. Writers: Styles::to_xml and to_el for each table entry,
StringItem::to_el (phonetic runs checked as on reading), SheetPart::to_xml with rows
streamed, Workbook::to_el, XlsxKind. Row and DefinedName keep their other attributes;
CellStyle reads iLevel. craft-opc: LazyPackage::canonical gives a part's stored name.

* craft-xlsx: typed worksheet features and comments, written back

SheetPart::features lifts sheet views, print setup, data validation, conditional formats,
hyperlinks and the legacy drawing into types that mirror their elements (optional attributes,
unnamed ones kept) and writes them in schema order. Comments come from the comments part,
note shapes from the VML drawing; a sheet that gains comments without a VML drawing gets one.
A hyperlink to a new URL gets its own relationship. craft-sheet: Range derives Default.

* craft-xlsx: drawings, charts and the theme on craft-drawingml

Drawing reads a sheet's xdr:wsDr into anchors with typed placements and objects kept as
written; Anchor gives the object's kind, properties, chart or image relationship and xfrm.
Package::drawing, Package::chart (c: and cx: parts through craft-drawingml) and
Package::theme. Document worksheets hold their drawing part, regenerated with its
relationships kept by id; add_chart and add_picture add new chart parts (chartEx behind
mc:AlternateContent) and images with their anchors. More drawing namespaces get prefixes
(a16, asvg, aink, am3d, cx1-cx4, dgm).
2026-11-11 21:59:45 -05:00
Dylan M. Taylor 7b936bf293 craft-xlsx: typed worksheet features (views, print, validation, conditional formats, hyperlinks, comments) (#1048)
* craft-xlsx: read parts with canonical prefixes so kept trees can be written back

The part layer read every part by local name, so extLst children (x14:, xr:, xm:),
mc:AlternateContent and r:id lost their namespaces and could not be written back.
Parts are now read with one fixed prefix per namespace (the main namespace unprefixed),
mc:Ignorable and mc:Choice/@Requires are rewritten to match, and ns::declare prepares a
kept tree for writing. craft-xml: a namespace listed with the empty prefix reads unprefixed.

* craft-xlsx: write SpreadsheetML workbooks (Document read and write)

Document holds a whole workbook: the workbook part, shared strings, styles, each worksheet's
rows and the rest of its part, and every other part kept as bytes. write regenerates the
workbook part, worksheets, shared strings and styles from the model, keeps unknown children
in place (schema order for regenerated ones), keeps part names and relationship ids, and
writes kept parts unchanged. Writers: Styles::to_xml and to_el for each table entry,
StringItem::to_el (phonetic runs checked as on reading), SheetPart::to_xml with rows
streamed, Workbook::to_el, XlsxKind. Row and DefinedName keep their other attributes;
CellStyle reads iLevel. craft-opc: LazyPackage::canonical gives a part's stored name.

* craft-xlsx: typed worksheet features and comments, written back

SheetPart::features lifts sheet views, print setup, data validation, conditional formats,
hyperlinks and the legacy drawing into types that mirror their elements (optional attributes,
unnamed ones kept) and writes them in schema order. Comments come from the comments part,
note shapes from the VML drawing; a sheet that gains comments without a VML drawing gets one.
A hyperlink to a new URL gets its own relationship. craft-sheet: Range derives Default.
2026-11-11 21:07:34 -05:00
Dylan M. Taylor ae085a2f7e craft-xlsx: write SpreadsheetML workbooks (Document read/write) (#1041)
* craft-xlsx: read parts with canonical prefixes so kept trees can be written back

The part layer read every part by local name, so extLst children (x14:, xr:, xm:),
mc:AlternateContent and r:id lost their namespaces and could not be written back.
Parts are now read with one fixed prefix per namespace (the main namespace unprefixed),
mc:Ignorable and mc:Choice/@Requires are rewritten to match, and ns::declare prepares a
kept tree for writing. craft-xml: a namespace listed with the empty prefix reads unprefixed.

* craft-xlsx: write SpreadsheetML workbooks (Document read and write)

Document holds a whole workbook: the workbook part, shared strings, styles, each worksheet's
rows and the rest of its part, and every other part kept as bytes. write regenerates the
workbook part, worksheets, shared strings and styles from the model, keeps unknown children
in place (schema order for regenerated ones), keeps part names and relationship ids, and
writes kept parts unchanged. Writers: Styles::to_xml and to_el for each table entry,
StringItem::to_el (phonetic runs checked as on reading), SheetPart::to_xml with rows
streamed, Workbook::to_el, XlsxKind. Row and DefinedName keep their other attributes;
CellStyle reads iLevel. craft-opc: LazyPackage::canonical gives a part's stored name.
2026-11-11 21:01:51 -05:00
Dylan M. Taylor 34aa8c1cfd craft-xlsx: read parts with canonical prefixes so kept trees can be written back (#1031)
The part layer read every part by local name, so extLst children (x14:, xr:, xm:),
mc:AlternateContent and r:id lost their namespaces and could not be written back.
Parts are now read with one fixed prefix per namespace (the main namespace unprefixed),
mc:Ignorable and mc:Choice/@Requires are rewritten to match, and ns::declare prepares a
kept tree for writing. craft-xml: a namespace listed with the empty prefix reads unprefixed.
2026-11-11 20:46:37 -05:00
Dylan M. Taylorandkiwi4boy 119415f46f Add craft-xlsx: XLSX and XLSB part layer (workbook, strings, styles, streamed rows) (#976)
* Add craft-sheet: the cell positions, values and tables the spreadsheet formats share

craft-xls carried its own CellRef, Range, Value, CellError, Visibility, sheet-name
quoting, built-in number format table and indexed palette. craft-xlsx and craft-ods
need the same ones, so they move to a crate with no dependencies and craft-xls
re-exports them: an application gets one Value and one CellRef whichever file it read.

Added on the way: A1 parsing (CellRef::parse, Range::parse), Range::count and a1,
CellError::parse and the newer error values SpreadsheetML stores as text,
builtin_format_id for writers.

* Add craft-xlsx: the part layer of XLSX and XLSB workbooks

Package::open finds the workbook part through craft-opc and reads the workbook
part, shared strings (runs and phonetic readings), the styles tables as indexed
tables, and a worksheet's rows one at a time with the rest of the part as a tree.
Binary workbooks give the same workbook, strings, rows and merged cells from their
records. Every other part stays reachable through Package::opc.

From GridCraft crates/xlsx (7e0d96d7): read.rs, sheet_read.rs, styles.rs, xml.rs
(string items, xstring escapes), xlsb.rs and its tests, split from GridCraft's
document model.

* craft-xlsx: XLSB opens up to 4 million cells, records counted once over the workbook

Binary workbooks over 1 million cells were refused, a quarter of what .xls allows,
and an allowance of 5 million records per part refused ordinary files: Excel writes
four records per non-empty row besides the cells, and one BrtCellBlank for every
formatted empty cell. Cells are now 4 million over the workbook (also the most
shared strings), text 256 MiB, and records 40 million for every part together, as
in craft-xls.

Ported from storytold/gridcraft#3807.

---------

Co-authored-by: kiwi4boy <kiwi4boy@gmail.com>
2026-11-11 19:32:04 -05:00