diff --git a/CHANGELOG.md b/CHANGELOG.md index 87a094d1f..676fc8653 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,38 @@ follow semantic versioning; release dates are ISO 8601. ### Public API +- **A DOCX export's report names where a page zone's parts stand, and what its paragraphs + lose.** A page zone is written as one Word line. Word sets its parts one after another from + the page's left margin, and those after the first spacer against its right margin, on one + baseline, its tallest part's. The page sets each part by the zone's padding, a row's columns + and gap and a paragraph's alignment, and each part's sides, on a baseline of its own. So + these moved in Word without a note: + - a centred line, a padded zone, a row's column or gap; + - a page field's sides; + - a smaller part beside a larger one, which Word sets on the larger one's baseline. + + A zone paragraph's right-to-left direction, prefix letters, fitted size and outline entry + went unnamed too. A `page zone` note now: + - counts the parts that stand off where the page sets them. Each part is read from the + layout's zone fragments on the first page the zone is drawn on. A part stands where the + page sets it when it meets all of these: + - its line starts within a point and a half of Word's, or, against the right margin, ends + there; + - it sits on Word's baseline: its tallest part's, with the line standing at the zone's edge; + - it is one line; + - no prefix stands before it, on the line's left side. + + Past a part Word sets at another width, in a zone whose nodes the page names or nests + otherwise than the file, and with no layout, the note says where the parts stand is not + measured; + - names a zone paragraph's right-to-left text written left to right, its prefix's letters, + the size its text is fitted to, and its outline entry. + + None of this changes what is written, and no document of the DOCX fidelity corpus has a page + zone. In `DocxNodeFieldLedgerTest` a page field's `padding` and `margin` move from a gap to + `REPORTED`, and its `align` to `INERT`: the page sets a field in a box a point wider than its + number. The `zones` option keeps a gap for the line's height and the room its parts hold above + and below, and a zone paragraph's anchor. 1 node-field gap remains, `CanvasLayerNode.height`. - **A DOCX export's report names what a paragraph's own fields lose.** Several of a paragraph's own fields were lost without a note: - an auto-sized paragraph's text was written at its style's size, not the one the page fits it @@ -34,7 +66,7 @@ follow semantic versioning; release dates are ISO 8601. side holds the line's level. A paragraph set in a text box over the flow carries these on the note it already had. A page - zone's paragraphs are not named yet: that stays a gap of the `zones` option. Across + zone's paragraphs are named on the zone's own note (`page zone`). Across the DOCX fidelity corpus the report names no paragraph: `EngineeringResume`'s auto-sized name fits at its own size. None of this changes what is written: the 62 documents of the corpus export to the same bytes. In `DocxNodeFieldLedgerTest` a paragraph's `autoSize`, diff --git a/docs/architecture/backend-capability-matrix.md b/docs/architecture/backend-capability-matrix.md index 549d6cc2b..633e20b7e 100644 --- a/docs/architecture/backend-capability-matrix.md +++ b/docs/architecture/backend-capability-matrix.md @@ -115,7 +115,7 @@ honour an option ignores it (documented contract). | Page backgrounds (`DocumentSession.pageBackgrounds`, `PageBackgroundFill` — full page, columns, bands) | ✅ `DocumentPageBackgrounds` adds each fill as a shape fragment under every page's content, drawn by the ordinary shape handler | ✅ the same fragments, drawn as shapes on every slide | ⚠️ `DocxPageBackgrounds` — each fill is a rectangle anchored to the page, behind the text. A section of more than one page, or with a header or footer, carries them in every header part it has (default, first page, even pages), so they are drawn on every page; a section without a header gets an empty one against the page edge to carry them, and a later section without fills gets an empty header of its own rather than inheriting them. On a page with no top margin LibreOffice still sets the first line about 3pt lower under that header. A section of one page with neither draws them from the body instead — in the first cell's paragraph when the page opens with a table — and its lines stand where the page sets them in both editors (the seven sidebar CVs stood 2.6 to 3.3pt low in LibreOffice); they are on that page alone, so a page an editor's text runs onto has none. A fill's alpha is carried as the shape's. A two-column layout still flows its columns one after the other, so a column fill can stand beside text that is not its column's | | Watermark (front/back layers) | ✅ `PdfWatermarkRenderer` | ✅ `PptxChromeRenderer` (per-slide shape at the PDF placement math; behind-content applies before fragments, so no z-order surgery) | ❌ (not written; reported `DROPPED`, `watermark`) | | Repeating headers / footers | ✅ `PdfHeaderFooterRenderer` — the zone's `fontName` is resolved through the document's own `FontLibrary`, so a zone draws in the family the author named; unnamed means standard-14 Helvetica, and a code point that family cannot encode is substituted with `?` exactly as body text is | ✅ `PptxChromeRenderer` (positioned per-slide text boxes; `{page}` / `{pages}` / `{date}` tokens with the numbering window rules). The named family reaches the slide run through `PptxFontMapping.familyFor`, and the same family measures the slots — a run measured against one face and typeset in another lands off-centre | ✅ `DocxSemanticBackend.writeBand` (`DocxTextBands`) — one line of a Word header or footer part: the left slot, the centre slot at a centre tab and the right slot at a right tab against the margins; `{page}` / `{pages}` as `PAGE` / `NUMPAGES` (`SECTIONPAGES` per section) fields with the roman or alphabetic switch; `{date}` as the date of the export; the separator as the paragraph's border; the header or footer distance from the band's geometry, baseline within 0.1pt in LibreOffice; a band sharing its kind with another band or a page zone stands in a frame (`w:framePr`) at its own height; `showOnFirstPage(false)` or counting from page 2 → an empty first-page part. A band starting after page 2, numbers not counting from 1 on page 1, and a band alone of its kind reaching past the page margin (written as a negative margin, so that Word holds the body at it as the page does; LibreOffice moves the body clear of it) are reported | -| Page zones (node subtree in the band) | ✅ Spliced into the layout graph by `DocumentPageZones`, so the ordinary fragment handlers draw it — no zone-specific code in the backend | ✅ Same splice, same reason: `PptxFixedLayoutBackend.renderGraph` draws every fragment of the graph | ✅ Written into a real `w:ftr` / `w:hdr` part. The band's children become runs on one Word line: a paragraph contributes its runs, a flex spacer becomes the right tab stop, and `PageContext.pageNumber()` / `pageTotal()` become live `PAGE` / `NUMPAGES` fields. Other node kinds are skipped, logged once a kind and reported once each (`DROPPED`, `page zone content`); a zone row's own fill, outline and side borders are reported as `row paint`. Because Word paginates, `PageContext.number()` refuses here rather than baking a number that would be wrong on every page but one. A zone's `appliesTo` predicate is asked over sample pages (`DocxPageClasses`) and, when it follows Word's first / even / other pages, becomes the matching part — `w:titlePg` for the first page, `w:evenAndOddHeaders` for even pages — with an empty part on the pages it skips; a predicate that picks pages within a kind (the last page) is written on every page and reported | +| Page zones (node subtree in the band) | ✅ Spliced into the layout graph by `DocumentPageZones`, so the ordinary fragment handlers draw it — no zone-specific code in the backend | ✅ Same splice, same reason: `PptxFixedLayoutBackend.renderGraph` draws every fragment of the graph | ✅ Written into a real `w:ftr` / `w:hdr` part. The band's children become runs on one Word line: a paragraph contributes its runs, a flex spacer becomes the right tab stop, and `PageContext.pageNumber()` / `pageTotal()` become live `PAGE` / `NUMPAGES` fields. Other node kinds are skipped, logged once a kind and reported once each (`DROPPED`, `page zone content`); a zone row's own fill, outline and side borders are reported as `row paint`. Word sets the line's parts one after another from the left margin and, after the first spacer, against the right margin, on one baseline, its tallest part's; the page sets each by the zone's padding, a row's columns and gap, a paragraph's alignment and a part's own sides (a page field's alignment moves nothing: its box is a point wider than its number). The `page zone` note counts the parts the page sets elsewhere — read from the layout's zone fragments: a part stands where the page sets it when its line starts, or against the right margin ends, within a point and a half of Word's, on Word's baseline with the line at the zone's edge, in one line and with no prefix before it on the left side; past a part whose width Word does not keep, or a zone whose nodes the page names or nests otherwise, where a part stands is said to be not measured — and names a zone paragraph's right-to-left direction, prefix letters, fitted size and outline entry, which the line does not carry; the line's height and the room its parts hold above and below are Word's, and a zone paragraph's anchor has no bookmark, none of these yet named. Because Word paginates, `PageContext.number()` refuses here rather than baking a number that would be wrong on every page but one. A zone's `appliesTo` predicate is asked over sample pages (`DocxPageClasses`) and, when it follows Word's first / even / other pages, becomes the matching part — `w:titlePg` for the first page, `w:evenAndOddHeaders` for even pages — with an empty part on the pages it skips; a predicate that picks pages within a kind (the last page) is written on every page and reported | | Protection / encryption | ✅ `PdfDocumentPostProcessor` | ❌ (ignored with a one-time warning — no OOXML encryption support planned) | ❌ (not written, so the file opens unprotected; reported `DROPPED`, `protection`) | | Viewer preferences | ✅ `applyViewerPreferences` in `PdfFixedLayoutBackend` | ❌ (ignored with a one-time warning — PDF-viewer concept) | n/a (not written; reported `DROPPED`, `viewer preferences`) | | Debug guide lines / node labels | ✅ `PdfGuideLinesRenderer`, `PdfNodeLabelRenderer` | ❌ (ignored with a one-time warning — render through the PDF backend to see overlays) | n/a | diff --git a/docs/recipes/docx-export.md b/docs/recipes/docx-export.md index 769002cf7..ac3c48b0f 100644 --- a/docs/recipes/docx-export.md +++ b/docs/recipes/docx-export.md @@ -67,7 +67,7 @@ creation date is real metadata. | Document node | DOCX output | |---|---| -| Paragraphs | Word paragraphs with alignment, font, size, colour, bold/italic/underline; inline runs preserved; a `\n` in the text is a line break (`w:br`), which Word would otherwise read as a space; a table cell's `text("a\nb")` stays one line, as the page sets it; a `bulletOffset` of spaces is an indent — the wrapped lines (`FROM_SECOND_LINE`), the first (`FIRST_LINE`) or all of them start that far in, measured in the paragraph's style as the page measures it; a prefix with letters in it is not written, but the wrapped lines still start after the spaces the page covers it with; no prefix is applied to a paragraph written over the flow, as one of an overlay's left-and-right pair, as a badge's initials, or in a header or footer; outside a header or footer, the report names a prefix's letters, and the room a prefix sets lines in by where a path that writes none leaves it out and it moves a line. An auto-sized paragraph (`autoSize`) is written at its style's size, not the one the page fits its text to, and outside a header or footer the report names both sizes where Word, to its half point, holds them apart. A body paragraph the layout moves to a new page keeps the space the layout leaves above its text there — its own top edge, the edges of the containers opening with it, and the gap before it where the gap did not fit at the foot of the page above — as an empty line that tall before it, kept with it, since Word drops a paragraph's space above at the top of a page and keeps a line's height; the rest of the space owed stays above that line, so Word breaks the page where it did, and the gap between the paragraph's lines comes off the line as it would off its space above. A paragraph in a table cell, an overlay or a list is left to its container | +| Paragraphs | Word paragraphs with alignment, font, size, colour, bold/italic/underline; inline runs preserved; a `\n` in the text is a line break (`w:br`), which Word would otherwise read as a space; a table cell's `text("a\nb")` stays one line, as the page sets it; a `bulletOffset` of spaces is an indent — the wrapped lines (`FROM_SECOND_LINE`), the first (`FIRST_LINE`) or all of them start that far in, measured in the paragraph's style as the page measures it; a prefix with letters in it is not written, but the wrapped lines still start after the spaces the page covers it with; no prefix is applied to a paragraph written over the flow, as one of an overlay's left-and-right pair, as a badge's initials, or in a header or footer; the report names a prefix's letters, and the room a prefix sets lines in by where a path that writes none leaves it out and it moves a line — on the paragraph, or in a header or footer on the zone's note. An auto-sized paragraph (`autoSize`) is written at its style's size, not the one the page fits its text to, and the report names both sizes where Word, to its half point, holds them apart, on the paragraph or, in a header or footer, on the zone's note. A body paragraph the layout moves to a new page keeps the space the layout leaves above its text there — its own top edge, the edges of the containers opening with it, and the gap before it where the gap did not fit at the foot of the page above — as an empty line that tall before it, kept with it, since Word drops a paragraph's space above at the top of a page and keeps a line's height; the rest of the space owed stays above that line, so Word breaks the page where it did, and the gap between the paragraph's lines comes off the line as it would off its space above. A paragraph in a table cell, an overlay or a list is left to its container | | Lists | Real Word lists: a `numbering.xml` definition per list, `w:numPr` on each item, and the authored marker as the level's text. Nesting is a list level, so Enter continues the list and Tab demotes an item. See "What a list becomes" below for the kinds that stay plain paragraphs | | Tables | Word tables, one cell per cell. Each cell states its own padding, on all four sides, so a row is as tall as the page draws it: as `w:tcMar`, and above and below partly in its paragraphs. Word and LibreOffice give every cell of a row the largest top and bottom margin of any cell in it, so a row's cells are written with its smallest, and the rest of a cell's padding above and below is space above its first paragraph and below its last (measured: a row whose day cells were padded 5.5pt above and 10.25pt below beside a label padded 0.75pt stood 60.3pt tall in both editors, where its tallest cell came to 46). A cell opening with a table has no paragraph above it to hold its padding, and a cell in a vertical merge has its bottom edge in another row: these keep their margins, and the row's comes down no lower than the largest of them. Its padding above and below gives up the room Word makes for the table's horizontal rules — half of a rule between two rows to each, the lower row's rule where the two differ, the rule above the table and the one below it whole to their row — which the page does not (measured: a 0.75pt rule made each row 0.75pt taller). A row held at the page's height is written less its margins and those rules too — a rule and a half in the first row and the last, two in a table of one row — since both editors read a row's written height as its cells' content (measured: held less one rule, a table ruled at 0.75pt stood 0.46pt taller in its first row and 0.36pt in its last). A cell that holds nothing but an empty line — a row that is only a rule, its thickness the empty cell's font — has that line cut to the room its row leaves it, the page's row less the cell's own margins and border: the page draws the rule's borders across the line, and Word and LibreOffice keep them outside it and grow the row (measured: `CobaltRota`'s two rules under a 0.9pt border stood 0.9pt taller each). A line with letters, a picture or a paragraph border of its own keeps its height. A table that states no rule is written with the engine's default 1pt black rule, as the page draws it, not left on Word's thinner grid. Its `textAnchor` becomes `w:vAlign` and the paragraph's `w:jc`, with the engine's default — the vertical middle, on the left — where Word's is the top, so a line beside a taller neighbour sits where the page puts it and an amount column stays right-aligned. A cell with no style of its own is set in the engine's default cell face rather than the document's Normal. A cell's lines are one paragraph with line breaks; when its style's `lineSpacing(...)` is above zero and it has more than one line, they are a paragraph each, with the spacing after every line but the last, since Word has no space between the lines of one paragraph but a taller line. A column sized to its content gets a point more than the page gives it, so the editor's font substitute cannot wrap its widest cell. The width is written when the document states one or every column is fixed; otherwise Word sizes the table — see "What falls back". A table breaks across pages where the layout breaks it: every row the layout placed is kept whole (`w:cantSplit`), `repeatHeader(n)` rows repeat on each page (`w:tblHeader`) and stay with the row under them. Two tables in a row — rows included, since a row is carried as a table — are kept apart by a paragraph a tenth of a point tall, holding the rest of the gap between them: an editor joins two tables with nothing between them into one. A table or a row the layout moves to a new page keeps its own top edge there, as the page does — written as a line that tall, kept with it, since Word drops a paragraph's space above at the top of a page — while the gap between it and the block before stays at the foot of the page above, where it fits there; a gap the layout carries onto the new page, because it did not fit at the foot of the page above, is not yet held above a table (body paragraphs and spacers: see their rows). A table's margin is its indent and the space round it, and its padding on the sides holds its rows in as the page draws them: its left side is in the indent too, and both are out of the room its columns are given | | Composed cells (`DocumentTableCell.node(...)`) | Written by the same writers that write that node anywhere else, so a cell built from an image, a list or a table carries it. A nested table is a real `w:tbl` followed by the paragraph Word requires a cell to end with — a hairline, which the paragraph written next in the cell takes over, so no empty line opens under the table, and whose mark is hidden where it is left at the cell's end holding nothing and no space, since LibreOffice lays it out — and takes the width of the column it sits in, less its own margins and padding — the column's, not the one the page gives it, because the layout reports a composed cell's content under the owner's path | @@ -1007,6 +1007,20 @@ A zone is written from its paragraphs, page fields and spacers: anything else in logo, a panel, a table — is not written, and the export report names it once (`page zone content`). +The zone's line is Word's: its parts one after another from the page's left margin, and +those after the first spacer against its right margin, at the right tab the line holds, all +on one baseline, its tallest part's. Where the page sets a part elsewhere — by the zone's +padding, a row's columns and gap, a paragraph's alignment or a part's own sides — off that +baseline, over more than one line or after a prefix, the export report counts it (`page +zone`): "1 of its 3 parts stands off where the page sets them". A page field's alignment +moves nothing: the page sets it in a box a point wider than its number. Past a part Word sets +at another width — after a prefix, auto-sized to a size the file does not hold, over more +lines than one — or in a zone whose nodes the page names or nests otherwise than the file, it +says where a part stands is not measured. It names what a paragraph in the zone loses of its +own too: its right-to-left direction, a prefix's letters, the size an auto-sized one is fitted +to, its outline entry. The line's height and the room its parts hold above and below are +Word's, and an anchor in a zone has no bookmark; none of these is named yet. + A zone drawn on some pages only (`appliesTo(...)`) lands on the same pages when Word can say so. Word has a header and footer for the first page, for even pages and for the rest, so the predicate is asked over sample pages and sorted into those kinds: diff --git a/render-docx/README.md b/render-docx/README.md index d8d7fbad5..c357a7b8e 100644 --- a/render-docx/README.md +++ b/render-docx/README.md @@ -113,6 +113,8 @@ What is not written — each one is named in the export report - **A row's own fill, outline and side borders**, named in the export report as `row paint`. - **In a page zone, anything but paragraphs, page fields and spacers** — a logo, a barcode, a rule — named in the export report as `page zone content`. +- **Where a page zone's parts stand on Word's line, and what a paragraph in it loses of its + own**, named in the export report as `page zone`. - **A list's own geometry where Word cannot hold it**, named in the export report on the list: - a centred or right-aligned list's alignment; - its `lineSpacing` where the layout's items are not its own; @@ -121,7 +123,7 @@ What is not written — each one is named in the export report too narrow for its marker — while a flat hanging-indent list keeps the page's column; - a row the page draws as a marker alone, for a blank item. - **What a paragraph's own fields set where Word cannot hold it**, named in the export report on - the paragraph outside a header or footer (a page zone's paragraphs are not named yet): + the paragraph outside a header or footer (a page zone's are named on the zone): - the size an auto-sized paragraph's text is fitted to, where Word, to its half point, holds it apart from its style's; - the letters of a `bulletOffset` prefix; and, where it moves a line, the room a prefix sets diff --git a/render-docx/src/main/java/com/demcha/compose/document/backend/semantic/docx/DocxLayoutMetrics.java b/render-docx/src/main/java/com/demcha/compose/document/backend/semantic/docx/DocxLayoutMetrics.java index e0e3648fc..c340422fd 100644 --- a/render-docx/src/main/java/com/demcha/compose/document/backend/semantic/docx/DocxLayoutMetrics.java +++ b/render-docx/src/main/java/com/demcha/compose/document/backend/semantic/docx/DocxLayoutMetrics.java @@ -496,6 +496,62 @@ OptionalDouble zoneDistanceFromEdge(int zoneIndex, boolean header, double pageHe return OptionalDouble.of(header ? pageHeight - highest : lowest); } + /** + * The text a page zone's content laid out, on the first page the zone is drawn on: each + * node's first fragment of paragraph lines, by its path within the content. + * + *

A zone's content is compiled on its own, its paths as a document's of that one root, + * and spliced in under {@code @page-zone[page][index]} (see {@link #zoneDistanceFromEdge}). + * The export builds the content again, so it finds its nodes here by those paths + * ({@link #pathsWithin}).

+ * + * @param zoneIndex the zone's position in the section's zone list + * @return the fragments by path, empty when the layout carries no such zone + */ + Map zoneText(int zoneIndex) { + java.util.regex.Pattern zone = + java.util.regex.Pattern.compile("^@page-zone\\[\\d+]\\[" + zoneIndex + "]"); + // The page a zone's fragment is drawn on is the one its path names. + int first = Integer.MAX_VALUE; + for (Map.Entry> entry : fragments.entrySet()) { + if (zone.matcher(entry.getKey()).find()) { + for (PlacedFragment fragment : entry.getValue()) { + first = Math.min(first, fragment.pageIndex()); + } + } + } + if (first == Integer.MAX_VALUE) { + return Map.of(); + } + String prefix = "@page-zone[" + first + "][" + zoneIndex + "]"; + Map text = new HashMap<>(); + for (Map.Entry> entry : fragments.entrySet()) { + if (!entry.getKey().startsWith(prefix)) { + continue; + } + for (PlacedFragment fragment : entry.getValue()) { + if (fragment.payload() instanceof ParagraphFragmentPayload paragraph && !paragraph.lines().isEmpty()) { + text.putIfAbsent(entry.getKey().substring(prefix.length()), fragment); + break; + } + } + } + return text; + } + + /** + * The paths the layout gives a tree compiled as a document of its own root: a page zone's + * content, which the layout lays out apart from the body. + * + * @param root the tree's root + * @return each node's path + */ + static Map pathsWithin(DocumentNode root) { + Map paths = new IdentityHashMap<>(); + indexPaths(root, null, 0, paths); + return paths; + } + /** * The path the layout graph addresses a node by, for a note that has to say where in * the document it came from. diff --git a/render-docx/src/main/java/com/demcha/compose/document/backend/semantic/docx/DocxSemanticBackend.java b/render-docx/src/main/java/com/demcha/compose/document/backend/semantic/docx/DocxSemanticBackend.java index 43c244a06..ca904947b 100644 --- a/render-docx/src/main/java/com/demcha/compose/document/backend/semantic/docx/DocxSemanticBackend.java +++ b/render-docx/src/main/java/com/demcha/compose/document/backend/semantic/docx/DocxSemanticBackend.java @@ -406,6 +406,9 @@ public final class DocxSemanticBackend implements SemanticBackend { /** The page's top margin in points, or {@code NaN} when the export has no canvas. */ private double canvasTopMargin = Double.NaN; + /** The page's left margin in points, where a header or footer starts; {@code NaN} with no canvas. */ + private double canvasLeftMargin = Double.NaN; + /** Whether this export writes more than one section — see {@link #exportSections}. */ private boolean sectioned; @@ -870,6 +873,7 @@ private void beginSection(SemanticSection section, int index) { contentWidth = context.canvas() == null ? Double.MAX_VALUE : context.canvas().innerWidth(); canvasHeight = context.canvas() == null ? Double.NaN : context.canvas().height(); canvasTopMargin = context.canvas() == null ? Double.NaN : context.canvas().margin().top(); + canvasLeftMargin = context.canvas() == null ? Double.NaN : context.canvas().margin().left(); } /** @@ -1241,7 +1245,10 @@ private java.util.Set applyPageZones( int at = index; boolean header = zone.getZone() == DocumentHeaderFooterZone.HEADER; writers.add(new ZoneWriter(zone.getZone(), pageClassesOf(zone), - part -> writeZoneLine(part, content), () -> placeZone(document, zone, at, header))); + part -> writeZoneLine(part, content), () -> { + placeZone(document, zone, at, header); + reportZoneLine(at, header, content); + })); } boolean titlePage = false; for (ZoneWriter writer : writers) { @@ -1717,9 +1724,9 @@ private void writeZoneLine(XWPFHeaderFooter target, DocumentNode content) { : para.getCTP().addNewPPr(); CTTabStop tab = properties.addNewTabs().addNewTab(); tab.setVal(STTabJc.RIGHT); - tab.setPos(java.math.BigInteger.valueOf(Math.round(contentWidth * TWIPS_PER_POINT))); + tab.setPos(java.math.BigInteger.valueOf(Math.round(zoneRightTab() * TWIPS_PER_POINT))); - List parts = content instanceof RowNode row ? row.children() : List.of(content); + List parts = zoneParts(content); // A zone's row is its children on one line; its paint is lost as a body row's is, and // said once, though the line is written into each kind of header the zone is given. if (content instanceof RowNode row && zonePartsReported.add(row)) { @@ -1730,6 +1737,267 @@ private void writeZoneLine(XWPFHeaderFooter target, DocumentNode content) { } } + /** The parts a zone's line is written from, in order: a row's children, or the zone's one node. */ + private static List zoneParts(DocumentNode content) { + return content instanceof RowNode row ? row.children() : List.of(content); + } + + /** Where a zone's line holds its right tab, from the left margin: at the right margin, in points. */ + private double zoneRightTab() { + return contentWidth; + } + + /** + * How near Word's place for a part of a zone's line the page's may be and still be its own, + * in points: a point and a half. A page field's box is a point wider than its number, which + * its alignment moves it within, and Word sets a size to the half point. + */ + private static final double ZONE_PLACE_CLEARANCE = 1.5; + + /** + * Names what a page zone loses as the one line of a Word header or footer it is written as + * ({@link #writeZoneLine}). + * + *

Word sets the line's parts one after another from the page's left margin, and those + * after the first spacer against its right margin, at the right tab the line holds; a part + * after a second spacer goes to no tab the line holds. The page sets each part where the + * zone's padding, a row's columns and gap and the part's own alignment and sides put it, on + * a baseline of its own. Word's line has one baseline, its tallest part's, and stands at the + * zone's edge — the foot of a footer, the head of a header ({@link #placeZone}). A part + * stands where the page sets it when it is one line — the zone's line is written with none + * of what holds a body paragraph's breaks where the page sets them — on Word's baseline, and + * its line starts within {@link #ZONE_PLACE_CLEARANCE} of Word's start, or, against the + * right margin, ends within it of Word's end; a part a prefix stands before starts off it, + * the prefix being unwritten. Word's place for a part follows from the widths of those + * before it on its side of the line: past a part whose width Word does not keep — of more + * lines than one, after a prefix, or auto-sized to a size the file does not hold — or one + * the layout does not show, where it stands across the line is not measured. A zone whose + * nodes the page names or nests otherwise than the file, built for no page in particular, + * shows none of its parts.

+ * + *

A paragraph's own losses are named too: its right-to-left text is written left to + * right, its prefix's letters are not written, its text is written at its style's size, + * and its outline entry is not written.

+ * + * @param zoneIndex the zone's position in the section's zone list + * @param header whether the zone is a header + * @param content the zone's content, as written + */ + private void reportZoneLine(int zoneIndex, boolean header, DocumentNode content) { + List parts = zoneParts(content); + java.util.Map paths = DocxLayoutMetrics.pathsWithin(content); + java.util.Map laid = layout.zoneText(zoneIndex); + boolean measured = !laid.isEmpty() && !Double.isNaN(canvasLeftMargin); + // Each text part's side of the line: 0 from the left margin, 1 against the right, 2 + // after a second spacer, where the line holds no tab for it. + java.util.Map side = new java.util.IdentityHashMap<>(); + List texts = new ArrayList<>(); + int spacers = 0; + for (DocumentNode part : parts) { + if (part instanceof SpacerNode) { + spacers++; + } else if (part instanceof ParagraphNode || part instanceof PageFieldNode) { + texts.add(part); + side.put(part, Math.min(spacers, 2)); + } + } + // Where Word starts each part from the left margin, and ends each one against the right, + // as far as the widths before it on its side are ones Word keeps. + java.util.Map wordsStart = new java.util.IdentityHashMap<>(); + java.util.Map wordsEnd = new java.util.IdentityHashMap<>(); + double x = canvasLeftMargin; + for (DocumentNode part : texts) { + com.demcha.compose.document.layout.PlacedFragment fragment = laid.get(paths.get(part)); + if (side.get(part) != 0 || fragment == null) { + break; + } + wordsStart.put(part, x); + if (!widthKept(part, fragment)) { + break; + } + x += wordsWidthOf(fragment); + } + double end = canvasLeftMargin + zoneRightTab(); + List againstTheRight = texts.stream().filter(part -> side.get(part) == 1).toList(); + for (int index = againstTheRight.size() - 1; index >= 0; index--) { + DocumentNode part = againstTheRight.get(index); + com.demcha.compose.document.layout.PlacedFragment fragment = laid.get(paths.get(part)); + if (fragment == null) { + break; + } + wordsEnd.put(part, end); + if (!widthKept(part, fragment)) { + break; + } + end -= wordsWidthOf(fragment); + } + // Where the page sets each part's first line. + java.util.Map onThePage = new java.util.IdentityHashMap<>(); + for (DocumentNode part : texts) { + com.demcha.compose.document.layout.PlacedFragment fragment = laid.get(paths.get(part)); + if (measured && fragment != null) { + onThePage.put(part, firstLineOnThePage(fragment)); + } + } + double baseline = wordsBaseline(onThePage.values(), header); + int off = 0; + int unread = 0; + for (DocumentNode part : texts) { + ZoneLine line = onThePage.get(part); + Double wordStart = wordsStart.get(part); + Double wordEnd = wordsEnd.get(part); + boolean prefixed = side.get(part) == 0 && part instanceof ParagraphNode paragraph + && setsAPrefixBeforeTheFirstLine(paragraph); + if (line == null) { + unread++; + } else if (side.get(part) == 2 || !line.oneLine() || prefixed + || Math.abs(line.baseline() - baseline) > ZONE_PLACE_CLEARANCE) { + off++; + } else if (wordStart == null && wordEnd == null) { + unread++; + } else if (wordStart != null ? Math.abs(line.start() - wordStart) > ZONE_PLACE_CLEARANCE + : Math.abs(line.end() - wordEnd) > ZONE_PLACE_CLEARANCE) { + off++; + } + } + java.util.Set lost = new java.util.LinkedHashSet<>(); + if (!texts.isEmpty() && unread == texts.size()) { + lost.add("whether its text stands where the page sets it is not measured"); + } else { + if (off > 0) { + lost.add(texts.size() == 1 ? "its text stands off where the page sets it" + : partsOf(off, texts.size()) + " off where the page sets them"); + } + if (unread > 0) { + lost.add("where " + partsOf(unread, texts.size()) + " is not measured"); + } + } + for (DocumentNode part : texts) { + if (part instanceof ParagraphNode paragraph) { + com.demcha.compose.document.layout.PlacedFragment fragment = laid.get(paths.get(part)); + List lines = fragment == null ? List.of() + : ((com.demcha.compose.document.layout.payloads.ParagraphFragmentPayload) fragment.payload()).lines(); + lost.addAll(zoneParagraphLost(paragraph, lines)); + } + } + if (!lost.isEmpty()) { + String kind = header ? "header" : "footer"; + report.add(DocxExportReport.Severity.APPROXIMATED, "page zone", + sectioned ? "section " + (sectionIndex + 1) : null, + "a " + kind + " written as one line of Word's " + kind + "; " + String.join("; ", lost)); + } + } + + /** + * What a paragraph of a page zone loses of its own on the zone's line: its direction, its + * prefix's letters, the size its text is fitted to, and its outline entry. + * + * @param lines the lines the page laid it out in, empty where they are not read + */ + private List zoneParagraphLost(ParagraphNode node, List lines) { + List lost = new ArrayList<>(4); + if (ParagraphDirection.resolve(node) == TextDirection.RTL) { + lost.add("a paragraph's right-to-left text is written left to right"); + } + if (setsAPrefixBeforeTheFirstLine(node) && !node.bulletOffset().isBlank()) { + lost.add("a paragraph's bulletOffset letters, \"" + node.bulletOffset().strip() + "\", are not written " + + "before its first line"); + } + String size = autoSizeLost(node, lines, "a paragraph's"); + if (size != null) { + lost.add(size); + } + if (node.bookmarkOptions() != null) { + lost.add("a paragraph's outline entry is not written"); + } + return lost; + } + + /** How many of a zone's parts a phrase is about, with its verb: "1 of its 3 parts stands". */ + private static String partsOf(int some, int all) { + return some + " of its " + all + " parts " + (some == 1 ? "stands" : "stand"); + } + + /** The width Word sets a part of a zone's line at: its laid-out line at Word's size. */ + private static double wordsWidthOf(com.demcha.compose.document.layout.PlacedFragment fragment) { + return widthAtWordsSize(((com.demcha.compose.document.layout.payloads.ParagraphFragmentPayload) fragment.payload()) + .lines().get(0)); + } + + /** + * Whether Word sets a part of a zone's line as wide as the page sets it, give or take its + * half-point size: one line, with no prefix it does not write and at the size the page fits + * its text to. + */ + private static boolean widthKept(DocumentNode part, com.demcha.compose.document.layout.PlacedFragment fragment) { + List lines = + ((com.demcha.compose.document.layout.payloads.ParagraphFragmentPayload) fragment.payload()).lines(); + return lines.size() == 1 && !(part instanceof ParagraphNode paragraph + && (setsAPrefixBeforeTheFirstLine(paragraph) || autoSizeLost(paragraph, lines, "its") != null)); + } + + /** + * Where the page sets a part of a zone's line, from the page's left edge and its foot. + * + * @param start where its first line starts + * @param end where its first line ends + * @param baseline its first line's baseline, seated as the PDF backend seats it + * @param top its first line's top + * @param bottom its first line's foot + * @param above how far its first line's top stands above its baseline + * @param below how far its first line's foot stands below its baseline + * @param oneLine whether it is laid out as one line + */ + private record ZoneLine(double start, double end, double baseline, double top, double bottom, + double above, double below, boolean oneLine) { + } + + /** + * Where the page sets a fragment's first line (see {@link ZoneLine}), its baseline seated as the + * PDF backend seats it ({@link com.demcha.compose.document.backend.fixed.pdf.handlers.ParagraphSeating}). + */ + private ZoneLine firstLineOnThePage(com.demcha.compose.document.layout.PlacedFragment fragment) { + com.demcha.compose.document.layout.payloads.ParagraphFragmentPayload text = + (com.demcha.compose.document.layout.payloads.ParagraphFragmentPayload) fragment.payload(); + com.demcha.compose.document.layout.payloads.ParagraphLine line = text.lines().get(0); + double start = com.demcha.compose.document.layout.payloads.ParagraphLineGeometry.lineStartX(text.align(), + fragment.x() + text.padding().left(), + fragment.width() - text.padding().left() - text.padding().right(), line.width()); + double top = com.demcha.compose.document.layout.payloads.ParagraphLineGeometry.contentTop(fragment.y(), + fragment.height(), text.padding().top()); + double baseline = com.demcha.compose.document.layout.payloads.ParagraphLineGeometry.baselineY( + top, line.lineHeight(), line.baselineOffsetFromBottom()); + double below = line.baselineOffsetFromBottom(); + double above = line.lineHeight() - below; + if (text.verticalAlign() != null && text.verticalAlign() != TextVerticalAlign.DEFAULT) { + baseline += com.demcha.compose.document.backend.fixed.pdf.handlers.ParagraphSeating + .shift(line, measuredFonts(), text.verticalAlign()); + } + return new ZoneLine(start, start + line.width(), baseline, top, top - line.lineHeight(), above, below, + text.lines().size() == 1); + } + + /** + * The baseline Word sets a zone's line on, where the page sets its parts: the tallest part's, + * Word having one baseline for a line, with the line standing at the zone's edge — its foot at + * the lowest foot of the parts in a footer, its head at the highest head in a header. + * {@code NaN} where no part is read. + */ + private static double wordsBaseline(java.util.Collection lines, boolean header) { + ZoneLine tallest = null; + double edge = header ? Double.NEGATIVE_INFINITY : Double.POSITIVE_INFINITY; + for (ZoneLine line : lines) { + if (tallest == null || line.above() + line.below() > tallest.above() + tallest.below()) { + tallest = line; + } + edge = header ? Math.max(edge, line.top()) : Math.min(edge, line.bottom()); + } + if (tallest == null) { + return Double.NaN; + } + return header ? edge - tallest.above() : edge + tallest.below(); + } + private void appendZonePart(XWPFParagraph para, DocumentNode part) { if (part instanceof ParagraphNode paragraph) { writeParagraphRuns(para, paragraph, false); @@ -6331,7 +6599,8 @@ private void writeLinePair(XWPFDocument document, DocumentNode overlay, DocxLine // The left side starts where its line starts, prefix and all; the right side does too // where a left tab holds its start, and where a right tab holds its end it ends there. reportWrittenWithout(pair.left(), "written as one side of a line it shares", - paragraphLost(pair.left(), laysOutAPrefix(pair.left()), leftHeads ? line : null)); + paragraphLost(pair.left(), laysOutAPrefix(pair.left()), + leftHeads ? line : null)); reportWrittenWithout(pair.right(), "written as one side of a line it shares", paragraphLost(pair.right(), pair.fromItsStart() && laysOutAPrefix(pair.right()), leftHeads ? null : line)); @@ -6732,7 +7001,8 @@ private void writeParagraph(XWPFDocument document, ParagraphNode node) { /** * What a paragraph's own fields lose on the way to Word, on any path that writes it in the * body: the size an auto-sized paragraph's text is fitted to, its {@code bulletOffset} and its - * outline entry. A page zone's paragraphs are written apart, and these are not named for them. + * outline entry. A page zone's paragraphs are written apart, and named on the zone's note + * ({@link #zoneParagraphLost}). * *

Its text is written at its style's size, not the one the page fits it to. A prefix's * letters are never written. A path that does not write a prefix as a distance @@ -6749,7 +7019,7 @@ private void writeParagraph(XWPFDocument document, ParagraphNode node) { */ private List paragraphLost(ParagraphNode node, boolean roomLost, String listedAs) { List lost = new ArrayList<>(4); - String size = autoSizeLost(node); + String size = node.autoSize() == null ? null : autoSizeLost(node, layout.lines(node), "its"); if (size != null) { lost.add(size); } @@ -6788,24 +7058,32 @@ private boolean roomLostInItsBox(ParagraphNode node) { return laysOutAPrefix(node) && !(layout.lineCount(node) == 1 && setFromTheEndAwayFromItsPrefix(node)); } + /** Whether the page lays out a body paragraph's prefix, its lines read only where it has one. */ + private boolean laysOutAPrefix(ParagraphNode node) { + return !node.bulletOffset().isEmpty() && laysOutAPrefix(node, layout.lines(node)); + } + /** * What an auto-sized paragraph's text loses of its size: the size the file holds it at, to * Word's half point, and the one the page fits it to, where Word sets the two apart; the * size alone, saying the fitted one is not measured, where the layout does not tell it; or * {@code null} when it loses nothing, or nothing laid out takes the paragraph's style — a run * with a style of its own keeps its size on the page. + * + * @param lines the lines the page laid the paragraph out in, empty where they are not read */ - private String autoSizeLost(ParagraphNode node) { - if (node.autoSize() == null || !holdsTextInTheParagraphsStyle(node) && !laysOutAPrefix(node)) { + private static String autoSizeLost(ParagraphNode node, List lines, + String whose) { + if (node.autoSize() == null || !holdsTextInTheParagraphsStyle(node) && !laysOutAPrefix(node, lines)) { return null; } double written = wordsSize(node.textStyle().size()); - double fitted = fittedSize(node); + double fitted = fittedSize(node, lines); if (Double.isNaN(fitted)) { - return "its text is written at " + pointsOf(written) + "pt — the size the page fits it to is not measured"; + return whose + " text is written at " + pointsOf(written) + "pt — the size the page fits it to is not measured"; } return wordsSize(fitted) != written - ? "its text is written at " + pointsOf(written) + "pt, where the page fits it to " + pointsOf(fitted) + "pt" + ? whose + " text is written at " + pointsOf(written) + "pt, where the page fits it to " + pointsOf(fitted) + "pt" : null; } @@ -6827,21 +7105,22 @@ private static boolean holdsTextInTheParagraphsStyle(ParagraphNode node) { * Whether the page lays out a paragraph's prefix, in the paragraph's style: before a first line * that holds something, or before a line after it that holds something, or where its lines * are not read. + * + * @param lines the lines the page laid the paragraph out in, empty where they are not read */ - private boolean laysOutAPrefix(ParagraphNode node) { + private static boolean laysOutAPrefix(ParagraphNode node, List lines) { DocumentTextIndent strategy = node.indentStrategy(); return setsAPrefixBeforeTheFirstLine(node) || !node.bulletOffset().isEmpty() && (strategy == DocumentTextIndent.FROM_SECOND_LINE || strategy == DocumentTextIndent.ALL_LINES) - && holdsALineAfterTheFirst(node); + && holdsALineAfterTheFirst(lines); } /** - * Whether a paragraph lays out a line after its first that holds something, or its lines are - * not read: an empty line, the page sets no prefix before. + * Whether a paragraph's lines hold a line after the first that holds something, or are not + * read: an empty line, the page sets no prefix before. */ - private boolean holdsALineAfterTheFirst(ParagraphNode node) { - List lines = layout.lines(node); + private static boolean holdsALineAfterTheFirst(List lines) { if (lines.isEmpty()) { return true; } @@ -6877,7 +7156,7 @@ private static boolean setFromTheEndAwayFromItsPrefix(ParagraphNode node) { * of its own is laid out at that style's size, so the paragraph's size is one no such run has; * where the lines hold a single size, it is that one. */ - private double fittedSize(ParagraphNode node) { + private static double fittedSize(ParagraphNode node, List lines) { java.util.Set ownSizes = new java.util.HashSet<>(); for (InlineRun run : node.inlineRuns()) { InlineTextRun text = textOf(run); @@ -6886,7 +7165,7 @@ private double fittedSize(ParagraphNode node) { } } java.util.Set laidOut = new java.util.LinkedHashSet<>(); - for (com.demcha.compose.document.layout.payloads.ParagraphLine line : layout.lines(node)) { + for (com.demcha.compose.document.layout.payloads.ParagraphLine line : lines) { for (com.demcha.compose.document.layout.payloads.ParagraphSpan span : line.spans()) { if (span instanceof com.demcha.compose.document.layout.payloads.ParagraphTextSpan text && text.width() > 0 && text.textStyle() != null) { diff --git a/render-docx/src/test/java/com/demcha/compose/document/backend/semantic/docx/DocxNodeFieldLedgerTest.java b/render-docx/src/test/java/com/demcha/compose/document/backend/semantic/docx/DocxNodeFieldLedgerTest.java index 45a7a7a35..e01dab967 100644 --- a/render-docx/src/test/java/com/demcha/compose/document/backend/semantic/docx/DocxNodeFieldLedgerTest.java +++ b/render-docx/src/test/java/com/demcha/compose/document/backend/semantic/docx/DocxNodeFieldLedgerTest.java @@ -59,7 +59,8 @@ * *

A node's entries are about the body. A page zone is written as one line of its * paragraphs' runs, page fields and tabs, which loses more of a paragraph and a row than the - * body does; that is recorded once, as the {@code zones} output option's gap.

+ * body does: where its parts stand and what its paragraphs lose of their own is reported, and + * what is not is recorded once, as the {@code zones} output option's gap.

* *

The entries are claims about the export, not proofs of it: a {@code WRITTEN} field is * proved by the export's own tests, a {@code REPORTED} one by a report test, and a {@code GAP} @@ -95,9 +96,11 @@ private record Entry(Fate fate, String note) { "viewerPreferences:REPORTED", "headersAndFooters:WRITTEN", // The node entries below are the body's. A zone is written as one line of its - // paragraphs' runs, page fields and tabs, which is a gap of its own. - "zones:GAP:in a page zone, a paragraph's alignment, spacing, direction, prefix, fitted size and " - + "outline entry and a row's columns, gap and padding; whatever else a zone holds is reported"); + // paragraphs' runs, page fields and tabs; what of that the report does not name is + // a gap of its own. + "zones:GAP:in a page zone, its line's height and the room its parts hold above and below their " + + "text, which Word sets its own way, and a paragraph's anchor; where its parts stand across the " + + "line and on its baseline, and what else a zone holds, is reported"); static { node(AlignNode.class, "name:INERT", "child:WRITTEN", "align:WRITTEN", "margin:WRITTEN"); @@ -154,8 +157,14 @@ private record Entry(Fate fate, String note) { + "two spaces a level in"); node(PageBreakNode.class, "name:INERT", "margin:INERT"); node(PageFieldNode.class, "name:INERT", "kind:WRITTEN", "textStyle:WRITTEN", - "align:GAP:its alignment in a page zone", "padding:GAP:its sides in a page zone", - "margin:GAP:its sides in a page zone"); + "align:INERT:the page sets a field in a box a point wider than its number, which its " + + "alignment moves it no further within", + "padding:REPORTED:at its sides, and above and below beside other parts, where they stand the " + + "field off the place Word sets it on the zone's line; a lone field's above and below, in the " + + "zones option's gap", + "margin:REPORTED:at its sides, and above and below beside other parts, where they stand the " + + "field off the place Word sets it on the zone's line; a lone field's above and below, in the " + + "zones option's gap"); node(PageReferenceNode.class, "name:INERT", "anchor:REPORTED:where the anchor has no bookmark, its number is written as text", "textStyle:WRITTEN", "align:WRITTEN", "placeholderText:WRITTEN", diff --git a/render-docx/src/test/java/com/demcha/compose/document/backend/semantic/docx/DocxZoneReportTest.java b/render-docx/src/test/java/com/demcha/compose/document/backend/semantic/docx/DocxZoneReportTest.java new file mode 100644 index 000000000..01b89987b --- /dev/null +++ b/render-docx/src/test/java/com/demcha/compose/document/backend/semantic/docx/DocxZoneReportTest.java @@ -0,0 +1,313 @@ +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.backend.semantic.SemanticBackend; +import com.demcha.compose.document.backend.semantic.SemanticExportContext; +import com.demcha.compose.document.dsl.ParagraphBuilder; +import com.demcha.compose.document.dsl.RowBuilder; +import com.demcha.compose.document.layout.DocumentGraph; +import com.demcha.compose.document.node.DocumentBookmarkOptions; +import com.demcha.compose.document.node.PageFieldKind; +import com.demcha.compose.document.node.PageFieldNode; +import com.demcha.compose.document.node.TextAlign; +import com.demcha.compose.document.node.TextDirection; +import com.demcha.compose.document.output.DocumentHeaderFooterZone; +import com.demcha.compose.document.output.DocumentPageZone; +import com.demcha.compose.document.style.DocumentInsets; +import com.demcha.compose.document.style.DocumentTextIndent; +import com.demcha.compose.document.style.DocumentTextStyle; +import org.junit.jupiter.api.Test; + +import java.util.List; +import java.util.concurrent.atomic.AtomicReference; + +import static org.assertj.core.api.Assertions.assertThat; + +/** + * What a page zone loses as the one line of a Word header or footer it is written as is in the + * report: where its parts stand, and what a paragraph among them loses of its own. + * + *

Word sets the line's parts one after another from the page's left margin, and those after + * the first spacer against its right margin. The page sets each where the zone's padding, a row's + * columns and gap and the part's own alignment and sides put it. A zone whose parts stand where + * Word sets them, and whose paragraphs lose nothing of their own, is not named.

+ */ +class DocxZoneReportTest { + + private static final DocumentTextStyle CHROME = DocumentTextStyle.DEFAULT.withSize(8); + private static final String FOOTER = "a footer written as one line of Word's footer; "; + private static final String OFF = "its text stands off where the page sets it"; + + @Test + void aLineSetFromTheLeftMarginIsNotNamed() throws Exception { + assertThat(zoneNotes(DocumentPageZone.footer(30, page -> text("Confidential").build()))).isEmpty(); + // Its parts after a spacer end at the right margin, where Word's right tab holds them. + assertThat(zoneNotes(DocumentPageZone.footer(30, page -> new RowBuilder().name("Line") + .addParagraph(p -> p.text("Confidential").textStyle(CHROME)) + .flexSpacer() + .add(page.pageNumber(CHROME)) + .build()))).isEmpty(); + } + + @Test + void aPartThePageSetsElsewhereThanWordIsNamed() throws Exception { + assertThat(zoneNotes(DocumentPageZone.footer(30, page -> text("Confidential").align(TextAlign.CENTER).build()))) + .containsExactly(FOOTER + OFF); + assertThat(zoneNotes(DocumentPageZone.footer(30, page -> text("Confidential").build()).toBuilder() + .padding(new DocumentInsets(0, 0, 0, 20)).build())) + .as("the zone's own padding").containsExactly(FOOTER + OFF); + assertThat(zoneNotes(DocumentPageZone.header(30, page -> text("Confidential").margin(new DocumentInsets(0, 0, 0, 12)) + .build()))) + .as("a paragraph's own side, in a header").containsExactly("a header written as one line of Word's header; " + OFF); + assertThat(zoneNotes(DocumentPageZone.footer(30, page -> page.pageNumber(CHROME)))) + .as("a page number set from the left").isEmpty(); + // The page sets a field in a box a point wider than its number, which its alignment moves + // it within; its own side moves it as a paragraph's does. + assertThat(zoneNotes(DocumentPageZone.footer(30, page -> new PageFieldNode("Number", PageFieldKind.NUMBER, + CHROME, TextAlign.RIGHT, DocumentInsets.zero(), DocumentInsets.zero())))).as("aligned right").isEmpty(); + assertThat(zoneNotes(DocumentPageZone.footer(30, page -> new PageFieldNode("Number", PageFieldKind.NUMBER, + CHROME, TextAlign.LEFT, DocumentInsets.zero(), new DocumentInsets(0, 0, 0, 12))))) + .as("set in by its margin").containsExactly(FOOTER + OFF); + // A row of a spacer and a page number sets the number against the right margin, as Word does. + assertThat(zoneNotes(DocumentPageZone.footer(30, page -> new RowBuilder().name("Line") + .flexSpacer() + .add(page.pageNumber(CHROME)) + .build()))).isEmpty(); + } + + @Test + void theLineTheReportReadsIsTheOneWritten() throws Exception { + // One right tab, at the right margin, which the report's line holds its right side at. + try (DocumentSession session = session(DocumentPageZone.footer(30, page -> new RowBuilder().name("Line") + .addParagraph(p -> p.text("Confidential").textStyle(CHROME)) + .flexSpacer() + .add(page.pageNumber(CHROME)) + .build()))) { + try (org.apache.poi.xwpf.usermodel.XWPFDocument document = new org.apache.poi.xwpf.usermodel.XWPFDocument( + new java.io.ByteArrayInputStream(session.export(new DocxSemanticBackend())))) { + var tabs = document.getFooterArray(0).getParagraphs().get(0).getCTP().getPPr().getTabs(); + assertThat(tabs.sizeOfTabArray()).isEqualTo(1); + assertThat(tabs.getTabArray(0).getVal().toString()).isEqualTo("right"); + assertThat(DocxTwips.of(tabs.getTabArray(0).getPos())).isEqualTo(Math.round((300 - 2 * 36) * 20.0)); + } + } + } + + @Test + void aRowsColumnsAndGapAreCountedWherePartsStandOffWordsLine() throws Exception { + // Without a spacer, Word sets the second right after the first; the page sets it at its column. + assertThat(zoneNotes(DocumentPageZone.footer(30, page -> new RowBuilder().name("Line") + .addParagraph(p -> p.text("Confidential").textStyle(CHROME)) + .addParagraph(p -> p.text("Acme").textStyle(CHROME)) + .build()))) + .containsExactly(FOOTER + "1 of its 2 parts stands off where the page sets them"); + // After a spacer, the page keeps its gap between the parts; Word sets them against each other. + assertThat(zoneNotes(DocumentPageZone.footer(30, page -> new RowBuilder().name("Line").spacing(8) + .addParagraph(p -> p.text("Confidential").textStyle(CHROME)) + .flexSpacer() + .addParagraph(p -> p.text("v2.4").textStyle(CHROME)) + .add(page.pageNumber(CHROME)) + .build()))) + .containsExactly(FOOTER + "1 of its 3 parts stands off where the page sets them"); + // A part after a second spacer goes to no tab the line holds. + assertThat(zoneNotes(DocumentPageZone.footer(30, page -> new RowBuilder().name("Line") + .addParagraph(p -> p.text("Confidential").textStyle(CHROME)) + .flexSpacer() + .addParagraph(p -> p.text("v2.4").textStyle(CHROME)) + .flexSpacer() + .add(page.pageNumber(CHROME)) + .build()))) + .containsExactly(FOOTER + "2 of its 3 parts stand off where the page sets them"); + } + + @Test + void partsSetOneAfterAnotherStandWhereWordSetsThem() throws Exception { + // Packed at either end, as Word sets them from the left margin and against the right. + assertThat(zoneNotes(DocumentPageZone.footer(30, page -> new RowBuilder().name("Line") + .addParagraph(p -> p.text("Confidential").textStyle(CHROME)) + .addParagraph(p -> p.text("Acme").textStyle(CHROME)) + .flexSpacer() + .addParagraph(p -> p.text("v2.4").textStyle(CHROME)) + .add(page.pageNumber(CHROME)) + .build()))).isEmpty(); + } + + @Test + void aPartOnABaselineOfItsOwnOrOfMoreLinesThanOneIsCounted() throws Exception { + // Word sets a line's parts on one baseline, its tallest part's; the page sets the parts from + // the top, the smaller ones higher. + assertThat(zoneNotes(DocumentPageZone.footer(40, page -> new RowBuilder().name("Line") + .addParagraph(p -> p.text("Confidential").textStyle(CHROME)) + .flexSpacer() + .addParagraph(p -> p.text("Acme").textStyle(DocumentTextStyle.DEFAULT.withSize(18))) + .build()))) + .containsExactly(FOOTER + "1 of its 2 parts stands off where the page sets them"); + assertThat(zoneNotes(DocumentPageZone.footer(40, page -> new RowBuilder().name("Line") + .addParagraph(p -> p.text("Acme").textStyle(DocumentTextStyle.DEFAULT.withSize(18))) + .flexSpacer() + .addParagraph(p -> p.text("v2.4").textStyle(CHROME)) + .add(page.pageNumber(CHROME)) + .build()))) + .as("both smaller parts move onto the tallest one's baseline") + .containsExactly(FOOTER + "2 of its 3 parts stand off where the page sets them"); + assertThat(zoneNotes(DocumentPageZone.header(40, page -> new RowBuilder().name("Line") + .addParagraph(p -> p.text("Acme").textStyle(DocumentTextStyle.DEFAULT.withSize(18))) + .flexSpacer() + .addParagraph(p -> p.text("v2.4").textStyle(CHROME)) + .add(page.pageNumber(CHROME)) + .build()))) + .as("in a header too").containsExactly("a header written as one line of Word's header; 2 of its 3 " + + "parts stand off where the page sets them"); + // Word stands the line at the footer's foot, which a smaller part set lower holds: the + // larger part moves down onto it, and the smaller one onto the larger one's baseline. + assertThat(zoneNotes(DocumentPageZone.footer(60, page -> new RowBuilder().name("Line") + .addParagraph(p -> p.text("Acme").textStyle(DocumentTextStyle.DEFAULT.withSize(18))) + .flexSpacer() + .addParagraph(p -> p.text("v2.4").textStyle(CHROME).margin(new DocumentInsets(30, 0, 0, 0))) + .build()))) + .containsExactly(FOOTER + "2 of its 2 parts stand off where the page sets them"); + // A part the page seats off its baseline is set on Word's. + assertThat(zoneNotes(DocumentPageZone.footer(40, page -> new RowBuilder().name("Line") + .addParagraph(p -> p.text("Confidential").textStyle(DocumentTextStyle.DEFAULT.withSize(18))) + .flexSpacer() + .addParagraph(p -> p.text("Acme").textStyle(DocumentTextStyle.DEFAULT.withSize(18)) + .verticalAlign(com.demcha.compose.document.node.TextVerticalAlign.CENTER)) + .build()))) + .containsExactly(FOOTER + "1 of its 2 parts stands off where the page sets them"); + // The zone's line holds none of what keeps a body paragraph's breaks where the page sets them. + assertThat(zoneNotes(DocumentPageZone.footer(40, page -> text( + "Confidential and proprietary: not for distribution outside the company").build()))) + .containsExactly(FOOTER + OFF); + } + + @Test + void aZoneParagraphsOwnLossesAreNamed() throws Exception { + assertThat(zoneNotes(DocumentPageZone.footer(30, page -> text("Confidential") + .direction(TextDirection.RTL).align(TextAlign.LEFT).build()))) + .singleElement().asString().contains("a paragraph's right-to-left text is written left to right"); + assertThat(zoneNotes(DocumentPageZone.footer(30, page -> text("Confidential").bulletOffset("• ") + .indentStrategy(DocumentTextIndent.FIRST_LINE).build()))) + .as("a prefix Word does not write stands the text off, and its letters are lost") + .containsExactly(FOOTER + OFF + "; a paragraph's bulletOffset letters, \"•\", are not written before " + + "its first line"); + assertThat(zoneNotes(DocumentPageZone.footer(30, page -> text("Hi").autoSize(14).build()))) + .containsExactly(FOOTER + "a paragraph's text is written at 8pt, where the page fits it to 14pt"); + assertThat(zoneNotes(DocumentPageZone.footer(30, page -> text("Confidential") + .bookmark(new DocumentBookmarkOptions("Confidential", 0)).build()))) + .containsExactly(FOOTER + "a paragraph's outline entry is not written"); + } + + @Test + void wherePartsStandPastOneWordSetsAtAnotherWidthIsNotMeasured() throws Exception { + // Word writes no prefix, so the part after it starts where the layout does not tell. + assertThat(zoneNotes(DocumentPageZone.footer(30, page -> new RowBuilder().name("Line") + .addParagraph(p -> p.text("Confidential").textStyle(CHROME).bulletOffset("• ") + .indentStrategy(DocumentTextIndent.FIRST_LINE)) + .addParagraph(p -> p.text("Acme").textStyle(CHROME)) + .flexSpacer() + .add(page.pageNumber(CHROME)) + .build()))) + .containsExactly(FOOTER + "1 of its 3 parts stands off where the page sets them; where 1 of its 3 " + + "parts stands is not measured; a paragraph's bulletOffset letters, \"•\", are not " + + "written before its first line"); + // Nor after a part auto-sized to a size the file does not hold; set lower than Word's + // baseline, the part after it stands off all the same. + assertThat(zoneNotes(DocumentPageZone.footer(40, page -> new RowBuilder().name("Line") + .addParagraph(p -> p.text("Hi").textStyle(CHROME).autoSize(14)) + .addParagraph(p -> p.text("Acme").textStyle(CHROME)) + .addParagraph(p -> p.text("Co").textStyle(CHROME)) + .build()))) + .containsExactly(FOOTER + "2 of its 3 parts stand off where the page sets them; a paragraph's text is " + + "written at 8pt, where the page fits it to 14pt"); + // Against the right margin, the part a prefix stands before ends where Word ends it; the + // part before it, Word sets the prefix's width off. + assertThat(zoneNotes(DocumentPageZone.footer(30, page -> new RowBuilder().name("Line") + .addParagraph(p -> p.text("Confidential").textStyle(CHROME)) + .flexSpacer() + .addParagraph(p -> p.text("v2.4").textStyle(CHROME)) + .addParagraph(p -> p.text("Acme").textStyle(CHROME).bulletOffset(" ") + .indentStrategy(DocumentTextIndent.FIRST_LINE)) + .add(page.pageNumber(CHROME)) + .build()))) + .containsExactly(FOOTER + "where 1 of its 4 parts stands is not measured"); + } + + @Test + void aZoneWhoseNodesThePageNestsOtherwiseIsNotMeasured() throws Exception { + // Written once for every page, the zone is built as for no page in particular: the last, + // as far as it can tell, where the page's first is not, and its nodes are another tree. + AtomicReference captured = new AtomicReference<>(); + try (DocumentSession session = GraphCompose.document().pageSize(300, 400).margin(DocumentInsets.of(36)).create()) { + session.chrome().zone(DocumentPageZone.footer(30, page -> page.isLast() + ? text("End").build() + : new RowBuilder().name("Line").addParagraph(p -> p.text("A").textStyle(CHROME)).build())); + session.pageFlow(page -> page.addParagraph("Body").addPageBreak(pageBreak -> { }) + .addParagraph("More")); + session.export(new DocxSemanticBackend(captured::set)); + } + assertThat(captured.get().bySubject().get("page zone")).extracting(DocxExportReport.Note::detail) + .containsExactly(FOOTER + "whether its text stands where the page sets it is not measured"); + } + + @Test + void aZoneWrittenOnSeveralKindsOfPageIsNamedOnce() throws Exception { + // The first page's header makes a title page, so the footer goes into two of Word's footers. + assertThat(zoneNotes(DocumentPageZone.footer(30, page -> text("Confidential").align(TextAlign.CENTER).build()), + DocumentPageZone.header(30, page -> text("Cover").build()).toBuilder() + .appliesTo(page -> page.isFirst()).build())) + .containsExactly(FOOTER + OFF); + } + + @Test + void withNoLayoutWhereItsTextStandsIsNotMeasured() throws Exception { + AtomicReference context = new AtomicReference<>(); + AtomicReference graph = new AtomicReference<>(); + AtomicReference report = new AtomicReference<>(); + try (DocumentSession session = session(DocumentPageZone.footer(30, page -> text("Confidential").build()))) { + session.export(new SemanticBackend() { + @Override + public String name() { + return "capture"; + } + + @Override + public byte[] export(DocumentGraph documentGraph, SemanticExportContext exportContext) { + graph.set(documentGraph); + context.set(exportContext); + return new byte[0]; + } + }); + new DocxSemanticBackend(report::set).export(graph.get(), new SemanticExportContext( + context.get().canvas(), List.of(), null, context.get().outputOptions())); + } + assertThat(report.get().bySubject().get("page zone")).extracting(DocxExportReport.Note::detail) + .containsExactly(FOOTER + "whether its text stands where the page sets it is not measured"); + } + + private static ParagraphBuilder text(String text) { + return new ParagraphBuilder().name("ZoneLine").text(text).textStyle(CHROME); + } + + private static List zoneNotes(DocumentPageZone... zones) throws Exception { + AtomicReference captured = new AtomicReference<>(); + try (DocumentSession session = session(zones)) { + session.export(new DocxSemanticBackend(captured::set)); + } + assertThat(captured.get()).as("the sink is called once the bytes exist").isNotNull(); + return captured.get().bySubject().getOrDefault("page zone", List.of()).stream() + .map(DocxExportReport.Note::detail).toList(); + } + + private static DocumentSession session(DocumentPageZone... zones) { + DocumentSession session = GraphCompose.document() + .pageSize(300, 400) + .margin(DocumentInsets.of(36)) + .create(); + for (DocumentPageZone zone : zones) { + session.chrome().zone(zone); + } + session.pageFlow(page -> page.addParagraph("Body")); + return session; + } +}