pdf 0.1.0 → 0.1.1

data/.claude/execution/07-entry-extensibility.md

@@ -0,0 +1,435 @@
+# Phase 7: Entry Point & Extensibility
+
+## Files
+- `lib/pdf.rb`
+
+---
+
+## Entry Point
+
+Main entry point. Requires all files, provides component registry and error classes.
+
+**Changes:**
+- Added `FileNotFoundError` for explicit file errors
+- Removed `PageNumber` component (handled by FooterEvaluator)
+- Added `Date` and `Spacer` components
+- Added `DynamicComponents` module
+- Added `rqrcode` require
+
+```ruby
+# lib/pdf.rb
+# frozen_string_literal: true
+
+require "prawn"
+require "prawn/table"
+require "rqrcode"
+
+require_relative "pdf/version"
+require_relative "pdf/blueprint"
+require_relative "pdf/resolver"
+require_relative "pdf/component"
+require_relative "pdf/dynamic_components"
+require_relative "pdf/renderer"
+
+require_relative "pdf/builders/content_builder"
+require_relative "pdf/builders/header_builder"
+require_relative "pdf/builders/footer_builder"
+
+require_relative "pdf/components/title"
+require_relative "pdf/components/subtitle"
+require_relative "pdf/components/heading"
+require_relative "pdf/components/paragraph"
+require_relative "pdf/components/span"
+require_relative "pdf/components/date"
+require_relative "pdf/components/hr"
+require_relative "pdf/components/spacer"
+require_relative "pdf/components/alert"
+require_relative "pdf/components/table"
+require_relative "pdf/components/logo"
+require_relative "pdf/components/qr_code"
+require_relative "pdf/components/context"
+
+require_relative "pdf/content_evaluator"
+require_relative "pdf/header_evaluator"
+require_relative "pdf/footer_evaluator"
+
+require_relative "pdf/view"
+require_relative "pdf/layout"
+
+module Pdf
+  class Error < StandardError; end
+  class FileNotFoundError < Error; end
+
+  # Component registry (PageNumber is handled by FooterEvaluator, not here)
+  @components = {
+    title: Components::Title,
+    subtitle: Components::Subtitle,
+    heading: Components::Heading,
+    paragraph: Components::Paragraph,
+    span: Components::Span,
+    date: Components::Date,
+    hr: Components::Hr,
+    spacer: Components::Spacer,
+    alert: Components::Alert,
+    table: Components::Table,
+    logo: Components::Logo,
+    qr_code: Components::QrCode,
+    context: Components::Context
+  }
+
+  class << self
+    # Register a custom component
+    #
+    # @param name [Symbol] Component name for DSL
+    # @param klass [Class] Component class (must inherit from Pdf::Component)
+    #
+    # @example
+    #   class MyBadge < Pdf::Component
+    #     def render(text, color: "blue")
+    #       # ...
+    #     end
+    #   end
+    #
+    #   Pdf.register_component(:badge, MyBadge)
+    #
+    #   class MyReport < Pdf::View
+    #     badge "NEW", color: "red"
+    #   end
+    #
+    def register_component(name, klass)
+      unless klass < Component
+        raise ArgumentError, "#{klass} must inherit from Pdf::Component"
+      end
+
+      @components[name.to_sym] = klass
+    end
+
+    # Check if component is registered
+    #
+    # @param name [Symbol] Component name
+    # @return [Boolean]
+    #
+    def component_registered?(name)
+      @components.key?(name.to_sym)
+    end
+
+    # Get component class
+    #
+    # @param name [Symbol] Component name
+    # @return [Class]
+    # @raise [Error] if not found
+    #
+    def component(name)
+      @components.fetch(name.to_sym) do
+        raise Error, "Unknown component: #{name}"
+      end
+    end
+
+    # List registered components
+    #
+    # @return [Array<Symbol>]
+    #
+    def components
+      @components.keys
+    end
+  end
+end
+```
+
+---
+
+## Usage Examples
+
+### Basic View
+
+```ruby
+class InvoiceReport < Pdf::View
+  title "INVOICE"
+  date :invoice_date  # Uses real Date component now
+
+  paragraph :description
+
+  # Conditional rendering
+  render_if(:has_discount) do
+    alert :discount_info
+  end
+
+  section "Items" do
+    table :line_items, columns: [:name, :qty, :price]
+  end
+
+  section "Summary" do
+    paragraph :total_line
+  end
+
+  def invoice_date
+    data[:date]  # Date component handles formatting
+  end
+
+  def description
+    "Invoice for #{data[:customer_name]}"
+  end
+
+  def has_discount
+    data[:discount].present?
+  end
+
+  def discount_info
+    { title: "Discount Applied!", description: data[:discount], color: "green" }
+  end
+
+  def line_items
+    data[:items]
+  end
+
+  def total_line
+    "Total: $#{data[:total]}"
+  end
+end
+
+# Generate
+pdf = InvoiceReport.new(
+  date: Date.current,
+  customer_name: "Acme Corp",
+  items: [
+    { name: "Widget", qty: 5, price: "$10.00" },
+    { name: "Gadget", qty: 2, price: "$25.00" }
+  ],
+  total: "100.00"
+).to_pdf
+
+File.binwrite("invoice.pdf", pdf)
+```
+
+### With Layout
+
+```ruby
+class CompanyLayout < Pdf::Layout
+  header do
+    logo "logo.png", width: 100
+    qr_code data: :qr_url, size: 60, position: :right  # Generates QR from data
+    context :header_lines
+  end
+
+  footer do
+    text :company_name, size: 8
+    page_number position: :right
+  end
+
+  margins top: 80, bottom: 60
+end
+
+class Report < Pdf::View
+  layout CompanyLayout
+
+  title :report_title
+  alert :summary
+
+  # Raw Prawn access when needed
+  raw do |pdf|
+    pdf.stroke_color "CCCCCC"
+    pdf.dash(2)
+    pdf.stroke_horizontal_line 0, pdf.bounds.width
+    pdf.undash
+  end
+
+  def report_title = data[:title]
+  def summary = data[:summary]
+  def header_lines = ["Company: #{data[:company]}", "Date: #{Date.current}"]
+  def company_name = data[:company]
+  def qr_url = "https://example.com/reports/#{data[:id]}"
+end
+```
+
+### View Inheritance
+
+Child views inherit parent's elements and can add more.
+
+```ruby
+class BaseReport < Pdf::View
+  title "Company Report"
+  hr
+  spacer amount: 10
+end
+
+class SalesReport < BaseReport
+  # Inherits: title "Company Report", hr, spacer
+  subtitle "Sales Department"
+  table :sales_data, columns: [:product, :revenue]
+
+  def sales_data = data[:sales]
+end
+
+class FinanceReport < BaseReport
+  # Inherits: title "Company Report", hr, spacer
+  subtitle "Finance Department"
+  render_unless(:is_draft) { table :budget_data, columns: [:category, :amount] }
+
+  def budget_data = data[:budget]
+  def is_draft = data[:draft]
+end
+```
+
+### Custom Component
+
+```ruby
+class Badge < Pdf::Component
+  COLORS = {
+    "success" => "4CAF50",
+    "warning" => "FF9800",
+    "error" => "F44336"
+  }.freeze
+
+  def render(text, type: "success", **_options)
+    color = COLORS[type.to_s] || COLORS["success"]
+
+    bounding_box([0, cursor], width: 60, height: 20) do
+      @pdf.fill_color color
+      @pdf.fill_rounded_rectangle [0, 20], 60, 20, 4
+      @pdf.fill_color "FFFFFF"
+      @pdf.text_box text.to_s, at: [5, 16], width: 50, size: 10, align: :center
+    end
+
+    @pdf.fill_color "000000"
+    move_down 25
+  end
+end
+
+Pdf.register_component(:badge, Badge)
+
+class StatusReport < Pdf::View
+  title "Status Report"
+  badge "LIVE", type: "success"
+  paragraph "All systems operational."
+end
+```
+
+---
+
+## Specs
+
+```ruby
+# spec/pdf_spec.rb
+RSpec.describe Pdf do
+  describe ".register_component" do
+    let(:custom_component) do
+      Class.new(Pdf::Component) do
+        def render(text) = @pdf.text(text)
+      end
+    end
+
+    after { described_class.instance_variable_get(:@components).delete(:custom) }
+
+    it "registers component" do
+      described_class.register_component(:custom, custom_component)
+      expect(described_class.component_registered?(:custom)).to be true
+    end
+
+    it "rejects non-Component classes" do
+      expect {
+        described_class.register_component(:bad, String)
+      }.to raise_error(ArgumentError)
+    end
+  end
+
+  describe ".component" do
+    it "returns built-in components" do
+      expect(described_class.component(:title)).to eq(Pdf::Components::Title)
+    end
+
+    it "returns date component" do
+      expect(described_class.component(:date)).to eq(Pdf::Components::Date)
+    end
+
+    it "returns spacer component" do
+      expect(described_class.component(:spacer)).to eq(Pdf::Components::Spacer)
+    end
+
+    it "raises for unknown" do
+      expect { described_class.component(:unknown) }.to raise_error(Pdf::Error)
+    end
+  end
+
+  describe ".components" do
+    it "lists all registered" do
+      expect(described_class.components).to include(:title, :table, :alert, :date, :spacer)
+    end
+
+    it "does not include page_number (handled by evaluator)" do
+      expect(described_class.components).not_to include(:page_number)
+    end
+  end
+
+  describe "Pdf::FileNotFoundError" do
+    it "is a subclass of Pdf::Error" do
+      expect(Pdf::FileNotFoundError.superclass).to eq(Pdf::Error)
+    end
+  end
+end
+
+# spec/integration_spec.rb
+RSpec.describe "Integration" do
+  let(:layout_class) do
+    Class.new(Pdf::Layout) do
+      header do
+        context :header_lines
+      end
+
+      footer do
+        text :footer_text
+        page_number
+      end
+
+      margins top: 70, bottom: 60
+    end
+  end
+
+  let(:view_class) do
+    lc = layout_class
+    Class.new(Pdf::View) do
+      layout lc
+
+      title "TEST REPORT"
+      date :report_date
+      alert :status
+
+      render_if(:show_details) do
+        section "Data" do
+          table :items, columns: [:name, :value]
+        end
+      end
+
+      def report_date = Date.new(2024, 1, 15)
+      def status = { title: "OK", color: "green" }
+      def show_details = data[:show]
+      def items = data[:items]
+      def header_lines = ["Test Header"]
+      def footer_text = "Confidential"
+    end
+  end
+
+  it "generates valid PDF" do
+    pdf = view_class.new(items: [{ name: "A", value: "1" }], show: true).to_pdf
+    expect(pdf).to start_with("%PDF")
+  end
+
+  it "writes to file" do
+    path = "tmp/test.pdf"
+    view_class.new(items: [], show: false).to_file(path)
+    expect(File.exist?(path)).to be true
+  ensure
+    FileUtils.rm_f(path)
+  end
+
+  describe "view inheritance" do
+    let(:parent) { Class.new(Pdf::View) { title "Parent" } }
+    let(:child) { Class.new(parent) { subtitle "Child" } }
+
+    it "child generates PDF with both elements" do
+      pdf = child.new.to_pdf
+      expect(pdf).to start_with("%PDF")
+      expect(pdf).to include("Parent")
+    end
+  end
+end
+```