@quario/xlsx 0.2.0 → 0.3.0

package/CHANGELOG.md

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

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/index.js

@@ -17,7 +17,7 @@
  */
 import { walk } from "quario";
 import { field } from "./cell.js";
-import { merge as under } from "./style.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";
 
@@ -85,6 +85,8 @@ export function xlsx(options) {
     // 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
@@ -92,7 +94,7 @@ export function xlsx(options) {
     // 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));
+      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;
@@ -112,6 +114,7 @@ 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 };
         if (event.style) base = under(BASELINE, event.style);
         if (event.marking) {
           mark(workbook, event.marking);
@@ -178,7 +181,9 @@ 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));
+        let headers = event.columns.map((/** @type {any} */ column) =>
+          cell(column.header, event.style),
+        );
         let row = append(worksheet, headers);
         if (!frozen) {
           freeze(worksheet, row);
@@ -186,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

@@ -13,6 +13,10 @@
 /** @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" };
 
 // The generic families as the fonts spreadsheet apps ship with; any other
 // name passes through verbatim for the host application to resolve.
@@ -29,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) => {
@@ -91,12 +114,37 @@ let fill = (value) => {
 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

@@ -32,11 +32,10 @@ let create = (meta) => {
 /** @type {(workbook: any) => any} */
 let sheet = (workbook) => workbook.addWorksheet("Report");
 
+let SLOTS = ["font", "fill", "border", "alignment", "numFmt"];
 /** @type {(cell: any, format: any) => void} */
 let paint = (cell, format) => {
-  if (format.font) cell.font = format.font;
-  if (format.fill) cell.fill = format.fill;
-  if (format.alignment) cell.alignment = format.alignment;
+  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.2.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.2.0",
+    "quario": "^0.3.0",
     "size-limit": "^13.0.3",
     "typescript": "^7.0.2"
   },
   "peerDependencies": {
-    "quario": "^0.2.0"
+    "quario": "^0.3.0"
   },
   "size-limit": [
     {
@@ -56,7 +56,7 @@
         "quario",
         "exceljs"
       ],
-      "limit": "2 kB"
+      "limit": "2.4 kB"
     }
   ],
   "engines": {