diff --git a/CHANGELOG.md b/CHANGELOG.md index 5c3992ac..62af1961 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -201,6 +201,21 @@ follow semantic versioning; release dates are ISO 8601. ### Documentation +- **The example catalogue stops calling current code legacy.** Two examples sat under + a heading reading "πŸ—„οΈ Legacy β€” pre-rebuild examples kept for downstream callers still + on V1; do not start new code here", pointing at a V1 β†’ V2 migration guide. There is no + V1: that surface was removed in 2.0, both examples compile against the current DSL, + and three hundred lines further down the same file called one of them a "useful + starting point". They are what they always were β€” documents assembled from primitives + with no template behind them β€” and the category now says that. +- **Reading one example no longer starts by rendering a hundred.** The run + instructions led with `GenerateAllExamples`, which empties the output directory and + regenerates the whole catalogue, and only afterwards mentioned running a single class. + A newcomer following the page in order paid for the catalogue before seeing one + document. Single-example first now, with the rule for deriving any other example's + main class from its source path, and the batch entry point below it β€” described as + what it actually is, the source both `cut-release.ps1` and `ShowcaseSync` read from + rather than something that publishes anything itself. - **The landing page lets you run it before it finishes selling it.** Ninety-one lines and twelve images stood between the title and `## Installation`, most of them a second showcase: thirty-five lines demonstrating the PowerPoint backend, with two renders and diff --git a/docs/recipes.md b/docs/recipes.md index a5e3c3ff..e66431a3 100644 --- a/docs/recipes.md +++ b/docs/recipes.md @@ -35,15 +35,12 @@ authoring API; public application code should not import For longer-form material: - [Extension guide](contributing/extension-guide.md) β€” walkthrough of the four - extension paths with the v1.5 `ShapeContainerNode` work as a - worked example. -- [Migration v1.4 β†’ v1.5](roadmaps/migration-v1-4-to-v1-5.md) β€” every public - API change in v1.5 plus suggested migration order. + extension paths, with `ShapeContainerNode` as the worked example. - [Font coverage and glyph fallback](font-coverage.md) β€” WinAnsi limits, `●` vs `β€’`, and the inline-shape / bundled-font alternatives. - [`ADR 0001 β€” Shape as container`](adr/0001-shape-as-container.md) and [`ADR 0002 β€” Theme unification`](adr/0002-theme-unification.md) - for the design reasoning behind the two largest v1.5 additions. + for the design reasoning behind shape containers and the unified theme model. ## Common DSL primitives β€” quick snippets diff --git a/examples/README.md b/examples/README.md index dca9e03b..4b26768c 100644 --- a/examples/README.md +++ b/examples/README.md @@ -1,7 +1,7 @@ # GraphCompose Examples A runnable, single-file Java example for every public surface in -GraphCompose β€” built-in templates, v1.5 cinematic features, public-API +GraphCompose β€” built-in templates, cinematic layout features, public-API showcases, and a kitchen-sink master demo. Each example writes a PDF to `examples/target/generated-pdfs/`; the same PDFs are committed to [`assets/readme/examples/`](../assets/readme/examples/) so you can @@ -15,24 +15,33 @@ Install the library artifact once from the repository root: ./mvnw -DskipTests install ``` -Then run every example in one shot: +Then run one example by passing its main class: ```bash ./mvnw -f examples/pom.xml exec:java \ - -Dexec.mainClass=com.demcha.examples.GenerateAllExamples + -Dexec.mainClass=com.demcha.examples.flagships.ModuleFirstFileExample ``` -…or run a single example by passing its main class: +For a different one, take a row from [πŸš€ Start here](#-start-here) below and turn its +Source path into a class name: drop `src/main/java/` and `.java`, then swap `/` for `.`. +So `src/main/java/com/demcha/examples/flagships/ModuleFirstFileExample.java` becomes +`com.demcha.examples.flagships.ModuleFirstFileExample`. + +Generated PDFs land in `examples/target/generated-pdfs/`. The same `mvnw.cmd` form +works on Windows PowerShell with backslash paths. + +To regenerate the **whole catalogue** β€” roughly a hundred documents, and the output +directory is emptied first β€” run the batch entry point. You do not need it to read one +example; it exists because two other things consume its output. `cut-release.ps1` +re-copies the committed subset under `assets/readme/examples/` from it, and +`ShowcaseSync` mirrors the full catalogue into the static site under `web/showcase/`, +rendering the PNG thumbnails and rewriting `web/examples.json`: ```bash ./mvnw -f examples/pom.xml exec:java \ - -Dexec.mainClass=com.demcha.examples.flagships.MasterShowcaseExample + -Dexec.mainClass=com.demcha.examples.GenerateAllExamples ``` -Generated PDFs land in `examples/target/generated-pdfs/`. The runner empties that -directory first, so what is left is exactly what this run produced. The same -`mvnw.cmd` form works on Windows PowerShell with backslash paths. - The documents that print a version take it from the reactor, which between releases sits on the next patch. To reproduce a published document from a development branch, name the published version: @@ -65,7 +74,7 @@ are with the canonical DSL, then jump to its detailed section below. > 🧱 **Core DSL** β€” features you'll author against every day once the basics click. > πŸ“‹ **Templates recommended** β€” the v2 / layered template surfaces and how to drive them; pick when you want a one-line CV / invoice / proposal / cover-letter. > πŸ”§ **Advanced SPI** β€” production-deployment patterns, specialty SPIs (shapes, transforms, barcodes), engine-level tools (snapshots). -> πŸ—„οΈ **Legacy** β€” pre-rebuild examples kept for downstream callers still on V1; do not start new code here. See [`docs/templates/which-template-system.md`](../docs/templates/which-template-system.md) for the V1 β†’ V2 migration path. +> ✍️ **Hand-composed** β€” no template involved: the same primitives assembled directly, for when your document is not one of the built-in families. ### πŸš€ Start here @@ -135,16 +144,16 @@ are with the canonical DSL, then jump to its detailed section below. | [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) | | [Debug overlay](#debug-overlay) | `DocumentDebugOptions` β€” guide lines + semantic node-path labels on the sheet; trace any misplaced block back to the builder call that authored it | [PDF](../assets/readme/examples/debug-overlay.pdf) Β· [Source](src/main/java/com/demcha/examples/features/debug/DebugOverlayExample.java) | | [Business report cover](#business-report-cover) | Single-page Q1 investor brief β€” hero image, KPI cards, bar chart, metrics table; the same composition also renders as an editable PowerPoint deck (KPI cards, chart, and table stay native shapes) via `buildPptx()` | [PDF](../assets/readme/examples/business-report.pdf) Β· [PPTX](../assets/readme/examples/business-report.pptx) Β· [Source](src/main/java/com/demcha/examples/flagships/BusinessReportExample.java) Β· [PPTX source](src/main/java/com/demcha/examples/flagships/BusinessReportPptxExample.java) | -| Financial report one-pager | Single-page monthly financial dashboard β€” three margin gauges, cash & stacked-OPEX charts, a revenue donut, and forecast bars; all v1.8 native vector charts plus inline sparklines and a path-clipped photo masthead; the same composition also renders as an editable PowerPoint deck via `buildPptx()` | [PDF](../assets/readme/examples/financial-report.pdf) Β· [PPTX](../assets/readme/examples/financial-report.pptx) Β· [Source](src/main/java/com/demcha/examples/flagships/FinancialReportExample.java) Β· [PPTX source](src/main/java/com/demcha/examples/flagships/FinancialReportPptxExample.java) | +| Financial report one-pager | Single-page monthly financial dashboard β€” three margin gauges, cash & stacked-OPEX charts, a revenue donut, and forecast bars; native vector charts plus inline sparklines and a path-clipped photo masthead; the same composition also renders as an editable PowerPoint deck via `buildPptx()` | [PDF](../assets/readme/examples/financial-report.pdf) Β· [PPTX](../assets/readme/examples/financial-report.pptx) Β· [Source](src/main/java/com/demcha/examples/flagships/FinancialReportExample.java) Β· [PPTX source](src/main/java/com/demcha/examples/flagships/FinancialReportPptxExample.java) | | [Master showcase](#master-showcase) | Kitchen-sink "Q2 sample report" combining the canonical surface end-to-end; the same composition also renders as a multi-slide editable PowerPoint deck via `buildPptx()` | [PDF](../assets/readme/examples/master-showcase.pdf) Β· [PPTX](../assets/readme/examples/master-showcase.pptx) Β· [Source](src/main/java/com/demcha/examples/flagships/MasterShowcaseExample.java) Β· [PPTX source](src/main/java/com/demcha/examples/flagships/MasterShowcasePptxExample.java) | | Feature catalog | Browsable reference PDF: every shipped capability as a block β€” outline-clickable heading, the exact API call, the rendered result right under it | [PDF](../assets/readme/examples/feature-catalog.pdf) Β· [Source](src/main/java/com/demcha/examples/flagships/FeatureCatalogExample.java) | -| Book template | A full novel front: full-bleed wave cover, a clickable dotted-leader table of contents with live page numbers, and chapters β€” the v1.9 book primitives (`pageMargins`, `addTableOfContents`, `DocumentPageNumbering`, container `bookmark`, `viewerPreferences`) in **one session**, no external PDF merge | [PDF](../assets/readme/examples/book-template.pdf) Β· [Source](src/main/java/com/demcha/examples/features/title/BookTemplateExample.java) | +| Book template | A full novel front: full-bleed wave cover, a clickable dotted-leader table of contents with live page numbers, and chapters β€” the book primitives (`pageMargins`, `addTableOfContents`, `DocumentPageNumbering`, container `bookmark`, `viewerPreferences`) in **one session**, no external PDF merge | [PDF](../assets/readme/examples/book-template.pdf) Β· [Source](src/main/java/com/demcha/examples/features/title/BookTemplateExample.java) | -### πŸ—„οΈ Legacy +### ✍️ Hand-composed | Example | What it shows | Preview Β· Source | |---|---|---| -| [Handcrafted Proposal](#handcrafted-proposal) | v1.4-style cinematic proposal composed by hand β€” pre-template authoring; kept for parity reference | [PDF](../assets/readme/examples/project-proposal-cinematic.pdf) Β· [Source](src/main/java/com/demcha/examples/templates/proposal/CinematicProposalFileExample.java) | +| [Handcrafted Proposal](#handcrafted-proposal) | A cinematic proposal assembled from primitives, with no template behind it β€” the shape to copy when your document is not one of the built-in families | [PDF](../assets/readme/examples/project-proposal-cinematic.pdf) Β· [Source](src/main/java/com/demcha/examples/templates/proposal/CinematicProposalFileExample.java) | | [Weekly schedule](#weekly-schedule) | Bar / restaurant shift schedule via `WeeklyScheduleRenderer` | [PDF](../assets/readme/examples/weekly-schedule.pdf) Β· [Source](src/main/java/com/demcha/examples/templates/schedule/WeeklyScheduleFileExample.java) | --- @@ -302,17 +311,16 @@ themed headings, timeline + pricing tables with ### Handcrafted proposal -A v1.4-style cinematic proposal composed by hand β€” no template β€” to -show how the same primitives compose without a `XxxTemplateV2` -wrapper. Useful starting point when your domain doesn't fit any -built-in template. +A cinematic proposal composed by hand β€” no template β€” to show how the +same primitives compose without a preset wrapping them. Useful starting +point when your domain doesn't fit any built-in template. [πŸ“„ View PDF](../assets/readme/examples/project-proposal-cinematic.pdf) Β· [πŸ“œ Full source](src/main/java/com/demcha/examples/templates/proposal/CinematicProposalFileExample.java) --- -## v1.5 feature showcases +## Feature showcases ### Shape containers @@ -345,10 +353,10 @@ for screen-space nudges. attached to any `Transformable` builder (`ShapeContainerBuilder`, `ShapeBuilder`, `LineBuilder`, `EllipseBuilder`, `ImageBuilder`, `BarcodeBuilder`). Identity -transforms emit no markers, so layout snapshots stay byte-identical to -v1.4. Per-layer `zIndex` lets a layer declared earlier draw on top of -layers declared later β€” `LayerStackNode.Layer` and shape-container -layers both gain `int zIndex` (default `0`). +transforms emit no markers, so adding one leaves a layout snapshot +byte-identical. Per-layer `zIndex` lets a layer declared earlier draw on +top of layers declared later β€” `LayerStackNode.Layer` and shape-container +layers both carry an `int zIndex` (default `0`). ```java