katalyst-tables 2.0.0 → 2.1.0

data/app/components/katalyst/table_component.rb

@@ -11,38 +11,61 @@ module Katalyst
   # <% end %>
   # ```
   class TableComponent < ViewComponent::Base
-    include ActiveSupport::Configurable
-    include Tables::Frontend::Helper
+    include Tables::ConfigurableComponent
+    include Tables::HasHtmlAttributes
+    include Tables::HasTableContent
+
+    attr_reader :collection, :object_name
+
+    config_component :header_row, default: "Katalyst::Tables::HeaderRowComponent"
+    config_component :header_cell, default: "Katalyst::Tables::HeaderCellComponent"
+    config_component :body_row, default: "Katalyst::Tables::BodyRowComponent"
+    config_component :body_cell, default: "Katalyst::Tables::BodyCellComponent"
+    config_component :caption, default: "Katalyst::Tables::EmptyCaptionComponent"
+
+    # Construct a new table component. This entry point supports a large number
+    # of options for customizing the table. The most common options are:
+    # - `collection`: the collection to render
+    # - `sorting`: the sorting to apply to the collection (defaults to collection.storing if available)
+    # - `header`: whether to render the header row (defaults to true, supports options)
+    # - `caption`: whether to render the caption (defaults to true, supports options)
+    # - `object_name`: the name of the object to use for partial rendering (defaults to collection.model_name.i18n_key)
+    # - `partial`: the name of the partial to use for rendering each row (defaults to collection.model_name.param_key)
+    # - `as`: the name of the local variable to use for rendering each row (defaults to collection.model_name.param_key)
+    # In addition to these options, standard HTML attributes can be passed which will be added to the table tag.
+    def initialize(collection:,
+                   sorting: nil,
+                   header: true,
+                   caption: false,
+                   **html_attributes)
+      @collection = collection
 
-    attr_reader :collection, :sort, :object_name
+      # sorting: instance of Katalyst::Tables::Backend::SortForm. If not provided will be inferred from the collection.
+      @sorting = sorting || html_attributes.delete(:sort) # backwards compatibility with old `sort` option
 
-    # Workaround: ViewComponent::Base.config is incompatible with ActiveSupport::Configurable
-    @_config = Class.new(Configuration).new
+      # header: true means render the header row, header: false means no header row, if a hash, passes as options
+      @header         = header
+      @header_options = (header if header.is_a?(Hash)) || {}
 
-    config_accessor :header_row
-    config_accessor :header_cell
-    config_accessor :body_row
-    config_accessor :body_cell
+      # caption: true means render the caption, caption: false means no caption, if a hash, passes as options
+      @caption         = caption
+      @caption_options = (caption if caption.is_a?(Hash)) || {}
 
-    def initialize(collection:,
-                   sort: nil,
-                   header: true,
-                   object_name: collection.try(:model_name)&.i18n_key,
-                   **html_options)
-      super
-
-      @collection   = collection
-      @sort         = sort
-      @header       = header
-      @object_name  = object_name
+      super(**html_attributes)
     end
 
     def call
-      tag.table(**@html_options) do
-        thead + tbody
+      tag.table(**html_attributes) do
+        concat(caption)
+        concat(thead)
+        concat(tbody)
       end
     end
 
+    def caption
+      caption_component&.new(self)&.render_in(view_context) if @caption
+    end
+
     def thead
       return "".html_safe unless @header
 
@@ -61,31 +84,19 @@ module Katalyst
 
     def render_header
       # extract the column's block from the slot and pass it to the cell for rendering
-      self.class.header_row_component.new(self).render_in(view_context, &@__vc_render_in_block)
+      header_row_component.new(self, **@header_options).render_in(view_context, &row_proc)
     end
 
     def render_row(record)
-      # extract the column's block from the slot and pass it to the cell for rendering
-      block = @__vc_render_in_block
-      self.class.body_row_component.new(self, record).render_in(view_context) do |row|
-        block.call(row, record)
+      body_row_component.new(self, record).render_in(view_context) do |row|
+        row_proc.call(row, record)
       end
     end
 
-    def self.header_row_component
-      @header_row_component ||= const_get(config.header_row || "Katalyst::Tables::HeaderRowComponent")
-    end
-
-    def self.header_cell_component
-      @header_cell_component ||= const_get(config.header_cell || "Katalyst::Tables::HeaderCellComponent")
-    end
-
-    def self.body_row_component
-      @body_row_component ||= const_get(config.body_row || "Katalyst::Tables::BodyRowComponent")
-    end
+    def sorting
+      return @sorting if @sorting.present?
 
-    def self.body_cell_component
-      @body_cell_component ||= const_get(config.body_cell || "Katalyst::Tables::BodyCellComponent")
+      collection.sorting if collection.respond_to?(:sorting)
     end
   end
 end

data/app/components/katalyst/tables/body_cell_component.rb

@@ -3,12 +3,12 @@
 module Katalyst
   module Tables
     class BodyCellComponent < ViewComponent::Base # :nodoc:
-      include Frontend::Helper
+      include HasHtmlAttributes
 
       attr_reader :record
 
-      def initialize(table, record, attribute, heading: false, **html_options)
-        super(**html_options)
+      def initialize(table, record, attribute, heading: false, **html_attributes)
+        super(**html_attributes)
 
         @table     = table
         @record    = record
@@ -24,7 +24,7 @@ module Katalyst
       def call
         content # ensure content is set before rendering options
 
-        content_tag(@type, content, **@html_options)
+        content_tag(@type, content, **html_attributes)
       end
 
       # @return the object for this row.

data/app/components/katalyst/tables/body_row_component.rb

@@ -3,7 +3,7 @@
 module Katalyst
   module Tables
     class BodyRowComponent < ViewComponent::Base # :nodoc:
-      include Frontend::Helper
+      include HasHtmlAttributes
 
       renders_many :columns, ->(component) { component }
 
@@ -17,7 +17,7 @@ module Katalyst
       def call
         content # generate content before rendering
 
-        tag.tr(**@html_options) do
+        tag.tr(**html_attributes) do
           columns.each do |column|
             concat(column.to_s)
           end
@@ -25,7 +25,7 @@ module Katalyst
       end
 
       def cell(attribute, **options, &block)
-        with_column(@table.class.body_cell_component.new(@table, @record, attribute, **options), &block)
+        with_column(@table.body_cell_component.new(@table, @record, attribute, **options), &block)
       end
 
       def header?

data/app/components/katalyst/tables/empty_caption_component.html.erb

@@ -0,0 +1,6 @@
+<%= tag.caption(**html_attributes) do %>
+  No <%= plural_human_model_name %> found.
+  <% if filtered? %>
+    <%= link_to("Clear filters", clear_filters_path) %>.
+  <% end %>
+<% end %>

data/app/components/katalyst/tables/empty_caption_component.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module Tables
+    class EmptyCaptionComponent < ViewComponent::Base # :nodoc:
+      include HasHtmlAttributes
+
+      def initialize(table, **html_attributes)
+        super(**html_attributes)
+
+        @table = table
+      end
+
+      def render?
+        @table.collection.empty?
+      end
+
+      def filtered?
+        @table.collection.respond_to?(:filtered?) && @table.collection.filtered?
+      end
+
+      def clear_filters_path
+        url_for
+      end
+
+      def plural_human_model_name
+        human = @table.model_name&.human || @table.object_name.to_s.humanize
+        human.pluralize.downcase
+      end
+
+      private
+
+      def default_attributes
+        { align: "bottom" }
+      end
+    end
+  end
+end

data/app/components/katalyst/tables/header_cell_component.rb

@@ -4,25 +4,28 @@ module Katalyst
   module Tables
     class HeaderCellComponent < ViewComponent::Base # :nodoc:
       include Frontend::Helper
+      include HasHtmlAttributes
+      include Sortable
 
-      delegate :object_name, :sort, to: :@table
+      delegate :object_name, :collection, :sorting, to: :@table
 
-      def initialize(table, attribute, label: nil, **html_options)
-        super(**html_options)
+      def initialize(table, attribute, label: nil, link: {}, **html_attributes)
+        super(**html_attributes)
 
-        @table        = table
-        @attribute    = attribute
-        @value        = label
+        @table           = table
+        @attribute       = attribute
+        @value           = label
+        @link_attributes = link
       end
 
       def call
-        content = if @table.sort&.supports?(@table.collection, @attribute)
-                    sort_link(value) # writes to html_options
-                  else
-                    value
-                  end
-
-        tag.th(content, **@html_options)
+        tag.th(**html_attributes) do
+          if sortable?(@attribute)
+            link_to(value, sort_url(@attribute), **@link_attributes)
+          else
+            value
+          end
+        end
       end
 
       def value
@@ -45,9 +48,10 @@ module Katalyst
 
       private
 
-      def sort_link(content)
-        (@html_options["data"] ||= {})["sort"] = sort.status(@attribute)
-        link_to(content, sort_url_for(sort: sort.toggle(@attribute)))
+      def default_attributes
+        return {} unless sorting&.supports?(collection, @attribute)
+
+        { data: { sort: sorting.status(@attribute) } }
       end
     end
   end

data/app/components/katalyst/tables/header_row_component.rb

@@ -3,20 +3,21 @@
 module Katalyst
   module Tables
     class HeaderRowComponent < ViewComponent::Base # :nodoc:
-      include Frontend::Helper
+      include HasHtmlAttributes
 
       renders_many :columns, ->(component) { component }
 
-      def initialize(table)
+      def initialize(table, link: {})
         super()
 
-        @table = table
+        @table           = table
+        @link_attributes = link
       end
 
       def call
         content # generate content before rendering
 
-        tag.tr(**@html_options) do
+        tag.tr(**html_attributes) do
           columns.each do |column|
             concat(column.to_s)
           end
@@ -24,7 +25,7 @@ module Katalyst
       end
 
       def cell(attribute, **options, &block)
-        with_column(@table.class.header_cell_component.new(@table, attribute, **options), &block)
+        with_column(@table.header_cell_component.new(@table, attribute, link: @link_attributes, **options), &block)
       end
 
       def header?

data/app/components/katalyst/tables/pagy_nav_component.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module Tables
+    class PagyNavComponent < ViewComponent::Base # :nodoc:
+      include Pagy::Frontend
+
+      attr_reader :pagy_options
+
+      def initialize(collection: nil, pagy: nil, **pagy_options)
+        super()
+
+        pagy ||= collection&.pagination if collection.respond_to?(:pagination)
+
+        raise ArgumentError, "pagy is required" if pagy.blank?
+
+        @pagy         = pagy
+        @pagy_options = pagy_options
+      end
+
+      def call
+        pagy_nav(@pagy, **pagy_options).html_safe # rubocop:disable Rails/OutputSafety
+      end
+    end
+  end
+end

data/app/components/katalyst/turbo/pagy_nav_component.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module Turbo
+    class PagyNavComponent < Tables::PagyNavComponent # :nodoc:
+      include Tables::TurboReplaceable
+
+      def initialize(id:, **options)
+        super(pagy_id: id, **options)
+      end
+
+      def id
+        pagy_options[:pagy_id]
+      end
+
+      private
+
+      def pagy_options
+        super.merge(link_extra: "data-turbo-stream")
+      end
+    end
+  end
+end

data/app/components/katalyst/turbo/table_component.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module Turbo
+    # Renders a table that uses turbo stream replacement when sorting or
+    # paginating.
+    class TableComponent < ::Katalyst::TableComponent
+      include Tables::TurboReplaceable
+
+      def initialize(collection:, id:, header: true, **options)
+        header = if header.is_a?(Hash)
+                   default_header_options.merge(header)
+                 elsif header
+                   default_header_options
+                 end
+
+        super(collection: collection, header: header, id: id, **options)
+      end
+
+      def id
+        html_attributes[:id]
+      end
+
+      private
+
+      def default_attributes
+        {
+          data: {
+            controller: "tables--turbo-collection",
+            tables__turbo_collection_url_value: current_path,
+            tables__turbo_collection_sort_value: collection.sort
+          }
+        }
+      end
+
+      def current_path
+        params = collection.to_params
+        query_string = params.empty? ? "" : "?#{Rack::Utils.build_nested_query(params)}"
+
+        "#{request.path}#{query_string}"
+      end
+
+      def default_header_options
+        { link: { data: { turbo_stream: "" } } }
+      end
+    end
+  end
+end

data/app/models/concerns/katalyst/tables/collection/core.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module Tables
+    module Collection
+      module Core # :nodoc:
+        extend ActiveSupport::Concern
+
+        include ActiveModel::Model
+        include ActiveModel::Attributes
+        include ActiveModel::Dirty
+        include ActiveSupport::Configurable
+
+        included do
+          class_attribute :reducers, default: ActionDispatch::MiddlewareStack.new
+
+          class << self
+            delegate :use, :before, to: :reducers
+          end
+
+          attr_accessor :items
+
+          delegate :model, :to_model, :each, :count, :empty?, to: :items, allow_nil: true
+          delegate :model_name, to: :model, allow_nil: true
+        end
+
+        def initialize(**options)
+          super
+
+          clear_changes_information
+        end
+
+        def filter
+          # no-op by default
+        end
+
+        def filtered?
+          !self.class.new.filters.eql?(filters)
+        end
+
+        def filters
+          attributes.except("page", "sort")
+        end
+
+        def apply(items)
+          @items = items
+          reducers.build do |_|
+            filter
+            self
+          end.call(self)
+          self
+        end
+
+        def with_params(params)
+          self.attributes = params.permit(self.class.attribute_types.keys)
+
+          self
+        end
+
+        # Returns a hash of the current attributes that have changed from defaults.
+        def to_params
+          attributes.slice(*changed)
+        end
+
+        def inspect
+          "#<#{self.class.name} @attributes=#{attributes.inspect} @model=\"#{model}\" @count=#{items&.count}>"
+        end
+      end
+    end
+  end
+end

data/app/models/concerns/katalyst/tables/collection/pagination.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "pagy/backend"
+
+module Katalyst
+  module Tables
+    module Collection
+      # Adds pagination support for a collection.
+      #
+      # Pagination will be applied if the collection is configured to paginate
+      # by either specifying `config.paginate = true` or passing
+      # `paginate: true` to the initializer.
+      #
+      # If the value given to `paginate` is a hash, it will be passed to the
+      # `pagy` gem as options.
+      #
+      # If `page` is present in params it will be passed to pagy.
+      module Pagination
+        extend ActiveSupport::Concern
+
+        included do
+          attr_accessor :pagination
+
+          attribute :page, :integer, default: 1
+
+          config_accessor :paginate
+        end
+
+        def initialize(paginate: config.paginate, **options)
+          super(**options)
+
+          @paginate = paginate
+        end
+
+        def paginate?
+          !!@paginate
+        end
+
+        def paginate_options
+          @paginate.is_a?(Hash) ? @paginate : {}
+        end
+
+        class Paginate # :nodoc:
+          include Pagy::Backend
+
+          def initialize(app)
+            @app = app
+          end
+
+          def call(collection)
+            @collection = @app.call(collection)
+            if collection.paginate?
+              @collection.pagination, @collection.items = pagy(@collection.items, collection.paginate_options)
+            end
+            @collection
+          end
+
+          # pagy shim
+          def params
+            @collection.attributes.with_indifferent_access
+          end
+        end
+      end
+    end
+  end
+end

data/app/models/concerns/katalyst/tables/collection/sorting.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "pagy/backend"
+
+module Katalyst
+  module Tables
+    module Collection
+      # Adds sorting support to a collection.
+      #
+      # Sorting will be applied if the collection is configured with a default
+      # sorting configuration by either specifying
+      # `config.sorting = "column direction"` or passing
+      # `sorting: "column direction"` to the initializer.
+      #
+      # If `sort` is present in params it will override the default sorting.
+      module Sorting
+        extend ActiveSupport::Concern
+
+        included do
+          config_accessor :sorting
+          attr_accessor :sorting
+
+          attribute :sort, :string
+        end
+
+        def initialize(sorting: config.sorting, **options)
+          @sorting = Backend::SortForm.parse(sorting) if sorting
+
+          super(sort: sorting, **options) # set default sort based on config
+        end
+
+        def sort=(value)
+          return unless @sorting
+
+          # update internal proxy
+          @sorting = Backend::SortForm.parse(value, default: attribute_was(:sort))
+
+          # update attribute based on normalized value
+          super(@sorting.to_param)
+        end
+
+        class Sort # :nodoc:
+          include Backend
+
+          def initialize(app)
+            @app = app
+          end
+
+          def call(collection)
+            @collection                            = @app.call(collection)
+            @collection.sorting, @collection.items = @collection.sorting.apply(@collection.items) if @collection.sorting
+            @collection
+          end
+
+          # pagy shim
+          def params
+            @collection.attributes
+          end
+        end
+      end
+    end
+  end
+end

data/app/models/katalyst/tables/collection.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module Tables
+    module Collection
+      # Entry point for creating a collection for use with table components.
+      # This class is intended to be subclassed, i.e.:
+      #
+      # class ApplicationController < ActionController::Base
+      #   class Collection < Katalyst::Tables::Collection::Base
+      #     ...
+      #   end
+      # end
+      #
+      # In the context of a controller action, construct a collection, apply it
+      # to a model, then pass the result to the view component:
+      # ```
+      # collection = Collection.new.with_params(params).apply(People.all)
+      # table = Katalyst::TableComponent.new(collection: collection)
+      # render table
+      # ````
+      class Base
+        include Core
+        include Pagination
+        include Sorting
+
+        use(Pagination::Paginate)
+        use(Sorting::Sort)
+      end
+    end
+  end
+end

data/config/importmap.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+pin "@hotwired/stimulus", to: "stimulus.min.js", preload: true
+
+pin_all_from Katalyst::Tables::Engine.root.join("app/assets/javascripts"),
+             # preload in tests so that we don't start clicking before controllers load
+             preload: Rails.env.test?

data/lib/katalyst/tables/backend/sort_form.rb

@@ -8,11 +8,25 @@ module Katalyst
       class SortForm
         DIRECTIONS = %w[asc desc].freeze
 
-        attr_accessor :column, :direction
+        attr_accessor :column, :direction, :default
 
-        def initialize(column: nil, direction: nil)
+        def self.parse(param, default: nil)
+          column, direction = param.to_s.split
+          direction         = "asc" unless DIRECTIONS.include?(direction)
+
+          default = SortForm.parse(default).to_param if default.present?
+
+          SortForm.new(column: column, direction: direction, default: default)
+        end
+
+        def initialize(column: nil, direction: nil, default: nil)
           self.column    = column
           self.direction = direction
+          self.default   = default
+        end
+
+        def to_param
+          "#{column} #{direction}"
         end
 
         # Returns true if the given collection supports sorting on the given