diff --git a/CHANGELOG.md b/CHANGELOG.md index 33ec90e2a..7e6121b77 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,37 @@ follow semantic versioning; release dates are ISO 8601. ### Public API +- **A DOCX export keeps a page break the layout makes by itself after a card where the page + makes it.** + - A block kept together or kept with the next in a table cell — a row's column, a panel's cell — + keeps its lines together (`w:keepLines`) and no longer keeps with the next (`w:keepNext`). + Word reads keep-with-next on the paragraph a cell opens with as keeping the cell's whole row + with what follows its table, and holds no keep across a break inside the row, so in a cell + those keeps did nothing else; a row of columns, which may not split, keeps the block whole. + The separator between two tables in a cell keeps with the next table as before: measured, Word + does not read it as the paragraph the cell opens with. Measured in Word 16 on `ObsidianInvoice` + with its line items repeated 12 times: its info cards, kept together in a row's two cells, went + to page 5 with the footer divider under them, 17 lines below the page's, where the layout sets + them at the foot of page 4. + - A rule the layout moves to a new page in the flow holds the space the layout leaves above it + there in an empty line kept with it, as a paragraph, a list and a picture do: Word and + LibreOffice drop a paragraph's space above at the top of a page they break themselves, and + a rule's is its paragraph's. The same invoice's footer divider stood its 13pt margin high on + page 5 in both. + - A table, a row, a painted row or a panel the layout moves to a new page holds there, with its + own top edge, the gap above it the layout carries onto that page where the gap does not fit at + the foot of the page above. It left the gap on the page above: `MeteredInvoice` with its line + items repeated 9 times opens page 4 with its closing row 12.4pt below the margin, the gap, and + Word set the page 13.0pt high and LibreOffice 12.8pt. One the layout runs on past the page it + opens has no place of its own there to measure, and holds its own top edge alone, as before. + - After: `ObsidianInvoice` ×12 sets every line on its page in Word and LibreOffice 24.2, page 5 + within 0.1pt; `MeteredInvoice` ×9's page 4 within 0.7pt in both. Of 35 lengths of 7 invoice + templates whose layout opens a page with a block of their body, those two move, and none + other. + - In the corpus, 15 documents lose keep-with-next on paragraphs in table cells, and nothing else; + no page in it opens with a rule or a gap the layout carries there. Word and LibreOffice 24.2 + set every one of their lines where they did. + - **A DOCX export writes the margins of a page that starts at a panel's cut as a Word section there.** - A page that `session.pageMargins(...)` sets against other top and bottom margins than Word @@ -39,11 +70,9 @@ follow semantic versioning; release dates are ISO 8601. Word and LibreOffice 24.2, as it did. Repeated 12 times, its page 5 starts between its info cards and its footer divider. With page 1's margins in force on pages 2 to 4, page 5 opened a Word section of its own, which fixed that break, and Word held the cards on page 4; page 5's - margins are now page 2's, so the editors place that break themselves: Word sets the cards on - page 5 with the divider, because `keepNext` on - the paragraphs inside the cards' cell keeps their table with the paragraph after it, and both - editors drop the divider's 13pt of space above it at a page they break themselves. The same - invoice with one set of margins on every page is set the same way in both editors. + margins are now page 2's, so the editors place that break themselves, as they do the same + invoice with one set of margins on every page — where the page places it, since the entry + above. - Where a page the panel runs onto is not cut and a later one is, LibreOffice 24.2 sets the part after that cut with the margins of the section before: it reads no section's margins after a table it broke over a page itself. Word reads them. diff --git a/docs/architecture/backend-capability-matrix.md b/docs/architecture/backend-capability-matrix.md index 657a44ad4..1c1c906ea 100644 --- a/docs/architecture/backend-capability-matrix.md +++ b/docs/architecture/backend-capability-matrix.md @@ -122,7 +122,7 @@ honour an option ignores it (documented contract). | 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 | -| Keep a block on one page (`keepTogether()`, `keepWithNext()`) | ✅ resolved by `LayoutCompiler` before any backend runs | ✅ same — the slides are the laid-out pages | ✅ `DocxSemanticBackend.keepOnOnePage` — Word re-paginates, so a block the layout placed on one page is told to stay there: `w:keepLines` on each of its paragraphs and `w:keepNext` on every one but the last (on the last too for `keepWithNext`), a table inside it chained row by row. A layer stack or a shape container in the flow is kept so too, as the layout moves it to a new page whole, a band of layers included; the first block of a band the layout moves to a new page — a paragraph, a picture, a list, a title and its dates set as one line or a spacer, a backdrop drawn before it or not — holds the space above it there, as one in the flow does: in a line kept with it, or in a spacer's own line; a table, a row or a panel opening it holds the band's top edge so with its own, the gap before the band left at the foot of the page above. A list or such a line the layout moves to a new page in the flow holds its space above there as a paragraph does. A block that ran over a page break in the layout is taller than a page and is left to flow, as the layout left it. A body table of one row kept with what follows, its cells holding paragraphs alone, is written with a row that may break (`letTheOneRowTablesKeptWithTheNextBreak`): LibreOffice reads a one-row table whose row may not break as one that may not split, and keeps such a table with nothing. A panel in the body the layout breaks over pages inside a table it holds is a table a page, cut at the row each page starts with (`cutThePanelsAtTheirPages`): Word repeats no header row of a table nested in a cell, so each part after a cut opens with copies of the table's header rows, where it has them, and the page breaks between the parts are fixed; where the page after a cut has other top and bottom margins, and the page above has room for it, the paragraph between the parts ends a Word section with them (per-page margins, below) | +| Keep a block on one page (`keepTogether()`, `keepWithNext()`) | ✅ resolved by `LayoutCompiler` before any backend runs | ✅ same — the slides are the laid-out pages | ✅ `DocxSemanticBackend.keepOnOnePage` — Word re-paginates, so a block the layout placed on one page is told to stay there: `w:keepLines` on each of its paragraphs and `w:keepNext` on every one but the last (on the last too for `keepWithNext`), a table inside it chained row by row; in a table cell, `w:keepLines` alone, as Word reads `w:keepNext` on the paragraph a cell opens with as keeping the row with what follows its table. A layer stack or a shape container in the flow is kept so too, as the layout moves it to a new page whole, a band of layers included; the first block of a band the layout moves to a new page — a paragraph, a picture, a list, a title and its dates set as one line or a spacer, a backdrop drawn before it or not — holds the space above it there, as one in the flow does: in a line kept with it, or in a spacer's own line; a table, a row or a panel opening it holds the band's top edge so with its own, the gap before the band left at the foot of the page above. A list, such a line or a rule the layout moves to a new page in the flow holds its space above there as a paragraph does, and a table, a row or a panel on that one page holds the gap the layout carries there with its own top edge. A block that ran over a page break in the layout is taller than a page and is left to flow, as the layout left it. A body table of one row kept with what follows, its cells holding paragraphs alone, is written with a row that may break (`letTheOneRowTablesKeptWithTheNextBreak`): LibreOffice reads a one-row table whose row may not break as one that may not split, and keeps such a table with nothing. A panel in the body the layout breaks over pages inside a table it holds is a table a page, cut at the row each page starts with (`cutThePanelsAtTheirPages`): Word repeats no header row of a table nested in a cell, so each part after a cut opens with copies of the table's header rows, where it has them, and the page breaks between the parts are fixed; where the page after a cut has other top and bottom margins, and the page above has room for it, the paragraph between the parts ends a Word section with them (per-page margins, below) | | Layer stack — layers drawn over one another (`addLayerStack`) | ✅ each layer's fragments at the place the layout gave it | ✅ same | ⚠️ `DocxSemanticBackend` — Word has no layers, so a stack's children are written one after the other, without their positions. The exception is a stack whose layers are side-by-side columns (`DocxLayerColumns`): every layer a plain container at the stack's top-left corner, the bands their padding leaves either the same or apart. That is written as one table row, a cell per band, the way a two-column CV lays its columns out as layers to draw the name first. Layers sharing a band follow one another in its cell. A spacer the layout placed level with content of another layer of the same band only keeps that content's place, and is not written. The space above a later layer's first block is the gap the page shows below the content before it, to the block's content: what the block holds above that content past the gap — its margin, its padding, a contained picture's room — comes out of its own edge (`DocxLayerColumns.resume`) where it is a paragraph, a picture, a list or a table in its layer's own flow with its edge above at zero or more, and a list keeps its own edges after the gap, as a table does. Each layer is held to its box across, past the stack's edge where the page sets it past it, by an indent below zero; in a table cell no further left than the indents round it give, the rest named. The one layer of a stack of one layer is held the same way, its offset across kept and its measure with it; in a table cell, composed in a table's cell with no place of its own, and for an offset down or up, which moves it without making room for it, it is written where the stack starts and named — not where a band or a column's layer sets it at the page's distance below what is above it, which holds the offset. A shape container written as a panel in a table cell keeps its padding round its outline, as the page does — the table's indent and the space above and below it; where its table ends its cell, Word sets the cell's content at its middle or foot without the space below, which a centred cell takes off the space above, the rest named — sets what its cell holds at the top, middle or foot as its first written layer is set, holds a paragraph across to its box, and names a written layer after the first (written under the ones before it), an offset down or up, a box past the shape's side, and a layer set across by a box the layout does not give (`layer offset`). A layer whose content the page starts above where those before it end — a caption over its photo, a label in a card's corner, not a block giving back its edge whose padding or contained picture's room alone reaches there — is written under them, in a column's cell as in a band, and the report names it; a stack composed in a table cell, or exported with no layout, has no place of its own, and one writing more than one of its layers is named with them not measured. What the page draws inside another layer's fill comes after that fill. Drawings stack as the page paints them, by their z-index, each given its place (`wp:anchor/@relativeHeight`) from where the page paints its fragment, whatever order the layers are written in — among the drawings behind the text, and among those in front of it, as Word draws every one behind under every one in front. Measured in LibreOffice: `CharcoalGold`, `SidebarPortrait` and `SlateOrange` fit on one page, as on the page; `NavySidebar` runs one line onto a second page. A stack or shape container the page gives no room — its margins taking back its whole height, as `LumaStudioInvoice`'s sidebar over the page's top margin — is laid over the flow (`laidOverTheFlow`): its drawings where the page draws them, each paragraph in a text box in front of the text where the page sets it, nothing in the flow. Not in a table cell or a panel, and not when it holds anything but drawing and plain paragraphs — a link, an anchor, a picture, a list or a table keeps it in the flow as above. A canvas is written as its contents — what it writes one block after another, its drawings where it places them — and holds its height: the room under what it writes is the space below it, and one that only draws holds its whole box where nothing round it — a band before its layer's first block, drawings held whole, an overlay it is a layer of — measures that room already. The report names the places and the width it loses, as it does a column's fixed width narrower than its band, and what it writes running past its height, a drawing in what it writes that takes no room in Word, or a height not measured | ## Output surface and lifecycle diff --git a/docs/recipes/docx-export.md b/docs/recipes/docx-export.md index ffccc558a..8a1d4cc0f 100644 --- a/docs/recipes/docx-export.md +++ b/docs/recipes/docx-export.md @@ -69,13 +69,13 @@ creation date is real metadata. |---|---| | Paragraphs | Word paragraphs with alignment, font, size, colour (a translucent one with its transparency, as Word's text fill — see "Translucent colours"), 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 character the page draws nothing for — a control such as a tab or a bell, a soft hyphen, a zero-width space, one of private use — is not written either, where the file held a question mark for most controls, the direction marks and joiners kept; a margin below zero on a paragraph, a list or a block round them sets its text out past that side in the flow as far as the page does — in a table cell, a panel's included, as far as the cell's text and no further, and the report names what is held back; a row's first child the page sets out past the row's left edge starts at it, named; 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. A session reads markdown unless told not to (`markdown(false)`): it sets a paragraph of plain text's emphasis marks as the style of the text they mark, a heading line bold (the first three levels larger), and drops its marks; the export writes the text as the page sets it — read line by line through the page's own parser, one run a piece in the face, family, colour, tracking and size the page sets it in, `**Java**` a bold run reading `Java`, a linked paragraph's pieces in one link, Word's outline listing a heading by the text written — wherever it writes a paragraph, a page zone's and a badge's included (a badge's initials counted as the page sets them, and written in the flow where they stand in two faces or as a heading, as initials in two runs' faces are). The page's laid-out lines decide it: the pieces are written where those lines hold their letters in their faces, families, colours and tracking, at their sizes — an auto-sized paragraph's read at the size the page fits it to, a heading at its multiple of it; a session that reads no markdown has its marks written as they stand, and text the parser changes nothing of, an underscore inside a word, is written as it stands too. A paragraph composed in a table cell takes only lines that set its pieces so. The page sets a markdown heading in a line as tall as the paragraph's own and draws its letters past it; written in that exact line, Word cuts their tops on screen, and the report names a heading written taller than its line. The faces are the page's: where the session reads markdown its parser sets every piece in a face of its own, the paragraph's left aside, so a bold paragraph's `Senior_Engineer` is written regular, as the page sets it. A paragraph whose lines are not read — with no layout, composed in a table cell whose text, as authored or as the page reads it, no line of its table carries, or a page zone's the layout shows none of — or that the page sets in other letters than its text, as Arabic, which the page shapes before it reads the marks, or that the parser reads into nothing — a lone `*`, an empty list item; `***`, a rule; a line set four spaces in, a block of code — which the page sets as nothing, is written as authored, marks and all, and the report names it, saying where the lines are not read that whether the page reads its marks is not measured, where the page's parser drops one. An auto-sized paragraph (`autoSize`) is written at the size the page fits its text to, read off the layout's lines, on every path that writes a paragraph: a run with a style of its own keeps it, as on the page, and a prefix is measured at the fitted size. Where the lines do not tell it — none are read, they are in sizes that do not say which is the paragraph's, or the paragraph is added at more than one place, which the page fits at each apart — the text is written at its style's size, and the report says the fitted size is not measured, on the paragraph or, in a header or footer, on the zone's note. LibreOffice breaks a badge's initials wider than the square inscribed in its disc, at any size, and hides what wraps; an auto-sized badge, which fills its disc, meets this too. 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 stack of one layer is in the flow: the paragraph opening one does the same, with the stack's own edges, though not the layer's offset in the stack, up or down, which is named and not written. So does the first paragraph of a band of layers the layout moves to a new page, in the flow, in a stack of one layer or in a section, a backdrop drawn before it or not: the band's own edges, its room above that paragraph and the edges of the containers opening with it (measured: a band with a 14pt margin, one with a backdrop laid first, one nested in a stack of one layer with that margin, and one in a section with a 10pt margin each stood that much high in Word and LibreOffice; held, each stands where the page sets it, within a point, the backdrop where the page draws it). A title and its dates an overlay sets as one line do the same, the room above the line inside the overlay held with its edges (measured: such a pair in a stack with a 14pt margin, in the flow or opening a band, stood 14pt high in Word and LibreOffice; held, within 0.1pt of a paragraph moved so); one whose text the page sets above its overlay's top is left as it was. A paragraph in a table cell or any other overlay is left to its container, and a list's items to their list (see Lists) | | 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. An item the page reads as markdown is written as the page sets it, as a paragraph is. A list the layout moves to a new page — in the flow, a stack of one layer's included, or first in a band of layers opening its page — keeps the space the layout leaves above its first item there, its margin, its padding and the edges of the containers opening with it, as an empty line that tall before it, kept with it, as a body paragraph does; a wrapped first item takes the gap between its lines out of that line (measured: a list with a 14pt margin stood 14pt high in Word and LibreOffice, one padded 10pt or opening a section padded 10pt 10pt, one opening a stack of one layer or a band with a 14pt margin 14pt; held, each within 0.1pt of a paragraph moved so). 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). Padding thinner than its share gives what it has; Word sets each cell at its content and, on each side, its padding or its share where that is more, and the row at its tallest cell, so a row stands taller where a cell of text then needs more than the page's height — by that much, which the report names, added up for the table (`cell rule`; measured in Word and LibreOffice on Windows against the same table unruled, to a tenth of a point: four rows with no padding, 3pt rules 15pt and 1pt rules 5pt; a two-line cell with no padding beside a padded one-line cell, each counted on its own). Cells built from a node, cells spanning rows and empty cells in rows held at the page's height are not counted; where the layout does not tell a row's height — a table composed in a cell, or no layout — the report names the most it can be. Each rule comes off as wide as Word draws it, in eighths of a point: a 0.7pt hairline is drawn 0.75pt wide (measured: taken off at 0.7, `EditorialProposal`'s tables and all under them stood a step of Word's grid lower). A cell's rule is written from two to ninety-six eighths of a point, the range of a line border's width. A rule is counted as both editors count it, two and a half twips an eighth rounded down (measured: one of 12.5 twips takes 12, one of 17.5 takes 17), and a rule between two rows is shared in whole twips, the row above it taking half rounded down and the row under it the rest; a cell's top and bottom margins are rounded to the twip together. Tables of one, two, three and six rows ruled at five, six, seven and nine eighths then take the page's height to within a step of Word's grid and to the twip in LibreOffice (measured). 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 row between two others is written less the rest of its own rule above it and half that of the cell under it, one rule where the two are ruled alike, and any row less the most one of its cells takes, its margins and those rules together (measured: held less its own rule alone, a row ruled at 0.5pt over one ruled at 1.5pt stood half a point taller in Word, and all under it half a point lower). LibreOffice makes room at the edge between two rows for the heavier of their rules, where Word makes it for the lower row's: under a row ruled heavier than it, a row and all under it stand the difference lower there (measured: under a 1.5pt row, 0.5pt rows stood 1pt lower in LibreOffice on Windows and LibreOffice 24.2, and where the page sets them in Word). 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 text cell whose lines are at least as tall as its face's own is written at a least height, as a paragraph's are (see "Line height"): Word and LibreOffice stand a least line's baseline its face's descent above its foot, which is where the page sets it, so its row keeps the cell's padding as its margins and its lines grow with its text. A row of exact text cells is moved by its margins to stand its text where the page sets it: the page sets a cell's line its face's ascent below the line's top, Word an exact line's baseline four fifths of the way down it, so every cell's top margin is made smaller and its bottom one as much larger — or the other way — by the least any of its cells calls for, no further than the margin holds, and each cell's text moves with its room, set at the top, the middle or the bottom, while the row keeps its height (measured on exact lines: a line of 8pt Poppins stood 0.58pt low in Word and 0.55pt in LibreOffice, of Lato 0.24 and 0.25pt high; moved, within 0.04pt and 0.09pt). A least cell calls for no more than its rounding, so in a row with one the margins move by as little, and an exact cell beside it is left the rest of its call, for its position and its lines' heights below. Not a row holding a composed cell, whose paragraphs their own writers seat where they can, nor a row the layout did not measure, nor one in a vertical merge or whose cells call for opposite ways; a least call under a tenth of a point is left. What the margins leave of a cell's call is moved by its text's position where that is half a point or more, as a paragraph's is: LibreOffice moves raised text further than it is raised, by up to half as much again, which from half a point up is less than what is left. Less, from a tenth of a point, is moved by the height of the cell's lines: each written shorter and the space after it taller by as much, or the other way as far as that space holds, which keeps the cell's content as tall and each line's top where it was, and moves the text four fifths of the difference in both editors — where every paragraph of the cell is one line, in a face whose letters the export reads (not a standard face it does not embed), and its letters stay clear of the line's top and foot, where Word cuts them on screen (measured: `CobaltRota`'s staff names, beside the day cells its chips are composed in, stood 0.25pt low in Word, 0.2pt in LibreOffice on Windows and 0.19pt in LibreOffice 24.2; so, within 0.08pt in all three, every row its height; the line alone written shorter shortened a row whose tallest content it was by as much in LibreOffice 24.2, which holds a row to its cells' content). LibreOffice sets a vertically centred cell's content as if its first paragraph had no space above it, so a cell padded more above than its row's smallest stands its text up to half that difference higher there (measured: 3pt above it stood the line 1.5pt high). 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 gives its text a point more than the page gives it, so the editor's font substitute cannot wrap its widest cell: out of its text cells' margins, on the side their text does not lean on — the right where it is set left, the left where it is set right, half from each where it is centred — so the column stays as wide as the page sets it and its rules stand where the page draws them (measured: widened instead, `ClassicInvoice`'s line items stood every rule right of the description column 0.98 to 1.05pt right of the page's in Word and 0.96 to 1.06pt in LibreOffice; held in the margins, within 0.12pt in Word and with the table's other rules in LibreOffice, every line breaking where it did in both). A cell spanning more than one such column shares its margin among them. A composed cell keeps its margins — a paragraph in it may run past its text into them, which Word would cut off at the cell's edge — and what a column's cells do not hold — beside a composed cell, or where a cell's padding on the side it gives from, less the inner half of its rule as Word draws it, is thinner than the point (each side thinner than half of it, centred), as a line an editor's face sets wider would otherwise run onto the rule — widens it, its right end and what stands right of it that much further right, named (`right end`; `OrangeOps`'s aside headings, their accent rules 1pt longer in Word). 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`) — but the row of a one-row table of paragraphs kept with what follows (see Sections / containers) — `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 in the flow (body paragraphs, spacers and pictures: see their rows). A table, a row or a panel opening a band of layers the layout moves to a new page holds the band's own top edge there with its own — the band's margin and the room it leaves above the block — while the gap before the band stays at the foot of the page above (measured: each, opening a band with a 14pt margin, stood 14pt high in Word and LibreOffice, the margin left on the page above; held, within 0.1pt of the same block moved to a new page in the flow). 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 | +| 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). Padding thinner than its share gives what it has; Word sets each cell at its content and, on each side, its padding or its share where that is more, and the row at its tallest cell, so a row stands taller where a cell of text then needs more than the page's height — by that much, which the report names, added up for the table (`cell rule`; measured in Word and LibreOffice on Windows against the same table unruled, to a tenth of a point: four rows with no padding, 3pt rules 15pt and 1pt rules 5pt; a two-line cell with no padding beside a padded one-line cell, each counted on its own). Cells built from a node, cells spanning rows and empty cells in rows held at the page's height are not counted; where the layout does not tell a row's height — a table composed in a cell, or no layout — the report names the most it can be. Each rule comes off as wide as Word draws it, in eighths of a point: a 0.7pt hairline is drawn 0.75pt wide (measured: taken off at 0.7, `EditorialProposal`'s tables and all under them stood a step of Word's grid lower). A cell's rule is written from two to ninety-six eighths of a point, the range of a line border's width. A rule is counted as both editors count it, two and a half twips an eighth rounded down (measured: one of 12.5 twips takes 12, one of 17.5 takes 17), and a rule between two rows is shared in whole twips, the row above it taking half rounded down and the row under it the rest; a cell's top and bottom margins are rounded to the twip together. Tables of one, two, three and six rows ruled at five, six, seven and nine eighths then take the page's height to within a step of Word's grid and to the twip in LibreOffice (measured). 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 row between two others is written less the rest of its own rule above it and half that of the cell under it, one rule where the two are ruled alike, and any row less the most one of its cells takes, its margins and those rules together (measured: held less its own rule alone, a row ruled at 0.5pt over one ruled at 1.5pt stood half a point taller in Word, and all under it half a point lower). LibreOffice makes room at the edge between two rows for the heavier of their rules, where Word makes it for the lower row's: under a row ruled heavier than it, a row and all under it stand the difference lower there (measured: under a 1.5pt row, 0.5pt rows stood 1pt lower in LibreOffice on Windows and LibreOffice 24.2, and where the page sets them in Word). 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 text cell whose lines are at least as tall as its face's own is written at a least height, as a paragraph's are (see "Line height"): Word and LibreOffice stand a least line's baseline its face's descent above its foot, which is where the page sets it, so its row keeps the cell's padding as its margins and its lines grow with its text. A row of exact text cells is moved by its margins to stand its text where the page sets it: the page sets a cell's line its face's ascent below the line's top, Word an exact line's baseline four fifths of the way down it, so every cell's top margin is made smaller and its bottom one as much larger — or the other way — by the least any of its cells calls for, no further than the margin holds, and each cell's text moves with its room, set at the top, the middle or the bottom, while the row keeps its height (measured on exact lines: a line of 8pt Poppins stood 0.58pt low in Word and 0.55pt in LibreOffice, of Lato 0.24 and 0.25pt high; moved, within 0.04pt and 0.09pt). A least cell calls for no more than its rounding, so in a row with one the margins move by as little, and an exact cell beside it is left the rest of its call, for its position and its lines' heights below. Not a row holding a composed cell, whose paragraphs their own writers seat where they can, nor a row the layout did not measure, nor one in a vertical merge or whose cells call for opposite ways; a least call under a tenth of a point is left. What the margins leave of a cell's call is moved by its text's position where that is half a point or more, as a paragraph's is: LibreOffice moves raised text further than it is raised, by up to half as much again, which from half a point up is less than what is left. Less, from a tenth of a point, is moved by the height of the cell's lines: each written shorter and the space after it taller by as much, or the other way as far as that space holds, which keeps the cell's content as tall and each line's top where it was, and moves the text four fifths of the difference in both editors — where every paragraph of the cell is one line, in a face whose letters the export reads (not a standard face it does not embed), and its letters stay clear of the line's top and foot, where Word cuts them on screen (measured: `CobaltRota`'s staff names, beside the day cells its chips are composed in, stood 0.25pt low in Word, 0.2pt in LibreOffice on Windows and 0.19pt in LibreOffice 24.2; so, within 0.08pt in all three, every row its height; the line alone written shorter shortened a row whose tallest content it was by as much in LibreOffice 24.2, which holds a row to its cells' content). LibreOffice sets a vertically centred cell's content as if its first paragraph had no space above it, so a cell padded more above than its row's smallest stands its text up to half that difference higher there (measured: 3pt above it stood the line 1.5pt high). 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 gives its text a point more than the page gives it, so the editor's font substitute cannot wrap its widest cell: out of its text cells' margins, on the side their text does not lean on — the right where it is set left, the left where it is set right, half from each where it is centred — so the column stays as wide as the page sets it and its rules stand where the page draws them (measured: widened instead, `ClassicInvoice`'s line items stood every rule right of the description column 0.98 to 1.05pt right of the page's in Word and 0.96 to 1.06pt in LibreOffice; held in the margins, within 0.12pt in Word and with the table's other rules in LibreOffice, every line breaking where it did in both). A cell spanning more than one such column shares its margin among them. A composed cell keeps its margins — a paragraph in it may run past its text into them, which Word would cut off at the cell's edge — and what a column's cells do not hold — beside a composed cell, or where a cell's padding on the side it gives from, less the inner half of its rule as Word draws it, is thinner than the point (each side thinner than half of it, centred), as a line an editor's face sets wider would otherwise run onto the rule — widens it, its right end and what stands right of it that much further right, named (`right end`; `OrangeOps`'s aside headings, their accent rules 1pt longer in Word). 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`) — but the row of a one-row table of paragraphs kept with what follows (see Sections / containers) — `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 held there with that edge, as above a painted row or a panel the layout moves to a new page (measured: `MeteredInvoice`'s closing row, its 12.4pt gap carried onto its page, stood 13.0pt high in Word and 12.8pt in LibreOffice 24.2; held, within 0.7pt). One the layout runs on past the page it opens has no place of its own there to measure, and holds its own edge alone. A table, a row or a panel opening a band of layers the layout moves to a new page holds the band's own top edge there with its own — the band's margin and the room it leaves above the block — while the gap before the band stays at the foot of the page above (measured: each, opening a band with a 14pt margin, stood 14pt high in Word and LibreOffice, the margin left on the page above; held, within 0.1pt of the same block moved to a new page in the flow). 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. Its fixed columns are written where every column is fixed; where one is `auto`, the editor divides the width among them (measured: Word and LibreOffice on Windows alike, half the cell each for two), and the report names it (`TableNode`) | | Inline chips (`inlineCode(...)`, `inlineChip(...)`, `highlight(...)`) | The chip's fill becomes the run's own `w:shd`, in a paragraph and in a list item alike. Its shape does not travel — see "What a chip keeps and loses" below | | Images | Embedded pictures at the node's declared size. One contained in its box (`fitToBounds`, `CONTAIN`) is embedded at its fitted size, half the room it leaves above and below written as the space round its paragraph and half at its side as its indent; in a band the room below is its paragraph's own, as the band measures what it owes below from the box. In the flow, in a row's cell and held in by an alignment it stands in the box's middle, as the page draws it. In the flow, the margin and padding above and below are the space round the picture's paragraph; on the left they are not written, and the report names them, as it does a barcode's and a page reference's sides. A picture in the flow, a stack of one layer's included, or first in a band of layers there, that the layout moves to a new page keeps the space the layout leaves above it there — its margin, its padding, the room above it in its box, 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, as a body paragraph does. A picture drawn beside its text is fitted to its box with its padding in it, which the report names too | | Links and anchors | A `linkTarget` becomes a `w:hyperlink` — a relationship for an address, `w:anchor` for one of the document's own anchors — and a run's own link wins over the paragraph's — in a list item as much as in a paragraph. An `anchor(...)` becomes a bookmark wrapping that paragraph's text, named as Word requires; on a section, container, table or image it wraps everything the block wrote, from the start of its first paragraph to the end of its last, so a link to a block lands on its first line. A block that writes no paragraph — a section or a container of drawings alone, whose drawings stand in the paragraph beside them — has no bookmark, and the report names its anchor: a link to it points at none (measured: the page's link went to the section's place, and Word's and LibreOffice's PDFs carried no link at all), and a page reference to it is written as the number it reads. Two anchors that clean to one name, or to a name a suffix gave another, stay two bookmarks; one anchor two nodes declare is one bookmark, the last the file writes one for — the node the page sends a link to and reads a page reference's page from, where that node writes a paragraph to mark — and the report names the anchor, the nodes counted off the document, two cells of one table two of them, and a node of a kind of the caller's own counted where the layout registers it. An anchor in a table's header row the page repeats is drawn again on each page it repeats on, and the page sends a link to the last of them; the file holds the row once, where the table starts, which a link goes to and a page reference reads once Word updates it (measured: the bookmark on page 1, a reference written as 5 reading 1), and the report names it. A `bookmark(...)` outline level becomes Word's own `HeadingN` style, which is what puts the paragraph in the Navigation Pane, the outline view and a generated table of contents. The style states the outline level and nothing else, so the paragraph keeps its own formatting. The role comes from what the document declared, never from how big the text is | | Rows | A one-row table spanning the content width — or only its columns, where fixed columns leave part of the row empty — so editors keep the side-by-side layout. The row's slots become the column grid when they are weights, an even split or fixed columns; fixed columns that add up to less than the row leave the rest of it empty, the last one at its own width and the table no wider than its columns, so its text wraps where the page wraps it; the gap and the row's padding ride in the neighbouring column and come back out as that cell's margin; a cell holds whatever its child is, written as it is anywhere else. The row's `verticalAlign` is every cell's `w:vAlign`, so a child shorter than the row sits at its middle or bottom as on the page — a table of contents' leader on its entry's baseline. A row composed in a table cell (`DocumentTableCell.node(...)`), which the layout places nowhere, that the page divides by what its children measure — an arrangement other than `START`, a spacer that grows, an auto column — takes its columns from where its paragraphs' lines start, the table having laid them out, a spacer where the page spreads the room between them; one holding a child those lines do not place — a picture, a shape, or a spacer in a row of stated columns, which gives it a slot of its own — or written inside a panel or another table in its cell has its columns sized by Word to their text, and the report names it. The row is kept whole across a page break, as the layout keeps it. A row is held at least as tall as the page makes it inside a painted panel, and anywhere its tallest child is a drawing Word holds nothing of in its cell — a badge beside a heading. A section or other container in any cell — a row's, a table's, a panel's — that pulls its first line up with a negative top edge writes that one-line paragraph as much shorter, its text seated where the page sets it — no more than the room above its letters, as Word draws an exact line's text only inside the line. A row that paints its box — `fillColor`, `stroke`, `borders` — is a panel holding its columns (see "What a panel keeps and loses" below): a table of one cell carrying the fill and borders, its margins the row's padding as a panel's are, and in it the columns as a table of their own, without the padding; a corner radius squares, and is named (`corner radius`), and what of its borders above and below Word draws past its box is taken, or named, as a panel's is. A row composed in a table cell, in a page zone's line, in a band of overlapping layers or where a stack's column measures the space round it to its text, with a padding below zero or a column hanging into it, or with a margin below zero above or below it or at a side in a cell, is written as its columns alone, its paint in the report (`row paint`); in the body a row bleeding past the margin is its panel | -| Sections / containers | Children written in order. A timeline with its markers on the rail (`markerOnRail()`) lays each entry's body out in the header row's content column, below the row; the body is written in the flow, indented to that column where the page puts it. A container with a fill, per-side borders or a uniform stroke is a one-cell table carrying them, its padding as the cell's margins, so a card keeps its panel — see "What a panel keeps and loses" below. A `keepTogether()` or `keepWithNext()` block the layout placed on one page stays on one page in Word too (`w:keepLines` + `w:keepNext`, and a row that may not split for a panel). A table of one row in the body kept with what follows — a row of columns — whose cells hold paragraphs alone is written with a row that may break: LibreOffice reads a one-row table whose row may not break as a table that may not split, and keeps such a table with nothing (measured: `EditorialProposal`'s page-two masthead stood at the foot of page one in LibreOffice, and all of page two 45 to 47pt high; freed, it opens page two in LibreOffice, Word set it there either way, and moved down to straddle the foot of page one it went to page two whole in both). A row holding a table keeps `w:cantSplit`: the keep chains a cell's own paragraphs, not the rows of a table in it. A box with no paint is only its contents, so a `fixedWidth` narrower than the column is not written: its paragraphs and lists run the column's width, as a panel's in a table cell do, and the report names it. Under an alignment wrapper, or as a layer of a band, the box is held in to where the page placed it. A painted section's bleed is not written: its fill and borders stop at its box, and where the page bleeds it — in the flow it lays out page by page, the body and the panels in it — the report names it. A line drawn as a shape holds no keep: its drawing is anchored in a paragraph near it, a page can end between it and the next block, and in that same flow the report names the keep it loses. A layer stack or a shape container in the flow is kept on its page as a block kept together is (`w:keepLines` on each paragraph, `w:keepNext` on all but the last), since the layout moves it to a new page whole: told nothing, Word set the first lines of a stack of one layer and of a shape container the page moved down at the foot of the page above, and the first layer of a band of two, in Word and LibreOffice alike. In a table's or a panel's cell they are the row's, which keeps or breaks on its own terms | +| Sections / containers | Children written in order. A timeline with its markers on the rail (`markerOnRail()`) lays each entry's body out in the header row's content column, below the row; the body is written in the flow, indented to that column where the page puts it. A container with a fill, per-side borders or a uniform stroke is a one-cell table carrying them, its padding as the cell's margins, so a card keeps its panel — see "What a panel keeps and loses" below. A `keepTogether()` or `keepWithNext()` block the layout placed on one page stays on one page in Word too (`w:keepLines` + `w:keepNext`, and a row that may not split for a panel). In a table cell — a row's column, a panel's cell — such a block keeps its lines together and nothing with the next: Word reads keep-with-next on the paragraph a cell opens with as keeping the whole row with what follows its table, and holds no keep across a break inside the row, so there those keeps did nothing else; a row of columns, which may not split, keeps the block whole (measured: `ObsidianInvoice`'s info cards, kept together in a row's two cells, went with the footer divider under them to the next page in Word, 17 lines below the page's; without keep-with-next in the cards, they stood on their page). The paragraph between two tables in a cell still keeps with the next table: Word does not read it as the paragraph the cell opens with, even after the table the cell opens with (measured: a row at the foot of a page stayed there either way). A table of one row in the body kept with what follows — a row of columns — whose cells hold paragraphs alone is written with a row that may break: LibreOffice reads a one-row table whose row may not break as a table that may not split, and keeps such a table with nothing (measured: `EditorialProposal`'s page-two masthead stood at the foot of page one in LibreOffice, and all of page two 45 to 47pt high; freed, it opens page two in LibreOffice, Word set it there either way, and moved down to straddle the foot of page one it went to page two whole in both). A row holding a table keeps `w:cantSplit`: the keep chains a cell's own paragraphs, not the rows of a table in it. A box with no paint is only its contents, so a `fixedWidth` narrower than the column is not written: its paragraphs and lists run the column's width, as a panel's in a table cell do, and the report names it. Under an alignment wrapper, or as a layer of a band, the box is held in to where the page placed it. A painted section's bleed is not written: its fill and borders stop at its box, and where the page bleeds it — in the flow it lays out page by page, the body and the panels in it — the report names it. A line drawn as a shape holds no keep: its drawing is anchored in a paragraph near it, a page can end between it and the next block, and in that same flow the report names the keep it loses. A layer stack or a shape container in the flow is kept on its page as a block kept together is (`w:keepLines` on each paragraph, `w:keepNext` on all but the last), since the layout moves it to a new page whole: told nothing, Word set the first lines of a stack of one layer and of a shape container the page moved down at the foot of the page above, and the first layer of a band of two, in Word and LibreOffice alike. In a table's or a panel's cell they are the row's, which keeps or breaks on its own terms | | Spacers | An empty paragraph a tenth of a point tall, which Word keeps; the rest of the spacer's height is the space above the next block, or below this paragraph when a table follows. A spacer shorter than that tenth — a width anchor of no height, as `Panel`'s and `PanelLetter`'s cards open with — has its line reach past it by the rest, which the space below takes, as it takes a line hanging below a block, and what it cannot take is named (`space above`): taken nowhere, the line stood every card a tenth of a point taller in Word. A spacer in the body the layout moves to a new page with the gap before it, because the gap did not fit at the foot of the page above, holds the space the layout leaves above it there — that gap, and the edges of any containers opening with it — in its line, which Word keeps at the top of a page where it drops the space above. So does a spacer opening a stack of one layer, or a band of layers, which the layout moves to a new page whole: the space the layout leaves above it there is held in its line, less, in a stack of one layer, its layer's offset, which is named. It is kept with what follows it in the stack, which Word would otherwise set at the new page's top with the spacer left at the foot of the page above. A spacer's own margin and padding are not written, and the report names them — except below the lowest block of a band, or of a layer another resumes after in its column, where the space is measured from the page, the block's own margin and padding included | | Page breaks | Explicit Word page breaks | @@ -213,10 +213,9 @@ four in LibreOffice; with the section at the cut, every line stands on the page on, lower by the cut's top border only. `ObsidianInvoice` is written so from page 2 on, its larger foot there. With its line items repeated 3 to 11 times every line stands on its page in both editors. Repeated 12 times, page 5 starts between its info cards and its footer divider, a page -break the editors place themselves: Word sets the cards on page 5 with the divider, `keepNext` on -the paragraphs inside the cards' cell keeping their table with the paragraph after it, and both -editors drop the divider's 13pt of space above it at a page they break themselves — as they do -with one set of margins on every page. Where a page a panel runs onto is not cut and a later one +break the editors place themselves, where the page places it: nothing in the cards keeps them with +the divider, and the divider holds its 13pt of space above it in a line of its own (see "What maps +1:1" and "What is skipped"). Where a page a panel runs onto is not cut and a later one is, LibreOffice 24.2 sets the part after that cut with the earlier section's margins: it reads no section's margins after a table it broke over a page itself. Word reads them. @@ -1320,6 +1319,13 @@ Word's thickest border, or a filled bar no taller than that — what `addDivider draws — is Word's own rule: an empty paragraph whose bottom border is the stroke, in its colour and thickness, from where the line starts to where it ends, with the space above and below the stroke kept. +A rule the layout moves to a new page in the flow keeps the space the layout leaves above it +there — its margin, 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, as a body paragraph does: Word and LibreOffice drop a paragraph's space above at the top of +a page they break themselves (measured: `ObsidianInvoice`'s footer divider, moved under its info +cards to a new page with its 13pt margin, stood 13pt high in both, with everything under it; +held, it stands where the page sets it). Word draws a paragraph's border past both its indents, and LibreOffice between them, so each indent is taken in by Word's reach: 1.42pt at the left and 1.51pt at the right (measured on nine rules in the body, half a point to 4pt thick: 1.36 to diff --git a/qa/src/test/java/com/demcha/compose/document/templates/invoice/presets/InvoiceNaturalPageBreakDocxTest.java b/qa/src/test/java/com/demcha/compose/document/templates/invoice/presets/InvoiceNaturalPageBreakDocxTest.java new file mode 100644 index 000000000..76fca52ed --- /dev/null +++ b/qa/src/test/java/com/demcha/compose/document/templates/invoice/presets/InvoiceNaturalPageBreakDocxTest.java @@ -0,0 +1,163 @@ +package com.demcha.compose.document.templates.invoice.presets; + +import com.demcha.compose.GraphCompose; +import com.demcha.compose.document.api.DocumentSession; +import com.demcha.compose.document.backend.semantic.docx.DocxSemanticBackend; +import com.demcha.compose.document.layout.LayoutGraph; +import com.demcha.compose.document.layout.PlacedNode; +import com.demcha.compose.document.templates.data.invoice.InvoiceServiceLines; +import com.demcha.compose.document.templates.data.invoice.StructuredInvoiceData; +import org.apache.poi.xwpf.usermodel.IBodyElement; +import org.apache.poi.xwpf.usermodel.XWPFDocument; +import org.apache.poi.xwpf.usermodel.XWPFParagraph; +import org.apache.poi.xwpf.usermodel.XWPFTable; +import org.junit.jupiter.api.Test; +import org.openxmlformats.schemas.wordprocessingml.x2006.main.CTP; +import org.openxmlformats.schemas.wordprocessingml.x2006.main.CTSpacing; +import org.openxmlformats.schemas.wordprocessingml.x2006.main.STLineSpacingRule; + +import java.io.ByteArrayInputStream; +import java.math.BigInteger; +import java.util.ArrayList; +import java.util.List; + +import static org.assertj.core.api.Assertions.assertThat; +import static org.assertj.core.api.Assertions.within; + +/** + * An invoice the layout breaks onto a new page by itself, after a card or a row, breaks there in + * Word too: nothing in a card keeps it with what follows, and the block opening the next page + * holds the space the layout leaves above it there. + * + *

Measured in Word 16 and LibreOffice 24.2. {@code ObsidianInvoice} with its line items repeated + * twelve times sets its info cards at the foot of its fourth page and opens the fifth with its + * footer divider, 13pt below the margin. Word set the cards on the fifth page with the divider, + * 17 lines low, and both editors set the fifth page 13pt high. {@code MeteredInvoice} with its + * line items repeated nine times opens its fourth page with its closing row 12.4pt below the + * margin, the gap above it carried there; Word set that page 13.0pt high and LibreOffice 12.8pt.

+ */ +class InvoiceNaturalPageBreakDocxTest { + + @Test + void obsidiansInfoCardsKeepNothingWithTheDividerTheNextPageOpensWith() throws Exception { + try (DocumentSession session = GraphCompose.document().create()) { + ObsidianInvoice.create().compose(session, longer(ObsidianInvoiceFixtures.invoice(), 12)); + LayoutGraph layout = session.layoutGraph(); + PlacedNode cards = named(layout, "InfoCardsRow"); + PlacedNode divider = named(layout, "FooterDivider"); + assertThat(divider.startPage()).as("the premise: the divider opens the page after the cards") + .isEqualTo(cards.endPage() + 1); + double held = spaceAbove(layout, divider); + assertThat(held).as("the premise: the divider's margin is on its page").isGreaterThan(12); + + try (XWPFDocument document = new XWPFDocument(new ByteArrayInputStream( + session.export(new DocxSemanticBackend())))) { + List body = document.getBodyElements(); + XWPFTable row = tableReading(document, "Payment details"); + List inside = paragraphsIn(row); + assertThat(inside).as("the premise: the cards' paragraphs").hasSizeGreaterThan(10); + // Word keeps a row with what follows its table where a paragraph a cell opens with + // keeps with the next; one between two tables in a cell opens none, even after the + // table a cell opens with (measured: a row at a page's foot stayed there either way). + for (CTP paragraph : inside) { + if (paragraph.isSetPPr() && paragraph.getPPr().isSetKeepNext()) { + assertThat(followsATable(paragraph)) + .as("only a paragraph after a table in a card keeps with the next").isTrue(); + } + } + XWPFParagraph line = (XWPFParagraph) body.get(body.indexOf(row) + 1); + XWPFParagraph rule = (XWPFParagraph) body.get(body.indexOf(row) + 2); + assertThat(rule.getCTP().getPPr().isSetPBdr()).as("the divider, a paragraph's border").isTrue(); + assertHolds(line, held); + assertThat(before(rule)).as("its edge is the line's").isZero(); + } + } + } + + @Test + void meteredsClosingRowHoldsTheGapTheLayoutCarriesOntoItsPage() throws Exception { + try (DocumentSession session = GraphCompose.document().create()) { + MeteredInvoice.create().compose(session, longer(MeteredInvoiceFixtures.invoice(), 9)); + LayoutGraph layout = session.layoutGraph(); + PlacedNode items = named(layout, "LineItems"); + PlacedNode closing = named(layout, "ClosingRow"); + assertThat(closing.startPage()).as("the premise: the closing row opens the page after the line items") + .isEqualTo(items.endPage() + 1); + assertThat(closing.margin().top()).as("the premise: no edge of its own").isZero(); + double held = spaceAbove(layout, closing); + assertThat(held).as("the premise: the gap above it carried onto its page").isGreaterThan(12); + + try (XWPFDocument document = new XWPFDocument(new ByteArrayInputStream( + session.export(new DocxSemanticBackend())))) { + List body = document.getBodyElements(); + XWPFTable row = tableReading(document, "PAYMENT DETAILS"); + assertHolds((XWPFParagraph) body.get(body.indexOf(row) - 1), held); + } + } + } + + private static void assertHolds(XWPFParagraph line, double points) { + // The drawings the page anchors in its first paragraph may stand in it. + assertThat(line.getRuns()).as("a line holding no text of its own") + .allSatisfy(run -> assertThat(run.getCTR().sizeOfTArray()).isZero()); + CTSpacing spacing = line.getCTP().getPPr().getSpacing(); + assertThat(spacing.getLineRule()).isEqualTo(STLineSpacingRule.EXACT); + assertThat(((BigInteger) spacing.getLine()).longValue()).as("the space above, a line's height") + .isCloseTo(Math.round(points * 20), within(1L)); + assertThat(line.getCTP().getPPr().isSetKeepNext()).as("kept with what follows").isTrue(); + } + + private static long before(XWPFParagraph paragraph) { + CTSpacing spacing = paragraph.getCTP().getPPr().getSpacing(); + return spacing == null || !spacing.isSetBefore() ? 0 : ((BigInteger) spacing.getBefore()).longValue(); + } + + /** How far below its page's top margin the layout starts a block, in points. */ + private static double spaceAbove(LayoutGraph layout, PlacedNode node) { + double top = layout.pageGeometry().marginForPage(node.startPage()).top(); + return layout.canvas().height() - top - node.placementY() - node.placementHeight(); + } + + private static PlacedNode named(LayoutGraph layout, String name) { + return layout.nodes().stream().filter(node -> name.equals(node.semanticName())).findFirst().orElseThrow(); + } + + /** The body table whose text reads {@code text}. */ + private static XWPFTable tableReading(XWPFDocument document, String text) { + return document.getTables().stream().filter(table -> { + try (org.apache.xmlbeans.XmlCursor cursor = table.getCTTbl().newCursor()) { + return cursor.getTextValue().contains(text); + } + }).findFirst().orElseThrow(); + } + + /** Whether a paragraph comes right after a table in its cell: none of its cell's opens with it. */ + private static boolean followsATable(CTP paragraph) { + try (org.apache.xmlbeans.XmlCursor cursor = paragraph.newCursor()) { + return cursor.toPrevSibling() && cursor.getObject() instanceof + org.openxmlformats.schemas.wordprocessingml.x2006.main.CTTbl; + } + } + + /** Every paragraph a table holds, at any depth. */ + private static List paragraphsIn(XWPFTable table) { + List paragraphs = new ArrayList<>(); + for (org.apache.xmlbeans.XmlObject found : table.getCTTbl().selectPath( + "declare namespace w='http://schemas.openxmlformats.org/wordprocessingml/2006/main' .//w:p")) { + paragraphs.add((CTP) found); + } + return paragraphs; + } + + /** The invoice with its line items repeated {@code times}. */ + private static StructuredInvoiceData longer(StructuredInvoiceData data, int times) { + List lines = new ArrayList<>(); + for (int time = 0; time < times; time++) { + lines.addAll(data.serviceLines().lines()); + } + return new StructuredInvoiceData(data.brand(), data.supplier(), data.masthead(), + data.billTo(), data.shipTo(), data.summary(), + new InvoiceServiceLines(data.serviceLines().columns(), lines), data.totals(), data.payment(), + data.notes(), data.currencyCode()); + } +} 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 6794ab191..533874d48 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 @@ -3783,7 +3783,7 @@ private void writePlacedNode(XWPFDocument document, DocumentNode node) throws Ex } List written = elements.get().subList(first, elements.get().size()); if (keepTogether || keepWithNext) { - keepOnOnePage(written, keepWithNext); + keepOnOnePage(written, keepWithNext, destination == null); } // A section or a container that writes no paragraph — drawings alone, standing in the // paragraph beside them — has nothing for a bookmark to go round, and a link to its anchor is @@ -4051,8 +4051,20 @@ private static void moveToParagraphStart(org.openxmlformats.schemas.wordprocessi *

Only a block the layout placed on one page is kept. The layout keeps a block together * only when a page can hold it and lets a taller one flow, and a block that ran over a * page break is exactly that; without a layout there is nothing to say either way.

+ * + *

In a table cell only the block's lines are kept together. Word reads keep-with-next on the + * paragraph a cell opens with as keeping the cell's row with what follows it — the next row, + * or the paragraph after the table — and holds none across a break inside the row (measured, + * see {@link #keepThePanelMayBreak}). Written there, a block's keeps held the table it stands in + * with what the layout set on the next page: {@code ObsidianInvoice}'s info cards, kept together + * in a row's two cells, went with the footer divider under them to the next page in Word, 17 + * lines below the page's; with keep-with-next taken off the paragraphs each card opens with, + * they stood on their page (measured, Word 16). A row of columns keeps a block in it whole, as + * it may not split.

+ * + * @param inTheBody whether the block is written in the body, not in a table cell */ - private static void keepOnOnePage(List written, boolean withNext) { + private static void keepOnOnePage(List written, boolean withNext, boolean inTheBody) { List> units = new ArrayList<>(); for (IBodyElement element : written) { if (element instanceof XWPFParagraph paragraph) { @@ -4076,7 +4088,7 @@ private static void keepOnOnePage(List written, boolean withNext) if (!properties.isSetKeepLines()) { properties.addNewKeepLines(); } - if ((!last || withNext) && !properties.isSetKeepNext()) { + if (inTheBody && (!last || withNext) && !properties.isSetKeepNext()) { properties.addNewKeepNext(); } } @@ -7094,13 +7106,13 @@ private void writePanel(XWPFDocument document, DocumentNode node, ContainerPaint writePageBreak(document); } else if (currentCell == null && (bandOpensItsPage || startsAPageOfItsOwn(node))) { // What the block above leaves below itself stays on its page, and the space above - // the panel is held on its own, as at a table the layout moves to a new page - // (writeTableWithItsOwnSpacing): a band's first, where the band opens its page, the - // band's top edge with it (leaveThePageAboveTheBand). + // the panel is held on its own, with a gap the layout carries there, as at a table + // the layout moves to a new page (writeTableWithItsOwnSpacing): a band's first, where + // the band opens its page, the band's top edge with it (leaveThePageAboveTheBand). if (bandOpensItsPage) { leaveThePageAboveTheBand(node); } else { - leaveThePageAbove(); + leaveThePageAboveForTheBlock(node); } onANewPage = true; } @@ -15286,6 +15298,13 @@ private void writeRule(XWPFDocument document, DocumentNode node, DocxRules.Rule // the rule takes that drawing, which is not drawn again. CellRule drawnAs = takeTheDrawingOf(node, rule); + if (opensItsPageInTheFlow(node)) { + // Its top edge is held on the page the layout moves it to, as a paragraph's is: the space + // above a rule is its paragraph's, which Word and LibreOffice drop at the top of a page. + // ObsidianInvoice's footer divider, moved under its info cards to a new page with its + // 13pt margin, stood 13pt high there in both, with everything under it. + holdAParagraphsTopEdgeOnItsPage(document, node, 0); + } XWPFParagraph para = newBodyParagraph(document); applyVerticalSpacing(para, node); CTPPr properties = para.getCTP().isSetPPr() ? para.getCTP().getPPr() : para.getCTP().addNewPPr(); @@ -15546,6 +15565,36 @@ private void leaveThePageAbove() { forgetTheHang(); } + /** + * Leaves on the page above what the layout leaves there when it moves a table, a row or a + * panel to a new page ({@link #leaveThePageAbove}), but for the space owed above the block that + * the layout carries onto the new page, which is held there with the block's own top edge + * ({@link #holdTheSpaceAboveOnItsPage}). + * + *

Where the gap between two blocks does not fit at the foot of a page, the layout carries it + * onto the next, and starts the block that far below the page's top margin, as it starts a + * paragraph ({@link #holdAParagraphsTopEdgeOnItsPage}). {@code MeteredInvoice} with its line + * items repeated nine times opens its fourth page with its closing row 12.4pt below the margin, + * the gap above it, which did not fit in the 9.2pt left at the foot of the third. Left on the page + * above, the row and everything under it stood 13.0pt high in Word and 12.8pt in LibreOffice + * (measured). + * The part carried is what the page holds above the block past its own top margin, the edges + * of the containers opening with it and a layer's offset down its stack of one layer, which is + * named, not written; the space below the block above stays on that page. A block the layout + * runs on past its first page has no place of its own on it ({@link #spaceAboveOnItsPage}), + * and holds its own edge alone.

+ */ + private void leaveThePageAboveForTheBlock(DocumentNode block) { + nameAHangLeftOver(); + resumeHere(); + double carried = spaceAboveOnItsPage(block) - block.margin().top() - carriedSpacingBefore + - layerOffsetNotWritten; + double onItsPage = Double.isNaN(carried) ? 0 : Math.max(0, carried); + pendingSpacingAfter -= onItsPage; + leaveThePageAbove(); + carriedSpacingBefore += onItsPage; + } + /** * Leaves on the page above what a band the layout moves to a new page leaves there, where the * band opens with a block Word puts no space of its own above — a table, a row or a panel: the @@ -15578,15 +15627,16 @@ private void writeTableWithItsOwnSpacing(XWPFDocument document, DocumentNode nod reportWrittenWithout(node, "written as a Word table"); } // The layout starts a block it moves to a new page at the block's own top edge: what - // the page above holds below its last block, and the gap between the two, stay there. - // A band's first block, where the band opens its page, opens that page too, the band's top - // edge above it (leaveThePageAboveTheBand). + // the page above holds below its last block, and the gap between the two, stay there, + // but for a gap that does not fit there, which it carries onto the new page + // (leaveThePageAboveForTheBlock). A band's first block, where the band opens its page, + // opens that page too, the band's top edge above it (leaveThePageAboveTheBand). boolean opensItsBand = currentCell == null && bandOpensItsPage; boolean onANewPage = currentCell == null && (opensItsBand || startsAPageOfItsOwn(node)); if (opensItsBand) { leaveThePageAboveTheBand(node); } else if (onANewPage) { - leaveThePageAbove(); + leaveThePageAboveForTheBlock(node); } // A table a band's or a column's layer opens is that layer's first block, so it starts // where the layer resumes, as a paragraph does, and its own top margin comes after: @@ -17790,7 +17840,7 @@ private void writePaintedRow(XWPFDocument document, RowNode row) throws Exceptio warnContainerRadiusDropped(row); boolean onANewPage = currentCell == null && startsAPageOfItsOwn(row); if (onANewPage) { - leaveThePageAbove(); + leaveThePageAboveForTheBlock(row); } writePanelPiece(document, row, paint, () -> writeRow(document, row, true), true, true, onANewPage); } diff --git a/render-docx/src/test/java/com/demcha/compose/document/backend/semantic/docx/DocxBlockOpeningAPageTest.java b/render-docx/src/test/java/com/demcha/compose/document/backend/semantic/docx/DocxBlockOpeningAPageTest.java index 3656038ac..330c85630 100644 --- a/render-docx/src/test/java/com/demcha/compose/document/backend/semantic/docx/DocxBlockOpeningAPageTest.java +++ b/render-docx/src/test/java/com/demcha/compose/document/backend/semantic/docx/DocxBlockOpeningAPageTest.java @@ -11,6 +11,7 @@ import com.demcha.compose.document.dsl.TableBuilder; import com.demcha.compose.document.image.DocumentImageData; import com.demcha.compose.document.node.DocumentNode; +import com.demcha.compose.document.node.LayerAlign; import com.demcha.compose.document.node.TextAlign; import com.demcha.compose.document.style.DocumentColor; import com.demcha.compose.document.style.DocumentInsets; @@ -41,6 +42,11 @@ * band's margin was left on the page above. Each held in a line kept with it, as a paragraph's * edge is, stood where the page sets it, within 0.1pt of the paragraphs round it.

* + *

So do a rule, and a table, a row or a panel whose gap above it the layout carries onto the new + * page, where the gap does not fit at the foot of the page above. Measured in Word 16 and + * LibreOffice 24.2: {@code ObsidianInvoice}'s footer divider stood 13pt high, its margin, and + * {@code MeteredInvoice}'s closing row about 13pt, its 12.4pt gap; held in a line, within 0.7pt.

+ * * @author Artem Demchyshyn */ class DocxBlockOpeningAPageTest { @@ -334,6 +340,187 @@ void aLinePairSetAboveItsOverlayIsLeftAsItWas() throws Exception { } } + @Test + void aRuleTheLayoutMovesToANewPageHoldsItsMarginInALineKeptWithIt() throws Exception { + // A rule's space above is its paragraph's, which Word and LibreOffice drop at the top of a + // page: ObsidianInvoice's footer divider, moved to a new page with its 13pt margin, stood + // 13pt high in both. + Consumer content = movedToANewPage(rule(EDGE)); + assertOpensTheSecondPage(content, "Block"); + try (XWPFDocument document = export(content)) { + XWPFParagraph rule = rule(document); + + assertThat(lineBefore(document, rule)).as("the rule's margin, a line's height").isEqualTo(Math.round(EDGE * 20)); + assertThat(before(spacing(paragraphBefore(document, rule)))) + .as("the filler's height stays above the line").isEqualTo(owed(CONTENT - 10)); + assertThat(before(spacing(rule))).as("its edge is the line's").isZero(); + } + } + + @Test + void aRuleWhoseGapCarriesToANewPageHoldsTheGapWithItsMargin() throws Exception { + // 157pt leave 3, less than the gap: the gap and the rule open the second page. + Consumer content = page -> page.spacing(GAP).spacer(0, CONTENT - 3).add(rule(EDGE)); + assertOpensTheSecondPage(content, "Block"); + try (XWPFDocument document = export(content)) { + assertThat(lineBefore(document, rule(document))).as("the gap and the margin") + .isEqualTo(Math.round((GAP + EDGE) * 20)); + } + } + + @Test + void aRuleOnThePageOfTheBlockBeforeItHoldsNoLine() throws Exception { + Consumer content = page -> page.spacer(0, CONTENT - 40).add(rule(EDGE)); + assertThat(startPage(content, "Block")).as("the premise: the rule stays on the first page").isZero(); + try (XWPFDocument document = export(content)) { + XWPFParagraph rule = rule(document); + + assertThat(DocxTwips.of(spacing(paragraphBefore(document, rule)).getLine())) + .as("the filler's hairline, no line held").isEqualTo(HAIRLINE); + assertThat(before(spacing(rule))).as("the filler's height and its margin, as before") + .isEqualTo(owed(CONTENT - 40 + EDGE)); + } + } + + @Test + void aRowWhoseGapCarriesToANewPageHoldsTheGap() throws Exception { + // 157pt leave 3, less than the gap: the layout starts the row 4pt below the second page's + // margin. MeteredInvoice's closing row, its 12.4pt gap carried so, stood 13.0pt high in Word + // and 12.8pt in LibreOffice. + Consumer content = gapCarried(0, row(0)); + assertOpensTheSecondPage(content, "Block"); + try (XWPFDocument document = export(content)) { + XWPFParagraph line = paragraphBefore(document, document.getTables().get(0)); + + assertThat(lineHeight(line)).as("the gap").isEqualTo(Math.round(GAP * 20)); + assertThat(after(spacing(paragraphBefore(document, line)))) + .as("the filler's height alone below it, the gap not left on the page above as well") + .isEqualTo(owed(CONTENT - 3)); + } + } + + @Test + void aRowWhoseGapStaysAboveHoldsNoLine() throws Exception { + // 150pt leave 10: the gap fits at the foot of the first page, the row does not. + Consumer content = page -> page.spacing(GAP).spacer(0, CONTENT - 10).add(row(0)); + assertOpensTheSecondPage(content, "Block"); + try (XWPFDocument document = export(content)) { + assertThat(DocxTwips.of(spacing(paragraphBefore(document, document.getTables().get(0))).getLine())) + .as("the filler's hairline, no line held").isEqualTo(HAIRLINE); + } + } + + @Test + void aRowsOwnMarginIsHeldWithTheGapAndTheSpaceBelowTheBlockAboveStaysThere() throws Exception { + // The filler's 6pt below it fit at the foot of the first page and the gap did not: the layout + // starts the row its own 6pt and the gap below the margin. + Consumer content = gapCarried(6, row(6)); + assertOpensTheSecondPage(content, "Block"); + try (XWPFDocument document = export(content)) { + XWPFParagraph line = paragraphBefore(document, document.getTables().get(0)); + + assertThat(lineHeight(line)).as("the gap and the row's margin").isEqualTo(Math.round((GAP + 6) * 20)); + assertThat(after(spacing(paragraphBefore(document, line)))) + .as("the filler's height and its margin below it stay on the page above") + .isEqualTo(owed(CONTENT - 3)); + } + } + + @Test + void aRowSetDownItsStackOfOneLayerHoldsNoneOfTheOffset() throws Exception { + // The layer stands 12pt down its stack, which is named, not written; no gap is carried, and + // no line holds the offset, where the note says Word writes the row. + Consumer content = movedToANewPage(new LayerStackBuilder() + .position(row(0), 0, EDGE, LayerAlign.TOP_LEFT).build()); + assertOpensTheSecondPage(content, "Block"); + try (XWPFDocument document = export(content)) { + assertThat(DocxTwips.of(spacing(paragraphBefore(document, document.getTables().get(0))).getLine())) + .as("the filler's hairline, no line held").isEqualTo(HAIRLINE); + } + assertThat(DocxExports.report(300, 200, 20, content).bySubject().get("layer offset")) + .as("the offset named").isNotNull(); + } + + @Test + void aRowOpeningAPaddedSectionHoldsTheGapWithThePadding() throws Exception { + Consumer content = gapCarried(6, new SectionBuilder().padding(DocumentInsets.top(PADDING)) + .add(row(0)).build()); + assertOpensTheSecondPage(content, "Block"); + try (XWPFDocument document = export(content)) { + assertThat(lineHeight(paragraphBefore(document, document.getTables().get(0)))) + .as("the gap and the section's padding").isEqualTo(Math.round((GAP + PADDING) * 20)); + } + } + + @Test + void aTableWhoseGapCarriesToANewPageHoldsTheGapWithItsMargin() throws Exception { + Consumer content = gapCarried(0, new TableBuilder().name("Block").margin(DocumentInsets.top(6)) + .autoColumns(2).row("Opening", "Beside").build()); + assertOpensTheSecondPage(content, "Block"); + try (XWPFDocument document = export(content)) { + assertThat(lineHeight(paragraphBefore(document, document.getTables().get(0)))) + .as("the gap and the table's margin").isEqualTo(Math.round((GAP + 6) * 20)); + } + } + + @Test + void aPaintedRowWhoseGapCarriesToANewPageHoldsTheGap() throws Exception { + Consumer content = gapCarried(0, new RowBuilder().name("Block").fillColor(DocumentColor.LIGHT_GRAY) + .addParagraph("Opening").addParagraph("Beside").build()); + assertOpensTheSecondPage(content, "Block"); + try (XWPFDocument document = export(content)) { + assertThat(lineHeight(paragraphBefore(document, document.getTables().get(0)))) + .as("the gap").isEqualTo(Math.round(GAP * 20)); + } + } + + @Test + void aPanelWhoseGapCarriesToANewPageHoldsTheGap() throws Exception { + Consumer content = gapCarried(0, new SectionBuilder().name("Block") + .fillColor(DocumentColor.LIGHT_GRAY).padding(DocumentInsets.of(6)) + .addParagraph("Opening").build()); + assertOpensTheSecondPage(content, "Block"); + try (XWPFDocument document = export(content)) { + assertThat(lineHeight(paragraphBefore(document, document.getTables().get(0)))) + .as("the gap").isEqualTo(Math.round(GAP * 20)); + } + } + + /** A gap between blocks, which does not fit in the 3pt the filler leaves at the foot of the first page. */ + private static final double GAP = 4; + + /** A section's padding above a block opening the second page with it. */ + private static final double PADDING = 8; + + /** + * A 157pt filler with {@code below} of it its margin below, {@link #GAP} between the blocks, and + * {@code block}: the 3pt the filler leaves at the foot of the first page do not hold the gap. + */ + private static Consumer gapCarried(double below, DocumentNode block) { + return page -> page.spacing(GAP) + .addSection(s -> s.margin(DocumentInsets.bottom(below)).spacer(0, CONTENT - 3 - below)) + .add(block); + } + + /** A row of two paragraphs with {@code margin} above it, named for the layout's placement of it. */ + private static DocumentNode row(double margin) { + return new RowBuilder().name("Block").margin(DocumentInsets.top(margin)) + .addParagraph("Opening").addParagraph("Beside").build(); + } + + /** A rule with {@code margin} above it, named for the layout's placement of it. */ + private static DocumentNode rule(double margin) { + return new com.demcha.compose.document.dsl.LineBuilder().name("Block").horizontal(200).thickness(1) + .margin(DocumentInsets.top(margin)).build(); + } + + /** The paragraph a rule is written as: the one with a border. */ + private static XWPFParagraph rule(XWPFDocument document) { + return document.getParagraphs().stream() + .filter(paragraph -> paragraph.getCTP().isSetPPr() && paragraph.getCTP().getPPr().isSetPBdr()) + .findFirst().orElseThrow(); + } + /** A list of one item, named for the layout's placement of it. */ private static DocumentNode list(DocumentInsets margin, DocumentInsets padding) { return new ListBuilder().name("List").items("Opening").margin(margin).padding(padding).build(); diff --git a/render-docx/src/test/java/com/demcha/compose/document/backend/semantic/docx/DocxKeepTogetherTest.java b/render-docx/src/test/java/com/demcha/compose/document/backend/semantic/docx/DocxKeepTogetherTest.java index 74d5e05ee..fcaa1ac85 100644 --- a/render-docx/src/test/java/com/demcha/compose/document/backend/semantic/docx/DocxKeepTogetherTest.java +++ b/render-docx/src/test/java/com/demcha/compose/document/backend/semantic/docx/DocxKeepTogetherTest.java @@ -1,11 +1,17 @@ package com.demcha.compose.document.backend.semantic.docx; +import com.demcha.compose.document.style.DocumentColor; +import com.demcha.compose.document.style.DocumentInsets; import org.apache.poi.xwpf.usermodel.XWPFDocument; import org.apache.poi.xwpf.usermodel.XWPFParagraph; import org.apache.poi.xwpf.usermodel.XWPFTable; import org.apache.poi.xwpf.usermodel.XWPFTableCell; import org.apache.poi.xwpf.usermodel.XWPFTableRow; import org.junit.jupiter.api.Test; +import org.openxmlformats.schemas.wordprocessingml.x2006.main.CTP; + +import java.util.ArrayList; +import java.util.List; import static org.assertj.core.api.Assertions.assertThat; @@ -213,6 +219,58 @@ void aBandInARowsCellIsLeftToItsRow() throws Exception { } } + @Test + void aBlockKeptTogetherInARowsCellKeepsItsLinesAndNothingWithTheNext() throws Exception { + // Word reads keep-with-next on the paragraph a cell opens with as keeping the row with what + // follows the table; the row, which may not split, keeps the block whole. + try (XWPFDocument document = DocxExports.withLayout(595, 842, 36, page -> page + .addRow(row -> row + .addSection(s -> s.keepTogether().addParagraph("Opening").addParagraph("Body")) + .addParagraph("Beside")) + .addParagraph(p -> p.text("After")))) { + XWPFTableRow row = document.getTables().get(0).getRow(0); + List kept = row.getCell(0).getParagraphs().stream() + .filter(paragraph -> !paragraph.getText().isEmpty()).toList(); + + assertThat(kept).extracting(XWPFParagraph::getText).containsExactly("Opening", "Body"); + for (XWPFParagraph paragraph : kept) { + assertThat(keepsNext(paragraph)).as("kept with nothing in its cell").isFalse(); + assertThat(keepsLines(paragraph)).as("its lines kept together").isTrue(); + } + assertThat(row.isCantSplitRow()).isTrue(); + } + } + + @Test + void cardsKeptTogetherInARowsCellsKeepNothingWithWhatFollowsTheRow() throws Exception { + // ObsidianInvoice's info cards: kept with the next, the paragraph each card's cell opens with + // kept the row with the footer divider the layout set on the next page, and Word set the + // cards there too, 17 lines below the page's (measured, Word 16). + DocumentColor surface = DocumentColor.LIGHT_GRAY; + try (XWPFDocument document = DocxExports.withLayout(595, 842, 36, page -> page + .addRow(row -> row + .addSection(card -> card.keepTogether().fillColor(surface).padding(DocumentInsets.of(6)) + .addParagraph("Notes").addParagraph("Thank you")) + .addSection(card -> card.keepTogether().fillColor(surface).padding(DocumentInsets.of(6)) + .addParagraph("Payment") + .addSection(fields -> fields.addParagraph("Payee").addParagraph("Kestrel")))) + .addParagraph(p -> p.text("After")))) { + XWPFTable row = document.getTables().get(0); + List inside = paragraphsIn(row); + + assertThat(inside).extracting(DocxKeepTogetherTest::textOf) + .contains("Notes", "Thank you", "Payment", "Payee", "Kestrel"); + for (CTP paragraph : inside) { + assertThat(paragraph.isSetPPr() && paragraph.getPPr().isSetKeepNext()) + .as("a paragraph in the cards' row keeps nothing with the next").isFalse(); + if (!textOf(paragraph).isEmpty()) { + // Laid out, and kept: the cards' lines are kept together. + assertThat(paragraph.getPPr().isSetKeepLines()).as("%s keeps its lines", textOf(paragraph)).isTrue(); + } + } + } + } + @Test void withoutALayoutAStackIsNotKnownToBeOnOnePage() throws Exception { try (XWPFDocument document = DocxExports.withoutLayout(595, 842, 36, page -> page @@ -243,6 +301,22 @@ private static XWPFParagraph paragraph(XWPFDocument document, String text) { .orElseThrow(() -> new AssertionError("no paragraph reads " + text)); } + /** Every paragraph a table holds, at any depth. */ + private static List paragraphsIn(XWPFTable table) { + List paragraphs = new ArrayList<>(); + for (org.apache.xmlbeans.XmlObject found : table.getCTTbl().selectPath( + "declare namespace w='http://schemas.openxmlformats.org/wordprocessingml/2006/main' .//w:p")) { + paragraphs.add((CTP) found); + } + return paragraphs; + } + + private static String textOf(CTP paragraph) { + try (org.apache.xmlbeans.XmlCursor cursor = paragraph.newCursor()) { + return cursor.getTextValue(); + } + } + private static boolean keepsNext(XWPFParagraph paragraph) { return paragraph.getCTP().isSetPPr() && paragraph.getCTP().getPPr().isSetKeepNext(); } 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 9b2df3197..b386c1f71 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 @@ -227,8 +227,10 @@ record Entry(Fate fate, String note) { // A keep is written only for a block the layout keeps on one page. private static final String KEEP = "with no layout, in the section's note; inside a panel the layout runs on to " + "the next page, named as one Word may break; composed in a table cell, " - + "where the table row it stands in is what is kept, not written; any other " - + "is written"; + + "where the table row it stands in is what is kept, not written; in any other " + + "table cell its lines kept together and nothing kept with the next, as Word " + + "reads keep-with-next there as keeping the row with what follows the table; " + + "any other is written"; // A page field is a zone line's part: anywhere else it is dropped with a note. private static final String FIELD_OUTSIDE_A_ZONE = "outside a page zone's line, not written, which its note " + "names; any other is written"; diff --git a/render-docx/src/test/java/com/demcha/compose/document/backend/semantic/docx/DocxOneRowTableKeptWithTheNextTest.java b/render-docx/src/test/java/com/demcha/compose/document/backend/semantic/docx/DocxOneRowTableKeptWithTheNextTest.java index a86ccaa47..2bd79a380 100644 --- a/render-docx/src/test/java/com/demcha/compose/document/backend/semantic/docx/DocxOneRowTableKeptWithTheNextTest.java +++ b/render-docx/src/test/java/com/demcha/compose/document/backend/semantic/docx/DocxOneRowTableKeptWithTheNextTest.java @@ -64,8 +64,9 @@ void aRowKeptTogetherAndNotWithTheNextStaysWhole() throws Exception { @Test void aRowWhoseHeadingAloneIsKeptWithTheNextStaysWhole() throws Exception { - // Only a row whose every paragraph holds onto what follows is kept with it: LibreOffice - // reads the keep off the first alone. + // The heading is kept with the line under it in its column, which the row holds whole: kept + // with the next in the cell it opens, it would keep the row with the paragraph after it in + // Word, which reads the keep off the paragraph a cell opens with. try (XWPFDocument document = DocxExports.withLayout(595, 842, 36, page -> page .addRow(row -> row .addSection(column -> column @@ -75,8 +76,8 @@ void aRowWhoseHeadingAloneIsKeptWithTheNextStaysWhole() throws Exception { .addParagraph("Deliverables"))) { XWPFTableRow row = document.getTables().get(0).getRow(0); - assertThat(keepsNext(paragraph(row, "Summary"))).isTrue(); - assertThat(rowKeepsNext(row)).isFalse(); + assertThat(keepsNext(paragraph(row, "Summary"))).isFalse(); + assertThat(paragraph(row, "Summary").getCTP().getPPr().isSetKeepLines()).isTrue(); assertThat(row.isCantSplitRow()).isTrue(); } } @@ -133,7 +134,8 @@ void aKeptRowHoldingATableStaysWhole() throws Exception { @Test void aRowKeptWithTheNextInsideACellStaysWhole() throws Exception { - // A table in a cell goes where its cell's row goes. + // A table in a cell goes where its cell's row goes. Kept with the next, the paragraph the + // card's cell opens with would keep the card with what follows it in Word. try (XWPFDocument document = DocxExports.withLayout(595, 842, 36, page -> page .addSection(card -> card.fillColor(SURFACE) .addSection(s -> s.keepWithNext().addRow(row -> row.addParagraph("Northline").addParagraph("Proposal"))) @@ -141,7 +143,11 @@ void aRowKeptWithTheNextInsideACellStaysWhole() throws Exception { XWPFTableCell card = document.getTables().get(0).getRow(0).getCell(0); XWPFTableRow row = card.getTables().get(0).getRow(0); - assertThat(rowKeepsNext(row)).isTrue(); + for (XWPFTableCell cell : row.getTableCells()) { + for (XWPFParagraph paragraph : cell.getParagraphs()) { + assertThat(keepsNext(paragraph)).as("nothing in the card keeps with the next").isFalse(); + } + } assertThat(row.isCantSplitRow()).isTrue(); } } diff --git a/render-docx/src/test/java/com/demcha/compose/document/backend/semantic/docx/DocxPanelEdgeCasesTest.java b/render-docx/src/test/java/com/demcha/compose/document/backend/semantic/docx/DocxPanelEdgeCasesTest.java index f28a56253..3901acdde 100644 --- a/render-docx/src/test/java/com/demcha/compose/document/backend/semantic/docx/DocxPanelEdgeCasesTest.java +++ b/render-docx/src/test/java/com/demcha/compose/document/backend/semantic/docx/DocxPanelEdgeCasesTest.java @@ -66,7 +66,9 @@ void aBlockInsideACardThatTakesOverATablesCloserIsBookmarkedFromIt() throws Exce } @Test - void keepingABlockInsideACardTogetherKeepsItsParagraphs() throws Exception { + void keepingABlockInsideACardTogetherKeepsItsLinesAndNothingWithTheNext() throws Exception { + // Word reads keep-with-next on the paragraph a cell opens with as keeping the card's row + // with what follows the card. try (XWPFDocument document = export(page -> page.addSection("Card", card -> card .fillColor(SURFACE) .addSection("Kept", kept -> kept.keepTogether() @@ -74,7 +76,8 @@ void keepingABlockInsideACardTogetherKeepsItsParagraphs() throws Exception { .addParagraph(p -> p.text("Second kept")))))) { XWPFTableCell cell = card(document); - assertThat(paragraphIn(cell, "First kept").getCTP().getPPr().isSetKeepNext()).isTrue(); + assertThat(paragraphIn(cell, "First kept").getCTP().getPPr().isSetKeepNext()).isFalse(); + assertThat(paragraphIn(cell, "First kept").getCTP().getPPr().isSetKeepLines()).isTrue(); assertThat(paragraphIn(cell, "Second kept").getCTP().getPPr().isSetKeepLines()).isTrue(); } }