Merge pull request #171 from DemchaAV/feat/path-dash-pattern

feat(api): dashed strokes for vector paths - PathBuilder.dashed

Author: DemchaAV

CHANGELOG.md

@@ -64,7 +64,9 @@ Entries land here as they merge.
   and/or stroke. This is the leaf vehicle for smooth chart lines, decorative
   design shapes, and future SVG path import. DSL:
   `addPath(p -> p.moveTo(...).curveTo(...).closePath().fillColor(...))` on
-  every flow builder authors design shapes directly.
+  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.
 - **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

assets/readme/examples/vector-path.pdf

@@ -362,7 +362,8 @@ Free-form design shapes with native cubic Bézier curves through
 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.
+control points may overshoot it. Strokes can be dashed via
+`dashed(on, off, ...)` — the pattern follows the curve.
 
 ```java
 flow.addPath(path -> path

examples/README.md

@@ -52,7 +52,7 @@ public static Path generate() throws Exception {
         Path pdfFile = ExampleOutputPaths.prepare("features/shapes", "vector-path.pdf");
 
         try (DocumentSession document = GraphCompose.document(pdfFile)
-                .pageSize(420, 420)
+                .pageSize(420, 540)
                 .margin(DocumentInsets.of(28))
                 .create()) {
             document.pageFlow(page -> page
@@ -76,6 +76,16 @@ public static Path generate() throws Exception {
                             .fillColor(SAND)
                             .stroke(DocumentStroke.of(SAND_EDGE, 1.4))
                             .margin(DocumentInsets.bottom(16)))
+                    .addParagraph("Dashed Bézier wave — dashed(6, 3) follows the curve")
+                    .addPath(path -> path
+                            .name("DashedWave")
+                            .size(364, 44)
+                            .moveTo(0.0, 0.5)
+                            .curveTo(0.25, 1.2, 0.25, -0.2, 0.5, 0.5)
+                            .curveTo(0.75, 1.2, 0.75, -0.2, 1.0, 0.5)
+                            .stroke(DocumentStroke.of(INK, 1.8))
+                            .dashed(6, 3)
+                            .margin(DocumentInsets.bottom(16)))
                     .addParagraph("Mixed ribbon — lines and curves in one closed, filled subpath")
                     .addPath(path -> path
                             .name("Ribbon")

examples/src/main/java/com/demcha/examples/features/shapes/VectorPathExample.java

@@ -25,18 +25,6 @@ public final class PdfLineFragmentRenderHandler
     public PdfLineFragmentRenderHandler() {
     }
 
-    private static void applyDashPattern(PDPageContentStream stream, DocumentDashPattern dash) throws IOException {
-        if (dash == null || dash.isSolid()) {
-            return;
-        }
-        List<Double> segments = dash.segments();
-        float[] dashArray = new float[segments.size()];
-        for (int i = 0; i < dashArray.length; i++) {
-            dashArray[i] = segments.get(i).floatValue();
-        }
-        stream.setLineDashPattern(dashArray, 0f);
-    }
-
     @Override
     public Class<LineFragmentPayload> payloadType() {
         return LineFragmentPayload.class;
@@ -56,7 +44,7 @@ public void render(PlacedFragment fragment,
         try {
             stream.setStrokingColor(stroke.strokeColor().color());
             stream.setLineWidth((float) stroke.width());
-            applyDashPattern(stream, payload.dashPattern());
+            PdfShapeGeometry.applyDashPattern(stream, payload.dashPattern());
             stream.moveTo((float) (fragment.x() + payload.startX()), (float) (fragment.y() + payload.startY()));
             stream.lineTo((float) (fragment.x() + payload.endX()), (float) (fragment.y() + payload.endY()));
             stream.stroke();

src/main/java/com/demcha/compose/document/backend/fixed/pdf/handlers/PdfLineFragmentRenderHandler.java

@@ -42,6 +42,7 @@ public void render(PlacedFragment fragment,
         float width = (float) fragment.width();
         float height = (float) fragment.height();
         PdfShapeGeometry.fillAndStrokePath(stream, payload.fillColor(), payload.stroke(),
+                payload.dashPattern(),
                 s -> PdfShapeGeometry.addPathSegments(s, x, y, width, height, payload.segments()));
     }
 }

src/main/java/com/demcha/compose/document/backend/fixed/pdf/handlers/PdfPathFragmentRenderHandler.java

@@ -1,5 +1,6 @@
 package com.demcha.compose.document.backend.fixed.pdf.handlers;
 
+import com.demcha.compose.document.style.DocumentDashPattern;
 import com.demcha.compose.document.style.DocumentPathSegment;
 import com.demcha.compose.document.style.ShapePoint;
 import com.demcha.compose.engine.components.content.shape.Stroke;
@@ -28,6 +29,20 @@ static void fillAndStrokePath(PDPageContentStream stream,
                                   Color fillColor,
                                   Stroke stroke,
                                   PathEmitter path) throws IOException {
+        fillAndStrokePath(stream, fillColor, stroke, null, path);
+    }
+
+    /**
+     * Variant of {@link #fillAndStrokePath(PDPageContentStream, Color, Stroke, PathEmitter)}
+     * with an optional dash pattern applied to the stroke inside the saved
+     * graphics state ({@code null} or {@link DocumentDashPattern#NONE} keeps
+     * the stroke solid).
+     */
+    static void fillAndStrokePath(PDPageContentStream stream,
+                                  Color fillColor,
+                                  Stroke stroke,
+                                  DocumentDashPattern dashPattern,
+                                  PathEmitter path) throws IOException {
         boolean hasFill = fillColor != null;
         boolean hasStroke = stroke != null
                             && stroke.strokeColor() != null
@@ -42,6 +57,7 @@ static void fillAndStrokePath(PDPageContentStream stream,
                 PdfAlphaSupport.applyStrokeAlpha(stream, stroke.strokeColor().color());
                 stream.setStrokingColor(stroke.strokeColor().color());
                 stream.setLineWidth((float) stroke.width());
+                applyDashPattern(stream, dashPattern);
             }
             if (hasFill) {
                 PdfAlphaSupport.applyFillAlpha(stream, fillColor);
@@ -168,6 +184,23 @@ static void roundedRectPath(PDPageContentStream stream,
         stream.closePath();
     }
 
+    /**
+     * Applies a dash pattern to the stream's stroking state. No-op for
+     * {@code null} or solid patterns. Shared by the line and path renderers
+     * so both emit identical dash arrays.
+     */
+    static void applyDashPattern(PDPageContentStream stream, DocumentDashPattern dash) throws IOException {
+        if (dash == null || dash.isSolid()) {
+            return;
+        }
+        List<Double> segments = dash.segments();
+        float[] dashArray = new float[segments.size()];
+        for (int i = 0; i < dashArray.length; i++) {
+            dashArray[i] = segments.get(i).floatValue();
+        }
+        stream.setLineDashPattern(dashArray, 0f);
+    }
+
     /**
      * A path contribution: the caller adds the geometry (ellipse, rectangle,
      * polygon, …) so the fill/stroke wrapper can be shared.

src/main/java/com/demcha/compose/document/backend/fixed/pdf/handlers/PdfShapeGeometry.java

@@ -236,7 +236,7 @@ private static ChartPrimitive bezierRun(String name, List<double[]> run, Documen
                     (end[0] - minX) / w, (end[1] - minY) / h));
         }
         PathNode node = new PathNode(name, w, h, segments, null, stroke,
-                DocumentInsets.zero(), DocumentInsets.zero());
+                DocumentInsets.zero(), DocumentInsets.zero(), null);
         return new ChartPrimitive(node, minX, minY, w, h);
     }
 
@@ -289,7 +289,7 @@ private static void emitCurvedArea(List<ChartPrimitive> out, String name,
         segments.add(DocumentPathSegment.close());
 
         PathNode node = new PathNode(name, w, h, segments, fill, null,
-                DocumentInsets.zero(), DocumentInsets.zero());
+                DocumentInsets.zero(), DocumentInsets.zero(), null);
         out.add(new ChartPrimitive(node, minX, minY, w, h));
     }
 

src/main/java/com/demcha/compose/document/chart/LineChartLayout.java

@@ -2,6 +2,7 @@
 
 import com.demcha.compose.document.node.PathNode;
 import com.demcha.compose.document.style.DocumentColor;
+import com.demcha.compose.document.style.DocumentDashPattern;
 import com.demcha.compose.document.style.DocumentInsets;
 import com.demcha.compose.document.style.DocumentPathSegment;
 import com.demcha.compose.document.style.DocumentStroke;
@@ -43,6 +44,7 @@ public final class PathBuilder {
     private DocumentStroke stroke;
     private DocumentInsets padding = DocumentInsets.zero();
     private DocumentInsets margin = DocumentInsets.zero();
+    private DocumentDashPattern dashPattern = DocumentDashPattern.NONE;
 
     /**
      * Creates a path builder.
@@ -182,6 +184,32 @@ public PathBuilder stroke(DocumentStroke stroke) {
         return this;
     }
 
+    /**
+     * Makes the stroke dashed using alternating on/off lengths in points
+     * (the same contract as {@code LineBuilder.dashed}). Affects only the
+     * stroke; fills are unaffected.
+     *
+     * @param pattern alternating on/off lengths in points
+     * @return this builder
+     */
+    public PathBuilder dashed(double... pattern) {
+        this.dashPattern = DocumentDashPattern.of(pattern);
+        return this;
+    }
+
+    /**
+     * Makes the stroke dashed using a prepared {@link DocumentDashPattern}.
+     * A {@code null} or {@link DocumentDashPattern#NONE} pattern keeps the
+     * stroke solid.
+     *
+     * @param pattern dash pattern, or {@code null} for solid
+     * @return this builder
+     */
+    public PathBuilder dashed(DocumentDashPattern pattern) {
+        this.dashPattern = pattern == null ? DocumentDashPattern.NONE : pattern;
+        return this;
+    }
+
     /**
      * Sets the path padding.
      *
@@ -215,6 +243,6 @@ public PathBuilder margin(DocumentInsets margin) {
      *                                  added, or the box is not positive
      */
     public PathNode build() {
-        return new PathNode(name, width, height, segments, fillColor, stroke, padding, margin);
+        return new PathNode(name, width, height, segments, fillColor, stroke, padding, margin, dashPattern);
     }
 }

src/main/java/com/demcha/compose/document/dsl/PathBuilder.java

@@ -64,6 +64,7 @@ public List<LayoutFragment> emitFragments(PreparedNode<PathNode> prepared,
                         node.fillColor() == null ? null : node.fillColor().color(),
                         toStroke(node.stroke()),
                         null,
-                        null)));
+                        null,
+                        node.dashPattern())));
     }
 }