stationery 0.3.0 → 0.5.0

data/lib/stationery/forms/appearance.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Forms
+    # A widget's normal appearance: the form XObject(s) every viewer draws, so
+    # a form looks right without relying on the viewer to regenerate it.
+    # Variable text sits between `/Tx BMC … EMC`, the part a viewer redraws
+    # when the value changes.
+    class Appearance
+      PADDING = 2
+      LEADING = 1.15
+      CHECK = { glyph: "4", width: 0.846, middle: 0.345 }.freeze
+      DOT = 0.45
+      SIGNATURE = { rule: 14, label_size: 7, label_baseline: 4, label_gray: 0.42 }.freeze
+
+      def initialize(field, width, height, fonts)
+        @field = field
+        @width = width
+        @height = height
+        @fonts = fonts
+      end
+
+      # One stream, or a Hash of streams by appearance state for buttons.
+      def normal
+        case @field.kind
+        when :text, :select then stream(frame + variable_text(text_lines))
+        when :checkbox then { @field.on_state => stream(frame + check), Off: stream(frame) }
+        when :radio then { @field.on_state => stream(circle + dot), Off: stream(circle) }
+        when :signature then stream(signature)
+        end
+      end
+
+      private
+
+      def options = @field.options
+      def size = @field.font_size
+      def num(value) = PDF::Serializer.number(value.is_a?(Float) && value == value.round ? value.round : value)
+
+      def stream(content)
+        PDF::Stream.new(content, { Type: :XObject, Subtype: :Form, BBox: [0, 0, @width, @height],
+                                   Resources: { Font: @fonts } })
+      end
+
+      def frame
+        return +"" unless options[:background] || options[:border]
+
+        draw do |canvas|
+          canvas.rounded_rect(0.5, 0.5, @width - 1, @height - 1,
+                              radius: options[:radius], fill: options[:background], stroke: options[:border])
+        end
+      end
+
+      # [x, baseline, WinAnsi bytes] runs in PDF space.
+      def text_lines
+        return comb_cells if options[:comb]
+        return multiline_runs if options[:multiline]
+
+        [[PADDING, (@height / 2.0) - (size * (Metrics::ASCENT + Metrics::DESCENT) / 2), Metrics.encode(@field.value)]]
+      end
+
+      def multiline_runs
+        top = @height - PADDING - (size * Metrics::ASCENT)
+        Metrics.wrap(@field.value, @width - (2 * PADDING), size).each_with_index.map do |line, index|
+          [PADDING, top - (index * size * LEADING), line]
+        end
+      end
+
+      def comb_cells
+        cell = @width.fdiv(@field.max_length)
+        baseline = (@height / 2.0) - (size * (Metrics::ASCENT + Metrics::DESCENT) / 2)
+        Metrics.encode(@field.value)[0, @field.max_length].chars.each_with_index.map do |char, index|
+          [(index * cell) + ((cell - Metrics.width(char, size)) / 2), baseline, char]
+        end
+      end
+
+      def variable_text(runs)
+        ops = ["/Tx BMC", "q", "1 1 #{num(@width - 2)} #{num(@height - 2)} re W n", "0 g"]
+        runs.reject { |_, _, bytes| bytes.empty? }.each do |x, y, bytes|
+          ops.push("BT", "/#{Field::FONT} #{num(size)} Tf", "#{num(x)} #{num(y)} Td",
+                   "#{PDF::Serializer.literal(bytes)} Tj", "ET")
+        end
+        ops.push("Q", "EMC").join("\n") << "\n"
+      end
+
+      def circle
+        draw { |canvas| canvas.circle(*center, radius - 0.5, fill: options[:background], stroke: options[:border]) }
+      end
+
+      def dot = draw { |canvas| canvas.circle(*center, radius * DOT, fill: "#000000") }
+      def center = [@width / 2.0, @height / 2.0]
+      def radius = [@width, @height].min / 2.0
+
+      def signature
+        y = @height - SIGNATURE[:rule]
+        content = draw { |canvas| canvas.line(PADDING, y, @width - PADDING, y, color: options[:border], width: 0.75) }
+        label = Metrics.encode(options[:label])
+        return content if label.empty?
+
+        ops = ["q", "#{SIGNATURE[:label_gray]} g", "BT", "/#{Field::FONT} #{SIGNATURE[:label_size]} Tf",
+               "#{PADDING} #{SIGNATURE[:label_baseline]} Td", "#{PDF::Serializer.literal(label)} Tj", "ET", "Q"]
+        "#{content}#{ops.join("\n")}\n"
+      end
+
+      def draw
+        page = Page.new(size: [@width, @height])
+        yield Canvas.new(page, nil)
+        page.content
+      end
+
+      def check
+        glyph = [@width, @height].min * 0.8
+        x = (@width - (glyph * CHECK[:width])) / 2
+        y = (@height / 2.0) - (glyph * CHECK[:middle])
+        ["q", "0 g", "BT", "/ZaDb #{num(glyph)} Tf", "#{num(x)} #{num(y)} Td", "(#{CHECK[:glyph]}) Tj", "ET", "Q"]
+          .join("\n") << "\n"
+      end
+    end
+  end
+end

data/lib/stationery/forms/field.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Stationery
+  # Interactive form fields (AcroForm): what each one holds and how it is
+  # written, apart from where the layout puts it.
+  module Forms
+    # One form field widget: its kind, full (dotted) name, value and options.
+    # Widgets sharing a name form one field (a radio group); dotted names are
+    # grouped under parent fields.
+    class Field
+      TYPES = { text: :Tx, checkbox: :Btn, radio: :Btn, select: :Ch, signature: :Sig }.freeze
+      # Field flag bit positions (PDF 32000-1, 12.7.3.1 and 12.7.4).
+      BITS = { read_only: 1, required: 2, multiline: 13, no_toggle_to_off: 15, radio: 16, combo: 18, edit: 19,
+               comb: 25 }.freeze
+      DEFAULTS = { font_size: 10, read_only: false, required: false, border: "#9CA3AF", background: "#FFFFFF",
+                   radius: 2 }.freeze
+      OPTIONS = {
+        text: %i[multiline max_length comb], checkbox: [], radio: %i[checked], select: %i[options editable],
+        signature: %i[label]
+      }.freeze
+      FONT = "Helv"
+
+      attr_reader :kind, :name, :value, :options
+
+      def initialize(kind, name, value: nil, **options)
+        @kind = kind
+        @name = validate_name(name.to_s)
+        @value = value
+        unknown = options.keys - DEFAULTS.keys - OPTIONS.fetch(kind)
+        raise ArgumentError, "unknown #{kind} field option: #{unknown.join(", ")}" if unknown.any?
+
+        @options = DEFAULTS.merge(options)
+        validate_comb
+      end
+
+      def segments = @name.split(".")
+      def type = TYPES.fetch(@kind)
+      def font_size = @options[:font_size]
+      def default_appearance = "/#{FONT} #{PDF::Serializer.number(font_size)} Tf 0 g"
+      def max_length = @options[:comb].is_a?(Integer) ? @options[:comb] : @options[:max_length]
+      def radio? = @kind == :radio
+      def checked? = radio? ? @options[:checked] == true : @value == true
+
+      # The on-state of a button: /Yes, or a radio's export value.
+      def on_state = radio? ? @value.to_s.to_sym : :Yes
+
+      def flags
+        set = %i[read_only required].select { |key| @options[key] }
+        set += kind_flags
+        set.sum { |key| 1 << (BITS.fetch(key) - 1) }
+      end
+
+      # The field-level entries; the widget's come from #widget_entries.
+      # `value` overrides this widget's own: a radio group's checked choice.
+      def field_entries(value = field_value)
+        entries = { FT: type, DA: default_appearance }
+        entries[:Ff] = flags if flags.positive?
+        entries[:V] = value unless value.nil?
+        entries[:MaxLen] = max_length if max_length
+        entries[:Opt] = @options[:options].map { |option| PDF::TextString.new(option.to_s) } if @kind == :select
+        entries
+      end
+
+      # What Document#fields reports for this field.
+      def data_value
+        case @kind
+        when :checkbox then checked?
+        when :radio then checked? ? @value : nil
+        else @value
+        end
+      end
+
+      # `state` overrides the button's own appearance state.
+      def widget_entries(width, height, fonts, state: nil)
+        normal = Appearance.new(self, width, height, fonts).normal
+        entries = { Type: :Annot, Subtype: :Widget, F: 4, AP: { N: normal } }
+        entries[:MK] = appearance_characteristics unless @kind == :signature
+        entries[:AS] = state || (checked? ? on_state : :Off) if normal.is_a?(Hash)
+        entries
+      end
+
+      private
+
+      def field_value
+        case @kind
+        when :checkbox, :radio then checked? ? on_state : :Off
+        when :signature then nil
+        else @value.nil? ? nil : PDF::TextString.new(@value.to_s)
+        end
+      end
+
+      def kind_flags
+        case @kind
+        when :text then %i[multiline comb].select { |key| @options[key] }
+        when :radio then %i[radio no_toggle_to_off]
+        when :select then @options[:editable] ? %i[combo edit] : %i[combo]
+        else []
+        end
+      end
+
+      def appearance_characteristics
+        mk = {}
+        mk[:BG] = Color.parse(@options[:background]).components if @options[:background]
+        mk[:BC] = Color.parse(@options[:border]).components if @options[:border]
+        mk[:CA] = radio? ? "l" : "4" if type == :Btn
+        mk
+      end
+
+      def validate_name(name)
+        return name unless name.empty? || name.split(".", -1).any?(&:empty?)
+
+        raise ArgumentError, "invalid field name #{name.inspect}: use non-empty, dot-separated segments"
+      end
+
+      def validate_comb
+        return unless @options[:comb] && !max_length
+
+        raise ArgumentError, "a comb field needs max_length: (or comb: <cells>)"
+      end
+    end
+  end
+end

data/lib/stationery/forms/metrics.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Forms
+    # Helvetica's advance widths (the standard-14 AFM, in 1/1000 em) for the
+    # printable ASCII range, enough to lay out a field's appearance; other
+    # WinAnsi characters count as a digit's width.
+    module Metrics
+      ASCII = [
+        278, 278, 355, 556, 556, 889, 667, 191, 333, 333, 389, 584, 278, 333, 278, 278, # space - /
+        556, 556, 556, 556, 556, 556, 556, 556, 556, 556, 278, 278, 584, 584, 584, 556, # 0 - ?
+        1015, 667, 667, 722, 722, 667, 611, 778, 722, 278, 500, 667, 556, 833, 722, 778, # @ - O
+        667, 778, 722, 667, 611, 722, 667, 944, 667, 667, 611, 278, 278, 278, 469, 556, # P - _
+        333, 556, 556, 500, 556, 556, 278, 556, 556, 222, 222, 500, 222, 833, 556, 556, # ` - o
+        556, 556, 333, 500, 278, 556, 500, 722, 500, 500, 500, 334, 260, 334, 584 # p - ~
+      ].freeze
+      DEFAULT = 556
+      ASCENT = 0.718
+      DESCENT = -0.207
+
+      module_function
+
+      # WinAnsi bytes for an appearance stream; unmappable characters become "?".
+      def encode(text)
+        text.to_s.encode(Encoding::Windows_1252, invalid: :replace, undef: :replace).b
+      end
+
+      # The width of WinAnsi `bytes` at `size`.
+      def width(bytes, size)
+        bytes.each_byte.sum { |byte| (byte in 32..126) ? ASCII[byte - 32] : DEFAULT } * size / 1000.0
+      end
+
+      # `text` broken into WinAnsi lines no wider than `width`, keeping its own
+      # line breaks; a word wider than a line stands alone.
+      def wrap(text, width, size)
+        encode(text).split("\n", -1).flat_map do |paragraph|
+          paragraph.split.each_with_object([+""]) do |word, lines|
+            candidate = lines.last.empty? ? word : "#{lines.last} #{word}"
+            if lines.last.empty? || width(candidate, size) <= width
+              lines[-1] = candidate
+            else
+              lines << word
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/stationery/layout/box.rb

@@ -10,22 +10,29 @@ 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)
+                     open: [], decoration: :slice, role: nil, rotate: 0, shadow: nil)
         raise ArgumentError, "pass height: or min_height:, not both" if height && min_height
 
         super()
+        @tag = role && Tagging::Element.new(Tagging.role(role))
         @min_height = min_height
         @open = open
         @decoration = decoration
         @link = link
+        @link_tag = link && Tagging::Element.new(:Link)
         @outset = Geometry.box(outset)
         @content = content
         @padding = Geometry.box(padding)
@@ -37,6 +44,8 @@ module Stationery
         @overflow = overflow
         @valign = valign
         @opacity = opacity
+        @rotate = rotate
+        @shadow = shadow && SHADOW.merge(shadow == true ? {} : shadow)
       end
 
       def natural_width
@@ -53,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)
@@ -81,11 +93,18 @@ module Stationery
 
       def paint(canvas, x, y, width, height = nil, valign: nil, debug_kind: :box, **)
         height ||= measure(width)
-        paint_background(canvas, x, y, width, height)
-        paint_border(canvas, x, y, width, height)
-        paint_content(canvas, x, y, width, height, valign || @valign)
-        canvas.link(x, y, width, height, @link) if @link
-        paint_debug(canvas, Rect.new(x, y, width, height), debug_kind) if canvas.debug?
+        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
       end
 
       protected
@@ -119,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)
@@ -184,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/field.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Layout
+    # An interactive form field: a widget `height` tall that fills the width
+    # (`width: :full`) or takes `width` points. Its look comes from the
+    # widget's own appearance, so it paints nothing into the page but an
+    # optional `label` node to the right of the widget.
+    class Field < Node
+      LABEL_GAP = 6
+
+      def initialize(field, height:, width: :full, label: nil)
+        super()
+        @field = field
+        @height = height
+        @width = width
+        @label = label
+        @tag = Tagging::Element.new(:Form, kind: :field)
+      end
+
+      def measure(width)
+        @label ? [@height, @label.measure(label_width(width))].max : @height
+      end
+
+      def natural_width = @label ? label_offset + @label.natural_width : fixed_points || 0
+      def min_width = @label ? label_offset + @label.min_width : fixed_points || 0
+
+      def fixed_width(available)
+        return [natural_width, available].min if @label
+
+        fixed_points && [fixed_points, available].min
+      end
+
+      def paint(canvas, x, y, width, _height = nil, **)
+        own = @label ? @width : width
+        total = measure(width)
+        top = y + ((total - @height) / 2.0)
+        canvas.widget(@field, x, top, own, @height, tag: @tag)
+        @label&.paint(canvas, x + label_offset, y + ((total - @label.measure(label_width(width))) / 2.0),
+                      label_width(width))
+        canvas.debug_rect(x, top, own, @height, :field) if canvas.debug?
+      end
+
+      private
+
+      def fixed_points = @width.is_a?(Numeric) ? @width : nil
+      def label_offset = @width + LABEL_GAP
+      def label_width(width) = [width - label_offset, 0].max
+    end
+  end
+end

data/lib/stationery/layout/flow.rb

@@ -10,11 +10,13 @@ module Stationery
     class Flow < Node
       attr_reader :children, :gap, :align
 
-      def initialize(children = [], gap: 0, align: :left)
+      # `tag` groups the children in a tagged PDF (a list's L).
+      def initialize(children = [], gap: 0, align: :left, tag: nil)
         super()
         @children = children
         @gap = gap
         @align = align
+        @tag = tag
       end
 
       def <<(child)
@@ -35,6 +37,20 @@ module Stationery
       end
 
       def paint(canvas, x, y, width, _height = nil, **)
+        canvas.structure(@tag) { paint_children(canvas, x, y, width) }
+      end
+
+      def split(width, height, fresh: false)
+        Splitter.new(self, width, height, fresh).call
+      end
+
+      def with_children(children)
+        self.class.new(children, gap: @gap, align: @align, tag: @tag)
+      end
+
+      private
+
+      def paint_children(canvas, x, y, width)
         cursor = y
         @children.reject(&:page_break?).each_with_index do |child, index|
           cursor += @gap unless index.zero?
@@ -46,14 +62,6 @@ module Stationery
           cursor += height
         end
       end
-
-      def split(width, height, fresh: false)
-        Splitter.new(self, width, height, fresh).call
-      end
-
-      def with_children(children)
-        self.class.new(children, gap: @gap, align: @align)
-      end
     end
 
     # One pass of Flow#split, kept apart so the rules read top to bottom.

data/lib/stationery/layout/image.rb

@@ -4,15 +4,25 @@ 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
-      def initialize(source, width: nil, height: nil, fit: nil, opacity: nil)
+      # `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, 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)
         @width = width
         @height = height
         @fit = fit
         @opacity = opacity
+        @radius = radius
+        @rotate = rotate
       end
 
       def size(available)
@@ -29,16 +39,37 @@ module Stationery
 
       def paint(canvas, x, y, width, _height = nil, **)
         w, h = size(width)
-        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/list_item.rb

@@ -9,8 +9,12 @@ module Stationery
     class ListItem < Node
       attr_reader :marker, :body, :indent, :marker_gap
 
-      def initialize(marker, body, indent:, marker_gap:)
+      # `tag` and `body_tag` are the item's LI and LBody; a Text marker carries its own Lbl.
+      def initialize(marker, body, indent:, marker_gap:, tag: Tagging::Element.new(:LI),
+                     body_tag: Tagging::Element.new(:LBody))
         super()
+        @tag = tag
+        @body_tag = body_tag
         @marker = marker
         @body = body
         @indent = indent
@@ -31,11 +35,13 @@ module Stationery
       end
 
       def paint(canvas, x, y, width, _height = nil, **)
-        if @marker
-          own = @marker.width_in(column)
-          @marker.paint(canvas, x + column - own, y, own)
+        canvas.structure(@tag) do
+          if @marker
+            own = @marker.width_in(column)
+            @marker.paint(canvas, x + column - own, y, own)
+          end
+          canvas.structure(@body_tag) { @body.paint(canvas, x + @indent, y, body_width(width)) }
         end
-        @body.paint(canvas, x + @indent, y, body_width(width))
       end
 
       def split(width, height, fresh: false)
@@ -51,7 +57,10 @@ module Stationery
 
       def column = [@indent - @marker_gap, 0].max
       def body_width(width) = [width - @indent, 0].max
-      def with(marker, body) = self.class.new(marker, body, indent: @indent, marker_gap: @marker_gap)
+
+      def with(marker, body)
+        self.class.new(marker, body, indent: @indent, marker_gap: @marker_gap, tag: @tag, body_tag: @body_tag)
+      end
     end
 
     # A drawn bullet (:disc, :circle or :square) sized to the text style and

data/lib/stationery/layout/node.rb

@@ -26,6 +26,8 @@ module Stationery
     # - fixed_width(available)    → its own width, or nil when it fills the width
     class Node
       attr_accessor :keep_with_next, :break_inside
+      # The Tagging::Element this node paints into, shared by its fragments.
+      attr_reader :tag
 
       def measure(_width) = raise(NotImplementedError, "#{self.class} must implement measure")
       def paint(_canvas, _x, _y, _width, _height = nil, **) = raise(NotImplementedError, "#{self.class}#paint")

data/lib/stationery/layout/paginator.rb

@@ -7,8 +7,9 @@ module Stationery
     class Paginator
       attr_reader :warnings
 
-      def initialize(resources:, page: {}, warnings: Warnings.new, debug: false, regions: nil)
+      def initialize(resources:, page: {}, warnings: Warnings.new, debug: false, regions: nil, tagging: nil)
         @resources = resources
+        @tagging = tagging
         @debug = debug
         @page_options = page
         @regions = regions
@@ -61,7 +62,7 @@ module Stationery
         box = page.content_box
         height = head.measure(box.width)
         @warnings << Overflow.new(page: number, height:, available: box.height) if height > box.height + EPSILON
-        canvas = Canvas.new(page, @resources, debug: @debug)
+        canvas = Canvas.new(page, @resources, debug: @debug, tagging: @tagging)
         head.paint(canvas, box.x, box.y, box.width)
         canvas.debug_rect(box.x, box.y, box.width, box.height, :page)
       end