fix(docx): name in the report what the export draws as a picture or draws without

CHANGELOG.md

@@ -8,6 +8,27 @@ follow semantic versioning; release dates are ISO 8601.
 
 ### Public API
 
+- **A DOCX export's report names what it draws as a picture, or draws without, where it said nothing
+  or more than was lost.** An inline shape — a dot, an arrow, a checkbox — and an SVG icon that
+  states no text were drawn into pictures with no note, though Word could hold a shape in the line;
+  each is now reported `APPROXIMATED` as a picture. A box drawn as a shape whose corners round by
+  radii that differ — a shape container's outline, or a section's or a container's paint laid over
+  the flow — was drawn at the largest of them unnamed; its note now says so, and so does a shape
+  container composed in a table cell that its table draws. A path composed in a table cell lost its
+  caps and joins in silence, and a drawn path's note named a gradient paint, a dash pattern, caps
+  and joins whatever it lost. A path's outline is written with no cap and no join, which Word and
+  LibreOffice draw with flat ends and round joins (measured: a 10pt stroke's ends stood where the
+  page ends them, and its mitred point 2.76pt short), so the note now names a gradient, a dash, a
+  cap that is not flat where the path has an open end, and a join that is not round where two of
+  its segments meet — the page's default mitre among them. A path painted only with a gradient
+  was dropped as geometry Word has no analogue for; it is dropped for its gradient. Page numbers
+  that do not count from 1 on page 1 were reported as numbered from 1 by Word's fields, which a
+  section's `w:pgNumType` could offset; the note now says the export writes them without that
+  offset. A page zone's icons and shapes are named once, though its line is written into each kind
+  of header Word is given. None of the corpus's 62 DOCX changes. Their reports go from 969 notes to
+  1340: 278 inline shapes and 85 icons named pictures, 8 paths in table cells naming their caps, and
+  the 50 path notes that named all four now naming caps (37), joins (1), caps and joins (1) or none
+  (11) — none of those paths has a gradient or a dash.
 - **A DOCX export gives a paragraph opening a row's column the gap above its first line out of the
   space above the row.** Word sets a paragraph's lines one height apart, the gap between them inside
   the line, so a paragraph of more than one line holds a gap too many, which comes off the space

docs/recipes/docx-export.md

@@ -651,7 +651,7 @@ page.addParagraph(p -> p
   picture from the same layers the page draws, by the raster the PPTX export falls back
   to, so it looks as it does on the page. The text it stands for is the picture's
   description, which a screen reader reads; it is not a character a reader copies or
-  searches, and the report says so.
+  searches. The report names every icon a picture, and an icon's text its description.
 - **Links.** A picture carrying a link, or in a linked paragraph, is inside the link.
 
 - **What a shape is.** An inline shape — a `dot(...)`, an arrow, a chevron, a checkbox,
@@ -664,7 +664,8 @@ page.addParagraph(p -> p
   pixels a point), and is lowered by what it takes below, so the
   outline stands where the page has it, no edge is cut, and a shape takes that much more
   room in the line than on the page. A list marker that draws a disc is written the same
-  way, followed by the space a text marker gets.
+  way, followed by the space a text marker gets. Word could hold a shape in the line, which
+  this export does not write: the report names each shape among the words a picture.
 
 ## What a chip keeps and loses
 
@@ -1077,7 +1078,7 @@ shapes stand above the page backgrounds, which LibreOffice stacks together with
 - A drawing carries no link, no outline entry and no bookmark: a link to a drawn shape's
   anchor points at none, and a page reference to it is a fixed number. A gradient fill,
   unequal corners (drawn at the largest radius) and a line's dash pattern (drawn solid) are
-  not carried either, and a line's caps are not written, which leaves its ends to the editor.
+  not carried either, and a line's caps are not written: Word and LibreOffice end it flat.
   A rule — a line or a thin bar written as a paragraph border — keeps its anchor; its note
   names a lost outline entry, caps (a border ends flat) or a bar's link, a line's link being
   reported as `rule link`.
@@ -1089,9 +1090,12 @@ shapes stand above the page backgrounds, which LibreOffice stacks together with
 
 Polygons and paths — a star, a chevron, an SVG icon's layers, a portrait drawn as paths —
 are drawn the same way, as custom geometry through the same points and curves, their fill
-and stroke colours carried; the dash pattern, the caps and joins and the clip round an
-SVG icon are not — a clip that cuts the icon's art, parked outside its box, is named in the
-report. A shape filled only with a gradient paint shows nothing the export
+and stroke colours carried; the dash pattern and the clip round an SVG icon are not, and
+the outline is written with no cap and no join, which Word and LibreOffice draw with flat
+ends and round joins. A path's note names a dash, a cap that is not flat where the path has
+an open end and a join that is not round where two of its segments meet, and a clip that
+cuts the icon's art, parked
+outside its box, is named in the report. A shape filled only with a gradient paint shows nothing the export
 carries and is **skipped**, and the report names each one. In the flow a drawn or skipped
 shape still takes its room:
 its placed height and margins are owed as space above what follows, and so are
@@ -1126,9 +1130,11 @@ height on the page, since one after another in the footer they would keep
 the order they were added in rather than the page's order by height. A
 band kept off the first page (`showOnFirstPage(false)`, or counted from page
 2) leaves the first page's header or footer empty. Two numbering settings
-have no Word equivalent and are reported: a band that starts after the
-second page is written on every page but the first, and page numbers that do
-not count from 1 on the first page are numbered from 1 by Word. A band alone of
+are not carried and are reported: a band that starts after the second page,
+which has no Word part to hold it off, is written on every page but the first,
+and page numbers that do not count from 1 on the first page are written
+without their offset, so Word numbers the pages from 1 — a section's
+`w:pgNumType` could start them elsewhere. A band alone of
 its kind that reaches past the page margin, by more than a twentieth of a point, writes that
 margin negative: the page lets the
 band overlap the body, and Word holds the body at a negative margin whatever the band

render-docx/src/main/java/com/demcha/compose/document/backend/semantic/docx/DocxDrawings.java

@@ -227,6 +227,17 @@ private static void add(List<Shape> shapes, Shape shape) {
         }
     }
 
+    /**
+     * Whether a box fragment's box is drawn as a shape — filled or outlined — rather than only
+     * its side borders, or nothing.
+     */
+    static boolean drawsItsBox(PlacedFragment fragment) {
+        return fragment.payload() instanceof ShapeFragmentPayload shape
+               && visible(new Shape(Kind.RECT, fragment.x(), 0, fragment.width(), fragment.height(),
+                       shape.fillColor(), colourOf(shape.stroke()), widthOf(shape.stroke()), 0, false,
+                       fragment.pageIndex())) != null;
+    }
+
     private static Shape visible(Shape shape) {
         boolean filled = shape.fill() != null && shape.fill().getAlpha() > 0;
         boolean outlined = shape.stroke() != null && shape.stroke().getAlpha() > 0 && shape.strokeWidth() > 0;