@particle-academy/holy-sheet 2.6.0 → 2.7.0

package/CHANGELOG.md

@@ -10,6 +10,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.7.0] — 2026-10-19
+
+### Added
+
+- **`print`** (`orientation`, `fitToWidth`, `footer` with `{page}` / `{pages}`)
+  and **`rowHeights`** (pixels by 1-based row number). Read back, validated and
+  published in the schema. **Nothing to do**: a workbook without them is
+  byte-identical. Same as `particle-academy/holy-sheet` 2.6.0 and
+  `fancy-holy-sheet` 0.6.0; parity holds (`printSetup` fixture).
+
 ## [2.6.0] — 2026-10-11
 
 ### Fixed

package/dist/index.cjs

@@ -418,13 +418,15 @@ var MergedRegion = class {
 
 // src/workbook/sheet.ts
 var Sheet = class {
-  constructor(name, cells = /* @__PURE__ */ new Map(), mergedRegions = [], columnWidths = /* @__PURE__ */ new Map(), frozenRows = 0, frozenCols = 0) {
+  constructor(name, cells = /* @__PURE__ */ new Map(), mergedRegions = [], columnWidths = /* @__PURE__ */ new Map(), frozenRows = 0, frozenCols = 0, rowHeights = /* @__PURE__ */ new Map(), print = null) {
     this.name = name;
     this.cells = cells;
     this.mergedRegions = mergedRegions;
     this.columnWidths = columnWidths;
     this.frozenRows = frozenRows;
     this.frozenCols = frozenCols;
+    this.rowHeights = rowHeights;
+    this.print = print;
   }
   /** rowNumber → (colLetter → Cell), sorted by ascending row number. */
   rows() {
@@ -665,7 +667,9 @@ var Normalizer = class {
       this.normalizeMerges(sheet.mergedRegions ?? []),
       this.normalizeWidths(sheet),
       toInt(sheet.frozenRows ?? 0),
-      toInt(sheet.frozenCols ?? 0)
+      toInt(sheet.frozenCols ?? 0),
+      normalizeRowHeights(sheet.rowHeights),
+      normalizePrint(sheet.print)
     );
   }
   normalizeCellMap(map, sheetName2) {
@@ -856,6 +860,34 @@ function toInt(v) {
   const n = Math.trunc(Number(v));
   return Number.isFinite(n) ? n : 0;
 }
+function phpNumeric(v) {
+  if (typeof v === "number") return Number.isFinite(v) ? v : null;
+  return isNumericString(v) ? numericStringToNumber(v) : null;
+}
+function normalizeRowHeights(map) {
+  const out = /* @__PURE__ */ new Map();
+  if (!isPlainObject(map) && !Array.isArray(map)) return out;
+  for (const [row, px] of Object.entries(map)) {
+    const n = phpNumeric(px);
+    if (/^[1-9]\d{0,6}$/.test(row) && n !== null && n >= 0) out.set(parseInt(row, 10), n);
+  }
+  return new Map([...out.entries()].sort((a, b) => a[0] - b[0]));
+}
+function normalizePrint(print) {
+  if (!isPlainObject(print) && !Array.isArray(print)) return null;
+  const p = print;
+  const orientation = p.orientation === "portrait" || p.orientation === "landscape" ? p.orientation : null;
+  const fitToWidth = p.fitToWidth === true;
+  let footer = null;
+  if (isPlainObject(p.footer) || Array.isArray(p.footer)) {
+    const f = p.footer;
+    const slot = (k) => typeof f[k] === "string" ? f[k] : "";
+    footer = { left: slot("left"), center: slot("center"), right: slot("right") };
+    if (footer.left === "" && footer.center === "" && footer.right === "") footer = null;
+  }
+  if (orientation === null && !fitToWidth && footer === null) return null;
+  return { orientation, fitToWidth, footer };
+}
 
 // src/schema/formula-linter.ts
 var ERR_VALUE = "#VALUE!";
@@ -1703,6 +1735,95 @@ var Validator = class {
         }
       }
     }
+    if (sheet.rowHeights != null) {
+      if (!isPlainObject(sheet.rowHeights) && !Array.isArray(sheet.rowHeights)) {
+        errors.push(
+          error(
+            `${path}.rowHeights`,
+            "object keyed by 1-based row number",
+            typeOf(sheet.rowHeights),
+            sheet.rowHeights,
+            'Row heights map a row NUMBER to pixels: {"1": 32, "4": 28}.'
+          )
+        );
+      } else {
+        for (const [row, px] of Object.entries(sheet.rowHeights)) {
+          const n = typeof px === "number" ? px : isNumericString(px) ? numericStringToNumber(px) : null;
+          if (!/^[1-9]\d{0,6}$/.test(row)) {
+            errors.push(error(
+              `${path}.rowHeights.${row}`,
+              "a 1-based row number",
+              typeOf(row),
+              row,
+              'Keys are row numbers as Excel shows them: "1" is the first row.'
+            ));
+          } else if (n === null || !Number.isFinite(n) || n < 0) {
+            errors.push(error(
+              `${path}.rowHeights.${row}`,
+              "a non-negative number of pixels",
+              typeOf(px),
+              px,
+              "A height is a number of pixels, like 28 (20 is a default row)."
+            ));
+          }
+        }
+      }
+    }
+    if (sheet.print != null) {
+      const print = sheet.print;
+      if (!isPlainObject(print) && !Array.isArray(print)) {
+        errors.push(error(
+          `${path}.print`,
+          "object {orientation?, fitToWidth?, footer?}",
+          typeOf(print),
+          print,
+          'Print setup: {"orientation": "landscape", "fitToWidth": true, "footer": {"right": "Page {page} of {pages}"}}.'
+        ));
+      } else {
+        if (print.orientation != null && print.orientation !== "portrait" && print.orientation !== "landscape") {
+          errors.push(error(
+            `${path}.print.orientation`,
+            "one of: portrait, landscape",
+            typeOf(print.orientation),
+            print.orientation,
+            "Use landscape for a sheet wider than it is tall."
+          ));
+        }
+        if (print.fitToWidth != null && typeof print.fitToWidth !== "boolean") {
+          errors.push(error(
+            `${path}.print.fitToWidth`,
+            "boolean",
+            typeOf(print.fitToWidth),
+            print.fitToWidth,
+            "true scales the sheet to one page wide when printed."
+          ));
+        }
+        if (print.footer != null) {
+          if (!isPlainObject(print.footer) && !Array.isArray(print.footer)) {
+            errors.push(error(
+              `${path}.print.footer`,
+              "object {left?, center?, right?}",
+              typeOf(print.footer),
+              print.footer,
+              "A footer has up to three slots of text."
+            ));
+          } else {
+            const footer = print.footer;
+            for (const slot of ["left", "center", "right"]) {
+              if (footer[slot] != null && typeof footer[slot] !== "string") {
+                errors.push(error(
+                  `${path}.print.footer.${slot}`,
+                  "string",
+                  typeOf(footer[slot]),
+                  footer[slot],
+                  "Footer text; {page} and {pages} print the page number and count."
+                ));
+              }
+            }
+          }
+        }
+      }
+    }
     return errors;
   }
   validateColumn(col, path) {
@@ -2792,6 +2913,22 @@ function sheetToSchema(sheet) {
   }
   if (sheet.frozenRows > 0) out["frozenRows"] = sheet.frozenRows;
   if (sheet.frozenCols > 0) out["frozenCols"] = sheet.frozenCols;
+  if (sheet.rowHeights.size > 0) {
+    const heights = {};
+    for (const [k, v] of sheet.rowHeights) heights[k] = v;
+    out["rowHeights"] = heights;
+  }
+  if (sheet.print !== null) {
+    const print = {};
+    if (sheet.print.orientation !== null) print["orientation"] = sheet.print.orientation;
+    if (sheet.print.fitToWidth) print["fitToWidth"] = true;
+    if (sheet.print.footer !== null) {
+      const footer = {};
+      for (const k of ["left", "center", "right"]) if (sheet.print.footer[k] !== "") footer[k] = sheet.print.footer[k];
+      print["footer"] = footer;
+    }
+    out["print"] = print;
+  }
   return out;
 }
 function cellToSchema(cell) {
@@ -3414,9 +3551,62 @@ var WorksheetParser = {
     const merges = parseMerges(xml);
     const columnWidths = parseColumnWidths(xml);
     const [frozenRows, frozenCols] = parseFrozen(xml);
-    return new Sheet(name, cells, merges, columnWidths, frozenRows, frozenCols);
+    return new Sheet(name, cells, merges, columnWidths, frozenRows, frozenCols, parseRowHeights(xml), parsePrint(xml));
   }
 };
+function parseRowHeights(xml) {
+  const out = /* @__PURE__ */ new Map();
+  const sheetData = el(xml, "sheetData");
+  if (!sheetData) return out;
+  for (const row of els(sheetData, "row")) {
+    const r = parseInt(at(row, "r") ?? "0", 10);
+    const custom = at(row, "customHeight");
+    const ht = at(row, "ht");
+    if (r > 0 && ht !== void 0 && (custom === "1" || custom === "true")) {
+      out.set(r, Math.round(parseFloat(ht) / 0.75 * 100) / 100);
+    }
+  }
+  return out;
+}
+function parsePrint(xml) {
+  const fitToPage = ["1", "true"].includes(at(el(el(xml, "sheetPr"), "pageSetUpPr"), "fitToPage") ?? "");
+  const setup = el(xml, "pageSetup");
+  const o = at(setup, "orientation");
+  const orientation = o === "portrait" || o === "landscape" ? o : null;
+  const fitToWidth = fitToPage && setup !== void 0 && at(setup, "fitToWidth") === "1" && ["0", ""].includes(at(setup, "fitToHeight") ?? "");
+  const oddFooter = el(el(xml, "headerFooter"), "oddFooter");
+  const footer = oddFooter !== void 0 ? parseFooterCodes(oddFooter.text) : null;
+  if (orientation === null && !fitToWidth && footer === null) return null;
+  return { orientation, fitToWidth, footer };
+}
+function parseFooterCodes(codes) {
+  const slots = { left: "", center: "", right: "" };
+  let current = "center";
+  const len = codes.length;
+  for (let i = 0; i < len; i++) {
+    const ch = codes[i];
+    if (ch !== "&" || i + 1 >= len) {
+      slots[current] += ch;
+      continue;
+    }
+    const next = codes[++i];
+    if (next === "&") slots[current] += "&";
+    else if (next === "L") current = "left";
+    else if (next === "C") current = "center";
+    else if (next === "R") current = "right";
+    else if (next === "P") slots[current] += "{page}";
+    else if (next === "N") slots[current] += "{pages}";
+    else if (next === '"') {
+      const close = codes.indexOf('"', i + 1);
+      i = close === -1 ? len : close;
+    } else if (/[0-9]/.test(next)) {
+      while (i + 1 < len && /[0-9]/.test(codes[i + 1])) i++;
+    } else if (next === "K") {
+      i = Math.min(len - 1, i + 6);
+    }
+  }
+  return slots.left === "" && slots.center === "" && slots.right === "" ? null : slots;
+}
 function parseCells(xml, stylesIndex, comments, sharedStrings) {
   const cells = /* @__PURE__ */ new Map();
   const sheetData = el(xml, "sheetData");
@@ -3792,6 +3982,19 @@ function hexToArgb(hex2) {
 
 // src/writer/xlsx-writer.ts
 var encoder2 = new TextEncoder();
+function footerCodes(footer) {
+  let codes = "";
+  for (const [slot, code] of [["left", "&L"], ["center", "&C"], ["right", "&R"]]) {
+    if (footer[slot] !== "") {
+      codes += code + footer[slot].replace(/&/g, "&&").replace(/\{pages\}/g, "&N").replace(/\{page\}/g, "&P");
+    }
+  }
+  return codes;
+}
+function decimal(value) {
+  const out = value.toFixed(4).replace(/0+$/, "").replace(/\.$/, "");
+  return out === "" || out === "-0" ? "0" : out;
+}
 var XlsxWriter = class {
   toBytes(workbook) {
     const styles = new StylesRegistry();
@@ -3880,14 +4083,20 @@ var XlsxWriter = class {
       }
       colsXml += "</cols>";
     }
+    const rows = sheet.rows();
+    for (const rowIndex of sheet.rowHeights.keys()) {
+      if (!rows.has(rowIndex)) rows.set(rowIndex, /* @__PURE__ */ new Map());
+    }
     let rowsXml = "";
-    for (const [rowIndex, row] of sheet.rows()) {
+    for (const [rowIndex, row] of [...rows.entries()].sort((a, b) => a[0] - b[0])) {
       let cellsXml = "";
       const sortedCols = [...row.keys()].sort();
       for (const col of sortedCols) {
         cellsXml += this.cellXml(row.get(col), styles);
       }
-      rowsXml += `<row r="${rowIndex}">${cellsXml}</row>`;
+      const height = sheet.rowHeights.get(rowIndex);
+      const ht = height !== void 0 ? ` ht="${decimal(height * 0.75)}" customHeight="1"` : "";
+      rowsXml += cellsXml === "" ? `<row r="${rowIndex}"${ht}/>` : `<row r="${rowIndex}"${ht}>${cellsXml}</row>`;
     }
     let mergesXml = "";
     if (sheet.mergedRegions.length > 0) {
@@ -3896,7 +4105,14 @@ var XlsxWriter = class {
       mergesXml += "</mergeCells>";
     }
     const legacyDrawing = sheet.hasComments() ? '<legacyDrawing r:id="rId1"/>' : "";
-    return '<?xml version="1.0" encoding="UTF-8" standalone="yes"?><worksheet xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships">' + sheetViewsXml + colsXml + `<sheetData>${rowsXml}</sheetData>` + mergesXml + legacyDrawing + "</worksheet>";
+    const print = sheet.print;
+    const sheetPrXml = print?.fitToWidth ? '<sheetPr><pageSetUpPr fitToPage="1"/></sheetPr>' : "";
+    let pageSetupXml = "";
+    if (print !== null && (print.orientation !== null || print.fitToWidth)) {
+      pageSetupXml = "<pageSetup" + (print.orientation !== null ? ` orientation="${print.orientation}"` : "") + (print.fitToWidth ? ' fitToWidth="1" fitToHeight="0"' : "") + "/>";
+    }
+    const headerFooterXml = print?.footer ? `<headerFooter><oddFooter>${this.escape(footerCodes(print.footer))}</oddFooter></headerFooter>` : "";
+    return '<?xml version="1.0" encoding="UTF-8" standalone="yes"?><worksheet xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships">' + sheetPrXml + sheetViewsXml + colsXml + `<sheetData>${rowsXml}</sheetData>` + mergesXml + pageSetupXml + headerFooterXml + legacyDrawing + "</worksheet>";
   }
   cellXml(cell, styles) {
     const ref = cell.address;
@@ -5013,6 +5229,31 @@ var holy_sheet_schema_default = {
           type: "integer",
           minimum: 0,
           description: "How many columns stay visible while the sheet scrolls sideways. Set to 1 when the first column is the label for the row."
+        },
+        rowHeights: {
+          type: "object",
+          description: 'Row heights in pixels, keyed by 1-based row NUMBER as Excel shows it: {"1": 32, "4": 28}. A default row is 20; give a title row or a header row room (28-36) instead of packing text against its fill.',
+          propertyNames: { pattern: "^[1-9][0-9]*$" },
+          additionalProperties: { type: "number", minimum: 0 }
+        },
+        print: {
+          type: "object",
+          additionalProperties: false,
+          description: "How the sheet prints. A sheet wider than a page splits its columns across pages unless fitToWidth is set.",
+          properties: {
+            orientation: { type: "string", enum: ["portrait", "landscape"] },
+            fitToWidth: { type: "boolean", description: "Scale the sheet to one page wide (as many pages tall as it needs)." },
+            footer: {
+              type: "object",
+              additionalProperties: false,
+              description: 'A printed footer: up to three slots. {page} and {pages} print the page number and count: {"left": "Q3 Revenue Review", "right": "Page {page} of {pages}"}.',
+              properties: {
+                left: { type: "string" },
+                center: { type: "string" },
+                right: { type: "string" }
+              }
+            }
+          }
         }
       }
     },
@@ -5221,7 +5462,7 @@ var holy_sheet_schema_default = {
 };
 
 // src/agent.ts
-var VERSION = "2.6.0";
+var VERSION = "2.7.0";
 function toU8(input) {
   return input instanceof Uint8Array ? input : new Uint8Array(input);
 }