Merge branch 'main' into version-2

Author: bogdan

lib/datagrid/filters.rb

@@ -192,35 +192,28 @@ def filter_by_name(attribute)
       # @param [Hash] options hash of options
       # @param [Proc] block proc to apply the filter
       # @return [Datagrid::Filters::BaseFilter] Filter definition object
-      # @see https://github.com/bogdan/datagrid/wiki/Filters
-      #
-      # Available options:
-      #
-      # * <tt>:header</tt> - determines the header of the filter
-      # * <tt>:default</tt> - the default filter value.
-      #   Can be a <tt>Proc</tt> in case default should be recalculated.
-      # * <tt>:range</tt> - if true, filter can accept two values that are treated
-      #   as a range that will be used for filtering.
-      #   Not all of the filter types support this option. Here are the list of types that do:
-      #   <tt>:integer</tt>, <tt>:float</tt>, <tt>:date</tt>, <tt>:datetime</tt>, <tt>:string</tt>
-      # * <tt>:multiple</tt> -  if true multiple values can be assigned to this filter.
-      #   If String is assigned as a filter value, it is parsed from string using a separator symbol (`,` by default).
-      #   But you can specify a different separator as option value. Default: false.
-      # * <tt>:allow_nil</tt> - determines if the value can be nil
-      # * <tt>:allow_blank</tt> - determines if the value can be blank
-      # * <tt>:before</tt> - determines the position of this filter,
-      #   by adding it before the filter passed here (when using datagrid_form_with helper)
-      # * <tt>:after</tt> - determines the position of this filter,
-      #   by adding it after the filter passed here (when using datagrid_form_with helper)
-      # * <tt>:dummy</tt> - if true, this filter will not be applied automatically
-      #   and will be just displayed in form. In case you may want to apply it manually.
-      # * <tt>:if</tt> - specify the condition when the filter can be dislayed and used.
-      #   Accepts a block or a symbol with an instance method name
-      # * <tt>:unless</tt> - specify the reverse condition when the filter can be dislayed and used.
-      #   Accepts a block or a symbol with an instance method name
-      # * <tt>:input_options</tt> - options passed when rendering html input tag attributes.
-      #   Use <tt>input_options.type</tt> to control input type including <tt>textarea</tt>.
-      # * <tt>:label_options</tt> - options passed when rendering html label tag attributes
+      # @see Datagrid::Filters
+      # @option options [String] header Determines the header of the filter.
+      # @option options [Object, Proc] default The default filter value. Accepts a `Proc` to allow dynamic calculation.
+      # @option options [Boolean] range Whether the filter accepts two values to define a range.
+      #   Supported by types: `:integer`, `:float`, `:date`, `:datetime`, and `:string`.
+      # @option options [Boolean, String] multiple If true, allows multiple values for the filter.
+      #   Strings are parsed using a separator (default: `,`). Can accept a custom separator. Default: `false`.
+      # @option options [Boolean] allow_nil Whether the filter value can be `nil`. Default: `false`.
+      # @option options [Boolean] allow_blank Whether the filter value can be blank. Default: `false`.
+      # @option options [Symbol] before Specifies the position of this filter by placing it before another filter.
+      #   Used with the `datagrid_form_for` helper.
+      # @option options [Symbol] after Specifies the position of this filter by placing it after another filter.
+      #   Used with the `datagrid_form_for` helper.
+      # @option options [Boolean] dummy If true, the filter is not applied automatically and is only displayed in the form.
+      #   Useful for manual application.
+      # @option options [Proc, Symbol] if Specifies a condition under which the filter is displayed and used.
+      #   Accepts a block or the name of an instance method.
+      # @option options [Proc, Symbol] unless Specifies a condition under which the filter is NOT displayed or used.
+      #   Accepts a block or the name of an instance method.
+      # @option options [Hash] input_options Options passed to the HTML input tag for rendering attributes.
+      #   Use `input_options[:type]` to control the input type (e.g., `textarea`).
+      # @option options [Hash] label_options Options passed to the HTML label tag for rendering attributes.
       def filter(name, type = :default, **options, &block)
         klass = type.is_a?(Class) ? type : FILTER_TYPES[type]
         raise ConfigurationError, "filter class #{type.inspect} not found" unless klass

lib/datagrid/helper.rb

@@ -264,19 +264,16 @@ def datagrid_format_value(grid, column, model)
     # Renders html table with columns defined in grid class.
     # In the most common used you need to pass paginated collection
     # to datagrid table because datagrid do not have pagination compatibilities:
-    # Supported options:
-    #
-    # * <tt>:html</tt> - hash of attributes for <table> tag
-    # * <tt>:order</tt> - If false do not generate ordering controlls.
-    #   Default: true.
-    # * <tt>:columns</tt> - Array of column names to display.
-    #   Used in case when same grid class is used in different places
-    #   and needs different columns. Default: all defined columns.
-    # * <tt>:partials</tt> - Path for partials lookup.
-    #   Default: 'datagrid'.
     # @param grid [Datagrid] grid object
     # @param assets [Array] objects from grid scope
     # @param [Hash{Symbol => Object}] options HTML attributes to be passed to `<table>` tag
+    # @option options [Hash] html A hash of attributes for the `<table>` tag.
+    # @option options [Boolean] order Whether to generate ordering controls.
+    #   If set to `false`, ordering controls are not generated. Default: `true`.
+    # @option options [Array<Symbol>] columns An array of column names to display.
+    #   Use this when the same grid class is used in different contexts and requires different columns.
+    #   Default: all defined columns.
+    # @option options [String] partials The path for partials lookup. Default: `'datagrid'`.
     # @return [String] table tag HTML markup
     # @example
     #   assets = grid.assets.page(params[:page])
@@ -294,15 +291,13 @@ def datagrid_table(grid, assets = grid.assets, **options)
 
     # Renders HTML table header for given grid instance using columns defined in it
     #
-    # Supported options:
-    #
-    # * <tt>:order</tt> - display ordering controls built-in into header
-    #   Default: true
-    # * <tt>:columns</tt> - Array of column names to display.
-    #   Used in case when same grid class is used in different places
-    #   and needs different columns. Default: all defined columns.
-    # * <tt>:partials</tt> - Path for partials lookup.
-    #   Default: 'datagrid'.
+    # @option options [Boolean] order Whether to display ordering controls built into the header.
+    #   Default: `true`.
+    # @option options [Array<Symbol,String>] columns An array of column names to display.
+    #   Use this when the same grid class is used in different contexts and requires different columns.
+    #   Default: all defined columns.
+    # @option options [String] partials The path for partials lookup.
+    #   Default: `'datagrid'`.
     # @param grid [Datagrid] grid object
     # @param [Object] opts (deprecated) pass keyword arguments instead
     # @param [Hash] options
@@ -321,19 +316,16 @@ def datagrid_header(grid, opts = :__unspecified__, **options)
     # Renders HTML table rows using given grid definition using columns defined in it.
     # Allows to provide a custom layout for each for in place with a block
     #
-    # Supported options:
-    #
-    # * <tt>:columns</tt> - Array of column names to display.
-    #   Used in case when same grid class is used in different places
-    #   and needs different columns. Default: all defined columns.
-    # * <tt>:partials</tt> - Path for partials lookup.
-    #   Default: 'datagrid'.
-    #
+    # @option options [Array<Symbol>] columns An array of column names to display.
+    #   Use this when the same grid class is used in different contexts and requires different columns.
+    #   Default: all defined columns.
+    # @option options [String] partials The path for partials lookup.
+    #   Default: `'datagrid'`.
     # @return [String]
-    # @example
-    #   = datagrid_rows(grid) # Generic table rows Layout
-    #
-    #   = datagrid_rows(grid) do |row| # Custom Layout
+    # @example Generic table rows Layout
+    #   = datagrid_rows(grid)
+    # @example Custom Layout
+    #   = datagrid_rows(grid) do |row|
     #     %tr
     #       %td= row.project_name
     #       %td.project-status{class: row.status}= row.status
@@ -346,11 +338,8 @@ def datagrid_rows(grid, assets = grid.assets, **options, &block)
     end
 
     # @return [String] renders ordering controls for the given column name
-    #
-    # Supported options:
-    #
-    # * <tt>:partials</tt> - Path for partials lookup.
-    #   Default: 'datagrid'.
+    # @option options [String] partials The path for partials lookup.
+    #   Default: `'datagrid'`.
     def datagrid_order_for(grid, column, options = {})
       Datagrid::Utils.warn_once(<<~MSG)
         datagrid_order_for is deprecated.
@@ -414,20 +403,19 @@ def datagrid_form_for(grid, options = {})
     # @param block [Proc] block with Datagrid::Helper::HtmlRow as an argument returning a HTML markup as a String
     # @param [Hash{Symbol => Object}] options
     # @return [Datagrid::Helper::HtmlRow, String] captured HTML markup if block given otherwise row object
-    # @example
-    #   # Suppose that grid has first_name and last_name columns
+    # @example Render default layout for row
+    #   <%= datagrid_row(grid, user, columns: [:first_name, :last_name, :actions]) %>
+    # @example Rendering custom layout for `first_name` and `last_name` columns
     #   <%= datagrid_row(grid, user) do |row| %>
     #     <tr>
     #       <td><%= row.first_name %></td>
     #       <td><%= row.last_name %></td>
     #     </tr>
     #   <% end %>
-    # @example
+    # @example Rendering custom layout passing a block
     #   <% row = datagrid_row(grid, user) %>
     #   First Name: <%= row.first_name %>
     #   Last Name: <%= row.last_name %>
-    # @example
-    #   <%= datagrid_row(grid, user, columns: [:first_name, :last_name, :actions]) %>
     def datagrid_row(grid, asset, **options, &block)
       Datagrid::Helper::HtmlRow.new(self, grid, asset, options).tap do |row|
         return capture(row, &block) if block_given?