stationery 0.11.0 → 0.11.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6ebbefcf328d01eacf608d65fe46e05ac3561d335ae3ea255805afcb4fef66d2
-  data.tar.gz: 37b7e8db370b6f1d82c9b2fd493300f4194be46006c6bd29456a3002774af3f3
+  metadata.gz: b208319414f7dea1a6af8a89b47aec788e1135ace442031a1d05623240483d7c
+  data.tar.gz: f9d15f729afcfd2fa6861b01b365462b4a5d413a4ce9b6fb101c2b7c3b9f68db
 SHA512:
-  metadata.gz: 21b371d2b1cd3a829ac46991185c0e9b4406b67089984d5ea35dc8e60d9bacb7e0f97e2cec744e37f2c9bed39264b32af83f75e765eb2053d81834082c8aae38
-  data.tar.gz: b2aa8f17f1d896c7e9796ff960cf2777db76f20270f05ffce4dc28da9aa370973e4c6ed7aa84ccfe20da1b8579aa9183ecc6922ac9ddecf7da282007faac6a19
+  metadata.gz: fca53eecf78b67b65c7bb9b9582d625f6e693ba9ff29264423f9c1028d3ea8b2477d69af7858edde8169b91b592d43a364d4874703cf719173158c09f187f4b1
+  data.tar.gz: 9bd72b967a7e1cd32acf650e5662d009cf792e23f1fef9cec3df579b74fad916f2ed4a0d6d96bdd0b0bbefcecc85f7d277510ff69b486c742d0d00ae169ac8da

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.11.1 (2026-09-28)
+
+What putting 0.11.0 to work found: PDF/UA claims that hold, boxes that stay on their page, columns that fill evenly, and lists that widen below a float.
+
+- PDF/UA-1 refuses heading levels that are skipped (ISO 14289-1, 7.4.2; veraPDF rule 7.4.2-1): the first heading of a document is `heading: 1` and a heading is at most one level below the heading before it, so `heading: 1` followed by `heading: 3`, or a document that starts at `heading: 2`, raises `Stationery::ConformanceError` with an issue per heading (`heading 3 on page 2 skips a level: heading 2 is the deepest that may follow heading 1`) instead of writing a file that claims a level it does not keep. Going back up is free (`3`, then `1`), and a heading that skipped is what the next one is measured against. Headings are read in the order of the structure tree, which is what a validator follows, inside sections, lists, table cells, columns and floats, from `text(heading:)`, `html` and `markdown` alike; the headings of headers, footers and page templates are artifacts and a heading without text is not written, so neither counts. In a tagged render without the claim it is a `Warnings::SkippedHeading` (`level`, `allowed`, `page`), so `strict` catches it.
+- A blank `alt:` is a missing one: `image(source, alt: "")`, `svg(source, alt: " ")` and a `markdown` image without a description (`![](photo.png)`) are reported as `Warnings::MissingAlt` in a tagged render and raise `ConformanceError` under PDF/UA-1 (ISO 14289-1, 7.3; veraPDF rule 7.3-1 fails an empty `/Alt`), where only a missing `alt:` was caught. An `alt:` of whitespace alone is refused as well, although veraPDF accepts it: it describes as little as the empty one. `alt: false` still marks decoration, which is an artifact and needs no description, and the message of `MissingAlt` now names it: `image on page 1 has no alt: text (alt: false marks decoration)`.
+- In `html`, `<img alt="">` is decoration, as HTML means it: an `alt` attribute that is there and empty (or whitespace alone) draws the image as `alt: false` does, an artifact outside the structure tree, floated or not, so it neither warns nor raises. An `<img>` without an `alt` attribute is still a missing description. Markdown has no way to say that an image is decorative, so `![](photo.png)` counts as a description forgotten: use `html` or the `image` element for decoration.
+- A `box` that splits across pages no longer runs over the page by the padding and border that close it. A head is open at the bottom, so its content was cut at the height less the top of the box alone: content that ended on the page by that measure was placed with the bottom padding under it, up to that much over the edge, and reported as an `Overflow`. The last of the content now goes to the next page with what closes the box; content that cannot be cut there moves whole, and first on a fresh page it is kept and reported as before. Boxes inside boxes added their paddings up: 29 of 200 random flows of nested padded boxes overflowed, none do. A box that did not overflow is laid out as it was.
+- Balanced `columns` fill evenly: ten lines in three columns are 4, 3 and 3 (they were 4, 4 and 2, the last column taking what was left over), thirteen in four are 4, 3, 3 and 3. At the balanced height the first column takes what fits, and what it leaves is balanced through the columns after it in the same way, down to the last two, so what cannot be shared goes to the earlier columns. Every column is still cut where a page would cut it, so `orphans:`/`widows:`, `keep_with_next`, `break_inside: :avoid` and blocks that cannot split hold as they did; the columns filled in order are kept where the levelled ones would not place everything, would change the height of the block, or would have a later column taller than an earlier one where there was none. The block is exactly as tall as it was, so what follows it stays where it is, and a block of two columns, `balance: false`, the full pages of a block that continues and documents without `columns` are byte for byte what they were. A block is levelled once, when it is placed, with at most `(count - 2) * 41` pours more than its balancing: 700 paragraphs in two and three columns render in the time they did. `Layout::Columns::Leveller`, `Layout::Columns::Pour#first`.
+- Beside a float, a list item and a `box` that paints nothing of its own wrap what they hold: they keep the full width of their flow, and their lines are narrow beside the float and take the full width below it, in the middle of a paragraph if need be. They were blocks of the width the float left, all the way down, so a long item or box beside a short image stayed narrow below it. That is a box without `background:`, `border:`, `shadow:` or `link:` and without `width:`, `height:`, `rotate:`, `overflow:` or `valign:`; its padding lies under the float, as a block's does in CSS. A list item keeps its indent from the float, with the marker beside its first line. They split across pages as they did (`break_inside:`, `keep_with_next:`, `orphans:` and `widows:` inside them), the lines carried over are wrapped again at the full width, and a tagged PDF reads them in the order they were written. In `html`, the items of a list beside a floated `img` wrap, and so does a block indented by `margin-left` or `margin-right`, whose margin lies under the float. A box with a background, a border, a shadow or a link stays a block of the width that is left: it is painted after the float written before it, and at the full width it would paint over the float. So do a `table`, a `row` and `columns`, whose columns depend on their width. Documents without floats are byte for byte what they were, and allocate what they did. `Layout::Box::Wrapping`, `Text::Exclusions#inset`.
+- `html` reads `margin-left` and `margin-right`, which were reported as `Warnings::UnsupportedCss`: lengths in `px` or `pt`, as `margin-top` takes them. On a floated `img` they are that side of the space kept around it, so `style="float: right; margin-left: 12pt"` keeps 12 pt between the image and the text. On a block (`p`, `div`-like containers, headings, lists, tables, `blockquote`, `pre`) they indent it from that side, its background and padding inside the margin; the block breaks across pages where it did, and a heading or a paragraph keeps its `keep_with_next`. `margin` and its sides are read in the order of the cascade, specificity first and position then: a side wins over a `margin` declared before it, and a `margin` takes back the sides declared before it. `auto`, `em` and `%` are reported as they were, and so is a negative `margin-left` or `margin-right`. HTML without margins renders byte for byte as before. `CSS::Stylesheet#matching`.
+- Testing: `Inspector#text` and `#page_texts`, and so `have_pdf_text`, `have_pdf_text_on_page` and `assert_pdf_text`, read a sequence with `/ActualText` as that text, once, whatever the glyphs inside it advance. A shaped stretch whose first glyph has no advance (a mark drawn before its base, as HarfBuzz answers for Arabic) was missing from the text: pdf-reader gives the `ActualText` to the first glyph shown and drops a glyph without a width. The helpers now read a page through the receiver `Inspector#structure` already read it with: glyphs outside such a sequence are laid out by pdf-reader as before, and the sequence is one run from where its first glyph is shown to where it ends. The text of a page without `ActualText` is what it was. `ActualText` and the structure tree are read with pdf-reader 2.12 and later, where they needed 2.16. For a PDF Stationery did not write, `untagged_text` and `structure` follow a form XObject the page draws, as `text` does. The PDFs written are unchanged.
+- Testing: `fields: true` reads what form fields show. A field's value is drawn by its widget's appearance, a form XObject of the annotation and no part of the page content, so `have_pdf_text("Astrid")` does not find the value of `text_field "name", value: "Astrid"`. `have_pdf_text("Astrid", fields: true)`, `have_pdf_text_on_page(1, "Astrid", fields: true)`, `assert_pdf_text pdf, "Astrid", fields: true`, `refute_pdf_text`, `Inspector#text(fields: true)` and `#page_texts(fields: true)` read the normal appearance of every widget with the page content, each where the widget is on its page: text fields (every line of `multiline:`, every cell of `comb:`), a select's value, a signature field's label, characters no font has from their `ActualText`, a field set in the standard Helvetica, in an encrypted document as in a plain one. A widget that is hidden (`Hidden`, `NoView`) is not read, and of a button's appearances the one its state names, never `Off`. It is an option and not the default, so no text a spec reads today changes: the text of a form with its fields is other text (more words, and other blank lines between those of the page content), which `not_to have_pdf_text` and a comparison of `Inspector#text` would notice. Without the option, the failure of `have_pdf_text` over a text that a field shows says so.
+- **Behaviour changes:** in `html`, the left and right of the `margin` shorthand indent a block, as CSS means them: `margin: 0 20px` drew no indent. Top and bottom draw what they drew. A `margin` declared after `margin-top` or `margin-bottom`, or by a more specific rule, takes them back, where the side always won. A negative margin on a floated `img` is drawn as none: it moved the image out of the flow, off the page when it was large, which nothing in a style may do. Beside a float, a list or a box without a background or a border is laid out at the full width with its lines around the float, where it was laid out at the width left beside it; a document with floats and such content may break its pages elsewhere. A render with `conformance :pdf_ua1` whose heading levels skip, or with a figure whose `alt:` is blank, now raises `ConformanceError` (it wrote a file veraPDF rejected); a tagged render reports both as warnings, so with `strict` it raises `WarningsError`. PDF/A alone asks for neither (level B does not ask for structure) and raises for neither. In a tagged render an `html` image with `alt=""` is an artifact, where it was a `Figure` with an empty `/Alt`. The message of `MissingAlt`, and with it the issue of the `ConformanceError`, ends in `(alt: false marks decoration)`. A `box` that ran over the page by the padding or border that closes it breaks a line or more earlier, and no longer reports an `Overflow`. Documents that are not tagged, and tagged documents that keep both rules and have no `<img alt="">`, are byte for byte what they were.
+
 ## 0.11.0 (2026-09-28)
 
 Text wrap around images, balanced columns, lossless WebP, a shaper hook for complex scripts, and far less memory for long documents.

data/README.md

@@ -83,7 +83,7 @@ renders them all, or render one with `stationery render examples/report.rb`.
 | `text { b "Total"; plain " due" }` | Styled runs in Ruby. Take a block argument (`{ \|t\| t.b @x }`) to keep your own `self`. |
 | `box(padding:, background:, border:, radius:, width:, height:, min_height:, overflow:, at:, link:, outset:, break_inside:, decoration:, rotate:, shadow:, float:, margin:) { }` | A container. Moves to the next page whole when it fits there and continues across pages when it does not; `break_inside: :auto` splits it at any page break, `:avoid` never splits it. At a cut, `decoration: :slice` (default) drops the padding and border, `:clone` keeps the padding. `overflow: :truncate` or `:shrink_to_fit` for fixed heights; a fixed `height:` never splits. `min_height:` is a floor that still splits: the first fragment keeps as much of it as the page holds, the next carries the rest (not combinable with `height:`). `at: [x, y]` pins it to a page position. `link:` makes the whole box clickable. `outset:` bleeds the background past the box (e.g. into the page margins). `rotate: -3` turns the painted box around its centre (layout box unchanged, never splits; a `link:` keeps its unrotated rectangle). `shadow: true` or `{ offset: [0, 4], blur: 8, color:, opacity: 0.15 }` paints a soft drop shadow under it, taking no space. `overflow: :hidden` clips the content to the rounded outline. `float: :left` or `:right` with a `width:` takes it to that side, `margin:` away from the text that wraps beside it: see [Floats](#floats). |
 | `row(gap:, align:, break_inside:) { column(width:) { } }` | Columns side by side. `width:` is points, a fraction (`0.5`), `:auto` or `nil` (equal share). Splits across pages like a box, every column at once; a row with a fixed-height column never splits; columns with `min_height:` do. |
-| `columns(count:, gap:, balance:, rule:) { }` | One flow poured through `count` columns, newspaper style: column 1 top to bottom, then column 2. Breaks where a page would (between lines with `orphans:`/`widows:`, never inside `break_inside: :avoid`, `keep_with_next` honoured). `balance: true` (default) ends the columns at nearly the same height where the content ends; `false` fills each before the next. Continues across pages; `page_break` inside ends the page; `rule: true \| { color:, width: }` draws a line between columns. |
+| `columns(count:, gap:, balance:, rule:) { }` | One flow poured through `count` columns, newspaper style: column 1 top to bottom, then column 2. Breaks where a page would (between lines with `orphans:`/`widows:`, never inside `break_inside: :avoid`, `keep_with_next` honoured). `balance: true` (default) ends the columns at nearly the same height where the content ends and fills them evenly, what cannot be shared going to the earlier columns (ten lines in three columns are 4, 3 and 3); `false` fills each before the next. Continues across pages; `page_break` inside ends the page; `rule: true \| { color:, width: }` draws a line between columns. |
 | `table(rows, widths:, width:, header:, split_rows:, cell:) { \|t\| }` | Tables. Cells are strings, layout nodes, procs built with the DSL (`-> { image logo }`) or components. Style with `t.row(0)`, `t.rows(-1)`, `t.column(1)`, `t.columns(1..)`, chained, plus `t.zebra`. Header rows repeat after a page break. A cell may be `{ content:, colspan:, rowspan: }` plus any cell option; rows list only the cells they start, as in HTML, and pages never break through a rowspan. Spans are set in the rows, not through selections. A row taller than the page continues on the next page, cut through its cells, with the header repeated; `split_rows: true` cuts any row that reaches the page bottom instead of moving it whole. |
 | `image(path_or_io, width:, height:, fit:, align:, radius:, rotate:, max_ppi:, downscale:, float:, margin:)` | JPEG, PNG or lossless WebP, aspect preserved. `fit: [w, h]` scales to fit inside; `fit: :cover` fills `width:` × `height:` and crops around the centre. `radius:` rounds the corners; `rotate:` turns it (degrees, clockwise) without changing the space it takes. Drawn at more than twice `max_ppi:` (300) it is reported as oversized; `downscale: true` resamples a PNG or WebP to that resolution instead. |
 | `svg(source_or_path, width:, height:, color:, align:)` | Vector icons and drawings; `currentColor` takes `color:` (or the `color` an element sets). Linear and radial gradients (`fill="url(#id)"`, `href` chains, both gradient units); `text`/`tspan` in the document's fonts; `<style>` stylesheets (element, class, id and `*` selectors); `use`, `symbol` sprites and nested `svg` viewports (`viewBox`, `preserveAspectRatio`); `clipPath` (both `clipPathUnits`). |
@@ -136,7 +136,14 @@ text more                                       # around the pull quote
 - Text (paragraphs, headings, the text inside a `group` or an `html` block) wraps: every line takes
   the width left at its own top and is aligned and justified in it. A paragraph whose widest word
   does not fit beside the floats starts below them.
-- Anything else (a `box`, `row`, `columns`, `table`, list item, `rule`, `image`, `svg`, form field) is a block:
+- A list item and a `box` that paints nothing of its own wrap what they hold: they keep the full
+  width, and their lines are narrow beside the float and wide below it. That is a box without
+  `background:`, `border:`, `shadow:` or `link:` and without `width:`, `height:`, `rotate:`,
+  `overflow:` or `valign:`. Its padding lies under the float, as a block's does in CSS, so beside
+  the float its lines are the float's `margin:` away from it. A list item keeps its indent from the
+  float, with the marker beside its first line.
+- Anything else (a `box` with a background, a border or a size of its own, a `row`, `columns`, `table`,
+  `rule`, `image`, `svg`, form field) is a block:
   it goes beside the float in the width that is left, and keeps that width all the way down, when
   its own width (or the least its content takes) fits there; else it starts below the float. A
   `spacer` takes its height beside the float; a `page_break` ends the page and the float with it.
@@ -147,7 +154,8 @@ text more                                       # around the pull quote
 - Across pages a float never splits. When it does not fit what is left of the page, or the content
   after it could not start beside it there, it moves to the next page with that content. A
   paragraph beside a float splits between lines as always (`orphans:`, `widows:`); the lines carried
-  over are wrapped again at the full width, because the float stayed behind.
+  over are wrapped again at the full width, because the float stayed behind. So are those of a list
+  item and of a box.
 - In a tagged PDF the float is where it was written: an image is a `Figure`, a box has its `role:`.
 
 A line beside a float is taken to be as tall as a line of the paragraph's own style when its width
@@ -212,17 +220,19 @@ ignored and reported. At-rules are skipped, except that rules inside `@media pri
 | `text-align` | `left`, `center`, `right`, `justify` | paragraphs, headings, cells, images; inherited from a container |
 | `background-color` | as `color`, or `transparent` | `p`, `div` and other containers, `blockquote`, `pre`, `table`, `td`, `th` |
 | `padding`, `padding-top` … `padding-left` | one to four lengths in `px` or `pt` | the same |
-| `margin`, `margin-top`, `margin-bottom` | lengths in `px` or `pt`; top and bottom only, added to `gap:` | blocks |
+| `margin`, `margin-top` … `margin-left` | one to four lengths in `px` or `pt`: top and bottom are added to `gap:`, left and right indent the block. A negative margin is drawn as none | blocks, and a floated `img` |
 | `border` | `1px solid #ccc` in any order, `none` | `table` (every cell), `td`, `th` |
 | `width` | `px`, `pt`, `%`, `auto` | `img`, `table`, and `td`/`th` (column widths, when every cell of the first row has one) |
-| `float` | `left`, `right`, `none` | `img` only: the text that follows wraps beside it. Its `margin` (all four sides) is kept around it, else `styles: { img: { float_margin: 8 } }` towards the text |
+| `float` | `left`, `right`, `none` | `img` only: the text that follows wraps beside it. Its `margin`, with `margin-top` … `margin-left` over it, is kept around it, else `styles: { img: { float_margin: 8 } }` towards the text |
 | `page-break-before`, `page-break-after`, `break-before`, `break-after` | `always`, `page`, `auto` | blocks |
 | `page-break-inside`, `break-inside` | `avoid`, `auto` | blocks |
 | `column-count`, `columns` | a number of columns, `auto` (a column width is not read) | `div` and other containers, `p`, headings, lists, tables, `blockquote`, `pre` |
 | `column-gap` | a length in `px` or `pt`, `normal` | the same |
 
+`margin` and its sides are read in the order of the cascade: a side wins over a `margin` declared
+before it or by a lesser rule, and a `margin` takes back the sides declared before it.
 `<font color size>`, `<center>` and `<img align="left|right">` (a float) are read the same way.
-Everything else (`display`, `float` on anything but an image, `position`, `font-family`, `line-height`, `em` lengths outside `font-size`, `url()` values,
+Everything else (`display`, `float` on anything but an image, `position`, `font-family`, `line-height`, `em` lengths outside `font-size`, `auto` margins, a negative `margin-left` or `margin-right`, `url()` values,
 inline backgrounds) is ignored and named in the `UnsupportedCss` warning, so `strict` catches
 content that expects more than this. No value is ever fetched: `url()` and `@import` are dropped.
 
@@ -347,6 +357,10 @@ signature_field "signature", label: "Signature of the applicant"
   signer, unless `sign field:` signs it (see [Digital signatures](#digital-signatures)).
 - `document.fields` returns `{ name => value }` for the last render (a check box's value is `true` or
   `false`, an unchecked radio group's and a signature field's `nil`). Encrypted documents keep their fields fillable.
+- In tests, `document.fields` is what the form was filled with, and `have_pdf_text("Astrid", fields:
+  true)` or `assert_pdf_text pdf, "Astrid", fields: true` finds what a field shows on the page. A
+  value is drawn by its widget and is no part of the page content, so the text leaves it out
+  without `fields: true` (see [Testing](#testing)).
 
 ## Components
 
@@ -481,7 +495,9 @@ and across page breaks: a paragraph continued on the next page stays one `P`.
 - `table_of_contents` is `TOC` > `TOCI` > `Link` (the title and its annotation) and `Reference` (the
   page number).
 - `html`/`markdown` tag headings `H1`–`H6` (with or without `bookmarks: true`) and block quotes
-  `BlockQuote`, and give images their `alt`.
+  `BlockQuote`, and give images their `alt`. In `html`, `<img alt="">` is decoration as `alt: false`
+  is (an `<img>` without the attribute is a description missing). Markdown has no way to say so:
+  `![](photo.png)` is a description missing, and decoration goes through `html` or `image`.
 - Headers, footers and page templates are pagination artifacts; backgrounds, borders and rules drawn
   outside any element are layout artifacts.
 - `metadata lang:` writes the catalog's `/Lang`; the title is shown instead of the file name.
@@ -489,8 +505,15 @@ and across page breaks: a paragraph continued on the next page stays one `P`.
   `dc:title`, `dc:creator`, `dc:description`, `dc:subject`, `dc:language`, the `xmp:` dates and
   `pdf:Producer`. PDF/A and PDF/UA identification lives there (see
   [PDF/A and PDF/UA](#pdfa-and-pdfua)); `metadata xmp: false` or `to_pdf(xmp: false)` leaves it out.
-- An image or drawing without `alt:` (`Warnings::MissingAlt`) and a missing `lang`
-  (`Warnings::MissingLanguage`) are warnings, so `strict` catches them.
+- An image or drawing without `alt:`, or with a blank one (`alt: ""`, whitespace alone, which
+  veraPDF would accept), is a `Warnings::MissingAlt`; `alt: false` is how decoration is marked.
+- A heading level that is skipped is a `Warnings::SkippedHeading` (`level`, `allowed`, `page`): the
+  first heading is `heading: 1` and a heading is at most one level below the heading before it
+  (`1`, then `3` skips `2`). Going back up is free (`3`, then `1`). Headings are read in the order of
+  the structure tree, inside sections, lists, table cells, columns and floats; those of headers,
+  footers and page templates are artifacts and do not count.
+- A missing `lang` is a `Warnings::MissingLanguage`. All three are warnings, so `strict` catches them,
+  and `conformance :pdf_ua1` raises on the first two.
 - Untagged documents (the default) are written exactly as before.
 
 Check the tree in tests with `have_structure` and `have_tagged_content` (see [Testing](#testing)):
@@ -536,7 +559,10 @@ mislabelled: `ArgumentError` for options that contradict the level, `Stationery:
 - **PDF/UA-1** (ISO 14289): turns `tagged` on, needs `metadata title:` and `lang:`, writes
   `pdfuaid:part`, shows the title in the viewer, orders tabs by structure (`/Tabs /S`) and gives
   every link annotation a description (`/Contents`: the URL, or the target page). A figure without
-  `alt:` raises; mark decoration with `alt: false`. Encryption is allowed.
+  `alt:` or with a blank one raises (7.3); mark decoration with `alt: false`, or `<img alt="">` in
+  `html`. A heading level that is skipped raises (7.4.2): the first heading is `heading: 1`, and a
+  heading is at most one level below the heading before it. PDF/A alone asks for neither.
+  Encryption is allowed.
 - Combined, the XMP packet also describes the `pdfuaid` schema to PDF/A (`pdfaExtension:schemas`).
 - Interactive form fields are allowed: their appearances draw with embedded fonts and paths, every
   field has a `/TU`, and `NeedAppearances` and ZapfDingbats are left out. Only a field made without
@@ -1038,8 +1064,8 @@ The limits of a hook:
 - Vertical advances are not read: text runs horizontally.
 - A reader that takes `ActualText` for the text (the gem's `Inspector`) gets it as written. poppler
   (`pdftotext` 26.09) and MuPDF (1.28) run their own reordering over it and return a right-to-left
-  stretch reversed. pdf-reader, and so `Inspector#text`, drops a `Span` whose first glyph has no
-  advance (a mark drawn first); `Inspector#structure` does not.
+  stretch reversed. pdf-reader's own `Page#text` drops a `Span` whose first glyph has no advance (a
+  mark drawn first); the `Inspector` does not.
 
 [`examples/shaping/harfbuzz_shaper.rb`](https://github.com/zoolutions/stationery/blob/main/examples/shaping/harfbuzz_shaper.rb)
 is an adapter for HarfBuzz through the [`harfbuzz-ruby`](https://github.com/ydah/harfbuzz) gem
@@ -1073,6 +1099,7 @@ RSpec.describe InvoicePdf do
 
   it { is_expected.to have_pdf_text("Invoice INV-7") }
   it { is_expected.to have_pdf_text_on_page(2, /Total €[\d ,]+/) }
+  it { is_expected.to have_pdf_text("Astrid Lindqvist", fields: true) } # with what the form fields show
   it { is_expected.to have_page_count(2) }
   it { is_expected.to have_pdf_link("mailto:hello@acme.test") }
   it { is_expected.to have_image_count(1) }
@@ -1100,6 +1127,7 @@ class InvoicePdfTest < Minitest::Test
 
     assert_pdf_text pdf, "Invoice INV-7"
     refute_pdf_text pdf, "DRAFT"
+    assert_pdf_text pdf, "Astrid Lindqvist", fields: true
     assert_page_count pdf, 2
     assert_pdf_link pdf, /acme\.test/
     assert_no_pdf_warnings pdf
@@ -1131,6 +1159,20 @@ read from its marked content: `[type, "text"]`, `[type, [children]]` (its own te
 between the children, as for a `P` holding a `Link`) or `[type]` when empty; a
 `Figure` reads as its alt text.
 
+`text` and `page_texts` are the text of the page content as pdf-reader lays it out, line by line. A
+`Span` with `ActualText` (a stretch a shaper reordered, characters no font has) reads as that text,
+once, whatever glyphs it shows.
+
+A form field's value is not page content: its widget draws it, so `have_pdf_text("Astrid")` does not
+find the value of a `text_field`. `fields: true` reads what the form fields show as well, each where
+it is on its page: `have_pdf_text("Astrid", fields: true)`, `have_pdf_text_on_page(1, "Astrid",
+fields: true)`, `assert_pdf_text pdf, "Astrid", fields: true`, `refute_pdf_text`, and
+`Inspector#text(fields: true)` and `#page_texts(fields: true)`. What is read is the normal appearance
+of every widget that is not hidden, in the state the widget is in, and never a button's `Off` state
+(the marks of a `checkbox` and a `radio` are paths and read as nothing). Without `fields: true` the
+text is what it always was, and the failure of `have_pdf_text` over a text that a field shows says
+so.
+
 ## Why not Prawn, Chrome or Typst?
 
 - **Prawn** is an imperative cursor API: every document does its own layout
@@ -1255,18 +1297,22 @@ Images are JPEG, PNG (non-interlaced) and lossless WebP (not lossy or animated W
 than 33 megapixels) and never fetched from a URL; a JPEG is embedded at its
 source resolution (only PNG and WebP can be downscaled), so an oversized one is reported, not resized. `html` reads a fixed subset of CSS (colours, sizes, weights, alignment, margins, padding, table
 borders and widths, page breaks; see [What CSS is read](#what-css-is-read)), not a layout
-engine's worth: no `display`, positioning, `font-family` or selectors with combinators, and floats
-for images only.
+engine's worth: no `display`, positioning, `font-family`, `auto` or negative margins or selectors
+with combinators, and floats for images only, with their `margin` around them.
 `markdown` reads no CSS, and raw HTML inside Markdown stays literal text.
 
 Layout: a box with a fixed `height:` never splits (use `min_height:` for a floor that can); a row
 splits only when every column can; a rotated box and a `stack` move to the next page whole.
-`columns` balances to the shortest height that holds the content and fills the columns in order
-(ten lines in three columns are 4, 4 and 2), has columns of one width, nothing spanning them
-(end the block, write the full-width content, start another) and no column break of its own; a
-spacer that lands at the top of a column keeps its height. Text
+`columns` balances to the shortest height that holds the content and fills the columns evenly
+from the first one on (ten lines in three columns are 4, 3 and 3): a column takes what fits the
+height balanced for it and the columns after it, so one that ends above a block that cannot
+split may stay shorter than the column after it. It has columns of one width, nothing spanning
+them (end the block, write the full-width content, start another) and no column break of its
+own; a spacer that lands at the top of a column keeps its height. Text
 wraps around floated images and boxes, along their rectangles, never along a shape; beside a float
-a table, box, row or list is a block of the width that is left, all the way down (see
+a table, a row, `columns` and a box with a background, a border or a size of its own are blocks of
+the width that is left, all the way down: a box is painted after the float written before it, so
+one that kept the full width would paint its background over the float (see
 [Floats](#floats)). Link and form-widget rectangles stay in page space inside `rotate`
 and `transform`, and `shadow:` is stacked rectangles, not a blur.
 

data/lib/stationery/css/stylesheet.rb

@@ -52,9 +52,17 @@ module Stationery
       def empty? = @rules.empty?
 
       def declarations(element)
+        rules_for(element).reduce({}) { |merged, rule| merged.merge(rule.declarations) }
+      end
+
+      # The declarations of every rule that matches, the one that wins last.
+      def matching(element) = rules_for(element).map(&:declarations)
+
+      private
+
+      def rules_for(element)
         @rules.select { |rule| rule.selector.match?(element) }
               .sort_by { |rule| [rule.selector.specificity, rule.index] }
-              .reduce({}) { |merged, rule| merged.merge(rule.declarations) }
       end
     end
   end

data/lib/stationery/html/css.rb

@@ -37,9 +37,13 @@ module Stationery
       # Properties read on text (inherited by everything inside the element).
       INLINE = %w[color font-size font-weight font-style text-decoration].freeze
       # Properties read on the block an element becomes.
-      BLOCK = %w[text-align background-color margin margin-top margin-bottom padding padding-top padding-right
-                 padding-bottom padding-left border width page-break-before page-break-after break-before
-                 break-after page-break-inside break-inside column-count column-gap columns].freeze
+      BLOCK = %w[text-align background-color margin margin-top margin-right margin-bottom margin-left padding
+                 padding-top padding-right padding-bottom padding-left border width page-break-before
+                 page-break-after break-before break-after page-break-inside break-inside column-count column-gap
+                 columns].freeze
+      # The sides `margin` sets, and the two that indent a block: a negative one is not drawn.
+      MARGINS = %w[margin-top margin-right margin-bottom margin-left].freeze
+      INDENTS = %w[margin-left margin-right].freeze
       FONT_SIZES = { "1" => 0.625, "2" => 0.8125, "3" => 1.0, "4" => 1.125, "5" => 1.5, "6" => 2.0,
                      "7" => 3.0 }.freeze
       KEYWORD_SIZES = { "xx-small" => 0.5625, "x-small" => 0.625, "small" => 0.8125, "medium" => 1.0,
@@ -79,9 +83,17 @@ module Stationery
       end
 
       # The declarations that apply to `element`: legacy attributes, then the
-      # stylesheet by specificity, then its inline style.
+      # stylesheet by specificity, then its inline style. A margin declared
+      # again stands where it was declared last, since `margin` and its sides
+      # are read in that order.
       def declarations(element)
-        legacy(element).merge(@sheet.declarations(element), CSS.declarations(element.attributes["style"]))
+        layers = [legacy(element), *@sheet.matching(element), CSS.declarations(element.attributes["style"])]
+        layers.each_with_object({}) do |layer, merged|
+          layer.each do |name, value|
+            merged.delete(name) if name.start_with?("margin")
+            merged[name] = value
+          end
+        end
       end
 
       # [marks, block]: the text marks the element's content inherits and the
@@ -149,8 +161,9 @@ module Stationery
         case name
         when "text-align" then read(name, value, block, :align) { align(value) }
         when "background-color" then read(name, value, block, :background) { color(value) }
-        when "margin" then read(name, value, block, :margin) { box(value) }
+        when "margin" then margin(value, block)
         when "padding" then read(name, value, block, :padding) { box(value) }
+        when *INDENTS then read(name, value, block, name.tr("-", "_").to_sym) { indent(value) }
         when /\A(margin|padding)-/ then read(name, value, block, name.tr("-", "_").to_sym) { points(value) }
         when "border" then read(name, value, block, :border) { border(value) }
         when "width" then read(name, value, block, :width) { width(value) }
@@ -244,6 +257,18 @@ module Stationery
         end
       end
 
+      # `margin` sets every side, so it takes back the sides declared before
+      # it; one with a value that is not read leaves them as they are.
+      def margin(value, block)
+        sides = read("margin", value, block, :margin) { box(value) }
+        MARGINS.each { |name| block.delete(name.tr("-", "_").to_sym) } if sides
+      end
+
+      def indent(value)
+        length = points(value)
+        length unless length&.negative?
+      end
+
       # One to four lengths as [top, right, bottom, left].
       def box(value)
         sides = value.split.map { |part| points(part) }

data/lib/stationery/html/tree_builder/blocks.rb

@@ -27,13 +27,13 @@ module Stationery
         ALIGN = /\A\s*(left|center|right|justify)\s*\z/i
         # What makes a container a block of its own instead of flattening into its parent.
         BOXED = %i[background padding padding_top padding_right padding_bottom padding_left margin margin_top
-                   margin_bottom break_before break_after keep_together columns].freeze
+                   margin_right margin_bottom margin_left break_before break_after keep_together columns].freeze
         # What a block of its own takes besides.
         WITH_BOX = %i[column_gap].freeze
         INHERITED = %i[align].freeze
         # What an image takes from its style, and what a floated one takes too.
         IMAGE = %i[width align].freeze
-        FLOATED = %i[width float margin margin_top margin_bottom].freeze
+        FLOATED = %i[width float margin margin_top margin_right margin_bottom margin_left].freeze
         EMPTY = {}.freeze
 
         def self.convert(root, css = Css.parse([])) = new(css).blocks_of(root, EMPTY, EMPTY)
@@ -129,11 +129,15 @@ module Stationery
         def image(attributes, style)
           return unless attributes["src"]
 
-          Rich::Image.new(src: attributes["src"], alt: attributes["alt"],
+          Rich::Image.new(src: attributes["src"], alt: description(attributes["alt"]),
                           width: dimension(attributes["width"]), height: dimension(attributes["height"]),
                           style: style.slice(*(style[:float] ? FLOATED : IMAGE)))
         end
 
+        # An alt that is there and empty is how HTML marks decoration (false,
+        # as `image alt: false`); one that is not there is a description missing.
+        def description(alt) = alt && !Tagging.blank?(alt) && alt
+
         def dimension(value) = value&.[](/\A\s*(\d+)/, 1)&.to_i
 
         def table(element, marks, inherited, style)

data/lib/stationery/layout/box/wrapping.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Layout
+    class Box < Node
+      # A box beside floats. One that paints nothing of its own and takes the
+      # width it is given is a block as CSS knows it: it keeps the full width
+      # of its flow and hands the floats to its content (`exclusions:`, from
+      # its own top), which wraps beside them and takes the full width below
+      # them. The content meets the floats inside the padding: padding that
+      # lies under a float is not added to it.
+      #
+      # Any other box is a block of the width the floats leave, all the way
+      # down: one with a background, a border, a shadow or a link, which
+      # would be painted over a float that was painted before it, and one
+      # with a width or a height of its own, a rotated or a clipped one, or
+      # one that places its content by `valign:`.
+      module Wrapping
+        def wraps? = !sized? && !painted? && @content.wraps?
+
+        private
+
+        def sized?
+          !(@width_spec.nil? && @height.nil?) || !@rotate.zero? || @overflow != :visible || @valign != :top
+        end
+
+        def painted? = !(@background || @border || @shadow || @link).nil?
+
+        # Where the content goes beside floats, and what they take from it
+        # there: measure, split and paint place it by this one slot. nil
+        # without floats.
+        def beside(width, exclusions)
+          return unless exclusions
+
+          top, right, _bottom, left = insets
+          Flow::Placement::Slot.new(top:, left:, width: inner_width(width),
+                                    exclusions: exclusions.inset(top:, right:, left:))
+        end
+
+        def content_height(width, exclusions)
+          slot = beside(width, exclusions)
+          slot ? slot.measure(@content) : @content.measure(inner_width(width))
+        end
+
+        def split_content(width, height, fresh, exclusions)
+          slot = beside(width, exclusions)
+          slot ? slot.split(@content, height, fresh:) : @content.split(inner_width(width), height, fresh:)
+        end
+      end
+    end
+  end
+end

data/lib/stationery/layout/box.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "box/wrapping"
+
 module Stationery
   module Layout
     # A container with padding, background, border and corner radius. A box
@@ -15,6 +17,8 @@ module Stationery
     # never splits); `shadow:` paints a soft drop shadow under it, taking no
     # space; `overflow: :hidden` clips the content to the rounded outline.
     class Box < Node
+      include Wrapping
+
       BORDER = { width: 1, color: "#000000", sides: %i[top right bottom left] }.freeze
       SHADOW = { offset: [0, 4], blur: 8, color: "#000000", opacity: 0.15 }.freeze
       SHADOW_LAYERS = 8
@@ -68,16 +72,16 @@ module Stationery
 
       def prefer_whole? = break_inside.nil? && splittable?
 
-      def split(width, height, fresh: false)
-        return [self, nil] if measure(width) <= height + EPSILON
+      def split(width, height, fresh: false, exclusions: nil)
+        return [self, nil] if measure(width, exclusions:) <= height + EPSILON
 
         cut = @open | [:bottom]
         available = height - vertical(cut)
-        head, tail = @content.split(inner_width(width), available, fresh:)
+        head, tail = split_content(width, available, fresh, exclusions)
         return [nil, self] unless head
-        return [with_content(head), nil] unless tail || @min_height.to_f > height + EPSILON
+        return closed(width, height, head, fresh, exclusions) unless tail || @min_height.to_f > height + EPSILON
 
-        fragments(width, height, head, tail || Flow.new, cut)
+        fragments(width, height, head, tail || Flow.new, cut, exclusions)
       end
 
       # An empty continuation: open at the top, without a floor.
@@ -87,19 +91,24 @@ module Stationery
       def with_content(content, open = @open) = dup.reopen(content, open)
       def with_open(*sides) = with_content(@content, @open | sides)
 
-      def measure(width)
-        @height || memoize_by_width(width) { [@content.measure(inner_width(width)) + vertical, @min_height || 0].max }
+      def measure(width, exclusions: nil)
+        return @height if @height
+
+        memoize_by_width(exclusions ? [width, exclusions] : width) do
+          [content_height(width, exclusions) + vertical, @min_height || 0].max
+        end
       end
 
-      def paint(canvas, x, y, width, height = nil, valign: nil, debug_kind: :box, **)
-        height ||= measure(width)
+      def paint(canvas, x, y, width, height = nil, valign: nil, debug_kind: :box, exclusions: nil, **)
+        height ||= measure(width, exclusions:)
+        slot = beside(width, exclusions)
         canvas.rotate(@rotate, around: [x + (width / 2.0), y + (height / 2.0)]) do
           canvas.structure(@tag) do
             canvas.structure(@link_tag) do
               paint_shadow(canvas, x, y, width, height)
               paint_background(canvas, x, y, width, height)
               paint_border(canvas, x, y, width, height)
-              paint_content(canvas, x, y, width, height, valign || @valign)
+              slot ? slot.paint(@content, canvas, x, y) : paint_content(canvas, x, y, width, height, valign || @valign)
             end
           end
           paint_debug(canvas, Rect.new(x, y, width, height), debug_kind) if canvas.debug?
@@ -120,9 +129,26 @@ module Stationery
 
       def fragment(content, open, min_height) = dup.reopen(content, open, min_height)
 
-      def fragments(width, height, head, tail, cut)
+      # The content ends on this page. A head is open at the bottom, so the
+      # content was cut at the height less the top of the box alone: it fits
+      # with the box closed under it (what it dropped at the cut made the
+      # room), or the padding and border that close the box do not. Then the
+      # content is cut again with their room kept, and the last of it goes to
+      # the next page with them. Content that cannot be cut there moves whole;
+      # first on a fresh page it is kept as it is, and reported.
+      def closed(width, height, head, fresh, exclusions)
+        whole = with_content(head)
+        return [whole, nil] if whole.measure(width, exclusions:) <= height + EPSILON
+
+        head, tail = split_content(width, height - vertical, fresh, exclusions)
+        return fragments(width, height, head, tail, @open | [:bottom], exclusions) if head && tail
+
+        fresh ? [whole, nil] : [nil, self]
+      end
+
+      def fragments(width, height, head, tail, cut, exclusions)
         first = fragment(head, cut, @min_height && [@min_height, height].min).tap { |part| part.keep_with_next = nil }
-        rest = @min_height.to_f - first.measure(width)
+        rest = @min_height.to_f - first.measure(width, exclusions:)
         [first, fragment(tail, @open | [:top], rest.positive? ? rest : nil)]
       end
 

data/lib/stationery/layout/columns/leveller.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Layout
+    class Columns
+      # Fills balanced columns evenly. Columns filled in order at the balanced
+      # height leave the last one what is left over: ten lines in three
+      # columns are 4, 4 and 2. Here the first column keeps what fits the
+      # height, what it leaves is balanced through the columns after it, and
+      # so on down to the last two: 4, 3 and 3. What cannot be shared goes to
+      # the earlier columns.
+      #
+      # Every column is cut by Flow#split from what the one before it left,
+      # so the result is a pour like any other and the break rules hold in
+      # it. Fitting is not monotonic in the height, so nothing is assumed of
+      # that pour: the columns filled in order are kept unless it places
+      # everything, is exactly as tall as they are (what follows the block
+      # stays where it is), and has no later column taller than an earlier
+      # one where they have none. They are also kept when their first column
+      # cannot be cut again below other content (a child too tall for the
+      # page).
+      #
+      # Each level is one Balancer search with a column less, so levelling
+      # pours at most (count - 2) * (MAX_PROBES + 1) times and cuts a first
+      # column count - 2 times. Two columns are even as they are: the second
+      # takes what the first left.
+      class Leveller
+        # `limit` is the tallest a column may be.
+        def initialize(pour, limit: Float::INFINITY)
+          @pour = pour
+          @limit = limit
+        end
+
+        # `poured` is the balanced pour: the columns filled in order.
+        def call(poured)
+          return poured unless poured.complete? && @pour.count > 2
+
+          height = [@limit, poured.height(@pour.width)].min
+          first, rest = @pour.first(height)
+          return poured unless first && rest
+
+          levelled = after(first, rest, height)
+          better?(levelled, poured) ? levelled : poured
+        end
+
+        private
+
+        def after(first, rest, height)
+          poured = self.class.new(rest, limit: height).call(Balancer.new(rest, limit: height).call)
+          Poured.new(columns: [first, *poured.columns], rest: poured.rest)
+        end
+
+        def better?(levelled, poured)
+          levelled.complete? && (levelled.height(@pour.width) - poured.height(@pour.width)).abs <= EPSILON &&
+            (descending?(levelled) || !descending?(poured))
+        end
+
+        def descending?(poured)
+          heights = poured.columns.map { |column| column.measure(@pour.width) }
+          heights.each_cons(2).all? { |taller, shorter| shorter <= taller + EPSILON }
+        end
+      end
+    end
+  end
+end

data/lib/stationery/layout/columns/pour.rb

@@ -41,6 +41,13 @@ module Stationery
           end
           Poured.new(columns:, rest:)
         end
+
+        # [the first column at `height`, the pour of what it leaves through
+        # the columns after it (nil when it leaves nothing)].
+        def first(height)
+          head, tail = @flow.split(@width, height)
+          [head, tail && self.class.new(tail, @width, @count - 1)]
+        end
       end
     end
   end