Compare commits

...
Author SHA1 Message Date
Dylan M. Taylor 7e4235c85b Merge pull request #4399 from storytold/dot/shared-xstring-20261117
xlsx: share SpreadsheetML string reader/writer codec (cutover stage 1)
2026-11-16 20:00:52 -05:00
Dylan M. Taylor ef87aaa590 test(xlsx): retain XML predicate for escaping oracle 2026-11-16 19:45:33 -05:00
Dylan M. Taylor 4ebc9a5127 Merge remote-tracking branch 'origin/main' into dot/shared-xstring-20261117 2026-11-16 19:44:21 -05:00
Dylan M. Taylor fc7698eb11 Merge pull request #4383 from Hamza0101/fix/table-hidden-total-row-keeps-calc
XLSX: a hidden Total Row keeps its calculations
2026-11-16 19:43:58 -05:00
Dylan M. Taylor 058ea183ec Merge pull request #4382 from Hamza0101/fix/xlsx-first-page-number
XLSX: keep Page Setup's first page number
2026-11-16 19:43:34 -05:00
Dylan M. Taylor faef1a06c8 xlsx: use shared SpreadsheetML string codec in reader and writer 2026-11-16 19:40:39 -05:00
Hamza 8d8716cdc0 XLSX: a hidden Total Row keeps its calculations
A table whose Total Row was turned off still holds each column's total:
Excel writes totalsRowFunction, totalsRowLabel and a custom
totalsRowFormula without totalsRowCount, and restores them when the row
is turned back on. The reader took them, but the writer wrote them only
while the row was shown, so a save lost a custom formula or an Average
and Excel brought back SUBTOTAL(109,...) instead. They are now written
whether the row is shown or not.

Fixes #4296
2026-11-16 20:10:00 +05:00
Hamza 496c13e7b4 XLSX: keep Page Setup's first page number
A sheet set to First page number 7 has pageSetup firstPageNumber="7"
useFirstPageNumber="1"; neither attribute was read, so a save reset it
to Automatic. PrintSettings now holds it (None for Automatic), the
reader takes the number when useFirstPageNumber is on, and the writer
writes both in the schema's order. A JSON workbook leaves it out when
Automatic, so existing files are written as before.

Fixes #4293
2026-11-16 20:04:07 +05:00
10 changed files with 211 additions and 87 deletions
Generated
+24
View File
@@ -932,6 +932,17 @@ dependencies = [
"thiserror 2.0.21",
]
[[package]]
name = "craft-drawingml"
version = "0.1.0"
source = "git+https://github.com/storytold/craft-libs?rev=bb57d422d0bc842cbde430955825553ab7b976f4#bb57d422d0bc842cbde430955825553ab7b976f4"
dependencies = [
"craft-xml",
"kurbo",
"log",
"serde",
]
[[package]]
name = "craft-fonts-build"
version = "0.1.0"
@@ -1127,6 +1138,18 @@ dependencies = [
"thiserror 2.0.21",
]
[[package]]
name = "craft-xlsx"
version = "0.1.0"
source = "git+https://github.com/storytold/craft-libs?rev=bb57d422d0bc842cbde430955825553ab7b976f4#bb57d422d0bc842cbde430955825553ab7b976f4"
dependencies = [
"craft-drawingml",
"craft-opc",
"craft-sheet",
"craft-xml",
"thiserror 2.0.21",
]
[[package]]
name = "craft-xml"
version = "0.1.0"
@@ -2379,6 +2402,7 @@ dependencies = [
"craft-offcrypto",
"craft-opc",
"craft-xls",
"craft-xlsx",
"craft-xml",
"gridcraft-core",
"gridcraft-formula",
+2
View File
@@ -44,6 +44,8 @@ craft-csv = { git = "https://github.com/storytold/craft-libs", rev = "bb57d422d0
# The native JSON workbook (`.json`, `.scjson`): read, written, and kept newer macros written back.
craft-gridcraft-format = { git = "https://github.com/storytold/craft-libs", rev = "9a6d894200221fcfedc274870c30394d404f859d", version = "0.1.0" }
# Excel 97-2003 (.xls, BIFF8) workbooks; `crates/xlsx/src/xls.rs` maps them onto the model.
# SpreadsheetML string encoding/decoding; workbook model mapping stays in gridcraft-xlsx.
craft-xlsx = { git = "https://github.com/storytold/craft-libs", rev = "bb57d422d0bc842cbde430955825553ab7b976f4", version = "0.1.0" }
craft-xml = { git = "https://github.com/storytold/craft-libs", rev = "bb57d422d0bc842cbde430955825553ab7b976f4", version = "0.1.0" }
craft-xls = { git = "https://github.com/storytold/craft-libs", rev = "bb57d422d0bc842cbde430955825553ab7b976f4", version = "0.1.0" }
+19
View File
@@ -53,6 +53,11 @@ pub struct PrintSettings {
/// sheet is more than one page wide and tall.
#[serde(default)]
pub page_order: PageOrder,
/// Page Setup › Page › First page number: the number the sheet's first printed page takes,
/// or `None` for Automatic (XLSX `pageSetup firstPageNumber` with `useFirstPageNumber`). Left
/// out of a JSON workbook when Automatic, so files without it are written as before.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub first_page_number: Option<u32>,
}
fn yes() -> bool {
@@ -187,6 +192,7 @@ impl Default for PrintSettings {
hf_scale_with_doc: true,
hf_align_with_margins: true,
page_order: PageOrder::DownThenOver,
first_page_number: None,
}
}
}
@@ -281,4 +287,17 @@ mod tests {
p = serde_json::from_value(saved).unwrap();
assert_eq!(p, PrintSettings::default());
}
#[test]
fn first_page_number_is_saved_only_when_set() {
// Automatic writes nothing, so a JSON workbook without a first page number is unchanged and
// one saved before the field existed loads as Automatic.
let saved = serde_json::to_value(PrintSettings::default()).unwrap();
assert!(saved.get("first_page_number").is_none(), "{saved}");
assert_eq!(serde_json::from_value::<PrintSettings>(saved).unwrap().first_page_number, None);
let p = PrintSettings { first_page_number: Some(7), ..Default::default() };
let saved = serde_json::to_value(&p).unwrap();
assert_eq!(saved["first_page_number"], 7);
assert_eq!(serde_json::from_value::<PrintSettings>(saved).unwrap(), p);
}
}
+1
View File
@@ -24,6 +24,7 @@ craft-offcrypto = { workspace = true }
craft-opc = { workspace = true }
craft-xls = { workspace = true }
craft-xml = { workspace = true }
craft-xlsx = { workspace = true }
thiserror = { workspace = true }
quick-xml = { workspace = true }
zip = { workspace = true }
+2
View File
@@ -267,6 +267,8 @@ pub fn read_sheet(cx: &mut Ctx<'_>, part: &str, name: &str) -> Result<(Sheet, cr
}
// `downThenOver` when absent (ECMA-376's default); an unknown value reads as that too.
sheet.print.page_order = e.attr("pageOrder").and_then(PageOrder::parse).unwrap_or_default();
// The number counts only when `useFirstPageNumber` says so; otherwise it's Automatic.
sheet.print.first_page_number = e.flag("useFirstPageNumber", false).then(|| e.attr_u32("firstPageNumber")).flatten();
if let Some(p) = e.attr_u32("paperSize").and_then(paper_name) {
sheet.print.paper = p.to_string();
}
+7
View File
@@ -409,6 +409,9 @@ fn write_sheet_printing<'a>(s: &mut String, sheet: &'a Sheet, rels: &mut Rels, o
if p.scale != 100 && (10..=400).contains(&p.scale) {
let _ = write!(s, " scale=\"{}\"", p.scale);
}
if let Some(n) = p.first_page_number {
let _ = write!(s, " firstPageNumber=\"{n}\"");
}
if let Some((w, h)) = p.fit_to {
let _ = write!(s, " fitToWidth=\"{w}\" fitToHeight=\"{h}\"");
}
@@ -417,6 +420,10 @@ fn write_sheet_printing<'a>(s: &mut String, sheet: &'a Sheet, rels: &mut Rels, o
let _ = write!(s, " pageOrder=\"{}\"", p.page_order.id());
}
let _ = write!(s, " orientation=\"{}\"", if p.orientation == Orientation::Landscape { "landscape" } else { "portrait" });
// In the schema's attribute order, as Excel writes it: after the orientation.
if p.first_page_number.is_some() {
s.push_str(" useFirstPageNumber=\"1\"");
}
if let Some(id) = kept.page_setup_id() {
let _ = write!(s, " r:id=\"{id}\"");
}
+19 -19
View File
@@ -142,27 +142,27 @@ pub(super) fn table_xml(t: &Table, cols: &[String], name: &str, id: u32, out: &m
}
let _ = write!(s, " name=\"{}\"", esc_attr(&encode_xstring(name)));
let totals = col.map(|c| c.totals).unwrap_or_default();
if t.totals_row {
let f = match totals {
TotalsFn::None => None,
TotalsFn::Average => Some("average"),
TotalsFn::Count => Some("count"),
TotalsFn::CountNums => Some("countNums"),
TotalsFn::Max => Some("max"),
TotalsFn::Min => Some("min"),
TotalsFn::Sum => Some("sum"),
TotalsFn::StdDev => Some("stdDev"),
TotalsFn::Var => Some("var"),
TotalsFn::Custom => Some("custom"),
};
if let Some(f) = f {
let _ = write!(s, " totalsRowFunction=\"{f}\"");
} else if let Some(l) = col.and_then(|c| c.totals_label.as_ref()) {
let _ = write!(s, " totalsRowLabel=\"{}\"", esc_attr(l));
}
// A hidden Total Row keeps each column's calculation, as Excel's files do: turning the row
// back on restores it (#4296). The reader takes them whether the row is shown or not.
let f = match totals {
TotalsFn::None => None,
TotalsFn::Average => Some("average"),
TotalsFn::Count => Some("count"),
TotalsFn::CountNums => Some("countNums"),
TotalsFn::Max => Some("max"),
TotalsFn::Min => Some("min"),
TotalsFn::Sum => Some("sum"),
TotalsFn::StdDev => Some("stdDev"),
TotalsFn::Var => Some("var"),
TotalsFn::Custom => Some("custom"),
};
if let Some(f) = f {
let _ = write!(s, " totalsRowFunction=\"{f}\"");
} else if let Some(l) = col.and_then(|c| c.totals_label.as_ref()) {
let _ = write!(s, " totalsRowLabel=\"{}\"", esc_attr(l));
}
let calc = col.and_then(|c| c.formula.as_ref()).filter(|f| !f.is_empty());
let custom = if t.totals_row && totals == TotalsFn::Custom { col.and_then(|c| c.totals_label.as_ref()) } else { None };
let custom = if totals == TotalsFn::Custom { col.and_then(|c| c.totals_label.as_ref()) } else { None };
let xml = col.and_then(|c| c.xml.as_ref());
if calc.is_none() && custom.is_none() && xml.is_none() {
s.push_str("/>");
+36
View File
@@ -73,3 +73,39 @@ fn page_margins_are_written_as_their_decimals() {
let xml = sheet_xml(&write_xlsx(&Workbook::new()).unwrap());
assert!(xml.contains(r#"<pageMargins left="0.7" right="0.7" top="0.75" bottom="0.75" header="0.3" footer="0.3"/>"#), "{xml}");
}
#[test]
fn first_page_number_is_read_and_written_back() {
// #4293: Excel writes Page Setup's First page number 7 as these two attributes; both were lost.
let body = r#"<sheetData/><pageMargins left="0.7" right="0.7" top="0.75" bottom="0.75" header="0.3" footer="0.3"/><pageSetup paperSize="9" firstPageNumber="7" orientation="portrait" useFirstPageNumber="1"/>"#;
let (wb, _) = read_xlsx(&minimal(body, &[], "", "")).unwrap();
assert_eq!(wb.sheet(0).unwrap().print.first_page_number, Some(7));
let bytes = write_xlsx(&wb).unwrap();
let xml = sheet_xml(&bytes);
assert_eq!(page_setup(&xml), r#"<pageSetup paperSize="9" firstPageNumber="7" orientation="portrait" useFirstPageNumber="1"/>"#);
let (back, _) = read_xlsx(&bytes).unwrap();
assert_eq!(back.sheet(0).unwrap().print.first_page_number, Some(7));
// In the schema's order with the other attributes: after the scale, before Fit To.
let mut wb = back;
wb.sheet_mut(0).unwrap().print.scale = 80;
wb.sheet_mut(0).unwrap().print.fit_to = Some((1, 2));
let xml = sheet_xml(&write_xlsx(&wb).unwrap());
assert!(page_setup(&xml).contains(r#"scale="80" firstPageNumber="7" fitToWidth="1""#), "{xml}");
// Automatic: no number, a number Excel keeps without using it, and `useFirstPageNumber="0"`.
for body in [
r#"<sheetData/><pageSetup paperSize="9" orientation="portrait"/>"#,
r#"<sheetData/><pageSetup paperSize="9" firstPageNumber="5" orientation="portrait"/>"#,
r#"<sheetData/><pageSetup paperSize="9" firstPageNumber="5" orientation="portrait" useFirstPageNumber="0"/>"#,
"<sheetData/>",
] {
let (wb, _) = read_xlsx(&minimal(body, &[], "", "")).unwrap();
assert_eq!(wb.sheet(0).unwrap().print.first_page_number, None, "{body}");
let xml = sheet_xml(&write_xlsx(&wb).unwrap());
assert!(!xml.contains("irstPageNumber"), "{body}: {xml}");
}
// 1 is a number of its own (Excel's field shows 1, not Automatic) and is kept too.
let mut wb = Workbook::new();
wb.sheet_mut(0).unwrap().print.first_page_number = Some(1);
let xml = sheet_xml(&write_xlsx(&wb).unwrap());
assert!(xml.contains(r#"firstPageNumber="1""#) && xml.contains(r#"useFirstPageNumber="1""#), "{xml}");
}
+71
View File
@@ -310,6 +310,7 @@ fn sample() -> Workbook {
hf_scale_with_doc: false,
hf_align_with_margins: true,
page_order: PageOrder::OverThenDown,
first_page_number: Some(7),
};
s.sparklines.push(Sparkline { cell: at("J2"), source: "B2:B3".into(), kind: SparklineKind::WinLoss, color: Color::Rgb(0x112233), markers: true });
s.tables.push(Table {
@@ -1406,6 +1407,76 @@ fn table_newline_column_and_backslash_name_survive() {
assert!(gridcraft_formula::parse("COUNTA(\\_Prime.1[Name])").is_ok(), "backslash table name parses as a structured reference");
}
/// #4296: a table whose Total Row is turned off keeps each column's calculation in the file, as
/// Excel writes it, so turning the row back on in Excel restores a custom formula or Average.
#[test]
fn hidden_total_row_keeps_its_calculations() {
let col = |name: &str, totals: TotalsFn, label: Option<&str>| TableColumn {
name: name.into(),
totals,
totals_label: label.map(str::to_string),
formula: None,
unique_name: None,
xml: None,
};
let mut wb = Workbook::new();
let s = wb.sheet_mut(0).unwrap();
s.tables.push(Table {
id: 1,
name: "Table1".into(),
range: rr("A1:C3"),
header_row: true,
totals_row: false,
columns: vec![
col("Group", TotalsFn::None, Some("Total")),
col("Amount", TotalsFn::Custom, Some("SUM(B2:B3)+10")),
col("Mean", TotalsFn::Average, None),
],
style: "TableStyleMedium2".into(),
banded_rows: true,
banded_cols: false,
first_col: false,
last_col: false,
filter_button: true,
filter: vec![],
table_type: None,
connection_id: None,
});
let bytes = write_xlsx(&wb).unwrap();
let mut xml = String::new();
zip::ZipArchive::new(std::io::Cursor::new(&bytes)).unwrap().by_name("xl/tables/table1.xml").unwrap().read_to_string(&mut xml).unwrap();
// Still a table without a total row: no totalsRowCount, and its range unchanged.
assert!(xml.contains(r#"ref="A1:C3""#) && xml.contains(r#"totalsRowShown="0""#) && !xml.contains("totalsRowCount"), "{xml}");
for part in [
r#"name="Group" totalsRowLabel="Total"/>"#,
r#"name="Amount" totalsRowFunction="custom"><totalsRowFormula>SUM(B2:B3)+10</totalsRowFormula></tableColumn>"#,
r#"name="Mean" totalsRowFunction="average"/>"#,
] {
assert!(xml.contains(part), "{part}: {xml}");
}
let (back, report) = read_xlsx(&bytes).unwrap();
assert!(report.warnings.is_empty(), "{:?}", report.warnings);
let t = &back.sheet(0).unwrap().tables[0];
assert!(!t.totals_row);
assert_eq!(t.range.a1(), "A1:C3");
let got: Vec<_> = t.columns.iter().map(|c| (c.totals, c.totals_label.clone())).collect();
assert_eq!(got, vec![(TotalsFn::None, Some("Total".into())), (TotalsFn::Custom, Some("SUM(B2:B3)+10".into())), (TotalsFn::Average, None)]);
// A table that never had a total row writes no calculation.
let mut plain = wb.clone();
plain.sheet_mut(0).unwrap().tables[0].columns =
vec![col("Group", TotalsFn::None, None), col("Amount", TotalsFn::None, None), col("Mean", TotalsFn::None, None)];
let mut xml = String::new();
zip::ZipArchive::new(std::io::Cursor::new(write_xlsx(&plain).unwrap()))
.unwrap()
.by_name("xl/tables/table1.xml")
.unwrap()
.read_to_string(&mut xml)
.unwrap();
for attr in ["totalsRowFunction", "totalsRowLabel", "totalsRowFormula"] {
assert!(!xml.contains(attr), "{attr}: {xml}");
}
}
/// A table that is only a header row and a totals row (Insert Table on one row, then Total
/// Row) is written like the header-only and one-data-row shapes, not dropped on save.
#[test]
+30 -68
View File
@@ -359,11 +359,10 @@ pub fn parse_streaming(xml: &[u8], split: &[&str], cb: &mut dyn FnMut(El) -> Res
// ---------------------------------------------------------------- writing helpers
// XML 1.0 byte escaping is shared; spreadsheet string and phonetic policy stays here.
use craft_xml::is_xml_char;
#[cfg(test)]
use craft_xml::push_esc;
// XML escaping and SpreadsheetML strings are shared; phonetic/model mapping stays here.
pub use craft_xml::{esc, esc_attr};
#[cfg(test)]
use craft_xml::{is_xml_char, push_esc};
/// Appends `n` in decimal.
pub fn push_u64(o: &mut String, mut n: u64) {
@@ -402,70 +401,8 @@ pub fn push_a1(o: &mut String, c: gridcraft_core::CellRef) {
push_u64(o, u64::from(c.row) + 1);
}
/// ST_Xstring encoding for cell text: characters XML can't carry and carriage returns become
/// `_xHHHH_`, and literal `_xHHHH_` sequences are protected with `_x005F_`. The result still needs
/// [`esc`].
pub fn encode_xstring(s: &str) -> String {
let mut o = String::with_capacity(s.len());
let chars: Vec<char> = s.chars().collect();
for (i, &c) in chars.iter().enumerate() {
if c == '_' && looks_like_escape(&chars, i) {
o.push_str("_x005F_");
} else if !is_xml_char(c) || (c.is_control() && !matches!(c, '\t' | '\n')) {
o.push_str(&format!("_x{:04X}_", c as u32 & 0xFFFF));
} else {
o.push(c);
}
}
o
}
fn looks_like_escape(chars: &[char], i: usize) -> bool {
chars.get(i + 1) == Some(&'x') && chars.get(i + 6) == Some(&'_') && (i + 2..i + 6).all(|k| chars.get(k).is_some_and(char::is_ascii_hexdigit))
}
fn escape_unit(chars: &[char], i: usize) -> Option<u32> {
let hex: String = chars.get(i + 2..i + 6)?.iter().collect();
u32::from_str_radix(&hex, 16).ok()
}
/// The character for a high surrogate escape at `i` (value `high`) followed directly by a low surrogate escape.
fn surrogate_pair(chars: &[char], i: usize, high: u32) -> Option<char> {
if !(0xD800..=0xDBFF).contains(&high) || chars.get(i + 7) != Some(&'_') || !looks_like_escape(chars, i + 7) {
return None;
}
let low = escape_unit(chars, i + 7).filter(|l| (0xDC00..=0xDFFF).contains(l))?;
char::from_u32(0x10000 + ((high - 0xD800) << 10) + (low - 0xDC00))
}
/// Inverse of [`encode_xstring`].
pub fn decode_xstring(s: &str) -> String {
if !s.contains("_x") {
return s.to_string();
}
let chars: Vec<char> = s.chars().collect();
let mut o = String::with_capacity(s.len());
let mut i = 0;
while i < chars.len() {
if chars[i] == '_' && looks_like_escape(&chars, i) {
let unit = escape_unit(&chars, i);
if let Some(ch) = unit.and_then(char::from_u32) {
o.push(ch);
i += 7;
continue;
}
// A high surrogate escape followed by a low surrogate escape is one UTF-16 pair.
if let Some(ch) = unit.and_then(|high| surrogate_pair(&chars, i, high)) {
o.push(ch);
i += 14;
continue;
}
}
o.push(chars[i]);
i += 1;
}
o
}
// Existing call sites and regression coverage use the production shared codec.
pub use craft_xlsx::{decode_xstring, encode_xstring};
/// `<t>` element with `xml:space="preserve"` when needed.
pub fn t_el(s: &str) -> String {
@@ -778,3 +715,28 @@ mod shared_escape_parity {
assert_eq!(decode_xstring(&encode_xstring("_x000D_\r\0😀")), "_x000D_\r\0😀");
}
}
#[cfg(test)]
mod shared_xstring_parity {
use super::*;
#[test]
fn xstring_preserves_controls_unicode_and_literal_escapes() {
// XML-invalid scalars, C1 controls and literal escapes survive save/reopen.
for c in (0..=0xffff).filter_map(char::from_u32) {
let text = format!("left{c}right_x0041_");
assert_eq!(decode_xstring(&encode_xstring(&text)), text);
}
for (encoded, decoded) in [
("_x005F_x000D_", "_x000D_"),
("_xD83D__xDE00_", "😀"),
("_xD83D__x0041_", "_xD83D_A"),
("_xD83D__x005F_xDE00_", "_xD83D__xDE00_"),
("_X0041_", "_X0041_"),
("_xZZZZ_", "_xZZZZ_"),
] {
assert_eq!(decode_xstring(encoded), decoded);
}
assert_eq!(encode_xstring("\r\n\t\0"), "_x000D_\n\t_x0000_");
}
}