warped 0.2.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 01d84d855e451182cddf0b6d9e38d922e0dfd40c5ee05752496759d5344b042b
-  data.tar.gz: 9d0ddb61f7af15597abb5e0a12f11cbb602f86b2f52763288f4be797f2d41509
+  metadata.gz: c1c6444d0d93fbbfa88436418e69edc9e44e228402d56becbc99bd7eae122f14
+  data.tar.gz: 4eeeb9b833549db2c33a67fa73627e3e55f27dda5178d9f2f377b989f64739a0
 SHA512:
-  metadata.gz: 4b9d8acfdfd217f5755800657688ce6e2c5f7ddab564a8b658c6a94ee38d8b19ae1dc5f416ea3996d103015cf09793734beeaa63b1388356347b5354eb65da10
-  data.tar.gz: '0407936f782cdc2dbb0f210b43a7204a6758866e13bd1eb6772b3410e7063f49909dc3ed60d3cfd081ece0dfdccc10a6ced6e4f295d407f4795ea9f4bbe00b85'
+  metadata.gz: 486f3074c354576fb33e04df666248b27e4b0f2dd13a6ce1256c9ec66c9ad786a158010b199b80f11761b5c5bcc83af5ee3f6c01b5a631de83da53a706d5c520
+  data.tar.gz: 2a3f730c41a5f42c92aac9c3e2708caf0f803f157771a25be75b524304ec1f7203056ae4f7bc40675b7c2aef779f7dce7a2e54cb6a494ded18261361eef84237

data/.rubocop.yml

@@ -21,6 +21,7 @@ Layout/LineLength:
 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"
@@ -34,8 +35,13 @@ 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:

data/Gemfile.lock

@@ -1,8 +1,8 @@
 PATH
   remote: .
   specs:
-    warped (0.2.0)
-      rails (>= 6.0, < 8.0)
+    warped (1.0.0)
+      rails (>= 7.1, <= 8.0)
       zeitwerk (>= 2.4)
 
 GEM

data/README.md

@@ -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,6 +84,8 @@ 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.
 
 [Complete documentation for Warped::Controllers::Filterable](docs/controllers/FILTERABLE.md).
 
@@ -113,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`.
@@ -204,6 +236,78 @@ Just like `paginate`, when calling the `tabulate` method in the controller actio
 
 [Complete documentation for Warped::Controllers::Tabulatable](docs/controllers/TABULATABLE.md).
 
+### Views
+
+Warped comes with a set of partials and stimulus controllers that can be used to make development of index views easier/faster.
+
+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.
+
+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
+# app/models/user.rb
+class User < ApplicationRecord
+  # first_name :string
+  # last_name :string
+  # email :string
+  # created_at :datetime
+
+  scope :search, ->(query) { where('first_name LIKE ? OR last_name LIKE ? OR email LIKE ?', "%#{query}%", "%#{query}%", "%#{query}%") }
+
+end
+
+# app/controllers/users_controller.rb
+class UsersController < ApplicationControlelr
+  include Warped::Controllers::Tabulatable::Ui
+
+  tabulatable_by name: { kind: :string }, email: { kind: :string }, created_at: { kind: :date_time }
+
+  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,
+                           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.

data/app/assets/config/warped_manifest.js

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

data/app/assets/javascript/warped/controllers/filter_controller.js

@@ -0,0 +1,76 @@
+import { Controller } from "@hotwired/stimulus"
+
+export default class FilterController extends Controller {
+  static targets = ["relation", "relationInput", "value", "valueInput", "panel", "badgeValue"]
+  static outlets = ["filter"]
+  static classes = ["empty", "collapsed"]
+
+
+  clickOutside(event) {
+    if (!this.element.contains(event.target)) {
+      this.close();
+    }
+  }
+
+  toggle() {
+    this.collapsedClasses.forEach(c => this.panelTarget.classList.toggle(c))
+
+    this.filterOutlets.forEach(outlet => {
+      if (this != outlet) {
+        outlet.close();
+      }
+    })
+  }
+
+  close() {
+    this.panelTarget.classList.add(...this.collapsedClasses)
+  }
+
+  collapsePanel() {
+    this.panelTarget.classList.add(...this.collapsedClasses)
+  }
+
+  uncollapsePanel() {
+    this.panelTarget.classList.remove(...this.collapsedClasses)
+  }
+
+  changeRelation() {
+    if (this.valueInputTarget.value) {
+      this.relationTarget.textContent = `${this.relationInputTarget.value}:`
+    }
+  }
+
+  changeValue() {
+    const currentFilterValue = this.valueInputTarget.value.trim()
+
+    this.valueTarget.textContent = currentFilterValue
+    this.changeRelation()
+
+    if (currentFilterValue) {
+      this.badgeValueTarget.classList.remove(...this.collapsedClasses)
+      this.element.classList.remove(this.emptyClass)
+    } else {
+      this.relationTarget.textContent = "";
+      this.badgeValueTarget.classList.add(...this.collapsedClasses)
+      this.element.classList.add(this.emptyClass)
+    }
+  }
+
+  clear(submit = true) {
+    this.valueTarget.textContent = ""
+    this.valueInputTarget.value = ""
+    this.relationInputTarget.value = ""
+    this.badgeValueTarget.classList.add("hidden")
+    this.element.classList.add(this.emptyClass)
+
+    if (submit) {
+      this.form.requestSubmit();
+    }
+  }
+
+  get form() {
+    return this.element.closest("form")
+  }
+}
+
+export { FilterController }

data/app/assets/javascript/warped/controllers/filters_controller.js

@@ -0,0 +1,21 @@
+import { Controller } from "@hotwired/stimulus"
+
+export default class FiltersController extends Controller {
+  static outlets = ["filter"]
+
+  clearAll(event) {
+    event.preventDefault();
+
+    this.filterOutlets.forEach(outlet => {
+      outlet.clear(false);
+    })
+
+    this.form.requestSubmit();
+  }
+
+  get form() {
+    return this.element;
+  }
+}
+
+export { FiltersController }

data/app/assets/javascript/warped/index.js

@@ -0,0 +1,2 @@
+import FilterController from "warped/controllers/filter_controller";
+import FiltersController from "warped/controllers/filters_controller";

data/app/assets/stylesheets/warped/application.css

@@ -0,0 +1,15 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or any plugin's vendor/assets/stylesheets directory can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the bottom of the
+ * compiled file so the styles you add here take precedence over styles defined in any other CSS/SCSS
+ * files in this directory. Styles in this file should be added after the last require_* statement.
+ * It is generally better to create a new file per style scope.
+ *
+ *= require_tree .
+ *= require_self
+ */

data/app/assets/stylesheets/warped/base.css

@@ -0,0 +1,23 @@
+:root {
+  /* colors */
+  --warped-base: white;
+  --warped-base-rgb: 255, 255, 255;
+
+  --warped-neutral: #1F2937;
+  --warped-neutral-rgb: 31, 41, 55;
+
+  --warped-neutral-content: #fbfbfb;
+  --warped-neutral-content-rgb: 251, 251, 251;
+
+  --warped-primary: #2563EB;
+  --warped-primary-rgb: 37, 99, 235;
+
+  --warped-primary-content: #fbfbfb;
+  --warped-primary-content-rgb: 251, 251, 251;
+
+  --warped-danger: #EF4444;
+  --warped-danger-rgb: 239, 68, 68;
+
+  /* roundness */
+  --warped-roundness: 0.5rem;
+}

data/app/assets/stylesheets/warped/filters.css

@@ -0,0 +1,115 @@
+.warped-filters {
+  width: 100%;
+  display: flex;
+  gap: 0.5rem;
+  background-color: var(--warped-base);
+  border-radius: var(--warped-roundness);
+  flex-wrap: wrap
+}
+
+.warped-filters--submit {
+  background-color: var(--warped-primary);
+  color: var(--warped-primary-content);
+  padding: 0.5rem;
+  border-radius: var(--warped-roundness);
+  font-size: 0.875rem;
+  cursor: pointer;
+}
+
+.warped-filters--clear {
+  background-color: var(--warped-neutral);
+  color: var(--warped-neutral-content);
+  padding: 0.5rem;
+  border-radius: var(--warped-roundness);
+  font-size: 0.875rem;
+  cursor: pointer;
+}
+
+.warped-filters--filter {
+  display: flex;
+  gap: 0.25rem;
+  height: 100%;
+  border-radius: var(--warped-roundness);
+  background-color: var(--warped-base);
+  padding-left: 0.5rem;
+  padding-right: 0.5rem;
+  padding-top: 0.25rem;
+  padding-bottom: 0.25rem;
+  position: relative;
+  border: 1px solid var(--warped-neutral);
+  align-items: center;
+}
+
+.warped-filters--filter-inactive {
+  border: 1px dashed var(--warped-neutral);
+}
+
+.warped-filters--filter--label {
+  font-size: 0.875rem;
+  color: var(--warped-neutral);
+  font-weight: 500;
+}
+
+.warped-filters--filter--icon {
+  height: 1.5rem;
+  width: 1.5rem;
+  color: var(--warped-neutral);
+  cursor: pointer;
+}
+
+.warped-filters--filter--value {
+  display: flex;
+  transition: all 200ms;
+  color: var(--warped-neutral);
+}
+
+.warped-filters--filter--panel-collapsed {
+  visibility: hidden;
+  opacity: 0;
+}
+
+.warped-filters--filter--value--values {
+  font-size: 0.875rem;
+  color: var(--warped-neutral);
+  font-weight: 600;
+}
+
+.warped-filters--filter--panel {
+  transition: all 200ms;
+  width: max-content;
+  position: absolute;
+  top: 2.5rem;
+  left: 0;
+  background-color: var(--warped-base);
+  border-radius: var(--warped-roundness);
+  padding: 0.5rem;
+  display: flex;
+  z-index: 40;
+  box-shadow: 0 3px 10px rgba(0, 0, 0, 0.2);
+}
+
+.warped-filters--filter--panel--remove {
+  cursor: pointer;
+  color: var(--warped-danger);
+  width: 2rem;
+  stroke-width: 2;
+}
+
+.warped-filters--filter--panel--select {
+  width: max-content;
+  padding-left: 0.5rem;
+  padding-top: 0.25rem;
+  padding-bottom: 0.25rem;
+  border-top-left-radius: var(--warped-roundness);
+  border-bottom-left-radius: var(--warped-roundness);
+  border-right: 1px solid var(--warped-neutral);
+}
+
+.warped-filters--filter--panel--input {
+  width: max-content;
+  padding-top: 0.25rem;
+  padding-bottom: 0.25rem;
+  border-top-right-radius: var(--warped-roundness);
+  border-bottom-right-radius: var(--warped-roundness);
+  border-left: 0;
+}

data/app/assets/stylesheets/warped/pagination.css

@@ -0,0 +1,74 @@
+.warped--pagination {
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: center;
+  width: 100%;
+  height: 2.5rem;
+}
+
+.warped--pagination--btn {
+  background-color: var(--warped-neutral);
+  color: var(--warped-neutral-content);
+  padding: 0.25rem 0.5rem;
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  min-width: 2.5rem;
+}
+
+.warped--pagination--btn button {
+  height: 100%;
+  width: 100%;
+}
+
+.warped--pagination--btn:not(:last-child) {
+  border-right: 1px solid var(--warped-neutral-content);
+}
+
+.warped--pagination--btn:first-child {
+  border-top-left-radius: var(--warped-roundness);
+  border-bottom-left-radius: var(--warped-roundness);
+  width: 7rem;
+}
+
+.warped--pagination--btn:last-child {
+  border-top-right-radius: var(--warped-roundness);
+  border-bottom-right-radius: var(--warped-roundness);
+  width: 7rem;
+}
+
+.warped--pagination--btn:hover {
+  background-color: var(--warped-primary);
+  color: var(--warped-primary-content);
+}
+
+.warped--pagination--btn-disabled {
+  background-color: var(--warped-neutral);
+  color: var(--warped-neutral-content);
+  padding: 0.25rem 0.5rem;
+  cursor: not-allowed;
+}
+
+.warped--pagination--btn-disabled:hover {
+  background-color: var(--warped-neutral);
+}
+
+.warped--pagination--btn-active {
+  background-color: var(--warped-primary);
+  color: var(--warped-primary-content);
+  padding: 0.25rem 0.5rem;
+  cursor: pointer;
+}
+
+.warped--pagination--btn-inactive {
+  background-color: var(--warped-neutral);
+  color: var(--warped-neutral-content);
+  padding: 0.25rem 0.5rem;
+  cursor: pointer;
+}
+
+.warped--pagination--btn-gap:hover {
+  background-color: var(--warped-neutral);
+  color: var(--warped-neutral-content);
+  cursor: not-allowed;
+}

data/app/assets/stylesheets/warped/search.css

@@ -0,0 +1,33 @@
+.warped-searchbar {
+  display: flex;
+  width: 100%;
+  background-color: white;
+  border-radius: var(--warped-roundness);
+}
+
+.warped-searchbar--button {
+  background-color: var(--warped-neutral);
+  color: var(--warped-neutral-content);
+  stroke: var(--warped-neutral-content);
+  padding-left: 1rem;
+  padding-right: 1rem;
+  padding-top: 0.5rem;
+  padding-bottom: 0.5rem;
+  border-top-left-radius: var(--warped-roundness);
+  border-bottom-left-radius: var(--warped-roundness);
+}
+
+.warped-searchbar--button svg {
+  height: 1.25rem;
+  width: 1.25rem;
+}
+
+.warped-searchbar--input {
+  flex-grow: 1;
+  border-top: 1px solid var(--warped-neutral);
+  border-right: 1px solid var(--warped-neutral);
+  border-bottom: 1px solid var(--warped-neutral);
+  border-top-right-radius: var(--warped-roundness);
+  border-bottom-right-radius: var(--warped-roundness);
+  padding-left: 0.5rem;
+}

data/app/assets/stylesheets/warped/table.css

@@ -0,0 +1,114 @@
+/* This file contains all the styles necessary for Warped::Table to work */
+.warped-table {
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+  row-gap: 0.5rem;
+  background-color: var(--warped-base);
+  border-radius: var(--warped-roundness);
+  padding: 0.5rem;
+}
+
+.warped-table--container {
+  overflow-x: auto;
+}
+
+.warped-table--controls {
+  display: flex;
+  flex-direction: column;
+  row-gap: 0.5rem;
+}
+
+.warped-table--table {
+  width: 100%;
+  border-collapse: collapse;
+  border-spacing: 0;
+  display: table;
+}
+
+.warped-table--table--header {
+  display: table-header-group;
+  background-color: var(--warped-neutral);
+}
+
+.warped-table--table--header .warped-table--table--row .warped-table--table--cell {
+  font-weight: 500;
+  color: var(--warped-neutral-content);
+  border-right: 1px solid var(--warped-neutral-content);
+  padding: 0 0.25rem;
+  stroke: var(--warped-neutral-content);
+  stroke-width: 0.5;
+}
+
+.warped-table--table--header .warped-table--table--row .warped-table--table--cell form {
+  width: 100%;
+}
+
+.warped-table--table--header .warped-table--table--row .warped-table--table--cell form button {
+  display: flex;
+  gap: 0.25rem;
+  width: 100%;
+}
+
+.warped-table--table--header .warped-table--table--row .warped-table--table--cell form button svg {
+  width: 1.25rem;
+  height: 1.25rem;
+  margin-top: auto;
+  margin-bottom: auto;
+}
+
+.warped-table--table--header .warped-table--table--row .warped-table--table--cell:last-child {
+  border-right: none;
+}
+
+.warped-table--table--row {
+  display: table-row;
+}
+
+.warped-table--table--row:not(:last-child) {
+  border-bottom: 1px solid var(--warped-neutral);
+}
+
+.warped-table--table--cell {
+  display: table-cell;
+  padding: 0.25rem;
+  vertical-align: middle;
+}
+
+.warped-table--table--row-group {
+  display: table-row-group;
+}
+
+.warped-table--table--row-group>*+* {
+  border-top: 1px solid var(--warped-neutral);
+}
+
+.warped-table--table--row-group .warped-table--table--empty-row:only-child {
+  display: table-row;
+}
+
+.warped-table--table--row-group .warped-table--table--row:nth-child(odd) {
+  background-color: rgba(var(--warped-neutral-rgb), 0.1);
+}
+
+.warped-table--table--row-group .warped-table--table--empty-row {
+  display: none;
+  position: relative;
+  height: 3rem;
+}
+
+.warped-table--table--row-group .warped-table--table--empty-row .warped-table--table--cell {
+  position: absolute;
+  width: 100%;
+  height: 100%;
+  text-align: center;
+  font-weight: 500;
+  padding-top: 0.5rem;
+}
+
+.warped-table--action {
+  padding: 0.25rem 0.5rem;
+  border-radius: var(--warped-roundness);
+  background-color: var(--warped-neutral);
+  color: var(--warped-neutral-content);
+}

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

@@ -0,0 +1,9 @@
+<%# locals: (resource:, actions:[])%>
+
+<div class="warped-table--table--cell">
+  <% actions.each do |action| %>
+    <% opts = action.options.deep_dup %>
+    <% action_class = "warped-table--action #{opts.delete(:class)}" %>
+    <%= link_to (action.name(resource)), action.path(resource), class: action_class, **opts %>
+  <% end %>
+</div>

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

@@ -0,0 +1,3 @@
+<div class="warped-table--table--cell">
+  <%= yield %>
+</div>