pdf 0.1.0 → 0.1.1

data/.claude/execution/06-evaluators.md

@@ -0,0 +1,494 @@
+# Phase 6: Evaluators
+
+## Files
+- `lib/pdf/content_evaluator.rb`
+- `lib/pdf/header_evaluator.rb`
+- `lib/pdf/footer_evaluator.rb`
+
+---
+
+## 6.1 ContentEvaluator
+
+Evaluates view blueprint, resolves symbols, dispatches to components.
+
+**New features:**
+- `render_if` / `render_unless` for conditional rendering
+- `raw` for direct Prawn access
+- `date` now uses real Date component
+- `spacer` support
+
+```ruby
+# lib/pdf/content_evaluator.rb
+# frozen_string_literal: true
+
+module Pdf
+  class ContentEvaluator
+    def initialize(context, renderer)
+      @context = context
+      @renderer = renderer
+      @resolver = Resolver.new(context)
+    end
+
+    def evaluate(blueprint)
+      blueprint.elements.each { |el| evaluate_element(el) }
+    end
+
+    private
+
+    def evaluate_element(element)
+      type = element[:type]
+      args = element[:args]
+      options = element[:options]
+
+      case type
+      when :title, :subtitle, :heading, :paragraph, :span
+        render_text_component(type, args.first, options)
+
+      when :date
+        render_date(args.first, options)
+
+      when :hr
+        component(:hr).render(**options)
+
+      when :spacer
+        component(:spacer).render(**options)
+
+      when :alert
+        render_alert(args.first, options)
+
+      when :table
+        render_table(args.first, options)
+
+      when :section
+        render_section(args.first, options)
+
+      when :each
+        render_each(args.first, options)
+
+      when :partial
+        @context.send(args.first, @renderer)
+
+      when :page_break
+        @renderer.start_new_page
+
+      when :page_break_if
+        threshold = options[:threshold]
+        @renderer.start_new_page if @renderer.cursor < (@renderer.bounds.height * threshold)
+
+      when :render_if
+        render_conditional(args.first, options[:nested], truthy: true)
+
+      when :render_unless
+        render_conditional(args.first, options[:nested], truthy: false)
+
+      when :raw
+        # Escape hatch for direct Prawn access
+        block = options[:block]
+        @renderer.raw(&block) if block
+
+      else
+        # Try registered component
+        render_custom_component(type, args, options)
+      end
+    end
+
+    def render_text_component(type, source, options)
+      content = @resolver.resolve(source)
+      component(type).render(content, **options)
+    end
+
+    def render_date(source, options)
+      value = @resolver.resolve(source)
+      component(:date).render(value, **options)
+    end
+
+    def render_alert(source, options)
+      data = @resolver.resolve(source)
+
+      if data.is_a?(Hash)
+        component(:alert).render(
+          title: data[:title] || data["title"],
+          description: data[:description] || data["description"] || data[:subtitle] || data["subtitle"],
+          color: data[:color] || data["color"] || options[:color] || "blue"
+        )
+      else
+        component(:alert).render(title: data.to_s, color: options[:color] || "blue")
+      end
+    end
+
+    def render_table(source, options)
+      data = @resolver.resolve(source)
+      columns = options[:columns]
+      widths = options[:widths]
+
+      headers, rows = extract_table_data(data, columns, options)
+      component(:table).render(headers: headers, rows: rows, widths: widths)
+    end
+
+    def extract_table_data(data, columns, options)
+      if data.is_a?(Array) && data.first.is_a?(Hash) && columns
+        headers = columns.map { |c| c.is_a?(Hash) ? c[:label] : c.to_s.capitalize }
+        rows = data.map do |row|
+          columns.map do |col|
+            key = col.is_a?(Hash) ? col[:key] : col
+            row[key] || row[key.to_s] || "-"
+          end
+        end
+        [headers, rows]
+
+      elsif data.is_a?(Hash) && data[:headers] && data[:rows]
+        [data[:headers], data[:rows]]
+
+      elsif data.is_a?(Array) && data.first.is_a?(Array)
+        if options[:headers]
+          [options[:headers], data]
+        else
+          [data.first, data[1..]]
+        end
+
+      else
+        [["Key", "Value"], data.to_a]
+      end
+    end
+
+    def render_section(title, options)
+      component(:heading).render(title, size: 12)
+      evaluate(options[:nested]) if options[:nested]
+    end
+
+    def render_each(source, options)
+      collection = @resolver.resolve(source)
+      block = options[:block]
+      return if collection.nil? || collection.empty?
+
+      collection.each do |item|
+        item_context = EachItemContext.new(@context, item)
+        sub_evaluator = self.class.new(item_context, @renderer)
+
+        builder = Builders::ContentBuilder.new
+        builder.instance_exec(item, &block)
+        sub_evaluator.evaluate(builder.blueprint)
+      end
+    end
+
+    def render_conditional(condition, nested_blueprint, truthy:)
+      return unless nested_blueprint
+
+      condition_value = @resolver.resolve(condition)
+      should_render = truthy ? condition_value : !condition_value
+
+      evaluate(nested_blueprint) if should_render
+    end
+
+    def render_custom_component(type, args, options)
+      return unless Pdf.component_registered?(type)
+
+      comp = component(type)
+      if args.empty?
+        comp.render(**options)
+      else
+        resolved_args = args.map { |a| @resolver.resolve(a) }
+        comp.render(*resolved_args, **options)
+      end
+    end
+
+    def component(type)
+      Pdf.component(type).new(@renderer.pdf)
+    end
+  end
+
+  # Context wrapper for each iteration
+  class EachItemContext
+    def initialize(parent, item)
+      @parent = parent
+      @item = item
+    end
+
+    def data
+      @parent.data
+    end
+
+    attr_reader :item
+
+    def method_missing(method, *args, &block)
+      if @item.respond_to?(method)
+        @item.send(method, *args, &block)
+      elsif @item.is_a?(Hash) && (@item.key?(method) || @item.key?(method.to_s))
+        @item[method] || @item[method.to_s]
+      else
+        @parent.send(method, *args, &block)
+      end
+    end
+
+    def respond_to_missing?(method, include_private = false)
+      @item.respond_to?(method) ||
+        (@item.is_a?(Hash) && (@item.key?(method) || @item.key?(method.to_s))) ||
+        @parent.respond_to?(method, include_private)
+    end
+  end
+end
+```
+
+---
+
+## 6.2 HeaderEvaluator
+
+Evaluates header blueprint.
+
+**QR code now takes `data:` param** - generates from data, not file path.
+
+```ruby
+# lib/pdf/header_evaluator.rb
+# frozen_string_literal: true
+
+module Pdf
+  class HeaderEvaluator
+    def initialize(context, renderer)
+      @context = context
+      @renderer = renderer
+      @resolver = Resolver.new(context)
+    end
+
+    def evaluate(blueprint)
+      blueprint.elements.each { |el| evaluate_element(el) }
+    end
+
+    private
+
+    def evaluate_element(element)
+      type = element[:type]
+      args = element[:args]
+      options = element[:options]
+
+      case type
+      when :logo
+        component(:logo).render(args.first, **options)
+
+      when :qr_code
+        # QR code generates from data, not file path
+        data = @resolver.resolve(options[:data])
+        component(:qr_code).render(data: data, **options.except(:data))
+
+      when :context
+        lines = @resolver.resolve(args.first)
+        component(:context).render(lines, **options)
+
+      when :header_text
+        content = @resolver.resolve(args.first)
+        component(:paragraph).render(content, **options)
+
+      else
+        render_custom_component(type, args, options)
+      end
+    end
+
+    def render_custom_component(type, args, options)
+      return unless Pdf.component_registered?(type)
+
+      comp = component(type)
+      resolved_args = args.map { |a| @resolver.resolve(a) }
+      comp.render(*resolved_args, **options)
+    end
+
+    def component(type)
+      Pdf.component(type).new(@renderer.pdf)
+    end
+  end
+end
+```
+
+---
+
+## 6.3 FooterEvaluator
+
+Sets up footer (deferred rendering via repeat).
+
+**Page numbers handled here** - not as a separate component. This is the right place since page_count isn't known until all content is rendered.
+
+```ruby
+# lib/pdf/footer_evaluator.rb
+# frozen_string_literal: true
+
+module Pdf
+  class FooterEvaluator
+    def initialize(context, renderer)
+      @context = context
+      @renderer = renderer
+      @resolver = Resolver.new(context)
+    end
+
+    def setup(blueprint)
+      texts = []
+      page_number_opts = nil
+
+      blueprint.elements.each do |el|
+        case el[:type]
+        when :footer_text
+          content = @resolver.resolve(el[:args].first)
+          texts << { text: content, size: el[:options][:size] || 8 }
+
+        when :page_number
+          page_number_opts = el[:options]
+        end
+      end
+
+      @renderer.setup_footer do |pdf|
+        render_footer_content(pdf, texts, page_number_opts)
+      end
+    end
+
+    private
+
+    def render_footer_content(pdf, texts, page_number_opts)
+      # Text lines
+      unless texts.empty?
+        pdf.repeat(:all) do
+          pdf.canvas do
+            pdf.bounding_box([36, 60], width: pdf.bounds.absolute_right - 72, height: 40) do
+              y = 30
+              texts.each do |t|
+                pdf.draw_text t[:text].to_s, at: [0, y], size: t[:size]
+                y -= 12
+              end
+            end
+          end
+        end
+      end
+
+      # Page numbers
+      return unless page_number_opts
+
+      position = page_number_opts[:position] || :right
+      size = page_number_opts[:size] || 8
+      fmt = page_number_opts[:format] || "Page %<page>d / %<total>d"
+
+      pdf.repeat(:all, dynamic: true) do
+        pdf.canvas do
+          page_str = format(fmt, page: pdf.page_number, total: pdf.page_count)
+          text_w = pdf.width_of(page_str, size: size)
+          x = position == :right ? pdf.bounds.absolute_right - 36 - text_w : 36
+          pdf.draw_text page_str, at: [x, 24], size: size
+        end
+      end
+    end
+  end
+end
+```
+
+---
+
+## Tests
+
+```ruby
+# test/pdf/content_evaluator_test.rb
+# frozen_string_literal: true
+
+require "test_helper"
+
+class ContentEvaluatorTest < Minitest::Test
+  def setup
+    @view_class = Class.new(Pdf::View) do
+      title :report_title
+      paragraph "Static text"
+      alert :summary
+
+      def report_title = "Dynamic Title"
+      def summary = { title: "OK", color: "green" }
+    end
+
+    @view = @view_class.new
+    @renderer = Pdf::Renderer.new.setup
+    @evaluator = Pdf::ContentEvaluator.new(@view, @renderer)
+  end
+
+  def test_evaluates_blueprint
+    @evaluator.evaluate(@view_class.blueprint)
+  end
+
+  def test_resolves_symbols
+    @evaluator.evaluate(@view_class.blueprint)
+    pdf = @renderer.finalize
+    assert_includes pdf, "Dynamic Title"
+  end
+
+  def test_render_if_renders_when_condition_is_truthy
+    conditional_view = Class.new(Pdf::View) do
+      render_if(:show_title) { title "Conditional" }
+      def show_title = data[:show]
+    end
+
+    view = conditional_view.new(show: true)
+    pdf = view.to_pdf
+    assert_includes pdf, "Conditional"
+  end
+
+  def test_render_if_skips_when_condition_is_falsy
+    conditional_view = Class.new(Pdf::View) do
+      render_if(:show_title) { title "Conditional" }
+      def show_title = data[:show]
+    end
+
+    view = conditional_view.new(show: false)
+    pdf = view.to_pdf
+    refute_includes pdf, "Conditional"
+  end
+
+  def test_render_unless_renders_when_condition_is_falsy
+    conditional_view = Class.new(Pdf::View) do
+      render_unless(:hide_content) { title "Visible" }
+      def hide_content = data[:hidden]
+    end
+
+    view = conditional_view.new(hidden: false)
+    pdf = view.to_pdf
+    assert_includes pdf, "Visible"
+  end
+
+  def test_render_unless_skips_when_condition_is_truthy
+    conditional_view = Class.new(Pdf::View) do
+      render_unless(:hide_content) { title "Visible" }
+      def hide_content = data[:hidden]
+    end
+
+    view = conditional_view.new(hidden: true)
+    pdf = view.to_pdf
+    refute_includes pdf, "Visible"
+  end
+
+  def test_raw_executes_block_with_prawn_document
+    raw_view = Class.new(Pdf::View) do
+      raw { |pdf| pdf.stroke_circle [100, 100], 50 }
+    end
+
+    raw_view.new.to_pdf
+  end
+end
+
+# test/pdf/each_item_context_test.rb
+# frozen_string_literal: true
+
+require "test_helper"
+
+class EachItemContextTest < Minitest::Test
+  def setup
+    @parent = Object.new
+    def @parent.data = { key: "parent_value" }
+    def @parent.parent_method = "from_parent"
+
+    @item = { name: "Item", value: 42 }
+    @context = Pdf::EachItemContext.new(@parent, @item)
+  end
+
+  def test_resolves_item_keys
+    assert_equal "Item", @context.name
+  end
+
+  def test_falls_back_to_parent
+    assert_equal "from_parent", @context.parent_method
+  end
+
+  def test_exposes_item
+    assert_equal @item, @context.item
+  end
+end
+```