@dimarborda/xlsx-editor 0.1.0 → 0.2.0

package/README.md

@@ -112,6 +112,7 @@ element.addEventListener('ready', async ({ detail: { editor } }) => {
   // Cambiar celdas con la API del motor y volver a dibujar
   editor.workbook.fillTemplate({ CLIENTE: 'Acme' });
   editor.workbook.sheet('Resumen').setValues('B2', [[1200, 0.25]]);
+  editor.workbook.addSheet('Notas');  // reload() también redibuja las pestañas
   editor.reload();
 
   editor.undo();                       // también editor.redo(), editor.canUndo, editor.canRedo
@@ -167,6 +168,8 @@ En Node el motor se carga solo. En el navegador, los bundlers (Vite, webpack 5,
 | `hoja.setValue('B3', valor)` | Escribe texto, número, booleano, `Date` o una fórmula (`{ formula: '=SUM(A1:A3)' }`); `null` borra el valor y deja el formato. Las fórmulas que dependen de la celda se recalculan. |
 | `hoja.setValues('A2', filas)` | Escribe una matriz desde la celda indicada, creando filas y celdas en orden. `undefined` deja la celda como está. |
 | `wb.fillTemplate(valores)` | Sustituye `{{CAMPO}}` (se admiten espacios y una pista: `{{ CAMPO }}`, `{{CAMPO: pista}}`) en las cadenas compartidas y en las cadenas en línea; devuelve cuántas sustituyó. Las variables sin valor se quedan como están. |
+| `wb.addSheet(nombre, después?)` | Agrega una hoja vacía detrás de la pestaña `después` (nombre o posición; al final sin ella) y la devuelve. El nombre sigue las reglas de Excel: de 1 a 31 caracteres, sin `[ ] : * ? / \`, sin apóstrofo al principio ni al final, distinto de `History` y de las demás hojas (sin distinguir mayúsculas). |
+| `wb.renameSheet(hoja, nombre)` | Renombra una pestaña (nombre o posición) y las referencias a ella en fórmulas, nombres definidos, validaciones de datos, formato condicional y gráficos; devuelve cuántas cambió. Las referencias dentro de textos (`INDIRECT("Hoja1!A1")`) y a otros libros se quedan como están, igual que en Excel. |
 | `wb.markers({ kind })` | Marcadores del léxico estándar (el mismo de `@dimarborda/docx-editor`) en las celdas de texto de todas las hojas: `field` para `{{CLAVE}}` / `{clave}`, `pending` para `[…]` (contenido por completar). Cada uno con `sheet`, `sheetName`, `ref` (`B3`), `row`, `col`, `raw`, `key`, `hint`, `offset` y `length`. |
 | `wb.checkpoint(selección?)` | Abre un paso de deshacer: los cambios hasta el siguiente `checkpoint` se deshacen juntos. `selección` es un texto libre que `undo()` devuelve. `wb.setSelectionAfter(selección)` guarda la de después, que devuelve `redo()`. |
 | `wb.undo()` / `wb.redo()` | Deshace o rehace un paso: `{ selection, parts }`, o `null` si no hay nada. `wb.canUndo` / `wb.canRedo` dicen si se puede. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dimarborda/xlsx-editor",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Excel (.xlsx) editor for the browser and engine for Node.js: Rust + WebAssembly that edits workbooks without losing what it does not touch, with a canvas grid as a framework-agnostic web component",
   "type": "module",
   "license": "MIT",

package/src/engine.d.ts

@@ -243,6 +243,13 @@ export class Workbook {
    * Replaces `{{FIELD}}` placeholders (also `{{ FIELD }}` and `{{FIELD: hint}}`) in the shared and inline strings of the workbook and
    * returns how many were replaced. Unknown placeholders are left as they are.
    */
+  /** Adds an empty worksheet after the tab `after` (name or position; at the end without it) */
+  addSheet(name: string, after?: string | number): Sheet;
+  /**
+   * Renames a tab and the references to it in formulas, defined names, data validations,
+   * conditional formats and charts; returns how many of those changed
+   */
+  renameSheet(sheet: string | number, name: string): number;
   fillTemplate(values: Record<string, string | number | boolean | null | undefined>): number;
   /**
    * Markers of the standard lexicon (shared with @dimarborda/docx-editor) in the text cells of

package/src/engine.js

@@ -241,6 +241,43 @@ export class Workbook {
     return new Sheet(this, index, all[index].name);
   }
 
+  /**
+   * Adds an empty worksheet after the tab `after` (name or position; at the end without it).
+   * Names follow Excel's rules: 1–31 characters, none of `[ ] : * ? / \`, unique ignoring case.
+   * Returns the new sheet.
+   * @param {string} name
+   * @param {string | number} [after]
+   */
+  addSheet(name, after) {
+    const index = call(() => this._engine.add_sheet(String(name), after === undefined || after === null ? undefined : this.#tabIndex(after)));
+    return this.sheet(index);
+  }
+
+  /**
+   * Renames a tab (name or position) and the references to it in formulas, defined names,
+   * data validations, conditional formats and charts; returns how many of those changed
+   * @param {string | number} sheet
+   * @param {string} name
+   */
+  renameSheet(sheet, name) {
+    return call(() => this._engine.rename_sheet(this.#tabIndex(sheet), String(name)));
+  }
+
+  /** Position of a tab by name (ignoring case) or position */
+  #tabIndex(nameOrIndex) {
+    const all = JSON.parse(this._engine.sheets_json());
+    if (typeof nameOrIndex === 'number') {
+      if (!Number.isInteger(nameOrIndex) || nameOrIndex < 0 || nameOrIndex >= all.length) {
+        throw new RangeError(`El libro tiene ${all.length} hoja(s); no existe la hoja ${nameOrIndex}.`);
+      }
+      return nameOrIndex;
+    }
+    let index = all.findIndex(s => s.name === nameOrIndex);
+    if (index < 0) index = all.findIndex(s => s.name.toLowerCase() === String(nameOrIndex).toLowerCase());
+    if (index < 0) throw new Error(`El libro no tiene ninguna hoja llamada '${nameOrIndex}'.`);
+    return index;
+  }
+
   /**
    * Replaces `{{FIELD}}` placeholders (also `{{ FIELD }}` and `{{FIELD: hint}}`) in every text
    * of the workbook; returns how many

package/src/grid.js

@@ -65,6 +65,12 @@ export class Axis {
     return this.offset(this.count + 1);
   }
 
+  /** The same axis with room for `count` rows/columns, up to `max` (sizes are kept) */
+  grown(count, max) {
+    const next = Math.min(max, Math.max(this.count, count));
+    return next === this.count ? this : new Axis(next, this.defaultSize, this.custom);
+  }
+
   /** The row/column under position `pos` (clamped to the grid) */
   indexAt(pos) {
     if (pos <= 0) return 1;
@@ -79,6 +85,10 @@ export class Axis {
   }
 }
 
+/** Last row and column of a worksheet */
+export const MAX_ROWS = 1_048_576;
+export const MAX_COLS = 16_384;
+
 /** Column letters: 1 → A, 27 → AA */
 export function columnName(col) {
   let name = '';
@@ -133,7 +143,7 @@ export function sheetAxes(layout, used, mdw, defaultRowPt = 15) {
     lastRow = Math.max(lastRow, last.row);
     lastCol = Math.max(lastCol, last.col);
   }
-  const rows = Math.min(1_048_576, Math.max(lastRow + 100, 200));
-  const cols = Math.min(16_384, Math.max(lastCol, used.maxCol) + 12, 16_384);
+  const rows = Math.min(MAX_ROWS, Math.max(lastRow + 100, 200));
+  const cols = Math.min(MAX_COLS, Math.max(lastCol, used.maxCol) + 12);
   return { rows: new Axis(rows, rowPx, rowSizes), cols: new Axis(Math.max(cols, 26), colPx, colSizes) };
 }

package/src/xlsx_editor.js

@@ -4,7 +4,7 @@
 // frozen panes in place and handles selection, the in-cell editor, the clipboard, undo and tabs.
 import { createWorkbook, initEngine, openWorkbook } from './engine.js';
 import { canvasFont, drawHeaders, drawRegion, key } from './draw.js';
-import { columnName, parseRange, sheetAxes } from './grid.js';
+import { MAX_COLS, MAX_ROWS, columnName, parseRange, sheetAxes } from './grid.js';
 import { editText, parseInput, parseTSV, toTSV } from './input.js';
 
 const COL_HEADER_H = 22;
@@ -113,7 +113,10 @@ export class XlsxEditor extends EventTarget {
     this.#input = root.querySelector('.xlsx-editor-input');
     this.#sink = root.querySelector('.xlsx-editor-clipboard');
 
-    this.#scroller.addEventListener('scroll', () => this.render());
+    this.#scroller.addEventListener('scroll', () => {
+      this.#growOnScroll();
+      this.render();
+    });
     this.#scroller.addEventListener('pointerdown', e => this.#onPointerDown(e));
     this.#scroller.addEventListener('keydown', e => this.#onKeyDown(e));
     this.#scroller.addEventListener('dblclick', () => this.#beginEdit({ mode: 'edit' }));
@@ -239,7 +242,15 @@ export class XlsxEditor extends EventTarget {
   reload() {
     if (!this.#workbook || this.#sheetIndex < 0) return;
     this.#styles = this.#workbook.styleView();
-    this.#loadSheet(this.#sheetIndex, { keepScroll: true });
+    // Sheets added or renamed through `workbook` show up in the tabs
+    this.#renderTabs();
+    this.#loadSheet(this.#validSheet(this.#sheetIndex), { keepScroll: true });
+  }
+
+  /** `index` if it is still a worksheet (after undoing an added sheet), else the first one */
+  #validSheet(index) {
+    const tabs = this.#workbook.tabs;
+    return tabs[index]?.kind === 'worksheet' ? index : tabs.findIndex(t => t.kind === 'worksheet');
   }
 
   /** @param {number} zoom 0.25–4 */
@@ -258,6 +269,7 @@ export class XlsxEditor extends EventTarget {
   select(ref) {
     const range = parseRange(ref);
     this.#commitEdit(null, { focus: false });
+    this.#extend(range.last.row, range.last.col);
     this.#setSelection(range.first, range.last, range.first);
   }
 
@@ -384,7 +396,12 @@ export class XlsxEditor extends EventTarget {
       }
     }
     this.#mdw = this.#measureMdw();
-    const { rows, cols } = sheetAxes(layout, { maxRow, maxCol }, this.#mdw);
+    let { rows, cols } = sheetAxes(layout, { maxRow, maxCol }, this.#mdw);
+    // Reading the same sheet again keeps the room scrolled into past its cells
+    if (this.#sheetIndex === index && this.#sheet) {
+      rows = rows.grown(this.#sheet.rows.count, MAX_ROWS);
+      cols = cols.grown(this.#sheet.cols.count, MAX_COLS);
+    }
     const frozen = layout.frozen ?? { rows: 0, cols: 0 };
     this.#sheet = {
       cells, merges, mergeAt, covered, rows, cols,
@@ -417,6 +434,30 @@ export class XlsxEditor extends EventTarget {
     return this.#sheet?.headings ? Math.round(COL_HEADER_H * this.zoom) : 0;
   }
 
+  /**
+   * Makes room up to row `row` and column `col` and some more, as Excel does when scrolling or
+   * moving past the end of the shown grid
+   */
+  #extend(row, col) {
+    const sheet = this.#sheet;
+    if (!sheet) return;
+    const rows = row + 50 > sheet.rows.count ? sheet.rows.grown(row + 200, MAX_ROWS) : sheet.rows;
+    const cols = col + 5 > sheet.cols.count ? sheet.cols.grown(col + 20, MAX_COLS) : sheet.cols;
+    if (rows === sheet.rows && cols === sheet.cols) return;
+    sheet.rows = rows;
+    sheet.cols = cols;
+    this.#updateSpacer();
+  }
+
+  /** Grows the grid when the view comes near its bottom or right end */
+  #growOnScroll() {
+    const s = this.#scroller;
+    if (!this.#sheet) return;
+    const nearBottom = s.scrollTop + s.clientHeight * 2 >= s.scrollHeight;
+    const nearRight = s.scrollLeft + s.clientWidth * 2 >= s.scrollWidth;
+    if (nearBottom || nearRight) this.#extend(nearBottom ? this.#sheet.rows.count : 1, nearRight ? this.#sheet.cols.count : 1);
+  }
+
   #updateSpacer() {
     if (!this.#sheet) {
       this.#spacer.style.width = '0px';
@@ -679,8 +720,9 @@ export class XlsxEditor extends EventTarget {
 
   /** Moves the active cell (or, with `extend`, the moving corner of the range) one step */
   #move(dr, dc, extend = false) {
-    const { rows, cols } = this.#sheet;
     const from = extend ? this.#selection.cursor : this.#selection.active;
+    this.#extend(from.row + Math.max(dr, 0), from.col + Math.max(dc, 0));
+    const { rows, cols } = this.#sheet;
     // Step over merged ranges and hidden rows or columns
     const range = this.#expandToMerges(from, from);
     let row = dr > 0 ? range.last.row + 1 : dr < 0 ? range.first.row - 1 : from.row;
@@ -962,11 +1004,14 @@ export class XlsxEditor extends EventTarget {
     this.#clip = null;
     this.#styles = this.#workbook.styleView();
     const tabs = this.#workbook.tabs;
+    this.#renderTabs();
     if (token && token.sheet !== this.#sheetIndex && tabs[token.sheet]?.kind === 'worksheet') {
       this.#loadSheet(token.sheet);
       this.dispatchEvent(new CustomEvent('sheetchange', { detail: { index: token.sheet, name: tabs[token.sheet].name } }));
     } else {
-      this.#loadSheet(this.#sheetIndex, { keepScroll: true });
+      const index = this.#validSheet(this.#sheetIndex);
+      this.#loadSheet(index, { keepScroll: index === this.#sheetIndex });
+      if (index !== token?.sheet && tabs[index]) this.dispatchEvent(new CustomEvent('sheetchange', { detail: { index, name: tabs[index].name } }));
     }
     if (token?.range) {
       const range = parseRange(token.range);

package/wasm/xlsx_engine.d.ts

@@ -7,6 +7,11 @@
 export class XlsxWorkbook {
     free(): void;
     [Symbol.dispose](): void;
+    /**
+     * Adds an empty worksheet after the tab at `after` (at the end without it); returns its
+     * tab position
+     */
+    add_sheet(name: string, after?: number | null): number;
     /**
      * Context of an area for an agent (see `Workbook::area_context`): `target` is a table or
      * defined name, an address with its sheet, or a range of the sheet at `sheet`
@@ -70,6 +75,10 @@ export class XlsxWorkbook {
      * The region around a cell (Excel's current region) as JSON
      */
     region_at_json(sheet: number, reference: string): string;
+    /**
+     * Renames the tab at `sheet` and the references to it; returns how many formulas changed
+     */
+    rename_sheet(sheet: number, name: string): number;
     /**
      * Width in characters of the columns `first..=last` (1 = A)
      */
@@ -125,6 +134,7 @@ export interface InitOutput {
     readonly memory: WebAssembly.Memory;
     readonly __wbg_xlsxworkbook_free: (a: number, b: number) => void;
     readonly main_js: () => void;
+    readonly xlsxworkbook_add_sheet: (a: number, b: number, c: number, d: number) => [number, number, number];
     readonly xlsxworkbook_area_context_json: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => [number, number, number, number];
     readonly xlsxworkbook_areas_json: (a: number, b: number) => [number, number, number, number];
     readonly xlsxworkbook_can_redo: (a: number) => number;
@@ -142,6 +152,7 @@ export interface InitOutput {
     readonly xlsxworkbook_recalculate: (a: number) => [number, number, number];
     readonly xlsxworkbook_redo_json: (a: number) => [number, number];
     readonly xlsxworkbook_region_at_json: (a: number, b: number, c: number, d: number) => [number, number, number, number];
+    readonly xlsxworkbook_rename_sheet: (a: number, b: number, c: number, d: number) => [number, number, number];
     readonly xlsxworkbook_set_column_width: (a: number, b: number, c: number, d: number, e: number) => [number, number];
     readonly xlsxworkbook_set_format_json: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number];
     readonly xlsxworkbook_set_selection_after: (a: number, b: number, c: number) => void;

package/wasm/xlsx_engine.js

@@ -20,6 +20,22 @@ export class XlsxWorkbook {
         const ptr = this.__destroy_into_raw();
         wasm.__wbg_xlsxworkbook_free(ptr, 0);
     }
+    /**
+     * Adds an empty worksheet after the tab at `after` (at the end without it); returns its
+     * tab position
+     * @param {string} name
+     * @param {number | null} [after]
+     * @returns {number}
+     */
+    add_sheet(name, after) {
+        const ptr0 = passStringToWasm0(name, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.xlsxworkbook_add_sheet(this.__wbg_ptr, ptr0, len0, isLikeNone(after) ? Number.MAX_SAFE_INTEGER : (after) >>> 0);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return ret[0] >>> 0;
+    }
     /**
      * Context of an area for an agent (see `Workbook::area_context`): `target` is a table or
      * defined name, an address with its sheet, or a range of the sheet at `sheet`
@@ -305,6 +321,21 @@ export class XlsxWorkbook {
             wasm.__wbindgen_free(deferred3_0, deferred3_1, 1);
         }
     }
+    /**
+     * Renames the tab at `sheet` and the references to it; returns how many formulas changed
+     * @param {number} sheet
+     * @param {string} name
+     * @returns {number}
+     */
+    rename_sheet(sheet, name) {
+        const ptr0 = passStringToWasm0(name, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.xlsxworkbook_rename_sheet(this.__wbg_ptr, sheet, ptr0, len0);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return ret[0] >>> 0;
+    }
     /**
      * Width in characters of the columns `first..=last` (1 = A)
      * @param {number} sheet

package/wasm/xlsx_engine_bg.wasm.d.ts

@@ -3,6 +3,7 @@
 export const memory: WebAssembly.Memory;
 export const __wbg_xlsxworkbook_free: (a: number, b: number) => void;
 export const main_js: () => void;
+export const xlsxworkbook_add_sheet: (a: number, b: number, c: number, d: number) => [number, number, number];
 export const xlsxworkbook_area_context_json: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => [number, number, number, number];
 export const xlsxworkbook_areas_json: (a: number, b: number) => [number, number, number, number];
 export const xlsxworkbook_can_redo: (a: number) => number;
@@ -20,6 +21,7 @@ export const xlsxworkbook_range_json: (a: number, b: number, c: number, d: numbe
 export const xlsxworkbook_recalculate: (a: number) => [number, number, number];
 export const xlsxworkbook_redo_json: (a: number) => [number, number];
 export const xlsxworkbook_region_at_json: (a: number, b: number, c: number, d: number) => [number, number, number, number];
+export const xlsxworkbook_rename_sheet: (a: number, b: number, c: number, d: number) => [number, number, number];
 export const xlsxworkbook_set_column_width: (a: number, b: number, c: number, d: number, e: number) => [number, number];
 export const xlsxworkbook_set_format_json: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number];
 export const xlsxworkbook_set_selection_after: (a: number, b: number, c: number) => void;