nexabase-report 0.1.1 → 0.1.2

package/README.md

@@ -1,6 +1,48 @@
-# NexaBase Report (Designer + Viewer)
-
-Librería para diseñar y visualizar reportes tipo banded (inspirada en Stimulsoft) con exportación a PDF/Excel/Word.
+# 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)
+
+> 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)
+  - [React](#react)
+  - [Vue 3](#vue-3)
+  - [Angular](#angular)
+  - [HTML puro (CDN)](#html-puro-cdn)
+- [API del Viewer](#api-del-viewer)
+  - [Props](#props)
+  - [Métodos](#métodos)
+  - [Eventos](#eventos)
+- [Formato de datos](#formato-de-datos)
+- [Variables de sistema](#variables-de-sistema)
+- [Funciones de expresiones](#funciones-de-expresiones)
+- [Exportación programática](#exportación-programática)
+- [Solución de problemas](#solución-de-problemas)
+- [Documentación adicional](#documentación-adicional)
+
+---
+
+## Características
+
+| Característica | Descripción |
+|----------------|-------------|
+| **Custom Element** | `<nexa-viewer>` funciona en Vue, React, Angular, Svelte o HTML puro |
+| **Diseñador WYSIWYG** | Arrastra y suelta bandas, textos, tablas, imágenes, gráficos |
+| **Exportación cliente** | PDF (vectorial con jsPDF), Excel (SheetJS), Word (docx), CSV |
+| **Gráficos** | ECharts integrado (barras, líneas, pastel, etc.) |
+| **Tablas dinámicas** | Crosstabs (pivot tables) nativos |
+| **Códigos QR / Barras** | jsbarcode + qrcode |
+| **Formato condicional** | Reglas visuales por campo y valor |
+| **Master-Detail** | Subreportes anidados |
+| **Motor de expresiones** | Seguro (sin `eval`): `FormatNumber`, `IIF`, `ISNULL`, etc. |
+| **Sin backend requerido** | Los datos se pasan directamente por props |
+
+---
 
 ## Instalación
 
@@ -8,55 +50,17 @@ Librería para diseñar y visualizar reportes tipo banded (inspirada en Stimulso
 npm install nexabase-report
 ```
 
-## Uso rápido: Viewer (apps externas)
-
-El Viewer se expone como Custom Element: `<nexa-viewer />`.
-
-## Flujo real (NexaBase): cargar JSON exportado + pasar data
-
-1. Exporta el reporte desde NexaBase y guarda el JSON en tu app (por ejemplo en `public/report.json`).
-2. Carga ese JSON por `fetch()` y asígnalo a `definition`.
-3. Pasa tus datos del sistema en `data`.
-
-### 1) Vue 3
+También necesitarás importar los estilos globales **una vez** en tu app:
 
 ```ts
-import { registerNexaReport } from 'nexabase-report';
 import 'nexabase-report/style.css';
-
-registerNexaReport();
 ```
 
-```vue
-<script setup lang="ts">
-import { onMounted, ref } from 'vue';
+---
 
-const definition = ref<any>(null);
-const data = ref<any[]>([]);
+## Uso rápido
 
-onMounted(async () => {
-  const res = await fetch('/report.json');
-  definition.value = await res.json();
-
-  data.value = [
-    { nombre: 'Producto A', precio: 100, cantidad: 2 },
-    { nombre: 'Producto B', precio: 50, cantidad: 5 },
-  ];
-});
-</script>
-
-<template>
-  <nexa-viewer
-    :definition="definition"
-    :data="data"
-    :parameters="{ fechaDesde: '2026-01-01' }"
-    minimal
-    skip-params-dialog
-  />
-</template>
-```
-
-### 2) React
+### React
 
 ```tsx
 import { useEffect, useRef, useState } from 'react';
@@ -66,18 +70,17 @@ import 'nexabase-report/style.css';
 registerNexaReport();
 
 export function ReportViewer() {
-  const ref = useRef<any>(null);
+  const ref = useRef<HTMLElement>(null);
   const [definition, setDefinition] = useState<any>(null);
   const [data, setData] = useState<any[]>([]);
-  const [parameters] = useState<any>({ fechaDesde: '2026-01-01' });
 
   useEffect(() => {
     (async () => {
       const res = await fetch('/report.json');
       setDefinition(await res.json());
       setData([
-        { nombre: 'Producto A', precio: 100, cantidad: 2 },
-        { nombre: 'Producto B', precio: 50, cantidad: 5 },
+        { nombre: 'Producto A', precio: 100 },
+        { nombre: 'Producto B', precio: 50 },
       ]);
     })();
   }, []);
@@ -86,87 +89,242 @@ export function ReportViewer() {
     if (!ref.current) return;
     ref.current.definition = definition;
     ref.current.data = data;
-    ref.current.parameters = parameters;
-  }, [definition, data, parameters]);
+  }, [definition, data]);
 
   return <nexa-viewer ref={ref} minimal />;
 }
 ```
 
-### 3) Angular
+### Vue 3
+
+```vue
+<script setup lang="ts">
+import { ref, watch } from 'vue';
+import { registerNexaReport } from 'nexabase-report';
+import 'nexabase-report/style.css';
+
+registerNexaReport();
 
-En Angular, pon el JSON exportado en `src/assets/report.json` y cárgalo con `HttpClient` o `fetch()`.
+const props = defineProps<{ definition: any; data: any[] }>();
+const viewerRef = ref<HTMLElement | null>(null);
+
+watch(
+  () => [props.definition, props.data],
+  () => {
+    const el = viewerRef.value as any;
+    if (!el) return;
+    el.definition = props.definition;
+    el.data = props.data;
+  },
+  { immediate: true }
+);
+</script>
+
+<template>
+  <nexa-viewer ref="viewerRef" minimal style="display:block;height:100%" />
+</template>
+```
+
+### Angular
 
 ```ts
-import { AfterViewInit, Component, ElementRef, ViewChild } from '@angular/core';
+import { Component, ElementRef, ViewChild, AfterViewInit } from '@angular/core';
+import { registerNexaReport } from 'nexabase-report';
+import 'nexabase-report/style.css';
+
+registerNexaReport();
 
 @Component({
   selector: 'app-root',
-  template: '<nexa-viewer #viewer></nexa-viewer>',
+  template: '<nexa-viewer #viewer minimal></nexa-viewer>',
 })
 export class AppComponent implements AfterViewInit {
-  @ViewChild('viewer', { static: true }) viewerRef!: ElementRef<any>;
+  @ViewChild('viewer', { static: true }) viewerRef!: ElementRef<HTMLElement>;
 
   async ngAfterViewInit() {
-    const v = this.viewerRef.nativeElement;
+    const el = this.viewerRef.nativeElement as any;
     const res = await fetch('/assets/report.json');
-    v.definition = await res.json();
-    v.data = [
-      { nombre: 'Producto A', precio: 100, cantidad: 2 },
-      { nombre: 'Producto B', precio: 50, cantidad: 5 },
-    ];
-    v.minimal = true;
-    v.skipParamsDialog = true;
+    el.definition = await res.json();
+    el.data = [{ nombre: 'Producto A', precio: 100 }];
   }
 }
 ```
 
-### 3) HTML puro (CDN / UMD)
+### HTML puro (CDN)
 
 ```html
-<link rel="stylesheet" href="https://unpkg.com/nexabase-report@0.1.0/dist/style.css">
-<script src="https://unpkg.com/nexabase-report@0.1.0/dist/nexabase-report.umd.js"></script>
-<script>
-  window.NexaReport.registerNexaReport();
-</script>
+<!DOCTYPE html>
+<html>
+<head>
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/nexabase-report@latest/dist/style.css">
+</head>
+<body>
+  <nexa-viewer id="viewer" minimal></nexa-viewer>
+
+  <script src="https://cdn.jsdelivr.net/npm/nexabase-report@latest/dist/nexabase-report.umd.js"></script>
+  <script>
+    window.NexaReport.registerNexaReport();
+    const v = document.getElementById('viewer');
+    v.definition = { /* ... */ };
+    v.data = [ /* ... */ ];
+  </script>
+</body>
+</html>
+```
 
-<nexa-viewer id="viewer"></nexa-viewer>
-<script>
-  const v = document.getElementById('viewer');
-  v.definition = {/* ... */};
-  v.data = [{/* ... */}];
-</script>
+---
+
+## API del Viewer
+
+### Props
+
+| Prop | Tipo | Default | Descripción |
+|------|------|---------|-------------|
+| `definition` | `string \| object` | — | Definición del reporte (JSON o objeto) |
+| `data` | `string \| any[] \| Record<string, any[]>` | — | Datos del reporte |
+| `parameters` | `Record<string, any>` | `{}` | Valores de parámetros |
+| `minimal` | `boolean \| string` | `false` | Oculta la toolbar de exportación |
+| `skipParamsDialog` | `boolean` | `false` | Salta el diálogo de parámetros |
+| `showToolbar` | `boolean \| string` | `true` | Muestra/oculta toolbar |
+| `showThumbs` | `boolean \| string` | `true` | Muestra/oculta panel de miniaturas |
+| `currentPage` | `number` | `1` | Página actual (control externo) |
+
+### Métodos (vía ref DOM)
+
+```ts
+const viewer = document.querySelector('nexa-viewer');
+
+await viewer.exportPdf();
+await viewer.exportExcel();
+await viewer.exportWord();
+await viewer.exportCsv();
+
+viewer.goToPage(3);
+viewer.updateData({ main: [...] });
 ```
 
-## Probar sin publicar (recomendado)
+### Eventos
 
-Desde este repo:
+```ts
+viewer.addEventListener('page-change', (e) => console.log(e.detail));
+viewer.addEventListener('drill-click', (e) => console.log(e.detail));
+```
 
-```bash
-npm run build
-npm pack
+---
+
+## Formato de datos
+
+### Single DataSource (array simple)
+
+```json
+[
+  { "id": 1, "nombre": "Juan", "ventas": 1500 },
+  { "id": 2, "nombre": "María", "ventas": 2300 }
+]
 ```
 
-En el proyecto externo:
+### Multiple DataSources (objeto con alias)
 
-```bash
-npm install /ruta/al/nexabase-report-0.1.0.tgz
+```json
+{
+  "clientes": [
+    { "id": 1, "nombre": "Juan" }
+  ],
+  "pedidos": [
+    { "id": 101, "cliente_id": 1, "total": 500 }
+  ]
+}
 ```
 
-## Publicar en npm
+---
 
-Guía paso a paso: [docs/PUBLISHING.md](docs/PUBLISHING.md)
+## Variables de sistema
 
-Resumen:
+| Variable | Descripción | Ejemplo |
+|----------|-------------|---------|
+| `{{Page}}` | Página actual | `1` |
+| `{{TotalPages}}` | Total de páginas | `5` |
+| `{{Today}}` | Fecha actual | `2024-01-15` |
+| `{{Now}}` | Fecha y hora actual | `2024-01-15 14:30` |
+| `{{ReportName}}` | Nombre del reporte | `Ventas Mensuales` |
+| `{{RowNumber}}` | Número de fila | `1` |
+| `{{TotalRows}}` | Total de filas | `50` |
+| `{{EvenRow}}` / `{{OddRow}}` | Fila par/impar | `true` / `false` |
 
-```bash
-npm run build
-npm pack --dry-run
-npm version patch
-npm publish --access public
+---
+
+## Funciones de expresiones
+
+Usar sintaxis `{[...]}`:
+
+```
+{[FormatNumber(precio, 'es-ES')]}     → 1.234,56
+{[FormatDate(fecha, 'dd/MM/yyyy')]}   → 15/01/2024
+{[FormatCurrency(total, 'USD')]}      → $1,234.56
+{[IIF(total > 100, 'OK', 'Bajo')]}    → OK
+{[ISNULL(campo, 'Sin dato')]}         → Sin dato
+{[UPPER(nombre)]}                     → JUAN
+{[SUBSTRING(texto, 1, 3)]}            → pri
+{[ABS(-5)]}                           → 5
+{[CEIL(5.3)]}                         → 6
+{[FLOOR(5.9)]}                        → 5
 ```
 
-## Documentación
+---
+
+## Exportación programática
+
+```ts
+// React / Vue / Angular
+const viewer = viewerRef.current;
+await viewer.exportPdf();
+
+// HTML puro
+const viewer = document.getElementById('viewer');
+await viewer.exportPdf();
+```
+
+---
+
+## Solución de problemas
+
+### `<nexa-viewer>` no se renderiza
+
+Asegúrate de llamar `registerNexaReport()` **antes** de montar el componente, e importar `nexabase-report/style.css`.
+
+### TypeScript: `'nexa-viewer' is not a known element`
+
+En React/Vue/Angular, el custom element no está en el JSX/TSX estándar. Agrega declaraciones de tipo locales:
+
+```ts
+declare module 'nexabase-report' {
+  export function registerNexaReport(): void;
+}
+
+declare global {
+  namespace JSX {
+    interface IntrinsicElements {
+      'nexa-viewer': any;
+    }
+  }
+}
+```
+
+En Angular usa `CUSTOM_ELEMENTS_SCHEMA` en tu `@Component`.
+
+### Los datos no aparecen
+
+Verifica que `dataSource` en la definición del reporte coincida con el alias de tus datos. El primer datasource suele tener alias `"main"`.
+
+---
+
+## Documentación adicional
+
+- [API del Viewer](docs/VIEWER_API.md)
+- [Integración externa](docs/EXTERNAL_INTEGRATION.md)
+- [Plan de QA](docs/QA_PLAN.md)
+- [Guía de publicación](docs/PUBLISHING.md)
+
+## Licencia
 
-- API del Viewer: [docs/VIEWER_API.md](docs/VIEWER_API.md)
-- Integración externa: [docs/EXTERNAL_INTEGRATION.md](docs/EXTERNAL_INTEGRATION.md)
+MIT © NexaBase Team

package/dist/{html2canvas-MMn8dUQK.js → html2canvas-Bt7A8WrM.js}

@@ -1,4 +1,4 @@
-import { c as MQ } from "./index-j9lAJl17.js";
+import { c as MQ } from "./index-D3l3xYdG.js";
 var nt = { exports: {} };
 /*!
  * html2canvas 1.4.1 <https://html2canvas.hertzen.com>

package/dist/{html2canvas-Dmt1hL9C.js → html2canvas-ChtVTMFS.js}

@@ -1,5 +1,5 @@
-import { a as c } from "./index-j9lAJl17.js";
-import { r as f } from "./html2canvas-MMn8dUQK.js";
+import { a as c } from "./index-D3l3xYdG.js";
+import { r as f } from "./html2canvas-Bt7A8WrM.js";
 function l(r, n) {
   for (var o = 0; o < n.length; o++) {
     const e = n[o];

package/dist/{html2pdf-BumfBzwC.js → html2pdf-DsfBPN4L.js}

@@ -1,6 +1,6 @@
-import { g as De, a as Ke, c as Te } from "./index-j9lAJl17.js";
-import { j as Ge } from "./jspdf.es.min-DIevzj7_.js";
-import { r as Be } from "./html2canvas-MMn8dUQK.js";
+import { g as De, a as Ke, c as Te } from "./index-D3l3xYdG.js";
+import { j as Ge } from "./jspdf.es.min-M0h3R1kR.js";
+import { r as Be } from "./html2canvas-Bt7A8WrM.js";
 function Ue(ge, we) {
   for (var me = 0; me < we.length; me++) {
     const ce = we[me];