diff --git a/.changeset/group-title-fill-right.md b/.changeset/group-title-fill-right.md new file mode 100644 index 0000000..8cac300 --- /dev/null +++ b/.changeset/group-title-fill-right.md @@ -0,0 +1,5 @@ +--- +"javascript-excel": patch +--- + +`toDataset` with `headerRows` (and `importDataset` with a multi-row header) now carries a group title right across the empty upper-row cells that follow it when there are no merges, as in CSV: `Name,Q1,` over `,Jan,Feb` gives `Name`, `Q1 / Jan`, `Q1 / Feb` instead of `Name`, `Q1 / Jan`, `Feb`. Merged cells still decide where they are present, and a column with no text in the lower header rows is not filled. diff --git a/docs/api.md b/docs/api.md index 92e3ba0..72ec29b 100644 --- a/docs/api.md +++ b/docs/api.md @@ -702,7 +702,7 @@ export interface DatasetResult { columns: Array<{ title: string; key: string }>; **Totals rows.** With `skipTotals: 'auto'` (the default), the last data row is dropped when it contains at least one formula and every formula in it is `SUBTOTAL(…)`. That is the totals row `fromDataset` writes, and a label such as "Total" may sit next to the formulas. So `toDataset(read(write(fromDataset(ds))))` returns the data rows only. `true` always drops the last row, and `false` keeps every row. A sheet whose genuine last data row is all `SUBTOTAL` formulas needs `skipTotals: false`. Rows are **null-prototype objects** (`Object.create(null)`), so a header named `__proto__` from an untrusted file is just a key. -**Multi-row headers.** With `headerRows: n`, the title of each column joins the text of rows `headerRow` to `headerRow + n - 1` with `join`, skipping empty parts. Merged cells are expanded first, so a group title merged over three columns prefixes all three ("Q1 / Jan", "Q1 / Feb", "Q1 / Mar"), and a title merged down through the header rows appears once ("Name"). That reads back the header groups `fromDataset` writes. Data starts after the last header row. Header detection, type inference and column mapping are in `javascript-excel/import` (§5.6). +**Multi-row headers.** With `headerRows: n`, the title of each column joins the text of rows `headerRow` to `headerRow + n - 1` with `join`, skipping empty parts. Merged cells are expanded first, so a group title merged over three columns prefixes all three ("Q1 / Jan", "Q1 / Feb", "Q1 / Mar"), and a title merged down through the header rows appears once ("Name"). That reads back the header groups `fromDataset` writes. Without merges (always the case in CSV), a group title is written once, over the first of its columns (`Name,Q1,` over `,Jan,Feb`). So an empty, unmerged cell in an upper header row takes the nearest non-empty cell to its left in the same row, when the column has text in a lower header row: that gives "Q1 / Jan", "Q1 / Feb", and `toCsv` of header groups reads back with the original titles. The fill never starts left of the table's first column (a leading empty cell over "Name" stays empty), never crosses a merged cell (a real merge already gives the extent), and skips columns with no text in the lower rows. Data starts after the last header row. Header detection, type inference and column mapping are in `javascript-excel/import` (§5.6). ### 4.4 Style and colour helpers diff --git a/packages/javascript-excel/src/dataset.ts b/packages/javascript-excel/src/dataset.ts index fccdd25..cc32f47 100644 --- a/packages/javascript-excel/src/dataset.ts +++ b/packages/javascript-excel/src/dataset.ts @@ -677,7 +677,7 @@ export function toDatasetDetailed(sheet: Sheet | Sheet, options: ToDataset if (typeof join !== "string") throw new TypeError("join must be a string"); const asCell = options.values === "cell"; - const titleOf = headerRow === false ? undefined : headerRows === 1 ? (c: number) => cellText(s.rows[headerRow]?.[c]).trim() : multiRowTitles(s, headerRow, headerRows, join); + const titleOf = headerRow === false ? undefined : headerRows === 1 ? (c: number) => cellText(s.rows[headerRow]?.[c]).trim() : multiRowTitles(s, headerRow, headerRows, join, rng.start.col); const columns: DetailedDataset["columns"] = []; const used = new Map(); for (let c = rng.start.col; c <= rng.end.col; c++) { @@ -724,19 +724,41 @@ export function toDatasetDetailed(sheet: Sheet | Sheet, options: ToDataset * Titles of a header spanning several rows: the text of each row joined, * with merged cells expanded (a group title merged across columns prefixes * each of them) and a cell merged down through the rows counted once. + * + * Without merges (CSV), a group title is written once, over the first of its + * columns: "Q1," over "Jan,Feb". So an empty, unmerged cell in an upper header + * row takes the nearest non-empty cell to its left in that row, as long as + * the column has text in a lower header row (it is a sub-column). The fill + * stops at the table's first column and at a merged cell, whose extent the + * merge already gives. */ -function multiRowTitles(s: Sheet, top: number, count: number, join: string): (c: number) => string { +function multiRowTitles(s: Sheet, top: number, count: number, join: string, firstCol: number): (c: number) => string { const bottom = top + count - 1; const merges = (s.merges ?? []).map((m) => decodeRange(m)).filter((m) => m.start.row <= bottom && m.end.row >= top); + const mergeAt = (r: number, c: number) => merges.find((x) => r >= x.start.row && r <= x.end.row && c >= x.start.col && c <= x.end.col); + const textAt = (r: number, c: number) => cellText(s.rows[r]?.[c]).trim(); + const filledFromLeft = (r: number, c: number): string => { + for (let k = c - 1; k >= firstCol; k--) { + if (mergeAt(r, k)) return ""; + const t = textAt(r, k); + if (t !== "") return t; + } + return ""; + }; return (c) => { const parts: string[] = []; let last: unknown; for (let r = top; r <= bottom; r++) { - const m = merges.find((x) => r >= x.start.row && r <= x.end.row && c >= x.start.col && c <= x.end.col); + const m = mergeAt(r, c); const id = m ?? `${r}`; if (id === last) continue; last = id; - const text = cellText(m ? s.rows[m.start.row]?.[m.start.col] : s.rows[r]?.[c]).trim(); + let text = m ? cellText(s.rows[m.start.row]?.[m.start.col]).trim() : textAt(r, c); + if (text === "" && !m && r < bottom) { + let subColumn = false; + for (let q = r + 1; q <= bottom && !subColumn; q++) subColumn = mergeAt(q, c) === undefined && textAt(q, c) !== ""; + if (subColumn) text = filledFromLeft(r, c); + } if (text !== "") parts.push(text); } return parts.join(join); diff --git a/packages/javascript-excel/test/dataset/from-dataset.test.ts b/packages/javascript-excel/test/dataset/from-dataset.test.ts index 33bb757..554b15e 100644 --- a/packages/javascript-excel/test/dataset/from-dataset.test.ts +++ b/packages/javascript-excel/test/dataset/from-dataset.test.ts @@ -296,6 +296,24 @@ describe("toDataset", () => { expect(() => toDataset(sheet, { headerRows: 0 })).toThrow(); }); + it("headerRows without merges carries a group title right over its sub-columns (CSV)", () => { + // "Name,Q1,,Q2," over ",Jan,Feb,Apr,May": Name isn't filled from the left; Q1 and Q2 cover their columns. + const csvLike: Sheet = { name: "S", rows: [["Name", "Q1", "", "Q2", ""], ["", "Jan", "Feb", "Apr", "May"], ["Ada", 1, 2, 3, 4]] }; + expect(toDataset(csvLike, { headerRows: 2 }).columns.map((c) => c.title)).toEqual(["Name", "Q1 / Jan", "Q1 / Feb", "Q2 / Apr", "Q2 / May"]); + // Upper cells left of the first title stay empty; a column with no lower text isn't a sub-column. + const leading: Sheet = { name: "S", rows: [["", "", "Q1", "", ""], ["Name", "City", "Jan", "Feb", ""], ["Ada", "Oslo", 1, 2, 3]] }; + expect(toDataset(leading, { headerRows: 2 }).columns.map((c) => c.title)).toEqual(["Name", "City", "Q1 / Jan", "Q1 / Feb", ""]); + // Every upper cell non-empty (a units row): nothing to fill. + const units: Sheet = { name: "S", rows: [["Temp", "Pressure"], ["°C", "hPa"], [20, 1013]] }; + expect(toDataset(units, { headerRows: 2 }).columns.map((c) => c.title)).toEqual(["Temp / °C", "Pressure / hPa"]); + }); + + it("headerRows: a real merge wins, and a fill never crosses a merged cell", () => { + // Q1 merged over B:C; D's upper cell is empty and stays empty instead of taking Q1. + const s: Sheet = { name: "S", rows: [["Name", "Q1", null, null], [null, "Jan", "Feb", "Notes"], ["Ada", 1, 2, "x"]], merges: ["B1:C1"] }; + expect(toDataset(s, { headerRows: 2 }).columns.map((c) => c.title)).toEqual(["Name", "Q1 / Jan", "Q1 / Feb", "Notes"]); + }); + it("builds keys from header text: deduplicated, letters for empty headers", () => { const sheet: Sheet = { name: "S", rows: [["Name", "Name", "", " Qty "], ["Ada", "x", true, 2], [], ["Grace", "y", false, { formula: "1+1", value: 2 }]] }; const { columns, data } = toDataset(sheet); diff --git a/packages/javascript-excel/test/import/fixtures.test.ts b/packages/javascript-excel/test/import/fixtures.test.ts index e45a51d..39250d0 100644 --- a/packages/javascript-excel/test/import/fixtures.test.ts +++ b/packages/javascript-excel/test/import/fixtures.test.ts @@ -2,6 +2,8 @@ // test/fixtures/import, see the README there). import { readFileSync } from "node:fs"; import { describe, expect, it } from "vitest"; +import { toCsv } from "../../src/csv"; +import { fromDataset } from "../../src/dataset"; import { importDataset } from "../../src/import"; const file = (path: string) => new Uint8Array(readFileSync(new URL(`../fixtures/import/${path}`, import.meta.url))); @@ -36,3 +38,24 @@ describe("header detection on react-data-import's fixtures", () => { expect(explicit.data).toEqual(r.data); }); }); + +describe("header groups through CSV", () => { + it("toCsv of fromDataset header groups imports back with the original column titles", async () => { + const sheet = fromDataset({ + columns: [ + { title: "Name", key: "name" }, + { title: "Q1", children: [{ title: "Jan", key: "jan" }, { title: "Feb", key: "feb" }, { title: "Mar", key: "mar" }] }, + { title: "Q2", children: [{ title: "Apr", key: "apr" }, { title: "May", key: "may" }] }, + { title: "Notes", key: "notes" }, + ], + data: [ + { name: "Ada", jan: 1, feb: 2, mar: 3, apr: 4, may: 5, notes: "first" }, + { name: "Grace", jan: 6, feb: 7, mar: 8, apr: 9, may: 10, notes: "second" }, + ], + }); + const r = await importDataset(toCsv(sheet), { format: "csv" }); + expect(r.meta.header).toEqual({ rows: [0, 1], detected: true, confidence: "high" }); + expect(r.columns.map((c) => c.key)).toEqual(["Name", "Q1 / Jan", "Q1 / Feb", "Q1 / Mar", "Q2 / Apr", "Q2 / May", "Notes"]); + expect({ ...r.data[1] }).toEqual({ Name: "Grace", "Q1 / Jan": 6, "Q1 / Feb": 7, "Q1 / Mar": 8, "Q2 / Apr": 9, "Q2 / May": 10, Notes: "second" }); + }); +});