@quario/xlsx 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -7,6 +7,80 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-09-02
+
+### Added
+
+- **`format` maps to a number format; the cell stays typed.** `number` is
+  `#,##0.00`, `percent` `0.00%`, `date` `yyyy-mm-dd`, `currency` the
+  instance currency code as `"USD"#,##0.00`. A kind on the wrong type
+  contributes nothing.
+
+- **Cell borders map; padding and flow spacing do not.** `solid` is exceljs
+  `thin`; `dashed` and `dotted` keep their names. A header-row, row, or
+  total-row box fans onto that row's cells; a cell that named any of a
+  side's three keys owns that side whole. Padding is unread: a worksheet
+  cell has no inset. Flow spacing is unread: a grid has no flow.
+
+- **`page.margin` and report-header `height` are unread.** A grid has no
+  page top to pin from.
+
+### Changed
+
+- **A table total emits N rows.** Each `total-row` is one worksheet row, as
+  each data row is.
+
+- **A cell whose display contains a newline wraps.** `wrapText` is this
+  target's mapping of a literal newline as a line break, so `"one\ntwo"` is
+  two lines in the grid. Single-line cells are unchanged.
+
+## [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/cell.js

@@ -3,24 +3,63 @@
  * 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.
+ * 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, merge } from "./style.js";
+import { format as look, sides } from "./style.js";
+
+/** @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),
+};
+/** @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 {(cell: { tokens: any[] }) => any} */
+let shownOf = (cell) => {
+  let value = typed(cell.tokens);
+  return value !== undefined ? value : text(cell.tokens);
+};
+/** @type {(out: any, resolved: any, shown: any, intl: any) => void} */
+let paintFmt = (out, resolved, shown, intl) => {
+  let numFmt = numFmtOf(resolved?.format, shown, intl?.currency);
+  if (numFmt) out.numFmt = numFmt;
+};
+/** @type {(out: any, shown: any) => void} */
+let paintWrap = (out, shown) => {
+  if (typeof shown === "string" && /[\r\n]/.test(shown))
+    out.alignment = { ...out.alignment, wrapText: true };
+};
 
 /**
  * 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).
  *
- * @type {(cell: { tokens: any[], style?: any }, under: any) => { value: any, format: any }}
+ * @type {(cell: { tokens: any[], style?: any }, under: any, intl?: any) => { value: any, format: any }}
  */
-let field = (cell, under) => {
-  let resolved = merge(under, cell.style);
-  let value = typed(cell.tokens);
-  return {
-    value: value !== undefined ? value : text(cell.tokens),
-    format: format(resolved),
-  };
+let field = (cell, under, intl) => {
+  let resolved = sides(under, cell.style);
+  let shown = shownOf(cell);
+  let out = look(resolved);
+  paintFmt(out, resolved, shown, intl);
+  paintWrap(out, shown);
+  return { value: shown, format: out };
 };
 
 export { field };

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 { sides 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,76 @@ 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;
+    /** @type {{ locale?: string, currency?: string, timeZone?: string } | null} */
+    let intl = null;
+    // 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), intl);
+    // 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).
+        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);
-          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 +169,21 @@ 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, event.style),
+        );
         let row = append(worksheet, headers);
         if (!frozen) {
           freeze(worksheet, row);
@@ -119,7 +191,7 @@ export function xlsx(options) {
         }
       },
       row: (event) => record(event, event.style),
-      "total-row": (event) => record(event, null),
+      "total-row": (event) => record(event, event.style),
     });
     return save(workbook);
   };

package/lib/style.js

@@ -11,14 +11,17 @@
  */
 
 /** @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;
+let SIDES = ["Top", "Right", "Bottom", "Left"];
+let BORDER_PARTS = ["Width", "Style", "Color"];
+/** @type {Record<string, string>} */
+let LINE = { solid: "thin", dashed: "dashed", dotted: "dotted" };
 
 // 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} */
@@ -30,9 +33,28 @@ let argb = (value) => {
   return "FF" + digits.toUpperCase();
 };
 
-// Style blocks layer outward-in: row under cell.
+// 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.
 /** @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) => {
@@ -41,9 +63,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 +85,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 +96,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,14 +111,40 @@ 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;
+
+/** @type {(width: any) => boolean} */
+let isStroke = (width) => finite(width) && width > 0;
+/** @type {(named: any) => string | null} */
+let lineOf = (named) => {
+  if (typeof named !== "string") return null;
+  return Object.hasOwn(LINE, named) ? LINE[named] : null;
+};
+
+/** @type {(style: any, side: string) => any} */
+let edge = (style, side) => {
+  let line = lineOf(style["border" + side + "Style"]);
+  let color = argb(style["border" + side + "Color"]);
+  if (!isStroke(style["border" + side + "Width"]) || !line || !color) return null;
+  return { style: line, color: { argb: color } };
+};
+
+/** @type {(style: any) => any} */
+let border = (style) => {
+  let out = null;
+  for (let side of SIDES) out = put(out, side.toLowerCase(), edge(style, side));
+  return out;
+};
 
 // The whole-cell reading: the font plus the parts only a cell can carry.
+// Padding is unread: a worksheet cell has no inset (docs/adr/0008).
 /** @type {(style: any) => any} */
 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));
 };
 
-export { format, merge };
+export { format, sides };

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,17 @@ 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"];
+let SLOTS = ["font", "fill", "border", "alignment", "numFmt"];
 /** @type {(cell: any, format: any) => void} */
 let paint = (cell, format) => {
-  for (let key of KEYS) if (format[key]) cell[key] = format[key];
+  for (let key of SLOTS) if (format[key]) cell[key] = format[key];
 };
 
 // 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.3.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.3.0",
     "size-limit": "^13.0.3",
     "typescript": "^7.0.2"
   },
   "peerDependencies": {
-    "quario": "^0.1.0"
+    "quario": "^0.3.0"
   },
   "size-limit": [
     {
@@ -56,7 +56,7 @@
         "quario",
         "exceljs"
       ],
-      "limit": "2 kB"
+      "limit": "2.4 kB"
     }
   ],
   "engines": {