@particle-academy/holy-sheet 2.4.2 → 2.4.3

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.4.3";
 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.4.3";
     validate(schema: Any$5): ValidationError[];
     toBytes(schema: Any$5): Uint8Array;
     write(schema: Any$5, path: string): Promise<WriteResult>;

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.4.3";
 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.4.3";
     validate(schema: Any$5): ValidationError[];
     toBytes(schema: Any$5): Uint8Array;
     write(schema: Any$5, path: string): Promise<WriteResult>;

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) {
@@ -629,7 +662,10 @@ var Normalizer = class {
   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 +1363,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 +1592,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) {
@@ -5039,7 +5136,7 @@ var holy_sheet_schema_default = {
 };
 
 // src/agent.ts
-var VERSION = "2.4.2";
+var VERSION = "2.4.3";
 function toU8(input) {
   return input instanceof Uint8Array ? input : new Uint8Array(input);
 }