@particle-academy/holy-sheet 2.4.2 → 2.5.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.2";
+declare const VERSION = "2.5.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.2";
+    static readonly VERSION = "2.5.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.2";
+declare const VERSION = "2.5.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.2";
+    static readonly VERSION = "2.5.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

@@ -285,6 +285,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) {
@@ -580,7 +613,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)
     );
@@ -626,10 +659,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;
   }
@@ -1327,6 +1393,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;
@@ -1532,6 +1622,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) {
@@ -1563,6 +1690,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;
   }
 };
@@ -5039,7 +5177,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);
 }