katalyst-tables 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4c4a55f7a1b45c9f70f357eaa670debf6457aca92a8ac7ea8b10df20140d1c23
-  data.tar.gz: 620cff7771f9de2d74c613d6b107136ea34c494862d2da4e612ccb55d8dee51d
+  metadata.gz: 2a572503d453b3b8b98a82942a48c5e2772cec4023417e8db71ed2cd8299331a
+  data.tar.gz: 4761c4fa4b21aa8c91f70c2118e27bd68dfd700ffc419ed6f7eae299b582710f
 SHA512:
-  metadata.gz: 15cc508fdbb3ad40baec51314fde01c3889b670d4ccd6366ea49171a45b979d441a4fb3fafe65e5bd07093375615b6d298ebe091f240122edf9d68b10471f251
-  data.tar.gz: e5f4186c070c81c4645bc3cf8a378927f502df6084d235c38416d98eb7e4ab45c775da2d22338d32bf5063774a575b4c7a92a556468f1b35d18c809db421922c
+  metadata.gz: aa9c1dc28479dc744c18804999d5f34ea9937e1500dbe8c01a1f2c183439077dfdd7047dbb8ce2ea0f93ef43bcfcea15eee6d08b2606f3682a00747e590cbc3b
+  data.tar.gz: 45c36c312e7f6efa8b11409d4822d135c961eba6ade51055b4671371b3b1a6e25a01c9fd1e059c0a89fa5da6bea3e7fe56fda267a1b3d7bfdf51e515b7b8a696

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 ## [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 

data/README.md

@@ -16,76 +16,99 @@ And then execute:
 
 ## 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 %>
 ```
 
-The 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") %>
+``` 
+
+### Inline tables
 
-Tables support options via the call to `table_with`, similar to `form_with`.
+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
@@ -93,8 +116,8 @@ 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.
@@ -130,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 %>
 ```
 
@@ -139,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.
 
-### Sort
+## Collections
 
-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.
+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.
+
+```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
@@ -183,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.
 
-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`.
+`Katalyst::Tables::PagyNavComponent` can be used to render the pagination links
+for a collection.
 
-You may also want to whitelist the `sort` param if you encounter strong param warnings.
+```erb
+<%= render Katalyst::Tables::PagyNavComponent.new(collection: @people) %>
+```
 
-### Pagination
+## Turbo streams
 
-This gem designed to work with [pagy](https://github.com/ddnexus/pagy/).
+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.
 
-```ruby
+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:
 
@@ -255,11 +311,12 @@ 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, component: ActionTableComponent) do |row| %>
+<%= render ActionTableComponent.new(collection:) do |row| %>
   <% row.cell :name %>
   <% row.actions do |cell| %>
     <%= cell.action "Edit", :edit %>
@@ -276,10 +333,9 @@ class ActionTableComponent < Katalyst::TableComponent
   config.header_row = "ActionHeaderRow"
   config.body_row   = "ActionBodyRow"
   config.body_cell  = "ActionBodyCell"
-
-  def call
-    options(class: "action-table")
-    super
+  
+  def default_attributes
+    { class: "action-table" }
   end
 
   class ActionHeaderRow < Katalyst::Tables::HeaderRowComponent
@@ -295,21 +351,13 @@ class ActionTableComponent < Katalyst::TableComponent
   end
 
   class ActionBodyCell < Katalyst::Tables::BodyCellComponent
-    def action(label, href, **opts)
-      content_tag :a, label, { href: href }.merge(opts)
+    def action(label, href, **attrs)
+      content_tag(:a, label, href: href, **attrs)
     end
   end
 end
 ```
 
-If you have a table component 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_component ActionTableComponent
-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

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module Tables
+    # Adds support for turbo stream replacement to ViewComponents. Components
+    # that are rendered from a turbo-stream-compatible response will be rendered
+    # using turbo stream replacement. Components must define `id`.
+    #
+    # Turbo stream replacement rendering will only be enabled if the component
+    # passes `turbo: true` as a constructor option.
+    module TurboReplaceable
+      extend ActiveSupport::Concern
+
+      include ::Turbo::StreamsHelper
+
+      def turbo?
+        @turbo
+      end
+
+      def initialize(turbo: true, **options)
+        super(**options)
+
+        @turbo = turbo
+      end
+
+      class_methods do
+        # Redefine the compiler to use our custom compiler.
+        # Compiler is set on `inherited` so we need to re-set it if it's not the expected type.
+        def compiler
+          @vc_compiler = @vc_compiler.is_a?(TurboCompiler) ? @vc_compiler : TurboCompiler.new(self)
+        end
+      end
+
+      included do
+        # ensure that our custom compiler is used, as `inherited` calls `compile` before our module is included.
+        compile(force: true) if compiled?
+      end
+
+      # Wraps the default compiler provided by ViewComponent to add turbo support.
+      class TurboCompiler < ViewComponent::Compiler
+        private
+
+        def define_render_template_for # rubocop:disable Metrics/MethodLength
+          super
+
+          redefinition_lock.synchronize do
+            component_class.alias_method(:vc_render_template_for, :render_template_for)
+            component_class.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+            def render_template_for(variant = nil)
+              return vc_render_template_for(variant) unless turbo?
+              controller.respond_to do |format|
+                format.html { vc_render_template_for(variant) }
+                format.turbo_stream { turbo_stream.replace(id, vc_render_template_for(variant)) }
+              end
+            end
+            RUBY
+          end
+        end
+      end
+    end
+  end
+end