stationery 0.3.0 → 0.4.0

data/lib/stationery/elements/lists.rb

@@ -4,6 +4,9 @@ module Stationery
   # Bulleted and numbered lists.
   module Elements
     BULLETS = %i[disc circle square].freeze
+    # ListNumbering for tagged PDF, by bullet shape and number format.
+    NUMBERING = { disc: :Disc, circle: :Circle, square: :Square, decimal: :Decimal, alpha: :LowerAlpha,
+                  upper_alpha: :UpperAlpha, roman: :LowerRoman, upper_roman: :UpperRoman }.freeze
 
     # A bulleted list. `style:` is :disc, :circle, :square, :dash or any
     # String; unstyled nested lists cycle disc → circle → square. Every node
@@ -11,7 +14,8 @@ module Stationery
     def ul(style: nil, gap: 4, indent: nil, marker_gap: 6, marker_color: nil, &)
       shape = style || BULLETS[@_builder.list_depth % BULLETS.size]
       marker_style = @_builder.style({ color: marker_color }.compact)
-      list(marker_style, gap:, indent:, marker_gap:, marker: ->(_) { list_bullet(shape, marker_style) }, &)
+      list(marker_style, gap:, indent:, marker_gap:, marker: ->(_) { list_bullet(shape, marker_style) },
+                         numbering: shape, &)
     end
 
     # A numbered list. `format:` is :decimal, :alpha, :upper_alpha, :roman,
@@ -19,7 +23,7 @@ module Stationery
     def ol(format: :decimal, start: 1, suffix: ".", gap: 4, indent: nil, marker_gap: 6, marker_color: nil, &)
       marker_style = @_builder.style({ color: marker_color }.compact)
       label = ->(index) { list_label(ListMarkers.label(format, start + index, suffix), marker_style) }
-      list(marker_style, gap:, indent:, marker_gap:, marker: label, &)
+      list(marker_style, gap:, indent:, marker_gap:, marker: label, numbering: format, &)
     end
 
     # A list item: a String becomes a paragraph (taking every text option),
@@ -32,7 +36,7 @@ module Stationery
 
     private
 
-    def list(marker_style, gap:, indent:, marker_gap:, marker:, &)
+    def list(marker_style, gap:, indent:, marker_gap:, marker:, numbering:, &)
       items = Builder::Items.new
       @_builder.nested_list { @_builder.within(items) { yield_content(&) } }
       markers = items.nodes.each_index.map(&marker)
@@ -40,7 +44,12 @@ module Stationery
       entries = items.nodes.zip(markers).map do |node, mark|
         Layout::ListItem.new(mark, node.is_a?(Layout::Flow) ? node : Layout::Flow.new([node]), indent:, marker_gap:)
       end
-      @_builder.add(Layout::Flow.new(entries, gap:))
+      @_builder.add(Layout::Flow.new(entries, gap:, tag: list_tag(numbering)))
+    end
+
+    def list_tag(numbering)
+      numbering = NUMBERING[numbering] if numbering.is_a?(Symbol)
+      Tagging::Element.new(:L, attributes: numbering ? { List: { ListNumbering: numbering } } : {})
     end
 
     def list_bullet(shape, style)
@@ -52,7 +61,8 @@ module Stationery
     end
 
     def list_label(label, style)
-      Layout::Text.new([Text::Run.new(label, style)], context: @_builder.context(style), align: :right)
+      Layout::Text.new([Text::Run.new(label, style)], context: @_builder.context(style), align: :right,
+                                                      tag: Tagging::Element.new(:Lbl))
     end
   end
 end

data/lib/stationery/elements.rb

@@ -6,21 +6,23 @@ module Stationery
     PARAGRAPH_DEFAULTS = { align: :left, leading: 0 }.freeze
 
     # A paragraph. Plain strings are always literal; pass `markup: true` to
-    # read inline tags, or a block to build styled runs in Ruby.
+    # read inline tags, or a block to build styled runs in Ruby. `heading: 1..6`
+    # tags it as a heading in a tagged PDF.
     def text(content = nil, markup: false, keep_with_next: nil, break_inside: nil, anchor: nil, bookmark: nil,
-             **options, &)
+             heading: nil, **options, &)
       settings = PARAGRAPH_DEFAULTS.merge(@_builder.text_defaults.slice(:align, :leading)).merge(options)
       style = @_builder.style(options)
       runs = text_runs(content, style, markup, &)
       node = Layout::Text.new(runs, context: @_builder.context(style), align: settings[:align],
-                                    leading: settings[:leading])
+                                    leading: settings[:leading], tag: Tagging::Element.new(Tagging.heading(heading)))
       node.keep_with_next = keep_with_next
       node.break_inside = break_inside
       @_builder.add(mark(node, anchor, bookmark))
     end
 
     # A container with padding, background, border and radius. `at: [x, y]`
-    # places it at a fixed page position outside the flow.
+    # places it at a fixed page position outside the flow. `role:` (:section,
+    # :blockquote, :note, :caption, …) groups its content in a tagged PDF.
     # `break_inside: :auto` splits it at any page break, `:avoid` never; by
     # default it splits only when it does not fit on a page of its own.
     def box(at: nil, align: nil, gap: 0, width: nil, keep_with_next: nil, break_inside: nil, anchor: nil, bookmark: nil,
@@ -65,15 +67,15 @@ module Stationery
     end
 
     # An SVG drawing: markup String, or a path to a .svg file. `currentColor`
-    # takes `color:`.
-    def svg(source, width: nil, height: nil, color: "#000000", align: nil)
+    # takes `color:`. `alt:` describes it in a tagged PDF (false: decorative).
+    def svg(source, width: nil, height: nil, color: "#000000", align: nil, alt: nil)
       name = source.to_s.lstrip.start_with?("<") ? "inline" : File.basename(source.to_s)
       source = File.read(source.to_s) unless name == "inline"
       document = SVG::Document.parse(source)
       if document.unsupported.any?
         @_builder.warnings << Warnings::UnsupportedSvg.new(elements: document.unsupported, source: name)
       end
-      node = Layout::Svg.new(document, width:, height:, color:, context: @_builder.context)
+      node = Layout::Svg.new(document, width:, height:, color:, context: @_builder.context, alt:)
       @_builder.add(align ? Layout::Flow.new([node], align:) : node)
     end
 
@@ -95,6 +97,7 @@ module Stationery
       @_builder.add(node)
     end
 
+    # `alt:` describes the image in a tagged PDF (false: decorative).
     def image(source, align: nil, **)
       node = Layout::Image.new(source, **)
       @_builder.add(align ? Layout::Flow.new([node], align:) : node)

data/lib/stationery/forms/acro_form.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Forms
+    # Collects the widgets pages place and writes the document's interactive
+    # form: one field per name, parent fields for dotted names, the shared
+    # Helvetica and ZapfDingbats resources and the catalog's /AcroForm.
+    class AcroForm
+      FONTS = { Helv: :Helvetica, ZaDb: :ZapfDingbats }.freeze
+
+      # A widget placed on a page: its field, PDF-space rect, page and the
+      # reference the page's /Annots already points at.
+      Widget = Data.define(:field, :rect, :page, :ref, :extra)
+
+      # A name segment: widgets when it is a field, children when a group.
+      Node = Struct.new(:name, :widgets, :children)
+
+      # { full name => value } for every field widget on `pages`.
+      def self.values(pages)
+        pages.flat_map(&:annotations).each_with_object({}) do |annotation, values|
+          field = annotation[:widget] or next
+          value = field.data_value
+          values[field.name] = value unless value.nil? && values.key?(field.name)
+        end
+      end
+
+      def initialize(writer)
+        @writer = writer
+        @widgets = []
+      end
+
+      # Reserves the widget annotation for `field` at `rect` on `page`.
+      # `extra` entries for the widget dictionary may be computed from its
+      # reference (a tagged PDF's /StructParent).
+      def add(field, rect, page)
+        ref = @writer.reserve
+        @widgets << Widget.new(field, rect, page, ref, block_given? ? yield(ref) : {})
+        ref
+      end
+
+      # Writes every field; returns the /AcroForm dictionary, or nil without
+      # fields.
+      def write
+        return if @widgets.empty?
+
+        @fonts = FONTS.transform_values { |base| @writer.add(font(base)) }
+        fields = tree.children.values.map { |node| write_node(node, nil) }
+        { Fields: fields, NeedAppearances: true, DA: "/#{Field::FONT} 0 Tf 0 g", DR: { Font: @fonts } }
+      end
+
+      private
+
+      def font(base)
+        font = { Type: :Font, Subtype: :Type1, BaseFont: base }
+        base == :Helvetica ? font.merge(Encoding: :WinAnsiEncoding) : font
+      end
+
+      def tree
+        root = Node.new(nil, [], {})
+        @widgets.each do |widget|
+          node = widget.field.segments.reduce(root) do |parent, segment|
+            parent.children[segment] ||= Node.new(segment, [], {})
+          end
+          node.widgets << widget
+        end
+        root.children.each_value { |node| validate(node, node.name) }
+        root
+      end
+
+      def validate(node, path)
+        if node.widgets.any? && node.children.any?
+          raise ArgumentError, "field name #{path.inspect} is both a field and a group"
+        end
+        if node.widgets.map { |widget| widget.field.kind }.uniq.size > 1
+          raise ArgumentError, "field name #{path.inspect} is used by fields of different kinds"
+        end
+
+        node.children.each_value { |child| validate(child, "#{path}.#{child.name}") }
+      end
+
+      def write_node(node, parent)
+        own = { T: PDF::TextString.new(node.name) }
+        own[:Parent] = parent if parent
+        return write_field(node.widgets, own) if node.widgets.any?
+
+        ref = @writer.reserve
+        @writer.set(ref, own.merge(Kids: node.children.values.map { |child| write_node(child, ref) }))
+      end
+
+      # One widget is merged with its field; several, or radios, become the
+      # field's kids. A radio group's value is its checked choice.
+      def write_field(widgets, own)
+        field = widgets.first.field
+        unless field.radio? || !widgets.one?
+          return @writer.set(widgets.first.ref, own.merge(field.field_entries, widget(widgets.first)))
+        end
+
+        ref = @writer.reserve
+        value = field.radio? ? widgets.map(&:field).find(&:checked?)&.on_state || :Off : nil
+        widgets.each { |kid| @writer.set(kid.ref, widget(kid, value).merge(Parent: ref)) }
+        entries = value ? field.field_entries(value) : field.field_entries
+        @writer.set(ref, own.merge(entries, Kids: widgets.map(&:ref)))
+      end
+
+      def widget(widget, group_value = nil)
+        x1, y1, x2, y2 = widget.rect
+        state = group_value && (widget.field.on_state == group_value ? group_value : :Off)
+        entries = widget.field.widget_entries(x2 - x1, y2 - y1, @fonts, state:)
+        normal = entries.dig(:AP, :N)
+        normal = normal.is_a?(Hash) ? normal.transform_values { |stream| @writer.add(stream) } : @writer.add(normal)
+        entries.merge(AP: { N: normal }, Rect: widget.rect, P: widget.page, **widget.extra)
+      end
+    end
+  end
+end

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

@@ -18,14 +18,16 @@ module Stationery
 
       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)
         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)
@@ -81,10 +83,14 @@ 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
+        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)
+          end
+        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
 

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

@@ -6,8 +6,10 @@ module Stationery
     # preserved), never wider than the space it is given. One pixel is one
     # point when no size is given.
     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)
         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
@@ -29,7 +31,7 @@ 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]) { canvas.image(@image, x:, y:, width: w, height: h, opacity: @opacity) }
         canvas.debug_rect(x, y, w, h, :image)
       end