Implement natural language search opt-in

Why these changes are being introduced:

We want users to be able to decide whether to use
hybrid (termed 'natural language search' in the
public UI) or lexical search. USE-577 implemented
the frontend work on this feature; this ticket
implements the controller layer.

Relevant ticket(s):

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

How this addresses that need:

This adds natural language search opt-in cookie,
which is toggled via a stimulus controller. When
the cookie is set, hybrid search is the default
query mode. When it is not set, the query mode
falls back to lexical search (or other default
mode specified by env).

This behavior can be overridden by supplying a
`queryMode` param manually. For example, if a user
has the NLS cookie set but adds `queryMode=semantic`
to their query string, the search will execute
in semantic mode, not hybrid.

If NLS is not available for a given tab, a
message displays to notify the user of the
limitation.

Side effects of this change:

Tests for this feature are stored in a separate
file. This is different from how we usually do
things, but there are so many conditions to test
that I did not want to pollute the search
controller test file further.

Author: jazairi

app/controllers/application_controller.rb

@@ -1,6 +1,8 @@
 class ApplicationController < ActionController::Base
   helper Mitlibraries::Theme::Engine.helpers
 
+  before_action :set_natural_language_search_optin
+
   # Set active tab based on params (no persistent cookie). This intentionally
   # avoids storing the user's last-used tab in a cookie per UXWS request.
   def set_active_tab
@@ -31,4 +33,8 @@ def all_tabs
   def valid_tab?(tab)
     all_tabs.include?(tab)
   end
+
+  def set_natural_language_search_optin
+    @natural_language_search_optin = cookies[:natural_language_search_optin] == 'true'
+  end
 end

app/controllers/search_controller.rb

@@ -16,7 +16,11 @@ def results
     # inject session preference for boolean type if it is present
     params[:booleanType] = cookies[:boolean_type] || 'AND'
 
+    # inject queryMode from cookie if not provided in URL params
+    params[:queryMode] = 'hybrid' if params[:queryMode].blank? && cookies[:natural_language_search_optin] == 'true'
+
     @enhanced_query = Enhancer.new(params).enhanced_query
+    @show_nls_warning = show_nls_warning?
 
     # Load GeoData results if applicable
     if Feature.enabled?(:geodata)
@@ -442,4 +446,10 @@ def valid_token?
 
     false
   end
+
+  # show_nls_warning? determines if the user should see a warning that results are not using natural language search.
+  # Shows when: user is opted-in AND viewing a Primo-only tab (which only supports keyword search).
+  def show_nls_warning?
+    @natural_language_search_optin && primo_tabs.include?(@active_tab)
+  end
 end

app/controllers/static_controller.rb

@@ -1,3 +1,5 @@
+require 'uri'
+
 class StaticController < ApplicationController
   def style_guide; end
 
@@ -10,4 +12,29 @@ def boolpref
 
     redirect_back_or_to root_path
   end
+
+  def natural_language_search_optin
+    optin = params[:natural_language_search_optin]
+    if %w[true false].include?(optin)
+      cookies[:natural_language_search_optin] = optin
+    else
+      cookies.delete :natural_language_search_optin
+    end
+
+    # Redirect to return_to param if it's a safe local path, otherwise root
+    return_to = params[:return_to].presence
+    safe_return_to = nil
+    if return_to
+      begin
+        parsed = URI.parse(return_to)
+        # Only allow local paths with no host or scheme
+        if parsed.path&.start_with?('/') && !return_to.start_with?('//') && parsed.host.nil? && parsed.scheme.nil?
+          safe_return_to = return_to
+        end
+      rescue URI::InvalidURIError
+        safe_return_to = nil
+      end
+    end
+    redirect_to(safe_return_to || root_path)
+  end
 end

app/javascript/controllers/natural_language_search_toggle_controller.js

@@ -0,0 +1,25 @@
+import { Controller } from "@hotwired/stimulus"
+
+export default class extends Controller {
+  toggle(event) {
+    event.preventDefault()
+    
+    const isCurrentlyOn = this.element.classList.contains('toggled-on')
+    const newState = isCurrentlyOn ? 'false' : 'true'
+    
+    this.setOptinState(newState)
+  }
+
+  setOptinState(state) {
+    // Build the redirect URL to return to the current results page
+    const redirectUrl = window.location.pathname + window.location.search
+    
+    // Make a GET request to the toggle endpoint
+    const url = new URL('/natural_language_search_optin', window.location.origin)
+    url.searchParams.set('natural_language_search_optin', state)
+    url.searchParams.set('return_to', redirectUrl)
+    
+    // Navigate to the toggle URL, which will redirect back with the new cookie set
+    window.location.href = url.toString()
+  }
+}

app/views/search/_form.html.erb

@@ -11,8 +11,8 @@
   </div>
   <div class="search-actions">
     <a href="https://libraries.mit.edu/search-advanced" data-matomo-click="Search, Advanced Search Engaged, Tab: {{getActiveTabName}}">Advanced search</a>
-    <div class="semantic-search-toggle toggled-off" data-matomo-seen="Semantic Search Toggle, Seen by user, Tab: {{getActiveTabName}}">
-      <button type="button" data-matomo-click="Semantic Search Toggle, Toggle Clicked, Was: {{getToggleState}}">Natural language search</button>
+    <div class="semantic-search-toggle <%= @natural_language_search_optin ? 'toggled-on' : 'toggled-off' %>" data-controller="natural-language-search-toggle" data-matomo-seen="Semantic Search Toggle, Seen by user, Tab: {{getActiveTabName}}">
+      <button type="button" aria-pressed="<%= @natural_language_search_optin %>" data-action="click->natural-language-search-toggle#toggle" data-matomo-click="Semantic Search Toggle, Toggle Clicked, Was: {{getToggleState}}">Natural language search</button>
       <a href="#" data-matomo-click="Semantic Search Toggle, Learn more Clicked, Tab: {{getActiveTabName}}">Learn more</a>
     </div>
   </div>

app/views/search/results.html.erb

@@ -18,7 +18,10 @@
       <% elsif @results.present? && @errors.blank? %>
 
         <h2 class="results-context" data-matomo-seen="Search, Results Found, Tab: {{getActiveTabName}}"><%= results_summary(@pagination[:hits]) %></h2>
-        <%= render partial: 'search/nls_alert' %>
+        <p class="results-context-description"><%= tab_description %></p>
+        <% if @show_nls_warning %>
+          <%= render partial: 'search/nls_alert' %>
+        <% end %>
         <div id="results-layout-wrapper">
           <main id="results">
             <ol class="results-list use" data-matomo-click="Results, Link Engaged, Link: {{getElementText}}; Tab: {{getActiveTabName}}" start="<%= @pagination[:start] %>">

config/routes.rb

@@ -17,6 +17,7 @@
   get 'style-guide', to: 'static#style_guide'
 
   get 'boolpref', to: 'static#boolpref'
+  get 'natural_language_search_optin', to: 'static#natural_language_search_optin'
 
   get 'robots.txt', to: 'robots#robots'
 end