@particle-academy/holy-sheet 2.4.2 → 2.5.0

package/README.md

@@ -1,12 +1,12 @@
 # @particle-academy/holy-sheet
 
-[![Fancy UI suite](art/fancy-ui.svg)](https://particle.academy)
+[![Fancified](art/fancified.svg)](https://particle.academy)
 
 Zero-dependency, **isomorphic** (browser + Node) `.xlsx` writer + reader +
 formula linter for agentic document creation. The Node/TypeScript mirror of the
 PHP [`particle-academy/holy-sheet`](https://github.com/Particle-Academy/holy-sheet)
-— same schema in, same `.xlsx` out (feature-parity with PHP 1.2.0; the PHP
-package has since shipped 1.3.0, whose additions are not yet mirrored here).
+— same schema in, same `.xlsx` out (the PHP package's `dumpJson` and `Toolkit`
+are not mirrored here; `CHANGELOG.md` records which PHP releases each fix mirrors).
 
 ```ts
 import { Agent } from "@particle-academy/holy-sheet";

package/dist/index.cjs

@@ -287,6 +287,39 @@ var Cell = class {
   }
 };
 
+// src/schema/column-widths.ts
+var ColumnWidths = {
+  MAX_INDEX: 16383,
+  index(key) {
+    if (typeof key === "number") {
+      return Number.isInteger(key) && key >= 0 && key <= ColumnWidths.MAX_INDEX ? key : null;
+    }
+    if (typeof key === "string" && /^[0-9]{1,5}$/.test(key)) {
+      const index = parseInt(key, 10);
+      return index <= ColumnWidths.MAX_INDEX ? index : null;
+    }
+    return null;
+  },
+  width(px) {
+    if (typeof px === "number") {
+      return Number.isFinite(px) && px >= 0 ? px : null;
+    }
+    if (typeof px === "string" && /^[0-9]+(\.[0-9]+)?$/.test(px)) {
+      return Number(px);
+    }
+    return null;
+  },
+  /**
+   * A column letter key (`"B"`, `"aa"`) as an index, for repair only. One or two
+   * letters (A to ZZ): a longer run like `"abc"` is more likely a mistake than
+   * column ABC, and a repair must not guess.
+   */
+  fromLetters(key) {
+    if (typeof key !== "string" || !/^[A-Za-z]{1,2}$/.test(key.trim())) return null;
+    return CellAddress.index(key.trim());
+  }
+};
+
 // src/workbook/cell-comment.ts
 var CellComment = class {
   constructor(text, author = null, color2 = null) {
@@ -582,7 +615,7 @@ var Normalizer = class {
       name,
       cells,
       this.normalizeMerges(sheet.mergedRegions ?? []),
-      this.normalizeColumnWidths(sheet.columnWidths ?? {}),
+      this.normalizeWidths(sheet),
       toInt(sheet.frozenRows ?? 0),
       toInt(sheet.frozenCols ?? 0)
     );
@@ -628,10 +661,43 @@ 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)) {
-      out.set(parseInt(key, 10), Number(px));
+      const index = ColumnWidths.index(key);
+      const width = ColumnWidths.width(px);
+      if (index === null || width === null) continue;
+      out.set(index, width);
     }
     return out;
   }
@@ -1329,6 +1395,30 @@ var Repairer = class {
       sheet.theme = "default";
       this.repairs.push(`changed '${path}.theme' from '${original}' to 'default' (unknown theme)`);
     }
+    if (sheet.columnWidths != null && (isPlainObject(sheet.columnWidths) || Array.isArray(sheet.columnWidths))) {
+      const widths = {};
+      let changed = false;
+      for (const [key, px] of Object.entries(sheet.columnWidths)) {
+        let index = ColumnWidths.index(key);
+        if (index === null) {
+          const letters = ColumnWidths.fromLetters(key);
+          if (letters !== null) {
+            index = letters;
+            this.repairs.push(`converted '${path}.columnWidths.${key}' to column index ${index}`);
+            changed = true;
+          }
+        }
+        if (index === null || ColumnWidths.width(px) === null) {
+          this.repairs.push(`dropped '${path}.columnWidths.${key}' (not a column index and a width)`);
+          changed = true;
+          continue;
+        }
+        widths[String(index)] = px;
+      }
+      if (changed) {
+        sheet.columnWidths = widths;
+      }
+    }
     if (sheet.cells != null && isPlainObject(sheet.cells)) {
       const cleaned = {};
       let changed = false;
@@ -1534,6 +1624,43 @@ var Validator = class {
         )
       );
     }
+    if (sheet.columnWidths != null) {
+      if (!isPlainObject(sheet.columnWidths) && !Array.isArray(sheet.columnWidths)) {
+        errors.push(
+          error(
+            `${path}.columnWidths`,
+            "object keyed by 0-based column index",
+            typeOf(sheet.columnWidths),
+            sheet.columnWidths,
+            'Column widths map a 0-based column index to pixels: {"0": 120, "1": 80}.'
+          )
+        );
+      } else {
+        for (const [key, px] of Object.entries(sheet.columnWidths)) {
+          if (ColumnWidths.index(key) === null) {
+            errors.push(
+              error(
+                `${path}.columnWidths.${key}`,
+                `a 0-based column index from 0 to ${ColumnWidths.MAX_INDEX}`,
+                typeOf(key),
+                key,
+                'Keys are 0-based column indexes: "0" is column A, "1" is column B. Use the index, not the letter.'
+              )
+            );
+          } else if (ColumnWidths.width(px) === null) {
+            errors.push(
+              error(
+                `${path}.columnWidths.${key}`,
+                "a non-negative number of pixels",
+                typeOf(px),
+                px,
+                "A width is a number of pixels, like 120."
+              )
+            );
+          }
+        }
+      }
+    }
     return errors;
   }
   validateColumn(col, path) {
@@ -1565,6 +1692,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;
   }
 };
@@ -5041,7 +5179,7 @@ var holy_sheet_schema_default = {
 };
 
 // src/agent.ts
-var VERSION = "2.4.2";
+var VERSION = "2.5.0";
 function toU8(input) {
   return input instanceof Uint8Array ? input : new Uint8Array(input);
 }