warped 0.2.0 → 1.0.0

data/lib/warped/controllers/filterable.rb

@@ -3,6 +3,8 @@
 require "active_support/concern"
 require "active_support/core_ext/class/attribute"
 require "active_support/core_ext/enumerable"
+require "active_support/core_ext/hash/indifferent_access"
+require "active_support/core_ext/object/blank"
 
 module Warped
   module Controllers
@@ -40,7 +42,7 @@ module Warped
     #   class UsersController < ApplicationController
     #     include Filterable
     #
-    #     filterable_by :name, :created_at, 'accounts.kind' => 'kind'
+    #     filterable_by :name, :created_at, 'accounts.kind' => { alias_name: 'kind' }
     #
     #     def index
     #       scope = filter(User.joins(:account))
@@ -74,71 +76,102 @@ module Warped
     # Example requests:
     #   GET /users?created_at[]=2020-01-01&created_at[]=2020-01-03&created_at.rel=in
     #   GET /users?created_at[]=2020-01-01&created_at[]=2020-01-03&created_at.rel=between
+    #
+    # Setting types and casting:
+    # By default, the filter values are cast to strings. If you want to cast the values to a specific type,
+    # and validate that the values are of the correct type, you can pass the kind of the filter to
+    # the +filterable_by+ method.
+    #
+    # Example:
+    #
+    #   class UsersController < ApplicationController
+    #     include Filterable
+    #
+    #     filterable_by :name, :created_at, 'accounts.active' => { kind: :integer, alias_name: 'active' }
+    #
+    #     def index
+    #       scope = filter(User.joins(:account))
+    #       render json: scope
+    #     end
+    #   end
+    #
+    # Example requests:
+    #   GET /users?active=1
+    #
+    # The +kind+ parameter will be cast to an integer.
+    # If the value is not an integer, an error will be raised, and the response will be a 400 Bad Request.
+    #
+    # In order to change the error message, you can rescue from the +Filter::ValueError+ exception, or
+    # override the +render_invalid_filter_value+ method.
+    #
+    #   def render_invalid_filter_value(exception)
+    #     render action_name, status: :bad_request
+    #   end
+    #
     module Filterable
       extend ActiveSupport::Concern
 
       included do
-        class_attribute :filter_fields, default: []
-        class_attribute :mapped_filter_fields, default: []
+        class_attribute :filters, default: []
+        class_attribute :strict_filtering, default: false
+
+        helper_method :current_action_filters, :current_action_filter_values
       end
 
       class_methods do
         # @param keys [Array<Symbol,String,Hash>]
         # @param mapped_keys [Hash<Symbol,String>]
-        def filterable_by(*keys, **mapped_keys)
-          self.filter_fields = keys
-          self.mapped_filter_fields = mapped_keys.to_a
-        end
-      end
+        def filterable_by(*keys, strict: nil, **mapped_keys)
+          self.strict_filtering = strict unless strict.nil?
 
-      # @param scope [ActiveRecord::Relation]
-      # @param filter_conditions [Array<Hash>]
-      # @option filter_conditions [Symbol,String] :field
-      # @option filter_conditions [String,Integer,Array<String,Integer>] :value
-      # @option filter_conditions [String] :relation
-      # @return [ActiveRecord::Relation]
-      def filter(scope, filter_conditions: filter_conditions(*filter_fields, *mapped_filter_fields))
-        Warped::Queries::Filter.call(scope, filter_conditions:)
-      end
+          self.filters = keys.map do |field|
+            Warped::Filter.build(nil, field, strict:)
+          end
 
-      # @param fields [Array<Symbol,String>]
-      # @return [Array<Hash>]
-      def filter_conditions(*fields)
-        fields.filter_map do |filter_opt|
-          field = filter_name(filter_opt)
+          complex_filters = mapped_keys.with_indifferent_access
 
-          next if filter_value(filter_opt).blank? && %w[is_null is_not_null].exclude?(filter_rel_value(filter_opt))
+          self.filters += complex_filters.map do |field_name, opts|
+            kind = opts[:kind]
+            alias_name = opts[:alias_name]
 
-          {
-            field:,
-            value: filter_value(filter_opt),
-            relation: filter_rel_value(filter_opt).presence || (filter_value(filter_opt).is_a?(Array) ? "in" : "eq")
-          }
+            Warped::Filter.build(kind, field_name, alias_name:, strict:)
+          end
         end
       end
 
-      def filterable_by
-        @filterable_by ||= self.class.filter_fields.concat(self.class.mapped_filter_fields)
+      # @param scope [ActiveRecord::Relation]
+      # @param filter_conditions [Array<Warped::Filter::Base>|nil]
+      # @return [ActiveRecord::Relation]
+      def filter(scope, filter_conditions: nil)
+        action_filters = filter_conditions.presence || filters
+        @current_action_filters = action_filters
+        @current_action_filter_values = parse_filter_params
+
+        Warped::Queries::Filter.call(scope, filter_conditions: current_action_filter_values.map(&:to_h))
       end
 
-      private
+      # @return [Array<Hash>]
+      def parse_filter_params
+        current_action_filters.filter_map do |filter|
+          raw_value = params[filter.parameter_name]
+          raw_relation = params["#{filter.parameter_name}.rel"]
 
-      def filter_name(filter)
-        filter.is_a?(Array) ? filter.first : filter
-      end
+          filter_value = filter.class::Value.new(filter, raw_relation.presence || "eq", raw_value.presence)
 
-      def filter_mapped_name(filter)
-        filter.is_a?(Array) ? filter.last : filter
+          next if filter_value.empty?
+
+          filter_value
+        end
       end
 
-      def filter_value(filter)
-        param_key = filter_mapped_name(filter)
-        params[param_key]
+      # @return [Array<Warped::Filter::Base>]
+      def current_action_filters
+        @current_action_filters ||= []
       end
 
-      def filter_rel_value(filter)
-        param_key = filter_mapped_name(filter)
-        params["#{param_key}.rel"]
+      # @return [Array<Warped::Filter::Base::Value>]
+      def current_action_filter_values
+        @current_action_filter_values ||= []
       end
     end
   end

data/lib/warped/controllers/pageable/ui.rb

@@ -14,24 +14,28 @@ module Warped
           helper_method :pagination, :paginated?, :paginate_url_params
         end
 
+        # @return [Hash] The paginate_url_params
         def paginate_url_params(**options)
           url_params = { page:, per_page: }
           url_params.merge!(options)
-          url_params
         end
 
+        # @see Pageable#pagination
+        # @return [Hash]
         def pagination
           super.tap do |hsh|
             hsh[:series] = series(hsh[:page], hsh[:total_pages])
           end
         end
 
+        # @see Pageable#paginate
         def paginate(...)
           @paginated = true
 
           super
         end
 
+        # @return [Boolean] Whether the current action is paginated.
         def paginated?
           @paginated ||= false
         end
@@ -45,13 +49,19 @@ module Warped
         #   the current page is a string, the others are integers
         #   series example: [1, :gap, 7, 8, "9", 10, 11, :gap, 36]
         def series(page, total_pages)
+          current_page = [page, total_pages].min
           return [] if total_pages.zero?
           return ["1"] if total_pages == 1
 
           if total_pages <= 9
-            (1..(page - 1)).to_a + [page.to_s] + ((page + 1)..total_pages).to_a
+            (1..(current_page - 1)).to_a + [current_page.to_s] + ((current_page + 1)..total_pages).to_a
+          elsif current_page <= 5
+            [*(1..6).to_a.map { |i| i == page ? i.to_s : i }, :gap, total_pages]
+          elsif current_page >= total_pages - 4
+            [1, :gap, *(total_pages - 5..total_pages).to_a.map { |i| i == current_page ? i.to_s : i }]
           else
-            [1, :gap, page - 2, page - 1, page.to_s, page + 1, page + 2, :gap, total_pages]
+            [1, :gap, current_page - 2, current_page - 1, current_page.to_s, current_page + 1, current_page + 2, :gap,
+             total_pages]
           end
         end
       end

data/lib/warped/controllers/pageable.rb

@@ -112,7 +112,7 @@ module Warped
       #
       # @return [String,Integer] The number of records per page.
       def per_page
-        params[:per_page].presence || self.class.default_per_page
+        params[:per_page].presence || default_per_page
       end
 
       # Retrieves pagination metadata.

data/lib/warped/controllers/searchable/ui.rb

@@ -14,20 +14,22 @@ module Warped
           helper_method :searched?, :search_url_params
         end
 
+        # @see Searchable#search
         def search(...)
           @searched = true
 
           super
         end
 
+        # @return [Boolean] Whether the current action is searched.
         def searched?
           @searched ||= false
         end
 
+        # @return [Hash] The search_url_params
         def search_url_params(**options)
           url_params = { search_param => search_term }
           url_params.merge!(options)
-          url_params
         end
       end
     end

data/lib/warped/controllers/sortable/ui.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "active_support/concern"
+require "active_support/core_ext/object/blank"
 
 module Warped
   module Controllers
@@ -11,46 +12,40 @@ module Warped
         include Sortable
 
         included do
-          helper_method :sorted?, :sort_url_params, :sort_key, :sort_direction
+          helper_method :attribute_name, :sorted?, :sorted_field?, :sortable_field?, :sort_url_params
         end
 
+        # @see Sortable#sort
         def sort(...)
           @sorted = true
 
           super
         end
 
-        def sorted?
-          @sorted ||= false
+        # @param parameter_name [String]
+        # @return [Boolean]
+        def sorted_field?(parameter_name)
+          current_action_sort_value.parameter_name == parameter_name.to_s
         end
 
-        def sort_url_params(**options)
-          url_params = { sort_key:, sort_direction: }
-          url_params.merge!(options)
-          url_params
+        # @param parameter_name [String]
+        # @return [Boolean] Whether the parameter_name is sortable.
+        def sortable_field?(parameter_name)
+          current_action_sorts.any? { |sort| sort.parameter_name == parameter_name.to_s }
         end
 
-        def sorts
-          sort_fields + mapped_sort_fields.keys
+        # @return [Boolean] Whether the current action is sorted.
+        def sorted?
+          @sorted ||= false
         end
 
-        def current_sorts
-          return [] unless params[:sort_key].present?
-
-          mapped_sort_field_param = mapped_sort_fields.value?(params[:sort_key]) ? params[:sort_key] : nil
-          sort_field_param = sort_fields.find do |field|
-            field == params[:sort_key]
-          end
-          param_sort_key = mapped_sort_field_param.presence || sort_field_param.presence
-
-          return [] unless param_sort_key.present?
-
-          [
-            {
-              key: param_sort_key,
-              value: sort_direction
-            }
-          ]
+        # @return [Hash] The sort_url_params
+        def sort_url_params(**options)
+          url_params = {
+            sort_key: current_action_sort_value.parameter_name,
+            sort_direction: current_action_sort_value.direction
+          }
+          url_params.merge!(options)
         end
       end
     end

data/lib/warped/controllers/sortable.rb

@@ -2,6 +2,7 @@
 
 require "active_support/concern"
 require "active_support/core_ext/class/attribute"
+require "active_support/core_ext/object/blank"
 
 module Warped
   module Controllers
@@ -35,7 +36,7 @@ module Warped
     #   class UsersController < ApplicationController
     #     include Sortable
     #
-    #     sortable_by :name, :created_at, 'accounts.referrals_count' => 'referrals'
+    #     sortable_by :name, :created_at, 'accounts.referrals_count' => { alias_name: 'referrals' }
     #
     #     def index
     #       scope = sort(User.joins(:account))
@@ -55,60 +56,79 @@ module Warped
       extend ActiveSupport::Concern
 
       included do
-        class_attribute :sort_fields, default: []
-        class_attribute :mapped_sort_fields, default: {}
-        class_attribute :default_sort_key, default: :id
-        class_attribute :default_sort_direction, default: :desc
+        class_attribute :sorts, default: []
+        class_attribute :default_sort, default: Sort.new("id")
+        class_attribute :default_sort_direction, default: "desc"
+
+        attr_reader :current_action_sorts
+
+        helper_method :current_action_sorts, :current_action_sort_value, :default_sort, :default_sort_direction
+
+        rescue_from Sort::DirectionError, with: :render_invalid_sort_direction
       end
 
       class_methods do
         # @param keys [Array<Symbol,String>]
         # @param mapped_keys [Hash<Symbol,String>]
         def sortable_by(*keys, **mapped_keys)
-          self.sort_fields = keys.map(&:to_s)
-          self.mapped_sort_fields = mapped_keys.with_indifferent_access
+          self.sorts = keys.map do |field|
+            Warped::Sort.new(field)
+          end
+
+          self.sorts += mapped_keys.map do |field, opts|
+            Warped::Sort.new(field, alias_name: opts[:alias_name])
+          end
+
+          return if self.sorts.any? { |sort| sort.name == default_sort.name }
+
+          self.sorts.push(default_sort)
         end
       end
 
       # @param scope [ActiveRecord::Relation] The scope to sort.
-      # @param sort_key [String, Symbol] The sort key.
-      # @param sort_direction [String, Symbol] The sort direction.
+      # @param sort_conditions [Array<Warped::Sort::Base>|nil] The sort conditions.
       # @return [ActiveRecord::Relation]
-      def sort(scope, sort_key: self.sort_key, sort_direction: self.sort_direction)
-        return scope unless sort_key && sort_direction
-
-        validate_sort_key!
+      def sort(scope, sort_conditions: nil)
+        action_sorts = sort_conditions.presence || sorts
+        @current_action_sorts = action_sorts
 
-        Queries::Sort.call(scope, sort_key:, sort_direction:)
+        Queries::Sort.call(scope, sort_key: current_action_sort_value.name,
+                                  sort_direction: current_action_sort_value.direction)
       end
 
-      protected
+      # @return [Warped::Sort::Value] The current sort value.
+      def current_action_sort_value
+        @current_action_sort_value ||= begin
+          sort_obj = current_action_sorts.find do |sort|
+            params[:sort_key] == sort.parameter_name
+          end
 
-      # @return [Symbol] The sort direction.
-      def sort_direction
-        @sort_direction ||= params[:sort_direction] || default_sort_direction
+          if sort_obj.present?
+            Sort::Value.new(sort_obj, params[:sort_direction] || default_sort_direction)
+          else
+            Sort::Value.new(default_sort, default_sort_direction)
+          end
+        end
       end
 
-      def sort_key
-        @sort_key ||= mapped_sort_fields.key(params[:sort_key]).presence ||
-                      params[:sort_key] ||
-                      default_sort_key.to_s
+      protected
+
+      # @param exception [Sort::DirectionError]
+      def render_invalid_sort_direction(exception)
+        render json: { error: exception.message }, status: :bad_request
       end
 
       private
 
-      def validate_sort_key!
-        return if valid_sort_key?
+      # @return [Warped::Sort] The current sort object.
+      def current_sort
+        @current_sort ||= begin
+          sort_obj = sorts.find do |sort|
+            params[:sort_key] == sort.parameter_name
+          end
 
-        possible_values = sort_fields + mapped_sort_fields.values
-        message = "Invalid sort key: #{sort_key}, must be one of #{possible_values}"
-        raise ActionController::BadRequest, message
-      end
-
-      def valid_sort_key?
-        sort_key == default_sort_key.to_s ||
-          sort_fields.include?(sort_key) ||
-          mapped_sort_fields[sort_key].present?
+          sort_obj.presence || Warped::Sort.new(default_sort_key)
+        end
       end
     end
   end

data/lib/warped/controllers/tabulatable/ui.rb

@@ -31,6 +31,8 @@ module Warped
           }
         end
 
+        # @param options [Hash] Additional hash of options to include in the tabulation url_params
+        # @return [Hash] The tabulation url_params
         def tabulate_url_params(**options)
           base = paginate_url_params
           base.merge!(search_url_params)
@@ -41,6 +43,8 @@ module Warped
           base.tap(&:compact_blank!)
         end
 
+        # @param options [Hash] Additional hash of options to include in the tabulation query
+        # @return [String] The tabulation query string
         def tabulate_query(**options)
           tabulate_url_params(**options).to_query
         end

data/lib/warped/controllers/tabulatable.rb

@@ -13,7 +13,7 @@ module Warped
     #   class UsersController < ApplicationController
     #     include Tabulatable
     #
-    #     tabulatable_by :name, :email, :age, 'posts.created_at', 'posts.id' => 'post_id'
+    #     tabulatable_by :email, :age, 'posts.created_at', 'posts.id' => { alias_name: 'post_id', kind: :integer }
     #
     #     def index
     #       users = User.left_joins(:posts).group(:id)
@@ -31,8 +31,8 @@ module Warped
     #   class PostsController < ApplicationController
     #     include Tabulatable
     #
-    #     tabulatable_by :title, :content, :created_at, user: 'users.name'
-    #     filterable_by :created_at, user: 'users.name'
+    #     tabulatable_by :title, :content, :created_at, user: { alias_name: 'users.name' }
+    #     filterable_by :created_at, user: { alias_name: 'users.name' }
     #
     #     def index
     #       posts = Post.left_joins(:user).group(:id)
@@ -50,16 +50,13 @@ module Warped
 
       included do
         class_attribute :tabulate_fields, default: []
-        class_attribute :mapped_tabulate_fields, default: []
+        class_attribute :mapped_tabulate_fields, default: {}
       end
 
       class_methods do
         def tabulatable_by(*keys, **mapped_keys)
-          self.tabulate_fields = keys
-          self.mapped_tabulate_fields = mapped_keys.to_a
-
-          filterable_by(*keys, **mapped_keys) if filter_fields.empty? && mapped_filter_fields.empty?
-          sortable_by(*keys, **mapped_keys) if sort_fields.empty? && mapped_sort_fields.empty?
+          filterable_by(*keys, **mapped_keys) if filters.empty?
+          sortable_by(*keys, **mapped_keys) if sorts.empty?
         end
       end
 

data/lib/warped/engine.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "rails"
+
+module Warped
+  class Engine < ::Rails::Engine
+    isolate_namespace Warped
+
+    initializer "warped.assets" do
+      if Rails.application.config.respond_to?(:assets)
+        Rails.application.config.assets.precompile += %w[warped_manifest.js]
+      end
+    end
+
+    initializer "warped.importmap", before: "importmap" do |app|
+      app.config.importmap.paths << Engine.root.join("config/importmap.rb") if Rails.application.respond_to?(:importmap)
+    end
+  end
+end

data/lib/warped/queries/filter.rb

@@ -25,7 +25,7 @@ module Warped
     # @see RELATIONS
     # To see the list of available relations, check the +RELATIONS+ constant.
     class Filter
-      RELATIONS = %w[eq neq gt gte lt lte between in not_in starts_with ends_with contains is_null is_not_null].freeze
+      RELATIONS = ::Warped::Filter::Base::RELATIONS.freeze
 
       # @param scope [ActiveRecord::Relation] the scope to filter
       # @param filter_conditions [Array<Hash>] the conditions to filter by
@@ -85,11 +85,11 @@ module Warped
         when "is_not_null"
           scope.where.not(field => nil)
         when "gt"
-          scope.where.not(field => ...value)
+          scope.where.not(field => ..value)
         when "gte"
           scope.where(field => value..)
         when "lt"
-          scope.where(field => ...value)
+          scope.where.not(field => value..)
         when "lte"
           scope.where(field => ..value)
         end

data/lib/warped/table/action.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/module/delegation"
+
+module Warped
+  module Table
+    class Action
+      attr_reader :options
+
+      delegate :[], to: :options
+
+      # @param name [String | Symbol | Proc] The name of the action
+      # @param path [String | Symbol | Proc] The path of the action
+      def initialize(name, path, **options)
+        @name = name
+        @path = path
+        @options = options
+      end
+
+      def path(...)
+        return @path.call(...) if @path.is_a?(Proc)
+
+        @path
+      end
+
+      def name(...)
+        return @name.call(...) if @name.is_a?(Proc)
+
+        @name
+      end
+    end
+  end
+end

data/lib/warped/table/column.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/object/blank"
+require "active_support/core_ext/string/inflections"
+
+module Warped
+  module Table
+    class Column
+      attr_reader :parameter_name, :method, :options
+
+      # @param parameter_name [String] The parameter name to be used by the column
+      # @param display_name [String] The display name of the column
+      # @param method [String, Symbol, Proc] The method to be called on the record to get the content of the column
+      def initialize(parameter_name, display_name = nil, method: nil, **options)
+        @parameter_name = parameter_name
+        @display_name = display_name
+        @options = options
+        @method = method.presence || parameter_name
+      end
+
+      def display_name
+        @display_name.presence || parameter_name.to_s.humanize
+      end
+
+      def content_for(record)
+        if method.is_a?(Proc)
+          method.call(record)
+        else
+          record.public_send(method)
+        end
+      end
+    end
+  end
+end

data/lib/warped/version.rb

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

data/lib/warped.rb

@@ -28,5 +28,6 @@ loader = Zeitwerk::Loader.for_gem
 loader.ignore("#{__dir__}/generators")
 loader.ignore("lib/warped/railtie.rb") unless defined?(Rails::Railtie)
 loader.collapse("#{__dir__}/warped/emails/components")
+loader.collapse("#{__dir__}/warped/api")
 loader.setup
 loader.eager_load

data/warped.gemspec

@@ -28,6 +28,6 @@ Gem::Specification.new do |spec|
   spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "rails", ">= 6.0", "< 8.0"
+  spec.add_dependency "rails", ">= 7.1.0", "<= 8.0"
   spec.add_dependency "zeitwerk", ">= 2.4"
 end