blacklight_range_limit 8.5.0 → 9.0.0.beta2

data/blacklight_range_limit.gemspec

@@ -19,11 +19,11 @@ Gem::Specification.new do |s|
 
   s.add_dependency 'blacklight', '>= 7.25.2', '< 9'
   s.add_dependency 'view_component', ">= 2.54", "< 4"
-  s.add_dependency 'deprecation'
 
   s.add_development_dependency 'rspec', '~> 3.0'
   s.add_development_dependency 'rspec-rails'
   s.add_development_dependency 'capybara', '~> 3'
+  s.add_development_dependency 'capybara-screenshot', "~> 1.0"
   s.add_development_dependency 'sqlite3'
   s.add_development_dependency 'launchy'
   s.add_development_dependency 'solr_wrapper'

data/config/importmap.rb

@@ -0,0 +1,9 @@
+# our local js
+pin_all_from File.expand_path("../app/assets/javascripts/blacklight-range-limit", __dir__), under: "blacklight-range-limit", to: "blacklight-range-limit"
+
+
+# our dependencies also need to be pinned -- chart.js and it's single dependenchy.
+# But instead of including here, we generate into local app, so they can update version
+# numbers themselves if they want to, seems preferable.
+#
+# Chart.js will not work as a vendored pin at present, it has to be pin to "live" CDN.

data/config/locales/blacklight_range_limit.ar.yml

@@ -1,13 +1,18 @@
+---
 ar:
   blacklight:
     range_limit:
+      loading_html: تحميل
+      missing: غير معروف
       range_begin: "%{field_label} بداية المدة"
+      range_begin_short: يبدأ
       range_end: "%{field_label} نهاية المدة"
-      submit_limit: 'تطبيق'
-      remove_limit: 'حذف'
-      missing: 'غير معروف'
-      view_distribution: 'عرض التوزيع'
-      view_larger: 'عرض بحجم أكبر »'
-      results_range_html: 'تمتد النتائج الحالية من <span class="min">%{min}</span> إلى<span class="max">%{max}</span>'
-      single_html: '<span class="single" data-blrl-single="%{begin_value}">%{begin}</span>'
-      range_html: '<span class="from" data-blrl-begin="%{begin_value}">%{begin}</span> الى <span class="to" data-blrl-end="%{end_value}">%{end}</span>'
+      range_end_short: نهاية
+      range_html: <span class="from" data-blrl-begin="%{begin_value}">%{begin}</span> الى <span class="to" data-blrl-end="%{end_value}">%{end}</span>
+      range_list_heading: قائمة النطاق
+      remove_limit: حذف
+      results_range_html: تمتد النتائج الحالية من <span class="min">%{min}</span> إلى<span class="max">%{max}</span>
+      single_html: <span class="single" data-blrl-single="%{begin_value}">%{begin}</span>
+      submit_limit: تطبيق
+      view_distribution: عرض التوزيع
+      view_larger: عرض بحجم أكبر »

data/config/locales/blacklight_range_limit.de.yml

@@ -1,13 +1,18 @@
+---
 de:
   blacklight:
     range_limit:
+      loading_html: Laden...
+      missing: Unbekannt
       range_begin: "%{field_label} Bereichsanfang"
+      range_begin_short: Beginnen
       range_end: "%{field_label} Bereichsende"
-      submit_limit: 'Anwenden'
-      remove_limit: 'Entfernen'
-      missing: 'Unbekannt'
-      view_distribution: 'Verteilung Anzeigen'
-      view_larger: 'Größer anzeigen »'
-      results_range_html: 'Aktuelle Ergebnisse reichen von <span class="min">%{min}</span> bis <span class="max">%{max}</span>'
-      single_html: '<span class="single" data-blrl-single="%{begin_value}">%{begin}</span>'
-      range_html: '<span class="from" data-blrl-begin="%{begin_value}">%{begin}</span> bis <span class="to" data-blrl-end="%{end_value}">%{end}</span>'
+      range_end_short: Ende
+      range_html: <span class="from" data-blrl-begin="%{begin_value}">%{begin}</span> bis <span class="to" data-blrl-end="%{end_value}">%{end}</span>
+      range_list_heading: Bereichsliste
+      remove_limit: Entfernen
+      results_range_html: Aktuelle Ergebnisse reichen von <span class="min">%{min}</span> bis <span class="max">%{max}</span>
+      single_html: <span class="single" data-blrl-single="%{begin_value}">%{begin}</span>
+      submit_limit: Anwenden
+      view_distribution: Verteilung Anzeigen
+      view_larger: Größer anzeigen »

data/config/locales/blacklight_range_limit.en.yml

@@ -2,8 +2,10 @@ en:
   blacklight:
     range_limit:
       range_begin: "%{field_label} range begin"
+      range_begin_short: "Begin"
       range_end: "%{field_label} range end"
-      submit_limit: 'Apply'
+      range_end_short: "End"
+      submit_limit: 'Apply limit'
       remove_limit: 'remove'
       missing: 'Unknown'
       view_distribution: 'View distribution'
@@ -11,3 +13,5 @@ en:
       results_range_html: 'Current results range from <span class="min">%{min}</span> to <span class="max">%{max}</span>'
       single_html: '<span class="single" data-blrl-single="%{begin_value}">%{begin}</span>'
       range_html: '<span class="from" data-blrl-begin="%{begin_value}">%{begin}</span> to <span class="to" data-blrl-end="%{end_value}">%{end}</span>'
+      loading_html: "Loading..."
+      range_list_heading: "Range List"

data/config/locales/blacklight_range_limit.es.yml

@@ -0,0 +1,18 @@
+---
+es:
+  blacklight:
+    range_limit:
+      loading_html: Cargando...
+      missing: Desconocido
+      range_begin: Rango %{field_label} inicio
+      range_begin_short: Comenzar
+      range_end: Fin del rango %{field_label}
+      range_end_short: Fin
+      range_html: <span class="from" data-blrl-begin="%{begin_value}">%{begin}</span> a <span class="to" data-blrl-end="%{end_value}">%{end}</span>
+      range_list_heading: Lista de rangos
+      remove_limit: eliminar
+      results_range_html: Los resultados actuales varían de <span class="min">%{min}</span> a <span class="max">%{max}</span>
+      single_html: <span class="single" data-blrl-single="%{begin_value}">%{begin}</span>
+      submit_limit: Aplicar
+      view_distribution: Ver distribución
+      view_larger: Ver más grande »

data/config/locales/blacklight_range_limit.it.yml

@@ -1,13 +1,18 @@
+---
 it:
   blacklight:
     range_limit:
+      loading_html: Caricamento...
+      missing: Data sconosciuta
       range_begin: "%{field_label} da"
+      range_begin_short: Inizio
       range_end: "%{field_label} a"
-      submit_limit: 'Invia'
-      remove_limit: 'cancella'
-      missing: 'Data sconosciuta'
-      view_distribution: 'Visualizzazione della distribuzione'
-      view_larger: 'Visualizza più grande »'
-      results_range_html: 'Risultati attuali vanno da <span class="min">%{min}</span> a <span class="max">%{max}</span>'
-      single_html: '<span class="single" data-blrl-single="%{begin_value}">%{begin}</span>'
-      range_html: '<span class="from" data-blrl-begin="%{begin_value}">%{begin}</span> a <span class="to" data-blrl-end="%{end_value}">%{end}</span>'
+      range_end_short: Fine
+      range_html: <span class="from" data-blrl-begin="%{begin_value}">%{begin}</span> a <span class="to" data-blrl-end="%{end_value}">%{end}</span>
+      range_list_heading: Elenco intervalli
+      remove_limit: cancella
+      results_range_html: Risultati attuali vanno da <span class="min">%{min}</span> a <span class="max">%{max}</span>
+      single_html: <span class="single" data-blrl-single="%{begin_value}">%{begin}</span>
+      submit_limit: Invia
+      view_distribution: Visualizzazione della distribuzione
+      view_larger: Visualizza più grande »

data/lib/blacklight_range_limit/controller_override.rb

@@ -4,44 +4,22 @@
 require 'blacklight_range_limit/segment_calculation'
 module BlacklightRangeLimit
   module ControllerOverride
-    extend Deprecation
     extend ActiveSupport::Concern
 
     RANGE_LIMIT_FIELDS = [:range_end, :range_field, :range_start].freeze
 
-    included do
-      before_action do
-        template = lookup_context.find_all('blacklight_range_limit/range_limit_panel', lookup_context.prefixes + [""], true, [:field_name], {}).first
-
-        if template
-          fields = blacklight_config.facet_fields.select { |_k, v| v.range && !v.had_existing_component_configuration }
-
-          fields.each_value do |facet_config|
-            Deprecation.warn(BlacklightRangeLimit, 'Found partial blacklight_range_limit/range_limit_panel, so falling back to legacy behavior.') unless facet_config.partial
-            facet_config.partial ||= 'blacklight_range_limit/range_limit_panel'
-            facet_config.component = nil
-          end
-        else
-          fields = blacklight_config.facet_fields.select { |_k, v| v.partial == 'blacklight_range_limit/range_limit_panel' }
-          fields.each_value do |facet_config|
-            Deprecation.warn(BlacklightRangeLimit, 'Ignoring partial configuration for missing blacklight_range_limit/range_limit_panel partial')
-            facet_config.partial = nil
-          end
-        end
-
-        # Blacklight 7.25+: Allow range limit params if necessary
-        if blacklight_config.search_state_fields
-          missing_keys = RANGE_LIMIT_FIELDS - blacklight_config.search_state_fields
-          blacklight_config.search_state_fields.concat(missing_keys)
-        end
-      end
-    end
-
     # Action method of our own!
     # Delivers a _partial_ that's a display of a single fields range facets.
     # Used when we need a second Solr query to get range facets, after the
     # first found min/max from result set.
     def range_limit
+      # The builder in this action will need our special range_limit fields, so we
+      # must allow them.
+      if blacklight_config.search_state_fields
+        missing_keys = RANGE_LIMIT_FIELDS - blacklight_config.search_state_fields
+        blacklight_config.search_state_fields.concat(missing_keys)
+      end
+
       @facet = blacklight_config.facet_fields[params[:range_field]]
       raise ActionController::RoutingError, 'Not Found' unless @facet&.range
 
@@ -59,12 +37,7 @@ module BlacklightRangeLimit
 
       @presenter = (@facet.presenter || BlacklightRangeLimit::FacetFieldPresenter).new(@facet, display_facet, view_context)
 
-      render 'blacklight_range_limit/range_segments', locals: { facet_field: @presenter }, layout: !request.xhr?
-    end
-
-    def range_limit_panel
-      Deprecation.warn(BlacklightRangeLimit::ControllerOverride, 'range_limit_panel is deprecated; use the normal facet modal route instead')
-      facet
+      render BlacklightRangeLimit::RangeSegmentsComponent.new(facet_field: @presenter), layout: !request.xhr?
     end
 
     class_methods do

data/lib/blacklight_range_limit/engine.rb

@@ -3,11 +3,59 @@ require 'blacklight_range_limit'
 require 'rails'
 
 module BlacklightRangeLimit
+  # delegate for easier configability
+  def self.config
+    Engine.config
+  end
+
   class Engine < Rails::Engine
     config.action_dispatch.rescue_responses.merge!(
       "BlacklightRangeLimit::InvalidRange" => :not_acceptable
     )
 
+
+    config.using_importmaps = nil
+    config.using_importmaps_sprockets = nil
+
+    initializer "blacklight_range_limit.asset_mode_config" do |app|
+      # We guess based on what's in the app which is normally good enough,
+      # but you can set eg BlacklightRangeLimit.config.using_importmaps directly
+      # in your config/application.rb if the guess was not right for your environment.
+
+      if config.using_importmaps.nil?
+        config.using_importmaps = begin
+          Pathname(Rails.application.root).join("config/importmap.rb").exist? && app.config.respond_to?(:importmap)
+        end
+      end
+
+      if config.using_importmaps_sprockets.nil?
+        config.using_importmaps_sprockets ||= begin
+          config.using_importmaps && defined?(Sprockets) && !defined?(Propshaft)
+        end
+      end
+    end
+
+    # TODO:  Config for using_importmaps and
+    # move source elsewhere so it's not in asset path with propshaft putting
+    # it in public, unless you actually want that?  Only want that if we have propshaft and importmaps?
+
+    # TODO only turn this on if we're supporting sprockets-direct-importmaps combo
+    initializer "blacklight_range_limit.assets.precompile" do |app|
+      # IF they are using SPROCKETS *and* importmaps directly to engine files, then we
+      # need to tell sprockets all our JS files need to be available via HTTP, like
+      # so
+      if BlacklightRangeLimit.config.using_importmaps_sprockets
+        app.config.assets.precompile += ["blacklight-range-limit/index.js"]
+      end
+    end
+
+    initializer "blacklight_range_limit.importmap", before: "importmap" do |app|
+      if BlacklightRangeLimit.config.using_importmaps
+        app.config.importmap.paths << Engine.root.join("config/importmap.rb")
+        app.config.importmap.cache_sweepers << Engine.root.join("app/assets/javascripts/blacklight-range-limit")
+      end
+    end
+
     config.before_configuration do
       Blacklight::Configuration::FacetField.prepend BlacklightRangeLimit::FacetFieldConfigOverride
     end

data/lib/blacklight_range_limit/range_limit_builder.rb

@@ -22,12 +22,14 @@ module BlacklightRangeLimit
         solr_params["stats.field"] << config.field
 
         range_config = config.range_config
-        next if range_config[:segments] == false
+        next unless range_config[:chart_js] || range_config[:textual_facets]
 
         selected_value = search_state.filter(config.key).values.first
-        range = (selected_value if selected_value.is_a? Range) || range_config[:assumed_boundaries]
 
-        add_range_segments_to_solr!(solr_params, field_key, range.first, range.last) if range.present?
+        range = bl_create_selected_range_value(selected_value, config)
+
+        # If we have both ends of a range
+        add_range_segments_to_solr!(solr_params, field_key, range.begin, range.end) if range && range.count != Float::INFINITY
       end
 
       solr_params
@@ -61,5 +63,61 @@ module BlacklightRangeLimit
       return solr_params
     end
 
+    # hacky polyfill for new Blacklight behavior we need, if we don't have it yet
+    #
+    # https://github.com/projectblacklight/blacklight/pull/3213
+    # https://github.com/projectblacklight/blacklight/pull/3443
+    bl_version = Gem.loaded_specs["blacklight"]&.version
+    if bl_version && (bl_version <= Gem::Version.new("8.6.1"))
+      def facet_value_to_fq_string(facet_field, value, use_local_params: true)
+        facet_config = blacklight_config.facet_fields[facet_field]
+
+        # if it's an one-end range, and condition from original that would use query instead isn't met
+        if value.is_a?(Range) && (value.count == Float::INFINITY) && !facet_config&.query
+          # Adapted from
+          # https://github.com/projectblacklight/blacklight/blob/1494bd0884efe7a48623e9b37abe558fa6348e2a/lib/blacklight/solr/search_builder_behavior.rb#L362-L366
+
+          solr_field = facet_config.field if facet_config && !facet_config.query
+          solr_field ||= facet_field
+
+          local_params = []
+          local_params << "tag=#{facet_config.tag}" if use_local_params && facet_config && facet_config.tag
+
+          prefix = "{!#{local_params.join(' ')}}" unless local_params.empty?
+
+          "#{prefix}#{solr_field}:[#{value.begin || "*"} TO #{value.end || "*"}]"
+        else
+          super
+        end
+      end
+    end
+
+    # @returns Range or nil
+    #
+    # Range created from a range value or from assumed boundaries if present, and clamped between min and max
+    def bl_create_selected_range_value(selected_value, field_config)
+      range_config = field_config.range_config
+
+      range = if selected_value.is_a? Range
+        selected_value
+      elsif range_config[:assumed_boundaries].is_a?(Range)
+        range_config[:assumed_boundaries]
+      elsif range_config[:assumed_boundaries] # Array of two things please
+        Range.new(*range_config[:assumed_boundaries])
+      else
+        nil
+      end
+
+      # clamp between config'd min and max
+      min = range_config[:min_value]
+      max = range_config[:max_value]
+
+      range = Range.new(
+        (range.begin.clamp(min, max) if range.begin),
+        (range.end.clamp(min, max) if range.end),
+      ) if range
+
+      range
+    end
   end
 end

data/lib/blacklight_range_limit.rb

@@ -1,9 +1,5 @@
 # BlacklightRangeLimit
-require 'deprecation'
-
 module BlacklightRangeLimit
-  extend Deprecation
-
   require 'blacklight_range_limit/facet_field_config_override'
   require 'blacklight_range_limit/range_limit_builder'
   require 'blacklight_range_limit/controller_override'
@@ -19,41 +15,25 @@ module BlacklightRangeLimit
   mattr_accessor :classes
 
   self.classes = {
-    form: 'range_limit subsection form-inline',
-    submit: 'submit btn btn-secondary'
+    form: 'range_limit_form',
+    submit: 'submit btn btn-sm btn-secondary'
   }
 
-  # Add element to array only if it's not already there
-  def self.safe_arr_add(array, element)
-    Deprecation.warn(BlacklightRangeLimit, 'BlacklightRangeLimit.safe_arr_add is deprecated without replacement')
-    array << element unless array.include?(element)
-  end
-
-  def self.range_config(blacklight_config, solr_field)
-    Deprecation.warn(BlacklightRangeLimit, 'BlacklightRangeLimit.range_config is deprecated without replacement')
-    field = blacklight_config.facet_fields[solr_field.to_s]
-
-    return false unless field&.range
-
-    if field.range == true
-      default_range_config
-    else
-      field.range.merge(partial: field.partial)
-    end
-  end
-
   def self.default_range_config
     {
       range: true,
       range_config: {
         num_segments: 10,
         chart_js: true,
-        slider_js: true,
-        segments: true,
+        textual_facets: true,
+        textual_facets_collapsible: true,
+        show_missing_link: true,
+        chart_segment_border_color: 'rgb(54, 162, 235)',
+        chart_segment_bg_color: 'rgba(54, 162, 235, 0.5)',
+        chart_aspect_ratio: 2,
         assumed_boundaries: nil,
-        maxlength: nil,
-        input_label_range_begin: nil,
-        input_label_range_end: nil
+        min_value: -2_147_483_648, # solr intfield min and max
+        max_value: 2_147_483_648
       },
       filter_class: BlacklightRangeLimit::FilterField,
       presenter: BlacklightRangeLimit::FacetFieldPresenter,

data/lib/generators/blacklight_range_limit/assets_generator.rb

@@ -11,39 +11,103 @@
 # as suggested above.
 require 'rails/generators'
 require 'rails/generators/base'
+
 module BlacklightRangeLimit
   class AssetsGenerator < Rails::Generators::Base
     source_root File.join(BlacklightRangeLimit::Engine.root, 'app', 'assets')
 
-    def assets
-      application_css = Dir["app/assets/stylesheets/application{.css,.scss,.css.scss}"].first
+    # for vite-ruby you may set to eg 'app/frontend/entrypoints/application.js'
+    class_option :js_file, type: :string, default: "app/javascript/application.js"
+    class_option :yarn_local_package, type: :boolean, default: nil
+    class_option :asset_delivery_mode, type: :string, default: nil
+
+    attr_reader :option_js_file, :option_yarn_local_package, :option_asset_delivery_mode
 
-      if application_css
+    def set_default_options
+      @option_js_file = options[:js_file]
 
-        insert_into_file application_css, :before => "*/" do
-%q{
- *
- * Used by blacklight_range_limit
- *= require  'blacklight_range_limit'
- *
-}
+      @option_asset_delivery_mode = options[:asset_delivery_mode]
+      if option_asset_delivery_mode.nil?
+        # prefererntially default to importmap
+        if defined?(Importmap) && root.join("config/importmap.rb").exist?
+          @option_asset_delivery_mode = "importmap-rails"
+        elsif root.join("package.json").exist?
+          @option_asset_delivery_mode = "yarn-package"
+        else
+          raise ArgumentError.new("Could not identify asset_delivery_mode, try supplying --asset-delivery-mode=[importmap-rails|yarn-package]")
         end
-      else
-        say_status "warning", "Can not find application.css, did not insert our require", :red
       end
 
-      append_to_file "app/assets/javascripts/application.js" do
-%q{
+      unless option_asset_delivery_mode.in?(["importmap-rails", "yarn-package"])
+        raise ArgumentError.new("Illegal --asset-delivery-mode '#{option_asset_delivery_mode}', must be importmap-rails or yarn-package")
+      end
 
-// For blacklight_range_limit built-in JS, if you don't want it you don't need
-// this:
-//= require 'blacklight_range_limit'
+      @option_yarn_local_package = options[:yarn_local_package]
+      if option_yarn_local_package.nil?
+        # default guess by CI in ENV or app name that we use for test apps
+        @option_yarn_local_package = ENV['CI'].present? || Rails.application.class.name == "Internal::Application"
+      end
+    end
+
+    def add_to_package_json
+      # for apps using jsbundling_rails, vite-ruby, etc.
+      if option_asset_delivery_mode == "yarn-package"
+        say_status "info", "Adding blacklight-range-limit to package.json", :blue
+
+        if option_yarn_local_package
+          run "yarn add blacklight-range-limit@file:#{BlacklightRangeLimit::Engine.root}", abort_on_failure: true
+        else
+          # are we actually going to release one-to-one? Maybe just matching major
+          # version would be enough?
+          run "yarn add blacklight-range-limit@^#{BlacklightRangeLimit::VERSION.split(".").first}.0.0", abort_on_failure: true
+        end
+      else
+        say_status "info", "No package.json, not adding blacklight-range-limit npm package", :blue
+      end
+    end
 
-}
+    def dependencies_to_importmap_rb
+     if option_asset_delivery_mode == "importmap-rails"
+        # No need to pin "blacklight-range-limit", importmaps can find it when imported
+        # already, because our engine put it in importmap.paths
+        append_to_file("config/importmap.rb") do
+          # We'll want to update these version numbers periodically in source here, no other way to do it?
+          # And generated apps will have to manually update them too?
+          <<~EOS
+            # chart.js is dependency of blacklight-range-limit, currently is not working
+            # as vendored importmaps, but instead must be pinned to CDN. You may want to update
+            # versions perioidically.
+            pin "chart.js", to: "https://ga.jspm.io/npm:chart.js@4.2.0/dist/chart.js"
+            # single dependency of chart.js:
+            pin "@kurkle/color", to: "https://ga.jspm.io/npm:@kurkle/color@0.3.2/dist/color.esm.js"
+          EOS
+        end
+      else
+        say_status(:info, "no config/importmap.rb, so did not pin JS dependencies for blacklight-range-limit there", :yellow)
       end
     end
 
 
+    def import_and_start_in_application_js
+      if root.join(option_js_file).exist?
+        js_file_path = root.join(option_js_file).to_s
 
+        append_to_file js_file_path do
+          <<~EOS
+
+            import BlacklightRangeLimit from "blacklight-range-limit";
+            BlacklightRangeLimit.init({onLoadHandler: Blacklight.onLoad });
+          EOS
+        end
+      else
+        say_status(:warn, "No file detected at #{option_js_file} so JS setup not added", :yellow)
+      end
+    end
+
+    private
+
+    def root
+      @root ||= Pathname(destination_root)
+    end
   end
 end

data/lib/generators/blacklight_range_limit/install_generator.rb

@@ -4,10 +4,13 @@ module BlacklightRangeLimit
   class InstallGenerator < Rails::Generators::Base
     source_root File.expand_path('../templates', __FILE__)
 
+    class_option :'skip-assets', type: :boolean, default: false, desc: "Skip generation of assets into app"
     class_option :'builder-path', type: :string, default: 'app/models/search_builder.rb', aliases: "-b", desc: "Set the path, relative to Rails root, to the Blacklight app's search builder class"
 
-    def copy_public_assets
-      generate 'blacklight_range_limit:assets'
+    def generate_assets
+      unless options[:'skip-assets']
+        generate 'blacklight_range_limit:assets'
+      end
     end
 
     def install_catalog_controller_mixin

data/lib/generators/blacklight_range_limit/jsbundling_bl7_fixup_generator.rb

@@ -0,0 +1,98 @@
+require 'rails/generators'
+
+# FOR CI: NOT INTENDED FOR REAL APP
+#
+# We hackily get a BL7 app into a state jsbundling-rails/esbuild will work with it.
+#
+# May not work with all permutations of real-world apps, may do some hacks that get CI
+# to run but would break a real app!
+
+module BlacklightRangeLimit
+  class JsbundlingBl7FixupGenerator < Rails::Generators::Base
+    source_root File.expand_path("../../../../../spec/test_app_templates", __FILE__)
+
+    def guard_test_app_only
+      unless Rails.application.class.name == "Internal::Application"
+        raise "For safety, this generator can only be run in a test app, with app name 'test', not '#{Rails.application.name}'"
+      end
+    end
+
+    def add_blacklight_dependencies_to_package_json
+      # there is no blacklight 7.39.0 or 7.40.0 makes it hard for us to know what version to
+      # generate here, I guess we'll try generating an open range like "^7.0.0"?
+
+      # while blacklight7 may work with bootstrap 5, we'll test with 4 for now, and popper 1.x that goes with it
+      run %{yarn add --non-interactive
+              blacklight-frontend@^#{Blacklight::VERSION.split(".").first}.0.0
+              bootstrap@^4.1.0
+              popper.js@^1.16.0}.squish, abort_on_failure: true
+    end
+
+    # NOTE this is why you don't want to run this in a real app!!!
+    def remove_default_stimulus_code
+      # Due to a bug or something, import of stimulus will cause a problem with
+      # esbuild, in the presence of Blacklight layout's default application.js
+      # script tag lacking type=module
+      #
+      # generated BL app isn't using this stuff, we will just remove the include
+      #
+      # SEE: https://gist.github.com/pch/fe276b29ba037bdaeaa525932478ca18
+
+      gsub_file("app/javascript/application.js", %r{^ *import +["']\./controllers.*$}, '')
+    end
+
+    def add_blacklight7_esm_imports
+      js_dir = "app/javascript"
+      app_js_file = js_dir + "/application.js"
+
+      unless Pathname(app_js_file).exist?
+        raise "Cannot find file to set up at #{app_js_file}"
+      end
+
+      # Need to setup some things BEFORE actual blacklight imports, to work right
+      create_file (js_dir + "/blacklight_dependency_setup.js") do
+        <<~EOS
+          // Making JQuery from ESM available to Blacklight 7 and Bootstrap 4 that want
+          // it in window globals.
+          import $ from 'jquery'
+          window.jQuery = window.$ = $
+
+          // Bootstrap 4 also needs Popper, and needs it installed in window.Popper
+          import Popper from 'popper.js';
+          window.Popper = Popper;
+        EOS
+      end
+
+      append_to_file app_js_file do
+        <<~EOS
+          import "bootstrap";
+          import "./blacklight_dependency_setup.js"
+
+          //import 'blacklight-frontend/app/assets/javascripts/blacklight/blacklight';
+          // for some reason we need these all like this to work, can we figure out why?
+
+          import 'blacklight-frontend/app/javascript/blacklight/core';
+          import 'blacklight-frontend/app/javascript/blacklight/bookmark_toggle';
+          import 'blacklight-frontend/app/javascript/blacklight/button_focus';
+          import 'blacklight-frontend/app/javascript/blacklight/checkbox_submit';
+          import 'blacklight-frontend/app/javascript/blacklight/facet_load';
+          import 'blacklight-frontend/app/javascript/blacklight/modal';
+          import 'blacklight-frontend/app/javascript/blacklight/search_context';
+        EOS
+      end
+    end
+
+    def add_blacklight7_sass_esm_import
+      # only if we're using propshaft and not sprockets: We are using cssbundling-rails with
+      # sass, and we need to add a sass import from blacklight npm package -- that BL7 geenrator
+      # didn't know how to do.  (BL8 generator prob does!)
+      if !defined?(Sprockets) && defined?(Propshaft)
+        append_to_file 'app/assets/stylesheets/application.bootstrap.scss' do
+          <<~CONTENT
+            @import "blacklight-frontend/app/assets/stylesheets/blacklight/blacklight";
+          CONTENT
+        end
+      end
+    end
+  end
+end