diff --git a/README.md b/README.md index 9bb4a33d9..8940ff262 100644 --- a/README.md +++ b/README.md @@ -19,9 +19,9 @@

> **Release status** — -> ๐ŸŸข **Latest stable**: [v1.7.1](https://github.com/DemchaAV/GraphCompose/releases/tag/v1.7.1) (byte-identical layout / render / measurement performance โ€” text wrapping, font embedding, glyph probing, table pagination; the legacy ECS engine is deprecated; zero breaking from v1.7.0) +> ๐ŸŸข **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; additive, zero breaking from v1.7) ->  ยท  ๐ŸŸก **In develop**: v1.8.0 — codenamed **"illustrative"** (native vector charts + inline sparklines, free-form `ShapeOutline.Path` clip, sharper SVG-reader errors; additive, zero breaking from v1.7) +>  ยท  ๐ŸŸก **In develop**: next cycle โ€” open (see [CHANGELOG](./CHANGELOG.md)) >  ยท  See [API stability policy](./docs/api-stability.md) for tier definitions.

diff --git a/docs/roadmaps/migration-v1-7-to-v1-8.md b/docs/roadmaps/migration-v1-7-to-v1-8.md new file mode 100644 index 000000000..cb39f34ba --- /dev/null +++ b/docs/roadmaps/migration-v1-7-to-v1-8.md @@ -0,0 +1,78 @@ +# Migration: v1.7 โ†’ v1.8 + +v1.8 โ€” codenamed **"illustrative"** โ€” is **additive only**. Every public +type, method, and behaviour from v1.7 is unchanged: bump the dependency +to `1.8.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 **data and artwork as first-class authoring +primitives** โ€” charts you used to rasterise through Graphics2D, and icons +you used to embed as images, are now drawn directly from semantic data +and native vector geometry, deterministic and snapshot-testable like the +rest of the document. + +If your application targets v1.7 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.8.0` and purely additive โ€” no v1.7 API is +replaced, deprecated, or removed. + +| Area | v1.8 addition | Reach for it when | +| --- | --- | --- | +| **Native vector charts** | `ChartData` + sealed `ChartSpec` (`bar()` / `line()` / `pie()`), `ChartStyle`, `section.chart(spec)` / `chart(spec, style)` | bar / line / pie-donut charts compiled into engine primitives โ€” deterministic, themable, no rasterised PNG | +| **Line interpolation modes** | `LineInterpolation` (`LINEAR` / `SMOOTH` / `MONOTONE`) via `ChartSpec.line().interpolation(โ€ฆ)` | a pretty curve (`SMOOTH`), or a smooth curve that never overshoots the data (`MONOTONE`), or exact straight segments (`LINEAR`) | +| **Inline sparklines** | `RichText` / `ParagraphBuilder` `sparkline(โ€ฆ)` / `sparklineLine(โ€ฆ)` | mini trend charts on the text baseline, inside running prose | +| **Vector path primitive** | `PathNode` + `addPath(p -> p.moveTo(โ€ฆ).curveTo(โ€ฆ)โ€ฆ)` on every flow builder; `dashed(โ€ฆ)` | open, curve-capable design shapes rendered with native PDF curve operators (no tessellation) | +| **Free-form clip outline** | `ShapeOutline.Path` + `ShapeContainerBuilder.path(w, h, segments)` / `path(w, h, svgPath)` | clip a container's children to โ€” and fill / stroke along โ€” an arbitrary native-curve silhouette | +| **SVG path & icon import** | `SvgPath.parse(d)`, `PathBuilder.svg(โ€ฆ)`, `SvgIcon.read(file)` / `parse(xml)`, `addSvgIcon(icon, width)` (**beta**) | drop an icon or logo's `d` string / whole SVG file in as native curves, with native linear / radial gradients on fills and strokes | +| **Block-level horizontal alignment** | `AlignNode` + `HorizontalAlign` (`LEFT` / `CENTER` / `RIGHT`), `flow.addAligned(align, node)`, `flow.addSvgIcon(icon, width, align)` | centre or right-align a fixed-size flow child (path, image, icon, barcode, shape) without a full-width wrapper | +| **Declarative paints** | `DocumentPaint` (solid, `LinearAxis`, `RadialCircle`); `PathNode` / `PathBuilder` `fill(paint)` / `strokePaint(paint)` | endpoint-exact gradient fills and strokes on charts and paths | + +Runnable code for each primitive lives in the +[examples gallery](../../examples/README.md); the exact public-API list +is in [`CHANGELOG.md`](../../CHANGELOG.md) under **v1.8.0**. + +## One behaviour to know about + +- **`ChartData.Series` rejects non-finite values.** A `NaN` / ยฑโˆž entry + now fails fast at construction โ€” naming the series and the offending + index โ€” instead of poisoning axis derivation and surfacing later as a + misleading "height must be finite" failure in the layout pass. `null` + entries are still allowed as gaps. This only affects code that builds a + chart series from a value that can be non-finite; guard or filter such + values before constructing the series. + +## 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 โ€” the additive + primitives change geometry only where you opt into them. + +> **Binary compatibility note.** `ShapeOutline` gained a `Path` permit +> and `DocumentPaint` gained `LinearAxis` / `RadialCircle` forms. These +> are additive โ€” the published authoring surface stays binary-compatible +> with v1.7 (the `japicmp` gate is green); only consumer code that +> exhaustively `switch`es over the sealed `ShapeOutline` would need a new +> branch, and the canonical authoring surface exposes no such switch. + +## Upgrading + +```xml + + io.github.demchaav + graph-compose + 1.8.0 + +``` + +That is the entire migration. Pull in any of the primitives above as you +need them.