stationery 0.2.0 → 0.4.0

data/lib/stationery/svg/text.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Stationery
+  module SVG
+    # Lays out a <text> element: its strings and tspans become pieces along
+    # the baseline, a new chunk starting wherever x or y is set, and each
+    # chunk is shifted by its text-anchor. Glyphs are drawn upright at the
+    # transformed origin, sized by the transform's uniform scale, so rotated,
+    # skewed or unevenly scaled text is approximated.
+    class Text
+      ANCHORS = { "middle" => 0.5, "end" => 1.0 }.freeze
+      DEFAULT_SIZE = 16
+
+      Piece = Data.define(:runs, :style, :x, :y, :chunk, :advance)
+
+      def initialize(canvas, painter, book, family)
+        @canvas = canvas
+        @painter = painter
+        @book = book
+        @family = family
+      end
+
+      def draw(element, style)
+        @pieces = []
+        @x = @y = @chunk = 0
+        @space = true
+        place(element, style)
+        trim
+        @pieces.group_by(&:chunk).each_value { |chunk| draw_chunk(chunk) }
+      end
+
+      private
+
+      def place(element, style)
+        move(element.attributes)
+        element.children.each do |child|
+          if child.is_a?(String) then add(child, style)
+          elsif child.name == "tspan" then place(child, style.child(child))
+          end
+        end
+      end
+
+      def move(attributes)
+        x, y, dx, dy = attributes.values_at("x", "y", "dx", "dy").map { |value| first(value) }
+        @chunk += 1 if x || y
+        @x = (x || @x) + (dx || 0)
+        @y = (y || @y) + (dy || 0)
+      end
+
+      def first(value) = value.to_s.split(/[\s,]+/).find { |part| !part.empty? }&.to_f
+
+      # Collapses the space between pieces and at the start of the text.
+      def add(string, style)
+        string = string.lstrip if @space
+        return if string.empty?
+
+        @space = string.end_with?(" ")
+        @pieces << piece(string, style, @x, @y)
+        @x += @pieces.last.advance
+      end
+
+      def piece(string, style, x, y, chunk = @chunk)
+        italic = style.values["font-style"].to_s.match?(/italic|oblique/)
+        text_style = Stationery::Text::Style.new(family: family(style), size: size(style), weight: weight(style),
+                                                 style: italic ? :italic : :normal)
+        runs = @book.fallback([Stationery::Text::Run.new(string, text_style)])
+        advance = runs.sum { |run| font(run).width_of(run.text, text_style.size) }
+        Piece.new(runs, style, x, y, chunk, advance)
+      end
+
+      def trim
+        last = @pieces.last or return
+        text = last.runs.map(&:text).join
+        return unless text.end_with?(" ")
+
+        @pieces[-1] = piece(text.rstrip, last.style, last.x, last.y, last.chunk)
+      end
+
+      def draw_chunk(pieces)
+        width = pieces.last.x + pieces.last.advance - pieces.first.x
+        shift = -width * ANCHORS.fetch(pieces.first.style.values["text-anchor"].to_s, 0)
+        pieces.each { |piece| draw_piece(piece, shift) }
+      end
+
+      def draw_piece(piece, shift)
+        color = @painter.color(piece.style.fill, piece.style)
+        return unless color
+
+        x = piece.x + shift
+        scale = Transform.scale(piece.style.matrix)
+        piece.runs.each do |run|
+          font, face = @book.resolve(run.style)
+          page_x, page_y = Transform.apply(piece.style.matrix, x, piece.y)
+          @canvas.text(run.text, x: page_x, y: page_y, font:, size: run.style.size * scale, color:,
+                                 opacity: Painter.translucent(piece.style.opacity),
+                                 synthetic_bold: face.synthetic_bold, synthetic_oblique: face.synthetic_oblique)
+          x += font.width_of(run.text, run.style.size)
+        end
+      end
+
+      def font(run) = @book.resolve(run.style).first
+
+      # The first family of the list the book knows, else the document's.
+      def family(style)
+        names = style.values["font-family"].to_s.split(",").map { |name| name.strip.delete("'\"") }
+        names.find { |name| !name.empty? && @book.known?(name) } || @family
+      end
+
+      def size(style)
+        size = style.values["font-size"].to_f
+        size.positive? ? size : DEFAULT_SIZE
+      end
+
+      def weight(style)
+        value = style.values["font-weight"].to_s.strip
+        return value.to_i if value.match?(/\A\d+\z/)
+
+        %w[bold bolder].include?(value) ? :bold : :regular
+      end
+    end
+  end
+end

data/lib/stationery/svg/transform.rb

@@ -31,6 +31,17 @@ module Stationery
         multiply(multiply([1, 0, 0, 1, cx, cy], rotation), [1, 0, 0, 1, -cx, -cy])
       end
 
+      def apply(matrix, x, y)
+        a, b, c, d, e, f = matrix
+        [(a * x) + (c * y) + e, (b * x) + (d * y) + f]
+      end
+
+      # The uniform scale a matrix applies to areas, as a length factor.
+      def scale(matrix)
+        a, b, c, d, = matrix
+        Math.sqrt(((a * d) - (b * c)).abs)
+      end
+
       # The transform that applies `inner` first, then `outer`.
       def multiply(outer, inner)
         a, b, c, d, e, f = outer

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
@@ -63,6 +64,20 @@ module Stationery
         outlines ? titles(outlines[:First]) : []
       end
 
+      # The structure tree of a tagged PDF as nested arrays; see StructureReader.
+      def structure = @structure ||= StructureReader.new(reader).tree
+
+      # Whether the catalog marks the PDF as tagged and holds a structure tree.
+      def tagged?
+        catalog = objects.deref!(objects.trailer[:Root])
+        catalog.dig(:MarkInfo, :Marked) == true && !catalog[:StructTreeRoot].nil?
+      end
+
+      # 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

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

@@ -111,6 +111,29 @@ 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)
@@ -118,6 +141,8 @@ module Stationery
       def have_image_count(expected) = HaveImageCount.new(expected)
       def have_bookmark(title) = HaveBookmark.new(title)
       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
@@ -102,9 +117,10 @@ module Stationery
                                            color: style.color, letter_spacing: style.letter_spacing, rise: style.rise,
                                            opacity: style.opacity, underline: style.underline,
                                            strikethrough: style.strikethrough, kerning: style.kerning,
+                                           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/text/style.rb

@@ -6,9 +6,11 @@ module Stationery
 
     # How a run of text looks. Immutable; derive variants with #with.
     Style = Data.define(:family, :size, :weight, :style, :color, :letter_spacing,
-                        :underline, :strikethrough, :script, :link, :opacity, :kerning) do
+                        :underline, :strikethrough, :script, :link, :opacity, :kerning,
+                        :ligatures) do
       def initialize(family:, size: 10, weight: :regular, style: :normal, color: "#000000", letter_spacing: 0,
-                     underline: false, strikethrough: false, script: nil, link: nil, opacity: nil, kerning: true)
+                     underline: false, strikethrough: false, script: nil, link: nil, opacity: nil, kerning: true,
+                     ligatures: true)
         super
       end
 

data/lib/stationery/text/wrapper.rb

@@ -125,7 +125,8 @@ module Stationery
 
       def measure(text, style)
         font = @book.resolve(style).first
-        font.width_of(text, style.render_size, letter_spacing: style.letter_spacing, kerning: style.kerning)
+        font.width_of(text, style.render_size, letter_spacing: style.letter_spacing, kerning: style.kerning,
+                                               ligatures: style.ligatures)
       end
     end
   end

data/lib/stationery/version.rb

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

data/lib/stationery/warnings.rb

@@ -37,6 +37,14 @@ module Stationery
       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)