blacklight 7.5.1 → 7.9.0

data/app/components/blacklight/facet_field_component.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Blacklight
+  class FacetFieldComponent < ::ViewComponent::Base
+    with_content_areas :label, :body
+
+    def initialize(facet_field:)
+      @facet_field = facet_field
+    end
+  end
+end

data/app/components/blacklight/facet_field_list_component.html.erb

@@ -0,0 +1,18 @@
+<%= render(@layout.new(facet_field: @facet_field)) do |component| %>
+  <% component.with(:label) do %>
+    <%= @facet_field.label %>
+  <% end %>
+  <% component.with(:body) do %>
+    <ul class="facet-values list-unstyled">
+      <%= render_facet_limit_list @facet_field.paginator, @facet_field.key %>
+    </ul>
+    <%# backwards compatibility, ugh %>
+    <% if @layout == Blacklight::FacetFieldNoLayoutComponent && !@facet_field.in_modal? && @facet_field.modal_path %>
+      <div class="more_facets">
+        <%= link_to t("more_#{@facet_field.key}_html", scope: 'blacklight.search.facets', default: :more_html, field_name: @facet_field.label),
+          @facet_field.modal_path,
+          data: { blacklight_modal: 'trigger' } %>
+      </div>
+    <% end %>
+  <% end %>
+<% end %>

data/app/components/blacklight/facet_field_list_component.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Blacklight
+  class FacetFieldListComponent < ::ViewComponent::Base
+    def initialize(facet_field:, layout: nil)
+      @facet_field = facet_field
+      @layout = layout == false ? FacetFieldNoLayoutComponent : Blacklight::FacetFieldComponent
+    end
+
+    # Here for backwards compatibility only.
+    # @private
+    def render_facet_limit_list(*args)
+      Deprecation.silence(Blacklight::FacetsHelperBehavior) do
+        @view_context.render_facet_limit_list(*args)
+      end
+    end
+
+    def render?
+      @facet_field.paginator.items.any?
+    end
+  end
+end

data/app/components/blacklight/facet_field_no_layout_component.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Blacklight
+  class FacetFieldNoLayoutComponent < ::ViewComponent::Base
+    with_content_areas :label, :body
+
+    def initialize(**); end
+
+    def call
+      body
+    end
+  end
+end

data/app/components/blacklight/facet_item_component.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Blacklight
+  class FacetItemComponent < ::ViewComponent::Base
+    with_collection_parameter :facet_item
+
+    def initialize(facet_item:, wrapping_element: 'li', suppress_link: false)
+      @facet_item = facet_item
+      @label = facet_item.label
+      @hits = facet_item.hits
+      @href = facet_item.href
+      @selected = facet_item.selected?
+      @wrapping_element = wrapping_element
+      @suppress_link = suppress_link
+    end
+
+    def call
+      # if the downstream app has overridden the helper methods we'd usually call,
+      # use the helpers to preserve compatibility
+      content = if overridden_helper_methods?
+                  content_from_legacy_view_helper
+                elsif @selected
+                  render_selected_facet_value
+                else
+                  render_facet_value
+                end
+
+      return if content.blank?
+      return content unless @wrapping_element
+
+      content_tag @wrapping_element, content
+    end
+
+    # This is a little shim to let us call the render methods below outside the
+    # usual component rendering cycle (for backward compatibility)
+    # @private
+    # @deprecated
+    def with_view_context(view_context)
+      @view_context = view_context
+      self
+    end
+
+    # Check if the downstream application has overridden these methods
+    # @deprecated
+    # @private
+    def overridden_helper_methods?
+      return false if explicit_component_configuration?
+
+      @view_context.method(:render_facet_item).owner != Blacklight::FacetsHelperBehavior ||
+        @view_context.method(:render_facet_value).owner != Blacklight::FacetsHelperBehavior ||
+        @view_context.method(:render_selected_facet_value).owner != Blacklight::FacetsHelperBehavior
+    end
+
+    # Call out to the helper method equivalent of this component
+    # @deprecated
+    # @private
+    def content_from_legacy_view_helper
+      Deprecation.warn('Calling out to the #render_facet_item helper for backwards compatibility.')
+      Deprecation.silence(Blacklight::FacetsHelperBehavior) do
+        @view_context.render_facet_item(@facet_item.facet_field, @facet_item.facet_item)
+      end
+    end
+
+    ##
+    # Standard display of a facet value in a list. Used in both _facets sidebar
+    # partial and catalog/facet expanded list. Will output facet value name as
+    # a link to add that to your restrictions, with count in parens.
+    #
+    # @param [Blacklight::Solr::Response::Facets::FacetField] facet_field
+    # @param [Blacklight::Solr::Response::Facets::FacetItem] item
+    # @param [Hash] options
+    # @option options [Boolean] :suppress_link display the facet, but don't link to it
+    # @return [String]
+    # @private
+    def render_facet_value
+      content_tag(:span, class: "facet-label") do
+        link_to_unless(@suppress_link, @label, @href, class: "facet-select")
+      end + render_facet_count
+    end
+
+    ##
+    # Standard display of a SELECTED facet value (e.g. without a link and with a remove button)
+    # @see #render_facet_value
+    # @param [Blacklight::Solr::Response::Facets::FacetField] facet_field
+    # @param [String] item
+    # @private
+    def render_selected_facet_value
+      content_tag(:span, class: "facet-label") do
+        content_tag(:span, @label, class: "selected") +
+          # remove link
+          link_to(@href, class: "remove") do
+            content_tag(:span, '✖', class: "remove-icon") +
+              content_tag(:span, '[remove]', class: 'sr-only')
+          end
+      end + render_facet_count(classes: ["selected"])
+    end
+
+    ##
+    # Renders a count value for facet limits. Can be over-ridden locally
+    # to change style. And can be called by plugins to get consistent display.
+    #
+    # @param [Integer] num number of facet results
+    # @param [Hash] options
+    # @option options [Array<String>]  an array of classes to add to count span.
+    # @return [String]
+    # @private
+    def render_facet_count(options = {})
+      return @view_context.render_facet_count(@hits, options) unless @view_context.method(:render_facet_count).owner == Blacklight::FacetsHelperBehavior || explicit_component_configuration?
+
+      classes = (options[:classes] || []) << "facet-count"
+      content_tag("span", t('blacklight.search.facets.count', number: number_with_delimiter(@hits)), class: classes)
+    end
+
+    private
+
+    def explicit_component_configuration?
+      @facet_item.facet_config.item_component.present?
+    end
+  end
+end

data/app/components/blacklight/facet_item_pivot_component.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Blacklight
+  # Render facet items and any subtree
+  class FacetItemPivotComponent < ::ViewComponent::Base
+    # Somewhat arbitrary number; the only important thing is that
+    # it is bigger than the number of leaf nodes in any collapsing
+    # pivot facet on the page.
+    ID_COUNTER_MAX = 2**20 - 1
+
+    # Mint a (sufficiently) unique identifier, so we can associate
+    # the expand/collapse control with labels
+    def self.mint_id
+      @id_counter = ((@id_counter || 0) + 1) % ID_COUNTER_MAX
+
+      # We convert the ID to hex for markup compactness
+      @id_counter.to_s(16)
+    end
+
+    with_collection_parameter :facet_item
+
+    def initialize(facet_item:, wrapping_element: 'li', suppress_link: false, collapsing: nil)
+      @facet_item = facet_item
+      @wrapping_element = wrapping_element
+      @suppress_link = suppress_link
+      @collapsing = collapsing.nil? ? facet_item.facet_config.collapsing : collapsing
+      @icons = { show: '⊞', hide: '⊟' }.merge(facet_item.facet_config.icons || {})
+    end
+
+    def call
+      facet = Blacklight::FacetItemComponent.new(facet_item: @facet_item, wrapping_element: nil, suppress_link: @suppress_link)
+
+      id = "h-#{self.class.mint_id}" if @collapsing && has_items?
+
+      content_tag @wrapping_element, role: 'treeitem' do
+        concat facet_toggle_button(id) if has_items? && @collapsing
+        concat content_tag('span', render_component(facet), class: "facet-values #{'facet-leaf-node' if has_items? && @collapsing}", id: id && "#{id}_label")
+
+        if has_items?
+          concat(content_tag('ul', class: "pivot-facet list-unstyled #{'collapse' if @collapsing}", id: id, role: 'group') do
+            render_component(
+              self.class.with_collection(
+                @facet_item.items.map { |i| facet_item_presenter(i) }
+              )
+            )
+          end)
+        end
+      end
+    end
+
+    private
+
+    def has_items?
+      @facet_item.items.present?
+    end
+
+    def facet_toggle_button(id)
+      content_tag 'button', class: 'btn facet-toggle-handle collapsed',
+                            data: { toggle: 'collapse', target: "##{id}" },
+                            aria: { expanded: false, controls: id, describedby: "#{id}_label" } do
+        concat toggle_icon(:show)
+        concat toggle_icon(:hide)
+      end
+    end
+
+    def toggle_icon(type)
+      content_tag 'span', class: type do
+        concat @icons[type]
+        concat content_tag('span', t(type, scope: 'blacklight.search.facets.pivot'), class: 'sr-only')
+      end
+    end
+
+    # This is a little convoluted in Blacklight 7 in order to maintain backwards-compat
+    # with overrides of deprecated helpers. In 8.x, we can just call Component#render_in
+    # and call it a day
+    def render_component(component)
+      @view_context.render(component)
+    end
+
+    def facet_item_presenter(facet_item)
+      Blacklight::FacetItemPresenter.new(facet_item, @facet_item.facet_config, @view_context, @facet_item.facet_field, @facet_item.search_state)
+    end
+  end
+end

data/app/helpers/blacklight/blacklight_helper_behavior.rb

@@ -148,7 +148,8 @@ module Blacklight::BlacklightHelperBehavior
     document = args.first
 
     field = options[:field]
-    html_escape t(:"blacklight.search.index.#{document_index_view_type}.label", default: :'blacklight.search.index.label', label: index_field_label(document, field))
+    label = options[:label] || index_field_label(document, field)
+    html_escape t(:"blacklight.search.index.#{document_index_view_type}.label", default: :'blacklight.search.index.label', label: label)
   end
 
   ##
@@ -169,8 +170,9 @@ module Blacklight::BlacklightHelperBehavior
     document = args.first
 
     field = options[:field]
+    label = options[:label] || document_show_field_label(document, field)
 
-    t(:'blacklight.search.show.label', label: document_show_field_label(document, field))
+    t(:'blacklight.search.show.label', label: label)
   end
 
   ##

data/app/helpers/blacklight/catalog_helper_behavior.rb

@@ -40,8 +40,6 @@ module Blacklight::CatalogHelperBehavior
   # @param [RSolr::Resource] collection (or other Kaminari-compatible objects)
   # @return [String]
   def page_entries_info(collection, entry_name: nil)
-    return unless show_pagination? collection
-
     entry_name = if entry_name
                    entry_name.pluralize(collection.size, I18n.locale)
                  else
@@ -153,7 +151,7 @@ module Blacklight::CatalogHelperBehavior
   # @return [String]
   def render_document_sidebar_partial(document = nil)
     unless document
-      Deprecation.warn(self, 'render_document_sidebar_partial expects one argument ' /
+      Deprecation.warn(self, 'render_document_sidebar_partial expects one argument ' \
         '(@document) and you passed none. This behavior will be removed in version 8')
       document = @document
     end
@@ -279,7 +277,7 @@ module Blacklight::CatalogHelperBehavior
     facet_config = facet_configuration_for_field(facet)
     filter_label = facet_field_label(facet_config.key)
     filter_value = if values.size < 3
-                     values.map { |value| facet_display_value(facet, value) }.to_sentence
+                     values.map { |value| facet_item_presenter(facet_config, value, facet).label }.to_sentence
                    else
                      t('blacklight.search.page_title.many_constraint_values', values: values.size)
                    end

data/app/helpers/blacklight/configuration_helper_behavior.rb

@@ -91,10 +91,11 @@ module Blacklight::ConfigurationHelperBehavior
   end
 
   # Shortcut for commonly needed operation, look up display
-  # label for the key specified. Returns "Keyword" if a label
-  # can't be found.
+  # label for the key specified.
   def label_for_search_field(key)
     field_config = blacklight_config.search_fields[key]
+    return if key.nil? && field_config.nil?
+
     field_config ||= Blacklight::Configuration::NullField.new(key: key)
 
     field_config.display_label('search')

data/app/helpers/blacklight/facets_helper_behavior.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 module Blacklight::FacetsHelperBehavior
+  extend Deprecation
+  self.deprecation_horizon = 'blacklight 8.0'
+
   include Blacklight::Facet
 
   ##
@@ -14,7 +17,9 @@ module Blacklight::FacetsHelperBehavior
         '8.0.0')
       response = @response
     end
-    facets_from_request(fields, response).any? { |display_facet| should_render_facet?(display_facet) }
+    Deprecation.silence(Blacklight::FacetsHelperBehavior) do
+      facets_from_request(fields, response).any? { |display_facet| should_render_facet?(display_facet) }
+    end
   end
 
   ##
@@ -58,10 +63,29 @@ module Blacklight::FacetsHelperBehavior
   # @return [String]
   def render_facet_limit(display_facet, options = {})
     field_config = facet_configuration_for_field(display_facet.name)
-    return unless should_render_facet?(display_facet, field_config)
 
+    if field_config.component
+      component = field_config.component == true ? Blacklight::FacetFieldListComponent : field_config.component
+      return render(
+        component.new(
+          facet_field: facet_field_presenter(field_config, display_facet),
+          layout: (params[:action] == 'facet' ? false : options[:layout])
+        )
+      )
+    end
+
+    Deprecation.warn(Blacklight::FacetsHelperBehavior, 'Calling #render_facet_limit on a non-componentized'\
+      ' facet is deprecated and will be removed in Blacklight 8')
+
+    Deprecation.silence(Blacklight::FacetsHelperBehavior) do
+      return unless should_render_facet?(display_facet, field_config)
+    end
     options = options.dup
-    options[:partial] ||= facet_partial_name(display_facet)
+
+    Deprecation.silence(Blacklight::FacetsHelperBehavior) do
+      options[:partial] ||= facet_partial_name(display_facet)
+    end
+
     options[:layout] ||= "facet_layout" unless options.key?(:layout)
     options[:locals] ||= {}
     options[:locals][:field_name] ||= display_facet.name
@@ -76,12 +100,20 @@ module Blacklight::FacetsHelperBehavior
   # removes any elements where render_facet_item returns a nil value. This enables an application
   # to filter undesireable facet items so they don't appear in the UI
   def render_facet_limit_list(paginator, facet_field, wrapping_element = :li)
-    safe_join(paginator.items.map { |item| render_facet_item(facet_field, item) }.compact.map { |item| content_tag(wrapping_element, item) })
+    facet_config ||= facet_configuration_for_field(facet_field)
+
+    collection = paginator.items.map do |item|
+      facet_item_presenter(facet_config, item, facet_field)
+    end
+
+    render(facet_item_component_class(facet_config).with_collection(collection, wrapping_element: wrapping_element))
   end
+  deprecation_deprecate :render_facet_limit_list
 
   ##
   # Renders a single facet item
   def render_facet_item(facet_field, item)
+    deprecated_method(:render_facet_item)
     if facet_in_params?(facet_field, item.value)
       render_selected_facet_value(facet_field, item)
     else
@@ -104,6 +136,7 @@ module Blacklight::FacetsHelperBehavior
     facet_config ||= facet_configuration_for_field(display_facet.name)
     should_render_field?(facet_config, display_facet)
   end
+  deprecation_deprecate :should_render_facet?
 
   ##
   # Determine whether a facet should be rendered as collapsed or not.
@@ -114,8 +147,11 @@ module Blacklight::FacetsHelperBehavior
   # @param [Blacklight::Configuration::FacetField] facet_field
   # @return [Boolean]
   def should_collapse_facet? facet_field
-    !facet_field_in_params?(facet_field.key) && facet_field.collapse
+    Deprecation.silence(Blacklight::FacetsHelperBehavior) do
+      !facet_field_in_params?(facet_field.key) && facet_field.collapse
+    end
   end
+  deprecation_deprecate :should_collapse_facet?
 
   ##
   # The name of the partial to use to render a facet field.
@@ -130,6 +166,11 @@ module Blacklight::FacetsHelperBehavior
     name ||= "facet_pivot" if config.pivot
     name || "facet_limit"
   end
+  deprecation_deprecate :facet_partial_name
+
+  def facet_field_presenter(facet_config, display_facet)
+    Blacklight::FacetFieldPresenter.new(facet_config, display_facet, self)
+  end
 
   ##
   # Standard display of a facet value in a list. Used in both _facets sidebar
@@ -142,13 +183,9 @@ module Blacklight::FacetsHelperBehavior
   # @option options [Boolean] :suppress_link display the facet, but don't link to it
   # @return [String]
   def render_facet_value(facet_field, item, options = {})
-    path = path_for_facet(facet_field, item)
-    content_tag(:span, class: "facet-label") do
-      link_to_unless(options[:suppress_link],
-                     facet_display_value(facet_field, item),
-                     path,
-                     class: "facet-select")
-    end + render_facet_count(item.hits)
+    deprecated_method(:render_facet_value)
+    facet_config = facet_configuration_for_field(facet_field)
+    facet_item_component(facet_config, item, facet_field, **options).render_facet_value
   end
 
   ##
@@ -158,12 +195,9 @@ module Blacklight::FacetsHelperBehavior
   # @return [String]
   def path_for_facet(facet_field, item, path_options = {})
     facet_config = facet_configuration_for_field(facet_field)
-    if facet_config.url_method
-      send(facet_config.url_method, facet_field, item)
-    else
-      search_action_path(search_state.add_facet_params_and_redirect(facet_field, item).merge(path_options))
-    end
+    facet_item_presenter(facet_config, item, facet_field).href(path_options)
   end
+  deprecation_deprecate :path_for_facet
 
   ##
   # Standard display of a SELECTED facet value (e.g. without a link and with a remove button)
@@ -171,15 +205,9 @@ module Blacklight::FacetsHelperBehavior
   # @param [Blacklight::Solr::Response::Facets::FacetField] facet_field
   # @param [String] item
   def render_selected_facet_value(facet_field, item)
-    remove_href = search_action_path(search_state.remove_facet_params(facet_field, item))
-    content_tag(:span, class: "facet-label") do
-      content_tag(:span, facet_display_value(facet_field, item), class: "selected") +
-      # remove link
-      link_to(remove_href, class: "remove") do
-        content_tag(:span, '✖', class: "remove-icon") +
-        content_tag(:span, '[remove]', class: 'sr-only')
-      end
-    end + render_facet_count(item.hits, classes: ["selected"])
+    deprecated_method(:render_selected_facet_value)
+    facet_config = facet_configuration_for_field(facet_field)
+    facet_item_component(facet_config, item, facet_field).render_selected_facet_value
   end
 
   ##
@@ -191,18 +219,22 @@ module Blacklight::FacetsHelperBehavior
   # @option options [Array<String>]  an array of classes to add to count span.
   # @return [String]
   def render_facet_count(num, options = {})
+    deprecated_method(:render_facet_count)
     classes = (options[:classes] || []) << "facet-count"
     content_tag("span", t('blacklight.search.facets.count', number: number_with_delimiter(num)), class: classes)
   end
 
   ##
   # Are any facet restrictions for a field in the query parameters?
-  #
+  # @private
   # @param [String] field
   # @return [Boolean]
   def facet_field_in_params? field
-    facet_params(field).present?
+    config = facet_configuration_for_field(field)
+    search_state.has_facet? config
   end
+  # Left undeprecated for the sake of temporary backwards compatibility
+  # deprecation_deprecate :facet_field_in_params?
 
   ##
   # Check if the query parameters have the given facet field with the
@@ -212,18 +244,19 @@ module Blacklight::FacetsHelperBehavior
   # @param [String] item facet value
   # @return [Boolean]
   def facet_in_params?(field, item)
-    value = facet_value_for_facet_item(item)
-
-    (facet_params(field) || []).include? value
+    config = facet_configuration_for_field(field)
+    search_state.has_facet? config, value: facet_value_for_facet_item(item)
   end
+  deprecation_deprecate :facet_in_params?
 
   ##
   # Get the values of the facet set in the blacklight query string
   def facet_params field
     config = facet_configuration_for_field(field)
 
-    params[:f][config.key] if params[:f]
+    search_state.params.dig(:f, config.key)
   end
+  deprecation_deprecate :facet_params
 
   ##
   # Get the displayable version of a facet's value
@@ -231,30 +264,17 @@ module Blacklight::FacetsHelperBehavior
   # @param [Object] field
   # @param [String] item value
   # @return [String]
+  # @deprecated
   def facet_display_value field, item
+    deprecated_method(:facet_display_value)
     facet_config = facet_configuration_for_field(field)
-
-    value = if item.respond_to? :label
-              item.label
-            else
-              facet_value_for_facet_item(item)
-            end
-
-    if facet_config.helper_method
-      send facet_config.helper_method, value
-    elsif facet_config.query && facet_config.query[value]
-      facet_config.query[value][:label]
-    elsif facet_config.date
-      localization_options = facet_config.date == true ? {} : facet_config.date
-      l(Time.zone.parse(value), localization_options)
-    else
-      value
-    end
+    facet_item_presenter(facet_config, item, field).label
   end
 
   def facet_field_id facet_field
     "facet-#{facet_field.key.parameterize}"
   end
+  deprecation_deprecate :facet_field_id
 
   private
 
@@ -265,4 +285,27 @@ module Blacklight::FacetsHelperBehavior
       item
     end
   end
+
+  def facet_item_presenter(facet_config, facet_item, facet_field)
+    Blacklight::FacetItemPresenter.new(facet_item, facet_config, self, facet_field)
+  end
+
+  def facet_item_component(facet_config, facet_item, facet_field, **args)
+    facet_item_component_class(facet_config).new(facet_item: facet_item_presenter(facet_config, facet_item, facet_field), **args).with_view_context(self)
+  end
+
+  def facet_item_component_class(facet_config)
+    default_component = facet_config.pivot ? Blacklight::FacetItemPivotComponent : Blacklight::FacetItemComponent
+    facet_config.fetch(:item_component, default_component)
+  end
+
+  # We can't use .deprecation_deprecate here, because the new components need to
+  # see the originally defined location for these methods in order to properly
+  # call back into the helpers for backwards compatibility
+  def deprecated_method(method_name)
+    Deprecation.warn(Blacklight::FacetsHelperBehavior,
+                     Deprecation.deprecated_method_warning(Blacklight::FacetsHelperBehavior,
+                                                           method_name, {}),
+                     caller)
+  end
 end