katalyst-tables 3.0.0.beta1 → 3.0.0

data/app/components/katalyst/table_component.rb

@@ -4,103 +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)
-    # - `generate_ids`: whether to generate ids for each row (defaults to true)
-    # - `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: true,
-                   generate_ids: true,
-                   **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
+                   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
 
-      @generate_ids = generate_ids
+      @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 id
-      html_attributes[:id]
+    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.present?
+    def inspect
+      "#<#{self.class.name} collection: #{collection.inspect}>"
     end
 
-    def caption
-      caption_component&.new(self)
+    delegate :header?, :body?, to: :@current_row
+
+    def row
+      @current_row
     end
 
-    def header?
-      @header.present?
+    def record
+      @current_record
     end
 
-    def header_row
-      header_row_component.new(self, **@header_options)
+    # 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 body_row(record)
-      body_row_component.new(self, record)
+    # 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
 
-    def sorting
-      return @sorting if @sorting.present?
+    # 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
 
-      collection.sorting if collection.respond_to?(:sorting)
+    # 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
 
-    def generate_ids?
-      @generate_ids.present?
+    # 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
 
-    def inspect
-      "#<#{self.class.name} collection: #{collection.inspect}>"
+    # 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
 
-    define_html_attribute_methods(:thead_attributes)
-    define_html_attribute_methods(:tbody_attributes)
+    # 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
 
-    # Backwards compatibility with tables 1.0
-    alias_method :options, :html_attributes=
+    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

@@ -4,29 +4,11 @@ module Katalyst
   module Tables
     class BodyRowComponent < ViewComponent::Base # :nodoc:
       include Katalyst::HtmlAttributes
-      include Body::TypedColumns
 
-      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,18 +19,9 @@ module Katalyst
         true
       end
 
-      def default_html_attributes
-        return {} unless @table.generate_ids?
-
-        { id: dom_id(@record) }
-      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

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

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Katalyst
+  module Tables
+    class CellComponent < ViewComponent::Base # :nodoc:
+      include Katalyst::HtmlAttributes
+
+      attr_reader :collection, :row, :column, :record
+
+      def initialize(collection:, row:, column:, record:, label:, heading:, **)
+        super(**)
+
+        @collection = collection
+        @row = row
+        @column = column
+        @record = record
+        @heading = heading
+
+        if @row.header?
+          @label = Label.new(collection:, column:, label:)
+        else
+          @data = Data.new(record:, column:)
+        end
+      end
+
+      # @return true if the cell is a heading cell (th).
+      def heading?
+        @row.header? || @heading
+      end
+
+      # Adds a component to wrap the content of the cell, similar to a layout in Rails views.
+      def with_content_wrapper(component)
+        @content_wrapper = component
+
+        self
+      end
+
+      def call
+        content = if content?
+                    self.content
+                  elsif @row.header?
+                    label
+                  else
+                    rendered_value
+                  end
+
+        content = @content_wrapper.with_content(content).render_in(view_context) if @content_wrapper
+
+        concat(content_tag(cell_tag, content, **html_attributes))
+      end
+
+      # Return the rendered and sanitized label for the column.
+      def label
+        @label&.to_s
+      end
+
+      # Return the raw value of the cell (i.e. the value of the data read from the record)
+      def value
+        @data&.value
+      end
+
+      # Return the serialized and sanitised data value for rendering in the cell.
+      def rendered_value
+        @data&.to_s
+      end
+
+      # Serialize data for use in blocks, i.e.
+      #   row.text(:name) { |cell| tag.span(cell) }
+      def to_s
+        # Note, this can't be `content` because the block is evaluated in order to produce content.
+        rendered_value
+      end
+
+      def inspect
+        "#<#{self.class.name} method: #{@method.inspect}>"
+      end
+
+      private
+
+      def cell_tag
+        heading? ? :th : :td
+      end
+    end
+  end
+end

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

@@ -2,12 +2,18 @@
 
 module Katalyst
   module Tables
-    module Body
+    module Cells
       # Shows Yes/No for boolean values
-      class BooleanComponent < BodyCellComponent
+      class BooleanComponent < CellComponent
         def rendered_value
           value ? "Yes" : "No"
         end
+
+        private
+
+        def default_html_attributes
+          { class: "type-boolean" }
+        end
       end
     end
   end

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

@@ -1,17 +1,15 @@
 # frozen_string_literal: true
 
-using Katalyst::HtmlAttributes::HasHtmlAttributes
-
 module Katalyst
   module Tables
-    module Body
+    module Cells
       # Formats the value as a money value
       #
       # The value is expected to be in cents.
       # Adds a class to the cell to allow for custom styling
-      class CurrencyComponent < BodyCellComponent
-        def initialize(table, record, attribute, options: {}, **html_attributes)
-          super(table, record, attribute, **html_attributes)
+      class CurrencyComponent < CellComponent
+        def initialize(options:, **)
+          super(**)
 
           @options = options
         end
@@ -20,8 +18,10 @@ module Katalyst
           value.present? ? number_to_currency(value / 100.0, @options) : ""
         end
 
+        private
+
         def default_html_attributes
-          super.merge_html(class: "type-currency")
+          { class: "type-currency" }
         end
       end
     end

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

@@ -2,13 +2,13 @@
 
 module Katalyst
   module Tables
-    module Body
+    module Cells
       # Formats the value as a date
-      # @param format [String] date format, defaults to :table
+      # @param format [String] date format
       # @param relative [Boolean] if true, the date may be(if within 5 days) shown as a relative date
-      class DateComponent < BodyCellComponent
-        def initialize(table, record, attribute, format: :table, relative: true, **options)
-          super(table, record, attribute, **options)
+      class DateComponent < CellComponent
+        def initialize(format:, relative:, **)
+          super(**)
 
           @format   = format
           @relative = relative
@@ -24,6 +24,13 @@ module Katalyst
 
         private
 
+        def default_html_attributes
+          {
+            class: "type-date",
+            title: (absolute_time if row.body? && @relative && value.present? && days_ago_in_words(value).present?),
+          }
+        end
+
         def absolute_time
           value.present? ? I18n.l(value, format: @format) : ""
         end
@@ -36,10 +43,6 @@ module Katalyst
           end
         end
 
-        def default_html_attributes
-          @relative && value.present? && days_ago_in_words(value).present? ? { title: absolute_time } : {}
-        end
-
         def days_ago_in_words(value)
           from_time        = value.to_time
           to_time          = Date.current.to_time

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

@@ -2,17 +2,17 @@
 
 module Katalyst
   module Tables
-    module Body
+    module Cells
       # Formats the value as a datetime
-      # @param format [String] datetime format, defaults to :admin
+      # @param format [String] datetime format
       # @param relative [Boolean] if true, the datetime may be(if today) shown as a relative date/time
-      class DateTimeComponent < BodyCellComponent
+      class DateTimeComponent < CellComponent
         include ActionView::Helpers::DateHelper
 
-        def initialize(table, record, attribute, format: :table, relative: true, **options)
-          super(table, record, attribute, **options)
+        def initialize(format:, relative:, **)
+          super(**)
 
-          @format   = format
+          @format = format
           @relative = relative
         end
 
@@ -26,6 +26,13 @@ module Katalyst
 
         private
 
+        def default_html_attributes
+          {
+            class: "type-datetime",
+            title: (absolute_time if row.body? && @relative && today?),
+          }
+        end
+
         def absolute_time
           value.present? ? I18n.l(value, format: @format) : ""
         end
@@ -47,10 +54,6 @@ module Katalyst
             absolute_time
           end
         end
-
-        def default_html_attributes
-          @relative && today? ? { title: absolute_time } : {}
-        end
       end
     end
   end