datagrid 1.8.2 → 2.0.0

data/lib/datagrid/filters.rb

@@ -1,8 +1,135 @@
+# frozen_string_literal: true
+
 require "active_support/core_ext/class/attribute"
 
 module Datagrid
+  # Defines the accessible attribute that is used to filter
+  # the scope by the specified value with specified code.
+  #
+  #     class UserGrid < ApplicationGrid
+  #       scope do
+  #         User
+  #       end
+  #
+  #       filter(:name)
+  #       filter(:posts_count, :integer) do |value|
+  #         self.where(["posts_count >= ?", value])
+  #       end
+  #     end
+  #
+  # Each filter becomes a grid attribute.
+  #
+  # To create a grid displaying all users with the name 'John' who have more than zero posts:
+  #
+  #     grid = UserGrid.new(posts_count: 1, name: "John")
+  #     grid.assets # SELECT * FROM users WHERE users.posts_count > 1 AND name = 'John'
+  #
+  # # Filter Block
+  #
+  # Filter blocks should always return a chainable ORM object (e.g., `ActiveRecord::Relation`) rather than an `Array`.
+  #
+  # Filter blocks should have at least one argument representing the value assigned to the grid object attribute:
+  #
+  #     filter(:name, :string) # { |value| where(name: value) }
+  #
+  # You can pass additional arguments:
+  #
+  #     filter(:name, :string) { |value, scope| scope.where("name ilike ?", "%#{value}%") }
+  #     filter(:name, :string) do |value, scope, grid|
+  #       scope.where("name #{grid.predicate} ?", "%#{value}%")
+  #     end
+  #
+  # # Filter Types
+  #
+  # Filters perform automatic type conversion. Supported filter types include:
+  #
+  # - `default`
+  # - `date`
+  # - `datetime`
+  # - `enum`
+  # - `boolean`
+  # - `xboolean`
+  # - `integer`
+  # - `float`
+  # - `string`
+  # - `dynamic`
+  #
+  # ## Default
+  #
+  # `:default` - Leaves the value as is.
+  #
+  # ## Date
+  #
+  # `:date` - Converts value to a date. Supports the `:range` option to accept date ranges.
+  #
+  #     filter(:created_at, :date, range: true, default: proc { 1.month.ago.to_date..Date.today })
+  #
+  # ## Datetime
+  #
+  # `:datetime` - Converts value to a timestamp. Supports the `:range` option to accept time ranges.
+  #
+  #     filter(:created_at, :datetime, range: true, default: proc { 1.hour.ago..Time.now })
+  #
+  # ## Enum
+  #
+  # `:enum` - For collection selection with options like `:select` and `:multiple`.
+  #
+  #     filter(:user_type, :enum, select: ['Admin', 'Customer', 'Manager'])
+  #     filter(:category_id, :enum, select: proc { Category.all.map { |c| [c.name, c.id] } }, multiple: true)
+  #
+  # ## Boolean
+  #
+  # `:boolean` - Converts value to `true` or `false`.
+  #
+  # ## Xboolean
+  #
+  # `:xboolean` - Subtype of `enum` filter that provides "Yes", "No", and "Any" options.
+  #
+  #     filter(:active, :xboolean)
+  #
+  # ## Integer
+  #
+  # `:integer` - Converts value to an integer. Supports the `:range` option.
+  #
+  #     filter(:posts_count, :integer, range: true, default: (1..nil))
+  #
+  # ## String
+  #
+  # `:string` - Converts value to a string.
+  #
+  #     filter(:email, :string)
+  #
+  # ## Dynamic
+  #
+  # Provides a builder for dynamic SQL conditions.
+  #
+  #     filter(:condition1, :dynamic)
+  #     filter(:condition2, :dynamic)
+  #     UsersGrid.new(condition1: [:name, "=~", "John"], condition2: [:posts_count, ">=", 1])
+  #     UsersGrid.assets # SELECT * FROM users WHERE name like '%John%' and posts_count >= 1
+  #
+  # # Filter Options
+  #
+  # Options that can be passed to any filter:
+  #
+  # - `:header` - Human-readable filter name (default: generated from the filter name).
+  # - `:default` - Default filter value (default: `nil`).
+  # - `:multiple` - Allows multiple values (default: `false`).
+  # - `:allow_nil` - Whether to apply the filter when the value is `nil` (default: `false`).
+  # - `:allow_blank` - Whether to apply the filter when the value is blank (default: `false`).
+  #
+  # Example:
+  #
+  #     filter(:id, :integer, header: "Identifier")
+  #     filter(:created_at, :date, range: true, default: proc { 1.month.ago.to_date..Date.today })
+  #
+  # # Localization
+  #
+  # Filter labels can be localized or specified via the `:header` option:
+  #
+  #     filter(:created_at, :date, header: "Creation date")
+  #     filter(:created_at, :date, header: proc { I18n.t("creation_date") })
   module Filters
-
     require "datagrid/filters/base_filter"
     require "datagrid/filters/enum_filter"
     require "datagrid/filters/extended_boolean_filter"
@@ -11,49 +138,46 @@ module Datagrid
     require "datagrid/filters/date_time_filter"
     require "datagrid/filters/default_filter"
     require "datagrid/filters/integer_filter"
-    require "datagrid/filters/composite_filters"
     require "datagrid/filters/string_filter"
     require "datagrid/filters/float_filter"
     require "datagrid/filters/dynamic_filter"
 
+    # @!visibility private
     FILTER_TYPES = {
       date: Filters::DateFilter,
       datetime: Filters::DateTimeFilter,
       string: Filters::StringFilter,
       default: Filters::DefaultFilter,
-      xboolean: Filters::ExtendedBooleanFilter ,
-      boolean: Filters::BooleanFilter ,
+      xboolean: Filters::ExtendedBooleanFilter,
+      boolean: Filters::BooleanFilter,
       integer: Filters::IntegerFilter,
       enum: Filters::EnumFilter,
       float: Filters::FloatFilter,
-      dynamic: Filters::DynamicFilter
-    }
-
-    DEFAULT_FILTER_BLOCK = Object.new
+      dynamic: Filters::DynamicFilter,
+    }.freeze
 
     # @!visibility private
-    def self.included(base)
-      base.extend ClassMethods
-      base.class_eval do
+    DEFAULT_FILTER_BLOCK = Object.new
 
-        include Datagrid::Core
-        include Datagrid::Filters::CompositeFilters
-        class_attribute :filters_array, default: []
+    extend ActiveSupport::Concern
 
-      end
+    included do
+      include Datagrid::Core
+      class_attribute :filters_array, default: []
     end
 
+    # Grid class methods related to filters
     module ClassMethods
-
-      # Returns filter definition object by name
+      # @return [Datagrid::Filters::BaseFilter, nil] filter definition object by name
       def filter_by_name(attribute)
         if attribute.is_a?(Datagrid::Filters::BaseFilter)
           unless ancestors.include?(attribute.grid_class)
-            raise "#{attribute.grid_class}##{attribute.name} filter doen't belong to #{self.class}"
+            raise ArgumentError, "#{attribute.grid_class}##{attribute.name} filter doen't belong to #{self.class}"
           end
+
           return attribute
         end
-        self.filters.find do |filter|
+        filters.find do |filter|
           filter.name == attribute.to_sym
         end
       end
@@ -62,61 +186,58 @@ module Datagrid
       # This method automatically generates <tt>attr_accessor</tt> for filter name
       # and adds it to the list of datagrid attributes.
       #
-      # Arguments:
-      #
-      # * <tt>name</tt> - filter name
-      # * <tt>type</tt> - filter type that defines type case and GUI representation of a filter
-      # * <tt>options</tt> - hash of options
-      # * <tt>block</tt> - proc to apply the filter
-      #
-      # Available options:
-      #
-      # * <tt>:header</tt> - determines the header of the filter
-      # * <tt>:default</tt> - the default filter value. Able to accept a <tt>Proc</tt> in case default should be recalculated
-      # * <tt>:range</tt> - if true, filter can accept two values that are treated as a range that will be used for filtering
-      #   Not all of the filter types support this option. Here are the list of types that do:
-      #   <tt>:integer</tt>, <tt>:float</tt>, <tt>:date</tt>, <tt>:datetime</tt>, <tt>:string</tt>
-      # * <tt>:multiple</tt> -  if true multiple values can be assigned to this filter.
-      #   If String is assigned as a filter value, it is parsed from string using a separator symbol (`,` by default).
-      #   But you can specify a different separator as option value. Default: false.
-      # * <tt>:allow_nil</tt> - determines if the value can be nil
-      # * <tt>:allow_blank</tt> - determines if the value can be blank
-      # * <tt>:before</tt> - determines the position of this filter,
-      #   by adding it before the filter passed here (when using datagrid_form_for helper)
-      # * <tt>:after</tt> - determines the position of this filter,
-      #   by adding it after the filter passed here (when using datagrid_form_for helper)
-      # * <tt>:dummy</tt> - if true, this filter will not be applied automatically
-      #   and will be just displayed in form. In case you may want to apply it manually.
-      # * <tt>:if</tt> - specify the condition when the filter can be dislayed and used.
-      #   Accepts a block or a symbol with an instance method name
-      # * <tt>:unless</tt> - specify the reverse condition when the filter can be dislayed and used.
-      #   Accepts a block or a symbol with an instance method name
-      # * <tt>:input_options</tt> - options passed when rendering html input tag attributes.
-      #   Use <tt>input_options.type</tt> to control input type including <tt>textarea</tt>.
-      # * <tt>:label_options</tt> - options passed when rendering html label tag attributes
-      #
-      # See: https://github.com/bogdan/datagrid/wiki/Filters for examples
+      # @param [Symbol] name filter name
+      # @param [Symbol] type filter type that defines type case and GUI representation of a filter
+      # @param [Hash] options hash of options
+      # @param [Proc] block proc to apply the filter
+      # @return [Datagrid::Filters::BaseFilter] Filter definition object
+      # @see Datagrid::Filters
+      # @option options [String] header Determines the header of the filter.
+      # @option options [Object, Proc] default The default filter value. Accepts a `Proc` to allow dynamic calculation.
+      # @option options [Boolean] range Whether the filter accepts two values to define a range.
+      #   Supported by types: `:integer`, `:float`, `:date`, `:datetime`, and `:string`.
+      # @option options [Boolean, String] multiple If true, allows multiple values for the filter.
+      #   Strings are parsed using a separator (default: `,`). Can accept a custom separator. Default: `false`.
+      # @option options [Boolean] allow_nil Whether the filter value can be `nil`. Default: `false`.
+      # @option options [Boolean] allow_blank Whether the filter value can be blank. Default: `false`.
+      # @option options [Symbol] before Specifies the position of this filter by placing it before another filter.
+      #   Used with the `datagrid_form_for` helper.
+      # @option options [Symbol] after Specifies the position of this filter by placing it after another filter.
+      #   Used with the `datagrid_form_for` helper.
+      # @option options [Boolean] dummy If true, the filter is not applied automatically and
+      #   is only displayed in the form. Useful for manual application.
+      # @option options [Proc, Symbol] if Specifies a condition under which the filter is displayed and used.
+      #   Accepts a block or the name of an instance method.
+      # @option options [Proc, Symbol] unless Specifies a condition under which the filter is NOT displayed or used.
+      #   Accepts a block or the name of an instance method.
+      # @option options [Hash] input_options Options passed to the HTML input tag for rendering attributes.
+      #   Use `input_options[:type]` to control the input type (e.g., `textarea`).
+      # @option options [Hash] label_options Options passed to the HTML label tag for rendering attributes.
       def filter(name, type = :default, **options, &block)
         klass = type.is_a?(Class) ? type : FILTER_TYPES[type]
         raise ConfigurationError, "filter class #{type.inspect} not found" unless klass
 
         position = Datagrid::Utils.extract_position_from_options(filters_array, options)
-        filter = klass.new(self, name, options, &block)
+        filter = klass.new(self, name, **options, &block)
         filters_array.insert(position, filter)
 
         datagrid_attribute(name) do |value|
           filter.parse_values(value)
         end
+        filter
       end
 
+      # @!visibility private
       def default_filter
         DEFAULT_FILTER_BLOCK
       end
 
+      # @!visibility private
       def inspect
         "#{super}(#{filters_inspection})"
       end
 
+      # @return [Array<Datagrid::Filters::BaseFilter>] all defined filters
       def filters
         filters_array
       end
@@ -124,26 +245,27 @@ module Datagrid
       protected
 
       def inherited(child_class)
-        super(child_class)
-        child_class.filters_array = self.filters_array.clone
+        super
+        child_class.filters_array = filters_array.clone
       end
 
       def filters_inspection
         return "no filters" if filters.empty?
+
         filters.map do |filter|
           "#{filter.name}: #{filter.type}"
         end.join(", ")
       end
     end
 
-
     # @!visibility private
-    def initialize(*args, &block)
+    def initialize(...)
       self.filters_array = self.class.filters_array.clone
-      self.filters_array.each do |filter|
-        self[filter.name] = filter.default(self)
+      filters_array.each do |filter|
+        value = filter.default(self)
+        self[filter.name] = value unless value.nil?
       end
-      super(*args, &block)
+      super
     end
 
     # @!visibility private
@@ -151,68 +273,71 @@ module Datagrid
       apply_filters(super, filters)
     end
 
-    # Returns filter value for given filter definition
+    # @return [Object] filter value for given filter definition
     def filter_value(filter)
       self[filter.name]
     end
 
-    # Returns string representation of filter value
+    # @return [String] string representation of filter value
     def filter_value_as_string(name)
       filter = filter_by_name(name)
       value = filter_value(filter)
       if value.is_a?(Array)
-        value.map {|v| filter.format(v) }.join(filter.separator)
+        value.map { |v| filter.format(v) }.join(filter.separator)
       else
         filter.format(value)
       end
     end
 
-    # Returns filter object with the given name
+    # @return [Datagrid::Filters::BaseFilter, nil] filter object with the given name
     def filter_by_name(name)
       self.class.filter_by_name(name)
     end
 
-    # Returns assets filtered only by specified filters
-    # Allows partial filtering
+    # @return [Array<Object>] assets filtered only by specified filters
     def filter_by(*filters)
-      apply_filters(scope, filters.map{|f| filter_by_name(f)})
+      apply_filters(scope, filters.map { |f| filter_by_name(f) })
     end
 
-    # Returns select options for specific filter or filter name
-    # If given filter doesn't support select options raises `ArgumentError`
+    # @return [Array] the select options for the filter
+    # @raise [ArgumentError] if the filter doesn't support select options
     def select_options(filter)
       find_select_filter(filter).select(self)
     end
 
-    # Sets all options as selected for a filter that has options
+    # @return [void] sets all options as selected for a filter that has options
     def select_all(filter)
       filter = find_select_filter(filter)
       self[filter.name] = select_values(filter)
     end
 
-    # Returns all values that can be set to a filter with select options
+    # @return [Array] all possible values for the filter
     def select_values(filter)
       find_select_filter(filter).select_values(self)
     end
 
-    def default_filter
-      self.class.default_filter
-    end
-
-    # Returns all currently enabled filters
+    # @return [Array<Datagrid::Filters::BaseFilter>] all currently enabled filters
     def filters
       self.class.filters.select do |filter|
         filter.enabled?(self)
       end
     end
 
+    # @!visibility private
+    def default_filter
+      self.class.default_filter
+    end
+
     protected
 
     def find_select_filter(filter)
       filter = filter_by_name(filter)
       unless filter.class.included_modules.include?(::Datagrid::Filters::SelectOptions)
-        raise ::Datagrid::ArgumentError,
-          "#{self.class.name}##{filter.name} with type #{FILTER_TYPES.invert[filter.class].inspect} can not have select options"
+        type = FILTER_TYPES.invert[filter.class].inspect
+        raise(
+          ::Datagrid::ArgumentError,
+          "#{self.class.name}##{filter.name} with type #{type} can not have select options",
+        )
       end
       filter
     end