Make Primo errors friendlier

Why these changes are being introduced:

The error styling when Primo is down is minimal
and somewhat angry.

Relevant ticket(s):

- [USE-420](https://mitlibraries.atlassian.net/browse/USE-420)

How this addresses that need:

This modifies Primo error handling to return a
structure that contains messaging to display
in the corresponding partial.

The timeout error message remains as-is, because
attempting a search again usually resolves that.

Side effects of this change:

Additional styling may be needed, as this doesn't
exactly match the screenshots provided by UXWS.

Author: jazairi

app/controllers/search_controller.rb

@@ -388,15 +388,25 @@ def validate_geobox_values!
   end
 
   def handle_primo_errors(error)
-    Rails.logger.error("Primo search error: #{error.message}")
-
-    if error.is_a?(ArgumentError)
-      [{ 'message' => 'Primo search is not properly configured.' }]
-    elsif error.is_a?(HTTP::TimeoutError)
-      [{ 'message' => 'Sorry, that took longer than expected. Please try your search again.' }]
-    else
-      [{ 'message' => error.message }]
-    end
+    Rails.logger.error("Primo search error: #{error.class}: #{error.message}")
+
+    # For timeouts, prompt users to try again.
+    return [{ 'message' => 'Sorry, that took longer than expected. Please try your search again.' }] if error.is_a?(HTTP::TimeoutError)
+
+    # For other errors, Primo is probably down, and we should direct users elsewhere.
+    [{
+      'code' => 'primo_unavailable',
+      'message' => 'Hmm, we seem to be having difficulties...',
+      'description' => 'In the meantime, try searching these tools directly.',
+      'links' => [
+        { 'label' => "MIT's WorldCat", 'description' => 'Books and media', 'url' => 'https://libraries.mit.edu/worldcat' },
+        { 'label' => 'Google Scholar', 'description' => 'Articles', 'url' => 'https://scholar.google.com/' },
+        { 'label' => 'ArchivesSpace', 'description' => 'MIT archives', 'url' => 'https://archivesspace.mit.edu/' },
+        { 'label' => 'DSpace@MIT', 'description' => 'MIT research', 'url' => 'https://dspace.mit.edu/' }
+      ],
+      'help_label' => 'Ask Us',
+      'help_url' => 'https://libraries.mit.edu/ask/'
+    }]
   end
 
   # validate_format_token is only applicable to requests for JSON-format results. It takes no action so long as the

app/views/shared/_error.html.erb

@@ -1,8 +1,30 @@
 <% return unless error['message'].present? %>
+<% primo_unavailable = error['code'] == 'primo_unavailable' %>
 
-<aside class="alert alert-banner error" role="alert">
-  <i></i>
-  <div><h3><%= error['message'] %></h3>
-  <%= error&.dig('extensions')&.dig('problems')&.pluck("explanation")&.join %>
-  </div>
-</aside>
+<% if primo_unavailable %>
+  <aside role="alert" class="primo-unavailable">
+    <h3><%= error['message'] %></h3>
+
+    <p><%= error['description'] %></p>
+    <ul>
+      <% Array(error['links']).each do |link| %>
+        <% next unless link['label'].present? && link['url'].present? %>
+        <li>
+          <a href="<%= link['url'] %>"><%= link['label'] %></a><% if link['description'].present? %>: <%= link['description'] %><% end %>
+        </li>
+      <% end %>
+    </ul>
+    <% if error['help_label'].present? && error['help_url'].present? %>
+      <p>If you need help, <a href="<%= error['help_url'] %>"><%= error['help_label'] %></a>.</p>
+    <% end %>
+  </aside>
+<% else %>
+  <aside class="alert alert-banner error" role="alert">
+    <i></i>
+    <div>
+      <h3><%= error['message'] %></h3>
+
+    <%= error&.dig('extensions')&.dig('problems')&.pluck('explanation')&.join %>
+    </div>
+  </aside>
+<% end %>

test/controllers/search_controller_test.rb

@@ -851,8 +851,18 @@ def source_filter_count(controller)
 
     get '/results?q=test&tab=primo'
     assert_response :success
-    assert_select '.alert', count: 1
-    assert_select '.alert', text: /API Error/
+    assert_select 'aside[role="alert"]', count: 1
+    assert_select 'aside.primo-unavailable h3', text: /Hmm, we seem to be having difficulties/
+    assert_select 'aside.primo-unavailable', text: /In the meantime, try searching these tools directly/
+    assert_select 'aside.primo-unavailable', text: /MIT's WorldCat: Books and media/
+    assert_select 'aside.primo-unavailable', text: /Google Scholar: Articles/
+    assert_select 'aside.primo-unavailable', text: /ArchivesSpace: MIT archives/
+    assert_select 'aside.primo-unavailable', text: /DSpace@MIT: MIT research/
+    assert_select 'aside.primo-unavailable a[href="https://libraries.mit.edu/worldcat"]', text: /MIT's WorldCat/
+    assert_select 'aside.primo-unavailable a[href="https://scholar.google.com/"]', text: /Google Scholar/
+    assert_select 'aside.primo-unavailable a[href="https://archivesspace.mit.edu/"]', text: /ArchivesSpace/
+    assert_select 'aside.primo-unavailable a[href="https://dspace.mit.edu/"]', text: /DSpace@MIT/
+    assert_select 'aside.primo-unavailable a[href="https://libraries.mit.edu/ask/"]', text: /Ask Us/
   end
 
   test 'results uses simplified search summary for USE app' do
@@ -974,7 +984,8 @@ def source_filter_count(controller)
 
     get '/results?q=test&tab=all'
     assert_response :success
-    assert_select '.alert', text: /Primo API Error/
+    assert_select 'aside.primo-unavailable h3', text: /Hmm, we seem to be having difficulties/
+    assert_select 'aside.primo-unavailable', text: /In the meantime, try searching these tools directly/
   end
 
   test 'all tab is default when no tab specified' do