katalyst-tables 2.6.0 → 3.0.0

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

@@ -10,82 +10,26 @@ module Katalyst
       FORM_CONTROLLER = "tables--selection--form"
       ITEM_CONTROLLER = "tables--selection--item"
 
-      using Katalyst::HtmlAttributes::HasHtmlAttributes
-
-      # Support for inclusion in a table component class
-      # Adds an `selectable` slot and component configuration
-      included do
-        # Add `selectable` slot to table component
-        config_component :selection, default: "Katalyst::Tables::Selectable::FormComponent"
-        renders_one(:selection, lambda do |**attrs|
-          selection_component.new(table: self, **attrs)
-        end)
-      end
-
-      # Support for extending a table component instance
-      # Adds methods to the table component instance
-      def self.extended(table)
-        table.extend(TableMethods)
-
-        # ensure row components support selectable column calls
-        table.send(:add_selectable_columns)
-      end
-
-      def initialize(**attributes)
-        super
-
-        # ensure row components support selectable column calls
-        add_selectable_columns
-      end
-
-      private
-
-      # Add `selectable` columns to row components
-      def add_selectable_columns
-        header_row_component.include(HeaderRow)
-        body_row_component.include(BodyRow)
-      end
-
-      # Methods required to emulate a slot when extending an existing table.
-      module TableMethods
-        def with_selection(**attrs)
-          @selection = FormComponent.new(table: self, **attrs)
-
-          self
-        end
-
-        def selectable?
-          @selection.present?
-        end
-
-        def selection
-          @selection ||= FormComponent.new(table: self)
-        end
-      end
-
-      module HeaderRow # :nodoc:
-        def selection
-          cell(:_selection, class: "selection", label: "")
-        end
+      # Returns the default dom id for the selection form, uses the table's
+      # default id with '_selection' appended.
+      def self.default_form_id(collection)
+        "#{Identifiable::Defaults.default_table_id(collection)}_selection_form"
       end
 
-      module BodyRow # :nodoc:
-        def selection
-          id     = @record.public_send(@table.selection.primary_key)
-          params = {
-            id:,
-          }
-          cell(:_selection,
-               class: "selection",
-               data:  {
-                 controller:                                    ITEM_CONTROLLER,
-                 "#{ITEM_CONTROLLER}-params-value"              => params.to_json,
-                 "#{ITEM_CONTROLLER}-#{FORM_CONTROLLER}-outlet" => "##{@table.selection.id}",
-                 action:                                        "change->#{ITEM_CONTROLLER}#change",
-               }) do
-            tag.input(type: :checkbox)
-          end
-        end
+      # Adds the selection column to the table
+      #
+      # @param params [Hash] params to pass to the controller for selected rows
+      # @param form_id [String] id of the form element that will submit the selected row params
+      # @param ** [Hash] HTML attributes to be added to column cells
+      # @param & [Proc] optional block to alter the cell content
+      # @return [void]
+      #
+      # @example Render a select column
+      #   <% row.select %> # => <td><input type="checkbox" ...></td>
+      def select(params: { id: record&.id }, form_id: Selectable.default_form_id(collection), **, &)
+        with_cell(Cells::SelectComponent.new(
+                    collection:, row:, column: :_select, record:, label: "", heading: false, params:, form_id:, **,
+                  ), &)
       end
     end
   end

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

@@ -7,25 +7,59 @@ module Katalyst
     module Sortable
       extend ActiveSupport::Concern
 
-      # Returns true when the given attribute is sortable.
-      def sortable?(attribute)
-        sorting&.supports?(collection, attribute)
+      def initialize(**)
+        super(**)
+
+        @header_row_cell_callbacks << method(:add_sorting_to_cell) if collection.sortable?
+      end
+
+      private
+
+      def add_sorting_to_cell(cell)
+        if collection.sortable?(cell.column)
+          cell.update_html_attributes(data: { sort: collection.sort_status(cell.column) })
+          cell.with_content_wrapper(SortableHeaderComponent.new(collection:, cell:))
+        end
       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}"
+      class SortableHeaderComponent < ViewComponent::Base
+        include Katalyst::HtmlAttributes
+
+        attr_reader :collection, :cell
+
+        delegate :column, to: :cell
+
+        def initialize(collection:, cell:, **)
+          super(**)
+
+          @collection = collection
+          @cell = cell
+        end
+
+        def call
+          link_to(content, sort_url, **html_attributes)
+        end
+
+        # Generates a url for applying/toggling sort for the given column.
+        def sort_url
+          # 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 = column && collection.toggle_sort(column)
+          params = if sort && !sort.eql?(collection.default_sort)
+                     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
+
+        def default_html_attributes
+          { data: { turbo_action: "replace" } }
+        end
       end
     end
   end

data/app/components/katalyst/table_component.html.erb

@@ -1,13 +1,13 @@
 <%= tag.table(**html_attributes) do %>
   <%= render caption if caption? %>
-  <% if header? %>
+  <% if header_row? %>
     <%= tag.thead(**thead_attributes) do %>
-      <%= header_row.render_in(view_context, &row_proc) %>
+      <%= header_row %>
     <% end %>
   <% end %>
   <%= tag.tbody(**tbody_attributes) do %>
-    <% collection.each do |record| %>
-      <%= body_row(record).render_in(view_context) { |r| row_proc.call(r, record) } %>
+    <% body_rows.each do |body_row| %>
+      <%= body_row %>
     <% end %>
   <% end %>
 <% end %>

data/app/components/katalyst/table_component.rb

@@ -4,91 +4,321 @@ 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| %>
+  #   <%= row.text :name do |cell| %>
   #     <%= link_to cell.value, person %>
   #   <% end %>
-  #   <%= row.cell :email %>
+  #   <%= row.text :email %>
   # <% end %>
   # ```
   class TableComponent < ViewComponent::Base
     include Katalyst::HtmlAttributes
-    include Tables::ConfigurableComponent
     include Tables::HasTableContent
 
+    # Load table extensions. This allows users to disable specific extensions
+    # if they want to implement alternatives, e.g. a different sorting UI.
+    Katalyst::Tables.config.component_extensions.each do |extension|
+      include extension.constantize
+    end
+
     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"
+    renders_one :caption, Katalyst::Tables::EmptyCaptionComponent
+    renders_one :header_row, Katalyst::Tables::HeaderRowComponent
+    renders_many :body_rows, Katalyst::Tables::BodyRowComponent
+
+    define_html_attribute_methods(:thead_attributes)
+    define_html_attribute_methods(:tbody_attributes)
 
     # 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 to_partial_path on the object)
-    # - `as`: the name of the local variable to use for rendering each row (defaults to collection.model_name.param_key)
+    # @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
+    #
+    # 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 initialize(collection:,
-                   sorting: nil,
                    header: true,
-                   caption: false,
-                   **html_attributes)
-      @collection = collection
-
-      # sorting: instance of Katalyst::Tables::Collection::SortForm.
-      # If not provided will be inferred from the collection.
-      @sorting = sorting || html_attributes.delete(:sort) # backwards compatibility with old `sort` option
+                   caption: true,
+                   generate_ids: false,
+                   object_name: nil,
+                   partial: nil,
+                   as: nil,
+                   **)
+      @collection = normalize_collection(collection)
 
       # 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)) || {}
+      @header_options = header
 
       # 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)) || {}
+      @caption_options = caption
+
+      @header_row_callbacks = []
+      @body_row_callbacks = []
+      @header_row_cell_callbacks = []
+      @body_row_cell_callbacks = []
 
-      super(**html_attributes)
+      super(generate_ids:, object_name:, partial:, as:, **)
     end
 
-    def caption?
-      @caption.present?
+    def before_render
+      super
+
+      if @caption_options
+        options = (@caption_options.is_a?(Hash) ? @caption_options : {})
+        with_caption(self, **options)
+      end
+
+      if @header_options
+        options = @header_options.is_a?(Hash) ? @header_options : {}
+        with_header_row(**options) do |row|
+          @header_row_callbacks.each { |callback| callback.call(row, record) }
+          row_content(row, nil)
+        end
+      end
+
+      collection.each do |record|
+        with_body_row do |row|
+          @body_row_callbacks.each { |callback| callback.call(row, record) }
+          row_content(row, record)
+        end
+      end
     end
 
-    def caption
-      caption_component&.new(self)
+    def inspect
+      "#<#{self.class.name} collection: #{collection.inspect}>"
     end
 
-    def header?
-      @header.present?
+    delegate :header?, :body?, to: :@current_row
+
+    def row
+      @current_row
     end
 
-    def header_row
-      header_row_component.new(self, **@header_options)
+    def record
+      @current_record
     end
 
-    def body_row(record)
-      body_row_component.new(self, record)
+    # When rendering a row we pass the table to the row instead of the row itself. This lets the table define the
+    # column entry points so it's easy to define column extensions in subclasses. When a user wants to set html
+    # attributes on the row, they will call `row.html_attributes = { ... }`, so we need to proxy that call to the
+    # current row (if set).
+    def html_attributes=(attributes)
+      if row.present?
+        row.html_attributes = attributes
+      else
+        @html_attributes = HtmlAttributes.options_to_html_attributes(attributes)
+      end
     end
 
-    def sorting
-      return @sorting if @sorting.present?
+    # Generates a column from values rendered as text.
+    #
+    # @param column [Symbol] the column's name, called as a method on the record
+    # @param label [String|nil] the label to use for the column header
+    # @param heading [boolean] if true, data cells will use `th` tags
+    # @param ** [Hash] HTML attributes to be added to column cells
+    # @param & [Proc] optional block to wrap the cell content
+    #
+    # If a block is provided, it will be called with the cell component as an argument.
+    # @yieldparam cell [Katalyst::Tables::CellComponent] the cell component
+    #
+    # @return [void]
+    #
+    # @example Render a generic text column for any value that supports `to_s`
+    #   <% row.text :name %> # label => <th>Name</th>, data => <td>John Doe</td>
+    def text(column, label: nil, heading: false, **, &)
+      with_cell(Tables::CellComponent.new(
+                  collection:, row:, column:, record:, label:, heading:, **,
+                ), &)
+    end
+    alias cell text
 
-      collection.sorting if collection.respond_to?(:sorting)
+    # Generates a column from boolean values rendered as "Yes" or "No".
+    #
+    # @param column [Symbol] the column's name, called as a method on the record
+    # @param label [String|nil] the label to use for the column header
+    # @param heading [boolean] if true, data cells will use `th` tags
+    # @param ** [Hash] HTML attributes to be added to column cells
+    # @param & [Proc] optional block to alter the cell content
+    #
+    # If a block is provided, it will be called with the boolean cell component as an argument.
+    # @yieldparam cell [Katalyst::Tables::Cells::BooleanComponent] the cell component
+    #
+    # @return [void]
+    #
+    # @example Render a boolean column indicating whether the record is active
+    #   <% row.boolean :active %> # => <td>Yes</td>
+    def boolean(column, label: nil, heading: false, **, &)
+      with_cell(Tables::Cells::BooleanComponent.new(
+                  collection:, row:, column:, record:, label:, heading:, **,
+                ), &)
     end
 
-    def inspect
-      "#<#{self.class.name} collection: #{collection.inspect}>"
+    # Generates a column from date values rendered using I18n.l.
+    # The default format is :default, can be configured or overridden.
+    #
+    # @param column [Symbol] the column's name, called as a method on the record
+    # @param label [String|nil] the label to use for the column header
+    # @param heading [boolean] if true, data cells will use `th` tags
+    # @param format [Symbol] the I18n date format to use when rendering
+    # @param relative [Boolean] if true, the date may be shown as a relative date (if within 5 days)
+    # @param ** [Hash] HTML attributes to be added to column cells
+    #
+    # If a block is provided, it will be called with the date cell component as an argument.
+    # @yieldparam cell [Katalyst::Tables::Cells::DateComponent] the cell component
+    #
+    # @return [void]
+    #
+    # @example Render a date column describing when the record was created
+    #   <% row.date :created_at %> # => <td>29 Feb 2024</td>
+    def date(column, label: nil, heading: false, format: Tables.config.date_format, relative: true, **, &)
+      with_cell(Tables::Cells::DateComponent.new(
+                  collection:, row:, column:, record:, label:, heading:, format:, relative:, **,
+                ), &)
     end
 
-    define_html_attribute_methods(:thead_attributes)
-    define_html_attribute_methods(:tbody_attributes)
+    # Generates a column from datetime values rendered using I18n.l.
+    # The default format is :default, can be configured or overridden.
+    #
+    # @param column [Symbol] the column's name, called as a method on the record
+    # @param label [String|nil] the label to use for the column header
+    # @param heading [boolean] if true, data cells will use `th` tags
+    # @param format [Symbol] the I18n datetime format to use when rendering
+    # @param relative [Boolean] if true, the datetime may be(if today) shown as a relative date/time
+    # @param ** [Hash] HTML attributes to be added to column cells
+    # @param & [Proc] optional block to alter the cell content
+    #
+    # If a block is provided, it will be called with the date time cell component as an argument.
+    # @yieldparam cell [Katalyst::Tables::Cells::DateTimeComponent] the cell component
+    #
+    # @return [void]
+    #
+    # @example Render a datetime column describing when the record was created
+    #   <% row.datetime :created_at %> # => <td>29 Feb 2024, 5:00pm</td>
+    def datetime(column, label: nil, heading: false, format: Tables.config.datetime_format, relative: true, **, &)
+      with_cell(Tables::Cells::DateTimeComponent.new(
+                  collection:, row:, column:, record:, label:, heading:, format:, relative:, **,
+                ), &)
+    end
 
-    # Backwards compatibility with tables 1.0
-    alias_method :options, :html_attributes=
+    # Generates a column from numeric values formatted appropriately.
+    #
+    # @param column [Symbol] the column's name, called as a method on the record
+    # @param label [String|nil] the label to use for the column header
+    # @param heading [boolean] if true, data cells will use `th` tags
+    # @param ** [Hash] HTML attributes to be added to column cells
+    # @param & [Proc] optional block to alter the cell content
+    #
+    # If a block is provided, it will be called with the number cell component as an argument.
+    # @yieldparam cell [Katalyst::Tables::Cells::NumberComponent] the cell component
+    #
+    # @return [void]
+    #
+    # @example Render the number of comments on a post
+    #   <% row.number :comment_count %> # => <td>0</td>
+    def number(column, label: nil, heading: false, **, &)
+      with_cell(Tables::Cells::NumberComponent.new(
+                  collection:, row:, column:, record:, label:, heading:, **,
+                ), &)
+    end
+
+    # Generates a column from numeric values rendered using `number_to_currency`.
+    #
+    # @param column [Symbol] the column's name, called as a method on the record
+    # @param label [String|nil] the label to use for the column header
+    # @param heading [boolean] if true, data cells will use `th` tags
+    # @param options [Hash] options to be passed to `number_to_currency`
+    # @param ** [Hash] HTML attributes to be added to column cells
+    # @param & [Proc] optional block to alter the cell content
+    #
+    # If a block is provided, it will be called with the currency cell component as an argument.
+    # @yieldparam cell [Katalyst::Tables::Cells::CurrencyComponent] the cell component
+    #
+    # @return [void]
+    #
+    # @example Render a currency column for the price of a product
+    #   <% row.currency :price %> # => <td>$3.50</td>
+    def currency(column, label: nil, heading: false, options: {}, **, &)
+      with_cell(Tables::Cells::CurrencyComponent.new(
+                  collection:, row:, column:, record:, label:, heading:, options:, **,
+                ), &)
+    end
+
+    # Generates a column containing HTML markup.
+    #
+    # @param column [Symbol] the column's name, called as a method on the record
+    # @param label [String|nil] the label to use for the column header
+    # @param heading [boolean] if true, data cells will use `th` tags
+    # @param ** [Hash] HTML attributes to be added to column cells
+    # @param & [Proc] optional block to alter the cell content
+    #
+    # If a block is provided, it will be called with the rich text cell component as an argument.
+    # @yieldparam cell [Katalyst::Tables::Cells::RichTextComponent] the cell component
+    #
+    # @return [void]
+    #
+    # @note This method assumes that the method returns HTML-safe content.
+    #   If the content is not HTML-safe, it will be escaped.
+    #
+    # @example Render a description column containing HTML markup
+    #   <% row.rich_text :description %> # => <td><em>Emphasis</em></td>
+    def rich_text(column, label: nil, heading: false, options: {}, **, &)
+      with_cell(Tables::Cells::RichTextComponent.new(
+                  collection:, row:, column:, record:, label:, heading:, options:, **,
+                ), &)
+    end
+
+    private
+
+    # Extension point for subclasses and extensions to customize header row rendering.
+    def add_header_row_callback(&block)
+      @header_row_callbacks << block
+    end
+
+    # Extension point for subclasses and extensions to customize body row rendering.
+    def add_body_row_callback(&block)
+      @body_row_callbacks << block
+    end
+
+    # Extension point for subclasses and extensions to customize header row cell rendering.
+    def add_header_row_cell_callback(&block)
+      @header_row_cell_callbacks << block
+    end
+
+    # Extension point for subclasses and extensions to customize body row cell rendering.
+    def add_body_row_cell_callback(&block)
+      @body_row_cell_callbacks << block
+    end
+
+    # @internal proxy calls to row.with_cell and apply callbacks
+    def with_cell(cell, &)
+      if row.header?
+        @header_row_cell_callbacks.each { |callback| callback.call(cell) }
+        # note, block is silently dropped, it's not used for headers
+        @current_row.with_cell(cell)
+      else
+        @body_row_cell_callbacks.each { |callback| callback.call(cell) }
+        @current_row.with_cell(cell, &)
+      end
+    end
+
+    def normalize_collection(collection)
+      case collection
+      when Array
+        Tables::Collection::Array.new.apply(collection)
+      when ActiveRecord::Relation
+        Tables::Collection::Base.new.apply(collection)
+      else
+        collection
+      end
+    end
   end
 end

data/app/components/katalyst/tables/body_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/body_row_component.rb

@@ -5,27 +5,10 @@ module Katalyst
     class BodyRowComponent < ViewComponent::Base # :nodoc:
       include Katalyst::HtmlAttributes
 
-      renders_many :columns, ->(component) { component }
+      renders_many :cells, ->(cell) { cell }
 
-      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, **, &)
-        with_column(@table.body_cell_component.new(@table, @record, attribute, **), &)
+      def before_render
+        content # ensure content is rendered so html_attributes can be set
       end
 
       def header?
@@ -37,11 +20,8 @@ module Katalyst
       end
 
       def inspect
-        "#<#{self.class.name} record: #{record.inspect}>"
+        "#<#{self.class.name}>"
       end
-
-      # Backwards compatibility with tables 1.0
-      alias_method :options, :html_attributes=
     end
   end
 end