@quario/xlsx 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -7,6 +7,69 @@ 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

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
 
@@ -107,8 +122,13 @@ unread, and all of it may change without a breaking change.
 | `color`, `background`                                  | Font colour, solid fill                                                                                                              |
 | `align`                                                | Horizontal alignment                                                                                                                 |
 | `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.
+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 { 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} */

package/lib/index.js

@@ -15,7 +15,7 @@
  * 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 { merge as under } from "./style.js";
 import { pixels } from "./image.js";
@@ -39,7 +39,10 @@ import { append, create, embed, freeze, mark, place, save, sheet, span } from ".
 // 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
@@ -138,7 +141,11 @@ export function xlsx(options) {
         // 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);
@@ -163,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
@@ -188,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);
         }
@@ -205,12 +218,7 @@ export function xlsx(options) {
         place(worksheet, known.id, known, append(worksheet, []));
       },
       "table-start": (event) => {
-        let row = merged(
-          event.columns
-            .filter((/** @type {any} */ column) => column.header)
-            .map((/** @type {any} */ column) => column.header),
-          event.style,
-        );
+        let row = merged(event.header.cells, event.header.style);
         if (!frozen) {
           freeze(worksheet, row);
           frozen = true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quario/xlsx",
-  "version": "0.5.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.5.0",
+    "quario": "^0.6.0",
     "size-limit": "^13.0.3",
     "typescript": "^7.0.2"
   },
   "peerDependencies": {
-    "quario": "^0.5.0"
+    "quario": "^0.6.0"
   },
   "size-limit": [
     {