Adds availablility information to records

Why are these changes being introduced:

* This information is useful to users to understand if an item is
  available for checkout or needs to be requested.

Relevant ticket(s):

* https://mitlibraries.atlassian.net/browse/USE-246

How does this address that need:

* Creates a helper method to format availability information
* Updates the result partial to display availability information

Document any side effects to this change:

* Location information is now expected to be an array with three elements
  instead of a string to allow for more flexibility in formatting.

Author: JPrevost

app/helpers/results_helper.rb

@@ -2,4 +2,49 @@ module ResultsHelper
   def results_summary(hits)
     hits.to_i >= 10_000 ? '10,000+ results' : "#{number_with_delimiter(hits)} results"
   end
+
+  # Formats availability information for display.
+  # Expects:
+  # - status: a string indicating availability status
+  # - location: an array with three elements: [library name, location name, call number]
+  # - other_availability: a boolean string indicating if there is availability at other locations
+  def availability(status, location, other_availability)
+    blurb = case status.downcase
+            # `available` is a common status used in Alma/Primo VE for items that are not checked out and should be
+            # on the shelf
+            when 'available'
+              "#{icon('check')} Available in #{location(location)}"
+            # `check_holdings`: unclear when (or if) this is used. Bento handled this so we did too assuming it was
+            # meaningful
+            when 'check_holdings'
+              "#{icon('question')} May be available in #{location(location)}"
+            # 'unavailable' is used for items that are checked out, missing, or otherwise not on the shelf
+            when 'unavailable'
+              "#{icon('times')} Not currently available in #{location(location)}"
+            # Unclear if there are other statuses we should handle here. For now we log and display a generic message.
+            else
+              Rails.logger.error("Unhandled availability status: #{status.inspect}")
+              "#{icon('question')} Uncertain availability in #{location(location)} #{status}"
+            end
+
+    blurb += ' and other locations.' if other_availability.present?
+
+    # We are generating HTML in this helper, so we need to mark it as safe or it will be escaped in the view.
+    blurb.html_safe
+  end
+
+  # Fontawesome helper. Currently only takes the icon name and assumes solid sharp style.
+  # Could be extended later to default to these styles but allow overrides if appropriate.
+  # Also defaults to aria-hidden true, which is probably what we want for icons used
+  # purely for decoration. If an icon is used in a more meaningful way, we may want to extend this helper
+  # to allow passing in additional aria attributes.
+  def icon(fa)
+    "<i class='fa-sharp fa-solid fa-#{fa} aria-hidden='true''></i>"
+  end
+
+  # Formats location information for availability display.
+  # Expects an array with three elements: [library name, location name, call number]
+  def location(loc)
+    "<strong>#{loc[0]}</strong> #{loc[1]} (#{loc[2]})"
+  end
 end

app/models/normalize_primo_record.rb

@@ -280,7 +280,7 @@ def location
     return unless @record['delivery']['bestlocation']
 
     loc = @record['delivery']['bestlocation']
-    ["#{loc['mainLocation']} #{loc['subLocation']}", loc['callNumber']]
+    [loc['mainLocation'], loc['subLocation'], loc['callNumber']]
   end
 
   def subjects

app/views/search/_result_primo.html.erb

@@ -38,6 +38,9 @@
       <% if result[:links].present? %>
         <% result[:links].each do |link| %>
           <%= link_to link['kind'].titleize, link['url'], class: 'button' %>
+          <% if result[:availability].present? %>
+            <span class="availability"><%= availability(result[:availability], result[:location], result[:other_availability]) %></span>
+          <% end %>
         <% end %>
       <% end %>
     </div>

test/helpers/results_helper_test.rb

@@ -17,4 +17,24 @@ class ResultsHelperTest < ActionView::TestCase
     hits = 9000
     assert_equal '9,000 results', results_summary(hits)
   end
+
+  test 'availability helper handles known statuses correctly' do
+    location = ['Main Library', 'First Floor', 'QA76.73.R83 2023']
+
+    available_blurb = availability('available', location, false)
+    assert_includes available_blurb, 'Available in'
+    assert_includes available_blurb, location(location)
+
+    check_holdings_blurb = availability('check_holdings', location, false)
+    assert_includes check_holdings_blurb, 'May be available in'
+    assert_includes check_holdings_blurb, location(location)
+
+    unavailable_blurb = availability('unavailable', location, false)
+    assert_includes unavailable_blurb, 'Not currently available in'
+    assert_includes unavailable_blurb, location(location)
+
+    unknown_blurb = availability('unknown_status', location, false)
+    assert_includes unknown_blurb, 'Uncertain availability in'
+    assert_includes unknown_blurb, location(location)
+  end
 end

test/models/normalize_primo_record_test.rb

@@ -174,7 +174,7 @@ def cdi_record
 
   test 'returns best location with call number' do
     normalized = NormalizePrimoRecord.new(full_record, 'test').normalize
-    expected_location = ['Hayden Library Stacks', 'QA76.73.R83 2023']
+    expected_location = ['Hayden Library', 'Stacks', 'QA76.73.R83 2023']
     assert_equal expected_location, normalized[:location]
   end