pdf 0.1.0 → 0.1.1

data/.claude/execution/04-builders.md

@@ -0,0 +1,322 @@
+# Phase 4: Builders (DSL)
+
+All builders include `DynamicComponents` module for custom component support (DRY).
+
+## Files
+- `lib/pdf/builders/content_builder.rb`
+- `lib/pdf/builders/header_builder.rb`
+- `lib/pdf/builders/footer_builder.rb`
+
+---
+
+## 4.1 ContentBuilder
+
+Main DSL for view content. Includes conditional rendering via `render_if`/`render_unless`.
+
+```ruby
+# lib/pdf/builders/content_builder.rb
+# frozen_string_literal: true
+
+module Pdf
+  module Builders
+    class ContentBuilder
+      include DynamicComponents
+
+      attr_reader :blueprint
+
+      def initialize(blueprint = Blueprint.new)
+        @blueprint = blueprint
+      end
+
+      def title(value, **options)
+        @blueprint.add(:title, value, **options)
+      end
+
+      def subtitle(value, **options)
+        @blueprint.add(:subtitle, value, **options)
+      end
+
+      def date(value, **options)
+        @blueprint.add(:date, value, **options)
+      end
+
+      def heading(value, **options)
+        @blueprint.add(:heading, value, **options)
+      end
+
+      def paragraph(value, **options)
+        @blueprint.add(:paragraph, value, **options)
+      end
+
+      def span(value, **options)
+        @blueprint.add(:span, value, **options)
+      end
+
+      def hr(**options)
+        @blueprint.add(:hr, **options)
+      end
+
+      def spacer(**options)
+        @blueprint.add(:spacer, **options)
+      end
+
+      def alert(source, **options)
+        @blueprint.add(:alert, source, **options)
+      end
+
+      def table(source, **options)
+        @blueprint.add(:table, source, **options)
+      end
+
+      def section(title_text, **options, &block)
+        nested = self.class.new
+        nested.instance_eval(&block) if block
+        @blueprint.add(:section, title_text, nested: nested.blueprint, **options)
+      end
+
+      def each(source, **options, &block)
+        @blueprint.add(:each, source, block: block, **options)
+      end
+
+      def partial(method_name)
+        @blueprint.add(:partial, method_name)
+      end
+
+      def page_break
+        @blueprint.add(:page_break)
+      end
+
+      def page_break_if(threshold:)
+        @blueprint.add(:page_break_if, threshold: threshold)
+      end
+
+      # Conditional rendering - render block only if condition is truthy
+      def render_if(condition, &block)
+        nested = self.class.new
+        nested.instance_eval(&block) if block
+        @blueprint.add(:render_if, condition, nested: nested.blueprint)
+      end
+
+      # Conditional rendering - render block only if condition is falsy
+      def render_unless(condition, &block)
+        nested = self.class.new
+        nested.instance_eval(&block) if block
+        @blueprint.add(:render_unless, condition, nested: nested.blueprint)
+      end
+
+      # Escape hatch for direct Prawn access
+      def raw(&block)
+        @blueprint.add(:raw, block: block)
+      end
+    end
+  end
+end
+```
+
+---
+
+## 4.2 HeaderBuilder
+
+DSL for layout headers. Uses DynamicComponents mixin.
+
+```ruby
+# lib/pdf/builders/header_builder.rb
+# frozen_string_literal: true
+
+module Pdf
+  module Builders
+    class HeaderBuilder
+      include DynamicComponents
+
+      attr_reader :blueprint
+
+      def initialize
+        @blueprint = Blueprint.new
+      end
+
+      def logo(path, **options)
+        @blueprint.add(:logo, path, **options)
+      end
+
+      def qr_code(**options)
+        @blueprint.add(:qr_code, **options)
+      end
+
+      def context(source, **options)
+        @blueprint.add(:context, source, **options)
+      end
+
+      def text(value, **options)
+        @blueprint.add(:header_text, value, **options)
+      end
+    end
+  end
+end
+```
+
+---
+
+## 4.3 FooterBuilder
+
+DSL for layout footers. Uses DynamicComponents mixin.
+
+```ruby
+# lib/pdf/builders/footer_builder.rb
+# frozen_string_literal: true
+
+module Pdf
+  module Builders
+    class FooterBuilder
+      include DynamicComponents
+
+      attr_reader :blueprint
+
+      def initialize
+        @blueprint = Blueprint.new
+      end
+
+      def text(source, **options)
+        @blueprint.add(:footer_text, source, **options)
+      end
+
+      # Page number is handled by FooterEvaluator, not as a component
+      def page_number(**options)
+        @blueprint.add(:page_number, **options)
+      end
+    end
+  end
+end
+```
+
+---
+
+## Tests
+
+```ruby
+# test/pdf/builders/content_builder_test.rb
+# frozen_string_literal: true
+
+require "test_helper"
+
+class ContentBuilderTest < Minitest::Test
+  def setup
+    @builder = Pdf::Builders::ContentBuilder.new
+  end
+
+  def test_title_adds_element
+    @builder.title("Report")
+    el = @builder.blueprint.elements.first
+    assert_equal :title, el[:type]
+    assert_equal ["Report"], el[:args]
+  end
+
+  def test_section_creates_nested_blueprint
+    @builder.section("Details") do
+      paragraph "Text"
+      table :items
+    end
+
+    el = @builder.blueprint.elements.first
+    assert_equal :section, el[:type]
+    assert_equal 2, el[:options][:nested].elements.size
+  end
+
+  def test_each_stores_block
+    @builder.each(:items) { |item| paragraph item[:name] }
+    el = @builder.blueprint.elements.first
+    assert_kind_of Proc, el[:options][:block]
+  end
+
+  def test_render_if_stores_condition_and_nested_blueprint
+    @builder.render_if(:has_items) do
+      table :items
+    end
+
+    el = @builder.blueprint.elements.first
+    assert_equal :render_if, el[:type]
+    assert_equal :has_items, el[:args].first
+    assert_equal 1, el[:options][:nested].elements.size
+  end
+
+  def test_render_unless_stores_condition_and_nested_blueprint
+    @builder.render_unless(:is_empty) do
+      paragraph "Not empty"
+    end
+
+    el = @builder.blueprint.elements.first
+    assert_equal :render_unless, el[:type]
+    assert_equal :is_empty, el[:args].first
+  end
+
+  def test_raw_stores_block_for_direct_prawn_access
+    @builder.raw { |pdf| pdf.stroke_circle [100, 100], 50 }
+    el = @builder.blueprint.elements.first
+    assert_equal :raw, el[:type]
+    assert_kind_of Proc, el[:options][:block]
+  end
+
+  def test_dynamic_components_via_mixin
+    Pdf.register_component(:badge, Class.new(Pdf::Component))
+    @builder.badge("NEW", color: "red")
+    el = @builder.blueprint.elements.first
+    assert_equal :badge, el[:type]
+  ensure
+    Pdf.instance_variable_get(:@components).delete(:badge)
+  end
+end
+
+# test/pdf/builders/header_builder_test.rb
+# frozen_string_literal: true
+
+require "test_helper"
+
+class HeaderBuilderTest < Minitest::Test
+  def setup
+    @builder = Pdf::Builders::HeaderBuilder.new
+  end
+
+  def test_adds_logo
+    @builder.logo("logo.png", width: 100)
+    assert_equal :logo, @builder.blueprint.elements.first[:type]
+  end
+
+  def test_adds_qr_code
+    @builder.qr_code(data: "https://example.com")
+    assert_equal :qr_code, @builder.blueprint.elements.first[:type]
+  end
+
+  def test_adds_context
+    @builder.context(:context_lines)
+    assert_equal :context, @builder.blueprint.elements.first[:type]
+  end
+
+  def test_includes_dynamic_components
+    assert_includes Pdf::Builders::HeaderBuilder.ancestors, Pdf::DynamicComponents
+  end
+end
+
+# test/pdf/builders/footer_builder_test.rb
+# frozen_string_literal: true
+
+require "test_helper"
+
+class FooterBuilderTest < Minitest::Test
+  def setup
+    @builder = Pdf::Builders::FooterBuilder.new
+  end
+
+  def test_adds_text
+    @builder.text(:footer_title, size: 8)
+    assert_equal :footer_text, @builder.blueprint.elements.first[:type]
+  end
+
+  def test_adds_page_number
+    @builder.page_number(position: :right)
+    assert_equal :page_number, @builder.blueprint.elements.first[:type]
+  end
+
+  def test_includes_dynamic_components
+    assert_includes Pdf::Builders::FooterBuilder.ancestors, Pdf::DynamicComponents
+  end
+end
+```

data/.claude/execution/05-view-layout.md

@@ -0,0 +1,362 @@
+# Phase 5: View & Layout
+
+## Files
+- `lib/pdf/view.rb`
+- `lib/pdf/layout.rb`
+
+---
+
+## 5.1 View
+
+Base class for PDF views. Provides class-level DSL.
+
+**Key fix: Proper inheritance** - Child views inherit parent's blueprint via `dup`, so they get all parent elements plus can add their own.
+
+```ruby
+# lib/pdf/view.rb
+# frozen_string_literal: true
+
+module Pdf
+  class View
+    class << self
+      def inherited(subclass)
+        # CRITICAL: Inherit parent's blueprint via dup, not empty blueprint
+        # This allows child views to extend parent views
+        parent_blueprint = @blueprint || Blueprint.new
+        subclass.instance_variable_set(:@blueprint, parent_blueprint.dup)
+        subclass.instance_variable_set(:@content_builder, nil)
+      end
+
+      def blueprint
+        @blueprint ||= Blueprint.new
+      end
+
+      def layout(klass)
+        blueprint.set_layout(klass)
+      end
+
+      # DSL methods - delegate to ContentBuilder
+      %i[title subtitle date heading paragraph span hr spacer alert table page_break].each do |method|
+        define_method(method) do |*args, **options, &block|
+          content_builder.send(method, *args, **options, &block)
+        end
+      end
+
+      def section(title_text, **options, &block)
+        content_builder.section(title_text, **options, &block)
+      end
+
+      def each(source, **options, &block)
+        content_builder.each(source, **options, &block)
+      end
+
+      def partial(method_name)
+        content_builder.partial(method_name)
+      end
+
+      def page_break_if(threshold:)
+        content_builder.page_break_if(threshold: threshold)
+      end
+
+      def render_if(condition, &block)
+        content_builder.render_if(condition, &block)
+      end
+
+      def render_unless(condition, &block)
+        content_builder.render_unless(condition, &block)
+      end
+
+      def raw(&block)
+        content_builder.raw(&block)
+      end
+
+      # Dynamic component support via DynamicComponents pattern
+      def method_missing(name, *args, **options, &block)
+        if Pdf.component_registered?(name)
+          content_builder.send(name, *args, **options, &block)
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        Pdf.component_registered?(name) || super
+      end
+
+      private
+
+      def content_builder
+        @content_builder ||= Builders::ContentBuilder.new(blueprint)
+      end
+    end
+
+    attr_reader :data
+
+    def initialize(data = {})
+      @data = data.is_a?(Hash) ? symbolize_keys(data) : data
+    end
+
+    def to_pdf
+      renderer = Renderer.new
+      layout_class = self.class.blueprint.layout_class
+
+      if layout_class
+        layout = layout_class.new(self)
+        layout.render(renderer)
+      else
+        renderer.setup
+        render_content(renderer)
+      end
+
+      renderer.finalize
+    end
+
+    def to_file(path)
+      File.binwrite(path, to_pdf)
+    end
+
+    def render_content(renderer)
+      evaluator = ContentEvaluator.new(self, renderer)
+      evaluator.evaluate(self.class.blueprint)
+    end
+
+    private
+
+    def symbolize_keys(hash)
+      hash.transform_keys { |k| k.is_a?(String) ? k.to_sym : k }
+    end
+  end
+end
+```
+
+---
+
+## 5.2 Layout
+
+Base class for layouts. Defines header/footer/margins.
+
+**Uses shared `Pdf::DEFAULT_MARGINS`** - same constant as Renderer for consistency.
+
+```ruby
+# lib/pdf/layout.rb
+# frozen_string_literal: true
+
+module Pdf
+  class Layout
+    class << self
+      def inherited(subclass)
+        subclass.instance_variable_set(:@header_blueprint, nil)
+        subclass.instance_variable_set(:@footer_blueprint, nil)
+        subclass.instance_variable_set(:@margins_config, Pdf::DEFAULT_MARGINS.dup)
+      end
+
+      def header(&block)
+        builder = Builders::HeaderBuilder.new
+        builder.instance_eval(&block)
+        @header_blueprint = builder.blueprint
+      end
+
+      def footer(&block)
+        builder = Builders::FooterBuilder.new
+        builder.instance_eval(&block)
+        @footer_blueprint = builder.blueprint
+      end
+
+      def margins(**options)
+        @margins_config = Pdf::DEFAULT_MARGINS.merge(options)
+      end
+
+      attr_reader :header_blueprint, :footer_blueprint
+
+      def margins_config
+        @margins_config || Pdf::DEFAULT_MARGINS
+      end
+    end
+
+    attr_reader :view
+
+    def initialize(view)
+      @view = view
+    end
+
+    def render(renderer)
+      renderer.setup(margins: self.class.margins_config)
+
+      render_header(renderer) if self.class.header_blueprint
+      view.render_content(renderer)
+      setup_footer(renderer) if self.class.footer_blueprint
+    end
+
+    private
+
+    def render_header(renderer)
+      evaluator = HeaderEvaluator.new(view, renderer)
+      evaluator.evaluate(self.class.header_blueprint)
+    end
+
+    def setup_footer(renderer)
+      evaluator = FooterEvaluator.new(view, renderer)
+      evaluator.setup(self.class.footer_blueprint)
+    end
+  end
+end
+```
+
+---
+
+## Tests
+
+```ruby
+# test/pdf/view_test.rb
+# frozen_string_literal: true
+
+require "test_helper"
+
+class ViewTest < Minitest::Test
+  def test_class_level_dsl_stores_blueprint
+    view_class = Class.new(Pdf::View) do
+      title "Report"
+      paragraph :description
+
+      section "Items" do
+        table :items
+      end
+
+      def description
+        "Desc: #{data[:name]}"
+      end
+    end
+
+    assert_equal 3, view_class.blueprint.elements.size
+  end
+
+  def test_inheritance_child_inherits_parent_elements
+    parent = Class.new(Pdf::View) do
+      title "Parent Title"
+      paragraph "Parent content"
+    end
+
+    child = Class.new(parent) do
+      subtitle "Child Subtitle"
+    end
+
+    # Parent has 2 elements
+    assert_equal 2, parent.blueprint.elements.size
+    # Child has parent's 2 elements + its own 1 = 3 total
+    assert_equal 3, child.blueprint.elements.size
+  end
+
+  def test_inheritance_child_modifications_dont_affect_parent
+    parent = Class.new(Pdf::View) do
+      title "Parent Title"
+      paragraph "Parent content"
+    end
+
+    child = Class.new(parent) do
+      subtitle "Child Subtitle"
+    end
+
+    # Trigger child blueprint
+    child.blueprint
+    assert_equal 2, parent.blueprint.elements.size
+  end
+
+  def test_inheritance_preserves_element_order
+    parent = Class.new(Pdf::View) do
+      title "Parent Title"
+      paragraph "Parent content"
+    end
+
+    child = Class.new(parent) do
+      subtitle "Child Subtitle"
+    end
+
+    elements = child.blueprint.elements
+    assert_equal :title, elements[0][:type]
+    assert_equal :paragraph, elements[1][:type]
+    assert_equal :subtitle, elements[2][:type]
+  end
+
+  def test_render_if_and_render_unless_store_conditional_elements
+    view_class = Class.new(Pdf::View) do
+      render_if(:show_header) { title "Conditional Title" }
+      render_unless(:hide_footer) { paragraph "Footer" }
+    end
+
+    assert_equal 2, view_class.blueprint.elements.size
+    assert_equal :render_if, view_class.blueprint.elements[0][:type]
+    assert_equal :render_unless, view_class.blueprint.elements[1][:type]
+  end
+
+  def test_initialize_symbolizes_string_keys
+    view = Pdf::View.new("name" => "Test")
+    assert_equal "Test", view.data[:name]
+  end
+
+  def test_to_pdf_generates_pdf
+    view_class = Class.new(Pdf::View) do
+      title "Test"
+    end
+
+    pdf = view_class.new.to_pdf
+    assert pdf.start_with?("%PDF")
+  end
+end
+
+# test/pdf/layout_test.rb
+# frozen_string_literal: true
+
+require "test_helper"
+
+class LayoutTest < Minitest::Test
+  def test_stores_header_blueprint
+    layout_class = Class.new(Pdf::Layout) do
+      header do
+        logo "logo.png"
+        context :lines
+      end
+    end
+
+    assert_equal 2, layout_class.header_blueprint.elements.size
+  end
+
+  def test_stores_footer_blueprint
+    layout_class = Class.new(Pdf::Layout) do
+      footer do
+        text :title
+        page_number
+      end
+    end
+
+    assert_equal 2, layout_class.footer_blueprint.elements.size
+  end
+
+  def test_stores_margins
+    layout_class = Class.new(Pdf::Layout) do
+      margins top: 80, bottom: 60
+    end
+
+    assert_equal 80, layout_class.margins_config[:top]
+    assert_equal 60, layout_class.margins_config[:bottom]
+  end
+
+  def test_uses_default_margins_as_base
+    layout_class = Class.new(Pdf::Layout) do
+      margins top: 80, bottom: 60
+    end
+
+    assert_equal Pdf::DEFAULT_MARGINS[:right], layout_class.margins_config[:right]
+    assert_equal Pdf::DEFAULT_MARGINS[:left], layout_class.margins_config[:left]
+  end
+
+  def test_render_generates_pdf
+    layout_class = Class.new(Pdf::Layout)
+    view_class = Class.new(Pdf::View) do
+      layout layout_class
+    end
+
+    pdf = view_class.new.to_pdf
+    assert pdf.start_with?("%PDF")
+  end
+end
+```