nexabase-report 0.4.21 → 0.5.0

package/README.md

@@ -1,108 +1,59 @@
 # nexabase-report
 
-[![npm version](https://img.shields.io/npm/v/nexabase-report)](https://www.npmjs.com/package/nexabase-report)
-[![license](https://img.shields.io/npm/l/nexabase-report)](LICENSE)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.6-blue)](https://www.typescriptlang.org/)
-[![Vue 3](https://img.shields.io/badge/Vue-3.5-green)](https://vuejs.org/)
-
-> Librería Vue 3 + TypeScript para diseñar y visualizar reportes tipo banded (inspirada en Stimulsoft / DevExpress). Incluye **diseñador WYSIWYG** multilingüe (ES/EN/PT), **visor como Custom Element** framework-agnostic, y **exportación 100% cliente** a PDF, Excel, Word y CSV.
-
----
-
-## Características
-
-| Característica | Descripción |
-|----------------|-------------|
-| **Custom Element** | `<nexa-viewer>` funciona en Vue, React, Angular, Svelte, Blazor o HTML puro |
-| **Diseñador WYSIWYG** | `NexaDesigner.vue` — ribbon, lienzo con snap-to-grid, sidebars, i18n |
-| **Visor standalone** | Sin dependencia de Vue en el consumidor |
-| **Exportación 100% cliente** | PDF (html2pdf.js + fallback jsPDF vectorial), Excel (SheetJS), Word (docx), CSV (UTF-8 BOM) |
-| **Motor de paginación** | Algoritmo en dos fases: streaming + particionado por página, con splitting de tablas a través de páginas |
-| **Renderers** | Texto, imágenes, barras, QR, shapes, drill-down, charts (ECharts), crosstabs, subreportes, widgets |
-| **Watermarks** | Modo tile (texto repetido en grilla) o single posicionado (center, top-left, bottom-right, etc.) |
-| **TOC** | Tabla de contenidos auto-generada en página 1 con enlaces a secciones |
-| **Dashboard** | Modo de visualización con grilla de widgets |
-| **Gráficos** | ECharts (barras, líneas, pastel, área, scatter, radar, etc.) |
-| **Tablas dinámicas** | Crosstabs con agregaciones (sum, count, avg, min, max) |
-| **Códigos QR / Barras** | jsbarcode + qrcode con bindings a datos |
-| **Formato condicional** | Reglas por operador (eq, gt, contains, between, regex, etc.) |
-| **Master-Detail** | DataBand con DetailBand hijo, filtro por campo clave |
-| **Drill-Down** | Navegación a reporte destino con paso de parámetros |
-| **Subreportes** | Anidamiento vía definición embebida o remota (API REST) |
-| **Motor de expresiones** | Seguro (sin `eval`): `FormatNumber`, `FormatDate`, `IIF`, `ISNULL`, agregaciones, `SUBSTRING`, etc. |
-| **Parámetros** | Diálogo de entrada con tipos (text, number, date, boolean, select), validación, skip opcional |
-| **Shapes** | Rectángulos, elipses, líneas y flechas |
-| **Búsqueda** | Highlight inline con navegación entre resultados |
-| **Zoom** | Zoom +/- 10%, fitToWidth, fitToPage, modo continuo/página simple |
-| **i18n** | Visor y diseñador en español, inglés, portugués |
-
----
-
-## Instalación
+> Professional report designer and viewer — framework-agnostic, client-side PDF/Excel/Word export, banded report model inspired by Stimulsoft & DevExpress.
 
-```bash
-pnpm install nexabase-report
-```
+[![npm](https://img.shields.io/npm/v/nexabase-report.svg)](https://www.npmjs.com/package/nexabase-report)
+[![npm downloads](https://img.shields.io/npm/dm/nexabase-report.svg)](https://www.npmjs.com/package/nexabase-report)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/nexabase-report)](https://bundlephobia.com/package/nexabase-report)
+[![license](https://img.shields.io/npm/l/nexabase-report.svg)](https://github.com/nexabase/nexabase-report/blob/main/LICENSE)
 
-Importar estilos una sola vez al inicio:
+## Features
 
-```ts
-import 'nexabase-report/style.css';
-```
+- **WYSIWYG Designer** — drag & drop bands, elements, charts, crosstabs, barcodes, QR codes
+- **Framework-agnostic Viewer** — Custom Element (`<nexa-viewer>`) works with Vue, React, Angular, Blazor, jQuery, or plain HTML
+- **Client-side Export** — PDF (selectable text), Excel, Word, CSV — no server required
+- **Banded Report Model** — ReportHeader, PageHeader/Footer, DataBand, GroupHeader/Footer, ReportFooter
+- **Charts & Crosstabs** — ECharts integration, dynamic pivot tables with aggregations
+- **Dashboard Designer** — widgets (chart, gauge, indicator, table, filter, pivot, text, image)
+- **Expression Engine** — safe evaluation without `eval` — `FormatNumber`, `IIF`, `ISNULL`, `UPPER`, etc.
+- **Master-Detail & Drill-down** — nested data sources, subreports, clickable drill-through
+- **Conditional Formatting** — dynamic styles based on data values
+- **Parameters** — typed report parameters with validation dialog
+- **i18n** — built-in Spanish, English, Portuguese
 
----
+## Installation
+
+```bash
+npm install nexabase-report
+```
 
-## Uso rápido
+## Quick Start
 
-### HTML puro (sin framework)
+### Plain HTML / Any Framework
 
 ```html
 <!DOCTYPE html>
 <html>
 <head>
-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/nexabase-report/dist/style.css">
+  <link rel="stylesheet" href="node_modules/nexabase-report/dist/style.css">
 </head>
 <body>
   <nexa-viewer id="viewer" minimal></nexa-viewer>
 
-  <script src="https://cdn.jsdelivr.net/npm/nexabase-report/dist/nexabase-report.umd.js"></script>
+  <script src="node_modules/nexabase-report/dist/nexabase-report.umd.js"></script>
   <script>
-    NexaReport.registerNexaReport();
-
     const viewer = document.getElementById('viewer');
-    viewer.definition = { /* definición del reporte */ };
-    viewer.data = [ /* datos */ ];
+    viewer.definition = { /* report JSON */ };
+    viewer.data = [ /* array of records */ ];
   </script>
 </body>
 </html>
 ```
 
-### React
-
-```tsx
-import { useEffect, useRef } from 'react';
-import { registerNexaReport } from 'nexabase-report';
-import 'nexabase-report/style.css';
-
-registerNexaReport();
-
-export function ReportViewer({ definition, data }: { definition: any; data: any[] }) {
-  const ref = useRef<any>(null);
-
-  useEffect(() => {
-    if (!ref.current) return;
-    ref.current.definition = definition;
-    ref.current.data = data;
-  }, [definition, data]);
-
-  return <nexa-viewer ref={ref} minimal />;
-}
-```
-
 ### Vue 3
 
 ```vue
-<script setup lang="ts">
+<script setup>
 import { registerNexaReport } from 'nexabase-report';
 import 'nexabase-report/style.css';
 
@@ -110,473 +61,234 @@ registerNexaReport();
 </script>
 
 <template>
-  <nexa-viewer
-    :definition="definition"
-    :data="data"
-    minimal
-    style="display:block;height:700px"
-  />
+  <nexa-viewer :definition="reportDef" :data="reportData" minimal />
 </template>
 ```
 
-### Angular
+### React
 
-```ts
-import { registerNexaReport } from 'nexabase-report';
+```tsx
+import { useEffect, useRef } from 'react';
+import 'nexabase-report';
 import 'nexabase-report/style.css';
 
-registerNexaReport();
+function ReportViewer({ definition, data }: { definition: any; data: any[] }) {
+  const ref = useRef<any>(null);
 
-@Component({
-  template: '<nexa-viewer #viewer [definition]="reportDef" [data]="reportData"></nexa-viewer>',
-})
-export class ReportComponent {
-  @ViewChild('viewer') viewerRef!: ElementRef;
-  reportDef: any = null;
-  reportData: any[] = [];
-
-  async ngOnInit() {
-    this.reportDef = await fetch('/assets/report.json').then(r => r.json());
-    this.reportData = await fetch('/api/data').then(r => r.json());
-  }
+  useEffect(() => {
+    if (ref.current) {
+      ref.current.definition = definition;
+      ref.current.data = data;
+    }
+  }, [definition, data]);
+
+  return <nexa-viewer ref={ref} minimal style={{ width: '100%', height: '100%' }} />;
 }
 ```
 
-### Blazor (.NET 8+)
+### Blazor
 
 ```razor
-@page "/reporte/{Id:int}"
-@inject IJSRuntime JS
-
-<link rel="stylesheet" href="_content/nexabase-report/style.css" />
-<script src="_content/nexabase-report/nexabase-report.umd.js"></script>
-
 <nexa-viewer id="viewer" minimal></nexa-viewer>
 
 @code {
-    [Parameter] public int Id { get; set; }
-
     protected override async Task OnAfterRenderAsync(bool firstRender)
     {
-        if (!firstRender) return;
-        var def = await Http.GetFromJsonAsync<object>($"/api/reportes/{Id}");
-        var data = await Http.GetFromJsonAsync<List<object>>($"/api/reportes/{Id}/datos");
-        await JS.InvokeVoidAsync("renderNexaReport", def, data);
+        if (firstRender)
+        {
+            await JS.InvokeVoidAsync("initViewer", reportDef, data);
+        }
     }
 }
+```
 
-<script>
-    window.renderNexaReport = function(definition, data) {
-        if (!window.__nexaRegistered) {
-            NexaReport.registerNexaReport();
-            window.__nexaRegistered = true;
-        }
-        const v = document.getElementById('viewer');
-        v.definition = definition;
-        v.data = data;
-    };
-</script>
+```javascript
+// wwwroot/report.js
+function initViewer(def, data) {
+    const viewer = document.getElementById('viewer');
+    viewer.definition = def;
+    viewer.data = data;
+}
 ```
 
----
+## Viewer API
 
-## Diseñador (NexaDesigner)
+### Props
 
-Diseñador WYSIWYG como componente Vue 3:
+| Prop | Type | Description |
+|------|------|-------------|
+| `definition` | `NexaReportDefinition \| string` | Report definition (object or JSON string) |
+| `data` | `any[] \| Record<string, any[]>` | Data — array for single datasource, object for multiple |
+| `minimal` | `boolean` | Hide toolbar and sidebar |
+| `parameters` | `Record<string, any>` | Pre-fill parameter values (skips dialog) |
+| `skipParamsDialog` | `boolean` | Don't show parameter input dialog |
+| `currentPage` | `number` | Externally controlled page number |
+| `locale` | `'es' \| 'en' \| 'pt'` | UI language |
+| `licenseKey` | `string` | License key (optional) |
 
-- **Ribbon** — formato de texto (fuente, tamaño, color, negrita, cursiva, alineación)
-- **Lienzo** — snap-to-grid (5 px), rulers, selección múltiple, arrastrar/redimensionar
-- **Panel de propiedades** — secciones: apariencia, datos, bordes, formato condicional
-- **Diccionario de datos** — campos del datasource con drag al lienzo
-- **Multilingüe** — español, inglés, portugués, cambiable desde la barra
-- **Import/Export** — definiciones JSON
-- **Deshacer/Rehacer** — Ctrl+Z / Ctrl+Y
-- **Clipboard** — copiar/pegar elementos entre bandas
+### Methods
 
-### Uso
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `exportPdf()` | `Promise<void>` | Export to PDF and download |
+| `exportPdfAsBlob()` | `Promise<Blob>` | Export to PDF as Blob (for ZIP, upload, etc.) |
+| `exportExcel()` | `Promise<void>` | Export to Excel and download |
+| `exportWord()` | `Promise<void>` | Export to Word and download |
+| `exportCsv()` | `Promise<void>` | Export to CSV and download |
+| `printReport()` | `void` | Print the report |
+| `updateData(data)` | `void` | Update data without re-rendering definition |
 
-```vue
-<script setup lang="ts">
-import { NexaDesigner } from 'nexabase-report';
-import 'nexabase-report/style.css';
-import { ref } from 'vue';
+### Events
 
-const designerRef = ref(null);
-const locale = ref('es');
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `data-request` | `{ alias: string }` | Request data for a datasource |
+| `drill-click` | `{ element, sourceData, targetReportId, parameters }` | Drill-down element clicked |
+| `subreport-toggle` | `{ subReportId, collapsed }` | Subreport expanded/collapsed |
+| `page-change` | `{ page: number }` | Page changed |
 
-function onSave(reportDef: any) {
-  console.log('Reporte guardado:', reportDef);
-}
-</script>
+## Batch Export (ZIP)
 
-<template>
-  <NexaDesigner ref="designerRef" :locale="locale" @save="onSave" style="height: 100vh" />
-</template>
-```
+Export multiple reports to a single ZIP file without showing the viewer:
 
-### Props
+```javascript
+import { registerNexaReport } from 'nexabase-report';
+import JSZip from 'jszip';
 
-| Prop | Tipo | Default | Descripción |
-|------|------|---------|-------------|
-| `locale` | `'es' \| 'en' \| 'pt'` | `'es'` | Idioma del diseñador |
-| `initialReport` | `NexaReportDefinition` | — | Reporte a editar (nuevo si no se pasa) |
+registerNexaReport();
 
-### Eventos
+async function exportBatch(reportDef, invoices) {
+    // Create hidden viewer
+    const viewer = document.createElement('nexa-viewer');
+    viewer.style.display = 'none';
+    viewer.minimal = true;
+    viewer.definition = reportDef;
+    document.body.appendChild(viewer);
 
-| Evento | Payload | Descripción |
-|--------|---------|-------------|
-| `save` | `NexaReportDefinition` | Usuario presionó guardar |
+    await customElements.whenDefined('nexa-viewer');
+    await new Promise(r => setTimeout(r, 300));
 
----
+    const zip = new JSZip();
 
-## Visor (`<nexa-viewer>`)
+    for (const invoice of invoices) {
+        viewer.updateData(invoice.items);
+        await new Promise(r => setTimeout(r, 500));
+        const blob = await viewer.exportPdfAsBlob();
+        zip.file(invoice.name + '.pdf', blob);
+    }
 
-El visor se registra como Custom Element y funciona sin Vue en el proyecto consumidor.
+    const zipBlob = await zip.generateAsync({ type: 'blob' });
 
-### Formas de uso
+    // Download
+    const url = URL.createObjectURL(zipBlob);
+    const a = document.createElement('a');
+    a.href = url;
+    a.download = 'invoices.zip';
+    a.click();
+    URL.revokeObjectURL(url);
 
-```html
-<nexa-viewer
-  minimal
-  showToolbar
-  showThumbs
-  locale="es"
-  currentPage="1"
-  skipParamsDialog
-></nexa-viewer>
+    // Cleanup
+    document.body.removeChild(viewer);
+}
 ```
 
-Como Vue SFC directamente:
+## Designer
+
+The designer is a Vue 3 component for building reports visually:
 
 ```vue
-<script setup lang="ts">
-import { NexaViewerElement, registerNexaReport } from 'nexabase-report';
+<script setup>
+import NexaDesigner from 'nexabase-report/src/lib/designer/NexaDesigner.vue';
 import 'nexabase-report/style.css';
-
-registerNexaReport();
 </script>
 
 <template>
-  <nexa-viewer
-    :definition="reportDef"
-    :data="reportData"
-    :parameters="params"
-    locale="es"
-    @page-change="onPageChange"
-    @drill-click="onDrillClick"
-  />
+  <NexaDesigner :report="reportDefinition" @save="handleSave" />
 </template>
 ```
 
-### Props
-
-| Prop | Tipo | Default | Descripción |
-|------|------|---------|-------------|
-| `definition` | `string \| NexaReportDefinition` | — | Definición del reporte (objeto o JSON string) |
-| `data` | `string \| any[] \| Record<string, any[]>` | — | Datos: array simple (alias "main"), objeto multi-alias, o JSON string |
-| `parameters` | `Record<string, any>` | — | Valores iniciales de parámetros |
-| `minimal` | `boolean` | `false` | Oculta toolbar y thumbnails |
-| `showToolbar` | `boolean` | `true` | Forzar toolbar visible (útil en minimal) |
-| `showThumbs` | `boolean` | `true` | Forzar miniaturas visibles (útil en minimal) |
-| `skipParamsDialog` | `boolean` | `false` | Salta el diálogo de parámetros al cargar |
-| `currentPage` | `number` | `1` | Página inicial (soporta v-model) |
-| `locale` | `string` | `'es'` | Idioma: `'es'`, `'en'`, `'pt'` |
-| `apiBaseUrl` | `string` | — | URL base para subreportes/drill-down remotos |
-| `apiKey` | `string` | — | API Key para requests al backend |
-
-### Métodos (acceso vía ref o DOM)
-
-```ts
-const v = document.querySelector('nexa-viewer');
-
-// Exportación
-await v.exportPdf();               // pdf (html2pdf.js — fallback jsPDF vectorial)
-await v.exportPdfWithBookmarks();  // pdf con marcadores
-await v.exportExcel();             // .xlsx (SheetJS)
-await v.exportWord();              // .docx
-await v.exportCsv();               // .csv con UTF-8 BOM
-
-// Navegación
-v.goToPage(5);
-
-// Datos
-v.updateData(nuevosDatos);
-
-// Parámetros
-v.applyParams();
-v.applyParamsWithValidation();
-v.validateParams();          // retorna errores
-
-// Utilidad
-v.getDictionaryFields();     // retorna campos disponibles
-
-// Propiedades de lectura
-v.pageNumber;                // número actual
-v.totalPages;                // total de páginas
-v.paramValues;               // valores actuales de parámetros
-v.showParamsDialog;          // estado del diálogo
-v.paramValidationErrors;     // errores de validación
-```
-
-### Eventos
-
-```ts
-v.addEventListener('page-change',     e => console.log(e.detail.page));
-v.addEventListener('drill-click',     e => console.log(e.detail));
-v.addEventListener('subreport-toggle', e => console.log(e.detail));
-v.addEventListener('data-request',    e => console.log(e.detail.alias));
-```
-
----
-
-## Arquitectura del visor
+## Report Model
 
-### Template
+Reports use a banded structure:
 
+```json
+{
+  "metadata": { "name": "Sales Report", "version": "1.0" },
+  "layout": {
+    "page": { "format": "A4", "orientation": "portrait", "margins": { "top": 2, "right": 2, "bottom": 2, "left": 2 } },
+    "bands": [
+      { "id": "header", "type": "ReportHeader", "height": 60, "elements": [...] },
+      { "id": "data", "type": "DataBand", "height": 30, "dataSource": "main", "elements": [...] },
+      { "id": "footer", "type": "PageFooter", "height": 30, "elements": [...] }
+    ]
+  },
+  "dataSources": [{ "id": "ds1", "alias": "main", "collection": "sales" }]
+}
 ```
-<nexa-viewer>
-├── Toolbar (condicional)
-│   ├── Exportación: PDF, Excel, Word, CSV, imprimir
-│   ├── Zoom:       −, %, +, fitToWidth, fitToPage
-│   └── Paginación: ◀, input/total, ▶, búsqueda, info
-│
-├── Sidebar (condicional, 220px)
-│   ├── Pestaña Pages — miniaturas vía html2canvas
-│   ├── Pestaña TOC   — tabla de contenidos con navegación
-│   └── Pestaña Params — formulario de parámetros (text, number, date, boolean, select)
-│
-├── Viewport (scrollable)
-│   └── Pages root (transform: scale(Z%) )
-│       ├── Dashboard: grilla de DashboardWidgetRenderer
-│       └── Reporte: v-for pages
-│           └── report-page (sombra, fondo blanco)
-│               ├── Watermark (tile o single posicionado)
-│               ├── TOC page (si página 1 y generateTOC)
-│               └── Bands
-│                   ├── DataBand tabular → Table, Chart, Crosstab, SubReport
-│                   └── DataBand iterativa → Text, Image, Barcode, QR, Shape, DrillDown
-│
-├── Modal DrillDown (reporte anidado vía API)
-└── Modal About
-```
-
-### PaginationEngine
-
-El motor de paginación es una clase (`src/lib/viewer/services/PaginationEngine.ts`) que opera en **dos fases**:
 
-**Fase 1 — generateStream()**: Generator que produce un stream de `PageBandDef`:
-1. Emite `ReportHeader` primero
-2. Bandas estáticas (ni DataBand ni DetailBand)
-3. Para cada `DataBand`:
-   - **Tabular** (Table, Chart, Crosstab, SubReport): emite la banda completa con todas las filas en `rows`
-   - **Iterativa** (una instancia por fila): emite una banda por fila, intercalando GroupHeader/GroupFooter según agrupación y procesando DetailBand hijos (master-detail)
-4. Emite `ReportFooter` al final
+### Band Types
 
-**Fase 2 — generatePages()**: Algoritmo de particionado:
-- Calcula altura disponible: `pageHeight - pageHeader - pageFooter`
-- Itera el stream, acumulando bandas
-- Si una banda **tabular** no cabe:
-  - **Tabla**: calcula filas que entran (`(h disponible - h header) / h fila`), corta en chunks, coloca cada chunk en página nueva
-  - **Tabla agrupada**: corta por grupos completos (respeta `tableShowGroupHeader`/`tableShowGroupFooter`)
-  - Charts/Crosstabs: saltan a página nueva enteros
-- Respeta `pageBreakBefore` / `pageBreakAfter`
-- Asigna coordenadas Y absolutas para posicionamiento CSS
-- Cada ~10 páginas cede el hilo (`setTimeout`) para no bloquear en datasets grandes
+| Type | Description |
+|------|-------------|
+| `ReportHeader` | Renders once, on the first page |
+| `PageHeader` | Renders at the top of every page |
+| `DataBand` | Iterates over datasource records |
+| `GroupHeader` / `GroupFooter` | Renders when group key changes |
+| `PageFooter` | Renders at the bottom of every page |
+| `ReportFooter` | Renders once, on the last page |
 
-Métodos estáticos auxiliares: `applyFilters`, `applySort`, `applyJoins`, `matchesFilterValue` (soporta eq, ne, gt, gte, lt, lte, contains, starts_with, ends_with, is_null, is_not_null, between, regex).
+### Element Types
 
-### Renderers
+`Text`, `Image`, `Barcode`, `QRCode`, `Rectangle`, `Ellipse`, `Line`, `Arrow`, `Table`, `Chart`, `Crosstab`, `SubReport`, `DrillDown`
 
-| Renderer | Archivo | Descripción |
-|----------|---------|-------------|
-| TextRenderer | `viewer/renderers/TextRenderer.vue` | Texto plano con soporte de highlight de búsqueda |
-| ImageRenderer | `viewer/renderers/ImageRenderer.vue` | `<img>` con resolución de binding/URL |
-| BarcodeRenderer | `viewer/renderers/BarcodeRenderer.vue` | SVG vía jsbarcode (CODE128 default) |
-| QRCodeRenderer | `viewer/renderers/QRCodeRenderer.vue` | QR vía librería qrcode |
-| ShapeRenderer | `viewer/renderers/ShapeRenderer.vue` | Rectángulo, elipse, línea, flecha (CSS inline) |
-| DrillDownRenderer | `viewer/renderers/DrillDownRenderer.vue` | Elemento clickeable que emite `drill-click` |
-| FallbackRenderer | `viewer/renderers/FallbackRenderer.vue` | Muestra tipo no soportado |
-| SubreportRenderer | `viewer/renderers/SubreportRenderer.vue` | `<nexa-viewer>` anidado (embebido o remoto) |
-| ChartRenderer | `viewer/ChartRenderer.vue` | ECharts (barras, líneas, pastel, etc.) |
-| CrosstabRenderer | `viewer/CrosstabRenderer.vue` | Tabla dinámica con agrupación fila/columna |
-| DashboardWidgetRenderer | `viewer/DashboardWidgetRenderer.vue` | Widgets en modo dashboard |
+## Expression Engine
 
-Total: **11 renderers** (8 en `viewer/renderers/` + 3 en `viewer/`).
+Safe evaluation without `eval`. Supports:
 
-### Zoom (`useZoom`)
+- **Bindings:** `{{field}}` — resolves from data row
+- **Expressions:** `{[expr]}` — evaluated with context
+- **System variables:** `{[Page]}`, `{[TotalPages]}`, `{[Today]}`, `{[RowNumber]}`, `{[TotalRows]}`, `{[EvenRow]}`, `{[OddRow]}`
+- **Functions:** `FormatNumber`, `FormatDate`, `FormatCurrency`, `IIF`, `ISNULL`, `UPPER`, `LOWER`, `SUBSTRING`, `ABS`, `CEIL`, `FLOOR`, `ROUND`, `LEN`, `TRIM`, `CONCAT`
 
-- Rango: 25%–250%, default 100%
-- `zoomIn()` / `zoomOut()` — ±10 puntos
-- `fitToWidth()` — escala al ancho del viewport
-- `fitToPage()` — escala al alto y ancho
-- Modos: `continuous` (scroll vertical) / `single` (página por página)
-- Atajo: Ctrl+`+`, Ctrl+`-`, Ctrl+`0`
+## Integration with NexaBase
 
-### Búsqueda (`useSearch`)
+Works out of the box with [NexaBase](https://nexabase.dev) backend:
 
-- `searchQuery` con debounce de 200ms
-- Escanea hasta 250 páginas, case-insensitive, máx 500 resultados
-- Navegación: `nextMatch()` / `prevMatch()` con scroll automático
-- Highlight: `getHighlightParts(text)` retorna segmentos marcados/no marcados
-- Input de búsqueda en toolbar con atajo de teclado
+```javascript
+import { nexaService } from 'nexabase-report';
 
-### Watermarks
+// Connect
+nexaService.connect('https://your-nexabase.url', 'your-api-key');
 
-- **Tile**: texto repetido en grilla (20 spans CSS grid), opacidad configurable, rotado
-- **Single**: posicionado absoluto (center, top-left, top-right, bottom-left, bottom-right, top-center, bottom-center)
-- Opacidad, color, tamaño, rotación por configuración
-
-### TOC (Tabla de Contenidos)
-
-- Generación automática si `generateTOC: true` en la definición
-- Se Renderiza en página 1
-- Cada ítem: texto + dots + número de página
-- Navegación: click → `goToPage(n)` con scroll
-
-### Dashboard
-
-Si `documentType === 'Dashboard'`, el reporte se Renderiza como grilla de widgets (`DashboardWidgetRenderer`) en lugar de páginas con bandas.
-
----
-
-## Formato de datos
-
-### Array simple
-
-```json
-[
-  { "id": 1, "nombre": "Juan Pérez", "total": 150000 },
-  { "id": 2, "nombre": "María López", "total": 230000 }
-]
+// Fetch data and render
+const data = await nexaService.listDocuments('sales');
+viewer.data = data;
 ```
 
-El DataSource se asocia automáticamente al alias `"main"`.
+## Examples
 
-### Múltiples DataSources
+See `examples/` directory in the repository for working samples:
+- `integration-vue.html` — Vue 3 + UMD build
+- `integration-react.html` — React + UMD build
+- `integration-plain.html` — Plain HTML + UMD build
 
-```json
-{
-  "clientes": [
-    { "id": 1, "nombre": "Juan", "ciudad": "Bogotá" }
-  ],
-  "pedidos": [
-    { "cliente_id": 1, "producto": "Camisa", "cantidad": 3 }
-  ]
-}
-```
+## Development
 
-Cada banda referencia su DataSource por alias: `dataSource: "clientes"`.
-
-### Parámetros
-
-```ts
-viewer.parameters = {
-  fechaInicio: '2024-01-01',
-  fechaFin: '2024-12-31',
-  categoria: 'Electronics'
-};
+```bash
+pnpm install
+pnpm run dev          # Start dev server
+pnpm run build        # Build library
+pnpm run test         # Run tests (199 tests)
+pnpm run test:watch   # Watch mode
 ```
 
----
-
-## Variables y expresiones
-
-### Variables de sistema
-
-| Variable | Descripción | Ejemplo |
-|----------|-------------|---------|
-| `{{Page}}` | Página actual | `1` |
-| `{{TotalPages}}` | Total de páginas | `5` |
-| `{{Today}}` | Fecha actual (YYYY-MM-DD) | `2026-05-13` |
-| `{{Now}}` | Fecha y hora actual | `2026-05-13 14:30:00` |
-| `{{Year}}` | Año actual | `2026` |
-| `{{Month}}` | Mes actual | `5` |
-| `{{Day}}` | Día actual | `13` |
-| `{{ReportName}}` | Nombre del reporte | `Ventas Mensuales` |
-| `{{RowNumber}}` | Número de fila (1-based) | `1` |
-| `{{TotalRows}}` | Total de filas | `50` |
-| `{{EvenRow}}` / `{{OddRow}}` | Fila par / impar | `true` / `false` |
-| `{{FirstRow}}` / `{{LastRow}}` | Primera / última fila | `true` |
-| `{{GroupKey}}` | Clave del grupo actual | `Electronics` |
-| `{{GroupCount}}` | Registros en el grupo actual | `12` |
-
-### Expresiones `{[...]}`
-
-| Expresión | Resultado |
-|-----------|-----------|
-| `{[FormatNumber(precio, 'es-ES')]}` | `1.234,56` |
-| `{[FormatDate(fecha, 'dd/MM/yyyy')]}` | `15/01/2024` |
-| `{[FormatCurrency(total, 'USD')]}` | `$1,234.56` |
-| `{[IIF(total > 100000, 'ALTO', 'BAJO')]}` | `ALTO` |
-| `{[ISNULL(cliente, 'Sin nombre')]}` | `Sin nombre` |
-| `{[UPPER(nombre)]}` | `JUAN PÉREZ` |
-| `{[LOWER(nombre)]}` | `juan pérez` |
-| `{[SUBSTRING(texto, 0, 3)]}` | `Hel` |
-| `{[LENGTH(nombre)]}` | `10` |
-| `{[TRIM(texto)]}` | sin espacios |
-| `{[ABS(-5)]}` | `5` |
-| `{[CEIL(5.3)]}` | `6` |
-| `{[FLOOR(5.9)]}` | `5` |
-| `{[SUM(cantidad)]}` | suma |
-| `{[COUNT(id)]}` | conteo |
-| `{[AVG(precio)]}` | promedio |
-| `{[MIN(precio)]}` | mínimo |
-| `{[MAX(precio)]}` | máximo |
-| `{[CONCAT(nombre, ' - ', ciudad)]}` | `Juan - Bogotá` |
-| `{[REPLACE(texto, 'a', 'o')]}` | reemplazo |
-
----
-
-## Ejemplos
-
-Los reportes de ejemplo están en `examples/` y son compatibles con diseñador y visor.
-
-| Archivo | Descripción |
-|---------|-------------|
-| `report-factura.json` | Factura con ítems, cliente y totales |
-| `factura_de_recolección_de_residuos.json` | Factura ambiental multi-DataSource |
-| `report-factura-residuos.json` | Factura de residuos con GroupHeader/Footer |
-| `report-anexo-factura.json` | Anexo con tabla expandida |
-| `report-ventas-logo-tabla.json` | Corporativo con logo y tabla agrupada |
-| `report-agrupado-por-cliente.json` | GroupHeader + agrupación por cliente |
-| `report-productos.json` | Lista simple de productos |
-| `report-crosstab-categoria-mes.json` | Crosstab categoría × mes |
-| `report-grafico-ventas-por-mes.json` | Gráfico de barras ECharts |
-| `report-master-detail-ordenes.json` | Master-Detail con subreportes |
-| `report-codigos-qr-barcode.json` | Códigos QR y barras |
-
----
-
-## Publicación
+## Publishing
 
 ```bash
-pnpm run build
-pnpm version patch|minor|major
+pnpm run release:minor   # Bump minor version
 pnpm publish --access public
 ```
 
-CDN automático:
-
-```html
-<script src="https://cdn.jsdelivr.net/npm/nexabase-report/dist/nexabase-report.umd.js"></script>
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/nexabase-report/dist/style.css">
-```
-
-Ver [`docs/PUBLISHING.md`](docs/PUBLISHING.md) para CI/CD y registro privado.
-
----
-
-## Documentación adicional
-
-- [API completa del Viewer](docs/VIEWER_API.md) — props, métodos, eventos, tipos
-- [API REST](docs/API_REST.md) — endpoints serverless
-- [Integración externa](docs/EXTERNAL_INTEGRATION.md) — ASP.NET, Django, Laravel, Rails
-- [Plan de QA](docs/QA_PLAN.md) — checklist de pruebas manuales
-- [Checklist de regresión exportación](docs/EXPORT_REGRESSION.md) — PDF, Excel, Word, CSV
-- [Guía de publicación npm](docs/PUBLISHING.md) — build, versionado, CI/CD
-
----
-
-## Licencia
+## License
 
 MIT © NexaBase Team