DocumentationExamplesTest.java

package com.demcha.documentation;

import com.demcha.compose.GraphCompose;
import com.demcha.compose.document.api.DocumentPageSize;
import com.demcha.compose.document.api.DocumentSession;
import com.demcha.compose.document.image.DocumentImageFitMode;
import com.demcha.compose.document.templates.api.InvoiceTemplate;
import com.demcha.compose.document.templates.builtins.InvoiceTemplateV1;
import com.demcha.compose.document.templates.data.invoice.InvoiceDocumentSpec;
import com.demcha.compose.document.style.DocumentColor;
import com.demcha.compose.document.style.DocumentInsets;
import com.demcha.compose.document.style.DocumentStroke;
import com.demcha.compose.document.style.DocumentTextStyle;
import com.demcha.compose.document.table.DocumentTableColumn;
import com.demcha.compose.document.table.DocumentTableStyle;
import com.demcha.compose.font.FontName;
import com.demcha.testing.VisualTestOutputs;
import org.apache.pdfbox.Loader;
import org.apache.pdfbox.pdmodel.PDDocument;
import org.junit.jupiter.api.Test;

import java.awt.Color;
import java.awt.image.BufferedImage;
import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.List;
import java.util.TreeSet;
import java.util.stream.Collectors;
import javax.imageio.ImageIO;

import static org.assertj.core.api.Assertions.assertThat;

class DocumentationExamplesTest {
    private static final String LEGACY_RENDER_CALL = ".render(";
    private static final String LEGACY_PDF_ENTRYPOINT = "GraphCompose" + ".pdf(";
    private static final String LEGACY_PDF_COMPOSER = "Pdf" + "Composer";
    private static final String LEGACY_TEMPLATE_BUILDER = "Template" + "Builder";
    private static final String LEGACY_TEMPLATE_NAMESPACE = "com.demcha." + "templates";
    private static final String LEGACY_V2_NAMESPACE = "com.demcha.compose." + "v2";
    private static final String FIELD_BASED_CV = "MainPage" + "CV";
    private static final String FIELD_BASED_CV_REWRITE = "MainPage" + "CvDTO";
    private static final String FIELD_BASED_CV_MODULE = "Module" + "Yml";

    @Test
    void shouldRenderQuickStartExampleToFile() throws Exception {
        Path outputFile = VisualTestOutputs.preparePdf("quick-start", "clean", "documentation");

        try (DocumentSession document = GraphCompose.document(outputFile)
                .pageSize(DocumentPageSize.A4)
                .margin(24, 24, 24, 24)
                .create()) {
            document.pageFlow(page -> page
                    .module("Summary", module -> module.paragraph("Hello GraphCompose")));

            document.buildPdf();
        }

        assertPdfFileLooksValid(outputFile);
    }

    @Test
    void shouldRenderInMemoryQuickStartExampleToBytes() throws Exception {
        byte[] pdfBytes;
        Path outputFile = VisualTestOutputs.preparePdf("quick-start-bytes", "clean", "documentation");

        try (DocumentSession document = GraphCompose.document()
                .pageSize(DocumentPageSize.A4)
                .margin(24, 24, 24, 24)
                .create()) {
            document.pageFlow(page -> page
                    .module("Summary", module -> module.paragraph("In-memory PDF")));

            pdfBytes = document.toPdfBytes();
        }

        assertPdfBytesLookValid(pdfBytes, outputFile);
    }

    @Test
    void shouldRenderSectionDslExampleToBytes() throws Exception {
        byte[] pdfBytes;
        Path outputFile = VisualTestOutputs.preparePdf("section-dsl-bytes", "clean", "documentation");

        try (DocumentSession document = GraphCompose.document()
                .pageSize(DocumentPageSize.A4)
                .margin(24, 24, 24, 24)
                .create()) {
            document.compose(dsl -> dsl.pageFlow(flow -> flow
                    .name("TemplateStyleFlow")
                    .spacing(12)
                    .addSection("Profile", section -> section
                            .spacing(6)
                            .addParagraph("Profile")
                            .addParagraph(paragraph -> paragraph
                                    .text("Analytical engineer focused on reliable platform design.")
                                    .padding(DocumentInsets.of(4))))));

            pdfBytes = document.toPdfBytes();
        }

        assertPdfBytesLookValid(pdfBytes, outputFile);
    }

    @Test
    void shouldRenderRoundedCardRecipeToFile() throws Exception {
        Path outputFile = VisualTestOutputs.preparePdf("rounded-card", "clean", "documentation");

        try (DocumentSession document = GraphCompose.document(outputFile)
                .pageSize(DocumentPageSize.A4)
                .margin(24, 24, 24, 24)
                .create()) {
            document.pageFlow(page -> page
                    .spacing(12)
                    .addSection("InfoCard", card -> card
                            .fillColor(DocumentColor.rgb(245, 248, 255))
                            .stroke(DocumentStroke.of(DocumentColor.ROYAL_BLUE, 0.8))
                            .cornerRadius(10)
                            .padding(DocumentInsets.of(12))
                            .margin(DocumentInsets.bottom(10))
                            .addParagraph(paragraph -> paragraph
                                    .text("Block text inside a filled rounded card.")
                                    .textStyle(DocumentTextStyle.DEFAULT)
                                    .lineSpacing(2))));

            document.buildPdf();
        }

        assertPdfFileLooksValid(outputFile);
    }

    @Test
    void shouldRenderModuleFirstDslExampleToFile() throws Exception {
        Path outputFile = VisualTestOutputs.preparePdf("module-first-dsl", "clean", "documentation");

        try (DocumentSession document = GraphCompose.document(outputFile)
                .pageSize(DocumentPageSize.A4)
                .margin(24, 24, 24, 24)
                .create()) {
            document.pageFlow()
                    .name("CandidateProfile")
                    .spacing(12)
                    .module("Professional Summary", module -> module.paragraph(
                            "Platform engineer focused on clean document APIs and stable render output."))
                    .module("Technical Skills", module -> module.bullets(
                            "Java 21",
                            "Spring Boot",
                            "PDFBox",
                            "Testing and visual regression"))
                    .module("Projects", module -> module.rows(
                            "GraphCompose - Canonical document engine migration and template architecture.",
                            "Template Studio - Internal tooling for invoice, CV, and proposal design."))
                    .build();

            document.buildPdf();
        }

        assertPdfFileLooksValid(outputFile);
    }

    @Test
    void shouldRenderComposeFirstBuiltInTemplateExampleToFile() throws Exception {
        Path outputFile = VisualTestOutputs.preparePdf("compose-first-invoice-template", "clean", "documentation");
        InvoiceTemplate template = new InvoiceTemplateV1();

        try (DocumentSession document = GraphCompose.document(outputFile)
                .pageSize(DocumentPageSize.A4)
                .margin(22, 22, 22, 22)
                .create()) {
            template.compose(document, sampleInvoice());
            document.buildPdf();
        }

        assertPdfFileLooksValid(outputFile);
    }

    @Test
    void runnableExamplesShouldUseCanonicalDocumentTemplates() throws IOException {
        Path examplesRoot = Path.of("examples/src/main/java/com/demcha/examples").toAbsolutePath().normalize();

        try (var paths = Files.walk(examplesRoot)) {
            List<String> violations = new TreeSet<>(paths
                    .filter(Files::isRegularFile)
                    .filter(path -> path.toString().endsWith(".java"))
                    .filter(this::containsLegacyTemplateOrPdfApi)
                    .map(path -> examplesRoot.relativize(path).toString().replace('\\', '/'))
                    .collect(Collectors.toList()))
                    .stream()
                    .toList();

            assertThat(violations).isEmpty();
        }
    }

    @Test
    void shouldRenderAvailableFontsPreviewExample() throws Exception {
        Path outputFile = VisualTestOutputs.preparePdf("available-fonts-preview", "clean", "documentation");

        GraphCompose.renderAvailableFontsPreview(outputFile);

        assertThat(GraphCompose.availableFonts())
                .contains(FontName.HELVETICA, FontName.LATO, FontName.SPECTRAL);
        assertPdfFileLooksValid(outputFile);
    }

    @Test
    void shouldRenderLinePrimitiveExampleToFile() throws Exception {
        Path outputFile = VisualTestOutputs.preparePdf("line-primitive", "clean", "documentation");

        try (DocumentSession document = GraphCompose.document(outputFile)
                .pageSize(DocumentPageSize.A4)
                .margin(24, 24, 24, 24)
                .create()) {
            document.pageFlow()
                    .name("LinePrimitives")
                    .spacing(12)
                    .margin(DocumentInsets.of(8))
                    .addDivider(divider -> divider
                            .name("HorizontalRule")
                            .width(220)
                            .thickness(3)
                            .color(DocumentColor.ROYAL_BLUE)
                            .padding(DocumentInsets.of(6)))
                    .addShape(shape -> shape
                            .name("VerticalAccent")
                            .size(3, 90)
                            .fillColor(DocumentColor.ORANGE)
                            .padding(DocumentInsets.of(6)))
                    .build();

            document.buildPdf();
        }

        assertPdfFileLooksValid(outputFile);
    }

    @Test
    void shouldRenderSpacerLineAndCircleRecipeToFile() throws Exception {
        Path outputFile = VisualTestOutputs.preparePdf("spacer-line-circle", "clean", "documentation");

        try (DocumentSession document = GraphCompose.document(outputFile)
                .pageSize(DocumentPageSize.A4)
                .margin(24, 24, 24, 24)
                .create()) {
            document.pageFlow(page -> page
                    .name("VisualPrimitives")
                    .spacing(8)
                    .addSpacer(spacer -> spacer.name("Gap").height(12))
                    .addLine(line -> line
                            .name("Rule")
                            .horizontal(180)
                            .thickness(2)
                            .color(DocumentColor.ROYAL_BLUE))
                    .addEllipse(ellipse -> ellipse
                            .name("Badge")
                            .circle(24)
                            .fillColor(DocumentColor.ORANGE)
                            .stroke(DocumentStroke.of(DocumentColor.BLACK, 0.5))));

            document.buildPdf();
        }

        assertPdfFileLooksValid(outputFile);
    }

    @Test
    void shouldRenderImageFitRecipeToFile() throws Exception {
        Path outputFile = VisualTestOutputs.preparePdf("image-fit", "clean", "documentation");
        byte[] logo = testPng(96, 32);
        byte[] avatar = testPng(48, 72);

        try (DocumentSession document = GraphCompose.document(outputFile)
                .pageSize(DocumentPageSize.A4)
                .margin(24, 24, 24, 24)
                .create()) {
            document.pageFlow(page -> page
                    .name("ImageFit")
                    .addImage(image -> image
                            .name("Logo")
                            .source(logo)
                            .fitToBounds(96, 48)
                            .fitMode(DocumentImageFitMode.CONTAIN))
                    .addImage(image -> image
                            .name("Avatar")
                            .source(avatar)
                            .fitToBounds(48, 48)
                            .fitMode(DocumentImageFitMode.COVER)));

            document.buildPdf();
        }

        assertPdfFileLooksValid(outputFile);
    }

    @Test
    void shouldRenderCanonicalTableExampleToFile() throws Exception {
        Path outputFile = VisualTestOutputs.preparePdf("table-component", "clean", "documentation");

        try (DocumentSession document = GraphCompose.document(outputFile)
                .pageSize(DocumentPageSize.A4)
                .margin(24, 24, 24, 24)
                .create()) {
            document.pageFlow()
                    .name("StatusSection")
                    .spacing(12)
                    .addTable(table -> table
                            .name("StatusTable")
                            .columns(
                                    DocumentTableColumn.fixed(90),
                                    DocumentTableColumn.auto(),
                                    DocumentTableColumn.auto())
                            .width(520)
                            .defaultCellStyle(DocumentTableStyle.builder()
                                    .padding(DocumentInsets.of(6))
                                    .build())
                            .headerStyle(DocumentTableStyle.builder()
                                    .fillColor(DocumentColor.LIGHT_GRAY)
                                    .padding(DocumentInsets.of(6))
                                    .build())
                            .header("Role", "Owner", "Status")
                            .rows(
                                    new String[]{"Engine", "GraphCompose", "Stable"},
                                    new String[]{"Feature", "Table Builder", "Canonical"}))
                    .build();

            document.buildPdf();
        }

        assertPdfFileLooksValid(outputFile);
    }

    private void assertPdfBytesLookValid(byte[] pdfBytes, Path outputFile) throws Exception {
        assertThat(pdfBytes).isNotEmpty();
        assertThat(pdfBytes.length).isGreaterThan(4);
        assertThat(new String(pdfBytes, 0, 4, StandardCharsets.US_ASCII)).isEqualTo("%PDF");

        Files.write(outputFile, pdfBytes);
        assertPdfFileLooksValid(outputFile);
    }

    private void assertPdfFileLooksValid(Path outputFile) throws Exception {
        assertThat(outputFile).exists();
        assertThat(outputFile).isRegularFile();
        assertThat(outputFile).isNotEmptyFile();

        try (PDDocument saved = Loader.loadPDF(outputFile.toFile())) {
            assertThat(saved.getNumberOfPages()).isGreaterThan(0);
        }
    }

    private boolean containsLegacyTemplateOrPdfApi(Path path) {
        try {
            String source = Files.readString(path);
            return source.contains(LEGACY_RENDER_CALL)
                    || source.contains(LEGACY_PDF_ENTRYPOINT)
                    || source.contains(LEGACY_PDF_COMPOSER)
                    || source.contains(LEGACY_TEMPLATE_BUILDER)
                    || source.contains(LEGACY_TEMPLATE_NAMESPACE)
                    || source.contains(LEGACY_V2_NAMESPACE)
                    || source.contains(FIELD_BASED_CV)
                    || source.contains(FIELD_BASED_CV_REWRITE)
                    || source.contains(FIELD_BASED_CV_MODULE);
        } catch (IOException e) {
            throw new RuntimeException("Failed to inspect " + path, e);
        }
    }

    private byte[] testPng(int width, int height) throws IOException {
        BufferedImage image = new BufferedImage(width, height, BufferedImage.TYPE_INT_RGB);
        for (int y = 0; y < height; y++) {
            for (int x = 0; x < width; x++) {
                image.setRGB(x, y, x < width / 2 ? Color.RED.getRGB() : Color.BLUE.getRGB());
            }
        }
        ByteArrayOutputStream output = new ByteArrayOutputStream();
        ImageIO.write(image, "png", output);
        return output.toByteArray();
    }

    private InvoiceDocumentSpec sampleInvoice() {
        return InvoiceDocumentSpec.builder()
                .title("Invoice")
                .invoiceNumber("GC-2026-041")
                .issueDate("02 Apr 2026")
                .dueDate("16 Apr 2026")
                .reference("Platform Refresh Sprint")
                .status("Pending")
                .fromParty(party -> party
                        .name("GraphCompose Studio")
                        .addressLines("18 Layout Street", "London, UK", "EC1A 4GC")
                        .email("billing@graphcompose.dev")
                        .phone("+44 20 5555 1000")
                        .taxId("GB-99887766"))
                .billToParty(party -> party
                        .name("Northwind Systems")
                        .addressLines("Attn: Finance Team", "410 Market Avenue", "Manchester, UK")
                        .email("ap@northwind.example")
                        .phone("+44 161 555 2200")
                        .taxId("NW-2026-01"))
                .lineItem("Discovery workshop", "Stakeholder interviews and current-state review", "1", "GBP 1,450", "GBP 1,450")
                .lineItem("Template architecture", "Reusable document flows for invoice and proposal output", "2", "GBP 980", "GBP 1,960")
                .lineItem("Render QA", "Visual validation and guideline passes", "3", "GBP 320", "GBP 960")
                .lineItem("Developer enablement", "Examples module and onboarding notes", "1", "GBP 780", "GBP 780")
                .summaryRow("Subtotal", "GBP 5,150")
                .summaryRow("VAT (20%)", "GBP 1,030")
                .totalRow("Total", "GBP 6,180")
                .note("Please include the invoice number on your remittance advice.")
                .note("All work was delivered as agreed during the April implementation window.")
                .paymentTerm("Payment due within 14 calendar days.")
                .paymentTerm("Bank transfer preferred; contact billing@graphcompose.dev for remittance details.")
                .paymentTerm("Late payments may delay additional template customization work.")
                .footerNote("Thank you for choosing GraphCompose for production document rendering.")
                .build();
    }
}