@particle-academy/holy-sheet 2.4.3 → 2.6.0

package/dist/index.d.cts

@@ -223,7 +223,7 @@ interface SetMetaOp {
 }
 
 /** This package's own version, pinned to package.json by `version.test.ts`. */
-declare const VERSION = "2.4.3";
+declare const VERSION = "2.6.0";
 type Any$6 = any;
 /**
  * Agent — the structured-tool surface for Holy Sheet. Mirrors PHP `Agent`.
@@ -295,7 +295,7 @@ type Any$5 = any;
  * over `Agent`. Provided for parity / DI ergonomics; most callers use `Agent`.
  */
 declare class HolySheet {
-    static readonly VERSION = "2.4.3";
+    static readonly VERSION = "2.6.0";
     validate(schema: Any$5): ValidationError[];
     toBytes(schema: Any$5): Uint8Array;
     write(schema: Any$5, path: string): Promise<WriteResult>;
@@ -460,6 +460,22 @@ declare class Normalizer {
     private normalizeSheet;
     private normalizeCellMap;
     private normalizeMerges;
+    /**
+     * The two ways a width can be stated, folded into one map.
+     *
+     * `columns[].width` widens the column at that POSITION; the sheet-level
+     * `columnWidths` map keys the same columns by 0-based index. Both have been
+     * described in the shared `skills/holy-sheet.schema.json` ("Same as
+     * columnWidths but per-column") for as long as the field has existed, and only
+     * the map was ever read — so a width written the way the schema documents it
+     * emitted no `<cols>` element at all, with no error and no repair note
+     * (holy-sheet#8, fixed in PHP 2.4.0; this is the twin).
+     *
+     * The MAP IS APPLIED LAST and wins, matching PHP. It is the mechanism that
+     * already worked, so anyone who reached for it to work around this bug must not
+     * now find a leftover `width` quietly overriding it.
+     */
+    private normalizeWidths;
     private normalizeColumnWidths;
     private columnFormat;
     private buildCell;

package/dist/index.d.ts

@@ -223,7 +223,7 @@ interface SetMetaOp {
 }
 
 /** This package's own version, pinned to package.json by `version.test.ts`. */
-declare const VERSION = "2.4.3";
+declare const VERSION = "2.6.0";
 type Any$6 = any;
 /**
  * Agent — the structured-tool surface for Holy Sheet. Mirrors PHP `Agent`.
@@ -295,7 +295,7 @@ type Any$5 = any;
  * over `Agent`. Provided for parity / DI ergonomics; most callers use `Agent`.
  */
 declare class HolySheet {
-    static readonly VERSION = "2.4.3";
+    static readonly VERSION = "2.6.0";
     validate(schema: Any$5): ValidationError[];
     toBytes(schema: Any$5): Uint8Array;
     write(schema: Any$5, path: string): Promise<WriteResult>;
@@ -460,6 +460,22 @@ declare class Normalizer {
     private normalizeSheet;
     private normalizeCellMap;
     private normalizeMerges;
+    /**
+     * The two ways a width can be stated, folded into one map.
+     *
+     * `columns[].width` widens the column at that POSITION; the sheet-level
+     * `columnWidths` map keys the same columns by 0-based index. Both have been
+     * described in the shared `skills/holy-sheet.schema.json` ("Same as
+     * columnWidths but per-column") for as long as the field has existed, and only
+     * the map was ever read — so a width written the way the schema documents it
+     * emitted no `<cols>` element at all, with no error and no repair note
+     * (holy-sheet#8, fixed in PHP 2.4.0; this is the twin).
+     *
+     * The MAP IS APPLIED LAST and wins, matching PHP. It is the mechanism that
+     * already worked, so anyone who reached for it to work around this bug must not
+     * now find a leftover `width` quietly overriding it.
+     */
+    private normalizeWidths;
     private normalizeColumnWidths;
     private columnFormat;
     private buildCell;

package/dist/index.js

@@ -493,6 +493,54 @@ var DateConverter = {
   }
 };
 
+// src/exceptions.ts
+var SchemaException = class _SchemaException extends Error {
+  constructor(errors, message) {
+    super(message ?? summarize(errors));
+    this.name = "SchemaException";
+    this.errors = errors;
+    Object.setPrototypeOf(this, _SchemaException.prototype);
+  }
+  static fromErrors(errors) {
+    return new _SchemaException(errors);
+  }
+  getErrors() {
+    return this.errors;
+  }
+};
+function summarize(errors) {
+  if (errors.length === 1) {
+    const e = errors[0];
+    return `[holy-sheet] schema invalid at ${e.path}: expected ${e.expected}, got ${e.got}`;
+  }
+  const first2 = errors[0];
+  const rest = errors.length - 1;
+  return `[holy-sheet] schema invalid at ${first2.path}: expected ${first2.expected}, got ${first2.got} (+${rest} more)`;
+}
+var UnsupportedFormatException = class _UnsupportedFormatException extends Error {
+  constructor(message, path = null, mimetype = null) {
+    super(message);
+    this.name = "UnsupportedFormatException";
+    this.path = path;
+    this.mimetype = mimetype;
+    Object.setPrototypeOf(this, _UnsupportedFormatException.prototype);
+  }
+  static notAZip(path = null) {
+    return new _UnsupportedFormatException(
+      `[holy-sheet] cannot read ${path ?? "this file"}: it is not a zip archive, and xlsx and ods both are`,
+      path
+    );
+  }
+  static unknownPackage(path, mimetype) {
+    const what = mimetype !== null && mimetype !== "" ? `its mimetype is ${mimetype}` : "it has neither xl/workbook.xml nor an OpenDocument mimetype";
+    return new _UnsupportedFormatException(
+      `[holy-sheet] cannot read ${path ?? "this file"}: ${what}. Supported: xlsx, ods`,
+      path,
+      mimetype !== "" ? mimetype : null
+    );
+  }
+};
+
 // src/schema/theme.ts
 var Theme = class {
   constructor(key) {
@@ -570,7 +618,7 @@ var Normalizer = class {
         const columnFormat = columnFormats.get(c) ?? null;
         const rowBand = theme.dataFormat(r);
         const merged = rowBand !== null ? columnFormat ? columnFormat.mergeWith(rowBand) : rowBand : columnFormat;
-        cells.set(address, this.buildCell(address, value, merged));
+        cells.set(address, this.buildCell(address, value, merged, name));
       });
     });
     if (sheet.totals && isPlainObject(sheet.totals) && Object.keys(sheet.totals).length > 0 && rows.length > 0 && columns.length > 0) {
@@ -594,7 +642,7 @@ var Normalizer = class {
       }
     }
     if (sheet.cells != null) {
-      for (const [address, cell] of this.normalizeCellMap(sheet.cells)) {
+      for (const [address, cell] of this.normalizeCellMap(sheet.cells, name)) {
         const beneath = cells.get(address);
         cells.set(
           address,
@@ -613,19 +661,23 @@ var Normalizer = class {
       name,
       cells,
       this.normalizeMerges(sheet.mergedRegions ?? []),
-      this.normalizeColumnWidths(sheet.columnWidths ?? {}),
+      this.normalizeWidths(sheet),
       toInt(sheet.frozenRows ?? 0),
       toInt(sheet.frozenCols ?? 0)
     );
   }
-  normalizeCellMap(map) {
+  normalizeCellMap(map, sheetName2) {
     const cells = /* @__PURE__ */ new Map();
     for (const [address, cellData] of Object.entries(map)) {
-      if (!isPlainObject(cellData)) {
+      if (!isCellSpec(cellData)) {
         const [bare, formula] = promoteFormula(cellData);
         cells.set(
           address,
-          new Cell(address, formula !== null ? null : this.coerceValue(bare, null), formula)
+          new Cell(
+            address,
+            formula !== null ? null : this.coerceValue(bare, null, address, sheetName2),
+            formula
+          )
         );
         continue;
       }
@@ -640,7 +692,7 @@ var Normalizer = class {
         address,
         new Cell(
           address,
-          this.coerceValue(rawValue, format),
+          this.coerceValue(rawValue, format, address, sheetName2),
           cellData?.formula ?? null,
           format,
           comment,
@@ -659,6 +711,36 @@ var Normalizer = class {
     }
     return out;
   }
+  /**
+   * The two ways a width can be stated, folded into one map.
+   *
+   * `columns[].width` widens the column at that POSITION; the sheet-level
+   * `columnWidths` map keys the same columns by 0-based index. Both have been
+   * described in the shared `skills/holy-sheet.schema.json` ("Same as
+   * columnWidths but per-column") for as long as the field has existed, and only
+   * the map was ever read — so a width written the way the schema documents it
+   * emitted no `<cols>` element at all, with no error and no repair note
+   * (holy-sheet#8, fixed in PHP 2.4.0; this is the twin).
+   *
+   * The MAP IS APPLIED LAST and wins, matching PHP. It is the mechanism that
+   * already worked, so anyone who reached for it to work around this bug must not
+   * now find a leftover `width` quietly overriding it.
+   */
+  normalizeWidths(sheet) {
+    const out = /* @__PURE__ */ new Map();
+    for (const [colIdx, columnDef] of (sheet.columns ?? []).entries()) {
+      if (columnDef === null || typeof columnDef !== "object") continue;
+      if (columnDef.width === void 0) continue;
+      const index = ColumnWidths.index(colIdx);
+      const width = ColumnWidths.width(columnDef.width);
+      if (index === null || width === null) continue;
+      out.set(index, width);
+    }
+    for (const [index, width] of this.normalizeColumnWidths(sheet.columnWidths ?? {})) {
+      out.set(index, width);
+    }
+    return new Map([...out.entries()].sort((a, b) => a[0] - b[0]));
+  }
   normalizeColumnWidths(widths) {
     const out = /* @__PURE__ */ new Map();
     for (const [key, px] of Object.entries(widths)) {
@@ -691,8 +773,8 @@ var Normalizer = class {
         return null;
     }
   }
-  buildCell(address, value, columnFormat) {
-    if (isPlainObject(value)) {
+  buildCell(address, value, columnFormat, sheetName2) {
+    if (isCellSpec(value)) {
       const cellFormat = isPlainObject(value.format) ? CellFormat.fromInput(value.format) : null;
       const merged = columnFormat ? columnFormat.mergeWith(cellFormat) : cellFormat;
       const comment = isPlainObject(value.comment) ? new CellComment(
@@ -703,7 +785,7 @@ var Normalizer = class {
       const rawValue = value.value ?? null;
       return new Cell(
         address,
-        this.coerceValue(rawValue, merged),
+        this.coerceValue(rawValue, merged, address, sheetName2),
         value.formula ?? null,
         merged,
         comment,
@@ -713,12 +795,12 @@ var Normalizer = class {
     const [bare, formula] = promoteFormula(value);
     return new Cell(
       address,
-      formula !== null ? null : this.coerceValue(bare, columnFormat),
+      formula !== null ? null : this.coerceValue(bare, columnFormat, address, sheetName2),
       formula,
       columnFormat
     );
   }
-  coerceValue(value, format) {
+  coerceValue(value, format, address = "?", sheetName2) {
     if (value === null || value === void 0) return null;
     const df = format?.displayFormat;
     if (df === "date" || df === "datetime") {
@@ -732,12 +814,36 @@ var Normalizer = class {
     if (value instanceof Date) {
       return DateConverter.toSerial(value, true);
     }
-    if (typeof value !== "string" && typeof value !== "number" && typeof value !== "boolean") {
+    if (typeof value === "bigint") {
       return String(value);
     }
+    if (typeof value === "object" && !Array.isArray(value) && hasOwnToString(value)) {
+      return String(value);
+    }
+    if (typeof value !== "string" && typeof value !== "number" && typeof value !== "boolean") {
+      const where = sheetName2 === void 0 ? address : `${sheetName2}!${address}`;
+      const got = typeOf(value);
+      throw SchemaException.fromErrors([
+        {
+          path: where,
+          expected: "a string, number, bool, null, Date, or an object with its own toString",
+          got,
+          value,
+          hint: Array.isArray(value) ? 'This cell holds an array. The usual cause is a `rows` entry nested one level too deep: `rows: [[["x"]]]` makes cell A1 an array, where `rows: [["x"]]` makes it the string "x". For a cell with formatting use the object form: {value: "x", format: {...}}.' : "Give the cell a scalar or a Date, or define toString() on the object so the conversion is yours rather than implicit."
+        }
+      ]);
+    }
     return value;
   }
 };
+function isCellSpec(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  return Object.getPrototypeOf(value) === Object.prototype;
+}
+function hasOwnToString(value) {
+  const fn = value.toString;
+  return typeof fn === "function" && fn !== Object.prototype.toString;
+}
 function promoteFormula(value) {
   if (typeof value === "string" && value.length > 1 && value[0] === "=") {
     return [null, value.slice(1)];
@@ -1269,54 +1375,6 @@ function phpRound(x, n) {
   return Math.sign(x) * Math.round(Math.abs(x) * factor) / factor;
 }
 
-// src/exceptions.ts
-var SchemaException = class _SchemaException extends Error {
-  constructor(errors, message) {
-    super(message ?? summarize(errors));
-    this.name = "SchemaException";
-    this.errors = errors;
-    Object.setPrototypeOf(this, _SchemaException.prototype);
-  }
-  static fromErrors(errors) {
-    return new _SchemaException(errors);
-  }
-  getErrors() {
-    return this.errors;
-  }
-};
-function summarize(errors) {
-  if (errors.length === 1) {
-    const e = errors[0];
-    return `[holy-sheet] schema invalid at ${e.path}: expected ${e.expected}, got ${e.got}`;
-  }
-  const first2 = errors[0];
-  const rest = errors.length - 1;
-  return `[holy-sheet] schema invalid at ${first2.path}: expected ${first2.expected}, got ${first2.got} (+${rest} more)`;
-}
-var UnsupportedFormatException = class _UnsupportedFormatException extends Error {
-  constructor(message, path = null, mimetype = null) {
-    super(message);
-    this.name = "UnsupportedFormatException";
-    this.path = path;
-    this.mimetype = mimetype;
-    Object.setPrototypeOf(this, _UnsupportedFormatException.prototype);
-  }
-  static notAZip(path = null) {
-    return new _UnsupportedFormatException(
-      `[holy-sheet] cannot read ${path ?? "this file"}: it is not a zip archive, and xlsx and ods both are`,
-      path
-    );
-  }
-  static unknownPackage(path, mimetype) {
-    const what = mimetype !== null && mimetype !== "" ? `its mimetype is ${mimetype}` : "it has neither xl/workbook.xml nor an OpenDocument mimetype";
-    return new _UnsupportedFormatException(
-      `[holy-sheet] cannot read ${path ?? "this file"}: ${what}. Supported: xlsx, ods`,
-      path,
-      mimetype !== "" ? mimetype : null
-    );
-  }
-};
-
 // src/schema/repairer.ts
 var VALID_THEMES = ["default", "minimal", "plain", "business"];
 var ISO_DATE2 = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2})?(\.\d+)?(Z|[+-]\d{2}:?\d{2})?)?$/;
@@ -1563,7 +1621,21 @@ var Validator = class {
                 "Each row is an array of cell values, in column order."
               )
             );
+            return;
           }
+          row.forEach((cell, k) => {
+            if (Array.isArray(cell)) {
+              errors.push(
+                error(
+                  `${path}.rows[${j}][${k}]`,
+                  "a cell value or a cell object",
+                  "array",
+                  cell,
+                  'This cell is an array, which usually means the row is nested one level too deep: `rows: [[["x"]]]` makes cell A1 an array, where `rows: [["x"]]` makes it "x". For a cell with formatting use the object form: {value: "x", format: {...}}.'
+                )
+              );
+            }
+          });
         });
       }
     }
@@ -1660,6 +1732,17 @@ var Validator = class {
         )
       );
     }
+    if (col.width !== void 0 && ColumnWidths.width(col.width) === null) {
+      errors.push(
+        error(
+          `${path}.width`,
+          "a non-negative number of pixels",
+          typeOf(col.width),
+          col.width,
+          "A column width is a number of pixels, like 120. The sheet-level columnWidths map takes precedence over it."
+        )
+      );
+    }
     return errors;
   }
 };
@@ -5136,7 +5219,7 @@ var holy_sheet_schema_default = {
 };
 
 // src/agent.ts
-var VERSION = "2.4.3";
+var VERSION = "2.6.0";
 function toU8(input) {
   return input instanceof Uint8Array ? input : new Uint8Array(input);
 }