@quario/xlsx 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -7,6 +7,83 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-09-07
+
+### Added
+
+- **A date cell's number format follows the `form` its report declares.** The
+  four forms map to `dd/mm/yy`, `dd mmm yyyy`, `dd mmmm yyyy` and
+  `dddd, dd mmmm yyyy`. The shape is the document's; the language a month or
+  weekday name is spelled in stays the reader's, because that is what a
+  spreadsheet application supplies and pinning it would stop the file reading
+  naturally for whoever opens it.
+
+- **A declared digit count builds the pattern.** A `number` cell asking for
+  three digits writes `#,##0.000`, and a `currency` cell asking for none writes
+  `"EUR"#,##0` — the same count the page presents, taken off the declaration
+  the engine resolved rather than computed here.
+
+- **A cell's own `currency` code picks the number format**, ahead of the
+  instance's default: `"JPY"#,##0` where the row says `JPY`, since the code
+  decides the digits too. The cell stays a number either way. A code the engine
+  could not accept writes no number format at all, rather than labelling the
+  cell in the instance's currency.
+
+### Changed
+
+- **A `date` cell with no declared form now writes `dd mmm yyyy`, not
+  `yyyy-mm-dd`.** A bare `date` means the `medium` form throughout, so the grid
+  agrees with the page. A report that wants the ISO shape has no form for it;
+  the nearest is `{ "kind": "date", "form": "short" }`, which writes
+  `dd/mm/yy`. The cell is still a real typed date either way.
+
+- **A cell's number format now comes from the engine's fraction-digit count
+  rather than from four patterns this target held of its own.** The visible
+  change is `currency`: the pattern followed the currency's own minor units,
+  so an amount in a currency with none — JPY — is `"JPY"#,##0` where it was
+  `"JPY"#,##0.00`, and one with three is `"BHD"#,##0.000`. `number`
+  (`#,##0.00`), `percent` (`0.00%`) and `date` (`yyyy-mm-dd`) are unchanged in
+  a worksheet; what changed for those is that HTML and PDF now show the same
+  decimals the grid always did, instead of their own.
+
+- A `currency` code that is not a readable currency no longer produces a number
+  format at all. The cell keeps its value; before, the code was pasted straight
+  into a pattern while every other target fell back to the unformatted value.
+
+  Only the digit count is shared. The grouping separator and the symbol's
+  position still come from the application that opens the file, which is what
+  lets one workbook read naturally wherever it is opened.
+
+### Fixed
+
+- A `format` kind reaching this target from an `=` expression is now looked up
+  as an own key. Before, a kind resolving to the name of a built-in object
+  member threw out of the render (`valueOf`, `hasOwnProperty`) or wrote
+  `[object Undefined]` into the cell's number format (`toString`). A literal
+  was never affected: it is checked against the four kinds.
+
+### Fixed
+
+- **An image whose size cannot be read now names the item that asked for it.**
+  The failure said only that the size could not be read from the bytes, so a
+  report with two pictures gave no way to tell which one was bad. The message
+  now begins with the item's `source` path, as every other render error does
+  and as it does from every other target.
+
+## [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

@@ -74,10 +74,13 @@ host. Render-time failures reject with located errors.
 
 One worksheet, named `Report`, with the banded walk flattened onto it as rows in render order:
 report-header items, then per group instance its header items, nested content, and footer items,
-then the table's header row, data rows, and total row, then report-footer items. Grouping shows up
-as that order alone. Group boundaries add no rows of their own, and `break: "page"` is ignored.
+then the table's header row, data rows, and total rows, then report-footer items. Grouping shows up
+as that order alone. Group boundaries add no rows of their own, and `break: "page"` and
+`reset: "page"` are ignored, as are `page.margin` and a report header's `height`.
 
-Each item takes one row with its cell in the first column, unmerged. Two band roles carry an
+Each item takes one row with its cell in the first column, unmerged; a split takes one row with its
+slots as the cells across it (slot widths unread, a slot rendering nothing an empty cell), and a
+spanning header or total cell is a merged range. Two band roles carry an
 omakase default that the author's own style always overrides: report-header items render bold at
 size 14, group-header items render bold.
 
@@ -92,11 +95,23 @@ inert literal text: no formula-injection surface, and no apostrophe mangling eit
 
 A hidden cell keeps its column slot as an empty cell that retains its style.
 
+### Number formats
+
+`format` writes a number format so the grid presents what the other targets do. `date` builds
+its pattern from the cell's `form` (`dd mmm yyyy` undeclared), with month and weekday names
+spelled by the reader's application; the number kinds build theirs from the declaration's
+fraction-digit count — an undeclared `number` is `#,##0.00`, `percent` is `0.00%`,
+`{ "kind": "number", "digits": 3 }` is `#,##0.000` — and `currency` is the code the cell wears
+— its own `currency` when it declares one, else the instance's — over that currency's minor
+units unless `digits` says otherwise: `"USD"#,##0.00`, `"JPY"#,##0`, `"BHD"#,##0.000`. A kind
+on the wrong type, or a code the engine cannot read, writes no format.
+
 ### Images
 
 An image item is not a cell: it takes one worksheet row as its anchor and floats over the sheet as a
 drawing at its natural pixel size. Placement here is best-effort. `fit`, `alt`, and `style` go
-unread, and all of it may change without a breaking change.
+unread, and all of it may change without a breaking change. Bytes too short to carry a size reject
+the render rather than vanish.
 
 ### Styles
 
@@ -106,8 +121,14 @@ 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                                                                                                                 |
-
-Style blocks layer row under cell, as everywhere in quario.
+| `valign`                                               | Vertical alignment; undeclared writes nothing, so the spreadsheet application keeps its own default                                  |
+| `border*`                                              | Cell borders (`solid` → `thin`, `dashed`, `dotted`; width approximated); a row's borders arrive on its cells already                 |
+| `format`, `currency`                                   | A number format — see [Number formats](#number-formats)                                                                              |
+| `uppercase`, `padding*`, `spaceBefore`, `spaceAfter`   | Not read: a grid has no text-transform, no cell inset of its own, and no flow                                                        |
+
+Style blocks layer row under cell, as everywhere in quario, with the report default outermost.
+Every cell is written at 10 points unless something declares otherwise, and a cell whose display
+contains a newline wraps.
 
 ### Freeze
 

package/lib/cell.js

@@ -6,39 +6,79 @@
  * cell-level formatting from the style module. Display text that contains a
  * 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 { currencyOf, text, typed } from "quario";
+import { format as look, merge } from "./style.js";
+
+// The digit count is the engine's, never this target's: it rides on the
+// resolved declaration the stream carries, the same one HTML and PDF
+// stringify from, so a cell shows the same decimals in the grid as it does on
+// the page (docs/adr/0054, docs/adr/0056). What stays this target's own is
+// the form — the reader's application supplies the grouping separator, the
+// symbol's place, and the language a month name is spelled in.
+/** @type {(digits: number | undefined) => string} */
+let places = (digits) => (digits ? "." + "0".repeat(digits) : "");
 
 /** @type {(value: any, fmt: string) => string | null} */
 let whenNum = (value, fmt) => (typeof value === "number" ? fmt : null);
-/** @type {(value: any) => string | null} */
-let whenDate = (value) => (value instanceof Date ? "yyyy-mm-dd" : null);
-/** @type {(value: any, currency: any) => string | null} */
-let whenMoney = (value, currency) =>
-  typeof value === "number" && typeof currency === "string" && currency
-    ? '"' + currency + '"#,##0.00'
-    : null;
-/** @type {Record<string, (value: any, currency: any) => string | null>} */
-let NUMFMT = {
-  number: (value) => whenNum(value, "#,##0.00"),
-  percent: (value) => whenNum(value, "0.00%"),
-  date: (value) => whenDate(value),
-  currency: (value, currency) => whenMoney(value, currency),
+// A date's form is honoured as far as a sheet can honour one: the *shape* is
+// the author's, and the language of a month or weekday name is the reader's,
+// because Excel spells `mmmm` and `dddd` in whoever opens the file's
+// application language. Pinning that would take a `[$-...]` locale prefix and
+// would stop the sheet following its reader, which docs/adr/0054 refuses. The
+// day-first ordering is the author's here too, and that is the second half of
+// the same approximation (CONTEXT.md, "Form").
+/** @type {Record<string, string>} */
+let DATE_FMT = {
+  short: "dd/mm/yy",
+  medium: "dd mmm yyyy",
+  long: "dd mmmm yyyy",
+  full: "dddd, dd mmmm yyyy",
 };
-/** @type {(kind: any, value: any, currency: any) => string | null} */
-let numFmtOf = (kind, value, currency) => {
-  let rule = NUMFMT[kind];
-  return rule ? rule(value, currency) : null;
+/** @type {(value: any, decl: any) => string | null} */
+let whenDate = (value, decl) =>
+  value instanceof Date && Object.hasOwn(DATE_FMT, decl.form) ? DATE_FMT[decl.form] : null;
+/** @type {(value: any, decl: any, currency: any) => string | null} */
+let whenMoney = (value, decl, currency) => {
+  // The value first: a text cell in a money column would otherwise pay for a
+  // pattern it cannot wear. Then the count — a code the engine will not read
+  // resolved to no digits at all, so the cell keeps its value and gains no
+  // number format, the same withdrawal `format()` makes.
+  if (typeof value !== "number" || decl.digits === undefined) return null;
+  return '"' + currency + '"#,##0' + places(decl.digits);
 };
+/** @type {Record<string, (value: any, decl: any, currency: any) => string | null>} */
+let NUMFMT = {
+  number: (value, decl) => whenNum(value, "#,##0" + places(decl.digits)),
+  percent: (value, decl) => whenNum(value, "0" + places(decl.digits) + "%"),
+  date: whenDate,
+  currency: whenMoney,
+};
+// Own-key lookup, as everywhere a resolved declaration indexes a table: the
+// declaration reaches here having been resolved from author data, and
+// `valueOf` or `toString` as a kind would otherwise reach a member of
+// `Object.prototype` and either throw out of the render or write its return
+// value as a number format.
+/** @type {(decl: any, value: any, currency: any) => string | null} */
+let numFmtOf = (decl, value, currency) =>
+  !!decl && typeof decl === "object" && Object.hasOwn(NUMFMT, decl.kind)
+    ? NUMFMT[decl.kind](value, decl, currency)
+    : null;
 
-/** @type {(cell: { tokens: any[] }, kind: any) => any} */
-let shownOf = (cell, kind) => {
-  let value = typed(cell.tokens, kind);
+/** @type {(cell: { tokens: any[] }, decl: any) => any} */
+let shownOf = (cell, decl) => {
+  let value = typed(cell.tokens, decl);
   return value !== undefined ? value : text(cell.tokens);
 };
+// The code is spliced into the format string rather than looked up as a
+// symbol, so it must be a code and nothing else. It is: the engine gates a
+// resolved `currency` before it crosses, which is why an author-data code
+// (`currency: "=@.ccy"`) can reach a number format at all (docs/adr/0041).
+// Which code wins is the engine's rule too, taken from `currencyOf` rather
+// than restated: this target needs the code itself where the display targets
+// need presented text, and the two must not drift apart about a denomination.
 /** @type {(out: any, resolved: any, shown: any, intl: any) => void} */
 let paintFmt = (out, resolved, shown, intl) => {
-  let numFmt = numFmtOf(resolved?.format, shown, intl?.currency);
+  let numFmt = numFmtOf(resolved?.format, shown, currencyOf(resolved, intl));
   if (numFmt) out.numFmt = numFmt;
 };
 /** @type {(out: any, shown: any) => void} */
@@ -54,7 +94,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

@@ -15,11 +15,11 @@
  * the packing time. Byte-for-byte output is a goal for the writer that will
  * replace `workbook.js`.
  */
-import { walk } from "quario";
+import { imageError, 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.
@@ -39,7 +39,10 @@ import { append, create, embed, freeze, mark, place, save, sheet } from "./workb
 // them. `@quario/html/style.css` and `packages/viewer/lib/style.js` supply them for
 // that target; keep all four in agreement.
 /** @type {Record<string, any>} */
-let ROLES = { "report-header": { bold: true, size: 14 }, "group-header": { bold: true } };
+let ROLES = {
+  "report-header": { bold: true, size: 14 },
+  "group-header": { bold: true },
+};
 
 // This target's baseline type size, written into every cell rather than left
 // to the writer's own 11. The PDF target carries the same 10, and once a report
@@ -109,12 +112,40 @@ 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
         // written under the baseline alone: an author's `style` must not be
         // able to resize it (docs/adr/0002).
-        intl = { locale: event.locale, currency: event.currency, timeZone: event.timeZone };
+        intl = {
+          locale: event.locale,
+          currency: event.currency,
+          timeZone: event.timeZone,
+        };
         if (event.style) base = under(BASELINE, event.style);
         if (event.marking) {
           mark(workbook, event.marking);
@@ -139,7 +170,11 @@ export function xlsx(options) {
       "split-start": (event) => {
         // The split's own style layers over its band-role default, so a styled
         // split keeps the weight a plain item in the same band would have.
-        split = { fields: [], images: [], under: under(roleOf(event), event.style) };
+        split = {
+          fields: [],
+          images: [],
+          under: under(roleOf(event), event.style),
+        };
       },
       "split-end": () => {
         // The engine emits the bracket as one array, so a `split-end` always
@@ -164,8 +199,10 @@ export function xlsx(options) {
           // The engine vouched for the magic numbers, not for the rest of the
           // file. A header too short to carry a size leaves nothing to place a
           // drawing at, and failing beats dropping the picture in silence
-          // (SCHEMA.md, "Image item").
-          if (!size) throw Error("image: could not read the image's size from its bytes");
+          // (SCHEMA.md, "Image item"). Named on the item through the engine's
+          // own mint, so this failure reads the same from here as it does from
+          // a target that paints or embeds.
+          if (!size) throw imageError(event.path, "could not read the image's size from its bytes");
           known = { ...size, id: embed(workbook, event.bytes, event.format) };
           images.set(event.bytes, known);
         }
@@ -181,17 +218,14 @@ 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 = append(worksheet, headers);
+        let row = merged(event.header.cells, event.header.style);
         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.6.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.6.0",
     "size-limit": "^13.0.3",
     "typescript": "^7.0.2"
   },
   "peerDependencies": {
-    "quario": "^0.4.0"
+    "quario": "^0.6.0"
   },
   "size-limit": [
     {
@@ -56,7 +56,7 @@
         "quario",
         "exceljs"
       ],
-      "limit": "2.4 kB"
+      "limit": "3 kB"
     }
   ],
   "engines": {