katalyst-koi 4.5.0.beta.2 → 4.5.0

data/app/components/koi/tables/body.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+using Katalyst::HtmlAttributes::HasHtmlAttributes
+
 module Koi
   module Tables
     module Body
@@ -11,47 +13,117 @@ module Koi
       end
 
       # Formats the value as a date
-      # default format is :admin
+      # @param format [String] date format, defaults to :admin
+      # @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: :admin, **options)
+        include Koi::DateHelper
+
+        def initialize(table, record, attribute, format: :admin, relative: true, **options)
           super(table, record, attribute, **options)
 
-          @format = format
+          @format   = format
+          @relative = relative
+        end
+
+        def value
+          super&.to_date
         end
 
         def rendered_value
-          value.present? ? l(value.to_date, format: @format) : ""
+          @relative ? relative_time : absolute_time
+        end
+
+        private
+
+        def absolute_time
+          value.present? ? I18n.l(value, format: @format) : ""
+        end
+
+        def relative_time
+          if value.blank?
+            ""
+          else
+            days_ago_in_words(value)&.capitalize || absolute_time
+          end
+        end
+
+        def default_html_attributes
+          @relative && value.present? && days_ago_in_words(value).present? ? { title: absolute_time } : {}
         end
       end
 
       # Formats the value as a datetime
-      # default format is :admin
+      # @param format [String] datetime format, defaults to :admin
+      # @param relative [Boolean] if true, the datetime may be(if today) shown as a relative date/time
       class DatetimeComponent < BodyCellComponent
-        def initialize(table, record, attribute, format: :admin, **options)
+        include ActionView::Helpers::DateHelper
+
+        def initialize(table, record, attribute, format: :admin, relative: true, **options)
           super(table, record, attribute, **options)
 
-          @format = format
+          @format   = format
+          @relative = relative
+        end
+
+        def value
+          super&.to_datetime
         end
 
         def rendered_value
-          value.present? ? l(value.to_datetime, format: @format) : ""
+          @relative ? relative_time : absolute_time
+        end
+
+        private
+
+        def absolute_time
+          value.present? ? I18n.l(value, format: @format) : ""
+        end
+
+        def today?
+          value.to_date == Date.current
+        end
+
+        def relative_time
+          return "" if value.blank?
+
+          if today?
+            if value > DateTime.current
+              "#{distance_of_time_in_words(value, DateTime.current)} from now".capitalize
+            else
+              "#{distance_of_time_in_words(value, DateTime.current)} ago".capitalize
+            end
+          else
+            absolute_time
+          end
+        end
+
+        def default_html_attributes
+          @relative && today? ? { title: absolute_time } : {}
         end
       end
 
       # Formats the value as a money value
-      # The value is expected to be in cents
+      #
+      # The value is expected to be in cents.
       # Adds a class to the cell to allow for custom styling
-      class MoneyComponent < BodyCellComponent
+      class CurrencyComponent < BodyCellComponent
+        def initialize(table, record, attribute, options: {}, **html_attributes)
+          super(table, record, attribute, **html_attributes)
+
+          @options = options
+        end
+
         def rendered_value
-          value.present? ? number_to_currency(value / 100.0) : ""
+          value.present? ? number_to_currency(value / 100.0, @options) : ""
         end
 
         def default_html_attributes
-          { class: "number" }
+          super.merge_html(class: "type-currency")
         end
       end
 
       # Formats the value as a number
+      #
       # Adds a class to the cell to allow for custom styling
       class NumberComponent < BodyCellComponent
         def rendered_value
@@ -59,11 +131,12 @@ module Koi
         end
 
         def default_html_attributes
-          { class: "number" }
+          super.merge_html(class: "type-number")
         end
       end
 
       # 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
         def default_html_attributes
@@ -73,33 +146,43 @@ module Koi
 
       # Displays a link to the record
       # The link text is the value of the attribute
-      # @param url [Proc] a proc that takes the record and returns the url, defaults to [:admin, record]
+      # @see Koi::Tables::BodyRowComponent#link
       class LinkComponent < BodyCellComponent
-        def initialize(table, record, attribute, url: ->(object) { [:admin, object] }, **attributes)
-          super(table, record, attribute, **attributes)
+        def initialize(table, record, attribute, url:, link: {}, **options)
+          super(table, record, attribute, **options)
 
-          @url_builder = url
+          @url = url
+          @link_options = link
         end
 
         def call
           content # ensure content is set before rendering options
 
-          link = content.present? && url.present? ? link_to(content, url) : content.to_s
+          link = content.present? && url.present? ? link_to(content, url, @link_options) : content.to_s
           content_tag(@type, link, **html_attributes)
         end
 
         def url
-          @url ||= if @url_builder.is_a?(Symbol)
-                     helpers.public_send(@url_builder, record)
-                   else
-                     @url_builder.call(record)
-                   end
+          case @url
+          when Symbol
+            # helpers are not available until the component is rendered
+            @url = helpers.public_send(@url, record)
+          when Proc
+            @url = @url.call(record)
+          else
+            @url
+          end
         end
       end
 
-      # Shows a thumbnail image
-      # The value is expected to be an ActiveStorage attachment with a default variant named :thumb
-      class ImageComponent < BodyCellComponent
+      # Shows an attachment
+      #
+      # The value is expected to be an ActiveStorage attachment
+      #
+      # If it is representable, shows as a image tag using a default variant named :thumb.
+      #
+      # Otherwise shows as a link to download.
+      class AttachmentComponent < BodyCellComponent
         def initialize(table, record, attribute, variant: :thumb, **options)
           super(table, record, attribute, **options)
 
@@ -107,7 +190,13 @@ module Koi
         end
 
         def rendered_value
-          value.present? ? image_tag(value.variant(@variant)) : ""
+          if value.try(:representable?)
+            image_tag(@variant.nil? ? value : value.variant(@variant))
+          elsif value.try(:attached?)
+            link_to value.blob.filename, rails_blob_path(value, disposition: :attachment)
+          else
+            ""
+          end
         end
       end
     end

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

@@ -4,40 +4,138 @@ module Koi
   module Tables
     # Custom body row component, in order to override the default body cell component
     class BodyRowComponent < Katalyst::Tables::BodyRowComponent
-      def boolean(attribute, **options, &block)
-        with_column(Body::BooleanComponent.new(@table, @record, attribute, **options), &block)
+      # Generates a column from boolean values rendered as "Yes" or "No".
+      #
+      # @param method [Symbol] the method to call on the record
+      # @param attributes [Hash] HTML attributes to be added to the cell
+      # @param block [Proc] optional block to alter the cell content
+      # @return [void]
+      #
+      # @example Render a boolean column indicating whether the record is active
+      #   <% row.boolean :active %> # => <td>Yes</td>
+      def boolean(method, **attributes, &block)
+        with_column(Body::BooleanComponent.new(@table, @record, method, **attributes), &block)
       end
 
-      def date(attribute, format: :admin, **options, &block)
-        with_column(Body::DateComponent.new(@table, @record, attribute, format:, **options), &block)
+      # Generates a column from date values rendered using I18n.l.
+      # The default format is :admin, but it can be overridden.
+      #
+      # @param method [Symbol] the method to call on the record
+      # @param format [Symbol] the I18n date format to use when rendering
+      # @param attributes [Hash] HTML attributes to be added to the cell tag
+      # @param block [Proc] optional block to alter the cell content
+      # @return [void]
+      #
+      # @example Render a date column describing when the record was created
+      #   <% row.date :created_at %> # => <td>29 Feb 2024</td>
+      def date(method, format: :admin, **attributes, &block)
+        with_column(Body::DateComponent.new(@table, @record, method, format:, **attributes), &block)
       end
 
-      def datetime(attribute, format: :admin, **options, &block)
-        with_column(Body::DatetimeComponent.new(@table, @record, attribute, format:, **options), &block)
+      # Generates a column from datetime values rendered using I18n.l.
+      # The default format is :admin, but it can be overridden.
+      #
+      # @param method [Symbol] the method to call on the record
+      # @param format [Symbol] the I18n datetime format to use when rendering
+      # @param attributes [Hash] HTML attributes to be added to the cell tag
+      # @param block [Proc] optional block to alter the cell content
+      # @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(method, format: :admin, **attributes, &block)
+        with_column(Body::DatetimeComponent.new(@table, @record, method, format:, **attributes), &block)
       end
 
-      def number(attribute, **options, &block)
-        with_column(Body::NumberComponent.new(@table, @record, attribute, **options), &block)
+      # Generates a column from numeric values formatted appropriately.
+      #
+      # @param method [Symbol] the method to call on the record
+      # @param attributes [Hash] HTML attributes to be added to the cell tag
+      # @param block [Proc] optional block to alter the cell content
+      # @return [void]
+      #
+      # @example Render the number of comments on a post
+      #   <% row.number :comment_count %> # => <td>0</td>
+      def number(method, **attributes, &block)
+        with_column(Body::NumberComponent.new(@table, @record, method, **attributes), &block)
       end
 
-      def money(attribute, **options, &block)
-        with_column(Body::MoneyComponent.new(@table, @record, attribute, **options), &block)
+      # Generates a column from numeric values rendered using `number_to_currency`.
+      #
+      # @param method [Symbol] the method to call on the record
+      # @param options [Hash] options to be passed to `number_to_currency`
+      # @param attributes [Hash] HTML attributes to be added to the cell tag
+      # @param block [Proc] optional block to alter the cell content
+      # @return [void]
+      #
+      # @example Render a currency column for the price of a product
+      #   <% row.currency :price %> # => <td>$3.50</td>
+      def currency(method, options: {}, **attributes, &block)
+        with_column(Body::CurrencyComponent.new(@table, @record, method, options:, **attributes), &block)
       end
 
-      def rich_text(attribute, **options, &block)
-        with_column(Body::RichTextComponent.new(@table, @record, attribute, **options), &block)
+      # Generates a column containing HTML markup.
+      #
+      # @param method [Symbol] the method to call on the record
+      # @param attributes [Hash] HTML attributes to be added to the cell tag
+      # @param block [Proc] optional block to alter the cell content
+      # @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(method, **attributes, &block)
+        with_column(Body::RichTextComponent.new(@table, @record, method, **attributes), &block)
       end
 
-      def link(attribute, **options, &block)
-        with_column(Body::LinkComponent.new(@table, @record, attribute, **options), &block)
+      # Generates a column that links to the record's show page (by default).
+      #
+      # @param method [Symbol] the method to call on the record
+      # @param link [Hash] options to be passed to the link_to helper
+      # @option opts [Hash, Array, String, Symbol] :url ([:admin, object]) options for url_for,
+      # or a symbol to be passed to the route helper
+      # @param attributes [Hash] HTML attributes to be added to the cell tag
+      # @param block [Proc] optional block to alter the cell content
+      # @return [void]
+      #
+      # @example Render a column containing the record's title, linked to its show page
+      #   <% row.link :title %> # => <td><a href="/admin/post/15">About us</a></td>
+      # @example Render a column containing the record's title, linked to its edit page
+      #   <% row.link :title, url: :edit_admin_post_path do |cell| %>
+      #      Edit <%= cell %>
+      #   <% end %>
+      #   # => <td><a href="/admin/post/15/edit">Edit About us</a></td>
+      def link(method, url: [:admin, @record], link: {}, **attributes, &block)
+        with_column(Body::LinkComponent.new(@table, @record, method, url:, link:, **attributes), &block)
       end
 
-      def text(attribute, **options, &block)
-        with_column(BodyCellComponent.new(@table, @record, attribute, **options), &block)
+      # Generates a column that renders the contents as text.
+      #
+      # @param method [Symbol] the method to call on the record
+      # @param attributes [Hash] HTML attributes to be added to the cell tag
+      # @param block [Proc] optional block to alter the cell content
+      # @return [void]
+      #
+      # @example Render a column containing the record's title
+      #   <% row.text :title %> # => <td>About us</td>
+      def text(method, **attributes, &block)
+        with_column(BodyCellComponent.new(@table, @record, method, **attributes), &block)
       end
 
-      def image(attribute, variant: :thumb, **options, &block)
-        with_column(Body::ImageComponent.new(@table, @record, attribute, variant:, **options), &block)
+      # Generates a column that renders an ActiveStorage attachment as a downloadable link.
+      #
+      # @param method [Symbol] the method to call on the record
+      # @param variant [Symbol] the variant to use when rendering the image (default :thumb)
+      # @param attributes [Hash] HTML attributes to be added to the cell tag
+      # @param block [Proc] optional block to alter the cell content
+      # @return [void]
+      #
+      # @example Render a column containing a download link to the record's background image
+      #   <% row.attachment :background %> # => <td><a href="...">background.png</a></td>
+      def attachment(method, variant: :thumb, **attributes, &block)
+        with_column(Body::AttachmentComponent.new(@table, @record, method, variant:, **attributes), &block)
       end
     end
   end

data/app/components/koi/tables/header.rb

@@ -1,11 +1,61 @@
 # frozen_string_literal: true
 
+using Katalyst::HtmlAttributes::HasHtmlAttributes
+
 module Koi
   module Tables
     module Header
       class NumberComponent < HeaderCellComponent
         def default_html_attributes
-          { class: "number" }
+          super.merge_html(class: "type-number")
+        end
+      end
+
+      class CurrencyComponent < HeaderCellComponent
+        def default_html_attributes
+          super.merge_html(class: "type-currency")
+        end
+      end
+
+      class BooleanComponent < HeaderCellComponent
+        def default_html_attributes
+          super.merge_html(class: "type-boolean")
+        end
+      end
+
+      class DateComponent < HeaderCellComponent
+        def default_html_attributes
+          super.merge_html(class: "type-date")
+        end
+      end
+
+      class DateTimeComponent < HeaderCellComponent
+        def default_html_attributes
+          super.merge_html(class: "type-datetime")
+        end
+      end
+
+      class LinkComponent < HeaderCellComponent
+        def default_html_attributes
+          super.merge_html(class: "type-link")
+        end
+      end
+
+      class TextComponent < HeaderCellComponent
+        def default_html_attributes
+          super.merge_html(class: "type-text")
+        end
+      end
+
+      class ImageComponent < HeaderCellComponent
+        def default_html_attributes
+          super.merge_html(class: "type-image")
+        end
+      end
+
+      class AttachmentComponent < HeaderCellComponent
+        def default_html_attributes
+          super.merge_html(class: "type-attachment")
         end
       end
     end

data/app/components/koi/tables/header_cell_component.rb

@@ -1,8 +1,38 @@
 # frozen_string_literal: true
 
+using Katalyst::HtmlAttributes::HasHtmlAttributes
+
 module Koi
   module Tables
     class HeaderCellComponent < Katalyst::Tables::HeaderCellComponent
+      attr_reader :width
+
+      def initialize(table, attribute, label: nil, link: {}, width: nil, **html_attributes)
+        @width = width
+
+        super(table, attribute, label:, link:, **html_attributes)
+      end
+
+      def default_html_attributes
+        super.merge_html(class: width_class)
+      end
+
+      private
+
+      def width_class
+        case width
+        when :xs
+          "width-xs"
+        when :s
+          "width-s"
+        when :m
+          "width-m"
+        when :l
+          "width-l"
+        else
+          ""
+        end
+      end
     end
   end
 end