@particle-academy/holy-sheet 2.6.0 → 2.7.0

package/dist/index.d.cts

@@ -58,6 +58,18 @@ interface SheetSchema {
     columnWidths?: Record<number | string, number>;
     frozenRows?: number;
     frozenCols?: number;
+    /** 1-based row number → pixels. */
+    rowHeights?: Record<number | string, number>;
+    print?: {
+        orientation?: "portrait" | "landscape";
+        fitToWidth?: boolean;
+        /** `{page}` / `{pages}` print the page number and count. */
+        footer?: {
+            left?: string;
+            center?: string;
+            right?: string;
+        };
+    };
 }
 interface HolySheetSchema {
     sheets: SheetSchema[];
@@ -223,7 +235,7 @@ interface SetMetaOp {
 }
 
 /** This package's own version, pinned to package.json by `version.test.ts`. */
-declare const VERSION = "2.6.0";
+declare const VERSION = "2.7.0";
 type Any$6 = any;
 /**
  * Agent — the structured-tool surface for Holy Sheet. Mirrors PHP `Agent`.
@@ -295,7 +307,7 @@ type Any$5 = any;
  * over `Agent`. Provided for parity / DI ergonomics; most callers use `Agent`.
  */
 declare class HolySheet {
-    static readonly VERSION = "2.6.0";
+    static readonly VERSION = "2.7.0";
     validate(schema: Any$5): ValidationError[];
     toBytes(schema: Any$5): Uint8Array;
     write(schema: Any$5, path: string): Promise<WriteResult>;
@@ -428,6 +440,16 @@ declare class MergedRegion {
     ref(): string;
 }
 
+/** How a sheet prints. Mirrors the PHP `Sheet::$print` array. */
+interface PrintSetup {
+    orientation: "portrait" | "landscape" | null;
+    fitToWidth: boolean;
+    footer: {
+        left: string;
+        center: string;
+        right: string;
+    } | null;
+}
 /** A worksheet. Mirrors PHP `Workbook\Sheet`. Cells are an A1-keyed map. */
 declare class Sheet {
     readonly name: string;
@@ -436,7 +458,12 @@ declare class Sheet {
     readonly columnWidths: Map<number, number>;
     readonly frozenRows: number;
     readonly frozenCols: number;
-    constructor(name: string, cells?: Map<string, Cell>, mergedRegions?: MergedRegion[], columnWidths?: Map<number, number>, frozenRows?: number, frozenCols?: number);
+    /** 1-based row number → pixels. */
+    readonly rowHeights: Map<number, number>;
+    readonly print: PrintSetup | null;
+    constructor(name: string, cells?: Map<string, Cell>, mergedRegions?: MergedRegion[], columnWidths?: Map<number, number>, frozenRows?: number, frozenCols?: number, 
+    /** 1-based row number → pixels. */
+    rowHeights?: Map<number, number>, print?: PrintSetup | null);
     /** rowNumber → (colLetter → Cell), sorted by ascending row number. */
     rows(): Map<number, Map<string, Cell>>;
     hasComments(): boolean;
@@ -547,10 +574,6 @@ declare class Theme {
     totalsFormat(): CellFormat | null;
 }
 
-/**
- * XLSX writer — emits a complete OOXML SpreadsheetML package as bytes.
- * Mirrors PHP `Writer\XlsxWriter` (file I/O moved to the Agent for isomorphism).
- */
 declare class XlsxWriter {
     toBytes(workbook: Workbook): Uint8Array;
     private contentTypesXml;

package/dist/index.d.ts

@@ -58,6 +58,18 @@ interface SheetSchema {
     columnWidths?: Record<number | string, number>;
     frozenRows?: number;
     frozenCols?: number;
+    /** 1-based row number → pixels. */
+    rowHeights?: Record<number | string, number>;
+    print?: {
+        orientation?: "portrait" | "landscape";
+        fitToWidth?: boolean;
+        /** `{page}` / `{pages}` print the page number and count. */
+        footer?: {
+            left?: string;
+            center?: string;
+            right?: string;
+        };
+    };
 }
 interface HolySheetSchema {
     sheets: SheetSchema[];
@@ -223,7 +235,7 @@ interface SetMetaOp {
 }
 
 /** This package's own version, pinned to package.json by `version.test.ts`. */
-declare const VERSION = "2.6.0";
+declare const VERSION = "2.7.0";
 type Any$6 = any;
 /**
  * Agent — the structured-tool surface for Holy Sheet. Mirrors PHP `Agent`.
@@ -295,7 +307,7 @@ type Any$5 = any;
  * over `Agent`. Provided for parity / DI ergonomics; most callers use `Agent`.
  */
 declare class HolySheet {
-    static readonly VERSION = "2.6.0";
+    static readonly VERSION = "2.7.0";
     validate(schema: Any$5): ValidationError[];
     toBytes(schema: Any$5): Uint8Array;
     write(schema: Any$5, path: string): Promise<WriteResult>;
@@ -428,6 +440,16 @@ declare class MergedRegion {
     ref(): string;
 }
 
+/** How a sheet prints. Mirrors the PHP `Sheet::$print` array. */
+interface PrintSetup {
+    orientation: "portrait" | "landscape" | null;
+    fitToWidth: boolean;
+    footer: {
+        left: string;
+        center: string;
+        right: string;
+    } | null;
+}
 /** A worksheet. Mirrors PHP `Workbook\Sheet`. Cells are an A1-keyed map. */
 declare class Sheet {
     readonly name: string;
@@ -436,7 +458,12 @@ declare class Sheet {
     readonly columnWidths: Map<number, number>;
     readonly frozenRows: number;
     readonly frozenCols: number;
-    constructor(name: string, cells?: Map<string, Cell>, mergedRegions?: MergedRegion[], columnWidths?: Map<number, number>, frozenRows?: number, frozenCols?: number);
+    /** 1-based row number → pixels. */
+    readonly rowHeights: Map<number, number>;
+    readonly print: PrintSetup | null;
+    constructor(name: string, cells?: Map<string, Cell>, mergedRegions?: MergedRegion[], columnWidths?: Map<number, number>, frozenRows?: number, frozenCols?: number, 
+    /** 1-based row number → pixels. */
+    rowHeights?: Map<number, number>, print?: PrintSetup | null);
     /** rowNumber → (colLetter → Cell), sorted by ascending row number. */
     rows(): Map<number, Map<string, Cell>>;
     hasComments(): boolean;
@@ -547,10 +574,6 @@ declare class Theme {
     totalsFormat(): CellFormat | null;
 }
 
-/**
- * XLSX writer — emits a complete OOXML SpreadsheetML package as bytes.
- * Mirrors PHP `Writer\XlsxWriter` (file I/O moved to the Agent for isomorphism).
- */
 declare class XlsxWriter {
     toBytes(workbook: Workbook): Uint8Array;
     private contentTypesXml;

package/dist/index.js

@@ -416,13 +416,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() {
@@ -663,7 +665,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) {
@@ -854,6 +858,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!";
@@ -1701,6 +1733,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) {
@@ -2790,6 +2911,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) {
@@ -3412,9 +3549,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");
@@ -3790,6 +3980,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();
@@ -3878,14 +4081,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) {
@@ -3894,7 +4103,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;
@@ -5011,6 +5227,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" }
+              }
+            }
+          }
         }
       }
     },
@@ -5219,7 +5460,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);
 }