nexabase-report 0.3.3 → 0.4.1

package/docs/PUBLISHING.md

@@ -4,9 +4,9 @@
 
 | Método | Para quién | Complejidad | URL ejemplo |
 |--------|-----------|-------------|-------------|
-| **npm registry** | Cualquiera con `npm install` | Baja | `npm install nexabase-report` |
+| **npm registry** | Cualquiera con `pnpm install` | Baja | `ppnpm 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` |
+| **Verdaccio (privado)** | Empresa interna | Media | `ppnpm install nexabase-report --registry=https://npm.miempresa.com` |
 | **CDN (unpkg/jsDelivr)** | Quick demo, prototipos | Baja | `<script src="https://unpkg.com/nexabase-report">` |
 
 ---
@@ -31,7 +31,7 @@ npm adduser
 #    - "exports" debe definir entry points
 
 # 2. Build de producción
-npm run build
+pnpm run build
 
 # 3. Verificar qué se va a publicar
 npm pack --dry-run
@@ -41,33 +41,33 @@ npm pack --dry-run
 ### Publicar
 ```bash
 # Publicar versión
-npm publish --access public
+ppnpm publish --access public
 
 # O si usas scoped package (@nexabase/report):
-npm publish --access public
+ppnpm publish --access public
 ```
 
 ### Consumir
 ```bash
 # En cualquier proyecto:
-npm install nexabase-report
+pnpm install nexabase-report
 # o
-npm install @nexabase/nexabase-report
+pnpm install @nexabase/nexabase-report
 ```
 
 ### Actualizar versión
 ```bash
 # patch: 0.1.0 → 0.1.1
-npm version patch
+pnpm version patch
 
 # minor: 0.1.0 → 0.2.0
-npm version minor
+pnpm version minor
 
 # major: 0.1.0 → 1.0.0
 npm version major
 
 # Luego publicar
-npm publish
+pnpm publish
 ```
 
 ---
@@ -85,7 +85,7 @@ git push origin v0.1.0
 
 Consumir desde otro proyecto:
 ```bash
-npm install github:nexabase/nexabase-report#v0.1.0
+pnpm install github:nexabase/nexabase-report#v0.1.0
 ```
 
 ---
@@ -96,14 +96,14 @@ Para empresas que no quieren publicar en npm público:
 
 ```bash
 # Instalar Verdaccio
-npm install -g verdaccio
+pnpm install -g verdaccio
 verdaccio
 
 # En .npmrc del proyecto consumidor:
 # registry=https://npm.miempresa.com/
 
 # Publicar
-npm publish --registry=http://localhost:4873
+pnpm publish --registry=http://localhost:4873
 ```
 
 ---
@@ -161,7 +161,7 @@ nexabase-report-0.2.x.tgz
 
 ## Checklist antes de publicar
 
-- [ ] `npm run build` pasa sin errores
+- [ ] `pnpm run build` pasa sin errores
 - [ ] `package.json` tiene `"private": false` (o no tiene la clave)
 - [ ] `version` incrementada correctamente
 - [ ] `files` incluye `dist/`, `docs/`, `examples/`
@@ -213,8 +213,8 @@ jobs:
           node-version: 20
           registry-url: https://registry.npmjs.org
       - run: npm ci
-      - run: npm run build
-      - run: npm publish --access public
+      - run: pnpm run build
+      - run: ppnpm publish --access public
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 ```
@@ -226,7 +226,7 @@ jobs:
 ### Vue 3 + Vite
 
 ```bash
-npm install nexabase-report @nexabase/sdk
+pnpm install nexabase-report @nexabase/sdk
 ```
 
 ```vue

package/docs/VIEWER_API.md

@@ -110,6 +110,7 @@ function MiReporte({ definition, data, parameters }) {
 | `currentPage` | `number` | `1` | Página inicial que se debe mostrar. |
 | `apiBaseUrl` | `string` | — | URL base de NexaBase para reportes con datos dinámicos. |
 | `apiKey` | `string` | — | API Key para autenticación de datos desde NexaBase. |
+| `licenseKey` | `string` | — | Clave de licencia comercial. Sin licencia válida se muestra un aviso "Sin licencia" en el visor. |
 
 ## Métodos (vía ref DOM)
 

package/docs/guide/designer.md

@@ -0,0 +1,130 @@
+# Designer
+
+NexaDesigner is a fully-featured WYSIWYG report designer built as a Vue 3 component. It provides a ribbon toolbar, canvas with rulers, sidebars for dictionary/properties/settings, drag-and-drop banded report editing, and real-time preview.
+
+## Usage
+
+```vue
+<template>
+  <NexaDesigner
+    :report="reportDefinition"
+    :locale="'es'"
+    :license-key="'NXBR-XXXX-XXXX-XXXX'"
+    @save="onSave"
+    @update:locale="onLocaleChange"
+  />
+</template>
+
+<script setup>
+import NexaDesigner from 'nexabase-report/designer';
+import { ref } from 'vue';
+
+const reportDefinition = ref({ /* report JSON */ });
+
+function onSave(reports) {
+  console.log('Reports saved:', reports);
+}
+</script>
+```
+
+## Designer UI Layout
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  [Logo]  File  Home  Insert  Page  Data  View            │ ← Ribbon
+├────────┬────────────────────────────────────────┬─────────┤
+│        │  1   2   3   4   5   6   7   8   9   10 │         │
+│ 📁     │  └────────── rulers ──────────────────┘ │  🔍     │
+│ Dict   │                                          │ Props   │
+│        │  ┌──────────────────────────────────┐  │         │
+│ Fields │  │       Page Canvas                 │  │ x: 2cm  │
+│ Params │  │  ┌────────────────────────────┐  │  │ y: 1cm  │
+│        │  │  │ ReportHeader               │  │  │ w: 18cm │
+│        │  │  ├────────────────────────────┤  │  │ h: 1cm  │
+│        │  │  │ DataBand ──────────────── │  │  │         │
+│        │  │  ├────────────────────────────┤  │  │         │
+│        │  │  │ PageFooter                │  │  │         │
+│        │  │  └────────────────────────────┘  │  │         │
+│        │                                          │         │
+├────────┴────────────────────────────────────────┴─────────┤
+│  Ready to design   │   x: 2cm y: 1cm w: 18cm h: 1cm      │ ← Status bar
+└─────────────────────────────────────────────────────────┘
+```
+
+## Sidebar Tabs
+
+### Dictionary (📁)
+- Data source list with fields
+- Add/remove data sources
+- Drag fields onto the canvas to create elements
+
+### Properties (🔍)
+- **Content**: Element content, binding expressions, image source
+- **Position/Size**: X, Y, Width, Height (in cm)
+- **Format**: Font size, weight, color
+
+### Settings (⚙)
+- **Language**: ES / EN / PT
+- **NexaBase Connection**: API URL and Key
+- **License**: Activate commercial license
+
+## Ribbon Tabs
+
+| Tab | Sections |
+|-----|----------|
+| **File** | New, Open, Save, Preview, Export/Import, Settings, About |
+| **Home** | Clipboard, Undo/Redo, Delete, Select All |
+| **Insert** | Text, Image, Barcode, QR Code, Table, Chart, Shapes (Rectangle, Ellipse, Line) |
+| **Page** | Page format, orientation, margins, ruler toggle, grid toggle |
+| **Data** | Data source management, parameter binding |
+| **View** | Zoom, panels visibility |
+
+## Adding Elements
+
+### From the Ribbon
+
+1. Click **Insert** tab
+2. Choose element type (Text, Image, Barcode, Table, Chart, Shape)
+3. Click on the canvas to place the element
+
+### From Dictionary (drag & drop)
+
+1. Open **Dictionary** sidebar
+2. Drag a field from the list
+3. Drop it onto a band in the canvas
+
+## Band Context Menu
+
+Right-click on a band tag to access:
+- **Add Element** — insert new element into the band
+- **Delete Band** — remove the band
+- **Change Band Type** — convert between compatible types
+
+## Report Types
+
+### Banded Report (default)
+- Supports: ReportHeader, PageHeader, DataBand, DetailBand, GroupHeader, GroupFooter, PageFooter, ReportFooter
+- Full expression engine: `{{field}}`, `{[expression]}`
+
+### Dashboard
+- Grid-based widget layout
+- Widget types: Indicator (KPI), Chart, Gauge, Table
+
+Switch between modes via **File → New → Report** or **Dashboard**.
+
+## Save and Sync
+
+- **Save locally**: Downloads the report JSON file
+- **Save to NexaBase**: Syncs to your NexaBase instance (requires API key in Settings)
+
+## Licensing
+
+The designer shows a watermark banner when no valid license is provided. Activate a license in **Settings → License** by pasting a key like `NXBR-XXXX-XXXX-XXXX`. License types:
+
+| Type | Features |
+|------|----------|
+| `personal` | Basic use, watermark visible |
+| `business` | No watermark, unlimited projects |
+| `enterprise` | No watermark, priority support |
+
+Generate license keys using: `npm run license:gen -- --type=business --expires=2027-12-31`

package/docs/guide/getting-started.md

@@ -0,0 +1,179 @@
+# Getting Started
+
+## Requirements
+
+- **Node.js** 18+ with npm
+- **Vue 3** (if integrating in a Vue project)
+
+## Installation
+
+### npm (recommended)
+
+```bash
+npm install nexabase-report
+```
+
+### CDN (no install required)
+
+```html
+<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">
+```
+
+## Register the Custom Element
+
+### Vue 3
+
+```vue
+<script setup>
+import { registerNexaReport } from 'nexabase-report';
+registerNexaReport();
+</script>
+
+<template>
+  <nexa-viewer
+    :definition="reportDefinition"
+    :data="reportData"
+    :parameters="{ fechaDesde: '2024-01-01' }"
+    skip-params-dialog
+  />
+</template>
+```
+
+### HTML / Vanilla JS
+
+```html
+<script>
+  window.NexaReport.registerNexaReport();
+</script>
+
+<nexa-viewer id="viewer"></nexa-viewer>
+
+<script>
+  const viewer = document.getElementById('viewer');
+  viewer.definition = { /* report definition JSON */ };
+  viewer.data = [ /* data array */ ];
+</script>
+```
+
+### React
+
+```tsx
+import { useEffect } from 'react';
+import 'nexabase-report';
+
+export function ReportViewer({ definition, data }) {
+  useEffect(() => {
+    window.NexaReport?.registerNexaReport();
+  }, []);
+
+  return <nexa-viewer ref={(el) => {
+    if (el) {
+      el.definition = definition;
+      el.data = data;
+    }
+  }} />;
+}
+```
+
+### Angular
+
+```ts
+// app.module.ts
+import { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
+
+@NgModule({
+  schemas: [CUSTOM_ELEMENTS_SCHEMA],
+})
+export class AppModule {}
+```
+
+```html
+<!-- component.html -->
+<nexa-viewer
+  [definition]="reportDef"
+  [data]="reportData"
+  [parameters]="params"
+></nexa-viewer>
+```
+
+## Core Concepts
+
+### Report Definition
+
+A report is a JSON object that describes the layout, bands, elements, data sources, and styling.
+
+```json
+{
+  "metadata": {
+    "name": "Sales Report",
+    "version": "1.0",
+    "createdAt": "2024-01-01T00:00:00Z"
+  },
+  "layout": {
+    "page": {
+      "format": "A4",
+      "orientation": "portrait",
+      "margins": { "top": 1.5, "right": 1.5, "bottom": 1.5, "left": 1.5 }
+    },
+    "bands": [
+      {
+        "id": "header",
+        "type": "ReportHeader",
+        "height": 80,
+        "elements": [
+          {
+            "id": "title",
+            "type": "Text",
+            "x": 0,
+            "y": 0,
+            "width": 700,
+            "height": 50,
+            "content": "{{ReportName}}",
+            "style": { "fontSize": "24px", "fontWeight": "bold" }
+          }
+        ]
+      }
+    ]
+  },
+  "dataSources": [
+    { "id": "ds1", "collection": "sales", "alias": "main", "enabled": true }
+  ]
+}
+```
+
+### Bands (Report Model)
+
+NexaReport uses a **banded report model** inspired by Stimulsoft/DevExpress:
+
+| Band | When it renders |
+|------|----------------|
+| `ReportHeader` | Once, at the top of the first page |
+| `PageHeader` | At the top of every page |
+| `DataBand` | Once per data row |
+| `DetailBand` | Nested detail for master-detail |
+| `GroupHeader` | At the start of each group |
+| `GroupFooter` | At the end of each group |
+| `PageFooter` | At the bottom of every page |
+| `ReportFooter` | Once, at the end of the last page |
+
+### Expressions
+
+Use `{{field}}` for field binding and `{[expression]}` for computed expressions:
+
+```
+{{clientName}}           → bound to data field
+{[UPPER(clientName)]}    → uppercase
+{[FORMATNUMBER(amount, 2)]}  → formatted number
+{[IIF(total > 0, 'OK', 'ZERO')]}  → conditional
+{[NOW()]}                → current date/time
+```
+
+See the [Expression Engine](/api/expression-engine) reference for all available functions.
+
+## Next Steps
+
+- [Quick Start](/guide/quick-start) — build your first report
+- [Designer Guide](/guide/designer) — WYSIWYG report designer
+- [Viewer Props](/reference/props) — all available viewer properties
+- [Export Guide](/guide/export) — PDF, Excel, Word, CSV

package/docs/guide/quick-start.md

@@ -0,0 +1,170 @@
+# Quick Start
+
+## Step 1: Load the Library
+
+```html
+<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">
+```
+
+## Step 2: Define Your Report
+
+A minimal report JSON with a header band and one data band:
+
+```json
+{
+  "metadata": {
+    "name": "My First Report",
+    "version": "1.0"
+  },
+  "layout": {
+    "page": { "format": "A4", "orientation": "portrait" },
+    "bands": [
+      {
+        "id": "rh",
+        "type": "ReportHeader",
+        "height": 80,
+        "elements": [
+          {
+            "id": "title",
+            "type": "Text",
+            "x": 20,
+            "y": 10,
+            "width": 750,
+            "height": 50,
+            "content": "Sales Report",
+            "style": { "fontSize": "24px", "fontWeight": "bold" }
+          }
+        ]
+      },
+      {
+        "id": "db",
+        "type": "DataBand",
+        "height": 40,
+        "dataSource": "main",
+        "elements": [
+          {
+            "id": "client",
+            "type": "Text",
+            "x": 20,
+            "y": 5,
+            "width": 300,
+            "height": 30,
+            "content": "{{clientName}}",
+            "style": { "fontSize": "12px" }
+          },
+          {
+            "id": "amount",
+            "type": "Text",
+            "x": 330,
+            "y": 5,
+            "width": 150,
+            "height": 30,
+            "content": "{{amount}}",
+            "style": { "fontSize": "12px", "textAlign": "right" }
+          }
+        ]
+      }
+    ]
+  },
+  "dataSources": [
+    { "id": "ds1", "collection": "sales", "alias": "main", "enabled": true }
+  ]
+}
+```
+
+## Step 3: Mount the Viewer
+
+```html
+<nexa-viewer id="viewer"></nexa-viewer>
+
+<script>
+  window.NexaReport.registerNexaReport();
+
+  const viewer = document.getElementById('viewer');
+
+  viewer.definition = { /* paste report JSON above */ };
+  viewer.data = [
+    { clientName: 'Acme Corp', amount: 12500.00 },
+    { clientName: 'Globex Inc', amount: 8300.50 },
+    { clientName: 'Soylent Corp', amount: 15200.00 }
+  ];
+</script>
+```
+
+## Step 4: Export (optional)
+
+```javascript
+// Export to PDF
+await viewer.exportPdf();
+
+// Export to Excel
+await viewer.exportExcel();
+
+// Export to CSV
+await viewer.exportCsv();
+```
+
+## Complete HTML Example
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>NexaReport Quick Start</title>
+  <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="viewer" minimal></nexa-viewer>
+
+  <script>
+    NexaReport.registerNexaReport();
+
+    const reportDef = {
+      metadata: { name: 'Quick Start Demo', version: '1.0' },
+      layout: {
+        page: { format: 'A4', orientation: 'portrait' },
+        bands: [
+          {
+            id: 'rh', type: 'ReportHeader', height: 80,
+            elements: [{
+              id: 't1', type: 'Text', x: 20, y: 10,
+              width: 750, height: 50,
+              content: 'Client Report',
+              style: { fontSize: '24px', fontWeight: 'bold' }
+            }]
+          },
+          {
+            id: 'db', type: 'DataBand', height: 40, dataSource: 'main',
+            elements: [
+              { id: 'c1', type: 'Text', x: 20, y: 5, width: 300, height: 30,
+                content: '{{clientName}}', style: { fontSize: '12px' } },
+              { id: 'c2', type: 'Text', x: 330, y: 5, width: 150, height: 30,
+                content: '{{amount}}', style: { fontSize: '12px', textAlign: 'right' } }
+            ]
+          }
+        ]
+      },
+      dataSources: [{ id: 'ds1', collection: '', alias: 'main', enabled: true }]
+    };
+
+    const data = [
+      { clientName: 'Acme Corp', amount: 12500 },
+      { clientName: 'Globex Inc', amount: 8300 },
+      { clientName: 'Soylent Corp', amount: 15200 }
+    ];
+
+    const viewer = document.getElementById('viewer');
+    viewer.definition = reportDef;
+    viewer.data = data;
+  </script>
+</body>
+</html>
+```
+
+## Try the Examples
+
+See the `examples/` folder in the repository for React, Angular, Blazor, and jQuery integrations.