stationery 0.3.0 → 0.5.0

data/lib/stationery/layout/stack.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Layout
+    # A base flow with layers painted over it. The base sets the height and
+    # widths; each Layer is placed relative to the stack's rectangle and takes
+    # no space, so it can overhang the edges. A stack never splits: it moves
+    # to the next page whole (and is reported as an Overflow when taller than
+    # a page).
+    class Stack < Node
+      attr_reader :base, :layers
+
+      def initialize(base, layers)
+        super()
+        @base = base
+        @layers = layers
+      end
+
+      def measure(width) = @base.measure(width)
+      def natural_width = @base.natural_width
+      def min_width = @base.min_width
+      def fixed_width(available) = @base.fixed_width(available)
+      def prefer_whole? = true
+
+      def paint(canvas, x, y, width, height = nil, **)
+        height ||= measure(width)
+        @base.paint(canvas, x, y, width, height)
+        @layers.each { |layer| layer.paint(canvas, x, y, width, height) }
+        canvas.debug_rect(x, y, width, height, :stack)
+      end
+    end
+
+    # A box placed over a Stack by CSS-like insets. `top:`, `right:`,
+    # `bottom:`, `left:`, `width:` and `height:` are points, or fractions of
+    # the stack's width (horizontal ones) or height (vertical ones) when given
+    # as a Rational or a Float between -1 and 1; negative points overhang.
+    # Without `left:`/`top:` the layer sits at the stack's left/top edge;
+    # without `width:` it takes its content's natural width, at most the
+    # stack's, and without `height:` its content's height.
+    class Layer
+      def initialize(box, top: nil, right: nil, bottom: nil, left: nil, width: nil, height: nil)
+        @box = box
+        @top = top
+        @right = right
+        @bottom = bottom
+        @left = left
+        @width = width
+        @height = height
+      end
+
+      def paint(canvas, x, y, width, height)
+        own = layer_width(width)
+        tall = @height ? resolve(@height, height) : @box.measure(own)
+        @box.paint(canvas, x + offset(@left, @right, width, own), y + offset(@top, @bottom, height, tall), own, tall)
+      end
+
+      private
+
+      # Where the layer's near edge sits along one axis of the stack: `start`
+      # points from the start edge, else `finish` points before the end edge.
+      def offset(start, finish, extent, own)
+        return resolve(start, extent) if start
+        return extent - resolve(finish, extent) - own if finish
+
+        0
+      end
+
+      def layer_width(width)
+        return [@box.natural_width, width].min unless @width
+
+        resolve(@width, width)
+      end
+
+      def resolve(value, extent)
+        fraction?(value) ? extent * value : value
+      end
+
+      def fraction?(value) = value.is_a?(Rational) || (value.is_a?(Float) && value.abs <= 1)
+    end
+  end
+end

data/lib/stationery/layout/svg.rb

@@ -6,8 +6,10 @@ module Stationery
     # follows the viewBox's aspect ratio), never wider than the space given.
     class Svg < Node
       # `context` gives SVG text its font book and default family.
-      def initialize(document, width: nil, height: nil, color: "#000000", context: nil)
+      # `alt:` describes the drawing in a tagged PDF; `alt: false` marks it decorative.
+      def initialize(document, width: nil, height: nil, color: "#000000", context: nil, alt: nil)
         super()
+        @tag = alt == false ? nil : Tagging::Element.new(:Figure, alt:, kind: :svg)
         @document = document
         @context = context
         @width = width
@@ -28,8 +30,10 @@ module Stationery
 
       def paint(canvas, x, y, width, _height = nil, **)
         w, h = size(width)
-        @document.draw(canvas, x:, y:, width: w, height: h, color: @color, book: @context&.book,
-                               family: @context&.style&.family)
+        canvas.tag(@tag, bbox: [x, y, w, h]) do
+          @document.draw(canvas, x:, y:, width: w, height: h, color: @color, book: @context&.book,
+                                 family: @context&.style&.family)
+        end
         canvas.debug_rect(x, y, w, h, :image)
       end
 

data/lib/stationery/layout/table/cell.rb

@@ -9,7 +9,7 @@ module Stationery
         TEXT_OPTIONS = { size: :size, color: :color, weight: :weight, style: :style, font: :family,
                          letter_spacing: :letter_spacing }.freeze
 
-        attr_reader :content, :options, :colspan, :rowspan
+        attr_reader :content, :options, :colspan, :rowspan, :tag, :row_tag
 
         def initialize(content, options, colspan: 1, rowspan: 1)
           @content = content
@@ -23,7 +23,15 @@ module Stationery
         end
 
         # The same cell holding another node, as a row split into two parts needs.
-        def with_content(node) = Cell.new(node, @options, colspan:, rowspan:)
+        def with_content(node) = Cell.new(node, @options, colspan:, rowspan:).tagged(@tag, @row_tag)
+
+        # Its TH or TD and its row's TR in a tagged PDF; set once, by the
+        # table the cell is first laid out in.
+        def tagged(tag, row_tag)
+          @tag ||= tag
+          @row_tag ||= row_tag
+          self
+        end
 
         # Changes an option and forgets the node built from the old ones.
         def []=(name, value)

data/lib/stationery/layout/table.rb

@@ -10,8 +10,13 @@ module Stationery
       DEFAULT_CELL = { padding: 5, borders: %i[top right bottom left], border_width: 0.5,
                        border_color: "#000000" }.freeze
 
-      def initialize(rows, context:, widths: nil, width: :auto, header: false, split_rows: false, cell: {})
+      # `tag` is the Table element its fragments share; a `continued` fragment
+      # repeats header rows already read on an earlier page.
+      def initialize(rows, context:, widths: nil, width: :auto, header: false, split_rows: false, cell: {},
+                     tag: Tagging::Element.new(:Table), continued: false)
         super()
+        @tag = tag
+        @continued = continued
         @split_rows = split_rows
         @context = context
         @widths = widths
@@ -20,6 +25,7 @@ module Stationery
         defaults = DEFAULT_CELL.merge(cell)
         @cells = rows.map { |row| row.map { |content| build_cell(content, defaults) } }
         check_header
+        tag_cells
         yield self if block_given?
       end
 
@@ -74,11 +80,12 @@ module Stationery
       def paint(canvas, x, y, width, _height = nil, **)
         widths = column_widths(width)
         heights = row_heights(width)
-        grid.placements.each do |p|
-          rect = Rect.new(x + widths[0...p.column].sum, y + heights[0...p.row].sum,
-                          widths[p.columns].sum, heights[p.rows].sum)
-          p.cell.paint(canvas, @context, rect, last_column: p.columns.end == column_count,
-                                               last_row: p.rows.end == row_count)
+        canvas.structure(@tag) do
+          grid.placements.each do |p|
+            rect = Rect.new(x + widths[0...p.column].sum, y + heights[0...p.row].sum,
+                            widths[p.columns].sum, heights[p.rows].sum)
+            paint_cell(canvas, p, rect)
+          end
         end
       end
 
@@ -97,10 +104,34 @@ module Stationery
 
       def grid = @grid ||= Grid.new(@cells)
 
+      def paint_cell(canvas, placement, rect)
+        cell = placement.cell
+        paint = lambda do
+          cell.paint(canvas, @context, rect, last_column: placement.columns.end == column_count,
+                                             last_row: placement.rows.end == row_count)
+        end
+        return canvas.artifact(type: :pagination, &paint) if @continued && placement.row < @header
+
+        canvas.structure(cell.row_tag) { canvas.structure(cell.tag, &paint) }
+      end
+
+      def tag_cells
+        @cells.each_with_index do |row, index|
+          row_tag = Tagging::Element.new(:TR)
+          row.each { |cell| cell.tagged(cell_tag(cell, index < @header), row_tag) }
+        end
+      end
+
+      def cell_tag(cell, header)
+        attributes = { Scope: (:Column if header), ColSpan: (cell.colspan if cell.colspan > 1),
+                       RowSpan: (cell.rowspan if cell.rowspan > 1) }.compact
+        Tagging::Element.new(header ? :TH : :TD, attributes: attributes.empty? ? {} : { Table: attributes })
+      end
+
       def split_before(count)
         return [nil, self] if count == @header
 
-        [with_rows(@cells.first(count)), with_rows(@cells.first(@header) + @cells.drop(count))]
+        [with_rows(@cells.first(count)), with_rows(@cells.first(@header) + @cells.drop(count), continued: true)]
       end
 
       def split_row(row, width, space, fresh:)
@@ -113,7 +144,7 @@ module Stationery
         return unless heads
 
         [with_rows(@cells.first(row) + [heads], widths:),
-         with_rows(@cells.first(@header) + [tails] + @cells.drop(row + 1), widths:)]
+         with_rows(@cells.first(@header) + [tails] + @cells.drop(row + 1), widths:, continued: true)]
       end
 
       def build_cell(content, defaults)
@@ -156,8 +187,9 @@ module Stationery
         @row_heights[width] ||= grid.row_heights(column_widths(width)) { |p, span| p.cell.measure(@context, span) }
       end
 
-      def with_rows(rows, widths: @widths)
-        self.class.new(rows, context: @context, widths:, width: @width, header: @header, split_rows: @split_rows)
+      def with_rows(rows, widths: @widths, continued: @continued)
+        self.class.new(rows, context: @context, widths:, width: @width, header: @header, split_rows: @split_rows,
+                             tag: @tag, continued:)
       end
     end
   end

data/lib/stationery/layout/table_of_contents/entry.rb

@@ -5,7 +5,8 @@ module Stationery
     class TableOfContents
       # One contents row. The title wraps within the room the number slot
       # leaves; the leader and the number sit on its last line, and the whole
-      # row links to the entry's anchor once that anchor has painted.
+      # row links to the entry's anchor once that anchor has painted. Tagged,
+      # it is a TOCI holding the title as a Link and the number as a Reference.
       class Entry < Node
         LEADERS = { dots: { dash: [0, 3], cap: :round, width: 1 }, line: { width: 0.5 } }.freeze
 
@@ -16,20 +17,27 @@ module Stationery
           @options = options
           @slot = slot
           @paragraphs = {}
+          @tag = Tagging::Element.new(:TOCI)
+          @link = Tagging::Element.new(:Link)
+          @reference = Tagging::Element.new(:Reference)
         end
 
         def measure(width) = paragraph(width).height
         def natural_width = paragraph(Float::INFINITY).lines.map(&:width).max.to_f + offset + @slot + @options.gap
 
         def paint(canvas, x, y, width, _height = nil, **)
-          text = paragraph(width)
-          text.draw(canvas, x + offset, y)
-          last = text.lines.last
-          baseline = y + text.height - last.height + last.ascent
-          slot_x = x + width - @slot
-          draw_leader(canvas, x + offset + last.width + 2, slot_x, baseline)
-          canvas.number_slot(@entry.anchor, x: slot_x, baseline:, width: @slot, style: @context.style,
-                                            link: [x + offset, y, width - offset, text.height])
+          canvas.structure(@tag) do
+            text = paragraph(width)
+            text.draw(canvas, x + offset, y, tag: @link)
+            last = text.lines.last
+            baseline = y + text.height - last.height + last.ascent
+            slot_x = x + width - @slot
+            draw_leader(canvas, x + offset + last.width + 2, slot_x, baseline)
+            canvas.structure(@reference) { nil } # its place in reading order; Structure fills it
+            canvas.number_slot(@entry.anchor, x: slot_x, baseline:, width: @slot, style: @context.style,
+                                              link: [x + offset, y, width - offset, text.height],
+                                              tags: [@link, @reference])
+          end
         end
 
         private

data/lib/stationery/layout/table_of_contents.rb

@@ -26,7 +26,7 @@ module Stationery
 
       def rows
         @rows ||= Flow.new(entries.map { |entry| Entry.new(entry, context: @context, options: @options, slot:) },
-                           gap: @options.gap)
+                           gap: @options.gap, tag: Tagging::Element.new(:TOC))
       end
 
       def entries

data/lib/stationery/layout/text.rb

@@ -6,8 +6,9 @@ module Stationery
     class Text < Node
       attr_reader :runs
 
-      def initialize(runs, context:, align: :left, leading: 0, paragraph: nil)
+      def initialize(runs, context:, align: :left, leading: 0, paragraph: nil, tag: Tagging::Element.new(:P))
         super()
+        @tag = tag
         @runs = context.book.fallback(runs)
         @context = context
         @align = align
@@ -21,7 +22,7 @@ module Stationery
       def measure(width) = paragraph(width).height
 
       def paint(canvas, x, y, width, _height = nil, **)
-        paragraph(width).draw(canvas, x, y)
+        paragraph(width).draw(canvas, x, y, tag: @tag)
       end
 
       def split(width, height, **)
@@ -57,7 +58,7 @@ module Stationery
       end
 
       def from(paragraph)
-        self.class.new(@runs, context: @context, align: @align, leading: @leading, paragraph:)
+        self.class.new(@runs, context: @context, align: @align, leading: @leading, paragraph:, tag: @tag)
       end
     end
   end

data/lib/stationery/minitest.rb

@@ -16,7 +16,10 @@ module Stationery
       def assert_pdf_link(subject, url, msg = nil) = assert_pdf(Matchers::HaveLink.new(url), subject, msg)
       def assert_image_count(subject, count, msg = nil) = assert_pdf(Matchers::HaveImageCount.new(count), subject, msg)
       def assert_bookmark(subject, title, msg = nil) = assert_pdf(Matchers::HaveBookmark.new(title), subject, msg)
+      def assert_pdf_language(subject, lang, msg = nil) = assert_pdf(Matchers::HaveLanguage.new(lang), subject, msg)
       def assert_no_pdf_warnings(subject, msg = nil) = assert_pdf(Matchers::HaveNoWarnings.new, subject, msg)
+      def assert_pdf_structure(subject, tree, msg = nil) = assert_pdf(Matchers::HaveStructure.new(tree), subject, msg)
+      def assert_tagged_content(subject, msg = nil) = assert_pdf(Matchers::HaveTaggedContent.new, subject, msg)
 
       def refute_pdf_text(subject, expected, msg = nil)
         matcher = Matchers::HaveText.new(expected)

data/lib/stationery/page.rb

@@ -8,8 +8,11 @@ module Stationery
   class Page
     # Room for the page number of `anchor`, right-aligned in `width` from `x`
     # on `baseline` (top-left coordinates), drawn in `style`. `link` is an
-    # [x, y, w, h] area linked to the anchor only once it resolves.
-    Slot = Data.define(:anchor, :x, :baseline, :width, :style, :link)
+    # [x, y, w, h] area linked to the anchor only once it resolves. `tags` are
+    # its [link, number] structure elements in a tagged PDF.
+    Slot = Data.define(:anchor, :x, :baseline, :width, :style, :link, :tags) do
+      def initialize(anchor:, x:, baseline:, width:, style:, link:, tags: nil) = super
+    end
 
     SIZES = {
       a3: [841.89, 1190.55], a4: [595.28, 841.89], a5: [419.53, 595.28],

data/lib/stationery/page_templates.rb

@@ -7,8 +7,9 @@ module Stationery
   # Paints a document's headers, footers and page templates on every
   # finished page.
   class PageTemplates
-    def initialize(document, book:, resources:, debug: false, regions: nil, warnings: [])
+    def initialize(document, book:, resources:, debug: false, regions: nil, warnings: [], tagging: nil)
       @document = document
+      @tagging = tagging
       @debug = debug
       @book = book
       @resources = resources
@@ -38,7 +39,7 @@ module Stationery
         reserved = @regions.height_of(region, info.number)
         overflow(info.number, height, reserved)
         y = slot == :header ? box.y : box.bottom - height
-        paint(page, root, Rect.new(box.x, y, box.width, height))
+        paint(page, root, Rect.new(box.x, y, box.width, height), subtype: slot)
       end
     end
 
@@ -50,9 +51,11 @@ module Stationery
 
     def root(info, block) = @document.template_root(info, book: @book, &block)
 
-    def paint(page, root, rect, layer = :foreground)
+    # Everything a template paints is a pagination artifact in a tagged PDF.
+    def paint(page, root, rect, layer = :foreground, subtype: nil)
       mark = page.content.bytesize
-      root.paint(Canvas.new(page, @resources, template: true, debug: @debug), rect.x, rect.y, rect.width)
+      canvas = Canvas.new(page, @resources, template: true, debug: @debug, tagging: @tagging)
+      canvas.artifact(type: :pagination, subtype:) { root.paint(canvas, rect.x, rect.y, rect.width) }
       page.content.prepend(page.content.slice!(mark..)) if layer == :background
     end
   end

data/lib/stationery/pdf/assembler.rb

@@ -4,7 +4,11 @@ module Stationery
   module PDF
     # Writes finished pages, their shared resources and document info as PDF.
     class Assembler
-      def initialize(pages:, resources:, info: {}, outline: [], encryption: nil)
+      # `tagging:` (a Tagging::Tree) writes the structure tree of a tagged PDF;
+      # `lang:` is the document's natural language.
+      def initialize(pages:, resources:, info: {}, outline: [], encryption: nil, tagging: nil, lang: nil)
+        @tagging = tagging
+        @lang = lang
         @pages = pages
         @resources = resources
         @info = info
@@ -14,28 +18,43 @@ module Stationery
 
       def render
         writer = Writer.new(encryption: @encryption)
+        @form = Forms::AcroForm.new(writer)
         tree = writer.reserve
         refs = @resources.build(writer)
         kids = @kids = @pages.map { writer.reserve }
+        @structure = @tagging && Tagging::Writer.new(@tagging, pages: @pages, refs: kids)
         @pages.each_with_index { |page, index| write_page(writer, page, kids[index], tree, refs) }
         writer.set(tree, { Type: :Pages, Kids: kids, Count: kids.size })
-        root = writer.add(catalog(tree, OutlineWriter.new(writer, @outline, kids).write))
+        outlines = OutlineWriter.new(writer, @outline, kids).write
+        root = writer.add(catalog(tree, outlines, @form.write).merge(accessibility(writer)))
         writer.render(root:, info: writer.add(info_dictionary))
       end
 
       private
 
-      def catalog(tree, outlines)
+      def catalog(tree, outlines, form)
         catalog = { Type: :Catalog, Pages: tree }
+        catalog[:AcroForm] = form if form
         outlines ? catalog.merge(Outlines: outlines, PageMode: :UseOutlines) : catalog
       end
 
+      def accessibility(writer)
+        entries = @lang ? { Lang: PDF::TextString.new(@lang.to_s) } : {}
+        return entries unless @structure
+
+        entries.merge!(@structure.write(writer))
+        @info[:Title] ? entries.merge(ViewerPreferences: { DisplayDocTitle: true }) : entries
+      end
+
       def write_page(writer, page, ref, tree, refs)
         dictionary = {
           Type: :Page, Parent: tree, MediaBox: [0, 0, *page.size],
           Contents: writer.add(Stream.new(page.content)), Resources: page_resources(page, refs)
         }
-        dictionary[:Annots] = page.annotations.map { |link| writer.add(annotation(link)) } if page.annotations.any?
+        if page.annotations.any?
+          dictionary[:Annots] = page.annotations.map { |annot| annotation_ref(writer, annot, ref) }
+        end
+        dictionary.merge!(@structure.page_entries(page)) if @structure
         writer.set(ref, dictionary)
       end
 
@@ -45,6 +64,19 @@ module Stationery
         end
       end
 
+      def annotation_ref(writer, annotation, page)
+        if annotation[:widget]
+          return @form.add(annotation[:widget], annotation[:rect], page) do |widget_ref|
+            @structure ? @structure.annotation(annotation, widget_ref) : {}
+          end
+        end
+
+        ref = writer.reserve
+        dictionary = annotation(annotation)
+        dictionary = dictionary.merge(@structure.annotation(annotation, ref)) if @structure
+        writer.set(ref, dictionary)
+      end
+
       def annotation(link)
         target = if (dest = link[:dest])
                    { Dest: [@kids.fetch(dest.page), :XYZ, nil, dest.top, nil] }

data/lib/stationery/preview.rb

@@ -4,15 +4,19 @@ require "stationery"
 
 module Stationery
   # Browsable sample documents, like ActionMailer previews. Each public method
-  # returns one document:
+  # returns one document. `around_render` wraps building and rendering it,
+  # for anything that must be in effect while the document paints:
   #
   #   # spec/pdfs/previews/invoice_pdf_preview.rb
   #   class InvoicePdfPreview < Stationery::Preview
   #     def paid = InvoicePdf.new(Invoice.first)
   #     def overdue(params) = InvoicePdf.new(Invoice.find(params.fetch("id")))
+  #
+  #     def around_render(_name, params) = I18n.with_locale(params.fetch("locale", I18n.default_locale)) { yield }
   #   end
   class Preview
     REGISTRY_LOCK = Mutex.new
+    HOOKS = %w[around_render].freeze
 
     class << self
       def inherited(subclass)
@@ -40,7 +44,7 @@ module Stationery
       end
 
       def preview_name = underscore(name.delete_suffix("Preview"))
-      def pdfs = public_instance_methods(false).sort.map(&:to_s)
+      def pdfs = public_instance_methods(false).sort.map(&:to_s) - HOOKS
 
       protected
 
@@ -53,6 +57,19 @@ module Stationery
       end
     end
 
+    # The PDF bytes of one preview, built and rendered inside around_render.
+    # `debug: true` reaches to_pdf when the document accepts it.
+    def to_pdf(name, params = {}, debug: false)
+      around_render(name, params) do
+        document = render(name, params)
+        document.to_pdf(**(debug && accepts_debug?(document) ? { debug: true } : {}))
+      end
+    end
+
+    # Override to wrap the preview: set an I18n locale, Current attributes,
+    # a time zone. Both the preview method and to_pdf run inside the block.
+    def around_render(_name, _params) = yield
+
     def render(name, params = {})
       method = public_method(name)
       document = method.arity.zero? ? method.call : method.call(params)
@@ -60,5 +77,9 @@ module Stationery
 
       raise Error, "#{self.class}##{name} must return a Stationery::Document (got #{document.class})"
     end
+
+    private
+
+    def accepts_debug?(document) = document.method(:to_pdf).parameters.include?(%i[key debug])
   end
 end

data/lib/stationery/rails/previews_controller.rb

@@ -19,8 +19,8 @@ module Stationery
       klass, pdf = Preview.find(params[:path])
       return head(:not_found) unless klass
 
-      document = klass.new.render(pdf, request.query_parameters.except("debug"))
-      send_data document.to_pdf(**debug_option(document)), type: "application/pdf", disposition: "inline"
+      pdf = klass.new.to_pdf(pdf, request.query_parameters.except("debug"), debug: params[:debug].present?)
+      send_data pdf, type: "application/pdf", disposition: "inline"
     end
 
     private
@@ -35,11 +35,6 @@ module Stationery
       Preview.load(Railtie.preview_paths(::Rails.root, config.preview_paths))
     end
 
-    def debug_option(document)
-      debug = params[:debug].present? && document.method(:to_pdf).parameters.include?(%i[key debug])
-      debug ? { debug: true } : {}
-    end
-
     def page(paths)
       items = paths.map do |path|
         href = ERB::Util.html_escape("#{request.path.chomp("/")}/#{path}")

data/lib/stationery/rich/renderer/inlines.rb

@@ -19,16 +19,24 @@ module Stationery
           bold: [[:b]], italic: [[:i]], underline: [[:u]], strike: [[:strikethrough]]
         }.freeze
 
-        def initialize(runs, styles)
+        def initialize(runs, styles, links = Links.new(:all, nil))
           @runs = runs
           @styles = styles
+          @links = links
         end
 
         def write(inlines) = inlines.grep(Inline).each { |inline| inline.break? ? @runs.br : write_one(inline) }
 
         private
 
-        def write_one(inline) = nest(inline.marks.flat_map { |mark, value| steps(mark, value) }, inline.text)
+        def write_one(inline) = nest(marks_of(inline).flat_map { |mark, value| steps(mark, value) }, inline.text)
+
+        def marks_of(inline)
+          marks = inline.marks
+          return marks unless marks.key?(:link) && !@links.allowed?(marks[:link])
+
+          marks.except(:link)
+        end
 
         def nest(steps, text)
           return @runs.plain(text) if steps.empty?

data/lib/stationery/rich/renderer/links.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Rich
+    class Renderer
+      # Which hrefs become link annotations: `#anchor` always, otherwise only
+      # the allowed URL schemes (case-insensitive). A dropped href keeps its
+      # text and is reported once as a DroppedLink warning. `:all` keeps every
+      # href, for trusted sources.
+      class Links
+        SCHEME = /\A([a-z][a-z0-9+.-]*):/i
+
+        def initialize(schemes, warnings)
+          @schemes = schemes == :all ? :all : Array(schemes).map { |scheme| scheme.to_s.downcase }
+          @warnings = warnings
+        end
+
+        def allowed?(href)
+          return true if @schemes == :all || href.start_with?("#")
+          return true if @schemes.include?(href[SCHEME, 1].to_s.downcase)
+
+          @warnings << Warnings::DroppedLink.new(href:)
+          false
+        end
+      end
+    end
+  end
+end

data/lib/stationery/rich/renderer.rb

@@ -3,6 +3,7 @@
 require_relative "nodes"
 require_relative "styles"
 require_relative "renderer/inlines"
+require_relative "renderer/links"
 
 module Stationery
   module Rich
@@ -11,8 +12,9 @@ module Stationery
     # from files under `base_path:`; remote URLs are never fetched.
     class Renderer
       REMOTE = /\A[a-z][a-z0-9+.-]*:/i
+      LINK_SCHEMES = %w[http https mailto tel].freeze
 
-      def initialize(component, builder, gap:, styles:, images:, base_path:, bookmarks: false)
+      def initialize(component, builder, gap:, styles:, images:, base_path:, bookmarks: false, links: nil)
         @component = component
         @builder = builder
         @gap = gap
@@ -20,6 +22,7 @@ module Stationery
         @images = images
         @base_path = base_path && File.expand_path(base_path.to_s)
         @bookmarks = bookmarks
+        @links = Links.new(links || LINK_SCHEMES, builder.warnings)
       end
 
       def render(blocks) = @component.group(gap: @gap) { blocks.each { |block| block(block) } }
@@ -31,7 +34,7 @@ module Stationery
         when Paragraph then paragraph(block.inlines, **@styles[:p])
         when Heading then heading(block)
         when List then list(block)
-        when Blockquote then @component.box(**@styles[:blockquote]) { render(block.blocks) }
+        when Blockquote then @component.box(role: :blockquote, **@styles[:blockquote]) { render(block.blocks) }
         when CodeBlock then code(block)
         when Rule then @component.rule(**@styles[:hr])
         when Table then table(block)
@@ -40,14 +43,14 @@ module Stationery
       end
 
       def paragraph(inlines, **)
-        @component.text(**) { |runs| Inlines.new(runs, @styles).write(inlines) }
+        @component.text(**) { |runs| Inlines.new(runs, @styles, @links).write(inlines) }
       end
 
       def heading(heading)
         style = @styles[:"h#{heading.level}"]
         size = style[:size] || (@builder.style.size * style.fetch(:scale, 1))
         bookmark = heading_bookmark(heading)
-        paragraph(heading.inlines, **style.except(:scale), size:, **({ bookmark: } if bookmark))
+        paragraph(heading.inlines, **style.except(:scale), size:, heading: heading.level, **({ bookmark: } if bookmark))
       end
 
       def heading_bookmark(heading)
@@ -57,7 +60,7 @@ module Stationery
       end
 
       def list(list)
-        options = list.ordered ? { start: list.start || 1 } : {}
+        options = list.ordered ? { **@styles[:ol], start: list.start || 1 } : @styles[:ul]
         @component.public_send(list.ordered ? :ol : :ul, **options) do
           list.items.each do |blocks|
             @component.li { @component.text_style(**@styles[:li]) { render(blocks) } }
@@ -86,7 +89,7 @@ module Stationery
         return unless source
 
         loaded = Images.load(source)
-        @component.image(loaded, **dimensions(node, loaded))
+        @component.image(loaded, alt: node.alt, **dimensions(node, loaded))
       rescue UnsupportedImage => e
         skip(node.src, e.message)
       end