pdf 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 19e2ef9c0e0482e085bcdefd46dda508db90747f329907bceac9013519389b61
-  data.tar.gz: 763e676924914511fc86272f238b8b65700820005b968806ebccc080c6b492c2
+  metadata.gz: a65082843a9b93d0e95848671c5e58ba2921e838c168a76dd9cca4b14cd76044
+  data.tar.gz: a6dcf50015479680b09fc8a36039467fa188442781622e086ea12a0a43bbfb5d
 SHA512:
-  metadata.gz: 97298fcaa03b79cb466602cdb9fcfb48a0be7d42606a885219d36cb98a426df6e1461e5c504f44472f03504202e23f66f93588bb7cee55653f2114d92e81aae2
-  data.tar.gz: 405ff975805cb134173d87ed54492e34b371d1ba60d2b70e0140e713ce95c2cc2570f64275779d2ae432e1c4ce4db3f6bbff8c4d0616eb3013bf15856f3eadf0
+  metadata.gz: 306faa44b40d9be836752330a24198c7897892fc0b149e801fc08f72bfb91775f754c62e7a9e7b22cb28ea170389ffe6842e5153713b6d05181e10d915e3e344
+  data.tar.gz: dda4d0483b77b8a3ba2371e1bca8d4556d33ecaeb3c71a444b88869eb28ebfaab856ae99f9a993425b4edc6976fac425e978a5a4f885578b1d390b6ed2a8558d

data/.claude/execution/00-overview.md

@@ -0,0 +1,121 @@
+# PDF Gem - Execution Overview
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                      User Code                          │
+│   class MyReport < Pdf::View                            │
+│     title "Report"                                      │
+│     table :items                                        │
+│   end                                                   │
+└─────────────────────────────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────┐
+│                    Builders (DSL)                       │
+│   ContentBuilder, HeaderBuilder, FooterBuilder          │
+│   Translate DSL calls → Blueprint                       │
+│   (uses DynamicComponents mixin for extensibility)      │
+└─────────────────────────────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────┐
+│                      Blueprint                          │
+│   Stores element declarations as data                   │
+│   [{type: :title, args: ["Report"], options: {}}]       │
+└─────────────────────────────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────┐
+│                     Evaluators                          │
+│   ContentEvaluator, HeaderEvaluator, FooterEvaluator    │
+│   Resolve symbols, dispatch to components               │
+│   Handle conditionals (render_if), page numbers         │
+└─────────────────────────────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────┐
+│                     Components                          │
+│   Title, Paragraph, Table, Alert, Hr, Date, QrCode...   │
+│   Each component renders using primitives               │
+│   NEVER swallow errors - always raise                   │
+└─────────────────────────────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────┐
+│                 Renderer (Primitives)                   │
+│   text, box, line, image, table_data, raw               │
+│   Thin wrapper over Prawn                               │
+└─────────────────────────────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────┐
+│                       Prawn                             │
+│   PDF generation                                        │
+└─────────────────────────────────────────────────────────┘
+```
+
+## Design Principles
+
+1. **No silent failures** - All errors bubble up. Client code handles exceptions.
+2. **Proper inheritance** - Child views inherit parent blueprint via `dup`.
+3. **DRY** - Shared behavior extracted to modules (e.g., `DynamicComponents`).
+4. **Escape hatches** - `raw` block for direct Prawn access when needed.
+
+## Execution Phases
+
+| Phase | Focus | Files |
+|-------|-------|-------|
+| 01 | Core Infrastructure | blueprint.rb, resolver.rb, component.rb, dynamic_components.rb |
+| 02 | Renderer Primitives | renderer.rb |
+| 03 | Built-in Components | components/*.rb |
+| 04 | Builders (DSL) | builders/*.rb |
+| 05 | View & Layout | view.rb, layout.rb |
+| 06 | Evaluators | *_evaluator.rb |
+| 07 | Entry Point & Extensibility | pdf.rb, register_component |
+
+## Dependencies
+
+```ruby
+spec.add_dependency "prawn", "~> 2.4"
+spec.add_dependency "prawn-table", "~> 0.2"
+spec.add_dependency "rqrcode", "~> 2.0"      # QR code generation
+```
+
+## File Structure
+
+```
+lib/
+  pdf.rb
+  pdf/
+    version.rb
+    blueprint.rb
+    resolver.rb
+    component.rb
+    dynamic_components.rb
+    renderer.rb
+    view.rb
+    layout.rb
+    content_evaluator.rb
+    header_evaluator.rb
+    footer_evaluator.rb
+    builders/
+      content_builder.rb
+      header_builder.rb
+      footer_builder.rb
+    components/
+      title.rb
+      subtitle.rb
+      heading.rb
+      paragraph.rb
+      span.rb
+      date.rb
+      hr.rb
+      spacer.rb
+      alert.rb
+      table.rb
+      logo.rb
+      qr_code.rb
+      context.rb
+```

data/.claude/execution/01-core.md

@@ -0,0 +1,324 @@
+# Phase 1: Core Infrastructure
+
+## Files
+- `lib/pdf/blueprint.rb`
+- `lib/pdf/resolver.rb`
+- `lib/pdf/component.rb`
+- `lib/pdf/dynamic_components.rb`
+
+---
+
+## 1.1 Blueprint
+
+Storage for DSL declarations. Elements stored as data, evaluated later.
+
+```ruby
+# lib/pdf/blueprint.rb
+# frozen_string_literal: true
+
+module Pdf
+  class Blueprint
+    attr_reader :elements, :layout_class, :metadata
+
+    def initialize
+      @elements = []
+      @layout_class = nil
+      @metadata = {}
+    end
+
+    def add(type, *args, **options, &block)
+      element = { type: type, args: args, options: options }
+      element[:block] = block if block
+      @elements << element
+    end
+
+    def set_layout(klass)
+      @layout_class = klass
+    end
+
+    def set_metadata(key, value)
+      @metadata[key] = value
+    end
+
+    def empty?
+      @elements.empty? && @layout_class.nil? && @metadata.empty?
+    end
+
+    def dup
+      copy = Blueprint.new
+      copy.instance_variable_set(:@elements, deep_dup_elements)
+      copy.instance_variable_set(:@layout_class, @layout_class)
+      copy.instance_variable_set(:@metadata, @metadata.dup)
+      copy
+    end
+
+    private
+
+    def deep_dup_elements
+      @elements.map do |el|
+        duped = el.dup
+        duped[:args] = el[:args].dup
+        duped[:options] = el[:options].dup
+        duped
+      end
+    end
+  end
+end
+```
+
+---
+
+## 1.2 Resolver
+
+Resolves symbols to values at render time.
+
+Resolution order:
+1. Method on context → call it
+2. Key in `data` hash → return value
+3. Raise `ResolutionError`
+
+```ruby
+# lib/pdf/resolver.rb
+# frozen_string_literal: true
+
+module Pdf
+  class ResolutionError < StandardError; end
+
+  class Resolver
+    def initialize(context)
+      @context = context
+    end
+
+    def resolve(value)
+      case value
+      when Symbol then resolve_symbol(value)
+      when Proc then @context.instance_exec(&value)
+      when Array then value.map { |v| resolve(v) }
+      when Hash then value.transform_values { |v| resolve(v) }
+      else value
+      end
+    end
+
+    private
+
+    def resolve_symbol(sym)
+      if @context.respond_to?(sym, true)
+        return @context.send(sym)
+      end
+
+      if @context.respond_to?(:data) && @context.data.is_a?(Hash)
+        return @context.data[sym] if @context.data.key?(sym)
+        return @context.data[sym.to_s] if @context.data.key?(sym.to_s)
+      end
+
+      raise ResolutionError, "Cannot resolve :#{sym}"
+    end
+  end
+end
+```
+
+---
+
+## 1.3 Component Base
+
+Base class for all components. Components receive Prawn document and render using primitives.
+
+```ruby
+# lib/pdf/component.rb
+# frozen_string_literal: true
+
+module Pdf
+  class Component
+    attr_reader :pdf
+
+    def initialize(pdf)
+      @pdf = pdf
+    end
+
+    def render(...)
+      raise NotImplementedError, "#{self.class}#render not implemented"
+    end
+
+    private
+
+    # Primitive helpers (delegate to pdf)
+
+    def text(content, **options)
+      @pdf.text content.to_s, **options
+    end
+
+    def move_down(amount)
+      @pdf.move_down amount
+    end
+
+    def stroke_horizontal_rule
+      @pdf.stroke_horizontal_rule
+    end
+
+    def bounding_box(point, **options, &block)
+      @pdf.bounding_box(point, **options, &block)
+    end
+
+    def cursor
+      @pdf.cursor
+    end
+
+    def bounds
+      @pdf.bounds
+    end
+  end
+end
+```
+
+---
+
+## 1.4 DynamicComponents Module
+
+Shared mixin for dynamic component support. DRYs up method_missing across builders and views.
+
+```ruby
+# lib/pdf/dynamic_components.rb
+# frozen_string_literal: true
+
+module Pdf
+  module DynamicComponents
+    def method_missing(name, *args, **options, &block)
+      if Pdf.component_registered?(name)
+        @blueprint.add(name, *args, **options, &block)
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      Pdf.component_registered?(name) || super
+    end
+  end
+end
+```
+
+---
+
+## Tests
+
+```ruby
+# test/pdf/blueprint_test.rb
+# frozen_string_literal: true
+
+require "test_helper"
+
+class BlueprintTest < Minitest::Test
+  def setup
+    @blueprint = Pdf::Blueprint.new
+  end
+
+  def test_add_stores_element
+    @blueprint.add(:title, "Hello", size: 20)
+    element = @blueprint.elements.first
+    assert_equal :title, element[:type]
+    assert_equal ["Hello"], element[:args]
+    assert_equal({ size: 20 }, element[:options])
+  end
+
+  def test_add_stores_block
+    @blueprint.add(:section, "Items") { table :items }
+    assert_kind_of Proc, @blueprint.elements.first[:block]
+  end
+
+  def test_dup_creates_independent_copy
+    @blueprint.add(:title, "Original")
+    copy = @blueprint.dup
+    copy.add(:title, "Copy")
+    assert_equal 1, @blueprint.elements.size
+  end
+
+  def test_empty_returns_true_for_new_blueprint
+    assert @blueprint.empty?
+  end
+
+  def test_empty_returns_false_after_adding_element
+    @blueprint.add(:title, "Hello")
+    refute @blueprint.empty?
+  end
+end
+
+# test/pdf/resolver_test.rb
+# frozen_string_literal: true
+
+require "test_helper"
+
+class ResolverTest < Minitest::Test
+  def setup
+    context_class = Class.new do
+      attr_reader :data
+      def initialize(data) = @data = data
+      def computed = "computed:#{data[:raw]}"
+    end
+    @context = context_class.new({ raw: "value", key: "data_value" })
+    @resolver = Pdf::Resolver.new(@context)
+  end
+
+  def test_returns_strings_as_is
+    assert_equal "hello", @resolver.resolve("hello")
+  end
+
+  def test_resolves_method
+    assert_equal "computed:value", @resolver.resolve(:computed)
+  end
+
+  def test_resolves_data_key
+    assert_equal "data_value", @resolver.resolve(:key)
+  end
+
+  def test_raises_on_unknown
+    assert_raises(Pdf::ResolutionError) { @resolver.resolve(:unknown) }
+  end
+end
+
+# test/pdf/component_test.rb
+# frozen_string_literal: true
+
+require "test_helper"
+
+class ComponentTest < Minitest::Test
+  def test_requires_render_implementation
+    pdf = Object.new
+    component = Pdf::Component.new(pdf)
+    assert_raises(NotImplementedError) { component.render }
+  end
+end
+
+# test/pdf/dynamic_components_test.rb
+# frozen_string_literal: true
+
+require "test_helper"
+
+class DynamicComponentsTest < Minitest::Test
+  def setup
+    @builder_class = Class.new do
+      include Pdf::DynamicComponents
+      attr_reader :blueprint
+
+      def initialize
+        @blueprint = Pdf::Blueprint.new
+      end
+    end
+    Pdf.register_component(:badge, Class.new(Pdf::Component))
+  end
+
+  def teardown
+    Pdf.instance_variable_get(:@components).delete(:badge)
+  end
+
+  def test_handles_registered_components
+    builder = @builder_class.new
+    builder.badge("NEW", color: "red")
+    assert_equal :badge, builder.blueprint.elements.first[:type]
+  end
+
+  def test_raises_for_unknown_methods
+    builder = @builder_class.new
+    assert_raises(NoMethodError) { builder.unknown_thing }
+  end
+end
+```

data/.claude/execution/02-renderer.md

@@ -0,0 +1,237 @@
+# Phase 2: Renderer (Primitives)
+
+## Files
+- `lib/pdf/renderer.rb`
+
+---
+
+## Renderer
+
+Thin wrapper over Prawn. Provides primitives that components use.
+
+**Key principles:**
+- Never swallow errors - let them bubble up
+- Consistent default margins (shared constant)
+- `raw` escape hatch for direct Prawn access
+
+```ruby
+# lib/pdf/renderer.rb
+# frozen_string_literal: true
+
+require "prawn"
+require "prawn/table"
+
+module Pdf
+  # Default margins used by both Renderer and Layout
+  DEFAULT_MARGINS = { top: 72, right: 36, bottom: 72, left: 36 }.freeze
+
+  class Renderer
+    attr_reader :pdf
+
+    def initialize
+      @pdf = nil
+      @footer_callback = nil
+    end
+
+    def setup(margins: {})
+      m = Pdf::DEFAULT_MARGINS.merge(margins)
+      @pdf = Prawn::Document.new(
+        margin: [m[:top], m[:right], m[:bottom], m[:left]]
+      )
+      setup_fonts
+      self
+    end
+
+    def finalize
+      apply_footer if @footer_callback
+      @pdf.render
+    end
+
+    # --- Primitives ---
+
+    def text(content, **options)
+      @pdf.text content.to_s, **options
+    end
+
+    def text_box(content, at:, **options)
+      @pdf.text_box content.to_s, at: at, **options
+    end
+
+    def move_down(amount)
+      @pdf.move_down amount
+    end
+
+    def stroke_horizontal_rule
+      @pdf.stroke_horizontal_rule
+    end
+
+    def start_new_page
+      @pdf.start_new_page
+    end
+
+    def cursor
+      @pdf.cursor
+    end
+
+    def bounds
+      @pdf.bounds
+    end
+
+    def bounding_box(point, **options, &block)
+      @pdf.bounding_box(point, **options, &block)
+    end
+
+    def canvas(&block)
+      @pdf.canvas(&block)
+    end
+
+    def float(&block)
+      @pdf.float(&block)
+    end
+
+    # Image embedding - raises if file not found (no silent failures)
+    def image(path, **options)
+      raise Pdf::FileNotFoundError, "Image not found: #{path}" unless File.exist?(path)
+
+      @pdf.image path, **options
+    end
+
+    # Image from string data (for generated images like QR codes)
+    def image_data(data, **options)
+      @pdf.image StringIO.new(data), **options
+    end
+
+    def fill_color(color)
+      @pdf.fill_color color
+    end
+
+    def stroke_color(color)
+      @pdf.stroke_color color
+    end
+
+    def line_width(width)
+      @pdf.line_width width
+    end
+
+    def fill_and_stroke_rounded_rectangle(point, width, height, radius)
+      @pdf.fill_and_stroke_rounded_rectangle point, width, height, radius
+    end
+
+    def draw_text(content, at:, **options)
+      @pdf.draw_text content.to_s, at: at, **options
+    end
+
+    def width_of(content, **options)
+      @pdf.width_of content.to_s, **options
+    end
+
+    def height_of(content, **options)
+      @pdf.height_of content.to_s, **options
+    end
+
+    def table(data, **options, &block)
+      @pdf.table(data, **options, &block)
+    end
+
+    def page_number
+      @pdf.page_number
+    end
+
+    def page_count
+      @pdf.page_count
+    end
+
+    def repeat(page_filter, options = {}, &block)
+      @pdf.repeat(page_filter, options, &block)
+    end
+
+    # --- Escape hatch for direct Prawn access ---
+
+    def raw(&block)
+      yield @pdf
+    end
+
+    # --- Footer setup (deferred) ---
+
+    def setup_footer(&block)
+      @footer_callback = block
+    end
+
+    private
+
+    def setup_fonts
+      # Use Helvetica by default (built into Prawn)
+      # Users can override in their app
+    end
+
+    def apply_footer
+      @footer_callback&.call(@pdf)
+    end
+  end
+end
+```
+
+---
+
+## Tests
+
+```ruby
+# test/pdf/renderer_test.rb
+# frozen_string_literal: true
+
+require "test_helper"
+
+class RendererTest < Minitest::Test
+  def setup
+    @renderer = Pdf::Renderer.new.setup
+  end
+
+  def test_setup_creates_prawn_document
+    assert_kind_of Prawn::Document, @renderer.pdf
+  end
+
+  def test_setup_accepts_custom_margins
+    r = Pdf::Renderer.new.setup(margins: { top: 100 })
+    assert_kind_of Prawn::Document, r.pdf
+  end
+
+  def test_uses_default_margins
+    expected = { top: 72, right: 36, bottom: 72, left: 36 }
+    assert_equal expected, Pdf::DEFAULT_MARGINS
+  end
+
+  def test_finalize_returns_pdf_binary
+    result = @renderer.finalize
+    assert result.start_with?("%PDF")
+  end
+
+  def test_text_delegates_to_prawn
+    # Just verify it doesn't raise
+    @renderer.text("Hello", size: 12)
+  end
+
+  def test_image_raises_file_not_found_error
+    error = assert_raises(Pdf::FileNotFoundError) do
+      @renderer.image("/nonexistent/path.png")
+    end
+    assert_match(/Image not found/, error.message)
+  end
+
+  def test_raw_yields_prawn_document
+    yielded = nil
+    @renderer.raw { |pdf| yielded = pdf }
+    assert_equal @renderer.pdf, yielded
+  end
+
+  def test_raw_allows_direct_prawn_operations
+    @renderer.raw { |pdf| pdf.stroke_circle [100, 100], 50 }
+  end
+
+  def test_setup_footer_stores_callback_for_finalize
+    called = false
+    @renderer.setup_footer { |_pdf| called = true }
+    @renderer.finalize
+    assert called
+  end
+end
+```