@quario/xlsx 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -7,6 +7,53 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-09-01
+
+### Added
+
+- **The report default reaches every cell.** A report's top-level `style`
+  replaces this target's baseline, so a document declaring a face and size gets
+  them in cells that declare nothing of their own. It is the layer under the
+  band-role defaults — a report declaring `size: 12` still writes its report
+  header at 14 — and under each cell's own style.
+
+- **`uppercase` is accepted and deliberately not read.** A spreadsheet font
+  has no text-transform, and writing capitals into the cell instead would turn
+  presentation into data — the cell would stop round-tripping and would sort
+  differently. The cell keeps the text you wrote; every other declaration on
+  it still applies. Same posture as the column widths this target withdrew.
+
+- **A split is one row, its slots the cells across it.** The grid's own
+  reading of values placed beside each other. Slot `width` shares go unread,
+  on exactly the ground the table's column widths do — a worksheet's columns
+  are global to the sheet. The split's own style is what its slots sit under,
+  layering the way a table row's does, and a slot that renders nothing writes
+  an empty cell so the cells either side keep their columns.
+
+### Changed
+
+- **Every cell is written at 10 points unless something declares otherwise.**
+  The size was previously left to the writer's own default of 11. Now that a
+  report can declare its own size, this target and the PDF carrying different
+  numbers for one declaration is exactly what the targets' agreement rule
+  forbids. A worksheet's row height follows its font size, so existing unstyled
+  sheets come out slightly tighter.
+
+- **Display-text `Date`s join as ISO 8601 UTC.** A `Date` inside a mixed
+  cell (literal text plus interpolation) joined through `String(date)`, which
+  bakes the host's timezone and locale into the worksheet. It now joins
+  through the engine's shared display rule as `toISOString()` text. Typed
+  cells are untouched: a cell that is one bare `Date` interpolation still
+  writes a native date.
+
+### Fixed
+
+- **Cells carry their font face explicitly.** Text declaring no `family` used
+  to inherit whatever the workbook writer defaulted to, which agreed with the
+  other targets only by coincidence. It now writes the same face that
+  `family: "sans"` resolves to, so the baseline is a rule rather than a
+  property of the library underneath.
+
 ## [0.1.0] - 2026-08-27
 
 ### Added

package/lib/image.js

@@ -13,9 +13,6 @@
 /** @type {(bytes: Uint8Array, at: number) => number} */
 let word = (bytes, at) => (bytes[at] << 8) | bytes[at + 1];
 
-/** @type {(bytes: Uint8Array) => { width: number, height: number }} */
-let png = (bytes) => ({ width: word(bytes, 18), height: word(bytes, 22) });
-
 // The dimensions live in the frame header, the first SOFn marker: every
 // code in C0..CF except the three in that range that are not frames --
 // DHT, the JPG extension, and DAC.
@@ -42,6 +39,7 @@ let jpeg = (bytes) => {
  * @returns {{ width: number, height: number } | null} The size, if readable.
  */
 export let pixels = (bytes, format) => {
-  let size = format === "png" ? png(bytes) : jpeg(bytes);
+  // A PNG carries the two numbers in its IHDR at a fixed offset.
+  let size = format === "png" ? { width: word(bytes, 18), height: word(bytes, 22) } : jpeg(bytes);
   return size.width > 0 && size.height > 0 ? size : null;
 };

package/lib/index.js

@@ -17,6 +17,7 @@
  */
 import { walk } from "quario";
 import { field } from "./cell.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";
 
@@ -40,6 +41,14 @@ import { append, create, embed, freeze, mark, place, save, sheet } from "./workb
 /** @type {Record<string, any>} */
 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
+// can declare its own `style.size` the two supplying different numbers for one
+// declaration is exactly what docs/adr/0014's corollary forbids. A worksheet's
+// row height follows its font size, so this is visible in the grid as well as
+// in the type (docs/adr/0033).
+let BASELINE = { size: 10 };
+
 // The unlicensed-output marking (LICENSE section 6): one styled banner row
 // above the report, written only on keyless renders through the same cell
 // path as every other row. This is the banner's look; the wording arrives on
@@ -71,22 +80,73 @@ export function xlsx(options) {
     // down a thousand rows is one copy in the file rather than a thousand.
     /** @type {Map<Uint8Array, any>} */
     let images = new Map();
+    // The layers under an event's own style, outermost first: this target's
+    // baseline, then the report default the author declared, then the band-role
+    // default if the role carries one. `base` is the first two, settled once
+    // per render off `report-start`.
+    let base = BASELINE;
+    // One cell, wearing everything beneath it. Every cell in the sheet goes
+    // through here rather than through `field` directly, so `base` -- this
+    // target's baseline plus the author's report default -- cannot be
+    // forgotten by a call site that means "nothing encloses this". The
+    // marking is the one deliberate exception, and says so where it is
+    // written.
+    let cell = (/** @type {any} */ value, /** @type {any} */ over = null) =>
+      field(value, under(base, over));
+    // The band-role default an event sits under, if its role carries one.
+    let roleOf = (/** @type {any} */ event) =>
+      Object.hasOwn(ROLES, event.role) ? ROLES[event.role] : null;
+    // The split being filled, if any: the fields its slots have written and
+    // the pictures owed an anchor, which is the row the whole split lands on.
+    // Splits never nest, so one is enough.
+    /** @type {{ fields: any[], images: any[], under: any } | null} */
+    let split = null;
     // A table row and a total row differ only in the style they sit under.
-    let record = (/** @type {any} */ event, /** @type {any} */ under) =>
+    let record = (/** @type {any} */ event, /** @type {any} */ layer) =>
       append(
         worksheet,
-        event.cells.map((/** @type {any} */ cell) => field(cell, under)),
+        event.cells.map((/** @type {any} */ each) => cell(each, layer)),
       );
     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).
+        if (event.style) base = under(BASELINE, event.style);
         if (event.marking) {
           mark(workbook, event.marking);
-          append(worksheet, [field({ tokens: [{ literal: event.marking }], style: BANNER }, null)]);
+          append(worksheet, [
+            field({ tokens: [{ literal: event.marking }], style: BANNER }, BASELINE),
+          ]);
         }
       },
       item: (event) => {
-        let role = Object.hasOwn(ROLES, event.role) ? ROLES[event.role] : null;
-        append(worksheet, [field({ tokens: event.tokens, style: event.style }, role)]);
+        let written = cell(
+          { tokens: event.tokens, style: event.style },
+          split ? split.under : roleOf(event),
+        );
+        if (split) split.fields.push(written);
+        else append(worksheet, [written]);
+      },
+      // A split is one row, its slots the cells across it -- the grid's own
+      // reading of items placed beside each other. Slot `width` shares go
+      // unread on the same ground the table's column widths do: a worksheet's
+      // columns are global to the sheet. The split's own style is what its
+      // slots sit under, exactly as a table row's is.
+      "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-end": () => {
+        // The engine emits the bracket as one array, so a `split-end` always
+        // has its opening and `split` is never null here.
+        let owed = /** @type {{ fields: any[], images: any[] }} */ (split);
+        split = null;
+        let row = append(worksheet, owed.fields);
+        // A picture in a slot floats from the split's own row: the cell under
+        // it holds the slot so the fields either side keep their columns.
+        for (let known of owed.images) place(worksheet, known.id, known, row);
       },
       // An image is not a cell: it takes one row as its anchor and floats
       // over the sheet from there, at its own pixel size. `fit` is not read
@@ -106,12 +166,19 @@ export function xlsx(options) {
           known = { ...size, id: embed(workbook, event.bytes, event.format) };
           images.set(event.bytes, known);
         }
+        if (split) {
+          // The slot keeps its cell, empty, and the picture waits for the row
+          // the whole split lands on.
+          split.fields.push(cell({ tokens: [] }));
+          split.images.push(known);
+          return;
+        }
         // The anchor: a row of its own, with nothing written in it, which the
         // picture then floats over.
         place(worksheet, known.id, known, append(worksheet, []));
       },
       "table-start": (event) => {
-        let headers = event.columns.map((/** @type {any} */ column) => field(column.header, null));
+        let headers = event.columns.map((/** @type {any} */ column) => cell(column.header));
         let row = append(worksheet, headers);
         if (!frozen) {
           freeze(worksheet, row);

package/lib/style.js

@@ -11,14 +11,13 @@
  */
 
 /** @type {(value: any) => boolean} */
-let finite = (value) => typeof value === "number" && Number.isFinite(value);
+let finite = (value) => Number.isFinite(value);
 let HEX = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i;
 
 // The generic families as the fonts spreadsheet apps ship with; any other
 // name passes through verbatim for the host application to resolve.
 /** @type {Record<string, string>} */
 let FAMILY = { sans: "Calibri", serif: "Times New Roman", mono: "Courier New" };
-let ALIGNMENTS = ["left", "center", "right"];
 
 // A declared colour as an ARGB string, or null when the value is not one.
 /** @type {(value: any) => string | null} */
@@ -41,9 +40,13 @@ let put = (out, key, value) => {
   return out;
 };
 
+// The face a declared family names, or the baseline one an undeclared family
+// resolves to: text that declares nothing renders in the same face
+// `family: "sans"` does, written rather than left to the writer's own default
+// (docs/adr/0014). One answer, in one place.
 /** @type {(family: any) => string} */
 let face = (family) => {
-  if (typeof family !== "string" || !family) return "";
+  if (typeof family !== "string" || !family) return FAMILY.sans;
   let key = family.toLowerCase();
   // Own-key lookup: `constructor` must not resolve an inherited member.
   return Object.hasOwn(FAMILY, key) ? FAMILY[key] : family;
@@ -59,8 +62,8 @@ let tint = (value) => {
   return color ? { argb: color } : null;
 };
 
-// The font half of a resolved style, or null when the style declares none
-// of it.
+// The font half of a resolved style. Never null: every cell carries the
+// baseline face even when it declares nothing else.
 /** @type {(style: any) => any} */
 let font = (style) => {
   let out = put(null, "name", face(style.family));
@@ -70,6 +73,12 @@ let font = (style) => {
   out = put(out, "underline", flag(style.underline));
   // exceljs names the flag `strike`; the authoring surface says strikethrough.
   out = put(out, "strike", flag(style.strikethrough));
+  // `uppercase` is deliberately unread: a spreadsheet font has no
+  // text-transform (OOXML's font carries none, and neither does the writer's
+  // model), and uppercasing the string instead would make presentation into
+  // data -- the cell would stop round-tripping and sort differently. A
+  // mapping quario cannot honestly make is withdrawn rather than invented,
+  // exactly as the column widths were (docs/adr/0008).
   return put(out, "color", tint(style.color));
 };
 
@@ -79,7 +88,8 @@ let fill = (value) => {
   return color ? { type: "pattern", pattern: "solid", fgColor: { argb: color } } : null;
 };
 /** @type {(value: any) => any} */
-let align = (value) => (ALIGNMENTS.includes(value) ? { horizontal: value } : null);
+let align = (value) =>
+  value === "left" || value === "center" || value === "right" ? { horizontal: value } : null;
 
 // The whole-cell reading: the font plus the parts only a cell can carry.
 /** @type {(style: any) => any} */

package/lib/workbook.js

@@ -9,14 +9,13 @@
  */
 import ExcelJS from "exceljs";
 
-// Host metadata keys as the workbook properties they become.
-/** @type {Record<string, string>} */
-let META = { title: "title", author: "creator", subject: "subject" };
-/** @type {(workbook: any, meta: any) => any} */
+// Host metadata keys as the workbook properties they become -- `author` is the
+// only one exceljs names differently.
+/** @type {(workbook: any, meta: any) => void} */
 let describe = (workbook, meta) => {
-  if (!meta) return workbook;
-  for (let from in META) if (typeof meta[from] === "string") workbook[META[from]] = meta[from];
-  return workbook;
+  if (typeof meta.title === "string") workbook.title = meta.title;
+  if (typeof meta.author === "string") workbook.creator = meta.author;
+  if (typeof meta.subject === "string") workbook.subject = meta.subject;
 };
 
 // A fresh workbook. Never the current time: a timestamp would make the same
@@ -26,16 +25,18 @@ let create = (meta) => {
   let workbook = new ExcelJS.Workbook();
   workbook.created = new Date(0);
   workbook.modified = new Date(0);
-  return describe(workbook, meta);
+  if (meta) describe(workbook, meta);
+  return workbook;
 };
 
 /** @type {(workbook: any) => any} */
 let sheet = (workbook) => workbook.addWorksheet("Report");
 
-let KEYS = ["font", "fill", "alignment"];
 /** @type {(cell: any, format: any) => void} */
 let paint = (cell, format) => {
-  for (let key of KEYS) if (format[key]) cell[key] = format[key];
+  if (format.font) cell.font = format.font;
+  if (format.fill) cell.fill = format.fill;
+  if (format.alignment) cell.alignment = format.alignment;
 };
 
 // Write one worksheet row from cell descriptors; returns the row number.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quario/xlsx",
-  "version": "0.1.0",
+  "version": "0.2.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.1.0",
+    "quario": "^0.2.0",
     "size-limit": "^13.0.3",
     "typescript": "^7.0.2"
   },
   "peerDependencies": {
-    "quario": "^0.1.0"
+    "quario": "^0.2.0"
   },
   "size-limit": [
     {