@quario/xlsx 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-09-05
+
+### Added
+
+- **Chrome merges, data does not.** A cell spanning several columns in the
+  header row or a total row is written into the first column it covers, the
+  rest of the range is written empty, and the range is merged. Nothing in the
+  data region merges, so sort, filter and column selection keep working over
+  it.
+
+- **`valign`** writes the cell's vertical alignment for table cells and split
+  slots. Undeclared writes nothing, so the spreadsheet application keeps its
+  own default.
+
 ## [0.4.0] - 2026-09-03
 
 ### Changed

package/README.md

@@ -106,6 +106,7 @@ unread, and all of it may change without a breaking change.
 | `size`, `bold`, `italic`, `underline`, `strikethrough` | Font (`strikethrough` → writer's `strike`)                                                                                           |
 | `color`, `background`                                  | Font colour, solid fill                                                                                                              |
 | `align`                                                | Horizontal alignment                                                                                                                 |
+| `valign`                                               | Vertical alignment; undeclared writes nothing, so the spreadsheet application keeps its own default                                  |
 
 Style blocks layer row under cell, as everywhere in quario.
 

package/lib/cell.js

@@ -7,7 +7,7 @@
  * newline gains `wrapText` so the break is visible in the grid.
  */
 import { text, typed } from "quario";
-import { format as look, sides } from "./style.js";
+import { format as look, merge } from "./style.js";
 
 /** @type {(value: any, fmt: string) => string | null} */
 let whenNum = (value, fmt) => (typeof value === "number" ? fmt : null);
@@ -54,7 +54,7 @@ let paintWrap = (out, shown) => {
  * @type {(cell: { tokens: any[], style?: any }, under: any, intl?: any) => { value: any, format: any }}
  */
 let field = (cell, under, intl) => {
-  let resolved = sides(under, cell.style);
+  let resolved = merge(under, cell.style);
   let shown = shownOf(cell, resolved?.format);
   let out = look(resolved);
   paintFmt(out, resolved, shown, intl);

package/lib/index.js

@@ -17,9 +17,9 @@
  */
 import { walk } from "quario";
 import { field } from "./cell.js";
-import { sides as under } from "./style.js";
+import { merge as under } from "./style.js";
 import { pixels } from "./image.js";
-import { append, create, embed, freeze, mark, place, save, sheet } from "./workbook.js";
+import { append, create, embed, freeze, mark, place, save, sheet, span } from "./workbook.js";
 
 // The options are described once, in the hand-written public declarations, and
 // read back here — a second copy in JSDoc is a copy that drifts.
@@ -109,6 +109,30 @@ export function xlsx(options) {
         worksheet,
         event.cells.map((/** @type {any} */ each) => cell(each, layer)),
       );
+    // Chrome merges, data does not (docs/adr/0047). A cell covering several
+    // columns writes its value into the first of them, the rest are written
+    // empty, and the range is merged -- so the label stays where the document
+    // put it. Reached by the header row and the total rows; a data row cannot
+    // span, so `record` above stays the plain path it was.
+    /** @type {(each: any, layer: any) => any[]} */
+    let covering = (each, layer) => [
+      cell(each, layer),
+      ...Array.from({ length: (each.span || 1) - 1 }, () => cell({ tokens: [] }, layer)),
+    ];
+    /** @type {(cells: any[], layer: any) => number} */
+    let merged = (cells, layer) => {
+      /** @type {any[]} */
+      let fields = [];
+      /** @type {{ at: number, width: number }[]} */
+      let ranges = [];
+      for (let each of cells) {
+        if (each.span > 1) ranges.push({ at: fields.length + 1, width: each.span });
+        fields.push(...covering(each, layer));
+      }
+      let row = append(worksheet, fields);
+      for (let range of ranges) span(worksheet, row, range.at, range.width);
+      return row;
+    };
     await walk(stream(data), {
       "report-start": (event) => {
         // The report default over this target's baseline. The marking is
@@ -181,17 +205,19 @@ export function xlsx(options) {
         place(worksheet, known.id, known, append(worksheet, []));
       },
       "table-start": (event) => {
-        let headers = event.columns.map((/** @type {any} */ column) =>
-          cell(column.header, event.style),
+        let row = merged(
+          event.columns
+            .filter((/** @type {any} */ column) => column.header)
+            .map((/** @type {any} */ column) => column.header),
+          event.style,
         );
-        let row = append(worksheet, headers);
         if (!frozen) {
           freeze(worksheet, row);
           frozen = true;
         }
       },
       row: (event) => record(event, event.style),
-      "total-row": (event) => record(event, event.style),
+      "total-row": (event) => merged(event.cells, event.style),
     });
     return save(workbook);
   };

package/lib/style.js

@@ -10,11 +10,8 @@
  * target's own edge, never shared engine code.
  */
 
-/** @type {(value: any) => boolean} */
-let finite = (value) => Number.isFinite(value);
 let HEX = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i;
 let SIDES = ["Top", "Right", "Bottom", "Left"];
-let BORDER_PARTS = ["Width", "Style", "Color"];
 /** @type {Record<string, string>} */
 let LINE = { solid: "thin", dashed: "dashed", dotted: "dotted" };
 
@@ -33,28 +30,14 @@ let argb = (value) => {
   return "FF" + digits.toUpperCase();
 };
 
-// Style blocks layer outward-in: row under cell. A border side is won whole
-// by the inner block when that block named any of its three keys, so a cell
-// that failed-soft on a side does not pick up the row's other two names.
+// Style blocks layer outward-in: the enclosing block under the cell's own.
+// A row's block reaches here with no box in it -- the engine resolved that
+// half onto the cells themselves, border sides won whole and all (SCHEMA.md,
+// "Style declarations") -- so what layers here is a plain overwrite. The only
+// other block that sits under a cell is a band-role default, which declares
+// no box either.
 /** @type {(under: any, over: any) => any} */
 let merge = (under, over) => (under ? (over ? { ...under, ...over } : under) : over || {});
-/** @type {(style: any, side: string) => boolean} */
-let owns = (style, side) =>
-  !!style && BORDER_PARTS.some((part) => Object.hasOwn(style, "border" + side + part));
-/** @type {(out: any, over: any, side: string) => void} */
-let take = (out, over, side) => {
-  for (let part of BORDER_PARTS) {
-    let name = "border" + side + part;
-    if (Object.hasOwn(over, name)) out[name] = over[name];
-    else delete out[name];
-  }
-};
-/** @type {(under: any, over: any) => any} */
-let sides = (under, over) => {
-  let out = merge(under, over);
-  if (over) for (let side of SIDES) if (owns(over, side)) take(out, over, side);
-  return out;
-};
 
 /** @type {(out: any, key: string, value: any) => any} */
 let put = (out, key, value) => {
@@ -76,7 +59,7 @@ let face = (family) => {
 };
 
 /** @type {(value: any) => number | null} */
-let size = (value) => (finite(value) && value > 0 ? value : null);
+let size = (value) => (Number.isFinite(value) && value > 0 ? value : null);
 /** @type {(value: any) => true | null} */
 let flag = (value) => (value ? true : null);
 /** @type {(value: any) => { argb: string } | null} */
@@ -113,9 +96,17 @@ let fill = (value) => {
 /** @type {(value: any) => any} */
 let align = (value) =>
   value === "left" || value === "center" || value === "right" ? { horizontal: value } : null;
+// The writer's own words for the vertical half, one to one. Undeclared is
+// left to the host application (Excel's bottom) rather than pinned: a
+// spreadsheet user expects its default, and an author who cares declares one.
+let VERTICAL = ["top", "middle", "bottom"];
+/** @type {(value: any) => any} */
+let valign = (value) => (VERTICAL.includes(value) ? value : null);
+/** @type {(style: any) => any} */
+let alignment = (style) => put(align(style.align), "vertical", valign(style.valign));
 
 /** @type {(width: any) => boolean} */
-let isStroke = (width) => finite(width) && width > 0;
+let isStroke = (width) => Number.isFinite(width) && width > 0;
 /** @type {(named: any) => string | null} */
 let lineOf = (named) => {
   if (typeof named !== "string") return null;
@@ -144,7 +135,7 @@ let format = (style) => {
   let out = put(null, "font", font(style));
   out = put(out, "fill", fill(style.background));
   out = put(out, "border", border(style));
-  return put(out, "alignment", align(style.align));
+  return put(out, "alignment", alignment(style));
 };
 
-export { format, sides };
+export { format, merge };

package/lib/workbook.js

@@ -68,6 +68,14 @@ let place = (worksheet, id, size, row) => {
   });
 };
 
+// One merged range across `width` columns of a row, from column `at` (1-based).
+// Chrome merges and data does not (docs/adr/0047), so this reaches the header
+// row and the total rows only.
+/** @type {(worksheet: any, row: number, at: number, width: number) => void} */
+let span = (worksheet, row, at, width) => {
+  worksheet.mergeCells(row, at, row, at + width - 1);
+};
+
 // Freeze everything above the body so the header row stays visible.
 /** @type {(worksheet: any, row: number) => void} */
 let freeze = (worksheet, row) => {
@@ -93,4 +101,4 @@ let save = async (workbook) => {
     : new Uint8Array(out);
 };
 
-export { append, create, embed, freeze, mark, place, save, sheet };
+export { append, create, embed, freeze, mark, place, save, sheet, span };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quario/xlsx",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "The spreadsheet render target for quario — in the makings, not yet released",
   "homepage": "https://getquario.com",
   "license": "SEE LICENSE IN LICENSE",
@@ -42,12 +42,12 @@
     "@arethetypeswrong/cli": "^0.18.3",
     "@size-limit/preset-small-lib": "^13.0.3",
     "@types/node": "^22.20.1",
-    "quario": "^0.4.0",
+    "quario": "^0.5.0",
     "size-limit": "^13.0.3",
     "typescript": "^7.0.2"
   },
   "peerDependencies": {
-    "quario": "^0.4.0"
+    "quario": "^0.5.0"
   },
   "size-limit": [
     {
@@ -56,7 +56,7 @@
         "quario",
         "exceljs"
       ],
-      "limit": "2.4 kB"
+      "limit": "3 kB"
     }
   ],
   "engines": {