diff --git a/CHANGELOG.md b/CHANGELOG.md
index b9ab9f314..42d204817 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,17 @@ PDF `GoTo` actions. External links are unchanged.
### Public API
+- **`addPageReference(anchor)` + `PageReferenceNode`** (`@since 1.9.0`). Prints the
+ page a declared `anchor(...)` lands on — a native "see page N" cross-reference —
+ in a single authoring pass. A document that contains a page reference is laid
+ out twice: the first pass resolves every anchor's page, the second renders the
+ references with the resolved numbers; the reference reserves only its content
+ width in both passes, so its own footprint does not shift the pages it reports.
+ Available on flows (`addPageReference(anchor)`) and inside rows (the number
+ column of a table-of-contents row). Documents without a page reference are
+ unaffected (single pass, byte-identical). `pageIndex()` remains for programmatic
+ access.
+
- **`RowBuilder.columns(...)` + `DocumentRowColumn`** (`@since 1.9.0`). Size each row
column explicitly: `DocumentRowColumn.fixed(pt)`, `auto()` (intrinsic content
width), or `weight(w)` (a share of the space left after the fixed and intrinsic
diff --git a/assets/readme/examples/page-reference.pdf b/assets/readme/examples/page-reference.pdf
index 1ad7bdcbb..ed37ecd04 100644
Binary files a/assets/readme/examples/page-reference.pdf and b/assets/readme/examples/page-reference.pdf differ
diff --git a/examples/README.md b/examples/README.md
index 6a955a144..73f8775c7 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -101,7 +101,7 @@ are with the canonical DSL, then jump to its detailed section below.
| [Charts](#charts) | Native vector bar, line, and pie/donut charts — data/spec/style layers, axis & grid toggles, point markers, value labels, legend | [PDF](../assets/readme/examples/chart-showcase.pdf) · [Source](src/main/java/com/demcha/examples/features/charts/ChartShowcaseExample.java) |
| [PDF chrome](#pdf-chrome) | `DocumentMetadata`, `DocumentWatermark`, `DocumentHeaderFooter`, `DocumentBookmarkOptions` | [PDF](../assets/readme/examples/pdf-chrome.pdf) · [Source](src/main/java/com/demcha/examples/features/chrome/PdfChromeExample.java) |
| [Page numbering](#page-numbering) | `DocumentPageNumbering` — offset / restart / roman / suppress-on-first-page for `{page}` / `{pages}` footer tokens | [PDF](../assets/readme/examples/page-numbering.pdf) · [Source](src/main/java/com/demcha/examples/features/chrome/PageNumberingExample.java) |
-| [Page references](#page-references) | `DocumentSession.pageIndex()` — resolve an `anchor(...)` to its page for a two-pass "see page N" cross-reference | [PDF](../assets/readme/examples/page-reference.pdf) · [Source](src/main/java/com/demcha/examples/features/navigation/PageReferenceExample.java) |
+| [Page references](#page-references) | `addPageReference(anchor)` — print the page an `anchor(...)` lands on (a native "see page N" cross-reference), resolved in one authoring pass | [PDF](../assets/readme/examples/page-reference.pdf) · [Source](src/main/java/com/demcha/examples/features/navigation/PageReferenceExample.java) |
| [HTTP streaming](#http-streaming) | `writePdf(OutputStream)` for Servlet / S3 / GCS — caller's stream is not closed | [PDF](../assets/readme/examples/invoice-http-stream.pdf) · [Source](src/main/java/com/demcha/examples/features/streaming/HttpStreamingExample.java) |
| [Word export (DOCX)](#word-export-docx) | `DocxSemanticBackend` — the same session renders a fixed-layout PDF and an editable Word file; paragraphs / lists / tables / images map 1:1, charts fall back to their data table | [PDF](../assets/readme/examples/word-export-companion.pdf) · [DOCX](../assets/readme/examples/word-export-companion.docx) · [Source](src/main/java/com/demcha/examples/features/docx/WordExportExample.java) |
| [Layout snapshot regression](#layout-snapshot-regression) | Deterministic `layoutSnapshot()` workflow with baseline + drift report — production regression-testing pattern | [PDF](../assets/readme/examples/invoice-snapshot-regression.pdf) · [Source](src/main/java/com/demcha/examples/features/snapshots/LayoutSnapshotRegressionExample.java) |
@@ -704,16 +704,19 @@ session.chrome().footer(DocumentHeaderFooter.builder()
### Page references
-`DocumentSession.pageIndex()` resolves every declared `anchor(...)` to its final
-page, so a document can print a real "see page N" cross-reference. It is a
-two-pass workflow — a throwaway first pass lays the document out and reads the
-anchor's page; the second renders the same document with the resolved number.
-Computed from the layout graph (not from rendered bytes), so it is backend-neutral
-and consistent with where a `linkTo(anchor)` jumps.
+`addPageReference(anchor)` prints the page a declared `anchor(...)` lands on — a
+native "see page N" cross-reference — in a single authoring pass. The engine
+resolves the number from the laid-out document automatically (a second layout
+pass under the hood), so there is no manual probe-then-render. It is
+backend-neutral (read from the layout graph, not rendered bytes) and consistent
+with where a `linkTo(anchor)` jumps; `pageIndex()` remains for programmatic
+access.
```java
-int page = probe.pageIndex().pageNumberOf("appendix").orElse(0);
-// ... render again, printing "see page " + page
+flow.addRow(r -> r.columns(auto(), weight(1), auto())
+ .addParagraph("Appendix")
+ .addLine(l -> l.fill().dashed(0.1, 4).lineCap(DocumentLineCap.ROUND)) // dot leader
+ .addPageReference("appendix", style, TextAlign.RIGHT)); // resolves to the page
```
[📄 View PDF](../assets/readme/examples/page-reference.pdf) ·
diff --git a/examples/src/main/java/com/demcha/examples/features/navigation/PageReferenceExample.java b/examples/src/main/java/com/demcha/examples/features/navigation/PageReferenceExample.java
index efac9d74c..b761ffae6 100644
--- a/examples/src/main/java/com/demcha/examples/features/navigation/PageReferenceExample.java
+++ b/examples/src/main/java/com/demcha/examples/features/navigation/PageReferenceExample.java
@@ -2,25 +2,28 @@
import com.demcha.compose.GraphCompose;
import com.demcha.compose.document.api.DocumentSession;
+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.DocumentLineCap;
+import com.demcha.compose.document.style.DocumentRowColumn;
+import com.demcha.compose.document.style.DocumentStroke;
import com.demcha.compose.document.style.DocumentTextStyle;
import com.demcha.examples.support.ExampleOutputPaths;
import java.nio.file.Path;
/**
- * Runnable showcase for v1.9 page references: {@code DocumentSession.pageIndex()}
- * resolves a declared {@code anchor(...)} to its final page, so a document can
- * print a real "see page N" cross-reference.
- *
- * It is a two-pass workflow — exactly what {@code pageIndex()} exists for. A
- * throwaway first pass lays out the document and reads the anchor's page; the
- * second pass renders the same document with the resolved number substituted.
+ * Runnable showcase for v1.9 native page references: {@code addPageReference(anchor)}
+ * prints the page a declared {@code anchor(...)} lands on — the "see page N"
+ * cross-reference — in a single authoring pass. The engine resolves the number
+ * from the laid-out document automatically (a second layout pass), so there is no
+ * manual probe-then-render; {@code pageIndex()} remains for programmatic access.
*
* {@code
- * int page = probe.pageIndex().pageNumberOf("appendix").orElse(0);
- * // ... render again, printing "see page " + page
+ * flow.addRow(r -> r.columns(auto(), auto())
+ * .addParagraph("Configuration is in the Appendix on page")
+ * .addPageReference("appendix", style, TextAlign.LEFT)); // resolves to the real page
* }
*
* @author Artem Demchyshyn
@@ -35,7 +38,7 @@ private PageReferenceExample() {
/**
* Renders a two-page note whose first page cross-references the appendix by
- * its resolved page number.
+ * its resolved page number, in one authoring pass.
*
* @return path to the generated PDF
* @throws Exception if rendering or file IO fails
@@ -43,49 +46,37 @@ private PageReferenceExample() {
public static Path generate() throws Exception {
Path pdfFile = ExampleOutputPaths.prepare("features/navigation", "page-reference.pdf");
- // Pass 1 — throwaway layout to resolve the anchor's page. The appendix is
- // forced onto its own page by the break, so its page is stable regardless
- // of the (still-unresolved) reference text on page 1.
- int appendixPage;
- try (DocumentSession probe = newSession(null)) {
- compose(probe, 0);
- appendixPage = probe.pageIndex().pageNumberOf("appendix").orElse(0);
- }
-
- // Pass 2 — render with the resolved cross-reference.
- try (DocumentSession document = newSession(pdfFile)) {
- compose(document, appendixPage);
- document.buildPdf();
- }
- return pdfFile;
- }
-
- private static DocumentSession newSession(Path output) {
- return (output == null ? GraphCompose.document() : GraphCompose.document(output))
- .pageSize(320, 240)
- .margin(DocumentInsets.of(30))
- .create();
- }
-
- private static void compose(DocumentSession session, int appendixPage) {
DocumentTextStyle title = DocumentTextStyle.DEFAULT.withSize(18).withColor(INK);
DocumentTextStyle body = DocumentTextStyle.DEFAULT.withSize(11).withColor(INK);
DocumentTextStyle ref = DocumentTextStyle.DEFAULT.withSize(11).withColor(MUTED);
- session.pageFlow(page -> {
- page.addParagraph(p -> p.text("Release notes").textStyle(title));
- String reference = appendixPage > 0
- ? "Full configuration options are listed in the Appendix on page " + appendixPage + "."
- : "Full configuration options are listed in the Appendix.";
- page.addParagraph(p -> p.text(reference).textStyle(ref).padding(DocumentInsets.top(10)));
+ try (DocumentSession document = GraphCompose.document(pdfFile)
+ .pageSize(320, 240)
+ .margin(DocumentInsets.of(30))
+ .create()) {
+ DocumentStroke dots = DocumentStroke.of(MUTED, 1.2);
+ document.pageFlow(page -> {
+ page.addParagraph(p -> p.text("Release notes").textStyle(title));
+ page.addParagraph(p -> p.text("Where to read more — the page resolves itself:")
+ .textStyle(ref).padding(DocumentInsets.top(10)));
- page.addPageBreak(b -> b.name("toAppendix"));
+ // One authoring pass: the reference resolves to the appendix's real page.
+ page.addRow(r -> r.gap(6).columns(DocumentRowColumn.auto(), DocumentRowColumn.weight(1), DocumentRowColumn.auto())
+ .padding(DocumentInsets.top(8))
+ .addParagraph(p -> p.text("Appendix").textStyle(body))
+ .addLine(l -> l.fill().height(11).stroke(dots).dashed(0.1, 4).lineCap(DocumentLineCap.ROUND))
+ .addPageReference("appendix", body, TextAlign.RIGHT));
- page.addSection(s -> s.anchor("appendix")
- .addParagraph(p -> p.text("Appendix").textStyle(title)));
- page.addParagraph(p -> p.text("Configuration keys, defaults, and units.")
- .textStyle(body).padding(DocumentInsets.top(6)));
- });
+ page.addPageBreak(b -> b.name("toAppendix"));
+
+ page.addSection(s -> s.anchor("appendix")
+ .addParagraph(p -> p.text("Appendix").textStyle(title)));
+ page.addParagraph(p -> p.text("Configuration keys, defaults, and units.")
+ .textStyle(body).padding(DocumentInsets.top(6)));
+ });
+ document.buildPdf();
+ }
+ return pdfFile;
}
public static void main(String[] args) throws Exception {
diff --git a/src/main/java/com/demcha/compose/document/api/DocumentSession.java b/src/main/java/com/demcha/compose/document/api/DocumentSession.java
index df8ad6d10..cc884f87c 100644
--- a/src/main/java/com/demcha/compose/document/api/DocumentSession.java
+++ b/src/main/java/com/demcha/compose/document/api/DocumentSession.java
@@ -17,6 +17,7 @@
import com.demcha.compose.document.layout.*;
import com.demcha.compose.document.node.ContainerNode;
import com.demcha.compose.document.node.DocumentNode;
+import com.demcha.compose.document.node.PageReferenceNode;
import com.demcha.compose.document.output.*;
import com.demcha.compose.document.snapshot.LayoutSnapshot;
import com.demcha.compose.document.snapshot.PageIndex;
@@ -32,7 +33,9 @@
import java.nio.file.Path;
import java.util.ArrayList;
import java.util.Collection;
+import java.util.HashMap;
import java.util.List;
+import java.util.Map;
import java.util.Objects;
import java.util.concurrent.TimeUnit;
import java.util.function.Consumer;
@@ -63,6 +66,13 @@
public final class DocumentSession implements AutoCloseable {
private static final Logger LIFECYCLE_LOG = LoggerFactory.getLogger("com.demcha.compose.document.lifecycle");
+ /**
+ * Cap on page-reference recompiles after the first resolve. A table of
+ * contents converges in one recompile; the cap bounds a pathological document
+ * whose numbers keep shifting pages, falling back to the last layout.
+ */
+ private static final int MAX_PAGE_REFERENCE_PASSES = 5;
+
private final String sessionId = Integer.toHexString(System.identityHashCode(this));
private final Path defaultOutputFile;
private final NodeRegistry registry;
@@ -754,8 +764,7 @@ public LayoutGraph layoutGraph() {
long startNanos = System.nanoTime();
LIFECYCLE_LOG.debug("document.layout.start sessionId={} revision={} roots={}", sessionId, revision, roots.size());
try {
- DocumentLayoutPassContext context = new DocumentLayoutPassContext(registry, canvas, measurementResources.fontLibrary(), measurementResources.textMeasurementSystem(), markdown);
- LayoutGraph computed = layoutCache.layout(() -> DocumentPageBackgrounds.apply(compiler.compile(documentGraph(), context, context), pageBackgrounds));
+ LayoutGraph computed = layoutCache.layout(this::computeLayout);
LIFECYCLE_LOG.debug("document.layout.end sessionId={} revision={} roots={} pages={} nodes={} fragments={} durationMs={}", sessionId, revision, roots.size(), computed.totalPages(), computed.nodes().size(), computed.fragments().size(), elapsedMillis(startNanos));
return computed;
} catch (RuntimeException ex) {
@@ -764,6 +773,57 @@ public LayoutGraph layoutGraph() {
}
}
+ /**
+ * Compiles the semantic graph for one layout revision. A document that
+ * contains a {@link PageReferenceNode} is compiled in two passes — the first
+ * resolves every anchor's page, the next renders the references with the
+ * resolved numbers — then re-resolved to a fixed point: if rendering the
+ * numbers shifted any anchor's page (a reference whose own width re-wrapped a
+ * neighbour and pushed content across a boundary), it recompiles with the new
+ * numbers until the pages stop moving, capped at {@link #MAX_PAGE_REFERENCE_PASSES}
+ * recompiles. All passes run inside the cache compute, so the result is cached
+ * once per revision. Documents without a page reference compile once and are
+ * byte-identical to before.
+ */
+ private LayoutGraph computeLayout() {
+ LayoutGraph graph = compilePass(Map.of());
+ if (!containsPageReference(roots)) {
+ return DocumentPageBackgrounds.apply(graph, pageBackgrounds);
+ }
+ Map resolved = resolvedPageNumbers(graph);
+ for (int pass = 0; pass < MAX_PAGE_REFERENCE_PASSES; pass++) {
+ graph = compilePass(resolved);
+ Map rendered = resolvedPageNumbers(graph);
+ if (rendered.equals(resolved)) {
+ return DocumentPageBackgrounds.apply(graph, pageBackgrounds);
+ }
+ resolved = rendered;
+ }
+ LIFECYCLE_LOG.debug("document.layout.pageReference.unconverged sessionId={} passes={}", sessionId, MAX_PAGE_REFERENCE_PASSES);
+ return DocumentPageBackgrounds.apply(graph, pageBackgrounds);
+ }
+
+ private LayoutGraph compilePass(Map resolvedPages) {
+ DocumentLayoutPassContext context = new DocumentLayoutPassContext(registry, canvas,
+ measurementResources.fontLibrary(), measurementResources.textMeasurementSystem(), markdown, resolvedPages);
+ return compiler.compile(documentGraph(), context, context);
+ }
+
+ private static boolean containsPageReference(List nodes) {
+ for (DocumentNode node : nodes) {
+ if (node instanceof PageReferenceNode || containsPageReference(node.children())) {
+ return true;
+ }
+ }
+ return false;
+ }
+
+ private static Map resolvedPageNumbers(LayoutGraph graph) {
+ Map pages = new HashMap<>();
+ PageIndexExtractor.from(graph).all().forEach((anchor, reference) -> pages.put(anchor, reference.pageNumber()));
+ return pages;
+ }
+
/**
* Extracts the current deterministic layout snapshot used by regression tests.
*
diff --git a/src/main/java/com/demcha/compose/document/dsl/AbstractFlowBuilder.java b/src/main/java/com/demcha/compose/document/dsl/AbstractFlowBuilder.java
index db5c7f84b..da090a7aa 100644
--- a/src/main/java/com/demcha/compose/document/dsl/AbstractFlowBuilder.java
+++ b/src/main/java/com/demcha/compose/document/dsl/AbstractFlowBuilder.java
@@ -7,6 +7,8 @@
import com.demcha.compose.document.node.ChartNode;
import com.demcha.compose.document.node.DocumentLinkOptions;
import com.demcha.compose.document.node.DocumentNode;
+import com.demcha.compose.document.node.PageReferenceNode;
+import com.demcha.compose.document.node.TextAlign;
import com.demcha.compose.document.style.*;
import java.awt.*;
@@ -958,6 +960,33 @@ public T addSection(String name, Consumer spec) {
return add(BuilderSupport.configure(new SectionBuilder().name(name), spec).build());
}
+ /**
+ * Adds a page reference that prints the page number a named {@code anchor(...)}
+ * lands on — the "see page N" cross-reference. The number is resolved from the
+ * laid-out document automatically (a second layout pass), so no manual
+ * probe-then-render is needed. Uses the default text style, left-aligned.
+ *
+ * @param anchor the anchor whose page number is printed
+ * @return this builder
+ * @since 1.9.0
+ */
+ public T addPageReference(String anchor) {
+ return add(new PageReferenceNode(anchor, DocumentTextStyle.DEFAULT, TextAlign.LEFT));
+ }
+
+ /**
+ * Adds a styled page reference (see {@link #addPageReference(String)}).
+ *
+ * @param anchor the anchor whose page number is printed
+ * @param textStyle text style for the number
+ * @param align horizontal alignment within the node box
+ * @return this builder
+ * @since 1.9.0
+ */
+ public T addPageReference(String anchor, DocumentTextStyle textStyle, TextAlign align) {
+ return add(new PageReferenceNode(anchor, textStyle, align));
+ }
+
/**
* Adds a heading bar with the default light-grey band look.
*
diff --git a/src/main/java/com/demcha/compose/document/dsl/RowBuilder.java b/src/main/java/com/demcha/compose/document/dsl/RowBuilder.java
index 50fedf98d..cc699b753 100644
--- a/src/main/java/com/demcha/compose/document/dsl/RowBuilder.java
+++ b/src/main/java/com/demcha/compose/document/dsl/RowBuilder.java
@@ -57,6 +57,10 @@ private static boolean isAllowedRowChild(DocumentNode child) {
|| child instanceof EllipseNode
|| child instanceof SpacerNode
|| child instanceof BarcodeNode
+ // PageReferenceNode is an atomic one-line text leaf (the page
+ // number of an anchor), so it slots into a row like a paragraph —
+ // it is the number column of a table-of-contents row.
+ || child instanceof PageReferenceNode
|| child instanceof SectionNode
|| child instanceof ContainerNode
// ShapeContainerNode is the same shape of thing as
@@ -359,6 +363,34 @@ public RowBuilder addLine(Consumer spec) {
return add(BuilderSupport.configure(new LineBuilder(), spec).build());
}
+ /**
+ * Adds a page reference that prints the page number of a named
+ * {@code anchor(...)} — the number column of a table-of-contents row, or the
+ * page in a "see page N" line. Resolved automatically from the laid-out
+ * document.
+ *
+ * @param anchor the anchor whose page number is printed
+ * @param textStyle text style for the number
+ * @param align horizontal alignment within the column
+ * @return this builder
+ * @since 1.9.0
+ */
+ public RowBuilder addPageReference(String anchor, DocumentTextStyle textStyle, TextAlign align) {
+ return add(new PageReferenceNode(anchor, textStyle, align));
+ }
+
+ /**
+ * Adds a page reference with the default text style, left-aligned (see
+ * {@link #addPageReference(String, DocumentTextStyle, TextAlign)}).
+ *
+ * @param anchor the anchor whose page number is printed
+ * @return this builder
+ * @since 1.9.0
+ */
+ public RowBuilder addPageReference(String anchor) {
+ return add(new PageReferenceNode(anchor, DocumentTextStyle.DEFAULT, TextAlign.LEFT));
+ }
+
/**
* Adds an ellipse/circle child configured through a nested builder.
*
diff --git a/src/main/java/com/demcha/compose/document/layout/BuiltInNodeDefinitions.java b/src/main/java/com/demcha/compose/document/layout/BuiltInNodeDefinitions.java
index 7afe5dcc2..032f1fcd6 100644
--- a/src/main/java/com/demcha/compose/document/layout/BuiltInNodeDefinitions.java
+++ b/src/main/java/com/demcha/compose/document/layout/BuiltInNodeDefinitions.java
@@ -38,6 +38,7 @@ public static NodeRegistry registerDefaults(NodeRegistry registry) {
.register(new ContainerDefinition())
.register(new SectionDefinition())
.register(new RowDefinition())
+ .register(new PageReferenceDefinition())
.register(new LayerStackDefinition())
.register(new ShapeContainerDefinition())
.register(new TableDefinition())
diff --git a/src/main/java/com/demcha/compose/document/layout/DocumentLayoutPassContext.java b/src/main/java/com/demcha/compose/document/layout/DocumentLayoutPassContext.java
index 1bd885b38..039511972 100644
--- a/src/main/java/com/demcha/compose/document/layout/DocumentLayoutPassContext.java
+++ b/src/main/java/com/demcha/compose/document/layout/DocumentLayoutPassContext.java
@@ -8,6 +8,7 @@
import java.util.List;
import java.util.Map;
import java.util.Objects;
+import java.util.OptionalInt;
/**
* Internal context for one canonical document layout pass.
@@ -25,10 +26,12 @@ public final class DocumentLayoutPassContext implements PrepareContext, Fragment
private final FontLibrary fontLibrary;
private final TextMeasurementSystem textMeasurementSystem;
private final boolean markdown;
+ private final Map resolvedPages;
private final Map> preparedNodes = new HashMap<>();
/**
- * Creates a layout-pass context.
+ * Creates a layout-pass context with no resolved page numbers — the first
+ * pass, where page-reference nodes render their placeholder.
*
* @param registry semantic node registry used for preparation
* @param canvas active layout canvas
@@ -41,11 +44,38 @@ public DocumentLayoutPassContext(NodeRegistry registry,
FontLibrary fontLibrary,
TextMeasurementSystem textMeasurementSystem,
boolean markdown) {
+ this(registry, canvas, fontLibrary, textMeasurementSystem, markdown, Map.of());
+ }
+
+ /**
+ * Creates a layout-pass context carrying resolved anchor page numbers — the
+ * second pass of a page-reference / table-of-contents resolve.
+ *
+ * @param registry semantic node registry used for preparation
+ * @param canvas active layout canvas
+ * @param fontLibrary document font library
+ * @param textMeasurementSystem text measurement service for this pass
+ * @param markdown whether paragraph markdown parsing is enabled
+ * @param resolvedPages anchor name to 1-based page number
+ */
+ public DocumentLayoutPassContext(NodeRegistry registry,
+ LayoutCanvas canvas,
+ FontLibrary fontLibrary,
+ TextMeasurementSystem textMeasurementSystem,
+ boolean markdown,
+ Map resolvedPages) {
this.registry = Objects.requireNonNull(registry, "registry");
this.canvas = Objects.requireNonNull(canvas, "canvas");
this.fontLibrary = Objects.requireNonNull(fontLibrary, "fontLibrary");
this.textMeasurementSystem = Objects.requireNonNull(textMeasurementSystem, "textMeasurementSystem");
this.markdown = markdown;
+ this.resolvedPages = resolvedPages == null ? Map.of() : Map.copyOf(resolvedPages);
+ }
+
+ @Override
+ public OptionalInt resolvedPage(String anchor) {
+ Integer page = anchor == null ? null : resolvedPages.get(anchor);
+ return page == null ? OptionalInt.empty() : OptionalInt.of(page);
}
@Override
diff --git a/src/main/java/com/demcha/compose/document/layout/FragmentContext.java b/src/main/java/com/demcha/compose/document/layout/FragmentContext.java
index 5bd0572dc..2a0270c7f 100644
--- a/src/main/java/com/demcha/compose/document/layout/FragmentContext.java
+++ b/src/main/java/com/demcha/compose/document/layout/FragmentContext.java
@@ -5,6 +5,7 @@
import com.demcha.compose.font.FontLibrary;
import java.util.List;
+import java.util.OptionalInt;
/**
* Shared fragment emission context passed to node definitions.
@@ -68,6 +69,18 @@ default List emitChildFragments(
throw new UnsupportedOperationException(
"FragmentContext implementation does not support child fragment emission");
}
+
+ /**
+ * Resolves the 1-based page number a named {@code anchor(...)} lands on, when
+ * the pass has page numbers available (the second pass of a page-reference /
+ * table-of-contents resolve). Empty on the first pass and for unknown anchors.
+ *
+ * @param anchor anchor name to resolve
+ * @return the 1-based page number, or empty when unresolved
+ */
+ default OptionalInt resolvedPage(String anchor) {
+ return OptionalInt.empty();
+ }
}
diff --git a/src/main/java/com/demcha/compose/document/layout/PrepareContext.java b/src/main/java/com/demcha/compose/document/layout/PrepareContext.java
index f95cb043b..2fef1d3dd 100644
--- a/src/main/java/com/demcha/compose/document/layout/PrepareContext.java
+++ b/src/main/java/com/demcha/compose/document/layout/PrepareContext.java
@@ -4,6 +4,8 @@
import com.demcha.compose.engine.measurement.TextMeasurementSystem;
import com.demcha.compose.font.FontLibrary;
+import java.util.OptionalInt;
+
/**
* Shared prepare context passed to node definitions.
*/
@@ -47,6 +49,19 @@ public interface PrepareContext {
default boolean markdownEnabled() {
return false;
}
+
+ /**
+ * Resolves the 1-based page number a named {@code anchor(...)} lands on, when
+ * the pass has page numbers available (the second pass of a page-reference /
+ * table-of-contents resolve). Empty on the first pass and for unknown anchors,
+ * so a page-reference node renders a placeholder until it is resolved.
+ *
+ * @param anchor anchor name to resolve
+ * @return the 1-based page number, or empty when unresolved
+ */
+ default OptionalInt resolvedPage(String anchor) {
+ return OptionalInt.empty();
+ }
}
diff --git a/src/main/java/com/demcha/compose/document/layout/TextFlowSupport.java b/src/main/java/com/demcha/compose/document/layout/TextFlowSupport.java
index e553f88e3..f18ec44da 100644
--- a/src/main/java/com/demcha/compose/document/layout/TextFlowSupport.java
+++ b/src/main/java/com/demcha/compose/document/layout/TextFlowSupport.java
@@ -56,6 +56,20 @@ public final class TextFlowSupport {
private TextFlowSupport() {
}
+ /**
+ * Measures the glyph width of a single text string in a document text style —
+ * the content width, not a full-block paragraph width. Used by leaves that
+ * size themselves to a short string (e.g. a page-reference number).
+ *
+ * @param style document text style
+ * @param text text to measure
+ * @param measurement text measurement service
+ * @return the measured glyph width in points
+ */
+ public static double measureTextWidth(DocumentTextStyle style, String text, TextMeasurementSystem measurement) {
+ return measurement.textWidth(toTextStyle(style), text);
+ }
+
/**
* Measures a paragraph node and wraps it into a prepared leaf carrying its
* visual line layout.
diff --git a/src/main/java/com/demcha/compose/document/layout/definitions/PageReferenceDefinition.java b/src/main/java/com/demcha/compose/document/layout/definitions/PageReferenceDefinition.java
new file mode 100644
index 000000000..c6b2bc680
--- /dev/null
+++ b/src/main/java/com/demcha/compose/document/layout/definitions/PageReferenceDefinition.java
@@ -0,0 +1,72 @@
+package com.demcha.compose.document.layout.definitions;
+
+import com.demcha.compose.document.layout.*;
+import com.demcha.compose.document.node.PageReferenceNode;
+import com.demcha.compose.document.node.ParagraphNode;
+
+import java.util.List;
+import java.util.OptionalInt;
+
+/**
+ * Layout definition for {@link PageReferenceNode}: resolves the anchor's page
+ * number from the layout pass and renders it as a one-line text leaf. The text is
+ * laid out by reusing {@link TextFlowSupport}, so it shares the engine's text
+ * measurement and rendering with paragraphs.
+ *
+ * The leaf is sized to the number's glyph width (not a full text block), so an
+ * unresolved reference reserves only its content width and never over-constrains
+ * the row it sits in during the first pass.
+ *
+ * @author Artem Demchyshyn
+ */
+public final class PageReferenceDefinition implements NodeDefinition {
+
+ /** Slack added to the measured glyph width so a single-token number is not char-wrapped by float rounding. */
+ private static final double WRAP_SLACK_PT = 1.0;
+
+ /**
+ * Creates the page-reference layout definition.
+ */
+ public PageReferenceDefinition() {
+ }
+
+ @Override
+ public Class nodeType() {
+ return PageReferenceNode.class;
+ }
+
+ @Override
+ public PreparedNode prepare(PageReferenceNode node, PrepareContext ctx, BoxConstraints constraints) {
+ String text = resolveText(node, ctx.resolvedPage(node.anchor()));
+ // Size the box to the number's glyph width so the leaf measures as content,
+ // not as a full-width text block (an empty placeholder otherwise claims the
+ // whole row width). + 1pt guards against single-glyph wrap on float rounding.
+ double glyph = TextFlowSupport.measureTextWidth(node.textStyle(), text, ctx.textMeasurement());
+ double width = Math.min(constraints.availableWidth(), glyph + node.padding().horizontal() + WRAP_SLACK_PT);
+ ParagraphNode paragraph = new ParagraphNode(node.name(), text, node.textStyle(), node.align(),
+ 0.0, node.padding(), node.margin());
+ PreparedNode prepared = TextFlowSupport.prepareParagraph(paragraph, ctx, BoxConstraints.natural(width));
+ return PreparedNode.leaf(node, prepared.measureResult(), new PreparedPageReference(prepared));
+ }
+
+ @Override
+ public PaginationPolicy paginationPolicy(PageReferenceNode node) {
+ return PaginationPolicy.ATOMIC;
+ }
+
+ @Override
+ public List emitFragments(PreparedNode prepared,
+ FragmentContext ctx,
+ FragmentPlacement placement) {
+ PreparedPageReference layout = prepared.requirePreparedLayout(PreparedPageReference.class);
+ return TextFlowSupport.emitParagraphFragments(layout.paragraph(), placement);
+ }
+
+ private static String resolveText(PageReferenceNode node, OptionalInt page) {
+ return page.isPresent() ? Integer.toString(page.getAsInt()) : node.placeholderText();
+ }
+
+ /** Carries the prepared transient paragraph from prepare to emit. */
+ private record PreparedPageReference(PreparedNode paragraph) implements PreparedNodeLayout {
+ }
+}
diff --git a/src/main/java/com/demcha/compose/document/node/PageReferenceNode.java b/src/main/java/com/demcha/compose/document/node/PageReferenceNode.java
new file mode 100644
index 000000000..1003e0c54
--- /dev/null
+++ b/src/main/java/com/demcha/compose/document/node/PageReferenceNode.java
@@ -0,0 +1,67 @@
+package com.demcha.compose.document.node;
+
+import com.demcha.compose.document.style.DocumentInsets;
+import com.demcha.compose.document.style.DocumentTextStyle;
+
+/**
+ * Leaf that prints the resolved page number of a named {@code anchor(...)} — the
+ * "see page N" cross-reference. The number is resolved from the laid-out
+ * document on a second layout pass; until then (or when the anchor is unknown)
+ * it renders {@code placeholderText}.
+ *
+ * Because the number is resolved after layout, a document containing a
+ * page reference is laid out twice; the reference reserves a single text line in
+ * both passes, so its own footprint does not shift the pages it reports.
+ *
+ * Resolved in document flows and rows (the table-of-contents row). A reference
+ * nested inside a table cell is not resolved in this release.
+ *
+ * @param name node name used in snapshots and layout graph paths
+ * @param anchor the anchor whose page number is printed
+ * @param textStyle text style for the number
+ * @param align horizontal alignment within the node box
+ * @param placeholderText text shown before the number is resolved, or when the
+ * anchor is unknown
+ * @param padding inner padding
+ * @param margin outer margin
+ * @author Artem Demchyshyn
+ * @since 1.9.0
+ */
+public record PageReferenceNode(
+ String name,
+ String anchor,
+ DocumentTextStyle textStyle,
+ TextAlign align,
+ String placeholderText,
+ DocumentInsets padding,
+ DocumentInsets margin
+) implements DocumentNode {
+
+ /**
+ * Normalizes defaults and requires a non-blank anchor.
+ */
+ public PageReferenceNode {
+ name = name == null ? "" : name;
+ anchor = anchor == null ? "" : anchor.trim();
+ if (anchor.isBlank()) {
+ throw new IllegalArgumentException("PageReferenceNode anchor must not be blank.");
+ }
+ textStyle = textStyle == null ? DocumentTextStyle.DEFAULT : textStyle;
+ align = align == null ? TextAlign.LEFT : align;
+ placeholderText = placeholderText == null ? "" : placeholderText;
+ padding = padding == null ? DocumentInsets.zero() : padding;
+ margin = margin == null ? DocumentInsets.zero() : margin;
+ }
+
+ /**
+ * Convenience constructor for an unnamed reference with default spacing and no
+ * placeholder text.
+ *
+ * @param anchor the anchor whose page number is printed
+ * @param textStyle text style for the number
+ * @param align horizontal alignment within the node box
+ */
+ public PageReferenceNode(String anchor, DocumentTextStyle textStyle, TextAlign align) {
+ this("", anchor, textStyle, align, "", DocumentInsets.zero(), DocumentInsets.zero());
+ }
+}
diff --git a/src/test/java/com/demcha/compose/document/api/DocumentSessionTest.java b/src/test/java/com/demcha/compose/document/api/DocumentSessionTest.java
index 8c67484eb..55f82bdaf 100644
--- a/src/test/java/com/demcha/compose/document/api/DocumentSessionTest.java
+++ b/src/test/java/com/demcha/compose/document/api/DocumentSessionTest.java
@@ -1128,6 +1128,11 @@ public boolean markdownEnabled() {
return true;
}
+ @Override
+ public java.util.OptionalInt resolvedPage(String anchor) {
+ return java.util.OptionalInt.empty();
+ }
+
@Override
public void close() throws Exception {
measurementDocument.close();
diff --git a/src/test/java/com/demcha/compose/document/backend/fixed/pdf/PageReferenceTest.java b/src/test/java/com/demcha/compose/document/backend/fixed/pdf/PageReferenceTest.java
new file mode 100644
index 000000000..9a941ffe6
--- /dev/null
+++ b/src/test/java/com/demcha/compose/document/backend/fixed/pdf/PageReferenceTest.java
@@ -0,0 +1,112 @@
+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.node.TextAlign;
+import com.demcha.compose.document.style.DocumentInsets;
+import com.demcha.compose.document.style.DocumentTextStyle;
+import org.apache.pdfbox.Loader;
+import org.apache.pdfbox.pdmodel.PDDocument;
+import org.apache.pdfbox.text.PDFTextStripper;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+
+import java.nio.file.Path;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatCode;
+
+/**
+ * End-to-end proof that {@code addPageReference(anchor)} prints the page a forward
+ * anchor lands on: the reference sits on page 1, its target several pages later,
+ * and the rendered number on page 1 equals {@code pageIndex().pageNumberOf} — so
+ * the two-pass resolve converges and is backend-correct.
+ */
+class PageReferenceTest {
+
+ @TempDir
+ Path tempDir;
+
+ private static String pageText(PDDocument doc, int oneBasedPage) throws Exception {
+ PDFTextStripper stripper = new PDFTextStripper();
+ stripper.setStartPage(oneBasedPage);
+ stripper.setEndPage(oneBasedPage);
+ return stripper.getText(doc);
+ }
+
+ @Test
+ void pageReferencePrintsTheForwardAnchorsResolvedPage() throws Exception {
+ Path out = tempDir.resolve("page-ref.pdf");
+ int resolved;
+ try (DocumentSession session = GraphCompose.document(out)
+ .pageSize(220, 180)
+ .margin(DocumentInsets.of(24))
+ .create()) {
+ session.pageFlow(page -> {
+ page.addRow(r -> r.gap(4).columns(com.demcha.compose.document.style.DocumentRowColumn.auto(),
+ com.demcha.compose.document.style.DocumentRowColumn.auto())
+ .addParagraph("Appendix on page")
+ .addPageReference("appendix", DocumentTextStyle.DEFAULT, TextAlign.LEFT));
+ page.addPageBreak(b -> b.name("b1"));
+ page.addParagraph("Body");
+ page.addPageBreak(b -> b.name("b2"));
+ page.addSection(s -> s.anchor("appendix").addParagraph("Appendix"));
+ });
+ resolved = session.pageIndex().pageNumberOf("appendix").orElseThrow();
+ session.buildPdf();
+ }
+
+ assertThat(resolved).isGreaterThan(1); // a genuine forward reference
+ try (PDDocument doc = Loader.loadPDF(out.toFile())) {
+ // The reference on page 1 prints exactly the page pageIndex() resolved.
+ assertThat(pageText(doc, 1)).contains("Appendix on page", Integer.toString(resolved));
+ }
+ }
+
+ @Test
+ void multipleReferencesEachReportTheirFinalPage() throws Exception {
+ Path out = tempDir.resolve("multi-ref.pdf");
+ int appendix;
+ int glossary;
+ try (DocumentSession session = GraphCompose.document(out)
+ .pageSize(220, 180)
+ .margin(DocumentInsets.of(24))
+ .create()) {
+ session.pageFlow(page -> {
+ page.addRow(r -> r.gap(4).addParagraph("Appendix")
+ .addPageReference("appendix", DocumentTextStyle.DEFAULT, TextAlign.RIGHT));
+ page.addRow(r -> r.gap(4).addParagraph("Glossary")
+ .addPageReference("glossary", DocumentTextStyle.DEFAULT, TextAlign.RIGHT));
+ page.addPageBreak(b -> b.name("b1"));
+ page.addSection(s -> s.anchor("appendix").addParagraph("Appendix"));
+ page.addPageBreak(b -> b.name("b2"));
+ page.addSection(s -> s.anchor("glossary").addParagraph("Glossary"));
+ });
+ appendix = session.pageIndex().pageNumberOf("appendix").orElseThrow();
+ glossary = session.pageIndex().pageNumberOf("glossary").orElseThrow();
+ session.buildPdf();
+ }
+
+ assertThat(appendix).isNotEqualTo(glossary); // distinct target pages
+ try (PDDocument doc = Loader.loadPDF(out.toFile())) {
+ // Each reference on page 1 prints the page its own anchor finally lands on.
+ assertThat(pageText(doc, 1)).contains(Integer.toString(appendix), Integer.toString(glossary));
+ }
+ }
+
+ @Test
+ void unresolvedReferenceRendersWithoutThrowing() {
+ try (DocumentSession session = GraphCompose.document(tempDir.resolve("unresolved.pdf"))
+ .pageSize(220, 180)
+ .margin(DocumentInsets.of(24))
+ .create()) {
+ session.pageFlow(page -> {
+ page.addParagraph("No such anchor below");
+ page.addPageReference("missing");
+ });
+ // An unknown anchor resolves to empty → renders its placeholder, no throw.
+ assertThat(session.pageIndex().pageNumberOf("missing")).isEmpty();
+ assertThatCode(session::buildPdf).doesNotThrowAnyException();
+ }
+ }
+}