nexabase-report 0.28.0 → 0.28.3

package/NEXAREPORT.md

@@ -0,0 +1,291 @@
+<!-- nexabase-report@0.28.3 — 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.3/schema/nexareport.schema.json
+```
+
+(cambia `@0.28.3` 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/README.md

@@ -241,6 +241,29 @@ Reports use a banded structure:
 
 `Text`, `Image`, `Barcode`, `QRCode`, `Rectangle`, `Ellipse`, `Line`, `Arrow`, `Table`, `Chart`, `Crosstab`, `SubReport`, `DrillDown`
 
+## AI-Assisted Report Generation
+
+Let your AI coding assistant (Claude Code, Gemini CLI, OpenCode, Cursor...) build report JSON for
+you — one command, run once per project:
+
+```bash
+npx nexabase-report-ai
+```
+
+This detects your project's AI instructions file (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`,
+`.cursorrules`) — or creates `AGENTS.md` if none exists — and adds a pointer to the always-current
+report reference and JSON Schema (served straight from the published package, so it's never
+stale):
+
+- `https://unpkg.com/nexabase-report@latest/NEXAREPORT.md` — band/element types, binding syntax,
+  worked examples
+- `https://unpkg.com/nexabase-report@latest/schema/nexareport.schema.json` — the formal schema, to
+  validate generated JSON before trusting it
+
+From then on, any assistant that reads your project's instructions file already knows the current
+report format — no manual copy-pasting, and it can't drift out of date since both files are
+regenerated from the real TypeScript types on every published version.
+
 ## Expression Engine
 
 Safe evaluation without `eval`. Supports:

package/bin/nexabase-report-ai.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+// npx nexabase-report-ai  ->  agrega, UNA vez, el puntero a NEXAREPORT.md/schema en el archivo
+// de instrucciones de IA que ya tenga el proyecto (CLAUDE.md/AGENTS.md/GEMINI.md/.cursorrules).
+// Idempotente: si ya está, no duplica nada.
+import { readFile, writeFile, appendFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+const cwd = process.cwd();
+const MARKER = '<!-- nexabase-report:ai-context -->';
+
+const BLOCK = `
+${MARKER}
+## NexaReport
+
+Antes de crear o modificar un reporte de NexaReport (JSON \`NexaReportDefinition\`), lee
+https://unpkg.com/nexabase-report@latest/NEXAREPORT.md y valida el JSON generado contra
+https://unpkg.com/nexabase-report@latest/schema/nexareport.schema.json antes de entregarlo.
+`;
+
+const candidates = ['CLAUDE.md', 'AGENTS.md', 'GEMINI.md', '.cursorrules'];
+const found = candidates.filter(f => existsSync(join(cwd, f)));
+
+async function addTo(file) {
+  const path = join(cwd, file);
+  const current = existsSync(path) ? await readFile(path, 'utf-8') : '';
+  if (current.includes(MARKER)) {
+    console.log(`  = ${file} ya tiene la sección de NexaReport, sin cambios`);
+    return;
+  }
+  if (current) {
+    await appendFile(path, '\n' + BLOCK);
+  } else {
+    await writeFile(path, BLOCK.trimStart() + '\n');
+  }
+  console.log(`  + ${file} actualizado`);
+}
+
+if (found.length > 0) {
+  for (const f of found) await addTo(f);
+} else {
+  // Ningún archivo de instrucciones detectado: crea AGENTS.md, la convención más genérica
+  // (la leen Claude Code, Gemini CLI, OpenCode, Cursor y otros).
+  await addTo('AGENTS.md');
+}
+
+console.log('\nListo. Cualquier IA que lea ese archivo ya sabe consultar el formato actual de NexaReport.');

package/dist/{generated-BjsMhDVX.js → generated-BnErILTW.js}

@@ -859,6 +859,36 @@ promedio…). No dependen de la banda en la que estén, porque no hay bandas.</l
 <p>Los formatos pensados para documentos —Word, PPTX— y los de datos —Excel, CSV— están orientados a
 reportes paginados. Si necesitas repartir cifras periódicamente por correo o en un archivo, el
 formato adecuado es un <strong>reporte</strong>, no un dashboard.</p>
+`
+  },
+  {
+    id: "ia-generacion",
+    title: "Generar reportes con IA",
+    search: "ia, ai, claude, gemini, copilot, cursor, prompt, generar, automatizar, npx generar reportes con ia si integras nexareport en tu app, no necesitas armar el json del reporte a mano ni empezar desde cero en el diseñador: un asistente de ia puede generarlo por ti. configuración (un comando, una sola vez) desde la carpeta de tu proyecto: npx nexabase report ai ese comando detecta el archivo de instrucciones que tu asistente ya lee solo ( claude.md , agents.md , gemini.md , .cursorrules ) —o crea agents.md si no encuentra ninguno— y le agrega el puntero al formato actual de nexareport. no hay nada que copiar ni pegar a mano, y si lo corres de nuevo no duplica nada. de ahí en adelante, cualquier desarrollador del equipo , en cualquier sesión , con cualquier reporte que pida, la ia ya sabe consultar sola el formato actual — sin volver a tocar nada. por qué siempre está al día el comando apunta a nexabase report@latest en npm, no a una copia local: el documento de referencia y el schema formal se regeneran automáticamente en cada versión publicada, directo desde el código. nunca vas a recibir un json con un campo que ya no existe, o le falte uno nuevo (como staticpage , para reportes de páginas fijas). después de generarlo pega el json resultante en el diseñador ( importar json ) para revisarlo visualmente y ajustar posiciones, colores o binding fino — la ia arma la estructura, el diseñador es donde lo dejas exacto.",
+    element: "",
+    html: `<h1>Generar reportes con IA</h1>
+<p>Si integras NexaReport en tu app, no necesitas armar el JSON del reporte a mano ni empezar desde
+cero en el diseñador: un asistente de IA puede generarlo por ti.</p>
+<h2>Configuración (un comando, una sola vez)</h2>
+<p>Desde la carpeta de tu proyecto:</p>
+<pre><code>npx nexabase-report-ai
+</code></pre>
+<p>Ese comando detecta el archivo de instrucciones que tu asistente ya lee solo (<code>CLAUDE.md</code>,
+<code>AGENTS.md</code>, <code>GEMINI.md</code>, <code>.cursorrules</code>) —o crea <code>AGENTS.md</code> si no encuentra ninguno— y le agrega
+el puntero al formato actual de NexaReport. No hay nada que copiar ni pegar a mano, y si lo
+corres de nuevo no duplica nada.</p>
+<p>De ahí en adelante, <strong>cualquier desarrollador del equipo</strong>, en <strong>cualquier sesión</strong>, con
+<strong>cualquier reporte</strong> que pida, la IA ya sabe consultar sola el formato actual — sin volver a
+tocar nada.</p>
+<h2>Por qué siempre está al día</h2>
+<p>El comando apunta a <code>nexabase-report@latest</code> en npm, no a una copia local: el documento de
+referencia y el schema formal se regeneran automáticamente en cada versión publicada, directo
+desde el código. Nunca vas a recibir un JSON con un campo que ya no existe, o le falte uno nuevo
+(como <code>StaticPage</code>, para reportes de páginas fijas).</p>
+<h2>Después de generarlo</h2>
+<p>Pega el JSON resultante en el diseñador (<strong>Importar JSON</strong>) para revisarlo visualmente y ajustar
+posiciones, colores o binding fino — la IA arma la estructura, el diseñador es donde lo dejas
+exacto.</p>
 `
   }
 ];

package/dist/{html2pdf-C6SN8ITW.js → html2pdf-jHo6I3W3.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-Dc1HlUG3.js";
+import { j as Xl } from "./jspdf.es.min-Ce1kkozr.js";
 function Jl(Pe, br) {
   for (var fe = 0; fe < br.length; fe++) {
     const HA = br[fe];