pdfrb 0.2.1 → 0.6.0

data/lib/pdfrb/layout/bidi.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Layout
+    # Paragraph-level Unicode bidi reordering (UAX #9, simplified).
+    #
+    # Implements:
+    #   * P2-P3: paragraph embedding level from the first strong
+    #     character (L => 0, R/AL => 1).
+    #   * X9: skip BN/RLO/RLE/LRO/LRE/PDF/RLI/LRI/FSI (treated as
+    #     neutral for this paragraph-level pass).
+    #   * I1-I2: implicit level resolution for strong characters.
+    #   * L1-L4: whitespace resets, neutrals on level boundaries,
+    #     paired-bracket mirroring.
+    #   * L2: reverse character order on level runs from highest to
+    #     lowest, producing a visual order string.
+    #
+    # Scope: paragraph-level reordering only (no full isolating-run
+    # sequence handling). Sufficient for Hebrew/Arabic paragraphs and
+    # embedded LTR runs inside RTL paragraphs (and vice versa). Not
+    # sufficient for complex mixed-direction runs at character
+    # granularity inside a single visual line.
+    module Bidi
+      LEFT_TO_RIGHT = 0
+      RIGHT_TO_LEFT = 1
+
+      # Mirroring map for paired brackets (UAX #9 Bidi_Mirroring_Glyph
+      # property, subset covering common punctuation).
+      MIRROR = {
+        "(" => ")",
+        ")" => "(",
+        "[" => "]",
+        "]" => "[",
+        "{" => "}",
+        "}" => "{",
+        "<" => ">",
+        ">" => "<",
+        "‘" => "’",
+        "’" => "‘",
+        "“" => "”",
+        "”" => "“",
+        "«" => "»",
+        "»" => "«",
+        "‹" => "›",
+        "›" => "‹",
+      }.freeze
+
+      module_function
+
+      # Returns the resolved paragraph embedding level: 0 for LTR
+      # (or no strong direction), 1 for RTL.
+      def paragraph_level(text)
+        text.to_s.each_codepoint do |cp|
+          case strong_direction(cp)
+          when :ltr then return LEFT_TO_RIGHT
+          when :rtl then return RIGHT_TO_LEFT
+          end
+        end
+        LEFT_TO_RIGHT
+      end
+
+      # Reorder +text+ into visual order. Returns a new String of the
+      # same grapheme count.
+      def reorder(text)
+        clusters = text.to_s.grapheme_clusters.to_a
+        return text.to_s if clusters.size <= 1
+
+        base = paragraph_level(text)
+        levels = levels_for(clusters, base)
+        visual = reverse_by_levels(clusters, levels)
+        mirror_runs(visual, levels)
+      end
+
+      # Whether +text+ contains any RTL strong character.
+      def rtl?(text)
+        text.to_s.each_codepoint.any? { |cp| strong_direction(cp) == :rtl }
+      end
+
+      # ---- Character classification (UAX #9 BD1-BD2, trimmed) ----
+
+      # Strong direction (:ltr, :rtl, or nil for non-strong). Used by
+      # paragraph_level to find the first strong character per P2-P3.
+      def strong_direction(codepoint)
+        case bidi_type(codepoint)
+        when :L then :ltr
+        when :R, :AL then :rtl
+        end
+      end
+
+      # UAX #9 bidi type for a codepoint. Subset implementation:
+      # covers Latin, Hebrew, Arabic, digits, common punctuation.
+      def bidi_type(codepoint)
+        case codepoint
+        when 0x0660..0x0669, 0x06F0..0x06F9 then :AN
+        when 0x0300..0x036F, 0x0483..0x0489,
+             0x0591..0x05BD, 0x05BF, 0x05C1..0x05C2,
+             0x05C4..0x05C5, 0x05C7, 0x0610..0x061A,
+             0x064B..0x065F, 0x0670, 0x06D6..0x06DC,
+             0x06DF..0x06E4, 0x06E7..0x06E8,
+             0x06EA..0x06ED, 0x0711, 0x0730..0x074A then :NSM
+        when 0x0041..0x005A, 0x0061..0x007A,
+             0x00AA, 0x00B5, 0x00BA,
+             0x00C0..0x00D6, 0x00D8..0x00F6,
+             0x00F8..0x02B8, 0x02BB..0x02C1,
+             0x1D00..0x1D25, 0x1D2C..0x1D5C,
+             0x1D62..0x1D65, 0x1D6B..0x1D77,
+             0x1D79..0x1DBE, 0x1E00..0x1EFF,
+             0x2071, 0x207F, 0x2090..0x209C,
+             0x212A..0x212B, 0x2132, 0x214E,
+             0x2160..0x2188, 0x2C60..0x2C7F,
+             0xA722..0xA787, 0xA78B..0xA78E,
+             0xA790..0xA793, 0xA7A0..0xA7AA,
+             0xA7F8..0xA7FF, 0xFB00..0xFB06,
+             0xFB13..0xFB17 then :L
+        when 0x0590..0x05FF, 0x07C0..0x089F,
+             0xFB1D..0xFB4F then :R
+        when 0x0600..0x07BF, 0x08A0..0x08FF,
+             0xFB50..0xFDFF, 0xFE70..0xFEFF then :AL
+        when 0x0030..0x0039, 0x06DD then :EN
+        when 0x002B, 0x002D then :ES
+        when 0x0023, 0x0024, 0x0025, 0x00A2..0x00A5 then :ET
+        when 0x002C, 0x002E, 0x003A, 0x003B,
+             0x0028, 0x0029,
+             0x0000..0x0008, 0x000E..0x001B,
+             0x007F..0x0084, 0x0086..0x009F,
+             0x200B..0x200D, 0x2060, 0xFEFF then :ON
+        when 0x0020, 0x00A0, 0x1680, 0x2000..0x200A,
+             0x2028..0x2029, 0x202F, 0x205F, 0x3000 then :WS
+        else :BN
+        end
+      end
+
+      # ---- Level resolution ----
+
+      # Compute embedding level per grapheme cluster using the implicit
+      # level resolution rules I1/I2 from UAX #9. NSM inherits the
+      # level of the preceding character (simplified: assumes the
+      # paragraph base level for the first character).
+      def levels_for(clusters, base_level)
+        prev = base_level
+        clusters.map do |cluster|
+          cp = cluster.codepoints.first || 0
+          level = implicit_level(bidi_type(cp), base_level, prev)
+          prev = level
+          level
+        end
+      end
+
+      # I1/I2 from UAX #9. Even base levels add 1 for R/AL/AN, 2 for
+      # EN. Odd base levels add 1 for L/EN/AN.
+      def implicit_level(type, base_level, prev_level)
+        case type
+        when :NSM then prev_level
+        when :L then base_level.even? ? base_level : base_level + 1
+        when :R, :AL then base_level.even? ? base_level + 1 : base_level
+        when :AN then base_level + 1
+        when :EN then base_level + (base_level.even? ? 2 : 1)
+        else base_level
+        end
+      end
+
+      # UAX #9 L2: reverse contiguous runs at each level, from highest
+      # to lowest. Returns a new array of clusters in visual order.
+      def reverse_by_levels(clusters, levels)
+        result = clusters.dup
+        max_level = levels.max || 0
+        min_odd = levels.min.to_i
+        min_odd += 1 if min_odd.even?
+        (min_odd..max_level).to_a.reverse.each do |level|
+          start = nil
+          levels.each_with_index do |lvl, i|
+            if lvl >= level
+              start ||= i
+            elsif start
+              result[start, i - start] = result[start, i - start].reverse
+              start = nil
+            end
+          end
+          next unless start
+
+          result[start, levels.size - start] = result[start, levels.size - start].reverse
+        end
+        result
+      end
+
+      # UAX #9 L4: mirror paired brackets on RTL runs. Returns a
+      # string built from the visual-order cluster list with mirror
+      # glyphs substituted where applicable.
+      def mirror_runs(clusters, levels)
+        clusters.each_with_index.map do |cluster, i|
+          next cluster if levels[i].nil? || levels[i].even?
+
+          MIRROR[cluster] || cluster
+        end.join
+      end
+    end
+  end
+end

data/lib/pdfrb/layout/box.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Layout
+    # Base class for all layout boxes. A Box has a width, height, and
+    # content; it knows how to fit itself into a Frame region and how
+    # to draw onto a Canvas at a given (x, y) location.
+    #
+    # Subclasses override +fit+ (compute height for given width) and
+    # +draw_content+ (render to canvas).
+    class Box
+      attr_reader :style, :width, :height
+
+      def initialize(width: 0, height: 0, style: Style.new(:base), **)
+        @width = width.to_f
+        @height = height.to_f
+        @style = style
+      end
+
+      # Fit this box into the given available (width, height) region.
+      # Returns true if it fits (sets @height); false otherwise.
+      # Subclasses override.
+      def fit?(_available_width, _available_height)
+        true
+      end
+
+      # Draw this box at (x, y) on +canvas+. Subclasses override
+      # +draw_content+.
+      def draw(canvas, x, y)
+        draw_background(canvas, x, y)
+        draw_content(canvas, x, y)
+      end
+
+      def supports_position_flow?
+        false
+      end
+
+      def empty?
+        false
+      end
+
+      protected
+
+      def draw_background(canvas, x, y); end
+
+      def draw_content(canvas, x, y); end
+    end
+  end
+end

data/lib/pdfrb/layout/box_fitter.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Layout
+    # Fits an ordered list of boxes into a Frame, flowing to a new
+    # Frame (provided by a block) when one fills up.
+    class BoxFitter
+      attr_reader :boxes, :frame, :result, :overflow
+
+      def initialize(boxes:, frame:)
+        @boxes = boxes
+        @frame = frame
+        @result = []
+        @overflow = []
+      end
+
+      def fit
+        current_frame = @frame
+        cursor_y = current_frame.top
+        @boxes.each do |box|
+          loop do
+            position = current_frame.find_available_area(box.width || current_frame.width, box.height || (cursor_y - current_frame.bottom))
+            if position && box.fit?(position[2] || current_frame.width, position[3] || (cursor_y - current_frame.bottom))
+              @result << [box, position]
+              current_frame.remove_area(position[0], position[1] - box.height, box.width, box.height)
+              cursor_y = position[1] - box.height
+              break
+            else
+              next_frame = yield if block_given?
+              if next_frame
+                current_frame = next_frame
+                cursor_y = current_frame.top
+              else
+                @overflow << box
+                break
+              end
+            end
+          end
+        end
+        self
+      end
+
+      def draw(canvas)
+        @result.each do |box, pos|
+          box.draw(canvas, pos[0], pos[1])
+        end
+      end
+
+      def fit_complete?
+        @overflow.empty?
+      end
+    end
+  end
+end

data/lib/pdfrb/layout/column_box.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Layout
+    # Lays out children into N columns of equal width separated by
+    # gutters. Children flow top-to-bottom in column 1, then wrap to
+    # column 2 when column 1 fills, etc.
+    class ColumnBox < Box
+      attr_reader :children, :columns, :gutter
+
+      def initialize(children:, columns: 2, gutter: 20, **)
+        super(**)
+        @children = children
+        @columns = columns.to_i
+        @gutter = gutter.to_f
+      end
+
+      def fit?(available_width, available_height)
+        column_w = (available_width - (@gutter * (@columns - 1))) / @columns
+        @child_heights = []
+        remaining_children = @children.dup
+        col_heights = Array.new(@columns, 0.0)
+
+        @columns.times do |col_idx|
+          col_remaining = available_height
+          while remaining_children.any?
+            child = remaining_children.first
+            if child.fit?(column_w, col_remaining)
+              col_heights[col_idx] += child.height
+              col_remaining -= child.height
+              remaining_children.shift
+            else
+              break
+            end
+          end
+        end
+        @column_width = column_w
+        @column_heights = col_heights
+        @width = available_width
+        @height = available_height
+        remaining_children.empty?
+      end
+
+      def draw_content(canvas, x, y)
+        idx = 0
+        @column_heights.each_with_index do |_h, col_idx|
+          col_x = x + (col_idx * (@column_width + @gutter))
+          col_y = y
+          while idx < @children.size
+            child = @children[idx]
+            break if child_height_in_column(idx, col_idx).nil?
+
+            child.draw(canvas, col_x, col_y)
+            col_y -= child.height
+            idx += 1
+          end
+        end
+      end
+
+      def empty?
+        @children.empty?
+      end
+
+      private
+
+      def child_height_in_column(child_idx, col_idx)
+        @column_heights[col_idx] if child_idx < @column_heights.size
+      end
+    end
+  end
+end

data/lib/pdfrb/layout/container_box.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Layout
+    # A box that holds an ordered list of child boxes laid out
+    # vertically. Each child is fit in turn; if a child doesn't fit
+    # in the remaining height, +fit+ returns false and the fitter
+    # moves to a new Frame.
+    class ContainerBox < Box
+      attr_reader :children
+
+      def initialize(children: [], **)
+        super(**)
+        @children = children
+      end
+
+      def fit?(available_width, available_height)
+        remaining_height = available_height
+        @children.each do |child|
+          if child.fit?(available_width, remaining_height)
+            remaining_height -= child.height
+          else
+            return false
+          end
+        end
+        @width = available_width
+        @height = available_height - remaining_height
+        true
+      end
+
+      def draw(canvas, x, y)
+        super
+        offset_y = y
+        @children.each do |child|
+          child.draw(canvas, x, offset_y)
+          offset_y -= child.height
+        end
+      end
+
+      def empty?
+        @children.empty?
+      end
+    end
+  end
+end

data/lib/pdfrb/layout/frame.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Layout
+    # A rectangular region of a page where boxes are placed. The Frame
+    # tracks which areas are filled and exposes +find_available_area+
+    # to locate the next free region of a given width and height.
+    #
+    # Simple case: the Frame is a plain rectangle. Advanced: the
+    # +shape+ polygon allows non-rectangular regions (L-shaped, with
+    # cutouts around images).
+    class Frame
+      attr_reader :left, :bottom, :width, :height, :shape
+
+      def initialize(left:, bottom:, width:, height:, shape: nil)
+        @left = left.to_f
+        @bottom = bottom.to_f
+        @width = width.to_f
+        @height = height.to_f
+        @shape = shape || default_shape
+      end
+
+      def right
+        @left + @width
+      end
+
+      def top
+        @bottom + @height
+      end
+
+      # Locate the next free area of (width × height) within this Frame.
+      # Returns nil if none fits. After a successful find, callers
+      # typically call +remove_area+ with the returned rectangle to
+      # mark it as used.
+      def find_available_area(width, height)
+        w = width.to_f
+        h = height.to_f
+        return nil if w > @width || h > @height
+
+        [@left, @bottom + @height - h]
+      end
+
+      # Mark the rectangle at (x, y) of (w × h) as filled. Subsequent
+      # +find_available_area+ calls avoid this region.
+      def remove_area(x, y, w, h)
+        return if x.nil? || y.nil?
+
+        @removed ||= []
+        @removed << [x.to_f, y.to_f, w.to_f, h.to_f]
+      end
+
+      def full?
+        @removed&.any?
+      end
+
+      def empty?
+        !full?
+      end
+
+      private
+
+      def default_shape
+        [[@left, @bottom], [right, @bottom], [right, top], [@left, top]]
+      end
+    end
+  end
+end

data/lib/pdfrb/layout/image_box.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Layout
+    # Renders an image (PNG or JPEG) into the layout flow. The image
+    # is loaded via Pdfrb::ImageLoader and registered with the
+    # document's Resources on first draw.
+    class ImageBox < Box
+      attr_reader :path, :image_data
+
+      def initialize(path:, document:, width: 0, height: 0, **)
+        super(width: width, height: height, **)
+        @path = path
+        @document = document
+        @image_data = File.binread(path)
+      end
+
+      def fit?(available_width, available_height)
+        loader = Pdfrb::ImageLoader.load(@document, @image_data)
+        native_w = loader[:Width].to_f
+        native_h = loader[:Height].to_f
+        target_w = @width.positive? ? @width : native_w
+        target_h = @height.positive? ? @height : native_h
+
+        if @width.zero? && @height.zero?
+          scale = [available_width / native_w, available_height / native_h].min
+          scale = 1.0 if scale > 1
+          target_w = native_w * scale
+          target_h = native_h * scale
+        end
+
+        @width = target_w
+        @height = target_h
+        @loaded = loader
+        @width <= available_width && @height <= available_height
+      end
+
+      def draw_content(canvas, x, y)
+        name = canvas.document.images.add(@path)
+        canvas.draw_image(name, at: [x, y], width: @width, height: @height)
+      end
+    end
+  end
+end

data/lib/pdfrb/layout/inline_box.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Layout
+    # A box that sits inline within a text line (e.g., a styled span
+    # or an inline icon). Width + height are fixed; Line arranges it
+    # alongside TextFragments.
+    class InlineBox < Box
+      attr_reader :block
+
+      def initialize(width:, height:, &block)
+        super(width: width, height: height)
+        @block = block
+      end
+
+      def supports_position_flow?
+        true
+      end
+
+      def draw_content(canvas, x, y)
+        @block&.call(canvas, x, y)
+      end
+    end
+  end
+end

data/lib/pdfrb/layout/line.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Layout
+    # A single line of text — an ordered list of TextFragment instances
+    # sharing a baseline. Knows its total width/height/ascent/descent.
+    class Line
+      attr_reader :fragments
+
+      def initialize(fragments: [])
+        @fragments = fragments
+      end
+
+      def width
+        @fragments.sum(&:width)
+      end
+
+      def height
+        return 0 if @fragments.empty?
+
+        max_top = @fragments.map(&:y_max).max
+        min_bottom = @fragments.map(&:y_min).min
+        max_top - min_bottom
+      end
+
+      def ascender
+        @fragments.map(&:y_max).max || 0
+      end
+
+      def descender
+        @fragments.map(&:y_min).min || 0
+      end
+
+      def empty?
+        @fragments.empty?
+      end
+
+      # Draw the line at baseline (x, y) applying the requested alignment
+      # within the available width.
+      def draw(canvas, x, y, available_width:, alignment: :left)
+        offset = if alignment == :center
+                   x + ((available_width - width) / 2)
+                 elsif alignment == :right
+                   x + available_width - width
+                 else
+                   x
+                 end
+        @fragments.each do |frag|
+          frag.draw(canvas, offset, y)
+          offset += frag.width
+        end
+      end
+    end
+  end
+end

data/lib/pdfrb/layout/list_box.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Layout
+    # Roman numeral converter. Extracted as a standalone helper so
+    # +ListBox+ and +PageLabel+ (model layer) can share it.
+    class RomanNumeral
+      MAPPINGS = [[1000, "M"], [900, "CM"], [500, "D"], [400, "CD"],
+                  [100, "C"], [90, "XC"], [50, "L"], [40, "XL"],
+                  [10, "X"], [9, "IX"], [5, "V"], [4, "IV"], [1, "I"]].freeze
+
+      def self.convert(n)
+        return "0" if n <= 0
+
+        result = +""
+        MAPPINGS.each do |value, symbol|
+          while n >= value
+            result << symbol
+            n -= value
+          end
+        end
+        result
+      end
+    end
+
+    # A list of items, each rendered with a marker (bullet, decimal,
+    # alpha, roman, etc.). Children are boxes (typically TextBox).
+    class ListBox < Box
+      attr_reader :items, :marker_type
+
+      MARKERS = {
+        bullet: "•",
+        disc: "•",
+        circle: "○",
+        square: "▪",
+        decimal: ->(i) { "#{i + 1}." },
+        lower_alpha: ->(i) { "#{('a'.ord + i).chr}." },
+        upper_alpha: ->(i) { "#{('A'.ord + i).chr}." },
+        lower_roman: ->(i) { "#{RomanNumeral.convert(i + 1).downcase}." },
+        upper_roman: ->(i) { "#{RomanNumeral.convert(i + 1)}." },
+      }.freeze
+
+      def initialize(items:, marker_type: :bullet, **)
+        super(**)
+        @items = items
+        @marker_type = marker_type
+      end
+
+      def fit?(available_width, available_height)
+        marker_w = 20.0
+        content_w = available_width - marker_w
+        remaining = available_height
+        @items.each do |item|
+          return false unless item.fit?(content_w, remaining)
+
+          remaining -= item.height
+        end
+        @width = available_width
+        @height = available_height - remaining
+        true
+      end
+
+      def draw_content(canvas, x, y)
+        marker_w = 20.0
+        offset_y = y
+        @items.each_with_index do |item, i|
+          marker_text(canvas, x, offset_y, i)
+          item.draw(canvas, x + marker_w, offset_y)
+          offset_y -= item.height
+        end
+      end
+
+      def empty?
+        @items.empty?
+      end
+
+      private
+
+      def marker_text(canvas, x, y, index)
+        marker = MARKERS[@marker_type] || MARKERS[:bullet]
+        text = marker.is_a?(Proc) ? marker.call(index) : marker
+        canvas.text(text, at: [x, y], font: :Helvetica,
+                          size: @style.font_size || 10)
+      end
+    end
+  end
+end