katalyst-tables 3.0.0.beta1 → 3.0.0

data/app/components/katalyst/tables/{body → cells}/number_component.rb

@@ -1,20 +1,20 @@
 # frozen_string_literal: true
 
-using Katalyst::HtmlAttributes::HasHtmlAttributes
-
 module Katalyst
   module Tables
-    module Body
+    module Cells
       # Formats the value as a number
       #
       # Adds a class to the cell to allow for custom styling
-      class NumberComponent < BodyCellComponent
+      class NumberComponent < CellComponent
         def rendered_value
           value.present? ? number_to_human(value) : ""
         end
 
+        private
+
         def default_html_attributes
-          super.merge_html(class: "type-number")
+          { class: "type-number" }
         end
       end
     end

data/app/components/katalyst/tables/cells/ordinal_component.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module Tables
+    module Cells
+      class OrdinalComponent < CellComponent
+        def initialize(primary_key:, **)
+          super(**)
+
+          @primary_key = primary_key
+        end
+
+        def rendered_value
+          t("katalyst.tables.orderable.value")
+        end
+
+        private
+
+        def default_html_attributes
+          if @row.header?
+            { class: "ordinal" }
+          else
+            {
+              class: "ordinal",
+              data:  {
+                controller:                                   Orderable::ITEM_CONTROLLER,
+                "#{Orderable::ITEM_CONTROLLER}-params-value": params.to_json,
+              },
+            }
+          end
+        end
+
+        def params
+          {
+            id_name:     @primary_key,
+            id_value:    record.public_send(@primary_key),
+            index_name:  column,
+            index_value: record.public_send(column),
+          }
+        end
+      end
+    end
+  end
+end

data/app/components/katalyst/tables/{body → cells}/rich_text_component.rb

@@ -1,16 +1,19 @@
 # frozen_string_literal: true
 
-using Katalyst::HtmlAttributes::HasHtmlAttributes
-
 module Katalyst
   module Tables
-    module Body
+    module Cells
       # Displays the plain text for rich text content
       #
       # Adds a title attribute to allow for hover over display of the full content
-      class RichTextComponent < BodyCellComponent
+      class RichTextComponent < CellComponent
+        private
+
         def default_html_attributes
-          { title: value.to_plain_text }
+          {
+            class: "type-rich-text",
+            title: (value.to_plain_text unless row.header?),
+          }
         end
       end
     end

data/app/components/katalyst/tables/cells/select_component.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module Tables
+    module Cells
+      class SelectComponent < CellComponent
+        def initialize(params:, form_id:, **)
+          super(**)
+
+          @params  = params
+          @form_id = form_id
+        end
+
+        def rendered_value
+          tag.input(type: :checkbox)
+        end
+
+        private
+
+        def default_html_attributes
+          if @row.header?
+            { class: "selection" }
+          else
+            {
+              class: "selection",
+              data:  {
+                controller:                                    Selectable::ITEM_CONTROLLER,
+                "#{Selectable::ITEM_CONTROLLER}-params-value"              => @params.to_json,
+                "#{Selectable::ITEM_CONTROLLER}-#{Selectable::FORM_CONTROLLER}-outlet" => "##{@form_id}",
+                action:                                        "change->#{Selectable::ITEM_CONTROLLER}#change",
+                turbo_permanent:                               "",
+              },
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module Tables
+    class Data
+      def initialize(record:, column:)
+        @record = record
+        @column = column
+      end
+
+      def value
+        return @value if defined?(@value)
+
+        @value = @record&.public_send(@column)
+      end
+
+      def call
+        ActionView::OutputBuffer.new.tap do |output|
+          output << value.to_s
+        end.to_s
+      end
+
+      alias to_s call
+
+      def inspect
+        "#<#{self.class.name} column: #{@column.inspect}, value: #{value.inspect}>"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,5 @@
+<%= tag.tr(**html_attributes) do %>
+<% cells.each do |cell| %>
+  <%= cell %>
+<% end %>
+<% end %>

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

@@ -4,29 +4,11 @@ module Katalyst
   module Tables
     class HeaderRowComponent < ViewComponent::Base # :nodoc:
       include Katalyst::HtmlAttributes
-      include Header::TypedColumns
 
-      renders_many :columns, ->(component) { component }
+      renders_many :cells, ->(cell) { cell }
 
-      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, **, &)
-        with_column(@table.header_cell_component.new(@table, attribute, link: @link_attributes, **), &)
+      def before_render
+        content # ensure content is rendered so html_attributes can be set
       end
 
       def header?
@@ -38,11 +20,8 @@ module Katalyst
       end
 
       def inspect
-        "#<#{self.class.name} link_attributes: #{@link_attributes.inspect}>"
+        "#<#{self.class.name}>"
       end
-
-      # Backwards compatibility with tables 1.0
-      alias_method :options, :html_attributes=
     end
   end
 end

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module Tables
+    class Label
+      def initialize(collection:, column:, label: nil)
+        @collection = collection
+        @column = column
+        @label = label
+      end
+
+      def value
+        return @value if defined?(@value)
+
+        @value = if !@label.nil?
+                   @label
+                 elsif @collection.model.present?
+                   @collection.model.human_attribute_name(@column)
+                 else
+                   @column.to_s.humanize.capitalize
+                 end
+      end
+
+      def call
+        ActionView::OutputBuffer.new.tap do |output|
+          output << value.to_s
+        end.to_s
+      end
+
+      alias to_s call
+
+      def inspect
+        "#<#{self.class.name} column: #{@column.inspect} value: #{value.inspect}>"
+      end
+    end
+  end
+end

data/app/components/katalyst/tables/orderable/form_component.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module Tables
+    module Orderable
+      class FormComponent < ViewComponent::Base # :nodoc:
+        include Katalyst::Tables::Identifiable::Defaults
+
+        attr_reader :id, :url
+
+        # @param collection [Katalyst::Tables::Collection::Core] the collection to render
+        # @param url [String] the url to submit the form to (e.g. <resources>_order_path)
+        # @param id [String] the id of the form element (defaults to <resources>_order_form)
+        # @param scope [String] the base scope to use for form inputs (defaults to order[<resources>])
+        def initialize(collection:, url:, id: nil, scope: nil)
+          super
+
+          @id    = id || Orderable.default_form_id(collection)
+          @url   = url
+          @scope = scope || Orderable.default_scope(collection)
+        end
+
+        def call
+          form_with(id:, url:, method: :patch, data: {
+                      controller:                       FORM_CONTROLLER,
+                      "#{FORM_CONTROLLER}-scope-value": @scope,
+                    }) do |form|
+            form.button(hidden: "")
+          end
+        end
+
+        def inspect
+          "#<#{self.class.name} id: #{id.inspect}, url: #{url.inspect}>"
+        end
+      end
+    end
+  end
+end

data/app/components/katalyst/tables/selectable/form_component.html.erb

@@ -4,11 +4,11 @@
               data:   { controller:      form_controller,
                         turbo_action:    "replace",
                         turbo_permanent: "" },
-              html:   { hidden: "" }) do |form| %>
+              html:   { action: false, hidden: "" }) do |form| %>
   <p class="tables--selection--summary">
     <span data-<%= form_target("count") %>>0</span>
-    <span data-<%= form_target("singular") %> hidden><%= @table.collection.model_name.singular %></span>
-    <span data-<%= form_target("plural") %>><%= @table.collection.model_name.plural %></span>
+    <span data-<%= form_target("singular") %> hidden><%= @collection.model_name.singular %></span>
+    <span data-<%= form_target("plural") %>><%= @collection.model_name.plural %></span>
     selected
   </p>
   <%= content %>

data/app/components/katalyst/tables/selectable/form_component.rb

@@ -4,24 +4,21 @@ module Katalyst
   module Tables
     module Selectable
       class FormComponent < ViewComponent::Base # :nodoc:
+        include Katalyst::Tables::Identifiable::Defaults
+
         attr_reader :id, :primary_key
 
-        def initialize(table:,
+        # @param collection [Katalyst::Tables::Collection::Core] the collection to render
+        # @param id [String] the id of the form element (defaults to <resources>_selection_form)
+        # @param primary_key [String] the primary key of the record in the collection (defaults to :id)
+        def initialize(collection:,
                        id: nil,
                        primary_key: :id)
           super
 
-          @table       = table
-          @id          = id
+          @collection  = collection
+          @id          = id || Selectable.default_form_id(collection)
           @primary_key = primary_key
-
-          if @id.nil?
-            table_id = table.try(:id)
-
-            raise ArgumentError, "Table selection requires an id" if table_id.nil?
-
-            @id = "#{table_id}_selection"
-          end
         end
 
         def inspect

data/app/controllers/concerns/katalyst/tables/backend.rb

@@ -2,35 +2,10 @@
 
 module Katalyst
   module Tables
-    # Utilities for controllers that are generating collections for visualisation
-    # in a table view using Katalyst::Tables::Frontend.
-    #
-    # Provides `table_sort` for sorting based on column interactions (sort param).
+    # Configuration for controllers to specify which TableComponent should be used in associated views.
     module Backend
       extend ActiveSupport::Concern
 
-      # @deprecated backwards compatibility
-      class SortForm < Katalyst::Tables::Collection::SortForm
-      end
-
-      # Sort the given collection by params[:sort], which is set when a user
-      # interacts with a column header in a frontend table view.
-      #
-      # @return [[SortForm, ActiveRecord::Relation]]
-      def table_sort(collection)
-        column, direction = params[:sort]&.split
-        direction         = "asc" unless SortForm::DIRECTIONS.include?(direction)
-
-        SortForm.new(column:,
-                     direction:)
-          .apply(collection)
-      end
-
-      def self_referred?
-        request.referer.present? && URI.parse(request.referer).path == request.path
-      end
-      alias self_refered? self_referred?
-
       included do
         class_attribute :_default_table_component, instance_accessor: false
       end
@@ -39,8 +14,7 @@ module Katalyst
         # 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>component</tt> - Default table component, an instance of +Katalyst::TableComponent+
+        # @param component [Class] the table component class to use
         def default_table_component(component)
           self._default_table_component = component
         end

data/app/helpers/katalyst/tables/frontend.rb

@@ -4,9 +4,55 @@ module Katalyst
   module Tables
     # View Helper for generating HTML tables. Include in your ApplicationHelper, or similar.
     module Frontend
-      def table_with(collection:, component: nil, **, &)
+      # Construct a new table component. This entry point supports a large number
+      # of options for customizing the table. The most common options are:
+      # @param collection [Katalyst::Tables::Collection::Core] the collection to render
+      # @param header [Boolean] whether to render the header row (defaults to true, supports options)
+      # @param caption [Boolean Hash] whether to render the caption (defaults to true, supports options)
+      # @param generate_ids [Boolean] whether to generate dom ids for the table and rows
+      #
+      # Blocks will receive the table in row-rendering mode (with row and record defined):
+      # @yieldparam [Katalyst::TableComponent] the row component to render
+      # @yieldparam [Object, nil] the object to render, or nil for header rows
+      #
+      # If no block is provided when the table is rendered then the table will look for a row partial:
+      # @param object_name [Symbol] the name of the object to use for partial rendering
+      #        (defaults to collection.model_name.i18n_key)
+      # @param partial [String] the name of the partial to use for rendering each row
+      #        (defaults to to_partial_path on the object)
+      # @param as [Symbol] 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 table_with(collection:,
+                     component: nil,
+                     header: true,
+                     caption: true,
+                     generate_ids: false,
+                     object_name: nil,
+                     partial: nil,
+                     as: nil,
+                     **,
+                     &)
         component ||= default_table_component_class
-        render(component.new(collection:, **), &)
+        component = component.new(collection:, header:, caption:, generate_ids:, object_name:, partial:, as:, **)
+
+        render(component, &)
+      end
+
+      # @param collection [Katalyst::Tables::Collection::Core] the collection to render
+      # @param url [String] the url to submit the form to (e.g. <resources>_order_path)
+      # @param id [String] the id of the form element (defaults to <resources>_order_form)
+      # @param scope [String] the base scope to use for form inputs (defaults to order[<resources>])
+      def table_orderable_with(collection:, url:, id: nil, scope: nil, &)
+        render(Orderable::FormComponent.new(collection:, url:, id:, scope:))
+      end
+
+      # @param collection [Katalyst::Tables::Collection::Core] the collection to render
+      # @param id [String] the id of the form element (defaults to <resources>_selection_form)
+      # @param primary_key [String] the primary key of the record in the collection (defaults to :id)
+      def table_selection_with(collection:, id: nil, primary_key: :id, &)
+        render(Selectable::FormComponent.new(collection:, id:, primary_key:), &)
       end
 
       private

data/app/javascript/tables/application.js

@@ -1,4 +1,3 @@
-import TurboCollectionController from "./turbo/collection_controller";
 import OrderableItemController from "./orderable/item_controller";
 import OrderableListController from "./orderable/list_controller";
 import OrderableFormController from "./orderable/form_controller";
@@ -6,10 +5,6 @@ import SelectionFormController from "./selection/form_controller";
 import SelectionItemController from "./selection/item_controller";
 
 const Definitions = [
-  {
-    identifier: "tables--turbo--collection",
-    controllerConstructor: TurboCollectionController,
-  },
   {
     identifier: "tables--orderable--item",
     controllerConstructor: OrderableItemController,

data/app/javascript/tables/orderable/form_controller.js

@@ -1,13 +1,15 @@
 import { Controller } from "@hotwired/stimulus";
 
 export default class OrderableFormController extends Controller {
+  static values = { scope: String };
+
   add(item) {
-    const { id_name, id_value, index_name } = item.paramsValue;
-    this.element.insertAdjacentHTML(
-      "beforeend",
-      `<input type="hidden" name="${id_name}" value="${id_value}" data-generated>
-              <input type="hidden" name="${index_name}" value="${item.index}" data-generated>`,
-    );
+    item.params(this.scopeValue).forEach(({ name, value }) => {
+      this.element.insertAdjacentHTML(
+        "beforeend",
+        `<input type="hidden" name="${name}" value="${value}" data-generated>`,
+      );
+    });
   }
 
   submit() {

data/app/javascript/tables/orderable/item_controller.js

@@ -48,6 +48,15 @@ export default class OrderableRowController extends Controller {
     this.index = index;
   }
 
+  /** Retrieve params for use in the form */
+  params(scope) {
+    const { id_name, id_value, index_name } = this.paramsValue;
+    return [
+      { name: `${scope}[${id_value}][${id_name}]`, value: this.id },
+      { name: `${scope}[${id_value}][${index_name}]`, value: this.index },
+    ];
+  }
+
   /**
    * Restore any visual changes made during drag and remove the drag state.
    */

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

@@ -18,7 +18,7 @@ module Katalyst
           def permitted_params
             _default_attributes.to_h.each_with_object([]) do |(k, v), h|
               h << case v
-                   when Array
+                   when ::Array
                      { k => [] }
                    else
                      k
@@ -39,6 +39,11 @@ module Katalyst
           clear_changes_information
         end
 
+        # Collections that do not include Sorting are never sortable.
+        def sortable?
+          false
+        end
+
         def apply(items)
           @items = items
           reducers.build do |_|

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

@@ -14,27 +14,88 @@ module Katalyst
       module Sorting
         extend ActiveSupport::Concern
 
-        included do
-          config_accessor :sorting
-          attr_accessor :sorting
+        DIRECTIONS = %w[asc desc].freeze
+
+        module SortParams
+          refine Hash do
+            def to_param
+              "#{self[:column]} #{self[:direction]}"
+            end
+          end
+
+          refine String do
+            def to_param
+              to_h.to_param
+            end
 
+            def to_h
+              column, direction = split(/[ +]/, 2)
+
+              direction = "asc" unless DIRECTIONS.include?(direction)
+              { column:, direction: }
+            end
+          end
+        end
+
+        using SortParams
+
+        included do
           attribute :sort, :string
+
+          attr_reader :default_sort
         end
 
         def initialize(sorting: config.sorting, **options)
-          @sorting = SortForm.parse(sorting, default: sorting) if sorting
+          @default_sort = sorting.to_param if sorting.present?
+
+          super(sort: @default_sort, **options) # set default sort based on config
+        end
 
-          super(sort: @sorting.to_param, **options) # set default sort based on config
+        def default_sort?
+          sort == @default_sort
         end
 
+        # Returns true if the collection supports sorting on the given column.
+        # A column supports sorting if it is a database column or if
+        # the collection responds to `order_by_#{column}(direction)`.
+        #
+        # @param column [String, Symbol]
+        # @return [true, false]
+        def sortable?(column = nil)
+          if column.nil?
+            @default_sort.present?
+          else
+            items.respond_to?(:"order_by_#{column}") || items.model.has_attribute?(column.to_s)
+          end
+        end
+
+        # Set the current sort behaviour of the collection.
+        #
+        # @param value [String, Hash] "column direction", or { column:, direction: }
         def sort=(value)
-          return unless @sorting
+          super(value.to_param) if @default_sort
+        end
+
+        # Returns the current sort behaviour of the given column, for use as a
+        # column heading class in the table view.
+        #
+        # @param column [String, Symbol] the table column as defined in table_with
+        # @return [String] the current sort behaviour of the given column
+        def sort_status(column)
+          current, direction = sort.to_h.values_at(:column, :direction)
+          direction if column.to_s == current
+        end
 
-          # update internal proxy
-          @sorting = SortForm.parse(value, default: @sorting.default)
+        # Calculates the sort parameter to apply when the given column is toggled.
+        #
+        # @param column [String, Symbol]
+        # @return [String]
+        def toggle_sort(column)
+          current, direction = sort.to_h.values_at(:column, :direction)
 
-          # update attribute based on normalized value
-          super(@sorting.to_param)
+          return "#{column} asc" unless column.to_s == current
+
+          direction == "asc" ? "#{column} desc" : "#{column} asc"
         end
 
         class Sort # :nodoc:
@@ -44,15 +105,22 @@ module Katalyst
             @app = app
           end
 
+          using SortParams
+
           def call(collection)
-            @collection                            = @app.call(collection)
-            @collection.sorting, @collection.items = @collection.sorting.apply(@collection.items) if @collection.sorting
-            @collection
-          end
+            collection = @app.call(collection)
+
+            column, direction = collection.sort.to_h.values_at(:column, :direction)
+
+            return collection if column.nil?
+
+            if collection.items.respond_to?(:"order_by_#{column}")
+              collection.items = collection.items.reorder(nil).public_send(:"order_by_#{column}", direction.to_sym)
+            elsif collection.items.model.has_attribute?(column)
+              collection.items = collection.items.reorder(column => direction)
+            end
 
-          # pagy shim
-          def params
-            @collection.attributes
+            collection
           end
         end
       end