nexabase-report 0.1.0 → 0.1.2

package/README.md

@@ -1,6 +1,48 @@
-# NexaBase Report (Designer + Viewer)
+# nexabase-report
 
-Librería para diseñar y visualizar reportes tipo banded (inspirada en Stimulsoft) con exportación a PDF/Excel/Word.
+[![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,99 +50,281 @@ Librería para diseñar y visualizar reportes tipo banded (inspirada en Stimulso
 npm install nexabase-report
 ```
 
-## Uso rápido: Viewer (apps externas)
+También necesitarás importar los estilos globales **una vez** en tu app:
+
+```ts
+import 'nexabase-report/style.css';
+```
 
-El Viewer se expone como Custom Element: `<nexa-viewer />`.
+---
 
-### 1) Vue 3
+## Uso rápido
 
-```ts
+### React
+
+```tsx
+import { useEffect, useRef, useState } from 'react';
 import { registerNexaReport } from 'nexabase-report';
 import 'nexabase-report/style.css';
 
 registerNexaReport();
+
+export function ReportViewer() {
+  const ref = useRef<HTMLElement>(null);
+  const [definition, setDefinition] = useState<any>(null);
+  const [data, setData] = useState<any[]>([]);
+
+  useEffect(() => {
+    (async () => {
+      const res = await fetch('/report.json');
+      setDefinition(await res.json());
+      setData([
+        { nombre: 'Producto A', precio: 100 },
+        { nombre: 'Producto B', precio: 50 },
+      ]);
+    })();
+  }, []);
+
+  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">
+import { ref, watch } from 'vue';
+import { registerNexaReport } from 'nexabase-report';
+import 'nexabase-report/style.css';
+
+registerNexaReport();
+
+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
-    :definition="definition"
-    :data="data"
-    :parameters="{ fechaDesde: '2026-01-01' }"
-    minimal
-    skip-params-dialog
-  />
+  <nexa-viewer ref="viewerRef" minimal style="display:block;height:100%" />
 </template>
 ```
 
-### 2) React
+### Angular
 
-```tsx
-import { useEffect, useRef } from 'react';
+```ts
+import { Component, ElementRef, ViewChild, AfterViewInit } from '@angular/core';
 import { registerNexaReport } from 'nexabase-report';
 import 'nexabase-report/style.css';
 
 registerNexaReport();
 
-export function ReportViewer({ definition, data, parameters }: any) {
-  const ref = useRef<any>(null);
-  useEffect(() => {
-    if (!ref.current) return;
-    ref.current.definition = definition;
-    ref.current.data = data;
-    ref.current.parameters = parameters;
-  }, [definition, data, parameters]);
+@Component({
+  selector: 'app-root',
+  template: '<nexa-viewer #viewer minimal></nexa-viewer>',
+})
+export class AppComponent implements AfterViewInit {
+  @ViewChild('viewer', { static: true }) viewerRef!: ElementRef<HTMLElement>;
 
-  return <nexa-viewer ref={ref} minimal />;
+  async ngAfterViewInit() {
+    const el = this.viewerRef.nativeElement as any;
+    const res = await fetch('/assets/report.json');
+    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>
 
-<nexa-viewer id="viewer"></nexa-viewer>
-<script>
-  const v = document.getElementById('viewer');
-  v.definition = {/* ... */};
-  v.data = [{/* ... */}];
-</script>
+  <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>
 ```
 
-## Probar sin publicar (recomendado)
+---
 
-Desde este repo:
+## API del Viewer
 
-```bash
-npm run build
-npm pack
+### 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: [...] });
 ```
 
-En el proyecto externo:
+### Eventos
 
-```bash
-npm install /ruta/al/nexabase-report-0.1.0.tgz
+```ts
+viewer.addEventListener('page-change', (e) => console.log(e.detail));
+viewer.addEventListener('drill-click', (e) => console.log(e.detail));
 ```
 
-## Publicar en npm
+---
 
-Guía paso a paso: [docs/PUBLISHING.md](docs/PUBLISHING.md)
+## Formato de datos
 
-Resumen:
+### Single DataSource (array simple)
 
-```bash
-npm run build
-npm pack --dry-run
-npm version patch
-npm publish --access public
+```json
+[
+  { "id": 1, "nombre": "Juan", "ventas": 1500 },
+  { "id": 2, "nombre": "María", "ventas": 2300 }
+]
+```
+
+### Multiple DataSources (objeto con alias)
+
+```json
+{
+  "clientes": [
+    { "id": 1, "nombre": "Juan" }
+  ],
+  "pedidos": [
+    { "id": 101, "cliente_id": 1, "total": 500 }
+  ]
+}
 ```
 
-## Documentación
+---
+
+## Variables de sistema
+
+| 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` |
+
+---
+
+## 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
+```
+
+---
+
+## 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-CSJ68r_Q.js → html2canvas-Bt7A8WrM.js}

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

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

@@ -1,5 +1,5 @@
-import { a as c } from "./index-BJcVIdAR.js";
-import { r as f } from "./html2canvas-CSJ68r_Q.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-DwP6YZUu.js → html2pdf-DsfBPN4L.js}

@@ -1,6 +1,6 @@
-import { g as De, a as Ke, c as Te } from "./index-BJcVIdAR.js";
-import { j as Ge } from "./jspdf.es.min-CDx0J4wI.js";
-import { r as Be } from "./html2canvas-CSJ68r_Q.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];