arrolio 0.1.0

data/lib/arrolio/flavor/registry.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Arrolio
+  module Flavor
+    # Flavor registry. Flavors register their pipeline class at
+    # load time; applications look up flavors by name. This enables
+    # multiple flavors to coexist without
+    # the core engine knowing about any of them.
+    #
+    # A flavor's pipeline class must respond to:
+    #   .render(xml, io:, **opts) — render XML to PDF bytes
+    #
+    # Example:
+    #   Arrolio::Flavor::Registry.register(:my_flavor, Arrolio::Oiml::Pipeline)
+    #   Arrolio::Flavor::Registry.for(:my_flavor).render(xml, io: io)
+    class Registry
+      @flavors = {}
+
+      class << self
+        attr_reader :flavors
+
+        # Register a flavor by name. +pipeline_class+ must respond
+        # to +.render(xml, io:, **opts)+.
+        def register(name, pipeline_class)
+          @flavors[name.to_sym] = pipeline_class
+        end
+
+        # Look up a registered flavor. Returns the pipeline class
+        # or raises if not found.
+        def for(name)
+          key = name.to_sym
+          @flavors[key] ||
+            raise(ArgumentError,
+                  "Unknown flavor #{name.inspect}; registered: #{@flavors.keys.inspect}")
+        end
+
+        # All registered flavor names.
+        def names
+          @flavors.keys
+        end
+
+        # Is a flavor registered?
+        def registered?(name)
+          @flavors.key?(name.to_sym)
+        end
+
+        # Clear all registrations — used in specs.
+        def reset!
+          @flavors.clear
+        end
+      end
+    end
+  end
+end

data/lib/arrolio/flavor.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Arrolio
+  # Flavor system — allows external document flavors to plug into
+  # Arrolio without modifying core. Each flavor lives in its own
+  # directory (XSL + 3 generated YAML files) outside the gem and is
+  # rendered via Arrolio::ConfigDrivenPipeline.
+  #
+  # Arrolio core is flavor-agnostic: it knows about Content::Document,
+  # Flowable, Engine, and Renderer — but NOT about any specific XML
+  # format, XSL stylesheet, or document structure.
+  #
+  # Usage:
+  #   # In the flavor's gem:
+  #   Arrolio::Flavor::Registry.register(:my_flavor, MyFlavorPipeline)
+  #
+  #   # In the application:
+  #   Arrolio::Flavor::Registry.for(:my_flavor).render(xml, io: f)
+  module Flavor
+    autoload :Registry, 'arrolio/flavor/registry'
+    autoload :Manifest, 'arrolio/flavor/manifest'
+  end
+end

data/lib/arrolio/flow_context.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Arrolio
+  # State threaded through every flowable fit/emit call. Holds
+  # page-level state flowables need: current page number, total
+  # page count (filled in between pass 1 and pass 2), the running
+  # citation table, and the LayoutSpec for style resolution.
+  class FlowContext
+    attr_accessor :page_number, :page_count, :renderer
+    attr_reader :layout_spec, :citations, :heading_entries
+
+    def initialize(layout_spec:, page_number: 1, page_count: nil)
+      @layout_spec = layout_spec
+      @page_number = page_number
+      @page_count = page_count
+      @citations = {}
+      @heading_entries = []
+    end
+
+    def citation_for(ref_id)
+      @citations[ref_id.to_s]
+    end
+
+    def record_citation(ref_id, page_number)
+      @citations[ref_id.to_s] ||= page_number
+    end
+
+    def record_heading(number:, title:, level:, page_number:, id: nil)
+      @heading_entries << { number: number, title: title, level: level,
+                            page_number: page_number, id: id }
+    end
+
+    def total_pages
+      @page_count
+    end
+  end
+end

data/lib/arrolio/flowable.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+# Arrolio::Flowable — abstract base for everything the page-flow
+# engine places into Frames.
+module Arrolio
+  class Flowable
+    attr_reader :style
+
+    def initialize(style: Style::Definition.new)
+      @style = style
+    end
+
+    def height(_width, _context = nil)
+      raise NotImplementedError, "#{self.class}#height not implemented"
+    end
+
+    def emit(_x, _y, _width, _context = nil)
+      raise NotImplementedError, "#{self.class}#emit not implemented"
+    end
+
+    def splittable?
+      false
+    end
+
+    def keep_together?
+      @style.keep_together
+    end
+
+    def keep_with_next?
+      @style.keep_with_next
+    end
+
+    def page_break_before?
+      @style.page_break_before
+    end
+
+    def page_break_after?
+      @style.page_break_after
+    end
+
+    def space_before
+      @style.margin_top
+    end
+
+    def space_after
+      @style.margin_bottom
+    end
+
+    def split(width, remaining_height, context = nil)
+      natural = height(width, context)
+      if natural <= remaining_height
+        [self, nil]
+      elsif splittable?
+        do_split(width, remaining_height, context)
+      elsif keep_together?
+        [nil, self]
+      else
+        [self, nil]
+      end
+    end
+
+    def do_split(_width, _remaining_height, _context = nil)
+      [self, nil]
+    end
+  end
+end

data/lib/arrolio/flowables/footnote_marker_flowable.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Arrolio
+  module Flowables
+    # Zero-height placeholder that signals "the footnote with this id
+    # appears on the current page". The engine detects these during
+    # layout and records the footnote on the current Output::Page so
+    # the renderer can draw it at the bottom of the page.
+    #
+    # Carries a reference to the full Content::Footnote (marker +
+    # body). The marker is also rendered inline (as a superscript
+    # indicator) by the flow builder when it constructs the run
+    # sequence; this flowable's sole job is to anchor the footnote
+    # to a page.
+    class FootnoteMarkerFlowable < Flowable
+      attr_reader :footnote
+
+      def initialize(footnote)
+        super(style: Style::Definition.new)
+        @footnote = footnote
+      end
+
+      def height(_width, _context = nil) = 0.0
+
+      def emit(_x, _y, _width, _context = nil) = [[], 0.0]
+    end
+  end
+end

data/lib/arrolio/flowables/heading_flowable.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Arrolio
+  module Flowables
+    # A section heading: optional number + title text. Lives
+    # separate from TextFlowable so the adapter and Engine can
+    # recognise headings by type (for outline / TOC building).
+    class HeadingFlowable < TextFlowable
+      attr_reader :level, :number, :title, :id
+
+      def initialize(title, level: 1, number: nil, id: nil,
+                     style: Style::Definition.new, measurer: nil)
+        full_text = number ? "#{number} #{title}" : title.to_s
+        super([InlineRun.new(full_text, style: style)],
+              style: style, measurer: measurer)
+        @title = title
+        @level = level.to_i
+        @number = number
+        @id = id
+      end
+    end
+  end
+end

data/lib/arrolio/flowables/image_flowable.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Arrolio
+  module Flowables
+    # Renders a PNG / JPEG / SVG via Pdfrb's image registry. Scales
+    # to +display_width+ while preserving aspect ratio; if
+    # +display_width+ is nil, scales to fit the available width.
+    #
+    # Image registration is deferred to the render pass: the PlacedBox
+    # carries the source path, and the renderer resolves it (including
+    # SVG-to-PNG rasterization if needed) when it walks the page tree.
+    class ImageFlowable < Flowable
+      attr_reader :src, :natural_width, :natural_height, :display_width, :alt
+
+      def initialize(src, natural_width:, natural_height:,
+                     display_width: nil, alt: nil,
+                     style: Style::Definition.new)
+        super(style: style)
+        @src = src.to_s
+        @natural_width = natural_width.to_f
+        @natural_height = natural_height.to_f
+        @display_width = display_width
+        @alt = alt
+      end
+
+      def height(width, _context = nil)
+        return 0.0 if @natural_width.zero?
+
+        actual_w = actual_width(width)
+        actual_w * (@natural_height / @natural_width)
+      end
+
+      def emit(x, y, width, _context = nil)
+        return [[], 0.0] if @natural_width.zero?
+
+        actual_w = actual_width(width)
+        actual_h = actual_w * (@natural_height / @natural_width)
+        box = Output::PlacedBox.image(
+          x: x, y: y - actual_h,
+          width: actual_w, height: actual_h,
+          image_ref: @src
+        )
+        [[box], actual_h]
+      end
+
+      private
+
+      def actual_width(width)
+        @display_width && @display_width < width ? @display_width : width
+      end
+    end
+  end
+end

data/lib/arrolio/flowables/list_flowable.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Arrolio
+  module Flowables
+    # Hanging-indent list. Each item has a marker column (fixed
+    # width) and a body column (wraps under body, not marker).
+    class ListFlowable < Flowable
+      attr_reader :items, :kind, :marker_width, :body_indent
+
+      def initialize(items, kind: :bullet, style: Style::Definition.new,
+                     marker_width: 18.0, body_indent: 6.0)
+        super(style: style)
+        @kind = kind.to_sym
+        @marker_width = marker_width.to_f
+        @body_indent = body_indent.to_f
+        @items = items
+        freeze
+      end
+
+      def height(width, context = nil)
+        @items.sum do |item|
+          _, body_flowables = item
+          body_width = width - @marker_width - @body_indent
+          body_flowables.sum { |f| f.height(body_width, context) }
+        end
+      end
+
+      def emit(x, y, width, context = nil)
+        boxes = []
+        consumed = 0.0
+        cursor = y
+        body_x = x + @marker_width + @body_indent
+        body_width = width - @marker_width - @body_indent
+
+        @items.each_with_index do |item, idx|
+          marker_text, body_flowables = item
+          marker = marker_text || default_marker(idx)
+
+          if marker.is_a?(String)
+            if marker.empty?
+              # no marker to draw
+            else
+              mboxes, = marker_flowable(marker, x, cursor, width, context).emit(x, cursor, width, context)
+              boxes.concat(mboxes)
+            end
+          elsif marker
+            # marker is a Flowable (e.g. NoteFlowable passes a TextFlowable)
+            mboxes, = marker.emit(x, cursor, width, context)
+            boxes.concat(mboxes)
+          end
+
+          body_flowables.each do |f|
+            fh = f.height(body_width, context)
+            fboxes, = f.emit(body_x, cursor, body_width, context)
+            boxes.concat(fboxes)
+            cursor -= fh
+            consumed += fh
+          end
+        end
+
+        [boxes, consumed]
+      end
+
+      def splittable?
+        true
+      end
+
+      def do_split(width, remaining_height, context = nil)
+        head_items = []
+        tail_items = []
+        used = 0.0
+
+        @items.each do |item|
+          _, body_flowables = item
+          item_h = body_flowables.sum { |f| f.height(width - @marker_width - @body_indent, context) }
+          if used + item_h <= remaining_height || head_items.empty?
+            head_items << item
+            used += item_h
+          else
+            tail_items << item
+          end
+        end
+
+        head = if head_items.empty?
+  nil
+else
+  self.class.new(head_items, kind: @kind, style: @style,
+                             marker_width: @marker_width,
+                             body_indent: @body_indent)
+end
+        tail = if tail_items.empty?
+  nil
+else
+  self.class.new(tail_items, kind: @kind, style: @style,
+                             marker_width: @marker_width,
+                             body_indent: @body_indent)
+end
+        [head, tail]
+      end
+
+      private
+
+      def default_marker(idx)
+        case @kind
+        when :ordered then "#{idx + 1}."
+        when :bullet then "\u25A0"
+        else "\u2022"
+        end
+      end
+
+      def marker_flowable(text, _x, _y, _w, _ctx)
+        marker_style = @style.with(font_size: @style.font_size * 0.6)
+        TextFlowable.new([InlineRun.new(text, style: marker_style)], style: marker_style)
+      end
+    end
+  end
+end

data/lib/arrolio/flowables/note_flowable.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Arrolio
+  module Flowables
+    # Note / example callout: italic label in marker column, body
+    # indented. Reuses ListFlowable's hanging-indent infrastructure.
+    class NoteFlowable < ListFlowable
+      def initialize(label_text, body_flowables, style: Style::Definition.new,
+                     marker_width: 22.0, body_indent: 6.0)
+        label_style = style.with(font_size: style.font_size)
+        marker_run = InlineRun.new("#{label_text} ", style: label_style)
+        marker_flow = TextFlowable.new([marker_run], style: label_style)
+        super([[marker_flow, body_flowables]],
+              kind: :note, style: style,
+              marker_width: marker_width, body_indent: body_indent)
+      end
+    end
+  end
+end

data/lib/arrolio/flowables/page_break.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Arrolio
+  module Flowables
+    class PageBreak < Flowable
+      def height(_width, _context = nil) = 0.0
+
+      def emit(_x, _y, _width, _context = nil) = [[], 0.0]
+
+      def page_break_after?
+        true
+      end
+    end
+  end
+end

data/lib/arrolio/flowables/page_sequence_start.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Arrolio
+  module Flowables
+    # Forces a page break AND switches the active page sequence:
+    # role + header/footer templates apply to subsequent pages
+    # until the next PageSequenceStart.
+    class PageSequenceStart < Flowable
+      attr_reader :role, :header_template, :footer_template,
+                  :header_align, :footer_align, :initial_page_number
+
+      def initialize(role:, header_template: nil, footer_template: nil,
+                     header_align: :right, footer_align: :center,
+                     initial_page_number: nil)
+        @role = role.to_sym
+        @header_template = header_template
+        @footer_template = footer_template
+        @header_align = header_align.to_sym
+        @footer_align = footer_align.to_sym
+        @initial_page_number = initial_page_number
+      end
+
+      def height(_width, _context = nil) = 0.0
+
+      def emit(_x, _y, _width, _context = nil) = [[], 0.0]
+    end
+  end
+end

data/lib/arrolio/flowables/spacer.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Arrolio
+  module Flowables
+    class Spacer < Flowable
+      attr_reader :amount
+
+      def initialize(amount, style: Style::Definition.new)
+        super(style: style)
+        @amount = amount.to_f
+      end
+
+      def height(_width, _context = nil)
+        @amount
+      end
+
+      def emit(_x, _y, _width, _context = nil)
+        [[], @amount]
+      end
+
+      def splittable?
+        true
+      end
+
+      def do_split(_width, remaining_height, _context = nil)
+        if @amount <= remaining_height
+          [self, nil]
+        else
+          [self.class.new(remaining_height), self.class.new(@amount - remaining_height)]
+        end
+      end
+    end
+  end
+end

data/lib/arrolio/flowables/table_flowable.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module Arrolio
+  module Flowables
+    # Real table layout: equal-width columns by default (TODO 04
+    # adds auto/fixed), borders per cell, header row repeat.
+    class TableFlowable < Flowable
+      attr_reader :table, :column_widths
+
+      def initialize(table, style: Style::Definition.new)
+        super(style: style)
+        @table = table
+      end
+
+      def height(width, _context = nil)
+        cols = column_widths_for(width)
+        total = 0.0
+        rows.each do |row|
+          total += row_height(row, cols)
+        end
+        total
+      end
+
+      def emit(x, y, width, context = nil)
+        cols = column_widths_for(width)
+        boxes = []
+        consumed = 0.0
+        cursor = y
+        header_rows, body_rows = partition_rows
+
+        (header_rows + body_rows).each do |row|
+          rh = row_height(row, cols)
+          cursor -= rh
+          consumed += rh
+          cell_x = x.to_f
+          row.cells.each_with_index do |cell, ci|
+            cw = cols[ci] || (width / [row.cells.length, 1].max)
+            render_cell(cell, cell_x, cursor, cw, rh, boxes, context)
+            cell_x += cw
+          end
+        end
+
+        [boxes, consumed]
+      end
+
+      def splittable?
+        true
+      end
+
+      def do_split(width, remaining_height, _context = nil)
+        cols = column_widths_for(width)
+        head_rows = []
+        tail_rows = []
+        used = 0.0
+        header, body = partition_rows
+
+        body.each do |row|
+          rh = row_height(row, cols)
+          if used + rh <= remaining_height || head_rows.empty?
+            head_rows << row
+            used += rh
+          else
+            tail_rows << row
+          end
+        end
+
+        if head_rows.any?
+          head_table = rebuild_table(header, head_rows)
+          head = self.class.new(head_table, style: @style)
+        else
+          head = nil
+        end
+
+        tail_table = rebuild_table(header, tail_rows)
+        tail = self.class.new(tail_table, style: @style)
+        [head, tail]
+      end
+
+      private
+
+      def rows
+        @table.rows
+      end
+
+      def partition_rows
+        [@table.header, @table.body]
+      end
+
+      def column_widths_for(width)
+        return Array.new(@table.column_count, width.to_f / [@table.column_count, 1].max) if @table.column_count.zero?
+
+        @cached_widths ||= Table::AutoLayout.new(@table, available_width: width).compute
+      end
+
+      def row_height(row, cols)
+        max_h = 0.0
+        row.cells.each_with_index do |cell, ci|
+          cw = cols[ci] || 50.0
+          content_h = cell.content.sum do |node|
+            paragraph_height(node, cw)
+          end
+          max_h = [max_h, content_h].max
+        end
+        max_h + 4.0
+      end
+
+      def paragraph_height(paragraph, width)
+        return 0.0 unless paragraph.is_a?(Content::Paragraph)
+
+        style = cell_style(paragraph)
+        runs = paragraph.inline_runs.map { |r| InlineRun.new(r.text, style: style) }
+        TextFlowable.new(runs, style: style).height(width)
+      end
+
+      def render_cell(cell, x, y, w, h, boxes, _context)
+        style = cell_style(cell)
+        runs = []
+        cell.content.each do |node|
+          if node.is_a?(Content::Paragraph)
+            runs.concat(node.inline_runs.map { |r| InlineRun.new(r.text, style: style) })
+          end
+        end
+        if runs.any?
+          tf = TextFlowable.new(runs, style: style)
+          tboxes, = tf.emit(x + 2, y + h - 2, w - 4, nil)
+          boxes.concat(tboxes)
+        end
+        # Cell border: rectangle around the full cell.
+        boxes << Output::PlacedBox.rect(x: x, y: y, width: w, height: h,
+                                        stroke_width: 0.5, stroke_color: 'black')
+      end
+
+      def rebuild_table(header, body)
+        Content::Table.new(header: header.map { |r| r.cells.map(&:text) },
+                           body: body.map { |r| r.cells.map(&:text) })
+      end
+
+      # Use the parent table's style (which inherits from body →
+      # Times New Roman) rather than hard-coding Times-Roman.
+      # Falls back to Times-Roman only if the table style has no
+      # font_name (shouldn't happen in practice).
+      def cell_style(_cell_or_para)
+        @style.font_name ? @style : Style::Definition.new(font_name: 'Times-Roman', font_size: 10)
+      end
+    end
+  end
+end