pdfrb 0.3.0 → 0.6.0

data/lib/pdfrb/layout/numeric_refinements.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Layout
+    # Refinements on Numeric to convert CSS-style units to PDF points.
+    #
+    # Usage:
+    #   using Pdfrb::Layout::NumericRefinements
+    #   2.cm   # => 56.6929...
+    #   1.inch # => 72.0
+    module NumericRefinements
+      PT_PER_INCH = 72.0
+      PT_PER_CM = PT_PER_INCH / 2.54
+      PT_PER_MM = PT_PER_CM / 10.0
+
+      refine Numeric do
+        def pt
+          to_f
+        end
+
+        def cm
+          to_f * PT_PER_CM
+        end
+
+        def mm
+          to_f * PT_PER_MM
+        end
+
+        def inch
+          to_f * PT_PER_INCH
+        end
+
+        alias inches inch
+
+        def pixel(dpi: 96.0)
+          to_f * (PT_PER_INCH / dpi)
+        end
+
+        alias px pixel
+      end
+    end
+  end
+end

data/lib/pdfrb/layout/page_style.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Layout
+    # A named page template. A PageStyle knows:
+    # - page dimensions (size + orientation)
+    # - margin
+    # - the next page style (chains)
+    # - a block that draws page chrome (header/footer) each time a
+    #   new page with this style is created.
+    class PageStyle
+      attr_reader :name, :page_size, :orientation, :margin, :next_style, :block
+
+      PAGE_SIZES = {
+        A4: [595.28, 841.89],
+        A3: [841.89, 1190.55],
+        A5: [419.53, 595.28],
+        Letter: [612.0, 792.0],
+        Legal: [612.0, 1008.0],
+        Tabloid: [792.0, 1224.0],
+      }.freeze
+
+      def initialize(name:, page_size: :A4, orientation: :portrait,
+                     margin: 36, next_style: nil, &block)
+        @name = name
+        @page_size = page_size
+        @orientation = orientation
+        @margin = margin
+        @next_style = next_style || name
+        @block = block
+      end
+
+      def dimensions
+        base = PAGE_SIZES[@page_size] || [612.0, 792.0]
+        if @orientation == :landscape
+          [base[1], base[0]]
+        else
+          base
+        end
+      end
+
+      def width
+        dimensions[0]
+      end
+
+      def height
+        dimensions[1]
+      end
+
+      def frame
+        m = @margin.is_a?(Array) ? @margin : [@margin] * 4
+        Frame.new(
+          left: m[3],
+          bottom: m[2],
+          width: width - m[1] - m[3],
+          height: height - m[0] - m[2]
+        )
+      end
+
+      def draw_chrome(canvas)
+        @block&.call(canvas)
+      end
+    end
+  end
+end

data/lib/pdfrb/layout/style.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Layout
+    # Immutable typographic + visual style. Updating a property
+    # returns a new Style; the original is unchanged.
+    #
+    # Built-in presets (:base, :title, :heading1, :heading2, :heading3,
+    # :code, :caption) can be loaded via +Style.new(:heading1)+ or
+    # merged via +Style.new(base: :heading1, **overrides)+.
+    class Style
+      PROPERTIES = %i[
+        font_name font_size font_options fill_color stroke_color
+        fill_alpha stroke_alpha line_width line_spacing character_spacing
+        word_spacing text_align vertical_align text_rendering_mode
+        text_rise font_features text_decoration text_underline_color
+        subscript superscript border padding margin border_color
+        border_style border_radius background background_alpha
+        overlap_overflow_alpha position text_transform word_break
+        hyphenate language first_line_indent text_indent
+      ].freeze
+
+      PRESETS = {
+        base: { font_name: "Helvetica", font_size: 10, line_spacing: 1.2,
+                fill_color: [0, 0, 0] },
+        title: { font_name: "Helvetica-Bold", font_size: 24,
+                 fill_color: [0, 0, 0] },
+        heading1: { font_name: "Helvetica-Bold", font_size: 20,
+                    fill_color: [0, 0, 0] },
+        heading2: { font_name: "Helvetica-Bold", font_size: 16 },
+        heading3: { font_name: "Helvetica-BoldOblique", font_size: 14 },
+        code: { font_name: "Courier", font_size: 10 },
+        caption: { font_name: "Helvetica-Oblique", font_size: 9,
+                   fill_color: [0.3, 0.3, 0.3] },
+      }.freeze
+
+      def initialize(name_or_base = nil, **opts)
+        base = if name_or_base.is_a?(Hash)
+                 name_or_base
+               elsif name_or_base.is_a?(Symbol)
+                 PRESETS[name_or_base] || {}
+               else
+                 {}
+               end
+        @values = base.merge(opts).freeze
+      end
+
+      def update(**opts)
+        self.class.new(@values.merge(opts))
+      end
+      alias dup_with update
+
+      def to_h
+        @values.dup
+      end
+
+      PROPERTIES.each do |prop|
+        define_method(prop) { @values[prop] }
+      end
+    end
+  end
+end

data/lib/pdfrb/layout/table_box.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Layout
+    # A table of cells. Each cell holds a Box. Column widths are auto
+    # unless specified; row heights computed from content.
+    class TableBox < Box
+      attr_reader :rows, :column_widths
+
+      def initialize(rows:, column_widths: nil, **)
+        super(**)
+        @rows = rows
+        @column_widths = column_widths
+      end
+
+      def fit?(available_width, available_height)
+        compute_column_widths(available_width)
+        remaining = available_height
+        @rows.each do |row|
+          row_heights = []
+          row.each_with_index do |cell, col|
+            cell_w = @column_widths[col]
+            cell.fit?(cell_w, remaining) or return false
+            row_heights << cell.height
+          end
+          row_h = row_heights.max || 0
+          remaining -= row_h
+        end
+        @width = available_width
+        @height = available_height - remaining
+        true
+      end
+
+      def draw_content(canvas, x, y)
+        offset_y = y
+        @rows.each do |row|
+          max_h = 0
+          offset_x = x
+          row.each_with_index do |cell, col|
+            cell.draw(canvas, offset_x, offset_y)
+            offset_x += @column_widths[col]
+            max_h = cell.height if cell.height > max_h
+          end
+          offset_y -= max_h
+        end
+      end
+
+      def empty?
+        @rows.empty?
+      end
+
+      private
+
+      def compute_column_widths(available_width)
+        return @column_widths = equal_widths(available_width) if @column_widths.nil?
+
+        @column_widths.map!(&:to_f)
+      end
+
+      def equal_widths(available_width)
+        col_count = @rows.first&.size || 1
+        Array.new(col_count, available_width / col_count)
+      end
+    end
+  end
+end

data/lib/pdfrb/layout/text_box.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Layout
+    # Renders a string of text with word-wrap into a region. Uses
+    # TextLayouter internally.
+    class TextBox < Box
+      attr_reader :text, :lines
+
+      def initialize(text:, **)
+        super(**)
+        @text = text.to_s
+        @lines = []
+      end
+
+      def fit?(available_width, available_height)
+        layouter = TextLayouter.new(@style)
+        @lines = layouter.layout(@text, available_width)
+        @width = available_width
+        @height = @lines.sum(&:height)
+        @height <= available_height
+      end
+
+      def draw_content(canvas, x, y)
+        offset_y = y - (@lines.first&.ascender || 0)
+        @lines.each do |line|
+          line.draw(canvas, x, offset_y, available_width: @width,
+                                        alignment: @style.text_align || :left)
+          offset_y -= line.height
+        end
+      end
+
+      def empty?
+        @text.empty?
+      end
+    end
+  end
+end

data/lib/pdfrb/layout/text_fragment.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Layout
+    # A single fragment of styled text — one run of consecutive glyphs
+    # with the same Style. Pieces are [[glyph_id, x_offset, width], ...]
+    # in font units.
+    class TextFragment
+      attr_reader :pieces, :style, :width, :height, :y_min, :y_max
+
+      def initialize(pieces:, style:, width:, height:, y_min:, y_max:)
+        @pieces = pieces
+        @style = style
+        @width = width
+        @height = height
+        @y_min = y_min
+        @y_max = y_max
+      end
+
+      def ascender
+        @y_max
+      end
+
+      def descender
+        -@y_min
+      end
+
+      def draw(canvas, x, y)
+        canvas.save_graphics_state do
+          if @style.fill_color
+            canvas.fill_color(@style.fill_color)
+          end
+          canvas.text(@pieces.map(&:first).pack("U*"), at: [x, y],
+                                                       font: font_name_for_canvas, size: @style.font_size)
+        end
+      end
+
+      private
+
+      def font_name_for_canvas
+        @style.font_name || :Helvetica
+      end
+    end
+  end
+end

data/lib/pdfrb/layout/text_layouter.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Layout
+    # Breaks a string into Layout::Line instances that fit a given
+    # width. Uses real per-glyph widths from the font's AFM or hmtx
+    # table when available, falling back to a heuristic estimate.
+    class TextLayouter
+      attr_reader :style
+
+      def initialize(style)
+        @style = style
+        @metrics = lookup_metrics
+      end
+
+      # @param text [String] the text to lay out.
+      # @param width [Float] target line width in PDF units.
+      # @return [Array<Line>] lines, each fitting in +width+.
+      def layout(text, width)
+        reordered = reorder_for_layout(text.to_s)
+        clusters = reordered.grapheme_clusters
+        return [] if clusters.empty?
+
+        lines = []
+        current = []
+        current_width = 0.0
+        clusters.each do |cluster|
+          cw = cluster_width(cluster)
+          if current_width + cw > width && !current.empty?
+            lines << build_line(current)
+            current = []
+            current_width = 0.0
+          end
+          current << cluster
+          current_width += cw
+        end
+        lines << build_line(current) unless current.empty?
+        lines
+      end
+
+      private
+
+      def reorder_for_layout(text)
+        return text unless Pdfrb::Layout::Bidi.rtl?(text)
+
+        Pdfrb::Layout::Bidi.reorder(text)
+      rescue StandardError
+        text
+      end
+
+      def lookup_metrics
+        font_name = @style.font_name
+        Pdfrb::Font::MetricsHelper.metrics_for_standard14(font_name)
+      rescue StandardError
+        nil
+      end
+
+      def cluster_width(cluster)
+        size = @style.font_size || 10
+        upem = @metrics&.units_per_em || 1000
+
+        if @metrics
+          total = 0.0
+          cluster.each_codepoint do |cp|
+            width_in_font_units = glyph_width_in_font_units(cp)
+            total += width_in_font_units
+          end
+          total * size / upem
+        else
+          # Heuristic fallback when no AFM available.
+          size * cluster.length * 0.5
+        end
+      end
+
+      def glyph_width_in_font_units(codepoint)
+        # Map Unicode codepoint → glyph name → AFM width.
+        glyph_name = unicode_to_glyph_name(codepoint)
+        return 500 unless glyph_name && @metrics
+
+        afm = afm_for(@style.font_name)
+        return 500 unless afm
+
+        width = afm.width_for(glyph_name)
+        width.positive? ? width : 500
+      end
+
+      def unicode_to_glyph_name(codepoint)
+        table = begin
+          Pdfrb::Font::Encoding::WinAnsiEncoding::TABLE
+        rescue StandardError
+          nil
+        end
+        return nil unless table
+
+        table[codepoint]
+      end
+
+      def afm_for(font_name)
+        @afm_cache ||= {}
+        return @afm_cache[font_name] if @afm_cache.key?(font_name)
+
+        @afm_cache[font_name] = Pdfrb::Font::MetricsHelper.afm_for(font_name.to_s)
+      end
+
+      def build_line(clusters)
+        pieces = clusters.map.with_index { |c, i| [c.ord, i, cluster_width(c)] }
+        size = @style.font_size || 10
+        ascender = @metrics ? @metrics.ascender(size) : size
+        descender = @metrics ? @metrics.descender(size) : -size * 0.2
+        Line.new(fragments: [
+                   TextFragment.new(
+                     pieces: pieces,
+                     style: @style,
+                     width: pieces.sum { |p| p[2] },
+                     height: ascender - descender,
+                     y_min: descender,
+                     y_max: ascender
+                   ),
+                 ])
+      end
+    end
+  end
+end

data/lib/pdfrb/layout.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  # Layout engine (mirrors HexaPDF::Layout). High-level document
+  # composition: Frame + Box + Composer. Boxes (text, image, table,
+  # list) are placed into Frames which represent page regions. Content
+  # flows across pages when a Frame fills up.
+  module Layout
+    autoload :Frame, "pdfrb/layout/frame"
+    autoload :Style, "pdfrb/layout/style"
+    autoload :NumericRefinements, "pdfrb/layout/numeric_refinements"
+    autoload :Box, "pdfrb/layout/box"
+    autoload :ContainerBox, "pdfrb/layout/container_box"
+    autoload :TextBox, "pdfrb/layout/text_box"
+    autoload :ImageBox, "pdfrb/layout/image_box"
+    autoload :ListBox, "pdfrb/layout/list_box"
+    autoload :TableBox, "pdfrb/layout/table_box"
+    autoload :ColumnBox, "pdfrb/layout/column_box"
+    autoload :InlineBox, "pdfrb/layout/inline_box"
+    autoload :BoxFitter, "pdfrb/layout/box_fitter"
+    autoload :PageStyle, "pdfrb/layout/page_style"
+    autoload :TextLayouter, "pdfrb/layout/text_layouter"
+    autoload :TextFragment, "pdfrb/layout/text_fragment"
+    autoload :Line, "pdfrb/layout/line"
+    autoload :Bidi, "pdfrb/layout/bidi"
+    autoload :RomanNumeral, "pdfrb/layout/list_box"
+  end
+end

data/lib/pdfrb/linearization/hint_stream.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "stringio"
+require "zlib"
+
+module Pdfrb
+  module Linearization
+    # Builds the page-offset hint stream (ISO 32000-2 Annex F).
+    # The hint stream tells the viewer where each page's objects are
+    # located without needing to parse the full xref.
+    #
+    # This implementation produces a minimal valid hint table:
+    #   /S 16 (16 bits per entry field)
+    #   One page-offset entry per page.
+    class HintStream
+      DEFAULT_ITEM_BITS = 16
+
+      attr_reader :page_entries, :item_bits
+
+      def initialize(item_bits: DEFAULT_ITEM_BITS)
+        @item_bits = item_bits
+        @page_entries = []
+      end
+
+      # Add a page entry.
+      # @param offset_delta [Integer] offset relative to /O reference.
+      # @param page_length [Integer] length in bytes.
+      # @param num_objects [Integer] number of objects on this page.
+      # @param page_obj_num [Integer] object number of the Page dict.
+      def add_page(offset_delta:, page_length:, num_objects:, page_obj_num:)
+        @page_entries << {
+          offset_delta: offset_delta,
+          page_length: page_length,
+          num_objects: num_objects,
+          page_obj_num: page_obj_num,
+        }
+      end
+
+      # Encode the hint stream as PDF bytes (binary, ready for /Length).
+      # @return [String] binary hint table data.
+      def encode
+        bits = []
+
+        @page_entries.each do |entry|
+          bits << [entry[:offset_delta], @item_bits]
+          bits << [entry[:page_length], @item_bits]
+          bits << [entry[:num_objects], @item_bits]
+          bits << [entry[:page_obj_num], @item_bits]
+        end
+
+        packed = pack_bits(bits)
+        packed.force_encoding(Encoding::BINARY)
+      end
+
+      # Dictionary fields for the hint stream object.
+      def dictionary_fields(length)
+        {
+          S: @item_bits,
+        }.tap do |h|
+          h[:Length] = length
+        end
+      end
+
+      private
+
+      def pack_bits(bit_fields)
+        bytes = +""
+        buffer = 0
+        bits_in_buffer = 0
+
+        bit_fields.each do |value, width|
+          width.times do |i|
+            bit = (value >> (width - 1 - i)) & 1
+            buffer = (buffer << 1) | bit
+            bits_in_buffer += 1
+            if bits_in_buffer == 8
+              bytes << [buffer].pack("C")
+              buffer = 0
+              bits_in_buffer = 0
+            end
+          end
+        end
+
+        if bits_in_buffer.positive?
+          buffer <<= (8 - bits_in_buffer)
+          bytes << [buffer].pack("C")
+        end
+
+        bytes
+      end
+    end
+  end
+end