stationery 0.3.0 → 0.5.0

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/structure.rb

@@ -11,10 +11,13 @@ module Stationery
 
     # Returns the destinations by name; unresolved links are dropped.
     # Runs before resources are written, so slot digits join the font subset.
-    def self.resolve(pages, warnings:, resources: nil, book: nil) = new(pages, warnings, resources, book).resolve
+    def self.resolve(pages, warnings:, resources: nil, book: nil, tagging: nil)
+      new(pages, warnings, resources, book, tagging).resolve
+    end
 
-    def initialize(pages, warnings, resources, book)
+    def initialize(pages, warnings, resources, book, tagging = nil)
       @pages = pages
+      @tagging = tagging
       @warnings = warnings
       @resources = resources
       @book = book
@@ -57,19 +60,22 @@ module Stationery
       font, face = @book.resolve(slot.style)
       style = slot.style
       width = font.width_of(label, style.render_size, letter_spacing: style.letter_spacing)
-      canvas = Canvas.new(page, @resources)
-      canvas.link(*slot.link, "##{slot.anchor}") if slot.link
-      canvas.text(label, x: slot.x + slot.width - width, y: slot.baseline, font:,
-                         size: style.render_size, color: style.color,
-                         letter_spacing: style.letter_spacing, opacity: style.opacity,
-                         synthetic_bold: face.synthetic_bold, synthetic_oblique: face.synthetic_oblique)
+      canvas = Canvas.new(page, @resources, tagging: @tagging)
+      link, number = slot.tags
+      canvas.link(*slot.link, "##{slot.anchor}", tag: link) if slot.link
+      canvas.tag(number) do
+        canvas.text(label, x: slot.x + slot.width - width, y: slot.baseline, font:,
+                           size: style.render_size, color: style.color,
+                           letter_spacing: style.letter_spacing, opacity: style.opacity,
+                           synthetic_bold: face.synthetic_bold, synthetic_oblique: face.synthetic_oblique)
+      end
     end
 
     def link_to(link, index)
       return link unless link.key?(:dest)
 
       destination = @destinations[link[:dest]]
-      return { rect: link[:rect], dest: destination } if destination
+      return link.merge!(dest: destination) if destination
 
       @warnings << Warnings::UnresolvedLink.new(name: link[:dest], page: index + 1)
       nil

data/lib/stationery/tagging/element.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Stationery
+  # Tagged (accessible) PDF: a structure tree of standard structure types
+  # (ISO 32000-1 §14.8.4) whose leaves point at marked content on the pages.
+  module Tagging
+    # Grouping roles a box can take, as standard structure types.
+    ROLES = { section: :Sect, div: :Div, blockquote: :BlockQuote, note: :Note, caption: :Caption,
+              article: :Art, part: :Part }.freeze
+
+    # One marked-content sequence: the page it is on and its MCID there.
+    MarkedContent = Data.define(:page, :mcid)
+
+    # An annotation (the page's link Hash) that belongs to an element.
+    ObjectRef = Data.define(:page, :annotation)
+
+    def self.role(role)
+      ROLES.fetch(role) { raise ArgumentError, "unknown role #{role.inspect} (use #{ROLES.keys.join(", ")})" }
+    end
+
+    def self.heading(level)
+      return :P unless level
+      raise ArgumentError, "heading: takes 1 to 6, got #{level.inspect}" unless (1..6).cover?(level)
+
+      :"H#{level}"
+    end
+
+    # A structure element. Layout nodes create one per source node and share
+    # it with every fragment a split produces, so content continued on the
+    # next page stays one element. It joins the tree where it first paints.
+    class Element
+      CELLS = %i[TD TH].freeze
+
+      attr_reader :type, :alt, :kind, :kids, :parent, :attributes
+
+      # `alt` is a Figure's alternate text; `kind` names what drew it in
+      # warnings; `attributes` are { owner => { key => value } } (/A entries).
+      def initialize(type, alt: nil, kind: nil, attributes: {})
+        @type = type
+        @alt = alt
+        @kind = kind
+        @attributes = attributes.transform_values(&:dup)
+        @kids = []
+      end
+
+      def attached? = !@parent.nil?
+
+      def attach(parent)
+        return if @parent
+
+        @parent = parent
+        parent.kids << self
+      end
+
+      # A bounding box in PDF space, kept from the first fragment painted.
+      def place(bbox)
+        (@attributes[:Layout] ||= {})[:BBox] ||= bbox
+        self
+      end
+
+      def bbox = @attributes.dig(:Layout, :BBox)
+      def marked_content = @kids.grep(MarkedContent)
+      def elements = @kids.grep(Element)
+
+      # Holds no content, so the writer leaves it out; an empty table cell
+      # stays, keeping its row's columns in place.
+      def empty?
+        return false if CELLS.include?(@type)
+
+        @kids.none?(MarkedContent) && @kids.none?(ObjectRef) && elements.all?(&:empty?)
+      end
+    end
+  end
+end

data/lib/stationery/tagging/tree.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Tagging
+    # One render's structure: the Document element and, per page, the element
+    # each MCID belongs to (what the parent tree maps back from).
+    class Tree
+      attr_reader :root
+
+      def initialize
+        @root = Element.new(:Document)
+        @pages = {}.compare_by_identity
+      end
+
+      # The next MCID on `page`, recorded as marked content of `element`.
+      def mark(page, element)
+        marked = (@pages[page] ||= [])
+        marked << element
+        element.kids << MarkedContent.new(page, marked.size - 1)
+        marked.size - 1
+      end
+
+      def marked(page) = @pages.fetch(page, [])
+
+      # Records the accessibility gaps `strict` should catch.
+      def audit(pages, warnings, lang:)
+        warnings << Warnings::MissingLanguage.new unless lang
+        figures(@root).each do |figure|
+          next if figure.alt
+
+          page = pages.index(figure.marked_content.first.page) + 1
+          warnings << Warnings::MissingAlt.new(kind: figure.kind, page:)
+        end
+      end
+
+      private
+
+      def figures(element)
+        element.elements.flat_map { |kid| kid.type == :Figure ? [kid] : figures(kid) }
+      end
+    end
+  end
+end

data/lib/stationery/tagging/writer.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Tagging
+    # Writes a Tree as the catalog's /StructTreeRoot: one StructElem per
+    # element that holds content, and the /ParentTree mapping each page's
+    # /StructParents key to its elements by MCID.
+    class Writer
+      def initialize(tree, pages:, refs:)
+        @tree = tree
+        @page_refs = pages.zip(refs).to_h.compare_by_identity
+        @keys = pages.select { |page| tree.marked(page).any? }.each_with_index.to_h.compare_by_identity
+        @annotations = {}.compare_by_identity
+      end
+
+      # An annotation's entries: the /StructParent key of its element, when it
+      # belongs to one. `ref` is the annotation's reference, for the /OBJR.
+      def annotation(link, ref)
+        return {} unless link[:tag]
+
+        @annotations[link] = [ref, @keys.size + @annotations.size]
+        { StructParent: @annotations[link][1] }
+      end
+
+      # The page dictionary's entries: its parent tree key, when it has one.
+      def page_entries(page)
+        key = @keys[page]
+        key ? { StructParents: key } : {}
+      end
+
+      # Writes the tree and returns the catalog entries pointing at it.
+      def write(writer)
+        root = writer.reserve
+        @refs = {}.compare_by_identity
+        reserve(writer, @tree.root)
+        @refs.each_key { |element| writer.set(@refs[element], dictionary(element, root)) }
+        writer.set(root, { Type: :StructTreeRoot, K: [@refs[@tree.root]], ParentTree: { Nums: parent_tree },
+                           ParentTreeNextKey: @keys.size + @annotations.size })
+        { MarkInfo: { Marked: true }, StructTreeRoot: root }
+      end
+
+      private
+
+      def reserve(writer, element)
+        @refs[element] = writer.reserve
+        element.elements.each { |kid| reserve(writer, kid) unless kid.empty? }
+      end
+
+      def dictionary(element, root)
+        page = element.marked_content.first&.page
+        {
+          Type: :StructElem, S: element.type, P: element.parent ? @refs[element.parent] : root,
+          Pg: page && @page_refs[page], K: element.kids.filter_map { |kid| kid_entry(kid, page) },
+          Alt: element.alt && PDF::TextString.new(element.alt),
+          A: attributes(element)
+        }.compact
+      end
+
+      def kid_entry(kid, page)
+        case kid
+        when Element then @refs[kid]
+        when MarkedContent
+          kid.page.equal?(page) ? kid.mcid : { Type: :MCR, Pg: @page_refs[kid.page], MCID: kid.mcid }
+        when ObjectRef
+          ref, = @annotations[kid.annotation]
+          ref && { Type: :OBJR, Obj: ref, Pg: @page_refs[kid.page] }
+        end
+      end
+
+      def attributes(element)
+        list = element.attributes.map { |owner, values| { O: owner, **values } }
+        list.size > 1 ? list : list.first
+      end
+
+      def parent_tree
+        @keys.flat_map { |page, key| [key, @tree.marked(page).map { |element| @refs[element] }] } +
+          @annotations.flat_map { |link, (_, key)| [key, @refs[link[:tag]]] }
+      end
+    end
+  end
+end

data/lib/stationery/testing/inspector.rb

@@ -3,6 +3,7 @@
 require "pathname"
 require "stringio"
 require "stationery"
+require_relative "structure_reader"
 
 module Stationery
   module Testing
@@ -59,13 +60,33 @@ 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.dig(:MarkInfo, :Marked) == true && !catalog[:StructTreeRoot].nil?
+      end
+
+      # Text shown outside any marked content (neither tagged nor an artifact).
+      def untagged_text
+        @untagged_text ||= reader.pages.flat_map { |page| MarkedText.read(page).unmarked }
+      end
+
       private
 
       def objects = reader.objects
+      def catalog = objects.deref!(objects.trailer[:Root])
 
       def annotations
         reader.pages.flat_map do |page|

data/lib/stationery/testing/marked_text.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "forwardable"
+
+module Stationery
+  module Testing
+    # A pdf-reader receiver that collects a page's text by MCID, and the text
+    # shown outside any marked content. Text on a new baseline starts after
+    # a space, so a paragraph's lines read as one string.
+    class MarkedText
+      extend Forwardable
+
+      STATE = %i[save_graphics_state restore_graphics_state concatenate_matrix begin_text_object end_text_object
+                 set_text_font_and_size move_text_position move_text_position_and_set_leading
+                 set_text_matrix_and_text_line_matrix move_to_start_of_next_line set_text_leading
+                 set_character_spacing set_word_spacing set_text_rise set_horizontal_text_scaling
+                 set_text_rendering_mode].freeze
+
+      def_delegators :@state, *STATE
+
+      # { MCID => text } and the strings shown outside marked content.
+      attr_reader :texts, :unmarked
+
+      def self.read(page) = new(page).tap { |receiver| page.walk(receiver) }
+
+      def initialize(page)
+        @state = ::PDF::Reader::PageState.new(page)
+        @open = []
+        @texts = {}
+        @baselines = {}
+        @unmarked = []
+      end
+
+      def begin_marked_content_with_pl(_tag, properties)
+        @open << (properties[:MCID] if properties.is_a?(Hash))
+      end
+
+      def begin_marked_content(_tag) = @open << nil
+      def end_marked_content = @open.pop
+      def show_text(string) = append(string)
+      def show_text_with_positioning(params) = params.grep(String).each { |string| append(string) }
+
+      private
+
+      def append(string)
+        font = @state.current_font
+        text = font.unpack(string).map { |code| font.to_utf8(code) }.join
+        return @unmarked << text if @open.empty?
+
+        mcid = @open.compact.last
+        return unless mcid
+
+        baseline = @state.trm_transform_point(0, 0).y.round(2)
+        separator = @texts.key?(mcid) && @baselines[mcid] != baseline ? " " : ""
+        @texts[mcid] = "#{@texts[mcid]}#{separator}#{text}"
+        @baselines[mcid] = baseline
+      end
+    end
+  end
+end

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"
 
@@ -111,13 +120,39 @@ module Stationery
         def actual = messages.empty? ? "got none" : "got:\n#{messages.map { |m| "  - #{m}" }.join("\n")}"
       end
 
+      class HaveStructure < Base
+        def description = "have structure #{@expected.inspect}"
+
+        private
+
+        def match?(pdf) = pdf.structure == @expected
+        def actual = "got #{@inspector.structure.inspect}"
+      end
+
+      class HaveTaggedContent < Base
+        def description = "be tagged with every text in marked content"
+
+        private
+
+        def match?(pdf) = pdf.tagged? && pdf.untagged_text.empty?
+
+        def actual
+          return "but it is not tagged" unless @inspector.tagged?
+
+          "got untagged text #{@inspector.untagged_text.inspect}"
+        end
+      end
+
       def have_pdf_text(expected) = HaveText.new(expected)
       def have_pdf_text_on_page(page, expected) = HaveTextOnPage.new(page, expected)
       def have_page_count(expected) = HavePageCount.new(expected)
       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
     end
   end
 end

data/lib/stationery/testing/structure_reader.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative "marked_text"
+
+module Stationery
+  module Testing
+    # Reads a tagged PDF's structure tree as nested arrays, each element's
+    # text taken from the marked content it owns:
+    #
+    #   [[:Document, [[:H1, "Intro"], [:P, ["Read", [:Link, "the docs"], "now"]], [:Figure, "Logo"]]]]
+    #
+    # An element is [type, text] when it holds only text, [type, [kids]]
+    # when it holds elements (with its own text between them), [type] when
+    # empty. A Figure reads as its alt text. Untagged PDFs read as [].
+    class StructureReader
+      def initialize(reader)
+        @reader = reader
+        @objects = reader.objects
+        @texts = {}
+      end
+
+      def tree
+        root = @objects.deref(@objects.deref(@objects.trailer[:Root])[:StructTreeRoot])
+        root ? kids_of(root).grep(Array) : []
+      end
+
+      private
+
+      def element(dictionary)
+        return [dictionary[:S], dictionary[:Alt]].compact if dictionary[:Alt]
+
+        kids = merge(kids_of(dictionary, dictionary[:Pg]))
+        return [dictionary[:S]] if kids.empty?
+
+        [dictionary[:S], kids.size == 1 && kids.first.is_a?(String) ? kids.first : kids]
+      end
+
+      def kids_of(dictionary, page = nil)
+        Array(@objects.deref(dictionary[:K])).filter_map do |kid|
+          kid = @objects.deref(kid)
+          case kid
+          when Integer then text(page, kid)
+          when Hash then kid[:Type] == :MCR ? text(kid[:Pg], kid[:MCID]) : kid_element(kid)
+          end
+        end
+      end
+
+      def kid_element(kid) = kid[:Type] == :OBJR ? nil : element(kid)
+
+      # Adjacent strings (one element's marked content on two lines or pages) join with a space.
+      def merge(kids)
+        kids.each_with_object([]) do |kid, merged|
+          next if kid.is_a?(String) && kid.strip.empty?
+
+          if kid.is_a?(String) && merged.last.is_a?(String)
+            merged[-1] = "#{merged.last} #{kid.strip}"
+          else
+            merged << (kid.is_a?(String) ? kid.strip : kid)
+          end
+        end
+      end
+
+      def text(page, mcid) = page_texts(page)[mcid]
+
+      def page_texts(page)
+        index = @objects.page_references.index(page)
+        @texts[index] ||= MarkedText.read(@reader.page(index + 1)).texts
+      end
+    end
+  end
+end

data/lib/stationery/text/paragraph.rb

@@ -43,17 +43,32 @@ module Stationery
         shrink(max_height)
       end
 
-      def draw(canvas, x, y)
-        top = y
-        @lines.each do |line|
-          offset = x + Geometry.align_offset(@align, @width, line.width)
-          extra = word_spacing(line)
-          spaces = 0
-          line.fragments.each do |fragment|
-            draw_fragment(canvas, fragment, offset + (extra * spaces), top, line, extra)
-            spaces += fragment.text.count(" ")
+      # `tag` is the structure element the text belongs to in a tagged PDF;
+      # linked runs become Link elements inside it.
+      def draw(canvas, x, y, tag: nil)
+        links = Links.new
+        canvas.tag_runs(tag) do |mark|
+          top = y
+          @lines.each do |line|
+            offset = x + Geometry.align_offset(@align, @width, line.width)
+            extra = word_spacing(line)
+            spaces = 0
+            line.fragments.each do |fragment|
+              link = links.for(fragment.style.link)
+              mark.call(link) { draw_fragment(canvas, fragment, offset + (extra * spaces), top, line, extra, link:) }
+              spaces += fragment.text.count(" ")
+            end
+            top += line.height + @leading
           end
-          top += line.height + @leading
+        end
+      end
+
+      # One Link element per run of fragments with the same link target.
+      class Links
+        def for(target)
+          @element = nil unless target == @target
+          @target = target
+          @element = target && (@element || Tagging::Element.new(:Link))
         end
       end
 
@@ -94,7 +109,7 @@ module Stationery
         [(@width - line.width) / line.space_count, 0].max
       end
 
-      def draw_fragment(canvas, fragment, offset, top, line, word_spacing)
+      def draw_fragment(canvas, fragment, offset, top, line, word_spacing, link: nil)
         style = fragment.style
         count_missing(fragment)
         x = offset + fragment.x
@@ -105,7 +120,7 @@ module Stationery
                                            ligatures: style.ligatures,
                                            synthetic_bold: fragment.face.synthetic_bold,
                                            synthetic_oblique: fragment.face.synthetic_oblique, word_spacing:)
-        canvas.link(x, top, width, line.height, style.link) if style.link
+        canvas.link(x, top, width, line.height, style.link, tag: link) if style.link
       end
 
       def count_missing(fragment)

data/lib/stationery/version.rb

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

data/lib/stationery/warnings.rb

@@ -33,10 +33,22 @@ 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
 
+    MissingAlt = Data.define(:kind, :page) do
+      def message = "#{kind} on page #{page} has no alt: text"
+    end
+
+    MissingLanguage = Data.define do
+      def message = "tagged PDF has no language: set metadata lang:"
+    end
+
     def initialize
       @items = []
       @glyphs = Hash.new(0)

data/lib/stationery.rb

@@ -49,11 +49,19 @@ require_relative "stationery/color"
 require_relative "stationery/geometry"
 require_relative "stationery/page"
 require_relative "stationery/resources"
+require_relative "stationery/tagging/element"
+require_relative "stationery/tagging/tree"
+require_relative "stationery/tagging/writer"
 require_relative "stationery/canvas/path"
 require_relative "stationery/canvas/text"
 require_relative "stationery/canvas/debug"
+require_relative "stationery/canvas/marking"
 require_relative "stationery/canvas"
 require_relative "stationery/pdf/outline_writer"
+require_relative "stationery/forms/metrics"
+require_relative "stationery/forms/field"
+require_relative "stationery/forms/appearance"
+require_relative "stationery/forms/acro_form"
 require_relative "stationery/pdf/assembler"
 require_relative "stationery/text/style"
 require_relative "stationery/fonts/fallback"
@@ -99,6 +107,8 @@ 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"
 require_relative "stationery/outline"
@@ -106,6 +116,7 @@ require_relative "stationery/builder"
 require_relative "stationery/elements"
 require_relative "stationery/elements/lists"
 require_relative "stationery/elements/rich"
+require_relative "stationery/elements/forms"
 require_relative "stationery/component"
 require_relative "stationery/regions"
 require_relative "stationery/page_templates"