Smart Report

Smart Report is a browser-based, framework-independent TypeScript report engine. It renders JSON report templates and data contexts into printable HTML pages and includes an embeddable visual designer.

The runtime relies on real browser DOM measurement and CSS layout. It is not a server-side renderer and does not generate PDF files directly.

Install

npm install @jeasonduan/smart-report

Import the runtime stylesheet explicitly:

import '@jeasonduan/smart-report/report.css'
import { createReport, type ReportContext, type TemplateConfig } from '@jeasonduan/smart-report'

const template: TemplateConfig = {
  schemaVersion: 1,
  printMode: 'list',
  pages: [
    {
      layout: {
        width: 210,
        height: 297,
        padding: { top: 10, right: 10, bottom: 10, left: 10 },
        colCount: 1,
        rowCount: 1,
      },
      dataContent: {
        rows: [{ cells: [{ type: 'text', value: '{{ data.name }}' }] }],
      },
    },
  ],
}

const source: ReportContext = {
  params: {},
  info: {},
  summary: {},
  data: [{ name: 'Ada Lovelace' }],
}

const report = createReport({ template, source })
report.mount(document.querySelector('#report')!)

Call report.destroy() when the host view is removed. mount(), render(), and update() are synchronous and return page and warning information.

Call report.print() to print only that mounted report instance. During printing, Smart Report temporarily moves the report into an isolated document-level print portal, hides unrelated page content and other report instances, and restores the original DOM afterwards. Calling the browser's Print command directly does not activate this isolation. Only one report can be printed per document at a time; a nested call throws REPORT_PRINT_IN_PROGRESS.

Designer

The designer is a separate entry. Its preview uses the runtime, so load both stylesheets:

import '@jeasonduan/smart-report/report.css'
import '@jeasonduan/smart-report/designer.css'
import { createDesigner } from '@jeasonduan/smart-report/designer'

const designer = createDesigner({
  template,
  controlSize: 'small',
})

designer.mount(document.querySelector('#designer')!)
designer.on('change', ({ template: nextTemplate }) => {
  console.log(nextTemplate)
})

The runtime root does not re-export designer APIs. The designer owns its DOM, dialogs, preview report, messages, and event listeners, so multiple instances can share one page.

The report preview dialog includes a printer button after a preview renders successfully. It calls the preview report's isolated print() lifecycle; use this button instead of the browser's direct Print command when printing from the designer.

Data Modes

• list: pass one ReportContext; records flow continuously across pages.
• single: pass one ReportContext; each data record consumes the configured template pages.
• batch: pass an array of ReportContext objects. Grouping is the caller's responsibility.

Bindings use the restricted form {{ data.field | formatter }}. Formatters and plugin cells are registered per report instance and must run synchronously.

Package Entries

| Entry | Purpose | | --------------------------------------------------------- | ----------------------------------------------------- | | @jeasonduan/smart-report | Runtime API, template types, validation, and bindings | | @jeasonduan/smart-report/designer | Visual designer API | | @jeasonduan/smart-report/report.css | Runtime and print styles | | @jeasonduan/smart-report/designer.css | Designer shell styles | | @jeasonduan/smart-report/schema/report-template.v1.json | Version 1 JSON Schema |

UMD bundles are included under dist/smart-report.umd.cjs and dist/smart-report-designer.umd.cjs, exposing SmartReport and SmartReportDesigner respectively.

Security And Limits

• Template data is validated against the bundled v1 JSON Schema.
• Bindings do not execute JavaScript, Liquid tags, prototype-chain paths, or raw HTML.
• Plugin renderers are the only extension point that may return DOM nodes. Treat plugins as trusted code.
• Pagination requires browser layout measurements and is unavailable during SSR.
• Chrome and Edge are the reference browsers for print layout. Firefox and Safari should be tested for each report design.
• PDF, Excel, charts, images, barcodes, data-source connections, and framework adapters are outside the current v1 scope.

Development

npm ci
npm run check
npm run build
npm run test:package

Detailed Chinese documentation is available in doc/. Formal publishing requires explicit authorization and is not performed by the build scripts.

License

Apache License 2.0. See LICENSE.