katalyst-tables 1.1.0 → 2.1.0

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

data/lib/katalyst/tables/backend.rb

@@ -28,23 +28,23 @@ module Katalyst
       end
 
       included do
-        class_attribute :_default_table_builder, instance_accessor: false
+        class_attribute :_default_table_component, instance_accessor: false
       end
 
       class_methods do
-        # Set the table builder to be used as the default for all tables
+        # Set the table component to be used as the default for all tables
         # in the views rendered by this controller and its subclasses.
         #
         # ==== Parameters
-        # * <tt>builder</tt> - Default table builder, an instance of +Katalyst::Tables::Frontend::TableBuilder+
-        def default_table_builder(builder)
-          self._default_table_builder = builder
+        # * <tt>component</tt> - Default table component, an instance of +Katalyst::TableComponent+
+        def default_table_component(component)
+          self._default_table_component = component
         end
       end
 
-      # Default table builder for the controller
-      def default_table_builder
-        self.class._default_table_builder
+      # Default table component for this controller
+      def default_table_component
+        self.class._default_table_component
       end
     end
   end

data/lib/katalyst/tables/engine.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "rails"
+
+module Katalyst
+  module Tables
+    class Engine < ::Rails::Engine # :nodoc:
+      isolate_namespace Katalyst::Tables
+
+      initializer "katalyst-tables.asset" do
+        config.after_initialize do |app|
+          app.config.assets.precompile += %w[katalyst-tables.js] if app.config.respond_to?(:assets)
+        end
+      end
+
+      initializer "katalyst-tables.importmap", before: "importmap" do |app|
+        if app.config.respond_to?(:importmap)
+          app.config.importmap.paths << root.join("config/importmap.rb")
+          app.config.importmap.cache_sweepers << root.join("app/assets/javascripts")
+        end
+      end
+    end
+  end
+end

data/lib/katalyst/tables/frontend/helper.rb

@@ -3,6 +3,7 @@
 module Katalyst
   module Tables
     module Frontend
+      # @deprecated Use {Katalyst::TableComponent} instead.
       module Helper # :nodoc:
         extend ActiveSupport::Concern
 
@@ -10,22 +11,20 @@ module Katalyst
         #
         # @param sort [String, nil] sort parameter to apply, or nil to remove sorting
         # @return [String] URL for toggling column sorting
-        def sort_url_for(sort: nil)
+        # @deprecated Use {Katalyst::TablesComponent} instead.
+        def sort_url_for(sort: nil, default: nil)
           # Implementation inspired by pagy's `pagy_url_for` helper.
           # Preserve any existing GET parameters
           # CAUTION: these parameters are not sanitised
-          params       = request.GET.merge("sort" => sort).except("page")
+          params = if sort && !sort.eql?(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
-
-        private
-
-        def html_options_for_table_with(html: {}, **options)
-          html_options = options.slice(:id, :class, :data).merge(html)
-          html_options.stringify_keys!
-        end
       end
     end
   end

data/lib/katalyst/tables/frontend.rb

@@ -1,51 +1,21 @@
 # frozen_string_literal: true
 
-require_relative "frontend/builder/base"
-require_relative "frontend/builder/body_cell"
-require_relative "frontend/builder/body_row"
-require_relative "frontend/builder/header_cell"
-require_relative "frontend/builder/header_row"
 require_relative "frontend/helper"
-require_relative "frontend/table_builder"
 
 module Katalyst
   module Tables
     # View Helper for generating HTML tables. Include in your ApplicationHelper, or similar.
     module Frontend
-      include Helper
-
-      def table_with(collection:, **options, &block)
-        table_options = options.slice(:header, :object_name, :sort)
-
-        table_options[:object_name] ||= collection.try(:model_name)&.i18n_key
-
-        html_options = html_options_for_table_with(**options)
-
-        builder = options.fetch(:builder) { default_table_builder_class }
-        builder.new(self, collection, table_options, html_options).build(&block)
-      end
-
-      def table_header_row(table, builder, &block)
-        builder.new(table).build(&block)
-      end
-
-      def table_header_cell(table, method, builder, **options, &block)
-        builder.new(table, method, **options).build(&block)
-      end
-
-      def table_body_row(table, object, builder, &block)
-        builder.new(table, object).build(&block)
-      end
-
-      def table_body_cell(table, object, method, builder, **options, &block)
-        builder.new(table, object, method, **options).build(&block)
+      def table_with(collection:, component: nil, **options, &block)
+        component ||= default_table_component_class
+        render(component.new(collection: collection, **options), &block)
       end
 
       private
 
-      def default_table_builder_class
-        builder = controller.try(:default_table_builder) || TableBuilder
-        builder.respond_to?(:constantize) ? builder.constantize : builder
+      def default_table_component_class
+        component = controller.try(:default_table_component) || TableComponent
+        component.respond_to?(:constantize) ? component.constantize : component
       end
     end
   end

data/lib/katalyst/tables/version.rb

@@ -2,6 +2,6 @@
 
 module Katalyst
   module Tables
-    VERSION = "1.1.0"
+    VERSION = "2.1.0"
   end
 end

data/lib/katalyst/tables.rb

@@ -1,9 +1,14 @@
 # frozen_string_literal: true
 
+require "view_component"
+
 require_relative "tables/backend"
+require_relative "tables/engine"
 require_relative "tables/frontend"
 require_relative "tables/version"
 
+require_relative "tables/engine" if Object.const_defined?("Rails")
+
 module Katalyst
   module Tables
     class Error < StandardError; end

metadata

@@ -1,15 +1,43 @@
 --- !ruby/object:Gem::Specification
 name: katalyst-tables
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Katalyst Interactive
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-07-18 00:00:00.000000000 Z
-dependencies: []
+date: 2023-07-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: html-attributes-utils
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: view_component
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Builder-style HTML table generator for building tabular index views.
   Supports sorting by columns.
 email:
@@ -21,17 +49,34 @@ files:
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
+- app/assets/config/katalyst-tables.js
+- app/assets/javascripts/controllers/tables/turbo_collection_controller.js
+- app/components/concerns/katalyst/tables/configurable_component.rb
+- app/components/concerns/katalyst/tables/has_html_attributes.rb
+- app/components/concerns/katalyst/tables/has_table_content.rb
+- app/components/concerns/katalyst/tables/sortable.rb
+- app/components/concerns/katalyst/tables/turbo_replaceable.rb
+- app/components/katalyst/table_component.rb
+- app/components/katalyst/tables/body_cell_component.rb
+- app/components/katalyst/tables/body_row_component.rb
+- app/components/katalyst/tables/empty_caption_component.html.erb
+- app/components/katalyst/tables/empty_caption_component.rb
+- app/components/katalyst/tables/header_cell_component.rb
+- app/components/katalyst/tables/header_row_component.rb
+- app/components/katalyst/tables/pagy_nav_component.rb
+- app/components/katalyst/turbo/pagy_nav_component.rb
+- app/components/katalyst/turbo/table_component.rb
+- app/models/concerns/katalyst/tables/collection/core.rb
+- app/models/concerns/katalyst/tables/collection/pagination.rb
+- app/models/concerns/katalyst/tables/collection/sorting.rb
+- app/models/katalyst/tables/collection.rb
+- config/importmap.rb
 - lib/katalyst/tables.rb
 - lib/katalyst/tables/backend.rb
 - lib/katalyst/tables/backend/sort_form.rb
+- lib/katalyst/tables/engine.rb
 - lib/katalyst/tables/frontend.rb
-- lib/katalyst/tables/frontend/builder/base.rb
-- lib/katalyst/tables/frontend/builder/body_cell.rb
-- lib/katalyst/tables/frontend/builder/body_row.rb
-- lib/katalyst/tables/frontend/builder/header_cell.rb
-- lib/katalyst/tables/frontend/builder/header_row.rb
 - lib/katalyst/tables/frontend/helper.rb
-- lib/katalyst/tables/frontend/table_builder.rb
 - lib/katalyst/tables/version.rb
 homepage: https://github.com/katalyst/katalyst-tables
 licenses:

data/lib/katalyst/tables/frontend/builder/base.rb

@@ -1,63 +0,0 @@
-# frozen_string_literal: true
-
-require "active_support"
-require "active_support/core_ext/module/delegation"
-
-require_relative "../helper"
-
-module Katalyst
-  module Tables
-    module Frontend
-      module Builder
-        class Base # :nodoc:
-          include Helper
-
-          attr_reader :table
-
-          delegate :sort,
-                   :table_header_cell,
-                   :table_header_row,
-                   :table_body_cell,
-                   :table_body_row,
-                   :template,
-                   to: :table
-
-          delegate :content_tag,
-                   :link_to,
-                   :render,
-                   :request,
-                   :translate,
-                   :with_output_buffer,
-                   to: :template
-
-          def initialize(table, **options)
-            @table  = table
-            @header = false
-            self.options(**options)
-          end
-
-          def header?
-            @header
-          end
-
-          def body?
-            !@header
-          end
-
-          def options(**options)
-            @html_options = html_options_for_table_with(**options)
-          end
-
-          private
-
-          def table_tag(type, value = nil, &block)
-            # capture output before calling tag, to allow users to modify `options` during body execution
-            value = with_output_buffer(&block) if block_given?
-
-            content_tag(type, value, @html_options, &block)
-          end
-        end
-      end
-    end
-  end
-end

data/lib/katalyst/tables/frontend/builder/body_cell.rb

@@ -1,31 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "base"
-
-module Katalyst
-  module Tables
-    module Frontend
-      module Builder
-        class BodyCell < Base # :nodoc:
-          attr_reader :object, :method
-
-          def initialize(table, object, method, **options)
-            super table, **options
-
-            @type   = options.fetch(:heading, false) ? :th : :td
-            @object = object
-            @method = method
-          end
-
-          def build
-            table_tag(@type) { block_given? ? yield(self).to_s : value.to_s }
-          end
-
-          def value
-            object.public_send(method)
-          end
-        end
-      end
-    end
-  end
-end

data/lib/katalyst/tables/frontend/builder/body_row.rb

@@ -1,29 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "base"
-
-module Katalyst
-  module Tables
-    module Frontend
-      module Builder
-        class BodyRow < Base # :nodoc:
-          attr_reader :object
-
-          def initialize(table, object)
-            super table
-
-            @object = object
-          end
-
-          def build
-            table_tag(:tr) { yield self, object }
-          end
-
-          def cell(method, **options, &block)
-            table_body_cell(object, method, **options, &block)
-          end
-        end
-      end
-    end
-  end
-end

data/lib/katalyst/tables/frontend/builder/header_cell.rb

@@ -1,55 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "body_cell"
-
-module Katalyst
-  module Tables
-    module Frontend
-      module Builder
-        class HeaderCell < BodyCell # :nodoc:
-          def initialize(table, method, **options)
-            super(table, nil, method, **options)
-
-            @value  = options[:label]
-            @header = true
-          end
-
-          def build(&_block)
-            # NOTE: block ignored intentionally but subclasses may consume it
-            if @table.sort&.supports?(@table.collection, method)
-              content = sort_link(value) # writes to html_options
-              table_tag :th, content # consumes options
-            else
-              table_tag :th, value
-            end
-          end
-
-          def value
-            if !@value.nil?
-              @value
-            elsif @table.object_name.present?
-              translation
-            else
-              default_value
-            end
-          end
-
-          def translation(key = "activerecord.attributes.#{@table.object_name}.#{method}")
-            translate(key, default: default_value)
-          end
-
-          def default_value
-            method.to_s.humanize.titleize
-          end
-
-          private
-
-          def sort_link(content)
-            (@html_options["data"] ||= {})["sort"] = sort.status(method)
-            link_to(content, sort_url_for(sort: sort.toggle(method)))
-          end
-        end
-      end
-    end
-  end
-end

data/lib/katalyst/tables/frontend/builder/header_row.rb

@@ -1,23 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "body_row"
-
-module Katalyst
-  module Tables
-    module Frontend
-      module Builder
-        class HeaderRow < BodyRow # :nodoc:
-          def initialize(table)
-            super table, nil
-
-            @header = true
-          end
-
-          def cell(method, **options, &block)
-            table_header_cell(method, **options, &block)
-          end
-        end
-      end
-    end
-  end
-end

data/lib/katalyst/tables/frontend/table_builder.rb

@@ -1,71 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "builder/body_cell"
-require_relative "builder/body_row"
-require_relative "builder/header_cell"
-require_relative "builder/header_row"
-
-module Katalyst
-  module Tables
-    module Frontend
-      # Builder API for generating HTML tables from ActiveRecord.
-      # @see Frontend#table_with
-      class TableBuilder
-        attr_reader :template, :collection, :object_name, :sort
-
-        def initialize(template, collection, options, html_options)
-          @template     = template
-          @collection   = collection
-          @header       = options.fetch(:header, true)
-          @object_name  = options.fetch(:object_name, nil)
-          @sort         = options[:sort]
-          @html_options = html_options
-        end
-
-        def table_header_row(builder = nil, &block)
-          @template.table_header_row(self, builder || Builder::HeaderRow, &block)
-        end
-
-        def table_header_cell(method, builder = nil, **options, &block)
-          @template.table_header_cell(self, method, builder || Builder::HeaderCell, **options, &block)
-        end
-
-        def table_body_row(object, builder = nil, &block)
-          @template.table_body_row(self, object, builder || Builder::BodyRow, &block)
-        end
-
-        def table_body_cell(object, method, builder = nil, **options, &block)
-          @template.table_body_cell(self, object, method, builder || Builder::BodyCell, **options, &block)
-        end
-
-        def build(&block)
-          template.content_tag("table", @html_options) do
-            thead(&block) + tbody(&block)
-          end
-        end
-
-        private
-
-        def thead(&block)
-          return "".html_safe unless @header
-
-          template.content_tag("thead") do
-            table_header_row(&block)
-          end
-        end
-
-        def tbody(&block)
-          template.content_tag("tbody") do
-            buffer = ActiveSupport::SafeBuffer.new
-
-            collection.each do |object|
-              buffer << table_body_row(object, &block)
-            end
-
-            buffer
-          end
-        end
-      end
-    end
-  end
-end