katalyst-tables 1.1.0 → 2.1.0

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

data/app/components/katalyst/table_component.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Katalyst
+  # A component for rendering a table from a collection, with a header row.
+  # ```erb
+  # <%= Katalyst::TableComponent.new(collection: @people) do |row, person| %>
+  #   <%= row.cell :name do |cell| %>
+  #     <%= link_to cell.value, person %>
+  #   <% end %>
+  #   <%= row.cell :email %>
+  # <% end %>
+  # ```
+  class TableComponent < ViewComponent::Base
+    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
+
+      # 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
+
+      # 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)) || {}
+
+      # 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)) || {}
+
+      super(**html_attributes)
+    end
+
+    def call
+      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
+
+      tag.thead do
+        concat(render_header)
+      end
+    end
+
+    def tbody
+      tag.tbody do
+        collection.each do |record|
+          concat(render_row(record))
+        end
+      end
+    end
+
+    def render_header
+      # extract the column's block from the slot and pass it to the cell for rendering
+      header_row_component.new(self, **@header_options).render_in(view_context, &row_proc)
+    end
+
+    def render_row(record)
+      body_row_component.new(self, record).render_in(view_context) do |row|
+        row_proc.call(row, record)
+      end
+    end
+
+    def sorting
+      return @sorting if @sorting.present?
+
+      collection.sorting if collection.respond_to?(:sorting)
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module Tables
+    class BodyCellComponent < ViewComponent::Base # :nodoc:
+      include HasHtmlAttributes
+
+      attr_reader :record
+
+      def initialize(table, record, attribute, heading: false, **html_attributes)
+        super(**html_attributes)
+
+        @table     = table
+        @record    = record
+        @attribute = attribute
+        @type      = heading ? :th : :td
+      end
+
+      def before_render
+        # fallback if no content block is given
+        with_content(value.to_s) unless content?
+      end
+
+      def call
+        content # ensure content is set before rendering options
+
+        content_tag(@type, content, **html_attributes)
+      end
+
+      # @return the object for this row.
+      def object
+        @record
+      end
+
+      def value
+        @record.public_send(@attribute)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module Tables
+    class BodyRowComponent < ViewComponent::Base # :nodoc:
+      include HasHtmlAttributes
+
+      renders_many :columns, ->(component) { component }
+
+      def initialize(table, record)
+        super()
+
+        @table  = table
+        @record = record
+      end
+
+      def call
+        content # generate content before rendering
+
+        tag.tr(**html_attributes) do
+          columns.each do |column|
+            concat(column.to_s)
+          end
+        end
+      end
+
+      def cell(attribute, **options, &block)
+        with_column(@table.body_cell_component.new(@table, @record, attribute, **options), &block)
+      end
+
+      def header?
+        false
+      end
+
+      def body?
+        true
+      end
+    end
+  end
+end

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module Tables
+    class HeaderCellComponent < ViewComponent::Base # :nodoc:
+      include Frontend::Helper
+      include HasHtmlAttributes
+      include Sortable
+
+      delegate :object_name, :collection, :sorting, to: :@table
+
+      def initialize(table, attribute, label: nil, link: {}, **html_attributes)
+        super(**html_attributes)
+
+        @table           = table
+        @attribute       = attribute
+        @value           = label
+        @link_attributes = link
+      end
+
+      def call
+        tag.th(**html_attributes) do
+          if sortable?(@attribute)
+            link_to(value, sort_url(@attribute), **@link_attributes)
+          else
+            value
+          end
+        end
+      end
+
+      def value
+        if !@value.nil?
+          @value
+        elsif object_name.present?
+          translation
+        else
+          default_value
+        end
+      end
+
+      def translation(key = "activerecord.attributes.#{object_name}.#{@attribute}")
+        translate(key, default: default_value)
+      end
+
+      def default_value
+        @attribute.to_s.humanize.capitalize
+      end
+
+      private
+
+      def default_attributes
+        return {} unless sorting&.supports?(collection, @attribute)
+
+        { data: { sort: sorting.status(@attribute) } }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module Tables
+    class HeaderRowComponent < ViewComponent::Base # :nodoc:
+      include HasHtmlAttributes
+
+      renders_many :columns, ->(component) { component }
+
+      def initialize(table, link: {})
+        super()
+
+        @table           = table
+        @link_attributes = link
+      end
+
+      def call
+        content # generate content before rendering
+
+        tag.tr(**html_attributes) do
+          columns.each do |column|
+            concat(column.to_s)
+          end
+        end
+      end
+
+      def cell(attribute, **options, &block)
+        with_column(@table.header_cell_component.new(@table, attribute, link: @link_attributes, **options), &block)
+      end
+
+      def header?
+        true
+      end
+
+      def body?
+        false
+      end
+    end
+  end
+end

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