From 07bca42f736b9c91fe9cfce036aa6ca508d7e21d Mon Sep 17 00:00:00 2001
From: Jared Turner <jared.turner@thoughtbot.com>
Date: Fri, 17 Jan 2025 15:54:19 +0000
Subject: [PATCH] Add tooltip to search

You can add collection filters to a dashboard and then use them in the
search bar on the index page. eg. `email:jared@example.com`

However, these collection filters are not discoverable. You have to know
about them already to know how to use them.

This change introduces a tooltip which lists the available collection
filters, allowing all users to discover what is available.

Closes https://github.com/thoughtbot/administrate/issues/2750
---
 .../administrate/application_controller.rb    |  4 +-
 .../application/_index_header.html.erb        | 13 ++++++
 .../administrate/application/index.html.erb   |  1 +
 lib/administrate/search.rb                    | 16 +++----
 spec/features/search_spec.rb                  | 43 +++++++++++++++++++
 5 files changed, 68 insertions(+), 9 deletions(-)

diff --git a/app/controllers/administrate/application_controller.rb b/app/controllers/administrate/application_controller.rb
index 63f486d5ae..7dc8af756d 100644
--- a/app/controllers/administrate/application_controller.rb
+++ b/app/controllers/administrate/application_controller.rb
@@ -10,12 +10,14 @@ def index
       resources = order.apply(resources)
       resources = paginate_resources(resources)
       page = Administrate::Page::Collection.new(dashboard, order: order)
+      filters = Administrate::Search.new(scoped_resource, dashboard, search_term).valid_filters
 
       render locals: {
         resources: resources,
         search_term: search_term,
         page: page,
-        show_search_bar: show_search_bar?
+        show_search_bar: show_search_bar?,
+        filters: filters
       }
     end
 
diff --git a/app/views/administrate/application/_index_header.html.erb b/app/views/administrate/application/_index_header.html.erb
index 1b9c5623e7..b9fc50ba3c 100644
--- a/app/views/administrate/application/_index_header.html.erb
+++ b/app/views/administrate/application/_index_header.html.erb
@@ -15,6 +15,19 @@
       search_term: search_term,
       resource_name: display_resource_name(page.resource_name)
     ) %>
+
+    <% if filters.any? %>
+      <button popovertarget="search-tooltip" class="button--alt" style="margin-right: 2rem;">?</button>
+
+      <div popover id="search-tooltip" role="tooltip" style="padding: 2rem;">
+        <p>Use filters to refine your search:</p>
+        <ul>
+          <% filters.keys.each do |filter_key| %>
+          <li><strong><%= filter_key %></strong>:&lt;value&gt;</li>
+          <% end %>
+        </ul>
+      </div>
+    <% end %>
   <% end %>
 
   <div>
diff --git a/app/views/administrate/application/index.html.erb b/app/views/administrate/application/index.html.erb
index 36e64b0030..25db68c996 100644
--- a/app/views/administrate/application/index.html.erb
+++ b/app/views/administrate/application/index.html.erb
@@ -29,6 +29,7 @@ It renders the `_table` partial to display details about the resources.
     search_term: search_term,
     page: page,
     show_search_bar: show_search_bar,
+    filters: filters,
   )
 %>
 
diff --git a/lib/administrate/search.rb b/lib/administrate/search.rb
index ac04587c9f..672c05c9f2 100644
--- a/lib/administrate/search.rb
+++ b/lib/administrate/search.rb
@@ -63,6 +63,14 @@ def run
       end
     end
 
+    def valid_filters
+      if @dashboard.class.const_defined?(:COLLECTION_FILTERS)
+        @dashboard.class.const_get(:COLLECTION_FILTERS).stringify_keys
+      else
+        {}
+      end
+    end
+
     private
 
     def apply_filter(filter, filter_param, resources)
@@ -116,14 +124,6 @@ def search_results(resources)
         .where(query_template, *query_values)
     end
 
-    def valid_filters
-      if @dashboard.class.const_defined?(:COLLECTION_FILTERS)
-        @dashboard.class.const_get(:COLLECTION_FILTERS).stringify_keys
-      else
-        {}
-      end
-    end
-
     def attribute_types
       @dashboard.class.const_get(:ATTRIBUTE_TYPES)
     end
diff --git a/spec/features/search_spec.rb b/spec/features/search_spec.rb
index 5c193929cf..07d82139b0 100644
--- a/spec/features/search_spec.rb
+++ b/spec/features/search_spec.rb
@@ -25,6 +25,49 @@ def have_a_search_bar
     end
   end
 
+  describe "search bar tooltip" do
+    def have_a_search_tooltip
+      have_css("button[popovertarget=search-tooltip]")
+    end
+
+    it "is visible when the current dashboard has collection filters" do
+      visit admin_customers_path
+
+      expect(page).to have_a_search_tooltip
+    end
+
+    context "when clicked" do
+      it "shows a popover with the available filters" do
+        visit admin_customers_path
+        click_on "?"
+
+        expect(page).to have_content("Use filters to refine your search:")
+        expect(page).to have_content("vip:<value>")
+        expect(page).to have_content("kind:<value>")
+      end
+    end
+
+    it "is hidden when the current dashboard has no collection filters" do
+      CustomerDashboard::COLLECTION_FILTERS = {}.freeze
+
+      visit admin_customers_path
+
+      expect(page).not_to have_a_search_tooltip
+    end
+
+    it "is hidden when nothing is searchable in the current dashboard" do
+      CustomerDashboard::ATTRIBUTE_TYPES.each do |_name, field_class|
+        allow(field_class).to(
+          receive(:searchable?).and_return(false)
+        )
+      end
+
+      visit admin_customers_path
+
+      expect(page).not_to have_a_search_tooltip
+    end
+  end
+
   scenario "admin searches for customer by email", :js do
     query = "bar@baz.com"
     perfect_match = create(:customer, email: "bar@baz.com")