warped 0.1.0 → 1.0.0

data/docs/controllers/views/PARTIALS.md

@@ -0,0 +1,285 @@
+# Using Warped built-in view partials
+
+In order to use the built in Warped view partials, you need to include the `Warped::Controllers::<WarpedConcern>::Ui` module in your controller.
+
+## Warped::Controllers::Filterable::Ui
+```ruby
+# app/controllers/users_controller.rb
+class UsersController < ApplicationController
+  include Warped::Controllers::Filterable::Ui
+
+  def index
+    @users = filter(User.all)
+  end
+end
+```
+
+```erb
+<!-- app/views/users/index.html.erb -->
+
+<%= render "warped/filters", path: users_path, turbo_action: "replace" %>
+
+<% @users.each do |user| %>
+  <p><%= user.first_name %>, <%= user.last_name %></p>
+<% end %>
+```
+
+The `warped/_filters` partial uses [strict locals](https://edgeguides.rubyonrails.org/action_view_overview.html#strict-locals), and it accepts:
+- `path` - the path to the controller action to which the filters will be applied
+- `turbo_action` - the Turbo action to be used when submitting the form (replace/advance)
+
+The partial also accepts the following optional locals:
+- `class`: the class to be applied to the form
+- `data`: a hash of data attributes to be applied to the form
+Any other locals that are passed to the partial will be passed to the `form_with` helper.
+
+The `warped/_filters` partial will also render a set of hidden fields to store the sortable and searchable values, if the controller action called `#search` or `#sort`
+
+## Warped::Controllers::Pageable::Ui
+```ruby
+# app/controllers/users_controller.rb
+class UsersController < ApplicationController
+  include Warped::Controllers::Pageable::Ui
+
+  def index
+    @users = paginate(User.all)
+  end
+end
+```
+
+```erb
+<!-- app/views/users/index.html.erb -->
+
+<% @users.each do |user| %>
+  <p><%= user.first_name %>, <%= user.last_name %></p>
+<% end %>
+
+<%= render "warped/pagination", path: users_path, turbo_action: "replace" %>
+```
+
+The `warped/_pagination` partial uses [strict locals](https://edgeguides.rubyonrails.org/action_view_overview.html#strict-locals), and it accepts:
+- `path` - the path to the controller action to which the pagination will be applied
+- `turbo_action` - the Turbo action to be used when submitting the form (replace/advance)
+
+Any other locals that are passed to the partial will be passed to the pagination <nav> tag.
+
+The `warped/_pagination` partial will also render a set of hidden fields for each button, to store the sortable, searchable and filterable values, if the controller action called `#search`, `#sort` or `#filter`.
+
+## Warped::Controllers::Searchable::Ui
+```ruby
+# app/models/user.rb
+
+class User < ApplicationRecord
+
+  scope :search, ->(query) {
+    where("first_name ILIKE :query OR last_name ILIKE :query", query: "%#{query}%")
+  }
+end
+```
+
+```ruby
+# app/controllers/users_controller.rb
+class UsersController < ApplicationController
+  include Warped::Controllers::Searchable::Ui
+
+  def index
+    @users = search(User.all)
+  end
+end
+```
+
+```erb
+<!-- app/views/users/index.html.erb -->
+
+<%= render "warped/search", path: users_path, turbo_action: "replace" %>
+
+<% @users.each do |user| %>
+  <p><%= user.first_name %>, <%= user.last_name %></p>
+<% end %>
+```
+
+The `warped/_search` partial uses [strict locals](https://edgeguides.rubyonrails.org/action_view_overview.html#strict-locals), and it accepts:
+- `path` - the path to the controller action to which the search will be applied
+- `turbo_action` - the Turbo action to be used when submitting the form (replace/advance)
+Any other locals that are passed to the partial will be passed to the search `form_with` helper.
+
+The `warped/_search` partial will also render a set of hidden fields to store the sortable, filterable and pagination values, if the controller action called `#sort`, `#filter` or `#paginate`.
+
+## Warped::Controllers::Tabulatable::Ui
+```ruby
+# app/controllers/users_controller.rb
+class UsersController < ApplicationController
+  include Warped::Controllers::Tabulatable::Ui
+
+  def index
+    @users = tabulate(User.all)
+  end
+
+  def show
+    @user = User.find(params[:id])
+  end
+
+  def destroy
+    User.find(params[:id]).destroy
+    redirect_to users_path
+  end
+end
+```
+
+```erb
+<!-- app/views/users/index.html.erb -->
+
+<%= render "warped/table", collection: @users, path: users_path, turbo_action: "replace",
+                           columns: [
+                              Warped::Table::Column.new(:first_name, "First Name"),
+                              Warped::Table::Column.new(:last_name, "Last Name")
+                           ],
+                           actions: [
+                              Warped::Table::Action.new(:show, ->(user) { user_path(user) }),
+                              Warped::Table::Action.new(:destroy, ->(user) { user_path(user) }, data: { turbo_method: "delete", turbo_confirm: "Are you sure?" })
+                           ] %>
+```
+
+The `warped/_table` partial uses [strict locals](https://edgeguides.rubyonrails.org/action_view_overview.html#strict-locals), and it accepts:
+- `collection` - the collection of records to be displayed
+- `path` - the path to the controller action to which the table filtering/sorting/searching/pagination will be applied
+- `turbo_action` - the Turbo action to be used when submitting the form (replace/advance)
+- `columns` - an array of `Warped::Table::Column` objects that define the columns to be displayed
+- `actions` - an array of `Warped::Table::Action` objects that define the actions to be displayed for each record
+Any other locals under the keys `:table`, `:filters`, `:search` or `:pagination` are passed to the respective partials.
+Example:
+```erb
+<%= render "warped/table", collection: @users, path: users_path, turbo_action: "replace",
+                           columns: [
+                             Warped::Table::Column.new(:first_name, "First Name"),
+                             Warped::Table::Column.new(:last_name, "Last Name")
+                           ],
+                           actions: [
+                             Warped::Table::Action.new(:show, ->(user) { user_path(user) }),
+                             Warped::Table::Action.new(:destroy, ->(user) { user_path(user) }, data: { turbo_method: "delete", turbo_confirm: "Are you sure?" })
+                           ],
+                           table: { class: "table" },
+                           filters: { class: "filters" },
+                           search: { class: "search" },
+                           pagination: { class: "pagination" } %>
+```
+This will render the table with the class `table`, and it will forward the locals:
+- `class: "filters"` to the `warped/_filters` partial
+- `class: "search"` to the `warped/_search` partial
+- `class: "pagination"` to the `warped/_pagination` partial
+
+### Using the `Warped::Table::Column` class
+The `Warped::Table::Column` class is used to define the columns to be displayed in the table. The initializer accepts the following arguments:
+- `parameter_name` - the name of the parameter/alias_name passed to the `filterable_by`/`sortable_by`/`tabulatable_by` methods
+- `display_name`(optional) - the name to be displayed in the table header
+- `method`(optional) - this can be a symbol or a lambda. If the method is a symbol, it will be called on the record to get the value. If the method is a lambda, it will be called with the record as an argument.
+
+### Using the `Warped::Table::Action` class
+The `Warped::Table::Action` class is used to define the actions to be displayed for each record in the table. The initializer accepts the following arguments:
+- `name` - the name of the action. If the name is a symbol or a string, it will be used as the action name. If the name is a lambda, it will be called with the record as an argument.
+- `path` - the path to the controller action to which the action will be applied. If the path is a lambda, it will be called with the record as an argument.
+
+
+## Using turbo-frames with the partials
+The partials can be used with turbo-frames to provide a seamless experience, regardless of the action used in the controller.
+
+```ruby
+# app/controllers/user_controller.rb
+class UserController < ApplicationController
+  include Warped::Controllers::Tabulatable::Ui
+
+  tabulatable_by title: { kind: :string }, published_at: { kind: :date_time },
+
+  def show
+    @user = current_user
+    @posts = tabulate(@user.posts)
+  end
+end
+```
+
+```erb
+<!-- app/views/users/show.html.erb -->
+<h1><%= @user.name %></h1>
+
+<%= turbo_frame_tag dom_id(@posts) do %>
+  <%= render "warped/table", collection: @posts, path: user_path, turbo_action: "advance",
+                             columns: [
+                               Warped::Table::Column.new(:title, "Title"),
+                               Warped::Table::Column.new(:published_at, "Published At")
+                             ],
+                             actions: [
+                               <%# pass target: "_top" to the action, to escape from the turbo_frame navigation %>
+                               Warped::Table::Action.new(:show, ->(post) { post_path(post) }, target: "_top")
+                             ] %>
+<% end %>
+```
+
+## Styling the partials
+The partials are designed to be as unobtrusive as possible, and they can be styled using the classes passed as locals to the partials, or by modifying the partials css classes.
+
+The css classes are in the following files:
+– `app/assets/stylesheets/warped/base.css` - the base css variables
+- `app/assets/stylesheets/warped/filters.css` - the css classes for the filters partial
+- `app/assets/stylesheets/warped/pagination.css` - the css classes for the pagination partial
+- `app/assets/stylesheets/warped/search.css` - the css classes for the search partial
+- `app/assets/stylesheets/warped/table.css` - the css classes for the table partial
+
+You can override the css classes by adding the following to your css file:
+```css
+@import "warped/base.css";
+@import "warped/filters.css";
+@import "warped/pagination.css";
+@import "warped/search.css";
+@import "warped/table.css";
+```
+
+## Moving logic from the view to the controller
+Using the "warped/_table" can introduce a lot of logic in the view. To move the logic to the controller, you can instantiate the Columns and Actions in the controller and use them in the view as instance variables.
+
+```ruby
+# app/controllers/users_controller.rb
+class UsersController < ApplicationController
+  include Warped::Controllers::Tabulatable::Ui
+
+  helper_method :columns_for_index, :actions_for_index
+
+  tabulatable_by first_name: { kind: :string },
+                 last_name: { kind: :string },
+                 email: { kind: :string },
+                 created_at: { kind: :date_time, alias_name: :registered_at },
+                 status: { kind: :date_time }
+
+  def index
+    users_query = User.all.select("users.*, CASE WHEN confirmed_at IS NULL THEN 'Inactive' ELSE 'Active' END AS status")
+    @users = tabulate(users_query)
+  end
+
+  ...
+
+  private
+
+  def columns_for_index
+    [
+      Warped::Table::Column.new(:first_name, "First Name"),
+      Warped::Table::Column.new(:last_name, "Last Name"),
+      Warped::Table::Column.new(:email, "Email"),
+      Warped::Table::Column.new(:registered_at, "Registered At"),
+      Warped::Table::Column.new(:status, "Status")
+    ]
+  end
+
+  def actions_for_index
+    [
+      Warped::Table::Action.new(:show, ->(user) { user_path(user) }),
+      Warped::Table::Action.new(:edit, ->(user) { edit_user_path(user) }),
+      Warped::Table::Action.new(:destroy, ->(user) { user_path(user) }, data: { turbo_method: "delete", turbo_confirm: "Are you sure?" })
+    ]
+  end
+```
+
+```erb
+<!-- app/views/users/index.html.erb -->
+<%= render "warped/table", collection: @users, path: users_path, turbo_action: "replace",
+                           columns: columns_for_index,
+                           actions: actions_for_index %>
+```

data/docs/jobs/README.md

@@ -0,0 +1,22 @@
+# Warped::Jobs
+
+The gem provides a `Warped::Jobs::Base` class that can be used to create background jobs in a rails application.
+
+```ruby
+class PrintJob < Warped::Jobs::Base
+  def perform
+    puts 'Hello, world!'
+  end
+end
+```
+
+Warped::Jobs::Base is a subclass of ActiveJob::Base, and can be used as a regular ActiveJob job.
+
+The superclass can be overriden to inherit from a different job class, by changing it in the `config/initializers/warped.rb` file.
+
+```ruby
+# config/initializers/warped.rb
+Warped.configure do |config|
+  config.job_superclass = 'ApplicationJob'
+end
+```

data/docs/services/README.md

@@ -0,0 +1,81 @@
+# Warped::Services
+
+The gem provides a `Warped::Service::Base` class that can be used to create services in a rails application.
+
+```ruby
+class PrintService < Warped::Service::Base
+  def call
+    puts 'Hello, world!'
+  end
+end
+```
+
+The `call` method is the entry point for the service. It can be overridden to provide the service's functionality.
+
+```ruby
+class PrintService < Warped::Service::Base
+  def call
+    puts "Hello, #{name}!"
+  end
+
+  private
+
+  def name
+    'world'
+  end
+end
+```
+
+The way of calling the service is by calling the `call` method on the service class.
+The .call method is a class method that creates a new instance of the service, passing the arguments to the `initialize` method, and then calls the `call` method on the new instance.
+
+```ruby
+PrintService.call # Executes new.call
+```
+
+If you want to pass arguments to the service, you can so by defining the `initialize` method in the service class.
+
+```ruby
+class PrintService < Warped::Service::Base
+  def initialize(name = 'John')
+    @name = name
+  end
+
+  def call
+    puts "Hello, #{@name}!"
+  end
+end
+```
+
+```ruby
+PrintService.call # Executes new.call, prints "Hello, John!"
+PrintService.call('world') # Executes new('world').call, prints "Hello, world!"
+```
+
+## Using services as job classes in the background
+
+The `Warped::Service::Base` class provides a class method `.enable_job!` that can be used to enable the service to be used as a job class.
+
+```ruby
+class PrintService < Warped::Service::Base
+  enable_job!
+
+  def call
+    puts 'Hello, world!'
+  end
+end
+```
+
+The `enable_job!` method will define a `PrintService::Job` class that inherits from `Warped::Jobs::Base` and calls the `call` method on the service instance.
+
+```ruby
+PrintService.call_later # Executes PrintService::Job.perform_later
+PrintService::Job.perform_later # Executes PrintService.new.call in the background
+```
+
+call_later and perform_later will pass the arguments to the `initialize` method of the service class, and then call the `call` method on the new instance.
+
+```ruby
+PrintService.call_later('world') # Executes PrintService::Job.perform_later('world')
+PrintService::Job.perform_later('world') # Executes PrintService.new('world').call in the background
+```

data/lib/generators/warped/install_generator.rb

@@ -7,7 +7,7 @@ module Warped
     class InstallGenerator < Rails::Generators::Base
       source_root File.expand_path("templates", __dir__)
 
-      def say_hello
+      def install
         template "initializer.rb.tt", "config/initializers/warped.rb"
       end
     end

data/lib/warped/api/filter/base/value.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/object/blank"
+require "active_support/core_ext/module/delegation"
+
+module Warped
+  module Filter
+    class Base
+      class Value
+        attr_reader :filter
+
+        delegate :name, :alias_name, :parameter_name, :kind, to: :filter
+
+        # @param filter [Warped::Filter::Base] The filter object
+        # @param relation [String] The filter relation.
+        # @param value [String] The filter value.
+        def initialize(filter, relation, value)
+          @filter = filter
+          @relation = relation
+          @value = value
+        end
+
+        # @return [String] The casted filter value.
+        def value
+          filter.cast(@value)
+        end
+
+        # @return [String] The validated filter relation.
+        def relation
+          filter.relation(@relation)
+        end
+
+        # @return [Boolean] Whether the filter is empty.
+        def empty?
+          value.nil? && !%w[is_null is_not_null].include?(relation)
+        end
+
+        def to_h
+          {
+            field: filter.name,
+            relation:,
+            value:
+          }
+        end
+
+        # Some filters may need to be parsed/formatted differently for the HTML input value.
+        # This method can be overridden in the filter value class to provide a different value.
+        alias html_value value
+      end
+    end
+  end
+end

data/lib/warped/api/filter/base.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/module/delegation"
+require "active_support/core_ext/object/blank"
+require "active_support/core_ext/string/inflections"
+
+module Warped
+  module Filter
+    class Base
+      RELATIONS = %w[eq neq gt gte lt lte between in not_in starts_with ends_with contains is_null is_not_null].freeze
+
+      attr_reader :name, :strict, :alias_name, :options
+
+      delegate :[], to: :options
+
+      # @return [Symbol, nil] The filter kind.
+      def self.kind
+        filter_type = name.demodulize.underscore.to_sym
+
+        filter_type == :filter ? nil : filter_type
+      end
+
+      # @param name [String] The name of the filter.
+      # @param alias_name [String] The alias name of the filter, used for renaming the filter key in the URL params
+      # @param options [Hash] The filter options.
+      def initialize(name, strict:, alias_name: nil, **options)
+        raise ArgumentError, "name cannot be nil" if name.nil?
+
+        @name = name.to_s
+        @strict = strict
+        @alias_name = alias_name&.to_s
+        @options = options
+      end
+
+      # @return [Symbol, nil] The filter kind.
+      def kind
+        self.class.kind
+      end
+
+      # @return [Array<String>] The valid filter relations.
+      def relations
+        self.class::RELATIONS
+      end
+
+      # @param relation [Object] The filter relation.
+      # @return [Object] The casted value.
+      # @raise [Warped::Filter::RelationError] If the relation is invalid and strict is true.
+      def cast(value)
+        return if value.nil?
+
+        value
+      end
+
+      # @param relation [String] The validated filter relation.
+      # @return [String] The validated filter relation.
+      # @raise [Warped::Filter::RelationError] If the relation is invalid and strict is true.
+      def relation(relation)
+        if valid_relation?(relation)
+          relation
+        else
+          raise RelationError, "Invalid relation: #{relation}" unless strict
+
+          "eq"
+        end
+      end
+
+      # @return [String] The name to use in the URL params.
+      def parameter_name
+        alias_name.presence || name
+      end
+
+      # @return [String] The HTML input type.
+      def html_type
+        raise NotImplementedError, "#{self.class.name}#html_type not implemented"
+      end
+
+      private
+
+      def valid_relation?(relation)
+        relations.include?(relation.to_s)
+      end
+    end
+  end
+end

data/lib/warped/api/filter/boolean.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Warped
+  module Filter
+    class Boolean < Base
+      RELATIONS = %w[eq neq is_null is_not_null].freeze
+
+      def cast(value)
+        return if value.nil?
+
+        casted_value = case value
+                       when true, false
+                         value
+                       when "true", "1", "t", 1
+                         true
+                       when "false", "0", "f", 0
+                         false
+                       end
+
+        casted_value.tap do |casted|
+          raise ValueError, "#{value} cannot be casted to #{kind}" if casted.nil? && strict
+        end
+      end
+
+      def html_type
+        "text"
+      end
+
+      class Value < Value
+        def html_value
+          case value.class
+          when TrueClass
+            "true"
+          when FalseClass
+            "false"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/warped/api/filter/date.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "date"
+require "active_support/core_ext/object/blank"
+
+module Warped
+  module Filter
+    class Date < Base
+      RELATIONS = %w[eq neq gt gte lt lte between is_null is_not_null].freeze
+
+      def cast(value)
+        return if value.blank?
+
+        ::Date.parse(value)
+      rescue ::Date::Error
+        raise ValueError, "#{value} cannot be casted to #{kind}" if strict
+
+        nil
+      end
+
+      def html_type
+        "date"
+      end
+    end
+  end
+end

data/lib/warped/api/filter/date_time.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "date"
+require "active_support/core_ext/object/blank"
+
+module Warped
+  module Filter
+    class DateTime < Base
+      RELATIONS = %w[eq neq gt gte lt lte between is_null is_not_null].freeze
+
+      def cast(value)
+        return if value.blank?
+
+        ::DateTime.parse(value)
+      rescue ::Date::Error
+        raise ValueError, "#{value} cannot be casted to #{kind}" if strict
+
+        nil
+      end
+
+      def html_type
+        "datetime-local"
+      end
+
+      class Value < Value
+        def html_value
+          value.strftime("%Y-%m-%dT%H:%M:%S")
+        end
+      end
+    end
+  end
+end

data/lib/warped/api/filter/decimal.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require "active_support/core_ext/object/blank"
+
+module Warped
+  module Filter
+    class Decimal < Base
+      RELATIONS = %w[eq neq gt gte lt lte between in not_in is_null is_not_null].freeze
+
+      def cast(value)
+        return if value.blank?
+
+        casted_value = case value
+                       when ::BigDecimal
+                         value
+                       when ::Integer, ::Float, ::String
+                         value.to_d
+                       end
+
+        casted_value.tap do |casted|
+          raise ValueError, "#{value} cannot be casted to #{kind}" if casted.nil? && strict
+        end
+      end
+
+      def html_type
+        "number"
+      end
+    end
+  end
+end