acro_that 0.1.3 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 56f6be44d023bdedaf254cc097d18791f284793d0c79c07847fd462c0643cc91
-  data.tar.gz: b649d290433fac6a6113a74ca47bfde60e31687f6e93b85e30c32053ee416b3a
+  metadata.gz: ffb2119b2d0c114ad029baeff45ebcc155c660ef16a9a8ed844a9a9759861b67
+  data.tar.gz: 4d1101c45ad53eb66cf9ef16851e182220bce3b5862fe99f2a3e7c0af8d5dd04
 SHA512:
-  metadata.gz: b27c5ec88a2cfdec49750d9d3316979c90c0815461eb6281b4cf602dc6533c8761c8fba7fb49407256b9ade87f2f3731e8f9d121c4ef089d08be2901107cc295
-  data.tar.gz: f1b41cef40049564af8f081547460d72e787a721f676db4c80cd74eb21844b48364ac3b871e6ad2839505908d9e5be3b8d643c16812bd91ae6d0e858bcfb51eb
+  metadata.gz: 1ee4b2210fabe9d92f7296fc2d093dd281704e932e6f885b96e28a5ac470a96966180086a6689e9c8dff37bf2d35f21262a2a45f5e73a7070b9a9b1f90d8dabc
+  data.tar.gz: 4a23c547e4d42fad651be35ed769abf42ef308bcf6083ae11c15b7535f972d24b55afdf583a0396c4477819d2e0b7a6ef3169860b2e747206a5f9ed2fb3a5ee6

data/CHANGELOG.md

@@ -5,7 +5,15 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.1.3] - 2025-01-XX
+## [0.1.5] - 2025-11-01
+
+### Fixed
+- Fixed signature field image data parsing when adding signature fields. Image data (base64 or data URI) is now properly detected and parsed when creating signature fields, matching the behavior of `update_field`.
+
+### Added
+- Added support for `metadata` option in `add_field` to pass PDF widget properties. This allows setting properties like field flags (`Ff`) for multiline text fields, alignment (`Q`), and other PDF widget options directly when creating fields.
+
+## [0.1.4] - 2025-11-01
 
 ### Fixed
 - Fixed bug where fields added to multi-page PDFs were all placed on the same page. Fields now correctly appear on their specified pages when using the `page` option in `add_field`.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    acro_that (0.1.2)
+    acro_that (0.1.4)
       chunky_png (~> 1.4)
 
 GEM

data/README.md

@@ -234,6 +234,32 @@ fields.each do |field|
 end
 ```
 
+#### `#list_pages`
+Returns an array of `Page` objects representing all pages in the document. Each `Page` object provides page information and methods to add fields to that specific page.
+
+```ruby
+pages = doc.list_pages
+pages.each do |page|
+  puts "Page #{page.page_number}: #{page.width}x#{page.height}"
+end
+
+# Add fields to specific pages - the page is automatically set!
+first_page = pages[0]
+first_page.add_field("Name", x: 100, y: 700, width: 200, height: 20)
+
+second_page = pages[1]
+second_page.add_field("Email", x: 100, y: 650, width: 200, height: 20)
+```
+
+**Page Object Methods:**
+- `page.page_number` - Returns the page number (1-indexed)
+- `page.width` - Page width in points
+- `page.height` - Page height in points
+- `page.ref` - Page object reference `[obj_num, gen_num]`
+- `page.metadata` - Hash containing page metadata (rotation, boxes, etc.)
+- `page.add_field(name, options)` - Add a field to this page (page number is automatically set)
+- `page.to_h` - Convert to hash for backward compatibility
+
 #### `#add_field(name, options)`
 Adds a new form field to the document. Options include:
 - `value`: Default value for the field (String)

data/lib/acro_that/actions/add_field.rb

@@ -12,6 +12,7 @@ module AcroThat
         @document = document
         @name = name
         @options = options
+        @metadata = options[:metadata] || {}
       end
 
       def call
@@ -60,6 +61,19 @@ module AcroThat
         # Add widget to the target page's /Annots
         add_widget_to_page(widget_obj_num, page_num)
 
+        # If this is a signature field with image data, add the signature appearance
+        if @field_type == "/Sig" && @field_value && !@field_value.empty?
+          image_data = @field_value
+          # Check if value looks like base64 image data or data URI (same logic as update_field)
+          if image_data.is_a?(String) && (image_data.start_with?("data:image/") || (image_data.length > 50 && image_data.match?(%r{^[A-Za-z0-9+/]*={0,2}$})))
+            field_ref = [@field_obj_num, 0]
+            # Try adding signature appearance - use width and height from options
+            action = Actions::AddSignatureAppearance.new(@document, field_ref, image_data, width: width, height: height)
+            # NOTE: We don't fail if appearance addition fails - field was still created successfully
+            action.call
+          end
+        end
+
         true
       end
 
@@ -69,9 +83,33 @@ module AcroThat
         dict = "<<\n"
         dict += "  /FT #{type}\n"
         dict += "  /T #{DictScan.encode_pdf_string(@name)}\n"
-        dict += "  /Ff 0\n"
+
+        # Apply /Ff from metadata, or use default 0
+        field_flags = @metadata[:Ff] || @metadata["Ff"] || 0
+        dict += "  /Ff #{field_flags}\n"
+
         dict += "  /DA (/Helv 0 Tf 0 g)\n"
-        dict += "  /V #{DictScan.encode_pdf_string(value)}\n" if value && !value.empty?
+
+        # For signature fields with image data, don't set /V (appearance stream will be added separately)
+        # For other fields or non-image signature values, set /V normally
+        should_set_value = if type == "/Sig" && value && !value.empty?
+                             # Check if value looks like image data
+                             !(value.is_a?(String) && (value.start_with?("data:image/") || (value.length > 50 && value.match?(%r{^[A-Za-z0-9+/]*={0,2}$}))))
+                           else
+                             true
+                           end
+
+        dict += "  /V #{DictScan.encode_pdf_string(value)}\n" if should_set_value && value && !value.empty?
+
+        # Apply other metadata entries (excluding Ff which we handled above)
+        @metadata.each do |key, val|
+          next if [:Ff, "Ff"].include?(key) # Already handled above
+
+          pdf_key = format_pdf_key(key)
+          pdf_value = format_pdf_value(val)
+          dict += "  #{pdf_key} #{pdf_value}\n"
+        end
+
         dict += ">>"
         dict
       end
@@ -87,7 +125,29 @@ module AcroThat
         widget += "  /Rect #{rect_array}\n"
         widget += "  /F 4\n"
         widget += "  /DA (/Helv 0 Tf 0 g)\n"
-        widget += "  /V #{DictScan.encode_pdf_string(value)}\n" if value && !value.empty?
+
+        # For signature fields with image data, don't set /V (appearance stream will be added separately)
+        # For other fields or non-image signature values, set /V normally
+        should_set_value = if type == "/Sig" && value && !value.empty?
+                             # Check if value looks like image data
+                             !(value.is_a?(String) && (value.start_with?("data:image/") || (value.length > 50 && value.match?(%r{^[A-Za-z0-9+/]*={0,2}$}))))
+                           else
+                             true
+                           end
+
+        widget += "  /V #{DictScan.encode_pdf_string(value)}\n" if should_set_value && value && !value.empty?
+
+        # Apply metadata entries that are valid for widgets
+        # Common widget properties: /Q (alignment), /Ff (field flags), /BS (border style), etc.
+        @metadata.each do |key, val|
+          pdf_key = format_pdf_key(key)
+          pdf_value = format_pdf_value(val)
+          # Only add if not already present (we've added /F above, /V above if value exists)
+          next if ["/F", "/V"].include?(pdf_key)
+
+          widget += "  #{pdf_key} #{pdf_value}\n"
+        end
+
         widget += ">>"
         widget
       end
@@ -220,6 +280,42 @@ module AcroThat
         apply_patch(target_page_ref, new_body, page_body) if new_body && new_body != page_body
         true
       end
+
+      # Format a metadata key as a PDF dictionary key (ensure it starts with /)
+      def format_pdf_key(key)
+        key_str = key.to_s
+        key_str.start_with?("/") ? key_str : "/#{key_str}"
+      end
+
+      # Format a metadata value appropriately for PDF
+      def format_pdf_value(value)
+        case value
+        when Integer, Float
+          value.to_s
+        when String
+          # If it looks like a PDF string (starts with parenthesis or angle bracket), use as-is
+          if value.start_with?("(") || value.start_with?("<") || value.start_with?("/")
+            value
+          else
+            # Otherwise encode as a PDF string
+            DictScan.encode_pdf_string(value)
+          end
+        when Array
+          # Array format: [item1 item2 item3]
+          items = value.map { |v| format_pdf_value(v) }.join(" ")
+          "[#{items}]"
+        when Hash
+          # Dictionary format: << /Key1 value1 /Key2 value2 >>
+          dict = value.map do |k, v|
+            pdf_key = format_pdf_key(k)
+            pdf_val = format_pdf_value(v)
+            "  #{pdf_key} #{pdf_val}"
+          end.join("\n")
+          "<<\n#{dict}\n>>"
+        else
+          value.to_s
+        end
+      end
     end
   end
 end

data/lib/acro_that/document.rb

@@ -179,13 +179,14 @@ module AcroThat
           contents_refs: contents_refs
         }
 
-        pages << {
-          page: index + 1, # Page number starting at 1
-          width: width,
-          height: height,
-          ref: ref,
-          metadata: metadata
-        }
+        pages << Page.new(
+          index + 1, # Page number starting at 1
+          width,
+          height,
+          ref,
+          metadata,
+          self # Pass document reference
+        )
       end
 
       pages
@@ -202,7 +203,7 @@ module AcroThat
         next unless body
 
         is_widget = DictScan.is_widget?(body)
-        
+
         # Collect widget information if this is a widget
         if is_widget
           # Extract position from widget

data/lib/acro_that/page.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module AcroThat
+  # Represents a page in a PDF document
+  class Page
+    attr_reader :page, :width, :height, :ref, :metadata, :document
+
+    def initialize(page, width, height, ref, metadata, document)
+      @page = page # Page number (1-indexed)
+      @width = width
+      @height = height
+      @ref = ref # [obj_num, gen_num]
+      @metadata = metadata # Hash with :rotate, :media_box, :crop_box, etc.
+      @document = document
+    end
+
+    # Add a field to this page
+    # Options are the same as Document#add_field, but :page is automatically set
+    def add_field(name, options = {})
+      # Automatically set the page number to this page
+      options_with_page = options.merge(page: @page)
+      @document.add_field(name, options_with_page)
+    end
+
+    # Get the page number
+    def page_number
+      @page
+    end
+
+    # Get the page reference [obj_num, gen_num]
+    def page_ref
+      @ref
+    end
+
+    # Check if page has rotation
+    def rotated?
+      !@metadata[:rotate].nil? && @metadata[:rotate] != 0
+    end
+
+    # Get rotation angle (0, 90, 180, 270)
+    def rotation
+      @metadata[:rotate] || 0
+    end
+
+    # Get MediaBox dimensions
+    def media_box
+      @metadata[:media_box]
+    end
+
+    # Get CropBox dimensions
+    def crop_box
+      @metadata[:crop_box]
+    end
+
+    # Get ArtBox dimensions
+    def art_box
+      @metadata[:art_box]
+    end
+
+    # Get BleedBox dimensions
+    def bleed_box
+      @metadata[:bleed_box]
+    end
+
+    # Get TrimBox dimensions
+    def trim_box
+      @metadata[:trim_box]
+    end
+
+    # String representation for debugging
+    def to_s
+      dims = width && height ? " #{width}x#{height}" : ""
+      rot = rotated? ? " (rotated #{rotation}°)" : ""
+      "#<AcroThat::Page page=#{page}#{dims}#{rot} ref=#{ref.inspect}>"
+    end
+
+    alias inspect to_s
+
+    # Convert to hash for backward compatibility
+    def to_h
+      {
+        page: @page,
+        width: @width,
+        height: @height,
+        ref: @ref,
+        metadata: @metadata
+      }
+    end
+  end
+end

data/lib/acro_that/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AcroThat
-  VERSION = "0.1.3"
+  VERSION = "0.1.5"
 end

data/lib/acro_that.rb

@@ -12,6 +12,7 @@ require_relative "acro_that/objstm"
 require_relative "acro_that/pdf_writer"
 require_relative "acro_that/incremental_writer"
 require_relative "acro_that/field"
+require_relative "acro_that/page"
 require_relative "acro_that/document"
 
 # Load actions

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: acro_that
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.5
 platform: ruby
 authors:
 - Michael Wynkoop
@@ -116,6 +116,7 @@ files:
 - lib/acro_that/incremental_writer.rb
 - lib/acro_that/object_resolver.rb
 - lib/acro_that/objstm.rb
+- lib/acro_that/page.rb
 - lib/acro_that/pdf_writer.rb
 - lib/acro_that/version.rb
 - publish