nexabase-report 0.4.0 → 0.4.1

package/docs/guide/viewer.md

@@ -0,0 +1,199 @@
+# Viewer
+
+`<nexa-viewer>` is a custom element (Web Component) that renders NexaReport definitions. It works in any framework (Vue, React, Angular, Svelte, Blazor, plain HTML) and requires no Vue dependency in the consumer application.
+
+## Usage
+
+### HTML / Vanilla JS
+
+```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">
+
+<nexa-viewer id="viewer" minimal></nexa-viewer>
+
+<script>
+  NexaReport.registerNexaReport();
+
+  const viewer = document.getElementById('viewer');
+  viewer.definition = { /* report JSON */ };
+  viewer.data = [ /* data array */ ];
+</script>
+```
+
+### Vue 3
+
+```vue
+<script setup>
+import { registerNexaReport } from 'nexabase-report';
+
+registerNexaReport();
+</script>
+
+<template>
+  <nexa-viewer
+    :definition="reportDef"
+    :data="reportData"
+    :parameters="{ year: 2024 }"
+    skip-params-dialog
+    show-toolbar
+  />
+</template>
+```
+
+### React
+
+```tsx
+import { useEffect, useRef } from 'react';
+
+export function ReportViewer({ definition, data }) {
+  const viewerRef = useRef(null);
+
+  useEffect(() => {
+    window.NexaReport?.registerNexaReport();
+  }, []);
+
+  useEffect(() => {
+    if (viewerRef.current) {
+      viewerRef.current.definition = definition;
+      viewerRef.current.data = data;
+    }
+  }, [definition, data]);
+
+  return <nexa-viewer ref={viewerRef} />;
+}
+```
+
+### Blazor
+
+```razor
+@page "/report/{ReportId}"
+
+<div class="viewer-container">
+  <nexa-viewer id="reportViewer" style="width:100%; height:1200px;"></nexa-viewer>
+</div>
+
+<script src="https://cdn.jsdelivr.net/npm/nexabase-report/dist/nexabase-report.umd.js"></script>
+<script>
+  window.loadReport = async function(reportJson, data) {
+    if (!window._nexaReg) {
+      NexaReport.registerNexaReport();
+      window._nexaReg = true;
+    }
+    const viewer = document.getElementById('reportViewer');
+    viewer.definition = reportJson;
+    viewer.data = data;
+  };
+</script>
+
+@code {
+  [Parameter] public string ReportId { get; set; }
+
+  protected override async Task OnInitializedAsync() {
+    await JSRuntime.InvokeVoidAsync("loadReport", reportDef, reportData);
+  }
+}
+```
+
+## Viewer Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `definition` | `NexaReportDefinition \| string` | — | Report definition object or JSON string. |
+| `data` | `any[] \| Record<string, any[]> \| string` | — | Data for the report. Array (single source) or object keyed by datasource alias. |
+| `parameters` | `Record<string, any>` | `{}` | Initial values for report parameters. |
+| `minimal` | `boolean \| string` | `false` | Compact mode: hides toolbar and sidebar. |
+| `showToolbar` | `boolean \| string` | `true` | Show/hide the export toolbar. |
+| `showThumbs` | `boolean \| string` | `true` | Show/hide the thumbnail sidebar. |
+| `skipParamsDialog` | `boolean` | `false` | Skip the parameter input dialog at load time. |
+| `currentPage` | `number` | `1` | Initial page number to display. |
+| `apiBaseUrl` | `string` | — | NexaBase API URL for dynamic data loading. |
+| `apiKey` | `string` | — | NexaBase API key for authenticated data. |
+| `locale` | `string` | `'es'` | UI language: `'es'`, `'en'`, or `'pt'`. |
+| `licenseKey` | `string` | — | Commercial license key. Without a valid key, an "Unlicensed" watermark appears at the bottom. |
+
+## Viewer Methods
+
+Access via `document.querySelector('nexa-viewer')` or a template ref:
+
+```javascript
+const viewer = document.querySelector('nexa-viewer');
+
+// Navigation
+viewer.goToPage(3);        // Jump to page 3
+viewer.nextPage();          // Go to next page
+viewer.previousPage();      // Go to previous page
+
+// Export
+await viewer.exportPdf();           // Standard PDF
+await viewer.exportPdfWithBookmarks(); // PDF with bookmarks/TOC
+await viewer.exportExcel();          // Excel .xlsx
+await viewer.exportWord();           // Word .docx
+await viewer.exportCsv();            // CSV with UTF-8 BOM
+
+// State
+console.log(viewer.pageNumber);     // Current page (get/set)
+console.log(viewer.totalPages);      // Total pages (read-only)
+```
+
+## Events
+
+```javascript
+const viewer = document.querySelector('nexa-viewer');
+
+viewer.addEventListener('data-request', (e) => {
+  console.log('Data requested for:', e.detail.alias);
+  // Fetch data and set: viewer.data = { [e.detail.alias]: [...] }
+});
+
+viewer.addEventListener('page-change', (e) => {
+  console.log('Page changed to:', e.detail);
+});
+
+viewer.addEventListener('drill-click', (e) => {
+  console.log('Drill-down clicked:', e.detail);
+  // e.detail = { element, sourceData, targetReportId, parameters, config }
+});
+```
+
+## Renderers
+
+The viewer includes specialized renderers for each element type:
+
+| Renderer | Description |
+|----------|-------------|
+| `TextRenderer` | Text, expressions, bindings with highlight search |
+| `ImageRenderer` | Image from URL or data field, with `object-fit` support (contain/cover/fill) |
+| `TableRenderer` | Tabular data with headers, alternating row colors, conditional styling |
+| `ChartRenderer` | ECharts (bar, line, pie, area, scatter, radar, etc.) |
+| `CrosstabRenderer` | Pivot table with row/column grouping and aggregations |
+| `BarcodeRenderer` | CODE128, EAN13, CODE39, etc. via jsbarcode |
+| `QRCodeRenderer` | QR codes via qrcode library |
+| `ShapeRenderer` | Rectangle, Ellipse, Line, Arrow rendered as SVG/canvas |
+| `DashboardWidgetRenderer` | Dashboard widgets (Indicator, Chart, Gauge, Table) |
+
+## Pagination
+
+NexaReport uses a two-phase pagination engine:
+
+1. **Streaming Phase** (`generateStream`): Processes all bands and data rows, computing page breaks based on element heights, table row heights, and watermark space.
+
+2. **Page Generation Phase** (`generatePages`): Splits the stream into individual pages, handling table row splitting across page boundaries and accounting for `PageHeader`, `PageFooter`, and `ReportFooter` space.
+
+The `currentPage` prop allows programmatically navigating to any page. The thumbnail sidebar shows all pages and lets users click to navigate.
+
+## Watermark
+
+Without a valid `licenseKey`, the viewer displays an "Unlicensed · Trial version" banner at the bottom. This does not block functionality but serves as a reminder to activate a commercial license.
+
+## Styling
+
+The viewer uses scoped styles. Global overrides can be applied via CSS custom properties on the host element:
+
+```css
+nexa-viewer {
+  --viewer-bg: #f8fafc;
+  --viewer-toolbar-bg: #ffffff;
+  --viewer-border: #e2e8f0;
+}
+```

package/docs/index.md

@@ -0,0 +1,65 @@
+---
+layout: home
+
+hero:
+  name: "NexaReport"
+  text: "Professional Report Designer & Viewer"
+  tagline: "Vue 3 · TypeScript · WYSIWYG · Export to PDF/Excel/Word · 100% Client-Side"
+  image:
+    src: /logo.svg
+    alt: NexaReport
+  actions:
+    - theme: brand
+      text: Get Started
+      link: /guide/getting-started
+    - theme: alt
+      text: View on GitHub
+      link: https://github.com/nexabase/nexabase-report
+
+features:
+  - icon: 🎨
+    title: WYSIWYG Designer
+    details: Drag & drop report designer with ribbon, sidebar, snap-to-grid, i18n support (ES/EN/PT) and real-time preview.
+
+  - icon: 📦
+    title: Custom Element Viewer
+    details: "<nexa-viewer> works in Vue, React, Angular, Svelte, Blazor, or plain HTML — no Vue dependency in the consumer."
+
+  - icon: 📊
+    title: Charts, Crosstabs, Tables
+    details: ECharts integration (bar, line, pie, area, scatter), crosstab pivot tables, banded report model with data bands.
+
+  - icon: 📄
+    title: PDF, Excel, Word, CSV
+    details: 100% client-side export. Native vector PDF, SheetJS Excel, docx Word, and UTF-8 BOM CSV — no server required.
+
+  - icon: 🔑
+    title: Commercial Licensing
+    details: Designer supports license key activation (personal, business, enterprise). Watermark-free with valid license.
+
+  - icon: 🌐
+    title: CDN Ready
+    details: One script tag to include in any project. No build step required for HTML demos or quick integrations.
+---
+
+<div class="vp-doc flex flex-col items-center justify-center min-h-[30vh] text-center px-6">
+  <h2 class="mb-4 text-2xl font-bold text-[var(--vp-c-brand-1)]">Try it now — no install needed</h2>
+  <div class="code-block w-full max-w-2xl rounded-lg overflow-hidden text-left">
+
+```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">
+
+<nexa-viewer id="viewer" minimal></nexa-viewer>
+
+<script>
+  NexaReport.registerNexaReport();
+
+  const viewer = document.getElementById('viewer');
+  viewer.definition = { /* your report JSON */ };
+  viewer.data = [ /* your data array */ ];
+</script>
+```
+
+  </div>
+</div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexabase-report",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Professional report designer and viewer for NexaBase — drag & drop designer, PDF/Excel export, charts, crosstabs, subreports.",
   "license": "MIT",
   "author": "NexaBase Team",
@@ -54,21 +54,6 @@
     "custom-element",
     "web-component"
   ],
-  "scripts": {
-    "dev": "vite",
-    "build": "vue-tsc -b && vite build",
-    "preview": "vite preview",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
-    "release:patch": "npm test && npm run build && npm version patch",
-    "release:minor": "npm test && npm run build && npm version minor",
-    "release:major": "npm test && npm run build && npm version major",
-    "prepack": "npm run build",
-    "lint": "eslint src/lib/",
-    "lint:fix": "eslint src/lib/ --fix",
-    "license:gen": "node scripts/gen-license.mjs"
-  },
   "dependencies": {
     "@nexabase/sdk": "^2.17.6",
     "@types/jsbarcode": "^3.11.4",
@@ -99,7 +84,25 @@
     "typescript-eslint": "^8.31.1",
     "vite": "^5.4.14",
     "vite-plugin-dts": "^4.5.4",
+    "vitepress": "^1.6.4",
     "vitest": "^4.1.5",
     "vue-tsc": "^3.2.6"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "vue-tsc -b && vite build",
+    "preview": "vite preview",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "release:patch": "pnpm test && pnpm build && pnpm version patch",
+    "release:minor": "pnpm test && pnpm build && pnpm version minor",
+    "release:major": "pnpm test && pnpm build && pnpm version major",
+    "lint": "eslint src/lib/",
+    "lint:fix": "eslint src/lib/ --fix",
+    "license:gen": "node scripts/gen-license.mjs",
+    "docs:dev": "vitepress dev docs-site",
+    "docs:build": "vitepress build docs-site",
+    "docs:preview": "vitepress preview docs-site"
   }
-}
+}

package/dist/html2canvas-CIl29z_V.js

@@ -1,26 +0,0 @@
-import { a as c } from "./index-EE5FdcwR.js";
-import { r as f } from "./html2canvas-DrQHzW4S.js";
-function l(r, n) {
-  for (var o = 0; o < n.length; o++) {
-    const e = n[o];
-    if (typeof e != "string" && !Array.isArray(e)) {
-      for (const t in e)
-        if (t !== "default" && !(t in r)) {
-          const a = Object.getOwnPropertyDescriptor(e, t);
-          a && Object.defineProperty(r, t, a.get ? a : {
-            enumerable: !0,
-            get: () => e[t]
-          });
-        }
-    }
-  }
-  return Object.freeze(Object.defineProperty(r, Symbol.toStringTag, { value: "Module" }));
-}
-var s = f();
-const i = /* @__PURE__ */ c(s), u = /* @__PURE__ */ l({
-  __proto__: null,
-  default: i
-}, [s]);
-export {
-  u as h
-};