|
| 1 | +# Migration: v1.8 → v1.9 |
| 2 | + |
| 3 | +v1.9 — codenamed **"navigable"** — is **additive only**. Every public |
| 4 | +type, method, and behaviour from v1.8 is unchanged: bump the dependency |
| 5 | +to `1.9.0` and rebuild with **no source changes required**. Adding public |
| 6 | +API is what turns the open cycle into a minor release. |
| 7 | + |
| 8 | +The theme of the release is **in-document navigation** — a rendered PDF |
| 9 | +stops being a flat sequence of pages and becomes a document you can move |
| 10 | +through: named anchors, internal links, a native clickable table of |
| 11 | +contents, "see page N" cross-references, and a bookmark outline, all |
| 12 | +emitted as native PDF `GoTo` actions and resolved in a single authoring |
| 13 | +pass. |
| 14 | + |
| 15 | +If your application targets v1.8 today, there is nothing to do but |
| 16 | +upgrade. The rest of this guide is a tour of what you can now reach for. |
| 17 | + |
| 18 | +## TL;DR |
| 19 | + |
| 20 | +Everything below is `@since 1.9.0` and purely additive — no v1.8 API is |
| 21 | +replaced or removed. |
| 22 | + |
| 23 | +| Area | v1.9 addition | Reach for it when | |
| 24 | +| --- | --- | --- | |
| 25 | +| **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 | |
| 26 | +| **Table of contents** | `addTableOfContents(toc -> toc.entry(label, anchor))` + `TocBuilder` / `DocumentLeader` | a native clickable TOC with dot leaders and auto-resolved page numbers | |
| 27 | +| **Page references** | `addPageReference(anchor)` + `PageReferenceNode`; `DocumentSession.pageIndex()` → `PageIndex` / `PageReference` | a "see page N" cross-reference, or resolving any anchor to its page from code | |
| 28 | +| **Bookmarks & viewer prefs** | container `bookmark(DocumentBookmarkOptions)`; `chrome().viewerPreferences(...)` + `DocumentViewerPreferences` / `DocumentPageMode` / `DocumentPageLayout` | a PDF outline (bookmark panel), and controlling how a reader opens the document | |
| 29 | +| **Multi-section documents** | `GraphCompose.documents()` + `MultiSectionDocumentBuilder` / `MultiSectionDocument` | concatenating independently authored sections (own page size / margins / numbering) into one PDF, with links resolving across sections | |
| 30 | +| **Per-page margins & bleed** | `pageMargins(List<PageMarginRule>)`; `bleed(...)` + `DocumentBleed` / `DocumentEdge` | mixing a full-bleed cover with book-margin body pages, or running content to the trimmed page edge | |
| 31 | +| **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 | |
| 32 | +| **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 | |
| 33 | +| **Page numbering** | `DocumentPageNumbering` / `DocumentPageNumberStyle` | page-number offset / restart / numeral style in headers and footers | |
| 34 | +| **Lines** | `LineBuilder.fill()`; `LineBuilder.lineCap(DocumentLineCap)` | a line that stretches to its slot (dot leaders), and round / square caps or dotted strokes | |
| 35 | +| **Render to images** | render a `DocumentSession` straight to `BufferedImage` | a raster preview / thumbnail with no PDF round-trip | |
| 36 | + |
| 37 | +Runnable code for each lives in the |
| 38 | +[examples gallery](../../examples/README.md); the exact public-API list |
| 39 | +is in [`CHANGELOG.md`](../../CHANGELOG.md) under **v1.9.0**. |
| 40 | + |
| 41 | +## One behaviour to know about |
| 42 | + |
| 43 | +- **A negative page margin is now rejected; a negative bottom *content* |
| 44 | + margin is honoured.** A negative `margin(...)` on the page fails fast at |
| 45 | + construction instead of silently mis-laying-out the page, while an |
| 46 | + intentional negative bottom margin on a block now pulls the following |
| 47 | + content up as written. This only affects code that passed a negative |
| 48 | + *page* margin — pass a non-negative one. |
| 49 | + |
| 50 | +## Things that did NOT break |
| 51 | + |
| 52 | +- Every entry point on `GraphCompose`, the full `DocumentSession` |
| 53 | + authoring lifecycle (`compose`, `pageFlow`, add, `buildPdf`, export, |
| 54 | + close, `layoutGraph`, `layoutSnapshot`). |
| 55 | +- `DocumentDsl`, `BusinessTheme`, `DocumentPalette`, and the invoice / |
| 56 | + proposal / CV / cover-letter / weekly-schedule template entry points |
| 57 | + (V1 and V2). |
| 58 | +- The fixed-layout and semantic backend SPIs and every public render |
| 59 | + handler. |
| 60 | +- Layout snapshots and visual-regression baselines — navigation markers |
| 61 | + are non-visual, so a document that adds no anchors, links, or bookmarks |
| 62 | + renders byte-for-byte as before. |
| 63 | + |
| 64 | +> **Deprecations (informational, not breaking).** |
| 65 | +> `templates.api.CoverLetterTemplate` and the `cv.v2.components` |
| 66 | +> `HeadlineRenderer` / `ContactRenderer` / `BannerRenderer` shims are now |
| 67 | +> `@Deprecated(forRemoval = true, since = "1.9.0")` — superseded by the |
| 68 | +> generic `DocumentTemplate` seam and the `cv.v2.widgets` widgets |
| 69 | +> respectively. They still compile and behave exactly as before in 1.x; |
| 70 | +> they are slated for removal in 2.0. See |
| 71 | +> [`docs/api-stability.md`](../api-stability.md) §3 for the ledger. |
| 72 | +
|
| 73 | +## Upgrading |
| 74 | + |
| 75 | +```xml |
| 76 | +<dependency> |
| 77 | + <groupId>io.github.demchaav</groupId> |
| 78 | + <artifactId>graph-compose</artifactId> |
| 79 | + <version>1.9.0</version> |
| 80 | +</dependency> |
| 81 | +``` |
| 82 | + |
| 83 | +That is the entire migration. Pull in any of the primitives above as you |
| 84 | +need them. |
0 commit comments