active_admin_filter_extensions 1.0.0

data/lib/active_admin_filter_extensions/required_filters.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module ActiveAdminFilterExtensions
+  # `extensions: { required: }` - the mandatory window: a filter whose default applies whenever
+  # its own keys are absent, whatever else the request carries.
+  module RequiredFilters
+    protected
+
+    # The subset of the defaults that `required: true` promotes to mandatory, grouped per
+    # filter so each imposes itself all-or-nothing.
+    def required_filter_default_values
+      @required_filter_default_values ||= visible_filters.each_with_object({}) do |(attribute, options), result|
+        next unless options[:required]
+        unless options.key?(:default)
+          raise ArgumentError,
+                "filter :#{attribute} is required: true but declares no default: to fall back on"
+        end
+
+        # One materialization per request: the group shares filter_default_values' already
+        # validated (and sanitized) values instead of resolving the Procs a second time.
+        filter_default_values
+        group = filter_default_values.slice(*(@filter_default_keys || {})[attribute])
+        # Answered by ANY of the filter's own submitted keys, not only the ones its default
+        # happens to fill: an endless default must not inject a lower bound beside an
+        # upper-only request.
+        result[attribute] = { defaults: group, keys: policy_search_keys(attribute, options) }
+                            .merge(required_conditions(attribute, options))
+      end
+    end
+
+    # required: true is unconditional. A Hash narrows it: { if: keys } imposes the window only
+    # beside those keys, { unless: keys } excuses it beside those - a search pinpointing a
+    # record is not a scan to box in. Keys take a Symbol or an Array; both conditions combine.
+    def required_conditions(attribute, options)
+      return { if: [], unless: [] } unless options[:required].is_a?(Hash)
+
+      unknown = options[:required].keys - %i[if unless]
+      if unknown.any?
+        raise ArgumentError, "filter :#{attribute}: required: takes true or "                              "{ if:/unless: key(s) }, got #{unknown.map(&:inspect).join(', ')}"
+      end
+
+      { if: Array(options[:required][:if]).map(&:to_s),
+        unless: Array(options[:required][:unless]).map(&:to_s) }
+    end
+
+    # The required defaults this request has not answered: only the groups NONE of whose own
+    # keys the request carries, whose if: keys (if any) the request does carry, and none of
+    # whose unless: keys.
+    def required_filter_defaults_absent_from(requested)
+      required_filter_default_values.each_with_object({}) do |(_attribute, entry), result|
+        next if required_group_answered?(requested, entry[:keys])
+        next if entry[:if].any? && entry[:if].none? { |key| answered_value?(requested[key]) }
+        next if entry[:unless].any? { |key| answered_value?(requested[key]) }
+
+        result.merge!(entry[:defaults])
+      end
+    end
+
+    # Any predicate of the filter's own attribute is an answer about it - the admin picking
+    # "equals" on a :string filter submits title_eq where the derived key is title_cont, and
+    # completing that from the default searches two conditions on one column. Read exactly the
+    # way #any_declared_filter_answered? reads a question: an exact declared key, or a real
+    # predicate on the declared attribute - never a predicate-less stem Ransack ignores, which
+    # would switch a mandatory window off with a key that searches nothing.
+    def required_group_answered?(requested, keys)
+      bases = keys.map { |key| strip_ransack_predicate(key) }
+
+      requested.any? do |key, value|
+        next false unless answered_value?(value)
+
+        key = key.to_s
+        next true if keys.include?(key)
+
+        key != strip_ransack_predicate(key) && bases.include?(strip_ransack_predicate(key))
+      end
+    end
+
+    # `false` is a value, not a blank - the rule the normalized request already follows.
+    def answered_value?(value)
+      value.present? || value == false
+    end
+  end
+end

data/lib/active_admin_filter_extensions/search_keys.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module ActiveAdminFilterExtensions
+  # Which Ransack key(s) a filter's input actually submits - derived by building the input
+  # the way the sidebar would and asking it, so a declared value lands exactly where the
+  # form would put it.
+  module SearchKeys
+    private
+
+    # Asked against an empty search on purpose: `current_filter` otherwise answers with whatever
+    # predicate the current request happens to carry, and a default is about the request that
+    # carries none.
+    #
+    # @return [Array<String>] one key, or two for a range input
+    def filter_search_keys(attribute, options)
+      input = build_filter_input(attribute, options)
+
+      names =
+        if input.respond_to?(:gt_input_name)
+          [input.gt_input_name, input.lt_input_name]
+        elsif input.respond_to?(:current_filter) && !input.seems_searchable?
+          # `:string` and `:numeric` let the admin pick the predicate from a dropdown, and the
+          # head of that list is what an untouched form submits. Unless the filter name already
+          # carries a predicate, in which case there is no dropdown - and asking anyway raises,
+          # since `current_filter` would go looking for `title_eq_cont`.
+          [input.current_filter]
+        else
+          [input.input_name]
+        end
+
+      names.map { |name| name.to_s[/\Aq\[([^\]]+)\]/, 1] || name.to_s }
+      # Narrow on purpose: #policy_search_keys answers an ArgumentError from here by searching
+      # the declared filter name instead, so a catch-all would turn any internal failure into a
+      # policy quietly guarding the wrong key. A resource with no `ransack`, and an input class
+      # that does not exist, are both NameErrors - and they are what "cannot derive" means.
+    rescue NameError => e
+      raise_filter_default_error(attribute, "could not work out which search key it submits (#{e.class}: #{e.message}) - name the predicate with a Hash instead")
+    end
+
+    def build_filter_input(attribute, options)
+      builder = filter_input_builder
+      options = filter_input_options(options, builder)
+      as = options[:as] || builder.send(:default_input_type, attribute)
+      builder.send(:namespaced_input_class, as)
+             .new(builder, builder.template, builder.object, :q, attribute, options)
+    end
+
+    # `:input_html` may be a Proc, which the filters form resolves against the view before it
+    # builds the input. Handing the Proc over instead is not merely incomplete, it is wrong in
+    # a way nothing reports: `Proc#[]` is `call`, so Formtastic asking `input_html[:multiple]`
+    # invokes it, gets a truthy Hash back, and a `:select` derives `_in` rather than `_eq`.
+    def filter_input_options(options, builder)
+      options = FilterOptions.input_options(options)
+      return options unless options[:input_html].is_a?(Proc)
+
+      options.merge(input_html: builder.template.instance_exec(&options[:input_html]))
+    end
+
+    # One per request rather than one per filter: #view_context builds a fresh view class every
+    # time it is called, and every defaulted filter would pay for another one.
+    def filter_input_builder
+      @filter_input_builder ||= ::ActiveAdmin::Filters::FormBuilder.new(
+        :q, active_admin_config.resource_class.ransack({}), view_context, {}
+      )
+    end
+
+    def raise_filter_default_error(attribute, message)
+      raise ArgumentError, "filter :#{attribute} declares a `default:` but #{message}"
+    end
+  end
+end

data/lib/active_admin_filter_extensions/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ActiveAdminFilterExtensions
+  VERSION = "1.0.0"
+end

data/lib/active_admin_filter_extensions.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "activeadmin"
+require "active_admin_filter_extensions/version"
+
+# The violation messages live in plain i18n - config/locales/en.yml here, overridable by the
+# application's own locale files under the same keys.
+I18n.load_path += Dir[File.expand_path("../config/locales/*.yml", __dir__)]
+require "active_admin_filter_extensions/data_access"
+require "active_admin_filter_extensions/filter_options"
+require "active_admin_filter_extensions/search_keys"
+require "active_admin_filter_extensions/required_filters"
+require "active_admin_filter_extensions/filter_defaults"
+require "active_admin_filter_extensions/filters_form"
+require "active_admin_filter_extensions/redirect"
+require "active_admin_filter_extensions/policies"
+require "active_admin_filter_extensions/notice"
+
+module ActiveAdminFilterExtensions
+end
+
+# `add_filter` stores whatever options it is given without a whitelist, so `default:` needs no
+# registration of its own.
+ActiveAdmin.before_load do |_app|
+  # Prepended, because it replaces Active Admin's own #apply_filtering.
+  ActiveAdmin::ResourceController.prepend ActiveAdminFilterExtensions::DataAccess
+  # Included, because it only adds - and a resource overriding one of its seams in a
+  # `controller do` block should win, which is what including gives.
+  ActiveAdmin::ResourceController.include ActiveAdminFilterExtensions::FilterOptions
+  ActiveAdmin::ResourceController.include ActiveAdminFilterExtensions::SearchKeys
+  ActiveAdmin::ResourceController.include ActiveAdminFilterExtensions::RequiredFilters
+  ActiveAdmin::ResourceController.include ActiveAdminFilterExtensions::FilterDefaults
+  ActiveAdmin::ResourceController.helper_method :filtering_params, :filter_default_values, :visible_filters
+
+  ActiveAdmin::Resource.prepend ActiveAdminFilterExtensions::ResourceExtension
+  ActiveAdmin::ResourceDSL.include ActiveAdminFilterExtensions::Policies::ResourcePolicyDSL
+  ActiveAdmin::Resource.include ActiveAdminFilterExtensions::Policies::ResourcePolicySettings
+  ActiveAdmin::ResourceDSL.include ActiveAdminFilterExtensions::Notice
+  ActiveAdmin::Resource.include ActiveAdminFilterExtensions::NoticeResource
+  # Policies before the redirect: a sanitized or reset value must be what the redirect
+  # decision - and therefore the URL - is computed from.
+  ActiveAdmin::ResourceController.include ActiveAdminFilterExtensions::Policies::Controller
+  ActiveAdmin::ResourceController.include ActiveAdminFilterExtensions::Redirect
+  ActiveAdmin::Filters::ViewHelper.prepend ActiveAdminFilterExtensions::ViewHelper
+  ActiveAdmin::Filters::ActiveSidebar.prepend ActiveAdminFilterExtensions::ActiveSidebar
+end

data/spec/data_access_spec.rb

@@ -0,0 +1,252 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "active_admin_filter_extensions/policies"
+
+RSpec.describe ActiveAdminFilterExtensions::DataAccess do
+  subject(:searched_with) do
+    chain = FakeChain.new
+    controller.send(:apply_filtering, chain)
+    chain.ransacked_with
+  end
+
+  let(:controller) { FakeController.new(params: params, filters: filters) }
+  let(:params) { {} }
+
+  describe "a scalar default" do
+    let(:filters) { { starred_eq: { extensions: { default: true } } } }
+
+    it "applies to the filter name as it stands" do
+      expect(searched_with).to eq("starred_eq" => true)
+    end
+
+    context "when the request carries filters of its own" do
+      let(:params) { { q: { "title_cont" => "hello" } } }
+
+      it "is left out" do
+        expect(searched_with).to eq("title_cont" => "hello")
+      end
+    end
+
+    context "when the filters form was submitted with every field blank" do
+      # Active Admin disables empty fields on submit, so a blank submission sends no `q` at all
+      # and is only distinguishable from a first visit by `commit`.
+      let(:params) { { commit: "Filter" } }
+
+      it "is not re-applied, so the admin sees everything" do
+        expect(searched_with).to eq({})
+      end
+    end
+  end
+
+  describe "a q that is not a Hash" do
+    let(:filters) { { starred_eq: { extensions: { default: true } } } }
+
+    # Rack parses `?q=` to an empty String. It is blank, so the defaults apply - and merging
+    # them with a String must not be attempted.
+    context "when the request carries `?q=`" do
+      let(:params) { { q: "" } }
+
+      it "treats it as absent and applies the defaults" do
+        expect(searched_with).to eq("starred_eq" => true)
+      end
+    end
+  end
+
+  describe "a Hash default" do
+    let(:filters) { { created_at: { as: :date_range, extensions: { default: { gteq: "2020-01-01" } } } } }
+
+    it "keys each value by its predicate" do
+      expect(searched_with).to eq("created_at_gteq" => "2020-01-01")
+    end
+  end
+
+  describe "an Array default" do
+    # `filter :author, as: :check_boxes` submits as `q[author_id_in][]`, so the predicate side
+    # of the key is `id_in`, not `in`.
+    let(:filters) { { author: { as: :check_boxes, extensions: { default: { id_in: [1, 2] } } } } }
+
+    it "is keyed the way the input submits it" do
+      expect(searched_with).to eq("author_id_in" => [1, 2])
+    end
+  end
+
+  describe "a Proc default" do
+    let(:filters) { { position_eq: { extensions: { default: -> { params[:seed] } } } } }
+    let(:params) { { seed: "7" } }
+
+    it "is evaluated against the controller" do
+      expect(searched_with).to eq("position_eq" => "7")
+    end
+
+    context "when it returns nil" do
+      let(:params) { {} }
+
+      it "applies no filter rather than filtering on NULL" do
+        expect(searched_with).to eq({})
+      end
+    end
+
+    it "is evaluated once per request, so it may query" do
+      calls = 0
+      controller = FakeController.new(filters: { title_eq: { extensions: { default: -> { calls += 1; "v" } } } })
+      3.times { controller.send(:filter_default_values) }
+      expect(calls).to eq(1)
+    end
+  end
+
+  describe "a Symbol default" do
+    let(:filters) { { title_eq: { extensions: { default: :hello } } } }
+
+    it "is a value, not a method to send" do
+      expect(searched_with).to eq("title_eq" => :hello)
+    end
+  end
+
+  describe ":if and :unless" do
+    let(:filters) do
+      {
+        starred_eq: { extensions: { default: true }, if: -> { false } },
+        position_eq: { extensions: { default: 1 }, unless: -> { true } },
+        title_eq: { extensions: { default: "kept" }, if: -> { true } }
+      }
+    end
+
+    it "only applies the defaults of the filters that are rendered" do
+      expect(searched_with).to eq("title_eq" => "kept")
+    end
+
+    it "accepts a Symbol condition and sends it to the controller" do
+      controller = FakeController.new(filters: { title_eq: { extensions: { default: "v" }, if: :never } })
+      def controller.never = false
+      expect(controller.send(:filter_default_values)).to eq({})
+    end
+  end
+
+  describe "#filter_defaults_apply?" do
+    let(:filters) { { starred_eq: { extensions: { default: true } } } }
+
+    context "when an override lets defaults through on a partly filtered request" do
+      let(:params) { { q: { "customer_id_eq" => "7" } } }
+
+      before do
+        def controller.filter_defaults_apply?
+          super || params[:q].keys == %w[customer_id_eq]
+        end
+      end
+
+      it "keeps what the request asked for and adds the defaults to it" do
+        expect(searched_with).to eq("customer_id_eq" => "7", "starred_eq" => true)
+      end
+    end
+
+    context "when the request carries a value for a filter that also declares a default" do
+      let(:params) { { q: { "starred_eq" => false } } }
+
+      before do
+        def controller.filter_defaults_apply? = true
+      end
+
+      it "leaves the request value alone rather than overwriting it" do
+        expect(searched_with).to eq("starred_eq" => false)
+      end
+    end
+  end
+
+  describe "a resource without any default" do
+    let(:filters) { { title: {} } }
+
+    it "leaves the request alone" do
+      expect(searched_with).to eq({})
+    end
+  end
+
+  describe "a required filter's Proc default" do
+    it "is evaluated once per request, shared with the required grouping" do
+      calls = 0
+      controller = FakeController.new(
+        filters: { status_eq: { extensions: { default: -> { calls += 1; "published" }, required: true } } }
+      )
+
+      controller.send(:filtering_params)
+
+      expect(calls).to eq(1)
+    end
+  end
+
+  describe "a required filter answered with false" do
+    # Rack never delivers a boolean - `?q[starred_eq]=false` arrives as the String - but an
+    # override of #filtering_params can, and `false` is an answer everywhere else in the gem.
+    let(:filters) { { starred_eq: { extensions: { default: true, required: true } } } }
+    let(:params) { { q: { "starred_eq" => false } } }
+
+    it "is answered, so no default engages" do
+      expect(controller.send(:filter_defaults_engaged?)).to be(false)
+    end
+  end
+
+  describe "key derivation" do
+    # Deriving builds a real input, so the unit suite reaches it through a stub. A catch-all
+    # rescue turned every internal failure into "could not work out which search key it
+    # submits", which policy_search_keys then answered with a key of its own invention.
+    def deriving(error)
+      Class.new do
+        include ActiveAdminFilterExtensions::SearchKeys
+        define_method(:build_filter_input) { |_attribute, _options| raise error }
+      end.new
+    end
+
+    it "reports an input it cannot build" do
+      # No `ransack` on the resource - what a proxy page backed by an HTTP API answers.
+      controller = deriving(NoMethodError.new("undefined method 'ransack'"))
+
+      expect { controller.send(:filter_search_keys, :created_at, {}) }
+        .to raise_error(ArgumentError, /could not work out which search key it submits/)
+    end
+
+    it "lets a failure that is not a derivation failure through" do
+      controller = deriving(RuntimeError.new("boom"))
+
+      expect { controller.send(:filter_search_keys, :created_at, {}) }
+        .to raise_error(RuntimeError, "boom")
+    end
+  end
+
+  describe "a policy on a filter whose search key cannot be derived" do
+    # The derivation needs a resource Ransack can search; a proxy page backed by an HTTP API
+    # has none, and a policy must not turn every index of such a page into a 500. The declared
+    # filter name IS the submitted key on those pages, so the guard falls back to it.
+    let(:proxy_controller_class) do
+      Class.new(FakeController) do
+        def filter_search_keys(_attribute, _options)
+          raise ArgumentError, "could not work out which search key it submits"
+        end
+      end
+    end
+    let(:controller) { proxy_controller_class.new(params: params, filters: filters) }
+    let(:filters) { { time_start_gteq: { extensions: { sanitize: ->(v) { v.strip }, default: "keep" } } } }
+    let(:params) { { q: { "time_start_gteq" => "  2026-01-01  " } } }
+
+    it "falls back to the attribute name and still enforces" do
+      controller.send(:enforce_filter_value_policies)
+      expect(controller.params[:q]["time_start_gteq"]).to eq("2026-01-01")
+    end
+
+    context "when the filter declares a window policy" do
+      # The fallback gives one key, and a window policy demands two - so the very page the
+      # fallback keeps alive raised "needs a two-ended input" on every request instead.
+      let(:filters) { { time_start_gteq: { extensions: { max_range: 86_400 } } } }
+      let(:params) { { q: { "time_start_gteq" => "2026-01-01" } } }
+
+      it "logs and skips the window instead of raising" do
+        warnings = []
+        logger = Object.new
+        logger.define_singleton_method(:warn) { |message| warnings << message }
+        controller.define_singleton_method(:policy_logger) { logger }
+
+        expect { controller.send(:enforce_filter_value_policies) }.not_to raise_error
+        expect(warnings.first).to match(/could not be derived/)
+      end
+    end
+  end
+end

data/spec/integration/extensions_container_spec.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+# Everything of the gem's lives under the one extensions: option. Both ways out of the container
+# are loud: a gem key left flat would otherwise mean something else to Formtastic (required:),
+# and a typo inside would silently guard nothing.
+RSpec.describe "the extensions: container", type: :feature do
+  it "reads a string-keyed container" do
+    # The unknown-key check symbolizes before comparing, so "default" => ... passed it and then
+    # merged under a String key the gem never reads: a declared default that quietly did nothing.
+    Post.create!(title: "keep me", status: "published", position: 20)
+    Post.create!(title: "drop me", status: "draft", position: 1)
+
+    visit "/admin/string_keyed_extensions_posts"
+
+    expect(page).to have_content("keep me")
+    expect(page).to have_no_content("drop me")
+  end
+
+  it "raises for a gem option left outside extensions:" do
+    expect { visit "/admin/banana_flat_option_posts" }
+      .to raise_error(ArgumentError, /:default.*belong inside extensions:/m)
+  end
+
+  it "leaves a flat required: and min: to Formtastic" do
+    # `filter :position, as: :numeric, min: 0` is legal Active Admin. Annexed, the gem read
+    # min: as a window policy on a single-ended input and 500'd every index of the resource.
+    visit "/admin/host_option_posts"
+
+    expect(page).to have_css("input[name='q[position]'][min='0']")
+  end
+
+  it "raises for an unknown key inside extensions:" do
+    expect { visit "/admin/banana_policy_key_posts" }
+      .to raise_error(ArgumentError, /unknown extensions: :defult/m)
+  end
+end