pdf 0.1.0 → 0.1.1

data/examples/05_custom_components.rb

@@ -0,0 +1,442 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example 05: Custom Components
+# Run: ruby examples/05_custom_components.rb
+#
+# Demonstrates:
+# - Creating custom components
+# - Registering components with Pdf.register_component
+# - Using custom components in DSL
+# - Complex component rendering with Prawn primitives
+# - Components with multiple render styles
+# - Building a component library
+
+require_relative "../lib/pdf"
+
+# =============================================================================
+# CUSTOM COMPONENTS
+# =============================================================================
+
+# --- Badge Component ---
+# Renders a colored badge/pill with text
+
+class Badge < Pdf::Component
+  STYLES = {
+    "success" => { bg: "4CAF50", text: "FFFFFF" },
+    "warning" => { bg: "FF9800", text: "000000" },
+    "danger" => { bg: "F44336", text: "FFFFFF" },
+    "info" => { bg: "2196F3", text: "FFFFFF" },
+    "default" => { bg: "9E9E9E", text: "FFFFFF" }
+  }.freeze
+
+  def render(label, style: "default", **_options)
+    colors = STYLES[style.to_s] || STYLES["default"]
+    width = @pdf.width_of(label, size: 9) + 16
+    height = 18
+
+    @pdf.bounding_box([0, cursor], width: width, height: height) do
+      @pdf.fill_color colors[:bg]
+      @pdf.fill_rounded_rectangle [0, height], width, height, 4
+
+      @pdf.fill_color colors[:text]
+      @pdf.text_box label.to_s.upcase,
+                    at: [8, height - 4],
+                    width: width - 16,
+                    height: height - 4,
+                    size: 9,
+                    style: :bold,
+                    valign: :center
+    end
+
+    @pdf.fill_color "000000"
+    move_down height + 5
+  end
+end
+
+# --- Progress Bar Component ---
+# Renders a progress bar with percentage
+
+class ProgressBar < Pdf::Component
+  COLORS = {
+    "green" => "4CAF50",
+    "blue" => "2196F3",
+    "orange" => "FF9800",
+    "red" => "F44336"
+  }.freeze
+
+  def render(percent, label: nil, color: "blue", width: nil, **_options)
+    bar_width = width || bounds.width
+    bar_height = 20
+    percent = [[percent.to_f, 0].max, 100].min # Clamp 0-100
+
+    # Label
+    if label
+      @pdf.text label, size: 10, style: :bold
+      move_down 5
+    end
+
+    @pdf.bounding_box([0, cursor], width: bar_width, height: bar_height) do
+      # Background
+      @pdf.fill_color "E0E0E0"
+      @pdf.fill_rounded_rectangle [0, bar_height], bar_width, bar_height, 4
+
+      # Progress fill
+      if percent > 0
+        fill_width = (bar_width * percent / 100.0).round
+        @pdf.fill_color COLORS[color.to_s] || COLORS["blue"]
+        @pdf.fill_rounded_rectangle [0, bar_height], fill_width, bar_height, 4
+      end
+
+      # Percentage text
+      @pdf.fill_color "333333"
+      @pdf.text_box "#{percent.round}%",
+                    at: [0, bar_height - 3],
+                    width: bar_width,
+                    height: bar_height,
+                    size: 10,
+                    style: :bold,
+                    align: :center
+    end
+
+    @pdf.fill_color "000000"
+    move_down bar_height + 10
+  end
+end
+
+# --- Stat Card Component ---
+# Renders a highlighted statistic with label and optional delta
+
+class StatCard < Pdf::Component
+  def render(value:, label:, delta: nil, delta_color: nil, **_options)
+    card_width = 150
+    card_height = 70
+
+    @pdf.bounding_box([0, cursor], width: card_width, height: card_height) do
+      # Card background
+      @pdf.fill_color "F5F5F5"
+      @pdf.stroke_color "E0E0E0"
+      @pdf.line_width 1
+      @pdf.fill_and_stroke_rounded_rectangle [0, card_height], card_width, card_height, 6
+
+      # Value (large)
+      @pdf.fill_color "333333"
+      @pdf.text_box value.to_s,
+                    at: [10, card_height - 10],
+                    width: card_width - 20,
+                    size: 22,
+                    style: :bold
+
+      # Label
+      @pdf.fill_color "666666"
+      @pdf.text_box label.to_s,
+                    at: [10, card_height - 38],
+                    width: card_width - 20,
+                    size: 10
+
+      # Delta (if provided)
+      if delta
+        color = delta_color || (delta.to_s.start_with?("+") ? "4CAF50" : delta.to_s.start_with?("-") ? "F44336" : "666666")
+        @pdf.fill_color color
+        @pdf.text_box delta.to_s,
+                      at: [10, card_height - 52],
+                      width: card_width - 20,
+                      size: 9
+      end
+    end
+
+    @pdf.fill_color "000000"
+    @pdf.stroke_color "000000"
+    move_down card_height + 10
+  end
+end
+
+# --- Divider Component ---
+# Renders a styled divider line
+
+class Divider < Pdf::Component
+  STYLES = {
+    "solid" => [],
+    "dashed" => [4, 2],
+    "dotted" => [1, 2]
+  }.freeze
+
+  def render(style: "solid", color: "CCCCCC", thickness: 1, spacing: 15, **_options)
+    move_down spacing / 2
+
+    @pdf.stroke_color color
+    @pdf.line_width thickness
+    dash_pattern = STYLES[style.to_s]
+    @pdf.dash(dash_pattern) unless dash_pattern.nil? || dash_pattern.empty?
+    @pdf.stroke_horizontal_line 0, bounds.width
+    @pdf.undash
+
+    @pdf.stroke_color "000000"
+    @pdf.line_width 1
+    move_down spacing / 2
+  end
+end
+
+# --- Callout Component ---
+# Renders a callout box with icon indicator
+
+class Callout < Pdf::Component
+  TYPES = {
+    "tip" => { bg: "E8F5E9", border: "4CAF50", icon: "TIP" },
+    "note" => { bg: "E3F2FD", border: "2196F3", icon: "NOTE" },
+    "warning" => { bg: "FFF3E0", border: "FF9800", icon: "WARN" },
+    "danger" => { bg: "FFEBEE", border: "F44336", icon: "ALERT" }
+  }.freeze
+
+  def render(text, type: "note", **_options)
+    config = TYPES[type.to_s] || TYPES["note"]
+    padding = 12
+    icon_width = 50
+
+    text_height = @pdf.height_of(text.to_s, width: bounds.width - icon_width - padding * 3, size: 10)
+    box_height = [text_height + padding * 2, 50].max
+
+    @pdf.bounding_box([0, cursor], width: bounds.width, height: box_height) do
+      # Background
+      @pdf.fill_color config[:bg]
+      @pdf.stroke_color config[:border]
+      @pdf.line_width 2
+      @pdf.fill_and_stroke_rounded_rectangle [0, box_height], bounds.width, box_height, 6
+
+      # Icon area
+      @pdf.fill_color config[:border]
+      @pdf.text_box config[:icon],
+                    at: [padding, box_height - padding],
+                    width: icon_width - padding,
+                    size: 10,
+                    style: :bold
+
+      # Text
+      @pdf.fill_color "333333"
+      @pdf.text_box text.to_s,
+                    at: [icon_width, box_height - padding],
+                    width: bounds.width - icon_width - padding * 2,
+                    size: 10,
+                    leading: 3
+    end
+
+    @pdf.fill_color "000000"
+    @pdf.stroke_color "000000"
+    @pdf.line_width 1
+    move_down box_height + 10
+  end
+end
+
+# --- Two Column Layout Component ---
+# Renders content in two columns
+
+class TwoColumn < Pdf::Component
+  def render(left:, right:, ratio: 0.5, gap: 20, **_options)
+    left_width = (bounds.width * ratio) - (gap / 2)
+    right_width = bounds.width - left_width - gap
+
+    # Calculate heights
+    left_height = calculate_content_height(left, left_width)
+    right_height = calculate_content_height(right, right_width)
+    row_height = [left_height, right_height].max
+
+    start_cursor = cursor
+
+    # Left column
+    @pdf.bounding_box([0, start_cursor], width: left_width, height: row_height) do
+      render_content(left)
+    end
+
+    # Right column
+    @pdf.bounding_box([left_width + gap, start_cursor], width: right_width, height: row_height) do
+      render_content(right)
+    end
+
+    # Move cursor below both columns
+    @pdf.move_cursor_to(start_cursor - row_height)
+    move_down 10
+  end
+
+  private
+
+  def calculate_content_height(content, width)
+    case content
+    when String
+      @pdf.height_of(content, width: width, size: 10) + 10
+    when Hash
+      60 # Approximate for stat cards, etc.
+    else
+      50
+    end
+  end
+
+  def render_content(content)
+    case content
+    when String
+      @pdf.text content, size: 10, leading: 3
+    when Hash
+      if content[:stat]
+        @pdf.text content[:stat][:value].to_s, size: 20, style: :bold
+        @pdf.text content[:stat][:label].to_s, size: 10, color: "666666"
+      else
+        @pdf.text content.to_s, size: 10
+      end
+    end
+  end
+end
+
+# =============================================================================
+# REGISTER ALL CUSTOM COMPONENTS
+# =============================================================================
+
+Pdf.register_component(:badge, Badge)
+Pdf.register_component(:progress_bar, ProgressBar)
+Pdf.register_component(:stat_card, StatCard)
+Pdf.register_component(:divider, Divider)
+Pdf.register_component(:callout, Callout)
+Pdf.register_component(:two_column, TwoColumn)
+
+# =============================================================================
+# DASHBOARD VIEW USING CUSTOM COMPONENTS
+# =============================================================================
+
+class Dashboard < Pdf::View
+  title "Project Dashboard", size: 24
+  subtitle :project_name
+  date :report_date
+
+  divider style: "solid", color: "333333", thickness: 2
+
+  # Status badges row
+  heading "Project Status", size: 14
+  badge :status_badge, style: :status_style
+  spacer amount: 5
+
+  # Key metrics with stat cards
+  heading "Key Metrics", size: 14
+  spacer amount: 5
+
+  each(:metrics) do |metric|
+    stat_card value: metric[:value], label: metric[:label], delta: metric[:delta], delta_color: metric[:color]
+  end
+
+  divider style: "dashed"
+
+  # Progress section
+  heading "Sprint Progress", size: 14
+
+  each(:progress_items) do |item|
+    progress_bar item[:percent], label: item[:label], color: item[:color]
+  end
+
+  divider style: "dotted"
+
+  # Callouts
+  heading "Notes & Alerts", size: 14
+
+  each(:callouts) do |callout|
+    callout callout[:text], type: callout[:type]
+  end
+
+  divider
+
+  # Summary in two columns
+  heading "Quick Summary", size: 14
+
+  two_column left: :summary_left, right: :summary_right, ratio: 0.6
+
+  spacer amount: 20
+  span "Dashboard generated automatically. Data refreshed hourly.", size: 8, color: "888888"
+
+  # --- Data Methods ---
+
+  def project_name
+    "#{data[:project]} - Sprint #{data[:sprint]}"
+  end
+
+  def report_date
+    Time.now
+  end
+
+  def status_badge
+    data[:status]
+  end
+
+  def status_style
+    { "On Track" => "success", "At Risk" => "warning", "Behind" => "danger", "Completed" => "info" }[data[:status]] || "default"
+  end
+
+  def metrics
+    data[:metrics] || []
+  end
+
+  def progress_items
+    data[:progress] || []
+  end
+
+  def callouts
+    data[:callouts] || []
+  end
+
+  def summary_left
+    <<~TEXT
+      Team velocity has increased by 15% this sprint.
+      All critical path items are on track for delivery.
+      Two blockers were resolved this week.
+    TEXT
+  end
+
+  def summary_right
+    <<~TEXT
+      Next milestone: #{data[:next_milestone]}
+      Days remaining: #{data[:days_remaining]}
+      Team capacity: #{data[:capacity]}%
+    TEXT
+  end
+end
+
+# =============================================================================
+# GENERATE THE DASHBOARD
+# =============================================================================
+
+dashboard_data = {
+  project: "Phoenix Platform",
+  sprint: 14,
+  status: "On Track",
+
+  metrics: [
+    { value: "87%", label: "Sprint Completion", delta: "+12%", color: "4CAF50" },
+    { value: "23", label: "Stories Completed", delta: "+5", color: "4CAF50" },
+    { value: "4", label: "Open Blockers", delta: "-2", color: "4CAF50" },
+    { value: "98.5%", label: "Code Coverage", delta: "+0.3%", color: "4CAF50" }
+  ],
+
+  progress: [
+    { label: "Backend API", percent: 95, color: "green" },
+    { label: "Frontend UI", percent: 78, color: "blue" },
+    { label: "Testing", percent: 65, color: "orange" },
+    { label: "Documentation", percent: 45, color: "orange" },
+    { label: "Deployment", percent: 20, color: "blue" }
+  ],
+
+  callouts: [
+    { type: "tip", text: "Consider pairing on the documentation tasks to accelerate completion." },
+    { type: "note", text: "Sprint review scheduled for Friday at 2pm. Demo environment ready." },
+    { type: "warning", text: "Frontend performance tests showing 200ms regression on dashboard load." },
+    { type: "danger", text: "Security audit findings require immediate attention - 2 critical items." }
+  ],
+
+  next_milestone: "Beta Release",
+  days_remaining: 12,
+  capacity: 85
+}
+
+# Generate and open
+output_path = "/tmp/dashboard_custom_components.pdf"
+Dashboard.new(dashboard_data).to_file(output_path)
+
+puts "Generated: #{output_path}"
+puts "\nRegistered custom components:"
+puts Pdf.components.select { |c| %i[badge progress_bar stat_card divider callout two_column].include?(c) }.map { |c| "  - #{c}" }.join("\n")
+
+system("open", output_path)

data/examples/README.md

@@ -0,0 +1,123 @@
+# PDF Gem Examples
+
+Runnable examples demonstrating the PDF gem features.
+
+## Prerequisites
+
+```bash
+cd /path/to/pdf
+bundle install
+```
+
+## Running Examples
+
+Each example generates a PDF and opens it automatically:
+
+```bash
+ruby examples/01_basic_invoice.rb
+ruby examples/02_report_with_layout.rb
+ruby examples/03_inherited_views.rb
+ruby examples/04_conditional_content.rb
+ruby examples/05_custom_components.rb
+```
+
+## Example Overview
+
+### 01. Basic Invoice
+**File:** `01_basic_invoice.rb`
+
+Demonstrates:
+- Basic view structure
+- Title, subtitle, date components
+- Table with custom columns and widths
+- Sections with nested content
+- Data binding via symbols
+- Computed values from methods
+- Currency formatting
+
+**Output:** `/tmp/invoice_example.pdf`
+
+---
+
+### 02. Report with Layout
+**File:** `02_report_with_layout.rb`
+
+Demonstrates:
+- Custom layout with header and footer
+- QR code generation from dynamic data
+- Context lines in header
+- Page numbers in footer
+- Multi-section complex report
+- Alerts with different colors
+- Raw Prawn access for custom bar chart
+- Page breaks
+- Tables with data transformation
+
+**Output:** `/tmp/quarterly_report_example.pdf`
+
+---
+
+### 03. Inherited Views
+**File:** `03_inherited_views.rb`
+
+Demonstrates:
+- Base view with shared elements
+- Multi-level inheritance (3 levels deep)
+- Child views extending parents
+- Layout inheritance
+- Method overriding
+- Generating multiple report types from same base
+
+**Output:**
+- `/tmp/sales_report_inherited.pdf`
+- `/tmp/hr_report_inherited.pdf`
+- `/tmp/finance_report_inherited.pdf`
+
+---
+
+### 04. Conditional Content
+**File:** `04_conditional_content.rb`
+
+Demonstrates:
+- `render_if` for conditional sections
+- `render_unless` for inverse conditions
+- Complex boolean logic in conditions
+- Nested conditionals
+- Same view class producing different outputs
+- Dynamic alerts based on state
+
+**Output:**
+- `/tmp/order_digital.pdf` (digital-only order)
+- `/tmp/order_gift.pdf` (gift order with extras)
+- `/tmp/order_mixed.pdf` (physical + digital)
+- `/tmp/order_on_hold.pdf` (warning state)
+
+---
+
+### 05. Custom Components
+**File:** `05_custom_components.rb`
+
+Demonstrates:
+- Creating custom components extending `Pdf::Component`
+- Registering with `Pdf.register_component`
+- Using custom components in DSL
+- Complex rendering with Prawn primitives
+
+**Custom Components Created:**
+- `Badge` - Colored status badges
+- `ProgressBar` - Progress indicators
+- `StatCard` - Metric display cards
+- `Divider` - Styled line dividers
+- `Callout` - Tip/note/warning boxes
+- `TwoColumn` - Two-column layout
+
+**Output:** `/tmp/dashboard_custom_components.pdf`
+
+---
+
+## Notes
+
+- All examples output to `/tmp/` directory
+- Examples use `system("open", path)` to open PDFs (macOS)
+- For Linux, replace with `system("xdg-open", path)`
+- For Windows, replace with `system("start", path)`

data/lib/pdf/blueprint.rb

@@ -0,0 +1,50 @@
+# 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

data/lib/pdf/builders/content_builder.rb

@@ -0,0 +1,96 @@
+# 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 = nil, **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