warped 0.1.0 → 1.0.0

data/app/views/warped/_table.html.erb

@@ -0,0 +1,52 @@
+<%# locals: (collection:, path:, columns:, turbo_action: :replace, actions: [], **options) %>
+
+
+<%= tag.div class: 'warped-table' do %>
+  <div class="warped-table--controls">
+    <% if controller.class.include?(Warped::Controllers::Searchable::Ui) %>
+      <%= render "warped/search", path:, turbo_action:, **(options[:search].presence || {}) %>
+    <% end %>
+
+    <% if controller.class.include?(Warped::Controllers::Filterable::Ui) %>
+      <%= render "warped/filters", path:, turbo_action:, **(options[:filters].presence || {}) %>
+    <% end %>
+  </div>
+
+
+
+  <% table_opts = options[:table]&.deep_dup.presence || {} %>
+  <% table_class = "warped-table--table #{table_opts.delete(:class)}" %>
+
+  <div class="warped-table--container">
+    <%= tag.div class: table_class, **table_opts do %>
+      <div class="warped-table--table--header">
+        <div class="warped-table--table--row">
+          <% columns.each do |column| %>
+            <%= render "warped/column", column:, path:, turbo_action: %>
+          <% end %>
+
+          <% if actions.any? %>
+            <div class="warped-table--table--cell">
+              Actions
+            </div>
+          <% end %>
+        </div>
+      </div>
+      <div class="warped-table--table--row-group">
+        <div class="warped-table--table--empty-row">
+          <div class="warped-table--table--cell">
+            Whoops! Nothing over here!
+          </div>
+        </div>
+        <% if (block = yield).present? %>
+          <%= block %>
+        <% else %>
+          <% collection.each do |resource| %>
+            <%= render "warped/row", resource:, columns:, actions: %>
+          <% end %>
+        <% end %>
+      </div>
+    <% end %>
+  </div>
+  <%= render("warped/pagination", path:, turbo_action:, **(options[:pagination].presence || {})) if controller.class.include?(Warped::Controllers::Pageable::Ui) %>
+<% end %>

data/app/views/warped/filters/_filter.html.erb

@@ -0,0 +1,40 @@
+<%# locals: (form:, filter:) %>
+
+<% filter_value = current_action_filter_values.find { |v| v.filter.name == filter.name } %>
+
+<div class="warped-filters--filter <%= 'warped-filters--filter-inactive' if filter_value.blank? %>" data-controller="filter" data-filter-filter-outlet=".warped-filters--filter" data-filter-empty-class="warped-filters--filter-inactive" data-filter-collapsed-class="warped-filters--filter--panel-collapsed" data-action="keydown.esc@window->filter#close click@window->filter#clickOutside">
+  <div class="warped-filters--filter--icon" data-action="click->filter#toggle">
+    <% if !filter_value.nil? %>
+      <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor">
+        <path stroke-linecap="round" stroke-linejoin="round" d="M15 12H9m12 0a9 9 0 1 1-18 0 9 9 0 0 1 18 0Z" />
+      </svg>
+    <% else %>
+      <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor">
+        <path stroke-linecap="round" stroke-linejoin="round" d="M12 9v6m3-3H9m12 0a9 9 0 1 1-18 0 9 9 0 0 1 18 0Z" />
+      </svg>
+    <% end %>
+  </div>
+
+  <%= form.label filter.parameter_name, class: "warped-filters--filter--label" %>
+
+  <div data-filter-target="badgeValue" class="warped-filters--filter--value">
+    <span class="warped-filters--filter--value--values" data-filter-target="relation">
+      <%= filter_value&.relation if !filter_value&.empty? %>
+    </span>
+
+    <span class="warped-filters--filter--value--values" data-filter-target="value">
+      <%= ": #{filter_value&.value}" if !filter_value&.html_value.nil? %>
+    </span>
+  </div>
+
+  <div class="warped-filters--filter--panel-collapsed warped-filters--filter--panel" data-filter-target="panel">
+    <%= form.select "#{filter.parameter_name}.rel", options_for_select(filter.relations, include_blank: true, selected: filter_value&.relation), {}, class: "warped-filters--filter--panel--select", data: { filter_target: "relationInput", action: "change->filter#changeRelation" } %>
+    <%= tag :input, type: filter.html_type, name: filter.parameter_name, value: filter_value&.html_value, class: "warped-filters--filter--panel--input", data: { filter_target: "valueInput", action: "keyup->filter#changeValue" } %>
+
+    <span class="warped-filters--filter--panel--remove" data-action="click->filter#clear click->filter#close">
+      <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor">
+        <path stroke-linecap="round" stroke-linejoin="round" d="m9.75 9.75 4.5 4.5m0-4.5-4.5 4.5M21 12a9 9 0 1 1-18 0 9 9 0 0 1 18 0Z" />
+      </svg>
+    </span>
+  </div>
+</div>

data/config/importmap.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+pin_all_from File.expand_path("../app/assets/javascript", __dir__)

data/docs/controllers/FILTERABLE.md

@@ -0,0 +1,193 @@
+# Warped::Controllers::Filterable
+
+The `Filterable` concern provides a method to filter the records in a controller's action.
+The method `filterable_by` is used to define the filterable fields and the filter method to use.
+
+```ruby
+class UsersController < ApplicationController
+  include Warped::Controllers::Filterable
+
+  filterable_by :name, :email, :created_at
+
+  def index
+    users = filter(User.all)
+    render json: users
+  end
+end
+```
+The `filter` method will use the query parameters to filter the records. For example, to filter the users by name, email, and created_at, the following query parameters can be used:
+
+```
+GET /users?name=John
+GET /users?email=john@example.com
+GET /users?created_at=2021-01-01
+```
+
+## Adding type-safety to the fields
+
+The `filterable_by` method, accepts keyword arguments to be passed. The keyword arguments are the field names and the type to cast the query parameter to. This is useful to prevent invalid queries from being executed on the database.
+
+```ruby
+class UsersController < ApplicationController
+  include Warped::Controllers::Filterable
+
+  filterable_by name: { kind: :string }, email: { kind: :string }, created_at: { kind: :date }
+
+  def index
+    users = filter(User.all)
+    render json: users
+  end
+end
+```
+
+When passing a value to the query parameter, the value will be cast to the specified type. If casting fails, the query parameter will be ignored.
+
+If the strict flag is passed to the filterable_by method, then it will raise a `Filter::ValueError`.
+
+```ruby
+class UsersController < ApplicationController
+  include Warped::Controllers::Filterable
+
+  filterable_by created_at: { kind: :date }, strict: true
+
+  def index
+    users = filter(User.all)
+    render json: users
+  end
+end
+```
+
+Request examples:
+```
+GET /users?created_at=2021-01-01 # returns users created at 2021-01-01
+GET /users?created_at=not_a_date # Raises a Filter::ValueError, with the message 'not_a_date' cannot be casted to date
+```
+
+## Handling invalid filter values in strict mode
+
+```ruby
+class UsersController < ApplicationController
+  include Warped::Controllers::Filterable
+
+  rescue_from Filter::ValueError, with: :render_invalid_filter_value
+  rescue_from Filter::RelationError, with: :render_invalid_filter_relation
+
+  filterable_by age: { kind: :integer }, strict: true
+
+  def index
+    users = filter(User.all)
+    render json: users
+  end
+
+  private
+
+  # default handler for invalid filter values
+  def render_invalid_filter_value(exception)
+    render json: { error: exception.message }, status: :bad_request
+  end
+
+  def render_invalid_filter_relation(exception)
+    render json: { error: exception.message }, status: :bad_request
+  end
+end
+```
+
+Request examples:
+```
+GET /users?age=18 # returns users with age 18
+GET /users?age=not_an_integer
+# returns a 400 (Bad Request), with the message "'not_an_integer' cannot be casted to integer"
+```
+
+## 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, 'companies.name', "companies.created_at" => { kind: :date_time }
+
+  def index
+    users = filter(User.joins(:company))
+    render json: users
+  end
+end
+```
+
+Request examples:
+```
+GET /users?name=John
+GET /users?companies.name=Acme
+GET /users?companies.created_at=2021-01-01T00:00:00
+```
+
+## 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' => { kind: :string, alias_name: :company_name },
+                'users.name' => { kind: :string, alias_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: { kind: :string }, age: { kind: :integer }
+
+  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=gt&age=18 # returns users with age greater than 18
+```
+
+The full list of filter relations is:
+- `eq` (default) - equals
+- `neq` - not equals
+- `gt` - greater than
+- `gte` - greater than or equals
+- `lt` - less than
+- `lte` - 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)

data/docs/controllers/PAGEABLE.md

@@ -0,0 +1,70 @@
+# Warped::Controllers::Pageable
+
+The `Pageable` concern provides a method to paginate the records in a controller's action.
+
+The method `paginate` is used to paginate the records.
+It will use the query parameters `page` and `per_page` to paginate the records.
+
+```ruby
+class UsersController < ApplicationController
+  include Warped::Controllers::Pageable
+
+  def index
+    users = paginate(User.all)
+    render json: users, meta: pagination
+  end
+end
+```
+
+Request examples:
+```
+GET /users?page=1&per_page=10 # returns the first page of users with 10 records per page
+GET /users?per_page=25 # returns the first page of users with 25 records per page
+GET /users?page=2&per_page=25 # returns the second page of users with 25 records per page
+```
+
+## Accessing the pagination information
+
+The `pagination` method can be used to access the pagination information.
+
+```ruby
+class UsersController < ApplicationController
+  include Warped::Controllers::Pageable
+
+  def index
+    users = paginate(User.all)
+    render json: users, meta: pagination
+  end
+end
+```
+
+`pagination` 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
+
+
+## Customizing the pagination behavior
+
+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.
+
+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.
+
+You can customize the default page size and the default page number by overriding the `default_per_page` value in the controller.
+
+```ruby
+class UsersController < ApplicationController
+  include Warped::Controllers::Pageable
+
+  # This will set the default page size to 25 when the `per_page` query parameter is not provided
+  self.default_per_page = 25
+
+  def index
+    users = paginate(User.all)
+    render json: users, meta: pagination
+  end
+end
+```

data/docs/controllers/README.md

@@ -0,0 +1,8 @@
+# Warped::Controllers
+
+The `Warped::Controllers` module defines five concerns that can be included in a controller to provide additional functionality:
+- [Warped::Controllers::Filterable](FILTERABLE.md)
+- [Warped::Controllers::Searchable](SEARCHABLE.md)
+- [Warped::Controllers::Sortable](SORTABLE.md)
+- [Warped::Controllers::Pageable](PAGEABLE.md)
+- [Warped::Controllers::Tabulatable](TABULATABLE.md)

data/docs/controllers/SEARCHABLE.md

@@ -0,0 +1,95 @@
+# Warped::Controllers::Searchable
+
+The `Searchable` concern provides a method to search the records in a controller's action.
+
+By default it calls the scope `search` on the model, and uses the query parameter `q` to search the records.
+
+```ruby
+# app/models/user.rb
+class User < ApplicationRecord
+  # You can define your own search scope and use standard sql
+  # scope :search, ->(query) { where('name LIKE ?', "%#{query}%") }
+
+  # Or use pg_search
+  include PgSearch::Model
+  pg_search_scope :search, against: [:name, :email]
+end
+
+# app/controllers/users_controller.rb
+class UsersController < ApplicationController
+  include Warped::Controllers::Searchable
+
+  def index
+    users = search(User.all)
+    render json: users
+  end
+end
+```
+
+Request examples:
+```
+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
+```

data/docs/controllers/SORTABLE.md

@@ -0,0 +1,94 @@
+# Warped::Controllers::Sortable
+
+The `Sortable` concern provides a method to sort the records in a controller's action.
+
+The method `sortable_by` is used to define the sortable fields.
+
+```ruby
+class UsersController < ApplicationController
+  include Warped::Controllers::Sortable
+
+  sortable_by :name, :created_at
+
+  def index
+    users = sort(User.all)
+    render json: users
+  end
+end
+```
+
+This will use the query parameter `sort_key` and `sort_direction` to sort the records.
+- The default sort direction is `desc`.
+- The default sort key is `:id`.
+
+Example requests:
+```
+GET /users?sort_key=name # sort by name in descending order
+GET /users?sort_key=created_at&sort_direction=asc # sort by created_at in ascending order
+```
+
+When calling sort in a controller action, and the sort parameters are not provided, the default sort key and direction will be used.
+
+```ruby
+class UsersController < ApplicationController
+  include Warped::Controllers::Sortable
+
+  sortable_by :name, :created_at
+
+  def index
+    users = sort(User.all)
+    render json: users
+  end
+end
+```
+
+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
+```

data/docs/controllers/TABULATABLE.md

@@ -0,0 +1,28 @@
+# 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 tabulatable concern provides the `tabulatable_by` method, which passes the values to `filterable_by` and `sortable_by`.
+
+```ruby
+class UsersController < ApplicationController
+  include Warped::Controllers::Tabulatable
+
+  tabulatable_by :name, :email, :created_at
+
+  def index
+    users = tabulate(User.all)
+    render json: users, meta: pagination
+  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 `pagination` method can be used to access the pagination information.