nexabase-report 0.2.13 → 0.3.0

package/README.md

@@ -2,24 +2,10 @@
 
 [![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.0-blue)](https://www.typescriptlang.org/)
+[![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**, **visor framework-agnostic** como Custom Element, y **exportación 100% cliente** a PDF, Excel, Word y CSV.
-
----
-
-## Tabla de contenidos
-
-- [Características](#características)
-- [Instalación](#instalación)
-- [Uso rápido](#uso-rápido)
-- [Diseñador vs Viewer](#diseñador-vs-viewer)
-- [API del Viewer](#api-del-viewer)
-- [Formato de datos](#formato-de-datos)
-- [Variables y expresiones](#variables-y-expresiones)
-- [Ejemplos de integración](#ejemplos-de-integración)
-- [Documentación adicional](#documentación-adicional)
+> 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.
 
 ---
 
@@ -28,17 +14,27 @@
 | Característica | Descripción |
 |----------------|-------------|
 | **Custom Element** | `<nexa-viewer>` funciona en Vue, React, Angular, Svelte, Blazor o HTML puro |
-| **Diseñador WYSIWYG** | `NexaDesigner.vue` — arrastra/suelta bandas, textos, tablas, imágenes, gráficos |
-| **Visor standalone** | `<nexa-viewer>` — no requiere Vue en el proyecto consumidor |
-| **Exportación cliente** | PDF vectorial (jsPDF), Excel (SheetJS), Word (docx), CSV |
-| **Gráficos** | ECharts integrado (barras, líneas, pastel, area, scatter) |
-| **Tablas dinámicas** | Crosstabs nativos con agregaciones |
-| **Códigos QR / Barras** | jsbarcode + qrcode |
-| **Formato condicional** | Reglas visuales por campo y operador |
-| **Master-Detail** | Subreportes anidados con datos relacionados |
-| **Motor de expresiones** | Seguro (sin `eval`): `FormatNumber`, `FormatDate`, `IIF`, `ISNULL`, `sum`, `count`, etc. |
-| **Parámetros** | Dilogo de entrada, valores por props, skipParamsDialog |
-| **Paginación** | Automática por altura de página, thumbnails, navegación |
+| **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 |
 
 ---
 
@@ -48,7 +44,7 @@
 npm install nexabase-report
 ```
 
-Importar estilos **una sola vez** al inicio de la app:
+Importar estilos una sola vez al inicio:
 
 ```ts
 import 'nexabase-report/style.css';
@@ -64,18 +60,18 @@ import 'nexabase-report/style.css';
 <!DOCTYPE html>
 <html>
 <head>
-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/nexabase-report/dist/style.css">
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/nexabase-report@0.2/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="https://cdn.jsdelivr.net/npm/nexabase-report@0.2/dist/nexabase-report.umd.js"></script>
   <script>
     NexaReport.registerNexaReport();
 
     const viewer = document.getElementById('viewer');
-    viewer.definition = { /* tu definición de reporte */ };
-    viewer.data = [ /* array de datos */ ];
+    viewer.definition = { /* definición del reporte */ };
+    viewer.data = [ /* datos */ ];
   </script>
 </body>
 </html>
@@ -90,8 +86,8 @@ import 'nexabase-report/style.css';
 
 registerNexaReport();
 
-export function ReportViewer({ definition, data }) {
-  const ref = useRef<HTMLElement>(null);
+export function ReportViewer({ definition, data }: { definition: any; data: any[] }) {
+  const ref = useRef<any>(null);
 
   useEffect(() => {
     if (!ref.current) return;
@@ -106,16 +102,11 @@ export function ReportViewer({ definition, data }) {
 ### Vue 3
 
 ```vue
-<script setup>
+<script setup lang="ts">
 import { registerNexaReport } from 'nexabase-report';
 import 'nexabase-report/style.css';
 
 registerNexaReport();
-
-const props = defineProps<{
-  definition: object;
-  data: any[];
-}>();
 </script>
 
 <template>
@@ -136,158 +127,321 @@ import 'nexabase-report/style.css';
 
 registerNexaReport();
 
-// En tu componente
 @Component({
   template: '<nexa-viewer #viewer [definition]="reportDef" [data]="reportData"></nexa-viewer>',
 })
 export class ReportComponent {
   @ViewChild('viewer') viewerRef!: ElementRef;
-
-  reportDef = null;
+  reportDef: any = null;
   reportData: any[] = [];
 
   async ngOnInit() {
-    const res = await fetch('/assets/report.json');
-    this.reportDef = await res.json();
+    this.reportDef = await fetch('/assets/report.json').then(r => r.json());
     this.reportData = await fetch('/api/data').then(r => r.json());
   }
 }
 ```
 
-### Blazor Razor (.NET 8)
+### Blazor (.NET 8+)
 
 ```razor
 @page "/reporte/{Id:int}"
-@inject HttpClient Http
 @inject IJSRuntime JS
 
 <link rel="stylesheet" href="_content/nexabase-report/style.css" />
 <script src="_content/nexabase-report/nexabase-report.umd.js"></script>
 
-<div style="height:700px">
-    <nexa-viewer id="viewer" minimal></nexa-viewer>
-</div>
+<nexa-viewer id="viewer" minimal></nexa-viewer>
 
 @code {
     [Parameter] public int Id { get; set; }
 
-    protected override async Task OnInitializedAsync()
+    protected override async Task OnAfterRenderAsync(bool firstRender)
     {
-        var definition = await Http.GetFromJsonAsync<dynamic>($"/api/reportes/{Id}");
-        var data = await Http.GetFromJsonAsync<List<dynamic>>($"/api/reportes/{Id}/datos");
-
-        await JS.InvokeVoidAsync("renderNexaReport", definition, data);
+        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);
     }
 }
 
-@section Scripts {
-    <script>
-        function renderNexaReport(definition, data) {
-            if (!window.nexaRegistered) {
-                NexaReport.registerNexaReport();
-                window.nexaRegistered = true;
-            }
-            const v = document.getElementById('viewer');
-            v.definition = definition;
-            v.data = data;
+<script>
+    window.renderNexaReport = function(definition, data) {
+        if (!window.__nexaRegistered) {
+            NexaReport.registerNexaReport();
+            window.__nexaRegistered = true;
         }
-    </script>
-}
+        const v = document.getElementById('viewer');
+        v.definition = definition;
+        v.data = data;
+    };
+</script>
 ```
 
-O si prefieres usar un componente wrapper en Razor:
+---
 
-```razor
-@* Shared/ReportViewer.razor *@
-@inject IJSRuntime JS
+## Diseñador (NexaDesigner)
 
-<div style="height: @Height">
-    <nexa-viewer @ref="viewerRef" id="@Id" minimal></nexa-viewer>
-</div>
+Diseñador WYSIWYG como componente Vue 3:
 
-@code {
-    [Parameter] public string Id { get; set; } = "viewer";
-    [Parameter] public string Height { get; set; } = "700px";
-    [Parameter] public object Definition { get; set; }
-    [Parameter] public object Data { get; set; }
+- **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
 
-    private ElementReference viewerRef;
+### Uso
 
-    protected override async Task OnAfterRenderAsync(bool firstRender)
-    {
-        if (firstRender)
-        {
-            await JS.InvokeVoidAsync("nexaReportInterop.init", viewerRef, Definition, Data);
-        }
-    }
+```vue
+<script setup lang="ts">
+import { NexaDesigner } from 'nexabase-report';
+import 'nexabase-report/style.css';
+import { ref } from 'vue';
+
+const designerRef = ref(null);
+const locale = ref('es');
 
-    public async Task ExportPdf() => await JS.InvokeVoidAsync("nexaReportInterop.exportPdf", viewerRef);
-    public async Task ExportExcel() => await JS.InvokeVoidAsync("nexaReportInterop.exportExcel", viewerRef);
+function onSave(reportDef: any) {
+  console.log('Reporte guardado:', reportDef);
 }
+</script>
+
+<template>
+  <NexaDesigner ref="designerRef" :locale="locale" @save="onSave" style="height: 100vh" />
+</template>
 ```
 
----
+### Props
 
-## Diseñador vs Viewer
+| Prop | Tipo | Default | Descripción |
+|------|------|---------|-------------|
+| `locale` | `'es' \| 'en' \| 'pt'` | `'es'` | Idioma del diseñador |
+| `initialReport` | `NexaReportDefinition` | — | Reporte a editar (nuevo si no se pasa) |
 
-| Aspecto | NexaDesigner | NexaViewer |
-|---------|-------------|------------|
-| **Tag** | `<NexaReportDesigner>` | `<nexa-viewer>` |
-| **Framework** | Requiere Vue 3 | Framework-agnostic |
-| **Uso** | Crear/editar reportes | Solo visualización |
-| **Exportación** | No | Sí (PDF, Excel, Word, CSV) |
-| **Props data** | No | Sí |
+### Eventos
 
-**Flujo típico:**
-1. Diseñador crea → guarda JSON (definición del reporte)
-2. Viewer consume esa definición + datos del backend
-3. Usuario exporta / imprime desde el viewer
+| Evento | Payload | Descripción |
+|--------|---------|-------------|
+| `save` | `NexaReportDefinition` | Usuario presionó guardar |
 
 ---
 
-## API del Viewer
+## Visor (`<nexa-viewer>`)
+
+El visor se registra como Custom Element y funciona sin Vue en el proyecto consumidor.
+
+### Formas de uso
+
+```html
+<nexa-viewer
+  minimal
+  showToolbar
+  showThumbs
+  locale="es"
+  currentPage="1"
+  skipParamsDialog
+></nexa-viewer>
+```
+
+Como Vue SFC directamente:
+
+```vue
+<script setup lang="ts">
+import { NexaViewerElement, registerNexaReport } from 'nexabase-report';
+import 'nexabase-report/style.css';
+
+registerNexaReport();
+</script>
+
+<template>
+  <nexa-viewer
+    :definition="reportDef"
+    :data="reportData"
+    :parameters="params"
+    locale="es"
+    @page-change="onPageChange"
+    @drill-click="onDrillClick"
+  />
+</template>
+```
 
 ### Props
 
 | Prop | Tipo | Default | Descripción |
 |------|------|---------|-------------|
-| `definition` | `string \| object` | — | Definición del reporte (JSON) |
-| `data` | `string \| any[] \| object` | — | Datos: `[]` para single DS, `{alias: []}` para multi |
-| `parameters` | `object` | `{}` | Valores para parámetros del reporte |
+| `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` | Muestra/oculta barra superior |
-| `showThumbs` | `boolean` | `true` | Muestra panel de miniaturas |
-| `skipParamsDialog` | `boolean` | `false` | Salta el diálogo de parámetros |
-| `currentPage` | `number` | `1` | Página inicial |
-| `apiBaseUrl` | `string` | — | URL base de NexaBase |
-| `apiKey` | `string` | — | API key para NexaBase |
+| `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 (DOM)
+### Métodos (acceso vía ref o DOM)
 
 ```ts
 const v = document.querySelector('nexa-viewer');
 
-await v.exportPdf();               // PDF vectorial
-await v.exportPdfWithBookmarks();  // PDF con marcadores
+// 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 BOM UTF-8
-v.goToPage(3);                     // Navegar a página
-v.updateData(nuevosDatos);        // Actualizar datos
+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('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
+
+### Template
+
+```
+<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
+
+**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
+
+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).
+
+### Renderers
+
+| 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 |
+
+Total: **11 renderers** (8 en `viewer/renderers/` + 3 en `viewer/`).
+
+### Zoom (`useZoom`)
+
+- 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`
+
+### Búsqueda (`useSearch`)
+
+- `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
+
+### Watermarks
+
+- **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
 
-### Single DataSource (array simple)
+### Array simple
 
 ```json
 [
@@ -296,9 +450,9 @@ v.addEventListener('drill-click', e => console.log(e.detail));
 ]
 ```
 
-El reporte usa `dataSource: ""` (vacío) para tomar este array como `"main"`.
+El DataSource se asocia automáticamente al alias `"main"`.
 
-### Multiple DataSources (objeto con alias)
+### Múltiples DataSources
 
 ```json
 {
@@ -311,16 +465,15 @@ El reporte usa `dataSource: ""` (vacío) para tomar este array como `"main"`.
 }
 ```
 
-El reporte usa `dataSource: "clientes"` para referirse a ese alias.
+Cada banda referencia su DataSource por alias: `dataSource: "clientes"`.
 
-### Con parámetros
+### Parámetros
 
 ```ts
-// Pasando parameters al viewer
 viewer.parameters = {
   fechaInicio: '2024-01-01',
   fechaFin: '2024-12-31',
-  categoria: ' electronics'
+  categoria: 'Electronics'
 };
 ```
 
@@ -334,98 +487,96 @@ viewer.parameters = {
 |----------|-------------|---------|
 | `{{Page}}` | Página actual | `1` |
 | `{{TotalPages}}` | Total de páginas | `5` |
-| `{{Today}}` | Fecha actual (YYYY-MM-DD) | `2024-01-15` |
-| `{{Now}}` | Fecha y hora actual | `2024-01-15 14:30:00` |
-| `{{Year}}` | Año actual | `2024` |
-| `{{Month}}` | Mes actual | `1` |
-| `{{Day}}` | Día actual | `15` |
+| `{{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}}` | `true` si fila es par | `true` |
-| `{{OddRow}}` | `true` si fila es impar | `false` |
-| `{{FirstRow}}` / `{{LastRow}}` | Primera/última fila | `true` |
-| `{{GroupKey}}` | Clave de agrupación actual | `electronics` |
-| `{{GroupCount}}` | Conteo del grupo actual | `12` |
-
-### Expresiones con `{[...]}`
-
-```
-{[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
-{[SUBSTRING(texto, 0, 3)]}            → "Hel" (primeros 3)
-{[ABS(-5)]}                           → 5
-{[CEIL(5.3)]}                         → 6
-{[FLOOR(5.9)]}                        → 5
-```
-
-### Agregaciones en tablas
-
-En `footerText` de columnas:
-```
-Total: {[sum(cantidad)]}
-Cantidad: {[count(id)]}
-Promedio: {[avg(precio)]}
-Máximo: {[max(total)]}
-Mínimo: {[min(total)]}
-Primero: {[first(nombre)]}
-Último: {[last(apellido)]}
-```
-
-### Bindings mixtos (content + binding)
-
-```json
-{
-  "type": "Text",
-  "content": "Cliente: {{nombre}} ({{ciudad}})",
-  "binding": "nombre"
-}
-```
+| `{{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 de integración
+## Ejemplos
 
-Los ejemplos JSON en `examples/` son reportes completos que puedes cargar:
+Los reportes de ejemplo están en `examples/` y son compatibles con diseñador y visor.
 
 | Archivo | Descripción |
 |---------|-------------|
-| `report-factura.json` | Factura con tabla de items, cliente, totales |
-| `factura_de_recolección_de_residuos.json` | Factura ambiental con 3 DataSources relacionados |
-| `report-ventas-logo-tabla.json` | Reporte con logo, tabla agrupada, resumen |
-| `report-agrupado-por-cliente.json` | GroupHeader + Table con agrupació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` | Tabla dinámica (crosstab) |
-| `report-grafico-ventas-por-mes.json` | Gráfico de barras con datos mensuales |
-| `report-master-detail-ordenes.json` | Master-detail con subreportes |
+| `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 |
 
-### Cargar un ejemplo
+---
 
-```ts
-const res = await fetch('/examples/report-factura.json');
-const definition = await res.json();
-const data = [ /* tus datos */ ];
+## Publicación
 
-viewer.definition = definition;
-viewer.data = data;
+```bash
+npm run build
+npm version patch|minor|major
+npm publish --access public
+```
+
+CDN automático:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/nexabase-report@0.2/dist/nexabase-report.umd.js"></script>
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/nexabase-report@0.2/dist/style.css">
 ```
 
+Ver [`docs/PUBLISHING.md`](docs/PUBLISHING.md) para CI/CD y registro privado.
+
 ---
 
 ## Documentación adicional
 
-- [API del Viewer](docs/VIEWER_API.md) — Métodos, eventos, props detallados
-- [Integración con sistemas externos](docs/EXTERNAL_INTEGRATION.md) — ASP.NET, Django, Rails, etc.
-- [Guía de publicación npm](docs/PUBLISHING.md) — CI/CD, versiones, npmjs
-- [Plan de QA](docs/QA_PLAN.md) — Checklist de pruebas manuales
+- [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
 
-MIT © NexaBase Team
+MIT © NexaBase Team