|
| 1 | +# Which template system should I use? |
| 2 | + |
| 3 | +**Short answer.** For any **new** code on GraphCompose 1.6.x and later, use |
| 4 | +the [**layered**](v2-layered/README.md) template surface |
| 5 | +(`com.demcha.compose.document.templates.cv.v2.*`, paired with |
| 6 | +`*Letter` cover-letter presets in `…coverletter.v2.*`). The older |
| 7 | +[**classic**](v1-classic/README.md) surface still ships, still works, |
| 8 | +and stays supported through the 1.x line, but **the layered surface is |
| 9 | +the path forward** and is the only template family that will be in |
| 10 | +GraphCompose 2.0. |
| 11 | + |
| 12 | +This page is the decision guide. It exists because the project ships |
| 13 | +**two parallel canonical template surfaces** today, with confusingly |
| 14 | +similar names, and a new contributor needs to know which one to read |
| 15 | +and which one to write against. |
| 16 | + |
| 17 | +--- |
| 18 | + |
| 19 | +## 0. The naming, once |
| 20 | + |
| 21 | +The two surfaces have collided naming because the *codebase* and the |
| 22 | +*docs* labelled them at different points in time: |
| 23 | + |
| 24 | +| What you'll see | Where it lives | What it actually is | |
| 25 | +|---|---|---| |
| 26 | +| **"Templates v2" (in commit messages, ADR 0011, package names like `cv.v2`)** | `com.demcha.compose.document.templates.cv.v2.*` | The **layered** architecture — *data / theme / components / widgets / presets*, paired with `CvDocument` builder. Recommended. | |
| 27 | +| **"Templates v1.6" / "templates rebuild"** | `com.demcha.compose.document.templates.cv.presets.*` | The 1.6 rebuilt canonical surface — `CvSpec` + `CvBuilder` + presets + `BusinessTheme`. Still supported. | |
| 28 | +| **Folder `docs/templates/v1-classic/`** | docs only | Documents the **non-layered** surface (`cv.presets.*`). The doc folder name is *not* the same axis as the package's `v2` suffix. | |
| 29 | +| **Folder `docs/templates/v2-layered/`** | docs only | Documents the layered surface (`cv.v2.*`). | |
| 30 | + |
| 31 | +From here, this page uses one name per surface, consistently: |
| 32 | + |
| 33 | +- **`classic`** → `cv.presets.*`, documented in `docs/templates/v1-classic/` — pre-layered, still supported. |
| 34 | +- **`layered`** → `cv.v2.*` + `coverletter.v2.*`, documented in `docs/templates/v2-layered/` — recommended. |
| 35 | + |
| 36 | +ADR references: [ADR-0011 templates-v2-architecture](../adr/0011-templates-v2-architecture.md) introduces the `classic` surface; |
| 37 | +[ADR-0015 layered-template-architecture](../adr/0015-layered-template-architecture.md) introduces the `layered` one and supersedes 0011 for new template families. |
| 38 | + |
| 39 | +--- |
| 40 | + |
| 41 | +## 1. Status matrix |
| 42 | + |
| 43 | +| Surface | Status | Stability | Use for new code? | Will exist in 2.0? | First read | |
| 44 | +|---|---|---|---|---|---| |
| 45 | +| **Layered** (`cv.v2.*`, `coverletter.v2.*`) | **Recommended** | Stable (additive changes only) | ✅ Yes | ✅ Yes (canonical) | [v2-layered/quickstart](v2-layered/quickstart.md) | |
| 46 | +| **Classic** (`cv.presets.*`, paired classic letter presets) | **Supported** | Stable, no new features | 🟡 Only if migrating an existing v1.5-era caller | ❌ Removed (full migration to layered) | [v1-classic/README](v1-classic/README.md) | |
| 47 | +| **Built-in `*TemplateV2`** (Invoice / Proposal) | **Recommended** | Stable | ✅ Yes | ✅ Yes | [v1-classic/README](v1-classic/README.md) — InvoiceTemplateV2 / ProposalTemplateV2 sections | |
| 48 | +| **Built-in `*TemplateV1`** (Invoice / Proposal / WeeklySchedule) | **Legacy** | Stable, no new features | ❌ No (use V2 versions; WeeklySchedule has no V2 yet) | ❌ Removed | (no top-level doc — see source Javadoc) | |
| 49 | +| **Canonical DSL** (`GraphCompose.document()` + `DocumentSession` + `DocumentDsl`) | **Recommended** | Stable | ✅ Yes — required substrate for both template surfaces and direct authoring | ✅ Yes | [Main README — Hello world](../../README.md) | |
| 50 | +| **Legacy PDF API** (`GraphCompose.pdf(...)`, `PdfComposer`, `com.demcha.compose.v2.*`, `com.demcha.templates.*`) | **Legacy** | Frozen — bug fixes only | ❌ No | ❌ Removed | [graphcompose-legacy-architect skill](#) (internal) | |
| 51 | + |
| 52 | +> **Status definitions.** *Recommended* = the path GraphCompose 2.0 will |
| 53 | +> ship; new code targets it. *Supported* = bug fixes + structural fixes |
| 54 | +> only, no new features; existing callers keep working through 1.x. |
| 55 | +> *Legacy* = removed in 2.0; do not start new code here. |
| 56 | +
|
| 57 | +--- |
| 58 | + |
| 59 | +## 2. Decision tree |
| 60 | + |
| 61 | +``` |
| 62 | +I want to render a business document on GraphCompose. |
| 63 | +
|
| 64 | +├─ Is it a CV or cover letter? |
| 65 | +│ ├─ Yes → use a `layered` preset (cv.v2 / coverletter.v2). |
| 66 | +│ │ See [v2-layered/using-templates.md](v2-layered/using-templates.md). |
| 67 | +│ │ Existing `classic` (cv.presets.*) caller? Read § 3 below; the |
| 68 | +│ │ layered preset with the same name is a drop-in replacement |
| 69 | +│ │ for almost every case. |
| 70 | +│ │ |
| 71 | +│ └─ No → continue. |
| 72 | +│ |
| 73 | +├─ Is it an invoice or proposal? |
| 74 | +│ └─ Use `InvoiceTemplateV2` or `ProposalTemplateV2` (the `V2` variants). |
| 75 | +│ The `V1` variants exist for backward compatibility; do not start |
| 76 | +│ new code on them. |
| 77 | +│ |
| 78 | +├─ Is it a weekly schedule? |
| 79 | +│ └─ Use `WeeklyScheduleTemplateV1`. There is no V2 yet — the V1 API |
| 80 | +│ will be re-shaped before 2.0 (no concrete plan yet); track in |
| 81 | +│ the public release roadmap before adopting it long-term. |
| 82 | +│ |
| 83 | +└─ It's something else (custom shape, brochure, report)? |
| 84 | + └─ Author directly on the canonical DSL: `GraphCompose.document()` |
| 85 | + + `pageFlow(...)` or `dsl().pageFlow(...)`. Reuse `BusinessTheme` |
| 86 | + and layered widgets (`SectionDispatcher`, `EntryCompactRenderer`, |
| 87 | + `RichParagraphRenderer`, `CardWidget`) wherever they fit; lift |
| 88 | + new reusable widgets into the `cv.v2/components` and |
| 89 | + `cv.v2/widgets` packages so the next template family can share |
| 90 | + them. |
| 91 | +``` |
| 92 | + |
| 93 | +--- |
| 94 | + |
| 95 | +## 3. Migration table — `classic` → `layered` |
| 96 | + |
| 97 | +Every CV preset that shipped in `cv.presets.*` has a same-named drop-in |
| 98 | +replacement in `cv.v2.presets.*`. Migrating a caller is, in the common |
| 99 | +case, swap the import and the factory call: |
| 100 | + |
| 101 | +```diff |
| 102 | +-import com.demcha.compose.document.templates.cv.presets.NordicClean; |
| 103 | ++import com.demcha.compose.document.templates.cv.v2.presets.NordicClean; |
| 104 | + |
| 105 | +-NordicClean.create(BusinessTheme.nordicClean()).render(session, cvSpec); |
| 106 | ++NordicClean.create(cvTheme).render(session, cvDocument); |
| 107 | +``` |
| 108 | + |
| 109 | +Two real shape changes accompany the swap: |
| 110 | + |
| 111 | +1. **Theme.** `BusinessTheme.X()` → `CvTheme.X()`. The CV-specific |
| 112 | + tokens (palette / typography / spacing) are split out so `cv.v2` |
| 113 | + themes don't carry invoice / proposal vocabulary they don't use. |
| 114 | +2. **Data record.** `CvSpec` → `CvDocument`. The data shape becomes |
| 115 | + strongly-typed sections (`SectionGroup`, `EntryGroup`, `SkillGroup`, |
| 116 | + …) instead of a flat `Block` permit list. The |
| 117 | + [contributor-guide](v2-layered/contributor-guide.md) walks through |
| 118 | + the section types end-to-end. |
| 119 | + |
| 120 | +### CV presets — one-to-one mapping |
| 121 | + |
| 122 | +| `classic` (`cv.presets.*`) | `layered` (`cv.v2.presets.*`) | Cover letter (`coverletter.v2.presets.*`) | Notes | |
| 123 | +|---|---|---|---| |
| 124 | +| `BlueBanner` | `BlueBanner` | `BlueBannerLetter` | | |
| 125 | +| `BoxedSections` | `BoxedSections` | `BoxedSectionsLetter` | Reference preset for the layered architecture. | |
| 126 | +| `CenteredHeadline` | `CenteredHeadline` | `CenteredHeadlineLetter` | Layered-only in 1.6.5+; classic version is the rebuilt one. | |
| 127 | +| `ClassicSerif` | `ClassicSerif` | `ClassicSerifLetter` | | |
| 128 | +| `CompactMono` | `CompactMono` | `CompactMonoLetter` | | |
| 129 | +| `EditorialBlue` | `EditorialBlue` | `EditorialBlueLetter` | | |
| 130 | +| `EngineeringResume` | `EngineeringResume` | `EngineeringResumeLetter` | | |
| 131 | +| `Executive` | `Executive` | `ExecutiveLetter` | | |
| 132 | +| `ModernProfessional` | `ModernProfessional` | `ModernProfessionalLetter` | | |
| 133 | +| `MonogramSidebar` | `MonogramSidebar` | `MonogramSidebarLetter` | Layered version uses `pageBackgrounds(...)` for sidebar chrome (multi-page-safe). | |
| 134 | +| `NordicClean` | `NordicClean` | `NordicCleanLetter` | Layered version ships public `NordicClean.Options`. | |
| 135 | +| `Panel` | `Panel` | `PanelLetter` | | |
| 136 | +| `SidebarPortrait` | `SidebarPortrait` | `SidebarPortraitLetter` | Layered version uses `pageBackgrounds(...)`. | |
| 137 | +| `TimelineMinimal` | `TimelineMinimal` | `TimelineMinimalLetter` | | |
| 138 | +| _(no classic)_ | `MinimalUnderlined` | _(no letter yet)_ | Layered-only. | |
| 139 | +| _(no classic)_ | `MintEditorial` | `MintEditorialLetter` | Layered-only (shipped in v1.6.5). | |
| 140 | + |
| 141 | +If your caller uses a name on the left, the row tells you what to import |
| 142 | +on the right and which cover-letter preset pairs with it. |
| 143 | + |
| 144 | +### Built-ins (Invoice / Proposal / WeeklySchedule) |
| 145 | + |
| 146 | +| V1 | V2 | Migration | |
| 147 | +|---|---|---| |
| 148 | +| `InvoiceTemplateV1` | `InvoiceTemplateV2` | Same data record (`InvoiceSpec`), same `BusinessTheme`. Renderer rewrite uses layered widgets; output is visually equivalent and snapshot-tested. | |
| 149 | +| `ProposalTemplateV1` | `ProposalTemplateV2` | Same data record (`ProposalSpec`), same `BusinessTheme`. Same migration pattern as invoice. | |
| 150 | +| `WeeklyScheduleTemplateV1` | _(no V2 yet)_ | Stay on V1 until a V2 ships. | |
| 151 | + |
| 152 | +### Things that are **not** in either canonical surface (still legacy) |
| 153 | + |
| 154 | +These live under `com.demcha.compose.v2.*`, `com.demcha.templates.*`, or |
| 155 | +the `GraphCompose.pdf(...)` factory. They are the original (pre-1.6) |
| 156 | +PDF-direct authoring path. They will be removed in 2.0: |
| 157 | + |
| 158 | +- `GraphCompose.pdf(outputFile)` and `PdfComposer`. |
| 159 | +- `com.demcha.templates.MainPageCV`, `MainPageCvDTO`, `ModuleYml`, |
| 160 | + `TemplateBuilder` and friends. |
| 161 | +- `com.demcha.compose.v2.*` (engine-direct builders predating the |
| 162 | + canonical DSL). |
| 163 | + |
| 164 | +If a caller still imports any of these, the migration target is |
| 165 | +**directly the canonical DSL** (`GraphCompose.document()`) — there is no |
| 166 | +1:1 equivalent in the template surfaces, because these classes were |
| 167 | +never canonical templates, they were a PDF authoring shortcut. The |
| 168 | +[migration-v1-5-to-v1-6 roadmap](../roadmaps/migration-v1-5-to-v1-6.md) |
| 169 | +walks through the swap for the common shapes. |
| 170 | + |
| 171 | +--- |
| 172 | + |
| 173 | +## 4. Deprecation inventory — 1.x → 2.0 |
| 174 | + |
| 175 | +Read this when planning long-lived code or when auditing dependencies |
| 176 | +that may already use one of the slated-for-removal types. None of these |
| 177 | +are deleted in 1.x; the work below is anti-roadmap and lives in the |
| 178 | +private taskboard. |
| 179 | + |
| 180 | +### Removed in 2.0 |
| 181 | + |
| 182 | +| Item | Reason | Replacement | |
| 183 | +|---|---|---| |
| 184 | +| `GraphCompose.pdf(...)` factory + `PdfComposer` | PDF-direct path predates the canonical DSL; bypasses layout and rendering invariants. | `GraphCompose.document(...)` + `DocumentSession.buildPdf()`. | |
| 185 | +| `com.demcha.compose.v2.*` (the entire package) | Engine-direct builders predating canonical DSL. Mixes layout vocabulary with rendering vocabulary. | Canonical DSL surface (`document.api`, `document.dsl`, `document.node`, `document.style`). | |
| 186 | +| `com.demcha.templates.MainPageCV`, `MainPageCvDTO`, `ModuleYml`, `TemplateBuilder` | The original CV template pre-rebuild. Replaced by `cv.presets.*` (classic) in 1.6, now slated to be replaced again by `cv.v2.*` (layered). | A `cv.v2.presets.*` preset, or direct canonical DSL authoring. | |
| 187 | +| Entire `cv.presets.*` package (the `classic` surface) | Superseded by `cv.v2.presets.*` (layered). Every preset on the left has a same-named layered replacement (see § 3). | `cv.v2.presets.*`. | |
| 188 | +| `DocumentSession.builder()` (deprecated alias) | Pre-rebuild builder entry point. | `GraphCompose.document()`. | |
| 189 | +| `DocumentDsl.text(...)` (deprecated alias) | Pre-rebuild text shortcut. | `paragraph(...)` builders inside `pageFlow`. | |
| 190 | +| `DocumentPalette.of(...)` (deprecated alias) | Pre-rebuild palette factory. | `DocumentPalette.from(...)` (or theme-specific factories). | |
| 191 | +| PDF-specific chrome overloads on `BusinessTheme` | Coupled CV-specific tokens with PDF-specific decisions. | Layered `CvTheme` + render-time `pageBackgrounds(...)`. | |
| 192 | + |
| 193 | +### Open questions for 2.0 (no decision yet) |
| 194 | + |
| 195 | +- `WeeklyScheduleTemplateV1` — whether to ship a V2 along the layered |
| 196 | + architecture or to deprecate weekly schedule entirely. |
| 197 | +- `InlineRow` / `SplittableRow` / `GridNode` decisions deferred from |
| 198 | + 1.7 — may unblock magazine-style multi-column flow without needing a |
| 199 | + `GridNode` primitive (see [v1.8 engine refactor in the readiness |
| 200 | + taskboard](../private/v1.6.5-1.7-release-readiness-taskboard.md) once |
| 201 | + published). |
| 202 | + |
| 203 | +### Maven coordinates do **not** change in 2.0 |
| 204 | + |
| 205 | +The library `pom.xml` artifact id stays `graphcompose`; JitPack |
| 206 | +coordinates (`com.github.DemchaAV:GraphCompose:v<X>`) and the Maven |
| 207 | +Central coordinates being introduced in 1.6.6 (`io.github.demchaav:graphcompose:<X>`) |
| 208 | +both carry through to 2.0. |
| 209 | + |
| 210 | +--- |
| 211 | + |
| 212 | +## 5. Cross-links |
| 213 | + |
| 214 | +- **First-class architecture references** |
| 215 | + - [ADR-0011 Templates v2 architecture](../adr/0011-templates-v2-architecture.md) (the `classic` surface) |
| 216 | + - [ADR-0015 Layered template architecture](../adr/0015-layered-template-architecture.md) (the `layered` surface; supersedes 0011 for new families) |
| 217 | +- **Layered (recommended) docs** |
| 218 | + - [README](v2-layered/README.md) · [Quickstart](v2-layered/quickstart.md) · [Using templates](v2-layered/using-templates.md) · [Authoring presets](v2-layered/authoring-presets.md) · [Contributor guide](v2-layered/contributor-guide.md) |
| 219 | +- **Classic (supported) docs** |
| 220 | + - [README](v1-classic/README.md) · [Authoring](v1-classic/authoring.md) |
| 221 | +- **Migration roadmaps** |
| 222 | + - [v1.4 → v1.5](../roadmaps/migration-v1-4-to-v1-5.md) |
| 223 | + - [v1.5 → v1.6](../roadmaps/migration-v1-5-to-v1-6.md) |
| 224 | + |
| 225 | +--- |
| 226 | + |
| 227 | +*This page is maintained alongside the templates surfaces. When a new |
| 228 | +preset, built-in, or deprecation lands, update §1 (status matrix) and |
| 229 | +§3 (migration table) in the same commit. The `CanonicalSurfaceGuardTest` |
| 230 | +documentation-coverage check enforces that no legacy API token leaks |
| 231 | +into this doc.* |
0 commit comments