nexabase-report 0.1.0

package/docs/PUBLISHING.md

@@ -0,0 +1,304 @@
+# Publicar NexaReport para que otros lo usen
+
+## Opciones de distribución
+
+| Método | Para quién | Complejidad | URL ejemplo |
+|--------|-----------|-------------|-------------|
+| **npm registry** | Cualquiera con `npm install` | Baja | `npm install nexabase-report` |
+| **GitHub Releases** | Equipos internos, CI/CD | Baja | `npm i github:nexabase/nexabase-report` |
+| **Verdaccio (privado)** | Empresa interna | Media | `npm install nexabase-report --registry=https://npm.miempresa.com` |
+| **CDN (unpkg/jsDelivr)** | Quick demo, prototipos | Baja | `<script src="https://unpkg.com/nexabase-report">` |
+
+---
+
+## 1. npm registry (recomendado)
+
+### Prerequisitos
+```bash
+# Crear cuenta en npmjs.com (si no tienes)
+npm adduser
+# Username: tu-usuario-nexabase
+# Password: ******
+# Email: dev@nexabase.dev
+```
+
+### Preparar el paquete
+```bash
+# 1. Verificar que package.json esté correcto
+#    - "private" debe ser false (ya lo está)
+#    - version debe incrementarse
+#    - "files" debe incluir dist/, docs/, examples/
+#    - "exports" debe definir entry points
+
+# 2. Build de producción
+npm run build
+
+# 3. Verificar qué se va a publicar
+npm pack --dry-run
+# Debe mostrar: dist/, docs/, examples/, README.md
+```
+
+### Publicar
+```bash
+# Publicar versión
+npm publish --access public
+
+# O si usas scoped package (@nexabase/report):
+npm publish --access public
+```
+
+### Consumir
+```bash
+# En cualquier proyecto:
+npm install nexabase-report
+# o
+npm install @nexabase/nexabase-report
+```
+
+### Actualizar versión
+```bash
+# patch: 0.1.0 → 0.1.1
+npm version patch
+
+# minor: 0.1.0 → 0.2.0
+npm version minor
+
+# major: 0.1.0 → 1.0.0
+npm version major
+
+# Luego publicar
+npm publish
+```
+
+---
+
+## 2. GitHub Releases
+
+```bash
+# Taggear versión
+git tag v0.1.0
+git push origin v0.1.0
+
+# En GitHub → Releases → Draft new release → v0.1.0
+# Adjuntar el .tgz generado por `npm pack`
+```
+
+Consumir desde otro proyecto:
+```bash
+npm install github:nexabase/nexabase-report#v0.1.0
+```
+
+---
+
+## 3. Registry privado (Verdaccio)
+
+Para empresas que no quieren publicar en npm público:
+
+```bash
+# Instalar Verdaccio
+npm install -g verdaccio
+verdaccio
+
+# En .npmrc del proyecto consumidor:
+# registry=https://npm.miempresa.com/
+
+# Publicar
+npm publish --registry=http://localhost:4873
+```
+
+---
+
+## 4. CDN (sin instalación)
+
+Una vez publicado en npm, automáticamente disponible en:
+
+```html
+<!-- unpkg -->
+<script src="https://unpkg.com/nexabase-report@0.1.0/dist/nexabase-report.umd.js"></script>
+
+<!-- jsDelivr -->
+<script src="https://cdn.jsdelivr.net/npm/nexabase-report@0.1.0/dist/nexabase-report.umd.js"></script>
+
+<!-- Uso -->
+<script>
+  NexaReport.registerNexaReport();
+  const viewer = document.getElementById('miViewer');
+  viewer.definition = { /* ... */ };
+  viewer.data = [ /* ... */ ];
+</script>
+```
+
+---
+
+## Estructura del paquete publicado
+
+```
+nexabase-report-0.1.0.tgz
+├── dist/
+│   ├── nexabase-report.es.js      # ESM (import/export)
+│   ├── nexabase-report.umd.js     # UMD (script tag)
+│   ├── index.d.ts                 # Types
+│   ├── types/report.d.ts          # Types de definiciones
+│   ├── designer/                  # Designer component
+│   └── viewer/                    # Viewer custom element
+├── docs/
+│   └── VIEWER_API.md              # Documentación
+├── examples/
+│   ├── report-productos.json      # Ejemplo simple
+│   └── report-factura.json        # Ejemplo factura
+└── README.md
+```
+
+---
+
+## Checklist antes de publicar
+
+- [ ] `npm run build` pasa sin errores
+- [ ] `package.json` tiene `"private": false` (o no tiene la clave)
+- [ ] `version` incrementada correctamente
+- [ ] `files` incluye `dist/`, `docs/`, `examples/`
+- [ ] `exports` define todos los entry points
+- [ ] `README.md` tiene instrucciones de uso
+- [ ] `CHANGELOG.md` actualizado (opcional pero recomendado)
+- [ ] `npm pack --dry-run` muestra solo los archivos correctos
+- [ ] Licencia definida en `package.json`
+- [ ] Dependencias `peerDependencies` si aplica (vue, @nexabase/sdk)
+
+---
+
+## peerDependencies (recomendado agregar)
+
+Para evitar duplicar Vue y otras libs en el proyecto consumidor:
+
+```json
+{
+  "peerDependencies": {
+    "vue": "^3.5.0",
+    "@nexabase/sdk": "^2.12.0"
+  },
+  "peerDependenciesMeta": {
+    "@nexabase/sdk": {
+      "optional": true
+    }
+  }
+}
+```
+
+Esto le dice al consumidor: "necesitas Vue 3.5+, y opcionalmente @nexabase/sdk si quieres conectar al backend".
+
+---
+
+## Flujo de CI/CD recomendado (GitHub Actions)
+
+```yaml
+# .github/workflows/publish.yml
+name: Publish to npm
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org
+      - run: npm ci
+      - run: npm run build
+      - run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+```
+
+---
+
+## Ejemplo completo de uso en proyecto externo
+
+### Vue 3 + Vite
+
+```bash
+npm install nexabase-report @nexabase/sdk
+```
+
+```vue
+<script setup>
+import { ref, onMounted } from 'vue';
+import { registerNexaReport } from 'nexabase-report';
+import 'nexabase-report/style.css';
+
+registerNexaReport();
+
+const reportDef = ref(null);
+const data = ref([]);
+
+onMounted(async () => {
+  // Cargar desde archivo JSON local
+  const res = await fetch('/examples/report-productos.json');
+  reportDef.value = await res.json();
+
+  // Datos reales desde API
+  const dataRes = await fetch('/api/productos');
+  data.value = await dataRes.json();
+});
+</script>
+
+<template>
+  <nexa-viewer :definition="reportDef" :data="data" minimal />
+</template>
+```
+
+### React
+
+```jsx
+import { useEffect, useRef } from 'react';
+import { registerNexaReport } from 'nexabase-report';
+import 'nexabase-report/style.css';
+
+registerNexaReport();
+
+function Reporte() {
+  const viewerRef = useRef(null);
+
+  useEffect(() => {
+    fetch('/api/reports/123')
+      .then(r => r.json())
+      .then(report => {
+        viewerRef.current.definition = report.definition;
+        viewerRef.current.data = report.data;
+      });
+  }, []);
+
+  return <nexa-viewer ref={viewerRef} />;
+}
+```
+
+### HTML puro
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <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">
+</head>
+<body>
+  <nexa-viewer id="miReporte" minimal></nexa-viewer>
+
+  <script>
+    NexaReport.registerNexaReport();
+
+    const viewer = document.getElementById('miReporte');
+
+    fetch('/api/reports/123')
+      .then(r => r.json())
+      .then(report => {
+        viewer.definition = report.definition;
+        viewer.data = report.data;
+      });
+  </script>
+</body>
+</html>
+```

package/docs/QA_PLAN.md

@@ -0,0 +1,138 @@
+# Plan de Pruebas (Antes de UX) — NexaReport
+
+Este plan busca estabilizar el motor (viewer/designer/export) antes de invertir en UX.
+
+## 1) Objetivo
+
+- Confirmar que el viewer renderiza igual en pantalla y en export (PDF/Excel/Word/CSV).
+- Cubrir paginación, bandas, bindings/expresiones, filtros, formatos condicionales, drilldown y subreportes.
+- Detectar regresiones rápido con una rutina repetible.
+
+## 2) Precondiciones
+
+- Compilación OK:
+  - `npm.cmd run build`
+- Para desarrollo local:
+  - `npm.cmd run dev`
+
+## 3) Matriz de Escenarios (Checklist)
+
+### A. Render/Paginación
+
+- A4 portrait, A4 landscape, Letter, Ticket.
+- Márgenes (cm) distintos: 0, 1, 2.5.
+- Bandas:
+  - ReportHeader, PageHeader, DataBand, DetailBand, PageFooter, ReportFooter.
+  - `pageBreakBefore` y `pageBreakAfter` en banda intermedia.
+- Paginación:
+  - Dataset chico (1–5 filas).
+  - Dataset mediano (50–200 filas).
+  - Dataset grande (1000+ filas).
+- Verificar:
+  - Total de páginas calculado coincide con páginas renderizadas.
+  - PageFooter aparece al final de cada página.
+
+### B. Bindings/Expresiones
+
+- Bindings:
+  - `{{campoSimple}}`, `{{obj.campo}}`
+- Variables sistema:
+  - `{{Page}}`, `{{TotalPages}}`, `{{Today}}`, `{{Now}}`, `{{RowNumber}}`, `{{TotalRows}}`, `{{ReportName}}`
+- Expresiones:
+  - `{[FormatNumber(total, 'es-ES')]}`, `{[IIF(total>100,'OK','Bajo')]}`
+  - Parámetros: `{[$fecha_desde]}` (si aplica)
+- Verificar:
+  - En pantalla y en PDF muestran el mismo valor.
+
+### C. Tablas (Table)
+
+- Tabla con 5–8 columnas y ancho variable (forzar wrap).
+- 100+ filas para multipágina.
+- Verificar:
+  - Repite `thead` en cada página exportada.
+  - No corta filas de manera extraña.
+  - No se duplican tablas por fila (DataBand tabular por página).
+
+### D. Crosstab / Chart
+
+- Crosstab con:
+  - 2 rowFields, 1 columnField, 2 valueFields (sum/count).
+- Chart con:
+  - bar/line/pie.
+- Verificar:
+  - Render en pantalla.
+  - Export PDF: se ve completo (sin recortes/overflow).
+
+### E. Imágenes / Barcodes / QR
+
+- Imagen por URL y por binding.
+- Barcode con binding (CODE128) y con displayValue on/off.
+- QRCode (placeholder actual).
+- Verificar:
+  - En PDF respeta tamaño y posición.
+  - Barcode se renderiza en export (si no, registrar issue).
+
+### F. Formato condicional
+
+- Operadores: `eq`, `gt`, `contains`, `starts_with`, `between`, `regex`.
+- Verificar:
+  - Se aplica igual en pantalla y en PDF.
+
+### G. Filtros de DataSource y de Banda
+
+- `dataSources[].filters` (por alias) y `band.filter`.
+- Verificar:
+  - La cantidad de filas cambia como corresponde.
+  - PDF/Excel exporta el mismo conjunto filtrado.
+
+### H. DrillDown
+
+- DrillDown con:
+  - Mapeo de parámetros desde fila actual.
+  - Modal (showAsModal) y new tab (openInNewTab).
+- Verificar:
+  - Modal carga definición y datos del reporte destino.
+
+### I. SubReport
+
+- SubReport embebido (definition) y por `subReportId` si se usa.
+- Verificar:
+  - No rompe export.
+  - Se renderiza con datos esperados (issue conocido si se requiere dataset distinto).
+
+## 4) Set de Datos Recomendado
+
+- `ventas` (main): id, cliente, fecha, total, categoria
+- `detalle` (detail): venta_id, producto, cantidad, precio
+- `clientes`: id, nombre, email
+
+En pruebas rápidas, usar 3 tamaños: 10, 100, 1000 registros.
+
+## 4.1) Reportes de ejemplo (JSON)
+
+- `examples/report-ventas-logo-tabla.json` — logo (imagen) + tabla multipágina
+- `examples/report-master-detail-ordenes.json` — master–detail (DataBand + DetailBand)
+- `examples/report-agrupado-por-cliente.json` — agrupación (GroupHeader/GroupFooter)
+- `examples/report-codigos-qr-barcode.json` — imágenes (URL/base64) + barcode + QR
+- `examples/report-grafico-ventas-por-mes.json` — gráfico (bar)
+- `examples/report-crosstab-categoria-mes.json` — crosstab (pivot)
+
+## 5) Rutina de Smoke Test (10–15 min)
+
+- Abrir un reporte ejemplo por cada formato de papel.
+- Renderizar:
+  - 1 DataBand (texto) + PageHeader/Footer
+  - 1 Table (100 filas)
+  - 1 Crosstab
+- Exportar:
+  - PDF (validar páginas y encabezados de tabla)
+  - Excel (validar hojas)
+  - CSV (validar delimitadores/UTF-8 BOM)
+
+## 6) Criterios de Aceptación (Gate para UX)
+
+- PDF fiel al visor (posiciones, fuentes, márgenes, sin páginas extra).
+- Paginación consistente en visor y export.
+- Table multipágina con encabezado repetido sin duplicación.
+- DrillDown modal estable.
+- Filtros y formato condicional coherentes.