stationery 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dc2011ee51b715eb946943e60d0512157f2215acd871133433c6edf4f81bb9a9
-  data.tar.gz: a5a9c654b4c415ab77ba005eb228ba67fae05f87af1adeb39871ccb3353a00a3
+  metadata.gz: dab8be06e23e27d74ddd2ec627bc34923a79a9c0cb5fe40da55f43bdcb81e337
+  data.tar.gz: a7f90eadef2004318933e8a65cd1f86841c5b9bfc4cba8ff6191b2f96946b8e5
 SHA512:
-  metadata.gz: 239ad178900f1cce55589e1e6882fda2e713631df0a0d732945eefd0d8df762e9baa0a44efde7ea13fa643e6ee0dd038594886cd09cc14aac2cb0486ef88f05b
-  data.tar.gz: 0ac757cdf6a15a654c83b26fa80c5be99e20e9e28e09653c31c299627a5c46c5cfb3965cfa58e58c2c6ade241c3b86f07fbe37a761ad2738e09207ce0711c200
+  metadata.gz: ce40fc76233a4c6ba0ca455c9c80ac3a651832ba86ab7003c8f907b2abd8291cbe0a7421302b4a6762e876df284ebe98ed862017eaed7cb4854d609e3fa557ec
+  data.tar.gz: b1c1928f47210a8b29586f73881b8430978c644a2ea7489fab251796b7192213057a414c3145c47502fa267e3c857d5b581f91d8bf2bca394e61384844fc21d8

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.5.0 (2026-09-27)
+
+Rotated, overlapping, cropped photos (the collage look), and fixes from the first weeks of use.
+
+- `stack { … }` and `layer(top:, right:, bottom:, left:, width:, height:, **box) { … }`: overlapping content. The stack's ordinary children set its height; each layer is a box placed with CSS-inset semantics relative to the stack (points, or fractions of the stack's width/height; negative insets overhang) and takes no flow height. A stack moves to the next page whole. `examples/postcard.rb` shows the collage: a cover photo with two tilted, framed, shadowed photos over its corners.
+- `box(rotate:)` turns a box clockwise around its centre without moving its layout rectangle (a rotated box never splits); `box(shadow: true | { offset:, blur:, color:, opacity: })` paints a soft drop shadow as stacked rounded rectangles at fading opacity, an artifact taking no space; `box(overflow: :hidden)` clips the content to the rounded outline. `column` takes the same options.
+- `image(fit: :cover, width:, height:)` scales up to fill the box and clips the excess around the centre; `image(radius:)` clips to rounded corners; `image(rotate:)` turns the painted image around its centre. Sizing, measuring and the tagged `Figure` bbox are unchanged; plain images are byte-for-byte as before.
+- `Canvas#rotate(degrees, around: [x, y]) { … }` and `Canvas#transform([a, b, c, d, e, f]) { … }` wrap a block in a `cm` transform given in top-left space, clockwise like CSS `rotate()`. Link and form-widget rectangles are annotations in page space, so they stay unrotated.
+- `html`/`markdown` write link annotations only for `http`, `https`, `mailto` and `tel` hrefs (and `#anchor`); anything else (`javascript:`, `data:`, a relative path) keeps its text without a link and is reported as a `Warnings::DroppedLink`. `links: %w[http https]` changes the list, `links: :all` keeps every href from a trusted source.
+- `html`/`markdown` `styles:` take `ul:` and `ol:` (`gap:`, `indent:`, `marker_gap:`, `marker_color:`, plus `style:` for `ul` and `format:`/`suffix:` for `ol`), passed straight to the list elements, so dense documents can tighten the 4pt item gap.
+- Whitespace no font has (an ideographic space U+3000, a figure space U+2007, a narrow no-break space U+202F, thin and hair spaces, …) is drawn as a blank of the character's conventional width instead of `.notdef`, and no longer reports `MissingGlyph`; font fallback keeps every Unicode White_Space character with its neighbours.
+- Testing: the RSpec matchers include `RSpec::Matchers::Composable`, so `have_pdf_text(…).and have_bookmark(…)`, `.or` and use inside `all`/`include` work. `Inspector#lang` reads the catalog `/Lang`; `have_pdf_language("de")` and `assert_pdf_language` assert it.
+- Previews: `Stationery::Preview#around_render(name, params)` wraps both the preview method and `to_pdf`, for an I18n locale or `CurrentAttributes` that must be in effect while the document renders (`?locale=de`); `Preview#to_pdf(name, params, debug:)` is the entry point the previews controller uses.
+
 ## 0.4.0 (2026-09-27)
 
 Interactive forms and tagged (accessible) PDF.

data/README.md

@@ -70,7 +70,7 @@ InvoicePdf.new(invoice).to_pdf          # => "%PDF-1.7…" (binary String)
 InvoicePdf.new(invoice).to_pdf("a.pdf") # also writes a path or an IO
 ```
 
-`examples/` has a complete, runnable invoice, annual report, letter, packing slip and fillable form; `bundle exec rake examples`
+`examples/` has a complete, runnable invoice, annual report, letter, packing slip, fillable form and postcard collage; `bundle exec rake examples`
 renders them all, or render one with `stationery render examples/report.rb`.
 
 ## Elements
@@ -80,12 +80,14 @@ renders them all, or render one with `stationery render examples/report.rb`.
 | `text(string, **style)` | A paragraph. Plain strings are literal. |
 | `text(string, markup: true)` | Reads `<b> <i> <u> <strikethrough> <sub> <sup> <br> <color rgb=""> <font size="" name=""> <link href="">`; decodes numeric and HTML 4 named entities. |
 | `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:) { }` | 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). |
+| `box(padding:, background:, border:, radius:, width:, height:, min_height:, overflow:, at:, link:, outset:, break_inside:, decoration:, rotate:, shadow:) { }` | 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. |
 | `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. |
 | `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:)` | JPEG or PNG, aspect preserved. |
+| `image(path_or_io, width:, height:, fit:, align:, radius:, rotate:)` | JPEG or PNG, 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. |
 | `svg(source_or_path, width:, height:, color:, align:)` | Vector icons and drawings; `currentColor` takes `color:`. 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). |
 | `wrap(gap:, row_gap:, align:) { }` | Children side by side at their own widths, wrapping onto new rows (chips, tags). |
+| `stack(gap:, align:) { }` | A base with layers painted over it: ordinary children set the height, `layer` children float over them and take no space. Moves to the next page whole. |
+| `layer(top:, right:, bottom:, left:, width:, height:, **box) { }` | Inside `stack`: a box placed by insets from the stack's edges, in points or as a fraction (`0.4`, `1/3r`) of its width/height; negative insets overhang. Takes every box option (`rotate:`, `shadow:`, `radius:`, …). |
 | `ul(style:, gap:, indent:, marker_gap:, marker_color:) { li "…" }` | Bulleted list. `style:` is `:disc`, `:circle`, `:square`, `:dash` or any String; unstyled nested lists cycle disc → circle → square. Any node added inside (not only `li`) becomes an item. Items split across pages; the marker stays with the first line. |
 | `ol(format:, start:, suffix:, gap:, indent:, marker_gap:, marker_color:) { }` | Numbered list. `format:` is `:decimal`, `:alpha`, `:upper_alpha`, `:roman`, `:upper_roman` or a Proc `(n) -> String`; `suffix:` defaults to `"."`. Markers right-align so bodies line up. |
 | `li(string, **style)`, `li(gap:) { }` | A list item: a paragraph, or a block of any elements (including nested lists). |
@@ -93,14 +95,14 @@ renders them all, or render one with `stationery render examples/report.rb`.
 | `group(keep_together: true, align:) { }` | Keep a block on one page. |
 | `keep_with_next: true \| points` | On `text`, `box` or `group`: never end a page with this node; with a number, keep at least that many points of what follows with it. |
 | `text_style(**style) { }` | Default text style for a block. |
-| `canvas(height:) { \|canvas, rect\| }` | Draw directly: rectangles, rounded rectangles, circles, lines, Bézier paths, clipping, images, links. |
+| `canvas(height:) { \|canvas, rect\| }` | Draw directly: rectangles, rounded rectangles, circles, lines, Bézier paths, clipping, images, links; `rotate(degrees, around:) { }` and `transform([a, b, c, d, e, f]) { }` blocks. |
 | `text_field(name, value:, width:, height:, multiline:, max_length:, comb:, read_only:, required:, font_size:, border:, background:, radius:, at:)` | An interactive text input (AcroForm). `width:` is `:full` or points; dotted names (`"address.city"`) group fields. See [Forms](#forms). |
 | `checkbox(name, checked:, size:, label:, at:)` | An interactive check box, with an optional label drawn to its right. |
 | `radio(name, value, checked:, size:, label:, at:)` | One choice of a radio group: radios sharing `name` form one field whose value is the checked `value`. |
 | `select(name, options:, value:, width:, height:, editable:, at:)` | A drop-down (combo box); `editable: true` also accepts typed values. |
 | `signature_field(name, width:, height:, label:, at:)` | An empty signature field for the signer to fill, drawn as a rule over the label. |
-| `html(source, styles:, gap:, images:, base_path:, bookmarks:)` | Rich text from HTML (ActionText/Trix, CMS output): paragraphs, headings, lists, quotes, code, rules, tables, images, inline marks and links. See [HTML and Markdown](#html-and-markdown). |
-| `markdown(source, styles:, gap:, images:, base_path:, bookmarks:)` | The same from CommonMark (plus GFM tables and strikethrough). |
+| `html(source, styles:, gap:, images:, base_path:, bookmarks:, links:)` | Rich text from HTML (ActionText/Trix, CMS output): paragraphs, headings, lists, quotes, code, rules, tables, images, inline marks and links. See [HTML and Markdown](#html-and-markdown). |
+| `markdown(source, styles:, gap:, images:, base_path:, bookmarks:, links:)` | The same from CommonMark (plus GFM tables and strikethrough). |
 
 Text style options: `font`, `size`, `weight` (`:regular`, `:bold`), `style` (`:italic`), `color`,
 `letter_spacing`, `underline`, `strikethrough`, `link`, `opacity`, `kerning` (default `true`), `ligatures` (default `true`), `align` (`:left`, `:center`, `:right`, `:justify`), `leading`.
@@ -128,7 +130,12 @@ end
   points; bold, `keep_with_next`), `p`, `a` (colour, underline), `code` (`font:`; register a
   monospace family for inline and block code, otherwise the text font is used), `pre` and
   `blockquote` (box options), `hr` (rule options), `table` (`cell:` options, `header:` text style),
-  `li` (text style) and `img` (`max_width:`).
+  `ul` and `ol` (list options: `gap:`, `indent:`, `marker_gap:`, `marker_color:`, plus `style:` for
+  `ul` and `format:`/`suffix:` for `ol`), `li` (text style) and `img` (`max_width:`).
+- Links are written only for `http`, `https`, `mailto` and `tel` hrefs (and `#anchor`); anything
+  else (`javascript:`, `data:`, a relative path) keeps its text without a link and is reported as a
+  `DroppedLink` warning. `links: %w[http https]` changes the list, `links: :all` keeps every href
+  from a trusted source.
 - `gap:` spaces the blocks (default 6); `bookmarks: true` adds h1–h3 to the PDF outline.
 
 ### Links, bookmarks and table of contents
@@ -393,6 +400,21 @@ that take an argument (`?id=42`); `?debug=1` passes `debug: true` to `to_pdf`
 when the document supports it. Preview files are re-`load`ed on every request,
 so edits show up on refresh.
 
+Anything that must be in effect *while* the document renders (an I18n locale,
+`CurrentAttributes`, a time zone) goes in `around_render`, which wraps both the
+preview method and `to_pdf`:
+
+```ruby
+class FlyerPdfPreview < Stationery::Preview
+  def month(params) = FlyerPdf.new(Event.upcoming)
+
+  def around_render(_name, params) = I18n.with_locale(params.fetch("locale", I18n.default_locale)) { yield }
+end
+```
+
+`/rails/stationery/previews/flyer_pdf/month?locale=de` renders in German.
+`Preview#to_pdf(name, params, debug:)` is the same entry point for your own code.
+
 The gem has no Rails dependency; the Railtie loads only inside a Rails app.
 
 ## CLI
@@ -481,9 +503,12 @@ end
 ```
 
 Spaces, joiners, variation selectors and combining marks stay with the
-character before them. A glyph no font has is drawn as the family's
-`.notdef` and reported as a `Warnings::MissingGlyph` counting each drawn
-occurrence (so `strict` raises on it). Fallback covers every text element,
+character before them. Whitespace no font has (an ideographic space U+3000,
+a figure space, a narrow no-break space, …) is drawn as a blank of the
+character's conventional width, never as `.notdef`. Any other glyph no font
+has is drawn as the family's `.notdef` and reported as a
+`Warnings::MissingGlyph` counting each drawn occurrence (so `strict` raises
+on it). Fallback covers every text element,
 table cell, list marker, table of contents entry and page template text;
 direct `canvas.text` calls draw with the font they are given.
 
@@ -534,6 +559,7 @@ RSpec.describe InvoicePdf do
   it { is_expected.to have_pdf_link("mailto:hello@acme.test") }
   it { is_expected.to have_image_count(1) }
   it { is_expected.to have_no_warnings }
+  it { is_expected.to have_pdf_language("en") } # the catalog /Lang from `metadata lang:`
   it { is_expected.to have_tagged_content } # a tagged PDF with every text tagged or an artifact
   it { is_expected.to have_structure([[:Document, [[:H1, "Invoice"], [:P, "INV-7"]]]]) }
 end
@@ -554,6 +580,7 @@ class InvoicePdfTest < Minitest::Test
     assert_page_count pdf, 2
     assert_pdf_link pdf, /acme\.test/
     assert_no_pdf_warnings pdf
+    assert_pdf_language pdf, "en"
     assert_tagged_content pdf
     assert_pdf_structure pdf, [[:Document, [[:H1, "Invoice"], [:P, "INV-7"]]]]
   end
@@ -562,9 +589,10 @@ end
 
 The matcher names carry a `pdf_` prefix so they never clash with Capybara's
 `have_text` and `have_link`. `have_bookmark` / `assert_bookmark` match outline
-titles. For anything else, `Stationery::Testing::Inspector.new(subject)`
+titles. The RSpec matchers compose like the built-ins: `.and` / `.or`, and inside
+`all`, `include` or `match`. For anything else, `Stationery::Testing::Inspector.new(subject)`
 exposes `text`, `page_texts`, `page_count`, `links`, `internal_links`,
-`image_count`, `bookmarks`, `metadata`, `warnings`, `tagged?`, `untagged_text` and
+`image_count`, `bookmarks`, `metadata`, `lang`, `warnings`, `tagged?`, `untagged_text` and
 `structure` — a tagged PDF's structure tree as nested arrays, each element's text
 read from its marked content: `[type, "text"]`, `[type, [children]]` (its own text
 between the children, as for a `P` holding a `Link`) or `[type]` when empty; a

data/lib/stationery/builder.rb

@@ -62,6 +62,17 @@ module Stationery
       @containers.pop
     end
 
+    # Whether nodes are being added straight into a stack's flow (where a
+    # layer may go).
+    def in_stack? = stacks.include?(@containers.last)
+
+    def stack(flow, &)
+      stacks << flow
+      within(flow, &)
+    ensure
+      stacks.delete(flow)
+    end
+
     def with_text(**overrides)
       @text << text_defaults.merge(overrides.compact)
       yield
@@ -70,6 +81,7 @@ module Stationery
     end
 
     def text_defaults = @text.last
+    def stacks = @stacks ||= []
     def outline = @outline ||= Outline.new
     def warnings = @book.warnings
 

data/lib/stationery/canvas/debug.rb

@@ -9,7 +9,7 @@ module Stationery
       DEBUG_COLORS = {
         box: "#E11D48", padding: "#E11D48", column: "#2563EB", cell: "#16A34A", cell_padding: "#16A34A",
         flow: "#9CA3AF", positioned: "#DB2777", image: "#0D9488", page: "#06B6D4", region: "#0EA5E9",
-        field: "#7C3AED"
+        field: "#7C3AED", stack: "#F59E0B"
       }.freeze
       DEBUG_DASHES = { padding: [2, 2], cell_padding: [2, 2], flow: [1, 2] }.freeze
 

data/lib/stationery/canvas.rb

@@ -31,6 +31,32 @@ module Stationery
       emit("Q")
     end
 
+    # Paints the block with the affine `matrix` [a, b, c, d, e, f] applied,
+    # given in top-left space (x' = ax + cy + e, y' = bx + dy + f with y
+    # growing downwards). Annotations (`link`, `widget`) keep their
+    # untransformed page rectangles.
+    def transform(matrix)
+      a, b, c, d, e, f = matrix
+      height = @page.height
+      pdf_matrix = [a, -b, -c, d, (c * height) + e, height - (d * height) - f]
+      save do
+        emit("#{pdf_matrix.map { |v| num(v) }.join(" ")} cm")
+        yield self
+      end
+    end
+
+    # Paints the block rotated `degrees` clockwise around the page point
+    # `around` ([x, y]), as CSS `rotate()` turns an element. Zero just yields.
+    def rotate(degrees, around:, &)
+      return yield self if degrees.zero?
+
+      radians = degrees * Math::PI / 180
+      cos = Math.cos(radians)
+      sin = Math.sin(radians)
+      cx, cy = around
+      transform([cos, sin, -sin, cos, cx - (cx * cos) + (cy * sin), cy - (cx * sin) - (cy * cos)], &)
+    end
+
     def clip(x, y, w, h, radius: 0)
       save do
         emit(Path.new(self).rounded_rect(x, y, w, h, radius).to_s, "W n")

data/lib/stationery/elements/rich.rb

@@ -5,16 +5,18 @@ module Stationery
   module Elements
     # HTML such as ActionText's `record.body.to_s`. `images:` resolves an
     # image src to a path or IO (nil skips it); otherwise it is read from
-    # under `base_path:`. Remote images are never fetched.
-    def html(source, styles: {}, gap: 6, images: nil, base_path: nil, bookmarks: false)
+    # under `base_path:`. Remote images are never fetched. `links:` lists the
+    # URL schemes written as links (default http, https, mailto and tel;
+    # `#anchor` always is); `:all` keeps every href for trusted sources.
+    def html(source, styles: {}, gap: 6, images: nil, base_path: nil, bookmarks: false, links: nil)
       require_relative "../html/document"
-      rich(HTML.parse(source.to_s), styles:, gap:, images:, base_path:, bookmarks:)
+      rich(HTML.parse(source.to_s), styles:, gap:, images:, base_path:, bookmarks:, links:)
     end
 
     # CommonMark (plus GFM tables and strikethrough); options as for html.
-    def markdown(source, styles: {}, gap: 6, images: nil, base_path: nil, bookmarks: false)
+    def markdown(source, styles: {}, gap: 6, images: nil, base_path: nil, bookmarks: false, links: nil)
       require_relative "../markdown/document"
-      rich(Markdown.parse(source.to_s), styles:, gap:, images:, base_path:, bookmarks:)
+      rich(Markdown.parse(source.to_s), styles:, gap:, images:, base_path:, bookmarks:, links:)
     end
 
     private

data/lib/stationery/elements.rb

@@ -51,6 +51,29 @@ module Stationery
       @_builder.add(node)
     end
 
+    # A base with layers painted over it: every ordinary child is part of the
+    # base (which sets the height), every `layer` floats over it relative to
+    # the stack's rectangle, taking no space. The stack moves to the next
+    # page whole. Layers may overhang; wrap the stack in `box(padding:)` to
+    # keep them inside the page.
+    def stack(gap: 0, align: nil, &)
+      flow = Layout::Flow.new([], gap:, align: align || :left)
+      @_builder.stack(flow) { align ? @_builder.with_text(align:) { yield_content(&) } : yield_content(&) }
+      layers, base = flow.children.partition { |child| child.is_a?(Layout::Layer) }
+      @_builder.add(Layout::Stack.new(flow.with_children(base), layers))
+    end
+
+    # A box placed over the enclosing `stack` by insets from its edges:
+    # points, or a fraction (`0.4`, `1/3r`) of the stack's width or height;
+    # negative values overhang. Takes every box option (`rotate:`, `shadow:`,
+    # `padding:`, `background:`, `radius:`, `height:`, …).
+    def layer(top: nil, right: nil, bottom: nil, left: nil, width: nil, height: nil, align: nil, gap: 0, **, &)
+      raise ArgumentError, "layer must be inside a stack" unless @_builder.in_stack?
+
+      box = Layout::Box.new(container(align:, gap:, &), **)
+      @_builder.add(Layout::Layer.new(box, top:, right:, bottom:, left:, width:, height:))
+    end
+
     # Children kept in one vertical group; `keep_together: true` moves the
     # whole group to the next page rather than splitting it.
     def group(gap: 0, align: nil, keep_together: false, keep_with_next: nil, anchor: nil, bookmark: nil, &)
@@ -97,7 +120,8 @@ module Stationery
       @_builder.add(node)
     end
 
-    # `alt:` describes the image in a tagged PDF (false: decorative).
+    # `alt:` describes the image in a tagged PDF (false: decorative). Sizing,
+    # `fit: :cover`, `radius:` and `rotate:` as for Layout::Image.
     def image(source, align: nil, **)
       node = Layout::Image.new(source, **)
       @_builder.add(align ? Layout::Flow.new([node], align:) : node)

data/lib/stationery/fonts/fallback.rb

@@ -6,11 +6,13 @@ module Stationery
     # run's family, then the book's fallbacks in order, then bundled Inter. A
     # glyph no font has stays in the run's family and draws as .notdef.
     #
-    # Whitespace, joiners, variation selectors and combining marks carry the
-    # family of the character before them (or after them at the start of a
-    # run) so words are not chopped and marks stay with their base.
+    # Whitespace (any Unicode White_Space), joiners, variation selectors and
+    # combining marks carry the family of the character before them (or
+    # after them at the start of a run) so words are not chopped and marks
+    # stay with their base; whitespace a font lacks draws as a blank of the
+    # right width (see Font::WHITESPACE).
     class Fallback
-      CARRIED = /[\s‌‍︀-️\p{M}]/
+      CARRIED = /[\p{Space}‌‍︀-️\p{M}]/
 
       def self.carried?(char) = CARRIED.match?(char)
 

data/lib/stationery/fonts/font.rb

@@ -12,6 +12,18 @@ module Stationery
     class Font
       OBLIQUE_SKEW = Math.tan(12 * Math::PI / 180)
 
+      # Whitespace the font lacks draws as its space glyph advanced to the
+      # character's conventional width: a fraction of the em for the fixed
+      # spaces, a digit's or a period's advance for the figure and
+      # punctuation spaces, the space's own width for the rest (no-break,
+      # line and paragraph separators, ogham mark, …). Nothing is painted,
+      # nothing is .notdef.
+      WHITESPACE = /\A\p{Space}\z/
+      SPACE_FRACTIONS = { 0x2000 => 0.5, 0x2001 => 1.0, 0x2002 => 0.5, 0x2003 => 1.0, 0x2004 => 1.0 / 3,
+                          0x2005 => 0.25, 0x2006 => 1.0 / 6, 0x2009 => 0.2, 0x200A => 0.125, 0x205F => 4.0 / 18,
+                          0x3000 => 1.0 }.freeze
+      SPACE_LIKE = { 0x2007 => "0", 0x2008 => "." }.freeze
+
       attr_reader :ttf
 
       def initialize(ttf)
@@ -19,6 +31,7 @@ module Stationery
         @used = {}
         @pairs = {}
         @glyphs = {}
+        @blanks = {}
         @shapes = { true => {}, false => {} }
         @advances = { true => {}, false => {} }
         @kerns = { true => {}, false => {} }
@@ -59,12 +72,20 @@ module Stationery
       # `ligatures:` substitutes the font's standard ligatures; `kerning:`
       # then fills the adjustments with pair kerning between the glyphs.
       def glyph_run(text, kerning: false, ligatures: true)
-        gids, chars = shape(text, ligatures)
-        gids.each_with_index { |gid, i| @used[gid] ||= chars[i] }
-        adjust = gids.each_with_index.map { |gid, i| kerning && i + 1 < gids.size ? pair(gid, gids[i + 1]) : 0 }
+        gids, chars, blanks = shape(text, ligatures)
+        gids.each_with_index { |gid, i| @used[gid] ||= blanks[i] ? " " : chars[i] }
+        adjust = gids.each_with_index.map do |gid, i|
+          kern = kerning && i + 1 < gids.size ? pair(gid, gids[i + 1]) : 0
+          blanks[i] ? kern + (blanks[i] * 1000.0 / @ttf.units_per_em) : kern
+        end
         GlyphRun.new(font: self, gids:, adjust:, chars:)
       end
 
+      # Whether a character the font lacks is drawn as a blank (see WHITESPACE).
+      def blank?(char)
+        @blanks.fetch(char) { @blanks[char] = WHITESPACE.match?(char) && !glyph?(char) && glyph?(" ") }
+      end
+
       def used?
         @used.any?
       end
@@ -93,11 +114,13 @@ module Stationery
 
       private
 
-      # [gids, source text of each glyph], remembered per string.
+      # [gids, source text of each glyph, extra advance in font units after
+      # each blank or nil], remembered per string.
       def shape(text, ligatures)
         @shapes[ligatures][text] ||= begin
-          gids = text.each_char.map { |char| @ttf.glyph_id(char.ord) }
-          ligatures ? ligate(gids, text) : [gids, text.chars].each(&:freeze).freeze
+          gids = text.each_char.map { |char| glyph_for(char) }
+          gids, chars = ligatures ? ligate(gids, text) : [gids, text.chars]
+          [gids, chars, chars.map { |char| blank_units(char) }].each(&:freeze).freeze
         end
       end
 
@@ -105,11 +128,31 @@ module Stationery
         start = 0
         glyphs = @ttf.ligatures.substitute(gids)
         chars = glyphs.map { |_gid, count| text[start, count].tap { start += count } }
-        [glyphs.map(&:first), chars].each(&:freeze).freeze
+        [glyphs.map(&:first), chars]
+      end
+
+      def glyph_for(char)
+        blank?(char) ? @ttf.glyph_id(" ".ord) : @ttf.glyph_id(char.ord)
+      end
+
+      # How much wider (or narrower) than a space a blank's advance is.
+      def blank_units(char)
+        return unless blank?(char)
+
+        space = @ttf.advance(@ttf.glyph_id(" ".ord))
+        like = SPACE_LIKE[char.ord]
+        width = if (fraction = SPACE_FRACTIONS[char.ord]) then @ttf.units_per_em * fraction
+                elsif like && glyph?(like) then @ttf.advance(@ttf.glyph_id(like.ord))
+                else space
+                end
+        width - space
       end
 
       def advance_units(text, ligatures)
-        @advances[ligatures][text] ||= shape(text, ligatures).first.sum { |gid| @ttf.advance(gid) }
+        @advances[ligatures][text] ||= begin
+          gids, _, blanks = shape(text, ligatures)
+          gids.sum { |gid| @ttf.advance(gid) } + blanks.sum { |units| units || 0 }
+        end
       end
 
       def kerning_units(text, ligatures)

data/lib/stationery/layout/box.rb

@@ -10,15 +10,20 @@ module Stationery
     # fixed-height box can truncate or shrink text that does not fit
     # (`overflow:`) and never splits. `min_height:` is a floor that does split:
     # the first fragment keeps as much of it as the page holds and the next
-    # one carries only what is left of it.
+    # one carries only what is left of it. `rotate:` turns the painted box
+    # around its centre without moving its layout rectangle (a rotated box
+    # 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
       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
 
       attr_reader :content, :width_spec
 
       def initialize(content = Flow.new, padding: 0, background: nil, border: nil, radius: 0, width: nil,
                      height: nil, min_height: nil, overflow: :visible, valign: :top, opacity: nil, link: nil, outset: 0,
-                     open: [], decoration: :slice, role: nil)
+                     open: [], decoration: :slice, role: nil, rotate: 0, shadow: nil)
         raise ArgumentError, "pass height: or min_height:, not both" if height && min_height
 
         super()
@@ -39,6 +44,8 @@ module Stationery
         @overflow = overflow
         @valign = valign
         @opacity = opacity
+        @rotate = rotate
+        @shadow = shadow && SHADOW.merge(shadow == true ? {} : shadow)
       end
 
       def natural_width
@@ -55,7 +62,10 @@ module Stationery
         end
       end
 
-      def splittable? = @height.nil? && @overflow == :visible && @content.splittable?
+      def splittable?
+        @height.nil? && @rotate.zero? && %i[visible hidden].include?(@overflow) && @content.splittable?
+      end
+
       def prefer_whole? = break_inside.nil? && splittable?
 
       def split(width, height, fresh: false)
@@ -83,15 +93,18 @@ module Stationery
 
       def paint(canvas, x, y, width, height = nil, valign: nil, debug_kind: :box, **)
         height ||= measure(width)
-        canvas.structure(@tag) do
-          canvas.structure(@link_tag) do
-            paint_background(canvas, x, y, width, height)
-            paint_border(canvas, x, y, width, height)
-            paint_content(canvas, x, y, width, height, valign || @valign)
+        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)
+            end
           end
+          paint_debug(canvas, Rect.new(x, y, width, height), debug_kind) if canvas.debug?
         end
         canvas.link(x, y, width, height, @link, tag: @link_tag) if @link
-        paint_debug(canvas, Rect.new(x, y, width, height), debug_kind) if canvas.debug?
       end
 
       protected
@@ -125,6 +138,27 @@ module Stationery
       def vertical(open = @open) = insets(open).values_at(0, 2).sum
       def inner_width(width) = [width - horizontal, 0].max
 
+      # Stacked rounded rectangles under the box, the outermost grown by the
+      # blur and each fainter, so the centre sums to the opacity and the edge
+      # fades. An artifact: decoration, not content. Skipped on a fragment
+      # with cut sides, whose corners are square anyway.
+      def paint_shadow(canvas, x, y, width, height)
+        return unless @shadow && @open.empty?
+
+        blur = @shadow[:blur].to_f
+        layers = blur.positive? ? [(blur / 2).ceil, SHADOW_LAYERS].min : 1
+        dx, dy = @shadow[:offset]
+        canvas.artifact do
+          layers.downto(1) do |layer|
+            grow = blur * layer / layers
+            canvas.rounded_rect(x + dx - grow, y + dy - grow, width + (2 * grow), height + (2 * grow),
+                                radius: grown_radius(grow), fill: @shadow[:color], opacity: @shadow[:opacity] / layers)
+          end
+        end
+      end
+
+      def grown_radius(grow) = @radius.is_a?(Array) ? @radius.map { |r| r + grow } : @radius + grow
+
       # The outset paints the background past the box's own edges (a band that
       # bleeds into the page margins) without moving the content.
       def paint_background(canvas, x, y, width, height)
@@ -190,15 +224,27 @@ module Stationery
                                        end,
                                        inner.height, used)
         paint_inner = -> { content.paint(canvas, x + left, y + top + [offset, 0].max, inner.width) }
-        if @overflow == :visible
-          paint_inner.call
-        else
-          canvas.clip(inner.x, inner.y, inner.width, inner.height) do
+        clip_outline(canvas, Rect.new(x, y, width, height)) do
+          if @overflow == :visible || (@overflow == :hidden && @height.nil?)
             paint_inner.call
+          else
+            canvas.clip(inner.x, inner.y, inner.width, inner.height) do
+              paint_inner.call
+            end
           end
         end
       end
 
+      # `overflow: :hidden` keeps the content inside the rounded outline; cut
+      # sides stay square like the background's.
+      def clip_outline(canvas, area, &)
+        return yield unless @overflow == :hidden && @radius.positive?
+
+        cut(canvas, area, area) do |shape|
+          canvas.clip(shape.x, shape.y, shape.width, shape.height, radius: @radius, &)
+        end
+      end
+
       def paint_debug(canvas, rect, kind)
         canvas.debug_rect(rect.x, rect.y, rect.width, rect.height, kind)
         return if insets.all?(&:zero?)

data/lib/stationery/layout/image.rb

@@ -4,10 +4,16 @@ module Stationery
   module Layout
     # An image sized by width, height, both, or a box to fit into (aspect
     # preserved), never wider than the space it is given. One pixel is one
-    # point when no size is given.
+    # point when no size is given. `fit: :cover` fills `width:` × `height:`
+    # instead, scaling up and clipping the excess around the centre.
+    # `radius:` clips to rounded corners and `rotate:` (degrees, clockwise)
+    # turns the painted image around the centre of its rectangle; neither
+    # changes the space the image takes up.
     class Image < Node
       # `alt:` describes the image in a tagged PDF; `alt: false` marks it decorative.
-      def initialize(source, width: nil, height: nil, fit: nil, opacity: nil, alt: nil)
+      def initialize(source, width: nil, height: nil, fit: nil, opacity: nil, alt: nil, radius: 0, rotate: 0)
+        raise ArgumentError, "fit: :cover needs width: and height:" if fit == :cover && !(width && height)
+
         super()
         @tag = alt == false ? nil : Tagging::Element.new(:Figure, alt:, kind: :image)
         @image = source.respond_to?(:build) ? source : Images.load(source)
@@ -15,6 +21,8 @@ module Stationery
         @height = height
         @fit = fit
         @opacity = opacity
+        @radius = radius
+        @rotate = rotate
       end
 
       def size(available)
@@ -31,16 +39,37 @@ module Stationery
 
       def paint(canvas, x, y, width, _height = nil, **)
         w, h = size(width)
-        canvas.tag(@tag, bbox: [x, y, w, h]) { canvas.image(@image, x:, y:, width: w, height: h, opacity: @opacity) }
+        canvas.tag(@tag, bbox: [x, y, w, h]) do
+          canvas.rotate(@rotate, around: [x + (w / 2.0), y + (h / 2.0)]) { paint_clipped(canvas, x, y, w, h) }
+        end
         canvas.debug_rect(x, y, w, h, :image)
       end
 
       private
 
+      def paint_clipped(canvas, x, y, w, h)
+        return paint_image(canvas, x, y, w, h) unless @fit == :cover || @radius.positive?
+
+        canvas.clip(x, y, w, h, radius: @radius) { paint_image(canvas, x, y, w, h) }
+      end
+
+      def paint_image(canvas, x, y, w, h)
+        if @fit == :cover
+          scale = [w / @image.width.to_f, h / @image.height.to_f].max
+          cw = tidy(@image.width * scale)
+          ch = tidy(@image.height * scale)
+          x = tidy(x - ((cw - w) / 2.0))
+          y = tidy(y - ((ch - h) / 2.0))
+          w = cw
+          h = ch
+        end
+        canvas.image(@image, x:, y:, width: w, height: h, opacity: @opacity)
+      end
+
       def requested
         iw = @image.width.to_f
         ih = @image.height.to_f
-        if @fit
+        if @fit.is_a?(Array)
           scale = [@fit[0] / iw, @fit[1] / ih].min
           [iw * scale, ih * scale].map { |v| tidy(v) }
         elsif @width && @height then [@width, @height]

data/lib/stationery/layout/stack.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Layout
+    # A base flow with layers painted over it. The base sets the height and
+    # widths; each Layer is placed relative to the stack's rectangle and takes
+    # no space, so it can overhang the edges. A stack never splits: it moves
+    # to the next page whole (and is reported as an Overflow when taller than
+    # a page).
+    class Stack < Node
+      attr_reader :base, :layers
+
+      def initialize(base, layers)
+        super()
+        @base = base
+        @layers = layers
+      end
+
+      def measure(width) = @base.measure(width)
+      def natural_width = @base.natural_width
+      def min_width = @base.min_width
+      def fixed_width(available) = @base.fixed_width(available)
+      def prefer_whole? = true
+
+      def paint(canvas, x, y, width, height = nil, **)
+        height ||= measure(width)
+        @base.paint(canvas, x, y, width, height)
+        @layers.each { |layer| layer.paint(canvas, x, y, width, height) }
+        canvas.debug_rect(x, y, width, height, :stack)
+      end
+    end
+
+    # A box placed over a Stack by CSS-like insets. `top:`, `right:`,
+    # `bottom:`, `left:`, `width:` and `height:` are points, or fractions of
+    # the stack's width (horizontal ones) or height (vertical ones) when given
+    # as a Rational or a Float between -1 and 1; negative points overhang.
+    # Without `left:`/`top:` the layer sits at the stack's left/top edge;
+    # without `width:` it takes its content's natural width, at most the
+    # stack's, and without `height:` its content's height.
+    class Layer
+      def initialize(box, top: nil, right: nil, bottom: nil, left: nil, width: nil, height: nil)
+        @box = box
+        @top = top
+        @right = right
+        @bottom = bottom
+        @left = left
+        @width = width
+        @height = height
+      end
+
+      def paint(canvas, x, y, width, height)
+        own = layer_width(width)
+        tall = @height ? resolve(@height, height) : @box.measure(own)
+        @box.paint(canvas, x + offset(@left, @right, width, own), y + offset(@top, @bottom, height, tall), own, tall)
+      end
+
+      private
+
+      # Where the layer's near edge sits along one axis of the stack: `start`
+      # points from the start edge, else `finish` points before the end edge.
+      def offset(start, finish, extent, own)
+        return resolve(start, extent) if start
+        return extent - resolve(finish, extent) - own if finish
+
+        0
+      end
+
+      def layer_width(width)
+        return [@box.natural_width, width].min unless @width
+
+        resolve(@width, width)
+      end
+
+      def resolve(value, extent)
+        fraction?(value) ? extent * value : value
+      end
+
+      def fraction?(value) = value.is_a?(Rational) || (value.is_a?(Float) && value.abs <= 1)
+    end
+  end
+end

data/lib/stationery/minitest.rb

@@ -16,6 +16,7 @@ module Stationery
       def assert_pdf_link(subject, url, msg = nil) = assert_pdf(Matchers::HaveLink.new(url), subject, msg)
       def assert_image_count(subject, count, msg = nil) = assert_pdf(Matchers::HaveImageCount.new(count), subject, msg)
       def assert_bookmark(subject, title, msg = nil) = assert_pdf(Matchers::HaveBookmark.new(title), subject, msg)
+      def assert_pdf_language(subject, lang, msg = nil) = assert_pdf(Matchers::HaveLanguage.new(lang), subject, msg)
       def assert_no_pdf_warnings(subject, msg = nil) = assert_pdf(Matchers::HaveNoWarnings.new, subject, msg)
       def assert_pdf_structure(subject, tree, msg = nil) = assert_pdf(Matchers::HaveStructure.new(tree), subject, msg)
       def assert_tagged_content(subject, msg = nil) = assert_pdf(Matchers::HaveTaggedContent.new, subject, msg)

data/lib/stationery/preview.rb

@@ -4,15 +4,19 @@ require "stationery"
 
 module Stationery
   # Browsable sample documents, like ActionMailer previews. Each public method
-  # returns one document:
+  # returns one document. `around_render` wraps building and rendering it,
+  # for anything that must be in effect while the document paints:
   #
   #   # spec/pdfs/previews/invoice_pdf_preview.rb
   #   class InvoicePdfPreview < Stationery::Preview
   #     def paid = InvoicePdf.new(Invoice.first)
   #     def overdue(params) = InvoicePdf.new(Invoice.find(params.fetch("id")))
+  #
+  #     def around_render(_name, params) = I18n.with_locale(params.fetch("locale", I18n.default_locale)) { yield }
   #   end
   class Preview
     REGISTRY_LOCK = Mutex.new
+    HOOKS = %w[around_render].freeze
 
     class << self
       def inherited(subclass)
@@ -40,7 +44,7 @@ module Stationery
       end
 
       def preview_name = underscore(name.delete_suffix("Preview"))
-      def pdfs = public_instance_methods(false).sort.map(&:to_s)
+      def pdfs = public_instance_methods(false).sort.map(&:to_s) - HOOKS
 
       protected
 
@@ -53,6 +57,19 @@ module Stationery
       end
     end
 
+    # The PDF bytes of one preview, built and rendered inside around_render.
+    # `debug: true` reaches to_pdf when the document accepts it.
+    def to_pdf(name, params = {}, debug: false)
+      around_render(name, params) do
+        document = render(name, params)
+        document.to_pdf(**(debug && accepts_debug?(document) ? { debug: true } : {}))
+      end
+    end
+
+    # Override to wrap the preview: set an I18n locale, Current attributes,
+    # a time zone. Both the preview method and to_pdf run inside the block.
+    def around_render(_name, _params) = yield
+
     def render(name, params = {})
       method = public_method(name)
       document = method.arity.zero? ? method.call : method.call(params)
@@ -60,5 +77,9 @@ module Stationery
 
       raise Error, "#{self.class}##{name} must return a Stationery::Document (got #{document.class})"
     end
+
+    private
+
+    def accepts_debug?(document) = document.method(:to_pdf).parameters.include?(%i[key debug])
   end
 end

data/lib/stationery/rails/previews_controller.rb

@@ -19,8 +19,8 @@ module Stationery
       klass, pdf = Preview.find(params[:path])
       return head(:not_found) unless klass
 
-      document = klass.new.render(pdf, request.query_parameters.except("debug"))
-      send_data document.to_pdf(**debug_option(document)), type: "application/pdf", disposition: "inline"
+      pdf = klass.new.to_pdf(pdf, request.query_parameters.except("debug"), debug: params[:debug].present?)
+      send_data pdf, type: "application/pdf", disposition: "inline"
     end
 
     private
@@ -35,11 +35,6 @@ module Stationery
       Preview.load(Railtie.preview_paths(::Rails.root, config.preview_paths))
     end
 
-    def debug_option(document)
-      debug = params[:debug].present? && document.method(:to_pdf).parameters.include?(%i[key debug])
-      debug ? { debug: true } : {}
-    end
-
     def page(paths)
       items = paths.map do |path|
         href = ERB::Util.html_escape("#{request.path.chomp("/")}/#{path}")

data/lib/stationery/rich/renderer/inlines.rb

@@ -19,16 +19,24 @@ module Stationery
           bold: [[:b]], italic: [[:i]], underline: [[:u]], strike: [[:strikethrough]]
         }.freeze
 
-        def initialize(runs, styles)
+        def initialize(runs, styles, links = Links.new(:all, nil))
           @runs = runs
           @styles = styles
+          @links = links
         end
 
         def write(inlines) = inlines.grep(Inline).each { |inline| inline.break? ? @runs.br : write_one(inline) }
 
         private
 
-        def write_one(inline) = nest(inline.marks.flat_map { |mark, value| steps(mark, value) }, inline.text)
+        def write_one(inline) = nest(marks_of(inline).flat_map { |mark, value| steps(mark, value) }, inline.text)
+
+        def marks_of(inline)
+          marks = inline.marks
+          return marks unless marks.key?(:link) && !@links.allowed?(marks[:link])
+
+          marks.except(:link)
+        end
 
         def nest(steps, text)
           return @runs.plain(text) if steps.empty?

data/lib/stationery/rich/renderer/links.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Rich
+    class Renderer
+      # Which hrefs become link annotations: `#anchor` always, otherwise only
+      # the allowed URL schemes (case-insensitive). A dropped href keeps its
+      # text and is reported once as a DroppedLink warning. `:all` keeps every
+      # href, for trusted sources.
+      class Links
+        SCHEME = /\A([a-z][a-z0-9+.-]*):/i
+
+        def initialize(schemes, warnings)
+          @schemes = schemes == :all ? :all : Array(schemes).map { |scheme| scheme.to_s.downcase }
+          @warnings = warnings
+        end
+
+        def allowed?(href)
+          return true if @schemes == :all || href.start_with?("#")
+          return true if @schemes.include?(href[SCHEME, 1].to_s.downcase)
+
+          @warnings << Warnings::DroppedLink.new(href:)
+          false
+        end
+      end
+    end
+  end
+end

data/lib/stationery/rich/renderer.rb

@@ -3,6 +3,7 @@
 require_relative "nodes"
 require_relative "styles"
 require_relative "renderer/inlines"
+require_relative "renderer/links"
 
 module Stationery
   module Rich
@@ -11,8 +12,9 @@ module Stationery
     # from files under `base_path:`; remote URLs are never fetched.
     class Renderer
       REMOTE = /\A[a-z][a-z0-9+.-]*:/i
+      LINK_SCHEMES = %w[http https mailto tel].freeze
 
-      def initialize(component, builder, gap:, styles:, images:, base_path:, bookmarks: false)
+      def initialize(component, builder, gap:, styles:, images:, base_path:, bookmarks: false, links: nil)
         @component = component
         @builder = builder
         @gap = gap
@@ -20,6 +22,7 @@ module Stationery
         @images = images
         @base_path = base_path && File.expand_path(base_path.to_s)
         @bookmarks = bookmarks
+        @links = Links.new(links || LINK_SCHEMES, builder.warnings)
       end
 
       def render(blocks) = @component.group(gap: @gap) { blocks.each { |block| block(block) } }
@@ -40,7 +43,7 @@ module Stationery
       end
 
       def paragraph(inlines, **)
-        @component.text(**) { |runs| Inlines.new(runs, @styles).write(inlines) }
+        @component.text(**) { |runs| Inlines.new(runs, @styles, @links).write(inlines) }
       end
 
       def heading(heading)
@@ -57,7 +60,7 @@ module Stationery
       end
 
       def list(list)
-        options = list.ordered ? { start: list.start || 1 } : {}
+        options = list.ordered ? { **@styles[:ol], start: list.start || 1 } : @styles[:ul]
         @component.public_send(list.ordered ? :ol : :ul, **options) do
           list.items.each do |blocks|
             @component.li { @component.text_style(**@styles[:li]) { render(blocks) } }

data/lib/stationery/rich/styles.rb

@@ -18,6 +18,8 @@ module Stationery
         blockquote: { border: { sides: [:left], width: 3, color: "#E5E7EB" }, padding: [0, 0, 0, 10] },
         hr: { height: 1, color: "#E5E7EB" },
         table: { cell: { padding: 4 }, header: { weight: :bold } },
+        ul: {},
+        ol: {},
         li: {},
         img: { max_width: nil }
       }.freeze

data/lib/stationery/rspec.rb

@@ -3,4 +3,8 @@
 require "stationery"
 require_relative "testing/matchers"
 
+# Composable adds `and`/`or` and lets a matcher sit inside `include`, `match`
+# and `all`; Base stays framework-free for Minitest, so it is mixed in here.
+Stationery::Testing::Matchers::Base.include(RSpec::Matchers::Composable)
+
 RSpec.configure { |config| config.include Stationery::Testing::Matchers }

data/lib/stationery/testing/inspector.rb

@@ -60,16 +60,21 @@ module Stationery
       end
 
       def bookmarks
-        outlines = objects.deref!(objects.trailer[:Root])[:Outlines]
+        outlines = catalog[:Outlines]
         outlines ? titles(outlines[:First]) : []
       end
 
+      # The catalog /Lang written by `metadata lang:`, or nil.
+      def lang
+        lang = catalog[:Lang]
+        decode(lang) if lang
+      end
+
       # The structure tree of a tagged PDF as nested arrays; see StructureReader.
       def structure = @structure ||= StructureReader.new(reader).tree
 
       # Whether the catalog marks the PDF as tagged and holds a structure tree.
       def tagged?
-        catalog = objects.deref!(objects.trailer[:Root])
         catalog.dig(:MarkInfo, :Marked) == true && !catalog[:StructTreeRoot].nil?
       end
 
@@ -81,6 +86,7 @@ module Stationery
       private
 
       def objects = reader.objects
+      def catalog = objects.deref!(objects.trailer[:Root])
 
       def annotations
         reader.pages.flat_map do |page|

data/lib/stationery/testing/matchers.rb

@@ -101,6 +101,15 @@ module Stationery
         def actual = "got bookmarks #{@inspector.bookmarks.inspect}"
       end
 
+      class HaveLanguage < Base
+        def description = "have language #{show(@expected)}"
+
+        private
+
+        def match?(pdf) = pdf.lang == @expected.to_s
+        def actual = @inspector.lang ? "got #{@inspector.lang.inspect}" : "got none"
+      end
+
       class HaveNoWarnings < Base
         def description = "have no warnings"
 
@@ -140,6 +149,7 @@ module Stationery
       def have_pdf_link(expected) = HaveLink.new(expected)
       def have_image_count(expected) = HaveImageCount.new(expected)
       def have_bookmark(title) = HaveBookmark.new(title)
+      def have_pdf_language(lang) = HaveLanguage.new(lang)
       def have_no_warnings = HaveNoWarnings.new
       def have_structure(expected) = HaveStructure.new(expected)
       def have_tagged_content = HaveTaggedContent.new

data/lib/stationery/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Stationery
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end

data/lib/stationery/warnings.rb

@@ -33,6 +33,10 @@ module Stationery
       def message = %(link to "#{name}" on page #{page} has no matching anchor)
     end
 
+    DroppedLink = Data.define(:href) do
+      def message = %(link "#{href}" dropped: scheme not allowed)
+    end
+
     DuplicateAnchor = Data.define(:name, :page) do
       def message = %(anchor "#{name}" on page #{page} is already defined)
     end

data/lib/stationery.rb

@@ -107,6 +107,7 @@ require_relative "stationery/svg/document"
 require_relative "stationery/layout/svg"
 require_relative "stationery/layout/wrap"
 require_relative "stationery/layout/positioned"
+require_relative "stationery/layout/stack"
 require_relative "stationery/layout/field"
 require_relative "stationery/layout/list_item"
 require_relative "stationery/list_markers"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: stationery
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -110,6 +110,7 @@ files:
 - lib/stationery/layout/paginator.rb
 - lib/stationery/layout/positioned.rb
 - lib/stationery/layout/row.rb
+- lib/stationery/layout/stack.rb
 - lib/stationery/layout/svg.rb
 - lib/stationery/layout/table.rb
 - lib/stationery/layout/table/cell.rb
@@ -154,6 +155,7 @@ files:
 - lib/stationery/rich/nodes.rb
 - lib/stationery/rich/renderer.rb
 - lib/stationery/rich/renderer/inlines.rb
+- lib/stationery/rich/renderer/links.rb
 - lib/stationery/rich/styles.rb
 - lib/stationery/rspec.rb
 - lib/stationery/structure.rb