Module headings come from the sample's own section titles, so the + * sidebar reads Education & Certifications / Technical Skills / + * Projects and the main column Professional Summary / Professional + * Experience. The sample carries more than one page of content: the + * remainder continues on page two, where the axis shortens to match.
* *Output: * {@code examples/target/generated-pdfs/templates/cv/cv-timeline-minimal-v2.pdf}.
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 new file mode 100644 index 000000000..fb0a999d8 --- /dev/null +++ b/qa/src/test/java/com/demcha/compose/document/templates/cv/components/SectionAllocationTest.java @@ -0,0 +1,133 @@ +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.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 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; + +/** + * {@link SectionAllocation} hands each section out once and keeps the rest. + * + *The behaviour worth pinning is what a preset built on + * {@link SectionLookup#firstMatching} could not do: notice that a section was + * never asked for, and tell two sections apart when both answer to the same + * keywords.
+ */ +class SectionAllocationTest { + + private static final ParagraphSection SUMMARY = + new ParagraphSection("Professional Summary", "Builds pipelines."); + private static final ParagraphSection PROFILE = + new ParagraphSection("Profile", "A second prose block."); + private static final RowsSection AWARDS = + RowsSection.builder("Awards", RowStyle.PLAIN) + .row("Rising Star", "2019") + .build(); + + @Test + void claimReturnsTheFirstMatchInDocumentOrder() { + SectionAllocation allocation = SectionAllocation.of( + List.of(SUMMARY, PROFILE, AWARDS)); + + assertThat(allocation.claim(List.of("summary", "profile"))) + .isSameAs(SUMMARY); + } + + @Test + void aClaimedSectionIsNotHandedOutTwice() { + SectionAllocation allocation = SectionAllocation.of( + List.of(SUMMARY, PROFILE)); + + CvSection first = allocation.claim(List.of("summary", "profile")); + CvSection second = allocation.claim(List.of("summary", "profile")); + + assertThat(first).isSameAs(SUMMARY); + assertThat(second) + .describedAs("the second module must see the second section, " + + "not the one already spoken for") + .isSameAs(PROFILE); + } + + @Test + void remainingKeepsWhatNoModuleAskedForInDocumentOrder() { + SectionAllocation allocation = SectionAllocation.of( + List.of(SUMMARY, AWARDS, PROFILE)); + allocation.claim(List.of("summary")); + + assertThat(allocation.remaining()) + .describedAs("an unclaimed section is the one a keyword-only " + + "preset loses without trace") + .containsExactly(AWARDS, PROFILE); + } + + @Test + void remainingIsEmptyOnceEverySectionIsSpokenFor() { + SectionAllocation allocation = SectionAllocation.of(List.of(SUMMARY)); + allocation.claim(List.of("summary")); + + assertThat(allocation.remaining()).isEmpty(); + } + + @Test + void anEmptySectionIsNotOfferedAsLeftoverWork() { + CvSection empty = EntriesSection.builder("Publications").build(); + SectionAllocation allocation = SectionAllocation.of(List.of(SUMMARY, empty)); + + assertThat(allocation.remaining()) + .describedAs("rendering a heading with nothing under it is worse " + + "than skipping the section") + .doesNotContain(empty); + } + + @Test + void claimReturnsNullWhenNothingMatches() { + SectionAllocation allocation = SectionAllocation.of(List.of(SUMMARY)); + + assertThat(allocation.claim(List.of("references"))).isNull(); + assertThat(allocation.remaining()).containsExactly(SUMMARY); + } + + @Test + void nullInputsAreToleratedTheWayPresetCallSitesExpect() { + SectionAllocation allocation = SectionAllocation.of(null); + + assertThat(allocation.remaining()).isEmpty(); + assertThat(allocation.claim(List.of("summary"))).isNull(); + assertThat(SectionAllocation.of(List.of(SUMMARY)).claim(null)).isNull(); + } + + @Test + void theSectionsOwnTitleWinsOverThePresetsLabel() { + assertThat(SectionAllocation.titleOr(SUMMARY, "Profile")) + .isEqualTo("Professional Summary"); + } + + @Test + void thePresetsLabelIsUsedOnlyWhenNoSectionMatched() { + assertThat(SectionAllocation.titleOr(null, "Languages")) + .isEqualTo("Languages"); + } + + @Test + void aBlankTitleCannotReachTheLabelBecauseTheDataRejectsItFirst() { + assertThatThrownBy(() -> new ParagraphSection(" ", "body")) + .describedAs("titleOr has no blank branch precisely because " + + "this constructor makes one unreachable") + .isInstanceOf(IllegalArgumentException.class) + .hasMessageContaining("blank"); + } + + @Test + void aMissingFallbackLabelIsARejectedArgument() { + assertThatThrownBy(() -> SectionAllocation.titleOr(SUMMARY, null)) + .isInstanceOf(NullPointerException.class) + .hasMessageContaining("fallback"); + } +} diff --git a/qa/src/test/java/com/demcha/compose/document/templates/cv/presets/ColumnPaginationTest.java b/qa/src/test/java/com/demcha/compose/document/templates/cv/presets/ColumnPaginationTest.java new file mode 100644 index 000000000..ba6d71243 --- /dev/null +++ b/qa/src/test/java/com/demcha/compose/document/templates/cv/presets/ColumnPaginationTest.java @@ -0,0 +1,164 @@ +package com.demcha.compose.document.templates.cv.presets; + +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.Timeout; + +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.assertThatThrownBy; + +/** + * {@link ColumnPagination} decides page boundaries without losing lines. + * + *The property that matters is conservation: a preset reached for this + * because dropping the overflow is the bug it replaced, so every case below + * checks that what went in comes back out, whatever the budget.
+ */ +class ColumnPaginationTest { + + /** A sidebar-shaped column: 148pt wide, 7.5pt body, 12.5pt heading. */ + private static ColumnPagination sidebar() { + return ColumnPagination.forColumn(148.0, 7.5, 1.0, 12.5, 22.0); + } + + private static ColumnPagination.Block block(String title, String... lines) { + return new ColumnPagination.Block(title, List.of(lines), false); + } + + private static ListA preset that drops content is worse than one that fails: the PDF looks + * finished, the page is not obviously full, and the reader has no way to know + * a job, a degree, or a whole section was never drawn. The three ways this + * preset used to lose data are each pinned here, because each is silent.
+ * + *The fixture is deliberately denser than a one-page CV. Content that does + * not fit belongs on page two — the engine paginates — not in the bin.
+ */ +class TimelineMinimalContentFidelityTest { + + @Test + void everyEntryOfADenseCvSurvivesIntoThePdf() throws Exception { + String text = renderText(TimelineMinimal.create(), denseDocument()); + + // Tail entries of each module: the ones a per-module cap dropped first. + assertThat(text) + .describedAs("every education entry must reach the page; the 4th " + + "was the first casualty of the 5-line sidebar cap") + .contains("MSc Computer Science") + .contains("University of Leeds") + .contains("Cloud Architect") + .contains("BSc Hydraulic Engineering"); + + assertThat(text) + .describedAs("every employer must reach the page") + .contains("Acme Rendering") + .contains("Northwind Data") + .contains("Nikoplast"); + + assertThat(text) + .describedAs("every project must reach the page") + .contains("GraphCompose") + .contains("Ledger Sync") + .contains("Spring Cart API"); + + assertThat(text) + .describedAs("every skill group must reach the page") + .contains("Languages") + .contains("Frameworks") + .contains("AssertJ") + .contains("Build") + .contains("Datastores") + .contains("Messaging") + .contains("Observability") + .contains("Kubernetes"); + } + + @Test + void aSectionMatchingNoKnownCategoryIsStillRenderedUnderItsOwnTitle() throws Exception { + String text = renderText(TimelineMinimal.create(), denseDocument()); + + // Headings render in caps, so compare without case. + assertThat(text) + .describedAs("an arbitrary section title matched none of the preset's " + + "keyword lists and was discarded without a trace") + .containsIgnoringCase("Awards") + .contains("Rising Star"); + } + + @Test + void aSecondSectionOfAKnownCategoryIsNotSwallowedByTheFirst() throws Exception { + String text = renderText(TimelineMinimal.create(), denseDocument()); + + assertThat(text) + .describedAs("firstMatching consumed only the first title matching " + + "the summary keys, so the second prose section vanished") + .containsIgnoringCase("Open Source") + .contains("Maintains a document engine"); + } + + @Test + void proseIsNotCutWithAnEllipsisWhileThePageStillHasRoom() throws Exception { + String text = renderText(TimelineMinimal.create(), denseDocument()); + + assertThat(text) + .describedAs("the summary was clipped mid-sentence by a character " + + "budget rather than by what actually fits") + .contains("closing sentence of the profile"); + } + + @Test + void aCvWithATallContactStackStillRendersEveryEntry() throws Exception { + // The masthead grows a line per contact and per link, and the body + // budget is what is left of the page after it. Thirteen contact rows + // is far past anything the other fixtures exercise; the pagination has + // to absorb that without dropping content at either end. + CvIdentity.Builder identity = CvIdentity.builder() + .name("Jane", "Doe") + .jobTitle("Backend Engineer") + .contact("+44 0", "j@d.com", "London"); + for (int i = 1; i <= 10; i++) { + identity.link("Profile " + i, "https://example.com/" + i); + } + + CvDocument doc = CvDocument.builder() + .identity(identity.build()) + .sections(denseDocument().sections().toArray(new CvSection[0])) + .build(); + + String text = renderText(TimelineMinimal.create(), doc); + + assertThat(text) + .describedAs("the body has to give way to the taller masthead " + + "without losing what it was holding") + .contains("BSc Hydraulic Engineering") + .contains("Nikoplast") + .containsIgnoringCase("Awards"); + } + + private static String renderText(DocumentTemplate{@link SectionLookup#firstMatching} answers "which section is the + * Education one?" and nothing else. A preset built only from those calls + * renders exactly the categories it thought to ask about: a second section + * matching the same keywords is shadowed by the first, and a section whose + * title matches no list at all — "Awards", "Publications", anything a user + * invented — is never looked at. Neither loss is visible in the output. The + * page renders, it looks finished, and the reader has no way to tell that a + * section was dropped.
+ * + *This narrows that to an allocation: {@link #claim(List)} hands out each + * section once, and {@link #remaining()} returns everything no module + * asked for, in document order, so the preset can render it rather than + * discard it.
+ * + *Not thread-safe, and not meant to be: a preset builds one of these inside + * a single {@code compose} call and drops it.
+ * + * @since 2.1.2 + */ +public final class SectionAllocation { + + private final ListClaiming is what makes a second call with overlapping keys return a + * different section instead of the same one twice, and what moves + * the section out of {@link #remaining()}.
+ * + * @param keys candidate title fragments; {@code null} claims nothing + * @return the claimed section, or {@code null} when nothing matches + */ + public CvSection claim(ListThese are the ones a keyword-only preset loses silently. Render them + * under {@link CvSection#title()} — the user wrote that title, and it is + * the only label that can be correct for a category the preset does not + * know about.
+ * + * @return unclaimed sections carrying content, in document order + */ + public ListA preset that hardcodes its module labels renames the user's content: + * a section the author called "Projects" prints as "EXPERTISE", and + * "Additional Information" prints as "LANGUAGES". The author's title wins. + * There is no blank-title case to weigh against it — every + * {@link CvSection} implementation rejects a blank title at construction — + * so the label is reached only when the module found no section at all, + * which is also when it has nothing to render.
+ * + * @param section the claimed section, or {@code null} when none matched + * @param fallback the preset's own label for the module + * @return the title to print + * @throws NullPointerException if {@code fallback} is {@code null} + */ + public static String titleOr(CvSection section, String fallback) { + Objects.requireNonNull(fallback, "fallback"); + return section == null ? fallback : section.title(); + } +} diff --git a/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/ColumnPagination.java b/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/ColumnPagination.java new file mode 100644 index 000000000..faa8ed05f --- /dev/null +++ b/templates/src/main/java/com/demcha/compose/document/templates/cv/presets/ColumnPagination.java @@ -0,0 +1,211 @@ +package com.demcha.compose.document.templates.cv.presets; + +import java.util.ArrayList; +import java.util.List; + +/** + * Splits a column of titled text blocks across pages. + * + *A preset whose body is a multi-column {@code addRow} cannot lean on the + * paginator: a row is atomic, so a row taller than the page raises + * {@code AtomicNodeTooLargeException} rather than flowing. The preset has to + * pick the page boundary itself, and to pick it, it has to guess how tall its + * own content will be before the engine measures anything.
+ * + *The guess models one thing — line wrapping. A block's line is a logical + * line; in a 148pt sidebar at 7.5pt it renders as three. Counting logical + * lines and calling that a page budget is what overflows: the same count of + * lines is twice the height in the narrow column. So the estimate turns a + * character count into wrapped lines using the column's width and the font's + * mean advance, and packs blocks until the page height is spent.
+ * + *It is an estimate, and deliberately a conservative one: a page that + * breaks a block early costs some whitespace, while a page that breaks late + * costs an exception. A font far from the assumed mean advance, or a single + * unbreakable token wider than the column, can still push a page over.
+ * + *What it never does is lose a line. Everything handed to + * {@link #paginate} comes back out on some page.
+ */ +final class ColumnPagination { + + /** + * Mean glyph advance as a fraction of font size, for the humanist sans + * faces these presets use. + * + *Taken across the body text of the repository's CV fixtures in Lato + * at 7.5–7.9pt. Being a mean it is wrong for any individual line; over a + * block of prose it converges, which is the scale it is used at.
+ */ + private static final double MEAN_GLYPH_ADVANCE_RATIO = 0.48; + + /** + * Rendered line height as a ratio of font size, before extra spacing. + * + *Package-visible so a preset sizing its own header uses the same + * ratio this uses to size its columns — two copies of the number would + * drift and only show up as a page that overflows.
+ */ + static final double FONT_LEADING_RATIO = 1.2; + + private final double charsPerLine; + private final double lineHeight; + private final double headingHeight; + private final double blockGap; + + private ColumnPagination(double charsPerLine, double lineHeight, + double headingHeight, double blockGap) { + this.charsPerLine = charsPerLine; + this.lineHeight = lineHeight; + this.headingHeight = headingHeight; + this.blockGap = blockGap; + } + + /** + * One titled run of already-flattened content. + * + * @param title the heading to print + * @param lines the block's logical lines, complete and unclipped + * @param prose {@code true} to render as running text, {@code false} as bullets + */ + record Block(String title, ListA block that does not fit the remainder of a page starts the + * next one intact. A block too tall for a whole page is carried across as + * many pages as it needs, repeating its heading — dropping the heading + * would leave the continuation reading as part of what came before it.
+ * + * @param blocks the column's blocks in render order + * @param budget height available on one page, in points; must be positive + * @return one list per page; at least one, possibly empty + */ + ListThe preset stays a thin orchestrator. The 3-column body layout * (sidebar / axis / main) and the contact icon row are preset-local * because no other v2 preset uses this visual today. Section bodies - * are flattened to a list of lines via a preset-local helper so the - * sidebar can apply per-module truncation limits — the canonical - * shared dispatchers do not enforce that shape.
+ * are flattened to a list of lines via a preset-local helper, which is + * the shape the two narrow columns and the fixed-height axis need — the + * canonical shared dispatchers produce richly-styled multi-paragraph + * output instead. + * + *Sections are matched to modules by title keyword, and a keyword match + * is a guess: a CV may hold a category this preset never heard of, or two + * that answer to the same keywords. Both are routed rather than discarded — + * {@link SectionAllocation} hands each section out once and returns the + * rest, which land in the main column under their own headings. A module's + * heading is the section's own title where it has one; the labels here are + * only a fallback.
+ * + *Content longer than a page continues on the next one. The body is a + * row, and a row is atomic — the paginator cannot break inside one — so the + * preset estimates its own columns' heights through {@link ColumnPagination} + * and emits one row per page, letting each finished row overflow naturally. + * What it holds back for the masthead is measured from the identity, because + * the contact stack grows a row per link.
*/ public final class TimelineMinimal { @@ -101,6 +121,45 @@ public final class TimelineMinimal { */ private static final DocumentColor ICON_COLOR = DocumentColor.rgb(58, 58, 58); + /** + * Shortest axis a continuation page may draw. Below this the four + * segments and three markers stop reading as a timeline. + */ + private static final double MIN_CONTINUATION_AXIS_HEIGHT = 120.0; + + /** Gap between the three body columns; also the row's own spacing. */ + private static final double BODY_COLUMN_GAP = 16.0; + + private static final double SIDEBAR_WEIGHT = 0.74; + private static final double AXIS_WEIGHT = 0.12; + private static final double MAIN_WEIGHT = 1.74; + + /** Gap between the stacked contact rows. */ + private static final double CONTACT_ROW_GAP = 3.0; + + /** Gap between the name and the job title beneath it. */ + private static final double NAME_BLOCK_GAP = 4.0; + + /** Job-title size; read both by the style and by the masthead measurement. */ + private static final double JOB_TITLE_SIZE = 9.5; + + /** + * Slack added to the measured masthead height. + * + *Covers what the arithmetic below does not model — a contact line long + * enough to wrap, the rule's own thickness. An over-estimate costs + * whitespace at the foot of a page; an under-estimate costs + * {@code AtomicNodeTooLargeException}, because a row cannot be broken by + * the paginator, so the error is deliberately taken on the safe side.
+ */ + private static final double MASTHEAD_SLACK = 18.0; + + /** Heading gap plus the trailing rule each sidebar block carries. */ + private static final double SIDEBAR_BLOCK_GAP = 22.0; + + /** Heading gap plus the trailing rule each main-column block carries. */ + private static final double MAIN_BLOCK_GAP = 24.0; + private static final ListThe header is a row, so its height is the taller of its two + * columns: the name block on the left, the contact stack on the + * right. The stack grows a row per link, which is why this is + * measured rather than assumed — a fixed reserve is wrong in both + * directions. Too small, and a CV with enough contact links pushes + * the body row past the page into + * {@code AtomicNodeTooLargeException}, since a row cannot be + * broken. Too large, and every ordinary CV loses page space it + * could have filled.
+ * + * @param identity the header's data; {@code null} yields the rule alone + * @return height in points, including the rule and its slack + */ + private double mastheadHeight(CvIdentity identity) { + double nameBlock = theme.typography().sizeHeadline() + * ColumnPagination.FONT_LEADING_RATIO; + if (identity != null && !identity.jobTitle().isBlank()) { + nameBlock += NAME_BLOCK_GAP + + JOB_TITLE_SIZE * ColumnPagination.FONT_LEADING_RATIO; + } + int rows = contactItems(identity).size(); + double contactStack = rows == 0 ? 0.0 + : rows * theme.typography().sizeContact() + * ColumnPagination.FONT_LEADING_RATIO + + (rows - 1) * CONTACT_ROW_GAP; + return Math.max(nameBlock, contactStack) + + theme.spacing().accentRuleWidth() + MASTHEAD_SLACK; + } + private ListThe shared {@code SectionDispatcher} would produce richly-styled + * multi-paragraph output, which is not the shape this layout can work + * with: knowing the line count is what lets the preset choose its own + * page boundaries around the fixed-height axis. Counting lines is all it + * is for — every line produced here is rendered, on this page or the + * next.
*/ private static List