Add turbo_search_form_for helper for Turbo/Hotwire integration (#1611)

* Initial plan

* Add turbo_search_form_for helper for turbo stream support

Co-authored-by: scarroll32 <[email protected]>

* Add documentation for turbo_search_form_for helper

Co-authored-by: scarroll32 <[email protected]>

* Changes before error encountered

Co-authored-by: scarroll32 <[email protected]>

* Fix logic error in turbo_search_form_for turbo_frame handling

Co-authored-by: scarroll32 <[email protected]>

* Fix test interference by adding proper Ransack configuration cleanup

Co-authored-by: scarroll32 <[email protected]>

* Refactor turbo_search_form_for into smaller, testable methods

Co-authored-by: scarroll32 <[email protected]>

* Fix CI failure by removing unreliable caller_locations usage

Co-authored-by: scarroll32 <[email protected]>

* Fix data attribute format for Rails form helpers compatibility

Co-authored-by: scarroll32 <[email protected]>

* Fix specs

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: scarroll32 <[email protected]>
Co-authored-by: Sean <[email protected]>

Author: Copilot

docs/docs/getting-started/simple-mode.md

@@ -106,6 +106,39 @@ The `search_form_for` answer format can be set like this:
 <%= search_form_for(@q, format: :json) do |f| %>
 ```
 
+### Turbo-enabled search form
+
+For applications using Turbo (Hotwire), Ransack provides `turbo_search_form_for` helper which submits forms via turbo streams instead of traditional HTML GET requests. This is particularly useful when integrating with paginated results or other turbo-enabled components:
+
+```erb
+<%= turbo_search_form_for @q do |f| %>
+  <%= f.label :name_cont %>
+  <%= f.search_field :name_cont %>
+  <%= f.submit %>
+<% end %>
+```
+
+The turbo form helper supports the same options as `search_form_for`, plus additional turbo-specific options:
+
+```erb
+# Target a specific turbo frame
+<%= turbo_search_form_for @q, turbo_frame: 'search_results' do |f| %>
+  # form fields
+<% end %>
+
+# Use a custom HTTP method (defaults to POST)
+<%= turbo_search_form_for @q, method: :patch do |f| %>
+  # form fields
+<% end %>
+
+# Set turbo action behavior
+<%= turbo_search_form_for @q, turbo_action: 'replace' do |f| %>
+  # form fields
+<% end %>
+```
+
+This eliminates the need for complex controller logic to handle different request formats when combining search with pagination.
+
 ### Search link helper
 
 Ransack's `sort_link` helper creates table headers that are sortable links

lib/ransack/helpers/form_helper.rb

@@ -7,30 +7,28 @@ module FormHelper
       #   <%= search_form_for(@q) do |f| %>
       #
       def search_form_for(record, options = {}, &proc)
-        if record.is_a? Ransack::Search
-          search = record
-          options[:url] ||= polymorphic_path(
-            search.klass, format: options.delete(:format)
-            )
-        elsif record.is_a?(Array) &&
-        (search = record.detect { |o| o.is_a?(Ransack::Search) })
-          options[:url] ||= polymorphic_path(
-            options_for(record), format: options.delete(:format)
-            )
-        else
-          raise ArgumentError,
-          'No Ransack::Search object was provided to search_form_for!'
-        end
+        search = extract_search_and_set_url(record, options, 'search_form_for')
         options[:html] ||= {}
-        html_options = {
-          class:  html_option_for(options[:class], search),
-          id:     html_option_for(options[:id], search),
-          method: :get
-        }
-        options[:as] ||= Ransack.options[:search_key]
-        options[:html].reverse_merge!(html_options)
-        options[:builder] ||= FormBuilder
+        html_options = build_html_options(search, options, :get)
+        finalize_form_options(options, html_options)
+        form_for(record, options, &proc)
+      end
 
+      # +turbo_search_form_for+
+      #
+      #   <%= turbo_search_form_for(@q) do |f| %>
+      #
+      # This is a turbo-enabled version of search_form_for that submits via turbo streams
+      # instead of traditional HTML GET requests. Useful for seamless integration with
+      # paginated results and other turbo-enabled components.
+      #
+      def turbo_search_form_for(record, options = {}, &proc)
+        search = extract_search_and_set_url(record, options, 'turbo_search_form_for')
+        options[:html] ||= {}
+        turbo_options = build_turbo_options(options)
+        method = options.delete(:method) || :post
+        html_options = build_html_options(search, options, method).merge(turbo_options)
+        finalize_form_options(options, html_options)
         form_for(record, options, &proc)
       end
 
@@ -68,6 +66,48 @@ def sort_url(search_object, attribute, *args)
 
       private
 
+        def extract_search_and_set_url(record, options, method_name)
+          if record.is_a? Ransack::Search
+            search = record
+            options[:url] ||= polymorphic_path(
+              search.klass, format: options.delete(:format)
+            )
+            search
+          elsif record.is_a?(Array) &&
+          (search = record.detect { |o| o.is_a?(Ransack::Search) })
+            options[:url] ||= polymorphic_path(
+              options_for(record), format: options.delete(:format)
+            )
+            search
+          else
+            raise ArgumentError,
+            "No Ransack::Search object was provided to #{method_name}!"
+          end
+        end
+
+        def build_turbo_options(options)
+          data_options = {}
+          if options[:turbo_frame]
+            data_options[:turbo_frame] = options.delete(:turbo_frame)
+          end
+          data_options[:turbo_action] = options.delete(:turbo_action) || 'advance'
+          { data: data_options }
+        end
+
+        def build_html_options(search, options, method)
+          {
+            class:  html_option_for(options[:class], search),
+            id:     html_option_for(options[:id], search),
+            method: method
+          }
+        end
+
+        def finalize_form_options(options, html_options)
+          options[:as] ||= Ransack.options[:search_key]
+          options[:html].reverse_merge!(html_options)
+          options[:builder] ||= FormBuilder
+        end
+
         def options_for(record)
           record.map { |r| parse_record(r) }
         end

spec/ransack/helpers/form_helper_spec.rb

@@ -849,12 +849,153 @@ module Helpers
         before do
           Ransack.configure { |c| c.search_key = :example }
         end
+        after do
+          Ransack.configure { |c| c.search_key = :q }
+        end
         subject {
           @controller.view_context
           .search_form_for(Person.ransack) { |f| f.text_field :name_eq }
         }
         it { should match /example_name_eq/ }
       end
+
+      describe '#turbo_search_form_for with default options' do
+        subject {
+          @controller.view_context
+          .turbo_search_form_for(Person.ransack) {}
+        }
+        it { should match /action="\/people"/ }
+        it { should match /method="post"/ }
+        it { should match /data-turbo-action="advance"/ }
+      end
+
+      describe '#turbo_search_form_for with custom method' do
+        subject {
+          @controller.view_context
+          .turbo_search_form_for(Person.ransack, method: :patch) {}
+        }
+        it { should match /method="post"/ }
+        it { should match /name="_method" value="patch"/ }
+        it { should match /data-turbo-action="advance"/ }
+      end
+
+      describe '#turbo_search_form_for with turbo_frame' do
+        subject {
+          @controller.view_context
+          .turbo_search_form_for(Person.ransack, turbo_frame: 'search_results') {}
+        }
+        it { should match /data-turbo-frame="search_results"/ }
+      end
+
+      describe '#turbo_search_form_for with custom turbo_action' do
+        subject {
+          @controller.view_context
+          .turbo_search_form_for(Person.ransack, turbo_action: 'replace') {}
+        }
+        it { should match /data-turbo-action="replace"/ }
+      end
+
+      describe '#turbo_search_form_for with format' do
+        subject {
+          @controller.view_context
+          .turbo_search_form_for(Person.ransack, format: :json) {}
+        }
+        it { should match /action="\/people.json"/ }
+      end
+
+      describe '#turbo_search_form_for with array of routes' do
+        subject {
+          @controller.view_context
+          .turbo_search_form_for([:admin, Comment.ransack]) {}
+        }
+        it { should match /action="\/admin\/comments"/ }
+      end
+
+      describe '#turbo_search_form_for with custom search key' do
+        before do
+          Ransack.configure { |c| c.search_key = :example }
+        end
+        after do
+          Ransack.configure { |c| c.search_key = :q }
+        end
+        subject {
+          @controller.view_context
+          .turbo_search_form_for(Person.ransack) { |f| f.text_field :name_eq }
+        }
+        it { should match /example_name_eq/ }
+      end
+
+      describe '#turbo_search_form_for without Ransack::Search object' do
+        it 'raises ArgumentError' do
+          expect {
+            @controller.view_context.turbo_search_form_for("not a search object") {}
+          }.to raise_error(ArgumentError, 'No Ransack::Search object was provided to turbo_search_form_for!')
+        end
+      end
+
+      describe 'private helper methods' do
+        let(:helper) { @controller.view_context }
+        let(:search) { Person.ransack }
+
+        describe '#build_turbo_options' do
+          it 'builds turbo options with frame' do
+            options = { turbo_frame: 'results', turbo_action: 'replace' }
+            result = helper.send(:build_turbo_options, options)
+            expect(result).to eq({
+              data: {
+                turbo_frame: 'results',
+                turbo_action: 'replace'
+              }
+            })
+            expect(options).to be_empty
+          end
+
+          it 'builds turbo options without frame' do
+            options = { turbo_action: 'advance' }
+            result = helper.send(:build_turbo_options, options)
+            expect(result).to eq({ data: { turbo_action: 'advance' } })
+          end
+
+          it 'uses default turbo action' do
+            options = {}
+            result = helper.send(:build_turbo_options, options)
+            expect(result).to eq({ data: { turbo_action: 'advance' } })
+          end
+        end
+
+        describe '#build_html_options' do
+          it 'builds HTML options with correct method' do
+            options = { class: 'custom' }
+            result = helper.send(:build_html_options, search, options, :post)
+            expect(result[:method]).to eq(:post)
+            expect(result[:class]).to include('custom')
+          end
+        end
+
+        describe '#extract_search_and_set_url' do
+          it 'extracts search from Ransack::Search object' do
+            options = {}
+            result = helper.send(:extract_search_and_set_url, search, options, 'search_form_for')
+            expect(result).to eq(search)
+            expect(options[:url]).to match(/people/)
+          end
+
+          it 'extracts search from array with Search object' do
+            options = {}
+            comment_search = Comment.ransack
+            result = helper.send(:extract_search_and_set_url, [:admin, comment_search], options, 'search_form_for')
+            expect(result).to eq(comment_search)
+            expect(options[:url]).to match(/admin/)
+          end
+
+          it 'raises error for invalid record with correct method name' do
+            options = {}
+            expect {
+              helper.send(:extract_search_and_set_url, "invalid", options, 'turbo_search_form_for')
+            }.to raise_error(ArgumentError, 'No Ransack::Search object was provided to turbo_search_form_for!')
+          end
+        end
+      end
     end
   end
 end