nexabase-report 0.28.0 → 0.28.1

package/NEXAREPORT.md

@@ -0,0 +1,291 @@
+<!-- nexabase-report@0.28.1 — generado por scripts/gen-ai-context.mjs, no editar a mano -->
+# NexaReport — referencia para agentes de IA
+
+> Este archivo se genera desde los tipos TypeScript reales del paquete (`src/lib/types/report.ts`
+> vía `schema/nexareport.schema.json`), no a mano — así nunca queda desactualizado respecto al
+> código. Si este archivo dice una versión de `nexabase-report` distinta a la que tienes
+> instalada en `package.json`, hay una más reciente en
+> `https://unpkg.com/nexabase-report@latest/NEXAREPORT.md` — tráela de ahí antes de confiar
+> en este archivo (o corre `npm run build` en el repo de nexabase-report para regenerarla).
+
+## Qué es
+
+NexaReport es un motor de reportes (diseñador + visor + exportación PDF/Excel/Word) basado en
+**bandas** apiladas verticalmente, al estilo Stimulsoft/FastReport. Un reporte es un único objeto
+JSON: `NexaReportDefinition`.
+
+## Estructura mínima de un reporte
+
+```json
+{
+  "metadata": { "version": "1.0", "name": "Nombre del reporte", "createdAt": "2026-01-01" },
+  "layout": {
+    "page": { "format": "A4", "orientation": "portrait", "margins": { "top": 60, "right": 60, "bottom": 60, "left": 60 } },
+    "bands": [ /* ver "Tipos de banda" abajo */ ]
+  },
+  "dataSources": [ { "id": "ds1", "alias": "items", "collection": "items", "enabled": true } ]
+}
+```
+
+`layout.page.format` es `"A4" | "Letter" | "Ticket" | "Dashboard"`. `orientation` es
+`"portrait" | "landscape"`.
+
+## Tipos de banda (`NexaReportBand.type`)
+
+- **ReportHeader** — Se imprime una sola vez, al inicio (o en cada página si repeatOnEveryPage: true). El título/membrete del reporte.
+- **PageHeader** — Se repite en la parte superior de CADA página.
+- **DataBand** — La banda de datos principal — una instancia por fila (o una sola con una Table que lista todas las filas). Requiere dataSource.
+- **GroupHeader** — Se imprime al iniciar un grupo (requiere masterField). Va antes de las filas de ese grupo.
+- **GroupFooter** — Se imprime al cerrar un grupo (requiere masterField). Ideal para subtotales.
+- **PageFooter** — Se repite en la parte inferior de CADA página.
+- **ReportFooter** — Se imprime una sola vez, al final de todo el reporte (totales generales, firma).
+- **DetailBand** — Sub-banda para master-detail: una fila hija por cada fila del DataBand padre (parentDataSource + masterField + childField).
+- **StaticPage** — Contenido FIJO de una página completa, independiente de los datos. Repetible: una StaticPage por cada página fija que necesites (ej. una carta de 2 hojas). Puede tener dataSource igual que cualquier otra banda (ej. para el nombre del destinatario). Nace con pageBreakBefore: true.
+
+Toda banda puede tener: `pageBreakBefore` / `pageBreakAfter` (forzar salto de página),
+`backgroundColor`, `dataSource` (alias de `dataSources` a usar). Las coordenadas de los
+elementos dentro de una banda (`x`, `y`) son relativas a la banda, en píxeles.
+
+## Tipos de elemento (`NexaReportElement.type`)
+
+- **Text** — Texto simple. `binding` para un campo ({{campo}} implícito) o `content` con placeholders {{campo}} / expresiones {[expr]}.
+- **Image** — `options.imageSource`: "url" (URL fija en options.imageUrl) o "binding" (campo de datos con la URL/base64).
+- **Barcode** — Código de barras. `binding` o `content` con el valor; `options.barcodeFormat` (ej. "CODE128").
+- **Table** — Tabla tabular — usar dentro de un DataBand. `tableColumns` (id/title/binding/width/format), tableShowHeader/Footer/GroupHeader/Footer, tableGroupBy.
+- **Chart** — `chartConfig` (tipo, series, ejes).
+- **Crosstab** — Tabla dinámica. `crosstabConfig`.
+- **SubReport** — Reporte embebido. `subReportDefinition` (definición completa inline) + `subReportDataSource` (alias en el dataMap del padre) + `subReportBindings` ([{masterField, childField}]) para filtrar por la fila actual del padre.
+- **Line** — Forma. `shapeType` implícito ("Line").
+- **Rectangle** — Forma. `options.fillColor`, `options.cornerRadius`.
+- **Ellipse** — Forma.
+- **Arrow** — Forma.
+- **QRCode** — Código QR. Igual que Barcode pero sin formato.
+- **DrillDown** — Navega a otro reporte al hacer clic. `drillDownConfig`.
+- **Gauge** — `gaugeConfig` (valueField, min, max, ranges).
+- **Indicator** — KPI simple. `indicatorConfig` (binding, aggregation, label).
+- **RichText** — Texto con formato (negrita, listas, etc.). El HTML autorizado va en `richText` (NO en `content`).
+
+Todo elemento tiene `id`, `type`, `x`, `y`, `width`, `height`, `style` (obligatorios).
+
+## Binding de datos y expresiones
+
+- `{{campo}}` dentro de `content` — inserta el valor de ese campo de la fila actual.
+- `{[expresión]}` — evalúa una expresión, incluye funciones de agregación: `sum(campo)`,
+  `count(campo)`, `avg(campo)`, `min(campo)`, `max(campo)`, `first(campo)`, `last(campo)`.
+- Variables de sistema: `{{Page}}`, `{{TotalPages}}`, `{{Today}}`, `{{Now}}`, `{{RowNumber}}`,
+  `{{TotalRows}}`, `{{ReportName}}`, y más — ver `docs/VIEWER_API.md` para la lista completa.
+- Un elemento con `binding` (en vez de `content`) lee ese campo directamente — usado para
+  Barcode/QRCode/Image; para Text es más común usar `content` con `{{...}}`.
+
+## Ejemplo 1 — Carta fija de 2 páginas (StaticPage)
+
+```json
+{
+  "metadata": {
+    "version": "1.0",
+    "name": "Carta",
+    "createdAt": "2026-01-01"
+  },
+  "layout": {
+    "page": {
+      "format": "A4",
+      "orientation": "portrait",
+      "margins": {
+        "top": 60,
+        "right": 60,
+        "bottom": 60,
+        "left": 60
+      }
+    },
+    "bands": [
+      {
+        "id": "pagina1",
+        "type": "StaticPage",
+        "height": 900,
+        "dataSource": "destinatario",
+        "elements": [
+          {
+            "id": "saludo",
+            "type": "Text",
+            "x": 0,
+            "y": 0,
+            "width": 500,
+            "height": 30,
+            "style": {
+              "fontSize": "14px"
+            },
+            "binding": "nombre",
+            "content": "Estimado {{nombre}}:"
+          },
+          {
+            "id": "cuerpo",
+            "type": "Text",
+            "x": 0,
+            "y": 40,
+            "width": 500,
+            "height": 400,
+            "style": {
+              "fontSize": "12px"
+            },
+            "content": "Cuerpo de la carta..."
+          }
+        ]
+      },
+      {
+        "id": "pagina2",
+        "type": "StaticPage",
+        "height": 900,
+        "pageBreakBefore": true,
+        "elements": [
+          {
+            "id": "firma",
+            "type": "Text",
+            "x": 0,
+            "y": 700,
+            "width": 300,
+            "height": 30,
+            "style": {
+              "fontSize": "12px"
+            },
+            "content": "Atentamente,\nEl equipo"
+          }
+        ]
+      }
+    ]
+  },
+  "dataSources": [
+    {
+      "id": "ds1",
+      "alias": "destinatario",
+      "collection": "destinatario",
+      "enabled": true
+    }
+  ]
+}
+```
+
+## Ejemplo 2 — Factura con tabla y totales
+
+```json
+{
+  "metadata": {
+    "version": "1.0",
+    "name": "Factura",
+    "createdAt": "2026-01-01"
+  },
+  "layout": {
+    "page": {
+      "format": "A4",
+      "orientation": "portrait"
+    },
+    "bands": [
+      {
+        "id": "rh",
+        "type": "ReportHeader",
+        "height": 80,
+        "elements": [
+          {
+            "id": "titulo",
+            "type": "Text",
+            "x": 0,
+            "y": 0,
+            "width": 300,
+            "height": 30,
+            "style": {
+              "fontSize": "20px",
+              "fontWeight": "bold"
+            },
+            "content": "Factura {{numero}}"
+          }
+        ]
+      },
+      {
+        "id": "db",
+        "type": "DataBand",
+        "height": 200,
+        "dataSource": "items",
+        "elements": [
+          {
+            "id": "tabla",
+            "type": "Table",
+            "x": 0,
+            "y": 0,
+            "width": 500,
+            "height": 150,
+            "style": {},
+            "tableShowFooter": true,
+            "tableColumns": [
+              {
+                "id": "c1",
+                "title": "Producto",
+                "binding": "nombre",
+                "width": 250
+              },
+              {
+                "id": "c2",
+                "title": "Cantidad",
+                "binding": "cantidad",
+                "width": 100,
+                "alignment": "right"
+              },
+              {
+                "id": "c3",
+                "title": "Subtotal",
+                "binding": "subtotal",
+                "width": 150,
+                "alignment": "right",
+                "format": "$#,##0.00",
+                "footerText": "Total: {[sum(subtotal)]}"
+              }
+            ]
+          }
+        ]
+      },
+      {
+        "id": "pf",
+        "type": "PageFooter",
+        "height": 30,
+        "elements": [
+          {
+            "id": "pag",
+            "type": "Text",
+            "x": 400,
+            "y": 0,
+            "width": 100,
+            "height": 20,
+            "style": {
+              "fontSize": "9px",
+              "textAlign": "right"
+            },
+            "content": "Página {{Page}} de {{TotalPages}}"
+          }
+        ]
+      }
+    ]
+  },
+  "dataSources": [
+    {
+      "id": "ds1",
+      "alias": "items",
+      "collection": "items",
+      "enabled": true
+    }
+  ]
+}
+```
+
+## Validación
+
+El schema formal completo (todas las interfaces, no solo bandas/elementos) está en
+`schema/nexareport.schema.json` dentro del paquete — también publicado como export
+`nexabase-report/schema`, así que es accesible sin instalar nada vía:
+
+```
+https://unpkg.com/nexabase-report@0.28.1/schema/nexareport.schema.json
+```
+
+(cambia `@0.28.1` por `@latest` para la versión más reciente). Valida el JSON generado
+contra ese schema antes de darlo por bueno — evita que un campo inventado llegue al usuario.
+
+Más ejemplos reales (subreportes, crosstab, master-detail, códigos de barras) en `examples/*.json`
+dentro del paquete publicado.

package/dist/{html2pdf-C6SN8ITW.js → html2pdf-B3mAxkNT.js}

@@ -1,5 +1,5 @@
-import { g as Nl, c as ut, d as Vl } from "./index-Cn1BXocE.js";
-import { j as Xl } from "./jspdf.es.min-CQvy1ivX.js";
+import { g as Nl, c as ut, d as Vl } from "./index-n-ggfS1p.js";
+import { j as Xl } from "./jspdf.es.min-C6M8fb8R.js";
 function Jl(Pe, br) {
   for (var fe = 0; fe < br.length; fe++) {
     const HA = br[fe];