From b8126cb8283ea87e8ea2e4a98609e83672cf4d63 Mon Sep 17 00:00:00 2001 From: DemchaAV Date: Thu, 18 Jun 2026 14:32:14 +0100 Subject: [PATCH 1/2] docs(readme): lead with v1.8, retire the v1.6 spotlight MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- README.md | 72 ++++++++++++++++++++++++++++++------------------------- 1 file changed, 40 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index 9e631292..41a25e20 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@

> **Release status** — -> 🟒 **Latest stable**: [v1.8.0](https://github.com/DemchaAV/GraphCompose/releases/tag/v1.8.0) — 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).) +> 🟒 **Latest stable**: [v1.8.0](https://github.com/DemchaAV/GraphCompose/releases/tag/v1.8.0) — codenamed **"illustrative"**: native vector charts, SVG & gradient graphics, free-form clipping, and a leaner engine artifact. — **[What's new in v1.8 ↓](#whats-new-in-v18)** >  Β·  🟑 **In develop**: next cycle β€” open (see [CHANGELOG](./CHANGELOG.md)) >  Β·  See [API stability policy](./docs/api-stability.md) for tier definitions. @@ -46,11 +46,28 @@ - **Author intent, not coordinates.** Fluent DSL for sections, paragraphs, tables, lists, layer stacks, themes — the engine handles measurement, pagination, and rendering. - **Deterministic by design.** Two-pass layout. Snapshots are stable across machines, so layout regressions are catchable in tests before any byte ships. -- **Cinematic-by-default.** `BusinessTheme` + soft panels + accent strips + transforms + advanced tables are first-class primitives, not workarounds. +- **Cinematic by default.** `BusinessTheme`, soft panels, accent strips, transforms, native vector charts, and gradients are first-class primitives, not workarounds. - **PDFBox isolated, DOCX optional.** Single backend interface. Apache POI–backed DOCX export is available for compatible semantic content — see [support matrix](#output-support) for limitations. Sits between **iText** (low-level page primitives) and **JasperReports** (XML-template-driven layout): a Java DSL describes the document semantically, the engine renders. +## What's new in v1.8 + +The **"illustrative"** release — the engine gains a vector-graphics dimension. + +

+ GraphCompose native vector charts +

+ +- **Native vector charts** — bar / line / pie, inline sparklines, and `MONOTONE` / `SMOOTH` line interpolation, drawn as native PDF BΓ©ziers (no rasterization): `section.chart(ChartSpec.line()…, style)`. +- **SVG path & icon import** — `SvgIcon.parse(svg)` turns SVG into native vector geometry; recolour per use and place with `addSvgIcon(icon, width, align)`. +- **Gradients & free-form clipping** — linear / radial `DocumentPaint` fills and arbitrary `ShapeOutline.Path` clip regions. +- **Block-level alignment** — `addAligned(HorizontalAlign.CENTER, node)` centres or right-aligns any fixed node without a wrapper container. +- **`keepTogether()` pagination** — keep a section from splitting across a page break. +- **Leaner publication** — the bundled Google fonts moved to the independently-versioned `graph-compose-fonts` artifact, so the engine jar dropped from ~20 MB to ~2 MB. Pure-text / standard-14 documents need nothing extra; add `graph-compose-fonts` (or `graph-compose-bundle`) to keep the bundled families — see the [migration note](./docs/migration/v1.8.0-fonts.md). + +Core document APIs stay source- and binary-compatible with v1.7 (`ConfigLoader` is the one removal). Full notes in [`CHANGELOG.md`](./CHANGELOG.md). + ## Installation **Requires Java 17+** (enforced by the build). @@ -162,7 +179,7 @@ For a Spring Boot `@RestController` streaming the PDF straight to the response, |---|---|---|---|---| | **GraphCompose** | Java DSL, semantic nodes | Two-pass, deterministic, snapshot-testable | MIT | Code-first business documents with layout regression tests | | **PDFBox** | Low-level text / path primitives | Manual coordinates | Apache 2.0 | Direct PDF manipulation, parsing, extraction | -| **iText 7** | Low-level page primitives + high-level helpers | Manual + helpers | AGPL / commercial | When AGPL is acceptable or you have a commercial licence | +| **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 | | **OpenPDF** | iText 4 fork | Manual + helpers | LGPL / MPL | Legacy iText 4 codebases | | **JasperReports** | XML templates compiled to `.jasper` | Template-driven | LGPL | Tabular reports with datasource bindings | @@ -181,47 +198,38 @@ GraphCompose uses PDFBox under the hood as the rendering backend — the com > **Choosing a template surface** — 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. -## What's in v1.6 — "expressive" - -- **Layered templates** — 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.) -- **Composed primitives** — `ListBuilder.addItem(label, Consumer)` (nested lists), `DocumentTableCell.node(...)` (any node inside a cell), `CanvasLayerNode` (pixel-precise free-canvas placement). -- **Architecture hardening** — `@Internal` API stability marker, public `PdfFragmentRenderHandler` SPI, `DocumentRenderingException` on the convenience render path, documented thread-safety contract. - -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). - -## v1.6 primitives in 30 lines +## v1.8 primitives in 30 lines -Three snippets, one per new primitive. Full runnable versions live in the [examples gallery](./examples/README.md). +Three snippets from the new vector surfaces. Full runnable versions live in the [examples gallery](./examples/README.md). -**Nested list** — builder-callback child scopes with a per-depth marker cascade. +**Native chart** — categories + series in, native vector bars out (no rasterization). ```java -document.pageFlow().addList(list -> list - .addItem("Backend platform", row -> row - .addItem("Java 21, Spring Boot, PostgreSQL") - .addItem("REST APIs and event-driven services")) - .addItem("Document generation", row -> row - .addItem("PDF rendering pipeline") - .addItem("Layout snapshot tests"))); +ChartData revenue = ChartData.builder() + .categories("Q1", "Q2", "Q3", "Q4") + .series("2024", 12.4, 15.1, 9.8, 14.2) + .series("2025", 14.0, 18.2, 11.3, 16.9) + .build(); +section.chart(ChartSpec.bar().data(revenue) + .legend(LegendPosition.BOTTOM) + .size(ChartSize.aspectRatio(16, 7)) + .build()); ``` -**Composed table cell** — any composable node inside a cell, two-pass row measurement. +**Overshoot-free line** — a smooth curve constrained to never overshoot the data range. ```java -DocumentTableCell richSummary = DocumentTableCell.node( - new ParagraphNode("Summary", - "**Q3 results** were *strong* β€” revenue grew 18% YoY.", - bodyStyle, TextAlign.LEFT, 1.0, - DocumentInsets.zero(), DocumentInsets.zero())); +section.chart(ChartSpec.line().data(series) + .interpolation(LineInterpolation.MONOTONE) + .build()); ``` -**Canvas layer** — pixel-precise `(x, y)` placement inside a fixed bounding box. +**SVG import + alignment** — parse SVG to native geometry, seat any fixed node across the width. ```java -document.pageFlow().addCanvas(523, 360, canvas -> canvas - .clipPolicy(ClipPolicy.CLIP_BOUNDS) - .position(headline, 0, 60) - .position(rule(503, 1.4, accent), 10, 32)); +SvgIcon globe = SvgIcon.parse(svgMarkup); +flow.addSvgIcon(globe, 48, HorizontalAlign.CENTER); +flow.addAligned(HorizontalAlign.RIGHT, anyFixedNode); ``` ## Architecture From b165136cff4da1eaa8d6e8fd52835a18089437d1 Mon Sep 17 00:00:00 2001 From: DemchaAV Date: Thu, 18 Jun 2026 14:38:23 +0100 Subject: [PATCH 2/2] docs(readme): drop the redundant em-dash before the What's-new link --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 41a25e20..66e97b8c 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@

> **Release status** — -> 🟒 **Latest stable**: [v1.8.0](https://github.com/DemchaAV/GraphCompose/releases/tag/v1.8.0) — codenamed **"illustrative"**: native vector charts, SVG & gradient graphics, free-form clipping, and a leaner engine artifact. — **[What's new in v1.8 ↓](#whats-new-in-v18)** +> 🟒 **Latest stable**: [v1.8.0](https://github.com/DemchaAV/GraphCompose/releases/tag/v1.8.0) — codenamed **"illustrative"**: native vector charts, SVG & gradient graphics, free-form clipping, and a leaner engine artifact. **[What's new in v1.8 ↓](#whats-new-in-v18)** >  Β·  🟑 **In develop**: next cycle β€” open (see [CHANGELOG](./CHANGELOG.md)) >  Β·  See [API stability policy](./docs/api-stability.md) for tier definitions.