Merge pull request #162 from DemchaAV/docs/word-export-example

Word-export companion + library-wide import/Javadoc cleanup + ConfigLoader removal

Author: DemchaAV

.github/workflows/ci.yml

@@ -147,7 +147,7 @@ jobs:
         run: ./mvnw -B -ntp test -pl . -P no-poi
 
   binary-compat:
-    name: Binary Compatibility (japicmp vs v1.6.9)
+    name: Binary Compatibility (japicmp vs pom baseline)
     if: github.event_name == 'pull_request'
     needs: architecture-and-documentation-guards
     runs-on: ubuntu-latest
@@ -166,8 +166,9 @@ jobs:
           cache: maven
 
       - name: Compare public API against baseline
-        # The `japicmp` profile resolves the prior published jar
-        # (v1.6.8 from Maven Central) and diffs it against the
+        # The `japicmp` profile resolves the baseline release pinned
+        # by the `japicmp.baseline` property in pom.xml (via the
+        # profile-local JitPack repository) and diffs it against the
         # freshly-built artifact. Fails the job on any binary-
         # incompatible modification to the public surface. Source-
         # incompatible changes are reported only (phased policy).

CHANGELOG.md

@@ -95,6 +95,15 @@ Entries land here as they merge.
   not fit in the remaining page space relocates whole to the next page instead
   of orphaning its heading from the content below. Blocks taller than a page
   still flow. Default off — existing layouts are byte-identical.
+- **Removed: `ConfigLoader`** (breaking). The `com.demcha.compose.ConfigLoader`
+  YAML/JSON config-file helper was an application-bootstrap utility with no
+  connection to document rendering — nothing in the library, tests, or
+  examples referenced it. Gone with it: the `<optional>`
+  `jackson-dataformat-yaml` dependency (ConfigLoader was its only consumer)
+  and the YAML entry in the `NoClassDefFoundError` troubleshooting section.
+  Consumers who relied on the helper can copy the former ~100-line class into
+  their own codebase or load configs directly with Jackson
+  (`new ObjectMapper(new YAMLFactory()).readValue(...)`).
 
 ### Bug fixes
 
@@ -136,6 +145,15 @@ Entries land here as they merge.
   regression testing. Every snippet is verified against the current API;
   the folder index (`docs/recipes/README.md`) no longer carries a
   "not yet covered" list.
+- **Word-export example.** New `WordExportExample`
+  (`examples/features/docx`) renders the same `DocumentSession` as a
+  fixed-layout PDF *and* an editable Word file via `DocxSemanticBackend`,
+  one section per capability-table row: inline runs, nested lists with
+  custom markers, tables, side-by-side rows, an embedded image, a page
+  break, the chart→data-table fallback, and the geometry that stays
+  PDF-only. Committed previews live under `assets/readme/examples/`
+  (`word-export-companion.pdf` / `.docx`); the examples module adds the
+  optional `poi-ooxml` dependency exactly like a consuming project would.
 - **`BusinessReportExample` chart is now a native vector chart.** The flagship
   report's five-quarter Revenue/Profit block previously rasterised a bar chart
   through Graphics2D into an embedded PNG; it now uses `ChartSpec.bar()` with a

assets/readme/examples/word-export-companion.docx

@@ -39,8 +39,8 @@ Per-feature mapping: [canonical ↔ legacy parity matrix](architecture/canonical
 
 ## `NoClassDefFoundError` at runtime
 
-GraphCompose marks two heavy, rarely-needed dependencies **optional** so
-PDF-only consumers don't pay for them. If you use the feature, add the
+GraphCompose marks one heavy, rarely-needed dependency **optional** so
+PDF-only consumers don't pay for it. If you use DOCX export, add the
 dependency to **your** project.
 
 **DOCX export** — `document.export(new DocxSemanticBackend())` needs
@@ -54,20 +54,6 @@ Apache POI on your classpath:
 </dependency>
 ```
 
-**YAML config** — loading a `*.yaml` / `*.yml` resource through
-`ConfigLoader` needs the Jackson YAML dataformat (the error names
-`YAMLFactory`):
-
-```xml
-<dependency>
-  <groupId>com.fasterxml.jackson.dataformat</groupId>
-  <artifactId>jackson-dataformat-yaml</artifactId>
-  <!-- version: match the Jackson you already depend on -->
-</dependency>
-```
-
-…or load a JSON config instead, which needs no extra dependency.
-
 ## The bundled examples won't resolve `graph-compose`
 
 **Cause.** `examples/` is a **separate Maven module** that depends on the

assets/readme/examples/word-export-companion.pdf

@@ -93,6 +93,7 @@ are with the canonical DSL, then jump to its detailed section below.
 | [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) |
 | [PDF chrome](#pdf-chrome) | `DocumentMetadata`, `DocumentWatermark`, `DocumentHeaderFooter`, `DocumentBookmarkOptions` | [PDF](../assets/readme/examples/pdf-chrome.pdf) · [Source](src/main/java/com/demcha/examples/features/chrome/PdfChromeExample.java) |
 | [HTTP streaming](#http-streaming) | `writePdf(OutputStream)` for Servlet / S3 / GCS — caller's stream is not closed | [PDF](../assets/readme/examples/invoice-http-stream.pdf) · [Source](src/main/java/com/demcha/examples/features/streaming/HttpStreamingExample.java) |
+| [Word export (DOCX)](#word-export-docx) | `DocxSemanticBackend` — the same session renders a fixed-layout PDF and an editable Word file; paragraphs / lists / tables / images map 1:1, charts fall back to their data table | [PDF](../assets/readme/examples/word-export-companion.pdf) · [DOCX](../assets/readme/examples/word-export-companion.docx) · [Source](src/main/java/com/demcha/examples/features/docx/WordExportExample.java) |
 | [Layout snapshot regression](#layout-snapshot-regression) | Deterministic `layoutSnapshot()` workflow with baseline + drift report — production regression-testing pattern | [PDF](../assets/readme/examples/invoice-snapshot-regression.pdf) · [Source](src/main/java/com/demcha/examples/features/snapshots/LayoutSnapshotRegressionExample.java) |
 | [Business report cover](#business-report-cover) | Single-page Q1 investor brief — hero image, KPI cards, bar chart, metrics table | [PDF](../assets/readme/examples/business-report.pdf) · [Source](src/main/java/com/demcha/examples/flagships/BusinessReportExample.java) |
 | [Master showcase](#master-showcase) | Kitchen-sink "Q2 sample report" combining the canonical surface end-to-end | [PDF](../assets/readme/examples/master-showcase.pdf) · [Source](src/main/java/com/demcha/examples/flagships/MasterShowcaseExample.java) |
@@ -576,6 +577,47 @@ public ResponseEntity<StreamingResponseBody> invoice(@PathVariable Long id) {
 [📄 View PDF](../assets/readme/examples/invoice-http-stream.pdf) ·
 [📜 Full source](src/main/java/com/demcha/examples/features/streaming/HttpStreamingExample.java)
 
+### Word export (DOCX)
+
+The semantic backend walks the document graph and writes **editable
+Word content** — no layout pass, no PDF chrome. One session, two
+outputs:
+
+```java
+try (DocumentSession document = GraphCompose.document(pdfFile)
+        .pageSize(595, 842)
+        .margin(DocumentInsets.of(48))
+        .create()) {
+    document.metadata(DocumentMetadata.builder()
+            .title("GraphCompose Word export companion")
+            .author("GraphCompose").build());          // → Word core properties
+
+    document.pageFlow().name("Flow")
+            .addRich(rich -> rich.plain("Inline ").bold("runs").plain(" survive."))
+            .addList(list -> list.markerFor(1, ListMarker.custom("◦"))
+                    .addItem("Nested authoring", l1 -> l1
+                            .addItem("Two spaces of indent per depth in Word")))
+            .addTable(t -> t.headerRow("Quarter", "Revenue").row("Q1", "42"))
+            .addSection("Chart", s -> s.chart(ChartSpec.bar().data(quarters).build()))
+            .build();
+
+    document.buildPdf();                                   // fixed-layout PDF
+    document.export(new DocxSemanticBackend(), docxFile);  // editable Word file
+}
+```
+
+Paragraphs (inline runs included), lists, tables, side-by-side rows,
+images, spacers, and page breaks map 1:1; session metadata lands in the
+Word core properties. Charts export as their categories-by-series data
+table (one capability warning per export), shape containers flatten to
+inline layers, and pure geometry — dividers, shapes, barcodes — stays
+PDF-only by design. Requires `org.apache.poi:poi-ooxml` on the
+classpath (the dependency is optional in the GraphCompose POM).
+
+[📄 View PDF](../assets/readme/examples/word-export-companion.pdf) ·
+[📝 Word file](../assets/readme/examples/word-export-companion.docx) ·
+[📜 Full source](src/main/java/com/demcha/examples/features/docx/WordExportExample.java)
+
 ### Layout snapshot regression
 
 The full `compose → layoutSnapshot() → LayoutSnapshotJson.toJson(...)`

docs/troubleshooting.md

@@ -44,6 +44,15 @@
             <version>${graphcompose.version}</version>
         </dependency>
 
+        <!-- DOCX export (WordExportExample): poi-ooxml is optional in the
+             GraphCompose POM, so consumers add it explicitly.
+             Keep in lockstep with the root pom's poi.version. -->
+        <dependency>
+            <groupId>org.apache.poi</groupId>
+            <artifactId>poi-ooxml</artifactId>
+            <version>5.5.1</version>
+        </dependency>
+
         <dependency>
             <groupId>ch.qos.logback</groupId>
             <artifactId>logback-classic</artifactId>

examples/README.md

@@ -3,6 +3,7 @@
 import com.demcha.examples.features.barcodes.BarcodeShowcaseExample;
 import com.demcha.examples.features.charts.ChartShowcaseExample;
 import com.demcha.examples.features.canvas.CanvasLayerExample;
+import com.demcha.examples.features.docx.WordExportExample;
 import com.demcha.examples.features.chrome.PdfChromeExample;
 import com.demcha.examples.features.lists.NestedListExample;
 import com.demcha.examples.features.shapes.ShapeContainerExample;
@@ -138,6 +139,9 @@ public static void main(String[] args) throws Exception {
         System.out.println("Generated: " + CustomBusinessThemeExample.generate());
         System.out.println("Generated: " + PdfChromeExample.generate());
 
+        // DOCX export
+        System.out.println("Generated: " + WordExportExample.generate());
+
         // Barcodes
         System.out.println("Generated: " + BarcodeShowcaseExample.generate());