Set by DrawingML, the least capacious of the fixed backends: {@code spc} + * is {@code ST_TextPoint}, whose numeric member is bounded at + * ±400000 hundredths. Measured, not read — the schema validates + * {@code 400000} and rejects {@code 400001}.
+ */ + static final double MAX_FIXED_LAYOUT_TRACKING_POINTS = 4000.0; + + /** + * Tracking as fixed layout can actually express it: quantised to hundredths + * of a point. + * + *This exists because the engine's measurement and the file's declared + * spacing have to be the same number, and PPTX can only declare + * hundredths. Left unquantised, a {@code points(1.0/3.0)} style measured at + * {@code 0.33333…} per code point while the deck said {@code spc="33"} — + * {@code 0.33} — so the width the layout reserved, wrapped against, aligned + * to and sized its frames from was a width the deck would never draw. The + * residue is small per code point and accumulates with the string: a third + * of a point is {@code 0.0033} out per code point, {@code 0.13pt} over a + * forty-character line. Quantising here makes the engine measure the value + * every fixed backend will actually use, so PDF's {@code Tc} and PPTX's + * {@code spc} are two spellings of one number.
+ * + *It is done once, here, rather than in each backend: this is the single + * seam where the public value becomes engine points, so it is the only place + * that can make the measurement and every renderer agree by construction. + * The public {@link DocumentTextStyle} is untouched — it still carries + * exactly what the author wrote, and {@code DocumentLetterSpacing} still + * resolves to exactly what the author asked for. The quantisation is a + * property of fixed layout, not of the value.
+ * + *The semantic DOCX export does not come through here. It resolves the + * public value itself and rounds to Word's twentieths, which is a coarser + * grid again — and correctly so, because Word owns that layout and + * owes the PDF no coordinate.
+ * + *Out of range is refused rather than clamped or wrapped. {@code spc} is + * written as an {@code int} of hundredths, and a large enough value silently + * changes sign on the cast — {@code 2.2e7} points becomes + * {@code -2094967296}, turning wide tracking into tight. A document asking + * for more than the format can hold is a mistake worth hearing about.
+ * + * @param points resolved tracking in points + * @return the same tracking on the grid fixed layout can express + * @throws IllegalArgumentException if the tracking exceeds + * {@link #MAX_FIXED_LAYOUT_TRACKING_POINTS} + */ + private static double toFixedLayoutTracking(double points) { + if (points == 0.0) { + // Short-circuited so an untracked style keeps the identical double, + // and never depends on the rounding below behaving at zero. + return 0.0; + } + if (Math.abs(points) > MAX_FIXED_LAYOUT_TRACKING_POINTS) { + throw new IllegalArgumentException( + "Letter spacing resolves to " + points + "pt, beyond the " + + MAX_FIXED_LAYOUT_TRACKING_POINTS + + "pt a fixed-layout document can express (DrawingML spc is " + + "hundredths of a point, bounded at +/-400000)."); + } + return Math.round(points * 100.0) / 100.0; } static TextIndentStrategy toIndentStrategy(DocumentTextIndent indent) { diff --git a/core/src/main/java/com/demcha/compose/document/style/DocumentLetterSpacing.java b/core/src/main/java/com/demcha/compose/document/style/DocumentLetterSpacing.java new file mode 100644 index 000000000..9bf40ebf7 --- /dev/null +++ b/core/src/main/java/com/demcha/compose/document/style/DocumentLetterSpacing.java @@ -0,0 +1,160 @@ +package com.demcha.compose.document.style; + +/** + * Letter spacing (typographic tracking) for a + * {@link DocumentTextStyle} — extra advance inserted after every rendered + * code point, expressed either in absolute points or as a fraction of the font + * size. + * + *This is real tracking, not spaces: the string handed to the backend is the + * author's string, so the PDF text layer, search, copy/paste, text extraction + * and ATS parsing all still see {@code "JANE DOE"} for a headline that renders + * as widely spaced caps. Padding the string with literal spaces — the + * shape {@code "J A N E D O E"} — achieves the same picture and breaks + * every one of those.
+ * + *Prefer {@link #ofFontSize(double)}: expressed as a fraction, the tracking + * scales with the type, so one style value reads the same at 9pt as at 24pt and + * keeps its proportions under auto-size. {@link #points(double)} is there for + * the cases that are specified in absolute points. The unit lives in the value, + * so a call site says which one it meant — {@code ofFontSize(0.12)} and + * {@code points(1.2)} are both plausible-looking numbers and a bare + * {@code double} could not tell them apart.
+ * + *Negative tracking (tighter than normal) is allowed. {@link #NONE} is the + * neutral value carried by every style that has not opted in; it resolves to + * {@code 0} and leaves measurement and rendering exactly as they were. + * Instances are immutable and thread-safe.
+ * + *This value keeps exactly what it was given: {@link #resolve(double)} + * returns the amount asked for, to the last bit, and nothing rewrites it. The + * file formats are what quantise, and they do it differently:
+ * + *So an arbitrary {@code double} does not survive all three formats exactly, + * and no amount of care here would make it. What is guaranteed is that within + * fixed layout there is one number: what was measured, what the PDF states and + * what the deck states are the same value.
+ * + *Tracking larger than a format can state is refused when the document is + * rendered, rather than wrapped into a negative — fixed layout tops out at + * ±4000pt, DrawingML's own bound. The limits belong to the formats; this + * value accepts any finite number.
+ * + *{@code
+ * DocumentTextStyle headline = DocumentTextStyle.builder()
+ * .size(24)
+ * .letterSpacing(DocumentLetterSpacing.ofFontSize(0.12)) // 12% of 24pt = 2.88pt
+ * .build();
+ * }
+ *
+ * @param type whether {@code value} is read as points or as a fraction of the
+ * font size
+ * @param value the tracking amount, in the unit named by {@code type}
+ * @author Artem Demchyshyn
+ * @see DocumentTextStyle#letterSpacing()
+ * @since 2.4.0
+ */
+public record DocumentLetterSpacing(Type type, double value) {
+
+ /** The unit a tracking amount is expressed in. */
+ public enum Type {
+ /** {@code value} is an absolute amount in points. */
+ POINTS,
+ /** {@code value} is a fraction of the font size (an em share). */
+ FONT_SIZE
+ }
+
+ /**
+ * No tracking — the neutral value, and the default of every
+ * {@link DocumentTextStyle}. Resolves to {@code 0} at any font size.
+ */
+ public static final DocumentLetterSpacing NONE = new DocumentLetterSpacing(Type.POINTS, 0.0);
+
+ /**
+ * Validates the unit and the amount.
+ *
+ * @param type the unit; must not be {@code null}
+ * @param value the amount; must be finite, may be negative
+ */
+ public DocumentLetterSpacing {
+ if (type == null) {
+ throw new IllegalArgumentException("Letter-spacing type cannot be null.");
+ }
+ if (!Double.isFinite(value)) {
+ throw new IllegalArgumentException("Letter spacing must be a finite number, got: " + value);
+ }
+ // -0.0 renders identically to +0.0 but would compare unequal to it and
+ // hash differently, so it is folded. Note this does not make zero a
+ // single value: the factories return NONE for it, but
+ // new DocumentLetterSpacing(FONT_SIZE, 0.0) is still constructible and
+ // is not equal(NONE) — same behaviour, different unit, and the unit is
+ // the caller's to state.
+ value = value == 0.0 ? 0.0 : value;
+ }
+
+ /**
+ * Tracking of an absolute size, in points.
+ *
+ * @param points extra advance after each code point, in points; negative
+ * tightens, {@code 0} is {@link #NONE}
+ * @return a points-valued tracking
+ */
+ public static DocumentLetterSpacing points(double points) {
+ return points == 0.0 ? NONE : new DocumentLetterSpacing(Type.POINTS, points);
+ }
+
+ /**
+ * Tracking as a fraction of the font size, so it scales with the type.
+ *
+ * @param fraction share of the font size, e.g. {@code 0.12} for 12%;
+ * negative tightens, {@code 0} is {@link #NONE}
+ * @return a font-size-relative tracking
+ */
+ public static DocumentLetterSpacing ofFontSize(double fraction) {
+ return fraction == 0.0 ? NONE : new DocumentLetterSpacing(Type.FONT_SIZE, fraction);
+ }
+
+ /**
+ * Resolves this tracking to points against a concrete font size.
+ *
+ * A non-finite {@code fontSize} makes the tracking contribution + * {@code 0} instead of {@code NaN}. That bounds this term only — it says + * nothing about the rest of the measurement, which still multiplies glyph + * widths by that same font size. A non-finite font size remains a bad font + * size, and it is not this type's job to make it finite.
+ * + * @param fontSize the font size the text is set at, in points + * @return the extra advance per code point, in points + */ + public double resolve(double fontSize) { + return switch (type) { + case POINTS -> value; + case FONT_SIZE -> Double.isFinite(fontSize) ? value * fontSize : 0.0; + }; + } + + /** + * Whether this is the neutral value, i.e. it resolves to {@code 0} at every + * font size. + * + * @return {@code true} if no tracking is applied + */ + public boolean isNone() { + return value == 0.0; + } +} diff --git a/core/src/main/java/com/demcha/compose/document/style/DocumentTextStyle.java b/core/src/main/java/com/demcha/compose/document/style/DocumentTextStyle.java index 30ba09bcc..d517ffff0 100644 --- a/core/src/main/java/com/demcha/compose/document/style/DocumentTextStyle.java +++ b/core/src/main/java/com/demcha/compose/document/style/DocumentTextStyle.java @@ -18,13 +18,17 @@ * @param size font size in points * @param decoration text decoration * @param color text color + * @param letterSpacing typographic tracking; {@link DocumentLetterSpacing#NONE} + * (the default) leaves glyph advances exactly as they were * @author Artem Demchyshyn + * @see DocumentLetterSpacing */ public record DocumentTextStyle( FontName fontName, double size, DocumentTextDecoration decoration, - DocumentColor color + DocumentColor color, + DocumentLetterSpacing letterSpacing ) { public static final DocumentTextStyle DEFAULT = builder().build(); @@ -36,6 +40,27 @@ public record DocumentTextStyle( size = size <= 0 ? 14 : size; decoration = decoration == null ? DocumentTextDecoration.DEFAULT : decoration; color = color == null ? DocumentColor.BLACK : color; + letterSpacing = letterSpacing == null ? DocumentLetterSpacing.NONE : letterSpacing; + } + + /** + * Creates a normalized text style without tracking. + * + *The signature this type carried before {@code letterSpacing} was + * added. It stays so code compiled against the 2.0.0 surface keeps + * linking, and so the binary-compatibility gate still finds the + * constructor it has always found.
+ * + * @param fontName font family name + * @param size font size in points + * @param decoration text decoration + * @param color text color + */ + public DocumentTextStyle(FontName fontName, + double size, + DocumentTextDecoration decoration, + DocumentColor color) { + this(fontName, size, decoration, color, DocumentLetterSpacing.NONE); } /** @@ -54,7 +79,7 @@ public static Builder builder() { * @return updated text style */ public DocumentTextStyle withSize(double size) { - return new DocumentTextStyle(fontName, size, decoration, color); + return new DocumentTextStyle(fontName, size, decoration, color, letterSpacing); } /** @@ -64,7 +89,19 @@ public DocumentTextStyle withSize(double size) { * @return updated text style */ public DocumentTextStyle withColor(DocumentColor color) { - return new DocumentTextStyle(fontName, size, decoration, color); + return new DocumentTextStyle(fontName, size, decoration, color, letterSpacing); + } + + /** + * Creates a copy with different tracking. + * + * @param letterSpacing tracking to apply; {@code null} means + * {@link DocumentLetterSpacing#NONE} + * @return updated text style + * @since 2.4.0 + */ + public DocumentTextStyle withLetterSpacing(DocumentLetterSpacing letterSpacing) { + return new DocumentTextStyle(fontName, size, decoration, color, letterSpacing); } /** @@ -75,6 +112,7 @@ public static final class Builder { private double size = 14; private DocumentTextDecoration decoration = DocumentTextDecoration.DEFAULT; private DocumentColor color = DocumentColor.BLACK; + private DocumentLetterSpacing letterSpacing = DocumentLetterSpacing.NONE; private Builder() { } @@ -123,13 +161,33 @@ public Builder color(DocumentColor color) { return this; } + /** + * Sets the typographic tracking — extra advance after every + * rendered code point. + * + *Real tracking, not inserted spaces: the text handed to the + * backend stays the author's string, so search, copy/paste and text + * extraction still read it as written.
+ * + * @param letterSpacing tracking to apply, e.g. + * {@code DocumentLetterSpacing.ofFontSize(0.12)}; + * {@code null} means + * {@link DocumentLetterSpacing#NONE} + * @return this builder + * @since 2.4.0 + */ + public Builder letterSpacing(DocumentLetterSpacing letterSpacing) { + this.letterSpacing = Objects.requireNonNullElse(letterSpacing, DocumentLetterSpacing.NONE); + return this; + } + /** * Builds an immutable style value. * * @return text style */ public DocumentTextStyle build() { - return new DocumentTextStyle(fontName, size, decoration, color); + return new DocumentTextStyle(fontName, size, decoration, color, letterSpacing); } } } diff --git a/core/src/main/java/com/demcha/compose/engine/components/content/text/TextStyle.java b/core/src/main/java/com/demcha/compose/engine/components/content/text/TextStyle.java index b422f95d0..1b673a22e 100644 --- a/core/src/main/java/com/demcha/compose/engine/components/content/text/TextStyle.java +++ b/core/src/main/java/com/demcha/compose/engine/components/content/text/TextStyle.java @@ -5,8 +5,40 @@ import java.awt.*; +/** + * Engine-side text style. + * + *{@code letterSpacing} is the tracking already resolved to points: + * the public {@code DocumentLetterSpacing} keeps its unit (points or a share of + * the font size) and the single conversion seam resolves it, so nothing below + * this type has to remember to multiply by the font size.
+ * + * @param fontName font family name + * @param size font size in points + * @param decoration text decoration + * @param color text color + * @param letterSpacing tracking in points, already resolved; {@code 0} for none + */ @Builder -public record TextStyle(FontName fontName, double size, TextDecoration decoration, Color color) { +public record TextStyle(FontName fontName, + double size, + TextDecoration decoration, + Color color, + double letterSpacing) { public static TextStyle DEFAULT_STYLE = new TextStyle(FontName.HELVETICA, 14, TextDecoration.DEFAULT, Color.BLACK); + + /** + * Creates a style without tracking — the shape this record had before + * {@code letterSpacing} was added, kept so the existing engine call sites + * that build a style from four values stay as they are. + * + * @param fontName font family name + * @param size font size in points + * @param decoration text decoration + * @param color text color + */ + public TextStyle(FontName fontName, double size, TextDecoration decoration, Color color) { + this(fontName, size, decoration, color, 0.0); + } } diff --git a/core/src/main/java/com/demcha/compose/engine/text/markdown/MarkDownParser.java b/core/src/main/java/com/demcha/compose/engine/text/markdown/MarkDownParser.java index 7996d98a1..9d07a4d09 100644 --- a/core/src/main/java/com/demcha/compose/engine/text/markdown/MarkDownParser.java +++ b/core/src/main/java/com/demcha/compose/engine/text/markdown/MarkDownParser.java @@ -27,7 +27,7 @@ public ListThe public value keeps its unit; the engine is handed points. This is the + * only place that knows the unit and the font size at the same time, so it is + * the only place that can resolve one against the other — and the only + * place that has to be right about it.
+ */ +class LetterSpacingPropagationTest { + + @Test + void aStyleWithoutTrackingReachesTheEngineAsZero() { + TextStyle engineStyle = DocumentNodeAdapters.toTextStyle(DocumentTextStyle.DEFAULT); + + assertThat(engineStyle.letterSpacing()).isZero(); + } + + @Test + void aNullStyleFallsBackToTheEngineDefaultWhichHasNoTracking() { + assertThat(DocumentNodeAdapters.toTextStyle(null).letterSpacing()).isZero(); + assertThat(TextStyle.DEFAULT_STYLE.letterSpacing()).isZero(); + } + + @Test + void pointsCrossTheSeamUnchanged() { + DocumentTextStyle style = DocumentTextStyle.builder() + .size(24) + .letterSpacing(DocumentLetterSpacing.points(1.2)) + .build(); + + assertThat(DocumentNodeAdapters.toTextStyle(style).letterSpacing()).isEqualTo(1.2); + } + + @Test + void aFontSizeShareIsResolvedAgainstTheStylesOwnSizeBeforeTheEngineSeesIt() { + DocumentTextStyle style = DocumentTextStyle.builder() + .size(24) + .letterSpacing(DocumentLetterSpacing.ofFontSize(0.12)) + .build(); + + // 12% of 24pt. The engine never learns the share existed. + assertThat(DocumentNodeAdapters.toTextStyle(style).letterSpacing()).isEqualTo(2.88); + } + + @Test + void theShareIsResolvedAgainstTheNormalizedSizeNotTheRequestedOne() { + // DocumentTextStyle folds a non-positive size onto 14pt; the tracking + // has to follow the size the text is actually set at. + DocumentTextStyle style = DocumentTextStyle.builder() + .size(0) + .letterSpacing(DocumentLetterSpacing.ofFontSize(0.5)) + .build(); + + assertThat(style.size()).isEqualTo(14.0); + assertThat(DocumentNodeAdapters.toTextStyle(style).letterSpacing()).isEqualTo(7.0); + } + + @Test + void negativeTrackingSurvivesTheCrossing() { + DocumentTextStyle style = DocumentTextStyle.builder() + .size(20) + .letterSpacing(DocumentLetterSpacing.ofFontSize(-0.05)) + .build(); + + assertThat(DocumentNodeAdapters.toTextStyle(style).letterSpacing()).isEqualTo(-1.0); + } + + @Test + void everyOtherComponentStillCrossesAsItDid() { + DocumentTextStyle style = new DocumentTextStyle( + FontName.TIMES_ROMAN, 18, DocumentTextDecoration.BOLD, DocumentColor.rgb(17, 34, 51), + DocumentLetterSpacing.points(0.75)); + + TextStyle engineStyle = DocumentNodeAdapters.toTextStyle(style); + + assertThat(engineStyle.fontName()).isEqualTo(FontName.TIMES_ROMAN); + assertThat(engineStyle.size()).isEqualTo(18.0); + assertThat(engineStyle.color()).isEqualTo(DocumentColor.rgb(17, 34, 51).color()); + assertThat(engineStyle.letterSpacing()).isEqualTo(0.75); + } + + @Test + void theEngineStylesFourArgumentShapeStillMeansNoTracking() { + TextStyle style = new TextStyle( + FontName.HELVETICA, 12, + com.demcha.compose.engine.components.content.text.TextDecoration.DEFAULT, + java.awt.Color.BLACK); + + assertThat(style.letterSpacing()).isZero(); + } +} diff --git a/core/src/test/java/com/demcha/compose/document/style/DocumentLetterSpacingTest.java b/core/src/test/java/com/demcha/compose/document/style/DocumentLetterSpacingTest.java new file mode 100644 index 000000000..7fa07bccf --- /dev/null +++ b/core/src/test/java/com/demcha/compose/document/style/DocumentLetterSpacingTest.java @@ -0,0 +1,100 @@ +package com.demcha.compose.document.style; + +import org.junit.jupiter.api.Test; + +import static org.assertj.core.api.Assertions.assertThat; +import static org.assertj.core.api.Assertions.assertThatIllegalArgumentException; +import static org.assertj.core.api.Assertions.within; + +/** + * The tracking value itself: what it accepts, what it refuses, and how it + * resolves against the size the text is actually set at. + */ +class DocumentLetterSpacingTest { + + @Test + void noneResolvesToZeroAtEverySize() { + assertThat(DocumentLetterSpacing.NONE.isNone()).isTrue(); + assertThat(DocumentLetterSpacing.NONE.resolve(9)).isZero(); + assertThat(DocumentLetterSpacing.NONE.resolve(24)).isZero(); + assertThat(DocumentLetterSpacing.NONE.resolve(0)).isZero(); + } + + @Test + void pointsResolveToThemselvesRegardlessOfFontSize() { + DocumentLetterSpacing spacing = DocumentLetterSpacing.points(1.2); + + assertThat(spacing.type()).isEqualTo(DocumentLetterSpacing.Type.POINTS); + assertThat(spacing.resolve(9)).isEqualTo(1.2); + assertThat(spacing.resolve(24)).isEqualTo(1.2); + } + + @Test + void aFontSizeShareScalesWithTheType() { + DocumentLetterSpacing spacing = DocumentLetterSpacing.ofFontSize(0.12); + + assertThat(spacing.type()).isEqualTo(DocumentLetterSpacing.Type.FONT_SIZE); + assertThat(spacing.resolve(24)).isEqualTo(2.88); + assertThat(spacing.resolve(10)).isEqualTo(1.2); + } + + @Test + void theTwoUnitsAreDistinguishableAtTheSameNumber() { + // The whole reason this is a value type and not a bare double: 1.2 as + // points and 1.2 as a share of the font size are wildly different, and + // a double could not say which was meant. + assertThat(DocumentLetterSpacing.points(1.2)).isNotEqualTo(DocumentLetterSpacing.ofFontSize(1.2)); + // Points pass straight through, so this one is exact. The share is a + // product of two doubles (1.2 * 24 lands on 28.799999999999997), so it + // is asserted the way a float product has to be. + assertThat(DocumentLetterSpacing.points(1.2).resolve(24)).isEqualTo(1.2); + assertThat(DocumentLetterSpacing.ofFontSize(1.2).resolve(24)).isCloseTo(28.8, within(1e-9)); + } + + @Test + void negativeTrackingIsAllowedAndTightens() { + assertThat(DocumentLetterSpacing.points(-0.5).resolve(12)).isEqualTo(-0.5); + assertThat(DocumentLetterSpacing.ofFontSize(-0.05).resolve(20)).isEqualTo(-1.0); + } + + @Test + void zeroInEitherUnitFoldsOntoTheNeutralValue() { + assertThat(DocumentLetterSpacing.points(0)).isSameAs(DocumentLetterSpacing.NONE); + assertThat(DocumentLetterSpacing.ofFontSize(0)).isSameAs(DocumentLetterSpacing.NONE); + assertThat(DocumentLetterSpacing.points(-0.0)).isSameAs(DocumentLetterSpacing.NONE); + } + + @Test + void negativeZeroFoldsOntoPositiveZeroSoOneBehaviourHasOneValue() { + DocumentLetterSpacing minusZero = new DocumentLetterSpacing(DocumentLetterSpacing.Type.FONT_SIZE, -0.0); + + assertThat(minusZero.value()).isEqualTo(0.0); + assertThat(minusZero.isNone()).isTrue(); + assertThat(minusZero).isEqualTo(new DocumentLetterSpacing(DocumentLetterSpacing.Type.FONT_SIZE, 0.0)); + } + + @Test + void aNonFiniteAmountIsRefused() { + assertThatIllegalArgumentException() + .isThrownBy(() -> DocumentLetterSpacing.points(Double.NaN)); + assertThatIllegalArgumentException() + .isThrownBy(() -> DocumentLetterSpacing.ofFontSize(Double.POSITIVE_INFINITY)); + assertThatIllegalArgumentException() + .isThrownBy(() -> DocumentLetterSpacing.points(Double.NEGATIVE_INFINITY)); + } + + @Test + void aNullUnitIsRefused() { + assertThatIllegalArgumentException() + .isThrownBy(() -> new DocumentLetterSpacing(null, 1.0)); + } + + @Test + void aNonFiniteFontSizeMakesTheTrackingTermZeroNotNaN() { + // Bounds this term only. The rest of the measurement still multiplies + // glyph widths by the same bad font size, so this does not claim to + // make the resulting text width finite. + assertThat(DocumentLetterSpacing.ofFontSize(0.12).resolve(Double.NaN)).isZero(); + assertThat(DocumentLetterSpacing.ofFontSize(0.12).resolve(Double.POSITIVE_INFINITY)).isZero(); + } +} diff --git a/core/src/test/java/com/demcha/compose/document/style/DocumentTextStyleLetterSpacingTest.java b/core/src/test/java/com/demcha/compose/document/style/DocumentTextStyleLetterSpacingTest.java new file mode 100644 index 000000000..e2f260477 --- /dev/null +++ b/core/src/test/java/com/demcha/compose/document/style/DocumentTextStyleLetterSpacingTest.java @@ -0,0 +1,101 @@ +package com.demcha.compose.document.style; + +import com.demcha.compose.font.FontName; +import org.junit.jupiter.api.Test; + +import static org.assertj.core.api.Assertions.assertThat; + +/** + * How {@link DocumentTextStyle} carries tracking: the default costs nothing, + * the pre-existing constructor still means "no tracking", and the copy methods + * do not quietly drop it. + */ +class DocumentTextStyleLetterSpacingTest { + + @Test + void aStyleThatNeverAskedForTrackingHasNone() { + assertThat(DocumentTextStyle.DEFAULT.letterSpacing()).isEqualTo(DocumentLetterSpacing.NONE); + assertThat(DocumentTextStyle.builder().build().letterSpacing()).isEqualTo(DocumentLetterSpacing.NONE); + assertThat(DocumentTextStyle.DEFAULT.letterSpacing().resolve(DocumentTextStyle.DEFAULT.size())).isZero(); + } + + @Test + void theFourArgumentConstructorStillMeansNoTracking() { + DocumentTextStyle style = + new DocumentTextStyle(FontName.HELVETICA, 12, DocumentTextDecoration.BOLD, DocumentColor.BLACK); + + assertThat(style.letterSpacing()).isEqualTo(DocumentLetterSpacing.NONE); + } + + @Test + void aNullTrackingNormalizesToNone() { + DocumentTextStyle viaConstructor = + new DocumentTextStyle(FontName.HELVETICA, 12, DocumentTextDecoration.DEFAULT, DocumentColor.BLACK, null); + DocumentTextStyle viaBuilder = DocumentTextStyle.builder().letterSpacing(null).build(); + + assertThat(viaConstructor.letterSpacing()).isEqualTo(DocumentLetterSpacing.NONE); + assertThat(viaBuilder.letterSpacing()).isEqualTo(DocumentLetterSpacing.NONE); + } + + @Test + void theBuilderCarriesTrackingThrough() { + DocumentTextStyle style = DocumentTextStyle.builder() + .size(24) + .letterSpacing(DocumentLetterSpacing.ofFontSize(0.12)) + .build(); + + assertThat(style.letterSpacing()).isEqualTo(DocumentLetterSpacing.ofFontSize(0.12)); + assertThat(style.letterSpacing().resolve(style.size())).isEqualTo(2.88); + } + + @Test + void withSizeKeepsTheTrackingAndRescalesAFontSizeShare() { + DocumentTextStyle style = DocumentTextStyle.builder() + .size(10) + .letterSpacing(DocumentLetterSpacing.ofFontSize(0.1)) + .build(); + + DocumentTextStyle bigger = style.withSize(30); + + assertThat(bigger.letterSpacing()).isEqualTo(DocumentLetterSpacing.ofFontSize(0.1)); + // The share is kept, so the resolved amount follows the new size. + assertThat(bigger.letterSpacing().resolve(bigger.size())).isEqualTo(3.0); + } + + @Test + void withColorKeepsTheTracking() { + DocumentTextStyle style = DocumentTextStyle.builder() + .letterSpacing(DocumentLetterSpacing.points(1.5)) + .build(); + + assertThat(style.withColor(DocumentColor.rgb(255, 0, 0)).letterSpacing()) + .isEqualTo(DocumentLetterSpacing.points(1.5)); + } + + @Test + void withLetterSpacingReplacesOnlyTheTracking() { + DocumentTextStyle style = DocumentTextStyle.builder() + .fontName(FontName.TIMES_ROMAN) + .size(18) + .decoration(DocumentTextDecoration.ITALIC) + .color(DocumentColor.rgb(18, 52, 86)) + .build(); + + DocumentTextStyle tracked = style.withLetterSpacing(DocumentLetterSpacing.points(2)); + + assertThat(tracked.letterSpacing()).isEqualTo(DocumentLetterSpacing.points(2)); + assertThat(tracked.fontName()).isEqualTo(style.fontName()); + assertThat(tracked.size()).isEqualTo(style.size()); + assertThat(tracked.decoration()).isEqualTo(style.decoration()); + assertThat(tracked.color()).isEqualTo(style.color()); + } + + @Test + void trackingTakesPartInEquality() { + DocumentTextStyle plain = DocumentTextStyle.builder().size(12).build(); + DocumentTextStyle tracked = plain.withLetterSpacing(DocumentLetterSpacing.points(1)); + + assertThat(tracked).isNotEqualTo(plain); + assertThat(tracked.withLetterSpacing(DocumentLetterSpacing.NONE)).isEqualTo(plain); + } +} diff --git a/docs/recipes.md b/docs/recipes.md index 9b243c2f4..d1e47c602 100644 --- a/docs/recipes.md +++ b/docs/recipes.md @@ -22,6 +22,7 @@ authoring API; public application code should not import | [Tables](recipes/tables.md) | Row span, zebra rows, totals row, repeated header on page break | | [Text direction](recipes/text-direction.md) | `TextDirection` — right-to-left paragraphs, `AUTO` resolved from the text, mixed lines, and the bundled Hebrew / Arabic families | | [Rich text](recipes/rich-text.md) | `RichText` mixed-style runs in one paragraph: bold/accent/styled segments, inline links, inline images, inline SVG icons, emoji shortcodes, inline shapes and checkboxes | +| [Letter spacing](recipes/letter-spacing.md) | `DocumentLetterSpacing` — real typographic tracking for spaced caps, declared natively in PDF / PPTX / DOCX so the text layer still holds the word | | [Lists](recipes/lists.md) | `addList`: quick bulleted lists, marker customisation, nested lists with per-depth markers, spacing and styled items | | [Timelines](recipes/timelines.md) | `addTimeline`: the leading / axis / content model, markers (dot / circle / numbered / square / custom), leading column, axis sizing, `markerOnRail()`, rail extent, pagination, backends | | [Barcodes](recipes/barcodes.md) | QR / Code 128 / Code 39 / EAN / UPC / PDF417 / DataMatrix, tinting, quiet zone, card centring | diff --git a/docs/recipes/letter-spacing.md b/docs/recipes/letter-spacing.md new file mode 100644 index 000000000..462f77e0d --- /dev/null +++ b/docs/recipes/letter-spacing.md @@ -0,0 +1,113 @@ +# Letter spacing: spaced caps without wrecking the text + +Wide-set capitals are a typographic effect — a name across the top of a +CV, a section banner, an eyebrow label. The obvious way to draw them is +to put a space between every pair of letters, and it is the wrong way: +the picture is right and the file is wrong. `"JANE DOE"` written as +`"J A N E D O E"` is what search, copy/paste, a screen reader and an +applicant-tracking parser then read. + +`DocumentLetterSpacing` moves the pen instead of the text. + +```java +import com.demcha.compose.document.style.DocumentLetterSpacing; +import com.demcha.compose.document.style.DocumentTextStyle; + +DocumentTextStyle headline = DocumentTextStyle.builder() + .fontName(FontName.LATO) + .size(22) + .letterSpacing(DocumentLetterSpacing.ofFontSize(0.18)) + .build(); + +section.addParagraph(p -> p.text("JANE DOE").textStyle(headline)); +``` + +The page shows spaced caps; the file still says `JANE DOE`. + +## Two units, and why the value names its own + +```java +DocumentLetterSpacing.ofFontSize(0.18) // 18% of the font size +DocumentLetterSpacing.points(1.2) // 1.2 points, whatever the size +``` + +Prefer `ofFontSize`. Expressed as a share, the tracking scales with the +type, so one style value reads the same on a 24pt name as on an 8pt +label — and keeps its proportions under auto-size. `points` is there for +designs specified in absolute measure. + +The unit lives in the value rather than in a bare `double` because +`0.18` and `1.2` are both plausible-looking numbers and a call site +passing one has no way to say which it meant. + +Negative values tighten. `DocumentLetterSpacing.NONE` is the default and +resolves to zero at every size, so a style that never mentions tracking +renders exactly as it did. + +## What each format can express + +Tracking is declared natively, never faked, in all three outputs — PDF's +`Tc`, DrawingML's `spc`, Word's `w:spacing`. They do not all measure the +same, though: + +| | granularity | why | +|---|---|---| +| PDF and PPTX | **0.01pt** | DrawingML states spacing in hundredths of a point, so that is the finest distinction a PDF and a deck can both make. The engine measures on that grid, which keeps the width it reserves equal to the width the file draws. | +| DOCX | **0.05pt** | Word states spacing in twentieths and owns its own layout, so the export rounds to that grid independently. | + +The value you wrote is never rewritten: `resolve(fontSize)` returns what +you asked for. Ask for a third of a point and the fixed-layout formats +both use `0.33`; that is the grid, not a loss of your value. + +Tracking larger than a format can state is refused when the document is +rendered rather than silently wrapped — fixed layout tops out at +±4000pt, which is DrawingML's own bound. + +## Where the spacing lands + +One unit goes after **every** code point, the last one included, and an +ordinary space is spaced like any other character. That is what the PDF +`Tc` operator does, and PowerPoint and Word were measured doing the same. + +The practical consequence: a centred or right-aligned tracked line is +aligned on a width that includes that trailing unit, so it sits half a +unit left of where an untracked line of the same glyphs would. This is +also how CSS `letter-spacing` behaves. + +## The built-in presets + +The bundled CV and cover-letter presets use `ofFontSize(0.18)` for their +spaced-caps blocks, exposed as +`TextOrnaments.SPACED_CAPS`. Reach for the same constant if you are +writing a preset that should match them. + +### Coming from `TextOrnaments.spacedUpper` + +`spacedUpper(...)` drew spaced caps by rewriting the string with a space +between every pair of letters. It still exists and still behaves exactly +as it always did, but it is deprecated as of 2.4.0 and no built-in preset +calls it any longer. Put the text through `TextOrnaments.upper(...)` and +carry the spacing on the style instead — `SPACED_CAPS`, or any +`DocumentLetterSpacing` you prefer: + +```java +// before — the spacing is in the string +String text = TextOrnaments.spacedUpper(name); + +// after — the spacing is in the style +String text = TextOrnaments.upper(name); +DocumentTextStyle resolved = style.withLetterSpacing(TextOrnaments.SPACED_CAPS); +``` + +The reason to move is the text layer, not the look: padding the string is +what stored a name in the file as `J A N E D O E`, so that is what +search, copy/paste, screen readers and applicant-tracking parsers saw. + +The two do not render at identical widths. A whole space glyph per gap is +wider than editorial tracking, which is why `0.18` was chosen to match the +old *total* width rather than the old per-gap width. + +Runnable showcase: +[LetterSpacingExample](../../examples/src/main/java/com/demcha/examples/features/text/LetterSpacingExample.java) +— renders the same name at four trackings and prints what each of the +three formats says its text is. diff --git a/examples/README.md b/examples/README.md index 6652854de..c2dc391c4 100644 --- a/examples/README.md +++ b/examples/README.md @@ -119,6 +119,7 @@ are with the canonical DSL, then jump to its detailed section below. | [World scripts](#world-scripts) | One card per bundled script — Arabic, Hebrew, Georgian, Armenian, Korean — each set in its own `FontName` family | [PDF](../assets/readme/examples/world-scripts.pdf) · [Source](src/main/java/com/demcha/examples/features/text/WorldScriptsExample.java) | | [Inline shapes](#inline-shapes) | `InlineShapeRun` — dots, arrows, chevrons, diamonds, stars, checkmarks and checkboxes drawn as geometry on the text baseline | [PDF](../assets/readme/examples/inline-shapes.pdf) · [Source](src/main/java/com/demcha/examples/features/text/InlineShapesExample.java) | | [Inline highlight chips](#inline-highlight-chips) | `RichText.code(text)` / `chip(text, fg, bg)` / `highlight(text, style, bg, radius, padding)` — text on a rounded padded fill (inline code + status badges), wrapping across lines | [PDF](../assets/readme/examples/inline-highlight-chips.pdf) · [Source](src/main/java/com/demcha/examples/features/text/InlineHighlightExample.java) | +| [Letter spacing](#letter-spacing) | `DocumentTextStyle.builder().letterSpacing(DocumentLetterSpacing.ofFontSize(0.18))` — real typographic tracking through PDF `Tc`, DrawingML `spc` and Word `w:spacing`, so wide caps still copy and search as the word they are | [PDF](../assets/readme/examples/letter-spacing.pdf) · [Source](src/main/java/com/demcha/examples/features/text/LetterSpacingExample.java) | | [Inline SVG icons](#inline-svg-icons) | `RichText.svgIcon(icon, size)` — a parsed multi-colour `SvgIcon` on the text baseline, crisp at any zoom and carrying its own colours | [PDF](../assets/readme/examples/inline-svg-icons.pdf) · [Source](src/main/java/com/demcha/examples/features/text/InlineSvgIconExample.java) | | [Colour emoji](#colour-emoji) | `RichText.emoji(":star:", size)` — GitHub-style shortcodes resolve to inline vector glyphs via the `graph-compose-emoji` artifact; unknown codes fall back to literal text | [PDF](../assets/readme/examples/emoji-shortcodes.pdf) · [Source](src/main/java/com/demcha/examples/features/text/EmojiShortcodeExample.java) | | [Section presets](#section-presets) | `pageBackground`, `band`, `softPanel`, `accentLeft / Right / Top / Bottom`, per-corner `DocumentCornerRadius` | [PDF](../assets/readme/examples/section-presets.pdf) · [Source](src/main/java/com/demcha/examples/features/text/SectionPresetsExample.java) | @@ -784,6 +785,27 @@ across lines, painting one continuous rounded fill per visual fragment. On [📄 View PDF](../assets/readme/examples/inline-highlight-chips.pdf) · [📜 Full source](src/main/java/com/demcha/examples/features/text/InlineHighlightExample.java) +### Letter spacing + +`DocumentTextStyle.builder().letterSpacing(...)` (`@since 2.4.0`) takes a +`DocumentLetterSpacing` — `ofFontSize(0.18)` for a share of the type that scales +with it, or `points(1.2)` for an absolute amount; negative values tighten. The +advance is the format's own (PDF `Tc`, DrawingML `spc`, Word `w:spacing`), so the +string in the file stays the string that was typed: a headline set in wide caps +still copies, searches and parses as `JANE DOE` rather than `J A N E D O E`. +The example prints back what each of the three formats says its text is. + + +```java +.textStyle(DocumentTextStyle.builder() + .fontName(FontName.LATO).size(22) + .letterSpacing(DocumentLetterSpacing.ofFontSize(0.18)) + .build()) +``` + +[📄 View PDF](../assets/readme/examples/letter-spacing.pdf) · +[📜 Full source](src/main/java/com/demcha/examples/features/text/LetterSpacingExample.java) + ### Inline SVG icons `RichText.svgIcon(icon, size)` / `ParagraphBuilder.inlineSvgIcon(...)` diff --git a/examples/src/main/java/com/demcha/examples/GenerateAllExamples.java b/examples/src/main/java/com/demcha/examples/GenerateAllExamples.java index a88b6c4e5..201445dee 100644 --- a/examples/src/main/java/com/demcha/examples/GenerateAllExamples.java +++ b/examples/src/main/java/com/demcha/examples/GenerateAllExamples.java @@ -31,6 +31,7 @@ import com.demcha.examples.features.text.EmojiShortcodeExample; import com.demcha.examples.features.text.EmojiSvgVsPngExample; import com.demcha.examples.features.text.EmojiClipPathReportExample; +import com.demcha.examples.features.text.LetterSpacingExample; import com.demcha.examples.features.text.InlineShapesExample; import com.demcha.examples.features.text.ArabicArticleExample; import com.demcha.examples.features.text.HebrewInvoiceExample; @@ -197,6 +198,7 @@ public static void main(String[] args) throws Exception { // Text + sections System.out.println("Generated: " + InlineShapesExample.generate()); + System.out.println("Generated: " + LetterSpacingExample.generate()); System.out.println("Generated: " + TextDirectionExample.generate()); System.out.println("Generated: " + ArabicArticleExample.generate()); System.out.println("Generated: " + HebrewInvoiceExample.generate()); diff --git a/examples/src/main/java/com/demcha/examples/features/text/LetterSpacingExample.java b/examples/src/main/java/com/demcha/examples/features/text/LetterSpacingExample.java new file mode 100644 index 000000000..14a2cb3e0 --- /dev/null +++ b/examples/src/main/java/com/demcha/examples/features/text/LetterSpacingExample.java @@ -0,0 +1,186 @@ +package com.demcha.examples.features.text; + +import com.demcha.compose.GraphCompose; +import com.demcha.compose.document.api.DocumentPageSize; +import com.demcha.compose.document.api.DocumentSession; +import com.demcha.compose.document.backend.semantic.docx.DocxSemanticBackend; +import com.demcha.compose.document.node.TextAlign; +import com.demcha.compose.document.style.DocumentColor; +import com.demcha.compose.document.style.DocumentInsets; +import com.demcha.compose.document.style.DocumentLetterSpacing; +import com.demcha.compose.document.style.DocumentTextDecoration; +import com.demcha.compose.document.style.DocumentTextStyle; +import com.demcha.compose.font.FontName; +import com.demcha.examples.support.ExampleOutputPaths; +import org.apache.pdfbox.Loader; +import org.apache.pdfbox.pdmodel.PDDocument; +import org.apache.pdfbox.text.PDFTextStripper; + +import java.nio.file.Files; +import java.nio.file.Path; + +/** + * Runnable showcase for letter spacing ({@code @since 2.4.0}). + * + *Spaced caps used to be drawn by rewriting the string with a space between + * every pair of letters. That draws the right picture and ruins the file: the + * name in a CV came back out of it as {@code "J A N E D O E"}, so search, + * copy/paste, a screen reader and an applicant-tracking parser all missed the + * one field the document is looked up by.
+ * + *{@code DocumentLetterSpacing} moves the pen instead of the text. This + * example renders the same headline three ways, then reads its own output back + * and prints what each format says the text is — which is the whole + * point, and not something a look at the page can tell you.
+ */ +public final class LetterSpacingExample { + + private static final String NAME = "Jane O'Doe-Smith 3rd"; + private static final DocumentColor INK = DocumentColor.rgb(24, 28, 38); + private static final DocumentColor MUTED = DocumentColor.rgb(112, 116, 128); + private static final DocumentColor BRAND = DocumentColor.rgb(20, 80, 95); + + private LetterSpacingExample() { + } + + public static Path generate() throws Exception { + Path outputFile = ExampleOutputPaths.prepare("features/text", "letter-spacing.pdf"); + byte[] pdf; + + try (DocumentSession document = GraphCompose.document() + .pageSize(DocumentPageSize.A4) + .margin(40, 40, 40, 40) + .create()) { + compose(document); + pdf = document.toPdfBytes(); + } + Files.write(outputFile, pdf); + + // The picture is on the page; this is the half of the feature that is + // not. Printed rather than asserted, because an example should show the + // thing it claims. + System.out.println("PDF text layer : \"" + extracted(pdf) + "\""); + System.out.println("PPTX text : \"" + pptxText() + "\""); + System.out.println("DOCX text : \"" + docxText() + "\""); + + return outputFile; + } + + private static void compose(DocumentSession document) { + document.pageFlow() + .name("LetterSpacingShowcase") + .spacing(18) + .addSection("Intro", section -> section + .spacing(6) + .addParagraph(p -> p + .text("Letter spacing") + .textStyle(heading()) + .margin(DocumentInsets.zero())) + .addParagraph(p -> p + .text("The same name, set three ways. Select any of them and " + + "paste: the clipboard holds the name, not the spacing.") + .textStyle(body()) + .margin(DocumentInsets.zero()))) + .addSection("None", section -> specimen(section, + "no tracking", DocumentLetterSpacing.NONE)) + .addSection("Editorial", section -> specimen(section, + "ofFontSize(0.18) — what the built-in CV presets use", + DocumentLetterSpacing.ofFontSize(0.18))) + .addSection("Wide", section -> specimen(section, + "ofFontSize(0.4) — deliberately extreme", + DocumentLetterSpacing.ofFontSize(0.4))) + .addSection("Tight", section -> specimen(section, + "points(-0.4) — negative tracking tightens", + DocumentLetterSpacing.points(-0.4))) + .build(); + } + + private static void specimen(com.demcha.compose.document.dsl.SectionBuilder section, + String caption, + DocumentLetterSpacing spacing) { + section.spacing(4) + .addParagraph(p -> p + .text(caption) + .textStyle(caption()) + .margin(DocumentInsets.zero())) + .addParagraph(p -> p + .text(NAME.toUpperCase(java.util.Locale.ROOT)) + .textStyle(display().withLetterSpacing(spacing)) + .align(TextAlign.LEFT) + .margin(DocumentInsets.zero())); + } + + private static String extracted(byte[] pdf) throws Exception { + try (PDDocument document = Loader.loadPDF(pdf)) { + String text = new PDFTextStripper().getText(document); + for (String line : text.split("\\R")) { + if (line.contains("O'DOE")) { + return line.trim(); + } + } + return "(not found)"; + } + } + + private static String pptxText() throws Exception { + try (DocumentSession document = GraphCompose.document() + .pageSize(DocumentPageSize.A4).margin(40, 40, 40, 40).create()) { + compose(document); + byte[] pptx = document.toPptxBytes(); + try (var show = new org.apache.poi.xslf.usermodel.XMLSlideShow( + new java.io.ByteArrayInputStream(pptx))) { + for (var shape : show.getSlides().get(0).getShapes()) { + if (shape instanceof org.apache.poi.xslf.usermodel.XSLFTextShape textShape + && textShape.getText().contains("O'DOE")) { + return textShape.getText().trim(); + } + } + } + } + return "(not found)"; + } + + private static String docxText() throws Exception { + try (DocumentSession document = GraphCompose.document() + .pageSize(DocumentPageSize.A4).margin(40, 40, 40, 40).create()) { + compose(document); + byte[] docx = document.export(new DocxSemanticBackend()); + try (var word = new org.apache.poi.xwpf.usermodel.XWPFDocument( + new java.io.ByteArrayInputStream(docx))) { + for (var paragraph : word.getParagraphs()) { + if (paragraph.getText().contains("O'DOE")) { + return paragraph.getText().trim(); + } + } + } + } + return "(not found)"; + } + + private static DocumentTextStyle display() { + return DocumentTextStyle.builder() + .fontName(FontName.LATO).size(22) + .decoration(DocumentTextDecoration.BOLD).color(INK).build(); + } + + private static DocumentTextStyle heading() { + return DocumentTextStyle.builder() + .fontName(FontName.LATO).size(26) + .decoration(DocumentTextDecoration.BOLD).color(BRAND).build(); + } + + private static DocumentTextStyle body() { + return DocumentTextStyle.builder() + .fontName(FontName.LATO).size(10).color(MUTED).build(); + } + + private static DocumentTextStyle caption() { + return DocumentTextStyle.builder() + .fontName(FontName.LATO).size(8.5) + .decoration(DocumentTextDecoration.BOLD).color(MUTED).build(); + } + + public static void main(String[] args) throws Exception { + System.out.println("Wrote " + generate()); + } +} diff --git a/knowledge/api/authoring.json b/knowledge/api/authoring.json index ebfdc6605..10a85a758 100644 --- a/knowledge/api/authoring.json +++ b/knowledge/api/authoring.json @@ -22,10 +22,10 @@ "graph-compose-testing:sources" ], "counts": { - "types": 235, - "methods": 2093, - "constants": 234, - "generated": 1117 + "types": 237, + "methods": 2107, + "constants": 237, + "generated": 1126 }, "packages": [ { @@ -29241,6 +29241,136 @@ } ] }, + { + "name": "DocumentLetterSpacing", + "binaryName": "com.demcha.compose.document.style.DocumentLetterSpacing", + "kind": "record", + "modifiers": [ + "final" + ], + "artifact": "graph-compose-core", + "members": [ + { + "kind": "constant", + "name": "NONE", + "static": true, + "origin": "generated", + "type": "DocumentLetterSpacing" + }, + { + "kind": "constructor", + "name": "DocumentLetterSpacing", + "static": false, + "origin": "generated", + "typeParameters": null, + "returns": null, + "params": [ + { + "type": "DocumentLetterSpacing.Type", + "name": null + }, + { + "type": "double", + "name": null + } + ] + }, + { + "kind": "method", + "name": "points", + "static": true, + "origin": "source", + "typeParameters": null, + "returns": "DocumentLetterSpacing", + "params": [ + { + "type": "double", + "name": "points" + } + ] + }, + { + "kind": "method", + "name": "ofFontSize", + "static": true, + "origin": "source", + "typeParameters": null, + "returns": "DocumentLetterSpacing", + "params": [ + { + "type": "double", + "name": "fraction" + } + ] + }, + { + "kind": "method", + "name": "resolve", + "static": false, + "origin": "source", + "typeParameters": null, + "returns": "double", + "params": [ + { + "type": "double", + "name": "fontSize" + } + ] + }, + { + "kind": "method", + "name": "isNone", + "static": false, + "origin": "source", + "typeParameters": null, + "returns": "boolean", + "params": [] + }, + { + "kind": "method", + "name": "type", + "static": false, + "origin": "generated", + "typeParameters": null, + "returns": "DocumentLetterSpacing.Type", + "params": [] + }, + { + "kind": "method", + "name": "value", + "static": false, + "origin": "generated", + "typeParameters": null, + "returns": "double", + "params": [] + } + ] + }, + { + "name": "DocumentLetterSpacing.Type", + "binaryName": "com.demcha.compose.document.style.DocumentLetterSpacing$Type", + "kind": "enum", + "modifiers": [ + "final" + ], + "artifact": "graph-compose-core", + "members": [ + { + "kind": "constant", + "name": "POINTS", + "static": true, + "origin": "generated", + "type": "DocumentLetterSpacing.Type" + }, + { + "kind": "constant", + "name": "FONT_SIZE", + "static": true, + "origin": "generated", + "type": "DocumentLetterSpacing.Type" + } + ] + }, { "name": "DocumentLineCap", "binaryName": "com.demcha.compose.document.style.DocumentLineCap", @@ -30269,6 +30399,36 @@ { "type": "DocumentColor", "name": null + }, + { + "type": "DocumentLetterSpacing", + "name": null + } + ] + }, + { + "kind": "constructor", + "name": "DocumentTextStyle", + "static": false, + "origin": "source", + "typeParameters": null, + "returns": null, + "params": [ + { + "type": "FontName", + "name": "fontName" + }, + { + "type": "double", + "name": "size" + }, + { + "type": "DocumentTextDecoration", + "name": "decoration" + }, + { + "type": "DocumentColor", + "name": "color" } ] }, @@ -30309,6 +30469,20 @@ } ] }, + { + "kind": "method", + "name": "withLetterSpacing", + "static": false, + "origin": "source", + "typeParameters": null, + "returns": "DocumentTextStyle", + "params": [ + { + "type": "DocumentLetterSpacing", + "name": "letterSpacing" + } + ] + }, { "kind": "method", "name": "fontName", @@ -30344,6 +30518,15 @@ "typeParameters": null, "returns": "DocumentColor", "params": [] + }, + { + "kind": "method", + "name": "letterSpacing", + "static": false, + "origin": "generated", + "typeParameters": null, + "returns": "DocumentLetterSpacing", + "params": [] } ] }, @@ -30412,6 +30595,20 @@ } ] }, + { + "kind": "method", + "name": "letterSpacing", + "static": false, + "origin": "source", + "typeParameters": null, + "returns": "DocumentTextStyle.Builder", + "params": [ + { + "type": "DocumentLetterSpacing", + "name": "letterSpacing" + } + ] + }, { "kind": "method", "name": "build", @@ -32841,6 +33038,32 @@ "artifact": "graph-compose-core", "reachedVia": "referenced by admitted API", "members": [ + { + "kind": "constructor", + "name": "TextStyle", + "static": false, + "origin": "source", + "typeParameters": null, + "returns": null, + "params": [ + { + "type": "FontName", + "name": "fontName" + }, + { + "type": "double", + "name": "size" + }, + { + "type": "TextDecoration", + "name": "decoration" + }, + { + "type": "Color", + "name": "color" + } + ] + }, { "kind": "constructor", "name": "TextStyle", @@ -32864,6 +33087,10 @@ { "type": "Color", "name": null + }, + { + "type": "double", + "name": null } ] }, @@ -32911,6 +33138,15 @@ "typeParameters": null, "returns": "Color", "params": [] + }, + { + "kind": "method", + "name": "letterSpacing", + "static": false, + "origin": "generated", + "typeParameters": null, + "returns": "double", + "params": [] } ] }, @@ -32978,6 +33214,20 @@ } ] }, + { + "kind": "method", + "name": "letterSpacing", + "static": false, + "origin": "generated", + "typeParameters": null, + "returns": "TextStyle.TextStyleBuilder", + "params": [ + { + "type": "double", + "name": null + } + ] + }, { "kind": "method", "name": "build", diff --git a/knowledge/api/authoring.md b/knowledge/api/authoring.md index 4039d7bdb..e531a52b1 100644 --- a/knowledge/api/authoring.md +++ b/knowledge/api/authoring.md @@ -28,7 +28,7 @@ note: "Generated from the pinned artifact's class files. Authoritative closed se **GraphCompose version:** 2.4.0-SNAPSHOT -Types: 235 · methods: 2093 · constants: 234 · compiler-generated members: 1117 +Types: 237 · methods: 2107 · constants: 237 · compiler-generated members: 1126 ## com.demcha.compose @@ -2185,6 +2185,19 @@ Types: 235 · methods: 2093 · constants: 234 · compiler-generated members: 111 ### DocumentLeader (enum) - constants: `NONE`, `DOTS`, `DASHES` +### DocumentLetterSpacing (record) +- `new DocumentLetterSpacing(DocumentLetterSpacing.Type, double)` +- `DocumentLetterSpacing points(double points)` +- `DocumentLetterSpacing ofFontSize(double fraction)` +- `double resolve(double fontSize)` +- `boolean isNone()` +- `DocumentLetterSpacing.Type type()` +- `double value()` +- constants: `NONE` + +### DocumentLetterSpacing.Type (enum) +- constants: `POINTS`, `FONT_SIZE` + ### DocumentLineCap (enum) - `int pdfCode()` - constants: `BUTT`, `ROUND`, `SQUARE` @@ -2273,14 +2286,17 @@ Types: 235 · methods: 2093 · constants: 234 · compiler-generated members: 111 - constants: `NONE`, `FIRST_LINE`, `FROM_SECOND_LINE`, `ALL_LINES` ### DocumentTextStyle (record) -- `new DocumentTextStyle(FontName, double, DocumentTextDecoration, DocumentColor)` +- `new DocumentTextStyle(FontName, double, DocumentTextDecoration, DocumentColor, DocumentLetterSpacing)` +- `new DocumentTextStyle(FontName fontName, double size, DocumentTextDecoration decoration, DocumentColor color)` - `DocumentTextStyle.Builder builder()` - `DocumentTextStyle withSize(double size)` - `DocumentTextStyle withColor(DocumentColor color)` +- `DocumentTextStyle withLetterSpacing(DocumentLetterSpacing letterSpacing)` - `FontName fontName()` - `double size()` - `DocumentTextDecoration decoration()` - `DocumentColor color()` +- `DocumentLetterSpacing letterSpacing()` - constants: `DEFAULT` ### DocumentTextStyle.Builder (class) @@ -2288,6 +2304,7 @@ Types: 235 · methods: 2093 · constants: 234 · compiler-generated members: 111 - `DocumentTextStyle.Builder size(double size)` - `DocumentTextStyle.Builder decoration(DocumentTextDecoration decoration)` - `DocumentTextStyle.Builder color(DocumentColor color)` +- `DocumentTextStyle.Builder letterSpacing(DocumentLetterSpacing letterSpacing)` - `DocumentTextStyle build()` ### DocumentTransform (record) @@ -2501,18 +2518,21 @@ Types: 235 · methods: 2093 · constants: 234 · compiler-generated members: 111 - constants: `DEFAULT`, `BOLD`, `ITALIC`, `BOLD_ITALIC`, `UNDERLINE`, `STRIKETHROUGH` ### TextStyle (record) -- `new TextStyle(FontName, double, TextDecoration, Color)` +- `new TextStyle(FontName fontName, double size, TextDecoration decoration, Color color)` +- `new TextStyle(FontName, double, TextDecoration, Color, double)` - `TextStyle.TextStyleBuilder builder()` - `FontName fontName()` - `double size()` - `TextDecoration decoration()` - `Color color()` +- `double letterSpacing()` ### TextStyle.TextStyleBuilder (class) - `TextStyle.TextStyleBuilder fontName(FontName)` - `TextStyle.TextStyleBuilder size(double)` - `TextStyle.TextStyleBuilder decoration(TextDecoration)` - `TextStyle.TextStyleBuilder color(Color)` +- `TextStyle.TextStyleBuilder letterSpacing(double)` - `TextStyle build()` ## com.demcha.compose.engine.components.geometry diff --git a/knowledge/api/templates.json b/knowledge/api/templates.json index 447855dbf..90f43ab37 100644 --- a/knowledge/api/templates.json +++ b/knowledge/api/templates.json @@ -23,9 +23,9 @@ ], "counts": { "types": 161, - "methods": 953, - "constants": 117, - "generated": 402 + "methods": 954, + "constants": 118, + "generated": 403 }, "packages": [ { @@ -1436,6 +1436,27 @@ ], "artifact": "graph-compose-templates", "members": [ + { + "kind": "constant", + "name": "SPACED_CAPS", + "static": true, + "origin": "generated", + "type": "DocumentLetterSpacing" + }, + { + "kind": "method", + "name": "upper", + "static": true, + "origin": "source", + "typeParameters": null, + "returns": "String", + "params": [ + { + "type": "String", + "name": "value" + } + ] + }, { "kind": "method", "name": "spacedUpper", diff --git a/knowledge/api/templates.md b/knowledge/api/templates.md index cf770d0fd..52bbde25b 100644 --- a/knowledge/api/templates.md +++ b/knowledge/api/templates.md @@ -28,7 +28,7 @@ note: "Generated from the pinned artifact's class files. Authoritative closed se **GraphCompose version:** 2.4.0-SNAPSHOT -Types: 161 · methods: 953 · constants: 117 · compiler-generated members: 402 +Types: 161 · methods: 954 · constants: 118 · compiler-generated members: 403 ## com.demcha.compose.document.templates.api @@ -134,8 +134,10 @@ Types: 161 · methods: 953 · constants: 117 · compiler-generated members: 402 - `void render(SectionBuilder host, String text, DocumentTextStyle style, double lineSpacing, DocumentInsets margin, TextAlign align)` ### TextOrnaments (class) +- `String upper(String value)` - `String spacedUpper(String value)` - `String joinPipe(String... parts)` +- constants: `SPACED_CAPS` ### TextStyles (class) - `DocumentTextStyle of(FontName font, double size, DocumentTextDecoration decoration, DocumentColor color)` diff --git a/qa/src/test/java/com/demcha/compose/document/api/LetterSpacingAcrossBackendsTest.java b/qa/src/test/java/com/demcha/compose/document/api/LetterSpacingAcrossBackendsTest.java new file mode 100644 index 000000000..19a29b390 --- /dev/null +++ b/qa/src/test/java/com/demcha/compose/document/api/LetterSpacingAcrossBackendsTest.java @@ -0,0 +1,202 @@ +package com.demcha.compose.document.api; + +import com.demcha.compose.GraphCompose; +import com.demcha.compose.document.backend.fixed.pdf.PdfFixedLayoutBackend; +import com.demcha.compose.document.backend.fixed.pptx.PptxFixedLayoutBackend; +import com.demcha.compose.document.backend.semantic.docx.DocxSemanticBackend; +import com.demcha.compose.document.style.DocumentInsets; +import com.demcha.compose.document.style.DocumentLetterSpacing; +import com.demcha.compose.document.style.DocumentTextStyle; +import com.demcha.compose.font.FontName; +import org.apache.pdfbox.Loader; +import org.apache.pdfbox.pdmodel.PDDocument; +import org.apache.pdfbox.text.PDFTextStripper; +import org.apache.poi.xslf.usermodel.XMLSlideShow; +import org.apache.poi.xslf.usermodel.XSLFShape; +import org.apache.poi.xslf.usermodel.XSLFTextParagraph; +import org.apache.poi.xslf.usermodel.XSLFTextRun; +import org.apache.poi.xslf.usermodel.XSLFTextShape; +import org.apache.poi.xwpf.usermodel.XWPFDocument; +import org.apache.poi.xwpf.usermodel.XWPFParagraph; +import org.apache.poi.xwpf.usermodel.XWPFRun; +import org.junit.jupiter.api.Test; + +import java.io.ByteArrayInputStream; +import java.util.ArrayList; +import java.util.List; +import java.util.regex.Matcher; +import java.util.regex.Pattern; + +import static org.assertj.core.api.Assertions.assertThat; + +/** + * One authored style, all three backends. + * + *The point of {@code DocumentLetterSpacing} keeping its unit is that one + * declaration means the same thing everywhere. This takes a single + * {@code ofFontSize(0.12)} at 20pt — 2.4 points of tracking — and checks that + * each backend received that amount expressed in its own native unit, + * and that none of them touched the author's text to get it.
+ * + *The three units are genuinely different numbers for the same distance: + * 2.4pt is {@code spc="240"} in DrawingML's hundredths, {@code w:val="48"} in + * Word's twentieths, and a {@code Tc} of 2.4 in the PDF's points. A test that + * asserted one number across all three would be asserting a bug.
+ */ +class LetterSpacingAcrossBackendsTest { + + private static final String NAME = "JANE DOE"; + /** 12% of 20pt. */ + private static final double EXPECTED_POINTS = 2.4; + + private static final Pattern SPC = Pattern.compile("spc=\"(-?[0-9]+)\""); + private static final Pattern W_SPACING = Pattern.compile("spacing[^/>]*val=\"(-?[0-9]+)\""); + + private static final DocumentTextStyle TRACKED = DocumentTextStyle.builder() + .fontName(FontName.LATO) + .size(20) + .letterSpacing(DocumentLetterSpacing.ofFontSize(0.12)) + .build(); + + @Test + void theStyleResolvesToTheSameDistanceBeforeAnyBackendSeesIt() { + assertThat(TRACKED.letterSpacing().resolve(TRACKED.size())).isEqualTo(EXPECTED_POINTS); + } + + @Test + void pptxReceivesItInHundredthsOfAPoint() throws Exception { + byte[] pptx = render(session -> session.render(new PptxFixedLayoutBackend())); + + assertThat(values(pptxRunXml(pptx), SPC)) + .isNotEmpty() + .allMatch(value -> value == (int) Math.round(EXPECTED_POINTS * 100)); + assertThat(pptxText(pptx)).isEqualTo(NAME); + } + + @Test + void docxReceivesItInTwentiethsOfAPoint() throws Exception { + byte[] docx = render(session -> session.export(new DocxSemanticBackend())); + + assertThat(values(docxRunXml(docx), W_SPACING)) + .isNotEmpty() + .allMatch(value -> value == (int) Math.round(EXPECTED_POINTS * 20)); + assertThat(docxText(docx)).isEqualTo(NAME); + } + + @Test + void pdfReceivesItAsPointsOfCharacterSpacing() throws Exception { + byte[] pdf = render(session -> session.render(new PdfFixedLayoutBackend())); + + // Tc is written in points, so the operator carries the resolved value + // itself rather than a converted one. + assertThat(contentStream(pdf)).containsPattern("2\\.4\\d*\\s+Tc"); + assertThat(pdfText(pdf)).isEqualTo(NAME); + } + + @Test + void noBackendPadsTheTextToFakeIt() throws Exception { + // The whole reason the feature exists: the picture is spaced out and the + // text is not. + assertThat(pptxText(render(s -> s.render(new PptxFixedLayoutBackend())))).isEqualTo(NAME); + assertThat(docxText(render(s -> s.export(new DocxSemanticBackend())))).isEqualTo(NAME); + assertThat(pdfText(render(s -> s.render(new PdfFixedLayoutBackend())))).isEqualTo(NAME); + } + + // --- helpers --------------------------------------------------------- + + /** An export that is allowed to fail, which every backend's is. */ + @FunctionalInterface + private interface Export { + byte[] from(DocumentSession session) throws Exception; + } + + private static byte[] render(Export export) throws Exception { + try (DocumentSession session = GraphCompose.document() + .pageSize(500, 200) + .margin(DocumentInsets.of(20)) + .create()) { + session.pageFlow(page -> page.addParagraph(p -> p.text(NAME).textStyle(TRACKED))); + return export.from(session); + } + } + + private static ListA fixed-layout document reserves space, wraps, aligns and sizes its frames + * from the width the engine measured. PPTX can only declare spacing in + * hundredths of a point, so if the engine measured a finer value than that, the + * width it reserved is a width the deck will never draw. The engine therefore + * measures on the grid the file can express, and this holds the three numbers + * together: what the engine measured, what the PDF's {@code Tc} says, and what + * the deck's {@code spc} says.
+ * + *This is not a claim that a PDF and a deck rasterise identically. + * Measured by exporting both through PowerPoint, an untracked + * forty-glyph line already lands 0.77pt apart, because PowerPoint has its own + * font handling and rounds its own output. That difference is not ours to + * remove. The one in this test is: it is arithmetic we perform, it is knowable, + * and it accumulates with the length of the string.
+ */ +class TrackingFixedLayoutParityTest { + + /** Long enough that a per-code-point residue would be unmistakable. */ + private static final String LONG = "ABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMN"; + private static final Pattern SPC = Pattern.compile("spc=\"(-?[0-9]+)\""); + private static final Pattern TC = Pattern.compile("(-?[0-9]*\\.?[0-9]+)\\s+Tc"); + private static final Pattern W_SPACING = Pattern.compile("spacing[^/>]*val=\"(-?[0-9]+)\""); + + private static DocumentTextStyle style(DocumentLetterSpacing spacing) { + return DocumentTextStyle.builder() + .fontName(FontName.LATO).size(20).letterSpacing(spacing).build(); + } + + // --- the invariant --------------------------------------------------- + + @ParameterizedTest(name = "[{index}] {0} pt") + @ValueSource(doubles = {1.0 / 3.0, 0.005, -1.0 / 3.0, 0.125, 2.0 / 7.0}) + void whatThePdfDeclaresIsWhatTheDeckDeclares(double points) throws Exception { + DocumentTextStyle style = style(DocumentLetterSpacing.points(points)); + + int spc = spcOf(render(style, s -> s.render(new PptxFixedLayoutBackend()))); + double tc = tcOf(render(style, s -> s.render(new PdfFixedLayoutBackend()))); + + // Both files state the same distance. Unquantised, the PDF said + // 0.3333333333333333 where the deck said 0.33. + assertThat(spc / 100.0).as("PPTX spc=%d against PDF Tc=%s", spc, tc).isEqualTo(tc); + } + + @ParameterizedTest(name = "[{index}] {0} pt") + @ValueSource(doubles = {1.0 / 3.0, 0.005, -1.0 / 3.0, 0.125, 2.0 / 7.0}) + void whatTheEngineMeasuredIsWhatThoseFilesDeclare(double points) throws Exception { + DocumentTextStyle style = style(DocumentLetterSpacing.points(points)); + + int spc = spcOf(render(style, s -> s.render(new PptxFixedLayoutBackend()))); + + // Read back off the LayoutGraph's measured widths, so this is the number + // wrapping and alignment actually used. Derived as a difference of two + // summed line widths, so it carries ordinary float residue — the gap + // being ruled out is four orders of magnitude larger. + assertThat(engineTracking(style)) + .as("engine measurement against declared spc=%d", spc) + .isCloseTo(spc / 100.0, within(1e-9)); + } + + @ParameterizedTest(name = "[{index}] {0} pt") + @ValueSource(doubles = {1.0 / 3.0, 0.005, -1.0 / 3.0, 2.0 / 7.0}) + void aLongStringCannotAccumulateDriftBetweenPdfAndPptx(double points) throws Exception { + DocumentTextStyle style = style(DocumentLetterSpacing.points(points)); + + double engine = engineTracking(style); + int spc = spcOf(render(style, s -> s.render(new PptxFixedLayoutBackend()))); + int codePoints = LONG.codePointCount(0, LONG.length()); + + // Per code point they agree, so over any length they still do. + // Unquantised, a third of a point was 0.0033 out per code point and + // 0.133pt out over this line — which is what this tolerance excludes. + assertThat((spc / 100.0) * codePoints) + .as("accumulated over %d code points", codePoints) + .isCloseTo(engine * codePoints, within(1e-6)); + } + + @Test + void aTrackingBelowHalfTheGridQuantisesAwayToNone() throws Exception { + // Half-up rounding, which is Java's Math.round and what the PPTX + // conversion already used: +0.005 reaches the first hundredth while + // -0.005 does not. Stated here because it is the one asymmetry the grid + // has, and it costs a hundredth of a point at the knife edge. + assertThat(engineTracking(style(DocumentLetterSpacing.points(0.005)))) + .isCloseTo(0.01, within(1e-9)); + + DocumentTextStyle justUnder = style(DocumentLetterSpacing.points(-0.005)); + assertThat(engineTracking(justUnder)).isCloseTo(0.0, within(1e-9)); + // No tracking left to declare, so nothing is written. + assertThat(pptxRunXml(render(justUnder, s -> s.render(new PptxFixedLayoutBackend())))) + .noneMatch(xml -> SPC.matcher(xml).find()); + } + + @Test + void aValueAlreadyOnTheGridIsUntouched() throws Exception { + DocumentTextStyle style = style(DocumentLetterSpacing.points(0.25)); + + assertThat(engineTracking(style)).isCloseTo(0.25, within(1e-9)); + assertThat(spcOf(render(style, s -> s.render(new PptxFixedLayoutBackend())))).isEqualTo(25); + } + + @Test + void zeroStaysTheExactLegacyPath() throws Exception { + DocumentTextStyle style = style(DocumentLetterSpacing.NONE); + + assertThat(engineTracking(style)).isCloseTo(0.0, within(1e-12)); + // Still no attribute and no operator at all. + assertThat(pptxRunXml(render(style, s -> s.render(new PptxFixedLayoutBackend())))) + .noneMatch(xml -> SPC.matcher(xml).find()); + assertThat(contentStream(render(style, s -> s.render(new PdfFixedLayoutBackend())))) + .doesNotContain(" Tc"); + } + + @Test + void anUntrackedDocumentIsTheSameBytesItWouldHaveBeenWithoutTheFeature() throws Exception { + // The CHANGELOG says every existing document is byte-for-byte what it + // was. That is a claim about output, so it is asserted against output: + // a style that never mentions tracking and one that explicitly asks for + // NONE must produce the identical file. + DocumentTextStyle silent = DocumentTextStyle.builder() + .fontName(FontName.LATO).size(20).build(); + DocumentTextStyle explicitNone = style(DocumentLetterSpacing.NONE); + + // PDF embeds a creation date and a document ID, so whole-file equality + // is only a meaningful question in deterministic mode. It is the right + // question, though — it covers the content stream and every dictionary. + assertThat(render(explicitNone, s -> s.render( + PdfFixedLayoutBackend.builder().deterministic(true).build()))) + .isEqualTo(render(silent, s -> s.render( + PdfFixedLayoutBackend.builder().deterministic(true).build()))); + + // The OOXML pair carry timestamps of their own, so they are compared on + // the run properties — which is where a stray zero would have shown up. + assertThat(pptxRunXml(render(explicitNone, s -> s.render(new PptxFixedLayoutBackend())))) + .isEqualTo(pptxRunXml(render(silent, s -> s.render(new PptxFixedLayoutBackend())))); + assertThat(docxRunXml(render(explicitNone, s -> s.export(new DocxSemanticBackend())))) + .isEqualTo(docxRunXml(render(silent, s -> s.export(new DocxSemanticBackend())))); + } + + @Test + void theAuthoredValueItselfIsNeverRewritten() { + // Quantisation is a property of fixed layout, not of the value. What the + // author wrote is what the style still says. + DocumentLetterSpacing authored = DocumentLetterSpacing.points(1.0 / 3.0); + DocumentTextStyle style = style(authored); + + assertThat(style.letterSpacing()).isSameAs(authored); + assertThat(style.letterSpacing().value()).isEqualTo(1.0 / 3.0); + assertThat(style.letterSpacing().resolve(20)).isEqualTo(1.0 / 3.0); + assertThat(engineTracking(style)).isCloseTo(0.33, within(1e-9)); + } + + // --- DOCX keeps its own, coarser grid -------------------------------- + + @Test + void docxRoundsToItsOwnTwentiethsFromTheAuthoredValue() throws Exception { + // Word's grid is 0.05pt, and a semantic export owes the fixed backends + // no coordinate — so it rounds the authored value itself rather than + // inheriting the hundredth the fixed path settled on. + DocumentTextStyle style = style(DocumentLetterSpacing.points(1.0 / 3.0)); + + // 1/3 pt -> 6.667 twentieths -> 7 twips = 0.35pt, which is neither the + // authored third nor the fixed path's 0.33. + assertThat(wSpacingOf(render(style, s -> s.export(new DocxSemanticBackend())))) + .isEqualTo(7); + assertThat(engineTracking(style)).isCloseTo(0.33, within(1e-9)); + } + + // --- range ------------------------------------------------------------ + + @Test + void aTrackingTooLargeForFixedLayoutIsRefusedRatherThanWrapped() { + // 2.2e7 points would be 2_200_000_000 hundredths, which lands at + // -2094967296 on the int cast: wide tracking silently becoming tight. + DocumentTextStyle style = style(DocumentLetterSpacing.points(2.2e7)); + + assertThatIllegalArgumentException() + .isThrownBy(() -> render(style, s -> s.render(new PdfFixedLayoutBackend()))) + .withMessageContaining("fixed-layout"); + } + + @Test + void theFixedLayoutBoundIsTheOneTheSchemaActuallyEnforces() throws Exception { + // ST_TextPoint validates 400000 and rejects 400001, so 4000pt is in and + // anything past it is out. + DocumentTextStyle inRange = style(DocumentLetterSpacing.points(4000.0)); + assertThat(spcOf(render(inRange, s -> s.render(new PptxFixedLayoutBackend())))) + .isEqualTo(400000); + + DocumentTextStyle outOfRange = style(DocumentLetterSpacing.points(4000.01)); + assertThatIllegalArgumentException() + .isThrownBy(() -> render(outOfRange, s -> s.render(new PptxFixedLayoutBackend()))); + } + + @Test + void aTrackingTooLargeForWordIsRefusedRatherThanWrapped() { + // 1e9 points would be 20_000_000_000 twentieths, landing at -1474836480. + DocumentTextStyle style = style(DocumentLetterSpacing.points(1e9)); + + assertThatIllegalArgumentException() + .isThrownBy(() -> render(style, s -> s.export(new DocxSemanticBackend()))) + .withMessageContaining("Word run"); + } + + @Test + void theValueTypeItselfStillAcceptsAnyFiniteNumber() { + // The limits belong to the formats, not to the authored value: it is + // only refused where it cannot be written. + assertThat(DocumentLetterSpacing.points(1e9).resolve(20)).isEqualTo(1e9); + assertThat(DocumentLetterSpacing.ofFontSize(1e9).resolve(20)).isEqualTo(2e10); + } + + // --- helpers --------------------------------------------------------- + + /** + * The tracking the engine actually measured with, per code point. + * + *Read off the {@code LayoutGraph} — the measured span widths the whole + * fixed-layout pipeline reserves space from — rather than off any internal + * helper, so what is compared is the number that really drives wrapping, + * alignment and frame sizing. Derived as the difference the tracking made + * to the line, divided by the code points that were tracked.
+ */ + private static double engineTracking(DocumentTextStyle style) { + double tracked = measuredLineWidth(style); + double plain = measuredLineWidth(style.withLetterSpacing(DocumentLetterSpacing.NONE)); + return (tracked - plain) / LONG.codePointCount(0, LONG.length()); + } + + private static double measuredLineWidth(DocumentTextStyle style) { + try (DocumentSession session = GraphCompose.document() + .pageSize(900, 200) + .margin(DocumentInsets.of(20)) + .create()) { + session.pageFlow(page -> page.addParagraph(p -> p.text(LONG).textStyle(style))); + return session.layoutGraph().fragments().stream() + .map(fragment -> fragment.payload()) + .filter(payload -> payload instanceof ParagraphFragmentPayload) + .map(payload -> (ParagraphFragmentPayload) payload) + .flatMap(payload -> payload.lines().stream()) + .flatMap(line -> line.spans().stream()) + .filter(span -> span instanceof ParagraphTextSpan) + .mapToDouble(span -> ((ParagraphTextSpan) span).width()) + .sum(); + } + } + + @FunctionalInterface + private interface Export { + byte[] from(DocumentSession session) throws Exception; + } + + private static byte[] render(DocumentTextStyle style, Export export) throws Exception { + try (DocumentSession session = GraphCompose.document() + .pageSize(900, 200) + .margin(DocumentInsets.of(20)) + .create()) { + session.pageFlow(page -> page.addParagraph(p -> p.text(LONG).textStyle(style))); + return export.from(session); + } + } + + private static int spcOf(byte[] pptx) throws Exception { + for (String xml : pptxRunXml(pptx)) { + Matcher matcher = SPC.matcher(xml); + if (matcher.find()) { + return Integer.parseInt(matcher.group(1)); + } + } + throw new AssertionError("no spc written"); + } + + /** Every run's properties as the document spells them, in order. */ + private static ListThese are the blocks the probe words above deliberately avoid, and the + * reason they had to: while the look was made by rewriting the string, a + * name came out of the file as {@code "J A N E D O E"}, so the one thing + * every reader of a CV searches for — the applicant's name — was the one + * thing not in it. Tracking is a style now, so the name is a name.
+ */ + @ParameterizedTest(name = "{0}") + @MethodSource("presets") + void theNameAndSectionTitlesReadBackAsWords( + String slug, double margin, SupplierThe name in a CV is the field the document is searched by, and while the + * spaced-caps look was made by rewriting the string it was the one field not in + * the file: {@code "J A N E D O E"} is what an applicant-tracking parser got. + * This holds the migration to its purpose in each format — the picture is + * spaced, the text is not.
+ * + *The fixture carries the cases the old transform handled by three separate + * rules: several words, digits, and punctuation. It inserted one space between + * adjacent letters or digits, widened an authored space into three, + * and did neither around punctuation, so those are where it did the most + * damage.
+ */ +class SpacedCapsTextLayerAcrossBackendsTest { + + private static final String FIRST = "Jane"; + private static final String LAST = "O'Doe-Smith 3rd"; + private static final String FULL_UPPER = "JANE O'DOE-SMITH 3RD"; + private static final String TITLE_UPPER = "BACKEND ENGINEER"; + + /** Four or more single letters or digits in a row, each stranded by spaces. */ + private static final Pattern SPELLED_OUT = + Pattern.compile("\\b(?:[A-Za-z0-9] ){3,}[A-Za-z0-9]\\b"); + + private static final SupplierThe unit is twentieths of a point. Measured rather than assumed: + * exporting a probe document through Word itself and reading the glyph + * positions out of the PDF it wrote, {@code w:spacing w:val="100"} widened + * every step of {@code "JANE"} by 5.0pt — including the step onto a + * following untracked run, which is the trailing unit — and {@code "-30"} + * narrowed each by 1.5pt, with an ordinary space spaced like any other + * character. Word spends the value the same way the PDF {@code Tc} operator + * does.
+ * + *This is the one place the backend resolves the public unit itself: a + * semantic export never passes through the engine's text style, which is + * where a fixed-layout backend would have had it resolved already. Word owns + * the layout here, so the contract is that the asked-for tracking arrives as + * the right native value — not that any x coordinate matches the PDF. + * Twentieths of a point quantise to 0.05pt, which is the format's own + * granularity and not something to work around.
+ * + *No tracking writes no element, so a document that never asks for it + * carries exactly the run properties it carried before.
+ * + *Out of range is refused rather than wrapped. The value goes out as an + * {@code int} of twentieths, and a large enough tracking changes sign on the + * cast — {@code 1e9} points becomes {@code -1474836480}, turning wide + * tracking into tight. The limit is Word's, not the fixed backends': a + * semantic document is not held to what DrawingML can spell.
+ */ + private static void applyLetterSpacing(XWPFRun run, DocumentTextStyle style) { + double points = style.letterSpacing().resolve(style.size()); + if (points == 0.0) { + return; + } + if (Math.abs(points) > MAX_TRACKING_POINTS) { + throw new IllegalArgumentException( + "Letter spacing resolves to " + points + "pt, beyond the " + + MAX_TRACKING_POINTS + "pt a Word run can express " + + "(w:spacing is twentieths of a point, written as an int)."); + } + run.setCharacterSpacing((int) Math.round(points * 20.0)); + } + + /** + * The largest tracking that survives the conversion, in points — the + * point at which twentieths stop fitting in the {@code int} the value is + * written as. Not a typographic limit: Word renders nothing remotely near + * it, and this exists only so an absurd value fails loudly instead of + * wrapping into a negative. + */ + private static final double MAX_TRACKING_POINTS = Integer.MAX_VALUE / 20.0; + private void applyStyle(XWPFRun run, DocumentTextStyle style) { if (style == null) { return; @@ -1075,6 +1128,7 @@ private void applyStyle(XWPFRun run, DocumentTextStyle style) { // and everything else at Word's own default until this is written too. run.setComplexScriptFontSize(style.size()); } + applyLetterSpacing(run, style); if (style.color() != null) { run.setColor(toHexColor(style.color().color())); } diff --git a/render-docx/src/test/java/com/demcha/compose/document/backend/semantic/docx/DocxLetterSpacingTest.java b/render-docx/src/test/java/com/demcha/compose/document/backend/semantic/docx/DocxLetterSpacingTest.java new file mode 100644 index 000000000..7fae512c9 --- /dev/null +++ b/render-docx/src/test/java/com/demcha/compose/document/backend/semantic/docx/DocxLetterSpacingTest.java @@ -0,0 +1,185 @@ +package com.demcha.compose.document.backend.semantic.docx; + +import com.demcha.compose.GraphCompose; +import com.demcha.compose.document.api.DocumentSession; +import com.demcha.compose.document.style.DocumentInsets; +import com.demcha.compose.document.style.DocumentLetterSpacing; +import com.demcha.compose.document.style.DocumentTextStyle; +import com.demcha.compose.font.FontName; +import org.apache.poi.xwpf.usermodel.XWPFDocument; +import org.apache.poi.xwpf.usermodel.XWPFParagraph; +import org.apache.poi.xwpf.usermodel.XWPFRun; +import org.junit.jupiter.api.Test; + +import java.io.ByteArrayInputStream; +import java.util.ArrayList; +import java.util.List; +import java.util.function.Consumer; +import java.util.regex.Matcher; +import java.util.regex.Pattern; + +import static org.assertj.core.api.Assertions.assertThat; + +/** + * Tracking through the DOCX backend, as Word's own run-level {@code w:spacing}. + * + *The unit was measured by exporting a probe document through real Word and + * reading the glyph positions out of the PDF it produced: {@code w:spacing} is + * twentieths of a point, spent one unit per code point with the trailing one + * included — the same rule PowerPoint and the PDF {@code Tc} operator follow.
+ * + *What is not asserted is any x coordinate. Word owns semantic + * layout, and a DOCX export deliberately carries no measurement of its own; the + * contract is that the tracking an author asked for arrives as the right native + * value on the right run, and that the text is untouched.
+ */ +class DocxLetterSpacingTest { + + private static final String NAME = "JANE DOE"; + private static final FontName FAMILY = FontName.LATO; + /** {@codeRead out of the serialized XML rather than through the schema getter, + * which returns the union type {@code Object}: the question this asks is + * what the document says, and the element is the answer.
+ */ + private static Integer spacingOf(XWPFRun run) { + Matcher matcher = SPACING.matcher(run.getCTR().xmlText()); + return matcher.find() ? Integer.valueOf(matcher.group(1)) : null; + } + + private static ListDeduplicated like the font and the colour, and — more importantly — + * always applied before a run rather than only when the run + * wants tracking. {@code Tc} persists across {@code BT}/{@code ET} and + * over the whole {@code q..Q} block, so a span that says nothing about + * tracking keeps whatever the span before it set. Setting it back to + * zero for an untracked run is what stops a tracked headline from + * spreading the ordinary paragraph that follows it.
+ */ + void applyCharacterSpacing(PDPageContentStream stream, float newSpacing) throws IOException { + if (newSpacing != characterSpacing) { + stream.setCharacterSpacing(newSpacing); + characterSpacing = newSpacing; + } + } + void applyColor(PDPageContentStream stream, Color newColor) throws IOException { if (!newColor.equals(color)) { float newAlpha = newColor.getAlpha() / 255f; @@ -592,6 +634,12 @@ void invalidate() { font = null; size = Float.NaN; color = null; + // characterSpacing is deliberately NOT reset. Every nested draw runs + // in its own balanced q..Q, which restores Tc along with the rest of + // the graphics state, so the tracked value is still what the stream + // holds. Resetting it would force a re-emit, and in a document with + // no tracking at all that means writing a "0 Tc" that was never + // there before — a byte change for no behaviour change. } } diff --git a/render-pdf/src/main/java/com/demcha/compose/document/backend/fixed/pdf/handlers/PdfTableRowFragmentRenderHandler.java b/render-pdf/src/main/java/com/demcha/compose/document/backend/fixed/pdf/handlers/PdfTableRowFragmentRenderHandler.java index 428ca02cb..049f705a5 100644 --- a/render-pdf/src/main/java/com/demcha/compose/document/backend/fixed/pdf/handlers/PdfTableRowFragmentRenderHandler.java +++ b/render-pdf/src/main/java/com/demcha/compose/document/backend/fixed/pdf/handlers/PdfTableRowFragmentRenderHandler.java @@ -196,6 +196,16 @@ private void renderCellText(PDPageContentStream stream, PdfAlphaSupport.applyFillAlpha(environment, stream, cell.style().textStyle().color()); stream.setFont(font.fontType(cell.style().textStyle().decoration()), (float) cell.style().textStyle().size()); stream.setNonStrokingColor(cell.style().textStyle().color()); + double letterSpacing = cell.style().textStyle().letterSpacing(); + if (letterSpacing != 0.0) { + // One style for the whole cell, so Tc is set once here. Emitted + // only when there is tracking to apply: this q..Q block starts at + // the page default of zero, so writing "0 Tc" would add a byte to + // every table ever rendered and change nothing about any of them. + // The enclosing restoreGraphicsState puts Tc back, so a tracked + // cell cannot spread the next one. + stream.setCharacterSpacing((float) letterSpacing); + } List{@code written} and {@code reordered} are not the same question, which is + * why both are carried. A line states its own text when the glyphs and the + * meaning have come apart for any reason — reordering, or tracking + * wide enough that an extractor invents word breaks. Only reordering needs + * the shaped-glyph ToUnicode correction, and that correction costs a second + * serialization pass over the whole document.
+ */ + private record ResolvedTextLine(String text, String written, boolean reordered, + double x, double baselineY) { } } diff --git a/render-pdf/src/main/java/com/demcha/compose/engine/render/pdf/PdfFont.java b/render-pdf/src/main/java/com/demcha/compose/engine/render/pdf/PdfFont.java index 9b50dfdc1..5294ebb48 100644 --- a/render-pdf/src/main/java/com/demcha/compose/engine/render/pdf/PdfFont.java +++ b/render-pdf/src/main/java/com/demcha/compose/engine/render/pdf/PdfFont.java @@ -106,6 +106,12 @@ public double getTextHeight(TextStyle style) { * drifting when input contains characters outside the font's coverage * (arrows, dots, emoji, custom unicode). * + *The style's tracking is included, on the same string, by the rule the + * PDF {@code Tc} operator was measured to follow — see + * {@link #trackingAdvance(TextStyle, String)}. Width and pen advance are the + * same number or every span after the first on a line is drawn somewhere + * other than where the layout thinks it is.
+ * * @param style style selecting the concrete font variant * @param text raw text from the document model * @return rendered width in points @@ -124,13 +130,54 @@ public double getTextWidth(TextStyle style, String text) { String measured = whitespaceOnly ? text : sanitizeForRender(style, text); double width = fontType(style.decoration()).getStringWidth(measured) / 1000d * size; - return width; + return width + trackingAdvance(style, measured); } catch (Exception e) { log.error("Error while getting text width {}", e.getMessage(), e); return 0; } } + /** + * The advance a style's tracking adds to {@code measured}, in points. + * + *One unit per code point, trailing unit included — + * measured against PDFBox 3.0.8 rather than read off the specification or + * borrowed from CSS. Drawing a string at {@code Tc = 5} and reading where + * the pen actually landed: {@code "JANE"} advances 20pt further (4 code + * points), {@code "JANE DOE"} 40pt (8 — the space is a code point like any + * other), a single {@code "J"} 5pt, and the empty string not at all. The + * trailing unit is real: the pen sits one full unit past the last glyph's + * ink, which is why this counts N and not N-1. + * {@code PdfCharacterSpacingContractTest} re-measures this and fails if + * PDFBox ever changes it.
+ * + *Counted in code points of the string that is actually drawn, + * never in {@code char}s: {@code Tc} is applied once per glyph, and a + * supplementary code point is one glyph out of two {@code char}s. (With the + * bundled faces the distinction is currently unobservable — none of them can + * encode a supplementary code point, so {@code sanitizeForRender} folds one + * to {@code '?'} before it ever reaches here. Counting code points is what + * stays correct on the day a face that can encode one is added.)
+ * + *The result is not clamped. Negative tracking is allowed, and the pen in + * a reader genuinely moves backwards by it; clamping the measurement while + * being unable to clamp the reader is how the two stop agreeing.
+ * + * @param style the style whose tracking to apply, already resolved to points + * @param measured the exact string handed to {@code showText} + * @return the extra advance in points, {@code 0} when there is no tracking + */ + private static double trackingAdvance(TextStyle style, String measured) { + double spacing = style.letterSpacing(); + if (spacing == 0.0 || measured == null || measured.isEmpty()) { + // Short-circuited rather than added as a zero, so an untracked + // style returns the identical double it returned before tracking + // existed. + return 0.0; + } + return measured.codePointCount(0, measured.length()) * spacing; + } + /** * Sanitises {@code text} for safe rendering with the font selected by * {@code style}. Applies the standard control-character cleanup that @@ -224,12 +271,26 @@ public String sanitizeForLogicalTextExport(TextStyle style, String text) { fontType(style.decoration()), textSanitizer(text)); } + /** + * Measures {@code text} exactly as given, for a caller that has already + * sanitised it. + * + *Tracking is applied here too, by the same rule and on the same string, + * so the two entry points cannot disagree about the width of one run. There + * is no double application: this does not delegate to + * {@link #getTextWidth(TextStyle, String)}, and that one does not delegate + * here — each adds the tracking once, to the string it measured.
+ * + * @param style style selecting the concrete font variant + * @param text already-sanitised text + * @return rendered width in points + */ public double getTextWidthNoSanitize(TextStyle style, String text) { double size = style.size(); try { float width = fontType(style.decoration()).getStringWidth(text) / 1000 * (float) size; log.debug("Getting text width: " + width); - return width; + return width + trackingAdvance(style, text); } catch (Exception e) { e.printStackTrace(); log.error("Error while getting text width {}", e.getMessage(), e); @@ -245,8 +306,13 @@ private String textSanitizer(String text) { // measures against the input as written. The collapse therefore // shrank the rendered string under measurement, drifting // link annotations away from their glyphs and visually merging - // author-spaced strings like `spacedUpper("ARTEM DEMCHYSHYN")` - // (which inserts deliberate triple-spaces between words). + // any text whose author put more than one space in it on purpose. + // (The case that first showed this was the templates' old + // spaced-caps transform, which padded a name out to + // "A R T E M D E M C H Y S H Y N". That is gone — tracking is a + // style now — but the rule it exposed is not about that transform: + // a run of author spaces is content, and measurement and drawing + // have to agree on how wide it is.) // Newlines / NBSP / non-tab control chars still resolve to a // single space each \u2014 they no longer collapse adjacent author // spaces. diff --git a/render-pdf/src/test/java/com/demcha/compose/document/backend/fixed/pdf/DrawnPen.java b/render-pdf/src/test/java/com/demcha/compose/document/backend/fixed/pdf/DrawnPen.java new file mode 100644 index 000000000..0abc05f8c --- /dev/null +++ b/render-pdf/src/test/java/com/demcha/compose/document/backend/fixed/pdf/DrawnPen.java @@ -0,0 +1,113 @@ +package com.demcha.compose.document.backend.fixed.pdf; + +import org.apache.pdfbox.Loader; +import org.apache.pdfbox.text.PDFTextStripper; +import org.apache.pdfbox.pdmodel.PDDocument; + +import org.apache.pdfbox.pdmodel.font.PDFont; +import org.apache.pdfbox.util.Matrix; +import org.apache.pdfbox.util.Vector; + +import java.io.IOException; +import java.util.ArrayList; +import java.util.List; + +/** + * Where the pen actually put each glyph. + * + *{@code PDFTextStripper} answers a different question — what a reader + * makes of the page — and two things this codebase does deliberately get in the + * way of using it for geometry. It invents a word break wherever glyphs sit far + * apart, which is what tracking is; and where a run states its own + * {@code ActualText} it reports that string instead of the glyphs, so the + * positions stop lining up one to one.
+ * + *This reads the drawing operators instead. {@code showGlyph} is the callback + * PDFBox makes for each glyph it paints, with the text-rendering matrix at that + * moment, so the x it reports is the pen — {@code Tc} and all — and no + * extraction heuristic or marked-content section stands in between.
+ */ +final class DrawnPen { + + private DrawnPen() { + } + + /** One painted glyph: the pen position it was placed at, and how far it advanced. */ + record Placement(double x, double y, double advance) { + + @Override + public String toString() { + return String.format("@%.2f(+%.2f)", x, advance); + } + } + + /** + * Every glyph the first page paints, in painting order. + * + * @param pdf a rendered document + * @return the pen positions + * @throws IOException if the document cannot be read + */ + static ListNote this is N-1 gaps, not the run's full advance: the pen's final + * trailing step lands past the last glyph and no glyph records it.
+ */ + static double firstToLastX(byte[] pdf) throws IOException { + return lastX(pdf) - firstX(pdf); + } + + /** Distance from glyph {@code i-1}'s pen position to glyph {@code i}'s. */ + static double step(ListThe whole feature rests on one number: how many spacing units a string of + * N code points adds to the pen advance. The specification can be read either + * way by a careful person and CSS {@code letter-spacing} is a different + * product, so this measures it rather than citing it. {@code PdfFont} adds the + * same number to its measurement; if PDFBox ever changes the rule, this test + * says so instead of leaving every tracked line silently misplaced.
+ * + *The measurement trick is a marker glyph drawn immediately after the + * subject inside the same {@code BT}/{@code ET} with no repositioning: the + * marker's left edge is the pen position the subject left behind, + * trailing spacing included. Reading the subject's own ink extent instead would + * report N-1 by construction and prove nothing.
+ */ +class PdfCharacterSpacingContractTest { + + private static final String FONT = "fonts/google/lato/Lato-Regular.ttf"; + private static final float SIZE = 12f; + private static final float START_X = 50f; + /** Large enough that N and N-1 cannot be confused with rounding. */ + private static final float SPACING = 5f; + private static final String MARKER = "|"; + + /** + * No bundled family encodes a supplementary code point, so one can never + * reach the backend — {@code sanitizeForRender} folds it to {@code '?'} + * first. That case is covered through the production path instead; putting + * it here would only prove that PDFBox throws on a glyph it does not have. + */ + @ParameterizedTest(name = "[{index}] \"{0}\" -> {1} unit(s)") + @CsvSource({ + "JANE, 4", // plain ASCII + "'JANE DOE',8", // a normal space is a code point like any other + "J, 1", // one code point + "JOSÉ, 4", // a covered non-ASCII code point is still one unit + }) + void trackingAddsOneUnitPerCodePointIncludingTheTrailingOne(String subject, int expectedUnits) + throws Exception { + double untracked = advanceOf(subject, 0f); + double tracked = advanceOf(subject, SPACING); + + assertThat(tracked - untracked) + .as("%s: %d code points at %s pt of tracking", subject, + subject.codePointCount(0, subject.length()), SPACING) + .isCloseTo(expectedUnits * SPACING, within(0.01)); + } + + @Test + void theRuleIsNotOffByOneAgainstTheCodePointCount() throws Exception { + // Stated separately so a change from N to N-1 reads as what it is + // rather than as four arithmetic failures. + String subject = "JANE"; + int codePoints = subject.codePointCount(0, subject.length()); + + assertThat(codePoints).isEqualTo(4); + assertThat(advanceOf(subject, SPACING) - advanceOf(subject, 0f)) + .as("N (trailing unit included), not N-1") + .isCloseTo(codePoints * SPACING, within(0.01)) + .isNotCloseTo((codePoints - 1) * SPACING, within(0.01)); + } + + @Test + void theEmptyStringTakesNoTrackingAtAll() throws Exception { + assertThat(advanceOf("", SPACING)).isCloseTo(advanceOf("", 0f), within(0.001)); + assertThat(advanceOf("", SPACING)).isCloseTo(0.0, within(0.001)); + } + + @Test + void trackingDoesNotTouchTheTextLayer() throws Exception { + assertThat(extractionOf("JANE DOE", SPACING)).isEqualTo("JANE DOE|"); + assertThat(extractionOf("JANE DOE", 0f)).isEqualTo("JANE DOE|"); + } + + private static double advanceOf(String subject, float spacing) throws IOException { + ListHeld to the rule {@link PdfCharacterSpacingContractTest} measured off + * PDFBox — one unit per code point, trailing unit included — because the + * measurement and the pen have to produce the same number. A test that invented + * its own expectation here would pass while the page drifted.
+ */ +class PdfFontLetterSpacingMeasurementTest { + + private static final FontName FAMILY = FontName.LATO; + private static final double SIZE = 12.0; + + private static PDDocument document; + private static PdfFont font; + + @BeforeAll + static void loadFont() { + document = new PDDocument(); + FontLibrary library = PdfFontLibraryFactory.library(document, List.of()); + font = library.getFont(FAMILY, PdfFont.class).orElseThrow(); + } + + @AfterAll + static void closeDocument() throws Exception { + document.close(); + } + + private static TextStyle style(double letterSpacing) { + return new TextStyle(FAMILY, SIZE, TextDecoration.DEFAULT, Color.BLACK, letterSpacing); + } + + private static double units(String text, double spacing) { + return font.getTextWidth(style(spacing), text) - font.getTextWidth(style(0), text); + } + + @Test + void withoutTrackingTheWidthIsTheIdenticalDoubleItAlwaysWas() { + // Not "close to" — the same bits. The zero path short-circuits rather + // than adding a zero, so every existing document measures as before. + String text = "The quick brown fox jumps over the lazy dog"; + + TextStyle legacy = new TextStyle(FAMILY, SIZE, TextDecoration.DEFAULT, Color.BLACK); + TextStyle explicitZero = style(0.0); + + assertThat(font.getTextWidth(explicitZero, text)) + .isEqualTo(font.getTextWidth(legacy, text)); + } + + @Test + void positiveTrackingAddsOneUnitPerCodePoint() { + assertThat(units("JANE", 2.0)).isCloseTo(4 * 2.0, within(1e-9)); + assertThat(units("J", 2.0)).isCloseTo(2.0, within(1e-9)); + } + + @Test + void aNormalSpaceCountsAsACodePointLikeAnyOther() { + // "JANE DOE" is eight code points, not seven: the space is tracked too, + // which is exactly what Tc does to the pen. + assertThat(units("JANE DOE", 2.0)).isCloseTo(8 * 2.0, within(1e-9)); + } + + @Test + void negativeTrackingTightensByTheSameRule() { + assertThat(units("JANE", -0.5)).isCloseTo(4 * -0.5, within(1e-9)); + assertThat(font.getTextWidth(style(-0.5), "JANE")) + .isLessThan(font.getTextWidth(style(0), "JANE")); + } + + @Test + void anEmptyStringIsZeroWideWhateverTheTracking() { + assertThat(font.getTextWidth(style(5.0), "")).isZero(); + assertThat(font.getTextWidth(style(0), "")).isZero(); + } + + @Test + void aSupplementaryCodePointCostsOneUnitNotTwo() { + // No bundled face can encode one, so sanitizeForRender folds it to '?' + // before measurement — one char, one code point, one unit. Counting + // Java chars on the raw string would bill it twice. + String astral = new String(Character.toChars(0x1D400)); + assertThat(astral.length()).isEqualTo(2); + assertThat(astral.codePointCount(0, astral.length())).isEqualTo(1); + + assertThat(units(astral, 3.0)).isCloseTo(3.0, within(1e-9)); + assertThat(units("A" + astral + "B", 3.0)).isCloseTo(3 * 3.0, within(1e-9)); + } + + @Test + void trackingIsBilledOnTheSanitizedStringNotTheAuthorsOne() { + // A control character collapses to a single space before drawing, so it + // is billed once — as the thing that is actually drawn, not as what was + // typed. Measuring the raw string would bill a glyph that never appears. + String withControl = "AB\u0000CD"; + String sanitized = font.sanitizeForRender(style(0), withControl); + + assertThat(sanitized).hasSize(5); + assertThat(units(withControl, 2.0)) + .isCloseTo(sanitized.codePointCount(0, sanitized.length()) * 2.0, within(1e-9)); + } + + @Test + void theTwoEntryPointsAgreeAndNeitherBillsTrackingTwice() { + String alreadySanitized = "JANE"; + + double trackedSanitizing = font.getTextWidth(style(2.0), alreadySanitized); + double trackedNoSanitize = font.getTextWidthNoSanitize(style(2.0), alreadySanitized); + + // The tracking each one adds is the same number, exactly: one rule, one + // string, applied once by each entry point and never twice. Four units, + // not eight. + assertThat(trackedNoSanitize - font.getTextWidthNoSanitize(style(0), alreadySanitized)) + .isEqualTo(4 * 2.0); + assertThat(trackedSanitizing - font.getTextWidth(style(0), alreadySanitized)) + .isEqualTo(4 * 2.0); + + // The absolute widths agree only to float precision, and did so before + // tracking existed: getTextWidthNoSanitize computes in float while + // getTextWidth computes in double. That is pre-existing and untouched + // here — it is asserted so the gap is documented rather than discovered. + assertThat(trackedNoSanitize).isCloseTo(trackedSanitizing, within(1e-4)); + } + + @Test + void trackingScalesTheWholeRunNotJustItsEnds() { + // Guards the N vs N-1 boundary at the measurement layer: a one-code-point + // string gets a full unit, which N-1 would make zero. + assertThat(units("J", 4.0)).isCloseTo(4.0, within(1e-9)).isNotCloseTo(0.0, within(1e-6)); + } +} diff --git a/render-pdf/src/test/java/com/demcha/compose/document/backend/fixed/pdf/PdfLetterSpacingRenderTest.java b/render-pdf/src/test/java/com/demcha/compose/document/backend/fixed/pdf/PdfLetterSpacingRenderTest.java new file mode 100644 index 000000000..40892b039 --- /dev/null +++ b/render-pdf/src/test/java/com/demcha/compose/document/backend/fixed/pdf/PdfLetterSpacingRenderTest.java @@ -0,0 +1,328 @@ +package com.demcha.compose.document.backend.fixed.pdf; + +import com.demcha.compose.GraphCompose; +import com.demcha.compose.document.api.DocumentSession; +import com.demcha.compose.document.dsl.PageFlowBuilder; +import com.demcha.compose.document.node.DocumentLinkOptions; +import com.demcha.compose.document.node.TextAlign; +import com.demcha.compose.document.style.DocumentInsets; +import com.demcha.compose.document.style.DocumentLetterSpacing; +import com.demcha.compose.document.style.DocumentTextDecoration; +import com.demcha.compose.document.style.DocumentTextStyle; +import com.demcha.compose.font.FontName; +import org.apache.pdfbox.Loader; +import org.apache.pdfbox.contentstream.operator.Operator; +import org.apache.pdfbox.cos.COSBase; +import org.apache.pdfbox.cos.COSNumber; +import org.apache.pdfbox.pdfparser.PDFStreamParser; +import org.apache.pdfbox.pdmodel.PDDocument; +import org.apache.pdfbox.pdmodel.interactive.annotation.PDAnnotation; +import org.apache.pdfbox.text.PDFTextStripper; +import org.junit.jupiter.api.Test; + +import java.io.IOException; +import java.util.ArrayList; +import java.util.List; +import java.util.function.Consumer; + +import static org.assertj.core.api.Assertions.assertThat; +import static org.assertj.core.api.Assertions.within; + +/** + * Tracking on a real page: what it moves, and what it must not touch. + * + *The point of the feature is that the picture changes and the text does + * not. A headline set in spaced caps has to still be "JANE DOE" to + * anything that reads the file — search, copy/paste, a screen reader, an + * applicant-tracking parser — which is exactly what padding the string with + * spaces destroys.
+ * + *The geometry cases are not four more implementations being checked. + * Alignment, wrapping, decoration rules and link rectangles all consume one + * measured span width, so they are evidence that the width carries tracking, + * not evidence that four code paths each learned about it.
+ * + *Geometry is read through {@link DrawnPen} rather than the text stripper: + * tracked runs state their own {@code ActualText}, and a stripper honouring + * that reports the stated string instead of the glyphs it covers.
+ */ +class PdfLetterSpacingRenderTest { + + private static final String NAME = "JANE DOE"; + private static final FontName FAMILY = FontName.LATO; + + private static DocumentTextStyle style(DocumentLetterSpacing spacing) { + return DocumentTextStyle.builder() + .fontName(FAMILY).size(20).letterSpacing(spacing).build(); + } + + private static DocumentTextStyle underlined(DocumentLetterSpacing spacing) { + return DocumentTextStyle.builder() + .fontName(FAMILY).size(20) + .decoration(DocumentTextDecoration.UNDERLINE) + .letterSpacing(spacing).build(); + } + + // --- the text layer ------------------------------------------------- + + @Test + void aTrackedHeadlineStillReadsAsTheWordThatWasWritten() throws Exception { + byte[] pdf = render(page -> page.addParagraph(p -> p + .text(NAME).textStyle(style(DocumentLetterSpacing.ofFontSize(0.3))))); + + // Not "J A N E D O E". The string was never touched; only the pen was. + assertThat(extractedText(pdf)).isEqualTo(NAME); + } + + @Test + void theTextLayerSurvivesTrackingWideEnoughToFoolAnExtractor() throws Exception { + // Without the run stating its own text this comes back "J A N E D O E": + // an extractor decides where words are by how far apart glyphs sit, and + // tracking is the act of moving them apart. The file was always right — + // eight glyphs, correct ToUnicode — and a reader still got it wrong. + for (double points : new double[] {2, 4, 8, 16}) { + byte[] pdf = render(page -> page.addParagraph(p -> p + .text(NAME).textStyle(style(DocumentLetterSpacing.points(points))))); + + assertThat(extractedText(pdf)) + .as("extraction at %s pt of tracking", points) + .isEqualTo(NAME); + } + } + + @Test + void aTrackedRunDrawsTheGlyphsItWasGivenAndNoExtraSpaces() throws Exception { + byte[] tracked = render(page -> page.addParagraph(p -> p + .text(NAME).textStyle(style(DocumentLetterSpacing.points(4))))); + + // One glyph per character of the original string — the spaced-out + // imitation this replaces would have painted seven extra space glyphs. + assertThat(DrawnPen.placements(tracked)).hasSize(NAME.length()); + } + + @Test + void trackingActuallySpreadsTheGlyphs() throws Exception { + byte[] plain = render(page -> page.addParagraph(p -> p.text(NAME) + .textStyle(style(DocumentLetterSpacing.NONE)))); + byte[] tracked = render(page -> page.addParagraph(p -> p.text(NAME) + .textStyle(style(DocumentLetterSpacing.points(4))))); + + // Seven steps between eight glyphs, each four points longer. The eighth + // unit is past the last glyph, so no glyph records it — which is exactly + // why measurement counts N and this counts N-1. + assertThat(DrawnPen.firstToLastX(tracked) - DrawnPen.firstToLastX(plain)) + .isCloseTo(7 * 4.0, within(0.01)); + } + + @Test + void everyStepIsWidenedByExactlyTheTracking() throws Exception { + ListThe unit is hundredths of a point, and PowerPoint spends it the same + * way the PDF {@code Tc} operator does. Measured rather than assumed: + * exporting a probe deck through PowerPoint itself and reading the glyph + * positions out of the PDF it wrote, {@code spc="500"} widened every step of + * {@code "JANE"} by 5.0pt — including the step onto a following + * untracked run, which is the trailing unit — and {@code spc="-150"} + * narrowed each by 1.5pt. A single {@code "J"} gained a full unit, and an + * ordinary space was spaced like any other character. One unit per code + * point, trailing included: the same N rule the engine measures with, so a + * line laid out against the PDF measurement arrives on a slide at the width + * it was given.
+ * + *The conversion is exact, not a rounding: the engine quantises tracking + * to hundredths before it reaches any fixed backend, precisely so the number + * measured and the number declared here are the same one. Rounding again + * costs nothing and keeps this readable as the unit conversion it is. The + * bound the schema puts on {@code spc} — {@code ST_TextPoint} accepts + * {@code 400000} and rejects {@code 400001} — is enforced at that same + * engine seam, so a value that would wrap its sign on the cast below is + * refused before it ever arrives.
+ * + *Zero writes nothing at all. The attribute's absence is the default, so + * a deck with no tracking in it is byte-identical to one produced before + * this existed.
+ * + * @param run the run being styled + * @param letterSpacing tracking in points, already resolved and quantised + */ + private static void applyLetterSpacing(XSLFTextRun run, double letterSpacing) { + if (letterSpacing == 0.0) { + return; + } + characterProperties(run).ifPresent(properties -> + properties.setSpc((int) Math.round(letterSpacing * 100.0))); + } + + /** The run's character properties, created if the run has none yet. */ + private static OptionalThe unit and the advance rule were measured by exporting a probe deck + * through real PowerPoint and reading the glyph positions out of the PDF it + * produced: {@code spc} is hundredths of a point, and PowerPoint spends one unit + * per code point with the trailing one included — the same N rule the engine + * measures with, so a line laid out against that measurement arrives at the + * width it was given. What is asserted here is that the backend writes the + * value that measurement calls for, and leaves the text alone.
+ */ +class PptxLetterSpacingTest { + + private static final String NAME = "JANE DOE"; + private static final FontName FAMILY = FontName.LATO; + private static final Pattern SPC = Pattern.compile("spc=\"(-?[0-9]+)\""); + + private static DocumentTextStyle style(DocumentLetterSpacing spacing, double size) { + return DocumentTextStyle.builder() + .fontName(FAMILY).size(size).letterSpacing(spacing).build(); + } + + @Test + void pointsBecomeHundredthsOfAPoint() throws Exception { + // 1.25pt -> 125. The unit is the format's, not the engine's. + assertThat(spcOf(render(NAME, style(DocumentLetterSpacing.points(1.25), 20)))) + .containsExactly(125); + } + + @Test + void aFontSizeShareArrivesResolvedAgainstTheStylesSize() throws Exception { + // 12% of 20pt = 2.4pt -> 240. The share is resolved before the backend + // ever sees it; PPTX is handed points. + assertThat(spcOf(render(NAME, style(DocumentLetterSpacing.ofFontSize(0.12), 20)))) + .containsExactly(240); + } + + @Test + void theSameShareAtADifferentSizeResolvesDifferently() throws Exception { + // 12% of 24pt = 2.88pt -> 288, so the value really does follow the size + // rather than being a constant the backend made up. + assertThat(spcOf(render(NAME, style(DocumentLetterSpacing.ofFontSize(0.12), 24)))) + .containsExactly(288); + } + + @Test + void negativeTrackingIsWrittenAsANegativeValue() throws Exception { + assertThat(spcOf(render(NAME, style(DocumentLetterSpacing.points(-0.75), 20)))) + .containsExactly(-75); + } + + @Test + void noTrackingWritesNoAttributeAtAll() throws Exception { + // Absence is the default, so a deck without tracking carries exactly the + // run properties it carried before this existed. + byte[] pptx = render(NAME, style(DocumentLetterSpacing.NONE, 20)); + + assertThat(spcOf(pptx)).isEmpty(); + assertThat(runsOf(pptx)).isNotEmpty(); + } + + @Test + void aValueBetweenUnitsRoundsToTheNearestHundredth() throws Exception { + // 1/3 pt = 0.3333... -> 33 hundredths. Rounded, not truncated toward + // zero, and the residue is a hundredth of a point. + assertThat(spcOf(render(NAME, style(DocumentLetterSpacing.points(1.0 / 3.0), 20)))) + .containsExactly(33); + } + + @Test + void theTextIsTheAuthorsTextAndNothingElse() throws Exception { + byte[] tracked = render(NAME, style(DocumentLetterSpacing.points(4), 20)); + + // Not "J A N E D O E", and not eight runs of one letter either. + assertThat(textOf(tracked)).isEqualTo(NAME); + } + + @Test + void aTrackedRunAndAnUntrackedOneDoNotAffectEachOther() throws Exception { + // Each PPTX run carries its own rPr, so there is no shared state to + // leak — but that is a claim about the format, and this holds it. + byte[] pptx = renderDocument(page -> page.addParagraph(p -> p + .inlineText("AAAA", style(DocumentLetterSpacing.points(5), 20)) + .inlineText("BBBB", style(DocumentLetterSpacing.NONE, 20)))); + + ListRead out of the serialized XML rather than through the schema getter, + * which returns the union type {@code Object}: the question this asks is + * what the document says, and the attribute is the answer.
+ */ + private static Integer spcOf(XSLFTextRun run) { + if (!(run.getXmlObject() instanceof CTRegularTextRun ctRun)) { + return null; + } + Matcher matcher = SPC.matcher(ctRun.xmlText()); + return matcher.find() ? Integer.valueOf(matcher.group(1)) : null; + } + + private static ListThe spaced-caps look is no longer built here. It + * used to be: the text was rewritten with a space between every pair of + * letters, which drew the right picture and wrecked the text layer — + * a name came back out of the file as {@code "J A N E D O E"} to + * search, copy/paste, a screen reader and an applicant-tracking + * parser. Spacing is typography, so it now lives on the style as + * {@link #SPACED_CAPS}, and the text stays the text.
* - *These are algorithmic, not cosmetic — they do - * not belong in {@code theme}. The visual effect of "space letters - * apart" is structural: even if a theme picked a different banner - * colour, the letters would still need the same spacing logic.
+ *{@link #spacedUpper(String)} is still here and still does exactly + * what it always did, for callers compiled against 2.3.0 and earlier. + * It is deprecated, and no GraphCompose component or preset calls it — + * only the test that pins its output does.
*/ public final class TextOrnaments { + /** + * The tracking the spaced-caps components apply. + * + *Chosen against a measurement of what the old transform did. + * That transform put one space glyph between adjacent letters, + * which measured 0.232 em (IBM Plex Serif) to 0.278 em + * (Helvetica) across the faces these presets use — far more + * than editorial spaced caps normally carry, because a space glyph + * is what it had to work with.
+ * + *Matching that per-gap figure would have made every heading + * wider than it was, for two reasons: real tracking adds a unit + * after the last glyph as well as between them, and it tracks the + * real word space too. Matching the old total width + * instead puts the value at 0.174–0.209 em on the same + * faces, so 0.18 em sits inside that band, still reads + * unmistakably as spaced caps, and keeps headings near the width + * they already occupied rather than pushing them into new + * wrapping.
+ * + *Expressed as a share of the font size, so one value serves a + * 24pt name and an 8pt section label alike — which is what + * the old transform did implicitly, the space glyph scaling with + * the type.
+ */ + public static final DocumentLetterSpacing SPACED_CAPS = DocumentLetterSpacing.ofFontSize(0.18); + private TextOrnaments() { } + /** + * Uppercase rendering, with {@code null} treated as empty. + * + *The text and nothing but the text: pair it with + * {@link #SPACED_CAPS} on the style when the spaced-caps look is + * wanted.
+ * + * @param value source text (null tolerated, returned as empty) + * @return the value in upper case + */ + public static String upper(String value) { + if (value == null) { + return ""; + } + return value.toUpperCase(Locale.ROOT); + } + /** * Letter-spaced uppercase rendering (e.g. * {@code spacedUpper("Jane Doe") -> "J A N E D O E"}). * + *Unchanged from 2.3.0, character for character, and kept so + * that code written against it keeps compiling and keeps producing + * the same strings. No built-in preset calls it any more.
+ * * @param value source text (null tolerated, returned as empty) * @return spaced-caps representation + * @deprecated since 2.4.0; removed in 3.0. Use {@link #upper(String)} + * for the text and carry the spacing on the style instead + * — {@link #SPACED_CAPS}, or any + * {@link DocumentLetterSpacing} you prefer. The reason is + * not style: padding the string is what stored a name as + * {@code "J A N E D O E"}, so the one field a CV is + * searched and parsed by came back out of the file + * unreadable. The replacement draws spaced caps and leaves + * the text alone. It does not reproduce this method's + * metrics exactly — a whole space glyph per gap is + * wider than editorial tracking — so expect the same + * look at a slightly different width. */ + @Deprecated(since = "2.4.0", forRemoval = true) public static String spacedUpper(String value) { if (value == null) { return ""; diff --git a/templates/src/main/java/com/demcha/compose/document/templates/coverletter/presets/MintEditorialLetter.java b/templates/src/main/java/com/demcha/compose/document/templates/coverletter/presets/MintEditorialLetter.java index 0d6d4ffaf..d9430572e 100644 --- a/templates/src/main/java/com/demcha/compose/document/templates/coverletter/presets/MintEditorialLetter.java +++ b/templates/src/main/java/com/demcha/compose/document/templates/coverletter/presets/MintEditorialLetter.java @@ -359,7 +359,7 @@ private void addBandedMasthead(SectionBuilder section, .build(); ParagraphNode name = new ParagraphBuilder() .name("CoverLetterV2MintEditorialHeaderName") - .text(TextOrnaments.spacedUpper(identity.name().full())) + .text(TextOrnaments.upper(identity.name().full())) .textStyle(mastheadNameStyle()) .align(TextAlign.CENTER) .build(); @@ -367,7 +367,7 @@ private void addBandedMasthead(SectionBuilder section, ParagraphNode tagline = jobTitle != null && !jobTitle.isBlank() ? new ParagraphBuilder() .name("CoverLetterV2MintEditorialHeaderTagline") - .text(TextOrnaments.spacedUpper(jobTitle)) + .text(TextOrnaments.upper(jobTitle)) .textStyle(taglineStyle()) .align(TextAlign.CENTER) .build() @@ -387,16 +387,20 @@ private void addBandedMasthead(SectionBuilder section, }); } + /** Spaced caps: only the masthead name uses this. */ private DocumentTextStyle mastheadNameStyle() { return TextStyles.of(theme.typography().headlineFont(), theme.typography().sizeHeadline(), - DocumentTextDecoration.DEFAULT, nameColor); + DocumentTextDecoration.DEFAULT, nameColor) + .withLetterSpacing(TextOrnaments.SPACED_CAPS); } + /** Spaced caps: only the tagline uses this. */ private DocumentTextStyle taglineStyle() { return TextStyles.of(theme.typography().headlineFont(), theme.typography().sizeContact(), - DocumentTextDecoration.BOLD, accent); + DocumentTextDecoration.BOLD, accent) + .withLetterSpacing(TextOrnaments.SPACED_CAPS); } } } diff --git a/templates/src/main/java/com/demcha/compose/document/templates/coverletter/presets/MonogramSidebarLetter.java b/templates/src/main/java/com/demcha/compose/document/templates/coverletter/presets/MonogramSidebarLetter.java index 0fc1fce11..5a3f6e7c2 100644 --- a/templates/src/main/java/com/demcha/compose/document/templates/coverletter/presets/MonogramSidebarLetter.java +++ b/templates/src/main/java/com/demcha/compose/document/templates/coverletter/presets/MonogramSidebarLetter.java @@ -197,7 +197,7 @@ private void addNameBlock(SectionBuilder section, CvIdentity identity) { ? DocumentInsets.zero() : DocumentInsets.bottom(6); section.addParagraph(paragraph -> paragraph - .text(TextOrnaments.spacedUpper(part)) + .text(TextOrnaments.upper(part)) .textStyle(nameStyle) .align(TextAlign.CENTER) .lineSpacing(1.0) @@ -206,23 +206,27 @@ private void addNameBlock(SectionBuilder section, CvIdentity identity) { String jobTitle = identity.jobTitle(); if (jobTitle != null && !jobTitle.isBlank()) { section.addParagraph(paragraph -> paragraph - .text(TextOrnaments.spacedUpper(jobTitle)) + .text(TextOrnaments.upper(jobTitle)) .textStyle(titleStyle) .align(TextAlign.CENTER) .margin(new DocumentInsets(12, 0, 18, 0))); } } + /** Spaced caps: only the monogram name lines use this. */ private DocumentTextStyle nameStyle() { return TextStyles.of(theme.typography().headlineFont(), theme.typography().sizeHeadline(), - DocumentTextDecoration.DEFAULT, theme.palette().ink()); + DocumentTextDecoration.DEFAULT, theme.palette().ink()) + .withLetterSpacing(TextOrnaments.SPACED_CAPS); } + /** Spaced caps: only the job-title subtitle uses this. */ private DocumentTextStyle subtitleStyle() { return TextStyles.of(theme.typography().bodyFont(), theme.typography().sizeContact(), - DocumentTextDecoration.BOLD, ACCENT); + DocumentTextDecoration.BOLD, ACCENT) + .withLetterSpacing(TextOrnaments.SPACED_CAPS); } private DocumentTextStyle contactMetaStyle() { diff --git a/templates/src/main/java/com/demcha/compose/document/templates/coverletter/presets/SidebarPortraitLetter.java b/templates/src/main/java/com/demcha/compose/document/templates/coverletter/presets/SidebarPortraitLetter.java index 916212883..c808e431a 100644 --- a/templates/src/main/java/com/demcha/compose/document/templates/coverletter/presets/SidebarPortraitLetter.java +++ b/templates/src/main/java/com/demcha/compose/document/templates/coverletter/presets/SidebarPortraitLetter.java @@ -108,7 +108,7 @@ private void addHeroBand(PageFlowBuilder flow, CvIdentity identity) { String jobTitle = identity.jobTitle(); String subline = jobTitle == null || jobTitle.isBlank() ? "" - : TextOrnaments.spacedUpper(jobTitle); + : TextOrnaments.upper(jobTitle); flow.addSection("CoverLetterV2SidebarPortraitHero", hero -> { // No fill: the CV's beige hero band reads as a coloured box // on a single-column letter, which clashed with the concept, @@ -143,10 +143,12 @@ private DocumentTextStyle nameStyle() { DocumentTextDecoration.BOLD, theme.palette().ink()); } + /** Spaced caps: only the hero subline uses this. */ private DocumentTextStyle subtitleStyle() { return TextStyles.of(theme.typography().bodyFont(), theme.typography().sizeEntryDate(), - DocumentTextDecoration.DEFAULT, theme.palette().ink()); + DocumentTextDecoration.DEFAULT, theme.palette().ink()) + .withLetterSpacing(TextOrnaments.SPACED_CAPS); } private DocumentTextStyle contactStyle() { diff --git a/templates/src/main/java/com/demcha/compose/document/templates/coverletter/presets/TimelineMinimalLetter.java b/templates/src/main/java/com/demcha/compose/document/templates/coverletter/presets/TimelineMinimalLetter.java index f8aceb090..24017b040 100644 --- a/templates/src/main/java/com/demcha/compose/document/templates/coverletter/presets/TimelineMinimalLetter.java +++ b/templates/src/main/java/com/demcha/compose/document/templates/coverletter/presets/TimelineMinimalLetter.java @@ -141,7 +141,7 @@ public void compose(DocumentSession document, CoverLetterDocument doc) { private void addNameBlock(SectionBuilder section, CvIdentity identity) { section.spacing(4) .addParagraph(paragraph -> paragraph - .text(TextOrnaments.spacedUpper(identity.name().full())) + .text(TextOrnaments.upper(identity.name().full())) .textStyle(nameStyle()) .margin(DocumentInsets.zero())); String jobTitle = identity.jobTitle(); @@ -210,10 +210,12 @@ private SvgGlyph glyph(String iconFile) { return SvgGlyph.fromResource(CONTACT_ICON_ROOT + iconFile); } + /** Spaced caps: only the name block uses this. */ private DocumentTextStyle nameStyle() { return TextStyles.of(theme.typography().headlineFont(), theme.typography().sizeHeadline(), - DocumentTextDecoration.DEFAULT, theme.palette().ink()); + DocumentTextDecoration.DEFAULT, theme.palette().ink()) + .withLetterSpacing(TextOrnaments.SPACED_CAPS); } private DocumentTextStyle jobTitleStyle() { 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..9e864ed61 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 @@ -317,17 +317,19 @@ private void renderTightKeyValue(SectionBuilder host, CvRow row) { private void addCenteredTitle(SectionBuilder host, String title) { host.addParagraph(paragraph -> paragraph - .text(TextOrnaments.spacedUpper(title)) + .text(TextOrnaments.upper(title)) .textStyle(titleStyle()) .align(TextAlign.CENTER) .margin(DocumentInsets.zero())); } + /** Spaced caps: both section-title shapes of this preset use it. */ private DocumentTextStyle titleStyle() { return TextStyles.of(theme.typography().headlineFont(), theme.typography().sizeBanner(), DocumentTextDecoration.BOLD, - ACCENT); + ACCENT) + .withLetterSpacing(TextOrnaments.SPACED_CAPS); } private DocumentTextStyle contactMetaStyle() { 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 2105d3011..676f05ab9 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 @@ -650,7 +650,7 @@ private void addBandedHeader(SectionBuilder section, CvIdentity identity, .build(); ParagraphNode name = new ParagraphBuilder() .name("CvV2MintEditorialHeaderName") - .text(TextOrnaments.spacedUpper(identity.name().full())) + .text(TextOrnaments.upper(identity.name().full())) .textStyle(mastheadNameStyle()) .align(TextAlign.CENTER) .build(); @@ -659,7 +659,7 @@ private void addBandedHeader(SectionBuilder section, CvIdentity identity, ParagraphNode tagline = hasTagline ? new ParagraphBuilder() .name("CvV2MintEditorialHeaderTagline") - .text(TextOrnaments.spacedUpper(jobTitle)) + .text(TextOrnaments.upper(jobTitle)) .textStyle(taglineStyle()) .align(TextAlign.CENTER) .build() @@ -749,7 +749,7 @@ private void addEducation(SectionBuilder section, CvSection education) { section.addSection("CvV2MintEditorialEducation", block -> { block.spacing(0).padding(DocumentInsets.zero()); addBlockHeading(block, education.title()); - DocumentTextStyle degreeStyle = labelStyle(); + DocumentTextStyle degreeStyle = labelStyle().withLetterSpacing(TextOrnaments.SPACED_CAPS); DocumentTextStyle metaStyle = smallStyle(); for (CvEntry entry : entries) { block.addParagraph(p -> p @@ -757,7 +757,7 @@ private void addEducation(SectionBuilder section, CvSection education) { .align(TextAlign.LEFT) .margin(DocumentInsets.bottom(5)) .rich(rich -> MarkdownInline.appendTransformed(rich, entry.title(), - degreeStyle, TextOrnaments::spacedUpper))); + degreeStyle, TextOrnaments::upper))); if (!entry.subtitle().isBlank()) { block.addParagraph(p -> p .textStyle(metaStyle) @@ -904,7 +904,7 @@ private void addExperience(SectionBuilder section, String title, section.addSection("CvV2MintEditorialExperience", block -> { block.spacing(0).padding(DocumentInsets.zero()); addBlockHeading(block, title); - DocumentTextStyle titleStyle = labelStyle(); + DocumentTextStyle titleStyle = labelStyle().withLetterSpacing(TextOrnaments.SPACED_CAPS); DocumentTextStyle metaStyle = smallStyle(); DocumentTextStyle bodyStyle = bodyStyle(); for (CvEntry entry : entries) { @@ -913,7 +913,7 @@ private void addExperience(SectionBuilder section, String title, .align(TextAlign.LEFT) .margin(DocumentInsets.bottom(5)) .rich(rich -> MarkdownInline.appendTransformed(rich, entry.title(), - titleStyle, TextOrnaments::spacedUpper))); + titleStyle, TextOrnaments::upper))); String meta = composeMeta(entry); if (!meta.isBlank()) { block.addParagraph(p -> p @@ -958,8 +958,8 @@ private void addAwards(SectionBuilder section, CvSection awards, return; } ListIf the {@code titleStyle} parameter is {@code null} the widget @@ -206,8 +206,8 @@ public static void flatSpacedCaps(SectionBuilder host, String title, .build(); host.padding(new DocumentInsets(0, 0, 0, 0)) .addParagraph(p -> p - .text(TextOrnaments.spacedUpper(title)) - .textStyle(resolved) + .text(TextOrnaments.upper(title)) + .textStyle(resolved.withLetterSpacing(TextOrnaments.SPACED_CAPS)) .align(TextAlign.LEFT) .margin(DocumentInsets.zero())); } diff --git a/templates/src/main/java/com/demcha/compose/document/templates/cv/widgets/SkillBar.java b/templates/src/main/java/com/demcha/compose/document/templates/cv/widgets/SkillBar.java index e1d8f2c6e..286b0ca60 100644 --- a/templates/src/main/java/com/demcha/compose/document/templates/cv/widgets/SkillBar.java +++ b/templates/src/main/java/com/demcha/compose/document/templates/cv/widgets/SkillBar.java @@ -23,7 +23,7 @@ * *
The method is deprecated and no built-in preset calls it any more, + * which is precisely why it needs this: a deprecated method with no + * callers inside the project is one nobody would notice breaking. It is + * published Stable API in {@code graph-compose-templates}, so until a + * major release removes it, "still compiles" is not enough — it has + * to keep returning the same strings.
+ * + *These are not the outputs the replacement produces. Real tracking + * spreads letters without touching the string, so + * {@link TextOrnaments#upper(String)} returns {@code "JANE DOE"} where + * this returns {@code "J A N E D O E"}. That difference is the whole + * point of the deprecation; the assertions below deliberately describe + * the old behaviour.
+ */ +@SuppressWarnings({"deprecation", "removal"}) +class TextOrnamentsSpacedUpperCompatibilityTest { + + @Test + void nullBecomesEmptyRatherThanThrowing() { + assertThat(TextOrnaments.spacedUpper(null)).isEmpty(); + } + + @Test + void emptyStaysEmpty() { + assertThat(TextOrnaments.spacedUpper("")).isEmpty(); + } + + @Test + void lettersAreSeparatedBySingleSpacesAndWordsByThree() { + // One space between adjacent letters; the real word space keeps + // itself and gains two more, so words read as separated. + assertThat(TextOrnaments.spacedUpper("Jane Doe")).isEqualTo("J A N E D O E"); + } + + @Test + void digitsSpaceLikeLetters() { + // isLetterOrDigit, so "R2" spaces between R and 2, and a digit + // adjacent to a letter gets the same treatment either way round. + assertThat(TextOrnaments.spacedUpper("R2 D2")).isEqualTo("R 2 D 2"); + assertThat(TextOrnaments.spacedUpper("A1B2")).isEqualTo("A 1 B 2"); + } + + @Test + void punctuationBreaksTheRunAndIsNeverPaddedOnEitherSide() { + // The space is emitted only when BOTH the current and the next + // character are letters or digits, so punctuation sits tight + // against its neighbours on both sides. + assertThat(TextOrnaments.spacedUpper("O'Neill-Smith")) + .isEqualTo("O'N E I L L-S M I T H"); + assertThat(TextOrnaments.spacedUpper("A.B")).isEqualTo("A.B"); + assertThat(TextOrnaments.spacedUpper("C++")).isEqualTo("C++"); + } + + @Test + void everyWhitespaceCharacterKeepsItselfAndGainsTwoMore() { + assertThat(TextOrnaments.spacedUpper("A B")).isEqualTo("A B"); + // Each whitespace character is expanded independently, so a double + // space becomes six. + assertThat(TextOrnaments.spacedUpper("A B")).isEqualTo("A B"); + // Any Character.isWhitespace, not just the space glyph. + assertThat(TextOrnaments.spacedUpper("A\tB")).isEqualTo("A\t B"); + assertThat(TextOrnaments.spacedUpper("A\nB")).isEqualTo("A\n B"); + } + + @Test + void leadingAndTrailingWhitespaceIsExpandedRatherThanTrimmed() { + assertThat(TextOrnaments.spacedUpper(" A ")).isEqualTo(" A "); + } + + @Test + void aTrailingLetterOrDigitGetsNoSpaceAfterIt() { + // The trailing unit is exactly what real tracking adds and this + // transform does not — the reason 0.18em matches the old total + // width rather than the old per-gap width. + assertThat(TextOrnaments.spacedUpper("AB")).isEqualTo("A B"); + assertThat(TextOrnaments.spacedUpper("A")).isEqualTo("A"); + } + + @Test + void theReplacementDeliberatelyDoesNotReproduceThis() { + assertThat(TextOrnaments.upper("Jane Doe")).isEqualTo("JANE DOE"); + assertThat(TextOrnaments.spacedUpper("Jane Doe")).isEqualTo("J A N E D O E"); + } +}