stationery 0.1.0 → 0.2.0

data/lib/stationery/pdf/assembler.rb

@@ -4,31 +4,38 @@ module Stationery
   module PDF
     # Writes finished pages, their shared resources and document info as PDF.
     class Assembler
-      def initialize(pages:, resources:, info: {})
+      def initialize(pages:, resources:, info: {}, outline: [])
         @pages = pages
         @resources = resources
         @info = info
+        @outline = outline
       end
 
       def render
         writer = Writer.new
         tree = writer.reserve
         refs = @resources.build(writer)
-        kids = @pages.map { |page| write_page(writer, page, tree, refs) }
+        kids = @kids = @pages.map { writer.reserve }
+        @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({ Type: :Catalog, Pages: tree })
+        root = writer.add(catalog(tree, OutlineWriter.new(writer, @outline, kids).write))
         writer.render(root:, info: writer.add(info_dictionary))
       end
 
       private
 
-      def write_page(writer, page, tree, refs)
+      def catalog(tree, outlines)
+        catalog = { Type: :Catalog, Pages: tree }
+        outlines ? catalog.merge(Outlines: outlines, PageMode: :UseOutlines) : catalog
+      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?
-        writer.add(dictionary)
+        writer.set(ref, dictionary)
       end
 
       def page_resources(page, refs)
@@ -38,8 +45,12 @@ module Stationery
       end
 
       def annotation(link)
-        { Type: :Annot, Subtype: :Link, Rect: link[:rect], Border: [0, 0, 0],
-          A: { Type: :Action, S: :URI, URI: link[:url].b } }
+        target = if (dest = link[:dest])
+                   { Dest: [@kids.fetch(dest.page), :XYZ, nil, dest.top, nil] }
+                 else
+                   { A: { Type: :Action, S: :URI, URI: link[:url].b } }
+                 end
+        { Type: :Annot, Subtype: :Link, Rect: link[:rect], Border: [0, 0, 0], **target }
       end
 
       def info_dictionary

data/lib/stationery/pdf/outline_writer.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Stationery
+  module PDF
+    # Writes outline items as the /Outlines tree. Each item nests under the
+    # nearest earlier item of a shallower level, so a level jump (1 → 3) or a
+    # leading level-2 item still lands somewhere sensible.
+    class OutlineWriter
+      Node = Data.define(:item, :ref, :children) do
+        def open? = item.nil? || item.open
+      end
+
+      def initialize(writer, items, page_refs)
+        @writer = writer
+        @items = items
+        @page_refs = page_refs
+      end
+
+      # The /Outlines root reference, or nil when there is nothing to write.
+      def write
+        return if @items.empty?
+
+        root = tree
+        write_children(root)
+        @writer.set(root.ref, { Type: :Outlines, First: root.children.first.ref, Last: root.children.last.ref,
+                                Count: visible(root) })
+      end
+
+      private
+
+      def tree
+        root = Node.new(nil, @writer.reserve, [])
+        stack = []
+        @items.each do |item|
+          stack.pop while stack.any? && stack.last.item.level >= item.level
+          node = Node.new(item, @writer.reserve, [])
+          (stack.last || root).children << node
+          stack << node
+        end
+        root
+      end
+
+      def write_children(parent)
+        parent.children.each_with_index do |node, index|
+          write_children(node)
+          siblings = { Prev: index.positive? ? parent.children[index - 1].ref : nil,
+                       Next: parent.children[index + 1]&.ref }
+          @writer.set(node.ref, dictionary(node, parent).merge(siblings).compact)
+        end
+      end
+
+      def dictionary(node, parent)
+        dest = node.item.dest
+        {
+          Title: TextString.new(node.item.title), Parent: parent.ref,
+          First: node.children.first&.ref, Last: node.children.last&.ref, Count: count(node),
+          Dest: [@page_refs.fetch(dest.page), :XYZ, nil, dest.top, nil]
+        }
+      end
+
+      # Items shown when `node` is expanded: its children plus the visible
+      # descendants of each open child.
+      def visible(node) = node.children.sum { |child| 1 + (child.open? ? visible(child) : 0) }
+
+      def count(node)
+        return if node.children.empty?
+
+        node.open? ? visible(node) : -visible(node)
+      end
+    end
+  end
+end

data/lib/stationery/pdf/serializer.rb

@@ -41,7 +41,11 @@ module Stationery
       def number(value)
         return value.to_s if value.is_a?(Integer)
 
-        str = format("%.4f", value).sub(/\.?0+\z/, "")
+        str = format("%.4f", value)
+        last = str.bytesize
+        last -= 1 while str.getbyte(last - 1) == 48 # "0"
+        last -= 1 if str.getbyte(last - 1) == 46 # "."
+        str = str.byteslice(0, last)
         str == "-0" ? "0" : str
       end
 

data/lib/stationery/pdf/writer.rb

@@ -30,6 +30,10 @@ module Stationery
       end
 
       def render(root:, info:)
+        if (missing = @objects.index(nil))
+          raise Error, "object #{missing + 1} reserved but never set"
+        end
+
         out = HEADER.dup
         offsets = @objects.each_with_index.map { |object, index| write_object(out, index + 1, object) }
         xref = out.bytesize

data/lib/stationery/preview.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "stationery"
+
+module Stationery
+  # Browsable sample documents, like ActionMailer previews. Each public method
+  # returns one document:
+  #
+  #   # 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")))
+  #   end
+  class Preview
+    REGISTRY_LOCK = Mutex.new
+
+    class << self
+      def inherited(subclass)
+        super
+        REGISTRY_LOCK.synchronize { Preview.registry << subclass }
+      end
+
+      # Named subclasses with at least one preview; a name defined again (a
+      # reloaded file) keeps its latest class.
+      def all
+        classes = REGISTRY_LOCK.synchronize { Preview.registry.dup }
+        classes.select { it.name && it.pdfs.any? }.reverse.uniq(&:name).sort_by(&:preview_name)
+      end
+
+      # `load`, not `require`: edited previews show up without a restart.
+      def load(paths)
+        paths.each { |path| Dir["#{path}/**/*_preview.rb"].each { |file| Kernel.load(file) } }
+      end
+
+      # "invoice_pdf/paid" => [InvoicePdfPreview, "paid"]
+      def find(path)
+        name, _, pdf = path.to_s.rpartition("/")
+        klass = all.find { it.preview_name == name }
+        [klass, pdf] if klass&.pdfs&.include?(pdf)
+      end
+
+      def preview_name = underscore(name.delete_suffix("Preview"))
+      def pdfs = public_instance_methods(false).sort.map(&:to_s)
+
+      protected
+
+      def registry = (@registry ||= []) # rubocop:disable ThreadSafety/ClassInstanceVariable
+
+      private
+
+      def underscore(name)
+        name.gsub("::", "/").gsub(/([A-Z\d]+)([A-Z][a-z])/, '\1_\2').gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase
+      end
+    end
+
+    def render(name, params = {})
+      method = public_method(name)
+      document = method.arity.zero? ? method.call : method.call(params)
+      return document if document.respond_to?(:to_pdf)
+
+      raise Error, "#{self.class}##{name} must return a Stationery::Document (got #{document.class})"
+    end
+  end
+end

data/lib/stationery/rails/previews_controller.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "erb"
+require "stationery/preview"
+
+module Stationery
+  # Serves Stationery::Preview classes at /rails/stationery/previews. Loaded
+  # by the Railtie when config.stationery.show_previews is on.
+  class PreviewsController < ActionController::Base
+    before_action :require_previews
+    before_action :load_previews
+
+    def index
+      paths = Preview.all.flat_map { |klass| klass.pdfs.map { "#{klass.preview_name}/#{it}" } }
+      render html: page(paths).html_safe
+    end
+
+    def show
+      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"
+    end
+
+    private
+
+    def config = ::Rails.application.config.stationery
+
+    def require_previews
+      head :not_found unless config.show_previews
+    end
+
+    def load_previews
+      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}")
+        %(<li><a href="#{href}">#{ERB::Util.html_escape(path)}</a> <a href="#{href}?debug=1">debug</a></li>)
+      end
+      <<~HTML
+        <!doctype html>
+        <html>
+          <head><meta charset="utf-8"><title>PDF previews</title></head>
+          <body style="font-family: system-ui, sans-serif; margin: 2rem">
+            <h1>PDF previews</h1>
+            <ul>#{items.join("\n")}</ul>
+            #{"<p>No previews found in #{ERB::Util.html_escape(config.preview_paths.join(", "))}.</p>" if items.empty?}
+          </body>
+        </html>
+      HTML
+    end
+  end
+end

data/lib/stationery/rails.rb

@@ -18,3 +18,5 @@ end
 if defined?(ActiveSupport) && ActiveSupport.respond_to?(:on_load)
   ActiveSupport.on_load(:action_controller) { include Stationery::Rails }
 end
+
+require_relative "railtie" if defined?(Rails::Railtie)

data/lib/stationery/railtie.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Stationery
+  # Loaded by stationery/rails inside a Rails app. Adds `render pdf:` and the
+  # app's font directories. Configure in config/application.rb:
+  #
+  #   config.stationery.renderer = false            # keep another gem's render pdf:
+  #   config.stationery.font_paths = ["app/fonts"]  # relative to Rails.root
+  #   config.stationery.preview_paths = ["spec/pdfs/previews"] # see Stationery::Preview
+  #   config.stationery.show_previews = true        # default: development only
+  class Railtie < ::Rails::Railtie
+    config.stationery = ActiveSupport::OrderedOptions.new
+    config.stationery.renderer = true
+    config.stationery.font_paths = ["vendor/fonts"]
+    config.stationery.preview_paths = ["spec/pdfs/previews", "test/pdfs/previews"]
+    config.stationery.show_previews = ::Rails.env.development?
+
+    initializer "stationery.font_paths" do |app|
+      Railtie.add_font_paths(app.root, app.config.stationery.font_paths)
+    end
+
+    initializer "stationery.renderer" do |app|
+      Railtie.add_renderer if app.config.stationery.renderer
+    end
+
+    initializer "stationery.previews" do |app|
+      Railtie.add_previews(app.routes) if app.config.stationery.show_previews
+    end
+
+    def self.add_font_paths(root, dirs)
+      dirs.each do |dir|
+        path = root.join(dir).to_s
+        Stationery.font_paths << path if File.directory?(path) && !Stationery.font_paths.include?(path)
+      end
+    end
+
+    def self.preview_paths(root, dirs) = dirs.map { root.join(it).to_s }.select { File.directory?(it) }
+
+    def self.add_previews(routes)
+      ActiveSupport.on_load(:action_controller_base) { require "stationery/rails/previews_controller" }
+      routes.prepend do
+        get "/rails/stationery/previews" => "stationery/previews#index", :as => :stationery_previews
+        get "/rails/stationery/previews/*path" => "stationery/previews#show"
+      end
+    end
+
+    def self.add_renderer
+      ActiveSupport.on_load(:action_controller) do
+        ActionController::Renderers.add(:pdf) do |document, options|
+          unless document.respond_to?(:to_pdf)
+            raise ArgumentError, "render pdf: expects a Stationery::Document (got #{document.class})"
+          end
+
+          send_pdf(document, **{ filename: options[:filename],
+                                 disposition: options.fetch(:disposition, "inline") }.compact)
+        end
+      end
+    end
+  end
+end

data/lib/stationery/regions.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Stationery
+  # A header or footer declaration: which slot, how much space it reserves
+  # (nil = measured), the gap to the body, the pages it applies to and the
+  # block that draws it.
+  Region = Data.define(:slot, :height, :gap, :on, :block)
+
+  # A document's header and footer declarations. Later declarations win for
+  # the pages they match; a region without a height is measured once, at the
+  # first page that asks for it.
+  class Regions
+    SELECTORS = %i[all first rest odd even last].freeze
+    SLOTS = %i[header footer].freeze
+
+    def self.validate!(on)
+      return on if SELECTORS.include?(on) || on.is_a?(Integer) || on.is_a?(Range) || on.respond_to?(:call)
+
+      raise ArgumentError, "on: takes #{SELECTORS.map(&:inspect).join(", ")}, a page number, a range or a proc, " \
+                           "got #{on.inspect}"
+    end
+
+    def self.matches?(on, number, last: false)
+      case on
+      when :all then true
+      when :first then number == 1
+      when :rest then number > 1
+      when :odd then number.odd?
+      when :even then number.even?
+      when :last then last
+      when Integer then number == on
+      when Range then on.cover?(number)
+      else on.call(number)
+      end
+    end
+
+    def initialize(entries, measure:)
+      @entries = entries
+      @measure = measure
+      @heights = {}.compare_by_identity
+      @last = entries.any? { |entry| entry.on == :last }
+    end
+
+    def entry_for(slot, number, last: false)
+      @entries.reverse_each.find { |entry| entry.slot == slot && self.class.matches?(entry.on, number, last:) }
+    end
+
+    # [top, bottom] points taken from the body on page `number`.
+    def reserve(number, last: false)
+      SLOTS.map do |slot|
+        entry = entry_for(slot, number, last:)
+        height = entry ? height_of(entry, number) : 0
+        height.positive? ? height + entry.gap : 0
+      end
+    end
+
+    # Whether page `number` would reserve different space as the last page.
+    def last_sensitive?(number) = @last && reserve(number, last: true) != reserve(number)
+
+    def height_of(entry, number)
+      return entry.height if entry.height
+      return 0 unless entry.block
+
+      @heights[entry] ||= @measure.call(entry, number)
+    end
+  end
+end

data/lib/stationery/rich/nodes.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Stationery
+  # The block model rich-text parsers (HTML, Markdown) produce and elements render.
+  module Rich
+    # A run of text with its marks: any of bold:, italic:, underline:, strike:, code:, link: (href),
+    # script: (:sub/:sup) and break: true, a hard line break whose text is "".
+    Inline = Data.define(:text, :marks) do
+      def self.break = new(text: "", marks: { break: true })
+
+      def initialize(text:, marks: {}) = super(text: text.to_s, marks: marks.frozen? ? marks : marks.dup.freeze)
+      def break? = marks[:break] == true
+    end
+
+    Paragraph = Data.define(:inlines)
+    Heading = Data.define(:level, :inlines)
+    List = Data.define(:ordered, :start, :items)
+    Blockquote = Data.define(:blocks)
+    CodeBlock = Data.define(:text, :language)
+    Rule = Data.define
+    Table = Data.define(:rows)
+    Cell = Data.define(:header, :align, :blocks)
+    Image = Data.define(:src, :alt, :width, :height)
+
+    # Operations on inline sequences shared by the parsers.
+    module Inlines
+      module_function
+
+      # Joins adjacent inlines with equal marks and drops empty ones; breaks and images pass through.
+      def merge(items)
+        items.each_with_object([]) do |item, merged|
+          next merged << item unless item.is_a?(Inline) && !item.break?
+          next if item.text.empty?
+
+          last = merged.last
+          if last.is_a?(Inline) && !last.break? && last.marks == item.marks
+            merged[-1] = last.with(text: last.text + item.text)
+          else
+            merged << item
+          end
+        end
+      end
+
+      # Groups inlines into paragraphs, with each image standing as a block between them.
+      def paragraphs(items)
+        items.chunk_while { |a, b| !a.is_a?(Image) && !b.is_a?(Image) }.filter_map do |run|
+          next run.first if run.first.is_a?(Image)
+
+          inlines = merge(block_given? ? yield(run) : run)
+          Paragraph.new(inlines:) unless inlines.empty?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Rich
+    class Renderer
+      # Writes inlines into a Text::RunsBuilder, nesting one builder call per mark.
+      class Inlines
+        STYLE_STEPS = {
+          weight: ->(value) { [:b] if value == :bold },
+          style: ->(value) { [:i] if value == :italic },
+          underline: ->(value) { [:u] if value },
+          strikethrough: ->(value) { [:strikethrough] if value },
+          color: ->(value) { [:color, value] if value },
+          size: ->(value) { [:size, value] if value },
+          font: ->(value) { [:font, value] if value }
+        }.freeze
+
+        MARK_STEPS = {
+          bold: [[:b]], italic: [[:i]], underline: [[:u]], strike: [[:strikethrough]]
+        }.freeze
+
+        def initialize(runs, styles)
+          @runs = runs
+          @styles = styles
+        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 nest(steps, text)
+          return @runs.plain(text) if steps.empty?
+
+          name, *args = steps.first
+          @runs.public_send(name, *args) { nest(steps.drop(1), text) }
+        end
+
+        def steps(mark, value)
+          case mark
+          when :link then [[:link, value], *style_steps(@styles[:a])]
+          when :code then style_steps(@styles[:code])
+          when :script then [[value]]
+          else MARK_STEPS.fetch(mark, [])
+          end
+        end
+
+        def style_steps(style) = style.filter_map { |key, value| STYLE_STEPS[key]&.call(value) }
+      end
+    end
+  end
+end

data/lib/stationery/rich/renderer.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require_relative "nodes"
+require_relative "styles"
+require_relative "renderer/inlines"
+
+module Stationery
+  module Rich
+    # Draws rich-text blocks with a component's element DSL. Images come from
+    # `images:` (a callable given the src, returning a path, an IO or nil) or
+    # from files under `base_path:`; remote URLs are never fetched.
+    class Renderer
+      REMOTE = /\A[a-z][a-z0-9+.-]*:/i
+
+      def initialize(component, builder, gap:, styles:, images:, base_path:, bookmarks: false)
+        @component = component
+        @builder = builder
+        @gap = gap
+        @styles = Styles.resolve(styles)
+        @images = images
+        @base_path = base_path && File.expand_path(base_path.to_s)
+        @bookmarks = bookmarks
+      end
+
+      def render(blocks) = @component.group(gap: @gap) { blocks.each { |block| block(block) } }
+
+      private
+
+      def block(block)
+        case block
+        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 CodeBlock then code(block)
+        when Rule then @component.rule(**@styles[:hr])
+        when Table then table(block)
+        when Image then image(block)
+        end
+      end
+
+      def paragraph(inlines, **)
+        @component.text(**) { |runs| Inlines.new(runs, @styles).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))
+      end
+
+      def heading_bookmark(heading)
+        return unless @bookmarks && heading.level <= 3
+
+        { title: heading.inlines.grep(Inline).map(&:text).join, level: heading.level }
+      end
+
+      def list(list)
+        options = list.ordered ? { start: list.start || 1 } : {}
+        @component.public_send(list.ordered ? :ol : :ul, **options) do
+          list.items.each do |blocks|
+            @component.li { @component.text_style(**@styles[:li]) { render(blocks) } }
+          end
+        end
+      end
+
+      def code(block)
+        font = @styles[:code][:font]
+        @component.box(**@styles[:pre]) { @component.text(block.text, **({ font: } if font)) }
+      end
+
+      def table(table)
+        header = table.rows.first&.all?(&:header) ? 1 : 0
+        rows = table.rows.map { |row| row.map { |cell| cell_content(cell) } }
+        @component.table(rows, header:, cell: @styles[:table][:cell])
+      end
+
+      def cell_content(cell)
+        style = cell.header ? @styles[:table][:header] : {}
+        -> { @component.text_style(**style, align: cell.align) { render(cell.blocks) } }
+      end
+
+      def image(node)
+        source = resolve(node.src)
+        return unless source
+
+        loaded = Images.load(source)
+        @component.image(loaded, **dimensions(node, loaded))
+      rescue UnsupportedImage => e
+        skip(node.src, e.message)
+      end
+
+      def resolve(src)
+        return @images.call(src) || skip(src, "not found") if @images
+        return skip(src, "remote") if REMOTE.match?(src)
+        return skip(src, "not found") unless @base_path
+
+        path = File.expand_path(src, @base_path)
+        return skip(src, "outside base_path") unless path.start_with?(@base_path + File::SEPARATOR)
+
+        File.file?(path) ? path : skip(src, "not found")
+      end
+
+      def dimensions(node, loaded)
+        width = node.width
+        height = node.height
+        limit = @styles[:img][:max_width]
+        natural = width || (height ? loaded.width * height.fdiv(loaded.height) : loaded.width)
+        return { width:, height: } unless limit && natural > limit
+
+        { width: limit, height: height && (height * limit.fdiv(natural)) }
+      end
+
+      def skip(source, reason)
+        @builder.warnings << Warnings::SkippedImage.new(source:, reason:)
+        nil
+      end
+    end
+  end
+end

data/lib/stationery/rich/styles.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Rich
+    # How the html and markdown elements style each kind of block. Heading
+    # `scale:` multiplies the current text size; a `size:` in points wins.
+    module Styles
+      HEADING_SCALES = [2.0, 1.6, 1.3, 1.1, 1.0, 0.9].freeze
+
+      DEFAULTS = {
+        **HEADING_SCALES.each_with_index.to_h do |scale, index|
+          [:"h#{index + 1}", { scale:, weight: :bold, keep_with_next: true }]
+        end,
+        p: {},
+        a: { color: "#2563EB", underline: true },
+        code: { font: nil },
+        pre: { background: "#F3F4F6", padding: 8, radius: 4 },
+        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 } },
+        li: {},
+        img: { max_width: nil }
+      }.freeze
+
+      module_function
+
+      def resolve(overrides) = merge(DEFAULTS, overrides)
+
+      def merge(base, overrides)
+        base.merge(overrides) { |_, old, new| old.is_a?(Hash) && new.is_a?(Hash) ? merge(old, new) : new }
+      end
+    end
+  end
+end