@dimarborda/xlsx-editor 0.2.0 → 0.3.1

package/README.md

@@ -1,265 +1,76 @@
 # @dimarborda/xlsx-editor
 
-Componente para ver y editar libros de Excel (`.xlsx`) en el navegador, dibujados en canvas como los muestra Excel. Por dentro usa un motor escrito en Rust y compilado a WebAssembly, que lee el archivo, resuelve estilos y formatos de número, recalcula fórmulas y guarda sin pérdidas. Ese motor también se usa sin interfaz, en Node.js, desde [`@dimarborda/xlsx-editor/engine`](#motor-sin-interfaz-nodejs). Comparte con [`@dimarborda/docx-editor`](../docx-editor) la capa de paquete OOXML (`crates/ooxml-core`). Funciona en cualquier frontend (HTML, React, Vue, Svelte, Angular, Tauri) y nada sale del navegador.
+View and edit Excel (`.xlsx`) workbooks in the browser, drawn on canvas the way Excel shows them, and work with them from Node.js. A Rust and WebAssembly engine reads the file, recalculates formulas and saves losslessly: what it does not touch stays byte by byte. It works with React, Vue, Svelte, Angular or plain HTML, and in desktop apps such as Tauri. It needs no server: the library sends your files nowhere.
 
-> **Estado: fase 2, edición de celdas.** Se escriben valores y fórmulas en la cuadrícula, se borran, se copian y pegan, y se deshacen. Las fórmulas habituales se recalculan al momento (ver [Limitaciones](#limitaciones)). Con el atributo `readonly` sigue siendo un visor.
+For AI agents, `wb.area()` gives a table's columns, types and totals without reading the whole sheet, and a change that would break something is refused with the reason, leaving the workbook as it was.
+
+**Full documentation on GitHub:** [English](https://github.com/dimarborda/rust-web-docx/blob/master/docs/xlsx-editor/en/component.md) · [Español](https://github.com/dimarborda/rust-web-docx/blob/master/docs/xlsx-editor/es/component.md)
+
+## Install
 
 ```bash
 npm install @dimarborda/xlsx-editor
 ```
 
 ```html
-<xlsx-editor src="/informe.xlsx" locale="es" style="height: 80vh"></xlsx-editor>
+<xlsx-editor src="/report.xlsx" locale="en" style="height: 80vh"></xlsx-editor>
 <script type="module">
   import '@dimarborda/xlsx-editor';
-  import '@dimarborda/xlsx-editor/fonts';      // opcional: sustitutos de Calibri, Arial…
+  import '@dimarborda/xlsx-editor/fonts';      // optional: substitutes for Calibri, Arial…
   import '@dimarborda/xlsx-editor/style.css';
 </script>
 ```
 
-## Qué muestra
-
-- **Celdas como en Excel:** fuentes, negrita, cursiva, subrayado, tachado, colores (incluidos los del tema y sus tonos), rellenos y bordes con todos sus estilos.
-- **Formatos de número:** separadores según el idioma, moneda, porcentajes, notación científica, fracciones, secciones y condiciones, colores como `[Red]`, y fechas y horas con nombres de meses y días en español o inglés.
-- **Alineación:** la de Excel por defecto (números a la derecha, texto a la izquierda), horizontal y vertical, sangría, ajuste de texto, texto que se desborda sobre celdas vacías y `####` en los números que no caben.
-- **Cuadrícula:** anchos de columna y altos de fila del archivo, filas y columnas ocultas, celdas combinadas, paneles inmovilizados y líneas de cuadrícula (o su ausencia).
-- **Navegación:** desplazamiento fluido en hojas grandes (solo se dibuja lo visible), zoom, pestañas de hojas, selección con ratón y teclado, y una barra con la celda activa y su contenido o fórmula.
-
-Aún no se dibujan gráficos, imágenes, formato condicional ni comentarios, y el texto girado se dibuja horizontal. Las fórmulas se recalculan tras cada cambio con el motor del paquete; las que usan algo que no admite muestran el último valor que guardó Excel.
-
-## Edición
-
-| Acción | Cómo |
-| :--- | :--- |
-| Escribir en una celda | Empieza a escribir (sustituye el contenido), pulsa **F2** o haz doble clic (edita el contenido actual), o escribe en la barra de celda. |
-| Confirmar | **Enter** (baja), **Mayús+Enter** (sube), **Tab** / **Mayús+Tab** (derecha / izquierda). Si empezaste a escribir sin F2, las flechas también confirman y mueven; **F2** alterna entre ese modo y mover el cursor dentro del texto. |
-| Rellenar la selección | **Ctrl/Cmd+Enter** escribe lo mismo en todas las celdas seleccionadas. |
-| Salto de línea en la celda | **Alt+Enter**. |
-| Cancelar | **Escape**. |
-| Borrar | **Supr** o **Retroceso** vacían el rango seleccionado; el formato de las celdas se queda. |
-| Copiar, cortar y pegar | **Ctrl/Cmd+C**, **X** y **V**, como texto separado por tabulaciones (TSV), el mismo que intercambian Excel y Google Sheets. Al copiar se copian los textos que muestran las celdas; si se pega en el mismo editor lo que se acaba de copiar, se pegan los valores exactos. Un bloque que cabe un número entero de veces en la selección se repite. Cortar vacía las celdas al momento (no al pegar, como hace Excel). |
-| Deshacer y rehacer | **Ctrl/Cmd+Z**, y **Ctrl/Cmd+Y** o **Cmd+Mayús+Z**. Cada edición, borrado o pegado es un paso; deshacer vuelve a la hoja y a la selección de entonces. |
-
-### Qué se guarda al escribir
-
-Lo escrito se interpreta como lo hace Excel en el idioma del editor (`locale`; `es` y sus variantes usan las convenciones españolas y el resto las inglesas):
-
-| Escribes (`es`) | Escribes (`en`) | Se guarda |
-| :--- | :--- | :--- |
-| `1234,5` · `1.234,5` · `-0,5` · `(300)` · `1,5E+3` | `1234.5` · `1,234.5` · `-0.5` · `(300)` · `1.5E+3` | Número |
-| `1.234,50 €` | `$1,234.50` | Número (el símbolo se descarta) |
-| `15%` · `12,5 %` | `15%` · `12.5 %` | Número dividido por 100 (0,15) |
-| `15/03/2024` · `15-3-24` · `15/3` · `2024-03-15` | `3/15/2024` · `3-15-24` · `3/15` · `2024-03-15` | Fecha (sin año, el actual; años de dos cifras: 00–29 → 2000, 30–99 → 1900) |
-| `15/03/2024 14:30` | `3/15/2024 2:30 PM` | Fecha y hora |
-| `14:30` · `14:30:15` | `2:30 PM` | Hora, como fracción del día |
-| `VERDADERO` · `FALSO` | `TRUE` · `FALSE` | Booleano (sin distinguir mayúsculas) |
-| `'0012` | `'0012` | Texto `0012`: el apóstrofo inicial fuerza texto |
-| `=SUM(A1:A3)` | `=SUM(A1:A3)` | Fórmula (ver Limitaciones) |
-| Cualquier otra cosa | | Texto |
-| (vacío) | | Celda vacía |
-
-Los valores se escriben con `sheet.setValues` del motor, que conserva el formato de la celda: un número escrito en una celda con formato de moneda se ve como moneda. A las fechas se les da un formato de fecha basado en el de la celda si no lo tenía. Los porcentajes y las horas se guardan como su valor (0,15 o 0,604…) y se ven con el formato que ya tenga la celda. La misma función está disponible como `parseInput(texto, locale)`.
-
-### Limitaciones
-
-- **Fórmulas:** lo que empieza por `=` se guarda como fórmula y se calcula, igual que las fórmulas que dependen de ella. Se escriben en la sintaxis en inglés (`=SUM(A1:A3)`, `,` o `;` entre argumentos) en cualquier idioma del editor. Las funciones admitidas están en el [motor](#fórmulas); con otras, la celda muestra el último valor guardado y Excel la calcula al abrir el archivo (`fullCalcOnLoad`).
-- **Formato:** escribir no cambia el formato de número (salvo en fechas), y las columnas no se ensanchan solas: una fecha en una columna estrecha se ve como `####`, como en Excel.
-- No se puede sobrescribir la celda de origen de una fórmula compartida (la que usan otras celdas); el editor emite `error` y deja el libro como estaba.
-
-### Áreas y contexto para agentes
-
-- `editor.selectArea(destino)`: selecciona un área y muestra su hoja. Acepta una tabla o un rango con nombre, una dirección (`Ventas!A1:H40`) o un rango de la hoja activa. Devuelve el área (ver [Áreas para agentes](#áreas-para-agentes)).
-- `editor.selectionContext({ maxRows })`: contexto de lo seleccionado para un agente: el rango, o con una sola celda la región que la rodea (su tabla, o el bloque que seleccionaría Ctrl+A). Devuelve título, cabecera, tipos y totales por columna, las primeras filas y una tabla Markdown.
-
-Para dar formato desde código se usa `editor.workbook.sheet(…).setFormat(…)` y después `editor.reload()`.
-
-## Atributos
-
-| Atributo | Para qué |
-| :--- | :--- |
-| `src` | URL del `.xlsx` |
-| `blank` | Empieza con un libro vacío |
-| `locale` | Idioma de los formatos (`es`, `en-US`…); por defecto, el de la página |
-| `sheet` | Hoja inicial, por nombre o posición |
-| `zoom` | 0.25–4 |
-| `tabs="false"` | Oculta las pestañas |
-| `formula-bar="false"` | Oculta la barra de celda |
-| `readonly` | Modo visor: se selecciona y se copia, pero no se edita (se puede quitar y poner en cualquier momento) |
-| `quiet` | No escribe los errores en la consola |
-| `wasm-url` | Dónde se sirve `xlsx_engine_bg.wasm`, si el bundler no lo hace |
-
-Eventos en el elemento: `ready` (con `detail.editor`), `load`, `sheetchange`, `selectionchange`, `change` y `error`.
-
-`change` llega tras cada edición, borrado, pegado, corte, deshacer o rehacer:
-
-```js
-element.addEventListener('change', ({ detail }) => {
-  // detail: { sheet: 'Ventas', index: 0, range: 'B3:C4', source: 'edit' | 'clear' | 'paste' | 'cut' | 'undo' | 'redo',
-  //           cells: [{ ref: 'B3', value: 1200 }, …] }
-});
-```
-
-## API
+With WebAssembly, the production `script-src` needs `'wasm-unsafe-eval'`.
 
-```js
-const element = document.querySelector('xlsx-editor');
-element.addEventListener('ready', async ({ detail: { editor } }) => {
-  await editor.open(file);             // URL, File/Blob, ArrayBuffer o Uint8Array
-  editor.setSheet('Resumen');
-  editor.select('B3:D7');
-  editor.setZoom(1.25);
+## Features
 
-  // 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();
+- **Faithful display:** fonts, colors, borders, number formats, merged cells, frozen panes and hidden lines. Large sheets scroll smoothly.
+- **Editing:** values and formulas, copy and paste with Excel and Google Sheets, undo, and a status bar with average, count and sum.
+- **Rows and columns:** move, insert, delete, resize, autofit, hide and show, updating formulas, names, charts and tables across the workbook.
+- **Productivity:** fill handle with series, autosum, find and replace, keyboard navigation and a context menu.
+- **Formulas:** about 90 functions recalculated instantly; for anything else, Excel's saved value stays and Excel recalculates when opening the file.
+- **Headless engine:** the same API in Node.js.
 
-  editor.undo();                       // también editor.redo(), editor.canUndo, editor.canRedo
-  editor.readOnly = true;              // lo mismo que el atributo readonly
+Charts, images, conditional formats and comments are kept in the file but not drawn yet.
 
-  editor.download('informe.xlsx');
-});
-```
-
-Los cambios hechos desde código con `editor.workbook` no forman un paso de deshacer propio: llama antes a `editor.workbook.checkpoint()` para que lo sean.
-
-Sin el elemento: `const editor = await XlsxEditor.create(contenedor, { locale: 'es', readOnly: false })`.
-
-## Motor sin interfaz (Node.js)
-
-`@dimarborda/xlsx-editor/engine` es el mismo motor sin cuadrícula ni DOM: lee, escribe, recalcula y da formato a libros en Node.js (scripts, servidores, herramientas de agentes) o en el navegador.
-
-```bash
-npm install @dimarborda/xlsx-editor
-```
+## Use it from code
 
 ```js
 import { readFile, writeFile } from 'node:fs/promises';
 import { openWorkbook } from '@dimarborda/xlsx-editor/engine';
 
-const wb = await openWorkbook(await readFile('plantilla.xlsx'));
-
-// Variables {{CAMPO}} en cualquier texto del libro
-wb.fillTemplate({ CLIENTE: 'Acme S.A.', FECHA: '15/01/2024' });
+const wb = await openWorkbook(await readFile('template.xlsx'));
+const sheet = wb.sheet('Sales');
 
-// Filas de datos a partir de una celda
-const hoja = wb.sheet('Ventas');
-hoja.setValues('A2', [
-  ['Teclado', 3, 29.9, new Date(Date.UTC(2024, 0, 15))],
-  ['Ratón', 5, 12.5, new Date(Date.UTC(2024, 0, 16))],
-]);
+wb.fillTemplate({ CLIENT: 'Acme Inc.' });
+sheet.setValues('A2', [['Keyboard', 3, 29.9], ['Mouse', 5, 12.5]]);
+sheet.setValue('D2', { formula: '=B2*C2' });
+sheet.insertRows(2);
+sheet.fill('D3', 'D3:D4');
 
-console.log(hoja.getValue('B10'));   // resultado de una fórmula, ya recalculado
-await writeFile('salida.xlsx', wb.toBytes());
+await writeFile('output.xlsx', wb.toBytes());
 ```
 
-En Node el motor se carga solo. En el navegador, los bundlers (Vite, webpack 5, Rollup) sirven el `.wasm` junto al JavaScript; si lo sirves desde otro sitio, llama antes a `initEngine(url)`. La entrada principal del paquete también exporta todo esto, así que en el navegador basta con `import { openWorkbook } from '@dimarborda/xlsx-editor'`; `editor.workbook` es un `Workbook` de esta misma API.
-
-### API
-
-| | |
-|---|---|
-| `openWorkbook(bytes)` / `createWorkbook()` | Abre un `.xlsx` o crea un libro con una hoja vacía. |
-| `wb.sheetNames` | Nombres de las hojas en el orden de las pestañas. |
-| `wb.sheet(nombreOÍndice)` / `wb.sheets` | Una hoja de cálculo (por nombre, sin distinguir mayúsculas, o por posición desde 0) o todas. Las hojas de gráfico no tienen celdas. |
-| `hoja.getCell('B3')` | `{ ref, type, value, formula? }`. `type` es `empty`, `number`, `string`, `boolean`, `date` o `error` (`value` es entonces el código, p. ej. `#DIV/0!`). En las fórmulas, `value` es su resultado y `formula` su texto sin `=` (también en las celdas de una fórmula compartida). |
-| `hoja.getValue('B3')` / `hoja.getValues('A1:C3')` | Solo los valores; las celdas vacías dan `null`. |
-| `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. |
-| `wb.recalculate()` | Recalcula todas las fórmulas y devuelve cuántas celdas cambiaron de valor. |
-| `wb.areas({ sheet })` / `hoja.areas()` | Las áreas del libro (ver [Áreas](#áreas-para-agentes)). |
-| `wb.area(destino, { sheet, maxRows, locale })` / `hoja.area(rango)` | Contexto de un área para un agente. |
-| `hoja.regionAt('B5')` | La región alrededor de una celda, como la selecciona Ctrl+A en Excel (o su tabla). |
-| `hoja.setFormat('A1:C3', formato)` / `hoja.clearFormat(rango)` | Da formato (ver [Formato](#formato)) o lo quita. |
-| `hoja.setColumnWidth('B:D', 14)` | Ancho de columnas en caracteres. |
-| `hoja.mergeCells('A1:H1')` / `hoja.unmergeCells(rango)` | Combina o separa celdas; al combinar, solo la primera puede tener valor. |
-| `wb.toBytes()` | El libro como `.xlsx`. |
-| `wb.close()` | Libera la memoria del motor. |
-
-#### Fórmulas
-
-Las fórmulas se escriben con `{ formula: '=SUM(B2:B10)*IVA' }` y se calculan en el momento. Cada vez que se escribe una celda (o se rellena una plantilla) se recalculan, en orden de dependencias, todas las fórmulas del libro, y solo se reescribe el `<v>` de las celdas cuyo resultado cambió. `wb.recalculate()` hace lo mismo sin editar nada, por ejemplo para refrescar un libro recién abierto.
-
-Se usa la sintaxis en inglés que guarda Excel (`SUM`, `IF`, `,` entre argumentos; también se acepta `;`). Se admiten referencias relativas y absolutas, rangos, columnas completas (`A:A`), otras hojas (`'Mis datos'!B2`), nombres definidos, fórmulas compartidas y matrices constantes (`{1,2;3,4}`), con las conversiones de Excel entre texto, número y booleano y sus códigos de error. Funciones:
-
-- **Matemáticas:** `SUM`, `PRODUCT`, `AVERAGE`, `MIN`, `MAX`, `MEDIAN`, `COUNT`, `COUNTA`, `COUNTBLANK`, `ROUND`, `ROUNDUP`, `ROUNDDOWN`, `INT`, `TRUNC`, `ABS`, `SIGN`, `SQRT`, `POWER`, `MOD`, `PI`, `CEILING`, `FLOOR`, `CEILING.MATH`, `FLOOR.MATH`, `SUMPRODUCT`.
-- **Condicionales:** `SUMIF`, `SUMIFS`, `COUNTIF`, `COUNTIFS`, `AVERAGEIF`, `AVERAGEIFS`, `MAXIFS`, `MINIFS` (criterios como `">5"`, `"<>x"`, `"n*"`).
-- **Lógicas e información:** `IF`, `IFS`, `SWITCH`, `IFERROR`, `IFNA`, `AND`, `OR`, `XOR`, `NOT`, `TRUE`, `FALSE`, `ISBLANK`, `ISNUMBER`, `ISTEXT`, `ISNONTEXT`, `ISLOGICAL`, `ISERROR`, `ISERR`, `ISNA`, `NA`.
-- **Búsqueda:** `VLOOKUP`, `HLOOKUP`, `XLOOKUP`, `MATCH`, `INDEX`, `CHOOSE`, `ROW`, `COLUMN`, `ROWS`, `COLUMNS`.
-- **Texto:** `CONCATENATE`, `CONCAT`, `TEXTJOIN`, `LEFT`, `RIGHT`, `MID`, `LEN`, `UPPER`, `LOWER`, `PROPER`, `TRIM`, `SUBSTITUTE`, `REPT`, `EXACT`, `FIND`, `SEARCH`, `VALUE`, `TEXT`.
-- **Fechas:** `TODAY`, `NOW`, `DATE`, `YEAR`, `MONTH`, `DAY`, `WEEKDAY`, `EDATE`, `EOMONTH`, `DAYS`.
-
-Una fórmula que use otra cosa (una función que no está en la lista, `OFFSET`, `INDIRECT`, referencias a otros libros o a tablas, fórmulas matriciales, resultados que se desbordan a varias celdas) o que forme una referencia circular conserva el valor que guardó Excel, y las que dependen de ella lo usan. Al abrirse el archivo, Excel la calcula (ver abajo).
-
-#### Áreas para agentes
-
-Un agente no necesita leer toda la hoja: puede pedir las áreas y luego el contexto de la que le interesa. `wb.areas()` usa lo que el propio archivo marca, en este orden:
-
-1. **Tablas** de Excel (Dar formato como tabla, `xl/tables/tableN.xml`): nombre, rango, nombres de columna y fila de totales.
-2. **Nombres definidos** que apuntan a un rango (`Ventas = Datos!$A$3:$H$40`) y el **área de impresión**.
-3. **Filtros** (`autoFilter`) de la hoja.
-4. **Regiones**: bloques de celdas llenas contiguas, como los selecciona Ctrl+A, donde el archivo no marca nada. Las filas iniciales con una sola celda (o una combinada) son el **título**, igual que un texto suelto justo encima; la primera fila de textos seguida de datos (o en negrita) es la **cabecera**.
-
-Cada área es `{ kind, name, sheet, sheetName, ref, address, title, headerRow, totalsRow, body, columns }`; `address` (`Ventas!A1:H64`) sirve como destino en cualquier llamada.
-
-`wb.area(destino)` acepta el nombre de una tabla o de un rango con nombre, una dirección con hoja o, con `{ sheet }`, un rango de esa hoja. Devuelve la descripción del área y además:
-
-- `columnsInfo`: por columna, su nombre, tipo (`number`, `text`, `date`, `mixed`…), cuántas celdas tienen valor, suma, mínimo, máximo y media de los números, y cuántas fórmulas hay con un ejemplo (`D4: =B4*C4`).
-- `rows`: las primeras `maxRows` filas de datos (30 por defecto) con el texto que muestran las celdas, `firstRow`, `rowCount` y `truncated`.
-- `totals`, `merges` y `markdown`: el área como tabla Markdown con números de fila y letras de columna, lista para pasarla a un modelo.
-
-#### Formato
+In the browser, `element.editor` is the editor and `editor.workbook` this same API:
 
-`hoja.setFormat(rango, formato)` cambia solo lo que se indica y conserva el resto del aspecto de cada celda:
-
-| Propiedad | Valor |
-|---|---|
-| `bold`, `italic`, `underline`, `strike` | `true` / `false` |
-| `color` | Color de la letra, `#RRGGBB` |
-| `fontSize`, `fontName` | Puntos; nombre de fuente |
-| `fill` | Fondo `#RRGGBB`; `null` lo quita |
-| `numberFormat` | Código de Excel: `#,##0.00`, `0%`, `dd/mm/yyyy`, `#,##0.00 "€"`… |
-| `align`, `valign`, `wrap` | `left`, `center`, `right`…; `top`, `center`, `bottom`; ajuste de texto |
-| `border` | Un estilo (`'thin'`, `'medium'`, `'thick'`, `'dashed'`, `'dotted'`, `'double'`) en todos los lados, `null` para quitarlos, o `{ style, color, edges }` con `edges`: `all`, `outline`, `inside`, `top`, `bottom`, `left` o `right` |
-
-Los formatos nuevos se añaden a `xl/styles.xml` y se reutilizan los iguales que ya existan; nada de lo que ya estaba se reescribe.
-
-#### Fechas
-
-Excel guarda las fechas como números de serie (días desde 1900, o desde 1904 en libros con ese sistema) que se ven como fecha por el formato de la celda. Al leer, una celda numérica con formato de fecha se devuelve como `Date`; al escribir un `Date`, la celda recibe un formato de fecha basado en el que tenía (misma fuente, relleno y bordes), salvo que ya mostrara fechas.
-
-Las fechas de Excel no tienen zona horaria: la hora que muestra Excel se representa como hora **UTC** del `Date`. Escribe con `new Date(Date.UTC(2024, 0, 15))` y lee con `getUTCFullYear()`, `getUTCHours()` o `toISOString()`.
-
-### Sin pérdidas
-
-Solo se reescriben las partes del archivo que cambian (la hoja editada, las cadenas compartidas y, si hace falta, los estilos), y dentro de ellas solo las celdas escritas: gráficos, imágenes, formatos condicionales, validaciones, nombres definidos y todo lo demás se guarda byte a byte tal como estaba.
-
-Cuando un libro cambia, se elimina `xl/calcChain.xml` (Excel lo reconstruye) y se marca `fullCalcOnLoad="1"` para que Excel recalcule las fórmulas al abrirlo: así quedan bien también las que este motor no calcula.
-
-Limitaciones actuales:
-
-- Las fórmulas fuera de lo admitido (ver [Fórmulas](#fórmulas)) no se recalculan: `getValue` devuelve su último resultado guardado.
-- Las fórmulas se escriben en la sintaxis en inglés (`SUM`, no `SUMA`); los nombres de función en español no se traducen.
-- Escribir en la celda de origen de una fórmula compartida (la que usan otras celdas) da error, para no romper esas celdas.
-- Una variable `{{CAMPO}}` partida entre fragmentos de texto con formatos distintos no se reconoce.
-
-## Content Security Policy
+```js
+document.querySelector('xlsx-editor').addEventListener('ready', async ({ detail: { editor } }) => {
+  await editor.open(file);
+  editor.moveRows(4, 2, 9);
+  editor.download('report.xlsx');
+});
+```
 
-Como el motor es WebAssembly, el `script-src` de producción necesita `'wasm-unsafe-eval'`.
+## Documentation
 
-## Desarrollo
+| Guide | English | Español |
+| :--- | :--- | :--- |
+| Component: keyboard, attributes, events, editor API | [component](https://github.com/dimarborda/rust-web-docx/blob/master/docs/xlsx-editor/en/component.md) | [component](https://github.com/dimarborda/rust-web-docx/blob/master/docs/xlsx-editor/es/component.md) |
+| Move, insert, delete, fill, find and replace | [operations](https://github.com/dimarborda/rust-web-docx/blob/master/docs/xlsx-editor/en/operations.md) | [operations](https://github.com/dimarborda/rust-web-docx/blob/master/docs/xlsx-editor/es/operations.md) |
+| Engine: full API, formulas, formats, dates | [engine](https://github.com/dimarborda/rust-web-docx/blob/master/docs/xlsx-editor/en/engine.md) | [engine](https://github.com/dimarborda/rust-web-docx/blob/master/docs/xlsx-editor/es/engine.md) |
+| Areas and context for AI agents | [agents](https://github.com/dimarborda/rust-web-docx/blob/master/docs/xlsx-editor/en/agents.md) | [agents](https://github.com/dimarborda/rust-web-docx/blob/master/docs/xlsx-editor/es/agents.md) |
 
-Desde la raíz del repositorio:
+## License
 
-```bash
-npm run build:wasm:xlsx
-npm test -w packages/xlsx-editor
-npm run dev        # http://localhost:5173/xlsx.html
-```
+MIT

package/package.json

@@ -1,16 +1,18 @@
 {
   "name": "@dimarborda/xlsx-editor",
-  "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",
+  "version": "0.3.1",
+  "description": "Excel (.xlsx) editor for the browser and engine for Node.js: Rust + WebAssembly that edits workbooks without losing what it does not touch, from a canvas grid or from code. An AI agent can read a table's structure without loading the whole sheet",
   "type": "module",
   "license": "MIT",
   "author": "Dimar Borda",
+  "homepage": "https://github.com/dimarborda/rust-web-docx/blob/master/docs/xlsx-editor/README.md",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/dimarborda/rust-web-docx.git",
     "directory": "packages/xlsx-editor"
   },
   "keywords": [
+    "ai-agents",
     "xlsx",
     "excel",
     "spreadsheet",

package/src/draw.js

@@ -26,7 +26,7 @@ export function canvasFont(font, zoom = 1) {
 }
 
 const GRIDLINE = '#d9d9d9';
-const PAD = 3; // horizontal text padding, px at zoom 1
+export const PAD = 3; // horizontal text padding, px at zoom 1
 
 /** Line width and dash of an Excel border style, at zoom 1 */
 function borderLook(style) {
@@ -341,8 +341,13 @@ export function drawHeaders(ctx, { rows, cols, colSegs, rowSegs, rowHeaderW, col
     ctx.clip();
     for (let c = seg.from; c <= seg.to; c++) {
       const size = cols.size(c) * zoom;
-      if (size === 0) continue;
       const x = seg.start + (cols.offset(c) - cols.offset(seg.from)) * zoom;
+      if (size === 0) {
+        // Where hidden columns are: a thicker line, as Excel draws it
+        ctx.fillStyle = HEADER_TEXT;
+        ctx.fillRect(Math.round(x) - 2, 0, 2, colHeaderH);
+        continue;
+      }
       const active = selection && inSel(c, selection.first.col, selection.last.col);
       if (active) {
         ctx.fillStyle = ACTIVE_BG;
@@ -364,8 +369,12 @@ export function drawHeaders(ctx, { rows, cols, colSegs, rowSegs, rowHeaderW, col
     ctx.clip();
     for (let r = seg.from; r <= seg.to; r++) {
       const size = rows.size(r) * zoom;
-      if (size === 0) continue;
       const y = seg.start + (rows.offset(r) - rows.offset(seg.from)) * zoom;
+      if (size === 0) {
+        ctx.fillStyle = HEADER_TEXT;
+        ctx.fillRect(0, Math.round(y) - 2, rowHeaderW, 2);
+        continue;
+      }
       const active = selection && inSel(r, selection.first.row, selection.last.row);
       if (active) {
         ctx.fillStyle = ACTIVE_BG;

package/src/elements.js

@@ -49,6 +49,7 @@ export class XlsxEditorElement extends ElementBase {
       zoom: Number(this.getAttribute('zoom')) || 1,
       tabs: this.getAttribute('tabs') !== 'false',
       formulaBar: this.getAttribute('formula-bar') !== 'false',
+      statusBar: this.getAttribute('status-bar') !== 'false',
       readOnly: this.hasAttribute('readonly'),
       wasmUrl: this.getAttribute('wasm-url') || undefined,
     });

package/src/engine.d.ts

@@ -150,6 +150,46 @@ export class Sheet {
    * language `locale` (`es`, `en-US`…; default `en`)
    */
   cellViews(locale?: string): CellViewRow[];
+  /**
+   * Moves `count` whole rows from `first` before the row `before` (numbered as they are now), as
+   * Excel's "cut and insert": formats, heights, formulas of the whole workbook, names, charts,
+   * tables, validations, conditional formats, images and comments follow. Throws, and changes
+   * nothing, when it would tear merged cells, an array formula, a table or a filter. Returns
+   * where the first row ends up.
+   */
+  moveRows(first: number, count: number, before: number): number;
+  /** Moves whole columns (see `moveRows`); columns as letters (`'B'`) or numbers */
+  moveColumns(first: string | number, count: number, before: string | number): number;
+  /**
+   * Inserts `count` empty rows before the row `before`, with the height and format of the one
+   * above: formulas, names, charts and the rest are updated, and ranges, merged cells and tables
+   * that the new rows fall inside grow. Returns `before`.
+   */
+  insertRows(before: number, count?: number): number;
+  /** Inserts empty columns before `before`, like the one to their left (not inside a table) */
+  insertColumns(before: string | number, count?: number): number;
+  /**
+   * Deletes `count` rows from `first`: what pointed only at them becomes `#REF!`, and ranges,
+   * merged cells and tables shrink. Returns `first`.
+   */
+  deleteRows(first: number, count?: number): number;
+  /** Deletes columns from `first` (not inside a table) */
+  deleteColumns(first: string | number, count?: number): number;
+  /** Hides or shows rows (`3`, `'3:5'`); they keep their cells and height */
+  setRowsHidden(rows: string | number, hidden: boolean): void;
+  /** Hides or shows columns (`'B'`, `'B:D'`, `2`); they keep their cells and width */
+  setColumnsHidden(columns: string | number, hidden: boolean): void;
+  /**
+   * Fills `target` from `source`, the cells at one of its ends, as Excel's fill handle: formats
+   * repeat, formulas move their references, and with `series` (by default) numbers continue their
+   * trend, one date goes on day by day, texts ending in a number count on and names of months and
+   * days follow their order
+   */
+  fill(source: string, target: string, options?: { series?: boolean }): void;
+  /** The cells of a range (`A1:C3`), by row: their type, value and formula, if any */
+  getCells(range: string): Cell[][];
+  /** Height of a row or rows (`3`, `'3:5'`) in points; `null` goes back to the automatic height */
+  setRowHeight(rows: string | number, height: number | null): void;
   /** Areas of this sheet */
   areas(): Area[];
   /** The region around a cell as Excel's Ctrl+A selects it (or its table, or the cell alone) */
@@ -188,10 +228,10 @@ export interface SheetLayout {
 }
 
 /**
- * `[row, col, style, text, kind, color?]`: `kind` is `n` (number or date), `s` (text), `b`,
+ * `[row, col, style, text, kind, color?, number?]`: `kind` is `n` (number or date), `s` (text), `b`,
  * `e` (error) or `''` (empty cell with a format); `color` comes from the number format
  */
-export type CellViewRow = [number, number, number, string, 'n' | 's' | 'b' | 'e' | '', string?];
+export type CellViewRow = [number, number, number, string, 'n' | 's' | 'b' | 'e' | '', (string | null)?, number?];
 
 export interface FontView {
   name: string;

package/src/engine.js

@@ -73,6 +73,12 @@ function columnNumber(col) {
   throw new TypeError(`Columna no válida: ${col} (usa una letra como 'B' o un número desde 1).`);
 }
 
+/** A row or column number, or a count, for the engine */
+function lineNumber(value, what) {
+  if (!Number.isInteger(value) || value < 0) throw new TypeError(`${what} debe ser un entero positivo: ${value}`);
+  return value;
+}
+
 /** One worksheet of a workbook */
 export class Sheet {
   /**
@@ -96,6 +102,11 @@ export class Sheet {
     return this.getCell(ref).value;
   }
 
+  /** The cells of a range (`A1:C3`), by row: their type, value and formula, if any */
+  getCells(range) {
+    return JSON.parse(call(() => this.workbook._engine.range_json(this.index, range))).map(row => row.map(toCell));
+  }
+
   /** The values of a range (`A1:C3`), by row */
   getValues(range) {
     return JSON.parse(call(() => this.workbook._engine.range_json(this.index, range))).map(row => row.map(c => toCell(c).value));
@@ -132,8 +143,9 @@ export class Sheet {
 
   /**
    * Drawing API: every cell that shows something, with the text Excel shows for it in the
-   * language `locale`, as `[row, col, style, text, kind, color?]` (`kind`: `n`, `s`, `b`, `e`
-   * or `''` for an empty cell with a format; `style` indexes `workbook.styleView().xfs`)
+   * language `locale`, as `[row, col, style, text, kind, color?, number?]` (`kind`: `n`, `s`,
+   * `b`, `e` or `''` for an empty cell with a format; `style` indexes
+   * `workbook.styleView().xfs`; `number` is the value of `n` cells, dates as serial numbers)
    * @param {string} [locale]
    */
   cellViews(locale = 'en') {
@@ -183,6 +195,114 @@ export class Sheet {
     call(() => this.workbook._engine.set_column_width(this.index, columnNumber(a), columnNumber(b), width));
   }
 
+  /**
+   * Moves whole rows, as Excel's "cut and insert": `count` rows from `first` go before the row
+   * `before` (numbered as they are now). Formats, heights, merged cells, formulas of the whole
+   * workbook, defined names, charts, tables, validations, conditional formats, images and
+   * comments follow. Throws, and changes nothing, when it would tear merged cells, an array
+   * formula, a table or a filter. Returns where the first row ends up.
+   * @param {number} first
+   * @param {number} count
+   * @param {number} before
+   */
+  moveRows(first, count, before) {
+    const [a, n, b] = [lineNumber(first, 'La fila'), lineNumber(count, 'La cantidad'), lineNumber(before, 'El destino')];
+    return call(() => this.workbook._engine.move_rows(this.index, a, n, b));
+  }
+
+  /**
+   * Moves whole columns (see `moveRows`); `first` and `before` are letters (`'B'`) or numbers
+   * @param {string | number} first
+   * @param {number} count
+   * @param {string | number} before
+   */
+  moveColumns(first, count, before) {
+    const [a, n, b] = [columnNumber(first), lineNumber(count, 'La cantidad'), columnNumber(before)];
+    return call(() => this.workbook._engine.move_columns(this.index, a, n, b));
+  }
+
+  /**
+   * Inserts `count` empty rows before the row `before`, with the height and format of the one
+   * above. Formulas, names, charts and everything that `moveRows` follows are updated; ranges and
+   * merged cells that the new rows fall inside grow, also tables. Returns `before`.
+   * @param {number} before
+   * @param {number} [count]
+   */
+  insertRows(before, count = 1) {
+    const [b, n] = [lineNumber(before, 'La fila'), lineNumber(count, 'La cantidad')];
+    return call(() => this.workbook._engine.insert_rows(this.index, b, n));
+  }
+
+  /** Inserts empty columns before `before` (letters or number), like the one to their left */
+  insertColumns(before, count = 1) {
+    const [b, n] = [columnNumber(before), lineNumber(count, 'La cantidad')];
+    return call(() => this.workbook._engine.insert_columns(this.index, b, n));
+  }
+
+  /**
+   * Deletes `count` rows from `first`. What pointed only at them becomes `#REF!`; ranges and
+   * merged cells shrink, also tables. Returns `first`.
+   * @param {number} first
+   * @param {number} [count]
+   */
+  deleteRows(first, count = 1) {
+    const [a, n] = [lineNumber(first, 'La fila'), lineNumber(count, 'La cantidad')];
+    return call(() => this.workbook._engine.delete_rows(this.index, a, n));
+  }
+
+  /** Deletes columns from `first` (letters or number), see `deleteRows` */
+  deleteColumns(first, count = 1) {
+    const [a, n] = [columnNumber(first), lineNumber(count, 'La cantidad')];
+    return call(() => this.workbook._engine.delete_columns(this.index, a, n));
+  }
+
+  /**
+   * Height of a row or rows (`3`, `'3:5'`) in points; `null` goes back to the automatic height
+   * @param {string | number} rows
+   * @param {number | null} height
+   */
+  setRowHeight(rows, height) {
+    const [a, b = a] = typeof rows === 'string' ? rows.split(':').map(Number) : [rows];
+    if (height !== null && (typeof height !== 'number' || !Number.isFinite(height))) throw new TypeError('El alto debe ser un número de puntos o null.');
+    const [first, last] = [lineNumber(a, 'La fila'), lineNumber(b, 'La fila')];
+    call(() => this.workbook._engine.set_row_height(this.index, first, last, height ?? undefined));
+  }
+
+  /**
+   * Hides or shows rows (`3`, `'3:5'`); they keep their cells and height
+   * @param {string | number} rows
+   * @param {boolean} hidden
+   */
+  setRowsHidden(rows, hidden) {
+    const [a, b = a] = typeof rows === 'string' ? rows.split(':').map(Number) : [rows];
+    const [first, last] = [lineNumber(a, 'La fila'), lineNumber(b, 'La fila')];
+    call(() => this.workbook._engine.set_rows_hidden(this.index, first, last, !!hidden));
+  }
+
+  /**
+   * Hides or shows columns (`'B'`, `'B:D'`, `2`); they keep their cells and width
+   * @param {string | number} columns
+   * @param {boolean} hidden
+   */
+  setColumnsHidden(columns, hidden) {
+    const [a, b = a] = typeof columns === 'string' ? columns.split(':') : [columns];
+    const [first, last] = [columnNumber(a), columnNumber(b)];
+    call(() => this.workbook._engine.set_columns_hidden(this.index, first, last, !!hidden));
+  }
+
+  /**
+   * Fills `target` from `source`, the cells at one of its ends, as Excel's fill handle: formats
+   * repeat, formulas move their references, and with `series` (by default) numbers continue their
+   * trend, one date goes on day by day, texts ending in a number count on and names of months and
+   * days follow their order. Refuses to fill over merged cells.
+   * @param {string} source e.g. `A1:A2`
+   * @param {string} target e.g. `A1:A20`
+   * @param {{series?: boolean}} [options]
+   */
+  fill(source, target, { series = true } = {}) {
+    call(() => this.workbook._engine.fill_range(this.index, source, target, !!series));
+  }
+
   /** Merges a range into one cell; only its first cell may hold a value */
   mergeCells(range) {
     call(() => this.workbook._engine.merge_cells(this.index, range));
@@ -223,6 +343,16 @@ export class Workbook {
     return JSON.parse(call(() => this._engine.styles_view_json()));
   }
 
+  /**
+   * Numbers as a cell format shows them: `style` indexes `styleView().xfs`
+   * @param {number} style
+   * @param {number[]} values
+   * @param {string} [locale]
+   */
+  formatNumbers(style, values, locale = 'en') {
+    return call(() => this._engine.format_numbers(style, Float64Array.from(values), locale));
+  }
+
   /**
    * A worksheet by name (ignoring case) or by tab position, from 0
    * @param {string | number} nameOrIndex