acro_that 0.1.5 → 0.1.7

data/issues/refactoring-opportunities.md

@@ -2,30 +2,21 @@
 
 This document identifies code duplication and unused methods that could be refactored to improve maintainability.
 
-## 1. Duplicated Page-Finding Logic
+## 1. Duplicated Page-Finding Logic ✅ **COMPLETED**
 
-### Issue
-Multiple methods have similar logic for finding page objects in a PDF document.
-
-### Locations
-- `Document#list_pages` (lines 75-104)
-- `Document#collect_pages_from_tree` (lines 691-712)
-- `Document#find_page_number_for_ref` (lines 714-728)
-- `AddField#find_page_ref` (lines 155-211)
-
-### Pattern
-The pattern `body.include?("/Type /Page") || body =~ %r{/Type\s*/Page(?!s)\b}` appears in multiple places with slight variations.
+### Status
+**RESOLVED** - This refactoring has been completed:
+- ✅ `DictScan.is_page?(body)` exists (line 320 in dict_scan.rb)
+- ✅ `Document#find_all_pages` exists (line 693 in document.rb)
+- ✅ `Document#find_page_by_number(page_num)` exists (line 725 in document.rb)
+- ✅ `Base#find_page_by_number` delegates to Document
+- ✅ `AddField#find_page_ref` now uses `find_page_by_number` (line 288)
 
-### Suggested Refactor
-Create a shared module or utility methods in `DictScan`:
-- `DictScan.is_page?(body)` - Check if a body represents a page object
-- `Document#find_all_pages` - Unified method to find all page objects
-- `Document#find_page_by_number(page_num)` - Find a specific page by number
+### Original Issue
+Multiple methods had similar logic for finding page objects in a PDF document.
 
-### Benefits
-- Single source of truth for page detection logic
-- Easier to maintain and update page-finding behavior
-- Consistent page ordering across methods
+### Resolution
+All page-finding logic has been unified into `DictScan.is_page?` and `Document#find_all_pages` / `find_page_by_number`.
 
 ---
 
@@ -97,45 +88,18 @@ Extend `DictScan` with methods:
 
 ---
 
-## 4. Duplicated Box Parsing Logic
+## 4. Duplicated Box Parsing Logic ✅ **COMPLETED**
 
-### Issue
-`Document#list_pages` has repeated code blocks for parsing different box types (MediaBox, CropBox, ArtBox, BleedBox, TrimBox).
+### Status
+**RESOLVED** - This refactoring has been completed:
+- ✅ `DictScan.parse_box(body, box_type)` exists (line 340 in dict_scan.rb)
+- ✅ `Document#list_pages` now uses `parse_box` for all box types (lines 89-99 in document.rb)
 
-### Locations
-- `Document#list_pages` (lines 120-165)
+### Original Issue
+`Document#list_pages` had repeated code blocks for parsing different box types (MediaBox, CropBox, ArtBox, BleedBox, TrimBox).
 
-### Pattern
-Each box type uses identical logic:
-```ruby
-if body =~ %r{/MediaBox\s*\[(.*?)\]}
-  box_values = ::Regexp.last_match(1).scan(/[-+]?\d*\.?\d+/).map(&:to_f)
-  if box_values.length == 4
-    llx, lly, urx, ury = box_values
-    media_box = { llx: llx, lly: lly, urx: urx, ury: ury }
-  end
-end
-```
-
-### Suggested Refactor
-Create a helper method:
-```ruby
-def parse_box(body, box_type)
-  pattern = %r{/#{box_type}\s*\[(.*?)\]}
-  return nil unless body =~ pattern
-  
-  box_values = ::Regexp.last_match(1).scan(/[-+]?\d*\.?\d+/).map(&:to_f)
-  return nil unless box_values.length == 4
-  
-  llx, lly, urx, ury = box_values
-  { llx: llx, lly: lly, urx: urx, ury: ury }
-end
-```
-
-### Benefits
-- Reduces code duplication from ~45 lines to ~10 lines per box type
-- Easier to add new box types
-- Consistent parsing logic
+### Resolution
+Extracted the common box parsing logic into `DictScan.parse_box` helper method. All box type parsing in `Document#list_pages` now uses this shared method, reducing code duplication from ~45 lines to ~10 lines while maintaining existing functionality.
 
 ---
 
@@ -145,32 +109,23 @@ end
 The `next_fresh_object_number` method is implemented identically in two places.
 
 ### Locations
-- `Document#next_fresh_object_number` (lines 730-739)
+- `Document#next_fresh_object_number` (lines 745-754)
 - `Base#next_fresh_object_number` (lines 28-37)
 
 ### Pattern
-Both methods have identical implementation:
-```ruby
-def next_fresh_object_number
-  max_obj_num = 0
-  resolver.each_object do |ref, _|
-    max_obj_num = [max_obj_num, ref[0]].max
-  end
-  patches.each do |p|
-    max_obj_num = [max_obj_num, p[:ref][0]].max
-  end
-  max_obj_num + 1
-end
-```
+Both methods have identical implementation. However, `Document` doesn't include `Base`, so both need to exist independently.
 
 ### Suggested Refactor
-- Remove `Document#next_fresh_object_number` - it's only called within `Document` but could use `Base`'s implementation
-- Or: Document already has access to resolver and patches, so remove duplication by making Document use Base's method
+- Consider whether `Document` should use `Base`'s implementation via delegation
+- Or: Keep both implementations if Document needs independent access
 
 ### Benefits
 - Single implementation
 - Consistent object numbering logic
 
+### Note
+This may be intentional since `Document` doesn't include `Base` - both classes need this functionality independently.
+
 ---
 
 ## 6. Unused Methods
@@ -250,15 +205,50 @@ end
 1. **Widget Matching Logic (#2)** - Most duplicated, used in many critical operations
 2. **/Annots Array Manipulation (#3)** - Complex logic that's error-prone when duplicated
 
-### Medium Priority
-3. **Page-Finding Logic (#1)** - Used in multiple places, but less frequently
-4. **Box Parsing Logic (#4)** - Simple duplication, easy to refactor
 
 ### Low Priority
-5. **next_fresh_object_number (#5)** - Simple duplication
-6. **Object Reference Extraction (#8)** - Could improve consistency
-7. **Unused Methods (#6)** - Cleanup task
-8. **Base64 Decoding (#7)** - Minor duplication
+6. **next_fresh_object_number (#5)** - Simple duplication (may be intentional)
+7. **Object Reference Extraction (#8)** - Could improve consistency
+8. **Unused Methods (#6)** - Cleanup task (`get_widget_rect_dimensions`)
+9. **Base64 Decoding (#7)** - Minor duplication
+
+### Completed ✅
+- **Page-Finding Logic (#1)** - Successfully refactored into `DictScan.is_page?` and unified page-finding methods
+- **Checkbox Appearance Creation (#9)** - Extracted common Form XObject building logic into `build_form_xobject` helper method
+- **Box Parsing Logic (#4)** - Extracted common box parsing logic into `DictScan.parse_box` helper method
+- **PDF Metadata Formatting (#10)** - Moved `format_pdf_key` and `format_pdf_value` to `DictScan` module as shared utilities
+
+---
+
+## 9. Duplicated Checkbox Appearance Creation Logic ✅ **COMPLETED**
+
+### Status
+**RESOLVED** - This refactoring has been completed:
+- ✅ `AddField#build_form_xobject` exists (line 472 in add_field.rb)
+- ✅ `AddField#create_checkbox_yes_appearance` now uses `build_form_xobject` (line 458)
+- ✅ `AddField#create_checkbox_off_appearance` now uses `build_form_xobject` (line 469)
+
+### Original Issue
+The `create_checkbox_yes_appearance` and `create_checkbox_off_appearance` methods had duplicated Form XObject dictionary building logic.
+
+### Resolution
+Extracted the common Form XObject dictionary building logic into `build_form_xobject` helper method. Both checkbox appearance methods now use this shared method, reducing duplication while maintaining existing functionality.
+
+---
+
+## 10. PDF Metadata Formatting Methods Could Be Shared ✅ **COMPLETED**
+
+### Status
+**RESOLVED** - This refactoring has been completed:
+- ✅ `DictScan.format_pdf_key(key)` exists (line 134 in dict_scan.rb)
+- ✅ `DictScan.format_pdf_value(value)` exists (line 140 in dict_scan.rb)
+- ✅ `AddField` now uses `DictScan.format_pdf_key` and `DictScan.format_pdf_value` (lines 145-146, 195-196)
+
+### Original Issue
+The `format_pdf_key` and `format_pdf_value` methods in `AddField` were useful utility functions that could be shared across the codebase.
+
+### Resolution
+Moved `format_pdf_key` and `format_pdf_value` from `AddField` to the `DictScan` module as module functions. This makes them reusable throughout the codebase and provides a single source of truth for PDF formatting rules. `AddField` now uses these shared utilities, maintaining existing functionality while improving code reusability.
 
 ---
 

data/lib/acro_that/actions/add_field.rb

@@ -29,6 +29,10 @@ module AcroThat
                         "/Tx"
                       when :button, "button", "/Btn", "/btn"
                         "/Btn"
+                      when :radio, "radio"
+                        "/Btn"
+                      when :checkbox, "checkbox"
+                        "/Btn"
                       when :choice, "choice", "/Ch", "/ch"
                         "/Ch"
                       when :signature, "signature", "/Sig", "/sig"
@@ -38,6 +42,12 @@ module AcroThat
                       end
         @field_value = @options[:value] || ""
 
+        # Auto-set radio button flags if type is :radio and flags not explicitly set
+        # Radio button flags: Radio (bit 15 = 32768) + NoToggleToOff (bit 14 = 16384) = 49152
+        if [:radio, "radio"].include?(type_input) && !(@metadata[:Ff] || @metadata["Ff"])
+          @metadata[:Ff] = 49_152
+        end
+
         # Create a proper field dictionary + a widget annotation that references it via /Parent
         @field_obj_num = next_fresh_object_number
         widget_obj_num = @field_obj_num + 1
@@ -74,6 +84,21 @@ module AcroThat
           end
         end
 
+        # If this is a checkbox (button field that's not a radio button), add appearance dictionaries
+        # Button fields can be checkboxes or radio buttons:
+        # - Radio buttons have Radio flag (bit 15 = 32768) set
+        # - Checkboxes don't have Radio flag set
+        is_checkbox = false
+        if @field_type == "/Btn"
+          field_flags = (@metadata[:Ff] || @metadata["Ff"] || 0).to_i
+          is_radio = field_flags.anybits?(32_768) || [:radio, "radio"].include?(type_input)
+          is_checkbox = !is_radio
+        end
+
+        if is_checkbox
+          add_checkbox_appearance(widget_obj_num, x, y, width, height)
+        end
+
         true
       end
 
@@ -85,13 +110,15 @@ module AcroThat
         dict += "  /T #{DictScan.encode_pdf_string(@name)}\n"
 
         # Apply /Ff from metadata, or use default 0
+        # Note: Radio button flags should already be set in metadata during type normalization
         field_flags = @metadata[:Ff] || @metadata["Ff"] || 0
         dict += "  /Ff #{field_flags}\n"
 
         dict += "  /DA (/Helv 0 Tf 0 g)\n"
 
         # 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
+        # For checkboxes/radio buttons, set /V to normalized value (Yes/Off) - macOS Preview needs this
+        # For other fields, 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}$}))))
@@ -99,14 +126,24 @@ module AcroThat
                              true
                            end
 
-        dict += "  /V #{DictScan.encode_pdf_string(value)}\n" if should_set_value && value && !value.empty?
+        # For button fields (checkboxes/radio), normalize value to "Yes" or "Off"
+        normalized_field_value = if type == "/Btn" && value
+                                   # Accept "Yes", "/Yes" (PDF name format), true (boolean), or "true" (string)
+                                   value_str = value.to_s
+                                   is_checked = ["Yes", "/Yes", "true"].include?(value_str) || value == true
+                                   is_checked ? "Yes" : "Off"
+                                 else
+                                   value
+                                 end
+
+        dict += "  /V #{DictScan.encode_pdf_string(normalized_field_value)}\n" if should_set_value && normalized_field_value && !normalized_field_value.to_s.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)
+          pdf_key = DictScan.format_pdf_key(key)
+          pdf_value = DictScan.format_pdf_value(val)
           dict += "  #{pdf_key} #{pdf_value}\n"
         end
 
@@ -126,22 +163,37 @@ module AcroThat
         widget += "  /F 4\n"
         widget += "  /DA (/Helv 0 Tf 0 g)\n"
 
+        # For checkboxes, /V is set to "Yes" or "Off" and /AS is set accordingly
         # 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}$}))))
+                           elsif type == "/Btn"
+                             # For button fields (checkboxes), set /V to "Yes" or "Off"
+                             # This will be handled by checkbox appearance code, but we set it here for consistency
+                             true
                            else
                              true
                            end
 
-        widget += "  /V #{DictScan.encode_pdf_string(value)}\n" if should_set_value && value && !value.empty?
+        # For checkboxes, set /V to "Yes" or empty/Off
+        if type == "/Btn" && should_set_value
+          # Checkbox value should be "Yes" if checked, otherwise empty or "Off"
+          # Accept "Yes", "/Yes" (PDF name format), true (boolean), or "true" (string)
+          value_str = value.to_s
+          is_checked = ["Yes", "/Yes", "true"].include?(value_str) || value == true
+          checkbox_value = is_checked ? "Yes" : "Off"
+          widget += "  /V #{DictScan.encode_pdf_string(checkbox_value)}\n"
+        elsif should_set_value && value && !value.empty?
+          widget += "  /V #{DictScan.encode_pdf_string(value)}\n"
+        end
 
         # 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)
+          pdf_key = DictScan.format_pdf_key(key)
+          pdf_value = DictScan.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)
 
@@ -182,6 +234,41 @@ module AcroThat
           patched = DictScan.upsert_key_value(patched, "/NeedAppearances", "true")
         end
 
+        # Step 2.5: Remove /XFA if present (prevents XFA detection warnings in viewers like Master PDF)
+        # We're creating AcroForms, not XFA forms, so remove /XFA if it exists
+        if patched.include?("/XFA")
+          xfa_pattern = %r{/XFA(?=[\s(<\[/])}
+          if patched.match(xfa_pattern)
+            # Try to get the value token to determine what we're removing
+            xfa_value = DictScan.value_token_after("/XFA", patched)
+            if xfa_value
+              # Remove /XFA by replacing it with an empty string
+              # We'll use a simple approach: find the key and remove it with its value
+              xfa_match = patched.match(xfa_pattern)
+              if xfa_match
+                # Find the start and end of /XFA and its value
+                key_start = xfa_match.begin(0)
+                # Skip /XFA key
+                value_start = xfa_match.end(0)
+                value_start += 1 while value_start < patched.length && patched[value_start] =~ /\s/
+                # Use value_token_after to get the complete value token
+                # We already have xfa_value, so calculate its end
+                value_end = value_start + xfa_value.length
+                # Skip trailing whitespace
+                value_end += 1 while value_end < patched.length && patched[value_end] =~ /\s/
+                # Remove /XFA and its value
+                before = patched[0...key_start]
+                # Remove any whitespace before /XFA too (but not the opening <<)
+                before = before.rstrip
+                after = patched[value_end..]
+                patched = "#{before} #{after.lstrip}".strip
+                # Clean up any double spaces
+                patched = patched.gsub(/\s+/, " ")
+              end
+            end
+          end
+        end
+
         # Step 3: Ensure /DR /Font has /Helv mapping
         unless patched.include?("/DR") && patched.include?("/Helv")
           font_obj_num = next_fresh_object_number
@@ -281,40 +368,120 @@ module AcroThat
         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)
+      def add_checkbox_appearance(widget_obj_num, _x, _y, width, height)
+        # Create appearance form XObjects for Yes and Off states
+        yes_obj_num = next_fresh_object_number
+        off_obj_num = yes_obj_num + 1
+
+        # Create Yes appearance (checked box with checkmark)
+        yes_body = create_checkbox_yes_appearance(width, height)
+        @document.instance_variable_get(:@patches) << { ref: [yes_obj_num, 0], body: yes_body }
+
+        # Create Off appearance (empty box)
+        off_body = create_checkbox_off_appearance(width, height)
+        @document.instance_variable_get(:@patches) << { ref: [off_obj_num, 0], body: off_body }
+
+        # Get current widget body and add /AP dictionary
+        widget_ref = [widget_obj_num, 0]
+        original_widget_body = get_object_body_with_patch(widget_ref)
+        widget_body = original_widget_body.dup
+
+        # Create /AP dictionary with Yes and Off appearances
+        ap_dict = "<<\n  /N <<\n    /Yes #{yes_obj_num} 0 R\n    /Off #{off_obj_num} 0 R\n  >>\n>>"
+
+        # Add /AP to widget
+        if widget_body.include?("/AP")
+          # Replace existing /AP
+          ap_key_pattern = %r{/AP(?=[\s(<\[/])}
+          if widget_body.match(ap_key_pattern)
+            widget_body = DictScan.replace_key_value(widget_body, "/AP", ap_dict)
           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
+          # Insert /AP before closing >>
+          widget_body = DictScan.upsert_key_value(widget_body, "/AP", ap_dict)
         end
+
+        # Set /AS based on the value - use the EXACT same normalization logic as widget creation
+        # This ensures consistency between /V and /AS
+        # Normalize value: "Yes" if truthy (Yes, "/Yes", true, etc.), otherwise "Off"
+        value_str = @field_value.to_s
+        is_checked = value_str == "Yes" || value_str == "/Yes" || value_str == "true" || @field_value == true
+        normalized_value = is_checked ? "Yes" : "Off"
+
+        # Set /AS to match normalized value (same as what was set for /V in widget creation)
+        as_value = if normalized_value == "Yes"
+                     "/Yes"
+                   else
+                     "/Off"
+                   end
+
+        widget_body = if widget_body.include?("/AS")
+                        DictScan.replace_key_value(widget_body, "/AS", as_value)
+                      else
+                        DictScan.upsert_key_value(widget_body, "/AS", as_value)
+                      end
+
+        apply_patch(widget_ref, widget_body, original_widget_body)
+      end
+
+      def create_checkbox_yes_appearance(width, height)
+        # Create a form XObject that draws a checked checkbox
+        # Box outline + checkmark
+        # Scale to match width and height
+        # Simple appearance: draw a box and a checkmark
+        # For simplicity, use PDF drawing operators
+        # Box: rectangle from (0,0) to (width, height)
+        # Checkmark: simple path drawing
+
+        # PDF content stream for checked checkbox
+        # Draw just the checkmark (no box border)
+        border_width = [width * 0.08, height * 0.08].min
+
+        # Calculate checkmark path
+        check_x1 = width * 0.25
+        check_y1 = height * 0.45
+        check_x2 = width * 0.45
+        check_y2 = height * 0.25
+        check_x3 = width * 0.75
+        check_y3 = height * 0.75
+
+        content_stream = "q\n"
+        content_stream += "0 0 0 rg\n" # Black color (darker)
+        content_stream += "#{border_width} w\n" # Line width
+        # Draw checkmark only (no box border)
+        content_stream += "#{check_x1} #{check_y1} m\n"
+        content_stream += "#{check_x2} #{check_y2} l\n"
+        content_stream += "#{check_x3} #{check_y3} l\n"
+        content_stream += "S\n" # Stroke
+        content_stream += "Q\n"
+
+        build_form_xobject(content_stream, width, height)
+      end
+
+      def create_checkbox_off_appearance(width, height)
+        # Create a form XObject for unchecked checkbox
+        # Empty appearance (no border, no checkmark) - viewer will draw default checkbox
+
+        content_stream = "q\n"
+        # Empty appearance for unchecked state
+        content_stream += "Q\n"
+
+        build_form_xobject(content_stream, width, height)
+      end
+
+      def build_form_xobject(content_stream, width, height)
+        # Build a Form XObject dictionary with the given content stream
+        dict = "<<\n"
+        dict += "  /Type /XObject\n"
+        dict += "  /Subtype /Form\n"
+        dict += "  /BBox [0 0 #{width} #{height}]\n"
+        dict += "  /Length #{content_stream.bytesize}\n"
+        dict += ">>\n"
+        dict += "stream\n"
+        dict += content_stream
+        dict += "\nendstream"
+
+        dict
       end
     end
   end