super_admin 0.2.0

data/app/services/super_admin/queries/filter_query.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+
+module SuperAdmin
+  module Queries
+    # Query object for applying typed filters (string, numeric, date, boolean, enum).
+    class FilterQuery < BaseQuery
+      STRING_TYPES = %i[string text].freeze
+      NUMERIC_TYPES = %i[integer float decimal].freeze
+      DATE_TYPES = %i[date datetime].freeze
+      BOOLEAN_TYPES = %i[boolean].freeze
+
+      attr_reader :filters, :filter_definitions
+
+      # @param scope [ActiveRecord::Relation]
+      # @param model_class [Class]
+      # @param filters [Hash] Paramètres de filtrage
+      # @param filter_definitions [Array<SuperAdmin::FilterBuilder::FilterDefinition>]
+      def initialize(scope, model_class, filters = nil, filter_definitions: nil, **kwargs)
+        super(scope, model_class)
+
+        provided_filters = if filters.is_a?(Hash) && !kwargs.key?(:filters)
+          filters
+        else
+          kwargs[:filters] || {}
+        end
+
+        provided_definitions = filter_definitions || kwargs[:filter_definitions]
+
+        @filters = provided_filters.to_h.stringify_keys
+        @filter_definitions = provided_definitions || SuperAdmin::FilterBuilder.definitions_for(model_class)
+      end
+
+      # Applies all filters
+      # @return [ActiveRecord::Relation]
+      def call
+        return scope if filters.blank?
+
+        filter_definitions.each do |definition|
+          apply_filter_for_definition(definition)
+        end
+
+        scope
+      end
+
+      private
+
+      # Applies filter based on its definition
+      # @param definition [SuperAdmin::FilterBuilder::FilterDefinition]
+      def apply_filter_for_definition(definition)
+        case definition.type
+        when *STRING_TYPES
+          apply_string_filter(definition)
+        when *NUMERIC_TYPES
+          apply_numeric_filter(definition)
+        when *DATE_TYPES
+          apply_date_filter(definition)
+        when *BOOLEAN_TYPES
+          apply_boolean_filter(definition)
+        when :enum
+          apply_enum_filter(definition)
+        end
+      end
+
+      # Applies string filter (contains)
+      # @param definition [SuperAdmin::FilterBuilder::FilterDefinition]
+      def apply_string_filter(definition)
+        key = "#{definition.attribute}_contains"
+        value = filters[key]
+        return if value.blank?
+
+        column = column_for(definition.attribute)
+        return unless column && STRING_TYPES.include?(column.type)
+
+        sanitized = ActiveRecord::Base.sanitize_sql_like(value)
+        term = "%#{sanitized.downcase}%"
+        lowered_column = Arel::Nodes::NamedFunction.new("LOWER", [ arel_table[definition.attribute] ])
+        @scope = scope.where(lowered_column.matches(Arel::Nodes.build_quoted(term)))
+      end
+
+      # Applies numeric filter (min/max)
+      # @param definition [SuperAdmin::FilterBuilder::FilterDefinition]
+      def apply_numeric_filter(definition)
+        min_key = "#{definition.attribute}_min"
+        max_key = "#{definition.attribute}_max"
+
+        if filters[min_key].present?
+          parsed_min = parse_numeric(filters[min_key], definition.type)
+          @scope = scope.where(arel_table[definition.attribute].gteq(parsed_min)) if parsed_min
+        end
+
+        if filters[max_key].present?
+          parsed_max = parse_numeric(filters[max_key], definition.type)
+          @scope = scope.where(arel_table[definition.attribute].lteq(parsed_max)) if parsed_max
+        end
+      end
+
+      # Applies date filter (from/to)
+      # @param definition [SuperAdmin::FilterBuilder::FilterDefinition]
+      def apply_date_filter(definition)
+        from_key = "#{definition.attribute}_from"
+        to_key = "#{definition.attribute}_to"
+
+        if filters[from_key].present?
+          parsed_from = parse_temporal(filters[from_key], definition.type)
+          @scope = scope.where(arel_table[definition.attribute].gteq(parsed_from)) if parsed_from
+        end
+
+        if filters[to_key].present?
+          parsed_to = parse_temporal(filters[to_key], definition.type)
+          @scope = scope.where(arel_table[definition.attribute].lteq(parsed_to)) if parsed_to
+        end
+      end
+
+      # Applies boolean filter (equals)
+      # @param definition [SuperAdmin::FilterBuilder::FilterDefinition]
+      def apply_boolean_filter(definition)
+        key = "#{definition.attribute}_equals"
+        return unless filters.key?(key)
+
+        parsed = parse_boolean(filters[key])
+        @scope = scope.where(definition.attribute => parsed) unless parsed.nil?
+      end
+
+      # Applies enum filter (equals)
+      # @param definition [SuperAdmin::FilterBuilder::FilterDefinition]
+      def apply_enum_filter(definition)
+        key = "#{definition.attribute}_equals"
+        value = filters[key]
+        return if value.blank?
+        return unless definition.options.include?(value)
+
+        @scope = scope.where(definition.attribute => value)
+      end
+
+      # Parses numeric value based on type
+      # @param value [String]
+      # @param type [Symbol]
+      # @return [Numeric, nil]
+      def parse_numeric(value, type)
+        case type
+        when :integer
+          Integer(value)
+        when :float
+          Float(value)
+        when :decimal
+          BigDecimal(value)
+        end
+      rescue ArgumentError, TypeError
+        nil
+      end
+
+      # Parses temporal value based on type
+      # @param value [String]
+      # @param type [Symbol]
+      # @return [Date, Time, nil]
+      def parse_temporal(value, type)
+        case type
+        when :date
+          Date.parse(value)
+        when :datetime
+          Time.zone.parse(value)
+        end
+      rescue ArgumentError, TypeError
+        nil
+      end
+
+      # Parses boolean value
+      # @param value [String]
+      # @return [Boolean, nil]
+      def parse_boolean(value)
+        return true if %w[true 1 yes oui].include?(value.to_s.downcase)
+        return false if %w[false 0 no non].include?(value.to_s.downcase)
+
+        nil
+      end
+
+      # Returns the ActiveRecord column definition for a given attribute.
+      # Ensures we only build filters on real columns, protecting against SQL injection.
+      # @param attribute [String, Symbol]
+      # @return [ActiveRecord::ConnectionAdapters::Column, nil]
+      def column_for(attribute)
+        model_class.columns_hash[attribute.to_s]
+      end
+    end
+  end
+end

data/app/services/super_admin/queries/resource_scope_query.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module SuperAdmin
+  module Queries
+    # Orchestrator that composes query objects to build the complete scope.
+    class ResourceScopeQuery
+      LEGACY_ARGUMENT_ERROR = "ResourceScopeQuery expects an ActiveRecord::Relation or ActiveRecord::Base subclass".freeze
+
+      attr_reader :model_class, :scope, :search, :sort_column, :direction, :filters
+
+      # @param scope_or_model_class [ActiveRecord::Relation, Class]
+      # @param search [String, nil]
+      # @param query [String, nil] Legacy alias for +search+
+      # @param sort [String, nil] Legacy alias for +sort_column+
+      # @param sort_column [String, nil]
+      # @param direction [String, nil]
+      # @param sort_direction [String, nil] Legacy alias for +direction+
+      # @param filters [Hash]
+      def initialize(scope_or_model_class, search: nil, query: nil, sort: nil, sort_column: nil,
+                     direction: nil, sort_direction: nil, filters: {})
+        relation, klass = resolve_scope_and_class(scope_or_model_class)
+
+        @scope = relation
+        @model_class = klass
+        @search = search.presence || query
+        @sort_column = sort_column || sort
+        @direction = direction || sort_direction
+        @filters = filters || {}
+      end
+
+      # Builds the complete scope by composing query objects
+      # @return [ActiveRecord::Relation]
+      def call
+        result = scope
+        result = apply_search(result)
+        result = apply_filters(result)
+        apply_sort(result)
+      end
+
+      private
+
+      # Applies full-text search
+      # @param scope [ActiveRecord::Relation]
+      # @return [ActiveRecord::Relation]
+      def apply_search(scope)
+        SearchQuery.new(scope, model_class, term: search).call
+      end
+
+      # Applies typed filters
+      # @param scope [ActiveRecord::Relation]
+      # @return [ActiveRecord::Relation]
+      def apply_filters(scope)
+        FilterQuery.new(scope, model_class, filters: filters).call
+      end
+
+      # Applies sorting
+      # @param scope [ActiveRecord::Relation]
+      # @return [ActiveRecord::Relation]
+      def apply_sort(scope)
+        SortQuery.new(scope, model_class, sort_column: sort_column, direction: direction).call
+      end
+
+      def resolve_scope_and_class(scope_or_model_class)
+        if scope_or_model_class.is_a?(ActiveRecord::Relation)
+          [ scope_or_model_class, scope_or_model_class.klass ]
+        elsif scope_or_model_class.is_a?(Class) && scope_or_model_class < ActiveRecord::Base
+          [ scope_or_model_class.all, scope_or_model_class ]
+        else
+          raise ArgumentError, LEGACY_ARGUMENT_ERROR
+        end
+      end
+    end
+  end
+end

data/app/services/super_admin/queries/search_query.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module SuperAdmin
+  module Queries
+    # Query object for full-text search on string/text columns
+    # and their belongs_to associations.
+    class SearchQuery < BaseQuery
+      attr_reader :term
+
+      # @param scope [ActiveRecord::Relation]
+      # @param model_or_term [Class, String, nil] Model class or legacy positional search term
+      # @param term [String, nil] Search term when providing the model class explicitly
+      def initialize(scope, model_or_term = nil, term: nil)
+        if model_or_term.is_a?(Class)
+          super(scope, model_or_term)
+          @term = term
+        else
+          inferred_class = scope.respond_to?(:klass) ? scope.klass : model_or_term&.class
+          super(scope, inferred_class)
+          @term = model_or_term || term
+        end
+      end
+
+      # Applies full-text search
+      # @return [ActiveRecord::Relation]
+      def call
+        return scope if term.blank?
+
+        sanitized_term = ActiveRecord::Base.sanitize_sql_like(term)
+        original_pattern = "%#{sanitized_term}%"
+        lower_pattern = "%#{sanitized_term.downcase}%"
+        patterns = [ original_pattern ]
+        patterns << lower_pattern unless lower_pattern == original_pattern
+
+        predicates = []
+
+        # Search in model columns
+        base_predicates = search_in_columns(patterns, lower_pattern)
+        predicates << base_predicates if base_predicates.present?
+
+        # Search in belongs_to associations
+        association_data = search_in_associations(patterns, lower_pattern)
+        predicates.concat(association_data[:predicates]) if association_data[:predicates].present?
+
+        return scope if predicates.empty?
+
+        result = scope
+        result = result.left_outer_joins(association_data[:associations]) if association_data[:associations].present?
+        result.where(predicates.reduce { |memo, predicate| memo.or(predicate) })
+      end
+
+      private
+
+      # Searches in model's string/text columns
+      # @param patterns [Array<String>]
+      # @param lower_pattern [String]
+      # @return [Arel::Nodes::Node, nil]
+      def search_in_columns(patterns, lower_pattern)
+        searchable_columns = columns_of_type(:string, :text)
+        return nil if searchable_columns.empty?
+
+        column_predicates = searchable_columns.map do |column|
+          build_column_predicates(column, patterns, lower_pattern)
+        end
+
+        column_predicates.reduce { |memo, predicate| memo.or(predicate) }
+      end
+
+      # Builds predicates for a given column
+      # @param column [ActiveRecord::ConnectionAdapters::Column]
+      # @param patterns [Array<String>]
+      # @param lower_pattern [String]
+      # @return [Arel::Nodes::Node]
+      def build_column_predicates(column, patterns, lower_pattern)
+        lowered_column = Arel::Nodes::NamedFunction.new("LOWER", [ arel_table[column.name] ])
+
+        column_predicates = patterns.map do |pattern|
+          arel_table[column.name].matches(Arel::Nodes.build_quoted(pattern))
+        end
+
+        column_predicates << lowered_column.matches(Arel::Nodes.build_quoted(lower_pattern))
+
+        column_predicates.reduce { |memo, predicate| memo.or(predicate) }
+      end
+
+      # Searches in belongs_to associations
+      # @param patterns [Array<String>]
+      # @param lower_pattern [String]
+      # @return [Hash] { predicates: Array, associations: Array }
+      def search_in_associations(patterns, lower_pattern)
+        return { predicates: [], associations: [] } unless model_class.respond_to?(:reflect_on_all_associations)
+
+        associations = model_class.reflect_on_all_associations(:belongs_to).reject(&:polymorphic?)
+
+        predicates = []
+        joined_associations = []
+
+        associations.each do |association|
+          association_predicates = build_association_predicates(association, patterns, lower_pattern)
+          next if association_predicates.nil?
+
+          predicates << association_predicates
+          joined_associations << association.name
+        end
+
+        { predicates: predicates, associations: joined_associations.uniq }
+      end
+
+      # Builds predicates for a given association
+      # @param association [ActiveRecord::Reflection]
+      # @param patterns [Array<String>]
+      # @param lower_pattern [String]
+      # @return [Arel::Nodes::Node, nil]
+      def build_association_predicates(association, patterns, lower_pattern)
+        begin
+          associated_class = association.klass
+        rescue NameError
+          return nil
+        end
+
+        return nil unless associated_class.respond_to?(:columns)
+        return nil unless associated_class.table_exists?
+
+        associated_columns = associated_class.columns.select { |column| %i[string text].include?(column.type) }
+        return nil if associated_columns.empty?
+
+        association_table = associated_class.arel_table
+
+        column_predicates = associated_columns.map do |column|
+          attribute = association_table[column.name]
+          lowered = Arel::Nodes::NamedFunction.new("LOWER", [ attribute ])
+
+          predicates_for_column = patterns.map do |pattern|
+            attribute.matches(Arel::Nodes.build_quoted(pattern))
+          end
+
+          predicates_for_column << lowered.matches(Arel::Nodes.build_quoted(lower_pattern))
+
+          predicates_for_column.reduce { |memo, predicate| memo.or(predicate) }
+        end
+
+        column_predicates.reduce { |memo, predicate| memo.or(predicate) }
+      end
+    end
+  end
+end

data/app/services/super_admin/queries/sort_query.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module SuperAdmin
+  module Queries
+    # Query object for sorting on a given column.
+    class SortQuery < BaseQuery
+      attr_reader :sort_column, :direction
+
+      # @param scope [ActiveRecord::Relation]
+      # @param model_class [Class]
+      # @param sort_column [String, nil] Sort column name
+      # @param direction [String, nil] Direction (asc/desc)
+      def initialize(scope, model_class, sort_column: nil, direction: nil)
+        super(scope, model_class)
+        @sort_column = sort_column
+        @direction = direction
+      end
+
+      # Applies sorting
+      # @return [ActiveRecord::Relation]
+      def call
+        return default_sort if sort_column.blank?
+
+        column = model_class.columns_hash[sort_column.to_s]
+        return default_sort unless column
+
+        sanitized_direction = direction == "desc" ? :desc : :asc
+        arel_column = arel_table[column.name]
+        scope.order(arel_column.public_send(sanitized_direction))
+      end
+
+      private
+
+      # Default sort by id descending
+      # @return [ActiveRecord::Relation]
+      def default_sort
+        scope.order(id: :desc)
+      end
+    end
+  end
+end

data/app/services/super_admin/resource_configuration.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module SuperAdmin
+  # Provides configuration helpers for models managed in SuperAdmin.
+  class ResourceConfiguration
+    DISPLAY_EXCLUDED_ATTRIBUTES = %w[created_at updated_at].freeze
+    EDIT_EXCLUDED_ATTRIBUTES = %w[id created_at updated_at].freeze
+    SENSITIVE_ATTRIBUTES = %w[
+      encrypted_password
+      reset_password_token
+      reset_password_sent_at
+      remember_created_at
+      confirmation_token
+      confirmation_sent_at
+      unconfirmed_email
+      unlock_token
+      locked_at
+      invitation_token
+      invitation_sent_at
+      invitation_accepted_at
+      invitation_message
+      authentication_token
+      access_token
+      refresh_token
+      api_key
+    ].freeze
+    PRIORITY_ATTRIBUTES = %w[id email name title full_name first_name last_name].freeze
+
+    class << self
+      # Returns the list of displayable attributes for a resource.
+      # @param model_class [Class]
+      # @return [Array<String>]
+      def displayable_attributes(model_class)
+        base_attributes = model_class.attribute_names.reject do |attr|
+          DISPLAY_EXCLUDED_ATTRIBUTES.include?(attr) || SENSITIVE_ATTRIBUTES.include?(attr)
+        end
+
+        prioritized = PRIORITY_ATTRIBUTES.compact.select do |attr|
+          base_attributes.include?(attr) || attr == model_class.primary_key
+        end
+
+        (prioritized + base_attributes).uniq
+      end
+
+      # Returns the list of editable attributes (used by dynamic forms).
+      # @param model_class [Class]
+      # @return [Array<String>]
+      def editable_attributes(model_class)
+        base_attributes = model_class.attribute_names.reject do |attr|
+          EDIT_EXCLUDED_ATTRIBUTES.include?(attr) || SENSITIVE_ATTRIBUTES.include?(attr)
+        end
+
+        nested_attributes = if model_class.respond_to?(:nested_attributes_options)
+          model_class.nested_attributes_options.keys.map { |name| "#{name}_attributes" }
+        else
+          []
+        end
+
+        (base_attributes + nested_attributes).uniq
+      end
+    end
+  end
+end

data/app/services/super_admin/resource_exporter.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "csv"
+require "stringio"
+
+module SuperAdmin
+  # Generates a CSV export for a SuperAdmin resource respecting visible attributes.
+  class ResourceExporter
+    BATCH_SIZE = 1000
+
+    def initialize(model_class, scope, attributes: nil)
+      @model_class = model_class
+      @scope = scope
+      @attributes = attributes.presence || model_class.attribute_names
+    end
+
+    # Writes CSV content to a given IO (Tempfile, StringIO, etc.).
+    # @param io [IO]
+    def write_to(io)
+      csv = CSV.new(io, headers: header_row, write_headers: true)
+      export_scope.find_in_batches(batch_size: BATCH_SIZE) do |batch|
+        batch.each do |record|
+          csv << data_row(record)
+        end
+        io.flush if io.respond_to?(:flush)
+      end
+    end
+
+    # @return [String] contenu CSV avec en-têtes (utilisé principalement pour tests)
+    def to_csv
+      buffer = StringIO.new
+      write_to(buffer)
+      buffer.rewind
+      buffer.read
+    ensure
+      buffer&.close
+    end
+
+    private
+
+    attr_reader :model_class, :scope, :attributes
+
+    def header_row
+      attributes.map { |attr| model_class.human_attribute_name(attr) }
+    end
+
+    def data_row(record)
+      attributes.map do |attr|
+        value = record.public_send(attr)
+        format_value(value)
+      end
+    end
+
+    def export_scope
+      relation = scope
+      if relation.respond_to?(:except)
+        relation = relation.except(:select, :includes, :preload, :eager_load)
+      end
+      relation = relation.reorder(nil) if relation.order_values.any?
+      relation = relation.limit(nil) if relation.respond_to?(:limit)
+      relation = relation.offset(nil) if relation.respond_to?(:offset)
+      relation
+    end
+
+    def format_value(value)
+      case value
+      when nil
+        ""
+      when true, false
+        value ? "true" : "false"
+      when Time, Date, DateTime, ActiveSupport::TimeWithZone
+        value.iso8601
+      else
+        value.to_s
+      end
+    end
+  end
+end

data/app/services/super_admin/resource_query.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module SuperAdmin
+  # Builds ActiveRecord scopes for SuperAdmin resources (search, filters, sort).
+  # Delegates logic to query objects for better separation of concerns.
+  class ResourceQuery
+    class << self
+      # Returns the filtered scope ready for pagination/export.
+      # @param model_class [Class]
+      # @param search [String, nil]
+      # @param sort [String, nil]
+      # @param direction [String, nil]
+      # @param filters [Hash]
+      def filtered_scope(model_class, search:, sort:, direction:, filters: {})
+        SuperAdmin::Queries::ResourceScopeQuery.new(
+          model_class,
+          search: search,
+          sort_column: sort,
+          direction: direction,
+          filters: filters
+        ).call
+      end
+
+      # DEPRECATED: Use SuperAdmin::Queries::SearchQuery directly
+      def apply_search(scope, model_class, term)
+        SuperAdmin::Queries::SearchQuery.new(scope, model_class, term: term).call
+      end
+
+      # DEPRECATED: Use SuperAdmin::Queries::SortQuery directly
+      def apply_sort(scope, model_class, sort, direction)
+        SuperAdmin::Queries::SortQuery.new(scope, model_class, sort_column: sort, direction: direction).call
+      end
+
+      # DEPRECATED: Method kept for compatibility but not used
+      def association_search_predicates(model_class, patterns:, lower_pattern:)
+        { predicates: [], associations: [] }
+      end
+    end
+  end
+end