stationery 0.7.0 → 0.9.0

data/lib/stationery/forms/appearance.rb

@@ -6,28 +6,49 @@ module Stationery
     # a form looks right without relying on the viewer to regenerate it.
     # Variable text sits between `/Tx BMC … EMC`, the part a viewer redraws
     # when the value changes.
+    #
+    # It is drawn when the widget is placed, so the glyphs it uses are in the
+    # fonts before they are subset, and written as streams once the fonts
+    # have their references (#streams).
     class Appearance
       PADDING = 2
       LEADING = 1.15
-      CHECK = { glyph: "4", width: 0.846, middle: 0.345 }.freeze
+      # The check mark's corners in the unit square (y down) and its stroke.
+      CHECK = { points: [[0.22, 0.52], [0.42, 0.72], [0.78, 0.28]], stroke: 0.12 }.freeze
       DOT = 0.45
       SIGNATURE = { rule: 14, label_size: 7, label_baseline: 4, label_gray: 0.42 }.freeze
 
-      def initialize(field, width, height, fonts)
+      # `resources` are the render's, where the field's fonts get their names.
+      def initialize(field, width, height, resources = nil)
         @field = field
         @width = width
         @height = height
-        @fonts = fonts
+        @type = field.typeface.with(resources)
+        @contents = contents
+        keep
+      end
+
+      # Whether everything it draws with is embedded in the file.
+      def embedded? = @type.names.empty? || @type.embedded?
+
+      # The resource names of the fonts it draws with or keeps for editing.
+      def font_names = @type.names
+
+      # What the field's /DA says: the font and size a viewer redraws the
+      # value with. nil for a field without variable text.
+      def default_appearance
+        return unless @field.variable_text?
+
+        "/#{@type.name} #{num(@field.font_size)} Tf 0 g"
       end
 
       # One stream, or a Hash of streams by appearance state for buttons.
-      def normal
-        case @field.kind
-        when :text, :select then stream(frame + variable_text(text_lines))
-        when :checkbox then { @field.on_state => stream(frame + check), Off: stream(frame) }
-        when :radio then { @field.on_state => stream(circle + dot), Off: stream(circle) }
-        when :signature then stream(signature)
-        end
+      # `fonts` are the references by resource name.
+      def streams(fonts)
+        resources = font_names.empty? ? {} : { Font: fonts.slice(*font_names) }
+        return stream(@contents, resources) unless @contents.is_a?(Hash)
+
+        @contents.transform_values { |content| stream(content, resources) }
       end
 
       private
@@ -36,9 +57,29 @@ module Stationery
       def size = @field.font_size
       def num(value) = PDF::Serializer.number(value.is_a?(Float) && value == value.round ? value.round : value)
 
-      def stream(content)
+      def contents
+        case @field.kind
+        when :text, :select then frame + variable_text(text_lines)
+        when :checkbox then { @field.on_state => frame + check, Off: frame }
+        when :radio then { @field.on_state => circle + dot, Off: circle }
+        when :signature then signature
+        end
+      end
+
+      # What a viewer may draw after an edit: the other options of a select,
+      # and the base repertoire of a field that can be typed into.
+      def keep
+        return unless @field.variable_text?
+
+        @type.name
+        return if options[:read_only]
+
+        @type.keep(Array(options[:options]).join, size, repertoire: true)
+      end
+
+      def stream(content, resources)
         PDF::Stream.new(content, { Type: :XObject, Subtype: :Form, BBox: [0, 0, @width, @height],
-                                   Resources: { Font: @fonts } })
+                                   Resources: resources })
       end
 
       def frame
@@ -50,34 +91,49 @@ module Stationery
         end
       end
 
-      # [x, baseline, WinAnsi bytes] runs in PDF space.
+      def middle_baseline = (@height / 2.0) - ((@type.ascent(size) - @type.descent(size)) / 2)
+
+      # [x, baseline, text] runs in PDF space.
       def text_lines
         return comb_cells if options[:comb]
         return multiline_runs if options[:multiline]
 
-        [[PADDING, (@height / 2.0) - (size * (Metrics::ASCENT + Metrics::DESCENT) / 2), Metrics.encode(@field.value)]]
+        [[PADDING, middle_baseline, @field.value.to_s]]
       end
 
       def multiline_runs
-        top = @height - PADDING - (size * Metrics::ASCENT)
-        Metrics.wrap(@field.value, @width - (2 * PADDING), size).each_with_index.map do |line, index|
+        top = @height - PADDING - @type.ascent(size)
+        wrap(@field.value.to_s, @width - (2 * PADDING)).each_with_index.map do |line, index|
           [PADDING, top - (index * size * LEADING), line]
         end
       end
 
+      # The value broken into lines no wider than `width`, keeping its own
+      # line breaks; a word wider than a line stands alone.
+      def wrap(text, width)
+        text.split("\n", -1).flat_map do |paragraph|
+          paragraph.split.each_with_object([+""]) do |word, lines|
+            candidate = lines.last.empty? ? word : "#{lines.last} #{word}"
+            if lines.last.empty? || @type.width(candidate, size) <= width
+              lines[-1] = candidate
+            else
+              lines << word
+            end
+          end
+        end
+      end
+
       def comb_cells
         cell = @width.fdiv(@field.max_length)
-        baseline = (@height / 2.0) - (size * (Metrics::ASCENT + Metrics::DESCENT) / 2)
-        Metrics.encode(@field.value)[0, @field.max_length].chars.each_with_index.map do |char, index|
-          [(index * cell) + ((cell - Metrics.width(char, size)) / 2), baseline, char]
+        @field.value.to_s[0, @field.max_length].chars.each_with_index.map do |char, index|
+          [(index * cell) + ((cell - @type.width(char, size)) / 2), middle_baseline, char]
         end
       end
 
       def variable_text(runs)
         ops = ["/Tx BMC", "q", "1 1 #{num(@width - 2)} #{num(@height - 2)} re W n", "0 g"]
-        runs.reject { |_, _, bytes| bytes.empty? }.each do |x, y, bytes|
-          ops.push("BT", "/#{Field::FONT} #{num(size)} Tf", "#{num(x)} #{num(y)} Td",
-                   "#{PDF::Serializer.literal(bytes)} Tj", "ET")
+        runs.reject { |_, _, text| text.empty? }.each do |x, y, text|
+          ops.push("BT", "#{num(x)} #{num(y)} Td", *@type.show(text, size), "ET")
         end
         ops.push("Q", "EMC").join("\n") << "\n"
       end
@@ -93,11 +149,11 @@ module Stationery
       def signature
         y = @height - SIGNATURE[:rule]
         content = draw { |canvas| canvas.line(PADDING, y, @width - PADDING, y, color: options[:border], width: 0.75) }
-        label = Metrics.encode(options[:label])
+        label = options[:label].to_s
         return content if label.empty?
 
-        ops = ["q", "#{SIGNATURE[:label_gray]} g", "BT", "/#{Field::FONT} #{SIGNATURE[:label_size]} Tf",
-               "#{PADDING} #{SIGNATURE[:label_baseline]} Td", "#{PDF::Serializer.literal(label)} Tj", "ET", "Q"]
+        ops = ["q", "#{SIGNATURE[:label_gray]} g", "BT", "#{PADDING} #{SIGNATURE[:label_baseline]} Td",
+               *@type.show(label, SIGNATURE[:label_size]), "ET", "Q"]
         "#{content}#{ops.join("\n")}\n"
       end
 
@@ -107,12 +163,18 @@ module Stationery
         page.content
       end
 
+      # A check mark stroked as a path, so no symbol font is needed.
       def check
-        glyph = [@width, @height].min * 0.8
-        x = (@width - (glyph * CHECK[:width])) / 2
-        y = (@height / 2.0) - (glyph * CHECK[:middle])
-        ["q", "0 g", "BT", "/ZaDb #{num(glyph)} Tf", "#{num(x)} #{num(y)} Td", "(#{CHECK[:glyph]}) Tj", "ET", "Q"]
-          .join("\n") << "\n"
+        side = [@width, @height].min * 0.8
+        left = (@width - side) / 2.0
+        top = (@height - side) / 2.0
+        first, *rest = CHECK[:points].map { |x, y| [left + (x * side), top + (y * side)] }
+        draw do |canvas|
+          canvas.path(stroke: "#000000", line_width: side * CHECK[:stroke], cap: :round, join: :round) do |path|
+            path.move_to(*first)
+            rest.each { |point| path.line_to(*point) }
+          end
+        end
       end
     end
   end

data/lib/stationery/forms/field.rb

@@ -6,26 +6,29 @@ module Stationery
   module Forms
     # One form field widget: its kind, full (dotted) name, value and options.
     # Widgets sharing a name form one field (a radio group); dotted names are
-    # grouped under parent fields.
+    # grouped under parent fields. `typeface:` is what its appearance is set
+    # in: the document's fonts from the element DSL, the standard Helvetica
+    # otherwise. `tooltip:` is its accessible name (/TU), the name by default.
     class Field
       TYPES = { text: :Tx, checkbox: :Btn, radio: :Btn, select: :Ch, signature: :Sig }.freeze
       # Field flag bit positions (PDF 32000-1, 12.7.3.1 and 12.7.4).
       BITS = { read_only: 1, required: 2, multiline: 13, no_toggle_to_off: 15, radio: 16, combo: 18, edit: 19,
                comb: 25 }.freeze
       DEFAULTS = { font_size: 10, read_only: false, required: false, border: "#9CA3AF", background: "#FFFFFF",
-                   radius: 2 }.freeze
+                   radius: 2, tooltip: nil }.freeze
       OPTIONS = {
         text: %i[multiline max_length comb], checkbox: [], radio: %i[checked], select: %i[options editable],
         signature: %i[label]
       }.freeze
-      FONT = "Helv"
+      VARIABLE_TEXT = %i[text select].freeze
 
-      attr_reader :kind, :name, :value, :options
+      attr_reader :kind, :name, :value, :options, :typeface
 
-      def initialize(kind, name, value: nil, **options)
+      def initialize(kind, name, value: nil, typeface: Standard.new, **options)
         @kind = kind
         @name = validate_name(name.to_s)
         @value = value
+        @typeface = typeface
         unknown = options.keys - DEFAULTS.keys - OPTIONS.fetch(kind)
         raise ArgumentError, "unknown #{kind} field option: #{unknown.join(", ")}" if unknown.any?
 
@@ -36,7 +39,10 @@ module Stationery
       def segments = @name.split(".")
       def type = TYPES.fetch(@kind)
       def font_size = @options[:font_size]
-      def default_appearance = "/#{FONT} #{PDF::Serializer.number(font_size)} Tf 0 g"
+      # Whether a viewer redraws its text when the value changes.
+      def variable_text? = VARIABLE_TEXT.include?(@kind)
+      # The accessible name: `tooltip:`, a signature's label, else the name.
+      def tooltip = (@options[:tooltip] || @options[:label]).to_s.strip.then { |text| text.empty? ? @name : text }
       def max_length = @options[:comb].is_a?(Integer) ? @options[:comb] : @options[:max_length]
       def radio? = @kind == :radio
       def checked? = radio? ? @options[:checked] == true : @value == true
@@ -52,8 +58,10 @@ module Stationery
 
       # The field-level entries; the widget's come from #widget_entries.
       # `value` overrides this widget's own: a radio group's checked choice.
-      def field_entries(value = field_value)
-        entries = { FT: type, DA: default_appearance }
+      # `default_appearance` is the /DA of a field with variable text.
+      def field_entries(value = field_value, default_appearance: nil)
+        entries = { FT: type, TU: PDF::TextString.new(tooltip) }
+        entries[:DA] = default_appearance if default_appearance
         entries[:Ff] = flags if flags.positive?
         entries[:V] = value unless value.nil?
         entries[:MaxLen] = max_length if max_length
@@ -70,9 +78,10 @@ module Stationery
         end
       end
 
-      # `state` overrides the button's own appearance state.
-      def widget_entries(width, height, fonts, state: nil)
-        normal = Appearance.new(self, width, height, fonts).normal
+      # `appearance` is the widget's Appearance and `fonts` the references by
+      # resource name; `state` overrides the button's own appearance state.
+      def widget_entries(appearance, fonts, state: nil)
+        normal = appearance.streams(fonts)
         entries = { Type: :Annot, Subtype: :Widget, F: 4, AP: { N: normal } }
         entries[:MK] = appearance_characteristics unless @kind == :signature
         entries[:AS] = state || (checked? ? on_state : :Off) if normal.is_a?(Hash)

data/lib/stationery/forms/metrics.rb

@@ -3,8 +3,9 @@
 module Stationery
   module Forms
     # Helvetica's advance widths (the standard-14 AFM, in 1/1000 em) for the
-    # printable ASCII range, enough to lay out a field's appearance; other
-    # WinAnsi characters count as a digit's width.
+    # printable ASCII range, enough to lay out the appearance of a field made
+    # without a font book (see Standard); other WinAnsi characters count as a
+    # digit's width.
     module Metrics
       ASCII = [
         278, 278, 355, 556, 556, 889, 667, 191, 333, 333, 389, 584, 278, 333, 278, 278, # space - /
@@ -29,21 +30,6 @@ module Stationery
       def width(bytes, size)
         bytes.each_byte.sum { |byte| (byte in 32..126) ? ASCII[byte - 32] : DEFAULT } * size / 1000.0
       end
-
-      # `text` broken into WinAnsi lines no wider than `width`, keeping its own
-      # line breaks; a word wider than a line stands alone.
-      def wrap(text, width, size)
-        encode(text).split("\n", -1).flat_map do |paragraph|
-          paragraph.split.each_with_object([+""]) do |word, lines|
-            candidate = lines.last.empty? ? word : "#{lines.last} #{word}"
-            if lines.last.empty? || width(candidate, size) <= width
-              lines[-1] = candidate
-            else
-              lines << word
-            end
-          end
-        end
-      end
     end
   end
 end

data/lib/stationery/forms/typeface.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Forms
+    # What a field's appearance is set in. A field built by the element DSL
+    # draws with the document's own fonts (Typeface): embedded, subset and
+    # Identity-H encoded like any other text, with the book's fallbacks per
+    # character, so a value in any script the fonts cover renders. A field
+    # made without a font book (`Forms::Field.new` on a bare canvas) draws
+    # with the standard Helvetica in Windows-1252 (Standard).
+    #
+    # Both answer the same questions for an Appearance once bound to a
+    # render's resources with #with.
+    class Typeface
+      # What an editable field's font keeps beyond the value it shows, so the
+      # text a viewer redraws after an edit has its glyphs: printable ASCII
+      # and Latin-1. A read-only field keeps its value's glyphs only.
+      REPERTOIRE = [*0x20..0x7E, *0xA0..0xFF].pack("U*").freeze
+
+      def initialize(book, style, resources = nil)
+        @book = book
+        @style = style
+        @resources = resources
+        @names = {}
+      end
+
+      # This typeface naming its fonts in `resources` (a render's Resources).
+      def with(resources) = self.class.new(@book, @style, resources)
+
+      def embedded? = true
+      def ascent(size) = primary.ascender(size)
+      def descent(size) = primary.descender(size)
+      def width(text, size) = runs(text, size).sum { |font, run| font.width_of(run.text, size, ligatures: false) }
+
+      # The resource names of the fonts drawn or kept so far.
+      def names = @names.values
+
+      # The name the field's /DA selects: the font of the surrounding text.
+      def name = name_of(primary)
+
+      # The operators showing `text` at the current text position: a font
+      # selection and a string per run of one font. Characters no font has
+      # draw as .notdef and are reported, as in any other text.
+      def show(text, size)
+        runs(text, size).flat_map do |font, run|
+          report(font, run)
+          ["/#{name_of(font)} #{PDF::Serializer.number(size)} Tf", glyphs(font, run.text).to_operator]
+        end
+      end
+
+      # Keeps the glyphs of `text` in the embedded fonts without drawing it
+      # (a select's other options), and the REPERTOIRE when `repertoire:`.
+      def keep(text, size, repertoire: false)
+        runs(text, size).each do |font, run|
+          name_of(font)
+          glyphs(font, run.text)
+        end
+        return unless repertoire
+
+        name
+        glyphs(primary, REPERTOIRE.each_char.select { |char| primary.glyph?(char) }.join)
+      end
+
+      private
+
+      def primary = @primary ||= @book.resolve(@style).first
+      def name_of(font) = @names[font] ||= @resources.font(font)
+
+      # Marks the glyphs as used, so the subset embeds them.
+      def glyphs(font, text) = font.glyph_run(text, ligatures: false)
+
+      # [font, run] per stretch of `text` one font draws.
+      def runs(text, size)
+        return [] if text.empty?
+
+        @book.fallback([Text::Run.new(text, @style.with(size:))]).map { |run| [@book.resolve(run.style).first, run] }
+      end
+
+      def report(font, run)
+        run.text.each_char do |char|
+          next if Fonts::Fallback.carried?(char) || font.glyph?(char)
+
+          @book.warnings.missing_glyph(char, run.style.family)
+        end
+      end
+    end
+
+    # The standard Helvetica, not embedded: text is Windows-1252 bytes and
+    # characters outside it become "?".
+    class Standard
+      NAME = :Helv
+      FONT = { Type: :Font, Subtype: :Type1, BaseFont: :Helvetica, Encoding: :WinAnsiEncoding }.freeze
+
+      def with(_resources) = self.class.new
+      def embedded? = false
+      def ascent(size) = size * Metrics::ASCENT
+      def descent(size) = size * -Metrics::DESCENT
+      def width(text, size) = Metrics.width(Metrics.encode(text), size)
+      def names = @named ? [NAME] : []
+      # Nothing to keep: a standard font is the viewer's, whole.
+      def keep(*, **) = nil
+
+      def name
+        @named = true
+        NAME
+      end
+
+      def show(text, size)
+        ["/#{name} #{PDF::Serializer.number(size)} Tf", "#{PDF::Serializer.literal(Metrics.encode(text))} Tj"]
+      end
+    end
+  end
+end

data/lib/stationery/html/document.rb

@@ -1,14 +1,20 @@
 # frozen_string_literal: true
 
+require_relative "../rich/nesting"
 require_relative "tokenizer"
 require_relative "tree_builder"
 
 module Stationery
   # Lenient HTML to rich-text blocks (see Stationery::Rich).
   module HTML
-    def self.parse(source)
+    # Elements nested deeper than `max_depth` are flattened into the deepest
+    # one kept; the block is then given how deep the source went.
+    def self.parse(source, max_depth: Rich::Nesting::DEFAULT)
+      nesting = Rich::Nesting.new(max_depth)
       Stationery.instrument("parse.stationery", format: :html, bytes: source.bytesize) do
-        TreeBuilder.parse(Tokenizer.tokenize(source))
+        TreeBuilder.parse(Tokenizer.tokenize(source), nesting).tap do
+          yield nesting.deepest if nesting.exceeded? && block_given?
+        end
       end
     end
   end

data/lib/stationery/html/tree_builder.rb

@@ -6,7 +6,9 @@ module Stationery
   module HTML
     # Builds a lenient element tree from tokens, closing what HTML5 closes implicitly (a p before a block,
     # an li before the next li, cells and rows before the next), ignoring stray end tags, then converts
-    # the tree into rich-text blocks.
+    # the tree into rich-text blocks. An element nested deeper than the Rich::Nesting limit is left out
+    # of the tree: what it holds goes to the deepest element kept, so everything that walks the tree
+    # (and the layout it becomes) recurses no deeper than the limit.
     class TreeBuilder
       Element = Data.define(:name, :attributes, :children)
 
@@ -16,6 +18,7 @@ module Stationery
       ].freeze
       HEADINGS = %w[h1 h2 h3 h4 h5 h6].freeze
       SECTIONS = %w[thead tbody tfoot].freeze
+      BLOCKS = (CLOSES_P + SECTIONS + %w[tr td th caption]).freeze
       IMPLIED = {
         "li" => [%w[li], %w[ul ol]],
         "dt" => [%w[dt dd], %w[dl]], "dd" => [%w[dt dd], %w[dl]],
@@ -24,11 +27,13 @@ module Stationery
         "thead" => [SECTIONS, %w[table]], "tbody" => [SECTIONS, %w[table]], "tfoot" => [SECTIONS, %w[table]]
       }.freeze
 
-      def self.parse(tokens) = Blocks.convert(new.build(tokens))
+      def self.parse(tokens, nesting = Rich::Nesting.new) = Blocks.convert(new(nesting).build(tokens))
 
-      def initialize
+      def initialize(nesting = Rich::Nesting.new)
         @root = Element.new("#root", {}, [])
         @stack = [@root]
+        @nesting = nesting
+        @flattened = [] # the names of the open elements left out of the tree
       end
 
       def build(tokens)
@@ -45,9 +50,13 @@ module Stationery
       private
 
       def start(name, attributes, self_closing)
+        return flatten(name, attributes, self_closing) unless @flattened.empty?
+
         close_nearest(%w[p], %w[table td th caption]) if CLOSES_P.include?(name)
         close_nearest(HEADINGS, []) if HEADINGS.include?(name) && HEADINGS.include?(@stack.last.name)
         close_nearest(*IMPLIED[name]) if IMPLIED.key?(name)
+        return flatten(name, attributes, self_closing) if @stack.size > @nesting.limit
+
         push("tr", {}, false) if %w[td th].include?(name) && %w[table thead tbody tfoot].include?(@stack.last.name)
         push(name, attributes, self_closing)
       end
@@ -58,9 +67,30 @@ module Stationery
         @stack << element unless self_closing
       end
 
+      # Too deep for the tree: a void element (br, img, hr) still takes its place in the deepest
+      # element kept, anything else is only remembered until its end tag, its content going there too.
+      def flatten(name, attributes, self_closing)
+        return push(name, attributes, true) if self_closing
+
+        @flattened << name
+        @nesting.record(@stack.size - 1 + @flattened.size)
+        separate(name)
+      end
+
       def finish(name)
+        flattened = @flattened.rindex(name)
+        return @flattened.slice!(flattened..).each { |left_out| separate(left_out) } if flattened
+
         index = @stack.rindex { |element| element.name == name }
-        @stack.slice!(index..) if index&.positive?
+        return unless index&.positive?
+
+        @stack.slice!(index..)
+        @flattened.clear
+      end
+
+      # A flattened block no longer parts its text from its neighbours'; a space does.
+      def separate(name)
+        @stack.last.children << " " if BLOCKS.include?(name)
       end
 
       def close_nearest(names, boundary)

data/lib/stationery/images/jpeg.rb

@@ -21,9 +21,10 @@ module Stationery
       end
 
       def inspect = "#<#{self.class} #{@width}x#{@height}>"
+      def color_space = COLOR_SPACES.fetch(@components)
 
       def build(writer)
-        dictionary = Images.xobject(@width, @height, COLOR_SPACES.fetch(@components), @bits).merge(Filter: :DCTDecode)
+        dictionary = Images.xobject(@width, @height, color_space, @bits).merge(Filter: :DCTDecode)
         # Adobe CMYK JPEGs store inverted values.
         dictionary[:Decode] = [1, 0] * 4 if @components == 4 && @adobe
         writer.add(PDF::Stream.new(@data, dictionary))

data/lib/stationery/layout/image.rb

@@ -25,7 +25,7 @@ module Stationery
         super()
         @tag = alt == false ? nil : Tagging::Element.new(:Figure, alt:, kind: :image)
         @image = source.respond_to?(:build) ? source : Images.load(source)
-        @name = source.is_a?(String) || source.is_a?(Pathname) ? File.basename(source.to_s) : "inline image"
+        @name = name_of(source)
         @max_ppi = max_ppi
         @downscale = downscale
         @width = width
@@ -58,6 +58,14 @@ module Stationery
 
       private
 
+      # What a warning calls the image: the file's name for a path, a
+      # Pathname or an open File (anything with a path), else "inline image".
+      # Asked by duck type: Pathname is not loaded in plain Ruby.
+      def name_of(source)
+        path = source.is_a?(String) ? source : (source.to_path if source.respond_to?(:to_path))
+        path ? File.basename(path) : "inline image"
+      end
+
       def paint_clipped(canvas, x, y, w, h)
         return paint_image(canvas, x, y, w, h) unless @fit == :cover || @radius.positive?
 

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

@@ -6,6 +6,7 @@ module Stationery
       # One table cell: content (a String, markup String or layout node) and its
       # options, which selections change until the table is laid out.
       class Cell
+        SIDES = %i[top right bottom left].freeze
         TEXT_OPTIONS = { size: :size, color: :color, weight: :weight, style: :style, font: :family,
                          letter_spacing: :letter_spacing }.freeze
 
@@ -103,14 +104,23 @@ module Stationery
           canvas.debug_rect(inner.x, inner.y, inner.width, inner.height, :cell_padding)
         end
 
+        # One path for the cell's border, centred on its edges: the rectangle
+        # when all four sides are drawn, else a line per side.
         def paint_borders(canvas, rect)
           width = @options[:border_width]
           return if width.nil? || width.zero?
 
-          color = @options[:border_color]
-          Array(@options[:borders]).each do |side|
-            x1, y1, x2, y2 = edge(side, rect)
-            canvas.line(x1, y1, x2, y2, color:, width:)
+          sides = Array(@options[:borders]).uniq
+          return if sides.empty?
+
+          canvas.path(stroke: @options[:border_color], line_width: width) do |path|
+            next path.rect(rect.x, rect.y, rect.width, rect.height) if (SIDES - sides).empty?
+
+            sides.each do |side|
+              x1, y1, x2, y2 = edge(side, rect)
+              path.move_to(x1, y1)
+              path.line_to(x2, y2)
+            end
           end
         end