graphitepdf-layout 0.2.0

Minimal layout planning primitives for GraphitePDF.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106

<p align="center">
  <img src="https://tvnzqqaaq45nrfqc.public.blob.vercel-storage.com/graphite_pdf/graphitepdf-logo-oss.png" alt="GraphitePDF logo" width="560" />
</p>

<p align="center">
  <strong>The canonical layout engine and safe layout tree for the GraphitePDF workspace.</strong>
</p>

<p align="center">
  <img alt="Crate" src="https://img.shields.io/badge/crate-graphitepdf--layout-1E1E1C?style=for-the-badge&labelColor=060604&color=D4581A" />
  <img alt="Focus" src="https://img.shields.io/badge/focus-layout_%7C_pagination_%7C_safe_tree-C4C4C0?style=for-the-badge&labelColor=2E2E2C&color=3A3A38" />
  <img alt="Rust" src="https://img.shields.io/badge/rust-1.85%2B-F58040?style=for-the-badge&labelColor=2E2E2C&color=7C2806" />
</p>

---

## Overview

`graphitepdf-layout` is the canonical layout layer for GraphitePDF.

It combines page sizing, style resolution, inheritance, asset sizing, text layout, SVG and math resolution, pagination, origin assignment, and z-index ordering into a safe layout tree used by downstream rendering.

---

## Scope

`graphitepdf-layout` contains:

- authoring types such as `Document`, `Page`, `Node`, and `LayoutStyle`
- the ordered layout pipeline in `ORDERED_PIPELINE`
- `SafeLayoutDocument`, `SafeLayoutPage`, and `SafeLayoutNode`
- `LayoutEngine` for turning document input into positioned layout output

---

## Installation

```bash
cargo add graphitepdf-layout
```

---

## API Summary

| Category | Items |
| --- | --- |
| Authoring types | `Document`, `Page`, `Node`, `NodeKind`, `LayoutMetadata` |
| Style and spacing | `LayoutStyle`, `EdgeInsets` |
| Pipeline | `ORDERED_PIPELINE`, `LayoutPipelineStep`, `LayoutEngine` |
| Safe output | `SafeLayoutDocument`, `SafeLayoutPage`, `SafeLayoutNode`, `SafeNodeKind`, `SafeLayoutStyle`, `SafeFont` |
| Legacy compatibility | `LayoutDocument`, `LayoutPage`, `LayoutNode`, `LayoutContent` |

---

## Example

```rust
use graphitepdf_font::{FontSource, StandardFont};
use graphitepdf_layout::{Document, EdgeInsets, LayoutEngine, LayoutStyle, Node, Page};
use graphitepdf_primitives::{Color, Pt, Size};
use graphitepdf_textkit::{TextBlock, TextSpan};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let title = TextBlock::from(TextSpan::new("GraphitePDF layout")?);

    let document = Document::new().with_page(
        Page::new([
            Node::text(title).with_style(
                LayoutStyle::new()
                    .with_font_family("Helvetica")
                    .with_font_source(FontSource::standard(StandardFont::HelveticaBold))
                    .with_font_size(Pt::new(18.0))
                    .with_color(Color::rgb(0x17, 0x2b, 0x4d)),
            ),
        ])
        .with_size(Size::new(420.0, 180.0))
        .with_style(LayoutStyle::new().with_padding(EdgeInsets::all(Pt::new(24.0)))),
    );

    let layout = LayoutEngine::new().layout_document(&document)?;
    assert_eq!(layout.pages().len(), 1);
    Ok(())
}
```

---

## Design Principles

- keep layout policy centralized in one canonical crate
- represent downstream-safe geometry and style explicitly
- make pipeline stages inspectable and testable
- integrate text, image, SVG, and math handling without binding directly to PDF output

---

## Role In GraphitePDF

This crate is the bridge between authoring inputs and rendering. Everything that needs positioned, paginated, and inherited scene data should flow through `graphitepdf-layout`.

---

## License

MIT