laser-pdf

A Rust library for programmatic PDF generation with precise, predictable layout control.

laser-pdf is designed for applications that need to reproduce layouts with pixel-perfect accuracy, providing fine-grained control over page breaking and element positioning. Built for Escola to generate complex PDFs with predictable behavior.

Key Features

• Predictable Layout System: Inspired by Flutter's layout protocol for consistent, understandable behavior
• Precise Page Breaking Control: Elements like Titled, RepeatAfterBreak, and PinBelow for exact control over multi-page layouts
• Composable Element Architecture: Simple trait-based system for building complex layouts from primitive components
• Axis-Independent Collapse: Elements can collapse separately on horizontal and vertical axes, with per-location vertical collapse
• Multiple Font Systems: Support for built-in PDF fonts and TrueType fonts with advanced text shaping
• JSON Serialization: Complete serde support for language-agnostic PDF generation
• SVG and Image Support: Render SVG graphics and raster images with precise positioning

Design Philosophy

Unlike CSS, which can sometimes produce unexpected layouts, laser-pdf prioritizes predictability. Once you understand the relatively simple Element trait, you can easily predict how layouts will behave. Elements follow clear composition rules, and the collapse behavior is well-defined and consistent.

Quick Start

(These instructions might need some work. Don't fully trust them yet.)

Rust API

(A simple function convenient multi-page generation is still missing.)

use laser_pdf::*;
use laser_pdf::elements::{text::Text, column::Column, padding::Padding};
use laser_pdf::fonts::builtin::BuiltinFont;

// Create a PDF document
let mut pdf = Pdf::new();

// Add a page
let location = pdf.add_page((210., 297.)); // A4 size in mm

// Create fonts
let font = BuiltinFont::helvetica(&mut pdf);

// Build elements
let title = Text::basic("Document Title", &font, 16.0);
let body = Text::basic("This is the document body content.", &font, 12.0);

// Compose layout
let content = Column {
    gap: 10.0,
    collapse: true,
    content: |content| {
        content
          .add(&Padding::all(title, 5.0))?
          .add(&body)?;

        // Returns an option to support short-circuiting.
        None
    }
};

// Draw to PDF
let ctx = DrawCtx {
    pdf: &mut pdf,
    width: WidthConstraint { max: 200.0, expand: true },
    location,
    first_height: 280.0,
    preferred_height: None,
    breakable: None, // For single-page layout
};

content.draw(ctx);

// Save PDF
std::fs::write("output.pdf", pdf.finish())?;

CLI Usage (JSON Interface)

echo '{
  "title": "My Document",
  "entries": [{
    "size": [210, 297],
    "fonts": {
      "regular": "./fonts/regular.ttf"
    },
    "element": {
      "type": "Column",
      "gap": 10,
      "content": [
        {
          "type": "Text",
          "text": "Hello, World!",
          "font": "regular",
          "size": 16
        }
      ]
    }
  }]
}' | cargo run > output.pdf

Core Concepts

Element Trait

All layout components implement the Element trait with three key methods:

• first_location_usage(): Determines if the element will use the first location on a page
• measure(): Calculates dimensions given width constraints
• draw(): Renders the element to the PDF

Page Breaking

Elements can intelligently break across pages using the breakable draw context. Advanced elements like Titled ensure titles stay with their content, while RepeatAfterBreak can repeat headers on each page.

Collapse Behavior

Elements can collapse on each axis independently. When an element collapses in the direction of a container (like a Column), gaps around it are eliminated - similar to how display: none interacts with CSS Grid's gap property.

Available Elements

Layout Elements

• Column / Row: Vertical/horizontal stacking with gaps
• Stack: Layered positioning
• Padding: Add space around elements
• HAlign: Horizontal alignment control

Content Elements

• Text: Simple text rendering with built-in fonts
• RichText: Advanced text with TrueType fonts and text shaping
• Image: Raster image embedding
• SVG: Vector graphics rendering
• Rectangle / Circle: Basic shapes

Page Flow Elements

• Page: Force page boundary
• ForceBreak: Insert page breaks
• BreakWhole: Keep element groups together
• Titled: Keep titles with content
• RepeatAfterBreak: Repeat elements after page breaks
• PinBelow: Pin elements to page bottom

Advanced Elements

• ShrinkToFit: Scale content to fit constraints
• ExpandToPreferredHeight: Grow to fill available space
• ChangingTitle: Dynamic page titles

Current Status

⚠️ Pre-1.0: The library is under active development. While used in production at Escola, the API may change before the 1.0 release. Element names and some APIs are still being refined.

Roadmap to 1.0:

• Finalize element naming conventions
• Publish to crates.io
• Release PHP bindings as open source
• Complete documentation

Development

Building

cargo build --verbose

Testing

# Run all tests
cargo test --verbose

# Run specific test
cargo test test_name

# Update snapshots
cargo insta review

Contributing

The project uses insta for snapshot testing, including binary PDF snapshots for visual regression testing.

License

Licensed under the MIT License.

Used By

• Escola - Production PDF generation for educational documents

Built with ❤️ for precise, predictable PDF layouts