stationery 0.1.0

data/lib/stationery/document.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Stationery
+  # A whole PDF. Configure it at class level and describe it in view_template:
+  #
+  #   class Invoice < Stationery::Document
+  #     page size: :a4, margin: 40
+  #     font_family "Inter", regular: "Inter-Regular.ttf", bold: "Inter-Bold.ttf"
+  #     default_text font: "Inter", size: 9
+  #     metadata title: "Invoice"
+  #     page_template { |page| box(at: [40, page.height - 30]) { text "#{page.number}/#{page.count}" } }
+  #
+  #     def view_template = text("Hello")
+  #   end
+  #
+  #   Invoice.new.to_pdf # => "%PDF-1.7..."
+  class Document < Component
+    INFO_KEYS = { title: :Title, author: :Author, subject: :Subject, keywords: :Keywords, creator: :Creator,
+                  producer: :Producer }.freeze
+
+    class << self
+      def config
+        @config ||= if superclass.respond_to?(:config)
+                      superclass.config.transform_values(&:dup)
+                    else
+                      { page: { size: :letter, margin: 36 }, families: {}, text: {}, metadata: {}, templates: [] }
+                    end
+      end
+
+      def page(size: :letter, margin: 36, layout: :portrait)
+        config[:page] = { size:, margin:, layout: }
+      end
+
+      def font_family(name, **paths)
+        config[:families][name.to_s] = Fonts::Family.new(name, **paths)
+      end
+
+      def default_text(**options)
+        config[:text] = config[:text].merge(options)
+      end
+
+      def metadata(**info)
+        config[:metadata] = config[:metadata].merge(info)
+      end
+
+      # Runs after pagination on every page. `layer: :background` paints under
+      # the page's content.
+      def page_template(layer: :foreground, &block)
+        config[:templates] << [layer, block]
+      end
+    end
+
+    attr_reader :warnings
+
+    def page_options = self.class.config[:page]
+    def metadata = self.class.config[:metadata]
+
+    def to_pdf(target = nil)
+      book = Fonts::FontBook.new(self.class.config[:families])
+      call(builder = Builder.new(book:, text: self.class.config[:text]))
+      resources = Resources.new
+      paginator = Layout::Paginator.new(resources:, page: page_options)
+      pages = paginator.paginate(builder.root)
+      @warnings = paginator.warnings
+      PageTemplates.new(self, book:, resources:).apply(pages)
+      write(PDF::Assembler.new(pages:, resources:, info:).render, target)
+    end
+
+    # Used by page templates to build nodes into their own root.
+    def build_with(builder)
+      previous = @_builder
+      @_builder = builder
+      yield
+    ensure
+      @_builder = previous
+    end
+
+    private
+
+    def info
+      metadata.to_h do |key, value|
+        [INFO_KEYS.fetch(key.to_sym) { key.to_sym }, value.is_a?(Array) ? value.join(", ") : value]
+      end
+    end
+
+    def write(pdf, target)
+      if target.respond_to?(:write)
+        target.write(pdf)
+      elsif target
+        File.binwrite(target.to_s, pdf)
+      end
+      pdf
+    end
+  end
+end

data/lib/stationery/elements.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Stationery
+  # The element DSL available inside every component's view_template.
+  module Elements
+    PARAGRAPH_DEFAULTS = { align: :left, leading: 0 }.freeze
+
+    # A paragraph. Plain strings are always literal; pass `markup: true` to
+    # read inline tags, or a block to build styled runs in Ruby.
+    def text(content = nil, markup: false, keep_with_next: nil, break_inside: nil, **options, &)
+      settings = PARAGRAPH_DEFAULTS.merge(@_builder.text_defaults.slice(:align, :leading)).merge(options)
+      style = @_builder.style(options)
+      runs = text_runs(content, style, markup, &)
+      node = Layout::Text.new(runs, context: @_builder.context(style), align: settings[:align],
+                                    leading: settings[:leading])
+      node.keep_with_next = keep_with_next
+      node.break_inside = break_inside
+      @_builder.add(node)
+    end
+
+    # A container with padding, background, border and radius. `at: [x, y]`
+    # places it at a fixed page position outside the flow.
+    def box(at: nil, align: nil, gap: 0, width: nil, keep_with_next: nil, **, &)
+      node = Layout::Box.new(container(align:, gap:, &), width:, **)
+      node.keep_with_next = keep_with_next
+      @_builder.add(at ? Layout::Positioned.new(node, x: at[0], y: at[1], width:) : node)
+    end
+
+    def row(gap: 0, align: :top)
+      columns = Builder::Columns.new
+      @_builder.within(columns) { yield if block_given? }
+      @_builder.add(Layout::Row.new(columns.nodes, gap:, align:))
+    end
+
+    # A row column: `width:` in points, as a fraction (0.5), :auto or nil for
+    # an equal share. Takes every box option.
+    def column(width: nil, align: nil, gap: 0, **, &)
+      @_builder.add(Layout::Box.new(container(align:, gap:, &), width:, **))
+    end
+
+    # Children kept in one vertical group; `keep_together: true` moves the
+    # whole group to the next page rather than splitting it.
+    def group(gap: 0, keep_together: false, keep_with_next: nil, &)
+      flow = container(gap:, &)
+      flow.break_inside = :avoid if keep_together
+      flow.keep_with_next = keep_with_next
+      @_builder.add(flow)
+    end
+
+    def table(rows, widths: nil, width: :auto, header: false, cell: {}, &)
+      @_builder.add(Layout::Table.new(rows, context: @_builder.context, widths:, width:, header:, cell:, &))
+    end
+
+    def image(source, align: nil, **)
+      node = Layout::Image.new(source, **)
+      @_builder.add(align ? Layout::Flow.new([node], align:) : node)
+    end
+
+    def rule(**) = @_builder.add(Layout::Rule.new(**))
+    def spacer(height) = @_builder.add(Layout::Spacer.new(height))
+    def page_break = @_builder.add(Layout::PageBreak.new)
+
+    # Draw directly: the block receives the canvas and the reserved rectangle.
+    def canvas(height:, at: nil, width: nil, &)
+      node = Layout::CanvasNode.new(height:, &)
+      @_builder.add(at ? Layout::Positioned.new(node, x: at[0], y: at[1], width:) : node)
+    end
+
+    # Text defaults (font, size, colour, weight, align, leading, …) for a block.
+    def text_style(**, &)
+      @_builder.with_text(**, &)
+    end
+
+    private
+
+    def container(align: nil, gap: 0, &)
+      flow = Layout::Flow.new([], gap:, align: align || :left)
+      @_builder.within(flow) do
+        align ? @_builder.with_text(align:) { yield_content(&) } : yield_content(&)
+      end
+    end
+
+    def text_runs(content, style, markup, &)
+      return Text::RunsBuilder.build(style, &) if block_given?
+      return Text::Markup.parse(content, style) if markup
+
+      [Text::Run.new(content.to_s, style)]
+    end
+  end
+end

data/lib/stationery/errors.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Stationery
+  class Error < StandardError; end
+
+  # A font file stationery cannot read or embed (CFF, collections, WOFF, …).
+  class UnsupportedFont < Error; end
+
+  # An image format stationery cannot embed (WebP, GIF, interlaced PNG, …).
+  class UnsupportedImage < Error; end
+end

data/lib/stationery/fonts/cmap.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Fonts
+    # Parses a font's Unicode character map (formats 4 and 12) into a Hash of
+    # codepoint => glyph id.
+    module Cmap
+      module_function
+
+      def parse(ttf)
+        t = ttf.table_offset("cmap")
+        subtables = Array.new(ttf.u16(t + 2)) do |i|
+          record = t + 4 + (i * 8)
+          offset = t + ttf.u32(record + 4)
+          [ttf.u16(record), ttf.u16(record + 2), offset, ttf.u16(offset)]
+        end
+
+        best = preferred(subtables)
+        raise UnsupportedFont, "font has no Unicode character map" unless best
+
+        best[3] == 12 ? format12(ttf, best[2]) : format4(ttf, best[2])
+      end
+
+      # Full Unicode (format 12) wins over the Basic Multilingual Plane (format 4).
+      def preferred(subtables)
+        subtables.find { |platform, encoding, _, format| platform == 3 && encoding == 10 && format == 12 } ||
+          subtables.find { |platform, _, _, format| platform.zero? && format == 12 } ||
+          subtables.find { |platform, encoding, _, format| platform == 3 && encoding == 1 && format == 4 } ||
+          subtables.find { |platform, _, _, format| platform.zero? && format == 4 }
+      end
+
+      def format4(ttf, offset)
+        map = {}
+        seg_count = ttf.u16(offset + 6) / 2
+        ends = offset + 14
+        starts = ends + (seg_count * 2) + 2
+        deltas = starts + (seg_count * 2)
+        range_offsets = deltas + (seg_count * 2)
+
+        seg_count.times do |i|
+          range = ttf.u16(starts + (i * 2))..ttf.u16(ends + (i * 2))
+          format4_segment(ttf, map, range, ttf.u16(deltas + (i * 2)), range_offsets + (i * 2))
+        end
+        map
+      end
+
+      def format4_segment(ttf, map, range, delta, range_offset_pos)
+        range_offset = ttf.u16(range_offset_pos)
+        first = range.begin
+        range.each do |codepoint|
+          next if codepoint == 0xFFFF
+
+          gid = if range_offset.zero?
+                  (codepoint + delta) & 0xFFFF
+                else
+                  glyph = ttf.u16(range_offset_pos + range_offset + ((codepoint - first) * 2))
+                  glyph.zero? ? 0 : (glyph + delta) & 0xFFFF
+                end
+          map[codepoint] = gid unless gid.zero?
+        end
+      end
+
+      def format12(ttf, offset)
+        map = {}
+        ttf.u32(offset + 12).times do |i|
+          group = offset + 16 + (i * 12)
+          first = ttf.u32(group)
+          gid = ttf.u32(group + 8)
+          (first..ttf.u32(group + 4)).each { |codepoint| map[codepoint] = gid + codepoint - first }
+        end
+        map
+      end
+    end
+  end
+end

data/lib/stationery/fonts/family.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Fonts
+    # A named set of up to four TrueType files. A style without its own file is
+    # drawn from the nearest one with synthetic bold (stroked outlines) and/or
+    # synthetic oblique (sheared text matrix).
+    class Family
+      STYLES = %i[regular bold italic bold_italic].freeze
+
+      Face = Data.define(:path, :synthetic_bold, :synthetic_oblique)
+
+      attr_reader :name, :paths
+
+      def initialize(name, **paths)
+        unknown = paths.keys - STYLES
+        raise ArgumentError, "unknown font style #{unknown.join(", ")} (use #{STYLES.join(", ")})" if unknown.any?
+        raise ArgumentError, "font family #{name} needs a regular face" unless paths[:regular]
+
+        @name = name.to_s
+        @paths = paths.transform_values(&:to_s).freeze
+      end
+
+      def face(weight: :regular, style: :normal)
+        bold = bold?(weight)
+        italic = style.to_sym == :italic
+        candidates(bold, italic).each do |key, synthetic_bold, synthetic_oblique|
+          return Face.new(@paths[key], synthetic_bold, synthetic_oblique) if @paths[key]
+        end
+      end
+
+      private
+
+      def bold?(weight)
+        weight.is_a?(Numeric) ? weight >= 600 : %i[bold semibold].include?(weight.to_sym)
+      end
+
+      def candidates(bold, italic)
+        if bold && italic
+          [[:bold_italic, false, false], [:bold, false, true], [:italic, true, false], [:regular, true, true]]
+        elsif bold
+          [[:bold, false, false], [:regular, true, false]]
+        elsif italic
+          [[:italic, false, false], [:regular, false, true]]
+        else
+          [[:regular, false, false]]
+        end
+      end
+    end
+  end
+end

data/lib/stationery/fonts/font.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require "digest/md5"
+
+module Stationery
+  module Fonts
+    # One TrueType font as used by one document: measures text, encodes it as
+    # glyph ids and remembers which glyphs were drawn so only those are embedded.
+    #
+    # Embedded as a Type0 font over a CIDFontType2 with Identity-H encoding and a
+    # ToUnicode map, so text extracts and searches correctly.
+    class Font
+      OBLIQUE_SKEW = Math.tan(12 * Math::PI / 180)
+
+      attr_reader :ttf
+
+      def initialize(ttf)
+        @ttf = ttf
+        @used = {}
+        @widths = {}
+      end
+
+      def inspect = "#<#{self.class} #{@ttf.postscript_name} used=#{@used.size}>"
+
+      def width_of(text, size, letter_spacing: 0)
+        units = text.each_char.sum { |char| @widths[char] ||= @ttf.advance(@ttf.glyph_id(char.ord)) }
+        scale(units, size) + (letter_spacing * text.length)
+      end
+
+      def ascender(size) = scale(@ttf.ascender, size)
+      def descender(size) = -scale(@ttf.descender, size)
+      def line_gap(size) = scale(@ttf.line_gap, size)
+      def line_height(size) = ascender(size) + descender(size) + line_gap(size)
+      def underline_position(size) = scale(@ttf.underline_position, size)
+      def underline_thickness(size) = scale(@ttf.underline_thickness, size)
+      def strikeout_position(size) = scale(@ttf.strikeout_position, size)
+      def strikeout_size(size) = scale(@ttf.strikeout_size, size)
+      def glyph?(char) = @ttf.glyph?(char)
+
+      def bold?
+        @ttf.weight >= 600
+      end
+
+      def encode(text)
+        text.each_char.map do |char|
+          gid = @ttf.glyph_id(char.ord)
+          @used[gid] ||= char
+          gid
+        end.pack("n*")
+      end
+
+      def used?
+        @used.any?
+      end
+
+      def build(writer)
+        gids = @used.keys.sort
+        subset, mapping = Subset.build(@ttf, gids)
+        name = :"#{subset_tag(gids)}+#{@ttf.postscript_name}"
+
+        writer.add(
+          Type: :Font, Subtype: :Type0, BaseFont: name, Encoding: :"Identity-H",
+          DescendantFonts: [cid_font(writer, name, gids, subset, mapping)],
+          ToUnicode: writer.add(PDF::Stream.new(to_unicode_cmap))
+        )
+      end
+
+      private
+
+      def cid_font(writer, name, gids, subset, mapping)
+        writer.add(
+          Type: :Font, Subtype: :CIDFontType2, BaseFont: name,
+          CIDSystemInfo: { Registry: "Adobe", Ordering: "Identity", Supplement: 0 },
+          FontDescriptor: descriptor(writer, name, subset),
+          DW: glyph_space(@ttf.advance(0)), W: glyph_widths(gids),
+          CIDToGIDMap: writer.add(PDF::Stream.new(cid_to_gid_map(gids, mapping)))
+        )
+      end
+
+      def descriptor(writer, name, subset)
+        writer.add(
+          Type: :FontDescriptor, FontName: name, Flags: flags,
+          FontBBox: @ttf.bbox.map { |v| glyph_space(v) }, ItalicAngle: @ttf.italic_angle,
+          Ascent: glyph_space(@ttf.ascender), Descent: glyph_space(@ttf.descender),
+          CapHeight: glyph_space(@ttf.cap_height), XHeight: glyph_space(@ttf.x_height),
+          StemV: bold? ? 120 : 80,
+          FontFile2: writer.add(PDF::Stream.new(subset, { Length1: subset.bytesize }))
+        )
+      end
+
+      def scale(units, size)
+        units * size / @ttf.units_per_em.to_f
+      end
+
+      def glyph_space(units)
+        (units * 1000.0 / @ttf.units_per_em).round
+      end
+
+      def flags
+        flags = 32 # Nonsymbolic
+        flags |= 1 if @ttf.fixed_pitch?
+        flags |= 64 unless @ttf.italic_angle.zero?
+        flags
+      end
+
+      # Subset fonts are named with six uppercase letters: ABCDEF+OpenSans-Regular.
+      def subset_tag(gids)
+        Digest::MD5.digest(gids.pack("n*") + @ttf.postscript_name).bytes.first(6).map { |b| (65 + (b % 26)).chr }.join
+      end
+
+      # Text uses the original glyph ids as CIDs; this maps them to the subset's ids.
+      def cid_to_gid_map(gids, mapping)
+        map = Array.new((gids.max || 0) + 1, 0)
+        gids.each { |gid| map[gid] = mapping.fetch(gid) }
+        map.pack("n*")
+      end
+
+      def glyph_widths(gids)
+        gids.slice_when { |a, b| b != a + 1 }.flat_map do |run|
+          [run.first, run.map { |gid| glyph_space(@ttf.advance(gid)) }]
+        end
+      end
+
+      def to_unicode_cmap
+        mappings = @used.sort.map do |gid, char|
+          format("<%<gid>04X> <%<utf16>s>", gid:, utf16: char.encode(Encoding::UTF_16BE).unpack1("H*").upcase)
+        end
+        blocks = mappings.each_slice(100).map { |slice| "#{slice.size} beginbfchar\n#{slice.join("\n")}\nendbfchar" }
+
+        <<~CMAP
+          /CIDInit /ProcSet findresource begin
+          12 dict begin
+          begincmap
+          /CIDSystemInfo << /Registry (Adobe) /Ordering (UCS) /Supplement 0 >> def
+          /CMapName /Adobe-Identity-UCS def
+          /CMapType 2 def
+          1 begincodespacerange
+          <0000> <FFFF>
+          endcodespacerange
+          #{blocks.join("\n")}
+          endcmap
+          CMapName currentdict /CMap defineresource pop
+          end
+          end
+        CMAP
+      end
+    end
+  end
+end

data/lib/stationery/fonts/font_book.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Fonts
+    # A document's font families and the Font objects it has drawn with. Each
+    # document gets its own book so glyph usage (and so subsetting) is per
+    # document, while the parsed TrueType data is shared through the Registry.
+    class FontBook
+      attr_reader :families
+
+      def initialize(families = {})
+        @families = families.dup
+        @fonts = {}
+      end
+
+      def inspect = "#<#{self.class} families=#{@families.keys.inspect}>"
+
+      def register(name, **paths)
+        @families[name.to_s] = Family.new(name, **paths)
+      end
+
+      # Returns [Font, Family::Face] for a Text::Style.
+      def resolve(style)
+        face = family(style.family).face(weight: style.weight, style: style.style)
+        [@fonts[face.path] ||= Font.new(Registry.load(face.path)), face]
+      end
+
+      private
+
+      def family(name)
+        @families[name.to_s] || @families.values.first ||
+          raise(Error, "no font registered; declare one with `font_family \"Name\", regular: \"path/to/font.ttf\"`")
+      end
+    end
+  end
+end

data/lib/stationery/fonts/name_table.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Fonts
+    # Reads the PostScript name (name id 6) used as the embedded font's BaseFont.
+    module NameTable
+      FORBIDDEN = "[](){}<>/%#"
+
+      module_function
+
+      def postscript_name(ttf)
+        name = find(ttf) if ttf.table?("name")
+        name.nil? || name.empty? ? "Font" : name
+      end
+
+      def find(ttf)
+        t = ttf.table_offset("name")
+        strings = t + ttf.u16(t + 4)
+        ttf.u16(t + 2).times do |i|
+          record = t + 6 + (i * 12)
+          next unless ttf.u16(record + 6) == 6
+
+          raw = ttf.data.byteslice(strings + ttf.u16(record + 10), ttf.u16(record + 8)).dup
+          name = decode(raw, ttf.u16(record)).delete("^!-~").delete(FORBIDDEN)
+          return name unless name.empty?
+        end
+        nil
+      end
+
+      def decode(raw, platform)
+        if platform == 1
+          raw.force_encoding(Encoding::ISO_8859_1).encode(Encoding::UTF_8)
+        else
+          raw.force_encoding(Encoding::UTF_16BE).encode(Encoding::UTF_8, invalid: :replace, undef: :replace)
+        end
+      end
+    end
+  end
+end

data/lib/stationery/fonts/registry.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Fonts
+    # Process-wide cache of parsed TrueType files, keyed by path and mtime so an
+    # edited font is re-read. Parsing is the expensive part; the per-document
+    # Font objects that track used glyphs are cheap wrappers around a parse.
+    module Registry
+      SIZE = 16
+      @cache = {}
+      @mutex = Mutex.new
+
+      class << self
+        def load(path)
+          path = File.expand_path(path.to_s)
+          raise UnsupportedFont, "font file not found: #{path}" unless File.file?(path)
+
+          mtime = File.mtime(path)
+          @mutex.synchronize { fetch(path, mtime) }
+        end
+
+        def clear
+          @mutex.synchronize { @cache.clear }
+        end
+
+        private
+
+        def fetch(path, mtime)
+          cached_mtime, ttf = @cache.delete(path)
+          ttf = TrueType.new(File.binread(path)) unless cached_mtime == mtime
+          @cache[path] = [mtime, ttf]
+          @cache.shift while @cache.size > SIZE
+          ttf
+        end
+      end
+    end
+  end
+end