Merge branch 'develop' into docs/roadmap-block-align

Author: DemchaAV

CHANGELOG.md

@@ -67,6 +67,41 @@ Entries land here as they merge.
   every flow builder authors design shapes directly, and
   `dashed(on, off, ...)` makes the stroke dashed with the same
   `DocumentDashPattern` contract as lines — the pattern follows the curve.
+- **SVG path import** (`@since 1.8.0`, **beta** — annotated `@Beta` while
+  the surface hardens against real-world exporter output). `SvgPath.parse(d)` /
+  `parse(d, viewBox...)` in the new `document.svg` package lowers the full
+  SVG 1.1 path grammar — absolute/relative `M L H V C S Q T A Z`, implicit
+  repetition, quadratics (exact cubic elevation), smooth shorthands, and
+  elliptical arcs (deterministic W3C endpoint-to-center conversion, ≤90°
+  cubic slices) — into normalized, y-flipped `DocumentPathSegment`s.
+  `PathBuilder.svg(svgPath)` drops the result straight into `addPath(...)`:
+  any icon's `d` string renders as native PDF curves, no tessellation.
+  Syntax errors report the character position; fills keep SVG's default
+  non-zero winding rule. On top of it, `SvgIcon.read(file)` / `parse(xml)`
+  reads the practical subset of a whole SVG file — every `<path>` plus
+  `rect` / `circle` / `ellipse` / `line` / `polyline` / `polygon` lowered to
+  path data, `<g>` nesting with `translate` / `scale` / `rotate` / `matrix`
+  transforms (affine maps are exact on Bézier control points), and
+  `fill` / `stroke` / `stroke-width` styling with SVG inheritance and
+  defaults — into ordered layers, and `addSvgIcon(icon, width)` stacks them
+  back-to-front on the page. `SvgIcon#node(width)` packages the same layers
+  as one ready-to-place node whose box is exactly the icon box, so it
+  anchors true inside `ShapeContainer` / `LayerStack` nine-point grids (and
+  rows now accept `ShapeContainerNode` children directly — it is the same
+  atomic overlay composite as the already-allowed `LayerStackNode`).
+  **Gradients render natively**: `linearGradient` / `radialGradient`
+  referenced via `url(#id)` — on fills *and strokes* — map to PDF axial /
+  radial shadings with exact endpoints (`userSpaceOnUse` and
+  `objectBoundingBox` units, `gradientTransform`, percentage offsets,
+  multi-stop stitching, one `href` hop for split definitions); gradient
+  strokes ride a shading-pattern stroking colour. Underneath,
+  `DocumentPaint` gains endpoint-exact `LinearAxis` / `RadialCircle` forms
+  and `PathNode` / `PathBuilder` grow `fill(paint)` / `strokePaint(paint)`
+  with solid paints normalising to the flat-colour path (byte-identical
+  output for non-gradient documents). The XML reader refuses DOCTYPEs (no
+  XXE); CSS, text, filters, focal radials, non-pad `spreadMethod` and
+  translucent stops stay deliberately out of scope — the reader fails
+  loudly rather than rendering them wrong.
 - **Inline sparklines** (`@since 1.8.0`). `RichText.sparkline(w, h, color,
   values...)` draws a filled mini-area silhouette on the text baseline, and
   `sparklineLine(w, h, thickness, color, values...)` a constant-thickness line
@@ -181,10 +216,12 @@ Entries land here as they merge.
   a code panel shows the exact API call, and the live result renders right
   under it — rich text, sparklines, nested lists, timelines, tables, every
   chart kind, images (COVER vs CONTAIN fit), gradients, translucency,
-  polygons, shape basics (dividers, ellipses, soft cards), clipped
-  containers, canvas, transforms, barcodes, and the document's own chrome —
-  19 blocks across 6 pages. Blocks use `keepTogether()`, so a snippet is
-  never orphaned from its result.
+  polygons, vector paths (solid and dashed native Béziers), SVG path import
+  and a beta `SvgIcon` tile row, shape basics (dividers, ellipses, soft
+  cards), clipped containers, canvas, transforms, barcodes, the
+  debug-overlay switch, and the document's own chrome — 23 blocks across
+  7 pages. Blocks use `keepTogether()`, so a snippet is never orphaned
+  from its result.
 - **Recipe coverage is complete.** Nine new cookbook pages close every gap the
   recipe index tracked: rich text, lists, timelines, barcodes, images,
   PDF chrome (metadata / watermark / running header-footer / protection /

assets/readme/examples/svg-icon-gallery.pdf

@@ -88,7 +88,8 @@ are with the canonical DSL, then jump to its detailed section below.
 | Example | What it shows | Preview · Source |
 |---|---|---|
 | [Shape containers](#shape-containers) | Circles, ellipses, rounded cards with `ClipPolicy.CLIP_PATH` | [PDF](../assets/readme/examples/shape-container.pdf) · [Source](src/main/java/com/demcha/examples/features/shapes/ShapeContainerExample.java) |
-| [Vector paths (Bézier)](#vector-paths-bézier) | `addPath(...)` — design shapes with native cubic curves: waves, blobs, ribbons; zero tessellation | [PDF](../assets/readme/examples/vector-path.pdf) · [Source](src/main/java/com/demcha/examples/features/shapes/VectorPathExample.java) |
+| [Vector paths (Bézier)](#vector-paths-bézier) | `addPath(...)` + `SvgPath.parse(...)` — design shapes and imported SVG icons as native curves; zero tessellation | [PDF](../assets/readme/examples/vector-path.pdf) · [Source](src/main/java/com/demcha/examples/features/shapes/VectorPathExample.java) |
+| [SVG icon gallery](#svg-icon-gallery) | 34 real-world multicolour svgrepo icons via `SvgIcon.parse` — up to 19 layers each, the whole set 156 KB of sources | [PDF](../assets/readme/examples/svg-icon-gallery.pdf) · [Source](src/main/java/com/demcha/examples/features/svg/SvgIconGalleryExample.java) |
 | [Advanced tables](#advanced-tables) | Row span, zebra rows, totals, repeating header on page break | [PDF](../assets/readme/examples/table-advanced.pdf) · [Source](src/main/java/com/demcha/examples/features/tables/TableAdvancedExample.java) |
 | [Barcodes](#barcodes) | QR, Code 128, Code 39, EAN-13, EAN-8, branded QR with theme colours | [PDF](../assets/readme/examples/barcode-showcase.pdf) · [Source](src/main/java/com/demcha/examples/features/barcodes/BarcodeShowcaseExample.java) |
 | [Charts](#charts) | Native vector bar, line, and pie/donut charts — data/spec/style layers, axis & grid toggles, point markers, value labels, legend | [PDF](../assets/readme/examples/chart-showcase.pdf) · [Source](src/main/java/com/demcha/examples/features/charts/ChartShowcaseExample.java) |
@@ -363,7 +364,10 @@ ribbons in one closed subpath. Curves render as native PDF `curveTo`
 operators — perfectly smooth at any zoom, no tessellation. Coordinates
 are normalized to the shape's box (`(0,0)` bottom-left, `y` up) and
 control points may overshoot it. Strokes can be dashed via
-`dashed(on, off, ...)` — the pattern follows the curve.
+`dashed(on, off, ...)` — the pattern follows the curve. SVG icons drop in
+through `SvgPath.parse(d, viewBox...)` + `.svg(...)`, or whole files via
+`SvgIcon.read(file)` + `addSvgIcon(icon, width)` — multi-layer icons with
+group transforms and per-layer paints, all as native curves.
 
 ```java
 flow.addPath(path -> path
@@ -377,6 +381,21 @@ flow.addPath(path -> path
 [📄 View PDF](../assets/readme/examples/vector-path.pdf) ·
 [📜 Full source](src/main/java/com/demcha/examples/features/shapes/VectorPathExample.java)
 
+### SVG icon gallery
+
+A stress-test sheet for the beta SVG reader: 34 real-world multicolour
+icons (svgrepo.com) parsed by `SvgIcon.parse` and presented as a tile
+grid — each icon centred on a rounded card with a label plaque across
+the bottom, every layer a native vector path. The entire icon set weighs
+156 KB of `.svg` sources; the rendered page is a 70 KB PDF.
+
+```java
+flow.addSvgIcon(SvgIcon.parse(readResource("/icons/apple.svg")), 50);
+```
+
+[📄 View PDF](../assets/readme/examples/svg-icon-gallery.pdf) ·
+[📜 Full source](src/main/java/com/demcha/examples/features/svg/SvgIconGalleryExample.java)
+
 ### Advanced tables
 
 `DocumentTableCell.rowSpan(int)` mirrors `colSpan(int)`.

assets/readme/examples/vector-path.pdf

@@ -11,6 +11,7 @@
 import com.demcha.examples.features.shapes.VectorPathExample;
 import com.demcha.examples.features.snapshots.LayoutSnapshotRegressionExample;
 import com.demcha.examples.features.streaming.HttpStreamingExample;
+import com.demcha.examples.features.svg.SvgIconGalleryExample;
 import com.demcha.examples.features.tables.ComposedTableCellExample;
 import com.demcha.examples.features.tables.TableAdvancedExample;
 import com.demcha.examples.features.text.InlineShapesExample;
@@ -130,6 +131,7 @@ public static void main(String[] args) throws Exception {
         // v1.5 visual primitives
         System.out.println("Generated: " + ShapeContainerExample.generate());
         System.out.println("Generated: " + VectorPathExample.generate());
+        System.out.println("Generated: " + SvgIconGalleryExample.generate());
         System.out.println("Generated: " + TransformsExample.generate());
         System.out.println("Generated: " + TableAdvancedExample.generate());
 

examples/README.md

@@ -4,10 +4,14 @@
 import com.demcha.compose.document.api.DocumentSession;
 import com.demcha.compose.document.style.DocumentColor;
 import com.demcha.compose.document.style.DocumentInsets;
+import com.demcha.compose.document.style.DocumentPaint;
 import com.demcha.compose.document.style.DocumentStroke;
+import com.demcha.compose.document.svg.SvgIcon;
+import com.demcha.compose.document.svg.SvgPath;
 import com.demcha.examples.support.ExampleOutputPaths;
 
 import java.nio.file.Path;
+import java.util.List;
 
 /**
  * Runnable showcase for the v1.8 vector-path primitive: free-form design
@@ -37,6 +41,27 @@ public final class VectorPathExample {
     private static final DocumentColor SAND_EDGE = DocumentColor.rgb(140, 90, 30);
     private static final DocumentColor MOSS = DocumentColor.rgb(208, 226, 213);
     private static final DocumentColor MOSS_EDGE = DocumentColor.rgb(60, 110, 80);
+    private static final DocumentColor VIOLET = DocumentColor.rgb(167, 139, 250);
+    private static final DocumentColor DEEP_VIOLET = DocumentColor.rgb(97, 40, 217);
+
+    /** Brand gradient along the top-left → bottom-right diagonal. */
+    private static final DocumentPaint BRAND_AXIS = new DocumentPaint.LinearAxis(List.of(
+            new DocumentPaint.Stop(0.0, VIOLET),
+            new DocumentPaint.Stop(1.0, DEEP_VIOLET)), 0.0, 1.0, 1.0, 0.0);
+
+    /** Material Icons "favorite" path data (Apache 2.0), viewBox 0 0 24 24. */
+    private static final String MATERIAL_HEART_D =
+            "M12 21.35l-1.45-1.32C5.4 15.36 2 12.28 2 8.5 2 5.42 4.42 3 7.5 3"
+            + "c1.74 0 3.41.81 4.5 2.09C13.09 3.81 14.76 3 16.5 3 19.58 3 22 5.42 22 8.5"
+            + "c0 3.78-3.4 6.86-8.55 11.54L12 21.35z";
+
+    /** Inline two-tone badge: tinted disc behind the Material heart. */
+    private static final String TWO_TONE_BADGE_SVG = """
+            <svg viewBox="0 0 24 24">
+              <circle cx="12" cy="12" r="11" fill="#fde9e3"/>
+              <path fill="#c41e3a" d="%s"/>
+            </svg>
+            """.formatted(MATERIAL_HEART_D);
 
     private VectorPathExample() {
     }
@@ -52,7 +77,7 @@ public static Path generate() throws Exception {
         Path pdfFile = ExampleOutputPaths.prepare("features/shapes", "vector-path.pdf");
 
         try (DocumentSession document = GraphCompose.document(pdfFile)
-                .pageSize(420, 540)
+                .pageSize(420, 920)
                 .margin(DocumentInsets.of(28))
                 .create()) {
             document.pageFlow(page -> page
@@ -86,6 +111,34 @@ public static Path generate() throws Exception {
                             .stroke(DocumentStroke.of(INK, 1.8))
                             .dashed(6, 3)
                             .margin(DocumentInsets.bottom(16)))
+                    .addParagraph("SVG path import — Material 'favorite' heart via SvgPath.parse")
+                    .addPath(path -> path
+                            .name("HeartIcon")
+                            .size(72, 72)
+                            .svg(SvgPath.parse(MATERIAL_HEART_D, 0, 0, 24, 24))
+                            .fillColor(DocumentColor.rgb(196, 30, 58))
+                            .margin(DocumentInsets.bottom(16)))
+                    .addParagraph("Whole-file icon — SvgIcon.read/parse stacks every layer")
+                    .addSvgIcon(SvgIcon.parse(TWO_TONE_BADGE_SVG), 64)
+                    .addParagraph("Gradient paints — strokePaint and fill ride native PDF shadings")
+                    .addPath(path -> path
+                            .name("GradientWave")
+                            .size(364, 52)
+                            .moveTo(0.0, 0.5)
+                            .curveTo(0.25, 1.1, 0.25, -0.1, 0.5, 0.5)
+                            .curveTo(0.75, 1.1, 0.75, -0.1, 1.0, 0.5)
+                            .stroke(DocumentStroke.of(VIOLET, 2.6))
+                            .strokePaint(BRAND_AXIS)
+                            .margin(DocumentInsets.bottom(8)))
+                    .addPath(path -> path
+                            .name("GradientBlob")
+                            .size(96, 56)
+                            .moveTo(0.5, 1.0)
+                            .curveTo(1.12, 0.94, 0.96, 0.08, 0.5, 0.0)
+                            .curveTo(0.04, 0.08, -0.12, 0.94, 0.5, 1.0)
+                            .closePath()
+                            .fill(BRAND_AXIS)
+                            .margin(DocumentInsets.bottom(16)))
                     .addParagraph("Mixed ribbon — lines and curves in one closed, filled subpath")
                     .addPath(path -> path
                             .name("Ribbon")