Skip to content

Commit dfd587a

Browse files
authored
docs(readme): lead with v1.8, retire the v1.6 spotlight (#214)
* docs(readme): lead with v1.8, retire the v1.6 spotlight The README still centred on v1.6 while the v1.8 'illustrative' work (native charts, SVG, gradients) was buried in a single overlong release-status sentence, so the landing page lagged the engine. - Shrink the Release-status blurb to a one-liner that links to a new 'What's new in v1.8' section (chart preview + capability bullets, the fonts consumption change, and the ConfigLoader removal). - Replace 'What's in v1.6' / 'v1.6 primitives in 30 lines' with 'v1.8 primitives in 30 lines' — native chart, overshoot-free line, SVG import + block alignment, all lifted from runnable examples. - Correct the iText 7 comparison row: it has a high-level layout API, not just 'manual + helpers'. - Keep 'Cinematic by default' but ground it with the new primitives. * docs(readme): drop the redundant em-dash before the What's-new link
1 parent d709921 commit dfd587a

1 file changed

Lines changed: 40 additions & 32 deletions

File tree

README.md

Lines changed: 40 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@
1919
</p>
2020

2121
> **Release status** &mdash;
22-
> 🟢 **Latest stable**: [v1.8.0](https://github.com/DemchaAV/GraphCompose/releases/tag/v1.8.0) &mdash; codenamed **"illustrative"** (native vector charts — bar / line / pie + inline sparklines, monotone / smooth line interpolation, free-form `ShapeOutline.Path` clip, SVG path / icon import with native gradients, and a leaner publication — the bundled Google fonts split into the separate `graph-compose-fonts` artifact. Engine APIs stay source- & binary-compatible with v1.7; one consumption change — add `graph-compose-fonts` or `graph-compose-bundle` to keep the bundled fonts, see the [migration note](./docs/migration/v1.8.0-fonts.md).)
22+
> 🟢 **Latest stable**: [v1.8.0](https://github.com/DemchaAV/GraphCompose/releases/tag/v1.8.0) &mdash; codenamed **"illustrative"**: native vector charts, SVG &amp; gradient graphics, free-form clipping, and a leaner engine artifact. **[What's new in v1.8 &darr;](#whats-new-in-v18)**
2323
2424
> &nbsp;·&nbsp; 🟡 **In develop**: next cycle — open (see [CHANGELOG](./CHANGELOG.md))
2525
> &nbsp;·&nbsp; See [API stability policy](./docs/api-stability.md) for tier definitions.
@@ -46,11 +46,28 @@
4646

4747
- **Author intent, not coordinates.** Fluent DSL for sections, paragraphs, tables, lists, layer stacks, themes &mdash; the engine handles measurement, pagination, and rendering.
4848
- **Deterministic by design.** Two-pass layout. Snapshots are stable across machines, so layout regressions are catchable in tests before any byte ships.
49-
- **Cinematic-by-default.** `BusinessTheme` + soft panels + accent strips + transforms + advanced tables are first-class primitives, not workarounds.
49+
- **Cinematic by default.** `BusinessTheme`, soft panels, accent strips, transforms, native vector charts, and gradients are first-class primitives, not workarounds.
5050
- **PDFBox isolated, DOCX optional.** Single backend interface. Apache POI&ndash;backed DOCX export is available for compatible semantic content &mdash; see [support matrix](#output-support) for limitations.
5151

5252
Sits between **iText** (low-level page primitives) and **JasperReports** (XML-template-driven layout): a Java DSL describes the document semantically, the engine renders.
5353

54+
## What's new in v1.8
55+
56+
The **"illustrative"** release &mdash; the engine gains a vector-graphics dimension.
57+
58+
<p align="center">
59+
<img src="./assets/readme/chart-showcase.png" alt="GraphCompose native vector charts" width="720"/>
60+
</p>
61+
62+
- **Native vector charts** &mdash; bar / line / pie, inline sparklines, and `MONOTONE` / `SMOOTH` line interpolation, drawn as native PDF Béziers (no rasterization): `section.chart(ChartSpec.line()&hellip;, style)`.
63+
- **SVG path &amp; icon import** &mdash; `SvgIcon.parse(svg)` turns SVG into native vector geometry; recolour per use and place with `addSvgIcon(icon, width, align)`.
64+
- **Gradients &amp; free-form clipping** &mdash; linear / radial `DocumentPaint` fills and arbitrary `ShapeOutline.Path` clip regions.
65+
- **Block-level alignment** &mdash; `addAligned(HorizontalAlign.CENTER, node)` centres or right-aligns any fixed node without a wrapper container.
66+
- **`keepTogether()` pagination** &mdash; keep a section from splitting across a page break.
67+
- **Leaner publication** &mdash; the bundled Google fonts moved to the independently-versioned `graph-compose-fonts` artifact, so the engine jar dropped from ~20&nbsp;MB to ~2&nbsp;MB. Pure-text / standard-14 documents need nothing extra; add `graph-compose-fonts` (or `graph-compose-bundle`) to keep the bundled families &mdash; see the [migration note](./docs/migration/v1.8.0-fonts.md).
68+
69+
Core document APIs stay source- and binary-compatible with v1.7 (`ConfigLoader` is the one removal). Full notes in [`CHANGELOG.md`](./CHANGELOG.md).
70+
5471
## Installation
5572

5673
**Requires Java 17+** (enforced by the build).
@@ -162,7 +179,7 @@ For a Spring Boot `@RestController` streaming the PDF straight to the response,
162179
|---|---|---|---|---|
163180
| **GraphCompose** | Java DSL, semantic nodes | Two-pass, deterministic, snapshot-testable | MIT | Code-first business documents with layout regression tests |
164181
| **PDFBox** | Low-level text / path primitives | Manual coordinates | Apache 2.0 | Direct PDF manipulation, parsing, extraction |
165-
| **iText 7** | Low-level page primitives + high-level helpers | Manual + helpers | AGPL / commercial | When AGPL is acceptable or you have a commercial licence |
182+
| **iText 7** | Object/layout API + low-level canvas | Automatic layout with direct-positioning options | AGPL / commercial | When AGPL is acceptable or you have a commercial licence |
166183
| **OpenPDF** | iText 4 fork | Manual + helpers | LGPL / MPL | Legacy iText 4 codebases |
167184
| **JasperReports** | XML templates compiled to `.jasper` | Template-driven | LGPL | Tabular reports with datasource bindings |
168185

@@ -181,47 +198,38 @@ GraphCompose uses PDFBox under the hood as the rendering backend &mdash; the com
181198

182199
> **Choosing a template surface** &mdash; layered (`cv.v2`), classic (`cv.presets`), or the built-in `*TemplateV2` family? See **[Which template system should I use?](./docs/templates/which-template-system.md)** for the status matrix, decision tree, and `classic → layered` migration map.
183200
184-
## What's in v1.6 &mdash; "expressive"
185-
186-
- **Layered templates** &mdash; 16 CV and 15 paired cover-letter presets on the layered `cv.v2` / `coverletter.v2` architecture (data → theme → components → widgets → presets), one-liner `create()` factories over a typed `CvDocument` / `CoverLetterDocument`. Inline markdown, multi-column layouts. The going-forward standard for new template families. See [`docs/templates/v2-layered/README.md`](./docs/templates/v2-layered/README.md). (The earlier `BusinessTheme`-based preset surface is now deprecated.)
187-
- **Composed primitives** &mdash; `ListBuilder.addItem(label, Consumer)` (nested lists), `DocumentTableCell.node(...)` (any node inside a cell), `CanvasLayerNode` (pixel-precise free-canvas placement).
188-
- **Architecture hardening** &mdash; `@Internal` API stability marker, public `PdfFragmentRenderHandler` SPI, `DocumentRenderingException` on the convenience render path, documented thread-safety contract.
189-
190-
Full notes in [`CHANGELOG.md`](./CHANGELOG.md). Upgrade guide: [`docs/roadmaps/migration-v1-5-to-v1-6.md`](./docs/roadmaps/migration-v1-5-to-v1-6.md).
191-
192-
## v1.6 primitives in 30 lines
201+
## v1.8 primitives in 30 lines
193202

194-
Three snippets, one per new primitive. Full runnable versions live in the [examples gallery](./examples/README.md).
203+
Three snippets from the new vector surfaces. Full runnable versions live in the [examples gallery](./examples/README.md).
195204

196-
**Nested list** &mdash; builder-callback child scopes with a per-depth marker cascade.
205+
**Native chart** &mdash; categories + series in, native vector bars out (no rasterization).
197206

198207
```java
199-
document.pageFlow().addList(list -> list
200-
.addItem("Backend platform", row -> row
201-
.addItem("Java 21, Spring Boot, PostgreSQL")
202-
.addItem("REST APIs and event-driven services"))
203-
.addItem("Document generation", row -> row
204-
.addItem("PDF rendering pipeline")
205-
.addItem("Layout snapshot tests")));
208+
ChartData revenue = ChartData.builder()
209+
.categories("Q1", "Q2", "Q3", "Q4")
210+
.series("2024", 12.4, 15.1, 9.8, 14.2)
211+
.series("2025", 14.0, 18.2, 11.3, 16.9)
212+
.build();
213+
section.chart(ChartSpec.bar().data(revenue)
214+
.legend(LegendPosition.BOTTOM)
215+
.size(ChartSize.aspectRatio(16, 7))
216+
.build());
206217
```
207218

208-
**Composed table cell** &mdash; any composable node inside a cell, two-pass row measurement.
219+
**Overshoot-free line** &mdash; a smooth curve constrained to never overshoot the data range.
209220

210221
```java
211-
DocumentTableCell richSummary = DocumentTableCell.node(
212-
new ParagraphNode("Summary",
213-
"**Q3 results** were *strong* — revenue grew 18% YoY.",
214-
bodyStyle, TextAlign.LEFT, 1.0,
215-
DocumentInsets.zero(), DocumentInsets.zero()));
222+
section.chart(ChartSpec.line().data(series)
223+
.interpolation(LineInterpolation.MONOTONE)
224+
.build());
216225
```
217226

218-
**Canvas layer** &mdash; pixel-precise `(x, y)` placement inside a fixed bounding box.
227+
**SVG import + alignment** &mdash; parse SVG to native geometry, seat any fixed node across the width.
219228

220229
```java
221-
document.pageFlow().addCanvas(523, 360, canvas -> canvas
222-
.clipPolicy(ClipPolicy.CLIP_BOUNDS)
223-
.position(headline, 0, 60)
224-
.position(rule(503, 1.4, accent), 10, 32));
230+
SvgIcon globe = SvgIcon.parse(svgMarkup);
231+
flow.addSvgIcon(globe, 48, HorizontalAlign.CENTER);
232+
flow.addAligned(HorizontalAlign.RIGHT, anyFixedNode);
225233
```
226234

227235
## Architecture

0 commit comments

Comments
 (0)