pdf 0.1.0 → 0.1.1

data/.claude/execution/03-components.md

@@ -0,0 +1,551 @@
+# Phase 3: Built-in Components
+
+**Principles:**
+- NEVER swallow errors - all failures bubble up to client
+- Each component is single-responsibility
+- Components only render, no business logic
+
+## Files
+- `lib/pdf/components/title.rb`
+- `lib/pdf/components/subtitle.rb`
+- `lib/pdf/components/heading.rb`
+- `lib/pdf/components/paragraph.rb`
+- `lib/pdf/components/span.rb`
+- `lib/pdf/components/date.rb`
+- `lib/pdf/components/hr.rb`
+- `lib/pdf/components/spacer.rb`
+- `lib/pdf/components/alert.rb`
+- `lib/pdf/components/table.rb`
+- `lib/pdf/components/logo.rb`
+- `lib/pdf/components/qr_code.rb`
+- `lib/pdf/components/context.rb`
+
+Note: PageNumber is handled in FooterEvaluator, not as a component.
+
+---
+
+## 3.1 Title
+
+```ruby
+# lib/pdf/components/title.rb
+# frozen_string_literal: true
+
+module Pdf
+  module Components
+    class Title < Component
+      def render(content, size: 20, **options)
+        text content, size: size, style: :bold, **options
+        move_down 10
+      end
+    end
+  end
+end
+```
+
+---
+
+## 3.2 Subtitle
+
+```ruby
+# lib/pdf/components/subtitle.rb
+# frozen_string_literal: true
+
+module Pdf
+  module Components
+    class Subtitle < Component
+      def render(content, size: 16, **options)
+        text content, size: size, **options
+        move_down 5
+      end
+    end
+  end
+end
+```
+
+---
+
+## 3.3 Heading
+
+```ruby
+# lib/pdf/components/heading.rb
+# frozen_string_literal: true
+
+module Pdf
+  module Components
+    class Heading < Component
+      def render(content, size: 14, **options)
+        text content, size: size, style: :bold, **options
+        move_down 8
+      end
+    end
+  end
+end
+```
+
+---
+
+## 3.4 Paragraph
+
+```ruby
+# lib/pdf/components/paragraph.rb
+# frozen_string_literal: true
+
+module Pdf
+  module Components
+    class Paragraph < Component
+      def render(content, size: 10, leading: 3, **options)
+        text content, size: size, leading: leading, **options
+        move_down 10
+      end
+    end
+  end
+end
+```
+
+---
+
+## 3.5 Span
+
+```ruby
+# lib/pdf/components/span.rb
+# frozen_string_literal: true
+
+module Pdf
+  module Components
+    class Span < Component
+      def render(content, size: 10, **options)
+        text content, size: size, **options
+        move_down 3
+      end
+    end
+  end
+end
+```
+
+---
+
+## 3.6 Date
+
+Real Date component for formatted date rendering.
+
+```ruby
+# lib/pdf/components/date.rb
+# frozen_string_literal: true
+
+module Pdf
+  module Components
+    class Date < Component
+      DEFAULT_FORMAT = "%B %d, %Y"
+
+      def render(value, format: DEFAULT_FORMAT, size: 10, align: :right, **options)
+        formatted = format_date(value, format)
+        text formatted, size: size, align: align, **options
+        move_down 5
+      end
+
+      private
+
+      def format_date(value, format)
+        case value
+        when ::Date, ::Time, ::DateTime
+          value.strftime(format)
+        when String
+          value
+        else
+          value.to_s
+        end
+      end
+    end
+  end
+end
+```
+
+---
+
+## 3.7 Hr
+
+```ruby
+# lib/pdf/components/hr.rb
+# frozen_string_literal: true
+
+module Pdf
+  module Components
+    class Hr < Component
+      def render(**_options)
+        stroke_horizontal_rule
+        move_down 10
+      end
+    end
+  end
+end
+```
+
+---
+
+## 3.8 Spacer
+
+Explicit vertical space component.
+
+```ruby
+# lib/pdf/components/spacer.rb
+# frozen_string_literal: true
+
+module Pdf
+  module Components
+    class Spacer < Component
+      def render(amount: 20, **_options)
+        move_down amount
+      end
+    end
+  end
+end
+```
+
+---
+
+## 3.9 Alert
+
+```ruby
+# lib/pdf/components/alert.rb
+# frozen_string_literal: true
+
+module Pdf
+  module Components
+    class Alert < Component
+      COLORS = {
+        "green"  => { bg: "C8E6C9", text: "2E7D32", border: "4CAF50" },
+        "orange" => { bg: "FFE0B2", text: "E65100", border: "FF9800" },
+        "red"    => { bg: "FFCDD2", text: "C62828", border: "F44336" },
+        "blue"   => { bg: "E1F5FE", text: "0277BD", border: "2196F3" }
+      }.freeze
+
+      def render(title:, description: nil, color: "blue", **_options)
+        scheme = COLORS[color.to_s] || COLORS["blue"]
+
+        title_h = 20
+        desc_h = description ? (@pdf.height_of(description.to_s, width: bounds.width - 20, size: 10) + 10) : 0
+        total_h = title_h + desc_h + 6
+
+        bounding_box([bounds.left, cursor], width: bounds.width, height: total_h) do
+          @pdf.stroke_color scheme[:border]
+          @pdf.line_width 0.5
+          @pdf.fill_color scheme[:bg]
+          @pdf.fill_and_stroke_rounded_rectangle [bounds.left, bounds.top], bounds.width, bounds.height, 5
+
+          @pdf.fill_color scheme[:text]
+
+          y = bounds.top - 10
+          @pdf.text_box title.to_s, at: [10, y], width: bounds.width - 20, size: 11, style: :bold
+
+          if description
+            y -= 18
+            @pdf.text_box description.to_s, at: [10, y], width: bounds.width - 20, size: 10
+          end
+        end
+
+        @pdf.fill_color "000000"
+        move_down 15
+      end
+    end
+  end
+end
+```
+
+---
+
+## 3.10 Table
+
+```ruby
+# lib/pdf/components/table.rb
+# frozen_string_literal: true
+
+module Pdf
+  module Components
+    class Table < Component
+      def render(headers:, rows:, widths: nil, **_options)
+        data = [headers] + rows
+
+        opts = {
+          header: true,
+          cell_style: { borders: [:top, :bottom, :left, :right], padding: [4, 6], size: 8 }
+        }
+
+        opts[:column_widths] = calculate_widths(widths) if widths
+        opts[:width] = bounds.width unless widths
+
+        @pdf.table(data, **opts) do
+          row(0).background_color = "333333"
+          row(0).text_color = "FFFFFF"
+          row(0).font_style = :bold
+
+          (1..row_length - 1).each do |i|
+            row(i).background_color = i.odd? ? "F5F5F5" : "FFFFFF"
+          end
+        end
+
+        move_down 15
+      end
+
+      private
+
+      def calculate_widths(widths)
+        total = bounds.width
+        widths.map do |w|
+          case w
+          when String then w.end_with?("%") ? (w.to_f / 100 * total).round : w.to_f
+          when Numeric then w.to_f
+          else raise ArgumentError, "Invalid width: #{w}"
+          end
+        end
+      end
+    end
+  end
+end
+```
+
+---
+
+## 3.11 Logo
+
+No silent failures - raises if file not found.
+
+```ruby
+# lib/pdf/components/logo.rb
+# frozen_string_literal: true
+
+module Pdf
+  module Components
+    class Logo < Component
+      def render(path, width: 120, height: nil, **_options)
+        raise Pdf::FileNotFoundError, "Logo not found: #{path}" unless File.exist?(path)
+
+        opts = { width: width }
+        opts[:height] = height if height
+        @pdf.image path, **opts
+      end
+    end
+  end
+end
+```
+
+---
+
+## 3.12 QrCode
+
+Generates QR code from data using rqrcode gem. No pre-generated image needed.
+
+```ruby
+# lib/pdf/components/qr_code.rb
+# frozen_string_literal: true
+
+require "rqrcode"
+
+module Pdf
+  module Components
+    class QrCode < Component
+      def render(data:, size: 80, position: :right, **_options)
+        png_data = generate_qr_png(data, size)
+
+        if position == :right
+          @pdf.float do
+            bounding_box([bounds.width - size, cursor], width: size) do
+              @pdf.image StringIO.new(png_data), width: size, height: size
+            end
+          end
+        else
+          @pdf.image StringIO.new(png_data), width: size, height: size
+        end
+      end
+
+      private
+
+      def generate_qr_png(data, size)
+        qrcode = RQRCode::QRCode.new(data.to_s)
+        png = qrcode.as_png(
+          bit_depth: 1,
+          border_modules: 2,
+          color_mode: ChunkyPNG::COLOR_GRAYSCALE,
+          color: "black",
+          fill: "white",
+          size: size * 4  # Higher resolution for quality
+        )
+        png.to_s
+      end
+    end
+  end
+end
+```
+
+---
+
+## 3.13 Context
+
+```ruby
+# lib/pdf/components/context.rb
+# frozen_string_literal: true
+
+module Pdf
+  module Components
+    class Context < Component
+      def render(lines, label: "CONTEXT", **_options)
+        raise ArgumentError, "Context lines cannot be nil" if lines.nil?
+        return if lines.empty?
+
+        text label, size: 12, style: :bold
+        lines.each { |line| text line.to_s, size: 10 }
+        move_down 20
+      end
+    end
+  end
+end
+```
+
+---
+
+## Tests (examples)
+
+```ruby
+# test/pdf/components/title_test.rb
+# frozen_string_literal: true
+
+require "test_helper"
+
+class TitleComponentTest < Minitest::Test
+  def setup
+    @renderer = Pdf::Renderer.new.setup
+    @component = Pdf::Components::Title.new(@renderer.pdf)
+  end
+
+  def test_renders_title_text
+    @component.render("Hello")
+    # Just verify it doesn't raise - actual rendering tested via integration
+  end
+end
+
+# test/pdf/components/alert_test.rb
+# frozen_string_literal: true
+
+require "test_helper"
+
+class AlertComponentTest < Minitest::Test
+  def setup
+    @renderer = Pdf::Renderer.new.setup
+    @component = Pdf::Components::Alert.new(@renderer.pdf)
+  end
+
+  def test_renders_without_error
+    @component.render(title: "Test", color: "green")
+  end
+
+  def test_defaults_to_blue
+    @component.render(title: "Test")
+  end
+end
+
+# test/pdf/components/table_test.rb
+# frozen_string_literal: true
+
+require "test_helper"
+
+class TableComponentTest < Minitest::Test
+  def setup
+    @renderer = Pdf::Renderer.new.setup
+    @component = Pdf::Components::Table.new(@renderer.pdf)
+  end
+
+  def test_renders_table
+    @component.render(headers: ["A", "B"], rows: [["1", "2"]])
+  end
+
+  def test_calculates_percentage_widths
+    @component.render(headers: ["A", "B"], rows: [["1", "2"]], widths: ["50%", "50%"])
+  end
+end
+
+# test/pdf/components/date_test.rb
+# frozen_string_literal: true
+
+require "test_helper"
+
+class DateComponentTest < Minitest::Test
+  def setup
+    @renderer = Pdf::Renderer.new.setup
+    @component = Pdf::Components::Date.new(@renderer.pdf)
+  end
+
+  def test_formats_date_objects
+    date = ::Date.new(2024, 12, 25)
+    @component.render(date)
+    # Actual format verified in integration tests
+  end
+
+  def test_accepts_custom_format
+    date = ::Date.new(2024, 12, 25)
+    @component.render(date, format: "%d/%m/%Y")
+  end
+
+  def test_passes_through_strings
+    @component.render("Custom date")
+  end
+end
+
+# test/pdf/components/logo_test.rb
+# frozen_string_literal: true
+
+require "test_helper"
+
+class LogoComponentTest < Minitest::Test
+  def setup
+    @renderer = Pdf::Renderer.new.setup
+    @component = Pdf::Components::Logo.new(@renderer.pdf)
+  end
+
+  def test_raises_file_not_found_error
+    error = assert_raises(Pdf::FileNotFoundError) do
+      @component.render("/nonexistent/logo.png")
+    end
+    assert_match(/Logo not found/, error.message)
+  end
+end
+
+# test/pdf/components/qr_code_test.rb
+# frozen_string_literal: true
+
+require "test_helper"
+
+class QrCodeComponentTest < Minitest::Test
+  def setup
+    @renderer = Pdf::Renderer.new.setup
+    @component = Pdf::Components::QrCode.new(@renderer.pdf)
+  end
+
+  def test_generates_qr_code_from_data
+    @component.render(data: "https://example.com")
+  end
+
+  def test_accepts_size_option
+    @component.render(data: "test", size: 100)
+  end
+end
+
+# test/pdf/components/spacer_test.rb
+# frozen_string_literal: true
+
+require "test_helper"
+
+class SpacerComponentTest < Minitest::Test
+  def setup
+    @renderer = Pdf::Renderer.new.setup
+    @component = Pdf::Components::Spacer.new(@renderer.pdf)
+  end
+
+  def test_moves_down_by_default_amount
+    @component.render
+    # Default is 20, but we just verify no error
+  end
+
+  def test_accepts_custom_amount
+    @component.render(amount: 50)
+  end
+end
+```