@quario/xlsx 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -7,6 +7,85 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-09-07
+
+### Added
+
+- **Styled runs become rich text.** A cell of more than one styled run is written
+  as rich text, each run's font merged over the cell's — so bold, italic,
+  underline, strikethrough, size, face and colour survive into the grid. A
+  run-level `background` is not read: a spreadsheet's rich-text runs carry fonts
+  only, and filling the cell would colour text nobody asked to colour. A cell of
+  exactly one run stays a typed cell, so a single styled amount is still a
+  number.
+
+- **A run inside a sentence presents its value.** A run holding one
+  interpolation under a `format` shows the same decimals here as on the page,
+  where a mixed cell used to show the bare value.
+
+## [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 withdrawn, 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.
+drawing at its natural pixel size. Placement here is best-effort. `fit`, `alt`, and `style` are
+unused, 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
 
@@ -116,14 +136,14 @@ The first table's header row anchors the frozen view. Everything from that row u
 while the body scrolls, the spreadsheet analogue of the PDF target's repeated headers. A report
 without a table freezes nothing. This is normative.
 
-### Widths are not read
+### Widths are withdrawn
 
 Column `width` percentages size nothing here, and every worksheet column keeps the application
 default. A width is a share of the _table_ width, and a worksheet's columns are global to the sheet.
 Column A carries the flattened band item rows and the table's first column alike, so there is no
 table for a share to be a share of.
 
-### Page columns are not read
+### Page columns are withdrawn
 
 A page column count sizes and splits nothing here, and will not change, as `break: "page"` is
 ignored. Page columns are strips of a page, and this target has no page to strip.

package/lib/cell.js

@@ -2,43 +2,84 @@
  * From an event cell to a plain cell descriptor `{ value, format }`, built on
  * the engine's `typed` stream rule. `value` is a native number, boolean, or
  * Date when the cell is one bare interpolation (so numbers stay computable in
- * the sheet), and the display-text join otherwise. `format` is the resolved
- * cell-level formatting from the style module. Display text that contains a
- * newline gains `wrapText` so the break is visible in the grid.
+ * the sheet), the worksheet's rich-text shape when the cell holds more than
+ * one styled run, and the display-text join otherwise. `format` is the
+ * resolved 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, merge } from "./style.js";
+import { currencyOf, display, format as present, styledRuns, text, typed } from "quario";
+import { font, 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} */
@@ -47,14 +88,62 @@ let paintWrap = (out, shown) => {
     out.alignment = { ...out.alignment, wrapText: true };
 };
 
+// One run's presented text: literals verbatim, every value through the
+// declaration that run resolved. A run holding a single value token presents
+// it, so a formatted amount inside a sentence reads the same here as it does
+// on the page -- SCHEMA.md pins that the fraction digits are the same in every
+// target that presents, and this target presents (ADR 0061). A run the engine
+// withdrew the declaration from has nothing to present with and falls to
+// display text, which is what the whole cell used to do.
+/** @type {(tokens: any[], style: any, intl: any) => string} */
+let shownText = (tokens, style, intl) => {
+  let out = "";
+  for (let token of tokens)
+    out +=
+      "literal" in token
+        ? token.literal
+        : (present(token.value, style, intl) ?? display(token.value));
+  return out;
+};
+
+// A cell of more than one styled run takes the worksheet's rich-text shape:
+// each run's **font half** merged over the cell font, and nothing else. A
+// run-level `background` is inert -- spreadsheet rich-text runs carry fonts
+// only, and filling the cell would colour text the author did not name -- and
+// so is a run-level number format, since a cell has one and this cell is text.
+// No typed cell is lost: a cell of more than one run holds more than one token
+// and was display text already.
+/** @type {(cell: any, styled: any[], under: any, intl: any) => any} */
+let rich = (cell, styled, under, intl) => {
+  let base = merge(under, cell.style);
+  let out = look(base);
+  let parts = styled.map((one) => {
+    let style = one.style ? merge(base, one.style) : base;
+    return { font: font(style), text: shownText(one.tokens, style, intl) };
+  });
+  paintWrap(out, parts.map((part) => part.text).join(""));
+  return { value: { richText: parts }, format: out };
+};
+
+// The style a cell of one styled run wears: that run's resolved answer, which
+// already carries the cell's own declarations, or the cell's where it has no
+// run at all.
+/** @type {(cell: any, styled: any[]) => any} */
+let soleStyle = (cell, styled) => styled[0]?.style ?? cell.style;
+
 /**
  * Resolve one event cell against its enclosing style (a row's style, or an
  * item's band-role default — the layer under the cell's own).
  *
+ * A cell of exactly one styled run wears that run's answer whole, so a single
+ * styled amount is still a number in the grid.
+ *
  * @type {(cell: { tokens: any[], style?: any }, under: any, intl?: any) => { value: any, format: any }}
  */
 let field = (cell, under, intl) => {
-  let resolved = merge(under, cell.style);
+  let styled = styledRuns(cell.tokens);
+  if (styled.length > 1) return rich(cell, styled, under, intl);
+  let resolved = merge(under, soleStyle(cell, styled));
   let shown = shownOf(cell, resolved?.format);
   let out = look(resolved);
   paintFmt(out, resolved, shown, intl);

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";
@@ -27,19 +27,24 @@ import { append, create, embed, freeze, mark, place, save, sheet, span } from ".
 
 // Band-role omakase defaults, applied under the author's own style so a
 // declared style always wins. Only the headline roles carry one; every other
-// band writes plain cells. The PDF target carries the same two, byte-identical,
-// in its own `style.js` — SCHEMA.md states the pair for both, so they move
-// together, and a target imports only public engine helpers so there is nowhere
-// to share them from.
+// band writes plain cells. SCHEMA.md states the pair, and a target imports only
+// public engine helpers so there is nowhere to share them from.
 //
 // `@quario/html` deliberately carries none of them: its consumer has a
 // stylesheet and the `q-*` classes are the seam, where a worksheet has neither.
 // The rule is docs/adr/0014-a-target-supplies-defaults-only-where-its-consumer-has-no-seam.md —
 // a target supplies defaults only where its consumer has no seam to supply
-// them. `@quario/html/style.css` and `packages/viewer/lib/style.js` supply them for
-// that target; keep all four in agreement.
+// them.
+//
+// `test/omakase-defaults.test.js` is what holds the copies in agreement. This
+// comment names the gate rather than listing the files, because the list is
+// what rotted: it used to name `packages/viewer/lib/style.js` and a `style.js`
+// of the PDF target's own, and neither file exists.
 /** @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 +143,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 +172,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 +201,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 +220,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/lib/style.js

@@ -138,4 +138,4 @@ let format = (style) => {
   return put(out, "alignment", alignment(style));
 };
 
-export { format, merge };
+export { font, format, merge };

package/package.json

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