diff --git a/CHANGELOG.md b/CHANGELOG.md index eaeda76dd..4f3b911ca 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,7 +3,246 @@ All notable changes to GraphCompose are documented here. Versions follow semantic versioning; release dates are ISO 8601. -## v2.2.1 — Planned +## v2.3.0 — Planned + +### Public API + +- **A CV section whose shape is a value, for CVs assembled at runtime.** The four + section records each fix one shape at compile time, which is right when a CV is + written in Java — you pick the record, the compiler checks it. It is the wrong model + when the CV arrives as data: a user who has just chosen "Volunteering, shaped like + Education, with dates" cannot instantiate a different record per choice, so every + shape somebody thought of would have to become a type. + + `ModuleSection` carries the choice instead. One `CvItem` record holds every optional + field — title, link, subtitle, period, location, description lines — and a `CvKind` + (`PARAGRAPH`, `BULLETS`, `BULLETS_STACKED`, `INLINE_LIST`, `ENTRIES`, + `ENTRIES_DATED`) decides which of them are read: the same item renders with or without its dates depending on the kind + alone. `BodyStyle` decides whether a description reads as prose or as bullets, and + `SectionRole` states what a section *means* — the decision multi-column presets make + by matching headings against English keywords, which a CV headed `Ausbildung` or + `Навыки` never matches. The presets do not read the role yet; it travels with the + section now so a document built today needs no rewrite when the routing work lands. + + The existing four records are untouched and mix with modules in the same document. + A module renders through the existing components rather than beside them, so one + drawn as `ENTRIES_DATED` lays out exactly like the `EntriesSection` carrying the same + content — held node-for-node by a parity suite, for every kind, alongside the + extracted text so structure and content are both pinned. The addition is binary- + compatible (the japicmp gate covers this module); it is a fifth permit on a sealed + interface, so a downstream `switch` over `CvSection` that was exhaustive without a + `default` needs one. + +- **Which presets can be handed a runtime module, declared rather than assumed.** A module + is only useful if the template renders it, and not every preset can promise that: + several compose a fixed set of modules and find each by matching headings, so a + section they do not recognise never reaches a renderer. The CV still comes out — + minus a section, looking finished — which is the kind of failure nobody reports. + + `ModularCvTemplate` is the promise, and `CvTemplates.modular()` is the list a CV + builder should offer; `CvTemplates` also answers `byId`, `all`, `ids`, and + `recommendedMargin`, so picking a preset at runtime stops being a hand-kept map in + every consumer. Declaring the interface is not free: `ModularCvTemplateFidelityTest` + renders a document carrying every kind, an invented heading, a heading in a + script no keyword list contains, and a heading that *does* match one, through each + template that declares it, and asserts every item reached the page under the words + the author wrote — the last case because `EditorialBlue` renamed any heading + matching "certification" to EDUCATION, so "Certifications & Awards" arrived as a + word nobody had written. The promise covers `Slot.MAIN`, and says so: every shipped + preset composes a single main column, so a sidebar section is dropped by these + templates as by every other. Seven presets qualify today. `ClassicSerif` does not, + and finding that out is what the gate is for — it draws any shape it is given, but + only gives itself the sections it recognises. + + `CvTemplatesCoverageTest` derives the catalogue from the presets package rather than + trusting it, so a preset that ships without being registered fails the build instead + of being invisible to every caller that looks a template up by id. + +- **Columns that continue on the next page.** A row places its children in one band and + is atomic: the band must fit the page it starts on. That is right for a row of cells + and fatal for a document body — a two-column layout built from a row holds exactly one + page, and the moment it holds more the compiler throws `AtomicNodeTooLargeException`, + which is why such layouts carry truncation limits to stay under it. + + `addColumnFlow(...)` places the same columns and lets each break where it runs out of + page. The mechanism is the one the engine already had rather than a new one: a section + spans pages because the compiler places its children one at a time against a page + cursor and any child may start a new page, so a column flow gives each column its own + cursor from the flow's entry position and rejoins them at the end — everything inside a + column breaks exactly as it does anywhere else. The flow ends on the last page any + column reached, and what follows continues below the longest one. + + Rows are untouched and stay atomic; the new node is a sibling, not a change of + behaviour, and every existing layout snapshot and visual baseline is byte-identical. + `ColumnFlowPaginationTest` renders the same content twice — through a row, which + throws, and through a column flow, which paginates — then pins what the flow has to + hold while doing it: nothing dropped, reordered, or skipped over a page; a short + column neither stretches nor pulls the next block up; a panelled column is repainted + on every page it reaches; and a `keepWithNext` heading above the flow stays on the + page it was reached on rather than jumping and stranding the rest of that page. A + column flow inside a row slot or a stack layer is refused with the reason: those + layers are pinned to one page, and a flow that advances pages would have run past the + band and overlapped what followed. + +- **Sidebar Portrait stops truncating the sections it draws.** The preset held its body in + one row, and a row must fit the page it starts on, so it capped every block to stay under + that bound: two jobs, two degrees, five skills, three languages, two projects. A denser + CV came out looking finished, one job short, with nothing to tell the reader — and the + caps could not simply be deleted, because uncapped content raised + `AtomicNodeTooLargeException` instead of paginating. (A section the preset has no slot + for is still dropped; that is a separate, documented limit of every fixed-layout preset.) + + The body is a column flow now and the caps are gone: both columns continue onto the pages + they need, and the page backgrounds keep painting both fills on every page. + `SidebarPortraitContentFidelityTest` renders a career denser than one page and asserts + that each of its four degrees, twelve skills, five languages, five employers and three + projects reached the PDF, that both columns — not only the main one — carried past the + first page, and that they stayed side by side. The visual baseline and the committed + preview are both re-recorded, and each now runs to two pages. + + Two smaller changes ride along. The rule under each main-column section title fills the + column instead of drawing a fixed 346pt: that width was 21pt wider than the column's + content box on A4 and wider still on a narrower page — a row slot never checks a child's + measured width, and a column does. And each section heading is now kept with the block it + introduces, as in every single-column preset; a body that can break at all is a body that + can strand its heading at the foot of a page. + + The portrait geometry is still A4-sized, which now has an edge: below roughly 310pt of + page width the sidebar column has no room for the photo and the layout fails instead of + drawing it over the main column. + +- **Monogram Sidebar renders the whole CV it is handed too.** The same shape as Sidebar + Portrait, and the same caps: two jobs, two degrees, seven skills, three projects, three + additional rows, with everything past them dropped in silence because the body was one + atomic row that had to fit its page. The body is a column flow now, the caps are gone, + and the preset reserves the same half-inch safe area on the pages it continues onto — + its recommended margin is zero so the sidebar fill can reach the paper edge. + + Two visual changes ride along. The rule under each main-column section title fills the + column instead of drawing a fixed 355pt: that width fit A4's 360.83pt content box with + 5.8pt to spare and stopped fitting below a page width of about 587pt, where a row slot + drew it over the sidebar without a word — a fixed slot does not check a child's measured + width, and a column does. Filling also ends the rule on the column's own edge rather + than 5.8pt short of it. And both columns' section headings are now kept with the block + they introduce, as in every single-column preset; wrapping the sidebar heading in its + own group tightens that column's rhythm slightly, which is visible in the re-recorded + baseline. + + One behaviour is newly strict: the monogram badge is a fixed 122pt, so a page narrower + than about 450pt no longer has a sidebar column wide enough for it and the layout says + so. The same page used to come out with the badge drawn over the main column. + + `MonogramSidebarPaginationTest` renders a career denser than one page and asserts every + degree, skill, position, project and additional row reached the PDF; that the sidebar + carried onto page 2 while the main column finished on page 1 — each column taking the + pages it needs; that a continuation page keeps its first line off the trimmed edge, + measured again with the rule taken back off so the number is attributable to it; that + page 1 is laid out identically either way; and that every heading is bound to the block + it introduces. Baseline and committed preview re-recorded; the canonical CV now runs to + two pages. + +- **A safe area on the pages a body continues onto.** A container's padding is an edge of + the container: reserved once, at the top of the page it opens on and the bottom of the + page it closes on. The page margin is the inset applied once per page. In an ordinary + document the distinction never surfaces, because the margin is already holding content + off the paper edge everywhere. It surfaces in a full-bleed layout, which sets the margin + to zero so a page background can reach the paper edge — giving up the safe area on all + four sides when only the two horizontal ones had to go. A continuation page then opens + wherever the break happened to leave the first line — 3pt from the trimmed edge in the + dense CV the tests measure, inside the band most printers cannot reach; before the body + paginated there was no second page for it to happen on. + + `ContinuationSafeArea.applyTo(session, firstContinuationPage, topSafeArea)` (in + `templates`) raises the top margin from the page you name onward and keeps the other + three edges of whatever margin the caller chose, so the layout stays full-bleed + horizontally and page backgrounds — ratios of the page, not of the content box — keep + bleeding on every page. The pages before it are left alone: a body's first page owns its + own top edge. It does nothing at all when the margin already provides the safe area, so a + template can call it unconditionally without turning an ordinary document into a per-page + one — and, because it does nothing rather than handing back an empty rule list, without + clearing rules its caller set. The mechanism it writes is the existing + `PageMarginRule.from(...)`; what the helper adds is the decision, which is why it sits in + `templates` rather than in the engine. `DocumentSession.margin()` reads the document + margin back, which is what lets it derive the rule from the margin the caller actually + chose rather than the one the template recommends. + + A rule that moves only the top or bottom margin now costs nothing extra to lay out. + Per-page margins are resolved through a fixed point — a block's start page decides which + page's width it is measured against — and a block's assigned start page feeds nothing but + the page's content width and left edge. A vertical-only rule leaves one width for the + whole document, so the resolver settles it in a single pass instead of recompiling to + reach the answer it already had. + + Sidebar Portrait asks for half an inch (`CONTINUATION_TOP_SAFE_AREA`), which adds 36pt to + wherever a continuation page's first line landed — 3pt becomes 39pt in that CV — and + leaves page 1 laid out identically; its visual baseline and committed preview are + re-recorded again. Monogram Sidebar takes the same call in the entry above; Mint + Editorial's 48pt margin already clears the safe area, so the helper would leave it + alone. This covers the top edge only: + content still flows to the bottom of every page it fills, and a bottom safe area is a + bottom inset on `margin(...)` itself, because unlike the top it has to apply to page 1 as + well and changes where page 1 breaks. + + `PageMarginTest` measures the defect before asserting the fix — a full-bleed column flow + whose second page opens on nothing but the spacing that preceded the break — so the guard + cannot pass on padding that was doing the work all along, and pins that a top-only rule + lays out identically to the same geometry expressed in a form that does take the fixed + point. `ContinuationSafeAreaTest` covers the helper's own decisions: the horizontal edges + it must keep, the no-op that leaves a caller's rules standing, a body that starts on page + 2 and is inset from page 3, and the arguments it refuses. + `SidebarPortraitContentFidelityTest` pins the first line's distance from the page top on + every continuation page of a dense CV, takes the rule back off to attribute the number to + it, and pins page 1's own 78pt opening either way. + +- **Presets route by what a section means, not by the language it is written in.** A + preset with a designed layout places sections into fixed slots, and it chose what went + where by matching the heading against a list of English words each preset kept + privately — then guarded the slot on the section's Java type as well. A CV headed + `Ausbildung`, `Опыт работы`, or anything else in the author's own language matched + nothing: the section was dropped and the slot that wanted it rendered empty. Nothing + failed; the CV came out looking finished, one job short. + + `SectionRouter` asks the module's `SectionRole` first and falls back to the headings + for the sections that carry no role — every hand-written one, and any module left as + `OTHER` — so a document of hand-written sections routes exactly as it did. A heading + may not overrule a role: a module declared `EXPERIENCE` and headed "Projects" goes where its + author put it, and the projects slot does not also claim it, which would have rendered + it twice. The router also hands each slot the section in the shape that slot draws, so + a module reaching a slot written against `EntriesSection` is no longer discarded by + the guard — the preset draws it exactly as it draws everything else, with the entry + style, rules and spacing that make it that preset. `SectionAllocation.claim` gained + the same role-first overload for the preset that allocates rather than looks up. + + Nine presets and every slot they compose changed; a CV written in Russian and German + now renders on all sixteen, which `RoleRoutingTest` holds by rendering one. + +- **A preset can draw runtime modules in its own style.** `CvRenderKit` is the three + shapes a section body reduces to — a paragraph, a label/value row, a timeline entry — + and a template hands back the kit it draws them with. The lowering from `CvItem` + stays shared, because deciding what a linked title looks like or which fields a kind + reads belongs to the model and must not be re-decided per preset; only the drawing is + the preset's. `BlueBanner`, `ClassicSerif`, and `EditorialBlue` now render modules + with their own entry and project shapes rather than the canonical ones — the + limitation the entry above left open. + +### Fixed + +- **A section shape a preset did not recognise was lost three different ways.** + `BlueBanner` and `ClassicSerif` each kept a private copy of the section dispatcher + whose final `else` threw `IllegalStateException`; `EditorialBlue`'s had no `else` at + all; and `SectionLookup.hasContent` — which presets consult *before* routing, and + which `SectionAllocation.remaining()` uses to decide what still needs a home — + answered `false` for any subtype it had not been taught, dropping the heading along + with the body. So a section type added to the model would have crashed two presets + and vanished from several more, including through the very fallback that exists to + catch unplaced sections. All three dispatchers now delegate unfamiliar shapes to the + canonical one, and `hasContent` answers for every permit. + +- **An entry with no date no longer reserves a column for it.** `EntryRenderer` always + emitted the two-column title/date header, so an undated entry — a certification, a + project — had its title wrapped early to leave room for nothing. Its Javadoc had + described the collapsing behaviour since the entry renderer was written. No shipped + fixture has a blank date, so no existing render moves. ### Build diff --git a/README.md b/README.md index fb97aa3c0..e63ee3bc8 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ > **Release status** — > 🟢 **Latest stable**: [v2.2.0](https://github.com/DemchaAV/GraphCompose/releases/tag/v2.2.0) — the **right-to-left** release: Hebrew and Arabic lay out, shape, join and mirror through PDF, PowerPoint and Word — in paragraphs and in table cells — with the fonts to render them. See [CHANGELOG.md](./CHANGELOG.md). ->  ·  🟡 **In development**: v2.2.1 on `develop` — see [CHANGELOG.md](./CHANGELOG.md). +>  ·  🟡 **In development**: v2.3.0 on `develop` — see [CHANGELOG.md](./CHANGELOG.md).

Live Showcase diff --git a/assets/readme/examples/cv-monogram-sidebar-v2.pdf b/assets/readme/examples/cv-monogram-sidebar-v2.pdf index 8c1fa3c10..eab9d2429 100644 Binary files a/assets/readme/examples/cv-monogram-sidebar-v2.pdf and b/assets/readme/examples/cv-monogram-sidebar-v2.pdf differ diff --git a/assets/readme/examples/cv-sidebar-portrait-v2.pdf b/assets/readme/examples/cv-sidebar-portrait-v2.pdf index 7e18a86c1..c6daf78fb 100644 Binary files a/assets/readme/examples/cv-sidebar-portrait-v2.pdf and b/assets/readme/examples/cv-sidebar-portrait-v2.pdf differ diff --git a/benchmarks/pom.xml b/benchmarks/pom.xml index 1ad6ce226..fb743b64f 100644 --- a/benchmarks/pom.xml +++ b/benchmarks/pom.xml @@ -7,7 +7,7 @@ io.github.demchaav graph-compose-build - 2.2.1-SNAPSHOT + 2.3.0-SNAPSHOT ../pom.xml diff --git a/bundle/pom.xml b/bundle/pom.xml index b4f4b508b..4a6e658d4 100644 --- a/bundle/pom.xml +++ b/bundle/pom.xml @@ -32,7 +32,7 @@ graph-compose and graph-compose-templates dependencies below use ${project.version}, so they follow automatically. --> - 2.2.1-SNAPSHOT + 2.3.0-SNAPSHOT jar GraphCompose Bundle diff --git a/core/pom.xml b/core/pom.xml index 2d53ee4cf..25cdb4bd4 100644 --- a/core/pom.xml +++ b/core/pom.xml @@ -6,7 +6,7 @@ io.github.demchaav graph-compose-core - 2.2.1-SNAPSHOT + 2.3.0-SNAPSHOT GraphCompose Core A declarative layout engine for programmatic document generation, implemented primarily in Java. This is the lean engine coordinate; depend on the `graph-compose` artifact for the drop-in, PDF-capable install. diff --git a/core/src/main/java/com/demcha/compose/document/api/DocumentSession.java b/core/src/main/java/com/demcha/compose/document/api/DocumentSession.java index 1cb74ec1c..ac39402b0 100644 --- a/core/src/main/java/com/demcha/compose/document/api/DocumentSession.java +++ b/core/src/main/java/com/demcha/compose/document/api/DocumentSession.java @@ -688,6 +688,23 @@ public LayoutCanvas canvas() { return canvas; } + /** + * Returns the document-wide page margin — whatever was last passed to + * {@link #margin(DocumentInsets)}, or zero insets when none was. + * + *

Composition code that has to reason about the page's own edges reads it + * here rather than through {@link #canvas()}, whose margin is an engine type. + * A template that derives a {@link PageMarginRule} from it — reserving a safe + * area on continuation pages, say — keeps working when the caller chooses a + * margin other than the one the template recommends.

+ * + * @return the current page margin + * @since 2.3.0 + */ + public DocumentInsets margin() { + return margin; + } + /** * Returns the usable content height of the page in points — the page height * minus the top and bottom margins. Convenience alias for diff --git a/core/src/main/java/com/demcha/compose/document/dsl/AbstractFlowBuilder.java b/core/src/main/java/com/demcha/compose/document/dsl/AbstractFlowBuilder.java index e5aa793db..5c1117801 100644 --- a/core/src/main/java/com/demcha/compose/document/dsl/AbstractFlowBuilder.java +++ b/core/src/main/java/com/demcha/compose/document/dsl/AbstractFlowBuilder.java @@ -960,6 +960,36 @@ public T addRow(String name, Consumer spec) { return add(BuilderSupport.configure(new RowBuilder().name(name), spec).build()); } + /** + * Adds a multi-column flow: columns side by side, each continuing on the + * next page. + * + *

The page-spanning counterpart to {@link #addRow(Consumer)}. A row is + * one band and is atomic, so a two-column body built from a row holds only + * as much as fits the page it starts on; a column flow lets each column + * break and resume.

+ * + * @param spec column-flow builder callback + * @return this builder + * @since 2.3.0 + */ + public T addColumnFlow(Consumer spec) { + return add(BuilderSupport.configure(new ColumnFlowBuilder(), spec).build()); + } + + /** + * Adds a named multi-column flow without repeating the name inside the + * nested builder. + * + * @param name flow name used in snapshots and layout graph paths + * @param spec column-flow builder callback + * @return this builder + * @since 2.3.0 + */ + public T addColumnFlow(String name, Consumer spec) { + return add(BuilderSupport.configure(new ColumnFlowBuilder().name(name), spec).build()); + } + /** * Adds a section configured through a nested builder. * diff --git a/core/src/main/java/com/demcha/compose/document/dsl/ColumnFlowBuilder.java b/core/src/main/java/com/demcha/compose/document/dsl/ColumnFlowBuilder.java new file mode 100644 index 000000000..90a0537d7 --- /dev/null +++ b/core/src/main/java/com/demcha/compose/document/dsl/ColumnFlowBuilder.java @@ -0,0 +1,170 @@ +package com.demcha.compose.document.dsl; + +import com.demcha.compose.document.dsl.internal.BuilderSupport; +import com.demcha.compose.document.node.ColumnFlowNode; +import com.demcha.compose.document.node.ContainerNode; +import com.demcha.compose.document.node.DocumentNode; +import com.demcha.compose.document.node.SectionNode; +import com.demcha.compose.document.style.DocumentInsets; + +import java.util.ArrayList; +import java.util.List; +import java.util.function.Consumer; + +/** + * Builder for a multi-column flow: columns side by side, each continuing on + * the next page. + * + *

Use this where a {@link RowBuilder} would cap the document at a page. A + * row places one band and is atomic — the whole band must fit where it starts, + * and a two-column body built that way can hold only as much as one page. A + * column flow places the same two columns and lets each break where it runs + * out of room:

+ * + * 
{@code
+ * flow.addColumnFlow("Body", body -> body
+ *         .gap(18)
+ *         .weights(0.72, 1.28)
+ *         .addColumn(side -> side.spacing(6).addParagraph(...))
+ *         .addColumn(main -> main.spacing(8).addParagraph(...)));
+ * }
+ * + *

Every column is a vertical container, because a column is a + * vertical flow — that is what lets its contents paginate. Anything else + * (a paragraph, an image, a nested row) belongs inside one of those columns + * rather than beside them.

+ * + *

The flow has no fill or border of its own. A column that wants a panel is + * a section with a fill, and the engine repeats a section's fill on every page + * it spans; chrome that must reach the page edge belongs in a page background, + * which paints on every page by definition.

+ * + * @author Artem Demchyshyn + * @since 2.3.0 + */ +public final class ColumnFlowBuilder { + private final List columns = new ArrayList<>(); + private final List weights = new ArrayList<>(); + private String name = ""; + private double gap; + private DocumentInsets padding = DocumentInsets.zero(); + private DocumentInsets margin = DocumentInsets.zero(); + + /** + * Creates a column-flow builder. + */ + public ColumnFlowBuilder() { + } + + /** + * Sets the diagnostic name used in snapshots and layout-graph paths. + * + * @param value flow name + * @return this builder + */ + public ColumnFlowBuilder name(String value) { + this.name = value == null ? "" : value; + return this; + } + + /** + * Sets the horizontal gap between columns. + * + * @param value gap in points; must be finite and non-negative + * @return this builder + */ + public ColumnFlowBuilder gap(double value) { + this.gap = value; + return this; + } + + /** + * Sets the relative column widths. Omit to split the width evenly. + * + * @param values one positive weight per column + * @return this builder + */ + public ColumnFlowBuilder weights(double... values) { + this.weights.clear(); + if (values != null) { + for (double value : values) { + this.weights.add(value); + } + } + return this; + } + + /** + * Sets the inner padding of the whole flow. + * + * @param value padding insets + * @return this builder + */ + public ColumnFlowBuilder padding(DocumentInsets value) { + this.padding = value == null ? DocumentInsets.zero() : value; + return this; + } + + /** + * Sets the outer margin of the whole flow. + * + * @param value margin insets + * @return this builder + */ + public ColumnFlowBuilder margin(DocumentInsets value) { + this.margin = value == null ? DocumentInsets.zero() : value; + return this; + } + + /** + * Appends a column configured through a nested section builder. + * + * @param spec column builder callback + * @return this builder + */ + public ColumnFlowBuilder addColumn(Consumer spec) { + columns.add(BuilderSupport.configure(new SectionBuilder(), spec).build()); + return this; + } + + /** + * Appends a named column configured through a nested section builder. + * + * @param name column name used in snapshots and layout-graph paths + * @param spec column builder callback + * @return this builder + */ + public ColumnFlowBuilder addColumn(String name, Consumer spec) { + columns.add(BuilderSupport.configure(new SectionBuilder().name(name), spec).build()); + return this; + } + + /** + * Appends a pre-built column. + * + * @param column a vertical container — a section or a container + * @return this builder + * @throws IllegalArgumentException if the node is not a vertical container + */ + public ColumnFlowBuilder addColumn(DocumentNode column) { + if (!(column instanceof SectionNode) && !(column instanceof ContainerNode)) { + throw new IllegalArgumentException( + "A column flow's children are columns, and a column is a vertical container " + + "(section or container) because that is what paginates. Received: " + + (column == null ? "null" : column.nodeKind()) + + ". Wrap it in a column instead."); + } + columns.add(column); + return this; + } + + /** + * Builds the immutable flow node. + * + * @return the assembled column flow + */ + public ColumnFlowNode build() { + return new ColumnFlowNode(name, List.copyOf(columns), List.copyOf(weights), + gap, padding, margin); + } +} diff --git a/core/src/main/java/com/demcha/compose/document/layout/BuiltInNodeDefinitions.java b/core/src/main/java/com/demcha/compose/document/layout/BuiltInNodeDefinitions.java index 032f1fcd6..a361517e6 100644 --- a/core/src/main/java/com/demcha/compose/document/layout/BuiltInNodeDefinitions.java +++ b/core/src/main/java/com/demcha/compose/document/layout/BuiltInNodeDefinitions.java @@ -38,6 +38,7 @@ public static NodeRegistry registerDefaults(NodeRegistry registry) { .register(new ContainerDefinition()) .register(new SectionDefinition()) .register(new RowDefinition()) + .register(new ColumnFlowDefinition()) .register(new PageReferenceDefinition()) .register(new LayerStackDefinition()) .register(new ShapeContainerDefinition()) diff --git a/core/src/main/java/com/demcha/compose/document/layout/ColumnFlowCompiler.java b/core/src/main/java/com/demcha/compose/document/layout/ColumnFlowCompiler.java new file mode 100644 index 000000000..9fde4625a --- /dev/null +++ b/core/src/main/java/com/demcha/compose/document/layout/ColumnFlowCompiler.java @@ -0,0 +1,192 @@ +package com.demcha.compose.document.layout; + +import com.demcha.compose.document.node.DocumentNode; +import com.demcha.compose.engine.components.style.Margin; +import com.demcha.compose.engine.components.style.Padding; + +import java.util.List; + +/** + * Places a {@code ColumnFlowNode}: each column flows down its own column and + * continues on the next page, and the flow ends on the last page any column + * reached. + * + *

There is no split contract here, and there does not need to be. A + * vertical composite already spans pages — not by splitting itself, but + * because {@code LayoutCompiler} places its children one at a time against a + * shared page cursor, and any child may advance that cursor to a new page. A + * column is exactly such a flow. What a column flow adds is that its columns + * do not share one cursor: each gets its own, forked from the flow's entry + * position, and the flow rejoins them at the end.

+ * + * 
+ *   fork:  every column starts at (entryPage, entryUsed)
+ *   flow:  column i is compiled through the ordinary vertical path, so
+ *          everything inside it — paragraphs, tables, nested sections —
+ *          breaks and continues exactly as it does anywhere else
+ *   join:  page   = max over columns of the page each ended on
+ *          used   = max over the columns that ended on that page
+ *
+ * + *

The join takes the height only from columns that ended on the joined + * page: a shorter column that finished two pages earlier says nothing about + * how much of the last page is occupied, and taking its cursor would let the + * next sibling overwrite the longer column.

+ * + *

Column widths are resolved once, at entry, from the flow's weights. + * Re-resolving them per page would let a column change width halfway down the + * document, and would also break the layout fixed point, which requires the + * geometry to be a pure function of the entry state. A document with per-page + * margins therefore keeps the entry page's column widths on the pages the flow + * continues onto — the same rule every nested composite already follows, since + * only a page-level column re-reads the region per page.

+ * + *

Package-private — engine surface, not public API. Mirrors + * {@link StackedLayerCompiler} in taking the host compiler and calling back + * into it rather than owning the recursion.

+ * + * @author Artem Demchyshyn + */ +final class ColumnFlowCompiler { + + private ColumnFlowCompiler() { + // Utility class, no instantiation. + } + + /** + * Compiles a column flow starting at the current cursor. + * + * @param host the compiler that owns the per-column recursion + * @param prepared the prepared flow node + * @param definition the flow's node definition + * @param path the flow's layout path + * @param semanticName the flow's semantic name + * @param parentPath the parent's layout path + * @param childIndex the flow's index among its siblings + * @param depth the flow's tree depth + * @param regionX the content region's left edge + * @param state the page cursor, mutated to the joined position + * @param prepareContext preparation context for per-column measurement + * @param fragmentContext fragment emission context + * @param nodes placed-node sink + * @param fragments placed-fragment sink + * @param margin the flow's margin + * @param padding the flow's padding + * @param availableWidth the width available to the flow's content + * @param layoutSpec the flow's child-layout contract (gap + weights) + * @param naturalMeasure the flow's measured size + */ + static void compile(LayoutCompiler host, + PreparedNode prepared, + NodeDefinition definition, + String path, + String semanticName, + String parentPath, + int childIndex, + int depth, + double regionX, + CompilerState state, + PrepareContext prepareContext, + FragmentContext fragmentContext, + List nodes, + List fragments, + Margin margin, + Padding padding, + double availableWidth, + CompositeLayoutSpec layoutSpec, + MeasureResult naturalMeasure) { + DocumentNode node = prepared.node(); + List children = definition.children(node); + + // The flow opens like any composite: reserve its top edge, which may + // itself spill to the next page. Every column then starts from there. + double startReservation = margin.top() + padding.top(); + if (startReservation > state.remainingHeight() + NodeDefinitionSupport.EPS + && state.usedHeight > NodeDefinitionSupport.EPS) { + state.newPage(); + } + state.touchPage(); + + int startPage = state.pageIndex; + double placementX = regionX + margin.left(); + double placementTopY = state.pageTop() - state.usedHeight - margin.top(); + double placementY = placementTopY - naturalMeasure.height(); + int nodeIndex = nodes.size(); + nodes.add(null); + + state.advanceSpace(startReservation); + + int endPage = state.pageIndex; + double endUsed = state.usedHeight; + int maxTouched = state.maxTouchedPage; + + if (!children.isEmpty()) { + double childRegionWidth = Math.max(0.0, availableWidth - padding.horizontal()); + RowSlots.SlotLayout slotLayout = RowSlots.resolveLayout( + node, children, layoutSpec, childRegionWidth, prepareContext, semanticName); + double[] slotWidths = slotLayout.widths(); + double cursorX = placementX + padding.left(); + + for (int index = 0; index < children.size(); index++) { + DocumentNode child = children.get(index); + Margin childMargin = LayoutInsets.toMargin(child.margin()); + double slotWidth = slotWidths[index]; + double childInnerWidth = Math.max(0.0, slotWidth - childMargin.horizontal()); + + // Each column places against its own cursor, forked from the + // flow's entry position. Fragments and placed nodes still go to + // the shared sinks in column order, so a column's decoration + // stays behind its own children. + CompilerState columnState = state.forkAtCurrentPosition(); + PreparedNode childPrepared = + host.prepareForRegionWidth(prepareContext, child, childInnerWidth); + host.compileNode( + childPrepared, + path, + index, + depth + 1, + cursorX + childMargin.left(), + childInnerWidth, + columnState, + prepareContext, + fragmentContext, + nodes, + fragments); + + if (columnState.pageIndex > endPage) { + endPage = columnState.pageIndex; + endUsed = columnState.usedHeight; + } else if (columnState.pageIndex == endPage) { + endUsed = Math.max(endUsed, columnState.usedHeight); + } + maxTouched = Math.max(maxTouched, columnState.maxTouchedPage); + + cursorX += slotWidth + layoutSpec.spacing(); + } + } + + state.rejoinAt(endPage, endUsed, maxTouched); + state.closeBottomSpace(padding.bottom() + margin.bottom()); + + nodes.set(nodeIndex, new PlacedNode( + path, + semanticName, + node.nodeKind(), + parentPath, + childIndex, + depth, + depth, + placementX, + placementY, + placementX, + placementY, + naturalMeasure.width(), + naturalMeasure.height(), + startPage, + state.pageIndex, + naturalMeasure.width(), + naturalMeasure.height(), + margin, + padding)); + } +} diff --git a/core/src/main/java/com/demcha/compose/document/layout/CompilerState.java b/core/src/main/java/com/demcha/compose/document/layout/CompilerState.java index 59bd2bb40..0fc84cc4f 100644 --- a/core/src/main/java/com/demcha/compose/document/layout/CompilerState.java +++ b/core/src/main/java/com/demcha/compose/document/layout/CompilerState.java @@ -73,6 +73,42 @@ Margin activeMargin() { return canvas.height() - activeMargin().top(); } + /** + * A second cursor over the same canvas, starting exactly where this one + * is. Used by a multi-column flow so each column advances independently: + * they all begin at the flow's entry position and are rejoined afterwards + * via {@link #rejoinAt(int, double, int)}. + * + *

The geometry is shared, not copied — per-page margins must resolve + * identically in every column, or the layout fixed point would not + * converge.

+ */ + CompilerState forkAtCurrentPosition() { + CompilerState fork = new CompilerState(canvas, geometry); + fork.pageIndex = pageIndex; + fork.usedHeight = usedHeight; + fork.maxTouchedPage = maxTouchedPage; + return fork; + } + + /** + * Moves this cursor to where the longest of several forked cursors ended. + * + *

{@code usedHeight} is meaningful only together with the page it was + * measured on, which is why the caller passes both: a column that finished + * two pages earlier says nothing about how much of the final page is + * occupied.

+ * + * @param page the page the flow ends on + * @param used the height consumed on that page + * @param touchedPage the highest page any fork reached + */ + void rejoinAt(int page, double used, int touchedPage) { + pageIndex = page; + usedHeight = Math.min(activeInnerHeight(), Math.max(0.0, used)); + maxTouchedPage = Math.max(maxTouchedPage, Math.max(touchedPage, page)); + } + void newPage() { pageIndex++; usedHeight = 0.0; diff --git a/core/src/main/java/com/demcha/compose/document/layout/CompositeLayoutSpec.java b/core/src/main/java/com/demcha/compose/document/layout/CompositeLayoutSpec.java index 7dd9d0070..cf10dfb1e 100644 --- a/core/src/main/java/com/demcha/compose/document/layout/CompositeLayoutSpec.java +++ b/core/src/main/java/com/demcha/compose/document/layout/CompositeLayoutSpec.java @@ -11,7 +11,8 @@ * * @param spacing spacing between child nodes (vertical for {@link Axis#VERTICAL}, horizontal for {@link Axis#HORIZONTAL}) * @param axis composite stacking axis - * @param weights optional per-child weights (only consulted for {@link Axis#HORIZONTAL}) + * @param weights optional per-child weights (consulted for {@link Axis#HORIZONTAL} + * and {@link Axis#COLUMN_FLOW}) */ public record CompositeLayoutSpec(double spacing, Axis axis, List weights) { /** @@ -61,6 +62,19 @@ public enum Axis { * Children flow left to right inside a single row band. */ HORIZONTAL, + /** + * Children are columns placed side by side, each flowing down its own + * column and continuing on the next page. Unlike {@link #HORIZONTAL}, + * which places one band that must fit the page it starts on, a column + * flow ends on the last page any column reached. Used by + * {@code ColumnFlowNode}. + * + *

A {@code switch} over this enum that was exhaustive without a + * {@code default} needs one.

+ * + * @since 2.3.0 + */ + COLUMN_FLOW, /** * Children share the same bounding box and are painted in source order * (first child behind, last child in front). Used by {@code LayerStackNode} diff --git a/core/src/main/java/com/demcha/compose/document/layout/DocumentLayoutResolver.java b/core/src/main/java/com/demcha/compose/document/layout/DocumentLayoutResolver.java index 08de9607c..81ac1da3c 100644 --- a/core/src/main/java/com/demcha/compose/document/layout/DocumentLayoutResolver.java +++ b/core/src/main/java/com/demcha/compose/document/layout/DocumentLayoutResolver.java @@ -68,7 +68,12 @@ public DocumentLayoutResolver(Context context) { */ public LayoutGraph resolve() { PageGeometry geometry = context.pageGeometry(); - boolean hasMargins = geometry != null; + // Only a horizontal difference makes the loop load-bearing: a block's + // assigned start page feeds nothing but the page's content width and left + // edge. Overrides that move the top or bottom margin — a continuation-page + // safe area, say — leave one width for the whole document, which the first + // pass already used, so re-running it would return the same graph. + boolean hasMargins = geometry != null && geometry.hasHorizontalOverrides(); boolean hasPageReference = context.hasPageReference(); LayoutGraph graph = compilePass(Map.of(), geometry, Map.of()); diff --git a/core/src/main/java/com/demcha/compose/document/layout/LayoutCompiler.java b/core/src/main/java/com/demcha/compose/document/layout/LayoutCompiler.java index f68b0e94e..7fd73f321 100644 --- a/core/src/main/java/com/demcha/compose/document/layout/LayoutCompiler.java +++ b/core/src/main/java/com/demcha/compose/document/layout/LayoutCompiler.java @@ -125,7 +125,7 @@ public LayoutGraph compile(DocumentGraph graph, PrepareContext prepareContext, F return layoutGraph; } - private void compileNode(PreparedNode prepared, + void compileNode(PreparedNode prepared, String parentPath, int childIndex, int depth, @@ -245,6 +245,16 @@ private void compileComposite(PreparedNode prepared, return; } + if (layoutSpec.axis() == CompositeLayoutSpec.Axis.COLUMN_FLOW) { + // Columns that each flow down their own column across pages. No + // admitAtomicBlock: unlike a row band, this node is page-spanning by + // construction, so there is no height it must fit inside. + ColumnFlowCompiler.compile(this, prepared, definition, path, semanticName, parentPath, + childIndex, depth, regionX, state, prepareContext, fragmentContext, nodes, + fragments, margin, padding, availableWidth, layoutSpec, naturalMeasure); + return; + } + if (layoutSpec.axis() == CompositeLayoutSpec.Axis.STACK) { StackedLayerCompiler.compile(this, prepared, definition, path, semanticName, parentPath, childIndex, depth, regionX, margin, padding, naturalMeasure, @@ -830,6 +840,19 @@ private double compileNodeInFixedSlot(PreparedNode prepared, // STACK composites (e.g. LayerStackNode) are always allowed // because they are atomic and anchor their children inside // the existing slot. + // A column flow advances pages; a fixed slot pins one. Placed here + // it would quietly stack its columns down the slot and run past the + // band, overlapping whatever follows — so it is rejected in both + // slot kinds rather than rendered wrong. + if (layoutSpec.axis() == CompositeLayoutSpec.Axis.COLUMN_FLOW) { + throw new IllegalStateException("Node '" + path + + "' cannot contain a column flow: a " + + (kind == FixedSlotKind.ROW_SLOT ? "row slot" : "stack layer") + + " is pinned to one page, and a column flow spans pages. " + + "Put the column flow on the page flow, or use a row for " + + "side-by-side content that fits one page."); + } + if (layoutSpec.axis() == CompositeLayoutSpec.Axis.HORIZONTAL && kind == FixedSlotKind.ROW_SLOT) { throw new IllegalStateException("Row '" + path @@ -1019,7 +1042,7 @@ private double compileNodeInFixedSlot(PreparedNode prepared, return measure.height() + margin.vertical(); } - private PreparedNode prepareForRegionWidth(PrepareContext prepareContext, + PreparedNode prepareForRegionWidth(PrepareContext prepareContext, DocumentNode node, double regionWidth) { return prepareContext.prepare(node, BoxConstraints.natural(childAvailableWidth(regionWidth, node))); @@ -1076,11 +1099,25 @@ private double leadingUnitHeight(DocumentNode node, double regionWidth, PrepareC List children = definition.children(node); // A horizontal row or layer stack is atomic (never splits) and an empty // vertical box has no first line — the whole box is the leading unit. - if (layoutSpec.axis() != CompositeLayoutSpec.Axis.VERTICAL || children.isEmpty()) { + // A column flow is neither: it spans pages by construction, so its + // measured height is not what a preceding keep-with-next run has to + // fit beside. Its leading unit is its first column's, exactly as a + // vertical box's is its first child's — otherwise a heading above a + // multi-page flow hoists itself to the next page and wastes this one. + boolean columnFlow = layoutSpec.axis() == CompositeLayoutSpec.Axis.COLUMN_FLOW; + if ((layoutSpec.axis() != CompositeLayoutSpec.Axis.VERTICAL && !columnFlow) + || children.isEmpty()) { return prepared.measureResult().height() + margin.vertical(); } double availableWidth = childAvailableWidth(regionWidth, node); double innerRegionWidth = Math.max(0.0, availableWidth - padding.horizontal()); + if (columnFlow) { + // The first column occupies its slot, not the whole flow: asking a + // paragraph how tall its first line is at four times its real width + // would answer for a line it never gets. + innerRegionWidth = RowSlots.distributeRowSlotWidths( + children, layoutSpec.weights(), layoutSpec.spacing(), innerRegionWidth)[0]; + } return topReservation + leadingUnitHeight(children.get(0), innerRegionWidth, prepareContext, pageInnerHeight); } diff --git a/core/src/main/java/com/demcha/compose/document/layout/NodeDefinitionSupport.java b/core/src/main/java/com/demcha/compose/document/layout/NodeDefinitionSupport.java index c6a6281df..3da3fd6b6 100644 --- a/core/src/main/java/com/demcha/compose/document/layout/NodeDefinitionSupport.java +++ b/core/src/main/java/com/demcha/compose/document/layout/NodeDefinitionSupport.java @@ -441,6 +441,44 @@ public static MeasureResult measureRow(RowNode node, return new MeasureResult(constraints.availableWidth(), padding.vertical() + maxChildHeight); } + /** + * Measures a multi-column flow: each column at its resolved slot width, + * the flow as tall as its tallest column. + * + *

That height is what the flow would occupy if a page were tall enough + * to hold it, and it routinely is not — the node exists to span pages. + * Nothing admits the flow onto a page on the strength of this number; the + * columns admit themselves child by child as they flow, exactly as a + * section does.

+ * + * @param node column flow node + * @param padding engine padding + * @param ctx prepare context + * @param constraints parent constraints + * @return measured outer flow size + */ + public static MeasureResult measureColumnFlow(ColumnFlowNode node, + Padding padding, + PrepareContext ctx, + BoxConstraints constraints) { + double availableWidth = Math.max(0.0, constraints.availableWidth() - padding.horizontal()); + List children = node.children(); + if (children.isEmpty()) { + return new MeasureResult(constraints.availableWidth(), padding.vertical()); + } + double[] slotWidths = RowSlots.distributeRowSlotWidths( + children, node.weights(), node.gap(), availableWidth); + double tallest = 0.0; + for (int index = 0; index < children.size(); index++) { + DocumentNode child = children.get(index); + double childInner = Math.max(0.0, slotWidths[index] - child.margin().horizontal()); + PreparedNode prepared = ctx.prepare(child, BoxConstraints.natural(childInner)); + tallest = Math.max(tallest, + prepared.measureResult().height() + child.margin().vertical()); + } + return new MeasureResult(constraints.availableWidth(), padding.vertical() + tallest); + } + /** * Measures a stack by preparing each layer inside the padding-adjusted * available width and taking the largest child outer box. diff --git a/core/src/main/java/com/demcha/compose/document/layout/PageGeometry.java b/core/src/main/java/com/demcha/compose/document/layout/PageGeometry.java index 9eb571063..c6045336a 100644 --- a/core/src/main/java/com/demcha/compose/document/layout/PageGeometry.java +++ b/core/src/main/java/com/demcha/compose/document/layout/PageGeometry.java @@ -22,6 +22,8 @@ */ public final class PageGeometry { + private static final double EPS = 1e-6; + private final LayoutCanvas canvas; private final List overrides; @@ -57,6 +59,30 @@ public Margin marginForPage(int pageIndex) { return resolved; } + /** + * Whether any override changes the horizontal geometry — the left margin or the + * content width — against the canvas. + * + *

Per-page margins are resolved through a fixed point: a block's start page + * decides which page's width it is measured against, and its measured height + * decides where the next block starts. That loop is only load-bearing when the + * width can actually differ between pages. A document whose overrides move only + * the top or bottom margin has one width throughout, so its layout is settled in + * a single pass and the resolver skips the loop.

+ * + * @return {@code true} when some override differs horizontally from the canvas + */ + public boolean hasHorizontalOverrides() { + for (PageMarginOverride override : overrides) { + Margin margin = override.margin(); + if (Math.abs(margin.left() - canvas.margin().left()) > EPS + || Math.abs(margin.right() - canvas.margin().right()) > EPS) { + return true; + } + } + return false; + } + /** * The content width on the given page (page width minus the page's horizontal margin). * diff --git a/core/src/main/java/com/demcha/compose/document/layout/definitions/ColumnFlowDefinition.java b/core/src/main/java/com/demcha/compose/document/layout/definitions/ColumnFlowDefinition.java new file mode 100644 index 000000000..d346c703f --- /dev/null +++ b/core/src/main/java/com/demcha/compose/document/layout/definitions/ColumnFlowDefinition.java @@ -0,0 +1,73 @@ +package com.demcha.compose.document.layout.definitions; + +import com.demcha.compose.document.layout.*; +import com.demcha.compose.document.node.ColumnFlowNode; +import com.demcha.compose.document.node.DocumentNode; + +import java.util.List; + +import static com.demcha.compose.document.layout.NodeDefinitionSupport.*; + +/** + * Layout definition for {@link ColumnFlowNode}: columns measured in weighted + * slots, each flowing down its own column across pages. + * + * @author Artem Demchyshyn + */ +public final class ColumnFlowDefinition implements NodeDefinition { + + /** + * Creates the column-flow layout definition. + */ + public ColumnFlowDefinition() { + } + + @Override + public Class nodeType() { + return ColumnFlowNode.class; + } + + @Override + public PreparedNode prepare(ColumnFlowNode node, PrepareContext ctx, + BoxConstraints constraints) { + return PreparedNode.composite( + node, + measureColumnFlow(node, toPadding(node.padding()), ctx, constraints), + new CompositeLayoutSpec(node.gap(), CompositeLayoutSpec.Axis.COLUMN_FLOW, + node.weights())); + } + + /** + * {@inheritDoc} + * + *

{@code ATOMIC} like every other composite. The compiler dispatches a + * composite on its axis before it ever reads this policy + * ({@code LayoutCompiler.compileNode}), so the value is inert here exactly + * as it is for {@code SectionNode} — which also spans pages. Splitting is + * a leaf contract; a composite spans pages by placing its children one at + * a time, which is what this node does per column.

+ */ + @Override + public PaginationPolicy paginationPolicy(ColumnFlowNode node) { + return PaginationPolicy.ATOMIC; + } + + @Override + public List children(ColumnFlowNode node) { + return node.children(); + } + + /** + * No decoration of its own. A column that wants a panel is a section with + * a fill, which the engine already repeats on every page that section + * spans; chrome that must reach the page edge belongs in a page + * background. Keeping the flow itself undecorated is what avoids the + * question of what a rounded corner means halfway down a document. + */ + @Override + public List emitFragments(PreparedNode prepared, + FragmentContext ctx, + FragmentPlacement placement) { + return List.of(); + } +} diff --git a/core/src/main/java/com/demcha/compose/document/node/ColumnFlowNode.java b/core/src/main/java/com/demcha/compose/document/node/ColumnFlowNode.java new file mode 100644 index 000000000..91f876a0e --- /dev/null +++ b/core/src/main/java/com/demcha/compose/document/node/ColumnFlowNode.java @@ -0,0 +1,126 @@ +package com.demcha.compose.document.node; + +import com.demcha.compose.document.style.DocumentInsets; + +import java.util.ArrayList; +import java.util.List; + +/** + * Columns placed side by side, each flowing down its own column and + * continuing on the next page. + * + *

A {@link RowNode} puts children beside each other in one band and is + * atomic: the whole band must fit on the page it starts on, and content that + * does not fit has nowhere to go. That is right for a row of cells and wrong + * for a two-column document body, which is why layouts built that way cap + * their content at a page and truncate the rest.

+ * + *

This is the other shape. Each child is a column, and each column is an + * ordinary vertical flow: it breaks where it runs out of page and resumes at + * the top of the next one, independently of its neighbours. The node ends on + * the last page any column reached, so whatever follows continues below the + * longest column.

+ * + * 
+ *   page 1                    page 2
+ *   ┌────────┬─────────┐      ┌────────┬─────────┐
+ *   │ side   │ main    │      │ side   │ main    │
+ *   │ …      │ …       │  →   │ …cont. │ …cont.  │
+ *   └────────┴─────────┘      └────────┴─────────┘
+ *
+ * + *

Widths are resolved once, from {@code weights} (or evenly when none are + * given), and every page uses the same ones — a column that changed width + * halfway down a document would not read as one column.

+ * + *

The node carries no fill or border of its own: a column that wants a + * panel is a section with a fill, and the engine already repeats a section's + * fill on each page it spans. Chrome that must reach the page edge belongs in + * a page background, which paints on every page by definition.

+ * + * @param name diagnostic name for layout paths and snapshots + * @param children one node per column, left to right + * @param weights relative column widths; empty distributes evenly + * @param gap horizontal gap between columns + * @param padding inner padding applied to the whole flow + * @param margin outer margin applied to the whole flow + * @since 2.3.0 + */ +public record ColumnFlowNode( + String name, + List children, + List weights, + double gap, + DocumentInsets padding, + DocumentInsets margin +) implements DocumentNode { + + /** + * Creates a normalized multi-column flow container. + */ + public ColumnFlowNode { + name = name == null ? "" : name; + children = children == null ? List.of() : List.copyOf(children); + for (DocumentNode column : children) { + // A column is a vertical container because that is what paginates. + // Checked here rather than only in the builder so every route in — + // the record, the factory, an import layer — gets the same answer. + if (!(column instanceof SectionNode) && !(column instanceof ContainerNode)) { + throw new IllegalArgumentException( + "A column flow's children are columns, and a column is a vertical " + + "container (section or container) because that is what " + + "paginates. Received: " + column.nodeKind() + + ". Wrap it in a column instead."); + } + } + weights = weights == null ? List.of() : List.copyOf(weights); + if (!weights.isEmpty() && weights.size() != children.size()) { + throw new IllegalArgumentException( + "Column flow weights size (" + weights.size() + ") must match children size (" + + children.size() + "). Pass exactly " + children.size() + + " weight(s) or leave weights empty for an even split."); + } + for (Double weight : weights) { + if (weight == null || Double.isNaN(weight) || Double.isInfinite(weight) || weight <= 0.0) { + throw new IllegalArgumentException( + "Column flow weights must be positive finite numbers: " + weights); + } + } + if (Double.isNaN(gap) || Double.isInfinite(gap) || gap < 0.0) { + throw new IllegalArgumentException("gap must be finite and non-negative: " + gap); + } + padding = padding == null ? DocumentInsets.zero() : padding; + margin = margin == null ? DocumentInsets.zero() : margin; + } + + /** + * {@inheritDoc} + */ + @Override + public String nodeKind() { + return "columnFlow"; + } + + /** + * The columns, left to right. + * + * @return one node per column + */ + public List columns() { + return children; + } + + /** + * A flow whose columns share the width evenly. + * + * @param name diagnostic name + * @param gap horizontal gap between columns + * @param columns one node per column + * @return a column flow with even widths + */ + public static ColumnFlowNode of(String name, double gap, DocumentNode... columns) { + List children = columns == null ? List.of() : new ArrayList<>(List.of(columns)); + return new ColumnFlowNode(name, children, List.of(), gap, + DocumentInsets.zero(), DocumentInsets.zero()); + } +} diff --git a/core/src/test/java/com/demcha/compose/document/layout/DocumentLayoutResolverTest.java b/core/src/test/java/com/demcha/compose/document/layout/DocumentLayoutResolverTest.java index 85d5deca3..47dcd6cd8 100644 --- a/core/src/test/java/com/demcha/compose/document/layout/DocumentLayoutResolverTest.java +++ b/core/src/test/java/com/demcha/compose/document/layout/DocumentLayoutResolverTest.java @@ -100,7 +100,8 @@ void pageReferenceRecompilesUntilNumbersStabilize() { void perPageMarginRecompilesUntilStartPagesStabilize() { LayoutGraph first = graphWith(placed("body", 0)); LayoutGraph settled = graphWith(placed("body", 0)); - when(context.pageGeometry()).thenReturn(mock(PageGeometry.class)); + PageGeometry geometry = widthChangingGeometry(); + when(context.pageGeometry()).thenReturn(geometry); when(context.hasPageReference()).thenReturn(false); when(compiler.compile(any(), any(), any())).thenReturn(first, settled); @@ -118,7 +119,8 @@ void coupledResolveWaitsForBothPageNumbersAndStartPages() { LayoutGraph pass0 = graphWith(placed("body", 0)); LayoutGraph pass1 = graphWith(placed("body", 1)); LayoutGraph pass2 = graphWith(placed("body", 1)); - when(context.pageGeometry()).thenReturn(mock(PageGeometry.class)); + PageGeometry geometry = widthChangingGeometry(); + when(context.pageGeometry()).thenReturn(geometry); when(context.hasPageReference()).thenReturn(true); when(compiler.compile(any(), any(), any())).thenReturn(pass0, pass1, pass2); // Page numbers are stable from the first read; only the start-pages keep @@ -131,6 +133,25 @@ void coupledResolveWaitsForBothPageNumbersAndStartPages() { verify(compiler, times(3)).compile(any(), any(), any()); } + @Test + void marginsThatOnlyMoveVerticallySettleInOnePass() { + // A block's assigned start page feeds nothing but the page's content width + // and left edge, so overrides that leave the width alone — a continuation + // safe area, say — cannot change the second pass's answer. Recompiling to + // reach the graph the first pass already produced is pure cost. + LayoutGraph only = graphWith(placed("body", 0)); + PageGeometry verticalOnly = mock(PageGeometry.class); + when(verticalOnly.hasHorizontalOverrides()).thenReturn(false); + when(context.pageGeometry()).thenReturn(verticalOnly); + when(context.hasPageReference()).thenReturn(false); + when(compiler.compile(any(), any(), any())).thenReturn(only); + + LayoutGraph result = new DocumentLayoutResolver(context).resolve(); + + assertThat(result).isSameAs(only); + verify(compiler, times(1)).compile(any(), any(), any()); + } + @Test void nonConvergingDocumentIsCappedAndReturnsLastLayout() { when(context.pageGeometry()).thenReturn(null); @@ -175,4 +196,11 @@ void nonConvergingDocumentThrowsWhenFailOnUnconvergedPropertyIsSet() { } } } + + /** Per-page margins that change a page's width — what drives the fixed point. */ + private static PageGeometry widthChangingGeometry() { + PageGeometry geometry = mock(PageGeometry.class); + when(geometry.hasHorizontalOverrides()).thenReturn(true); + return geometry; + } } diff --git a/coverage/pom.xml b/coverage/pom.xml index c8ffe968f..7386afe42 100644 --- a/coverage/pom.xml +++ b/coverage/pom.xml @@ -29,7 +29,7 @@ io.github.demchaav graph-compose-build - 2.2.1-SNAPSHOT + 2.3.0-SNAPSHOT ../pom.xml diff --git a/docs/recipes.md b/docs/recipes.md index 9c4b868c2..38e5d1c1b 100644 --- a/docs/recipes.md +++ b/docs/recipes.md @@ -16,6 +16,7 @@ authoring API; public application code should not import | [Shape-as-container](recipes/shape-as-container.md) | `addCircle` / `addEllipse` / `addContainer` with `ClipPolicy` (clipped layered children) | | [Transforms and z-index](recipes/transforms.md) | `rotate` / `scale` mixin, per-layer `zIndex` for overlays | | [Page backgrounds](recipes/page-backgrounds.md) | `pageBackground` / `pageBackgrounds`, `PageBackgroundFill` columns, bands, point-based fills, layering | +| [Multi-column flow](recipes/multi-column-flow.md) | `addColumnFlow(...)` — columns side by side, each continuing on the next page (a row is one atomic band) | | [Layered page design](recipes/layered-page-design.md) | Page background vs. row vs. layer stack vs. canvas — choosing the layer | | [Absolute placement](recipes/absolute-placement.md) | `addCanvas` + `position(x, y)` for pixel-precise certificates and badges | | [Tables](recipes/tables.md) | Row span, zebra rows, totals row, repeated header on page break | diff --git a/docs/recipes/multi-column-flow.md b/docs/recipes/multi-column-flow.md new file mode 100644 index 000000000..663f5a9ac --- /dev/null +++ b/docs/recipes/multi-column-flow.md @@ -0,0 +1,180 @@ +# Multi-column flow — columns that continue on the next page + +A **row** places its children side by side in one band, and the band is +atomic: it must fit on the page it starts on. That is right for a row of +cells, and wrong for a document body. A two-column layout built from a row +can hold exactly one page of content, and the moment it holds more the +compiler throws `AtomicNodeTooLargeException` — there is nowhere for the +overflow to go. + +A **column flow** places the same columns and lets each one break where it +runs out of page: + +``` + page 1 page 2 + ┌────────┬─────────┐ ┌────────┬─────────┐ + │ side │ main │ │ side │ main │ + │ … │ … │ → │ …cont. │ …cont. │ + └────────┴─────────┘ └────────┴─────────┘ +``` + +```java +flow.addColumnFlow("Body", body -> body + .gap(18) + .weights(0.72, 1.28) + .addColumn("Sidebar", side -> side + .spacing(6) + .addParagraph(p -> p.text("Skills, education, languages…"))) + .addColumn("Main", main -> main + .spacing(8) + .addParagraph(p -> p.text("Profile, experience, projects…")))); +``` + +## Which one do I want? + +| | `addRow` | `addColumnFlow` | +|---|---|---| +| Shape | one band, children side by side | columns side by side | +| Pagination | atomic — the whole band moves, or throws | each column breaks and continues | +| Use for | a header bar, a label/value pair, a card strip | a document body, a sidebar layout | +| Children | paragraphs, images, sections… | columns only (a section or container) | + +If the content is bounded and belongs together on one page, a row is the +simpler node and stays the right answer. + +## How it paginates + +Each column is an ordinary vertical flow. That is the whole mechanism: a +section already spans pages, because the compiler places its children one at +a time and any child may start a new page. A column flow gives each column +its own page cursor, starting where the flow starts, and rejoins them at the +end — so everything inside a column (paragraphs, tables, nested sections) +breaks exactly as it does anywhere else. + +The flow ends on the last page **any** column reached, and whatever follows +continues below the longest column. A column that finished two pages earlier +does not pull the next block up. + +## Columns are the children + +A column is a vertical container — a section or a container — because that +is what paginates. Passing anything else is rejected at build time rather +than laid out oddly: + +```java +body.addColumn(someParagraph); // IllegalArgumentException — wrap it in a column +``` + +## Decoration and chrome + +The flow itself has no fill or border. A column that wants a panel is a +section with a fill, and the engine already repeats a section's fill on +every page that section spans: + +```java +body.addColumn("Sidebar", side -> side + .fillColor(DocumentColor.rgb(244, 246, 248)) + .padding(DocumentInsets.of(12))); +``` + +Chrome that must reach the page edge — a full-height sidebar band, a rule +down the gutter — belongs in a [page background](page-backgrounds.md), which +paints on every page by definition and does not care where the content +broke. + +## Safe areas on continuation pages + +A column's padding is an edge of the **column**, not of each page. It is +reserved once, at the top of the page the column opens on and the bottom of +the page it closes on. Every page in between — and the top of every page the +column continues onto — gets nothing from it. + +The page margin is the inset that applies once per page, so in an ordinary +document this never comes up: the margin is already holding content away from +the paper edge on every page, and the padding is decoration on top of it. It +shows up in a **full-bleed** layout. Setting the margin to zero so a page +background can reach the paper edge gives up the safe area on all four sides, +when only the two horizontal ones had to go — and the first line of page 2 +lands inside the band most printers cannot reach: + +``` + page 1 page 2 + ┌────────┬─────────┐ ┌────────┬─────────┐ + │ │ │ │ side… │ main… │ ← first line on the trim + │ side │ main │ │ …cont. │ …cont. │ + └────────┴─────────┘ └────────┴─────────┘ + ↑ the column padding held this page down, and only this page +``` + +Restore the top of the margin on the continuation pages only — a page-margin +rule is the one inset the engine applies per page: + + +```java +try (DocumentSession session = GraphCompose.document() + .pageSize(DocumentPageSize.A4) + .margin(DocumentInsets.zero()) // full bleed on all four sides… + .create()) { + // …but half an inch of safe area at the top of page 2 onward + session.pageMargins(List.of( + PageMarginRule.from(2, new DocumentInsets(36, 0, 0, 0)))); +} +``` + +Keep the other three edges of the margin you chose, so the layout stays +full-bleed horizontally and the page backgrounds — which are ratios of the +*page*, not of the content box — keep bleeding on every page. Page 1 is +deliberately not covered: a body's first page owns its own top edge, and a rule +that covered it would push that whole page down. + +Which page and which edge is a design decision rather than an engine one, so +the ready-made version lives in `templates`: +`ContinuationSafeArea.applyTo(session, 2, ContinuationSafeArea.PRINTER_SAFE_TOP)` +derives the rule from `session.margin()`, names the first page to inset (`2` +for a body that opens the document, `3` when a cover comes first), and does +nothing at all when the margin already provides the safe area — so a template +can call it unconditionally without turning an ordinary document into a +per-page one, or deleting rules its caller set. `pageMargins(...)` replaces +rather than merges, so a template that wants rules of its own writes them +together rather than calling both. + +It guards the **top** edge only. Content still flows to the bottom of every +page it fills, which in a full-bleed layout is the trimmed bottom edge. A +bottom safe area is a bottom inset on `margin(...)` itself rather than a rule +like this one, because unlike the top it has to apply to page 1 as well — and +giving page 1 less height changes where it breaks. + +A rule that moves only the top or bottom margin costs nothing extra to lay out: +per-page margins are resolved through a fixed point only when a page's *width* +can differ, and a vertical-only rule leaves one width for the whole document. + +Keeping the horizontal edges is not only about the bleed. Column widths are +resolved once, at the flow's entry, so a rule that narrowed the pages the flow +continues onto would inset the *page* without narrowing the columns drawn on +it — see [Widths](#widths). + +## Widths + +Widths come from `weights` (or split evenly when you pass none) and are +resolved **once**, at the flow's entry. Every page uses the same ones: a +column that changed width halfway down would not read as one column, and the +layout's fixed point requires the geometry to be a pure function of where +the flow started. In a document with per-page margins that means the flow +keeps its entry page's widths on the pages it continues onto, as any nested +block does. + +## What it does not do + +- **Balance columns.** Each column flows independently; the engine does not + even out their lengths. +- **Keep content together across columns.** `keepTogether` and + `keepWithNext` work inside a column, which is where they mean something. + On the flow itself `keepTogether` is ignored — a node that spans pages by + construction cannot relocate whole. A `keepWithNext` heading placed + *above* the flow works normally: it is kept with the flow's first line, + not with the whole flow. +- **Break every column at once.** A page break inside a column breaks that + column; its neighbours keep flowing. +- **Live inside a row slot or a stack layer.** A column flow needs to + advance pages, and both of those layers are pinned to one page. Putting + one there is rejected rather than laid out over the top of what follows. diff --git a/docs/roadmaps/post-2.0-engineering.md b/docs/roadmaps/post-2.0-engineering.md index e04ba0994..6e5da7a1c 100644 --- a/docs/roadmaps/post-2.0-engineering.md +++ b/docs/roadmaps/post-2.0-engineering.md @@ -111,7 +111,7 @@ exercise it. Report-only; thresholds can follow after a baseline read. `japicmp` ran report-only through the 2.0 major — the major intentionally broke binary compatibility. With the 2.0.0 GA artifacts on Central the gate switched to per-module baselines pinned at the major's floor (2.0.0) in break-on-incompatible -mode: `graph-compose-core` first, `graph-compose-templates` since 2.2.1 — each +mode: `graph-compose-core` first, `graph-compose-templates` since 2.3.0 — each module's `japicmp` profile lives in its own pom and runs in the PR-time `Binary Compatibility` job, in `cut-release.ps1` step 5b, and in the publish workflow. The remaining published modules (`render-pdf` / `render-docx` / diff --git a/docs/templates/v2-layered/using-templates.md b/docs/templates/v2-layered/using-templates.md index bcfaf31fd..225892a70 100644 --- a/docs/templates/v2-layered/using-templates.md +++ b/docs/templates/v2-layered/using-templates.md @@ -19,11 +19,12 @@ it sets up the conceptual model in 5 minutes. 1. [The pieces you assemble](#the-pieces-you-assemble) 2. [Identity — name, contact, optional links](#identity) 3. [Section types](#section-types) -4. [Slots — main vs sidebar](#slots) -5. [Picking a preset](#picking-a-preset) -6. [Customising a theme](#customising-a-theme) -7. [Rendering — pageSize, margins, output](#rendering) -8. [Common patterns](#common-patterns) +4. [Building sections at runtime — `ModuleSection`](#runtime-modules) +5. [Slots — main vs sidebar](#slots) +6. [Picking a preset](#picking-a-preset) +7. [Customising a theme](#customising-a-theme) +8. [Rendering — pageSize, margins, output](#rendering) +9. [Common patterns](#common-patterns) --- @@ -161,6 +162,119 @@ paragraph beneath. --- + +## Building sections at runtime — `ModuleSection` + +The four types above are the right choice when you write a CV in Java: +you pick the record and the compiler checks it. They are the wrong one +when the CV is assembled from data — a form, a JSON payload, an LLM — +because the shape is not known until it arrives, and a user who picks +"dated entries" from a menu cannot instantiate a different record per +choice. + +`ModuleSection` moves that choice into a value. One item record carries +every optional field, and a `CvKind` decides which of them are read: + +```java +ModuleSection.builder("Volunteering", SectionRole.OTHER, CvKind.ENTRIES_DATED) + .item(CvItem.of("Mentor, Rails Girls") + .at("Rails Girls Berlin") // subtitle + .in("Berlin, DE") // location + .period("2019 - 2021") // read by dated kinds only + .bullets("Ran three weekend workshops")) + .build(); +``` + +| `CvKind` | Shape | Reads | +|---|---|---| +| `PARAGRAPH` | prose under the section heading | `body` | +| `BULLETS` | a bullet per item, description inline | `title`, `body` (not `link`) | +| `BULLETS_STACKED` | a bullet per item, description underneath | `title`, `link`, `body` | +| `INLINE_LIST` | `Languages: Java 21, Kotlin` | `title`, `body` (not `link`) | +| `ENTRIES` | timeline, no date column | everything but `period` | +| `ENTRIES_DATED` | timeline with dates | everything | + +Only `title` is required on an item. Whatever a kind does not read is +ignored, so the same item renders with or without its dates depending +on the kind alone — which is what lets a "Volunteering" module be +shaped exactly like Education without a new type. + +`SectionRole` says what a section *means*, separately from how it +draws — and it is the first thing a preset routes on. A preset with a designed +layout places sections into fixed slots, and it used to choose what +went where by matching the heading against a list of English words: +a CV headed `Ausbildung` or `Навыки` matched nothing, so the section +was dropped and the slot that wanted it rendered empty. Give the module +a role and it lands in the right slot whatever language the CV is +written in, and whatever kind you chose to draw it with — for the roles +that preset has a slot for. `SectionRole.OTHER` names no slot, so a +module carrying it routes by heading like any other section. + +A heading that matches a keyword still routes a section that has no +role — every hand-written section, and any module you left as +`SectionRole.OTHER`. What a heading may not do is overrule a role: a +module declared `EXPERIENCE` and headed "Projects" goes where you put +it, and the projects slot does not also claim it. + +Modules and the four fixed types mix freely in one document, and both +render through the same components — a module drawn as `ENTRIES_DATED` +lays out exactly like the `EntriesSection` carrying the same content. + +### Which preset can you hand a runtime module to? + +Not every preset. Several compose a fixed set of modules and find each by +matching headings, so a section they do not recognise never reaches a +renderer; the CV still comes out, minus a section, looking finished. The +ones that render whatever they are handed say so in the type system: + +```java +List safe = CvTemplates.modular(); // offer these + +CvTemplates.byId("modern-professional") // or look one up + .orElseThrow() + .compose(session, doc); +``` + +`CvTemplates` also answers `all()`, `ids()`, and `recommendedMargin(id)` — +the margin a preset was designed at, which you need while building the +session, before you have a template. + +Declaring `ModularCvTemplate` is not free: a fidelity suite renders a +document carrying every kind, an invented heading, a heading in a script no +keyword list contains, and a heading that *does* match one, through each +template that declares it, and asserts every item reached the page under the +author's own words. + +The promise covers `Slot.MAIN`, which is where sections go unless you say +otherwise. Every shipped preset composes a single main column, so a section +placed in `Slot.SIDEBAR` is dropped — by these templates as by every other. + +The presets outside that list are not broken, they are *designed*: each +composes a fixed set of slots, so it renders the roles it has a place for +and drops a section it has no slot for. Give such a preset a CV whose +sections map onto roles and it renders them all; give it an extra +"Volunteering" module and that one is lost. For most of them the reason is +structural — the whole body is one atomic block that cannot break across +pages, so there is nowhere to put an extra section, and lifting that needs +pagination work rather than routing. + +`SidebarPortrait` and `MonogramSidebar` are past that point: their bodies are +column flows, so both columns continue on the next page and each renders as +much of a career as it is handed. Neither caps its blocks any more — +`SidebarPortrait` used to draw two jobs, two degrees, five skills, three +languages and two projects, `MonogramSidebar` two jobs, two degrees, seven +skills, three projects and three additional rows, and both silently dropped +the rest. What they still do not have is a place for a section they do not +recognise, which is why neither is on the modular list yet. + +A template also says *how* it draws through `CvRenderKit`. The shared +lowering turns a module into paragraphs, rows, and entries; the kit draws +them, so a preset with its own entry style renders your runtime module in +that style rather than the canonical one. Presets whose bodies already use +the shared components return `CvRenderKit.defaults()`. + +--- + ## Slots — main vs sidebar diff --git a/examples/pom.xml b/examples/pom.xml index 18f7234e6..ec908264c 100644 --- a/examples/pom.xml +++ b/examples/pom.xml @@ -7,7 +7,7 @@ io.github.demchaav graph-compose-build - 2.2.1-SNAPSHOT + 2.3.0-SNAPSHOT ../pom.xml diff --git a/pom.xml b/pom.xml index 72b797b8b..09849aeff 100644 --- a/pom.xml +++ b/pom.xml @@ -6,7 +6,7 @@ io.github.demchaav graph-compose-build - 2.2.1-SNAPSHOT + 2.3.0-SNAPSHOT pom GraphCompose Build Aggregator diff --git a/qa/pom.xml b/qa/pom.xml index 59fd176ce..9d7a002fe 100644 --- a/qa/pom.xml +++ b/qa/pom.xml @@ -22,7 +22,7 @@ io.github.demchaav graph-compose-build - 2.2.1-SNAPSHOT + 2.3.0-SNAPSHOT ../pom.xml diff --git a/qa/src/test/java/com/demcha/compose/document/api/PageMarginTest.java b/qa/src/test/java/com/demcha/compose/document/api/PageMarginTest.java index b6b645b64..80d1b1186 100644 --- a/qa/src/test/java/com/demcha/compose/document/api/PageMarginTest.java +++ b/qa/src/test/java/com/demcha/compose/document/api/PageMarginTest.java @@ -3,6 +3,7 @@ import com.demcha.compose.GraphCompose; import com.demcha.compose.document.layout.LayoutGraph; import com.demcha.compose.document.layout.PlacedNode; +import com.demcha.compose.document.layout.payloads.ParagraphFragmentPayload; import com.demcha.compose.document.node.TextAlign; import com.demcha.compose.document.style.DocumentInsets; import com.demcha.compose.document.style.DocumentTextStyle; @@ -309,4 +310,114 @@ void eachMultiSectionSectionResolvesItsOwnSectionLocalPageMargins() throws Excep } assertThat(out).exists(); } + + // -- continuation safe area ------------------------------------------ + + @Test + void aFullBleedDocumentResumesAtTheTrimmedEdgeWithoutASafeArea() throws Exception { + // The defect the safe area exists for, stated as a measurement. A page + // margin is the only inset applied once per page; the section's padding is + // an edge of the section, so it holds page 1 off the top and page 2 gets + // nothing. Without this case the safe-area test below would still pass if + // the padding had been doing the work all along. + try (DocumentSession session = fullBleedSession()) { + fillPastOnePage(session); + + assertThat(firstLineTopGap(session, 1)) + .as("page 2 opens on whatever spacing preceded the break, nowhere near " + + "the section's 30pt padding — that padding is an edge of the " + + "section and was already spent on page 1") + .isLessThan(12.0); + assertThat(firstLineTopGap(session, 0)) + .as("while page 1 sits on the section's own top padding") + .isCloseTo(30.0, within(0.5)); + } + } + + @Test + void aTopOnlyRuleInsetsEveryPageItCovers() { + // The mechanism the templates-side safe area is built on, pinned at the + // engine level: raising only the top margin from page 2 leaves page 1 alone. + try (DocumentSession session = fullBleedSession()) { + session.pageMargins(List.of( + PageMarginRule.from(2, new DocumentInsets(36, 0, 0, 0)))); + fillPastOnePage(session); + + assertThat(session.layoutGraph().totalPages()) + .as("the fixture has to actually continue for this to mean anything") + .isGreaterThan(1); + for (int page = 1; page < session.layoutGraph().totalPages(); page++) { + assertThat(firstLineTopGap(session, page)) + .as("page %d clears the safe area", page + 1) + .isGreaterThanOrEqualTo(36.0); + } + assertThat(firstLineTopGap(session, 0)) + .as("and page 1 keeps the top edge its own design gave it") + .isCloseTo(30.0, within(0.5)); + } + } + + @Test + void aVerticalOnlyRuleStillLaysOutLikeItsSinglePassSelf() { + // A top-only rule cannot change any page's width, so the resolver settles it + // in one pass. This pins that the shortcut did not change the answer: the + // same rule expressed with a horizontal difference — which does take the + // fixed point — puts the same first line in the same place vertically. + try (DocumentSession shortcut = fullBleedSession(); + DocumentSession fixedPoint = fullBleedSession()) { + shortcut.pageMargins(List.of( + PageMarginRule.from(2, new DocumentInsets(36, 0, 0, 0)))); + fixedPoint.pageMargins(List.of( + PageMarginRule.from(1, new DocumentInsets(0, 0, 0, 0)), + PageMarginRule.from(2, new DocumentInsets(36, 0, 0, 0)))); + fillPastOnePage(shortcut); + fillPastOnePage(fixedPoint); + + assertThat(shortcut.layoutGraph().totalPages()) + .isEqualTo(fixedPoint.layoutGraph().totalPages()); + assertThat(firstLineTopGap(shortcut, 1)) + .isCloseTo(firstLineTopGap(fixedPoint, 1), within(0.01)); + } + } + + private static DocumentSession fullBleedSession() { + return GraphCompose.document() + .pageSize(DocumentPageSize.A4) + .margin(DocumentInsets.zero()) + .create(); + } + + /** A padded section long enough to need a second page, as a column flow does. */ + private static void fillPastOnePage(DocumentSession session) { + session.dsl().pageFlow() + .name("Root") + .padding(DocumentInsets.zero()) + .addColumnFlow("Body", body -> body + .addColumn("Only", column -> { + column.padding(DocumentInsets.of(30)).spacing(6); + for (int index = 0; index < 60; index++) { + int current = index; + column.addParagraph(p -> p + .name("line-" + current) + .text("line " + current + " with enough words to occupy a line")); + } + })) + .build(); + } + + /** + * Distance from the trimmed top edge to the top of the highest line of text on + * a page. Measured on text fragments rather than nodes: a paragraph that broke + * across the page boundary still belongs to a node that started on the previous + * page, and it is exactly that line the reader sees at the top. + */ + private static double firstLineTopGap(DocumentSession session, int pageIndex) { + double pageHeight = session.canvas().height(); + return session.layoutGraph().fragments().stream() + .filter(fragment -> fragment.pageIndex() == pageIndex) + .filter(fragment -> fragment.payload() instanceof ParagraphFragmentPayload) + .mapToDouble(fragment -> pageHeight - (fragment.y() + fragment.height())) + .min() + .orElseThrow(() -> new AssertionError("no text on page " + (pageIndex + 1))); + } } diff --git a/qa/src/test/java/com/demcha/compose/document/layout/ColumnFlowPaginationTest.java b/qa/src/test/java/com/demcha/compose/document/layout/ColumnFlowPaginationTest.java new file mode 100644 index 000000000..30868dbd8 --- /dev/null +++ b/qa/src/test/java/com/demcha/compose/document/layout/ColumnFlowPaginationTest.java @@ -0,0 +1,384 @@ +package com.demcha.compose.document.layout; + +import com.demcha.compose.GraphCompose; +import com.demcha.compose.document.api.DocumentPageSize; +import com.demcha.compose.document.api.DocumentSession; +import com.demcha.compose.document.exceptions.AtomicNodeTooLargeException; +import com.demcha.compose.document.layout.payloads.ShapeFragmentPayload; +import com.demcha.compose.document.node.ColumnFlowNode; +import com.demcha.compose.document.node.SectionNode; +import com.demcha.compose.document.node.SpacerNode; +import com.demcha.compose.document.dsl.ColumnFlowBuilder; +import com.demcha.compose.document.dsl.SectionBuilder; +import com.demcha.compose.document.style.DocumentColor; +import com.demcha.compose.document.style.DocumentInsets; +import org.junit.jupiter.api.Test; + +import java.util.ArrayList; +import java.util.List; +import java.util.stream.IntStream; + +import static org.assertj.core.api.Assertions.assertThat; +import static org.assertj.core.api.Assertions.assertThatCode; +import static org.assertj.core.api.Assertions.assertThatThrownBy; + +/** + * A two-column body that outgrows its page. + * + *

A row is one band and is atomic: it must fit the page it starts on, and + * content that does not fit has nowhere to go — the compiler says so by + * throwing. That is correct for a row of cells and fatal for a document body, + * which is why layouts built from a row cap their content at a page and + * truncate the rest.

+ * + *

The first two cases are the same content twice: through a row, which + * throws, and through a column flow, which paginates. Everything after that + * pins the properties the flow has to hold while doing it.

+ */ +class ColumnFlowPaginationTest { + + @Test + void aRowCannotHoldMoreThanOnePage() { + assertThatThrownBy(() -> render(session -> session.pageFlow() + .name("Root") + .addRow("Body", row -> row + .gap(18) + .weights(1.0, 1.0) + .addSection("Side", side -> paragraphs(side, "side", 40)) + .addSection("Main", main -> paragraphs(main, "main", 40))) + .build())) + .as("the row band is atomic, so overflowing it is an error rather than a page break") + .isInstanceOf(AtomicNodeTooLargeException.class); + } + + @Test + void aColumnFlowWithTheSameContentPaginatesInstead() throws Exception { + try (DocumentSession session = newSession()) { + session.pageFlow() + .name("Root") + .addColumnFlow("Body", body -> body + .gap(18) + .weights(1.0, 1.0) + .addColumn("Side", side -> paragraphs(side, "side", 40)) + .addColumn("Main", main -> paragraphs(main, "main", 40))) + .build(); + + LayoutGraph graph = session.layoutGraph(); + assertThat(graph.totalPages()) + .as("the same content that overflowed a row now spans pages") + .isGreaterThan(1); + assertThat(paragraphPages(graph, "side")) + .as("the left column continues past the first page") + .contains(0, 1); + assertThat(paragraphPages(graph, "main")) + .as("the right column continues past the first page") + .contains(0, 1); + } + } + + @Test + void everyLineSurvivesTheBreak() throws Exception { + // The failures a paginator must not have: content that vanished, content + // that came back in the wrong order, and content that skipped a page. + try (DocumentSession session = newSession()) { + session.pageFlow() + .name("Root") + .addColumnFlow("Body", body -> body + .gap(18) + .addColumn("Side", side -> paragraphs(side, "side", 40)) + .addColumn("Main", main -> paragraphs(main, "main", 40))) + .build(); + + LayoutGraph graph = session.layoutGraph(); + for (String column : List.of("side", "main")) { + PlacedNode previous = null; + for (int index = 0; index < 40; index++) { + String text = column + "-" + index; + PlacedNode current = graph.nodes().stream() + .filter(placed -> placed.semanticName().equals(text)) + .findFirst() + .orElseThrow(() -> new AssertionError(text + " was dropped by the break")); + if (previous != null) { + assertThat(current.startPage()) + .as("%s must not move backwards or skip a page", text) + .isBetween(previous.startPage(), previous.startPage() + 1); + if (current.startPage() == previous.startPage()) { + assertThat(current.placementY()) + .as("%s must sit below its predecessor on the same page", text) + .isLessThan(previous.placementY()); + } + } + previous = current; + } + } + } + } + + @Test + void columnsAreIndependentSoAShortColumnDoesNotStretch() throws Exception { + try (DocumentSession session = newSession()) { + session.pageFlow() + .name("Root") + .addColumnFlow("Body", body -> body + .gap(18) + .addColumn("Short", side -> paragraphs(side, "short", 2)) + .addColumn("Long", main -> paragraphs(main, "long", 40))) + .build(); + + LayoutGraph graph = session.layoutGraph(); + assertThat(paragraphPages(graph, "short")) + .as("a column that fits stays on the first page") + .containsExactly(0); + assertThat(paragraphPages(graph, "long")) + .as("its neighbour keeps flowing") + .contains(0, 1); + } + } + + @Test + void whatFollowsTheFlowStartsBelowTheLongestColumn() throws Exception { + try (DocumentSession session = newSession()) { + session.pageFlow() + .name("Root") + .addColumnFlow("Body", body -> body + .gap(18) + .addColumn("Short", side -> paragraphs(side, "short", 2)) + .addColumn("Long", main -> paragraphs(main, "long", 40))) + .addParagraph(p -> p.name("after").text("after the flow")) + .build(); + + LayoutGraph graph = session.layoutGraph(); + PlacedNode after = node(graph, "after"); + PlacedNode lastLong = lastNodeNamed(graph, "long"); + + assertThat(after.startPage()) + .as("the flow ends where its longest column ended, not its shortest") + .isEqualTo(lastLong.startPage()); + assertThat(after.placementY()) + .as("and the next block sits below that column, not on top of it") + .isLessThan(lastLong.placementY()); + } + } + + @Test + void aFlowThatFitsOnOnePageLaysOutLikeARowWould() throws Exception { + // The new node must not cost anything for the ordinary case: content + // that fits produces one page and side-by-side columns. + try (DocumentSession session = newSession()) { + session.pageFlow() + .name("Root") + .addColumnFlow("Body", body -> body + .gap(18) + .weights(1.0, 1.0) + .addColumn("Side", side -> paragraphs(side, "side", 2)) + .addColumn("Main", main -> paragraphs(main, "main", 2))) + .build(); + + LayoutGraph graph = session.layoutGraph(); + assertThat(graph.totalPages()).isEqualTo(1); + PlacedNode side = node(graph, "side-0"); + PlacedNode main = node(graph, "main-0"); + assertThat(side.placementX()) + .as("columns sit side by side") + .isLessThan(main.placementX()); + assertThat(side.placementY()) + .as("and start at the same height") + .isCloseTo(main.placementY(), org.assertj.core.data.Offset.offset(0.01)); + } + } + + @Test + void anEmptyFlowIsHarmless() { + assertThatCode(() -> render(session -> session.pageFlow() + .name("Root") + .addColumnFlow("Body", body -> body.gap(12)) + .build())) + .doesNotThrowAnyException(); + } + + @Test + void aColumnMustBeAVerticalContainer() { + // A column is a vertical flow — that is what paginates. Anything else + // beside its siblings belongs inside a column. + assertThatThrownBy(() -> new ColumnFlowBuilderProbe().addNonColumn()) + .isInstanceOf(IllegalArgumentException.class) + .hasMessageContaining("vertical container"); + } + + @Test + void weightsMustMatchTheColumns() { + assertThatThrownBy(() -> new ColumnFlowNode("Body", + List.of(emptySection("a"), emptySection("b")), + List.of(1.0), 0.0, DocumentInsets.zero(), DocumentInsets.zero())) + .isInstanceOf(IllegalArgumentException.class) + .hasMessageContaining("must match children size"); + } + + @Test + void aColumnFlowIsRejectedInsideARowSlot() { + // A row slot is pinned to one page; a column flow advances pages. Placed + // here it would stack its columns down the slot and run past the band, + // overlapping whatever follows. + assertThatThrownBy(() -> render(session -> session.pageFlow() + .name("Root") + .addRow("Band", row -> row + .addSection("Left", left -> left + .addColumnFlow("Nested", body -> body + .addColumn("A", a -> paragraphs(a, "a", 2)) + .addColumn("B", b -> paragraphs(b, "b", 2)))) + .addSection("Right", right -> paragraphs(right, "right", 2))) + .build())) + .isInstanceOf(IllegalStateException.class) + .hasMessageContaining("cannot contain a column flow") + .hasMessageContaining("row slot"); + } + + @Test + void aColumnFlowIsRejectedInsideAStackLayer() { + assertThatThrownBy(() -> render(session -> session.pageFlow() + .name("Root") + .addLayerStack(stack -> stack.layer(new SectionBuilder() + .name("Layer") + .addColumnFlow("Nested", body -> body + .addColumn("A", a -> paragraphs(a, "a", 2)) + .addColumn("B", b -> paragraphs(b, "b", 2))) + .build())) + .build())) + .isInstanceOf(IllegalStateException.class) + .hasMessageContaining("cannot contain a column flow") + .hasMessageContaining("stack layer"); + } + + @Test + void aHeadingAboveTheFlowIsNotHoistedToTheNextPage() throws Exception { + // keepWithNext asks "does my run plus the first line of what follows fit + // here?". A flow answers with its own height unless the lookahead reads + // its first column -- and a heading above a body that is going to break + // anyway would then jump to the next page and strand the rest of this one. + try (DocumentSession session = newSession()) { + session.pageFlow() + .name("Root") + .spacing(4) + .addSection("Filler", filler -> paragraphs(filler, "filler", 38)) + .addSection("Heading", heading -> heading + .keepWithNext() + .addParagraph(p -> p.name("heading").text("Experience"))) + .addColumnFlow("Body", body -> body + .gap(18) + .addColumn("Side", side -> paragraphs(side, "side", 10)) + .addColumn("Main", main -> paragraphs(main, "main", 10))) + .build(); + + LayoutGraph graph = session.layoutGraph(); + assertThat(node(graph, "heading").startPage()) + .as("the heading stays on the page it was reached on") + .isEqualTo(lastNodeNamed(graph, "filler").startPage()); + assertThat(node(graph, "side-0").startPage()) + .as("and its body starts there too, using the rest of the page") + .isEqualTo(node(graph, "heading").startPage()); + } + } + + @Test + void aColumnPanelIsRepaintedOnEveryPageItSpans() throws Exception { + // The flow has no chrome of its own; a column that wants a panel is a + // section with a fill, and a section's fill already repeats per page. + // That is the whole decoration story, so it has to actually hold. + try (DocumentSession session = newSession()) { + session.pageFlow() + .name("Root") + .addColumnFlow("Body", body -> body + .gap(18) + .addColumn("Side", side -> { + side.fillColor(DocumentColor.rgb(240, 240, 240)); + paragraphs(side, "side", 40); + }) + .addColumn("Main", main -> paragraphs(main, "main", 40))) + .build(); + + LayoutGraph graph = session.layoutGraph(); + List panelPages = graph.fragments().stream() + .filter(fragment -> fragment.path().contains("Side")) + .filter(fragment -> fragment.payload() instanceof ShapeFragmentPayload) + .map(PlacedFragment::pageIndex) + .distinct() + .sorted() + .toList(); + + assertThat(graph.totalPages()).isGreaterThan(1); + assertThat(panelPages) + .as("the panel is painted on each page the column reached") + .containsExactlyElementsOf( + IntStream.range(0, graph.totalPages()).boxed().toList()); + } + } + + // -- helpers --------------------------------------------------------- + + /** Probe for the builder's column-type rejection. */ + private static final class ColumnFlowBuilderProbe { + void addNonColumn() { + new ColumnFlowBuilder().addColumn(new SpacerNode("spacer", 10, 10, + DocumentInsets.zero(), DocumentInsets.zero(), 0.0)); + } + } + + private static SectionNode emptySection(String name) { + return new SectionBuilder().name(name).build(); + } + + private static void paragraphs(SectionBuilder section, + String prefix, int count) { + section.spacing(4); + for (int index = 0; index < count; index++) { + int current = index; + section.addParagraph(p -> p + .name(prefix + "-" + current) + .text(prefix + " paragraph " + current + " with enough words to occupy a line")); + } + } + + private static DocumentSession newSession() { + return GraphCompose.document() + .pageSize(DocumentPageSize.A4) + .margin(36, 36, 36, 36) + .create(); + } + + private static void render(java.util.function.Consumer body) { + try (DocumentSession session = newSession()) { + body.accept(session); + session.layoutGraph(); + } + } + + private static List paragraphPages(LayoutGraph graph, String prefix) { + List pages = new ArrayList<>(); + for (PlacedNode node : graph.nodes()) { + if (node.semanticName().startsWith(prefix + "-") && !pages.contains(node.startPage())) { + pages.add(node.startPage()); + } + } + return pages; + } + + private static PlacedNode node(LayoutGraph graph, String semanticName) { + return graph.nodes().stream() + .filter(node -> node.semanticName().equals(semanticName)) + .findFirst() + .orElseThrow(() -> new AssertionError("no node named " + semanticName)); + } + + private static PlacedNode lastNodeNamed(LayoutGraph graph, String prefix) { + PlacedNode last = null; + for (PlacedNode node : graph.nodes()) { + if (node.semanticName().startsWith(prefix + "-")) { + last = node; + } + } + if (last == null) { + throw new AssertionError("no node starting with " + prefix); + } + return last; + } +} diff --git a/qa/src/test/java/com/demcha/compose/document/templates/core/page/ContinuationSafeAreaTest.java b/qa/src/test/java/com/demcha/compose/document/templates/core/page/ContinuationSafeAreaTest.java new file mode 100644 index 000000000..94e19c01c --- /dev/null +++ b/qa/src/test/java/com/demcha/compose/document/templates/core/page/ContinuationSafeAreaTest.java @@ -0,0 +1,173 @@ +package com.demcha.compose.document.templates.core.page; + +import com.demcha.compose.GraphCompose; +import com.demcha.compose.document.api.DocumentPageSize; +import com.demcha.compose.document.api.DocumentSession; +import com.demcha.compose.document.api.PageMarginRule; +import com.demcha.compose.document.layout.payloads.ParagraphFragmentPayload; +import com.demcha.compose.document.style.DocumentInsets; +import org.junit.jupiter.api.Test; + +import java.util.List; + +import static org.assertj.core.api.Assertions.assertThat; +import static org.assertj.core.api.Assertions.assertThatThrownBy; +import static org.assertj.core.api.Assertions.within; + +/** + * The safe area a full-bleed template reserves on the pages its body continues onto. + * + *

A template sets the page margin to zero so a page background can reach the + * paper edge, and gives up the safe area on all four sides to buy the two it needed. + * A column's own padding does not cover the difference: it is an edge of the column, + * spent on the page the column opens on.

+ */ +class ContinuationSafeAreaTest { + + @Test + void itInsetsTheContinuationPagesAndLeavesTheFirstAlone() { + try (DocumentSession session = fullBleed()) { + ContinuationSafeArea.applyTo(session, 2, 36); + fillPastOnePage(session); + + assertThat(session.layoutGraph().totalPages()).isGreaterThan(1); + assertThat(firstLineTopGap(session, 1)) + .as("page 2 clears the safe area") + .isGreaterThanOrEqualTo(36.0); + assertThat(firstLineTopGap(session, 0)) + .as("page 1 keeps the top edge its own design gave it") + .isCloseTo(30.0, within(0.5)); + } + } + + @Test + void itKeepsTheHorizontalEdgesItWasGiven() { + // The bug being prevented: reserving a top inset by rebuilding all four + // edges would silently un-bleed the sides, and the page backgrounds would + // no longer line up with the columns. + try (DocumentSession session = GraphCompose.document() + .pageSize(DocumentPageSize.A4) + .margin(new DocumentInsets(10, 20, 30, 40)) + .create()) { + ContinuationSafeArea.applyTo(session, 2, 36); + fillPastOnePage(session); + + assertThat(leftEdgeOfFirstLine(session, 1)) + .as("page 2 keeps the left margin the caller chose, plus the column padding") + .isCloseTo(leftEdgeOfFirstLine(session, 0), within(0.5)); + } + } + + @Test + void aMarginThatAlreadyClearsTheSafeAreaIsLeftAlone() { + // The empty case has to be a no-op, not an empty rule list: pageMargins() + // replaces, and an empty list clears. A template calling this + // unconditionally must not be able to delete rules the caller set. + try (DocumentSession session = GraphCompose.document() + .pageSize(DocumentPageSize.A4) + .margin(DocumentInsets.of(48)) + .create()) { + session.pageMargins(List.of(PageMarginRule.page(1, DocumentInsets.zero()))); + + ContinuationSafeArea.applyTo(session, 2, 36); + + fillPastOnePage(session); + assertThat(firstLineTopGap(session, 0)) + .as("the caller's own full-bleed first page survives the call") + .isCloseTo(30.0, within(0.5)); + } + } + + @Test + void aSafeAreaMustBeAUsableLengthOnAPageThatCanHaveOne() { + try (DocumentSession session = fullBleed()) { + assertThatThrownBy(() -> ContinuationSafeArea.applyTo(session, 1, 36)) + .as("page 1 is where a body starts; its own design owns its top edge") + .isInstanceOf(IllegalArgumentException.class) + .hasMessageContaining("firstContinuationPage"); + assertThatThrownBy(() -> ContinuationSafeArea.applyTo(session, 2, -1)) + .isInstanceOf(IllegalArgumentException.class) + .hasMessageContaining("topSafeArea"); + assertThatThrownBy(() -> ContinuationSafeArea.applyTo(session, 2, Double.NaN)) + .isInstanceOf(IllegalArgumentException.class); + assertThatThrownBy(() -> ContinuationSafeArea.applyTo(null, 2, 36)) + .isInstanceOf(NullPointerException.class); + } + } + + @Test + void aBodyThatStartsLaterInsetsFromThePageItSays() { + // A cover page and a body starting on page 2: the inset belongs from page 3, + // and page 2 — the body's own first page — must keep its design. + try (DocumentSession session = fullBleed()) { + ContinuationSafeArea.applyTo(session, 3, 36); + session.dsl().pageFlow() + .name("Root") + .padding(DocumentInsets.zero()) + .addParagraph(p -> p.name("cover").text("Cover")) + .addPageBreak(b -> b.name("break")) + .addColumnFlow("Body", body -> body.addColumn("Only", column -> { + column.padding(DocumentInsets.of(30)).spacing(6); + for (int index = 0; index < 60; index++) { + int current = index; + column.addParagraph(p -> p + .name("line-" + current) + .text("line " + current + " with enough words to occupy a line")); + } + })) + .build(); + + assertThat(session.layoutGraph().totalPages()).isGreaterThan(2); + assertThat(firstLineTopGap(session, 1)) + .as("page 2 opens the body and keeps its own top edge") + .isLessThan(36.0); + assertThat(firstLineTopGap(session, 2)) + .as("page 3 is the first continuation and clears the safe area") + .isGreaterThanOrEqualTo(36.0); + } + } + + // -- helpers ----------------------------------------------------------- + + private static DocumentSession fullBleed() { + return GraphCompose.document() + .pageSize(DocumentPageSize.A4) + .margin(DocumentInsets.zero()) + .create(); + } + + private static void fillPastOnePage(DocumentSession session) { + session.dsl().pageFlow() + .name("Root") + .padding(DocumentInsets.zero()) + .addColumnFlow("Body", body -> body.addColumn("Only", column -> { + column.padding(DocumentInsets.of(30)).spacing(6); + for (int index = 0; index < 60; index++) { + int current = index; + column.addParagraph(p -> p + .name("line-" + current) + .text("line " + current + " with enough words to occupy a line")); + } + })) + .build(); + } + + private static double firstLineTopGap(DocumentSession session, int pageIndex) { + double pageHeight = session.canvas().height(); + return session.layoutGraph().fragments().stream() + .filter(fragment -> fragment.pageIndex() == pageIndex) + .filter(fragment -> fragment.payload() instanceof ParagraphFragmentPayload) + .mapToDouble(fragment -> pageHeight - (fragment.y() + fragment.height())) + .min() + .orElseThrow(() -> new AssertionError("no text on page " + (pageIndex + 1))); + } + + private static double leftEdgeOfFirstLine(DocumentSession session, int pageIndex) { + return session.layoutGraph().fragments().stream() + .filter(fragment -> fragment.pageIndex() == pageIndex) + .filter(fragment -> fragment.payload() instanceof ParagraphFragmentPayload) + .mapToDouble(fragment -> fragment.x()) + .min() + .orElseThrow(() -> new AssertionError("no text on page " + (pageIndex + 1))); + } +} diff --git a/qa/src/test/java/com/demcha/compose/document/templates/cv/api/ModularCvTemplateFidelityTest.java b/qa/src/test/java/com/demcha/compose/document/templates/cv/api/ModularCvTemplateFidelityTest.java new file mode 100644 index 000000000..291e40360 --- /dev/null +++ b/qa/src/test/java/com/demcha/compose/document/templates/cv/api/ModularCvTemplateFidelityTest.java @@ -0,0 +1,265 @@ +package com.demcha.compose.document.templates.cv.api; + +import com.demcha.compose.GraphCompose; +import com.demcha.compose.document.api.DocumentPageSize; +import com.demcha.compose.document.api.DocumentSession; +import com.demcha.compose.document.node.DocumentNode; +import com.demcha.compose.document.node.ParagraphNode; +import com.demcha.compose.document.templates.api.DocumentTemplate; +import com.demcha.compose.document.templates.cv.data.CvDocument; +import com.demcha.compose.document.templates.cv.data.CvIdentity; +import com.demcha.compose.document.templates.cv.data.CvItem; +import com.demcha.compose.document.templates.cv.data.CvKind; +import com.demcha.compose.document.templates.cv.data.ModuleSection; +import com.demcha.compose.document.templates.cv.data.SectionRole; +import com.demcha.compose.document.templates.cv.data.Slot; +import com.demcha.compose.document.templates.cv.presets.CvTemplates; +import org.junit.jupiter.api.Named; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.MethodSource; + +import java.util.List; +import java.util.stream.Stream; + +import static org.assertj.core.api.Assertions.assertThat; + +/** + * Every template that declares {@link ModularCvTemplate} renders every kind + * of module, under whatever heading the author wrote. + * + *

The interface is a promise made to a caller who cannot check it: a CV + * builder offers the modular templates and trusts that whatever the user + * assembled comes out the other side. A template that quietly dropped a + * section would produce a CV that still looks finished — the failure has no + * symptom at the point it happens, only a missing job three weeks later. + * This is where the promise is checked, so wearing the interface costs + * something.

+ * + *

It enumerates {@link CvTemplates#modular()} rather than a list of its + * own, and every {@link CvKind} rather than the kinds in use, so a template + * or a kind added later is covered the day it lands — the coverage cannot + * be forgotten, only made to pass.

+ * + *

Text is read from the composed layout, not the PDF text layer: the CV + * themes draw with the standard-14 Helvetica, whose encoding has no + * Cyrillic, and the non-Latin heading below is the case that matters most. + * What the model owes is that the section is placed carrying its own words; + * which glyphs a font can draw is the caller's font choice.

+ */ +class ModularCvTemplateFidelityTest { + + private static Stream> modularTemplates() { + return CvTemplates.modular().stream() + .map(template -> Named.of(template.id(), template)); + } + + @ParameterizedTest(name = "{0}") + @MethodSource("modularTemplates") + void everyModularTemplateRendersEveryKind(ModularCvTemplate template) { + String text = composedText(template, everyKindDocument()); + + for (CvKind kind : CvKind.values()) { + // Case-insensitively: a preset that upper-cases its entry titles is + // styling them, not losing them. + assertThat(text) + .as("%s must render the %s module's item", template.id(), kind) + .containsIgnoringCase(itemTitle(kind)); + assertThat(text) + .as("%s must render the %s module's description", template.id(), kind) + .contains(bodyLine(kind)); + } + } + + @ParameterizedTest(name = "{0}") + @MethodSource("modularTemplates") + void everyModularTemplateRendersAnAdHocSection(ModularCvTemplate template) { + // No keyword list contains "Volunteering", and no preset was written + // with it in mind. A section the author invented is the whole point of + // assembling a CV at runtime, so it is the minimum this promise means. + CvDocument doc = document(ModuleSection.builder("Volunteering", SectionRole.OTHER, + CvKind.ENTRIES_DATED) + .item(CvItem.of("Mentor, Rails Girls").at("Rails Girls Berlin") + .period("2019 - 2021").bullets("Ran three weekend workshops")) + .build()); + + String text = composedText(template, doc); + + assertThatHeading(text, "Volunteering", template); + assertThat(text) + .as("%s must render the invented section's entry", template.id()) + .containsIgnoringCase("Mentor, Rails Girls"); + assertThat(text) + .as("%s must render the invented section's description", template.id()) + .contains("Ran three weekend workshops"); + } + + @ParameterizedTest(name = "{0}") + @MethodSource("modularTemplates") + void everyModularTemplateRendersANonLatinHeading(ModularCvTemplate template) { + CvDocument doc = document(ModuleSection.builder("Навыки", SectionRole.SKILLS, + CvKind.INLINE_LIST) + .item(CvItem.of("Языки").paragraphs("Java 21", "Kotlin")) + .build()); + + String text = composedText(template, doc); + + assertThatHeading(text, "Навыки", template); + assertThat(text) + .as("%s must render the section's items", template.id()) + .contains("Языки", "Java 21, Kotlin"); + } + + @ParameterizedTest(name = "{0}") + @MethodSource("modularTemplates") + void aHeadingThePresetHasAWordForIsStillTheAuthorsHeading(ModularCvTemplate template) { + // The ad-hoc cases above use headings no keyword list contains, which is + // the easy half. A preset with an editorial vocabulary of its own is the + // one that rewrites: one of these renamed any heading matching + // "certification" to EDUCATION, so "Certifications & Awards" reached the + // page as a word the author never wrote and the awards lost their title. + CvDocument doc = document(ModuleSection.builder("Certifications & Awards", + SectionRole.OTHER, CvKind.BULLETS) + .item(CvItem.of("AWS Solutions Architect").paragraphs("2024")) + .build()); + + String text = composedText(template, doc); + + assertThatHeading(text, "Certifications & Awards", template); + assertThat(text) + .as("%s must render the section's item", template.id()) + .containsIgnoringCase("AWS Solutions Architect"); + } + + @ParameterizedTest(name = "{0}") + @MethodSource("modularTemplates") + void aSidebarSectionIsNotRenderedAndTheContractSaysSo(ModularCvTemplate template) { + // Pinning a limitation, not a feature. Every shipped preset composes one + // main column and reads Slot.MAIN, so a section placed in the sidebar is + // dropped — which ModularCvTemplate's contract states rather than leaving + // "renders whatever it is handed" to be read generously. When slots go + // live this test goes red, which is the point: the promise and the code + // change together. + CvDocument doc = CvDocument.builder() + .identity(identity()) + .section(Slot.SIDEBAR, ModuleSection.builder("Languages", + SectionRole.LANGUAGES, CvKind.INLINE_LIST) + .item(CvItem.of("Spoken").paragraphs("English", "German")) + .build()) + .build(); + + assertThat(composedText(template, doc)) + .as("%s reads Slot.MAIN, as its contract says", template.id()) + .doesNotContain("Spoken"); + } + + @ParameterizedTest(name = "{0}") + @MethodSource("modularTemplates") + void everyModularTemplateDeclaresAKit(ModularCvTemplate template) { + assertThat(template.kit()) + .as("%s must hand back a kit — the drawing half of the promise", template.id()) + .isNotNull(); + } + + @Test + void theModularListIsASubsetOfTheCatalogueAndNotEmpty() { + List modularIds = CvTemplates.modular().stream() + .map(DocumentTemplate::id).toList(); + + assertThat(modularIds) + .as("a promise nobody makes is a promise nobody keeps") + .isNotEmpty(); + assertThat(CvTemplates.ids()).containsAll(modularIds); + assertThat(modularIds).doesNotHaveDuplicates(); + } + + /** + * Asserts the heading reached the page, ignoring how the preset styled + * it: several letter-space and upper-case their headings, so + * "Volunteering" arrives as "V O L U N T E E R I N G". The words are the + * template's to keep; the typography is the template's to choose. + */ + private static void assertThatHeading(String text, String heading, + ModularCvTemplate template) { + assertThat(text.replace(" ", "")) + .as("%s must render the section under its own heading (%s)", + template.id(), heading) + .containsIgnoringCase(heading.replace(" ", "")); + } + + // -- fixtures -------------------------------------------------------- + + /** + * One module per kind, each carrying an item whose title and description + * name the kind — so a failure says which kind was dropped rather than + * that something was missing. + */ + private static CvDocument everyKindDocument() { + CvDocument.Builder builder = CvDocument.builder().identity(identity()); + for (CvKind kind : CvKind.values()) { + builder.section(ModuleSection.builder(sectionTitle(kind), SectionRole.OTHER, kind) + .item(CvItem.of(itemTitle(kind)) + .at("Acme GmbH").in("Berlin").period("2021 - Present") + .paragraphs(bodyLine(kind))) + .build()); + } + return builder.build(); + } + + private static String sectionTitle(CvKind kind) { + return "Section " + marker(kind); + } + + /** + * The kind's name with its underscore removed. An underscore is markdown + * for italic, and a fixture carrying two of them would be reporting the + * markdown parser rather than the template. + */ + private static String marker(CvKind kind) { + return kind.name().replace("_", " "); + } + + private static String itemTitle(CvKind kind) { + // PARAGRAPH reads the body alone, so its item title never reaches the + // page; the body carries the marker for that kind instead. + return kind == CvKind.PARAGRAPH ? bodyLine(kind) : "Item " + marker(kind); + } + + private static String bodyLine(CvKind kind) { + return "Body of " + marker(kind); + } + + private static CvDocument document(ModuleSection module) { + return CvDocument.builder().identity(identity()).section(module).build(); + } + + private static CvIdentity identity() { + return CvIdentity.builder() + .name("Jordan", "Rivera") + .jobTitle("Backend Engineer") + .contact("+1 555 0100", "jordan@example.com", "Berlin, DE") + .build(); + } + + /** Every string the composed layout carries, joined. */ + private static String composedText(DocumentTemplate template, CvDocument doc) { + try (DocumentSession session = GraphCompose.document() + .pageSize(DocumentPageSize.A4) + .margin(24, 24, 24, 24) + .create()) { + template.compose(session, doc); + StringBuilder text = new StringBuilder(); + collectText(session.roots(), text); + return text.toString(); + } + } + + private static void collectText(List nodes, StringBuilder out) { + for (DocumentNode node : nodes) { + if (node instanceof ParagraphNode paragraph) { + out.append(paragraph.text()).append(' '); + } + collectText(node.children(), out); + } + } +} diff --git a/qa/src/test/java/com/demcha/compose/document/templates/cv/components/ModuleSectionKindCoverageTest.java b/qa/src/test/java/com/demcha/compose/document/templates/cv/components/ModuleSectionKindCoverageTest.java new file mode 100644 index 000000000..08defa811 --- /dev/null +++ b/qa/src/test/java/com/demcha/compose/document/templates/cv/components/ModuleSectionKindCoverageTest.java @@ -0,0 +1,243 @@ +package com.demcha.compose.document.templates.cv.components; + +import com.demcha.compose.GraphCompose; +import com.demcha.compose.document.api.DocumentPageSize; +import com.demcha.compose.document.api.DocumentSession; +import com.demcha.compose.document.node.DocumentNode; +import com.demcha.compose.document.node.ParagraphNode; +import com.demcha.compose.document.templates.api.DocumentTemplate; +import com.demcha.compose.document.templates.cv.data.CvDocument; +import com.demcha.compose.document.templates.cv.data.CvIdentity; +import com.demcha.compose.document.templates.cv.data.CvItem; +import com.demcha.compose.document.templates.cv.data.CvKind; +import com.demcha.compose.document.templates.cv.data.ModuleSection; +import com.demcha.compose.document.templates.cv.data.SectionRole; +import com.demcha.compose.document.templates.cv.presets.BlueBanner; +import com.demcha.compose.document.templates.cv.presets.BoxedSections; +import com.demcha.compose.document.templates.cv.presets.CenteredHeadline; +import com.demcha.compose.document.templates.cv.presets.ClassicSerif; +import com.demcha.compose.document.templates.cv.presets.CompactMono; +import com.demcha.compose.document.templates.cv.presets.EditorialBlue; +import com.demcha.compose.document.templates.cv.presets.EngineeringResume; +import com.demcha.compose.document.templates.cv.presets.Executive; +import com.demcha.compose.document.templates.cv.presets.MinimalUnderlined; +import com.demcha.compose.document.templates.cv.presets.MintEditorial; +import com.demcha.compose.document.templates.cv.presets.ModernProfessional; +import com.demcha.compose.document.templates.cv.presets.MonogramSidebar; +import com.demcha.compose.document.templates.cv.presets.NordicClean; +import com.demcha.compose.document.templates.cv.presets.Panel; +import com.demcha.compose.document.templates.cv.presets.SidebarPortrait; +import com.demcha.compose.document.templates.cv.presets.TimelineMinimal; +import org.apache.pdfbox.Loader; +import org.apache.pdfbox.pdmodel.PDDocument; +import org.apache.pdfbox.text.PDFTextStripper; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.EnumSource; +import org.junit.jupiter.params.provider.MethodSource; + +import java.util.List; +import java.util.stream.Stream; + +import static org.assertj.core.api.Assertions.assertThat; +import static org.assertj.core.api.Assertions.assertThatCode; + +/** + * Every {@link CvKind} reaches the page, and no preset fails on a module. + * + *

A runtime module is only as good as the weakest kind: an author who picks + * one the renderers never learned to lower gets a section that silently draws + * nothing, and the CV looks finished. Enumerating the enum rather than listing + * cases means a kind added later fails here until it is wired, which is the + * point — a new constant cannot ship half-rendered.

+ * + *

The per-template promise — every kind, an invented heading, a non-Latin + * one — is checked in {@code ModularCvTemplateFidelityTest}, which enumerates + * the templates that declare the capability instead of a list kept by hand. + * What stays here is the kind-level coverage and the floor every preset owes + * whether or not it declares anything.

+ */ +class ModuleSectionKindCoverageTest { + + /** Presets that render every section the document carries, in order. */ + private static Stream> generalPresets() { + return Stream.of(ModernProfessional.create(), BoxedSections.create(), + MinimalUnderlined.create(), Executive.create(), + CenteredHeadline.create(), BlueBanner.create()); + } + + /** + * Presets that render whatever section they are handed — the six general + * loops plus the two that route by heading and then draw any shape. + */ + private static Stream> presetsThatRenderAnyShape() { + return Stream.concat(generalPresets(), + Stream.of(ClassicSerif.create(), EditorialBlue.create())); + } + + /** + * Presets whose module slots are guarded on the section's Java type — + * {@code if (!(section instanceof EntriesSection entries)) return;} and + * friends — so a module routed to one of those slots is skipped whatever + * its kind. Placing them is the routing work, not this change; what is + * pinned here is that they do not fail. + */ + private static Stream> presetsThatGuardOnSectionType() { + return Stream.of(CompactMono.create(), EngineeringResume.create(), + MintEditorial.create(), MonogramSidebar.create(), NordicClean.create(), + Panel.create(), SidebarPortrait.create(), TimelineMinimal.create()); + } + + /** Every shipped CV preset. */ + private static Stream> everyPreset() { + return Stream.concat(presetsThatRenderAnyShape(), presetsThatGuardOnSectionType()); + } + + @ParameterizedTest + @EnumSource(CvKind.class) + void everyKindPutsItsDescriptionsOnThePage(CvKind kind) throws Exception { + ModuleSection module = ModuleSection.builder("Selected Work", SectionRole.OTHER, kind) + .item(CvItem.of("First entry").at("Acme GmbH").in("Berlin") + .period("2021 - Present").paragraphs("Did the work.")) + .item(CvItem.of("Second entry").at("Northwind").period("2018 - 2021") + .bullets("Shipped it", "Measured it")) + .build(); + + String text = render(ModernProfessional.create(), module); + + assertThat(text) + .as("%s must render every description line — no kind may drop the body", kind) + .contains("Did the work.", "Shipped it", "Measured it"); + } + + @ParameterizedTest + @EnumSource(value = CvKind.class, names = "PARAGRAPH", mode = EnumSource.Mode.EXCLUDE) + void everyTitledKindPutsItsTitlesOnThePage(CvKind kind) throws Exception { + // PARAGRAPH is excluded on purpose, not overlooked: it renders prose under + // the section's own heading and documents that it reads the body alone — + // the case below pins that, so the two together cover the whole enum. + ModuleSection module = ModuleSection.builder("Selected Work", SectionRole.OTHER, kind) + .item(CvItem.of("First entry").paragraphs("Did the work.")) + .item(CvItem.of("Second entry").period("2018").paragraphs("Did more.")) + .build(); + + assertThat(render(ModernProfessional.create(), module)) + .as("%s reads the item title, so it must reach the page", kind) + .contains("First entry", "Second entry"); + } + + @Test + void proseRendersWithoutRepeatingTheHeading() throws Exception { + ModuleSection module = ModuleSection.summary("Profile", "Backend engineer."); + + String text = render(ModernProfessional.create(), module); + + assertThat(text).contains("Backend engineer."); + assertThat(text.split("Profile", -1)) + .as("the heading is the section's; PARAGRAPH must not print it a second time") + .hasSize(2); + } + + @ParameterizedTest + @MethodSource("presetsThatRenderAnyShape") + void aModuleUnderAHeadingThePresetKnowsIsRendered(DocumentTemplate preset) + throws Exception { + // Stronger than "does not throw", and the case that catches the failure + // no-throw cannot see: presets consult SectionLookup.hasContent before they + // route or render, and its default for an unrecognised subtype is false — + // which discarded the module's heading and body together, on presets whose + // rendering path for it was perfectly good. The heading here is one every + // preset's keyword list contains, so nothing but that gate can lose it. + ModuleSection module = ModuleSection.builder("Professional Experience", + SectionRole.EXPERIENCE, CvKind.ENTRIES_DATED) + .item(CvItem.of("Senior Backend Engineer").at("Acme GmbH") + .period("2021 - Present").paragraphs("Owned the settlement service.")) + .build(); + + assertThat(render(preset, module)) + .as("%s must render a module it routed by heading", preset.id()) + // Case-insensitively: a preset that upper-cases entry titles — and + // one now does, through its own kit — is styling, not dropping. + .containsIgnoringCase("Senior Backend Engineer"); + } + + @Test + void aModuleAndTheOlderSectionTypesCoexistInOneDocument() throws Exception { + // The new permit is additive: a document may mix a runtime module with + // the hand-written records, which is what a migration looks like. + CvDocument doc = CvDocument.builder() + .identity(identity()) + .section(ModuleSection.summary("Profile", "Backend engineer.")) + .section(com.demcha.compose.document.templates.cv.data.EntriesSection + .builder("Education") + .entry("BSc Computer Science", "TU Berlin", "2014 - 2018", "") + .build()) + .section(ModuleSection.builder("Volunteering", SectionRole.OTHER, CvKind.BULLETS) + .item("Rails Girls mentor") + .build()) + .build(); + + assertThat(renderDocument(ModernProfessional.create(), doc)) + .contains("Backend engineer.", "BSc Computer Science", "Rails Girls mentor"); + } + + // -- helpers --------------------------------------------------------- + + private static String render(DocumentTemplate preset, ModuleSection module) + throws Exception { + return renderDocument(preset, CvDocument.builder() + .identity(identity()) + .sections(List.of(module)) + .build()); + } + + private static String renderDocument(DocumentTemplate preset, CvDocument doc) + throws Exception { + try (DocumentSession session = GraphCompose.document() + .pageSize(DocumentPageSize.A4) + .margin(24, 24, 24, 24) + .create()) { + preset.compose(session, doc); + try (PDDocument pdf = Loader.loadPDF(session.toPdfBytes())) { + return new PDFTextStripper().getText(pdf).replaceAll("\\s+", " ").trim(); + } + } + } + + /** + * Every string the composed layout carries, joined — the text before a font + * gets a say in whether it can draw it. + */ + private static String composedText(DocumentTemplate preset, ModuleSection module) { + try (DocumentSession session = GraphCompose.document() + .pageSize(DocumentPageSize.A4) + .margin(24, 24, 24, 24) + .create()) { + preset.compose(session, CvDocument.builder() + .identity(identity()).sections(List.of(module)).build()); + StringBuilder text = new StringBuilder(); + collectText(session.roots(), text); + return text.toString(); + } + } + + private static void collectText(List nodes, StringBuilder out) { + for (DocumentNode node : nodes) { + if (node instanceof ParagraphNode paragraph) { + // text() carries the plain string AND the concatenation of any + // rich runs, so it sees both a header written with .text(...) and + // a body assembled from markdown runs. + out.append(paragraph.text()).append(' '); + } + collectText(node.children(), out); + } + } + + private static CvIdentity identity() { + return CvIdentity.builder() + .name("Jordan", "Rivera") + .jobTitle("Backend Engineer") + .contact("+1 555 0100", "jordan@example.com", "Berlin, DE") + .build(); + } +} diff --git a/qa/src/test/java/com/demcha/compose/document/templates/cv/components/ModuleSectionParityTest.java b/qa/src/test/java/com/demcha/compose/document/templates/cv/components/ModuleSectionParityTest.java new file mode 100644 index 000000000..eb82d249a --- /dev/null +++ b/qa/src/test/java/com/demcha/compose/document/templates/cv/components/ModuleSectionParityTest.java @@ -0,0 +1,349 @@ +package com.demcha.compose.document.templates.cv.components; + +import com.demcha.compose.GraphCompose; +import com.demcha.compose.document.api.DocumentPageSize; +import com.demcha.compose.document.api.DocumentSession; +import com.demcha.compose.document.templates.cv.data.CvDocument; +import com.demcha.compose.document.templates.cv.data.CvIdentity; +import com.demcha.compose.document.templates.cv.data.CvItem; +import com.demcha.compose.document.templates.cv.data.CvKind; +import com.demcha.compose.document.templates.cv.data.CvSection; +import com.demcha.compose.document.templates.cv.data.EntriesSection; +import com.demcha.compose.document.templates.cv.data.ModuleSection; +import com.demcha.compose.document.templates.cv.data.ParagraphSection; +import com.demcha.compose.document.templates.cv.data.RowStyle; +import com.demcha.compose.document.templates.cv.data.RowsSection; +import com.demcha.compose.document.templates.cv.data.SectionRole; +import com.demcha.compose.document.templates.cv.presets.ModernProfessional; +import com.demcha.compose.testing.layout.LayoutSnapshotJson; +import org.apache.pdfbox.Loader; +import org.apache.pdfbox.pdmodel.PDDocument; +import org.apache.pdfbox.text.PDFTextStripper; +import org.junit.jupiter.api.Test; + +import static org.assertj.core.api.Assertions.assertThat; + +/** + * A {@code ModuleSection} chosen at runtime must lay out exactly like the + * section a Java author would have written by hand for the same content. + * + *

That equivalence is the whole basis of the runtime module: it renders + * through the existing components rather than beside them, so the two + * authoring routes are two spellings of one document. Left unchecked it is a + * claim in a Javadoc, and the failure it hides is silent — a module that + * merely looks close, on a preset nobody re-renders, in a CV nobody compares + * side by side.

+ * + *

Each case pins both halves of "the same": the layout snapshot, which + * carries node structure and bounds but not text, and the extracted PDF text, + * which carries the words but not their positions. Either alone passes + * documents the other would catch.

+ */ +class ModuleSectionParityTest { + + @Test + void datedEntriesMatchAHandWrittenEntriesSection() throws Exception { + CvSection handWritten = EntriesSection.builder("Professional Experience") + .entry("Senior Backend Engineer", "Acme GmbH", "2021 - Present", + "Cut p99 latency by 40%.") + .entry("Backend Engineer", "Northwind Systems", "2018 - 2021", + "Owned the billing service.") + .build(); + + CvSection module = ModuleSection.builder("Professional Experience", + SectionRole.EXPERIENCE, CvKind.ENTRIES_DATED) + .item(CvItem.of("Senior Backend Engineer").at("Acme GmbH") + .period("2021 - Present").paragraphs("Cut p99 latency by 40%.")) + .item(CvItem.of("Backend Engineer").at("Northwind Systems") + .period("2018 - 2021").paragraphs("Owned the billing service.")) + .build(); + + assertSameRender(handWritten, module); + } + + @Test + void anInlineListMatchesAHandWrittenPlainRowsSection() throws Exception { + CvSection handWritten = RowsSection.builder("Additional Information", RowStyle.PLAIN) + .row("Languages", "English (Fluent), German (B2)") + .row("Interests", "Chess, long-distance cycling") + .build(); + + CvSection module = ModuleSection.builder("Additional Information", + SectionRole.OTHER, CvKind.INLINE_LIST) + .item(CvItem.of("Languages").paragraphs("English (Fluent)", "German (B2)")) + .item(CvItem.of("Interests").paragraphs("Chess", "long-distance cycling")) + .build(); + + assertSameRender(handWritten, module); + } + + @Test + void oneLineBulletsMatchAHandWrittenBulletedRowsSection() throws Exception { + CvSection handWritten = RowsSection.builder("Highlights", RowStyle.BULLETED) + .row("Throughput", "Doubled it") + .row("Onboarding", "Cut to two days") + .build(); + + CvSection module = ModuleSection.builder("Highlights", SectionRole.OTHER, CvKind.BULLETS) + .item(CvItem.of("Throughput").paragraphs("Doubled it")) + .item(CvItem.of("Onboarding").paragraphs("Cut to two days")) + .build(); + + assertSameRender(handWritten, module); + } + + @Test + void stackedBulletsMatchAHandWrittenStackedRowsSection() throws Exception { + CvSection handWritten = RowsSection.builder("Projects", RowStyle.BULLETED_STACKED) + .row("GraphCompose (Java 21, PDFBox)", + "A declarative layout engine for programmatic documents.") + .row("Ledger (Kotlin)", "Double-entry bookkeeping for small studios.") + .build(); + + // paragraphs(), not bullets(): a stacked row indents its description under + // the title, which is what prose does. BodyStyle.BULLETS asks for a bullet + // on each description line instead — a different shape, pinned by the case + // below rather than smuggled into this comparison. + CvSection module = ModuleSection.builder("Projects", SectionRole.PROJECTS, + CvKind.BULLETS_STACKED) + .item(CvItem.of("GraphCompose (Java 21, PDFBox)") + .paragraphs("A declarative layout engine for programmatic documents.")) + .item(CvItem.of("Ledger (Kotlin)") + .paragraphs("Double-entry bookkeeping for small studios.")) + .build(); + + assertSameRender(handWritten, module); + } + + @Test + void aBulletedBodyNestsABulletUnderTheItemsOwn() throws Exception { + CvSection prose = ModuleSection.builder("Projects", SectionRole.PROJECTS, + CvKind.BULLETS_STACKED) + .item(CvItem.of("GraphCompose").paragraphs("Shipped it", "Measured it")) + .build(); + CvSection bulleted = ModuleSection.builder("Projects", SectionRole.PROJECTS, + CvKind.BULLETS_STACKED) + .item(CvItem.of("GraphCompose").bullets("Shipped it", "Measured it")) + .build(); + + assertThat(text(bulleted)) + .as("BodyStyle.BULLETS must reach the page as bullets, not as indented prose") + .isNotEqualTo(text(prose)) + .contains("• Shipped it", "• Measured it"); + } + + @Test + void proseMatchesAHandWrittenParagraphSection() throws Exception { + CvSection handWritten = new ParagraphSection("Professional Summary", + "Backend engineer with ten years on payment systems."); + + CvSection module = ModuleSection.summary("Professional Summary", + "Backend engineer with ten years on payment systems."); + + assertSameRender(handWritten, module); + } + + @Test + void undatedEntriesMatchAHandWrittenEntriesSectionWithBlankDates() throws Exception { + // The blank-date path is a change to EntryRenderer itself, so pin it the + // same way: an undated module and the hand-written section that has always + // been able to express one must produce the same layout. + CvSection handWritten = EntriesSection.builder("Certifications") + .entry("AWS Solutions Architect", "Amazon", "", "") + .entry("CKA", "Linux Foundation", "", "") + .build(); + + CvSection module = ModuleSection.builder("Certifications", SectionRole.OTHER, + CvKind.ENTRIES) + .item(CvItem.of("AWS Solutions Architect").at("Amazon")) + .item(CvItem.of("CKA").at("Linux Foundation")) + .build(); + + assertSameRender(handWritten, module); + } + + @Test + void anUndatedEntryDropsTheDateColumnRatherThanReservingIt() throws Exception { + // The kind's whole contract is that it ignores the period. Rendering an + // empty date column instead would still "ignore" it while narrowing every + // title on the page, so pin the shape, not just the absent text. + CvSection dated = ModuleSection.builder("Certifications", SectionRole.OTHER, + CvKind.ENTRIES_DATED) + .item(CvItem.of("AWS Solutions Architect").at("Amazon").period("2024")) + .build(); + CvSection undated = ModuleSection.builder("Certifications", SectionRole.OTHER, + CvKind.ENTRIES) + .item(CvItem.of("AWS Solutions Architect").at("Amazon").period("2024")) + .build(); + + assertThat(layoutJson(undated)) + .as("an undated entry must not lay out like a dated one") + .isNotEqualTo(layoutJson(dated)); + assertThat(text(undated)).contains("AWS Solutions Architect", "Amazon"); + assertThat(text(undated)) + .as("the period must not reach the page under CvKind.ENTRIES") + .doesNotContain("2024"); + assertThat(text(dated)).contains("2024"); + } + + @Test + void anItemLinkRendersAsAClickableTitle() throws Exception { + CvSection module = ModuleSection.builder("Projects", SectionRole.PROJECTS, + CvKind.BULLETS_STACKED) + .item(CvItem.of("GraphCompose").linkedTo("https://example.dev/gc") + .paragraphs("A layout engine.")) + .build(); + + assertThat(text(module)) + .as("the link URL is the target, not the visible text") + .contains("GraphCompose") + .doesNotContain("https://example.dev/gc"); + assertThat(text(module)) + .as("markdown markers are instructions, not content — none may reach the page") + .doesNotContain("*", "[", "]"); + assertThat(externalLinkTargets(module)).contains("https://example.dev/gc"); + } + + @Test + void aBracketedTitleNeverLeaksItsUrlAsVisibleText() throws Exception { + // The markdown link label admits no brackets, so wrapping this title would + // match nothing and print the whole construction. Losing the click target + // is the acceptable outcome here; printing the URL is not. + CvSection module = ModuleSection.builder("Projects", SectionRole.PROJECTS, + CvKind.BULLETS_STACKED) + .item(CvItem.of("Ledger [v2]").linkedTo("https://example.dev/ledger") + .paragraphs("Double-entry bookkeeping.")) + .build(); + + assertThat(text(module)) + .contains("Ledger [v2]", "Double-entry bookkeeping.") + .doesNotContain("https://example.dev/ledger"); + } + + @Test + void aTitleOnlyBulletHasNoColonPointingAtNothing() throws Exception { + CvSection module = ModuleSection.builder("Interests", SectionRole.OTHER, CvKind.BULLETS) + .item("Chess") + .item("Long-distance cycling") + .build(); + + assertThat(text(module)) + .contains("Chess", "Long-distance cycling") + .doesNotContain("Chess:", "cycling:"); + } + + @Test + void anInlineListWithNothingToListRendersItsLabelAlone() throws Exception { + CvSection module = ModuleSection.builder("Languages", SectionRole.LANGUAGES, + CvKind.INLINE_LIST) + .item("English") + .build(); + + assertThat(text(module)).contains("English").doesNotContain("English:"); + } + + @Test + void everyKindIgnoresExactlyTheFieldsItSaysItIgnores() throws Exception { + // The contract that makes one item record serve every module is that the + // kind decides what is read. Stated in CvKind's Javadoc and the docs table; + // pinned here, per kind, by rendering one item that carries everything. + CvItem everything = CvItem.of("Item title") + .at("SubtitleValue").in("LocationValue").period("PeriodValue") + .paragraphs("Body line."); + + assertThat(render(CvKind.PARAGRAPH, everything)) + .as("PARAGRAPH reads the body alone") + .contains("Body line.") + .doesNotContain("Item title", "SubtitleValue", "PeriodValue", "LocationValue"); + assertThat(render(CvKind.BULLETS, everything)) + .as("BULLETS reads title and body") + .contains("Item title", "Body line.") + .doesNotContain("SubtitleValue", "PeriodValue", "LocationValue"); + assertThat(render(CvKind.BULLETS_STACKED, everything)) + .as("BULLETS_STACKED reads title and body") + .contains("Item title", "Body line.") + .doesNotContain("SubtitleValue", "PeriodValue", "LocationValue"); + assertThat(render(CvKind.INLINE_LIST, everything)) + .as("INLINE_LIST reads title and body") + .contains("Item title", "Body line.") + .doesNotContain("SubtitleValue", "PeriodValue", "LocationValue"); + assertThat(render(CvKind.ENTRIES, everything)) + .as("ENTRIES reads everything but the period") + .contains("Item title", "SubtitleValue", "LocationValue", "Body line.") + .doesNotContain("PeriodValue"); + assertThat(render(CvKind.ENTRIES_DATED, everything)) + .as("ENTRIES_DATED reads every field") + .contains("Item title", "SubtitleValue", "LocationValue", "PeriodValue", + "Body line."); + } + + private static String render(CvKind kind, CvItem item) throws Exception { + return text(ModuleSection.of("Section", SectionRole.OTHER, kind, item)); + } + + // -- helpers --------------------------------------------------------- + + private static void assertSameRender(CvSection handWritten, CvSection module) throws Exception { + assertThat(layoutJson(module)) + .as("a runtime module must lay out node-for-node like the hand-written section") + .isEqualTo(layoutJson(handWritten)); + assertThat(text(module)) + .as("...and carry the same words: the snapshot above compares structure, not content") + .isEqualTo(text(handWritten)); + } + + private static String layoutJson(CvSection section) throws Exception { + try (DocumentSession session = newSession()) { + ModernProfessional.create().compose(session, docWith(section)); + return LayoutSnapshotJson.toJson(session.layoutSnapshot()); + } + } + + private static String text(CvSection section) throws Exception { + try (DocumentSession session = newSession()) { + ModernProfessional.create().compose(session, docWith(section)); + try (PDDocument pdf = Loader.loadPDF(session.toPdfBytes())) { + return new PDFTextStripper().getText(pdf).replaceAll("\\s+", " ").trim(); + } + } + } + + private static java.util.List externalLinkTargets(CvSection section) throws Exception { + try (DocumentSession session = newSession()) { + ModernProfessional.create().compose(session, docWith(section)); + try (PDDocument pdf = Loader.loadPDF(session.toPdfBytes())) { + java.util.List targets = new java.util.ArrayList<>(); + for (org.apache.pdfbox.pdmodel.PDPage page : pdf.getPages()) { + for (org.apache.pdfbox.pdmodel.interactive.annotation.PDAnnotation annotation + : page.getAnnotations()) { + if (annotation instanceof org.apache.pdfbox.pdmodel.interactive.annotation.PDAnnotationLink link + && link.getAction() + instanceof org.apache.pdfbox.pdmodel.interactive.action.PDActionURI uri) { + targets.add(uri.getURI()); + } + } + } + return targets; + } + } + } + + private static CvDocument docWith(CvSection section) { + return CvDocument.builder() + .identity(CvIdentity.builder() + .name("Jordan", "Rivera") + .jobTitle("Backend Engineer") + .contact("+1 555 0100", "jordan@example.com", "Berlin, DE") + .build()) + .section(section) + .build(); + } + + private static DocumentSession newSession() { + float margin = (float) ModernProfessional.RECOMMENDED_MARGIN; + return GraphCompose.document() + .pageSize(DocumentPageSize.A4) + .margin(margin, margin, margin, margin) + .create(); + } +} diff --git a/qa/src/test/java/com/demcha/compose/document/templates/cv/components/RoleRoutingTest.java b/qa/src/test/java/com/demcha/compose/document/templates/cv/components/RoleRoutingTest.java new file mode 100644 index 000000000..a5a92edcb --- /dev/null +++ b/qa/src/test/java/com/demcha/compose/document/templates/cv/components/RoleRoutingTest.java @@ -0,0 +1,185 @@ +package com.demcha.compose.document.templates.cv.components; + +import com.demcha.compose.GraphCompose; +import com.demcha.compose.document.api.DocumentPageSize; +import com.demcha.compose.document.api.DocumentSession; +import com.demcha.compose.document.node.DocumentNode; +import com.demcha.compose.document.node.ParagraphNode; +import com.demcha.compose.document.templates.api.DocumentTemplate; +import com.demcha.compose.document.templates.cv.data.CvDocument; +import com.demcha.compose.document.templates.cv.data.CvIdentity; +import com.demcha.compose.document.templates.cv.data.CvItem; +import com.demcha.compose.document.templates.cv.data.CvKind; +import com.demcha.compose.document.templates.cv.data.ModuleSection; +import com.demcha.compose.document.templates.cv.data.SectionRole; +import com.demcha.compose.document.templates.cv.presets.CvTemplates; +import org.junit.jupiter.api.Named; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.MethodSource; + +import java.util.List; +import java.util.stream.Stream; + +import static org.assertj.core.api.Assertions.assertThat; + +/** + * A CV whose headings are in the author's own language reaches the page on + * every preset. + * + *

Presets with a designed layout place sections into fixed slots, and they + * chose what goes where by matching the heading against a list of English + * words each kept privately. A CV headed {@code Berufserfahrung} or + * {@code Опыт работы} matched nothing: the section was dropped and the slot + * that wanted it rendered empty. Nothing failed — the CV came out looking + * finished, one job short.

+ * + *

A module states its {@link SectionRole}, so the routing has an answer + * that does not depend on the language the CV is written in. Every heading + * here is deliberately in Russian and German: if any preset still routes by + * keyword, its slot stays empty and this goes red.

+ */ +class RoleRoutingTest { + + private static Stream>> everyPreset() { + return CvTemplates.all().stream().map(t -> Named.of(t.id(), t)); + } + + @ParameterizedTest(name = "{0}") + @MethodSource("everyPreset") + void aCvWrittenInAnotherLanguageRendersOnEveryPreset(DocumentTemplate preset) { + String text = composedText(preset, foreignLanguageCv()); + + assertRendered(text, "Ведущий инженер", preset, "experience"); + assertRendered(text, "Информатика", preset, "education"); + } + + @ParameterizedTest(name = "{0}") + @MethodSource("everyPreset") + void aRoleRoutedModuleRendersWhateverItsKind(DocumentTemplate preset) { + // The slots were guarded on the section's Java type as well as its + // heading, so a module routed correctly was dropped anyway. Kinds here + // are deliberately the "wrong" shape for the slot each role names — + // experience as bullets, education as an inline list — because the + // author picks the kind and the preset does not get a veto. + CvDocument doc = CvDocument.builder() + .identity(identity()) + .section(ModuleSection.builder("Berufserfahrung", SectionRole.EXPERIENCE, + CvKind.BULLETS) + .item(CvItem.of("Senior Engineer").paragraphs("Acme GmbH, 2021-2025")) + .build()) + .section(ModuleSection.builder("Kenntnisse", SectionRole.SKILLS, + CvKind.INLINE_LIST) + .item(CvItem.of("Sprachen").paragraphs("Java 21", "Kotlin")) + .build()) + .build(); + + String text = composedText(preset, doc); + + assertRendered(text, "Senior Engineer", preset, "EXPERIENCE"); + assertRendered(text, "Java 21", preset, "SKILLS"); + } + + @Test + void theRoleWinsOverAHeadingThatMatchesADifferentSlot() { + // A module titled "Projects" but declared EXPERIENCE belongs where its + // author said, not where its heading reads. + List sections = List.of( + ModuleSection.builder("Projects", SectionRole.EXPERIENCE, CvKind.ENTRIES_DATED) + .item(CvItem.of("Senior Engineer").period("2021")).build()); + + assertThat(SectionRouter.find(sections, SectionRole.EXPERIENCE, List.of("experience"))) + .as("the role names the slot") + .isNotNull(); + assertThat(SectionRouter.find(sections, SectionRole.PROJECTS, List.of("projects"))) + .as("...and the heading no longer claims a slot the role did not name") + .isNull(); + } + + @Test + void aSectionWithoutARoleStillRoutesByItsHeading() { + // The four hand-written section types carry no role, and neither does a + // module the catalogue has no name for. Keywords remain the answer for + // them, so nothing that worked before stops working. + List sections = List.of( + new com.demcha.compose.document.templates.cv.data.ParagraphSection( + "Professional Summary", "Backend engineer."), + ModuleSection.builder("Awards", SectionRole.OTHER, CvKind.BULLETS) + .item("Employee of the year").build()); + + assertThat(SectionRouter.find(sections, SectionRole.SUMMARY, List.of("summary"))) + .as("a hand-written section still matches by heading") + .isNotNull(); + assertThat(SectionRouter.find(sections, SectionRole.OTHER, List.of("awards"))) + .as("SectionRole.OTHER claims no slot and falls through to the heading") + .isNotNull(); + } + + /** + * Asserts the words reached the page, ignoring how the preset set them: + * several upper-case entry titles and several letter-space them, so + * "Senior Engineer" arrives as "S E N I O R E N G I N E E R". Typography + * is the preset's to choose; the words are the author's to keep. + */ + private static void assertRendered(String text, String words, + DocumentTemplate preset, String slot) { + assertThat(text.replace(" ", "")) + .as("%s must render the %s module routed by role", preset.id(), slot) + .containsIgnoringCase(words.replace(" ", "")); + } + + // -- fixtures -------------------------------------------------------- + + private static CvDocument foreignLanguageCv() { + return CvDocument.builder() + .identity(identity()) + .section(ModuleSection.builder("О себе", SectionRole.SUMMARY, CvKind.PARAGRAPH) + .item(CvItem.of("summary").paragraphs("Backend engineer.")) + .build()) + .section(ModuleSection.builder("Опыт работы", SectionRole.EXPERIENCE, + CvKind.ENTRIES_DATED) + .item(CvItem.of("Ведущий инженер").at("Acme GmbH") + .period("2021 - 2025").paragraphs("Payments.")) + .build()) + .section(ModuleSection.builder("Образование", SectionRole.EDUCATION, + CvKind.ENTRIES_DATED) + .item(CvItem.of("Информатика").at("МГУ").period("2014 - 2018")) + .build()) + .build(); + } + + private static CvIdentity identity() { + return CvIdentity.builder() + .name("Jordan", "Rivera") + .jobTitle("Backend Engineer") + .contact("+1 555 0100", "jordan@example.com", "Berlin, DE") + .build(); + } + + /** + * Every string the composed layout carries. Read from the layout rather + * than the PDF text layer: the CV themes draw with the standard-14 + * Helvetica, which has no Cyrillic glyphs, and where the section was + * placed is what routing owes — the font is the caller's choice. + */ + private static String composedText(DocumentTemplate preset, CvDocument doc) { + try (DocumentSession session = GraphCompose.document() + .pageSize(DocumentPageSize.A4) + .margin(24, 24, 24, 24) + .create()) { + preset.compose(session, doc); + StringBuilder text = new StringBuilder(); + collectText(session.roots(), text); + return text.toString(); + } + } + + private static void collectText(List nodes, StringBuilder out) { + for (DocumentNode node : nodes) { + if (node instanceof ParagraphNode paragraph) { + out.append(paragraph.text()).append(' '); + } + collectText(node.children(), out); + } + } +} diff --git a/qa/src/test/java/com/demcha/compose/document/templates/cv/components/SectionAllocationTest.java b/qa/src/test/java/com/demcha/compose/document/templates/cv/components/SectionAllocationTest.java index fb0a999d8..7f7ab0f36 100644 --- a/qa/src/test/java/com/demcha/compose/document/templates/cv/components/SectionAllocationTest.java +++ b/qa/src/test/java/com/demcha/compose/document/templates/cv/components/SectionAllocationTest.java @@ -2,6 +2,10 @@ import com.demcha.compose.document.templates.cv.data.CvSection; import com.demcha.compose.document.templates.cv.data.EntriesSection; +import com.demcha.compose.document.templates.cv.data.ModuleSection; +import com.demcha.compose.document.templates.cv.data.SectionRole; +import com.demcha.compose.document.templates.cv.data.CvItem; +import com.demcha.compose.document.templates.cv.data.CvKind; import com.demcha.compose.document.templates.cv.data.ParagraphSection; import com.demcha.compose.document.templates.cv.data.RowStyle; import com.demcha.compose.document.templates.cv.data.RowsSection; @@ -130,4 +134,59 @@ void aMissingFallbackLabelIsARejectedArgument() { .isInstanceOf(NullPointerException.class) .hasMessageContaining("fallback"); } + + @Test + void aRoleClaimTakesTheModuleThatNamedTheRole() { + ModuleSection experience = ModuleSection.builder("Опыт работы", + SectionRole.EXPERIENCE, CvKind.ENTRIES_DATED) + .item(CvItem.of("Ведущий инженер").period("2021")) + .build(); + SectionAllocation allocation = SectionAllocation.of(List.of(SUMMARY, experience)); + + assertThat(allocation.claim(SectionRole.EXPERIENCE, List.of("experience"))) + .as("the heading matches no English keyword; the role is the answer") + .isSameAs(experience); + assertThat(allocation.remaining()) + .as("a role-claimed section is claimed, so it is not also a leftover") + .doesNotContain(experience); + } + + @Test + void aRoleClaimFallsBackToTheHeadingForSectionsWithoutARole() { + SectionAllocation allocation = SectionAllocation.of(List.of(SUMMARY)); + + assertThat(allocation.claim(SectionRole.SUMMARY, List.of("summary"))) + .as("hand-written sections carry no role and still route by heading") + .isSameAs(SUMMARY); + } + + @Test + void aDeclaredRoleIsNotClaimableByAnotherSlotsKeywords() { + // Otherwise the experience slot takes it by role and the projects slot + // takes it by heading, and the same module renders twice. + ModuleSection module = ModuleSection.builder("Projects", SectionRole.EXPERIENCE, + CvKind.ENTRIES_DATED) + .item(CvItem.of("Senior Engineer").period("2021")) + .build(); + SectionAllocation allocation = SectionAllocation.of(List.of(module)); + + assertThat(allocation.claim(SectionRole.PROJECTS, List.of("projects"))).isNull(); + assertThat(allocation.claim(SectionRole.EXPERIENCE, List.of("experience"))) + .isSameAs(module); + } + + @Test + void aRoleClaimsAtMostOneSectionSoASecondSlotSeesTheNextOne() { + ModuleSection first = ModuleSection.builder("Erfahrung", SectionRole.EXPERIENCE, + CvKind.ENTRIES_DATED).item(CvItem.of("First").period("2021")).build(); + ModuleSection second = ModuleSection.builder("Weitere Erfahrung", + SectionRole.EXPERIENCE, CvKind.ENTRIES_DATED) + .item(CvItem.of("Second").period("2019")).build(); + SectionAllocation allocation = SectionAllocation.of(List.of(first, second)); + + assertThat(allocation.claim(SectionRole.EXPERIENCE, List.of("experience"))).isSameAs(first); + assertThat(allocation.claim(SectionRole.EXPERIENCE, List.of("experience"))) + .as("claiming hands each section out once") + .isSameAs(second); + } } diff --git a/qa/src/test/java/com/demcha/compose/document/templates/cv/presets/MonogramSidebarPaginationTest.java b/qa/src/test/java/com/demcha/compose/document/templates/cv/presets/MonogramSidebarPaginationTest.java new file mode 100644 index 000000000..09aec5ff1 --- /dev/null +++ b/qa/src/test/java/com/demcha/compose/document/templates/cv/presets/MonogramSidebarPaginationTest.java @@ -0,0 +1,342 @@ +package com.demcha.compose.document.templates.cv.presets; + +import com.demcha.compose.GraphCompose; +import com.demcha.compose.document.api.DocumentPageSize; +import com.demcha.compose.document.api.DocumentSession; +import com.demcha.compose.document.layout.LayoutGraph; +import com.demcha.compose.document.layout.payloads.ParagraphFragmentPayload; +import com.demcha.compose.document.node.DocumentNode; +import com.demcha.compose.document.snapshot.LayoutNodeSnapshot; +import com.demcha.compose.document.snapshot.LayoutSnapshot; +import com.demcha.compose.document.style.DocumentInsets; +import com.demcha.compose.document.templates.cv.data.CvDocument; +import com.demcha.compose.document.templates.cv.data.CvIdentity; +import com.demcha.compose.document.templates.cv.data.CvSection; +import com.demcha.compose.document.templates.cv.data.EntriesSection; +import com.demcha.compose.document.templates.cv.data.ParagraphSection; +import com.demcha.compose.document.templates.cv.data.RowStyle; +import com.demcha.compose.document.templates.cv.data.RowsSection; +import com.demcha.compose.document.templates.core.page.ContinuationSafeArea; +import com.demcha.compose.document.templates.cv.data.SkillsSection; +import org.apache.pdfbox.Loader; +import org.apache.pdfbox.pdmodel.PDDocument; +import org.apache.pdfbox.text.PDFTextStripper; +import org.junit.jupiter.api.Test; + +import java.util.ArrayList; +import java.util.List; + +import static org.assertj.core.api.Assertions.assertThat; +import static org.assertj.core.api.Assertions.within; + +/** + * A CV denser than one page keeps every entry Monogram Sidebar was given, and the + * pages it needs. + * + *

The preset used to hold its body in one row. A row is atomic — it must fit + * the page it starts on — so the preset capped each block (two jobs, two degrees, + * seven skills, three projects, three additional rows) and dropped the rest + * without a word: the PDF looked finished and a reader had no way to know a job + * was never drawn. The body is a column flow now, so content that does not fit + * belongs on page two rather than in the bin.

+ * + *

The entry subtitle — the employer — is not asserted here because this preset + * draws position, date and description but never the subtitle. That omission and + * its fix live in their own change; this one is about what the caps and the atomic + * row cost.

+ */ +class MonogramSidebarPaginationTest { + + /** + * The floor a continuation page has to clear regardless of what the preset + * reserves — past the widest non-printable band in common consumer printers. + */ + private static final double PRINTER_SAFE_MINIMUM = 24.0; + + @Test + void everyEntryOfADenseCvSurvivesIntoThePdf() throws Exception { + String text = renderText(denseDocument()); + + assertThat(text) + .describedAs("sidebar: every degree, not the first two") + .contains("University of Manchester") + .contains("Imperial College London") + .contains("Open University") + .contains("University of Leeds"); + + assertThat(text) + .describedAs("sidebar: every skill, not the first seven") + .contains("Groovy", "Python", "SQL") + .contains("PDFBox", "PostScript", "ICC colour profiles", "font metrics") + .contains("JUnit 5", "AssertJ", "Pitest"); + + assertThat(text) + .describedAs("main column: every position, not the first two") + .contains("PRINCIPAL PLATFORM ENGINEER") + .contains("SENIOR BACKEND ENGINEER") + .contains("BACKEND ENGINEER") + .contains("SOFTWARE ENGINEER") + .contains("JUNIOR DEVELOPER"); + + assertThat(text) + .describedAs("main column: every project, not the first three") + .contains("GraphCompose") + .contains("Ledger Sync") + .contains("Field Atlas") + .contains("Harbour Watch"); + + assertThat(text) + .describedAs("main column: every additional row, not the first three") + .contains("Languages") + .contains("Work Eligibility") + .contains("Open Source") + .contains("Speaking"); + } + + @Test + void aDenseCvPaginatesInsteadOfOverflowing() throws Exception { + LayoutSnapshot snapshot = layoutOf(denseDocument()); + + assertThat(snapshot.totalPages()) + .describedAs("the fixture outgrows one page; a row would have thrown " + + "here rather than opened a second one") + .isGreaterThan(1); + // Only the sidebar outgrows page one on this fixture — the main column + // finishes on it — which is the point of a column flow: each column takes + // the pages it needs, and neither waits for the other. + assertThat(lastPageOf(snapshot, "CvV2MonogramSidebarSidebar")) + .describedAs("the sidebar continues past the first page") + .isGreaterThan(0); + assertThat(lastPageOf(snapshot, "CvV2MonogramSidebarMain")) + .describedAs("while the main column finishes on the first — every " + + "column of a flow opens on the same page, so only where it " + + "ends says anything") + .isZero(); + } + + @Test + void theColumnsStaySideBySide() throws Exception { + LayoutSnapshot snapshot = layoutOf(denseDocument()); + LayoutNodeSnapshot sidebar = column(snapshot, "CvV2MonogramSidebarSidebar"); + LayoutNodeSnapshot main = column(snapshot, "CvV2MonogramSidebarMain"); + + assertThat(sidebar.placementX()) + .describedAs("the sidebar is the left column") + .isLessThan(main.placementX()); + assertThat(sidebar.startPage()) + .describedAs("and both columns open on the same page") + .isEqualTo(main.startPage()); + } + + @Test + void aContinuationPageKeepsItsFirstLineOffTheTrimmedEdge() throws Exception { + // RECOMMENDED_MARGIN is 0 so the sidebar fill reaches the paper edge, and + // the columns' padding is an edge of the columns rather than of each page. + try (DocumentSession session = newSession()) { + MonogramSidebar.create().compose(session, denseDocument()); + LayoutGraph graph = session.layoutGraph(); + double pageHeight = session.canvas().height(); + + assertThat(graph.totalPages()).isGreaterThan(1); + for (int page = 1; page < graph.totalPages(); page++) { + double gap = firstLineTopGap(graph, pageHeight, page); + // Two floors. The literal is the requirement and does not move when + // the preset changes its mind; the constant is what the preset + // actually asks for, so reserving less than it advertises is named + // as that rather than passing silently. + assertThat(gap) + .describedAs("page %d clears the widest common non-printable band", + page + 1) + .isGreaterThanOrEqualTo(PRINTER_SAFE_MINIMUM); + assertThat(gap) + .describedAs("page %d gets the inset the preset asks for", page + 1) + .isGreaterThanOrEqualTo(ContinuationSafeArea.PRINTER_SAFE_TOP); + } + } + + // The same document with the preset's rule taken back off, so the number + // above is attributable to the rule rather than to whatever else happened to + // sit at the top of the page. + try (DocumentSession session = newSession()) { + MonogramSidebar.create().compose(session, denseDocument()); + session.pageMargins(List.of()); + LayoutGraph graph = session.layoutGraph(); + + assertThat(firstLineTopGap(graph, session.canvas().height(), 1)) + .describedAs("without the rule the first line lands on the trimmed edge") + .isLessThan(PRINTER_SAFE_MINIMUM); + } + } + + @Test + void theFirstPageKeepsTheTopEdgeItsOwnDesignGaveIt() throws Exception { + // A safe area applied to every page rather than to the continuations would + // push the monogram badge and the whole first page down with it. + try (DocumentSession session = newSession()) { + MonogramSidebar.create().compose(session, denseDocument()); + double withRule = firstLineTopGap( + session.layoutGraph(), session.canvas().height(), 0); + + session.pageMargins(List.of()); + double withoutRule = firstLineTopGap( + session.layoutGraph(), session.canvas().height(), 0); + + assertThat(withRule) + .describedAs("page one is laid out identically either way") + .isCloseTo(withoutRule, within(0.01)); + } + } + + @Test + void everySectionHeadingIsBoundToTheBlockItIntroduces() { + // Once a column breaks at all, a heading can close a page with its list + // overleaf, or be parted from its own rule — neither of which an atomic row + // could do. Asserted on the tree rather than on a rendered page because a + // fixture that happens to break at a heading is a coincidence, and one that + // stops breaking there would take the guard with it. The pagination + // behaviour of the flag itself is the engine's own SectionKeepWithNextTest. + try (DocumentSession session = newSession()) { + MonogramSidebar.create().compose(session, denseDocument()); + + List headings = new ArrayList<>(); + collectHeadings(session.roots(), headings); + + assertThat(headings) + .describedAs("both columns draw headings, and each is its own group") + .hasSizeGreaterThanOrEqualTo(2); + assertThat(headings) + .allSatisfy(heading -> assertThat(heading.keepWithNext()) + .describedAs("heading '%s' is kept with its block", + heading.name()) + .isTrue()); + } + } + + // -- helpers ----------------------------------------------------------- + + private static void collectHeadings(List nodes, List sink) { + for (DocumentNode node : nodes) { + if (node.name() != null && node.name().endsWith("Heading")) { + sink.add(node); + } + collectHeadings(node.children(), sink); + } + } + + private static LayoutNodeSnapshot column(LayoutSnapshot snapshot, String name) { + return snapshot.nodes().stream() + .filter(node -> name.equals(node.entityName())) + .findFirst() + .orElseThrow(() -> new AssertionError("no column named " + name)); + } + + private static int lastPageOf(LayoutSnapshot snapshot, String columnName) { + return column(snapshot, columnName).endPage(); + } + + private static double firstLineTopGap(LayoutGraph graph, double pageHeight, int pageIndex) { + return graph.fragments().stream() + .filter(fragment -> fragment.pageIndex() == pageIndex) + .filter(fragment -> fragment.payload() instanceof ParagraphFragmentPayload) + .mapToDouble(fragment -> pageHeight - (fragment.y() + fragment.height())) + .min() + .orElseThrow(() -> new AssertionError("no text on page " + (pageIndex + 1))); + } + + private static String renderText(CvDocument doc) throws Exception { + byte[] pdf; + try (DocumentSession session = newSession()) { + MonogramSidebar.create().compose(session, doc); + pdf = session.toPdfBytes(); + } + try (PDDocument document = Loader.loadPDF(pdf)) { + // Collapsed, so an item that reached the page but wrapped still counts. + // (PDFBox's Latin GSUB also eats "ti" in the text layer, which is why no + // assertion here spans that pair.) + return new PDFTextStripper().getText(document).replaceAll("\\s+", " "); + } + } + + private static LayoutSnapshot layoutOf(CvDocument doc) throws Exception { + try (DocumentSession session = newSession()) { + MonogramSidebar.create().compose(session, doc); + return session.layoutSnapshot(); + } + } + + private static DocumentSession newSession() { + return GraphCompose.document() + .pageSize(DocumentPageSize.A4) + .margin(DocumentInsets.of(MonogramSidebar.RECOMMENDED_MARGIN)) + .create(); + } + + /** A career denser than one page: five jobs, four degrees, a dozen skills. */ + private static CvDocument denseDocument() { + List sections = new ArrayList<>(); + sections.add(new ParagraphSection("Professional Summary", + "Platform engineer building document-generation pipelines, layout " + + "engines, and developer-facing template systems.")); + + sections.add(SkillsSection.builder("Expertise") + .group("Languages", "Java 21", "Kotlin", "Groovy", "Python", "SQL") + .group("Document & Print", "PDFBox", "PostScript", + "ICC colour profiles", "font metrics") + .group("Testing", "JUnit 5", "AssertJ", "Pitest") + .build()); + + sections.add(EntriesSection.builder("Education & Certifications") + .entry("MSc Computer Science", "University of Manchester", + "2019-2021", "Distinction.") + .entry("BSc Software Engineering", "Imperial College London", + "2015-2019", "First-class honours.") + .entry("Oracle Java Certification", "Open University", + "2023-2024", "Java 17 platform deep-dive.") + .entry("BSc Hydraulic Engineering", "University of Leeds", + "2011-2015", "Fluid dynamics and structural analysis.") + .build()); + + EntriesSection.Builder experience = + EntriesSection.builder("Professional Experience"); + experience.entry("Principal Platform Engineer", "Acme Rendering", + "2022-present", "Owns the rendering pipeline and its release train."); + experience.entry("Senior Backend Engineer", "Northwind Data", + "2020-2022", "Built the typed reporting layer."); + experience.entry("Backend Engineer", "Helios Print", + "2018-2020", "Migrated the print queue off cron scripts."); + experience.entry("Software Engineer", "Meridian Labs", + "2016-2018", "Instrumented the batch exporters."); + experience.entry("Junior Developer", "Nikoplast", + "2015-2016", "Maintained the intranet document tooling."); + sections.add(experience.build()); + + sections.add(RowsSection.builder("Projects", RowStyle.BULLETED_STACKED) + .row("GraphCompose (Java 21, PDFBox)", + "Declarative Java PDF layout engine.") + .row("Ledger Sync (Kotlin, Postgres)", + "Reconciles billing ledgers across three regions.") + .row("Field Atlas (Java, MapLibre)", + "Offline survey maps for field crews.") + .row("Harbour Watch (Java, Kafka)", + "Streams berth telemetry into an operations dashboard.") + .build()); + + sections.add(RowsSection.builder("Additional Information", RowStyle.PLAIN) + .row("Languages", "English (Fluent), German (Intermediate)") + .row("Work Eligibility", "Eligible to work in the UK and the EU") + .row("Open Source", "Maintainer of GraphCompose") + .row("Speaking", "JVM Summit 2024, Devoxx UK 2025") + .build()); + + return CvDocument.builder() + .identity(CvIdentity.builder() + .name("Jordan", "Rivera") + .jobTitle("Platform Engineer") + .contact("+44 20 5555 1000", "jordan@example.com", "London, UK") + .link("LinkedIn", "https://linkedin.com/in/jordan-rivera-demo") + .link("GitHub", "https://github.com/jrivera-demo") + .build()) + .sections(sections.toArray(new CvSection[0])) + .build(); + } +} diff --git a/qa/src/test/java/com/demcha/compose/document/templates/cv/presets/SidebarPortraitContentFidelityTest.java b/qa/src/test/java/com/demcha/compose/document/templates/cv/presets/SidebarPortraitContentFidelityTest.java new file mode 100644 index 000000000..70859bd64 --- /dev/null +++ b/qa/src/test/java/com/demcha/compose/document/templates/cv/presets/SidebarPortraitContentFidelityTest.java @@ -0,0 +1,325 @@ +package com.demcha.compose.document.templates.cv.presets; + +import com.demcha.compose.GraphCompose; +import com.demcha.compose.document.api.DocumentPageSize; +import com.demcha.compose.document.api.DocumentSession; +import com.demcha.compose.document.layout.LayoutGraph; +import com.demcha.compose.document.layout.payloads.ParagraphFragmentPayload; +import com.demcha.compose.document.snapshot.LayoutNodeSnapshot; +import com.demcha.compose.document.snapshot.LayoutSnapshot; +import com.demcha.compose.document.style.DocumentInsets; +import com.demcha.compose.document.templates.cv.data.CvDocument; +import com.demcha.compose.document.templates.cv.data.CvIdentity; +import com.demcha.compose.document.templates.cv.data.CvSection; +import com.demcha.compose.document.templates.cv.data.EntriesSection; +import com.demcha.compose.document.templates.cv.data.ParagraphSection; +import com.demcha.compose.document.templates.cv.data.RowStyle; +import com.demcha.compose.document.templates.cv.data.RowsSection; +import com.demcha.compose.document.templates.cv.data.SkillsSection; +import org.apache.pdfbox.Loader; +import org.apache.pdfbox.pdmodel.PDDocument; +import org.apache.pdfbox.text.PDFTextStripper; +import org.junit.jupiter.api.Test; + +import java.util.ArrayList; +import java.util.List; + +import static org.assertj.core.api.Assertions.assertThat; + +/** + * A CV rendered through Sidebar Portrait keeps every entry it was given. + * + *

The preset used to hold its body in one row. A row is atomic — it must + * fit the page it starts on — so the preset capped each block (two jobs, two + * degrees, five skills, three languages, two projects) and dropped the rest + * without a word: the PDF looked finished and a reader had no way to know a + * job was never drawn. The body is a column flow now, so the content that + * does not fit belongs on page two rather than in the bin.

+ * + *

Every assertion below names an item the old caps dropped first, in both + * columns, so a cap reintroduced anywhere fails here rather than shipping.

+ */ +class SidebarPortraitContentFidelityTest { + + /** + * The floor a continuation page has to clear regardless of what the preset + * chooses to reserve — roughly 8.5mm, past the widest non-printable band in + * common consumer printers. Stated here as a literal so the guard measures the + * requirement rather than the preset's own constant. + */ + private static final double PRINTER_SAFE_MINIMUM = 24.0; + + @Test + void everyEntryOfADenseCvSurvivesIntoThePdf() throws Exception { + String text = renderText(denseDocument()); + + assertThat(text) + .describedAs("sidebar: every degree, not the first two") + .contains("University of Manchester") + .contains("Imperial College London") + .contains("Open University") + .contains("University of Leeds"); + + assertThat(text) + .describedAs("sidebar: every skill, not the first five") + .contains("Java 21", "Kotlin", "Groovy", "Python", "SQL") + .contains("PDFBox", "PostScript", "ICC colour profiles", "font metrics") + .contains("JUnit 5", "AssertJ", "Pitest"); + + assertThat(text) + .describedAs("sidebar: every language, not the first three") + .contains("ENGLISH", "GERMAN", "FRENCH", "UKRAINIAN", "SPANISH"); + + assertThat(text) + .describedAs("main column: every employer, not the first two") + .contains("Acme Rendering") + .contains("Northwind Data") + .contains("Helios Print") + .contains("Meridian Labs") + .contains("Nikoplast"); + + assertThat(text) + .describedAs("main column: every project, not the first two") + .contains("GraphCompose") + .contains("Ledger Sync") + .contains("Field Atlas"); + } + + @Test + void aDenseCvPaginatesInsteadOfOverflowing() throws Exception { + LayoutSnapshot snapshot = layoutOf(denseDocument()); + + assertThat(snapshot.totalPages()) + .describedAs("the fixture outgrows one page; a row would have " + + "thrown here rather than opened a second one") + .isGreaterThan(1); + + // Both columns have to reach the later pages. A flow that carried only + // the main column over would leave the sidebar's tail behind — the same + // silent loss the caps used to cause, one layer down. The column node's + // own endPage says it directly, without depending on where a child + // happens to start. + assertThat(lastPageOf(snapshot, "CvV2SidebarPortraitSidebar")) + .describedAs("the sidebar continues past the first page") + .isGreaterThan(0); + assertThat(lastPageOf(snapshot, "CvV2SidebarPortraitMain")) + .describedAs("the main column continues past the first page") + .isGreaterThan(0); + } + + @Test + void theColumnsStaySideBySide() throws Exception { + // Stacking the columns instead of placing them beside each other would + // satisfy every assertion above; only geometry rules it out. + LayoutSnapshot snapshot = layoutOf(denseDocument()); + LayoutNodeSnapshot sidebar = column(snapshot, "CvV2SidebarPortraitSidebar"); + LayoutNodeSnapshot main = column(snapshot, "CvV2SidebarPortraitMain"); + + assertThat(sidebar.placementX()) + .describedAs("the sidebar is the left column") + .isLessThan(main.placementX()); + assertThat(sidebar.startPage()) + .describedAs("and both columns open on the same page") + .isEqualTo(main.startPage()); + } + + @Test + void aContinuationPageKeepsItsFirstLineOffTheTrimmedEdge() throws Exception { + // RECOMMENDED_MARGIN is 0 so the sidebar fill reaches the paper edge, and + // the columns' padding is an edge of the columns rather than of each page: + // it holds page one's content down and says nothing about page two's. The + // preset asks for a page-margin rule to cover the difference; this is the + // measurement that says it arrived. + try (DocumentSession session = newSession()) { + SidebarPortrait.create().compose(session, denseDocument()); + LayoutGraph graph = session.layoutGraph(); + double pageHeight = session.canvas().height(); + + assertThat(graph.totalPages()) + .describedAs("the fixture has to reach a second page for this to mean anything") + .isGreaterThan(1); + for (int page = 1; page < graph.totalPages(); page++) { + double gap = firstLineTopGap(graph, pageHeight, page); + // Two floors, deliberately. The literal is the requirement — it + // does not move when the preset's constant does, so lowering + // CONTINUATION_TOP_SAFE_AREA to zero fails here rather than + // quietly turning this assertion into `>= 0`. The constant is the + // preset's advertised promise, checked separately so a preset that + // reserves less than it documents is named as that. + assertThat(gap) + .describedAs("page %d clears the widest common non-printable band", page + 1) + .isGreaterThanOrEqualTo(PRINTER_SAFE_MINIMUM); + assertThat(gap) + .describedAs("page %d gets the inset the preset advertises", page + 1) + .isGreaterThanOrEqualTo(SidebarPortrait.CONTINUATION_TOP_SAFE_AREA); + } + } + + // The same document with the preset's rule taken back off, so the number + // above is attributed to the rule and not to whatever else is on the page. + // A preset that stopped asking for the safe area fails the loop above; a + // preset whose padding silently started covering it fails here. + try (DocumentSession session = newSession()) { + SidebarPortrait.create().compose(session, denseDocument()); + session.pageMargins(List.of()); + LayoutGraph graph = session.layoutGraph(); + + assertThat(firstLineTopGap(graph, session.canvas().height(), 1)) + .describedAs("without the rule the first line lands on the trimmed edge") + .isLessThan(6.0); + } + } + + @Test + void theFirstPageKeepsTheTopEdgeItsOwnDesignGaveIt() throws Exception { + // A safe area applied to every page rather than to the continuations would + // push the portrait, the hero strip and the whole first page down with it. + try (DocumentSession session = newSession()) { + SidebarPortrait.create().compose(session, denseDocument()); + double withRule = firstLineTopGap( + session.layoutGraph(), session.canvas().height(), 0); + + session.pageMargins(List.of()); + double withoutRule = firstLineTopGap( + session.layoutGraph(), session.canvas().height(), 0); + + assertThat(withRule) + .describedAs("page one is laid out identically either way") + .isCloseTo(withoutRule, org.assertj.core.data.Offset.offset(0.01)); + // Pinned as a number too: comparing the two runs alone would pass just + // as well if the preset had stopped asking for a safe area at all. The + // hero strip's 59pt top margin plus its 19pt padding is what puts the + // first glyph here, and no page rule may move it. + assertThat(withRule) + .describedAs("and it is the hero strip's own top edge, 59 + 19") + .isCloseTo(78.0, org.assertj.core.data.Offset.offset(0.5)); + } + } + + // -- helpers ----------------------------------------------------------- + + /** + * Distance from the trimmed top edge to the top of the highest line of text on + * a page. Measured on text fragments rather than placed nodes: a paragraph that + * broke across the page boundary belongs to a node that started on the previous + * page, and it is exactly that line the reader sees at the top of this one. + */ + private static double firstLineTopGap(LayoutGraph graph, double pageHeight, int pageIndex) { + return graph.fragments().stream() + .filter(fragment -> fragment.pageIndex() == pageIndex) + .filter(fragment -> fragment.payload() instanceof ParagraphFragmentPayload) + .mapToDouble(fragment -> pageHeight - (fragment.y() + fragment.height())) + .min() + .orElseThrow(() -> new AssertionError("no text on page " + (pageIndex + 1))); + } + + private static LayoutNodeSnapshot column(LayoutSnapshot snapshot, String name) { + return snapshot.nodes().stream() + .filter(node -> name.equals(node.entityName())) + .findFirst() + .orElseThrow(() -> new AssertionError("no column named " + name)); + } + + private static int lastPageOf(LayoutSnapshot snapshot, String columnName) { + return column(snapshot, columnName).endPage(); + } + + private static String renderText(CvDocument doc) throws Exception { + byte[] pdf; + try (DocumentSession session = newSession()) { + SidebarPortrait.create().compose(session, doc); + pdf = session.toPdfBytes(); + } + try (PDDocument document = Loader.loadPDF(pdf)) { + // Collapse wrapping the way the sibling fidelity test does: an item + // that reached the page but broke across two lines is present, and + // an assertion that failed on the line break would be reporting the + // wrong thing. (PDFBox's Latin GSUB also eats "ti" in the text + // layer, which is why no assertion here spans that pair.) + return new PDFTextStripper().getText(document).replaceAll("\\s+", " "); + } + } + + private static LayoutSnapshot layoutOf(CvDocument doc) throws Exception { + try (DocumentSession session = newSession()) { + SidebarPortrait.create().compose(session, doc); + return session.layoutSnapshot(); + } + } + + private static DocumentSession newSession() { + return GraphCompose.document() + .pageSize(DocumentPageSize.A4) + .margin(DocumentInsets.of(SidebarPortrait.RECOMMENDED_MARGIN)) + .create(); + } + + /** + * A career denser than any one page: five jobs, four degrees, a dozen + * skills, five languages, three projects. Every block reaches past the + * cap that used to truncate it. + */ + private static CvDocument denseDocument() { + List sections = new ArrayList<>(); + sections.add(new ParagraphSection("Professional Summary", + "Platform engineer building document-generation pipelines, " + + "layout engines, and developer-facing template systems.")); + + sections.add(SkillsSection.builder("Technical Skills") + .group("Languages", "Java 21", "Kotlin", "Groovy", "Python", "SQL") + .group("Document & Print", "PDFBox", "PostScript", + "ICC colour profiles", "font metrics") + .group("Testing", "JUnit 5", "AssertJ", "Pitest") + .build()); + + sections.add(EntriesSection.builder("Education & Certifications") + .entry("MSc Computer Science", "University of Manchester", + "2019-2021", "Distinction.") + .entry("BSc Software Engineering", "Imperial College London", + "2015-2019", "First-class honours.") + .entry("Oracle Java Certification", "Open University", + "2023-2024", "Java 17 platform deep-dive.") + .entry("BSc Hydraulic Engineering", "University of Leeds", + "2011-2015", "Fluid dynamics and structural analysis.") + .build()); + + sections.add(RowsSection.builder("Languages", RowStyle.PLAIN) + .row("Languages", "English (native), German (B2), French (B1), " + + "Ukrainian (C1), Spanish (A2)") + .build()); + + EntriesSection.Builder experience = + EntriesSection.builder("Professional Experience"); + experience.entry("Principal Platform Engineer", "Acme Rendering", + "2022-present", "Owns the rendering pipeline and its release train."); + experience.entry("Senior Backend Engineer", "Northwind Data", + "2020-2022", "Built the typed reporting layer."); + experience.entry("Backend Engineer", "Helios Print", + "2018-2020", "Migrated the print queue off cron scripts."); + experience.entry("Software Engineer", "Meridian Labs", + "2016-2018", "Instrumented the batch exporters."); + experience.entry("Junior Developer", "Nikoplast", + "2015-2016", "Maintained the intranet document tooling."); + sections.add(experience.build()); + + sections.add(RowsSection.builder("Projects", RowStyle.BULLETED_STACKED) + .row("GraphCompose (Java 21, PDFBox)", + "Declarative Java PDF layout engine.") + .row("Ledger Sync (Kotlin, Postgres)", + "Reconciles billing ledgers across three regions.") + .row("Field Atlas (Java, MapLibre)", + "Offline survey maps for field crews.") + .build()); + + return CvDocument.builder() + .identity(CvIdentity.builder() + .name("Jordan", "Rivera") + .jobTitle("Platform Engineer") + .contact("+44 20 5555 1000", "jordan@example.com", "London, UK") + .link("LinkedIn", "https://linkedin.com/in/jordan-rivera-demo") + .link("GitHub", "https://github.com/jrivera-demo") + .build()) + .sections(sections.toArray(new CvSection[0])) + .build(); + } +} diff --git a/qa/src/test/resources/visual-baselines/cv-v2-layered/monogram_sidebar-page-0.png b/qa/src/test/resources/visual-baselines/cv-v2-layered/monogram_sidebar-page-0.png index ac1306204..875c7a2d3 100644 Binary files a/qa/src/test/resources/visual-baselines/cv-v2-layered/monogram_sidebar-page-0.png and b/qa/src/test/resources/visual-baselines/cv-v2-layered/monogram_sidebar-page-0.png differ diff --git a/qa/src/test/resources/visual-baselines/cv-v2-layered/monogram_sidebar-page-1.png b/qa/src/test/resources/visual-baselines/cv-v2-layered/monogram_sidebar-page-1.png new file mode 100644 index 000000000..5fa0b916b Binary files /dev/null and b/qa/src/test/resources/visual-baselines/cv-v2-layered/monogram_sidebar-page-1.png differ diff --git a/qa/src/test/resources/visual-baselines/cv-v2-layered/sidebar_portrait-page-0.png b/qa/src/test/resources/visual-baselines/cv-v2-layered/sidebar_portrait-page-0.png index f6f426f92..dfc626ff8 100644 Binary files a/qa/src/test/resources/visual-baselines/cv-v2-layered/sidebar_portrait-page-0.png and b/qa/src/test/resources/visual-baselines/cv-v2-layered/sidebar_portrait-page-0.png differ diff --git a/qa/src/test/resources/visual-baselines/cv-v2-layered/sidebar_portrait-page-1.png b/qa/src/test/resources/visual-baselines/cv-v2-layered/sidebar_portrait-page-1.png new file mode 100644 index 000000000..892cf7a90 Binary files /dev/null and b/qa/src/test/resources/visual-baselines/cv-v2-layered/sidebar_portrait-page-1.png differ diff --git a/render-docx/pom.xml b/render-docx/pom.xml index 06bf51427..535f40aac 100644 --- a/render-docx/pom.xml +++ b/render-docx/pom.xml @@ -19,7 +19,7 @@ --> io.github.demchaav graph-compose-render-docx - 2.2.1-SNAPSHOT + 2.3.0-SNAPSHOT GraphCompose Render — DOCX Semantic DOCX export backend for GraphCompose, backed by Apache POI. diff --git a/render-docx/src/main/java/com/demcha/compose/document/backend/semantic/docx/DocxSemanticBackend.java b/render-docx/src/main/java/com/demcha/compose/document/backend/semantic/docx/DocxSemanticBackend.java index edba51a18..8aa95b792 100644 --- a/render-docx/src/main/java/com/demcha/compose/document/backend/semantic/docx/DocxSemanticBackend.java +++ b/render-docx/src/main/java/com/demcha/compose/document/backend/semantic/docx/DocxSemanticBackend.java @@ -182,10 +182,13 @@ private void writeNode(XWPFDocument document, DocumentNode node) throws Exceptio writeList(document, list); } else if (node instanceof ContainerNode || node instanceof SectionNode || node instanceof com.demcha.compose.document.node.LayerStackNode - || node instanceof com.demcha.compose.document.node.CanvasLayerNode) { + || node instanceof com.demcha.compose.document.node.CanvasLayerNode + || node instanceof com.demcha.compose.document.node.ColumnFlowNode) { // Overlay/positioned wrappers have no DOCX analogue for their // geometry, but their children can be semantic (text, images) — - // render them sequentially rather than dropping the subtree. + // render them sequentially rather than dropping the subtree. A + // column flow lands here too: Word reflows its own columns, so the + // page-spanning geometry is meaningless there, but the text is not. for (DocumentNode child : node.children()) { writeNode(document, child); } diff --git a/render-pdf/pom.xml b/render-pdf/pom.xml index 97a4eb8e5..ebe0860b6 100644 --- a/render-pdf/pom.xml +++ b/render-pdf/pom.xml @@ -25,7 +25,7 @@ --> io.github.demchaav graph-compose-render-pdf - 2.2.1-SNAPSHOT + 2.3.0-SNAPSHOT GraphCompose Render — PDF The PDFBox-backed PDF render backend for GraphCompose. diff --git a/render-pptx/pom.xml b/render-pptx/pom.xml index f231910b0..e856b0a4a 100644 --- a/render-pptx/pom.xml +++ b/render-pptx/pom.xml @@ -19,7 +19,7 @@ --> io.github.demchaav graph-compose-render-pptx - 2.2.1-SNAPSHOT + 2.3.0-SNAPSHOT GraphCompose Render — PPTX PPTX render backends for GraphCompose: the coordinate-exact fixed-layout backend (POI XSLF) and the slide-safe semantic export skeleton. diff --git a/templates/pom.xml b/templates/pom.xml index bb95bf1ea..5c8822d6e 100644 --- a/templates/pom.xml +++ b/templates/pom.xml @@ -17,7 +17,7 @@ --> io.github.demchaav graph-compose-templates - 2.2.1-SNAPSHOT + 2.3.0-SNAPSHOT GraphCompose Templates Built-in CV, cover-letter, invoice, and proposal document templates for GraphCompose. diff --git a/templates/src/main/java/com/demcha/compose/document/templates/core/page/ContinuationSafeArea.java b/templates/src/main/java/com/demcha/compose/document/templates/core/page/ContinuationSafeArea.java new file mode 100644 index 000000000..4f2b90943 --- /dev/null +++ b/templates/src/main/java/com/demcha/compose/document/templates/core/page/ContinuationSafeArea.java @@ -0,0 +1,88 @@ +package com.demcha.compose.document.templates.core.page; + +import com.demcha.compose.document.api.DocumentSession; +import com.demcha.compose.document.api.PageMarginRule; +import com.demcha.compose.document.style.DocumentInsets; + +import java.util.List; +import java.util.Objects; + +/** + * Keeps a full-bleed template's content off the trimmed edge on the pages its body + * continues onto. + * + *

A container's padding is an edge of the container: it is reserved once, at the + * top of the page the container opens on and the bottom of the page it closes on. + * The page margin is the inset applied once per page. In an ordinary + * document the distinction never surfaces, because the margin is already holding + * content off the paper edge everywhere. It surfaces in a full-bleed template, which + * sets the page margin to zero so a page background can reach the paper edge — and + * thereby gives up the safe area on all four sides when only the two horizontal ones + * had to go. A body that runs past its first page then resumes wherever the break + * left it, which can be a couple of points from the edge.

+ * + *

{@link #applyTo(DocumentSession, int, double)} raises the top margin from a + * given page onward and keeps the other three edges of whatever margin the caller + * chose, so the layout stays full-bleed horizontally and page backgrounds — which + * are ratios of the page, not of the content box — keep bleeding on every page.

+ * + *

This lives in {@code templates} rather than in the engine because the rule it + * writes is a design decision — which page, which edge, how much — over a per-page + * margin mechanism the engine already exposes. A template that wants a different + * shape writes its own {@link PageMarginRule}.

+ * + * @author Artem Demchyshyn + * @since 2.3.0 + */ +public final class ContinuationSafeArea { + + /** + * Half an inch — the safe area every common consumer printer's non-printable + * band fits inside. A template is free to ask for more or less; this is the + * number to reach for when there is no reason to pick another. + */ + public static final double PRINTER_SAFE_TOP = 36.0; + + private ContinuationSafeArea() { + } + + /** + * Reserves {@code topSafeArea} at the top of every page from + * {@code firstContinuationPage} onward, leaving the pages before it alone. + * + *

Does nothing at all when the document margin already provides the safe + * area, so a template can call this unconditionally: a document that does not + * need per-page geometry is not given any, and any rules the caller set + * themselves survive untouched. When it does apply, it replaces + * the session's page-margin rules — {@link DocumentSession#pageMargins(List)} has + * no additive form — so a template that also wants rules of its own has to write + * them together rather than call this as well.

+ * + * @param document the session to configure + * @param firstContinuationPage 1-based number of the first page to inset — the + * page after the one the body starts on + * @param topSafeArea top inset in points; see {@link #PRINTER_SAFE_TOP} + * @throws IllegalArgumentException if {@code firstContinuationPage} is below 2, + * or {@code topSafeArea} is negative or not finite + */ + public static void applyTo(DocumentSession document, + int firstContinuationPage, + double topSafeArea) { + Objects.requireNonNull(document, "document"); + if (firstContinuationPage < 2) { + throw new IllegalArgumentException( + "firstContinuationPage must be 2 or greater — page 1 is where a body starts, " + + "and its own design owns its top edge. Was " + firstContinuationPage); + } + if (!Double.isFinite(topSafeArea) || topSafeArea < 0.0) { + throw new IllegalArgumentException( + "topSafeArea must be a finite, non-negative value but was " + topSafeArea); + } + DocumentInsets margin = document.margin(); + if (margin.top() >= topSafeArea) { + return; + } + document.pageMargins(List.of(PageMarginRule.from(firstContinuationPage, + new DocumentInsets(topSafeArea, margin.right(), margin.bottom(), margin.left())))); + } +} diff --git a/templates/src/main/java/com/demcha/compose/document/templates/cv/api/ModularCvTemplate.java b/templates/src/main/java/com/demcha/compose/document/templates/cv/api/ModularCvTemplate.java new file mode 100644 index 000000000..8d25a9f62 --- /dev/null +++ b/templates/src/main/java/com/demcha/compose/document/templates/cv/api/ModularCvTemplate.java @@ -0,0 +1,59 @@ +package com.demcha.compose.document.templates.cv.api; + +import com.demcha.compose.document.templates.api.DocumentTemplate; +import com.demcha.compose.document.templates.cv.components.CvRenderKit; +import com.demcha.compose.document.templates.cv.data.CvDocument; +import com.demcha.compose.document.templates.cv.data.CvKind; +import com.demcha.compose.document.templates.cv.data.ModuleSection; +import com.demcha.compose.document.templates.cv.data.Slot; + +/** + * A CV template that renders every section placed in {@link Slot#MAIN} — + * every {@link CvKind}, under whatever heading the author wrote. + * + *

The promise is exactly that, and the slot is part of it. + * Every shipped preset composes a single main column and reads + * {@code sectionsIn(Slot.MAIN)}; a section placed in {@link Slot#SIDEBAR} or + * {@link Slot#FOOTER} is dropped, by these templates as by every other, which + * is the behaviour {@link com.demcha.compose.document.templates.cv.data.CvDocument} + * has always documented. Saying so here rather than leaving "whatever the + * document hands it" to be read generously is the difference between a + * contract and a slogan — a caller assembling a CV at runtime needs to know + * that placing a module in a sidebar loses it today.

+ * + *

This is the promise a CV assembled at runtime needs, and it is not one + * every preset can make. Several place their sections into fixed slots and + * guard each slot on the section's Java type, so a module routed to one is + * skipped rather than drawn; the CV still renders, minus a section, and + * looks finished. That failure is invisible from the outside, which is why + * the capability is declared in the type system rather than assumed: a + * constructor asks {@link com.demcha.compose.document.templates.cv.presets.CvTemplates#modular()} + * for the templates it may offer, and the rest stay available to callers + * who build the canonical sections by hand.

+ * + *

Declaring it is not enough to have it. {@code ModularCvTemplateFidelityTest} + * enumerates the implementations and renders a document carrying every kind, + * a section this catalogue has no name for, a heading in a script no keyword + * list contains, and a heading that does match a keyword list — the + * last because a preset with an editorial vocabulary of its own is the one + * likely to rename what the author wrote. Each item must reach the page, so + * the interface cannot be worn by a template that would drop or retitle + * one.

+ * + *

{@link #kit()} is how the promise stays compatible with a preset's own + * look: the shared lowering turns a {@link ModuleSection} into paragraphs, + * rows, and entries, and the kit draws them the way this template draws + * everything else.

+ * + * @since 2.3.0 + */ +public interface ModularCvTemplate extends DocumentTemplate { + + /** + * How this template draws the shapes a module lowers to. + * + * @return this template's kit; {@link CvRenderKit#defaults()} for a + * template whose modules look like the canonical components + */ + CvRenderKit kit(); +} diff --git a/templates/src/main/java/com/demcha/compose/document/templates/cv/components/CvRenderKit.java b/templates/src/main/java/com/demcha/compose/document/templates/cv/components/CvRenderKit.java new file mode 100644 index 000000000..5391265ef --- /dev/null +++ b/templates/src/main/java/com/demcha/compose/document/templates/cv/components/CvRenderKit.java @@ -0,0 +1,94 @@ +package com.demcha.compose.document.templates.cv.components; + +import com.demcha.compose.document.dsl.SectionBuilder; +import com.demcha.compose.document.templates.core.theme.BrandTheme; +import com.demcha.compose.document.templates.cv.data.CvEntry; +import com.demcha.compose.document.templates.cv.data.CvItem; +import com.demcha.compose.document.templates.cv.data.CvKind; +import com.demcha.compose.document.templates.cv.data.CvRow; +import com.demcha.compose.document.templates.cv.data.RowStyle; + +/** + * How one template draws the three shapes a CV section body reduces to: + * a paragraph of prose, a label/value row, a timeline entry. + * + *

A preset that wants runtime {@code ModuleSection}s to look like the + * rest of its own document implements this and hands it back through + * {@link com.demcha.compose.document.templates.cv.api.ModularCvTemplate}; + * {@link #defaults()} draws them the canonical way, and every method has a + * default, so a preset overrides only the shapes it actually styles + * differently.

+ * + *

Why the primitives and not the kinds. The obvious + * alternative is a function per {@link CvKind}. It puts the wrong work on + * the preset: turning a {@link CvItem} into an entry or a row means + * deciding what a linked title looks like, how a subtitle and a location + * join, which fields the kind ignores, what an empty description does to a + * trailing colon — rules that belong to the model and must not be + * re-decided sixteen times. {@link ModuleRenderer} keeps that lowering and + * asks the kit only to draw what came out of it, which is exactly the part + * a preset has an opinion about. It is also the shape the presets already + * have: their private renderers take a {@code CvEntry} or a {@code CvRow} + * today.

+ * + *

Implementations draw into the host and return; they do not set the + * host's spacing or padding, which the caller has already settled, and + * they do not insert separators between items — {@code ModuleRenderer} + * owns the gaps so that spacing stays uniform whoever is drawing.

+ * + * @since 2.3.0 + */ +public interface CvRenderKit { + + /** + * The canonical kit: every shape drawn by the shared components, which + * is what a section rendered through + * {@link SectionDispatcher#renderBody(SectionBuilder, com.demcha.compose.document.templates.cv.data.CvSection, BrandTheme)} + * has always produced. + * + * @return a kit that draws every shape the canonical way + */ + static CvRenderKit defaults() { + return DEFAULTS; + } + + /** The canonical kit. Stateless, so one instance serves every caller. */ + CvRenderKit DEFAULTS = new CvRenderKit() { + }; + + /** + * Draws one paragraph of prose. Blank text draws nothing. + * + * @param host host section receiving the paragraph + * @param text the prose; may carry inline markdown + * @param theme the active theme + */ + default void paragraph(SectionBuilder host, String text, BrandTheme theme) { + ParagraphRenderer.render(host, text, theme); + } + + /** + * Draws one label/value row with the given decoration. + * + * @param host host section receiving the row + * @param row label and body + * @param style plain, bulleted, or bulleted with the body stacked under + * the label + * @param theme the active theme + */ + default void row(SectionBuilder host, CvRow row, RowStyle style, BrandTheme theme) { + RowRenderer.render(host, row, style, theme); + } + + /** + * Draws one timeline entry. A blank {@code date} collapses the date + * column rather than reserving an empty one. + * + * @param host host section receiving the entry + * @param entry title, subtitle, date, and body + * @param theme the active theme + */ + default void entry(SectionBuilder host, CvEntry entry, BrandTheme theme) { + EntryRenderer.render(host, entry, theme); + } +} diff --git a/templates/src/main/java/com/demcha/compose/document/templates/cv/components/EntryRenderer.java b/templates/src/main/java/com/demcha/compose/document/templates/cv/components/EntryRenderer.java index 160302a03..f703bef09 100644 --- a/templates/src/main/java/com/demcha/compose/document/templates/cv/components/EntryRenderer.java +++ b/templates/src/main/java/com/demcha/compose/document/templates/cv/components/EntryRenderer.java @@ -44,28 +44,39 @@ public static void render(SectionBuilder section, CvEntry entry, BrandTheme them DocumentTextStyle subtitleStyle = theme.entrySubtitleStyle(); DocumentTextStyle bodyStyle = theme.bodyStyle(); - // -- title + date row ------------------------------------------- - // The two-column header is a row layout, not a paragraph, so it - // does not go through ParagraphPrimitive — its DSL shape is - // genuinely different. - section.addRow("CvV2EntryHeader", row -> row - .spacing(theme.spacing().entryHeaderRowSpacing()) - .weights(theme.spacing().entryTitleWeight(), - theme.spacing().entryDateWeight()) - .addSection("Title", titleColumn -> titleColumn - .padding(DocumentInsets.zero()) - .addParagraph(p -> p - .textStyle(titleStyle) - .align(TextAlign.LEFT) - .margin(DocumentInsets.zero()) - .rich(rich -> MarkdownInline.append(rich, entry.title(), titleStyle)))) - .addSection("Date", dateColumn -> dateColumn - .padding(DocumentInsets.zero()) - .addParagraph(p -> p - .text(entry.date()) - .textStyle(dateStyle) - .align(TextAlign.RIGHT) - .margin(DocumentInsets.zero())))); + // -- title (+ date) header -------------------------------------- + // With a date this is a two-column row, not a paragraph, so it does + // not go through ParagraphPrimitive — its DSL shape is genuinely + // different. Without one the row is dropped entirely rather than + // reserving an empty column: an undated entry — a certification, a + // project, anything a runtime module renders without dates — would + // otherwise have its title wrapped early to leave room for nothing. + if (entry.date().isBlank()) { + section.addParagraph(p -> p + .textStyle(titleStyle) + .align(TextAlign.LEFT) + .margin(DocumentInsets.zero()) + .rich(rich -> MarkdownInline.append(rich, entry.title(), titleStyle))); + } else { + section.addRow("CvV2EntryHeader", row -> row + .spacing(theme.spacing().entryHeaderRowSpacing()) + .weights(theme.spacing().entryTitleWeight(), + theme.spacing().entryDateWeight()) + .addSection("Title", titleColumn -> titleColumn + .padding(DocumentInsets.zero()) + .addParagraph(p -> p + .textStyle(titleStyle) + .align(TextAlign.LEFT) + .margin(DocumentInsets.zero()) + .rich(rich -> MarkdownInline.append(rich, entry.title(), titleStyle)))) + .addSection("Date", dateColumn -> dateColumn + .padding(DocumentInsets.zero()) + .addParagraph(p -> p + .text(entry.date()) + .textStyle(dateStyle) + .align(TextAlign.RIGHT) + .margin(DocumentInsets.zero())))); + } // -- italic subtitle -------------------------------------------- if (!entry.subtitle().isBlank()) { diff --git a/templates/src/main/java/com/demcha/compose/document/templates/cv/components/ModuleRenderer.java b/templates/src/main/java/com/demcha/compose/document/templates/cv/components/ModuleRenderer.java new file mode 100644 index 000000000..9d2a52726 --- /dev/null +++ b/templates/src/main/java/com/demcha/compose/document/templates/cv/components/ModuleRenderer.java @@ -0,0 +1,230 @@ +package com.demcha.compose.document.templates.cv.components; + +import com.demcha.compose.document.dsl.SectionBuilder; +import com.demcha.compose.document.style.DocumentInsets; +import com.demcha.compose.document.style.DocumentTextStyle; +import com.demcha.compose.document.templates.core.theme.BrandTheme; +import com.demcha.compose.document.templates.cv.data.BodyStyle; +import com.demcha.compose.document.templates.cv.data.CvEntry; +import com.demcha.compose.document.templates.cv.data.CvItem; +import com.demcha.compose.document.templates.cv.data.CvRow; +import com.demcha.compose.document.templates.cv.data.ModuleSection; +import com.demcha.compose.document.templates.cv.data.RowStyle; + +import java.util.List; + +/** + * Renders a {@link ModuleSection} by lowering it onto the renderers + * this package already ships. + * + *

Nothing here draws. Each {@code CvKind} is a rule for turning + * {@link CvItem}s into the inputs {@link ParagraphRenderer}, + * {@link RowRenderer} and {@link EntryRenderer} already take, which is + * what makes a runtime-assembled module and a hand-written + * {@code EntriesSection} carrying the same content lay out the same + * way — a property the parity suite checks node for node rather than + * by eye.

+ * + *

The lowering is also where a kind's documented indifference + * happens: {@code ENTRIES} builds its {@link CvEntry} with a blank + * date, so an item's {@code period} reaches no renderer at all. Every + * field a kind ignores is dropped here, in one place, rather than by + * each renderer deciding what to skip.

+ */ +public final class ModuleRenderer { + + private ModuleRenderer() { + } + + /** + * Renders every item of {@code module} into {@code host}, drawing the + * canonical way. + * + * @param host host section receiving the body + * @param module the module supplying items, kind, and role + * @param theme the active theme supplying palette, typography, and spacing + */ + public static void render(SectionBuilder host, ModuleSection module, BrandTheme theme) { + render(host, module, theme, CvRenderKit.defaults()); + } + + /** + * Renders every item of {@code module} into {@code host}, drawing + * through {@code kit}. + * + *

The lowering below is the same whoever draws: which fields a kind + * reads, how a linked title is spelled, what an empty description does + * to a trailing colon. Only the three drawing calls go to the kit, so a + * preset can restyle its modules without re-deciding any of that.

+ * + * @param host host section receiving the body + * @param module the module supplying items, kind, and role + * @param theme the active theme supplying palette, typography, and spacing + * @param kit how this template draws paragraphs, rows, and entries + */ + public static void render(SectionBuilder host, ModuleSection module, BrandTheme theme, + CvRenderKit kit) { + List items = module.items(); + for (int i = 0; i < items.size(); i++) { + CvItem item = items.get(i); + switch (module.kind()) { + case PARAGRAPH -> paragraph(host, item, theme, kit); + case BULLETS -> bullet(host, item, theme, kit); + case BULLETS_STACKED -> stackedBullet(host, item, theme, kit, i > 0); + case INLINE_LIST -> inlineList(host, item, theme, kit); + case ENTRIES -> entry(host, item, "", theme, kit, i > 0); + case ENTRIES_DATED -> entry(host, item, item.period(), theme, kit, i > 0); + } + } + } + + /** + * Prose: one paragraph per body line, the title left out (see + * {@code CvKind.PARAGRAPH}). A bulleted body still bullets — the + * body style is the author's second choice, independent of kind. + */ + private static void paragraph(SectionBuilder host, CvItem item, BrandTheme theme, + CvRenderKit kit) { + for (String line : item.body()) { + if (item.bodyStyle() == BodyStyle.BULLETS) { + bulletedLine(host, line, theme.bodyStyle(), theme); + } else { + kit.paragraph(host, line, theme); + } + } + } + + /** + * One line per item — bold label, the description collapsed into a + * comma-separated run after it. An item with nothing to list renders + * as its label alone: {@link RowStyle#PLAIN} would leave a colon + * pointing at nothing. + */ + private static void inlineList(SectionBuilder host, CvItem item, BrandTheme theme, + CvRenderKit kit) { + // The title, not linkedTitle: this kind documents that it ignores the + // link, and RowRenderer bolds a label by wrapping it in markdown + // markers — which would nest around a link and print as literal + // asterisks. + if (item.body().isEmpty()) { + ParagraphPrimitive.writeBody(host, item.title(), theme.bodyBoldStyle(), theme); + return; + } + kit.row(host, new CvRow(item.title(), String.join(", ", item.body())), + RowStyle.PLAIN, theme); + } + + /** + * A bullet whose description shares its line + * ({@link RowStyle#BULLETED}). + * + *

The title goes in unlinked. This row bolds its label by wrapping + * it in markdown markers, which would nest around link markup and + * reach the page as literal asterisks; a module whose titles are + * links wants {@link CvKind#BULLETS_STACKED}, which bolds through the + * text style and leaves the link intact.

+ */ + private static void bullet(SectionBuilder host, CvItem item, BrandTheme theme, + CvRenderKit kit) { + if (item.body().isEmpty()) { + // PLAIN/BULLETED end the label with a colon, which would point at + // nothing. A title-only entry is a plain bullet. + ParagraphPrimitive.writeBulleted(host, item.title(), theme.bodyBoldStyle(), + theme.decoration().bulletGlyph(), + DocumentInsets.top((float) theme.spacing().paragraphMarginTop()), theme); + return; + } + kit.row(host, new CvRow(item.title(), String.join(" ", item.body())), + RowStyle.BULLETED, theme); + } + + /** + * A bullet whose description is stacked underneath and indented to + * the title ({@link RowStyle#BULLETED_STACKED}). + */ + private static void stackedBullet(SectionBuilder host, CvItem item, BrandTheme theme, + CvRenderKit kit, boolean separate) { + // Stacked items are multi-line blocks, so they get the same gap the + // dispatcher puts between stacked rows — without it consecutive items + // read as one. + if (separate) { + host.spacer(0, theme.spacing().entrySeparation()); + } + kit.row(host, new CvRow(linkedTitle(item), ""), RowStyle.BULLETED_STACKED, theme); + // A bulleted body nests a bullet under the item's own; prose is indented + // to the title instead of carrying a second glyph. + String glyph = item.bodyStyle() == BodyStyle.BULLETS + ? theme.decoration().stackedIndent() + theme.decoration().bulletGlyph() + : theme.decoration().stackedIndent(); + for (String line : item.body()) { + ParagraphPrimitive.writeBulleted(host, line, theme.bodyStyle(), + glyph, DocumentInsets.zero(), theme); + } + } + + /** + * A timeline entry. The header goes through {@link EntryRenderer} + * with an empty body so the title / date / subtitle zones are the + * ones every other entry uses; the description follows underneath + * in the style the item asked for. + */ + private static void entry(SectionBuilder host, CvItem item, String date, + BrandTheme theme, CvRenderKit kit, boolean separate) { + if (separate) { + host.spacer(0, theme.spacing().entrySeparation()); + } + kit.entry(host, + new CvEntry(linkedTitle(item), subtitleWithLocation(item), date, ""), theme); + for (String line : item.body()) { + if (item.bodyStyle() == BodyStyle.BULLETS) { + bulletedLine(host, line, theme.bodyStyle(), theme); + } else { + ParagraphPrimitive.writeBody(host, line, theme.bodyStyle(), theme); + } + } + } + + private static void bulletedLine(SectionBuilder host, String line, + DocumentTextStyle style, BrandTheme theme) { + ParagraphPrimitive.writeBulleted(host, line, style, + theme.decoration().bulletGlyph(), + DocumentInsets.top((float) theme.spacing().paragraphMarginTop()), theme); + } + + /** + * The title, wrapped in markdown link syntax when the item carries a + * link. Every renderer here already routes titles through the shared + * markdown helper, so this needs no separate link path. + * + *

A title containing a bracket is left alone. The markdown link + * pattern's label admits no brackets, so wrapping + * {@code "Ledger [v2]"} would match nothing and print the whole + * construction — URL included — as visible text. Either the title + * already carries its own {@code [text](url)}, which renders as the + * link it is, or it is prose with a bracket in it and reaches the + * page as written.

+ */ + private static String linkedTitle(CvItem item) { + if (item.link() == null + || item.title().indexOf('[') >= 0 + || item.title().indexOf(']') >= 0) { + return item.title(); + } + return "[" + item.title() + "](" + item.link().url() + ")"; + } + + /** + * The italic line under an entry title: subtitle and location joined + * when both are present, whichever exists when only one is, blank + * when neither — no separator left dangling. + */ + private static String subtitleWithLocation(CvItem item) { + if (item.subtitle().isBlank()) { + return item.location(); + } + if (item.location().isBlank()) { + return item.subtitle(); + } + return item.subtitle() + " · " + item.location(); + } +} diff --git a/templates/src/main/java/com/demcha/compose/document/templates/cv/components/SectionAllocation.java b/templates/src/main/java/com/demcha/compose/document/templates/cv/components/SectionAllocation.java index 560c5b94d..c79045b57 100644 --- a/templates/src/main/java/com/demcha/compose/document/templates/cv/components/SectionAllocation.java +++ b/templates/src/main/java/com/demcha/compose/document/templates/cv/components/SectionAllocation.java @@ -1,6 +1,8 @@ package com.demcha.compose.document.templates.cv.components; import com.demcha.compose.document.templates.cv.data.CvSection; +import com.demcha.compose.document.templates.cv.data.ModuleSection; +import com.demcha.compose.document.templates.cv.data.SectionRole; import java.util.ArrayList; import java.util.IdentityHashMap; @@ -58,6 +60,53 @@ public static SectionAllocation of(List sections) { return new SectionAllocation(List.copyOf(copy)); } + /** + * Claims the section this slot means, preferring a module that named the + * role over one whose heading happens to match. + * + *

Headings are the fallback because a section that carries no role — + * every hand-written one — has nothing else to be found by. A module that + * did name a role is never claimed by a different slot's + * keywords: it would then render in two places, which is a worse failure + * than the one role routing exists to fix.

+ * + * @param role the role this slot holds; {@code null} or + * {@link SectionRole#OTHER} means "keywords only" + * @param keys candidate heading fragments + * @return the claimed section, or {@code null} when nothing matches + * @since 2.3.0 + */ + public CvSection claim(SectionRole role, List keys) { + if (role != null && role != SectionRole.OTHER) { + for (CvSection section : sections) { + if (claimed.containsKey(section)) { + continue; + } + if (section instanceof ModuleSection module && module.role() == role) { + claimed.put(section, Boolean.TRUE); + return section; + } + } + } + for (CvSection section : sections) { + if (claimed.containsKey(section)) { + continue; + } + if (section instanceof ModuleSection module + && module.role() != SectionRole.OTHER) { + continue; + } + String title = SectionLookup.normalize(section.title()); + for (String key : keys == null ? List.of() : keys) { + if (title.contains(SectionLookup.normalize(key))) { + claimed.put(section, Boolean.TRUE); + return section; + } + } + } + return null; + } + /** * Claims the first not-yet-claimed section whose normalised title contains * any of the keys. @@ -66,6 +115,10 @@ public static SectionAllocation of(List sections) { * different section instead of the same one twice, and what moves * the section out of {@link #remaining()}.

* + *

Heading-only. A slot that knows which {@link SectionRole} it holds + * should call {@link #claim(SectionRole, List)}, so a CV written in another + * language routes on what its sections mean.

+ * * @param keys candidate title fragments; {@code null} claims nothing * @return the claimed section, or {@code null} when nothing matches */ diff --git a/templates/src/main/java/com/demcha/compose/document/templates/cv/components/SectionDispatcher.java b/templates/src/main/java/com/demcha/compose/document/templates/cv/components/SectionDispatcher.java index c2280c71a..b450b8e67 100644 --- a/templates/src/main/java/com/demcha/compose/document/templates/cv/components/SectionDispatcher.java +++ b/templates/src/main/java/com/demcha/compose/document/templates/cv/components/SectionDispatcher.java @@ -34,11 +34,31 @@ private SectionDispatcher() { * @throws IllegalStateException if the section subtype is unhandled */ public static void renderBody(SectionBuilder host, CvSection section, BrandTheme theme) { + renderBody(host, section, theme, CvRenderKit.defaults()); + } + + /** + * Renders the section body, drawing through {@code kit}. + * + *

The routing is identical to the three-argument form; only who draws + * differs. A preset with its own entry or row style passes its kit here + * so a runtime module looks like the rest of its document instead of + * like the canonical components.

+ * + * @param host host section receiving the body + * @param section the section whose subtype selects the renderer + * @param theme the active theme supplying palette, typography, and spacing + * @param kit how this template draws paragraphs, rows, and entries + * @throws IllegalStateException if the section subtype is unhandled + * @since 2.3.0 + */ + public static void renderBody(SectionBuilder host, CvSection section, BrandTheme theme, + CvRenderKit kit) { host.spacing(theme.spacing().sectionBodySpacing()) .padding(theme.spacing().sectionBodyPadding()); if (section instanceof ParagraphSection p) { - ParagraphRenderer.render(host, p.body(), theme); + kit.paragraph(host, p.body(), theme); } else if (section instanceof SkillsSection s) { SkillsRenderer.render(host, s, theme); } else if (section instanceof RowsSection r) { @@ -52,8 +72,13 @@ public static void renderBody(SectionBuilder host, CvSection section, BrandTheme if (i > 0 && stackedNeedsSeparator) { host.spacer(0, theme.spacing().entrySeparation()); } - RowRenderer.render(host, r.rows().get(i), r.style(), theme); + kit.row(host, r.rows().get(i), r.style(), theme); } + } else if (section instanceof ModuleSection m) { + // Runtime-assembled module. The kind decides which of the + // renderers above each item lands on, so this branch draws + // nothing of its own — see ModuleRenderer. + ModuleRenderer.render(host, m, theme, kit); } else if (section instanceof EntriesSection e) { // Timeline entries (Education, Experience) get a spacer // between items — each entry is a multi-line block @@ -63,7 +88,7 @@ public static void renderBody(SectionBuilder host, CvSection section, BrandTheme if (i > 0) { host.spacer(0, theme.spacing().entrySeparation()); } - EntryRenderer.render(host, e.entries().get(i), theme); + kit.entry(host, e.entries().get(i), theme); } } else { throw new IllegalStateException( diff --git a/templates/src/main/java/com/demcha/compose/document/templates/cv/components/SectionLookup.java b/templates/src/main/java/com/demcha/compose/document/templates/cv/components/SectionLookup.java index c116eb34f..e5f3a96ce 100644 --- a/templates/src/main/java/com/demcha/compose/document/templates/cv/components/SectionLookup.java +++ b/templates/src/main/java/com/demcha/compose/document/templates/cv/components/SectionLookup.java @@ -50,9 +50,18 @@ public static CvSection firstMatching(List sections, * sealed {@code CvSection} hierarchy — {@code SectionLookupTest} pins the * contract.

* + *

The default is {@code false}, which makes an unlisted subtype + * invisible rather than merely unstyled: presets filter on this + * before they route or render, so a section this method does not + * recognise never reaches a dispatcher at all. Every {@code CvSection} + * permit therefore needs a case here — the branch below for + * {@code ModuleSection} exists because the fallback dropped the section + * heading and body together, on presets that had a perfectly good + * rendering path for it.

+ * * @param section the section to inspect; may be {@code null} * @return {@code true} if the section has non-empty body, entries, - * rows, or skill groups + * rows, skill groups, or module items */ public static boolean hasContent(CvSection section) { if (section instanceof ParagraphSection paragraph) { @@ -67,6 +76,9 @@ public static boolean hasContent(CvSection section) { if (section instanceof SkillsSection skills) { return skills.groups() != null && !skills.groups().isEmpty(); } + if (section instanceof ModuleSection module) { + return !module.items().isEmpty(); + } return false; } diff --git a/templates/src/main/java/com/demcha/compose/document/templates/cv/components/SectionRouter.java b/templates/src/main/java/com/demcha/compose/document/templates/cv/components/SectionRouter.java new file mode 100644 index 000000000..b87f3ad16 --- /dev/null +++ b/templates/src/main/java/com/demcha/compose/document/templates/cv/components/SectionRouter.java @@ -0,0 +1,258 @@ +package com.demcha.compose.document.templates.cv.components; + +import com.demcha.compose.document.templates.core.identity.Link; +import com.demcha.compose.document.templates.cv.data.BodyStyle; +import com.demcha.compose.document.templates.cv.data.CvEntry; +import com.demcha.compose.document.templates.cv.data.CvItem; +import com.demcha.compose.document.templates.cv.data.CvKind; +import com.demcha.compose.document.templates.cv.data.CvRow; +import com.demcha.compose.document.templates.cv.data.CvSection; +import com.demcha.compose.document.templates.cv.data.EntriesSection; +import com.demcha.compose.document.templates.cv.data.ModuleSection; +import com.demcha.compose.document.templates.cv.data.ParagraphSection; +import com.demcha.compose.document.templates.cv.data.RowStyle; +import com.demcha.compose.document.templates.cv.data.RowsSection; +import com.demcha.compose.document.templates.cv.data.SectionRole; +import com.demcha.compose.document.templates.cv.data.SkillGroup; +import com.demcha.compose.document.templates.cv.data.SkillsSection; + +import java.util.ArrayList; +import java.util.List; + +/** + * Finds the section a preset's slot should hold, by what it means rather + * than by what it is called — and hands it back in the shape that slot + * knows how to draw. + * + *

Presets with a designed layout place their sections into fixed slots, + * and they have been choosing what goes where by matching the section's + * heading against a list of English words each preset keeps privately. That + * works for a CV written in English by someone who used the expected + * headings. A CV headed {@code Ausbildung} or {@code Навыки} matches + * nothing and loses the section; so does {@code "Volunteering"}, and so does + * a second section whose heading matched a word the first one took.

+ * + *

A {@link ModuleSection} carries a {@link SectionRole} because the + * author already knew the answer, so the role is asked first and the + * keywords are the fallback for the sections that have no role to give.

+ * + *

The second half is the shape. These slots are written against a + * particular section type — {@code if (!(section instanceof EntriesSection + * entries)) return;} — because each draws its content its own way, and a + * module reaching one would be dropped by that guard however well it was + * routed. Each finder below therefore lowers a matched module to the type + * its slot expects, so the preset draws it exactly as it draws everything + * else. What that costs is stated per method: a module's description lines + * are joined where the target type holds one string, and a bulleted + * description reads as prose.

+ * + *

These presets still drop a section that matches no slot at all — their + * whole body is one atomic row that cannot paginate, so there is nowhere to + * put it. Routing by role fixes the sections that were lost while a slot + * for them sat empty; the rest waits on pagination.

+ * + * @since 2.3.0 + */ +public final class SectionRouter { + + private SectionRouter() { + } + + /** + * The section for a timeline slot — education, experience, anything the + * preset draws as dated entries. + * + *

A matched module becomes an {@link EntriesSection}: each item's + * title, its subtitle and location joined, its period (blank when the + * module's kind does not read one), and its description lines joined + * into the single body string a {@link CvEntry} holds. A description the + * author asked to bullet reads as prose here — the slot draws one + * paragraph.

+ * + * @param sections the document's sections for this slot's column + * @param role the role this slot holds + * @param keys heading fragments to fall back on + * @return an {@code EntriesSection}, or {@code null} when nothing matches + */ + public static CvSection entries(List sections, SectionRole role, + List keys) { + CvSection found = find(sections, role, keys); + if (!(found instanceof ModuleSection module)) { + return found; + } + List entries = new ArrayList<>(module.items().size()); + boolean dated = module.kind() == CvKind.ENTRIES_DATED; + for (CvItem item : module.items()) { + entries.add(new CvEntry(title(item), subtitleWithLocation(item), + dated ? item.period() : "", String.join(" ", item.body()))); + } + return new EntriesSection(module.title(), entries); + } + + /** + * The section for a label/value slot — projects, languages, additional + * information. + * + *

A matched module becomes a {@link RowsSection} in the caller's + * {@link RowStyle}: one row per item, its title the label and its + * description lines joined into the body.

+ * + * @param sections the document's sections for this slot's column + * @param role the role this slot holds + * @param keys heading fragments to fall back on + * @param style the decoration this slot draws rows with + * @return a {@code RowsSection}, or {@code null} when nothing matches + */ + public static CvSection rows(List sections, SectionRole role, + List keys, RowStyle style) { + CvSection found = find(sections, role, keys); + if (!(found instanceof ModuleSection module)) { + return found; + } + List rows = new ArrayList<>(module.items().size()); + for (CvItem item : module.items()) { + // Discrete points are joined with a comma and prose with a space: + // a row holds one string, and "Rebuilt the ledger Cut p99 40%" reads + // as one garbled sentence while "Shipped it., Measured it." puts a + // comma after a full stop. + String separator = item.bodyStyle() == BodyStyle.BULLETS ? ", " : " "; + // Only the stacked style keeps a linked title: the inline ones bold + // their label by wrapping it in markdown markers, which would nest + // around the link and reach the page as literal asterisks. + String label = style == RowStyle.BULLETED_STACKED ? title(item) : item.title(); + rows.add(new CvRow(label, String.join(separator, item.body()))); + } + return new RowsSection(module.title(), rows, style); + } + + /** + * The section for a prose slot — a profile, a summary, an objective. + * + *

A matched module becomes a {@link ParagraphSection} whose body is + * every item's description, joined. The slot holds one block of prose, + * so a module with several items reads as one.

+ * + * @param sections the document's sections for this slot's column + * @param role the role this slot holds + * @param keys heading fragments to fall back on + * @return a {@code ParagraphSection}, or {@code null} when nothing matches + */ + public static CvSection paragraph(List sections, SectionRole role, + List keys) { + CvSection found = find(sections, role, keys); + if (!(found instanceof ModuleSection module)) { + return found; + } + List lines = new ArrayList<>(); + for (CvItem item : module.items()) { + lines.addAll(item.body()); + } + return new ParagraphSection(module.title(), String.join(" ", lines)); + } + + /** + * The section for a skills slot — the one preset slot that wants + * categories rather than lines, because it may draw a table, chips, or + * proficiency bars. + * + *

A matched module becomes a {@link SkillsSection}: an item with a + * description is a category whose skills are its lines, and the items + * with none are collected into one group under the module's own heading — + * a plain list of skills is a list of skills, not a set of categories + * each holding itself.

+ * + * @param sections the document's sections for this slot's column + * @param role the role this slot holds + * @param keys heading fragments to fall back on + * @return a {@code SkillsSection}, or {@code null} when nothing matches + */ + public static CvSection skills(List sections, SectionRole role, + List keys) { + CvSection found = find(sections, role, keys); + if (!(found instanceof ModuleSection module)) { + return found; + } + List groups = new ArrayList<>(module.items().size()); + List loose = new ArrayList<>(); + for (CvItem item : module.items()) { + if (item.body().isEmpty()) { + // A skill with nothing under it is a skill, not a category of + // one: making it its own group prints "Java 21: Java 21". + loose.add(item.title()); + continue; + } + groups.add(SkillGroup.ofNames(item.title(), item.body())); + } + if (!loose.isEmpty()) { + groups.add(SkillGroup.ofNames(module.title(), loose)); + } + return new SkillsSection(module.title(), groups); + } + + /** + * The section this slot should hold, or {@code null} when the document + * has none: the first module whose role is the slot's, else the first + * section whose heading matches one of the keys. + * + *

Role first, and only a role the author actually chose — + * {@link SectionRole#OTHER} is what a module carries when the catalogue + * has no name for it, so it never claims a slot and falls through to the + * headings like any other section.

+ * + * @param sections the document's sections for this slot's column + * @param role the role this slot holds + * @param keys heading fragments to fall back on + * @return the section, or {@code null} when nothing matches + */ + public static CvSection find(List sections, SectionRole role, + List keys) { + if (sections == null) { + return null; + } + if (role != null && role != SectionRole.OTHER) { + for (CvSection section : sections) { + if (section instanceof ModuleSection module && module.role() == role + && SectionLookup.hasContent(section)) { + return section; + } + } + } + // The heading is the fallback, and it may not overrule a role. A module + // declared EXPERIENCE and headed "Projects" belongs where its author put + // it; letting the projects slot claim it by heading would render it in + // both places, which is worse than the drop this routing exists to fix. + return SectionLookup.firstMatching(spokenFor(sections), keys); + } + + /** The sections a keyword slot may still claim: everything but a module that named its own role. */ + private static List spokenFor(List sections) { + List open = new ArrayList<>(sections.size()); + for (CvSection section : sections) { + if (section instanceof ModuleSection module && module.role() != SectionRole.OTHER) { + continue; + } + open.add(section); + } + return open; + } + + /** The title, as markdown link syntax when the item carries a link. */ + private static String title(CvItem item) { + Link link = item.link(); + if (link == null || item.title().indexOf('[') >= 0 || item.title().indexOf(']') >= 0) { + return item.title(); + } + return "[" + item.title() + "](" + link.url() + ")"; + } + + /** Subtitle and location joined, or whichever exists, or blank. */ + private static String subtitleWithLocation(CvItem item) { + if (item.subtitle().isBlank()) { + return item.location(); + } + if (item.location().isBlank()) { + return item.subtitle(); + } + return item.subtitle() + " · " + item.location(); + } +} diff --git a/templates/src/main/java/com/demcha/compose/document/templates/cv/data/BodyStyle.java b/templates/src/main/java/com/demcha/compose/document/templates/cv/data/BodyStyle.java new file mode 100644 index 000000000..8d927a479 --- /dev/null +++ b/templates/src/main/java/com/demcha/compose/document/templates/cv/data/BodyStyle.java @@ -0,0 +1,28 @@ +package com.demcha.compose.document.templates.cv.data; + +/** + * How one {@link CvItem}'s description lines render — the second, + * smaller axis next to {@link CvKind}. + * + *

The kind decides the item's shape (a bullet, a dated entry, a + * line in a list); this decides what happens to + * {@link CvItem#body()} inside it. The same experience entry can list + * its achievements as bullets or read as a paragraph without changing + * the module's kind, which is the distinction authors actually make + * when they say "this section is bulleted".

+ * + * @since 2.3.0 + */ +public enum BodyStyle { + + /** + * Each body line is a paragraph of prose. The default: an item + * built without a stated style reads as text. + */ + PARAGRAPH, + + /** + * Each body line carries a bullet glyph and a hanging indent. + */ + BULLETS +} diff --git a/templates/src/main/java/com/demcha/compose/document/templates/cv/data/CvItem.java b/templates/src/main/java/com/demcha/compose/document/templates/cv/data/CvItem.java new file mode 100644 index 000000000..db0f1716a --- /dev/null +++ b/templates/src/main/java/com/demcha/compose/document/templates/cv/data/CvItem.java @@ -0,0 +1,189 @@ +package com.demcha.compose.document.templates.cv.data; + +import com.demcha.compose.document.templates.core.identity.Link; + +import java.util.ArrayList; +import java.util.Arrays; +import java.util.List; +import java.util.Objects; + +/** + * One entry inside a {@link ModuleSection} — the universal record every + * runtime-assembled module is built from. + * + *

A job, a degree, a project, a skill category, a paragraph of a + * summary: all of them are a title plus some optional context plus a + * description. Rather than a record per shape, this carries every + * optional field and lets the section's {@link CvKind} decide which + * ones it reads — a {@code period} is drawn by + * {@link CvKind#ENTRIES_DATED} and ignored by {@link CvKind#ENTRIES}, + * with the same item on both sides. Each kind documents exactly what + * it reads.

+ * + *

Only {@code title} is required, and only because a module entry + * with nothing to name it has nothing to render. Everything else is + * blank, {@code null}, or empty when the author has nothing to say — + * no placeholder text, no {@code "—"} stand-ins.

+ * + *

Build one through {@link #of(String)} and the {@code with}-style + * methods, which read in the order the fields render:

+ * + * 
{@code
+ * CvItem.of("Senior Backend Engineer")
+ *       .at("Acme GmbH")
+ *       .in("Berlin, DE")
+ *       .period("2021 - Present")
+ *       .bullets("Cut p99 latency 40%", "Led the payments migration");
+ * }
+ * + * @param title what the entry is called; required, non-blank. May + * carry inline markdown, including {@code [text](url)} + * @param link optional click target for the title; {@code null} + * when the title is not a link. A {@code link} and a + * markdown link inside {@code title} do the same job — + * prefer this one, which needs no escaping + * @param subtitle employer, institution, client; blank when absent + * @param period date or range as the author wants it written + * ({@code "2021 - Present"}, {@code "2019"}); blank + * when absent, and read only by dated kinds + * @param location city, country, or "Remote"; blank when absent + * @param body description lines; empty when the entry is a + * heading only. One line renders as one paragraph or + * one bullet, per {@code bodyStyle} + * @param bodyStyle whether {@code body} reads as prose or as bullets + * @since 2.3.0 + */ +public record CvItem(String title, Link link, String subtitle, String period, + String location, List body, BodyStyle bodyStyle) { + + /** + * Validates the required {@code title}, normalises every optional + * text field from {@code null} to blank, drops null or blank body + * lines, and defensively copies the body list. + */ + public CvItem { + Objects.requireNonNull(title, "title"); + if (title.isBlank()) { + throw new IllegalArgumentException("title must not be blank"); + } + title = title.trim(); + subtitle = subtitle == null ? "" : subtitle.trim(); + period = period == null ? "" : period.trim(); + location = location == null ? "" : location.trim(); + bodyStyle = bodyStyle == null ? BodyStyle.PARAGRAPH : bodyStyle; + + List cleaned = new ArrayList<>(body == null ? 0 : body.size()); + if (body != null) { + for (String line : body) { + if (line != null && !line.isBlank()) { + cleaned.add(line.trim()); + } + } + } + body = List.copyOf(cleaned); + } + + /** + * An item with nothing but its title. Chain the {@code with}-style + * methods below to add what the entry actually has. + * + * @param title what the entry is called; required, non-blank + * @return a new item carrying only {@code title} + */ + public static CvItem of(String title) { + return new CvItem(title, null, "", "", "", List.of(), BodyStyle.PARAGRAPH); + } + + /** + * Returns a copy whose title links to {@code url}. + * + * @param url click target; blank or null clears the link + * @return a copy carrying the link + */ + public CvItem linkedTo(String url) { + Link target = url == null || url.isBlank() ? null : Link.of(title, url); + return new CvItem(title, target, subtitle, period, location, body, bodyStyle); + } + + /** + * Returns a copy with the employer / institution / client line. + * + * @param value subtitle text; null or blank leaves the line out + * @return a copy carrying the subtitle + */ + public CvItem at(String value) { + return new CvItem(title, link, value, period, location, body, bodyStyle); + } + + /** + * Returns a copy with the location line. + * + * @param value city, country, or "Remote"; null or blank leaves it out + * @return a copy carrying the location + */ + public CvItem in(String value) { + return new CvItem(title, link, subtitle, period, value, body, bodyStyle); + } + + /** + * Returns a copy with the date or range, written as the author + * wants it. Read only by {@link CvKind#ENTRIES_DATED}. + * + * @param value date or range; null or blank leaves it out + * @return a copy carrying the period + */ + public CvItem period(String value) { + return new CvItem(title, link, subtitle, value, location, body, bodyStyle); + } + + /** + * Returns a copy whose description reads as prose, one paragraph + * per line. + * + * @param lines description lines; null or blank lines are dropped + * @return a copy carrying the description + */ + public CvItem paragraphs(String... lines) { + return withBody(lines, BodyStyle.PARAGRAPH); + } + + /** + * Returns a copy whose description reads as a bulleted list, one + * bullet per line. + * + * @param lines description lines; null or blank lines are dropped + * @return a copy carrying the description + */ + public CvItem bullets(String... lines) { + return withBody(lines, BodyStyle.BULLETS); + } + + /** + * Returns a copy with an explicit body list and style — the + * variant for callers holding a {@code List} they did not build + * literally (an import layer, a JSON mapper). + * + * @param lines description lines; null or blank lines are dropped + * @param style whether the lines read as prose or as bullets + * @return a copy carrying the description + */ + public CvItem body(List lines, BodyStyle style) { + return new CvItem(title, link, subtitle, period, location, lines, style); + } + + /** + * The click target for this item's title, if it has one. + * + * @return the link URL, or blank when the title is not a link + */ + public String url() { + return link == null ? "" : link.url(); + } + + private CvItem withBody(String[] lines, BodyStyle style) { + // Arrays.asList, not List.of: a null line is dropped by the canonical + // constructor, and List.of would throw before it ever got there. + List values = lines == null ? List.of() : Arrays.asList(lines); + return new CvItem(title, link, subtitle, period, location, values, style); + } +} diff --git a/templates/src/main/java/com/demcha/compose/document/templates/cv/data/CvKind.java b/templates/src/main/java/com/demcha/compose/document/templates/cv/data/CvKind.java new file mode 100644 index 000000000..8cecabda0 --- /dev/null +++ b/templates/src/main/java/com/demcha/compose/document/templates/cv/data/CvKind.java @@ -0,0 +1,103 @@ +package com.demcha.compose.document.templates.cv.data; + +/** + * How a {@link ModuleSection}'s items are laid out — the presentation + * shape the author picks at runtime, independent of what the section + * means. + * + *

This is the axis that lets one {@link CvItem} record serve every + * module: the kind decides which of the item's optional fields are + * read and which are ignored. An item carrying a + * {@code period} rendered under {@link #ENTRIES} simply does not show + * a date column — the same data under {@link #ENTRIES_DATED} does. + * Each constant below names exactly what it reads, so "ignored" is a + * documented contract rather than a surprise.

+ * + *

Every kind lowers onto the renderers this package already ships + * (see {@code components.ModuleRenderer}); none of them draws + * anything a hand-built {@link RowsSection}, {@link EntriesSection} or + * {@link ParagraphSection} could not.

+ * + *

The orthogonal axes are {@link SectionRole} — what the section + * means, which is what a multi-column preset places on — and + * {@link BodyStyle}, which decides how one item's description lines + * render. Keeping them apart is what lets a "Volunteering" module be + * shaped exactly like Education without a new type.

+ * + * @since 2.3.0 + */ +public enum CvKind { + + /** + * Prose — a summary, an objective, a statement. Each item renders + * as its description, one paragraph per body line. + * + *

Reads {@code body} only. The {@code title} is ignored here on + * purpose: the section already carries a heading, and a prose block + * that repeated it would print the same words twice. For a labelled + * one-liner ({@code Languages: English, German}) reach for + * {@link #INLINE_LIST}, which is what that shape is.

+ */ + PARAGRAPH, + + /** + * A bullet per item, description on the same line — + * {@code • Throughput: doubled it}. The shape of a short list where + * each entry is a label and a value ({@link RowStyle#BULLETED}). + * + *

Reads {@code title}, {@code link}, {@code body}. Ignores + * {@code subtitle}, {@code period}, {@code location}. A body of + * several lines is joined with spaces; if the lines are meant to + * stand apart, the module wants {@link #BULLETS_STACKED}.

+ */ + BULLETS, + + /** + * A bullet per item, description stacked underneath and indented to + * the title — the shape a Projects section takes when the + * description is a sentence rather than a value + * ({@link RowStyle#BULLETED_STACKED}). + * + *

Reads {@code title}, {@code link}, {@code body}. Ignores + * {@code subtitle}, {@code period}, {@code location}.

+ * + *

Inline or stacked is the module's choice, not something + * inferred from how long a description happens to be: the same + * section reads one way throughout, and an author who picked + * "bulleted list with descriptions underneath" gets it whether the + * first entry is one line or five.

+ */ + BULLETS_STACKED, + + /** + * One line per item, the description collapsed into a + * comma-separated run after a bold label — + * {@code Languages: Java 21, Kotlin, SQL}. The shape skills and + * languages take in a narrow column. + * + *

Reads {@code title} and {@code body}. Ignores {@code link}, + * {@code subtitle}, {@code period}, {@code location}.

+ */ + INLINE_LIST, + + /** + * Timeline entries without the date column: bold title, italic + * subtitle line, description beneath. + * + *

Reads {@code title}, {@code link}, {@code subtitle}, + * {@code location}, {@code body}. Ignores {@code period} — this + * is the kind to pick when the dates exist in the data but should + * not show.

+ */ + ENTRIES, + + /** + * Timeline entries with the date column right-aligned against the + * title — Education, Experience, and anything shaped like them. + * + *

Reads every field: {@code title}, {@code link}, + * {@code subtitle}, {@code period}, {@code location}, + * {@code body}.

+ */ + ENTRIES_DATED +} diff --git a/templates/src/main/java/com/demcha/compose/document/templates/cv/data/CvSection.java b/templates/src/main/java/com/demcha/compose/document/templates/cv/data/CvSection.java index e3da6bbe7..c5e2d2660 100644 --- a/templates/src/main/java/com/demcha/compose/document/templates/cv/data/CvSection.java +++ b/templates/src/main/java/com/demcha/compose/document/templates/cv/data/CvSection.java @@ -17,13 +17,21 @@ * items with four fields (title, subtitle, date, body). *
  • {@link SkillsSection} — grouped skill categories where each * category owns an ordered list of skill labels.
    • + *
  • {@link ModuleSection} — a section whose shape is a value + * rather than a type: one {@link CvItem} record plus a + * {@link CvKind} chosen at runtime. The four above stay the + * natural choice for a CV written in Java, where the author + * picks the record and the compiler checks it; this one is for a + * CV assembled from data, where the shape is not known until it + * arrives. It renders through the same components, so both + * routes lay out the same content identically.
    • * * *

    Every implementation carries a {@code title} — the banner text * the renderer wraps in a styled panel above the section body.

    */ public sealed interface CvSection - permits ParagraphSection, RowsSection, EntriesSection, SkillsSection { + permits ParagraphSection, RowsSection, EntriesSection, SkillsSection, ModuleSection { /** * Banner heading shown above this section's body. diff --git a/templates/src/main/java/com/demcha/compose/document/templates/cv/data/ModuleSection.java b/templates/src/main/java/com/demcha/compose/document/templates/cv/data/ModuleSection.java new file mode 100644 index 000000000..331078a78 --- /dev/null +++ b/templates/src/main/java/com/demcha/compose/document/templates/cv/data/ModuleSection.java @@ -0,0 +1,178 @@ +package com.demcha.compose.document.templates.cv.data; + +import java.util.ArrayList; +import java.util.Arrays; +import java.util.List; +import java.util.Objects; + +/** + * A section assembled at runtime: a heading, what it means + * ({@link SectionRole}), how it draws ({@link CvKind}), and the + * {@link CvItem}s it holds. + * + *

    The other {@link CvSection} implementations each fix one shape at + * compile time — {@link ParagraphSection} is prose, {@link RowsSection} + * is rows, {@link EntriesSection} is a timeline. That is the right + * model for a CV written in Java, where the author picks the record and + * the compiler checks it. It is the wrong one for a CV assembled from + * data at runtime: a user who has just chosen "Volunteering, shaped + * like Education, with dates" cannot instantiate a different record per + * choice, and every new shape would mean a new type.

    + * + *

    So this record moves the choice into a value. One item type carries + * every optional field; the kind decides which are read and which are + * ignored; the role says where the section belongs without a preset + * having to recognise its heading. The result is that a module nobody + * anticipated needs no new code — only a different + * {@code (role, kind)} pair.

    + * + *

    It renders through the same components as everything else. Every + * kind lowers onto {@link ParagraphSection}-, {@link RowsSection}- or + * {@link EntriesSection}-shaped output, so a module drawn as + * {@link CvKind#ENTRIES_DATED} is laid out exactly like the + * {@code EntriesSection} carrying the same content — which the parity + * suite holds to, layout node for layout node.

    + * + * 
    {@code
+ * ModuleSection.builder("Volunteering", SectionRole.OTHER, CvKind.ENTRIES_DATED)
+ *     .item(CvItem.of("Mentor, Rails Girls")
+ *                 .at("Rails Girls Berlin")
+ *                 .period("2019 - 2021")
+ *                 .bullets("Ran three weekend workshops"))
+ *     .build();
+ * }
    + * + * @param title non-blank banner heading, in the author's own words + * @param role what the section means; {@link SectionRole#OTHER} when + * the catalogue has no name for it + * @param kind how the items draw + * @param items ordered items; null entries are dropped + * @since 2.3.0 + */ +public record ModuleSection(String title, SectionRole role, CvKind kind, List items) + implements CvSection { + + /** + * Validates that every field is non-null and {@code title} is + * non-blank, drops null items, and defensively copies the list. + */ + public ModuleSection { + Objects.requireNonNull(title, "title"); + Objects.requireNonNull(role, "role"); + Objects.requireNonNull(kind, "kind"); + Objects.requireNonNull(items, "items"); + if (title.isBlank()) { + throw new IllegalArgumentException("title must not be blank"); + } + List cleaned = new ArrayList<>(items.size()); + for (CvItem item : items) { + if (item != null) { + cleaned.add(item); + } + } + items = List.copyOf(cleaned); + } + + /** + * Fluent builder seeded with the three choices that define the + * module. + * + * @param title non-blank banner heading + * @param role what the section means + * @param kind how its items draw + * @return new builder + */ + public static Builder builder(String title, SectionRole role, CvKind kind) { + return new Builder(title, role, kind); + } + + /** + * Module assembled from a fixed set of items. + * + * @param title non-blank banner heading + * @param role what the section means + * @param kind how its items draw + * @param items items in source order; null becomes empty + * @return a {@code ModuleSection} carrying the supplied items + */ + public static ModuleSection of(String title, SectionRole role, CvKind kind, CvItem... items) { + return new ModuleSection(title, role, kind, + items == null ? List.of() : Arrays.asList(items)); + } + + /** + * Prose module — the common case of a summary or objective, where + * the section is one block of text and naming a kind and a role + * adds nothing. + * + * @param title non-blank banner heading + * @param text the prose; each argument is its own paragraph + * @return a {@link CvKind#PARAGRAPH} module under + * {@link SectionRole#SUMMARY} + */ + public static ModuleSection summary(String title, String... text) { + // The item's title is the section's: PARAGRAPH reads only the body, so + // it names the item without reaching the page. + return of(title, SectionRole.SUMMARY, CvKind.PARAGRAPH, + CvItem.of(title).paragraphs(text)); + } + + /** + * Mutable builder. + */ + public static final class Builder { + private final String title; + private final SectionRole role; + private final CvKind kind; + private final List items = new ArrayList<>(); + + private Builder(String title, SectionRole role, CvKind kind) { + this.title = title; + this.role = role; + this.kind = kind; + } + + /** + * Appends one pre-built item. + * + * @param item the item to append (non-null) + * @return this builder for chaining + */ + public Builder item(CvItem item) { + this.items.add(Objects.requireNonNull(item, "item")); + return this; + } + + /** + * Appends a title-only item — the shape a bulleted list or an + * inline list of one-liners takes. + * + * @param title what the entry is called; required, non-blank + * @return this builder for chaining + */ + public Builder item(String title) { + return item(CvItem.of(title)); + } + + /** + * Appends a labelled item whose description is the given + * lines, read as prose. + * + * @param title what the entry is called; required, non-blank + * @param body description lines; null or blank lines dropped + * @return this builder for chaining + */ + public Builder item(String title, String... body) { + return item(CvItem.of(title).paragraphs(body)); + } + + /** + * Builds the immutable {@link ModuleSection}. + * + * @return the assembled section + */ + public ModuleSection build() { + return new ModuleSection(title, role, kind, items); + } + } +} diff --git a/templates/src/main/java/com/demcha/compose/document/templates/cv/data/SectionRole.java b/templates/src/main/java/com/demcha/compose/document/templates/cv/data/SectionRole.java new file mode 100644 index 000000000..de00b77ad --- /dev/null +++ b/templates/src/main/java/com/demcha/compose/document/templates/cv/data/SectionRole.java @@ -0,0 +1,54 @@ +package com.demcha.compose.document.templates.cv.data; + +/** + * What a {@link ModuleSection} means, stated by the author + * instead of guessed from its heading. + * + *

    Multi-column presets have to decide what belongs in a sidebar, + * and until now they decided it by matching the section's title + * against a list of English keywords each preset kept privately. A CV + * whose headings read {@code "Ausbildung"} or {@code "Навыки"} matched + * nothing, and a heading nobody anticipated was placed by whatever the + * preset does with leftovers. The role carries that decision in the + * data, where the author already knows the answer.

    + * + *

    It is deliberately separate from {@link CvKind}: the role says + * what a section is, the kind says how it draws. A "Volunteering" + * module shaped exactly like Education is + * {@code role = OTHER, kind = ENTRIES_DATED} — a combination no single + * enum could express without one constant per pairing.

    + * + *

    {@link #OTHER} is the honest default and is never a second-class + * citizen: a preset that cannot place it by role falls back to the + * heading the author wrote, in document order.

    + * + * @since 2.3.0 + */ +public enum SectionRole { + + /** Profile, objective, professional summary — the opening prose. */ + SUMMARY, + + /** Employment history. */ + EXPERIENCE, + + /** Degrees, certifications, courses. */ + EDUCATION, + + /** Technical or professional skills, however they are grouped. */ + SKILLS, + + /** Personal or professional projects. */ + PROJECTS, + + /** Spoken languages and proficiency. */ + LANGUAGES, + + /** + * Anything else — awards, volunteering, publications, interests, + * references, a section this catalogue has no name for. Carries no + * placement hint, so presets fall back to the author's own + * heading. + */ + OTHER +} diff --git a/templates/src/main/java/com/demcha/compose/document/templates/cv/data/package-info.java b/templates/src/main/java/com/demcha/compose/document/templates/cv/data/package-info.java index f5ff77798..54adaf5e0 100644 --- a/templates/src/main/java/com/demcha/compose/document/templates/cv/data/package-info.java +++ b/templates/src/main/java/com/demcha/compose/document/templates/cv/data/package-info.java @@ -40,8 +40,33 @@ * — grouped skills: category plus ordered skill labels. This * keeps skills semantic so presets can render them as tables, * sidebar chips, or inline rows without reparsing text. + *
  • {@link com.demcha.compose.document.templates.cv.data.ModuleSection} + * — the shape as a value: one + * {@link com.demcha.compose.document.templates.cv.data.CvItem} + * record carrying every optional field, plus a + * {@link com.demcha.compose.document.templates.cv.data.CvKind} + * that decides which of them are read. For CVs assembled at + * runtime, where the author picks "dated entries" or "bullets" + * from a menu and no compile-time type can be chosen per + * choice.
    • * * + *

    Which one to reach for

    + * + *

    Writing a CV in Java: the four fixed shapes. The compiler checks + * the record you picked, and a project is visibly a + * {@code RowsSection} rather than a section that happens to hold + * rows.

    + * + *

    Assembling one from data — a form, a JSON payload, an LLM: the + * module. The section's shape and meaning arrive as values + * ({@code CvKind}, {@code SectionRole}), so a heading nobody + * anticipated — "Volunteering", shaped like Education — needs no new + * type and no new branch. Both routes render through the same + * components, and the parity suite holds them to laying out the same + * content identically, so the choice is about how the CV is authored, + * not about what it can look like.

    + * *

    Placement

    * *

    Sections live inside a {@link com.demcha.compose.document.templates.cv.data.CvDocument} diff --git a/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/BlueBanner.java b/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/BlueBanner.java index 6f70fd3ab..69e7e90c5 100644 --- a/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/BlueBanner.java +++ b/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/BlueBanner.java @@ -10,6 +10,7 @@ import com.demcha.compose.document.style.DocumentTextDecoration; import com.demcha.compose.document.style.DocumentTextStyle; import com.demcha.compose.document.templates.api.DocumentTemplate; +import com.demcha.compose.document.templates.cv.api.ModularCvTemplate; import com.demcha.compose.document.templates.cv.components.*; import com.demcha.compose.document.templates.cv.data.*; import com.demcha.compose.document.templates.core.theme.BrandTheme; @@ -93,7 +94,7 @@ public static DocumentTemplate create(BrandTheme theme) { return new Template(theme); } - private record Template(BrandTheme theme) implements DocumentTemplate { + private record Template(BrandTheme theme) implements ModularCvTemplate { @Override public String id() { @@ -105,6 +106,11 @@ public String displayName() { return DISPLAY_NAME; } + @Override + public CvRenderKit kit() { + return KIT; + } + @Override public void compose(DocumentSession document, CvDocument doc) { Objects.requireNonNull(document, "document"); @@ -161,8 +167,13 @@ private static void renderBody(SectionBuilder host, renderEntry(host, entry, theme); } } else { - throw new IllegalStateException( - "Unknown CvSection subtype: " + section.getClass().getName()); + // A shape this preset has no styled path for — today the runtime + // ModuleSection. Hand it to the canonical dispatcher rather than + // throwing: a section the author put in the document reaches the + // page, which matters more than matching this preset's flavour of + // entry. A preset that wants its own module styling overrides this + // branch, it does not lose the content by omission. + SectionDispatcher.renderBody(host, section, theme, KIT); } } @@ -180,6 +191,31 @@ private static void renderRows(SectionBuilder host, } } + /** + * This preset's own drawing, so a runtime module gets the upper-cased + * two-column entry and the dash-joined project row the rest of the + * document uses rather than the canonical ones. + * + *

    Stateless: every method takes its theme, so one instance serves + * every {@code create(theme)}.

    + */ + private static final CvRenderKit KIT = new CvRenderKit() { + + @Override + public void entry(SectionBuilder host, CvEntry entry, BrandTheme theme) { + renderEntry(host, entry, theme); + } + + @Override + public void row(SectionBuilder host, CvRow row, RowStyle style, BrandTheme theme) { + if (style == RowStyle.BULLETED_STACKED) { + renderPlainProjectRow(host, row, theme); + return; + } + RowRenderer.render(host, row, style, theme); + } + }; + private static void renderPlainProjectRow(SectionBuilder host, CvRow row, BrandTheme theme) { @@ -214,11 +250,11 @@ private static void renderEntry(SectionBuilder section, private static List orderedSections(CvDocument doc) { List sections = doc.sectionsIn(Slot.MAIN); List ordered = new ArrayList<>(); - addIfPresent(ordered, SectionLookup.firstMatching(sections, SUMMARY_KEYS)); - addIfPresent(ordered, SectionLookup.firstMatching(sections, EXPERIENCE_KEYS)); - addIfPresent(ordered, SectionLookup.firstMatching(sections, EDUCATION_KEYS)); - addIfPresent(ordered, SectionLookup.firstMatching(sections, SKILL_KEYS)); - addIfPresent(ordered, SectionLookup.firstMatching(sections, ADDITIONAL_KEYS)); + addIfPresent(ordered, SectionRouter.find(sections, SectionRole.SUMMARY, SUMMARY_KEYS)); + addIfPresent(ordered, SectionRouter.find(sections, SectionRole.EXPERIENCE, EXPERIENCE_KEYS)); + addIfPresent(ordered, SectionRouter.find(sections, SectionRole.EDUCATION, EDUCATION_KEYS)); + addIfPresent(ordered, SectionRouter.find(sections, SectionRole.SKILLS, SKILL_KEYS)); + addIfPresent(ordered, SectionRouter.find(sections, SectionRole.OTHER, ADDITIONAL_KEYS)); for (CvSection section : sections) { addIfPresent(ordered, section); } diff --git a/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/BoxedSections.java b/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/BoxedSections.java index 9cbdd108e..269ac35c7 100644 --- a/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/BoxedSections.java +++ b/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/BoxedSections.java @@ -3,6 +3,8 @@ import com.demcha.compose.document.api.DocumentSession; import com.demcha.compose.document.dsl.PageFlowBuilder; import com.demcha.compose.document.templates.api.DocumentTemplate; +import com.demcha.compose.document.templates.cv.api.ModularCvTemplate; +import com.demcha.compose.document.templates.cv.components.CvRenderKit; import com.demcha.compose.document.templates.cv.components.SectionDispatcher; import com.demcha.compose.document.templates.cv.data.CvDocument; import com.demcha.compose.document.templates.cv.data.CvSection; @@ -83,7 +85,7 @@ public static DocumentTemplate create(BrandTheme theme) { return new Template(theme); } - private record Template(BrandTheme theme) implements DocumentTemplate { + private record Template(BrandTheme theme) implements ModularCvTemplate { @Override public String id() { @@ -95,6 +97,13 @@ public String displayName() { return DISPLAY_NAME; } + @Override + public CvRenderKit kit() { + // This preset renders bodies through the shared dispatcher, so a + // runtime module already looks like the rest of its document. + return CvRenderKit.defaults(); + } + @Override public void compose(DocumentSession document, CvDocument doc) { Objects.requireNonNull(document, "document"); @@ -128,7 +137,7 @@ public void compose(DocumentSession document, CvDocument doc) { SectionHeader.banner(host, sec.title(), theme); }); pageFlow.addSection("CvV2Body_" + idx, - host -> SectionDispatcher.renderBody(host, sec, theme)); + host -> SectionDispatcher.renderBody(host, sec, theme, kit())); } pageFlow.build(); diff --git a/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/CenteredHeadline.java b/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/CenteredHeadline.java index 0cf25e9b3..bb501bd66 100644 --- a/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/CenteredHeadline.java +++ b/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/CenteredHeadline.java @@ -8,7 +8,9 @@ import com.demcha.compose.document.style.DocumentTextDecoration; import com.demcha.compose.document.style.DocumentTextStyle; import com.demcha.compose.document.templates.api.DocumentTemplate; +import com.demcha.compose.document.templates.cv.api.ModularCvTemplate; import com.demcha.compose.document.templates.cv.components.ProjectRenderer; +import com.demcha.compose.document.templates.cv.components.CvRenderKit; import com.demcha.compose.document.templates.cv.components.SectionDispatcher; import com.demcha.compose.document.templates.cv.data.*; import com.demcha.compose.document.templates.core.theme.BrandTheme; @@ -109,7 +111,7 @@ public static DocumentTemplate create(BrandTheme theme) { return new Template(theme); } - private record Template(BrandTheme theme) implements DocumentTemplate { + private record Template(BrandTheme theme) implements ModularCvTemplate { @Override public String id() { @@ -121,6 +123,13 @@ public String displayName() { return DISPLAY_NAME; } + @Override + public CvRenderKit kit() { + // This preset renders bodies through the shared dispatcher, so a + // runtime module already looks like the rest of its document. + return CvRenderKit.defaults(); + } + @Override public void compose(DocumentSession document, CvDocument doc) { Objects.requireNonNull(document, "document"); @@ -184,7 +193,7 @@ private void renderBody(SectionBuilder host, CvSection sec) { } return; } - SectionDispatcher.renderBody(host, sec, theme); + SectionDispatcher.renderBody(host, sec, theme, kit()); } private void renderStackedProject(SectionBuilder host, CvRow row) { diff --git a/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/ClassicSerif.java b/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/ClassicSerif.java index e4dbab8da..22f93098c 100644 --- a/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/ClassicSerif.java +++ b/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/ClassicSerif.java @@ -118,16 +118,16 @@ public void compose(DocumentSession document, CvDocument doc) { .spacing(theme.spacing().pageFlowSpacing()); addHeader(flow, doc, width); - addSummary(flow, SectionLookup.firstMatching(sections, SUMMARY_KEYS)); - addCoverSkillsModule(flow, SectionLookup.firstMatching(sections, SKILL_KEYS)); + addSummary(flow, SectionRouter.paragraph(sections, SectionRole.SUMMARY, SUMMARY_KEYS)); + addCoverSkillsModule(flow, SectionRouter.skills(sections, SectionRole.SKILLS, SKILL_KEYS)); addLinearModule(flow, "Experience", - SectionLookup.firstMatching(sections, EXPERIENCE_KEYS)); + SectionRouter.find(sections, SectionRole.EXPERIENCE, EXPERIENCE_KEYS)); addLinearModule(flow, "Projects", - SectionLookup.firstMatching(sections, PROJECT_KEYS)); + SectionRouter.find(sections, SectionRole.PROJECTS, PROJECT_KEYS)); addLinearModule(flow, "Education", - SectionLookup.firstMatching(sections, EDUCATION_KEYS)); + SectionRouter.find(sections, SectionRole.EDUCATION, EDUCATION_KEYS)); addLinearModule(flow, "Additional", - SectionLookup.firstMatching(sections, ADDITIONAL_KEYS)); + SectionRouter.find(sections, SectionRole.OTHER, ADDITIONAL_KEYS)); flow.build(); } @@ -242,12 +242,49 @@ private void renderDetailBody(SectionBuilder host, CvSection section) { new CvRow(group.category(), group.skillsInline())); } } else { - throw new IllegalStateException( - "Unknown CvSection subtype: " - + section.getClass().getName()); + // A shape this preset has no serif-styled path for — today the + // runtime ModuleSection. The canonical dispatcher renders it + // rather than the render failing on a section the author + // legitimately added. + SectionDispatcher.renderBody(host, section, theme, kit()); } } + /** + * This preset's own drawing, so a runtime module routed into one + * of its modules gets the serif entry and the project row the + * rest of the document uses. + * + *

    Not a {@code ModularCvTemplate}: this preset composes six + * fixed modules and finds each by matching headings, so a section + * it does not recognise never reaches a renderer at all. Drawing + * modules well and rendering every module are different promises, + * and it can only make the first.

    + * + *

    Built per call rather than cached: a record's methods are + * only reachable from an instance, and the kit closes over this + * template's theme.

    + */ + private CvRenderKit kit() { + return new CvRenderKit() { + + @Override + public void entry(SectionBuilder host, CvEntry entry, BrandTheme unused) { + renderEntry(host, entry); + } + + @Override + public void row(SectionBuilder host, CvRow row, RowStyle style, + BrandTheme unused) { + if (style == RowStyle.BULLETED_STACKED) { + renderProject(host, row); + return; + } + renderKeyValue(host, row); + } + }; + } + private void renderEntries(SectionBuilder host, EntriesSection entries) { for (int i = 0; i < entries.entries().size(); i++) { if (i > 0) { diff --git a/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/CompactMono.java b/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/CompactMono.java index 506a112cc..00557f1dd 100644 --- a/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/CompactMono.java +++ b/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/CompactMono.java @@ -168,16 +168,16 @@ private void addRail(SectionBuilder rail, List sections) { .padding(new DocumentInsets(11, 11, 13, 11)) .fillColor(theme.palette().banner()) .accentLeft(ACCENT, 3.0); - addRailSkills(rail, SectionLookup.firstMatching(sections, SKILL_KEYS)); - addRailEducation(rail, SectionLookup.firstMatching(sections, EDUCATION_KEYS)); - addRailAdditional(rail, SectionLookup.firstMatching(sections, ADDITIONAL_KEYS)); + addRailSkills(rail, SectionRouter.skills(sections, SectionRole.SKILLS, SKILL_KEYS)); + addRailEducation(rail, SectionRouter.entries(sections, SectionRole.EDUCATION, EDUCATION_KEYS)); + addRailAdditional(rail, SectionRouter.rows(sections, SectionRole.OTHER, ADDITIONAL_KEYS, RowStyle.PLAIN)); } private void addMain(SectionBuilder main, List sections) { main.spacing(8); - addProfile(main, SectionLookup.firstMatching(sections, SUMMARY_KEYS)); - addExperience(main, SectionLookup.firstMatching(sections, EXPERIENCE_KEYS)); - addProjects(main, SectionLookup.firstMatching(sections, PROJECT_KEYS)); + addProfile(main, SectionRouter.paragraph(sections, SectionRole.SUMMARY, SUMMARY_KEYS)); + addExperience(main, SectionRouter.entries(sections, SectionRole.EXPERIENCE, EXPERIENCE_KEYS)); + addProjects(main, SectionRouter.rows(sections, SectionRole.PROJECTS, PROJECT_KEYS, RowStyle.BULLETED_STACKED)); } private void addRailSkills(SectionBuilder parent, CvSection section) { diff --git a/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/CvTemplates.java b/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/CvTemplates.java new file mode 100644 index 000000000..a6d6417ff --- /dev/null +++ b/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/CvTemplates.java @@ -0,0 +1,167 @@ +package com.demcha.compose.document.templates.cv.presets; + +import com.demcha.compose.document.templates.api.DocumentTemplate; +import com.demcha.compose.document.templates.cv.api.ModularCvTemplate; +import com.demcha.compose.document.templates.cv.data.CvDocument; + +import java.util.ArrayList; +import java.util.List; +import java.util.Optional; +import java.util.function.Supplier; + +/** + * Every shipped CV preset, by the id it publishes. + * + *

    A preset is a class, and picking one at compile time is a constructor + * call. Picking one at runtime — from a dropdown, a config file, a + * request field — is a lookup, and until now every caller wrote its own: + * a switch, a map, a list that has to be remembered when a preset ships. + * The consumer this model exists for keeps exactly such a map in another + * repository, where nothing tells it a preset was added.

    + * + * 
    {@code
+ * CvTemplates.byId("modern-professional")
+ *            .orElseThrow()
+ *            .compose(session, doc);
+ * }
    + * + *

    {@link #modular()} is the list to offer when the document is assembled + * at runtime: the presets that promise to render whatever they are handed + * (see {@link ModularCvTemplate}). The rest stay in {@link #all()} for + * callers who build the canonical sections by hand — they are not lesser + * templates, they are templates with a fixed idea of what a CV contains.

    + * + *

    Every lookup builds a fresh template with the preset's own default + * theme; a caller wanting a variant calls that preset's + * {@code create(BrandTheme)} directly. {@code CvTemplatesCoverageTest} holds + * this catalogue to the presets package, so a preset added and not + * registered fails the build rather than staying invisible to every runtime + * caller.

    + * + * @since 2.3.0 + */ +public final class CvTemplates { + + /** + * One catalogue entry. Keeping the id, the margin, and the factory + * together is what makes the catalogue impossible to half-update: there + * is one list, and a preset is in it or it is not. + */ + private record Preset(String id, double recommendedMargin, + Supplier> factory) { + } + + /** The catalogue, in the order a gallery shows it. */ + private static final List PRESETS = List.of( + new Preset(ModernProfessional.ID, ModernProfessional.RECOMMENDED_MARGIN, + ModernProfessional::create), + new Preset(BoxedSections.ID, BoxedSections.RECOMMENDED_MARGIN, + BoxedSections::create), + new Preset(MinimalUnderlined.ID, MinimalUnderlined.RECOMMENDED_MARGIN, + MinimalUnderlined::create), + new Preset(Executive.ID, Executive.RECOMMENDED_MARGIN, Executive::create), + new Preset(CenteredHeadline.ID, CenteredHeadline.RECOMMENDED_MARGIN, + CenteredHeadline::create), + new Preset(BlueBanner.ID, BlueBanner.RECOMMENDED_MARGIN, BlueBanner::create), + new Preset(ClassicSerif.ID, ClassicSerif.RECOMMENDED_MARGIN, ClassicSerif::create), + new Preset(EditorialBlue.ID, EditorialBlue.RECOMMENDED_MARGIN, + EditorialBlue::create), + new Preset(CompactMono.ID, CompactMono.RECOMMENDED_MARGIN, CompactMono::create), + new Preset(EngineeringResume.ID, EngineeringResume.RECOMMENDED_MARGIN, + EngineeringResume::create), + new Preset(NordicClean.ID, NordicClean.RECOMMENDED_MARGIN, NordicClean::create), + new Preset(Panel.ID, Panel.RECOMMENDED_MARGIN, Panel::create), + new Preset(TimelineMinimal.ID, TimelineMinimal.RECOMMENDED_MARGIN, + TimelineMinimal::create), + new Preset(MonogramSidebar.ID, MonogramSidebar.RECOMMENDED_MARGIN, + MonogramSidebar::create), + new Preset(SidebarPortrait.ID, SidebarPortrait.RECOMMENDED_MARGIN, + SidebarPortrait::create), + new Preset(MintEditorial.ID, MintEditorial.RECOMMENDED_MARGIN, + MintEditorial::create)); + + private CvTemplates() { + } + + /** + * The template published under {@code id}, built with its own default + * theme. + * + * @param id a preset id such as {@code "modern-professional"}; leading + * and trailing whitespace is ignored. An unknown or null id + * yields an empty result rather than an exception — an id + * arriving from a config file or a request is input to + * validate, not a programming error + * @return the template, or empty when no preset publishes that id + */ + public static Optional> byId(String id) { + return find(id).map(preset -> preset.factory().get()); + } + + /** + * Every shipped preset, freshly built, in gallery order. + * + * @return one template per preset + */ + public static List> all() { + List> templates = new ArrayList<>(PRESETS.size()); + for (Preset preset : PRESETS) { + templates.add(preset.factory().get()); + } + return List.copyOf(templates); + } + + /** + * The presets that render whatever the document hands them — the ones + * to offer for a CV assembled at runtime. + * + * @return one template per preset implementing {@link ModularCvTemplate}, + * in gallery order + */ + public static List modular() { + List templates = new ArrayList<>(); + for (DocumentTemplate template : all()) { + if (template instanceof ModularCvTemplate modular) { + templates.add(modular); + } + } + return List.copyOf(templates); + } + + /** + * Every registered preset id, in gallery order. + * + * @return the ids {@link #byId(String)} answers to + */ + public static List ids() { + List ids = new ArrayList<>(PRESETS.size()); + for (Preset preset : PRESETS) { + ids.add(preset.id()); + } + return List.copyOf(ids); + } + + /** + * The page margin the preset was designed at, in points — which a caller + * needs while building the session, before it has a template. + * + * @param id a preset id + * @return the margin, or empty when no preset publishes that id + */ + public static Optional recommendedMargin(String id) { + return find(id).map(Preset::recommendedMargin); + } + + private static Optional find(String id) { + if (id == null) { + return Optional.empty(); + } + String wanted = id.trim(); + for (Preset preset : PRESETS) { + if (preset.id().equals(wanted)) { + return Optional.of(preset); + } + } + return Optional.empty(); + } +} diff --git a/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/EditorialBlue.java b/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/EditorialBlue.java index 42637967f..c8cb9efe9 100644 --- a/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/EditorialBlue.java +++ b/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/EditorialBlue.java @@ -12,6 +12,7 @@ import com.demcha.compose.document.style.DocumentTextDecoration; import com.demcha.compose.document.style.DocumentTextStyle; import com.demcha.compose.document.templates.api.DocumentTemplate; +import com.demcha.compose.document.templates.cv.api.ModularCvTemplate; import com.demcha.compose.document.templates.cv.components.*; import com.demcha.compose.document.templates.cv.data.*; import com.demcha.compose.document.templates.core.theme.BrandTheme; @@ -87,7 +88,7 @@ public static DocumentTemplate create(BrandTheme theme) { return new Template(theme); } - private record Template(BrandTheme theme) implements DocumentTemplate { + private record Template(BrandTheme theme) implements ModularCvTemplate { @Override public String id() { @@ -121,7 +122,7 @@ public void compose(DocumentSession document, CvDocument doc) { CvSection section = sections.get(i); String name = "CvV2EditorialBlue_" + i; FlowSectionHeader.label(pageFlow, name + "_Title", - displayTitle(section.title()), width, theme, + headingFor(section), width, theme, sectionTitleStyle(), new DocumentInsets(8, 0, 0, 0), new DocumentInsets(7, 0, 5, 0), DocumentInsets.zero(), true); @@ -146,6 +147,13 @@ private void renderSectionBody(SectionBuilder section, CvSection cvSection, renderEntries(section, entries); } else if (cvSection instanceof RowsSection rows) { renderRows(section, rows); + } else { + // A shape this preset has no editorial-styled path for — today + // the runtime ModuleSection. Without this branch the section + // would render as nothing at all: an empty heading over blank + // space, which reads as a finished CV that quietly lost a + // section. + SectionDispatcher.renderBody(section, cvSection, theme, kit()); } } @@ -165,6 +173,43 @@ private void renderEntries(SectionBuilder section, EntriesSection entries) { } } + /** + * This preset's own drawing, so a runtime module gets the + * editorial entry, project, and key/value shapes. + * + *

    Entries take the experience styling. The preset picks + * between its experience and education variants by sniffing a + * section's heading, which is exactly what a module carries a + * role to avoid; until the kit is handed that role, one of the + * two has to be the answer, and experience is the shape most + * modules take.

    + */ + @Override + public CvRenderKit kit() { + return new CvRenderKit() { + + @Override + public void entry(SectionBuilder host, CvEntry entry, BrandTheme unused) { + renderExperienceEntry(host, entry); + } + + @Override + public void row(SectionBuilder host, CvRow row, RowStyle style, + BrandTheme unused) { + if (style == RowStyle.BULLETED_STACKED) { + renderProject(host, row); + return; + } + renderKeyValue(host, row); + } + + @Override + public void paragraph(SectionBuilder host, String text, BrandTheme unused) { + renderParagraph(host, text, 1.6); + } + }; + } + private void renderExperienceEntry(SectionBuilder section, CvEntry entry) { DocumentTextStyle titleStyle = TextStyles.of(FontName.HELVETICA, 11.0, DocumentTextDecoration.BOLD, NAME_COLOR); @@ -274,6 +319,21 @@ private void addFooter(PageFlowBuilder pageFlow, double width) { .margin(DocumentInsets.top(2)))); } + /** + * The heading to print. A module carries a heading the author + * chose and a role that already says what the section is, so it + * prints as written; the keyword rename below exists to give the + * canonical sections this preset's editorial vocabulary, and + * applying it to a module would retitle "Certifications & Awards" + * as "EDUCATION" — which is exactly the promise + * {@code ModularCvTemplate} makes it must not do. + */ + private String headingFor(CvSection section) { + return section instanceof ModuleSection + ? section.title().toUpperCase(Locale.ROOT) + : displayTitle(section.title()); + } + private String displayTitle(String title) { String normalized = SectionLookup.normalize(title); if (normalized.contains("summary") || normalized.contains("profile")) { diff --git a/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/EngineeringResume.java b/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/EngineeringResume.java index 40a190c87..f3ff748ee 100644 --- a/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/EngineeringResume.java +++ b/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/EngineeringResume.java @@ -12,6 +12,7 @@ import com.demcha.compose.document.templates.core.text.TextStyles; import com.demcha.compose.document.templates.core.text.MarkdownInline; import com.demcha.compose.document.templates.cv.components.ProjectLabel; +import com.demcha.compose.document.templates.cv.components.SectionRouter; import com.demcha.compose.document.templates.cv.components.SectionLookup; import com.demcha.compose.document.templates.cv.data.*; import com.demcha.compose.document.templates.core.theme.BrandTheme; @@ -272,17 +273,12 @@ private static String headerSubtitleText(CvIdentity identity) { // -- Body 2-column ------------------------------------------------- private void addBody(PageFlowBuilder flow, List sections) { - CvSection skills = SectionLookup.firstMatching(sections, SKILL_KEYS); - CvSection education = SectionLookup.firstMatching(sections, - EDUCATION_KEYS); - CvSection additional = SectionLookup.firstMatching(sections, - ADDITIONAL_KEYS); - CvSection summary = SectionLookup.firstMatching(sections, - SUMMARY_KEYS); - CvSection experience = SectionLookup.firstMatching(sections, - EXPERIENCE_KEYS); - CvSection projects = SectionLookup.firstMatching(sections, - PROJECT_KEYS); + CvSection skills = SectionRouter.skills(sections, SectionRole.SKILLS, SKILL_KEYS); + CvSection education = SectionRouter.entries(sections, SectionRole.EDUCATION, EDUCATION_KEYS); + CvSection additional = SectionRouter.rows(sections, SectionRole.OTHER, ADDITIONAL_KEYS, RowStyle.PLAIN); + CvSection summary = SectionRouter.paragraph(sections, SectionRole.SUMMARY, SUMMARY_KEYS); + CvSection experience = SectionRouter.entries(sections, SectionRole.EXPERIENCE, EXPERIENCE_KEYS); + CvSection projects = SectionRouter.rows(sections, SectionRole.PROJECTS, PROJECT_KEYS, RowStyle.BULLETED_STACKED); flow.addRow("CvV2EngineeringResumeBody", row -> row .spacing(14) diff --git a/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/Executive.java b/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/Executive.java index 95ae92d35..7842cdabf 100644 --- a/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/Executive.java +++ b/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/Executive.java @@ -12,7 +12,9 @@ import com.demcha.compose.document.style.DocumentTextDecoration; import com.demcha.compose.document.style.DocumentTextStyle; import com.demcha.compose.document.templates.api.DocumentTemplate; +import com.demcha.compose.document.templates.cv.api.ModularCvTemplate; import com.demcha.compose.document.templates.core.text.TextStyles; +import com.demcha.compose.document.templates.cv.components.CvRenderKit; import com.demcha.compose.document.templates.cv.components.SectionDispatcher; import com.demcha.compose.document.templates.cv.data.*; import com.demcha.compose.document.templates.core.theme.BrandTheme; @@ -96,7 +98,7 @@ public static DocumentTemplate create(BrandTheme theme) { return new Template(theme); } - private record Template(BrandTheme theme) implements DocumentTemplate { + private record Template(BrandTheme theme) implements ModularCvTemplate { @Override public String id() { @@ -108,6 +110,13 @@ public String displayName() { return DISPLAY_NAME; } + @Override + public CvRenderKit kit() { + // This preset renders bodies through the shared dispatcher, so a + // runtime module already looks like the rest of its document. + return CvRenderKit.defaults(); + } + @Override public void compose(DocumentSession document, CvDocument doc) { Objects.requireNonNull(document, "document"); @@ -132,7 +141,7 @@ public void compose(DocumentSession document, CvDocument doc) { ACCENT, theme); }); flow.addSection("CvV2ExecutiveBody_" + idx, host -> - SectionDispatcher.renderBody(host, sec, theme)); + SectionDispatcher.renderBody(host, sec, theme, kit())); } flow.build(); diff --git a/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/MinimalUnderlined.java b/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/MinimalUnderlined.java index a93206767..720fa0820 100644 --- a/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/MinimalUnderlined.java +++ b/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/MinimalUnderlined.java @@ -3,6 +3,8 @@ import com.demcha.compose.document.api.DocumentSession; import com.demcha.compose.document.dsl.PageFlowBuilder; import com.demcha.compose.document.templates.api.DocumentTemplate; +import com.demcha.compose.document.templates.cv.api.ModularCvTemplate; +import com.demcha.compose.document.templates.cv.components.CvRenderKit; import com.demcha.compose.document.templates.cv.components.SectionDispatcher; import com.demcha.compose.document.templates.cv.data.CvDocument; import com.demcha.compose.document.templates.cv.data.CvSection; @@ -83,7 +85,7 @@ public static DocumentTemplate create(BrandTheme theme) { return new Template(theme); } - private record Template(BrandTheme theme) implements DocumentTemplate { + private record Template(BrandTheme theme) implements ModularCvTemplate { @Override public String id() { @@ -95,6 +97,13 @@ public String displayName() { return DISPLAY_NAME; } + @Override + public CvRenderKit kit() { + // This preset renders bodies through the shared dispatcher, so a + // runtime module already looks like the rest of its document. + return CvRenderKit.defaults(); + } + @Override public void compose(DocumentSession document, CvDocument doc) { Objects.requireNonNull(document, "document"); @@ -123,7 +132,7 @@ public void compose(DocumentSession document, CvDocument doc) { SectionHeader.underlined(host, sec.title(), theme); }); pageFlow.addSection("Body_" + idx, host -> - SectionDispatcher.renderBody(host, sec, theme)); + SectionDispatcher.renderBody(host, sec, theme, kit())); } pageFlow.build(); diff --git a/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/MintEditorial.java b/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/MintEditorial.java index 261bf077b..072e4ae77 100644 --- a/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/MintEditorial.java +++ b/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/MintEditorial.java @@ -18,6 +18,7 @@ import com.demcha.compose.document.templates.api.DocumentTemplate; import com.demcha.compose.document.templates.core.text.TextStyles; import com.demcha.compose.document.templates.core.text.MarkdownInline; +import com.demcha.compose.document.templates.cv.components.SectionRouter; import com.demcha.compose.document.templates.cv.components.SectionLookup; import com.demcha.compose.document.templates.core.text.TextOrnaments; import com.demcha.compose.document.templates.cv.data.*; @@ -487,13 +488,13 @@ public void compose(DocumentSession document, CvDocument doc) { List sections = doc.sectionsIn(Slot.MAIN); CvIdentity identity = doc.identity(); - CvSection interests = SectionLookup.firstMatching(sections, INTERESTS_KEYS); - CvSection education = SectionLookup.firstMatching(sections, EDUCATION_KEYS); - CvSection skills = SectionLookup.firstMatching(sections, SKILL_KEYS); - CvSection profile = SectionLookup.firstMatching(sections, SUMMARY_KEYS); - CvSection experience = SectionLookup.firstMatching(sections, EXPERIENCE_KEYS); - CvSection awards = SectionLookup.firstMatching(sections, AWARDS_KEYS); - CvSection references = SectionLookup.firstMatching(sections, REFERENCES_KEYS); + CvSection interests = SectionRouter.rows(sections, SectionRole.OTHER, INTERESTS_KEYS, RowStyle.PLAIN); + CvSection education = SectionRouter.entries(sections, SectionRole.EDUCATION, EDUCATION_KEYS); + CvSection skills = SectionRouter.skills(sections, SectionRole.SKILLS, SKILL_KEYS); + CvSection profile = SectionRouter.paragraph(sections, SectionRole.SUMMARY, SUMMARY_KEYS); + CvSection experience = SectionRouter.entries(sections, SectionRole.EXPERIENCE, EXPERIENCE_KEYS); + CvSection awards = SectionRouter.rows(sections, SectionRole.OTHER, AWARDS_KEYS, RowStyle.PLAIN); + CvSection references = SectionRouter.rows(sections, SectionRole.OTHER, REFERENCES_KEYS, RowStyle.PLAIN); List experienceEntries = entriesOf(experience); List experiencePage1 = experienceEntries.stream() diff --git a/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/ModernProfessional.java b/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/ModernProfessional.java index b1ab62a94..4c2a81191 100644 --- a/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/ModernProfessional.java +++ b/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/ModernProfessional.java @@ -6,6 +6,8 @@ import com.demcha.compose.document.style.DocumentTextDecoration; import com.demcha.compose.document.style.DocumentTextStyle; import com.demcha.compose.document.templates.api.DocumentTemplate; +import com.demcha.compose.document.templates.cv.api.ModularCvTemplate; +import com.demcha.compose.document.templates.cv.components.CvRenderKit; import com.demcha.compose.document.templates.cv.components.SectionDispatcher; import com.demcha.compose.document.templates.cv.data.CvDocument; import com.demcha.compose.document.templates.cv.data.CvSection; @@ -109,7 +111,7 @@ public static DocumentTemplate create(BrandTheme theme) { return new Template(theme); } - private record Template(BrandTheme theme) implements DocumentTemplate { + private record Template(BrandTheme theme) implements ModularCvTemplate { @Override public String id() { @@ -121,6 +123,13 @@ public String displayName() { return DISPLAY_NAME; } + @Override + public CvRenderKit kit() { + // This preset renders bodies through the shared dispatcher, so a + // runtime module already looks like the rest of its document. + return CvRenderKit.defaults(); + } + @Override public void compose(DocumentSession document, CvDocument doc) { Objects.requireNonNull(document, "document"); @@ -178,7 +187,7 @@ public void compose(DocumentSession document, CvDocument doc) { SectionHeader.flat(host, sec.title(), SECTION_TITLE_COLOR, theme); }); pageFlow.addSection("Body_" + idx, host -> - SectionDispatcher.renderBody(host, sec, theme)); + SectionDispatcher.renderBody(host, sec, theme, kit())); } pageFlow.build(); diff --git a/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/MonogramSidebar.java b/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/MonogramSidebar.java index 09acff8d1..4dea3030d 100644 --- a/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/MonogramSidebar.java +++ b/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/MonogramSidebar.java @@ -3,6 +3,7 @@ import com.demcha.compose.document.templates.core.identity.Link; import com.demcha.compose.document.templates.core.text.MarkdownInline; +import com.demcha.compose.document.templates.core.page.ContinuationSafeArea; import com.demcha.compose.document.templates.core.text.TextOrnaments; import com.demcha.compose.document.templates.core.text.TextStyles; @@ -42,6 +43,28 @@ * any preset-side filler logic. The preset draws its visual ornaments * (monogram ring, section rules) inline because none of these visuals * are shared with another v2 preset today.

    + * + *

    The body is a column flow, so each column continues on the next page and the + * preset draws every entry of the sections it recognises. It used to be a row — + * one atomic band that had to fit the page it started on — and carried per-section + * caps (two jobs, two degrees, seven skills, three projects, three additional rows) + * to stay under that bound; the rest was dropped without a word. Both are gone. A + * section this preset has no slot for is still dropped, as in every preset that + * composes a fixed layout.

    + * + *

    {@code compose(...)} sets two session-wide settings and replaces + * whatever the caller had set: the page backgrounds above, and a page-margin rule + * reserving a printer-safe top inset on the pages after the first. The columns' + * padding is an edge of the columns rather than of each page, so without that rule a + * body running past page one would resume at the trimmed edge — the safe area a zero + * {@link #RECOMMENDED_MARGIN} gives up along the top of the sheet as well as the + * sides.

    + * + *

    The monogram badge is sized for A4 and needs a page about 450pt wide or more: + * below that the sidebar column is narrower than the {@value #MONOGRAM_DIAMETER}pt + * badge and the layout fails rather than drawing it. A row slot did not check a + * child's measured width, so a narrower page used to come out with the badge laid + * over the main column.

    */ public final class MonogramSidebar { @@ -94,6 +117,13 @@ public final class MonogramSidebar { private static final double MONOGRAM_DIAMETER = 122; private static final double SIDEBAR_RULE_WIDTH = 118; + + /** + * Vertical spacing inside each column. The heading groups repeat their column's + * value, so wrapping a heading in its own section leaves the rhythm as it was. + */ + private static final double SIDEBAR_SPACING = 8.0; + private static final double MAIN_CONTENT_SPACING = 5.0; private static final double CONTACT_ICON_SIZE = 22; /** @@ -101,13 +131,7 @@ public final class MonogramSidebar { */ private static final double SIDEBAR_WIDTH_RATIO = 0.33; - private static final double MAIN_SECTION_RULE_WIDTH = 355.0; - private static final int EDUCATION_LIMIT = 2; - private static final int SKILL_LIMIT = 7; - private static final int EXPERIENCE_LIMIT = 2; - private static final int PROJECT_LIMIT = 3; - private static final int ADDITIONAL_LIMIT = 3; private static final String CONTACT_ICON_ROOT = "/templates/cv/monogram-sidebar/icons/"; @@ -316,18 +340,10 @@ public void compose(DocumentSession document, CvDocument doc) { Objects.requireNonNull(doc, "doc"); double pageInnerWidth = document.canvas().innerWidth(); - double sidebarOuterWidth = pageInnerWidth * 0.33; + double sidebarOuterWidth = pageInnerWidth * SIDEBAR_WIDTH_RATIO; double sidebarHorizontalPadding = 13.0 * 2.0; double sidebarInnerWidth = Math.max(0.0, sidebarOuterWidth - sidebarHorizontalPadding); - double mainOuterWidth = pageInnerWidth - sidebarOuterWidth; - // Main section has 20pt left + 18pt right padding (see addMain). - // Spacer width must be the content-area width so the inner - // content fills exactly the section's allocated outer width - // (= mainOuterWidth) — passing the outer width directly - // would overflow because outer = content + padding. - double mainContentWidth = Math.max(0.0, - mainOuterWidth - (20.0 + 18.0)); List sections = doc.sectionsIn(Slot.MAIN); // Paint the two-column chrome via pageBackgrounds — the @@ -340,21 +356,30 @@ public void compose(DocumentSession document, CvDocument doc) { PageBackgroundFill.rightColumn(1.0 - SIDEBAR_WIDTH_RATIO, mainFill))); + // The columns' padding is an edge of the columns, not of each page, so + // it holds the first page's content off the trimmed edge and says + // nothing about the second's. RECOMMENDED_MARGIN is zero so the sidebar + // fill can reach the paper edge; this buys back the top of it on the + // pages the body continues onto. + ContinuationSafeArea.applyTo(document, 2, ContinuationSafeArea.PRINTER_SAFE_TOP); + document.dsl() .pageFlow() .name("CvV2MonogramSidebarRoot") .spacing(theme.spacing().pageFlowSpacing()) .padding(DocumentInsets.zero()) - .addRow("CvV2MonogramSidebarFrame", row -> row - .spacing(0) + // A column flow rather than a row: both columns keep flowing + // onto the next page instead of having to fit the first one. + .addColumnFlow("CvV2MonogramSidebarBody", body -> body + .gap(0) .weights(SIDEBAR_WIDTH_RATIO, 1.0 - SIDEBAR_WIDTH_RATIO) - .addSection("CvV2MonogramSidebarSidebar", + .addColumn("CvV2MonogramSidebarSidebar", section -> addSidebar(section, doc, sections, sidebarInnerWidth)) - .addSection("CvV2MonogramSidebarMain", + .addColumn("CvV2MonogramSidebarMain", section -> addMain(section, doc.identity(), - sections, mainContentWidth))) + sections))) .build(); } @@ -367,7 +392,7 @@ private void addSidebar(SectionBuilder section, CvDocument doc, // edge-to-edge on every page, including continuation // pages. Top padding establishes the breathing room above // the monogram badge. - section.spacing(8) + section.spacing(SIDEBAR_SPACING) .padding(new DocumentInsets(36, 13, 0, 13)); addMonogramBlock(section, initials(doc.identity().name()), @@ -376,14 +401,13 @@ private void addSidebar(SectionBuilder section, CvDocument doc, addSidebarHeader(section, "CONTACT", innerWidth); addContactBlock(section, doc.identity()); - CvSection education = SectionLookup.firstMatching(sections, - EDUCATION_KEYS); + CvSection education = SectionRouter.entries(sections, SectionRole.EDUCATION, EDUCATION_KEYS); if (hasContent(education)) { addSidebarHeader(section, education.title(), innerWidth); addEducationEntries(section, education); } - CvSection skills = SectionLookup.firstMatching(sections, SKILL_KEYS); + CvSection skills = SectionRouter.skills(sections, SectionRole.SKILLS, SKILL_KEYS); if (hasContent(skills)) { addSidebarHeader(section, "EXPERTISE", innerWidth); addSkillsList(section, skills); @@ -420,24 +444,33 @@ private void addMonogramBlock(SectionBuilder section, .layer(badge, LayerAlign.TOP_CENTER)); } + /** + * Heading + rule as one keep-with-next group. The sidebar is the column that + * outgrows the page on a dense CV, so a heading here is the one most likely + * to be left at the foot of a page with its list overleaf — or to be parted + * from its own rule, which an atomic row could never do. + */ private void addSidebarHeader(SectionBuilder section, String title, double innerWidth) { if (title == null || title.isBlank()) { return; } - section.addParagraph(paragraph -> paragraph - .text(TextOrnaments.spacedUpper(title)) - .textStyle(sidebarHeaderStyle()) - .align(TextAlign.CENTER) - .lineSpacing(1.2) - .margin(DocumentInsets.top(6))); double ruleWidth = Math.min(innerWidth, SIDEBAR_RULE_WIDTH); double sideInset = Math.max(0.0, (innerWidth - ruleWidth) / 2.0); - section.addLine(line -> line - .horizontal(ruleWidth) - .color(theme.palette().rule()) - .thickness(0.45) - .margin(new DocumentInsets(1, sideInset, 2, sideInset))); + section.addSection("CvV2MonogramSidebarSidebarHeading", heading -> heading + .spacing(SIDEBAR_SPACING) + .keepWithNext() + .addParagraph(paragraph -> paragraph + .text(TextOrnaments.spacedUpper(title)) + .textStyle(sidebarHeaderStyle()) + .align(TextAlign.CENTER) + .lineSpacing(1.2) + .margin(DocumentInsets.top(6))) + .addLine(line -> line + .horizontal(ruleWidth) + .color(theme.palette().rule()) + .thickness(0.45) + .margin(new DocumentInsets(1, sideInset, 2, sideInset)))); } private void addContactBlock(SectionBuilder section, CvIdentity identity) { @@ -486,7 +519,7 @@ private void addEducationEntries(SectionBuilder section, DocumentTextStyle metaStyle = sidebarEntryDateStyle(); List list = entries.entries(); - for (int i = 0; i < Math.min(list.size(), EDUCATION_LIMIT); i++) { + for (int i = 0; i < list.size(); i++) { CvEntry entry = list.get(i); section.addParagraph(paragraph -> paragraph .textStyle(headingStyle) @@ -519,7 +552,7 @@ private void addSkillsList(SectionBuilder section, CvSection skillSection) { } DocumentTextStyle skillStyle = sidebarSkillStyle(); List tokens = skillTokens(skills); - for (String token : tokens.stream().limit(SKILL_LIMIT).toList()) { + for (String token : tokens) { section.addParagraph(paragraph -> paragraph .text(MarkdownInline.plainText(token)) .textStyle(skillStyle) @@ -532,16 +565,15 @@ private void addSkillsList(SectionBuilder section, CvSection skillSection) { // -- Main column --------------------------------------------------- private void addMain(SectionBuilder section, CvIdentity identity, - List sections, double anchorWidth) { + List sections) { // No fillColor — the page background defaults to white, so // the right column is naturally white from top to bottom. - section.spacing(5) + section.spacing(MAIN_CONTENT_SPACING) .padding(new DocumentInsets(38, 20, 24, 18)); addNameBlock(section, identity); - CvSection profile = SectionLookup.firstMatching(sections, - SUMMARY_KEYS); + CvSection profile = SectionRouter.paragraph(sections, SectionRole.SUMMARY, SUMMARY_KEYS); if (hasContent(profile)) { addMainSectionHeader(section, profile.title().isBlank() @@ -550,8 +582,7 @@ private void addMain(SectionBuilder section, CvIdentity identity, addProfileBody(section, profile); } - CvSection experience = SectionLookup.firstMatching(sections, - EXPERIENCE_KEYS); + CvSection experience = SectionRouter.entries(sections, SectionRole.EXPERIENCE, EXPERIENCE_KEYS); if (hasContent(experience)) { addMainSectionHeader(section, experience.title().isBlank() @@ -560,8 +591,7 @@ private void addMain(SectionBuilder section, CvIdentity identity, addExperienceEntries(section, experience); } - CvSection projects = SectionLookup.firstMatching(sections, - PROJECT_KEYS); + CvSection projects = SectionRouter.rows(sections, SectionRole.PROJECTS, PROJECT_KEYS, RowStyle.BULLETED_STACKED); if (hasContent(projects)) { addMainSectionHeader(section, projects.title().isBlank() @@ -570,8 +600,7 @@ private void addMain(SectionBuilder section, CvIdentity identity, addProjectsList(section, projects); } - CvSection additional = SectionLookup.firstMatching(sections, - ADDITIONAL_KEYS); + CvSection additional = SectionRouter.rows(sections, SectionRole.OTHER, ADDITIONAL_KEYS, RowStyle.PLAIN); if (hasContent(additional)) { addMainSectionHeader(section, additional.title().isBlank() @@ -590,7 +619,7 @@ private void addProjectsList(SectionBuilder section, DocumentTextStyle stackStyle = mainEntryDateStyle(); DocumentTextStyle bodyStyle = mainBodyStyle(); List list = rows.rows(); - for (int i = 0; i < Math.min(list.size(), PROJECT_LIMIT); i++) { + for (int i = 0; i < list.size(); i++) { ProjectRenderer.inline(section, list.get(i), titleStyle, stackStyle, bodyStyle, theme.typography().bodyLineSpacing(), @@ -606,7 +635,7 @@ private void addAdditionalList(SectionBuilder section, DocumentTextStyle labelStyle = mainEntryTitleStyle(); DocumentTextStyle valueStyle = mainBodyStyle(); List list = rows.rows(); - for (int i = 0; i < Math.min(list.size(), ADDITIONAL_LIMIT); i++) { + for (int i = 0; i < list.size(); i++) { CvRow row = list.get(i); LabelValueRenderer.render(section, row.label(), row.body(), labelStyle, valueStyle, @@ -653,20 +682,35 @@ private void addNameBlock(SectionBuilder section, CvIdentity identity) { .margin(new DocumentInsets(12, 0, 22, 0))); } + /** + * Title + rule as one keep-with-next group, so the pair moves to the next + * page rather than closing this one with a heading whose body is overleaf — + * reachable only now that the column breaks at all. + */ private void addMainSectionHeader(SectionBuilder section, String title) { if (title == null || title.isBlank()) { return; } - section.addParagraph(paragraph -> paragraph - .text(TextOrnaments.spacedUpper(title)) - .textStyle(mainHeaderStyle()) - .align(TextAlign.LEFT) - .margin(DocumentInsets.top(6))); - section.addLine(line -> line - .horizontal(MAIN_SECTION_RULE_WIDTH) - .color(MAIN_RULE) - .thickness(theme.spacing().accentRuleWidth()) - .margin(new DocumentInsets(1, 0, 4, 0))); + section.addSection("CvV2MonogramSidebarMainHeading", heading -> heading + .spacing(MAIN_CONTENT_SPACING) + .keepWithNext() + .addParagraph(paragraph -> paragraph + .text(TextOrnaments.spacedUpper(title)) + .textStyle(mainHeaderStyle()) + .align(TextAlign.LEFT) + .margin(DocumentInsets.top(6))) + .addLine(line -> line + // Fills the main column rather than carrying a width of + // its own: the fixed 355pt this used to draw was wider + // than the column's 354.88pt content box on A4 and wider + // still on a narrower page, and a row slot never said so. + // horizontal(0) first so thickness() still reserves the + // stroke's height. + .horizontal(0) + .fill() + .color(MAIN_RULE) + .thickness(theme.spacing().accentRuleWidth()) + .margin(new DocumentInsets(1, 0, 4, 0)))); } private void addProfileBody(SectionBuilder section, @@ -697,7 +741,7 @@ private void addExperienceEntries(SectionBuilder section, DocumentTextStyle bodyStyle = mainBodyStyle(); List list = entries.entries(); - for (int i = 0; i < Math.min(list.size(), EXPERIENCE_LIMIT); i++) { + for (int i = 0; i < list.size(); i++) { CvEntry entry = list.get(i); section.addParagraph(paragraph -> paragraph .textStyle(positionStyle) diff --git a/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/NordicClean.java b/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/NordicClean.java index 416b5763a..e4e380b77 100644 --- a/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/NordicClean.java +++ b/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/NordicClean.java @@ -284,7 +284,7 @@ public void compose(DocumentSession document, CvDocument doc) { .spacing(theme.spacing().pageFlowSpacing()); addHeader(flow, doc); - addProfile(flow, SectionLookup.firstMatching(sections, SUMMARY_KEYS)); + addProfile(flow, SectionRouter.paragraph(sections, SectionRole.SUMMARY, SUMMARY_KEYS)); addBody(flow, sections); flow.build(); } @@ -367,15 +367,15 @@ private void addRail(SectionBuilder rail, List sections) { .fillColor(options.railFillColor()) .stroke(DocumentStroke.of(theme.palette().rule(), 0.35)) .cornerRadius(4); - addSkills(rail, SectionLookup.firstMatching(sections, SKILL_KEYS)); - addEducation(rail, SectionLookup.firstMatching(sections, EDUCATION_KEYS)); - addAdditional(rail, SectionLookup.firstMatching(sections, ADDITIONAL_KEYS)); + addSkills(rail, SectionRouter.skills(sections, SectionRole.SKILLS, SKILL_KEYS)); + addEducation(rail, SectionRouter.entries(sections, SectionRole.EDUCATION, EDUCATION_KEYS)); + addAdditional(rail, SectionRouter.rows(sections, SectionRole.OTHER, ADDITIONAL_KEYS, RowStyle.PLAIN)); } private void addMain(SectionBuilder main, List sections) { main.spacing(9); - addExperience(main, SectionLookup.firstMatching(sections, EXPERIENCE_KEYS)); - addProjects(main, SectionLookup.firstMatching(sections, PROJECT_KEYS)); + addExperience(main, SectionRouter.entries(sections, SectionRole.EXPERIENCE, EXPERIENCE_KEYS)); + addProjects(main, SectionRouter.rows(sections, SectionRole.PROJECTS, PROJECT_KEYS, RowStyle.BULLETED_STACKED)); } private void addSkills(SectionBuilder parent, CvSection section) { diff --git a/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/Panel.java b/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/Panel.java index 3f5e44530..5bacb9207 100644 --- a/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/Panel.java +++ b/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/Panel.java @@ -176,12 +176,12 @@ public void compose(DocumentSession document, CvDocument doc) { .name("CvV2PanelRoot") .spacing(gap); - CvSection summary = SectionLookup.firstMatching(sections, SUMMARY_KEYS); - CvSection skills = SectionLookup.firstMatching(sections, SKILL_KEYS); - CvSection education = SectionLookup.firstMatching(sections, EDUCATION_KEYS); - CvSection experience = SectionLookup.firstMatching(sections, EXPERIENCE_KEYS); - CvSection projects = SectionLookup.firstMatching(sections, PROJECT_KEYS); - CvSection additional = SectionLookup.firstMatching(sections, ADDITIONAL_KEYS); + CvSection summary = SectionRouter.paragraph(sections, SectionRole.SUMMARY, SUMMARY_KEYS); + CvSection skills = SectionRouter.skills(sections, SectionRole.SKILLS, SKILL_KEYS); + CvSection education = SectionRouter.entries(sections, SectionRole.EDUCATION, EDUCATION_KEYS); + CvSection experience = SectionRouter.entries(sections, SectionRole.EXPERIENCE, EXPERIENCE_KEYS); + CvSection projects = SectionRouter.rows(sections, SectionRole.PROJECTS, PROJECT_KEYS, RowStyle.BULLETED_STACKED); + CvSection additional = SectionRouter.rows(sections, SectionRole.OTHER, ADDITIONAL_KEYS, RowStyle.PLAIN); addHeader(flow, doc.identity(), fullCardContentWidth); addFullWidthPanel(flow, "Profile", "Profile", summary, diff --git a/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/SidebarPortrait.java b/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/SidebarPortrait.java index e57acc446..ce3a32f50 100644 --- a/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/SidebarPortrait.java +++ b/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/SidebarPortrait.java @@ -14,9 +14,11 @@ import com.demcha.compose.document.style.DocumentTextStyle; import com.demcha.compose.document.svg.SvgIcon; import com.demcha.compose.document.templates.api.DocumentTemplate; +import com.demcha.compose.document.templates.core.page.ContinuationSafeArea; import com.demcha.compose.document.templates.core.text.TextStyles; import com.demcha.compose.document.templates.core.text.MarkdownInline; import com.demcha.compose.document.templates.cv.components.ProjectLabel; +import com.demcha.compose.document.templates.cv.components.SectionRouter; import com.demcha.compose.document.templates.cv.components.SectionLookup; import com.demcha.compose.document.templates.cv.data.*; import com.demcha.compose.document.templates.core.theme.BrandTheme; @@ -47,6 +49,29 @@ * continuation pages of multi-page CVs) without any preset-side * filler logic. Use {@link Options} to override the sidebar fill, * main fill or accent colour without forking the theme.

    + * + *

    Both session-wide settings are set by {@code compose(...)} and replace + * whatever the caller had set: the page backgrounds above, and a page-margin rule + * that reserves {@link #CONTINUATION_TOP_SAFE_AREA} at the top of every page after + * the first. The columns' padding is an edge of the columns rather than of each + * page, so without that rule a body running past page one resumed at the trimmed + * edge — the safe area a zero {@link #RECOMMENDED_MARGIN} gives up along the top + * of the sheet as well as the sides.

    + * + *

    The body is a column flow, so each column continues on the next page and + * the preset draws every entry of the sections it recognises. It used to be a + * row — one atomic band that had to fit the page it started on — and carried + * per-section caps (two jobs, two degrees, five skills, three languages, two + * projects) to stay under that bound; the rest was dropped without a word. Both + * are gone. A section this preset has no slot for is still dropped, as in every + * preset that composes a fixed layout.

    + * + *

    The portrait geometry is sized for A4. A narrower page cannot hold it: the + * photo is clipped to the sidebar column — at 420pt roughly a third of it + * survives — and below about 310pt the column runs out of room altogether and + * the layout fails rather than drawing. The clipping predates the column flow; + * the failure is new, and replaces a page that came out with the portrait laid + * over the main column.

    */ public final class SidebarPortrait { @@ -65,6 +90,22 @@ public final class SidebarPortrait { */ public static final double RECOMMENDED_MARGIN = 0.0; + /** + * Top inset (in points) the body reserves on the pages it continues onto. + * + *

    Half an inch: the safe area every common printer's non-printable band + * fits inside. {@link #RECOMMENDED_MARGIN} is zero so the sidebar fill reaches + * the paper edge, and a zero margin gives up the safe area at the top of the + * sheet along with the one at the sides — which only matters now that the body + * paginates and there is a page whose top edge the columns' own padding does + * not cover. Page one is unaffected: it opens where its own design puts it — + * 54pt into the sidebar column, and 59pt into the main one, where the hero + * strip's top margin starts.

    + * + * @since 2.3.0 + */ + public static final double CONTINUATION_TOP_SAFE_AREA = 36.0; + /** * Ratio of the page width allocated to the left sidebar column. */ @@ -127,18 +168,12 @@ public final class SidebarPortrait { private static final double SIDEBAR_HEADER_RULE_WIDTH = 50.0; /** - * Width of the divider rule under each main-column section title - * (Professional Profile / Experience / Projects). V1 token — - * sized to match the natural main-column inner width once the 34pt - * left + right padding is subtracted from the column's allocated - * outer width. + * Vertical spacing inside the sidebar column and inside the main column's + * content section. The heading groups repeat these so wrapping a heading in + * its own section leaves the rhythm exactly as it was. */ - private static final double MAIN_SECTION_RULE_WIDTH = 346.0; - - private static final int EDUCATION_LIMIT = 2; - private static final int SKILL_LIMIT = 5; - private static final int LANGUAGE_LIMIT = 3; - private static final int EXPERIENCE_LIMIT = 2; + private static final double SIDEBAR_SPACING = 9.0; + private static final double MAIN_CONTENT_SPACING = 10.0; private static final String TEMPLATE_ASSET_ROOT = "/templates/cv/sidebar-portrait/"; @@ -163,22 +198,6 @@ public final class SidebarPortrait { private static final List PROJECT_KEYS = List.of("projects", "project", "selected projects"); - /** - * Maximum number of project rows rendered in the main column. - * - *

    The side-by-side body is wrapped in a {@code flow.addRow}, - * which is atomic by engine contract (see {@code RowBuilder}'s - * error message: "tables are splittable and would conflict - * with the row's atomic pagination"). That means the whole - * sidebar + main row has to fit on a single page — content - * overflow raises {@code AtomicNodeTooLargeException} instead of - * page-breaking. Capping projects keeps the dense canonical - * sample data inside the page bound; richer CVs that genuinely - * need page-breaking sidebar layouts will need a separate - * preset wired against a future splittable-row engine primitive.

    - */ - private static final int PROJECT_LIMIT = 2; - private SidebarPortrait() { } @@ -357,19 +376,32 @@ public void compose(DocumentSession document, CvDocument doc) { PageBackgroundFill.rightColumn(1.0 - SIDEBAR_WIDTH_RATIO, mainFill))); + // The columns' padding is an edge of the columns, not of each page, so + // it holds the first page's content off the trimmed edge and says + // nothing about the second's. Reserve the safe area the zero page + // margin gave up, on the pages the body continues onto only. Derived + // from the caller's own margin, so a caller who chose a margin of their + // own keeps it and a caller who already clears 36pt gets no rule at all. + ContinuationSafeArea.applyTo(document, 2, CONTINUATION_TOP_SAFE_AREA); + document.dsl() .pageFlow() .name("CvV2SidebarPortraitRoot") .spacing(theme.spacing().pageFlowSpacing()) .padding(DocumentInsets.zero()) - .addRow("CvV2SidebarPortraitBodyRow", row -> row - .spacing(0) + // A column flow rather than a row: both columns keep + // flowing onto the next page instead of having to fit the + // first one. The page backgrounds above already repeat the + // two fills per page, so a continuation page looks like the + // page it continues. + .addColumnFlow("CvV2SidebarPortraitBody", body -> body + .gap(0) .weights(SIDEBAR_WIDTH_RATIO, 1.0 - SIDEBAR_WIDTH_RATIO) - .addSection("CvV2SidebarPortraitSidebar", + .addColumn("CvV2SidebarPortraitSidebar", section -> addSidebar(section, doc, sections)) - .addSection("CvV2SidebarPortraitMain", + .addColumn("CvV2SidebarPortraitMain", section -> { section.spacing(0) .padding(DocumentInsets.zero()); @@ -386,27 +418,25 @@ private void addSidebar(SectionBuilder section, CvDocument doc, // Sidebar section deliberately has no fillColor — the // pageBackgrounds emitted in compose() paint the pale fill // edge-to-edge on every page. - section.spacing(9) + section.spacing(SIDEBAR_SPACING) .padding(new DocumentInsets(54, 20, 45.45, 26)); addPhotoBlock(section); addContactBlock(section, doc.identity()); - CvSection education = SectionLookup.firstMatching(sections, - EDUCATION_KEYS); + CvSection education = SectionRouter.entries(sections, SectionRole.EDUCATION, EDUCATION_KEYS); if (hasContent(education)) { addSidebarHeader(section, "Education"); addEducationEntries(section, education); } - CvSection skills = SectionLookup.firstMatching(sections, SKILL_KEYS); + CvSection skills = SectionRouter.skills(sections, SectionRole.SKILLS, SKILL_KEYS); if (hasContent(skills)) { addSidebarHeader(section, "Key Skills"); addSkillsList(section, skills); } - CvSection languages = SectionLookup.firstMatching(sections, - LANGUAGE_KEYS); + CvSection languages = SectionRouter.rows(sections, SectionRole.LANGUAGES, LANGUAGE_KEYS, RowStyle.PLAIN); if (hasContent(languages)) { addSidebarHeader(section, "Languages"); addLanguageList(section, languages); @@ -470,20 +500,29 @@ private void addContactBlock(SectionBuilder section, CvIdentity identity) { } } + /** + * Rule + heading as one keep-with-next group, so the pair travels to the + * next page rather than closing this one with a heading whose block is + * overleaf. A row could not break at all; a column can, which is what + * makes the stranding reachable. + */ private void addSidebarHeader(SectionBuilder section, String title) { if (title == null || title.isBlank()) { return; } - section.addLine(line -> line - .horizontal(SIDEBAR_HEADER_RULE_WIDTH) - .color(accent) - .thickness(0.75) - .margin(new DocumentInsets(12, 0, 7, 0))); - section.addParagraph(paragraph -> paragraph - .text(spacedUpper(title)) - .textStyle(sidebarHeaderStyle()) - .align(TextAlign.LEFT) - .margin(DocumentInsets.zero())); + section.addSection("CvV2SidebarPortraitSidebarHeading", heading -> heading + .spacing(SIDEBAR_SPACING) + .keepWithNext() + .addLine(line -> line + .horizontal(SIDEBAR_HEADER_RULE_WIDTH) + .color(accent) + .thickness(0.75) + .margin(new DocumentInsets(12, 0, 7, 0))) + .addParagraph(paragraph -> paragraph + .text(spacedUpper(title)) + .textStyle(sidebarHeaderStyle()) + .align(TextAlign.LEFT) + .margin(DocumentInsets.zero()))); } private void addEducationEntries(SectionBuilder section, @@ -494,9 +533,7 @@ private void addEducationEntries(SectionBuilder section, DocumentTextStyle headingStyle = sidebarEntryTitleStyle(); DocumentTextStyle metaStyle = sidebarEntryMetaStyle(); - List list = entries.entries(); - for (int i = 0; i < Math.min(list.size(), EDUCATION_LIMIT); i++) { - CvEntry entry = list.get(i); + for (CvEntry entry : entries.entries()) { section.addParagraph(paragraph -> paragraph .textStyle(headingStyle) .align(TextAlign.LEFT) @@ -528,8 +565,7 @@ private void addSkillsList(SectionBuilder section, return; } DocumentTextStyle skillStyle = sidebarSkillStyle(); - List tokens = skillTokens(skills); - for (String token : tokens.stream().limit(SKILL_LIMIT).toList()) { + for (String token : skillTokens(skills)) { section.addParagraph(paragraph -> paragraph .text(MarkdownInline.plainText(token)) .textStyle(skillStyle) @@ -543,8 +579,7 @@ private void addLanguageList(SectionBuilder section, CvSection langSection) { DocumentTextStyle nameStyle = sidebarLanguageNameStyle(); DocumentTextStyle metaStyle = sidebarLanguageMetaStyle(); - List items = languageItems(langSection); - for (String item : items.stream().limit(LANGUAGE_LIMIT).toList()) { + for (String item : languageItems(langSection)) { String text = MarkdownInline.plainText(item); int paren = text.indexOf('('); String langName = paren > 0 @@ -607,25 +642,22 @@ private void addNameBlock(SectionBuilder section, CvIdentity identity) { private void addMain(SectionBuilder section, List sections) { section.addSection("CvV2SidebarPortraitContent", content -> { - content.spacing(10) + content.spacing(MAIN_CONTENT_SPACING) .padding(new DocumentInsets(24, 34, 24, 34)); - CvSection profile = SectionLookup.firstMatching(sections, - SUMMARY_KEYS); + CvSection profile = SectionRouter.paragraph(sections, SectionRole.SUMMARY, SUMMARY_KEYS); if (hasContent(profile)) { addMainSectionHeader(content, "Professional Profile"); addProfileBody(content, profile); } - CvSection experience = SectionLookup.firstMatching(sections, - EXPERIENCE_KEYS); + CvSection experience = SectionRouter.entries(sections, SectionRole.EXPERIENCE, EXPERIENCE_KEYS); if (hasContent(experience)) { addMainSectionHeader(content, "Experience"); addExperienceEntries(content, experience); } - CvSection projects = SectionLookup.firstMatching(sections, - PROJECT_KEYS); + CvSection projects = SectionRouter.rows(sections, SectionRole.PROJECTS, PROJECT_KEYS, RowStyle.BULLETED_STACKED); if (hasContent(projects)) { addMainSectionHeader(content, "Projects"); addProjectsList(content, projects); @@ -633,20 +665,36 @@ private void addMain(SectionBuilder section, List sections) { }); } + /** + * Title + rule as one keep-with-next group, so the pair moves to the next + * page rather than closing this one with a heading whose body is + * overleaf — reachable only now that the column breaks at all. + */ private void addMainSectionHeader(SectionBuilder section, String title) { if (title == null || title.isBlank()) { return; } - section.addParagraph(paragraph -> paragraph - .text(spacedUpper(title)) - .textStyle(mainHeaderStyle()) - .align(TextAlign.LEFT) - .margin(DocumentInsets.top(8))); - section.addLine(line -> line - .horizontal(MAIN_SECTION_RULE_WIDTH) - .color(theme.palette().rule()) - .thickness(theme.spacing().accentRuleWidth()) - .margin(new DocumentInsets(2, 0, 7, 0))); + section.addSection("CvV2SidebarPortraitMainHeading", heading -> heading + .spacing(MAIN_CONTENT_SPACING) + .keepWithNext() + .addParagraph(paragraph -> paragraph + .text(spacedUpper(title)) + .textStyle(mainHeaderStyle()) + .align(TextAlign.LEFT) + .margin(DocumentInsets.top(8))) + .addLine(line -> line + // Fills the main column rather than carrying a width of + // its own: the fixed 346pt this used to draw was 21pt + // wider than the column's content box on A4 and wider + // still on a narrower page, and a row slot never said so. + // horizontal(0) first so thickness() still reserves the + // stroke's height — fill() alone leaves the box at 1pt + // and a thicker themed rule would bleed into the text. + .horizontal(0) + .fill() + .color(theme.palette().rule()) + .thickness(theme.spacing().accentRuleWidth()) + .margin(new DocumentInsets(2, 0, 7, 0)))); } private void addProfileBody(SectionBuilder section, @@ -676,9 +724,7 @@ private void addExperienceEntries(SectionBuilder section, DocumentTextStyle subtitleStyle = mainEntrySubtitleStyle(); DocumentTextStyle bodyStyle = mainBodyStyle(); - List list = entries.entries(); - for (int i = 0; i < Math.min(list.size(), EXPERIENCE_LIMIT); i++) { - CvEntry entry = list.get(i); + for (CvEntry entry : entries.entries()) { section.addParagraph(paragraph -> paragraph .textStyle(positionStyle) .align(TextAlign.LEFT) @@ -742,7 +788,7 @@ private void addProjectsList(SectionBuilder section, DocumentTextStyle bodyStyle = mainBodyStyle(); List list = rows.rows(); - for (int i = 0; i < Math.min(list.size(), PROJECT_LIMIT); i++) { + for (int i = 0; i < list.size(); i++) { CvRow row = list.get(i); ProjectLabel label = ProjectLabel.parse(row.label()); String body = MarkdownInline.plainText(row.body()); @@ -1004,6 +1050,22 @@ private static List languageItems(CvSection section) { result.add(label + " " + body); } } + if (result.isEmpty()) { + // The sniffing above exists because this slot also accepts an + // "Additional Information" section and has to pick the language + // rows out of it. A section routed here by its role is entirely + // languages, and nothing in it needs to look like one — without + // this the block draws its heading over nothing, which is worse + // than the drop it replaced. + for (CvRow row : rows.rows()) { + String label = MarkdownInline.plainText(row.label()).trim(); + String body = MarkdownInline.plainText(row.body()).trim(); + if (label.isBlank() && body.isBlank()) { + continue; + } + result.add(body.isBlank() ? label : label + " " + body); + } + } } else if (section instanceof SkillsSection skills) { for (SkillGroup group : skills.groups()) { String inline = MarkdownInline.plainText(group.skillsInline()); diff --git a/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/TimelineMinimal.java b/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/TimelineMinimal.java index 8f03cc54f..4a9da2a0b 100644 --- a/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/TimelineMinimal.java +++ b/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/TimelineMinimal.java @@ -25,6 +25,8 @@ import com.demcha.compose.document.templates.core.widgets.TimelineAxisWidget; import java.util.*; +import java.util.stream.Collectors; +import java.util.stream.Stream; /** * v2 port of the legacy "Timeline Minimal" CV preset. @@ -220,12 +222,12 @@ public void compose(DocumentSession document, CvDocument doc) { // Claim order decides which module wins when two lists could // match the same title, and every claim removes the section // from what falls through to the main column below. - CvSection education = allocation.claim(EDUCATION_KEYS); - CvSection skills = allocation.claim(SKILL_KEYS); - CvSection projects = allocation.claim(PROJECT_KEYS); - CvSection additional = allocation.claim(ADDITIONAL_KEYS); - CvSection summary = allocation.claim(SUMMARY_KEYS); - CvSection experience = allocation.claim(EXPERIENCE_KEYS); + CvSection education = allocation.claim(SectionRole.EDUCATION, EDUCATION_KEYS); + CvSection skills = allocation.claim(SectionRole.SKILLS, SKILL_KEYS); + CvSection projects = allocation.claim(SectionRole.PROJECTS, PROJECT_KEYS); + CvSection additional = allocation.claim(SectionRole.OTHER, ADDITIONAL_KEYS); + CvSection summary = allocation.claim(SectionRole.SUMMARY, SUMMARY_KEYS); + CvSection experience = allocation.claim(SectionRole.EXPERIENCE, EXPERIENCE_KEYS); List sidebar = modules( module(education, "Education"), @@ -654,6 +656,27 @@ private static List sectionLines(CvSection section) { lines.add(label + ": " + body); } } + } else if (section instanceof ModuleSection module) { + // A runtime module flattens the same way everything else does — one + // line per item — because these lines are what the column + // pagination measures. Rendering it through the shared dispatcher + // instead would draw rich multi-paragraph output the estimator + // never counted, and the axis row it lands in cannot page-break. + for (CvItem item : module.items()) { + StringBuilder line = new StringBuilder(MarkdownInline.plainText(item.title())); + String meta = Stream.of(item.subtitle(), item.location(), + module.kind() == CvKind.ENTRIES_DATED ? item.period() : "") + .filter(value -> !value.isBlank()) + .collect(Collectors.joining(" · ")); + if (!meta.isBlank()) { + line.append(" — ").append(meta); + } + if (!item.body().isEmpty()) { + line.append(": ").append(MarkdownInline.plainText( + String.join(" ", item.body()))); + } + lines.add(line.toString()); + } } else if (section instanceof EntriesSection entries) { for (CvEntry entry : entries.entries()) { // Flattened single-line excerpt: strip inline markdown so a diff --git a/templates/src/test/java/com/demcha/compose/document/templates/cv/components/SectionRouterTest.java b/templates/src/test/java/com/demcha/compose/document/templates/cv/components/SectionRouterTest.java new file mode 100644 index 000000000..8ee264a57 --- /dev/null +++ b/templates/src/test/java/com/demcha/compose/document/templates/cv/components/SectionRouterTest.java @@ -0,0 +1,222 @@ +package com.demcha.compose.document.templates.cv.components; + +import com.demcha.compose.document.templates.cv.data.CvEntry; +import com.demcha.compose.document.templates.cv.data.CvItem; +import com.demcha.compose.document.templates.cv.data.CvKind; +import com.demcha.compose.document.templates.cv.data.CvSection; +import com.demcha.compose.document.templates.cv.data.EntriesSection; +import com.demcha.compose.document.templates.cv.data.ModuleSection; +import com.demcha.compose.document.templates.cv.data.ParagraphSection; +import com.demcha.compose.document.templates.cv.data.RowStyle; +import com.demcha.compose.document.templates.cv.data.RowsSection; +import com.demcha.compose.document.templates.cv.data.SectionRole; +import com.demcha.compose.document.templates.cv.data.SkillGroup; +import com.demcha.compose.document.templates.cv.data.SkillsSection; +import org.junit.jupiter.api.Test; + +import java.util.List; + +import static org.assertj.core.api.Assertions.assertThat; +import static org.assertj.core.api.InstanceOfAssertFactories.type; + +/** + * What each slot receives, and what the lowering costs. + * + *

    The routing half is checked end to end by {@code RoleRoutingTest}, which + * renders a foreign-language CV through every preset. What that cannot see is + * the text itself: a preset draws whatever it is handed, so a module lowered + * with the wrong separator or a doubled label renders perfectly and reads + * wrong. These cases pin the strings.

    + */ +class SectionRouterTest { + + private static List only(CvSection section) { + return List.of(section); + } + + // -- role beats heading, heading still works ------------------------ + + @Test + void aModuleIsFoundByItsRoleWhateverItsHeadingSays() { + CvSection module = ModuleSection.builder("Berufserfahrung", SectionRole.EXPERIENCE, + CvKind.ENTRIES_DATED) + .item(CvItem.of("Senior Engineer").period("2021")) + .build(); + + assertThat(SectionRouter.find(only(module), SectionRole.EXPERIENCE, List.of("experience"))) + .isSameAs(module); + } + + @Test + void aHeadingNeverOverrulesADeclaredRole() { + // Both slots would otherwise claim it — the experience slot by role and + // the projects slot by heading — and the module would render twice. + CvSection module = ModuleSection.builder("Projects", SectionRole.EXPERIENCE, + CvKind.ENTRIES_DATED) + .item(CvItem.of("Senior Engineer").period("2021")) + .build(); + + assertThat(SectionRouter.find(only(module), SectionRole.PROJECTS, List.of("projects"))) + .isNull(); + } + + @Test + void aSectionWithNoRoleIsStillFoundByItsHeading() { + CvSection legacy = new ParagraphSection("Professional Summary", "Backend engineer."); + + assertThat(SectionRouter.find(only(legacy), SectionRole.SUMMARY, List.of("summary"))) + .isSameAs(legacy); + } + + @Test + void anEmptyModuleDoesNotShadowASectionThatHasContent() { + CvSection empty = ModuleSection.of("Experience", SectionRole.EXPERIENCE, + CvKind.ENTRIES_DATED); + CvSection populated = EntriesSection.builder("Experience") + .entry("Senior Engineer", "Acme", "2021", "") + .build(); + + assertThat(SectionRouter.find(List.of(empty, populated), SectionRole.EXPERIENCE, + List.of("experience"))).isSameAs(populated); + } + + // -- what each lowering produces ----------------------------------- + + @Test + void datedEntriesKeepThePeriodAndUndatedOnesDropIt() { + CvItem item = CvItem.of("Senior Engineer").at("Acme GmbH").in("Berlin") + .period("2021 - Present").paragraphs("Owned payments."); + + assertThat(entriesOf(CvKind.ENTRIES_DATED, item)) + .singleElement() + .satisfies(entry -> { + assertThat(entry.title()).isEqualTo("Senior Engineer"); + assertThat(entry.subtitle()).isEqualTo("Acme GmbH · Berlin"); + assertThat(entry.date()).isEqualTo("2021 - Present"); + assertThat(entry.body()).isEqualTo("Owned payments."); + }); + assertThat(entriesOf(CvKind.ENTRIES, item)) + .singleElement() + .extracting(CvEntry::date) + .as("ENTRIES ignores the period, so the slot draws no date column") + .isEqualTo(""); + } + + @Test + void aRowJoinsProseWithSpacesAndDiscretePointsWithCommas() { + CvSection prose = rowsOf(RowStyle.PLAIN, + CvItem.of("Languages").paragraphs("English (Fluent).", "German (B2).")); + CvSection points = rowsOf(RowStyle.PLAIN, + CvItem.of("Highlights").bullets("Doubled throughput", "Cut onboarding")); + + assertThat(rowBody(prose)).isEqualTo("English (Fluent). German (B2)."); + assertThat(rowBody(points)) + .as("bulleted points are discrete: joined with a space they read as one sentence") + .isEqualTo("Doubled throughput, Cut onboarding"); + } + + @Test + void onlyTheStackedRowStyleCarriesALinkedTitle() { + CvItem linked = CvItem.of("GraphCompose").linkedTo("https://example.dev/gc") + .paragraphs("A layout engine."); + + assertThat(rowLabel(rowsOf(RowStyle.BULLETED_STACKED, linked))) + .as("the stacked row bolds through the text style, so the link survives") + .isEqualTo("[GraphCompose](https://example.dev/gc)"); + assertThat(rowLabel(rowsOf(RowStyle.PLAIN, linked))) + .as("an inline row bolds by wrapping in markdown, which would nest " + + "around the link and print literal asterisks") + .isEqualTo("GraphCompose"); + } + + @Test + void aPlainListOfSkillsArrivesAsSkillsNotAsCategoriesHoldingThemselves() { + CvSection lowered = SectionRouter.skills(only(ModuleSection + .builder("Kenntnisse", SectionRole.SKILLS, CvKind.BULLETS) + .item("Java 21") + .item("Kotlin") + .build()), SectionRole.SKILLS, List.of("skills")); + + assertThat(lowered).asInstanceOf(type(SkillsSection.class)) + .extracting(SkillsSection::groups, org.assertj.core.api.InstanceOfAssertFactories.LIST) + .singleElement() + .satisfies(group -> { + SkillGroup skillGroup = (SkillGroup) group; + assertThat(skillGroup.category()).isEqualTo("Kenntnisse"); + assertThat(skillGroup.skills()).containsExactly("Java 21", "Kotlin"); + }); + } + + @Test + void anItemWithADescriptionBecomesItsOwnSkillCategory() { + CvSection lowered = SectionRouter.skills(only(ModuleSection + .builder("Technical Skills", SectionRole.SKILLS, CvKind.INLINE_LIST) + .item(CvItem.of("Languages").paragraphs("Java 21", "Kotlin")) + .item("Docker") + .build()), SectionRole.SKILLS, List.of("skills")); + + SkillsSection skills = (SkillsSection) lowered; + assertThat(skills.groups()).extracting(SkillGroup::category) + .containsExactly("Languages", "Technical Skills"); + assertThat(skills.groups().get(0).skills()).containsExactly("Java 21", "Kotlin"); + assertThat(skills.groups().get(1).skills()).containsExactly("Docker"); + } + + @Test + void proseJoinsEveryItemsDescriptionIntoOneBlock() { + CvSection lowered = SectionRouter.paragraph(only(ModuleSection + .builder("Profile", SectionRole.SUMMARY, CvKind.PARAGRAPH) + .item(CvItem.of("first").paragraphs("Backend engineer.", "Ten years of it.")) + .build()), SectionRole.SUMMARY, List.of("summary")); + + assertThat(lowered).asInstanceOf(type(ParagraphSection.class)) + .extracting(ParagraphSection::body) + .isEqualTo("Backend engineer. Ten years of it."); + } + + @Test + void aSectionThatIsAlreadyTheRightShapePassesThroughUntouched() { + CvSection legacy = EntriesSection.builder("Experience") + .entry("Senior Engineer", "Acme", "2021", "").build(); + + assertThat(SectionRouter.entries(only(legacy), SectionRole.EXPERIENCE, + List.of("experience"))) + .as("lowering must not rebuild what a preset already handles") + .isSameAs(legacy); + } + + @Test + void nothingMatchingYieldsNullFromEveryFinder() { + List none = List.of(new ParagraphSection("Awards", "Employee of the year")); + + assertThat(SectionRouter.entries(none, SectionRole.EXPERIENCE, List.of("experience"))).isNull(); + assertThat(SectionRouter.rows(none, SectionRole.PROJECTS, List.of("projects"), + RowStyle.PLAIN)).isNull(); + assertThat(SectionRouter.paragraph(none, SectionRole.SUMMARY, List.of("summary"))).isNull(); + assertThat(SectionRouter.skills(none, SectionRole.SKILLS, List.of("skills"))).isNull(); + assertThat(SectionRouter.find(null, SectionRole.SKILLS, List.of("skills"))).isNull(); + } + + // -- helpers --------------------------------------------------------- + + private static List entriesOf(CvKind kind, CvItem item) { + CvSection lowered = SectionRouter.entries(only(ModuleSection + .of("Experience", SectionRole.EXPERIENCE, kind, item)), + SectionRole.EXPERIENCE, List.of("experience")); + return ((EntriesSection) lowered).entries(); + } + + private static CvSection rowsOf(RowStyle style, CvItem item) { + return SectionRouter.rows(only(ModuleSection + .of("Section", SectionRole.OTHER, CvKind.BULLETS, item)), + SectionRole.OTHER, List.of("section"), style); + } + + private static String rowBody(CvSection section) { + return ((RowsSection) section).rows().get(0).body(); + } + + private static String rowLabel(CvSection section) { + return ((RowsSection) section).rows().get(0).label(); + } +} diff --git a/templates/src/test/java/com/demcha/compose/document/templates/cv/data/ModuleSectionTest.java b/templates/src/test/java/com/demcha/compose/document/templates/cv/data/ModuleSectionTest.java new file mode 100644 index 000000000..9930c6bce --- /dev/null +++ b/templates/src/test/java/com/demcha/compose/document/templates/cv/data/ModuleSectionTest.java @@ -0,0 +1,170 @@ +package com.demcha.compose.document.templates.cv.data; + +import org.junit.jupiter.api.Test; + +import java.util.ArrayList; +import java.util.Arrays; +import java.util.List; + +import static org.assertj.core.api.Assertions.assertThat; +import static org.assertj.core.api.Assertions.assertThatThrownBy; + +/** + * The runtime-assembled section and its item record: what they require, + * what they normalise, and what they refuse. + */ +class ModuleSectionTest { + + @Test + void anItemNeedsOnlyATitle() { + CvItem item = CvItem.of("Mentor, Rails Girls"); + + assertThat(item.title()).isEqualTo("Mentor, Rails Girls"); + assertThat(item.link()).isNull(); + assertThat(item.subtitle()).isEmpty(); + assertThat(item.period()).isEmpty(); + assertThat(item.location()).isEmpty(); + assertThat(item.body()).isEmpty(); + assertThat(item.bodyStyle()).isEqualTo(BodyStyle.PARAGRAPH); + assertThat(item.url()).isEmpty(); + } + + @Test + void anItemWithoutATitleIsRejected() { + assertThatThrownBy(() -> CvItem.of(" ")) + .isInstanceOf(IllegalArgumentException.class) + .hasMessageContaining("title"); + assertThatThrownBy(() -> CvItem.of(null)) + .isInstanceOf(NullPointerException.class) + .hasMessageContaining("title"); + } + + @Test + void theOptionalFieldsNormaliseNullToBlank() { + // An import layer that has no value for a field passes null rather than + // inventing a placeholder; every renderer downstream tests isBlank(). + CvItem item = new CvItem("Title", null, null, null, null, null, null); + + assertThat(item.subtitle()).isEmpty(); + assertThat(item.period()).isEmpty(); + assertThat(item.location()).isEmpty(); + assertThat(item.body()).isEmpty(); + assertThat(item.bodyStyle()).isEqualTo(BodyStyle.PARAGRAPH); + } + + @Test + void blankAndNullBodyLinesAreDropped() { + CvItem item = CvItem.of("Role").bullets("Shipped it", " ", null, "Measured it"); + + assertThat(item.body()).containsExactly("Shipped it", "Measured it"); + assertThat(item.bodyStyle()).isEqualTo(BodyStyle.BULLETS); + } + + @Test + void theBodyListIsCopiedAndUnmodifiable() { + List source = new ArrayList<>(List.of("first")); + CvItem item = CvItem.of("Role").body(source, BodyStyle.PARAGRAPH); + source.add("added after the fact"); + + assertThat(item.body()).containsExactly("first"); + assertThat(item.body().getClass().getName()).doesNotContain("ArrayList"); + } + + @Test + void theWithStyleMethodsReadInRenderOrder() { + CvItem item = CvItem.of("Senior Backend Engineer") + .linkedTo("https://acme.example") + .at("Acme GmbH") + .in("Berlin, DE") + .period("2021 - Present") + .bullets("Cut p99 latency 40%"); + + assertThat(item.title()).isEqualTo("Senior Backend Engineer"); + assertThat(item.url()).isEqualTo("https://acme.example"); + assertThat(item.link().label()).isEqualTo("Senior Backend Engineer"); + assertThat(item.subtitle()).isEqualTo("Acme GmbH"); + assertThat(item.location()).isEqualTo("Berlin, DE"); + assertThat(item.period()).isEqualTo("2021 - Present"); + assertThat(item.body()).containsExactly("Cut p99 latency 40%"); + } + + @Test + void aBlankLinkTargetLeavesTheTitlePlain() { + assertThat(CvItem.of("Role").linkedTo("").link()).isNull(); + assertThat(CvItem.of("Role").linkedTo(null).link()).isNull(); + } + + @Test + void aModuleCarriesItsRoleAndKind() { + ModuleSection module = ModuleSection.builder("Volunteering", + SectionRole.OTHER, CvKind.ENTRIES_DATED) + .item(CvItem.of("Mentor").period("2019")) + .build(); + + assertThat(module.title()).isEqualTo("Volunteering"); + assertThat(module.role()).isEqualTo(SectionRole.OTHER); + assertThat(module.kind()).isEqualTo(CvKind.ENTRIES_DATED); + assertThat(module.items()).hasSize(1); + assertThat(module).isInstanceOf(CvSection.class); + } + + @Test + void aModuleWithoutATitleIsRejected() { + assertThatThrownBy(() -> ModuleSection.of(" ", SectionRole.OTHER, CvKind.BULLETS)) + .isInstanceOf(IllegalArgumentException.class) + .hasMessageContaining("title"); + } + + @Test + void aModuleRejectsANullRoleOrKind() { + assertThatThrownBy(() -> ModuleSection.of("Skills", null, CvKind.BULLETS)) + .isInstanceOf(NullPointerException.class) + .hasMessageContaining("role"); + assertThatThrownBy(() -> ModuleSection.of("Skills", SectionRole.SKILLS, null)) + .isInstanceOf(NullPointerException.class) + .hasMessageContaining("kind"); + } + + @Test + void nullItemsAreDroppedAndTheListIsCopied() { + List source = new ArrayList<>( + Arrays.asList(CvItem.of("kept"), null, CvItem.of("also kept"))); + ModuleSection module = new ModuleSection("Interests", SectionRole.OTHER, + CvKind.BULLETS, source); + source.clear(); + + assertThat(module.items()).extracting(CvItem::title) + .containsExactly("kept", "also kept"); + // Both halves of "copied": the caller's list cannot reach in (above), and + // the accessor hands out nothing a caller could reach in through. + assertThatThrownBy(() -> module.items().add(CvItem.of("smuggled"))) + .isInstanceOf(UnsupportedOperationException.class); + } + + @Test + void aSummaryModuleIsProseUnderTheSummaryRole() { + ModuleSection module = ModuleSection.summary("Professional Summary", + "Backend engineer.", "Ten years of it."); + + assertThat(module.role()).isEqualTo(SectionRole.SUMMARY); + assertThat(module.kind()).isEqualTo(CvKind.PARAGRAPH); + assertThat(module.items()).singleElement() + .extracting(CvItem::body, org.assertj.core.api.InstanceOfAssertFactories.LIST) + .containsExactly("Backend engineer.", "Ten years of it."); + } + + @Test + void theBuilderShorthandsBuildTheSameItems() { + ModuleSection module = ModuleSection.builder("Interests", SectionRole.OTHER, + CvKind.BULLETS) + .item("Chess") + .item("Cycling", "Long-distance, mostly.") + .build(); + + assertThat(module.items()).extracting(CvItem::title) + .containsExactly("Chess", "Cycling"); + assertThat(module.items().get(0).body()).isEmpty(); + assertThat(module.items().get(1).body()).containsExactly("Long-distance, mostly."); + assertThat(module.items().get(1).bodyStyle()).isEqualTo(BodyStyle.PARAGRAPH); + } +} diff --git a/templates/src/test/java/com/demcha/compose/document/templates/cv/presets/CvTemplatesCoverageTest.java b/templates/src/test/java/com/demcha/compose/document/templates/cv/presets/CvTemplatesCoverageTest.java new file mode 100644 index 000000000..3d96b7866 --- /dev/null +++ b/templates/src/test/java/com/demcha/compose/document/templates/cv/presets/CvTemplatesCoverageTest.java @@ -0,0 +1,149 @@ +package com.demcha.compose.document.templates.cv.presets; + +import com.demcha.compose.document.templates.api.DocumentTemplate; +import com.demcha.compose.document.templates.cv.data.CvDocument; +import org.junit.jupiter.api.Test; + +import java.io.IOException; +import java.nio.file.Files; +import java.nio.file.Path; +import java.util.ArrayList; +import java.util.List; +import java.util.stream.Stream; + +import static org.assertj.core.api.Assertions.assertThat; + +/** + * The catalogue lists every preset in the package. + * + *

    A registry is only useful while it is complete, and the way it stops + * being complete is that someone ships a preset and forgets the one line. + * Nothing about that fails: the preset works, its tests pass, its example + * renders — it is merely invisible to every caller that picks a template by + * id, which is the whole audience the catalogue exists for. So the list is + * derived from the package rather than trusted, by reading the directory + * the presets live in.

    + * + *

    Reading source files rather than scanning the classpath is deliberate: + * it needs no reflection dependency, and the failure message can name the + * file to add.

    + */ +class CvTemplatesCoverageTest { + + /** The presets package, relative to this module's directory. */ + private static final Path PRESETS = Path.of( + "src/main/java/com/demcha/compose/document/templates/cv/presets"); + + @Test + void everyPresetInThePackageIsInTheCatalogue() throws IOException { + List missing = new ArrayList<>(); + for (String preset : presetClassNames()) { + if (CvTemplates.all().stream().noneMatch(t -> declaredBy(t, preset))) { + missing.add(preset); + } + } + + assertThat(missing) + .as("every preset in %s must be registered in CvTemplates — a preset " + + "missing from the catalogue is invisible to every caller that " + + "picks a template by id", PRESETS) + .isEmpty(); + } + + @Test + void theCatalogueListsNothingTwice() { + assertThat(CvTemplates.ids()).doesNotHaveDuplicates(); + assertThat(CvTemplates.all()).hasSameSizeAs(CvTemplates.ids()); + } + + @Test + void everyRegisteredIdResolvesToTheTemplateThatPublishesIt() { + for (String id : CvTemplates.ids()) { + assertThat(CvTemplates.byId(id)) + .as("byId(%s) must resolve", id) + .isPresent() + .get() + .extracting(DocumentTemplate::id) + .as("byId(%s) must return the template publishing that id", id) + .isEqualTo(id); + assertThat(CvTemplates.recommendedMargin(id)) + .as("recommendedMargin(%s) must be known", id) + .isPresent(); + } + } + + @Test + void anUnknownOrNullIdIsAnEmptyResultNotAnException() { + // The id arrives from a config file or a request; a caller validating + // input should not have to catch anything. + assertThat(CvTemplates.byId("no-such-preset")).isEmpty(); + assertThat(CvTemplates.byId(null)).isEmpty(); + assertThat(CvTemplates.byId("")).isEmpty(); + assertThat(CvTemplates.recommendedMargin("no-such-preset")).isEmpty(); + } + + @Test + void surroundingWhitespaceInAnIdIsIgnored() { + assertThat(CvTemplates.byId(" modern-professional ")) + .get() + .extracting(DocumentTemplate::id) + .isEqualTo(ModernProfessional.ID); + } + + @Test + void everyTemplateBuildsAFreshInstance() { + // all() hands each caller its own template rather than a shared one, + // so a caller cannot be surprised by another's theme. + List> first = CvTemplates.all(); + List> second = CvTemplates.all(); + + for (int i = 0; i < first.size(); i++) { + assertThat(first.get(i)).isNotSameAs(second.get(i)); + assertThat(first.get(i).id()).isEqualTo(second.get(i).id()); + } + } + + /** + * The class names in the presets package that are actually presets: + * public types with a factory. {@code package-info} carries no class, and + * {@code ColumnPagination} is a package-private helper rather than a + * template, so neither belongs in a catalogue of templates. + */ + private static List presetClassNames() throws IOException { + assertThat(PRESETS).as("presets package must exist at %s", PRESETS).exists(); + try (Stream files = Files.list(PRESETS)) { + List names = new ArrayList<>(); + for (Path file : files.toList()) { + String name = file.getFileName().toString(); + if (!name.endsWith(".java") || name.equals("package-info.java")) { + continue; + } + String simpleName = name.substring(0, name.length() - ".java".length()); + String source = Files.readString(file); + if (source.contains("public final class " + simpleName) + && source.contains("public static final String ID")) { + names.add(simpleName); + } + } + assertThat(names) + .as("the scan must find the presets it is meant to guard") + .hasSizeGreaterThan(10); + return names; + } + } + + /** + * Whether {@code template} is the one {@code presetClass} publishes, + * decided by the id constant that class declares. + */ + private static boolean declaredBy(DocumentTemplate template, String presetClass) { + try { + Class type = Class.forName( + "com.demcha.compose.document.templates.cv.presets." + presetClass); + Object id = type.getField("ID").get(null); + return template.id().equals(id); + } catch (ReflectiveOperationException e) { + throw new AssertionError("preset " + presetClass + " must publish a public ID", e); + } + } +} diff --git a/testing/pom.xml b/testing/pom.xml index 82398d0d6..2432158e2 100644 --- a/testing/pom.xml +++ b/testing/pom.xml @@ -19,7 +19,7 @@ --> io.github.demchaav graph-compose-testing - 2.2.1-SNAPSHOT + 2.3.0-SNAPSHOT GraphCompose Testing Consumer testing support for GraphCompose: layout-snapshot assertions and PDF visual regression. diff --git a/wrapper/pom.xml b/wrapper/pom.xml index b4b414829..4746605aa 100644 --- a/wrapper/pom.xml +++ b/wrapper/pom.xml @@ -22,7 +22,7 @@ --> io.github.demchaav graph-compose - 2.2.1-SNAPSHOT + 2.3.0-SNAPSHOT GraphCompose The graph-compose coordinate: a drop-in aggregator over graph-compose-core for a PDF-capable install.