katalyst-tables 1.1.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5482118f21175e8c1dbff1a397fa7b5ff68480783a2c47da2a92c0436c66e739
-  data.tar.gz: 99e70f74ef353cce895305e5ad39a98dc690efd7f0c68d4305867fbcdc23c941
+  metadata.gz: 2a572503d453b3b8b98a82942a48c5e2772cec4023417e8db71ed2cd8299331a
+  data.tar.gz: 4761c4fa4b21aa8c91f70c2118e27bd68dfd700ffc419ed6f7eae299b582710f
 SHA512:
-  metadata.gz: 219380d0ccb99e001c9604594d0aa68a58925bbd745d87898af359316192e61727d3549c4ab64198c31656c663ec00809d93ddc8034921143f8169fcb49f7769
-  data.tar.gz: b9d8a9e03604f9b39389d218bfceb4d354343bd0d1da4ff3bd7ca55f66446ba8f5fbc8430b9d5b22974f1210eed344ce0d579bccb209e29a0d35ca59982d4c63
+  metadata.gz: aa9c1dc28479dc744c18804999d5f34ea9937e1500dbe8c01a1f2c183439077dfdd7047dbb8ce2ea0f93ef43bcfcea15eee6d08b2606f3682a00747e590cbc3b
+  data.tar.gz: 45c36c312e7f6efa8b11409d4822d135c961eba6ade51055b4671371b3b1a6e25a01c9fd1e059c0a89fa5da6bea3e7fe56fda267a1b3d7bfdf51e515b7b8a696

data/CHANGELOG.md

@@ -1,5 +1,30 @@
 ## [Unreleased]
 
+## [2.1.0]
+
+- Add Collection model for building collections in a controller from params.
+  - See [[README.md]] for examples
+- Add turbo entry points for table and pagy_nav
+  - See [[README.md]] for examples
+- Add support for row partials when content is not provided
+  - See [[README.md]] for examples
+- Add messages when table is empty, off by default (caption: true)
+- Add PagyNavComponent for rendering `pagy_nav` from a collection.
+- Replaces internal references to SortForm to use `sorting` instead
+  - No changes required to existing code unless you were using the internal
+    classes directly
+  - Change allows sort param and sorting model to co-exist
+
+## [2.0.0]
+
+- Replaces builders with view_components 
+  We want view components to be the way to build custom tables, and add more
+  complete features to the gem. This will be a breaking change, but we have
+  tried hard to retain compatibility with existing code. Unless you are using
+  a custom builder then it's unlikely that you will see any changes.
+- If you are using custom builders, then you will need to update them to use
+  view components. See [[README.md]] for examples.
+
 ## [1.1.0] - 2023-07-18
 
 - Replaces `param_key` with `i18n_key` for attribute lookup in locale file

data/README.md

@@ -7,87 +7,108 @@ Tools for building HTML tables from ActiveRecord collections.
 Add this line to your application's Gemfile:
 
 ```ruby
-gem "katalyst-tables", git: "https://github.com/katalyst/katalyst-tables", branch: "main" 
+gem "katalyst-tables" 
 ```
 
 And then execute:
 
     $ bundle install
 
-**Reminder:** If you have a rails server running, remember to restart the server to prevent the `uninitialized constant` error.
-
 ## Usage
 
-This gem provides two entry points: Frontend for use in your views, and Backend for use in your controllers. The backend
-entry point is optional, as it's only required if you want to support sorting by column headers.
+This gem provides entry points for backend and frontend concerns:
+* `Katalyst::TableComponent` can be used render encapsulated tables, it calls a
+  partial for each row.
+* `Katalyst::Tables::Frontend` provides `table_with` for inline table generation
+* `Katalyst::Tables::Collection::Base` provides a default entry point for
+  building collections in your controller actions.
 
-### Frontend
+## Frontend
 
-Add `include Katalyst::Tables::Frontend` to your `ApplicationHelper` or similar.
+Use `Katalyst::TableComponent` to build a table component from an ActiveRecord
+collection, or from a `Katalyst::Tables::Collection::Base` instance.
+
+For example, if you render `Katalyst::TableComponent.new(collection: @people)`,
+the table component will look for a partial called `_person.html+row.erb` and
+render it for each row (and once for the header row).
 
 ```erb
-<%= table_with collection: @people do |row, person| %>
-  <%= row.cell :name %>
-  <%= row.cell :email %>
-  <%= row.cell :actions do %>
-   <%= link_to "Edit", person %>
-  <% end %>
+<%# locals: { row:, person: nil } %>
+<% row.cell :name do |cell| %>
+  <%= link_to cell.value, [:edit, person] %>
 <% end %>
+<% row.cell :email %>
 ```
 
-`table_builder` will call your block once per row and accumulate the cells you generate into rows:
+The table component will call your partial once per row and accumulate the cells
+you generate into rows, including a header row:
 
 ```html
 
 <table>
-    <thead>
-    <tr>
-        <th>Name</th>
-        <th>Email</th>
-        <th>Actions</th>
-    </tr>
-    </thead>
-    <tbody>
-    <tr>
-        <td>Alice</td>
-        <td>alice@acme.org</td>
-        <td><a href="/people/1/edit">Edit</a></td>
-    </tr>
-    <tr>
-        <td>Bob</td>
-        <td>bob@acme.org</td>
-        <td><a href="/people/2/edit">Edit</a></td>
-    </tr>
-    </tbody>
+  <thead>
+  <tr>
+    <th>Name</th>
+    <th>Email</th>
+  </tr>
+  </thead>
+  <tbody>
+  <tr>
+    <td><a href="/people/1/edit">Alice</a></td>
+    <td>alice@acme.org</td>
+  </tr>
+  <tr>
+    <td><a href="/people/2/edit">Bob</a></td>
+    <td>bob@acme.org</td>
+  </tr>
+  </tbody>
 </table>
 ```
 
-### Options
+You can customize the partial and/or the name of the resource in a similar style
+to view partials:
 
-You can customise the options passed to the table, rows, and cells.
+```erb
+<%= render Katalyst::TableComponent.new(collection: @employees, as: :person, partial: "person") %>
+``` 
 
-Tables support options via the call to `table_with`, similar to `form_with`.
+### Inline tables
+
+You can use the `table_with` helper to generate a table inline in your view without explicitly interacting with the
+table component. This is primarily intended for backwards compatibility, but it can be useful for simple tables.
+
+Add `include Katalyst::Tables::Frontend` to your `ApplicationHelper` or similar.
 
 ```erb
-<%= table_with collection: @people, id: "people-table" do |row, person| %>
-  ...
+<%= table_with collection: @people do |row, person| %>
+  <% row.cell :name do |cell| %>
+    <%= link_to cell.value, [:edit, person] %>
+  <% end %>
+  <% row.cell :email %>
 <% end %>
 ```
 
+### HTML Attributes
+
+You can add custom attributes on table, row, and cell tags.
+
+The table tag takes attributes passed to `TableComponent` or via the call to `table_with`, similar to `form_with`:
+
+```erb
+<%= TableComponent.new(collection: @people, id: "people-table")
+```
+
 Cells support the same approach:
 
 ```erb
 <%= row.cell :name, class: "name" %>
 ```
 
-Rows do not get called directly, so instead you can call `options` on the row builder to customize the row tag
+Rows do not get called directly, so instead you can assign to `html_attributes` on the row builder to customize row tag
 generation.
 
 ```erb
-<%= table_with collection: @people, id: "people-table" do |row, person| %>
-  <% row.options data: { id: person.id } if row.body? %>
-  ...
-<% end %>
+<% row.html_attributes = { id: person.id } if row.body? %>
 ```
 
 Note: because the row builder gets called to generate the header row, you may need to guard calls that access the
@@ -95,21 +116,21 @@ Note: because the row builder gets called to generate the header row, you may ne
 
 #### Headers
 
-`table_builder` will automatically generate a header row for you by calling your block with no object. During this
-iteration, `row.header?` is true, `row.body?` is false, and the object (`person`) is nil.
+Tables will automatically generate a header row for you by calling your row partial or provided block with no object.
+During this call, `row.header?` is true, `row.body?` is false, and the object (`person`) is nil.
 
 All cells generated in the table header iteration will automatically be header cells, but you can also make header cells
 in your body rows by passing `heading: true` when you generate the cell.
 
 ```erb
-<%= row.cell :id, heading: true %>
+<% row.cell :id, heading: true %>
 ```
 
-The table header cells default to showing the titleized column name, but you can customize this in one of two ways:
+The table header cells default to showing the capitalized column name, but you can customize this in one of two ways:
 
 * Set the value inline
     ```erb
-    <%= row.cell :id, label: "ID" %>
+    <% row.cell :id, label: "ID" %>
     ```
 * Define a translation for the attribute
     ```yml
@@ -132,8 +153,8 @@ the table cell. This is often all you need to do, but if you do want to customis
 the value you can pass a block instead:
 
 ```erb
-<%= row.cell :status do %>
- <%= person.password.present? ? "Active" : "Invited" %>
+<% row.cell :status do %>
+  <%= person.password.present? ? "Active" : "Invited" %>
 <% end %>
 ```
 
@@ -141,20 +162,61 @@ In the context of the block you have access the cell builder if you simply
 want to extend the default behaviour:
 
 ```erb
-<%= row.cell :status do |cell| %>
- <%= link_to cell.value, person %>
+<% row.cell :status do |cell| %>
+  <%= link_to cell.value, person %>
 <% end %>
 ```
 
-You can also call `options` on the cell builder, similar to the row builder, but
-please note that this will replace any options passed to the cell as arguments.
+You can also assign to `html_attributes` on the cell builder, similar to the row
+builder, but please note that this will replace any options passed to the cell
+as arguments.
+
+## Collections
 
-### Sort
+The `Katalyst::Tables::Collection::Base` class provides a convenient way to
+manage collections in your controller actions. It is designed to be used with
+Pagy for pagination and provides built-in sorting when used with ActiveRecord
+collections. Sorting and Pagination are off by default, but you can create
+a custom `ApplicationCollection` class that sets them on by default.
 
-The major reason why you should use this gem, apart the convenience of the
-builder, is for adding efficient and simple column sorting to your tables.
+```ruby
+class ApplicationCollection < Katalyst::Tables::Collection::Base
+  config.sorting = "name" # requires models have a name attribute
+  config.pagination = true
+end
+```
 
-Start by including the backend in your controller(s):
+You can then use this class in your controller actions:
+
+```ruby
+class PeopleController < ApplicationController
+  def index
+    @people = ApplicationCollection.new.with_params(params).apply(People.all)
+  end
+end
+```
+
+Collections can be passed directly to `TableComponent` and it will automatically
+detect features such as sorting and generate the appropriate table header links.
+
+```erb
+<%= render TableComponent.new(collection: @people) %>
+```
+
+## Sort
+
+When sort is enabled, table columns will be automatically sortable in the
+frontend for any column that corresponds to an attribute on the model. You can
+also add sorting to non-attribute columns by defining a scope in your
+model:
+
+```
+scope :order_by_status, ->(direction) { ... }
+```
+
+You can also use sort without using collections, this was the primary backend
+interface for V1 and takes design cues from Pagy. Start by including the backend
+in your controller(s):
 
 ```ruby
 include Katalyst::Tables::Backend
@@ -185,55 +247,47 @@ links and show the current sort state:
 <%= table_with collection: @people, sort: @sort do |row, person| %>
   <%= row.cell :name %>
   <%= row.cell :email %>
-  <%= row.cell :actions do %>
-   <%= link_to "Edit", person %>
-  <% end %>
 <% end %>
 ```
 
-That's it! Any column that corresponds to an ActiveRecord attribute will now be
-automatically sortable in the frontend.
+## Pagination
 
-You can also add sorting to non-attribute columns by defining a scope in your
-model:
+This gem designed to work with [pagy](https://github.com/ddnexus/pagy/).
 
-```
-scope :order_by_status, ->(direction) { ... }
-```
+If you use collections and enable pagination then pagy will be called internally
+and the pagy metadata will be available as `pagination` on the collection.
+
+`Katalyst::Tables::PagyNavComponent` can be used to render the pagination links
+for a collection.
 
-Finally, you can use sort with a collection that is already ordered, but please
-note that the backend will call `reorder` if the user provides a sort option. If
-you want to provide a tie-breaker default ordering, the best way to do so is after
-calling `table_sort`.
+```erb
+<%= render Katalyst::Tables::PagyNavComponent.new(collection: @people) %>
+```
 
-You may also want to whitelist the `sort` param if you encounter strong param warnings.
+## Turbo streams
 
-### Pagination
+This gem provides turbo stream entry points for table and pagy_nav. These are
+identical in the options they support, but they require ids, and they will
+automatically render turbo stream replace tags when rendered as part of a turbo
+stream response.
 
-This gem designed to work with [pagy](https://github.com/ddnexus/pagy/).
+To take full advantage of this feature, we suggest you build the component in
+your controller and pass it to the view. This allows you to use the same
+controller for both HTML and turbo responses.
 
 ```ruby
-
 def index
-  @people = People.all
-
-  @sort, @people = table_sort(@people) # sort
-  @pagy, @people = pagy(@people) # then paginate
+  collection = ApplicationCollection.new.with_params(params).apply(People.all)
+  table = Katalyst::Turbo::TableComponent.new(collection:, id: "people")
+  
+  respond_to do |format|
+    format.html { render locals: { table: table } }
+    format.turbo_stream { render table }
+  end
 end
 ```
 
-```erb
-<%= table_with collection: @people, sort: @sort do |row, person| %>
-  <%= row.cell :name %>
-  <%= row.cell :email %>
-  <%= row.cell :actions do %>
-   <%= link_to "Edit", person %>
-  <% end %>
-<% end %>
-<%== pagy_nav(@pagy) %>
-```
-
-### Customization
+## Customization
 
 A common pattern we use is to have a cell at the end of the table for actions. For example:
 
@@ -257,75 +311,53 @@ A common pattern we use is to have a cell at the end of the table for actions. F
 </table>
 ```
 
-You can write a custom builder that helps generate this type of table by adding the required classes and adding helpers
-for generating the actions. This allows for a declarative table syntax, something like this:
+You can write a custom component that helps generate this type of table by
+adding the required classes and adding helpers for generating the actions.
+This allows for a declarative table syntax, something like this:
 
 ```erb
-<%= table_with(collection: collection, builder: Test::ActionTable) do |row| %>
-  <%= row.cell :name %>
-  <%= row.actions do |cell| %>
+<%= render ActionTableComponent.new(collection:) do |row| %>
+  <% row.cell :name %>
+  <% row.actions do |cell| %>
     <%= cell.action "Edit", :edit %>
     <%= cell.action "Delete", :delete, method: :delete %>
   <% end %>
 <% end %>
 ```
 
-And the custom builder:
+And the customized component:
 
 ```ruby
-class ActionTable < Katalyst::Tables::Frontend::TableBuilder
-  def build(&block)
-    (@html_options[:class] ||= []) << "action-table"
-    super
-  end
-
-  def table_header_row(builder = ActionHeaderRow, &block)
-    super
-  end
-
-  def table_header_cell(method, builder = ActionHeaderCell, **options)
-    super
-  end
-
-  def table_body_row(object, builder = ActionBodyRow, &block)
-    super
-  end
+class ActionTableComponent < Katalyst::TableComponent
 
-  def table_body_cell(object, method, builder = ActionBodyCell, **options, &block)
-    super
+  config.header_row = "ActionHeaderRow"
+  config.body_row   = "ActionBodyRow"
+  config.body_cell  = "ActionBodyCell"
+  
+  def default_attributes
+    { class: "action-table" }
   end
 
-  class ActionHeaderRow < Katalyst::Tables::Frontend::Builder::HeaderRow
+  class ActionHeaderRow < Katalyst::Tables::HeaderRowComponent
     def actions(&block)
-      cell(:actions, class: "actions", label: "")
+      cell(:actions, class: "actions", label: "", &block)
     end
   end
 
-  class ActionHeaderCell < Katalyst::Tables::Frontend::Builder::HeaderCell
-  end
-
-  class ActionBodyRow < Katalyst::Tables::Frontend::Builder::BodyRow
+  class ActionBodyRow < Katalyst::Tables::BodyRowComponent
     def actions(&block)
       cell(:actions, class: "actions", &block)
     end
   end
 
-  class ActionBodyCell < Katalyst::Tables::Frontend::Builder::BodyCell
-    def action(label, href, **opts)
-      content_tag :a, label, { href: href }.merge(opts)
+  class ActionBodyCell < Katalyst::Tables::BodyCellComponent
+    def action(label, href, **attrs)
+      content_tag(:a, label, href: href, **attrs)
     end
   end
 end
 ```
 
-If you have a table builder you want to reuse, you can set it as a default for some or all of your controllers:
-
-```html
-class ApplicationController < ActiveController::Base
-  default_table_builder ActionTableBuilder
-end
-```
-
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rspec` to run the tests.

data/app/assets/config/katalyst-tables.js

@@ -0,0 +1 @@
+//= link_tree ../javascripts

data/app/assets/javascripts/controllers/tables/turbo_collection_controller.js

@@ -0,0 +1,22 @@
+import { Controller } from "@hotwired/stimulus";
+
+export default class TurboCollectionController extends Controller {
+  static values = {
+    url: String,
+    sort: String,
+  }
+
+  urlValueChanged(url) {
+    window.history.replaceState({}, "", this.urlValue);
+  }
+
+  sortValueChanged(sort) {
+    document.querySelectorAll(this.#sortSelector).forEach((input) => {
+      if (input) input.value = sort;
+    });
+  }
+
+  get #sortSelector() {
+    return "input[name='sort']";
+  }
+}

data/app/components/concerns/katalyst/tables/configurable_component.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module Tables
+    module ConfigurableComponent # :nodoc:
+      extend ActiveSupport::Concern
+
+      include ActiveSupport::Configurable
+
+      included do
+        # Workaround: ViewComponent::Base.config is incompatible with ActiveSupport::Configurable
+        @_config = Class.new(ActiveSupport::Configurable::Configuration).new
+      end
+
+      class_methods do
+        # Define a configurable sub-component.
+        def config_component(name, component_name: "#{name}_component", default: nil)
+          config_accessor(name)
+          config.public_send("#{name}=", default)
+          define_method(component_name) do
+            instance_variable_get("@#{component_name}") if instance_variable_defined?("@#{component_name}")
+
+            klass     = config.public_send(name)
+            component = self.class.const_get(klass) if klass
+            instance_variable_set("@#{component_name}", component) if component
+          end
+        end
+      end
+    end
+  end
+end

data/app/components/concerns/katalyst/tables/has_html_attributes.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "html_attributes_utils"
+
+module Katalyst
+  module Tables
+    module HasHtmlAttributes # :nodoc:
+      extend ActiveSupport::Concern
+
+      using HTMLAttributesUtils
+
+      DEFAULT_MERGEABLE_ATTRIBUTES = [
+        *HTMLAttributesUtils::DEFAULT_MERGEABLE_ATTRIBUTES,
+        %i[data controller],
+        %i[data action]
+      ].freeze
+
+      def initialize(**options)
+        super(**options.except(:id, :aria, :class, :data, :html))
+
+        self.html_attributes = options
+      end
+
+      # Add HTML options to the current component.
+      # Public method for customizing components from within
+      def html_attributes=(options)
+        @html_attributes = options.slice(:id, :aria, :class, :data).merge(options.fetch(:html, {}))
+      end
+
+      # Backwards compatibility with tables 1.0
+      alias options html_attributes=
+
+      private
+
+      def html_attributes
+        default_attributes
+          .deep_merge_html_attributes(@html_attributes, mergeable_attributes: DEFAULT_MERGEABLE_ATTRIBUTES)
+      end
+
+      def default_attributes
+        {}
+      end
+    end
+  end
+end

data/app/components/concerns/katalyst/tables/has_table_content.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module Tables
+    module HasTableContent # :nodoc:
+      extend ActiveSupport::Concern
+
+      def initialize(object_name: nil, partial: nil, as: nil, **options)
+        super(**options)
+
+        @object_name = object_name || model_name&.i18n_key
+        @partial     = partial
+        @as          = as
+      end
+
+      def model_name
+        collection.model_name if collection.respond_to?(:model_name)
+      end
+
+      private
+
+      def row_proc
+        @row_proc ||= @__vc_render_in_block || method(:row_partial)
+      end
+
+      def row_partial(row, record = nil)
+        partial = @partial || model_name&.param_key&.to_s
+        as      = @as || model_name&.param_key&.to_sym
+        render(partial: partial, variants: [:row], locals: { as => record, row: row })
+      end
+    end
+  end
+end

data/app/components/concerns/katalyst/tables/sortable.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module Tables
+    # Extension to add sorting support to a collection.
+    # Assumes collection and sorting are available in the current scope.
+    module Sortable
+      extend ActiveSupport::Concern
+
+      # Returns true when the given attribute is sortable.
+      def sortable?(attribute)
+        sorting&.supports?(collection, attribute)
+      end
+
+      # Generates a url for applying/toggling sort for the given column.
+      def sort_url(attribute) # rubocop:disable Metrics/AbcSize
+        # Implementation inspired by pagy's `pagy_url_for` helper.
+        # Preserve any existing GET parameters
+        # CAUTION: these parameters are not sanitised
+        sort = attribute && sorting.toggle(attribute)
+        params = if sort && !sort.eql?(sorting.default)
+                   request.GET.merge("sort" => sort).except("page")
+                 else
+                   request.GET.except("page", "sort")
+                 end
+        query_string = params.empty? ? "" : "?#{Rack::Utils.build_nested_query(params)}"
+
+        "#{request.path}#{query_string}"
+      end
+    end
+  end
+end