Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/group-title-fill-right.md
Original file line number Diff line number Diff line change
@@ -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.
2 changes: 1 addition & 1 deletion docs/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
30 changes: 26 additions & 4 deletions packages/javascript-excel/src/dataset.ts
Original file line number Diff line number Diff line change
Expand Up @@ -677,7 +677,7 @@ export function toDatasetDetailed(sheet: Sheet<Cell> | 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<string, number>();
for (let c = rng.start.col; c <= rng.end.col; c++) {
Expand Down Expand Up @@ -724,19 +724,41 @@ export function toDatasetDetailed(sheet: Sheet<Cell> | 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<CellInput>, top: number, count: number, join: string): (c: number) => string {
function multiRowTitles(s: Sheet<CellInput>, 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);
Expand Down
18 changes: 18 additions & 0 deletions packages/javascript-excel/test/dataset/from-dataset.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down
23 changes: 23 additions & 0 deletions packages/javascript-excel/test/import/fixtures.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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)));
Expand Down Expand Up @@ -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" });
});
});
Loading