sn_filterable 0.1.1

data/app/components/sn_filterable/main_component.html.erb

@@ -0,0 +1,97 @@
+<% url = @url || url_for %>
+<div x-data="{ filteringForm: $refs.filtering_form, entireComponenet: $el, filtersLoading: false, filtersPopupOpen: false, sidebarGapTarget: null }">
+  <%= content_tag :form,
+                  "x-ref": "filtering_form",
+                  "action": url,
+                  "method": "get",
+                  "data-turbo-frame": @frame_id,
+                  "class": "relative",
+                  "@submit": "filtersLoading = true" do %>
+    <div class="absolute w-full h-full pointer-events-none">
+      <div class="absolute flex flex-col sm:grid sm:grid-cols-3 gap-4 w-full pointer-events-none">
+        <div class="sm:hidden h-14"></div>
+        <% if @search_filter_name.present? %>
+          <% if search? %>
+            <%= search %>
+          <% else %>
+            <div class="col-span-2 col-start-2 md:ml-48 lg:ml-64 h-12 pointer-events-auto">
+              <%= render search_field %>
+            </div>
+          <% end %>
+        <% end %>
+      </div>
+      <% if @show_sidebar %>
+        <div class="mt-16 h-full pointer-events-auto">
+          <div class="h-full" x-init="sidebarGapTarget = $el">
+            <div x-show="filtersPopupOpen" class="fixed top-0 left-0 right-0 bottom-0 z-10 sm:z-0 bg-gray-600 bg-opacity-75 sm:hidden" @click="filtersPopupOpen = false" x-cloak></div>
+            <div x-show="filtersPopupOpen" class="fixed bottom-0 h-2/3 z-10 sm:z-0 left-0 w-full bg-white pt-4 sm:sticky sm:!block row-span-2 shrink-0 mr-4 self-start sm:top-16 lg:w-64 sm:w-52 sm:pt-2 sm:pb-6 sm:overflow-y-auto sm:h-[70vh] sm:max-h-[calc(100vh_-_5rem)]" x-cloak>
+            <div class="absolute top-0 right-0 -mt-12 mb-2 mr-2" x-show="filtersPopupOpen">
+              <button type="button" class="ml-1 flex items-center justify-center h-10 w-10 rounded-full focus:outline-none focus:ring-2 focus:ring-inset focus:ring-white" @click="filtersPopupOpen = false">
+                <span class="sr-only">Close filters</span>
+                <%= heroicon "x-mark", variant: :outline, options: { class: "h-6 w-6 text-grey-500" } %>
+              </button>
+            </div>
+            <div name="Filter Options" role="menu" aria-orientation="vertical" aria-labelledby="options-menu" class="overflow-y-auto max-h-full">
+              <% @filters.each do |filter| %>
+                <%= render SnFilterable::CategoryComponent.new(title: filter[:title], open: @filtered.queries.dig("filter", filter.try(:[], :filter_name)).present?) do |c| %>
+                  <% c.filter(filtered: @filtered, filter: filter) %>
+                <% end %>
+              <% end %>
+              <%= render SnFilterable::CategoryComponent.new(title: t("shared.filterable.results_per_page"), open: @filtered.queries.dig("per").present?) do %>
+                <fieldset class="pt-2" x-data="{ wasInteracted: false }">
+                  <% ([@filtered.items.default_per_page] | [10, 25, 50]).sort.each do |value| %>
+                    <div class="relative flex items-start px-4 transition-colors hover:bg-gray-200 text-gray-700 hover:text-gray-900">
+                      <div class="min-w-0 flex-1 flex-grow">
+                        <%= content_tag :label, value, class: "block py-2 pr-4 text-gray-600 select-none w-full cursor-pointer", for: "per-#{value}" %>
+                      </div>
+                      <div class="my-2 flex items-center">
+                        <% selected_explcitly = value == @filtered.queries["per"].to_i %>
+                        <% selected_by_default = @filtered.queries["per"].blank? && value == @filtered.items.default_per_page %>
+                        <%= content_tag :input, "",
+                                        class: "focus:ring-purple-400 cursor-pointer h-5 w-5 text-purple-500 bg-purple-100 border-0",
+                                        type: "radio",
+                                        id: "per-#{value}",
+                                        "x-data": { iteracted: selected_explcitly }.to_json,
+                                        ":name": "wasInteracted && 'per'",
+                                        value: value,
+                                        checked: selected_explcitly || selected_by_default,
+                                        "@click": "wasInteracted = true; $nextTick(() => { $el.checked = true; filteringForm.requestSubmit() })"
+                        %>
+                      </div>
+                    </div>
+                  <% end %>
+                </fieldset>
+              <% end %>
+            </div>
+          </div>
+          </div>
+        </div>
+      <% end %>
+    </div>
+  <% end %>
+
+  <%= turbo_frame_tag @frame_id, "data-turbo-action": "advance" do %>
+    <%= content_tag :input, "", type: "hidden", name: "sort", value: @filtered.queries["sort"] if @filtered.queries["sort"].present? %>
+    <%= content_tag :input, "", type: "hidden", name: "order", value: @filtered.queries["order"] if @filtered.queries["order"].present? %>
+
+    <div class="flex flex-col sm:grid sm:grid-cols-3 gap-4 pointer-events-none">
+      <div class="sm:hidden flex items-end h-14 pointer-events-auto">
+        <%= render SnFilterable::FilterButtonComponent.new(filtered: @filtered, filters: @filters) %>
+      </div>
+      <% if @search_filter_name.present? %>
+        <div class="col-span-2 col-start-2 md:ml-64 h-12 pointer-events-none"></div>
+      <% end %>
+    </div>
+
+    <%= render SnFilterable::ChipsComponent.new(filtered: @filtered, filters: @filters, url: url) %>
+
+    <div class="flex flex-row" x-init="filtersLoading = false">
+      <% if @show_sidebar %>
+        <div class="lg:w-64 sm:w-52"></div>
+      <% end %>
+      <div class="relative flex-1 <%= "sm:ml-4" if @show_sidebar %>">
+        <%= content %>
+      </div>
+    </div>
+  <% end %>
+</div>

data/app/components/sn_filterable/main_component.rb

@@ -0,0 +1,39 @@
+module SnFilterable
+  require "view_component"
+  # Renders the filtering interface
+  #
+  # ## Filters' info
+  # An array of hashes in the following Hash format:
+  #  - multi: [Boolean]; Determines if this filter supports multiple simultaneous subfilters. If true, the filter must be declared in the [Filterable]'s [ARRAY_FILTER_SCOPES]
+  #  - title: [String]; The title to display on the filtering interface
+  #  - filter_name: [String]; The filter's parameter name, see [Filterable]'s documentation
+  #  - filters: [Array<Hash>]; An array of the available preset sub filters
+  #    - name: [String]; The name of the sub filter to display in the interface
+  #    - value: [String]; The value of the sub filter
+  class MainComponent < ViewComponent::Base
+    include Turbo::FramesHelper
+    include Turbo::StreamsHelper
+    include Heroicon::Engine.helpers
+
+    renders_one :search
+
+    # @param [String] frame_id The unique turbo frame ID
+    # @param [Filtered] filtered The filtered instance
+    # @param [Array<Hash>] filters An array of the filters' info (see [Filterable::MainComponent]'s documentation)
+    # @param [String, nil] url Optional, the base URL of where the filters are displayed
+    # @param [String, nil] search_filter_name Optional, enable's and set's the search filter, specified by the filter's parameter name
+    # @param [Boolean] show_sidebar If true, will show the sidebar with the filters.
+    def initialize(frame_id:, filtered:, filters:, url: nil, search_filter_name: nil, show_sidebar: true)
+      @frame_id = frame_id
+      @filtered = filtered
+      @filters = filters
+      @url = url
+      @search_filter_name = search_filter_name
+      @show_sidebar = show_sidebar
+    end
+
+    def search_field
+      SnFilterable::SearchComponent.new(filtered: @filtered, filter_name: @search_filter_name)
+    end
+  end
+end

data/app/components/sn_filterable/search_component.html.erb

@@ -0,0 +1,16 @@
+<div class="mt-1 relative rounded-md shadow-sm">
+  <div class="absolute inset-y-0 left-0 pl-3 flex items-center pointer-events-none">
+    <%= heroicon "magnifying-glass", options: { class: "h-5 w-5 text-gray-400" } %>
+  </div>
+  <%= content_tag :input, "",
+                  class: "focus:ring-indigo-500 focus:border-indigo-500 block w-full pl-10 sm:text-sm border-gray-300 rounded-md",
+                  placeholder: "Search...",
+                  type: "search",
+                  ":name": "hasValue && `filter[#{@filter_name}]`",
+                  value: @filtered.queries.dig("filter", @filter_name),
+                  "x-data": "filteringSearchInput(#{@filter_name.to_json})",
+                  "x-init": "onInit()",
+                  "@input": "onUpdate(false)",
+                  "@keyup.enter": "onUpdate(true)",
+                  "@search": "onUpdate(true)" %>
+</div>

data/app/components/sn_filterable/search_component.rb

@@ -0,0 +1,13 @@
+module SnFilterable
+  # Renders the optional search bar
+  class SearchComponent < ViewComponent::Base
+    include Heroicon::Engine.helpers
+
+    # @param [Filtered] filtered The filtered instance
+    # @param [String] filter_name The search filter's parameter name
+    def initialize(filtered:, filter_name:)
+      @filtered = filtered
+      @filter_name = filter_name
+    end
+  end
+end

data/lib/models/filtered.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+# Helper class that provides access to the filtered items and generation
+# of sort/filter URLs for the items.
+#
+# Should not be initialized directly, models should implement [Filterable] instead.
+#
+# @see Filterable
+class Filtered
+  attr_accessor :items, :queries
+
+  # @param [Class] model_class The class of the ActiveRecord::Base subclass
+  # @param [ActiveRecord::Relation] items The items sorted and filtered by [Filterable]
+  # @param [Hash] queries A hash of the sorting / filtering parameters
+  # @param [Symbol] sort_name The current sorting name
+  # @param [Boolean] sort_reversed True when the current sorting order is reversed
+  def initialize(model_class, items, queries, sort_name, sort_reversed)
+    @model_class = model_class
+    @items = items
+    @queries = queries
+    @sort_name = sort_name
+    @sort_reversed = sort_reversed
+  end
+
+  # Returns if any filters are active
+  # @return [Boolean] True if at least one filter is active
+  def active_filters?
+    @queries["filter"].present?
+  end
+
+  # Sets one filter to the URL.
+  #
+  # @param [String] url The URL to apply the filter to
+  # @param [String] key The filter's key
+  # @param [String] value The value to apply using the filter
+  # @return [String] the modified URL with the filter applied
+  def set_filter_url(url, key, value)
+    modify_url_queries(url) do |queries|
+      queries["filter"] = { key => value }
+    end
+  end
+
+  # Adds a filter to the URL.
+  #
+  # @param [String] url The URL to add the filter to
+  # @param [String] key The filter's key
+  # @param [String] value The value to apply using the filter
+  # @return [String] the modified URL with the filter added
+  def add_filter_url(url, key, value)
+    modify_url_queries(url) do |queries|
+      queries["filter"][key] = value
+    end
+  end
+
+  # Removes a filter from the URL.
+  #
+  # @param [String] url The URL to remove the filter from
+  # @param [String] key The filter's key to remove
+  # @return [String] the modified URL with the filter removed
+  def remove_filter_url(url, key)
+    modify_url_queries(url) do |queries|
+      queries["filter"].delete(key)
+    end.chomp("?")
+  end
+
+  # Removes a sub filter from the URL.
+  #
+  # @param [String] url The URL to remove the filter from
+  # @param [String] key The filter's key to match
+  # @param [String] value The filter's value to remove
+  # @return [String] the modified URL with the filter removed
+  def remove_sub_filter_url(url, key, value)
+    modify_url_queries(url) do |queries|
+      queries["filter"][key].delete(value.to_s) if queries["filter"][key].is_a?(Array)
+    end.chomp("?")
+  end
+
+  # Clears all filters from the URL.
+  #
+  # @param [String] url The url to remove the filter from
+  # @return [String] the modified URL with all filters removed
+  def clear_filter_url(url)
+    clear_url(url, true, false)
+  end
+
+  # Clears sorting from the URL.
+  #
+  # @param [String] url The url to remove the sorting parameters from
+  # @return [String] the modified URL with no defined sort
+  def clear_sort_url(url)
+    clear_url(url, false, true)
+  end
+
+  # Clears all filters and sorting from the URL.
+  #
+  # @param [String] url The url to remove the sorting and filtering from
+  # @return [String] the modified URL with all filters and sorting removed
+  def clear_all_url(url)
+    clear_url(url, true, true)
+  end
+
+  # Generates a URL used in table headers for column sorting.
+  #
+  # Calls and returns `block`, providing the following parameters in the following order:
+  #  - url: [String] The URL for the column sorting which links to the *next* sorting state
+  #  - state: [nil, Symbol] The *current* sorting state of the provided key. Provides the key's sorting order as a symbol, either `:asc`, or `:desc` when active. Returns `nil`, this sorting key is not active.
+  #
+  # When the sorting key provided is active for this [Filtered] instance, this method will
+  # return a URL with the order reversed.
+  #
+  # @param [String] url The url to apply the sort parameters on
+  # @param [String] key The sorting key to toggle
+  # @param [Symbol, nil] order Optional, sets the sorting order. If set to nil, will toggle the order instead.
+  # @return the value returned from the block. If no block is given, [Array(String, Symbol | nil)] is returned, which contains the URL and state respectively
+  def sort_url(url, key, order = nil, scope: nil)
+    state = nil
+    url = modify_url_queries(url) do |queries|
+      queries["sort"] = key
+
+      if @sort_name == key
+        state = @sort_reversed ? :desc : :asc
+        queries["order"] = @sort_reversed ? "asc" : "desc"
+      else
+        queries.delete("order")
+      end
+
+      queries["order"] = order.to_s unless order.nil?
+
+      queries["scope"] = scope.to_s unless scope.nil?
+    end
+
+    return yield(url, state) if block_given?
+
+    [url, state]
+  end
+
+  private
+
+  # Clears parameters from the URL.
+  #
+  # @param [String] url The url to remove the filter from
+  # @param [Boolean] clear_filter If true, will clear all filters from the URL
+  # @param [Boolean] clear_sort If true, will clear the sort parameters from the URL
+  # @return [String] the cleared URL
+  def clear_url(url, clear_filter, clear_sort)
+    modify_url_queries(url) do |queries|
+      queries.delete("filter") if clear_filter
+
+      if clear_sort
+        queries.delete("sort")
+        queries.delete("order")
+      end
+    end.chomp("?")
+  end
+
+  # Modifies a URL query parameters by calling `block`,
+  # providing the mutable queries as the first parameter.
+  #
+  # @param url [String] The base URL
+  # @return [String] the modified URL
+  def modify_url_queries(url)
+    uri = URI.parse(url)
+    query = Rack::Utils.parse_nested_query(uri.query).deep_merge(@queries.deep_dup)
+
+    yield(query) if block_given?
+
+    uri.query = Rack::Utils.build_nested_query(query)
+
+    uri.to_s
+  end
+end

data/lib/sn_filterable/engine.rb

@@ -0,0 +1,10 @@
+require "rails/engine"
+require "view_component/engine"
+
+module SnFilterable
+  class Engine < Rails::Engine
+    config.autoload_paths = %W[
+      #{root}/app/components
+    ]
+  end
+end

data/lib/sn_filterable/filterable.rb

@@ -0,0 +1,292 @@
+# frozen_string_literal: true
+
+# Concern to add sorting and filtering for ActiveRecord models.
+#
+# The following constants must to be implemented in the base class
+# for filtering and sorting to work:
+#
+# `FILTER_SCOPE_MAPPINGS`: A [Hash] that maps a filter's parameter name to the filter's scope. The scope's proc should have a single argument for filtering. Multiple filters will be ANDed when building the full query.
+#
+# `ARRAY_FILTER_SCOPES`: An [Array] of filter parameter names that support having multiple values. If multiple filters of the same key are provided, the value's scope will be ORed when building the filter's query.
+#
+# `SORT_SCOPE_MAPPINGS`: A [Hash] that maps a sorting name to the sorting scope. If the scope is complex preventing automatic reversal, another scope with the suffix '_reversed' must be made.
+#
+# `DEFAULT_SORT`: Optional, sets the default sort of the items when no sorting parameter is set. Can be either a [String], which returns the sorting name or an [Array], where the first item is the sorting name and the second item is the sort direction (either `:asc` or `:desc`).
+#
+# @see Filtered
+require "pg_search"
+
+module SnFilterable
+  module Filterable
+    extend ActiveSupport::Concern
+    include PgSearch::Model
+
+    class_methods do
+      # Filters and sorts the model's items.
+      #
+      # @param [ActionController::Parameters] params The unfiltered parameters
+      # @param [ActiveRecord::Relation] items Optional, the items to scope from the model
+      # @param [String, Array, nil] default_sort Optional, similar to the `DEFAULT_SORT` constant, sets the default sort of items when no sorting parameter is set. Can be either a [String], which returns the sorting name or an [Array], where the first item is the sorting name and the second item is the sort direction (either `:asc` or `:desc`). Will take precedence over the `DEFAULT_SORT` constant.
+      # @param [Boolean] pagination_enabled Optional, toggles pagination
+      # @return [Filtered] the filtered and sorted items
+      def filter(params:, items: where(nil), default_sort: nil, pagination_enabled: true)
+        filter_params = filter_params(params)
+        sort_params = sort_params(params)
+        other_params = other_params(params, items)
+
+        items = perform_filter(items, filter_params)
+        items, sort_name, reverse_order = perform_sort(items, sort_params, default_sort)
+        items = items.page(other_params[:page]).per(other_params[:per]) if pagination_enabled
+
+        Filtered.new(self, items, generate_url_queries(filter_params, sort_params, other_params), sort_name, reverse_order)
+      end
+
+      private
+
+      # Filters the items using the provided parameters. All filters' clauses are ANDed.
+      #
+      # @param [ActiveRecord::Relation] items
+      # @param [ActionController::Parameters] params The filter parameters
+      # @return [ActiveRecord::Relation] the filtered items
+      def perform_filter(items, params)
+        params[:filter].try(:each) do |key, value|
+          filter_items = perform_single_filter(items, key, value)
+
+          items = items.merge(filter_items) unless filter_items.nil?
+        end
+
+        items
+      end
+
+      # Builds the relation for a single filter.
+      #
+      # All filters are performed against `items.model.all` to build a generic relation against the table.
+      # To be used with `#perform_filter` which will reduce the scope of the returned relation by ANDing.
+      #
+      # When an array of values is given, each value's clause is ORed.
+      #
+      # @param [ActiveRecord::Relation] items
+      # @param [String] key The filtering key
+      # @param [String, Array<String>] value The value(s) to sort
+      # @return [ActiveRecord::Relation, nil] returns the relation or `nil` if a non-empty value was given
+      def perform_single_filter(items, key, value)
+        if value.present?
+          return items.model.all.public_send(const_get(:FILTER_SCOPE_MAPPINGS)[key.to_sym], value) unless value.is_a?(Array)
+
+          output_items = nil
+
+          value.each do |x|
+            next if x.blank?
+
+            filter_items = items.model.all.public_send(const_get(:FILTER_SCOPE_MAPPINGS)[key.to_sym], x)
+            output_items = output_items.nil? ? filter_items : output_items.or(filter_items)
+          end
+
+          return output_items
+        end
+
+        nil
+      end
+
+      # Sorts the items using the `sort` and `order` parameters. Will default to using
+      # the default sort when the sorting parameters are not present.
+      #
+      # @param [ActiveRecord::Relation] items
+      # @param [ActionController::Parameters] params The sort parameters
+      # @param [String, Array, nil] default_sort
+      # @return [Array(ActiveRecord::Relation, Symbol | nil, Boolean)] the sorted items, sorting name and sorting order
+      def perform_sort(items, params, default_sort)
+        sort_name = nil
+        reverse_order = params[:order] == "desc"
+
+        if params[:sort].present?
+          sort_name = params[:sort]
+        elsif default_sort.present? || const_defined?(:DEFAULT_SORT)
+          default_sort ||= const_get(:DEFAULT_SORT) if const_defined?(:DEFAULT_SORT)
+
+          sort_name, reverse_order = parse_default_sort(default_sort)
+        end
+
+        items = sort_items(items, sort_name, reverse_order, scope: params[:scope]) if sort_name.present?
+
+        [items, sort_name, reverse_order]
+      end
+
+      # Parses the default sort.
+      #
+      # @param [String, Array, nil] default_sort
+      # @return [Array(Symbol, Boolean)] the sorting scope and the sorting order
+      def parse_default_sort(default_sort)
+        sort_scope = nil
+        reverse_order = false
+
+        case default_sort
+        when Array
+          sort_scope = default_sort[0]
+          reverse_order = default_sort[1] == :desc
+        when String
+          sort_scope = default_sort
+        else
+          raise TypeError, "Invalid type found for the default sort, expected either Array or Symbol, got #{default_sort.class}"
+        end
+
+        [sort_scope, reverse_order]
+      end
+
+      # Sorts the items using the sorting scope and reversing the sort if required.
+      # Will prioitize using the explicit `_reversed` scope over reversing automatically.
+      #
+      # @param [ActiveRecord::Relation] items The items to sort
+      # @param [String] sort_name The sorting name
+      # @param [Boolean] reverse_order If true, will attempt to reverse the order of the sort
+      # @return [ActiveRecord::Relation] the sorted items
+      def sort_items(items, sort_name, reverse_order, scope: nil)
+        sort_scope = const_get(:SORT_SCOPE_MAPPINGS)[sort_name.to_sym]
+        reversed_sort_scope_sym = "#{sort_scope}_reversed".to_sym
+
+        if reverse_order && methods.include?(reversed_sort_scope_sym)
+          items.public_send(reversed_sort_scope_sym)
+        else
+          items = if scope.nil?
+                    items.public_send(sort_scope)
+                  else
+                    items.public_send(sort_scope, scope.to_i)
+                  end
+          items = items.reverse_order if reverse_order
+
+          items
+        end
+      end
+
+      # Scopes the user parameters to only contain filtering parameters.
+      #
+      # @param [ActionController::Parameters] params
+      # @return [ActionController::Parameters]
+      def filter_params(params)
+        return ActionController::Parameters.new.permit unless const_defined?(:FILTER_SCOPE_MAPPINGS)
+
+        filters_with_array_support = const_defined?(:ARRAY_FILTER_SCOPES) ? const_get(:ARRAY_FILTER_SCOPES)&.map { |x| { x => [] } } : []
+
+        params.permit(filter: const_get(:FILTER_SCOPE_MAPPINGS).keys.concat(filters_with_array_support))
+      end
+
+      # Scopes the user parameters to only contain sorting parameters.
+      #
+      # @param [ActionController::Parameters] params
+      # @return [ActionController::Parameters]
+      def sort_params(params)
+        params = params.permit(:sort, :order, :scope)
+        return ActionController::Parameters.new.permit unless sort_params_valid?(params)
+
+        params
+      end
+
+      # Validates the sorting parameters.
+      #
+      # @param [ActionController::Parameters] params
+      def sort_params_valid?(params)
+        const_defined?(:SORT_SCOPE_MAPPINGS) &&
+          params[:sort].present? && params[:sort].in?(const_get(:SORT_SCOPE_MAPPINGS).keys.map(&:to_s)) &&
+          (params[:order].blank? || params[:order].in?(%w[asc desc]))
+      end
+
+      # Scopes the user parameters to contain only other parameters (pagination parameters, :page, :per)
+      #
+      # @param [ActionController::Parameters] params
+      # @param [ActiveRecord::Relation] items The items to scope from the model, used to determine pagination max
+      # @return [ActionController::Parameters]
+      def other_params(params, items)
+        params = params.permit(:page, :per)
+
+        return ActionController::Parameters.new.permit unless other_params_valid?(params, items)
+
+        params
+      end
+
+      # Validates the other parameters.
+      #
+      # @param [ActionController::Parameters] params
+      # @param [ActiveRecord::Relation] items The items to scope from the model, used to determine pagination max
+      def other_params_valid?(params, items)
+        params[:per].blank? || params[:per].to_i.between?(1, items.max_per_page)
+      end
+
+      # Generates a valid hash of the sorting and filtering queries.
+      #
+      # @param [ActionController::Parameters] f_params The filter parameters
+      # @param [ActionController::Parameters] s_params The sort parameters
+      # @param [ActionController::Parameters] o_params The other parameters
+      # @return [Hash] the valid URL queries
+      def generate_url_queries(f_params, s_params, o_params)
+        queries = { "filter" => {} }
+
+        f_params["filter"].try(:each) { |k, v| queries["filter"][k] = v }
+
+        queries["sort"] = s_params["sort"] if s_params["sort"].present?
+        queries["order"] = s_params["order"] if s_params["order"].present?
+        queries["page"] = o_params["page"] if o_params["page"].present?
+        queries["per"] = o_params["per"] if o_params["per"].present?
+
+        queries
+      end
+    end
+
+    # Helper class for generating `WHERE` conditions
+    class WhereHelper
+      # Helper to find if a value exists in a string (case-insensitive)
+      #
+      # @param [String] column_key The column's key to search
+      # @param [String] value The value to look for (case-insensitive)
+      def self.contains(column_key, value)
+        ["strpos(LOWER(#{column_key}), ?) > 0", value.downcase.strip]
+      end
+    end
+
+    # Helper class for handling polymorphic associations
+    class PolymorphicHelper
+      # Helper to join the polymorphic associated tables.
+      #
+      # @param [ActiveRecord::Relation] relation The relation to apply the JOIN clause
+      # @param [Symbol, String] polymorphic_association The name of the polymorphic association
+      # @param [Array<Class>] models An array of the models that the polymorphic association applies to
+      # @return [ActiveRecord::Relation]
+      def self.joins(relation, polymorphic_association, models)
+        table_name = ActiveRecord::Base.connection.quote_table_name(relation.table.name)
+        polymorphic_association_id = ActiveRecord::Base.connection.quote_column_name("#{polymorphic_association}_id")
+        polymorphic_association_type = ActiveRecord::Base.connection.quote_column_name("#{polymorphic_association}_type")
+
+        models.each do |model|
+          associated_table = ActiveRecord::Base.connection.quote_table_name(model.table_name)
+          associated_type = model.name
+
+          join_query = ActiveRecord::Base.sanitize_sql_array([
+                                                              "LEFT OUTER JOIN #{associated_table} ON #{associated_table}.id = #{table_name}.#{polymorphic_association_id} AND #{table_name}.#{polymorphic_association_type} = ?",
+                                                              associated_type
+                                                            ])
+
+          relation = relation.joins(join_query)
+        end
+
+        relation
+      end
+
+      # Coalesces the columns of a polymorphic association. Should be used in a relation that used the {#joins} helper.
+      #
+      # @param [Array<Class>] models An array of the models that the polymorphic association applies to
+      # @param [String] column The mutual column that exists in the models
+      # @return [String] the coalesce SQL function
+      def self.coalesce(models, column)
+        column = ActiveRecord::Base.connection.quote_column_name(column)
+
+        sql_columns = []
+
+        models.each do |model|
+          associated_table = ActiveRecord::Base.connection.quote_table_name(model.table_name)
+          sql_columns.push("#{associated_table}.#{column}")
+        end
+
+        "coalesce(#{sql_columns.join(', ')})"
+      end
+    end
+  end
+end

data/lib/sn_filterable/railtie.rb

@@ -0,0 +1,11 @@
+module SnFilterable
+  class Railtie < ::Rails::Railtie
+    initializer "sn-filterable.view_helpers" do |app|
+      ActiveSupport.on_load(:action_view) do
+        # include Heroicon::Engine.helpers
+        include SnFilterable::FilteredHelper
+      end
+      # app.config.i18n.load_path += Dir[File.expand_path(File.join(File.dirname(__FILE__), '../locales', '*.yml')).to_s]
+    end
+  end
+end

data/lib/sn_filterable/version.rb

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