trestle 0.10.0 → 0.10.1

data/app/helpers/trestle/headings_helper.rb

@@ -1,27 +1,6 @@
 module Trestle
   module HeadingsHelper
-    def h1(text, options={})
-      content_tag(:h1, text, options)
-    end
-
-    def h2(text, options={})
-      content_tag(:h2, text, options)
-    end
-
-    def h3(text, options={})
-      content_tag(:h3, text, options)
-    end
-
-    def h4(text, options={})
-      content_tag(:h4, text, options)
-    end
-
-    def h5(text, options={})
-      content_tag(:h5, text, options)
-    end
-
-    def h6(text, options={})
-      content_tag(:h6, text, options)
-    end
+    # These methods are delegated to the ActionView::Helpers::TagHelper proxy object for convenience.
+    delegate :h1, :h2, :h3, :h4, :h5, :h6, to: :tag
   end
 end

data/app/helpers/trestle/i18n_helper.rb

@@ -1,4 +1,5 @@
 module Trestle
+  # [Internal]
   module I18nHelper
     FLATPICKR_LOCALE_CONVERSIONS = { ca: "cat", el: "gr", nb: "no", vi: "vn" }.stringify_keys
 

data/app/helpers/trestle/icon_helper.rb

@@ -1,8 +1,21 @@
 module Trestle
   module IconHelper
-    def icon(*classes)
-      options = classes.extract_options!
-      content_tag(:i, "", options.merge(class: classes))
+    # Renders an icon (as an <i> tag).
+    #
+    # Trestle includes the FontAwesome icon library but other font
+    # libraries can be included via custom CSS.
+    #
+    # classes    - List of font name classes to add to the <i> tag
+    # attributes - Additional HTML attributes to add to the <i> tag
+    #
+    # Examples
+    #
+    #   <%= icon("fas fa-star") %>
+    #   <%= icon("fas", "fa-star", class: "fa-fw text-muted")
+    #
+    # Return the HTML i tag for the icon.
+    def icon(*classes, **attributes)
+      tag.i("", **attributes.merge(class: [*classes, attributes[:class]]))
     end
   end
 end

data/app/helpers/trestle/layout_helper.rb

@@ -1,4 +1,5 @@
 module Trestle
+  # [Internal]
   module LayoutHelper
     SIDEBAR_CLASSES = {
       "expanded"  => "sidebar-expanded",

data/app/helpers/trestle/modal_helper.rb

@@ -1,16 +1,34 @@
 module Trestle
   module ModalHelper
+    # Merges the given options with the existing hash of defined modal options.
+    #
+    # Trestle uses Bootstrap modal markup (https://getbootstrap.com/docs/5.3/components/modal/)
+    # to render modals, which consist of an outer .modal wrapper div with an inner
+    # .modal-dialog div.
+    #
+    # The `class` attribute (e.g. `"modal-lg"`) is applied to the inner element, and all
+    # other attributes are applied to the outer element. A class can be applied to the
+    # wrapper element using the `wrapper_class` option.
+    #
+    # Examples
+    #
+    #   <% modal_options! class: "modal-lg", controller: "modal-stimulus" %>
+    #
+    #   <% modal_options! wrapper_class: "custom-modal-animation" %>
+    #
     def modal_options!(options)
       modal_options.merge!(options)
     end
 
+    # Returns a hash of the currently defined modal options
     def modal_options
       @_modal_options ||= {}
     end
 
+    # Returns the HTML attributes to apply to the modal wrapper (.modal) <div>
     def modal_wrapper_attributes
       {
-        class: ["modal", "fade", modal_options[:wrapper_class]],
+        class: ["modal", "fade", modal_options[:wrapper_class]].compact,
         tabindex: "-1",
         role: "dialog",
         data: {
@@ -19,9 +37,10 @@ module Trestle
       }.deep_merge(modal_options.except(:class, :wrapper_class, :controller))
     end
 
+    # Returns the HTML attributes to apply to the inner modal dialog (.modal-dialog) <div>
     def modal_dialog_attributes
       {
-        class: ["modal-dialog", modal_options[:class]],
+        class: ["modal-dialog", modal_options[:class]].compact,
         role: "document"
       }
     end

data/app/helpers/trestle/navigation_helper.rb

@@ -1,4 +1,5 @@
 module Trestle
+  # [Internal]
   module NavigationHelper
     def current_navigation_item?(item)
       current_page?(item.path) || (item.admin && current_admin?(item.admin))

data/app/helpers/trestle/pagination_helper.rb

@@ -1,4 +1,5 @@
 module Trestle
+  # [Internal]
   module PaginationHelper
     # Custom version of Kaminari's page_entries_info helper to use a
     # Trestle-scoped I18n key and add a delimiter to the total count.

data/app/helpers/trestle/params_helper.rb

@@ -1,10 +1,42 @@
 module Trestle
   module ParamsHelper
+    # Returns a subset of the params "hash" (an instance of ActionController::Parameters)
+    # limited to only those keys that should be considered persistent throughout
+    # reordering and pagination.
+    #
+    # This could be a scope or the current order, but this may be extended by Trestle
+    # plugins and the application itself in `Trestle.config.persistent_params` to include
+    # search queries, filters, etc.
+    #
+    # By default this list is set to: [:sort, :order, :scope]
+    #
+    # Returns an instance of ActionController::Parameters.
     def persistent_params
       flat, nested = Trestle.config.persistent_params.partition { |p| !p.is_a?(Hash) }
       nested = nested.inject({}) { |result, param| result.merge(param) }
 
       params.slice(*(flat + nested.keys)).permit(*(flat << nested))
     end
+
+    # Converts the current set of persistent params into hidden form fields, suitable
+    # for inclusion within a form tag (e.g for search or filtering).
+    #
+    # except - List of param keys to exclude
+    # only   - List of param keys to only include
+    #
+    # Returns a HTML-safe String.
+    def serialize_persistent_params(except: [], only: [])
+      params = persistent_params
+
+      if Array(only).any?
+        params = params.slice(*only)
+      elsif Array(except).any?
+        params = params.except(*except)
+      end
+
+      safe_join(to_form_params(params).map { |param|
+        tag.input(type: "hidden", name: param[:name], value: param[:value], autocomplete: "off")
+      }, "\n")
+    end
   end
 end

data/app/helpers/trestle/sort_helper.rb

@@ -1,20 +1,47 @@
 module Trestle
   module SortHelper
-    def sort_link(text, field, options={})
-      sort_link = SortLink.new(field, persistent_params, options)
+    # Renders a sort link for a table column header.
+    #
+    # The `sort` and `order` params are used to determine whether the sort link is
+    # active, and which is the current sort direction (asc or desc). CSS classes are
+    # applied accordingly which are used to render the appropriate icons alongside the link.
+    #
+    # The current set of `persistent_params` is merged with the new `sort`/`order` params
+    # to build the target link URL.
+    #
+    # text    - Text or HTML content to render as the link label
+    # field   - The name of the current field, which should match the `sort` param
+    #           when the collection is being sorted by this field
+    # options - Hash of options (default: {}):
+    #           :default - (Boolean) Set to true if the field is considered to be active
+    #                      even when the `sort` param is blank (default: false)
+    #           :default_order - (String/Symbol) Specify the default collection order when
+    #                            the `order` param is blank (default: "asc")
+    #
+    # Examples
+    #
+    #   <%= sort_link "Title", :title, default: true %>
+    #
+    #   <%= sort_link "Created", :created_at, default_order: "desc" %>
+    #
+    # Returns a HTML-safe String.
+    def sort_link(text, field, **options)
+      sort_link = SortLink.new(field, persistent_params, **options)
       link_to text, sort_link.params, class: sort_link.classes
     end
 
     class SortLink
       attr_reader :field
 
-      def initialize(field, params, options)
-        @field, @params, @options = field, params, options
+      def initialize(field, params, default: false, default_order: "asc")
+        @field, @params = field, params
+
+        @default = default
+        @default_order = default_order.to_s
       end
 
       def active?
-        @params[:sort] == field.to_s ||
-          (@options[:default] && !@params.key?(:sort))
+        @params[:sort] == field.to_s || (default? && !@params.key?(:sort))
       end
 
       def params
@@ -33,8 +60,12 @@ module Trestle
         @params[:order] || default_order
       end
 
+      def default?
+        @default
+      end
+
       def default_order
-        @options.fetch(:default_order, "asc").to_s
+        @default_order
       end
 
       def classes

data/app/helpers/trestle/status_helper.rb

@@ -1,8 +1,24 @@
 module Trestle
   module StatusHelper
-    def status_tag(label, status=:primary, options={})
-      options[:class] ||= ["badge", "badge-#{status}"]
-      content_tag(:span, label, options)
+    # Renders a status indicator as a Bootstrap badge.
+    # (https://getbootstrap.com/docs/5.3/components/badge/)
+    #
+    # label      - Status badge text or HTML content
+    # status     - Status class (as .badge-{status}) to apply to the badge (default: :primary)
+    # attributes - Additional HTML attributes to add to the <span> tag
+    #
+    # Examples
+    #
+    #   <%= status_tag("Status Text") %>
+    #
+    #   <%= status_tag(icon("fas fa-check"), :success) %>
+    #
+    #   <%= status_tag(safe_join([icon("fas fa-warning"), "Error"], " "), :danger,
+    #                  data: { controller: "tooltip" }, title: "Full error message") %>
+    #
+    # Returns a HTML-safe String.
+    def status_tag(label, status=:primary, **attributes)
+      tag.span(label, **attributes.merge(class: ["badge", "badge-#{status}", attributes[:class]]))
     end
   end
 end

data/app/helpers/trestle/tab_helper.rb

@@ -1,13 +1,34 @@
 module Trestle
   module TabHelper
-    def tabs
-      @_trestle_tabs ||= {}
-    end
+    # Creates a tab pane using content via the given block, :partial option or partial
+    # template automatically inferred from the tab name.
+    #
+    # It also appends a Trestle::Tab object to the list of declared tabs that is
+    # accessible via the #tabs helper (e.g. for rendering the tab links).
+    #
+    # name    - (Symbol) Internal name for the tab
+    # options - Hash of options (default: {}):
+    #           :label - Optional tab label. If not provided, will be inferred by the
+    #                    admin-translated tab name (`admin.tabs.{name}` i18n scope)
+    #           :badge - Optional badge to show next to the tab label (e.g. a counter)
+    #           :partial - Optional partial template name to use when a block is not provided
+    #
+    # Examples
+    #
+    #   <%= tab :details %>
+    #   => Automatically renders the 'details' partial (e.g. "_details.html.erb") as the tab content
+    #
+    #   <%= tab :metadata, partial: "meta" %>
+    #   => Renders the 'meta' partial (e.g. "_meta.html.erb") as the tab content
+    #
+    #   <%= tab :comments do %> ...
+    #   => Renders the given block as the tab content
+    #
+    # Returns a HTML-safe String.
+    def tab(name, **options)
+      tabs[name] = tab = Tab.new(name, **options)
 
-    def tab(name, options={})
-      tabs[name] = tab = Tab.new(name, options)
-
-      content_tag(:div, id: tab.id(("modal" if modal_request?)), class: ["tab-pane", ('active' if name == tabs.keys.first)], role: "tabpanel") do
+      tag.div(id: tab.id(("modal" if modal_request?)), class: ["tab-pane", ('active' if name == tabs.keys.first)], role: "tabpanel") do
         if block_given?
           yield
         elsif options[:partial]
@@ -17,5 +38,19 @@ module Trestle
         end
       end
     end
+
+    # Returns a hash (name => Trestle::Tab) of the currently declared tabs.
+    def tabs
+      @_trestle_tabs ||= {}
+    end
+
+    # Captures the given block (using `content_for`) as the sidebar content.
+    def sidebar(&block)
+      content_for(:sidebar, &block)
+    end
+
+    def render_sidebar_as_tab?
+      modal_request? && content_for?(:sidebar)
+    end
   end
 end

data/app/helpers/trestle/table_helper.rb

@@ -2,15 +2,17 @@ module Trestle
   module TableHelper
     # Renders an existing named table or builds and renders a custom table if a block is provided.
     #
-    # name    - The (optional) name of the table to render (as a Symbol), or the actual Trestle::Table instance itself.
-    # options - Hash of options that will be passed to the table builder (default: {}):
-    #           :collection - The collection that should be rendered within the table. It should be an
-    #                         Array-like object, but will most likely be an ActiveRecord scope. It can
-    #                         also be a callable object (i.e. a Proc) in which case the result of calling
-    #                         the block will be used as the collection.
-    #           See Trestle::Table::Builder for additional options.
-    # block   - An optional block that is passed to Trestle::Table::Builder to define a custom table.
-    #           One of either the name or block must be provided, but not both.
+    # One of either the name or block must be provided, but not both.
+    #
+    # name       - The (optional) name of the table to render (as a Symbol), or the
+    #              actual Trestle::Table instance itself
+    # collection - The collection that should be rendered within the table.
+    #              It should be an Array-like object, but will most likely be an
+    #              ActiveRecord scope. It can also be a callable object (i.e. a Proc) in
+    #              which case the result of calling the block will be used as the collection
+    # options    - Hash of options that will be passed to the table builder (default: {}).
+    #              See Trestle::Table::Builder for additional options
+    # block      - An optional block that is passed to Trestle::Table::Builder to define a custom table
     #
     # Examples
     #
@@ -23,26 +25,23 @@ module Trestle
     #   <%= table :accounts %>
     #
     # Returns the HTML representation of the table as a HTML-safe String.
-    def table(name=nil, options={}, &block)
+    def table(name=nil, collection: nil, **options, &block)
       if block_given?
-        if name.is_a?(Hash)
-          options = name
-        else
-          collection = name
-        end
-
-        table = Table::Builder.build(options, &block)
+        table = Table::Builder.build(**options, &block)
       else
         if name.is_a?(Trestle::Table)
           table = name
         else
-          table = admin.tables.fetch(name) { raise ArgumentError, "Unable to find table named #{name.inspect}" }
+          table = admin.tables.fetch(name) {
+            raise ArgumentError, "Unable to find table named #{name.inspect}"
+          }
         end
 
-        table = table.with_options(options.reverse_merge(sortable: false))
+        table = table.with_options(sortable: false, **options)
       end
 
-      collection ||= options[:collection] || table.options[:collection]
+      collection ||= name if block_given?
+      collection ||= table.options[:collection]
       collection = collection.call if collection.respond_to?(:call)
 
       render "trestle/table/table", table: table, collection: collection
@@ -50,12 +49,13 @@ module Trestle
 
     # Renders the pagination controls for a collection.
     #
-    # collection - The paginated Kaminari collection to render controls for (required).
-    # options    - Hash of options that will be passed to the Kaminari #paginate method (default: {}):
+    # collection - The paginated Kaminari collection to render controls for (required)
+    # entry_name - Custom item name passed to the Kaminari #page_entries_info helper
+    # options    - Hash of options that will be passed to the Kaminari #paginate method (default: {})
     #
     # Examples
     #
-    #   <%= pagination collection: Account.page(params[:page]), remote: true %>
+    #   <%= pagination collection: Account.page(params[:page]) %>
     #
     # Returns the HTML representation of the pagination controls as a HTML-safe String.
     def pagination(collection:, entry_name: nil, **options)

data/app/helpers/trestle/timestamp_helper.rb

@@ -1,13 +1,13 @@
 module Trestle
   module TimestampHelper
-    # Renders a Time object as a formatted timestamp (using a <time> tag)
+    # Renders a Time object as a formatted timestamp (using a <time> tag).
     #
-    # time    - The Time object to format.
-    # options - Hash of options (default: {}):
-    #           :class       - Additional HTML classes to add to the <time> tag.
-    #           :precision   - Time precision, either :minutes or :seconds (default: :minutes).
-    #           :date_format - I18n date format to use for the date (default: :trestle_date).
-    #           :time_format - I18n time format to use for the time (default: :trestle_time).
+    # time        - The Time object to format
+    # precision   - Time precision, either :minutes or :seconds (default: :minutes)
+    # date_format - I18n date format to use for the date (default: :trestle_date)
+    # time_format - I18n time format to use for the time (default: :trestle_time,
+    #                 or :trestle_time_with_seconds if precision is :seconds)
+    # attributes  - Additional HTML attributes to add to the <time> tag
     #
     # Examples
     #
@@ -16,28 +16,24 @@ module Trestle
     #   <%= timestamp(Time.current, class: "timestamp-inline", precision: :seconds) %>
     #
     # Returns the HTML representation of the given Time.
-    def timestamp(time, options={})
+    def timestamp(time, precision: Trestle.config.timestamp_precision, date_format: :trestle_date, time_format: nil, **attributes)
       return unless time
 
-      classes     = ["timestamp", options[:class]].compact
-      precision   = options.fetch(:precision) { Trestle.config.timestamp_precision }
-      date_format = options.fetch(:date_format) { :trestle_date }
-      time_format = options.fetch(:time_format) { precision == :seconds ? :trestle_time_with_seconds : :trestle_time }
+      time_format ||= (precision == :seconds) ? :trestle_time_with_seconds : :trestle_time
 
-      time_tag(time, class: classes) do
+      time_tag(time, **attributes.merge(class: ["timestamp", attributes[:class]])) do
         safe_join([
-          l(time, format: date_format, default: proc { |date| "#{date.day.ordinalize} %b %Y" }),
-          content_tag(:small, l(time, format: time_format, default: "%l:%M:%S %p"))
+          tag.span(l(time, format: date_format, default: proc { |date| "#{date.day.ordinalize} %b %Y" })),
+          tag.small(l(time, format: time_format, default: "%l:%M:%S %p"))
         ], "\n")
       end
     end
 
-    # Renders a Date object as formatted datestamp (using a <time> tag)
+    # Renders a Date object as formatted datestamp (using a <time> tag).
     #
-    # date    - The Date object to format.
-    # options - Hash of options (default: {}):
-    #           :class  - Additional HTML classes to add to the <time> tag.
-    #           :format - I18n date format to use (default: :trestle_calendar).
+    # date       - The Date object to format
+    # format     - I18n date format to use (default: :trestle_calendar)
+    # attributes - Additional HTML attributes to add to the <time> tag
     #
     # Examples
     #
@@ -46,13 +42,10 @@ module Trestle
     #   <%= datestamp(article.created_at, format: :trestle_date, class: "custom-datestamp") %>
     #
     # Returns the HTML representation of the given Date.
-    def datestamp(date, options={})
+    def datestamp(date, format: :trestle_calendar, **attributes)
       return unless date
 
-      classes = ["datestamp", options[:class]].compact
-      format  = options.fetch(:format) { :trestle_calendar}
-
-      time_tag(date, class: classes) do
+      time_tag(date, **attributes.merge(class: ["datestamp", attributes[:class]])) do
         l(date, format: format, default: "%-m/%-d/%Y")
       end
     end

data/app/helpers/trestle/title_helper.rb

@@ -1,5 +1,7 @@
 module Trestle
   module TitleHelper
+    # Returns the page title (if set using content_for), falling back to
+    # the titleized action name as a default if not set.
     def title
       content_for(:title) || default_title
     end

data/app/helpers/trestle/toolbars_helper.rb

@@ -1,9 +1,10 @@
 module Trestle
+  # [Internal]
   module ToolbarsHelper
     def render_toolbar(toolbar, *args)
       result = toolbar.groups(self, *args).map do |items|
         if items.many?
-          content_tag(:div, class: "btn-group", role: "group") do
+          tag.div(class: "btn-group", role: "group") do
             safe_join(items, "\n")
           end
         else

data/app/helpers/trestle/turbo/frame_helper.rb

@@ -1,19 +1,20 @@
 module Trestle
   module Turbo
     module FrameHelper
-      def index_turbo_frame(options={}, &block)
-        defaults = {
-          id: "index",
-          data: {
-            controller: "reloadable",
-            turbo_action: "advance"
-          }
-        }
-
-        content_tag("turbo-frame", defaults.merge(options), &block)
-      end
-
-      def resource_turbo_frame(instance, options={}, &block)
+      # Renders a <turbo-frame> container for an instance/resource view. A resource
+      # turbo frame sets its DOM id from the given instance and has a default target of
+      # "_top" (except for modal requests).
+      #
+      # attributes - Additional HTML attributes to add to the <turbo-frame> tag
+      #
+      # Examples
+      #
+      #   <%= resource_turbo_frame(article) do %> ...
+      #
+      #   <%= resource_turbo_frame(article, id: dom_id(article, "comment")) %> ...
+      #
+      # Returns a HTML-safe String.
+      def resource_turbo_frame(instance, **attributes, &block)
         defaults = {
           id: dom_id(instance),
           target: ("_top" unless modal_request?),
@@ -22,7 +23,17 @@ module Trestle
           }
         }
 
-        content_tag("turbo-frame", defaults.merge(options), &block)
+        tag.turbo_frame(**defaults.merge(attributes), &block)
+      end
+
+      # [DEPRECATED]
+      #
+      # The #content turbo-frame found in app/views/trestle/application/_layout.html.erb
+      # is now used as a common top-level hook for the 'reloadable' Stimulus controller.
+      def index_turbo_frame(**attributes, &block)
+        Trestle.deprecator.warn("The index_turbo_frame helper is deprecated and will be removed in future versions of Trestle.")
+        yield
+        nil
       end
     end
   end