RavenRS Reporting — design and roadmap

Status: phase R1 done, 2026-11-01.

RavenRS Reporting turns data into paginated documents. It covers what a complete commercial reporting suite covers: a report engine, a document viewer, exports, an end-user report designer and a report server. Everything is in Rust and runs on desktop, in the browser (WebAssembly) and on servers.

Goals#

• One engine everywhere. The same report definition renders identically in the desktop viewer, the browser viewer, a PDF on a server and a test.
• Reports are data. A report is a JSON document (*.rvreport.json) that can be designed visually, stored in a database, versioned in git and generated by code or AI.
• Pixel-exact output. Layout is computed once into a Document of positioned primitives in points. Every exporter and the viewer draw that same document.
• Commercial depth. The bands, expressions, summaries, master-detail and controls a business report needs (invoices, statements, labels, ledgers, dashboards), with tests and performance budgets like the rest of RavenRS.

Architecture#

            report definition (JSON or Rust builder)      data (JSON, Rust structs, SQL, CSV/XLSX)
                              │                                   │
                              ▼                                   ▼
  ravenrs-report ──┬─ ravenrs-criteria ── data binding ── grouping/sorting/summaries
                   └─ ravenrs-graphics ── vector shapes, chart layout, barcodes
        │
        ▼  pagination (Parley text measurement, keep-together, page breaks, can-grow/shrink)
   Document (pages of positioned text, rects, lines, paths, images, links; in points)
        │
        ├── ravenrs-report-export  One entry point for all of these: format, file name, media type
        ├── ravenrs-report-pdf     PDF 1.7 / PDF/A-2b, embedded font subsets, links, outline (pdf-writer + subsetter)
        ├── ravenrs-report-xlsx    XLSX (rust_xlsxwriter), CSV, HTML, SVG/PNG
        ├── ravenrs-report-viewer  DocumentViewer and ParameterPanel: pages, zoom, thumbnails, search
        ├── ReportDesigner         (on the Ribbon): bands, field list, properties, drag and drop, undo/redo
        └── ravenrs-report-server  HTTP: POST a definition + data, get PDF/XLSX back

Today ravenrs-report, ravenrs-criteria, ravenrs-graphics, ravenrs-report-export, ravenrs-report-pdf, ravenrs-report-xlsx (XLSX and CSV) and the designer in examples/report-designer exist. ravenrs-report-server runs them headless (docs/REPORT-SERVER.md). ravenrs-report-viewer shows documents and asks for parameters. The other exporters arrive in the phases below.

ravenrs-report has no GPU or window dependency, so it runs in servers and tests. Text is measured with the same Parley stack as the UI, so the viewer and the PDF agree to the point.

Report model#

• Page. Size (A4, Letter, Legal, custom), orientation, margins, watermark (text or image).
• Bands.
  • Report: Report Header and Report Footer.
  • Page: Page Header and Page Footer.
  • Groups: Group Header and Group Footer, nested, each with its group field and sort.
  • Detail.
  • Detail Report: master-detail with its own bands, related by key.
  • Band behavior:
    • Keep-together, page break before and after.
    • "Repeat on every page" for headers.
    • Print on first page / last page.
• Controls.
  • Text and data:
    • Label, with static text or an expression.
    • Rich Text: simple markup — bold, italic, links, lists.
    • Check Box.
    • Page Info: page n of N, date, user.
  • Containers:
    • Table, with rows, cells and spans.
    • Panel.
    • Sub-report.
    • Cross-band line and box.
    • Table of contents.
  • Graphics: Picture (PNG, JPEG, SVG), Line, Shape.
  • Barcodes: Code 128, Code 39, EAN-13, EAN-8, UPC-A, ITF, QR, Data Matrix, PDF417.
  • Data visualization:
    • Chart: bar, line, area, pie, doughnut, scatter.
    • Sparkline.
    • Gauge.
    • Cross Tab (pivot).
• Expressions. The ravenrs-criteria language, reusable by other modules:
  • Fields and parameters: [Price] * [Quantity], ?Customer.
  • Conditionals: Iif([Total] > 1000, 'VIP', 'Regular').
  • Aggregates: Sum([Total]), Count(), Avg, Min, Max, RunningSum, scoped to group, page or report.
  • Text and dates: FormatString('{0:C}', [Total]), Today(), AddDays, Concat, Upper and others.
  • Expressions drive visibility, formatting rules (conditional styles), sorting, filtering and calculated fields.
• Parameters.
  • Kinds: typed values (text, number, date, boolean, list).
  • Defaults, required flags and multi-value parameters.
  • The viewer shows a parameter panel.
• Styles. Named styles, odd/even rows, conditional formatting. Built-in themes follow the RavenRS tokens and print well.
• Localization. Number, date and currency formats per culture (pt-BR first-class); report strings can be translated.

Data#

1. JSON and Rust structs (anything serde::Serialize), with nested arrays for master-detail.
2. SQL: PostgreSQL, MySQL and SQL Server. Each source has queries with parameters, and the report binds to their results. This lives behind a sql feature, so the WebAssembly build stays small.
3. CSV and Excel files.
4. Federation: join several sources and define master-detail relationships between them.

Delivery phases#

Each phase ends with tests, docs, demos and scripts/check.sh green, like every RavenRS feature. REPORTING-PARITY.md tracks every feature of a complete reporting suite against these phases.

Server and scheduled delivery#

ravenrs-report-server runs reports headless with the same engine and layouts:

• Storage. Layouts (*.rvreport.json, data sources included) are stored by the server and versioned; opening and saving them from the designer is planned.
• Data at run time.
  • The server resolves url data sources when a report runs, only from hosts in its configuration; sql sources are planned.
  • Connections and secrets live in the server's configuration, referred to by name, and never in a layout.
• Render on demand. An HTTP API: POST /render with a layout (or its name), parameters and a format returns PDF or XLSX.
• Scheduled jobs, following the job model report servers use:
  • A cron-like schedule.
  • A report and its parameter values, fixed or by expression (for example, last month).
  • Recipients, individually or on one shared email.
  • Delivery as a PDF, XLSX or CSV attachment or a file in a folder; inline HTML and a link are planned.
  • A skip-if-empty option and document retention.
  • A run history of who received what, and retries on failure.

Decisions#

• Logic that more than one engine can use lives in a shared crate. ravenrs-criteria (expressions), ravenrs-graphics (shapes, charts, barcodes) and ravenrs-report-export (files) know nothing about who calls them, so reports, the UI and later modules cannot drift apart.
• Own engine, not a port. The model uses the concepts report authors already know (bands, criteria-style expressions) so they feel at home, but the format is JSON and the code is ours.
• pdf-writer + subsetter (MIT/Apache, used by Typst) instead of a homemade PDF serializer: proven output, small, no C dependencies.
• rust_xlsxwriter (MIT/Apache) for XLSX.
• XLSX cells come from the Document, not the data. A text box keeps the value behind its text, so a spreadsheet gets real numbers and dates on a grid that matches the page. Pages flow into one sheet; the page header prints once and page footers, whose page numbers would mean nothing there, are left out.
• Points (1/72 in) as the document unit; the viewer scales to the screen.
• Layout separate from rendering: the paginator produces a Document once, and the viewer and every exporter consume it, so they cannot drift apart.

Showing pages elsewhere#

PageFan (in ravenrs-report-viewer) shows real pages of rendered documents spread like a hand of cards, for pages that present reporting: each page is painted once with paint_page and reused, opens as the fan scrolls into view, comes forward under the pointer or keyboard focus, and opens its address when clicked.