From 1080441a3079b3270990fe3e64e0c41f7e88b10c Mon Sep 17 00:00:00 2001 From: DemchaAV Date: Sun, 28 Jun 2026 19:25:18 +0100 Subject: [PATCH] docs(readme): announce v1.9.0 "navigable" and add the v1.8->v1.9 migration guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README "Release status" now names v1.9.0 (codename "navigable") as Latest stable, and the "What's new" section covers in-document navigation, the native TOC / page references / bookmarks, multi-section documents, the per-page-margin / bleed / row-layout additions, inline chips / SVG / emoji, and render-to-images. Install snippets stay at 1.8.0 (the release tooling flips them at cut time). - Add docs/roadmaps/migration-v1-8-to-v1-9.md β€” additive-only upgrade guide with a per-area TL;DR table, the one negative-margin behaviour note, the 2.0-bound shim deprecations, and the upgrade snippet. - Index the v1.8->v1.9 and the previously unlisted v1.7->v1.8 guides in docs/README.md. --- README.md | 25 ++++---- docs/README.md | 2 + docs/roadmaps/migration-v1-8-to-v1-9.md | 84 +++++++++++++++++++++++++ 3 files changed, 97 insertions(+), 14 deletions(-) create mode 100644 docs/roadmaps/migration-v1-8-to-v1-9.md diff --git a/README.md b/README.md index 66e97b8ce..9a53f7ff0 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.9.0](https://github.com/DemchaAV/GraphCompose/releases/tag/v1.9.0) — codenamed **"navigable"**: in-document navigation (anchors, internal links, a clickable TOC, page references & bookmarks), multi-section documents, and inline chips / SVG icons / colour emoji. **[What's new in v1.9 ↓](#whats-new-in-v19)** >  Β·  🟑 **In develop**: next cycle β€” open (see [CHANGELOG](./CHANGELOG.md)) >  Β·  See [API stability policy](./docs/api-stability.md) for tier definitions. @@ -51,22 +51,19 @@ 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 +## What's new in v1.9 -The **"illustrative"** release — the engine gains a vector-graphics dimension. +The **"navigable"** release — a rendered PDF becomes a document you can move through. -

- 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). +- **In-document navigation** — named `anchor(...)` targets and internal `link(...)` jumps emitted as native PDF `GoTo` actions: clickable cross-references, `[text](#heading)`-style links, and bidirectional footnotes (`DocumentLinkTarget` unifies internal and external links). +- **Native table of contents & page references** — `addTableOfContents(toc -> toc.entry(label, anchor))` builds a clickable TOC with dot leaders and auto-resolved page numbers; `addPageReference(anchor)` prints a native "see page N" cross-reference; `DocumentSession.pageIndex()` resolves any anchor to its page. +- **Bookmarks & viewer preferences** — `section.bookmark(...)` makes any section or container a PDF outline (bookmark-panel) target, and `chrome().viewerPreferences(...)` opens the reader on the outline panel, a chosen page layout, or the doc title in the window. +- **Multi-section documents** — `GraphCompose.documents()` concatenates independently authored sections — each with its own page size, margins, and footer numbering — into one PDF, with anchors, links, and the outline resolving across section boundaries. +- **Richer row & page layout** — `row.columns(auto(), weight(1), fixed(80))`, main-axis `flexSpacer()` / `arrangement(...)`, cross-axis `verticalAlign(...)`, per-page `pageMargins(...)`, and full-bleed `bleed(...)`. +- **Inline chips, SVG icons & colour emoji** — text on a rounded highlight chip, a parsed `SvgIcon` on the text baseline, and `RichText.emoji(":star:", size)` colour emoji via the new independently-versioned `graph-compose-emoji` module. +- **Render straight to images** — `DocumentSession` renders directly to `BufferedImage`s with no PDF round-trip; plus page-number offset / restart / style and round / dotted line caps. -Core document APIs stay source- and binary-compatible with v1.7 (`ConfigLoader` is the one removal). Full notes in [`CHANGELOG.md`](./CHANGELOG.md). +Core document APIs stay source- and binary-compatible with v1.8 — v1.9 is purely additive (two cover-letter / CV shim types are newly `@Deprecated` for 2.0). Full notes in [`CHANGELOG.md`](./CHANGELOG.md). ## Installation diff --git a/docs/README.md b/docs/README.md index 44c722e6c..33d23e7d4 100644 --- a/docs/README.md +++ b/docs/README.md @@ -54,6 +54,8 @@ back here. ### Roadmaps & migrations - **[roadmaps/v1.6-roadmap.md](roadmaps/v1.6-roadmap.md)** β€” current development roadmap. +- **[roadmaps/migration-v1-8-to-v1-9.md](roadmaps/migration-v1-8-to-v1-9.md)** β€” upgrade guide for v1.8 β†’ v1.9. +- **[roadmaps/migration-v1-7-to-v1-8.md](roadmaps/migration-v1-7-to-v1-8.md)** β€” upgrade guide for v1.7 β†’ v1.8. - **[roadmaps/migration-v1-6-to-v1-7.md](roadmaps/migration-v1-6-to-v1-7.md)** β€” upgrade guide for v1.6 β†’ v1.7. - **[roadmaps/migration-v1-5-to-v1-6.md](roadmaps/migration-v1-5-to-v1-6.md)** β€” upgrade guide for v1.5 β†’ v1.6. - **[roadmaps/migration-v1-4-to-v1-5.md](roadmaps/migration-v1-4-to-v1-5.md)** β€” upgrade guide for v1.4 β†’ v1.5. diff --git a/docs/roadmaps/migration-v1-8-to-v1-9.md b/docs/roadmaps/migration-v1-8-to-v1-9.md new file mode 100644 index 000000000..d12a8a3d1 --- /dev/null +++ b/docs/roadmaps/migration-v1-8-to-v1-9.md @@ -0,0 +1,84 @@ +# Migration: v1.8 β†’ v1.9 + +v1.9 β€” codenamed **"navigable"** β€” is **additive only**. Every public +type, method, and behaviour from v1.8 is unchanged: bump the dependency +to `1.9.0` and rebuild with **no source changes required**. Adding public +API is what turns the open cycle into a minor release. + +The theme of the release is **in-document navigation** β€” a rendered PDF +stops being a flat sequence of pages and becomes a document you can move +through: named anchors, internal links, a native clickable table of +contents, "see page N" cross-references, and a bookmark outline, all +emitted as native PDF `GoTo` actions and resolved in a single authoring +pass. + +If your application targets v1.8 today, there is nothing to do but +upgrade. The rest of this guide is a tour of what you can now reach for. + +## TL;DR + +Everything below is `@since 1.9.0` and purely additive β€” no v1.8 API is +replaced or removed. + +| Area | v1.9 addition | Reach for it when | +| --- | --- | --- | +| **In-PDF navigation** | `anchor(...)` targets + internal `link(...)`; sealed `DocumentLinkTarget` (`InternalLinkTarget` / `ExternalLinkTarget`) | clickable cross-references and `[text](#heading)`-style jumps emitted as native PDF `GoTo` actions | +| **Table of contents** | `addTableOfContents(toc -> toc.entry(label, anchor))` + `TocBuilder` / `DocumentLeader` | a native clickable TOC with dot leaders and auto-resolved page numbers | +| **Page references** | `addPageReference(anchor)` + `PageReferenceNode`; `DocumentSession.pageIndex()` β†’ `PageIndex` / `PageReference` | a "see page N" cross-reference, or resolving any anchor to its page from code | +| **Bookmarks & viewer prefs** | container `bookmark(DocumentBookmarkOptions)`; `chrome().viewerPreferences(...)` + `DocumentViewerPreferences` / `DocumentPageMode` / `DocumentPageLayout` | a PDF outline (bookmark panel), and controlling how a reader opens the document | +| **Multi-section documents** | `GraphCompose.documents()` + `MultiSectionDocumentBuilder` / `MultiSectionDocument` | concatenating independently authored sections (own page size / margins / numbering) into one PDF, with links resolving across sections | +| **Per-page margins & bleed** | `pageMargins(List)`; `bleed(...)` + `DocumentBleed` / `DocumentEdge` | mixing a full-bleed cover with book-margin body pages, or running content to the trimmed page edge | +| **Row layout** | `row.columns(auto() / weight() / fixed())` + `DocumentRowColumn`; `flexSpacer()` / `pushRight()` / `arrangement(...)` + `RowArrangement`; `verticalAlign(...)` + `RowVerticalAlign` | column tracks, main-axis justify (push a badge flush right), and cross-axis seating within a row | +| **Inline chips / SVG / emoji** | inline highlight chips, inline `SvgIcon` runs, `RichText.emoji(":star:", size)` via the new `graph-compose-emoji` module | a code/badge chip, an icon on the text baseline, or colour emoji by shortcode | +| **Page numbering** | `DocumentPageNumbering` / `DocumentPageNumberStyle` | page-number offset / restart / numeral style in headers and footers | +| **Lines** | `LineBuilder.fill()`; `LineBuilder.lineCap(DocumentLineCap)` | a line that stretches to its slot (dot leaders), and round / square caps or dotted strokes | +| **Render to images** | render a `DocumentSession` straight to `BufferedImage` | a raster preview / thumbnail with no PDF round-trip | + +Runnable code for each lives in the +[examples gallery](../../examples/README.md); the exact public-API list +is in [`CHANGELOG.md`](../../CHANGELOG.md) under **v1.9.0**. + +## One behaviour to know about + +- **A negative page margin is now rejected; a negative bottom *content* + margin is honoured.** A negative `margin(...)` on the page fails fast at + construction instead of silently mis-laying-out the page, while an + intentional negative bottom margin on a block now pulls the following + content up as written. This only affects code that passed a negative + *page* margin β€” pass a non-negative one. + +## Things that did NOT break + +- Every entry point on `GraphCompose`, the full `DocumentSession` + authoring lifecycle (`compose`, `pageFlow`, add, `buildPdf`, export, + close, `layoutGraph`, `layoutSnapshot`). +- `DocumentDsl`, `BusinessTheme`, `DocumentPalette`, and the invoice / + proposal / CV / cover-letter / weekly-schedule template entry points + (V1 and V2). +- The fixed-layout and semantic backend SPIs and every public render + handler. +- Layout snapshots and visual-regression baselines β€” navigation markers + are non-visual, so a document that adds no anchors, links, or bookmarks + renders byte-for-byte as before. + +> **Deprecations (informational, not breaking).** +> `templates.api.CoverLetterTemplate` and the `cv.v2.components` +> `HeadlineRenderer` / `ContactRenderer` / `BannerRenderer` shims are now +> `@Deprecated(forRemoval = true, since = "1.9.0")` β€” superseded by the +> generic `DocumentTemplate` seam and the `cv.v2.widgets` widgets +> respectively. They still compile and behave exactly as before in 1.x; +> they are slated for removal in 2.0. See +> [`docs/api-stability.md`](../api-stability.md) Β§3 for the ledger. + +## Upgrading + +```xml + + io.github.demchaav + graph-compose + 1.9.0 + +``` + +That is the entire migration. Pull in any of the primitives above as you +need them.