stationery 0.3.0 → 0.5.0

data/lib/stationery/canvas.rb

@@ -7,6 +7,7 @@ module Stationery
   class Canvas
     include Text
     include Debug
+    include Marking
 
     CAPS = { butt: 0, round: 1, square: 2 }.freeze
     JOINS = { miter: 0, round: 1, bevel: 2 }.freeze
@@ -14,11 +15,14 @@ module Stationery
     attr_reader :page
 
     # `template: true` records anchors apart, for canvases page templates draw on.
-    def initialize(page, resources, template: false, debug: false)
+    # `tagging:` (a Tagging::Tree) marks content for a tagged PDF.
+    def initialize(page, resources, template: false, debug: false, tagging: nil)
       @page = page
       @resources = resources
       @template = template
       @debug = debug
+      @tagging = tagging
+      @marked = 0
     end
 
     def save
@@ -27,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")
@@ -81,11 +111,22 @@ module Stationery
 
     # A clickable area opening `target`: a URL, or `#name` for an anchor in
     # this document. Annotation rectangles live in absolute, untransformed
-    # page space, so they ignore clips and path transforms.
-    def link(x, y, w, h, target)
+    # page space, so they ignore clips and path transforms. `tag:` is the
+    # Link element the annotation belongs to in a tagged PDF.
+    def link(x, y, w, h, target, tag: nil)
       target = target.to_s
       rect = [x, @page.height - y - h, x + w, @page.height - y].map { |v| num_value(v) }
-      @page.annotations << (target.start_with?("#") ? { rect:, dest: target[1..] } : { rect:, url: target })
+      annotation = target.start_with?("#") ? { rect:, dest: target[1..] } : { rect:, url: target }
+      @page.annotations << annotation
+      own(annotation, tag) if tag
+    end
+
+    # An interactive form field's widget (a Forms::Field) over the rectangle.
+    def widget(field, x, y, w, h, tag: nil)
+      rect = [x, @page.height - y - h, x + w, @page.height - y].map { |v| num_value(v) }
+      annotation = { rect:, widget: field }
+      @page.annotations << annotation
+      adopt(annotation, tag, rect) if tag
     end
 
     # Names the point `y` on this page as a link target.
@@ -94,9 +135,10 @@ module Stationery
     end
 
     # Leaves room for the page number `anchor` lands on; Structure fills it in
-    # and adds the `link:` area ([x, y, w, h]) when the anchor exists.
-    def number_slot(anchor, x:, baseline:, width:, style:, link: nil)
-      @page.slots << Page::Slot.new(anchor.to_s, x, baseline, width, style, link)
+    # and adds the `link:` area ([x, y, w, h]) when the anchor exists. `tags:`
+    # are the [link, number] elements they belong to in a tagged PDF.
+    def number_slot(anchor, x:, baseline:, width:, style:, link: nil, tags: nil)
+      @page.slots << Page::Slot.new(anchor.to_s, x, baseline, width, style, link, tags)
     end
 
     def num(value) = PDF::Serializer.number(num_value(value))
@@ -141,7 +183,7 @@ module Stationery
       ops = []
       ops << "/#{@page.use(:ExtGState, @resources.opacity(opacity))} gs" if opacity && opacity < 1
       yield ops
-      emit("q", *ops, "Q")
+      artifact { emit("q", *ops, "Q") }
     end
 
     def emit(*ops)

data/lib/stationery/document.rb

@@ -24,7 +24,7 @@ module Stationery
                       superclass.config.transform_values(&:dup)
                     else
                       { page: { size: :letter, margin: 36 }, families: {}, fallbacks: [], text: {}, metadata: {},
-                        templates: [], regions: [], strict: false }
+                        templates: [], regions: [], strict: false, tagged: false }
                     end
       end
 
@@ -55,6 +55,13 @@ module Stationery
         config[:strict] = value
       end
 
+      # Writes a tagged (accessible) PDF: a structure tree of headings,
+      # paragraphs and figures, and headers and footers marked as artifacts.
+      # Set `metadata lang:` and give images `alt:` text.
+      def tagged(value = true) # rubocop:disable Style/OptionalBooleanParameter
+        config[:tagged] = value
+      end
+
       # Encrypts every render with the standard security handler; see
       # PDF::Encryption::StandardSecurity for the options.
       def encrypt(**)
@@ -80,26 +87,29 @@ module Stationery
       end
     end
 
-    attr_reader :warnings
+    # `fields` is every form field's name and value from the last render.
+    attr_reader :warnings, :fields
 
     def page_options = self.class.config[:page]
     def metadata = self.class.config[:metadata]
 
-    def to_pdf(target = nil, strict: self.class.config[:strict], debug: false, encrypt: self.class.config[:encrypt])
+    def to_pdf(target = nil, strict: self.class.config[:strict], debug: false, encrypt: self.class.config[:encrypt],
+               tagged: self.class.config[:tagged])
       encryption = encrypt && PDF::Encryption::StandardSecurity.new(**encrypt)
+      tagging = Tagging::Tree.new if tagged
       warnings = Warnings.new
       book = Fonts::FontBook.new(self.class.config[:families], fallbacks: self.class.config[:fallbacks], warnings:)
       call(builder = Builder.new(book:, text: self.class.config[:text]))
       resources = Resources.new
-      regions = Regions.new(self.class.config[:regions], measure: region_measure(book))
-      paginator = Layout::Paginator.new(resources:, page: page_options, warnings:, debug:, regions:)
-      pages = paginator.paginate(builder.root)
-      PageTemplates.new(self, book:, resources:, debug:, regions:, warnings:).apply(pages)
-      outline = builder.outline.resolve(Structure.resolve(pages, warnings:, resources:, book:))
+      pages = paginate(builder.root, book:, resources:, warnings:, debug:, tagging:)
+      outline = builder.outline.resolve(Structure.resolve(pages, warnings:, resources:, book:, tagging:))
+      tagging&.audit(pages, warnings, lang: metadata[:lang])
       @warnings = warnings
+      @fields = Forms::AcroForm.values(pages)
       raise WarningsError, warnings if strict && warnings.any?
 
-      write(PDF::Assembler.new(pages:, resources:, info:, outline:, encryption:).render, target)
+      assembler = PDF::Assembler.new(pages:, resources:, info:, outline:, encryption:, tagging:, lang: metadata[:lang])
+      write(assembler.render, target)
     end
 
     # Used by page templates to build nodes into their own root.
@@ -120,6 +130,14 @@ module Stationery
 
     private
 
+    def paginate(root, book:, resources:, warnings:, debug:, tagging:)
+      regions = Regions.new(self.class.config[:regions], measure: region_measure(book))
+      paginator = Layout::Paginator.new(resources:, page: page_options, warnings:, debug:, regions:, tagging:)
+      paginator.paginate(root).tap do |pages|
+        PageTemplates.new(self, book:, resources:, debug:, regions:, warnings:, tagging:).apply(pages)
+      end
+    end
+
     def region_measure(book)
       page = Page.new(**page_options)
       lambda do |region, number|
@@ -129,7 +147,7 @@ module Stationery
     end
 
     def info
-      metadata.to_h do |key, value|
+      metadata.except(:lang).to_h do |key, value|
         [INFO_KEYS.fetch(key.to_sym) { key.to_sym }, value.is_a?(Array) ? value.join(", ") : value]
       end
     end

data/lib/stationery/elements/forms.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Stationery
+  # Interactive form fields. Each takes a name (dotted names group fields,
+  # "address.city") and lays out like a box, or at a fixed page position with
+  # `at: [x, y]`.
+  module Elements
+    # A text input. `width:` is :full or points; `multiline:`, `max_length:`,
+    # `comb:` (a cell count, or true with max_length:), `read_only:`,
+    # `required:`, `font_size:`, `border:`, `background:` and `radius:`.
+    def text_field(name, value: "", width: :full, height: 22, at: nil, **)
+      field_node(Forms::Field.new(:text, name, value: value.to_s, **), width:, height:, at:)
+    end
+
+    # A check box `size` points square, with an optional label to its right.
+    def checkbox(name, checked: false, size: 12, label: nil, at: nil, **)
+      field = Forms::Field.new(:checkbox, name, value: checked == true, **)
+      field_node(field, width: size, height: size, at:, label:)
+    end
+
+    # One choice of the radio group `name`; its `value` becomes the group's
+    # value when checked.
+    def radio(name, value, checked: false, size: 12, label: nil, at: nil, **)
+      field = Forms::Field.new(:radio, name, value: value.to_s, checked:, **)
+      field_node(field, width: size, height: size, at:, label:)
+    end
+
+    # A drop-down (combo box) of `options`; `editable: true` also accepts
+    # typed values.
+    def select(name, options:, value: nil, width: :full, height: 22, at: nil, **)
+      field = Forms::Field.new(:select, name, value: value&.to_s, options: options.map(&:to_s), **)
+      field_node(field, width:, height:, at:)
+    end
+
+    # An empty signature field for the signer to fill, drawn as a rule over
+    # the label.
+    def signature_field(name, width: :full, height: 40, label: "Signature", at: nil, **)
+      field = Forms::Field.new(:signature, name, label: label.to_s, **)
+      field_node(field, width:, height:, at:)
+    end
+
+    private
+
+    def field_node(field, width:, height:, at:, label: nil)
+      label &&= field_label(label)
+      node = Layout::Field.new(field, height:, width:, label:)
+      @_builder.add(at ? Layout::Positioned.new(node, x: at[0], y: at[1]) : node)
+    end
+
+    def field_label(label)
+      style = @_builder.style
+      Layout::Text.new([Text::Run.new(label.to_s, style)], context: @_builder.context(style))
+    end
+  end
+end

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/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

@@ -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,
@@ -49,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, &)
@@ -65,15 +90,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 +120,8 @@ module Stationery
       @_builder.add(node)
     end
 
+    # `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/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