warped 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 967b7e175b3e607946af10eef1af2cd6400d8bcb294a7a49a3298568b6234b25
-  data.tar.gz: f959ca8e38e009e9a59daecab21fb4ae855e2f3ad516a660b69c29c6acb219f3
+  metadata.gz: c1c6444d0d93fbbfa88436418e69edc9e44e228402d56becbc99bd7eae122f14
+  data.tar.gz: 4eeeb9b833549db2c33a67fa73627e3e55f27dda5178d9f2f377b989f64739a0
 SHA512:
-  metadata.gz: 5665f91cf7cb50151006cf7852283c4a5da5e05506a039eb70a8464738fee9b1c7903f530e1301489a9788f5781ef10e095efdd4acd19fe7e9fa253845b6beec
-  data.tar.gz: b6c2c71ab7de2ac911d599135a166a00e5a62870be1182c445f994656186d4f7fabf156fd6c513b5699ca3747ba9cd4351560b2441703ceca0576059ae4cf8f0
+  metadata.gz: 486f3074c354576fb33e04df666248b27e4b0f2dd13a6ce1256c9ec66c9ad786a158010b199b80f11761b5c5bcc83af5ee3f6c01b5a631de83da53a706d5c520
+  data.tar.gz: 2a3f730c41a5f42c92aac9c3e2708caf0f803f157771a25be75b524304ec1f7203056ae4f7bc40675b7c2aef779f7dce7a2e54cb6a494ded18261361eef84237

data/.rubocop.yml

@@ -18,13 +18,38 @@ Layout/LineLength:
   Exclude:
     - "lib/warped/queries/paginate.rb"
 
+Metrics/AbcSize:
+  Exclude:
+    - "lib/warped/controllers/filterable/ui.rb"
+    - "lib/warped/controllers/pageable/ui.rb"
+    - "lib/warped/controllers/sortable/ui.rb"
+    - "lib/warped/emails/components/**/*.rb"
+    - "lib/warped/queries/filter.rb"
+
 Metrics/BlockLength:
   Exclude:
+    - "lib/warped/emails/components/**/*.rb"
     - "spec/**/*"
 
+Metrics/ParameterLists:
+  Exclude:
+    - "lib/warped/emails/components/**/*.rb"
+
+Metrics/PerceivedComplexity:
+  Exclude:
+    - "lib/warped/controllers/pageable/ui.rb"
+
 Metrics/CyclomaticComplexity:
   Exclude:
+    - "lib/warped/controllers/pageable/ui.rb"
     - "lib/warped/queries/filter.rb"
 
 Metrics/MethodLength:
   Max: 20
+  Exclude:
+    - lib/warped/queries/filter.rb
+
+Style/OptionalArguments:
+  Exclude:
+    - lib/warped/emails/components/button.rb
+    - lib/warped/emails/components/link.rb

data/Gemfile

@@ -10,5 +10,3 @@ gem "rake", "~> 13.0"
 gem "rspec", "~> 3.0"
 
 gem "rubocop", "~> 1.21"
-
-gem "debug", "~> 1.5", platforms: %i[mri mingw x64_mingw]

data/Gemfile.lock

@@ -1,8 +1,8 @@
 PATH
   remote: .
   specs:
-    warped (0.1.0)
-      rails (>= 6.0, < 8.0)
+    warped (1.0.0)
+      rails (>= 7.1, <= 8.0)
       zeitwerk (>= 2.4)
 
 GEM
@@ -90,12 +90,8 @@ GEM
     connection_pool (2.4.1)
     crass (1.0.6)
     date (3.3.4)
-    debug (1.9.1)
-      irb (~> 1.10)
-      reline (>= 0.3.8)
     diff-lcs (1.5.1)
-    drb (2.2.0)
-      ruby2_keywords
+    drb (2.2.1)
     erubi (1.12.0)
     globalid (1.2.1)
       activesupport (>= 6.1)
@@ -115,7 +111,7 @@ GEM
       net-imap
       net-pop
       net-smtp
-    marcel (1.0.2)
+    marcel (1.0.4)
     mini_mime (1.1.5)
     minitest (5.22.2)
     mutex_m (0.2.0)
@@ -129,8 +125,18 @@ GEM
     net-smtp (0.4.0.1)
       net-protocol
     nio4r (2.7.0)
+    nokogiri (1.16.2-aarch64-linux)
+      racc (~> 1.4)
+    nokogiri (1.16.2-arm-linux)
+      racc (~> 1.4)
     nokogiri (1.16.2-arm64-darwin)
       racc (~> 1.4)
+    nokogiri (1.16.2-x86-linux)
+      racc (~> 1.4)
+    nokogiri (1.16.2-x86_64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.16.2-x86_64-linux)
+      racc (~> 1.4)
     parallel (1.24.0)
     parser (3.3.0.5)
       ast (~> 2.4.1)
@@ -180,7 +186,7 @@ GEM
     rdoc (6.6.2)
       psych (>= 4.0.0)
     regexp_parser (2.9.0)
-    reline (0.4.2)
+    reline (0.4.3)
       io-console (~> 0.5)
     rexml (3.2.6)
     rspec (3.13.0)
@@ -196,7 +202,7 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
     rspec-support (3.13.1)
-    rubocop (1.60.2)
+    rubocop (1.61.0)
       json (~> 2.3)
       language_server-protocol (>= 3.17.0)
       parallel (~> 1.10)
@@ -207,12 +213,11 @@ GEM
       rubocop-ast (>= 1.30.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 3.0)
-    rubocop-ast (1.30.0)
-      parser (>= 3.2.1.0)
+    rubocop-ast (1.31.1)
+      parser (>= 3.3.0.4)
     ruby-progressbar (1.13.0)
-    ruby2_keywords (0.0.5)
     stringio (3.1.0)
-    thor (1.3.0)
+    thor (1.3.1)
     timeout (0.4.1)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
@@ -224,17 +229,18 @@ GEM
     zeitwerk (2.6.13)
 
 PLATFORMS
-  arm64-darwin-21
-  arm64-darwin-22
-  arm64-darwin-23
+  aarch64-linux
+  arm-linux
+  arm64-darwin
+  x86-linux
+  x86_64-darwin
   x86_64-linux
 
 DEPENDENCIES
-  debug (~> 1.5)
   rake (~> 13.0)
   rspec (~> 3.0)
   rubocop (~> 1.21)
   warped!
 
 BUNDLED WITH
-   2.3.26
+   2.5.6

data/README.md

@@ -7,7 +7,7 @@ Develop rails applications at the speed of thought. Warped is a collection of to
 
 Install the gem and add to the Rails application's Gemfile by executing:
 
-    $ bundle add warped-rails
+    $ bundle add warped
 
 Then run the generator to create the configuration file:
 
@@ -15,6 +15,34 @@ Then run the generator to create the configuration file:
 
 The generator will create a file at `config/initializers/warped.rb` with the default configuration.
 
+### Installation for rails fullstack apps
+
+For using the views provided by the gem, your app will need to have the following:
+1. [rails/importmap-rails](https://github.com/rails/importmap-rails) configured
+2. [hotwired/stimulus-rails](https://github.com/hotwired/stimulus-rails) configured
+
+Add the following to your `config/importmap.rb`:
+
+```ruby
+pin_all_from "app/javascript/controllers/warped", under: "controllers/warped"
+```
+
+> This will import all the stimulus controllers provided by the gem.
+
+Add the following to your `app/javascript/controllers/index.js`, bellow the `eagerLoadControllersFrom("controllers", application)` line:
+```javascript
+eagerLoadControllersFrom("warped/controllers", application)
+```
+
+Include the css provided by the gem in your `app/views/layouts/application.html.erb`:
+```erb
+<%= stylesheet_link_tag "warped/base" %>
+<%= stylesheet_link_tag "warped/table" %>
+<%= stylesheet_link_tag "warped/search" %>
+<%= stylesheet_link_tag "warped/filters" %>
+<%= stylesheet_link_tag "warped/pagination" %>
+```
+
 ## Usage
 
 Warped provides utilities for making it easier to develop rails applications. The utilities are organized into modules and can be used by including the module in the class that needs the utility.
@@ -56,96 +84,10 @@ GET /users?name=John
 GET /users?email=john@example.com
 GET /users?created_at=2021-01-01
 ```
+> [!TIP]
+> It's highly recommended to use the type-safe filter methods provided by the gem. This prevents invalid queries from being executed on the database. See the [Filterable documentation](docs/controllers/FILTERABLE.md) for more information.
 
-##### Referencing tables in the filterable fields
-
-The `filterable_by` method can also be used to reference fields in associated tables. For example, to filter the users by the name of the company they work for, the following can be done:
-
-```ruby
-class UsersController < ApplicationController
-  include Warped::Controllers::Filterable
-
-  filterable_by :name, :email, :created_at, 'companies.name'
-
-  def index
-    users = filter(User.joins(:company))
-    render json: users
-  end
-end
-```
-
-Request examples:
-```
-GET /users?name=John
-GET /users?companies.name=Acme
-```
-
-##### Renaming the filter query parameters
-
-If you don't want to use the field name as the query parameter (as to not expose the database schema, or when joining the same table multiple times),
-you can specify the query parameter to use for each field:
-
-```ruby
-class UsersController < ApplicationController
-  include Warped::Controllers::Filterable
-
-  filterable_by 'companies.name' => :company_name, 'users.name' => :user_name
-
-  def index
-    users = filter(User.join(:company))
-    render json: users
-  end
-end
-```
-
-Request examples:
-```
-GET /users?user_name=John
-GET /users?company_name=Acme
-```
-
-##### Using filters other than `eq`
-
-By default, the `filter` method will use the `eq` filter method to filter the records. If you want to use a different filter method, you can specify the filter "relation" in the query parameter:
-
-```ruby
-class UsersController < ApplicationController
-  include Warped::Controllers::Filterable
-
-  filterable_by :name, :age
-
-  def index
-    users = filter(User.all)
-    render json: users
-  end
-end
-```
-
-Request examples:
-```
-GET /users?name=John # returns users with name John
-GET /users?name[]=John&name[]=Jane # returns users where the name is in ('John', 'Jane')
-GET /users?age.rel=is_null # returns users where the age is null
-GET /users?age.rel=is_not_null # returns users where the age is not null
-GET /users?age.rel=between&age[]=18&age[]=30 # returns users with age between 18 and 30
-GET /users?age.rel=%3E%0A&age=18 # returns users with age greater than 18, %3E%0A is url encoded for ">"
-```
-
-The full list of filter relations is:
-- `=` (default) - equals
-- `!=` - not equals
-- `>` - greater than
-- `>=` - greater than or equals
-- `<` - less than
-- `<=` - less than or equals
-- `between` - between (requires two values)
-- `in` - in (default when multiple values are provided)
-- `not_in` - not in (requires multiple values)
-- `starts_with` - starts with
-- `ends_with` - ends with
-- `contains` - contains
-- `is_null` - is null (does not require a value)
-- `is_not_null` - is not null (does not require a  value)
+[Complete documentation for Warped::Controllers::Filterable](docs/controllers/FILTERABLE.md).
 
 #### Warped::Controllers::Searchable
 
@@ -181,67 +123,7 @@ GET /users?q=John
 # calls #search(User.all, search_term: 'John', model_search_scope: :search) in the controller
 ```
 
-##### Customizing the search query parameter
-
-You can customize the default query parameter by:
-1. Passing fetching the fetch term from the params hash, and passing it directly to the search method:
-
-```ruby
-class UsersController < ApplicationController
-  include Warped::Controllers::Searchable
-
-  def index
-    # This will use the query parameter `term` instead of `q`
-    users = search(User.all, search_term: params[:term])
-    render json: users
-  end
-end
-```
-
-2. Overriding the `search_param` method in the controller
-
-```ruby
-class UsersController < ApplicationController
-  include Warped::Controllers::Searchable
-
-  def index
-    # This will use the query parameter `term` instead of `q`
-    users = search(User.all)
-    render json: users
-  end
-
-  private
-
-  def search_param
-    :term
-  end
-end
-```
-
-3. Calling #searchable_by in the controller and overriding the default query parameter
-
-```ruby
-# app/models/user.rb
-class User < ApplicationRecord
-  include PgSearch::Model
-  pg_search_scope :search_by_word, against: :name, using: { tsearch: { any_word: true } }
-end
-
-
-# app/controllers/users_controller.rb
-class UsersController < ApplicationController
-  include Warped::Controllers::Searchable
-
-  # This will use the query parameter `term` instead of `q`
-  # and the search scope `search_by_word` instead of the default
-  searchable_by :search_by_word, param: :term
-
-  def index
-    users = search(User.all)
-    render json: users
-  end
-end
-```
+[Complete documentation for Warped::Controllers::Searchable](docs/controllers/SEARCHABLE.md).
 
 #### Warped::Controllers::Sortable
 
@@ -261,6 +143,8 @@ class UsersController < ApplicationController
   end
 end
 ```
+> [!TIP]
+> It's highly recommended to use the type-safe sort methods provided by the gem. This prevents invalid queries from being executed on the database. See the [Sortable documentation](docs/controllers/SORTABLE.md) for more information.
 
 This will use the query parameter `sort_key` and `sort_direction` to sort the records.
 - The default sort direction is `desc`.
@@ -291,52 +175,8 @@ Request examples:
 ```
 GET /users # sort by id in descending order
 ```
-##### Referencing tables in the sortable fields
-
-Like the `filterable_by` method, the `sortable_by` method can also be used to reference fields in associated tables.
-
-```ruby
-class UsersController < ApplicationController
-  include Warped::Controllers::Sortable
-
-  sortable_by :name, 'companies.name'
-
-  def index
-    users = sort(User.joins(:company))
-    render json: users
-  end
-end
-```
-
-Request examples:
-```
-GET /users?sort_key=name # sort by name in descending order
-GET /users?sort_key=companies.name&sort_direction=asc # sort by company name in ascending order
-```
-
-##### Renaming the sort query parameters
-
-If you don't want to use the field name as the query parameter (as to not expose the database schema, or when joining the same table multiple times),
-you can specify the query parameter to use for each field:
-
-```ruby
-class UsersController < ApplicationController
-  include Warped::Controllers::Sortable
 
-  sortable_by 'companies.name' => :company_name, 'users.name' => :user_name
-
-  def index
-    users = sort(User.join(:company))
-    render json: users
-  end
-end
-```
-
-Request examples:
-```
-GET /users?sort_key=user_name # sort by name in descending order
-GET /users?sort_key=company_name&sort_direction=asc # sort by company name in ascending order
-```
+[Complete documentation for Warped::Controllers::Sortable](docs/controllers/SORTABLE.md).
 
 #### Warped::Controllers::Pageable
 
@@ -351,7 +191,7 @@ class UsersController < ApplicationController
 
   def index
     users = paginate(User.all)
-    render json: users, meta: page_info
+    render json: users, meta: pagination
   end
 end
 ```
@@ -363,81 +203,111 @@ GET /users?per_page=25 # returns the first page of users with 25 records per pag
 GET /users?page=2&per_page=25 # returns the second page of users with 25 records per page
 ```
 
-##### Accessing the pagination information
+[Complete documentation for Warped::Controllers::Pageable](docs/controllers/PAGEABLE.md).
+
+#### Warped::Controllers::Tabulatable
+
+The `Tabulatable` concern provides a method to filter, sort, search, and paginate the records in a controller's action.
+
+The method `tabulate` is used to filter, sort, search, and paginate the records. So, in the case that the controller action needs to filter, sort, search, and paginate the records, the `tabulate` method can be used.
 
-The `page_info` method can be used to access the pagination information.
+The tabulatable concern provides the `tabulatable_by` method, which passes the values to `filterable_by` and `sortable_by`.
 
 ```ruby
 class UsersController < ApplicationController
-  include Warped::Controllers::Pageable
+  include Warped::Controllers::Tabulatable
+
+  tabulatable_by :name, :email, :created_at
 
   def index
-    users = paginate(User.all)
-    render json: users, meta: page_info
+    users = tabulate(User.all)
+    render json: users, meta: pagination
   end
 end
 ```
 
-`page_info` returns a hash with
-- `page` - the current page
-- `per_page` - the number of records per page
-- `total_pages` - the total number of pages
-- `total_count` - the number of records in the scope
-- `next-page` - the next page number
-- `prev-page` - the previous page number
+Request examples:
+```
+GET /users?age[]=18&age[]=30&age.rel=between&sort_key=name&sort_direction=asc&q=John&page=2&per_page=10
+# returns the second page of users with 10 records per page, where the age is between 18 and 30, sorted by name in ascending order, and searched by the term John
+```
+
+Just like `paginate`, when calling the `tabulate` method in the controller action, the `pagination` method can be used to access the pagination information.
 
+[Complete documentation for Warped::Controllers::Tabulatable](docs/controllers/TABULATABLE.md).
 
-##### Customizing the pagination behavior
+### Views
 
-By default, the `paginate` method will paginate the scope in pages of size 10, and will return the first page if the `page` query parameter is not provided.
+Warped comes with a set of partials and stimulus controllers that can be used to make development of index views easier/faster.
 
-Additionally, there's a limit of `100` records per page. So, if the `per_page` query parameter is greater than `100`, the pagination will use `100` as the page size.
+In order to use the views provided by the gem, warped provides ::Ui modules for each of the before menttioned concerns. `These Warped::Controllers::<ConcernName>::Ui` provide the helper methods needed by the partials in order to work.
 
-You can customize the default page size and the default page number by overriding the `default_per_page` value in the controller.
+The partials are:
+- `Warped::Controllers::Filterable::Ui` -> `warped/_filters.html.erb`
+- `Warped::Controllers::Searchable::Ui` -> `warped/_search.html.erb`
+- `Warped::Controllers::Pageable::Ui` -> `warped/_pagination.html.erb`
+- `Warped::Controllers::Tabulatable::Ui` -> `warped/_table.html.erb`
 
+Example:
 ```ruby
-class UsersController < ApplicationController
-  include Warped::Controllers::Pageable
+# app/models/user.rb
+class User < ApplicationRecord
+  # first_name :string
+  # last_name :string
+  # email :string
+  # created_at :datetime
 
-  # This will set the default page size to 25 when the `per_page` query parameter is not provided
-  self.default_per_page = 25
+  scope :search, ->(query) { where('first_name LIKE ? OR last_name LIKE ? OR email LIKE ?', "%#{query}%", "%#{query}%", "%#{query}%") }
 
-  def index
-    users = paginate(User.all)
-    render json: users, meta: page_info
-  end
 end
-```
 
-#### Warped::Controllers::Tabulatable
-
-The `Tabulatable` concern provides a method to filter, sort, search, and paginate the records in a controller's action.
-
-The method `tabulate` is used to filter, sort, search, and paginate the records. So, in the case that the controller action needs to filter, sort, search, and paginate the records, the `tabulate` method can be used.
+# app/controllers/users_controller.rb
+class UsersController < ApplicationControlelr
+  include Warped::Controllers::Tabulatable::Ui
 
-The tabulatable concern provides the `tabulatable_by` method, which passes the values to `filterable_by` and `sortable_by`.
+  tabulatable_by name: { kind: :string }, email: { kind: :string }, created_at: { kind: :date_time }
 
-```ruby
-class UsersController < ApplicationController
-  include Warped::Controllers::Tabulatable
+  def index
+    @users = tabulate(User.all)
+  end
 
-  tabulatable_by :name, :email, :created_at
+  def show
+    @user = User.find(params[:id])
+  end
 
-  def index
-    users = tabulate(User.all)
-    render json: users, meta: page_info
+  def destroy
+    User.find(params[:id]).destroy
+    redirect_to users_path
   end
 end
 ```
 
-Request examples:
-```
-GET /users?age[]=18&age[]=30&age.rel=between&sort_key=name&sort_direction=asc&q=John&page=2&per_page=10
-# returns the second page of users with 10 records per page, where the age is between 18 and 30, sorted by name in ascending order, and searched by the term John
-```
-
-Just like `paginate`, when calling the `tabulate` method in the controller action, the `page_info` method can be used to access the pagination information.
-
+```erb
+# app/views/users/index.html.erb
+<%= render "warped/table", collection: @users,
+                           path: users_path,
+                           columns: [
+                             Warped::Table::Column.new(:id, 'ID'),
+                             Warped::Table::Column.new(:full_name, 'Full Name', method: ->(user) { [user.first_name, user.last_name].compact_blank.join(" ") }),
+                             Warped::Table::Column.new(:email),
+                             Warped::Table::Column.new(:created_at, 'Created At', method: ->(user) { user.created_at.strftime('%Y-%m-%d') })
+                           ],
+                           actions: [
+                             Warped::Table::Action.new('Show', ->(user) { user_path(user) }),
+                             Warped::Table::Action.new('Delete', ->(user) { user_path(user) }, turbo_method: :delete, turbo_confirm: 'Are you sure?')
+                           ],
+                           turbo_action: :replace
+                          %>
+```
+The code above, renders a table with:
+- The columns `ID`, `Full Name`, `Email`, and `Created At`, all of which are sortable.
+- The actions `Show` and `Delete` for each user. The action `Delete` will use the `DELETE` method and will ask for confirmation before executing the action.
+- The filters for the `name`, `email`, and `created_at` fields.
+- A search input that will search the users by the term provided.
+- A pagination component that will paginate the users, showing 10 users per page by default.
+- The table filtering/sorting/searching/pagination will be done using the [turbo-action=replace](https://turbo.hotwired.dev/handbook/frames#promoting-a-frame-navigation-to-a-page-visit).
+
+[Complete documentation for Warped built-in Partials](docs/controllers/views/PARTIALS.md).
 ### Services
 
 The gem provides a `Warped::Service::Base` class that can be used to create services in a rails application.
@@ -492,33 +362,7 @@ 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
-```
+[Complete documentation for Warped::Services](docs/services/README.md).
 
 ### Jobs
 
@@ -543,6 +387,8 @@ Warped.configure do |config|
 end
 ```
 
+[Complete documentation for Warped::Jobs](docs/jobs/README.md).
+
 
 ## Development
 

data/app/assets/config/warped_manifest.js

@@ -0,0 +1,2 @@
+//= link_directory ../stylesheets/warped .css
+//= link_directory ../stylesheets/warped .js