# @casoon/renderreport
[](https://github.com/casoon/renderreport/actions/workflows/ci.yml)
[](https://crates.io/crates/renderreport)
[](https://docs.rs/renderreport)
[](LICENSE-MIT)
[](https://www.rust-lang.org)
> ⚠️ **Early Development Stage** - This project is in active early development. APIs may change, and some features are still being implemented and optimized.
Data-driven report generation with Typst as embedded render engine.
Build professional PDF reports without learning Typst. Use components, themes, and template packs to create reports from structured data.
## Features
- **Component-based**: Build reports using pre-built components (ScoreCard, Finding, Table, etc.)
- **Theme Tokens**: CSS-variable-like theming system for consistent styling
- **Template Packs**: Extend with custom templates and components
- **Embedded Typst**: No CLI dependency, Typst runs as a library
- **Type-safe**: Full Rust API with compile-time guarantees
## Quick Start
```rust
use renderreport::prelude::*;
fn main() -> renderreport::Result<()> {
let engine = Engine::new()?;
let report = engine
.report("default")
.title("My Report")
.add_component(ScoreCard::new("Quality", 95))
.add_component(Finding::new(
"Issue Found",
Severity::Medium,
"Description of the issue"
))
.build();
let pdf = engine.render_pdf(&report)?;
std::fs::write("report.pdf", pdf)?;
Ok(())
}
```
## Installation
Add to your `Cargo.toml`:
```toml
[dependencies]
renderreport = "0.1"
```
## Components
**59+ production-ready components** organized into 8 semantic categories:
1. **Layout & Structure** — Section, Grid, Columns, FlowGroup, PageBreak
2. **Text & Editorial** — TextBlock, Label, Eyebrow
3. **Metrics & KPIs** — ScoreCard, Gauge, BigNumber, TrendTile, ProgressBar
4. **Data & Comparison** — AuditTable, ComparisonBlock, Crosstab, PivotTable
5. **Narrative & Storytelling** — Finding, QuoteBlock, WhyItMatters, ProblemSolution, BeforeAfter
6. **Infographics** — ProcessFlow, Timeline, Funnel, RoadmapBlock, PhaseBlock
7. **Marketing & Sales** — ProductHero, FeatureGrid, BenefitStrip, CTABox, PricingCard, Testimonial, UseCaseCard
8. **Media & Assets** — Image, Barcode, Sparkline, Chart, List, FaqList, GlossaryList
→ See [COMPONENTS.md](./COMPONENTS.md) for complete reference with examples.
## Patterns
Pre-configured report structures for common use cases:
- **AuditPattern** — Security/compliance audits (findings, impact, roadmap, CTA)
- **MarketingPattern** — Product showcases (hero, features, comparison, testimonials, pricing)
- **ExecutivePattern** — C-level summaries (metrics, top findings, recommendation, timeline)
| `Divider` | Horizontal separator line | BIRT Band Elements |
| `Watermark` | Background watermark text | Pentaho Watermark |
| `PageBreak` | Force page break | BIRT Page Setup |
### Chart Components
Visualize data with comprehensive chart types inspired by JasperReports Chart Components:
| `Chart` | Full-featured charts | Bar, Line, Pie, Area, Scatter, Radar |
| `Sparkline` | Inline mini-charts | Line, Bar |
| `Gauge` | Progress/metric meters | Circular, Thermometer, Horizontal |
### Data Analysis Components
Complex data aggregation inspired by BIRT Cross Tabs and JasperReports Crosstabs:
| `Crosstab` | Dynamic pivot table with aggregation | Sales by Region × Product |
| `PivotTable` | Pre-aggregated pivot display | Summary reports |
### Barcode Components
Generate barcodes in multiple formats (inspired by JasperReports Barcode and Pentaho):
| `Barcode` | Code128, Code39, EAN-13, EAN-8, UPC-A, UPC-E, QR Code, Data Matrix, PDF417, ITF, Codabar |
### Text & Field Components
Simple text display inspired by BIRT and Pentaho field elements:
| `Label` | Simple styled text | Headings, captions |
| `Text` | Multi-line text block | Paragraphs, descriptions |
| `NumberField` | Formatted numbers | Currency: $1,234.56, Percentage: 87.5% |
| `DateField` | Formatted dates | 2024-03-15, 15.03.2024, 03/15/2024 |
| `ResourceField` | Localized strings | i18n support |
## Theming
```rust
use renderreport::theme::{Theme, TokenValue};
let mut theme = Theme::new("brand", "Brand Theme");
theme.tokens.set("color.primary", TokenValue::Color("#1a56db".into()));
theme.tokens.set("color.ok", TokenValue::Color("#059669".into()));
let report = engine.report("default")
.theme(theme)
// ...
```
See [docs/CONVENTIONS.md](docs/CONVENTIONS.md) for all available tokens.
## Template Packs
Load external packs for specialized reports:
```rust
engine.load_pack("seo-audit")?;
let report = engine
.report("seo-audit")
.pack("seo-audit")
// ...
```
Create your own packs with custom templates and components. See [@casoon/renderreport-packs](https://github.com/casoon/renderreport-packs).
## Project Structure
```
renderreport/
├── src/
│ ├── lib.rs # Main library entry
│ ├── engine/ # Core rendering engine
│ ├── components/ # Standard components
│ ├── theme/ # Theme & token system
│ ├── pack/ # Pack loading system
│ ├── render/ # Typst compilation
│ └── vfs/ # Virtual filesystem
├── templates/ # Built-in Typst templates
├── packs/ # Bundled template packs
├── examples/ # Usage examples
└── docs/ # Documentation
```
## Roadmap
### Phase 1: MVP (Current)
- [x] Core engine with Typst integration
- [x] Standard component library
- [x] Theme token system
- [x] Basic pack loading
- [ ] Full test coverage
### Phase 2: Pack System
- [ ] Pack validation & versioning
- [ ] Remote pack loading
- [ ] Pack registry
### Phase 3: Ecosystem
- [ ] Preview server for development
- [ ] Visual regression tests
- [ ] HTML output (experimental)
- [ ] WASM support
## Related Projects
- [@casoon/renderreport-packs](https://github.com/casoon/renderreport-packs) - Official template packs
- [@casoon/renderreport-examples](https://github.com/casoon/renderreport-examples) - Demo applications
## License
MIT OR Apache-2.0