nrb 4.1.0

A responsive Flutter table and report builder with local Excel, PDF, Word exports, JSON-to-Excel, nested headers, and editable data grids.

📊 nrb (Nexora Report Builder)

A customizable and highly responsive Flutter data grid and report builder designed for complex nested headers, dynamic data visualization, and professional exports.

Ideal for enterprise dashboards, inventory tracking, financial reports, or structured data-entry UIs.

🚀 Try it live in your browser: Interactive Web Demo

---

📸 Capabilities at a Glance

Editable Data Grids

Local & Cloud Exporting

---

✨ Core Features

• 📱 Fully Responsive: Columns auto-scale and expand to fill screen space based on content.
• 📌 Freeze Panes: Sticky left-side columns and complex multi-row nested headers.
• ✍️ Editable Grids: Mix TextCell with interactive TextFieldCell for data-entry forms.
• 💰 Smart Formatting: Advanced NRBNumberFormatter for International and Indian currencies.
• 📏 Dynamic Resizing: Drag column edges to resize or double-click to auto-fit.
• 📥 Local Export (FREE): Generate Excel (.xlsx), PDF (.pdf), and Word (.docx) directly on the user device with no API key.
• ⚡ Native Background Processing: Local binary generation runs in a worker isolate on native platforms. Web uses the browser event loop.
• ☁️ Cloud Export (Optional): Existing API-key/subscription export remains available for applications that prefer server-side processing.

---

🚀 Getting Started

Add the dependency to your pubspec.yaml:

dependencies:
  nrb: ^4.1.0

💡 Use Case 1: Free Local Excel / PDF / Word

Leave apiKey null, empty, or whitespace-only. No packageName is required in local mode. NRB keeps the same existing draggable export FAB used by subscription mode:

NRB FAB → Share Report / Download Report → Excel / PDF / Word

NrbTableEngine(
  reportName: "Local_Monthly_Report",
  enableDownload: true,
  showDownloadFloatingButton: true,
  apiKey: "", // null/blank = fully local export
  headers: [ /* Your Headers */ ],
  tableData: [ /* Your Data */ ],
)

The format chooser displays a short notice that the selected file will be processed on the user's device and large reports can take longer. NRB copies the Flutter report into a plain export snapshot in small chunks, then hands XLSX/DOCX/PDF binary construction to Flutter's background-compute path on native platforms. This keeps heavy file assembly away from the UI isolate while preserving the existing export interaction.

Local export uses the same NRB payload semantics as the cloud path: header row/column spans, foreground/background colors, alignment, bold/italic header metadata, column widths, values, and report name are carried into the generated file.

On Web, Flutter's compute runs on the current event loop. NRB does not use a Web Worker; a large export can temporarily pause browser interaction. Native exports move JSON normalization and file assembly into worker isolates. Results are held in memory, so practical report size depends on available device memory.

Local PDF embeds bundled Noto fonts and shapes Bangla (Bengali) conjuncts, reph, and vowel signs. Latin, Greek, and Cyrillic are also supported, including mixed-language cells. Bengali supports regular/bold; italic Bengali uses the upright font. Other scripts and unsupported symbols cause a clear error; use Excel or Word for those characters. Fonts are bundled, with no font download or report upload. PDF repeats branding, table headers, and page numbers, wraps long cells, and splits oversized rows across pages. Wide tables use wider PDF pages. Bangla source text is retained in PDF ActualText spans; PDFium text extraction is tested. Copy/search results depend on the reader: MuPDF can split or duplicate some complex-script text.

Excel retains numeric amounts and decimal formatting where safe. Leading-zero identifiers and numbers exceeding Excel's 15-digit precision are stored as text. JSON string values remain strings, and JSON booleans become Excel boolean cells. Word retains horizontal/vertical header merges and uses landscape pages for wide tables, scaling exceptionally wide tables to Word's page-size limit.

💡 Use Case 2: API-Key / Subscription Export

Pass a non-empty API key to preserve the existing NRB feature lookup and server-side export behavior.

NrbTableEngine(
  packageName: "com.your.app",
  apiKey: "YOUR_API_KEY",
  enableDownload: true,
  headers: [ /* Your Headers */ ],
  tableData: [ /* Your Data */ ],
)

Both modes use the same NRB export payload semantics for header spans, colors, text colors, alignment, bold styling, widths, and report data. Supplying an API key does not change the table UI; it only changes where file generation runs.

Local mode note shown to users: “This file will be processed on your local device. Large reports may take a little longer, but your report data is not sent to the NRB server.”

---

📊 Beautiful Native Charts

nrb includes a suite of physics-based, animated charts optimized for report dashboards.

View Supported Chart Types

• Multi-Line Chart: Interactive trends with tooltips.
• Segmented Gauge: KPI achievement visualization.
• Scatter Plot: Data correlation tracking.
• Histogram & Pie Charts: Distribution analysis.
• Donut Cards & Metric Cards: Compact summary widgets.

---

💾 Standalone JSON → Excel

Export ordinary API JSON to Excel without creating an NrbTableEngine. With a null/empty API key the workbook is generated locally; with a non-empty key NRB keeps the existing feature lookup and server-processing flow.

Return the Excel binary

import 'dart:typed_data';
import 'package:nrb/nrb.dart';

final Uint8List bytes = await NRBJsonToExcel(
  apiResponseJson,
  apiKey: '', // packageName is not required for local Excel
  fileName: 'customer_report',
);

NRBJsonToExcel(...) returns the generated .xlsx bytes, so the caller can save, upload, share, or process the file independently.

Use Flutter 3.32 / Dart 3.8 or newer. packageName is optional for local conversion and is required only when a non-empty API key selects the registered subscription/server flow. NrbJsonToExcel.convert(...) and NRBJsonToExcel(...) share the same behavior.

Common Download floating action button

Scaffold(
  body: YourExistingScreen(),
  floatingActionButton: NRBJsonToExcelButton(
    json: apiResponseJson,
    apiKey: '', // packageName is not required in local mode
    fileName: 'customer_report',
  ),
);

If your API response keeps the row list under a non-standard key, specify it explicitly:

NRBJsonToExcelButton(
  json: response,
  dataKey: 'customerList',
  apiKey: '', // packageName is not required in local mode
)

The binary API accepts the same dataKey: 'customerList' argument. Without it, the converter checks data, items, results, records, and rows, then the first list of objects under another key. Otherwise, the input map becomes one row. An explicit dataKey must exist and contain a list.

Nested JSON objects become dot-notation columns (for example, customer.name). Headers include keys from every row in first-seen order. Missing/null fields become empty cells; arrays and empty nested objects become JSON text. Primitive or mixed row lists use one value column. An empty object or collection exports a No Data header and No data available row. Strings, booleans, finite numbers, Unicode, and Bangla text are supported.

The API propagates network/server errors. Invalid JSON values, cycles, nesting deeper than 100 levels, and colliding dot-notation fields throw FormatException. A blank/null API key deliberately selects local conversion; it is not an error. An invalid dataKey throws ArgumentError in either mode. Server mode also requires a nonblank packageName. Empty/non-ZIP server responses are rejected. Callers of the binary API should handle errors with try/catch.

The button prevents repeated taps while preparing the file and supports onCompleted / onError callbacks. Completion means the native file was saved or the browser download was started; browsers cannot confirm that a user kept the file. Callbacks are suppressed after the widget is disposed. Filenames are sanitized and receive exactly one .xlsx extension.

Native downloads use the desktop Downloads folder or app documents. Android first attempts public Downloads and falls back to app storage if scoped storage denies the write. Web downloads use the browser's download flow. Applications should present the returned save location or the button's success message to users.

---

🛠 Advanced Customization

Generate bytes from an export payload

NrbLocalExporter.generate accepts the plain NRB export payload and returns bytes without saving them. Initialize Flutter before calling it; PDF uses the package's bundled font assets.

final bytes = await NrbLocalExporter.generate(
  format: NrbLocalExportFormat.pdf, // excel or word also available
  payload: {
    'report_name': 'Sales / বিক্রয়',
    'column_widths': [180, 110],
    'structure': {
      'headers': [
        [
          {'text': 'Product', 'bg_hex': '0F766E', 'fg_hex': 'FFFFFF'},
          {'text': 'Amount', 'bg_hex': '0F766E', 'fg_hex': 'FFFFFF'},
        ],
      ],
    },
    'data': [
      [
        {'value': 'বাংলা বই'},
        {'value': '125000.50', 'align': 'right', 'is_bold': true},
      ],
    ],
  },
);

Headers accept row_span and col_span; style fields include is_bold, is_italic, bg_hex, fg_hex, and align. Widths are logical pixels. For Excel, set value_type: 'string' on a body cell to keep a numeric-looking value as text. Pass ordinary maps, lists, and primitive values and keep them unchanged until the returned future completes.

Number Formatting

TextCell(
  itemContent: "1099493.5",
  isAmount: true,
  numberFormatType: CellNumberFormat.indian, // 10,99,493.50
  roundTo: 2,
)

Complex Headers (ColSpan/RowSpan)

headers: [
  [
    NrbHeaderCell(text: "Group A", colSpan: 2, backgroundColor: Colors.blue),
    NrbHeaderCell(text: "Group B", colSpan: 3, backgroundColor: Colors.green),
  ],
  [
    NrbHeaderCell(text: "Sub 1"), NrbHeaderCell(text: "Sub 2"),
    NrbHeaderCell(text: "Sub 3"), NrbHeaderCell(text: "Sub 4"), NrbHeaderCell(text: "Sub 5"),
  ]
]

---

📂 Example Output

---

📄 License

© 2025-2026 Innovate Nest Labs. Released under the Innovate Nest Labs Custom License. Commercial integration is permitted subject to the terms in the LICENSE file.

---

📬 Support

Found a bug or need a feature? Open a GitHub Issue.